docs(specs): amend S32 with merged OCI collections

What

Amends S32 so virtual container repositories merge tags/list and referrers across eligible upstreams. Manifest and blob reads remain single-winner.

The merge is a cross-format decision, ratified in !2018 (note 3770508190). That thread keeps S30's Maven metadata merge and asks every format to follow it. It also scopes the OCI half: the collection endpoints merge, and manifests and blobs stay single-winner. The shared cached merged document is booked separately, under #1078.

The amendment defines PostgreSQL-backed merge sessions, best-effort tag pages, fail-closed native referrers, cursor controls, observability, and the required ADR and plan dependencies.

Scope

This MR also folds in the closed !2126 (closed) S32 specification corrections:

  • The npm virtual table is the precedent for the deferrable position constraint.
  • Invalid or oversized OCI tags return 404 MANIFEST_UNKNOWN.
  • Container virtual rule matching is case-sensitive.

These corrections belong here because they define the same S32 specification contract. The Error Cases table now includes the collection and invalid-tag cases.

Separate work

!2276 (merged) corrected the S32 implementation plan and has merged. It assigned work and recorded dependencies, rather than changing the S32 specification.

!2231 (merged) remains separate because it documents the npm virtual rule adapter in source code. It belongs to S31 and has separate code-owner review.

Implementation plan

This amendment adds no step to the existing S32 plan. The merged-collections implementation travels in a second plan, docs/plans/<date>-s32-merged-collections.md, authored after this MR merges. An ADR-007 amendment, an ADR-009 amendment, and S04-C's production encryptor wiring gate that tranche; they gate no step in the current plan. Appending steps would also move the <total> in the title marker of every S32 step MR that is not yet open.

The new plan's schema step owns one consequence of the tables above. The session-sources foreign key needs UNIQUE (id, namespace_id, container_virtual_repository_id) on container_virtual_repository_upstreams. The merged table carries its primary key and two other unique constraints, not that one. That step adds the constraint beside the two session tables, and its migration merges after Step 3's, because goose refuses an out-of-order timestamp.

Checks

markdownlint-cli2, vale, lychee, and the full commit hook chain pass.

Related to #291 Related to #264

Edited by Radamanthus Batnag

Merge request reports

Loading
Loading