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)
-
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,
Implementedmeans code complete, not production-deployed. S12's scope is the OCI protocol surface (handlers, datastore, parsers, conformance), which is code-complete and verified against thedevelopment_stubsstub 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. -
Required
conformance:oci(removedallow_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 reachesmainonly when this MR merges, after !569 (merged) (Step 13). The.gitlab-ci.ymlchange also makesconformance:ocirun on this MR's own pipeline, re-verifying the suite here. -
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. -
Appendix A consolidation caveats. Every in-scope row maps to a test (E-17 is deferred to S20). Three rows cite
internal/auth/internal/storagetests, 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.ymlchange triggersconformance:oci, now a required job) and on !569 (merged)'s.mise run conformanceat0f98d91areports 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.
- 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.
- Flip the README only, as the plan's Files listed. Rejected: it leaves the S12 spec header at
Approved, self-contradicting the index. - Land the
allow_failureremoval as a separate MR againstmain. Rejected: premature, it would gatemainbefore 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).