Cross-upstream packument merge for npm virtual repositories. Decision in !2018 (https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2018#note_3774142678): virtual repositories merge metadata across upstreams, all formats. For npm this replaces the winner-only packument in `docs/specs/S31-npm-virtual.md`. S31 is not a closed-beta blocker, so there is no winner-only first: the merge is the first implementation, delivered through the existing S31 step issues. ## Cross-upstream packument merge Items 1 to 7 are the spec text and landed with [!2338](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2338), merged 2026-09-04 as `c5ed5ef1d` in `docs/specs/S31-npm-virtual.md`. The residual `winner` wording left in that file is the tarball route, which stays single-winner, and the `*Amended:*` notes recording what each `## Resolutions` entry used to say. - [x] **S31 amendment MR.** Replace "No packument merge" and the winner-only resolution entry. Rules: `versions` union, lower position wins a conflict, whole object. `dist-tags` union, lower position wins each tag, `latest` included, same rule for `/-/package/{name}/dist-tags`. `time` union, lower position wins, `modified` is the max. `dist.tarball` re-pointed for every entry, `integrity` and `shasum` untouched, `_rev` dropped, `_id` is the name. No synthesized `latest`. - [x] **Collection semantics as in S30.** No Probe. Every eligible position contributes: hosted from its cache blob or rebuild, remote from a fresh row, a revalidation, or a fetch. Failed or unhealthy position contributes its cached copy or is omitted. Any contributor gives `200` and `merged` or `merged_partial`. All absent gives `404`, all failed `503`, data error vetoes the `404`. Bounded by `resolution.probe_concurrency`. - [x] **Streaming merge, no buffering.** Emit position 0 first, skip already-seen version keys from later positions. `versions` streamed, `dist-tags`, `time` and scalars buffered and emitted after. No `Content-Length`. PoC: 54 to 60 MB input in 126 to 180 ms with 4 to 5 MB heap. - [x] **Input-derived ETag.** Hash of merge version, `position`, `upstream_repository_id` and each input blob sha256. `If-None-Match` answers `304` after the DB reads. - [x] **Fan-out cost.** Every read asks every upstream, so a private package with a public remote costs one upstream GET per read. Specify: negative cache for `404` with a short TTL, scope deny rules on public remotes, per-position wait bound with omission on timeout. - [x] **Merged-document cache** keyed by the input fingerprint, stored in CAS behind a row owned by the virtual repository. No TTL, no invalidation path. Cross-format shape belongs to S13, tracked in #1078, which @mkhalifa3 opened on 2026-09-02. This replaces the virtual-owned metadata cache follow-up in S31. - [x] **Fix the S31 claim** that the merge removes the packument/tarball integrity mismatch. It does not. Add a metric for "same version, different integrity across positions" as a dependency-confusion signal. - [ ] **Shared seam.** Collection mode and per-position records in `internal/virtual` are the same ones S30 books. Build once. `internal/virtual` on `main` still holds only `decision.go`, `resolve.go`, `result.go`, `rules.go` and `upstream.go`, and no collection mode. The plan MR this item asked for is now open as [!2357](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2357), `docs/plans/2026-09-04-virtual-collection-mode.md`, six steps. While it is open no step MR that consumes the seam may open, under the plan-before-code guardrail; once it merges, its own Step 1 waits on an S13 spec amendment and its Step 6 on the S13 DRI's value for `resolution.position_wait_timeout`. Its Step 3 is the finding worth knowing before reviewing it: `loadAndFilter` marks an unhealthy remote failed before Phase 1, so `serveOutage` bars its cached copy on purpose, and both consumer specs require the opposite on the collection path. The six steps are tracked as #1243, an implementation issue under this item's own epic with one task each, #1244 through #1249, filed 2026-09-08. #1243 also carries the gates that outlive the plan MR: the S13 spec amendment, both `resolution` keys, and `ResolveTimeout`. - [x] **Update step issues** instead of opening new ones: #894 metadata serve surface, #896 packument handler, #897 dist-tags handler, #899 observability (`merged`, `merged_partial`, merge duration, inputs, conflicts), #900 e2e. #893, the resolution facade, is not exempt: its `resolve_timeout` derivation, Resolution acceptance criteria #11 and #12, the per-position `Transform`, and the aggregate-verdict arms in `virtual_read_errors.go` all move when the amendment lands. Those four are recorded on #893 rather than reworked ahead of the amendment, because Step 12 is built against the spec as it stands. Done 2026-09-04. #893 recorded the four re-opened parts of Step 12 on 2026-09-03, and the other five were rewritten against the amended plan: #894 (was 17 `winner` mentions) is retitled "metadata merge and serve surface" and now describes the three-part stack, its two gates, and which of #893's four parts its part 2 re-cuts; #899 (was 7) moves five metric families to Step 13, keeps four, and carries the re-derived 25/17/41 cardinality figures; #896 (was 5) keeps its scope and records that "A definite failure never reaches the network" stops being a short-circuit assertion; #897 (was 3) records the dist-tags reversal, the deleted byte-identical subtest, and the two fixtures the tag-less hosted case now needs; #900 (was 0) gains criterion #29, the install journey for a version held only at a lower-priority position. Every `winner` left in the five is deliberate: the tarball route, the barred winner-named metric values, or a statement of what reversed. - [x] **Amend the S31 plan.** Done by [!2352](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2352), merged 2026-09-04 as `7a76091b9`. It rewrote Step 13 into a three-part step, reversed Step 16's dist-tags behaviour, moved five metric families from Step 18 to Step 13, and re-derived every acceptance-criteria citation at `f057e9bde`. Before it merged, `docs/plans/2026-08-21-s31-npm-virtual.md` still described Steps 13, 15 and 16 winner-shaped, Step 17's tarball references were correct as they stood, and !2338 had not touched the plan file. The plan-before-code gate this MR held over the step MRs for 13, 15 and 16 has lifted. What still gates Step 13 is the shared seam above plus, at `dbf8b383f`, `S31-npm-virtual.md:85`: the S13 DRI ratifying `resolution.negative_cache_ttl` and `resolution.position_wait_timeout` and setting their values before the collection step MR. - [ ] **Merge order.** Every step issue above sits downstream of #893, Step 12. On the dependency rows of `docs/plans/2026-08-21-s31-npm-virtual.md` at `dbf8b383f`: Step 13 depends on Steps 8 and 12 and on the shared collection mode, Step 14 on Steps 10, 12 and 13, Steps 15, 16 and 17 each on Step 14, Step 18 on Steps 15, 16 and 17, and Step 19 on Steps 15 and 17. So the merge cannot reach `main` before Step 12 does, whatever order the amendment and the step MRs are written in. Step 12 is on `main`, as !2325 (1/3), !2326 (2/3) and !2255 (3/3), the last as `ba0b173a3`, and #893 is closed, so the gate this paragraph described has lifted. Of the two plan MRs it named, !2352 has merged. While !2357 is open no step MR consuming the collection seam may open; once it merges, its own six steps run ahead of S31's Step 13 part 2, and this box stays open until that ordering has been walked. ## Moved out - Non-standard upstream tarball hosting is an S15 npm remote item and does not depend on the merge. Tracked in #1059. - The S15 amendment committing `npm_remote_*` metrics and the `npm_remote_proxy` event to firing for a virtual-driven leg. Tracked in #1060. - Coalescing the resolution phase across concurrent reads, not only the Fetch. The merge removes the Probe phase, so #1061 re-scopes it against the amended S31. Part of the npm virtual workstream (S31).