A person associated with a package — an author, maintainer, contributor, or the per-version publisher (_npmUser).

Lenient: npm sends a person as either an object {name, email?, url?} or a single packed string of the conventional form "Name <email> (url)". The packed form is captured verbatim in personName (with personEmail/personUrl left Nothing); this wire layer does not attempt to split it, leaving that to the domain projection if it is ever needed. Distinct from Ecluse.Package's domain Person — this is the raw wire shape.

An SCM location for a package.

Lenient: npm sends repository as either an object {type?, url} or a bare string (a shorthand URL such as "github:user/repo"). Both are captured; the bare-string form fills repoUrl and leaves repoType Nothing.

The issue tracker for a package.

Lenient: npm sends bugs as either an object {url?, email?} or a bare string (just the tracker URL). The bare-string form fills bugsUrl.

A declared license.

Lenient: modern packages send a bare SPDX string (MIT); legacy packages send an object {type, url?}. Both are preserved as a sum so the distinction is not lost: LicenseSpdx for the string, LicenseObject for the legacy object.

The dist object: the artifact descriptor carried by every version manifest (full and abbreviated). It is the gateway to the tarball bytes and the integrity guarantee.

The integrity triple (distTarball, distShasum, distIntegrity) is rule-decisive and serving-decisive — a client fails the install if the downloaded bytes do not match integrity/shasum, so any mirror or URL rewrite must preserve these byte-for-byte. Prefer distIntegrity (SRI) over the legacy SHA-1 distShasum.

One registry signature over a published artifact: an ECDSA signature and the id of the key that produced it. Verifiable against npm's published public keys (GET /-/npm/v1/keys) — the basis of npm audit signatures.

A single version's manifest — the per-version object that is essentially the package's package.json at publish time plus registry-injected fields. It appears three ways on the wire and this one type decodes all of them: embedded in a full Packument (versions[v]), embedded in an AbbreviatedPackument (a trimmed subset of the same shape), and standalone (GET /{pkg}/{version}).

Only the fields Écluse's rules and serving need are modelled; everything else is ignored (see the module header). The two rule-decisive optionals deserve note:

• vmHasInstallScript is abbreviated-only — the registry sets it when the version declares preinstall/install/postinstall scripts. It is the cleanest install-script signal, but it is absent from the full manifest.
• vmScripts is therefore captured whole so that, when only the full form is available, install-script presence can be derived (scripts has any of preinstall/install/postinstall). That derivation is a domain-projection concern, not this layer's.

The publish timestamp is not here — it lives in the packument's pkmtTime map, not the manifest (see §8 of the protocol reference).

The full packument: GET /{pkg} with Accept: application/json (or no Accept). One document describing the package and every published version.

The field that earns the full form its place in the pipeline is pkmtTime: the map of publish timestamps (created, modified, and one per version), the source of truth for publish age that age-based rules need. The abbreviated form (§5) drops it, keeping only a top-level modified. Package-level description/license/author are hoisted from the latest version for convenience; the authoritative copy is the per-version one in pkmtVersions.

_attachments is intentionally not modelled — it is populated only on the publish document, not on reads.

The abbreviated packument: GET /{pkg} with Accept: application/vnd.npm.install-v1+json. The install-optimised view and the one the proxy treats as primary.

It carries exactly four top-level fields. Notably the full time map is dropped (only a top-level apkmtModified remains), so publish-age rules need the full Packument. Its apkmtVersions manifests are the trimmed subset of VersionManifest — the same type, with the install-only fields populated (including the abbreviated-only vmHasInstallScript).

An npm error body.

Lenient: the documented shape is an object { message?, error?, ok?: false } and clients "should check for message, then error". But the registry is inconsistent — its per-version 404 is a bare JSON string ("version not found: ^3.0.0"), not an object. This type tolerates both: the object form keeps its fields in an ErrorBody, and a bare string is captured whole as ErrorString. Read the human-facing reason via errorMessage, which applies npm's "message, then error" precedence across both shapes.

The fields of npm's object-form error body. A product type (not inline constructor fields on ErrorResponse) so its selectors are total — there is no ErrorString case for them to be partial over.

The human-facing reason carried by an error body, applying npm's documented precedence: prefer message, then error, and for the bare-string form the string itself. Nothing only when an object form carried neither field. Total.