A late addition to the shared `internal/virtual` collection mode, outside the six steps `docs/plans/2026-09-04-virtual-collection-mode.md` books. It ratifies and lands `resolution.negative_cache_ttl`, the second of the two keys S31 (npm-virtual) puts on the shared `virtual_repositories.resolution` block. The first, `resolution.position_wait_timeout`, is Step 6 of that plan and ships in https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2745. ## :mag: Findings Measured on main at 76249b2a8 and on the MR 2745 branch at bbe6ab605, while preparing S31 Step 13 (#894). - **The spec gate is real and half-open.** `docs/specs/S31-npm-virtual.md:85` makes the S13 DRI ratifying **both** keys a hard gate on the step MR that implements collection, which is S31 Step 13 part 2. MR 2745 ratifies and lands the wait bound. Nothing does the same for the negative cache. - **S13 never defines the key.** `docs/specs/S13-virtual-remote-foundation.md` has no mention of `negative_cache_ttl` or of a negative cache at all; its Configuration block defines every other key on the resolution block. S31 says the key lands there because it bounds the resolution rather than an npm leg, and that its value is the S13 DRI's to set rather than defaulted (`S31-npm-virtual.md:1189-1200`). - **No code carries it.** `git grep negative_cache_ttl` over `proto/`, `internal/`, and `config.example.yaml` returns nothing. The only hits are S31's own text, the collection-mode plan naming it as a residual, and `docs/plans/README.md`. - **No plan owns it.** The collection-mode plan says so at two places: its `### What this plan does not reach` bullet ("It needs its own steps for the in-process LRU, its ceiling, and its eviction, and folding them in here would double this plan") and its `## Dependencies` bullet ("`resolution.negative_cache_ttl` needs an owner, and it is not this plan"). The S31 plan places the LRU slice-side inside Step 13 part 2 and says nothing about the foundation half. The 2026-09-08 note on #894 records the same: "the negative cache has no plan yet, so that half of the gate is still unowned." - **The foundation vocabulary has no outcome for it.** `internal/virtual/position.go` defines nine `PositionOutcome` values and none is a negatively cached position. `internal/virtual/position_test.go:195-197` pins the `negative_cached` token as absent on purpose: "The npm virtual spec puts the negative-cache key on this seam's own resolution block rather than the slice's, so the token is unbuilt here rather than another layer's to mint." So a slice cannot emit `negative_cached` for a position until the foundation mints the outcome. - **What S31 already specifies**, so this task designs nothing new (`S31-npm-virtual.md`, section `### Cross-upstream packument merge`, the "A negative cache on a position's `404`" bullet): the cache is in-process and per pod; keyed by position and package name; replays that position's own `404`, which is an **absence** and not an omission, so a replayed absence cannot turn a `merged` into a `merged_partial`; bounded by a fixed entry ceiling with least-recently-used eviction, because the key carries a client-supplied package name and the TTL bounds an entry's life rather than the entry count; the ceiling is a fixed per-pod value set by the implementing MR against the measured per-entry cost, not a configuration key; and sizing the TTL is sizing how long a newly published private package can stay invisible behind a public one of the same name, which is why the value is ratified. Acceptance criteria 26 and 27 of that spec's Packument merge section are the two that assert it. - **Without it the merge still terminates**, so the residual is not an unbounded read. What stays open is the disclosure surface S31's Security Considerations records: every metadata read asks every position for every package, including packages only the private upstream holds. S31 calls the negative cache "the half with no interim substitute at all." ## :dart: Scope All of it foundation-side. Nothing under `internal/format/npm` changes here; S31 Step 13 part 2 consumes what this lands. 1. **S13 spec amendment**, `docs/specs/S13-virtual-remote-foundation.md`: a `resolution.negative_cache_ttl` entry in the Configuration block with its default and the ceiling argument, pointing at S31's merge section for the design rather than restating it; one sentence in the collection-mode section that a negatively cached position records an absence and issues no contributor call. 2. **The key**, mirroring how MR 2745 landed `position_wait_timeout`: the proto field on the resolution block and the regenerated `gen/**`, the loader default and positivity validation in `internal/config/virtualrepositories.go` with tests, `config.example.yaml`, and `docs/dev/configuration-reference.md`. 3. **The foundation half of the cache**: a `PositionNegativeCached` outcome in `internal/virtual/position.go`; `Collect` consulting a negative-cache seam before it asks a position, recording that outcome as an absence with no contributor call; the in-process LRU with the fixed ceiling and the TTL from the key; and `position_test.go`'s npm reconciliation moving `negative_cached` from its `absent` rows to the new outcome. ## :triangular_flag_on_post: Gates and ordering - **Plan before code.** No step books this work, so it needs either a new step appended to the collection-mode plan or a one-step plan of its own, merged before the implementation MR opens. - **Stack on MR 2745, not on main.** That MR is open and edits `Collect`; landing this on main first would conflict with it. Open every MR here as Draft. - **This task blocks S31 Step 13 part 2** (#894). Parts 1 and 3 of that step do not depend on it and proceed in parallel. ## :no_entry_sign: Out of scope - The slice-side wiring in `internal/format/npm` and the `negative_cached` wide-event token: S31 Step 13 part 2. - Any change to the winner path in `resolve.go`: a negative cache is a collection-mode cover. Related to #1243 and #894.