The two pure transforms an npm packument needs before Écluse serves it: rewrite the embedded artifact URLs under the mount's prefix, and assemble the served document from a cross-upstream MergePlan and the raw source documents.

Both transforms operate structurally over the raw aeson Value, never by re-serialising a typed model. This is load-bearing: the served packument is an open document -- its schema is additionalProperties: true (see docs/architecture/api-surface.md → "The synthesized-packument schema") -- so any field Écluse does not model (author keys, registry bookkeeping, per-version extras) must be relayed unchanged. Building the served body from the raw Values keeps every unmodelled key; rebuilding it from Ecluse.Core.Package would silently drop them.

The decision/replay split

Which versions survive, which source wins each one, where dist-tags.latest resolves, and each surviving version's publish instant are the ecosystem-agnostic decisions, taken over the typed PackageInfo by Ecluse.Core.Package.Filter and Ecluse.Core.Package.Merge and handed here as a MergePlan. This module owns the npm wire-shape assembly: rebuilding versions/dist-tags/time onto the base document from the plan, and the tarball-URL rewrite over the raw upstream bytes. The npm wire knowledge lives here; the decision logic does not (it is reused by every ecosystem). See docs/architecture/registry-model.md → "Decision surface vs served surface".

URL rewriting

rewriteTarballUrls rewrites each version's dist.tarball to {mount-base}/{pkg}/-/{file}, so a client resolving metadata through the proxy also downloads the bytes through it rather than going straight to upstream and bypassing the gate (see docs/architecture/hosting.md → "The load-bearing requirement: URL rewriting"). Keeping artifacts same-host also keeps npm's auth flowing, which a separate artifact host would silently drop. The mount's externally-visible base URL is supplied by the caller; this transform performs no IO. It is idempotent: re-deriving {pkg} and {file} from an already-rewritten URL yields the same URL, so applying it more than once is safe.

Assembling the served document

assembleMergedPackument replays a MergePlan onto the raw source Values in one pass: each surviving version's object is taken from the raw document of the source that won it (so the served bytes are the winning upstream's, unmodelled keys and all) with its dist.tarball rewritten under the mount base as it is placed; dist-tags and time are rebuilt from the plan's reconciled decisions (the times as normalised ISO-8601, with the base document's created/modified bookkeeping retained); every other top-level key is relayed from the base document. A version not in the plan's survivors is simply never taken, so a client's resolver only ever sees admitted versions (presence in the packument is availability -- see docs/research/reverse-engineering/npm.md §8).

The fused single pass is deliberate: restricting, assembling, and rewriting as separate whole-document edits would rebuild a many-version packument several times per request, and this transform sits on the serve path's hot loop (see docs/architecture/performance.md). The rewrite honours the same gate as rewriteTarballUrls: the base document's own name is validated component-wise (safeName) before it is interpolated, and a document with no usable name has no URLs rewritten.