Projection of npm wire JSON into the ecosystem-agnostic domain model.

This module is the second half of the npm protocol boundary. Where Ecluse.Core.Registry.Npm.Wire captures what the registry said as faithful wire types, this module turns those into the domain vocabulary of Ecluse.Core.Package -- PackageInfo (the packument-level view) and PackageDetails (the per-version snapshot the rules engine evaluates). Together they realise the parse* fields of the Ecluse.Core.Registry handle: nothing above the adapter ever sees npm wire data.

The projection is pure and total (it returns Either ParseError, never throws), the execution half of parse, don't validate -- once a response has been projected, downstream code holds precise domain types and never re-inspects the wire shape.

Per-version graceful degradation

The versions, dist-tags, and time maps are decoded element-wise: a version whose manifest is missing or malformed in a required/security-decisive field (no dist or tarball, an unusable version), a dist-tags entry whose value is not a string, or a time entry that is not a decodable instant is dropped rather than failing the whole packument. Because presence in the decision surface is what makes a version a serve-candidate, a dropped version is automatically never served -- fail-closed for that one version (a version that cannot be decoded cannot be evaluated for integrity, CVEs, or rules) while every healthy version still resolves; a dropped date is simply a version with no known publish time, and a dropped tag loses only that one tag. Only a document whose top-level structure is unusable (a versions that is not an object, an absent/empty name) is denied wholesale. A version's purely advisory fields degrade in the wire layer (Ecluse.Core.Registry.Npm.Wire) without dropping the version. Every drop is recorded as an InvalidEntry in infoInvalidEntries (a version-manifest, dist-tag, or publish-time drop, each carrying its key and reason), so the serve path can log what an upstream served malformed rather than dropping it silently.

Signal mapping

The npm-specific fields collapse onto the normalised, ecosystem-blind signals:

• install-script presence → CodeExecSignal, read fail-closed across two independent wire signals. A version runs code on install when either the abbreviated form's hasInstallScript flag is true or the scripts map declares any of preinstall/install/postinstall (matching what npm itself sets the flag from). The two fields are independent on the wire, so the scripts map is consulted __even when hasInstallScript is present and false__: a hostile upstream must not be able to mask a real install hook by lying in the sibling flag, so a declared script is authoritative and the signal is the union of the two, never the flag overriding a script. A version with neither signal maps to NoCodeOnInstall (both metadata forms always carry the scripts/hasInstallScript information, so its absence is a determination, not an unknown).
• deprecated → Availability: a notice yields Deprecated (carrying the message), its absence Available. npm has no per-version yank, so Yanked never arises here.
• dist → a single-element NonEmpty of Artifact (npm publishes exactly one tarball per version). Both integrity digests survive when present and well-formed: dist.shasum as a SHA1 Hash and dist.integrity as an SRI Hash. Carrying both is load-bearing -- a cross-upstream merge compares the same version's integrity across the private and public registries to detect a supply-chain divergence, which dropping either digest would blind. Each digest is built through the validating mkHash, so a malformed one -- empty ("shasum":"" / "integrity":""), truncated, non-hex, or bad-base64 -- is unconstructable and so treated as absent, never as a degenerate Hash: a digest that ties the version to no tamper-evident fingerprint must not slip past the public-integrity admission gate.
• _npmUser → pkgPublisher (who pushed this version -- provenance). It rides on the version object but is not modelled by the wire manifest, so the projection reads it directly from the version object here.
• time[version] → pkgPublishedAt. The publish timestamp lives in the packument's time map, not the manifest; a version with no time entry (or an abbreviated document, which omits time) projects to Nothing.

Trust is left TrustUnknown: establishing it needs signature verification against npm's published keys, a fetch this pure projection does not perform.

Name as a validation input

The requested PackageName -- the identity the proxy resolved from the route -- is the validation authority for the served packument's name, never a rewrite of it. The packument projection takes the requested name and checks the upstream's self-reported top-level name against it: a document whose self-report agrees is a Projected PackageInfo carrying the name the upstream genuinely reported; a document whose self-report disagrees is a NameMismatch, so the caller can treat that origin as untrusted for this request and drop its contribution. The served name is therefore always a value an upstream genuinely reported, never a substituted or manufactured one. An absent or otherwise undecodable name remains a ParseError, as before -- distinct from a present-but-different name.