## Spec Write the specification for S32 following the [spec template](docs/specs/TEMPLATE.md) and using the `spec-author` skill. **Deliverable:** `docs/specs/S32-container-virtual.md`, plus the S32 row in [docs/specs/README.md](docs/specs/README.md) (link, and status `Planned` → `Approved`). The spec lands through !972. That MR was opened before the remote/virtual work moved underneath it, so it was rebased and rewritten against the current S13, S16, and S17 text rather than merged as first drafted; the sections below describe the scope it covers. ## Scope Container **virtual** repositories (`kind=1`): an ordered composition of hosted and remote container repositories into one upstream list, resolved through [S13](docs/specs/S13-virtual-remote-foundation.md)'s single-winner algorithm. This is a vertical slice spec. It owns only the container-specific pieces layered on that resolution: - repository-kind dispatch for `kind=1`, replacing the interim `501` S16 ships on every route of a virtual container repository; - the three virtual tables — `container_virtual_repositories`, `container_virtual_repository_upstreams`, `container_virtual_upstream_rules` — and their migrations, which [S13's data model](docs/specs/S13-virtual-remote-foundation.md#data-model) assigns to the virtual slices; - the container allow/deny target fields (`0=image`, `1=tag`) and how a digest-addressed request scopes which rules decide its eligibility; - the **container Probe operation**, which [S16](docs/specs/S16-container-remote.md) defines no emitter for and hands here, including how it acquires an upstream `Authorization` header; - manifest and blob proxying backed by cross-upstream resolution, reusing S12's content-negotiation and blob contracts; - error mapping from S13's resolution taxonomy to the OCI envelope; - the fan-out metric family and wide event, plus the `probe` operation value S16 left its counter and event shaped for. Not in scope: the resolution algorithm and rule matcher themselves (S13), single-upstream remote proxying (S16), hosted OCI CRUD (S12), and the management API (S17). ## Context - [S13: Virtual and remote foundation](docs/specs/S13-virtual-remote-foundation.md) — Lookup/Probe/Fetch, the resolution phases and winner rule, the no-winner branches and cache fallback, allow/deny rule evaluation and its scoping, health monitoring, and the resolution error taxonomy. Its resolver ships as `internal/virtual`; S32 wires it rather than reimplementing it. - [S16: Container remote](docs/specs/S16-container-remote.md) — the remote upstream kind. Its cache tables back a remote position's Lookup, its Fetch serves a remote winner, and its token cache is what a container Probe reads. S16 also hands S32 two questions explicitly: how a container Probe gets its token, and how a digest mismatch behaves inside virtual resolution. - [S12: Container/OCI hosted](docs/specs/S12-container-oci-hosted.md) — the hosted upstream kind, and the path grammar, name resolution, manifest content-negotiation contract, blob and range contract, and OCI error envelope S32 reuses. - [S17: REST management API](docs/specs/S17-rest-management-api.md) — virtual-repository CRUD and the upstream-association endpoints that populate this spec's tables. - [ADR-004](docs/adr/004_data_and_application_limits.md) — 20 upstream sources per virtual repository, enforced at write time. - [ADR-007](docs/adr/007_database_schema.md) — the `container_virtual_*` tables. Already gives all three an application-generated UUIDv7 `id`, so no primary-key divergence remains for this slice. - [ADR-008](docs/adr/008_content_addressable_storage.md) — digest-keyed content is never revalidated, which is what makes a digest-addressed virtual pull resolve at Phase 1. - [ADR-009](docs/adr/009_api_design.md) — uniform client URLs across kinds; write endpoints unavailable on virtual. - [ADR-022](docs/adr/022_namespace_decoupling.md) — upstreams constrained to the same namespace. ## Decisions the spec settles Recorded in the spec's `Resolutions` so they do not have to be re-derived at plan or implementation time: - **The container Probe reads S16's token cache** rather than negotiating separately, so a Probe and the Fetch after it share one token. The handshake is charged to `container_remote.token_exchange_timeout` and the `HEAD` leg to `resolution.probe_timeout`, which S13 already fixes as bounding the `HEAD` alone. This discharges #269's fix 2 for the container path; no further S13 change is owed. - **A digest mismatch on the winner is a winner failure with no fall-through**, answering `503 UNAVAILABLE` where response headers are uncommitted and truncating the body where they are not. - **An all-ineligible read answers `500`, not the `404` an all-denied read answers.** A corrupt rule or an upstream of an unexpected `kind` is not a verdict about the image. - **`tags/list` and `referrers` answer `404 NAME_UNKNOWN`** on a virtual repository, a recorded ADR-009 divergence. S16 serving both on a single-upstream remote does not carry over: merging across independent cursors is the deferred part, and a hosted winner has no upstream to proxy. - **`target_field` scoping is the foundation's**, so this slice hands over the whole rule set and filters nothing. - **Rule CRUD is out of the closed-beta management surface**, per S17, so `container_virtual_upstream_rules` is SQL-only until a rule-CRUD patch lands. ## Merge order this spec depends on Stated in the spec's `Dependencies`, and each is a condition rather than a status: - The S13 amendment moving `target_field` scoping into the foundation, fixing the `Retry-After` value, and making upstream-kind eligibility a resolution-time concern must merge before the S32 step MR that implements rule evaluation. While it is unmerged, that step would have to carry a slice-side rule filter this spec does not define, assert a header value no approved spec states, or map an aggregate the foundation does not yet distinguish. Tracked in #609. - The S17 repository-delete guard must merge before the S32 schema MR creates `container_virtual_repository_upstreams`. The table's `NO ACTION` upstream foreign key stalls S20-A's purger from the moment the first association row exists, so the two cannot be separated by a release. - S16's remote operations and proxy handlers must merge before the first S32 client-facing handler MR, since a remote position's Lookup and Fetch are exactly those operations. Merging S32's handlers ahead of S17's virtual and remote management phase is safe — no operator can create a `kind=1` container repository until it lands — but leaves the feature unusable, and until then the three tables can only be populated by direct SQL. That is why resolution carries its own fail-closed upstream-kind check instead of relying on a write-side guard. ## Follow-ups Deferred items are tracked in #264: cross-upstream tag listing and referrers, the ADR-007 amendment for the four schema details ADR-007 leaves unstated, the ADR-009 amendment annotating the two read routes, and resolution-phase coalescing.