Part of #290, **S31 npm virtual**. This slice composes code that is already merged: S11's hosted npm reads, S15's remote legs, and S13's resolution engine in `internal/virtual`, which has had no caller until now. The three `npm_virtual_*` tables land in `internal/datastore/migrations/`, the resolution reads in `internal/datastore/`, and the loading slice, the serve surface, and the three read handlers in `internal/format/npm/`. **References:** [S31 spec](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S31-npm-virtual.md) · [S31 plan](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/2026-08-21-s31-npm-virtual.md) (see "Step 12"). **Type:** `feat` | **Depends on:** Step 11 (upstream assembly and memoized lookups) (tracked as blocked-by links below). ## Cross-upstream packument merge: what is contingent The decision recorded in !2018 (https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2018#note_3774142678) replaces the winner-only packument with a merge across every eligible upstream. #266 tracks that work. While the S31 amendment MR that #266 lists as its first item is unwritten, `docs/specs/S31-npm-virtual.md` still specifies winner-only resolution, and this step is built and reviewed against that text. Once the amendment merges, four parts of this step re-open: - **`resolution.resolve_timeout`'s default.** It is derived here as the 20-upstream Phase 2 worst case plus the Doer's `request_total_timeout`, with zero slack. The merge removes Phase 2 and makes every eligible position do a real fetch instead of a bodyless `HEAD`, so the arithmetic that produced the value stops describing the worst case. The value and the four surfaces named under `## Files` move together. - **Resolution acceptance criteria #11 and #12.** Cache fallback to the highest-priority non-winning position, and a winner Fetch failure not falling through, are both winner-shaped. The amendment rewrites them for the metadata routes. The tarball route keeps a single winner, so neither disappears outright. - **The `Transform` per position.** The merge makes every eligible position contribute bytes, so a rewriter built once per request and handed to the winner would serve one position's tarball URLs out of another position's cache row. A per-position rewriter survives the amendment unchanged; a request-global one is reworked by it. - **The aggregate verdict's arms in `virtual_read_errors.go`.** Every position absent gives `404`, every position failed gives `503`, and a data error vetoes the `404`. The rule belongs to the collection mode in `internal/virtual` that S30 books, but its translation into the npm envelope is this step's file. Unaffected either way: the facade's signature, the per-error sentinel table, and `virtual_fetch_options.go`'s `BodyKind`, size cap, and `npm.public_registry_url` guard. This step is also the whole plan's gate for that work. Step 13 depends on Step 12, Steps 15 and 16 depend on Step 14, and Steps 18 and 19 depend on Steps 15, 16 and 17, so every step issue #266 lists for update sits downstream of this one. ## The `resolve_timeout` gate is closed, and it took the mechanism with it The key is S13's, and the whole chain has landed: !2249 declared it on the `virtual_repositories.resolution` block with a `90s` default and added the `ResolveBudgetExpired` outcome, !2250 took the configuration surfaces out of this step in the plan, and !2289 landed the proto field, the loader default and validation, `config.example.yaml`, the configuration reference and the loader tests under #1069. **The ruling that arrived with it removed the mechanism from this step rather than moving it.** The S13 DRI put the aggregate budget inside `virtual.Resolver`, armed on entry and released at winner selection, so the winner's transfer, a single-flight follower's wait and a warm cache serve all sit outside it. The plan fences the facade-side passage this step was written from as not to be implemented as written, and S13's spec carries three acceptance criteria a facade-side budget fails by construction, one of which the branch's own cold-fill truncation case asserted the opposite of. #1139 carries the resolver-side work. So this step declares no configuration and arms no deadline. It keeps the facade, the slice-owned result, the fetch options and the error mapping. The mapping gains no budget-expiry arm: the verdict has no Go symbol until #1139 lands, and when it does it joins the existing `Retry-After: 1` coalescing arm rather than earning one of its own. **Nothing gates this step now.** Its `Depends on` is Step 11, which is merged. #1069 gates Step 14, not this one, because the facade holds no duration to configure. !2255 is rebased onto `main`, green, and left in Draft only for a human to confirm the rework. ## Scope One call that takes a namespace, a virtual repository, and a target and returns the resolution outcome; and the complete mapping from S13's error taxonomy to the npm envelope. ## Files - `internal/format/npm/virtual_operations.go` (Create): the facade over `virtual.Resolver.Resolve`. **It returns a slice-owned struct, not a bare `virtual.ResolveResult`.** `ResolveResult` carries `Outcome`, `Position`, `Cache`, and `Stream` and nothing else, and two consumers need more: Step 13 branches on the winner's kind and, for a hosted winner, needs the winning upstream's `repository_id`, because a virtual repository owns no npm rows of its own; Step 18 needs `winner_repository_id` and `winner_kind`. The struct therefore carries the `ResolveResult` alongside the assembled position list Step 11 built and the index-to-stored-`position` mapping. **The facade builds the kind-encoded target, which is where the document variant is chosen once.** The packument route negotiates `Accept` through `negotiatePackumentKind` and the facade turns the result into an `npmremote.Target`: `npmremote.TargetAbbreviated` for the abbreviated form, `npmremote.TargetPackument` otherwise, and `npmremote.TargetDistTags` on the dist-tags route. That target's `Path()` is the `virtual.Request.Path` every position sees, and its `MetadataKind()` is the `npm_remote_metadata_files` and `npm_metadata_files` kind column. A kind-agnostic implementation passes every other test here while answering an abbreviated `Accept` from a fresh full-kind row. **The facade also owns the resolution deadline**, because nothing else bounds a virtual read end to end. Phase 2 is bounded per probe, not in total, so a run in which every probe times out costs `ceil(N/probe_concurrency) * probe_timeout` (10s for 20 upstreams at the documented defaults), and Phase 3 then admits a follower wait of up to `single_flight_wait_timeout`, default `5m`. The facade wraps its `Resolve` call in a `context.WithTimeout` from a new `virtual_repositories.resolution.resolve_timeout`, default `40s`: the 20-upstream Phase 2 worst case plus the Doer's `request_total_timeout` (`30s`) exactly, with zero slack. **The value and everything derived from it are amendment-contingent**; if the amendment adds margin, four surfaces move together. **The deadline bounds the resolution decision, and on the warm path never the returned stream.** Both idiomatic implementations break this. A `defer cancel()` cancels every returned stream's body the moment the facade returns; omitting the cancel leaves the timer to fire `resolve_timeout` after the resolution started, on a stream the caller may still be reading. The discipline: cancel on every path that returns no stream, and on a path that returns one, hand the cancel to the stream so it runs on `Close`. That stops the timer early for a warm cache-blob serve; it does not carry a cold fill past expiry, and a fill truncated at the deadline publishes no row, so the next read re-fills from scratch. **Expiry does not take the `ErrResolverCancelled` arm.** That arm writes no response, which is right when nobody is waiting, but the deadline is sized below any sensible client patience, so when it fires the npm client is still connected and an empty implicit `200` surfaces as a JSON-parse or integrity failure. The two conditions are distinguishable at the facade because the request context is the deadline context's parent, so server-initiated expiry routes to the `503` upstream-unavailable-class arm with the fixed `Retry-After: 1` the coalescing rows carry. The key goes in the format-agnostic `virtual_repositories.resolution` block beside `probe_concurrency`, `probe_timeout`, and `single_flight_wait_timeout`, not under `npm`, because the bound is a property of the resolution and S30 and S32 need the same one. - `internal/format/npm/virtual_read_errors.go` (Create): the single mapping point for all three virtual read routes, mirroring `remote_read_errors.go`'s policy shape. The rule governing the whole table is that no error outside the answerable-terminal class may map to `404`. It also maps the three `internal/virtual` wiring-defect sentinels (`ErrZeroValueUpstreamSpec`, `ErrResolverNotConfigured`, `ErrZeroValueCoordinate`) to `500`. The mapping covers **nineteen** values, not twelve. Six of the extra seven are **derived from `remote.FallbackEligible`'s exclusion set rather than listed**, because a hand-written list goes stale the next time a sentinel is added and the failure is a silent `500`: `remote.ErrSingleFlightTimeout` (`503`, `Retry-After: 1`), `remote.ErrHeaderInjection` (`500`), `remote.ErrLeaderCanceled` (`503`, `Retry-After: 1`), `remote.ErrTransformRejected` (`500`, named rather than reached by fallthrough), `remote.ErrNotImplemented` (`500`), and `remote.ErrUpstreamDigestMismatch` (`500`). The nineteenth is `remote.ErrFillAbandoned` arriving **synchronously** from the coalesced `Fetch`, which answers `503` with `Retry-After: 1`; it is not in that exclusion set, so it needs its own named arm. Its asynchronous half, reported off the fill body's `Close`, is Step 13's. It also maps the two hosted-winner outcomes Step 8's seam surfaces, `CodeInlineBuildCapacityExceeded` and `CodeInlineBuildTimeout`, both `503` with the shed arm's `Retry-After`. Neither appears in the spec's Error Cases table, which is a gap this plan closes rather than inherits. `WinnerFetchFailedError`'s own arm defers to S15's `remoteUpstreamStatusMapping`, which emits **three** codes and not the two the spec's table names: a non-404 upstream 4xx relays as `upstream_rejected`. - `internal/format/npm/virtual_fetch_options.go` (Create): **this step owns `virtual.Request.Fetch`'s `BodyKind`, its size cap, and the unset guard**; the fill-time rewriter is Step 11's, per position. The zero value is wrong in three separate ways. - `BodyKind` must be set explicitly for the tarball route: the zero value `BodyKindMetadata` is documented as the fail-small default, so a zero-valued `Request.Fetch` fails any tarball larger than the metadata cap with `ErrResponseSizeTooLarge`. The tarball route passes `npmremote.TarballFetchOptions()`. - The metadata routes set `BodyKind` and `MaxBodyBytes` only, and the request-global options carry **no** `Transform`. The packument arm keeps `max_remote_packument_size` as `MaxBodyBytes`. **Corrected during implementation.** This bullet previously said the metadata routes pass `npmremote.MetadataFetchOptions(rewriter, maxPackumentBytes)`. That helper returns `errNilRewriter` on a nil rewriter and writes `rewriter.Transform` into the options it returns (`internal/format/npm/npmremote/fetch_options.go`), so following it forces exactly the request-global rewriter the next bullet forbids. The two bullets contradicted each other; the implementation follows the next one. - The rewriter is built on the **upstream remote repository's** base, not the virtual repository's, because the fill's bytes are the `npm_remote_metadata_files` row the standalone remote route serves from. **It is therefore per remote position, and this step does not build it**: `fetchWinner` copies `opts := req.Fetch` and hands the one `Transform` to whichever position wins, so a request-global rewriter built on position 1's base makes position 2's cache row serve position 1's tarball URLs. A single-remote fixture cannot see any of it. - The step carries the `npm.public_registry_url` unset guard (`errPublicRegistryURLUnset`), because a rewriter built on an empty base serves relative `dist.tarball` values. - `proto/artifactregistry/config/v1/config.proto`, `internal/config/virtualrepositories.go`, `config.example.yaml`, and `docs/dev/configuration-reference.md` (Modify): `resolve_timeout` and its validation, alongside the regenerated `gen/**`. - the paired test files (Create). ## Acceptance Spec AC, Resolution #6 (no winner), #7 (no upstreams), #8 (all eligible remotes unhealthy), #9 (a hosted miss alongside an unhealthy remote answers `404`, not `503`), #10 (outage answers `503`, never `404`), #11 (cache fallback serves the highest-priority non-winning position holding an entry, recorded as `served_from_fallback`), and #12 (a winner Fetch failure does not fall through). Plus Spec AC, Allow/deny rules #1 (a denial re-routes to the next upstream and emits the audit event), #2 (all denied is a `404`), #8 and #9 (a corrupt `target_field` fails the upstream closed on a tarball request **and** on a packument request, error-logged and audited under a data-error reason rather than as a denial), #10 (a corrupted deny rule never becomes eligible), #11 (every upstream ineligible for a data error is a `500`), and #12 (a data error alongside a policy denial is still a `500`). ## Tests The taxonomy table is **generated from `remote.FallbackEligible`'s exclusion set** plus the nine verdicts and the three wiring sentinels, not transcribed, and it asserts status, code, and `Retry-After` presence and value per value. A separate assertion drives an unmapped sentinel through the mapping and requires the `default:` arm to be reached only by a wrapped datastore error, so adding a sentinel to `FallbackEligible` fails this test rather than shipping a `500`. The nineteenth value needs its own case, because the generated table cannot reach it: a facade-level case producing a synchronous `remote.ErrFillAbandoned` through the leader-abandonment technique `internal/remote/standalone_test.go` and `internal/remote/singleflight_test.go` already use. Plus an explicit assertion that no mapped arm answers `404` outside the answerable-terminal class; the corrupt-rule cases driven by supplying the value to the resolver input directly rather than through an inserted row, because the range `CHECK` rejects every insert of one; `ErrResolverCancelled` writing no response and counting as no server error; an assertion that a `*url.Error` carrying userinfo is neither logged nor served with the credential intact. For the fetch options: a tarball request asserted to carry `BodyKindBlob`, a packument request asserted to carry the configured `max_remote_packument_size`, a rewriter asserted to be built on the remote repository's base and not the virtual one, and an unset `npm.public_registry_url` asserted to fail construction. For the deadline, the forcing input is **a blocking doer** whose upstream body is never closed and whose reads run on the facade's deadline context, with `request_total_timeout` wired above `resolve_timeout` in the fixture so the timer is the only canceler. The assertion is pinned to the **leader's** facade and asserted on what the client receives: a `503` carrying `Retry-After: 1` and a parseable body, not the implicit empty `200` a body-less arm produces, plus a companion case with the request context canceled first taking the `ErrResolverCancelled` arm. **The follower cannot carry that pinned value** (two timers decide the answer and the fixture controls neither), so no follower case is asserted. Three mechanics silently disarm this case if missed: 20 upstreams that all time out never reach the deadline, leader abandonment is the wrong terminal condition, and `request_total_timeout` has to be raised in the fixture. Plus the configuration round-trip and boundary-rejection cases the sibling `virtual_repositories.resolution` keys already have. ## Size Source ~530 · Test ~1,220 · Total ~1,750. Second largest non-schema step by source and over the plan's ceiling; the MR description carries the split by file group.