docs(oci): mark S12 implemented, consolidate coverage (S12 Step 18)

Why

Step 18 closes the OCI hosted plan: mark S12 Container/OCI hosted Implemented, consolidate the spec-coverage record, and require the conformance suite to pass now that Steps 1-17 have landed. The conformance suite is green on the stack: 75 of 80 upstream specs pass, 0 failed, 5 skipped, at the pinned commit 0f98d91a.

Stacked on the one predecessor not yet on main, feat(oci): manifest GET and HEAD content negoti... (!569 - merged) • Hayley Swimelar • 19.2. This MR targets that branch and retargets to main once it merges. Plan: docs/plans/2026-05-15-oci-hosted.md.

What (the non-obvious parts)

  1. Dropped the real-storage-driver gate from Step 18. The plan previously blocked the flip until a non-stub BlobStore backed the conformance run. Per the README status legend, Implemented means code complete, not production-deployed. S12's scope is the OCI protocol surface (handlers, datastore, parsers, conformance), which is code-complete and verified against the development_stubs stub BlobStore. Wiring a real driver into the OCI path is S06's scope. The flip now rests on a green conformance run, not on the backend behind it. This is the change you asked me to make to the plan.

  2. Required conformance:oci (removed allow_failure: true). The full OCI surface is implemented and the suite is green at the pinned commit, so a conformance failure is now a blocking regression. The stack sequences this safely: the gate reaches main only when this MR merges, after !569 (merged) (Step 13). The .gitlab-ci.yml change also makes conformance:oci run on this MR's own pipeline, re-verifying the suite here.

  3. Flipped the S12 spec header, not just the README. The plan's Files list named only docs/specs/README.md, but the spec file's own **Status:** header would otherwise contradict the index. One-line change for consistency, beyond the plan's listed Files.

  4. Appendix A consolidation caveats. Every in-scope row maps to a test (E-17 is deferred to S20). Three rows cite internal/auth / internal/storage tests, the S08/S07 contracts S12 consumes (bootstrap token, the 401 auth challenge, 24h session expiry). The manifest-push rows cite the coverage matrix from the closed !511 (closed), which the !518 (merged) / !519 (merged) / !520 (merged) split superseded. The skeleton's S-9/S-10 (manifest-size and reference-count limits) are disambiguated from some endpoint MRs' reuse of those labels for other invariants. Also backfilled the stale Status row for Step 12.

Test plan

  • Conformance: green on this MR's pipeline (the .gitlab-ci.yml change triggers conformance:oci, now a required job) and on !569 (merged)'s. mise run conformance at 0f98d91a reports 75/80 pass, 0 failed, 5 skipped. The 5 skips are explained in a note below.
  • mise run lint:markdown: markdownlint and Vale clean (0 errors).
  • No Go code or new Go tests. The conformance suite is the test surface per the plan.
Context for LLM reviewers

Design rationale. Marking S12 Implemented was originally gated on a real (non-stub) storage driver backing the conformance run. That conflated two specs: S12 is the OCI protocol implementation, and the storage backend (the BlobStore driver) is S06. The conformance suite verifies OCI protocol behavior fully against the development_stubs stub, which round-trips bytes for the harness lifetime. No plan step wires a real BlobStore into the OCI composition root (wire_oci_store_default.go returns nil, so production blob upload is 501 today); that integration belongs to S06. The status legend defines Implemented as "code complete," which the OCI surface is, so the gate was dropped and the flip rests on the green conformance run.

The conformance:oci allow_failure removal rides this MR rather than a standalone one because of sequencing. main lacks Step 13 (manifest GET and HEAD, in !569 (merged)), so conformance is not yet fully green there, and removing allow_failure on main now would break the gate. This MR stacks on !569 (merged), so the flip reaches main only after the full surface does. The job's own comment anticipated this: "a later step removes allow_failure once the final pass-rate is verified."

Rejected alternatives.

  1. Keep the real-driver gate, block S12 until S06 wires a real driver into the OCI path. Rejected: no such step exists in this plan, and it ties S12's code-complete status to S06 sequencing for no code-completeness reason.
  2. Flip the README only, as the plan's Files listed. Rejected: it leaves the S12 spec header at Approved, self-contradicting the index.
  3. Land the allow_failure removal as a separate MR against main. Rejected: premature, it would gate main before Step 13 lands.

Non-goals.

  • Wiring a real BlobStore into the OCI path (S06).
  • GC, orphan cleanup, and counter accounting (S20 / S22 per the plan's Decisions).

Stacking. Based on hswimelar/oci-hosted-step-13 at 9b649ec9 (the !569 (merged) tip). The diff is the Step 18 docs plus the conformance gate flip. Do not merge before !569 (merged).

Edited by Hayley Swimelar

Merge request reports

Loading
Loading