70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
|
# ADR-0006 — OCI Artifact Compatibility Kept Reachable
|
||
|
|
|
||
|
|
Status: accepted
|
||
|
|
Date: 2026-05-15
|
||
|
|
Related: ADR-0001, ADR-0003, `docs/PLATFORM-AMBITION.md` commitment A9
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
The OCI Distribution Specification and the OCI Artifact Manifest define
|
||
|
|
a widely-deployed wire format for content-addressed artifact exchange.
|
||
|
|
The ecosystem includes `oras`, `cosign`, `crane`, Helm, ChartMuseum,
|
||
|
|
ML-model packaging tools, and most container registries. Compatibility
|
||
|
|
with this ecosystem is the single highest-leverage opportunity in
|
||
|
|
`docs/PLATFORM-AMBITION.md`.
|
||
|
|
|
||
|
|
We do not implement OCI compatibility in v1. We do refuse to take any
|
||
|
|
v1 decision that prevents it.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
1. The internal data model is structurally compatible with an OCI
|
||
|
|
artifact manifest. Concretely:
|
||
|
|
- Storage addresses content as `<algorithm>:<lowercase-hex>`
|
||
|
|
(ADR-0001). OCI requires exactly this shape.
|
||
|
|
- Manifests have a `config` blob plus an ordered list of `layers`,
|
||
|
|
each with `mediaType`, `digest`, `size`, and optional
|
||
|
|
`annotations`. Our `Manifest` value class includes all of these
|
||
|
|
fields, even when v1 has no use for `mediaType` or `annotations`.
|
||
|
|
- Manifest serialisation produces byte-identical output across
|
||
|
|
callers (ADR-0003). OCI requires this for the manifest digest.
|
||
|
|
2. The native API may be richer than OCI, but v1 reviews every schema
|
||
|
|
change against the OCI spec and rejects changes that would block
|
||
|
|
later OCI compatibility.
|
||
|
|
3. A future `/v2/` namespace will speak the OCI Distribution Spec on
|
||
|
|
top of the same storage. This is its own workplan; it does not
|
||
|
|
modify v1 endpoints, only add new ones.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
Positive:
|
||
|
|
|
||
|
|
- `oras push`, `cosign sign`, `crane copy`, Helm `chart pull` become
|
||
|
|
reachable additions, not rewrites.
|
||
|
|
- Customers who already speak OCI can adopt incrementally.
|
||
|
|
- The `mediaType` discipline forces v1 producers to label their files,
|
||
|
|
which improves the manifest's value as a portable record.
|
||
|
|
|
||
|
|
Negative:
|
||
|
|
|
||
|
|
- v1 carries some otherwise-unnecessary manifest fields. Acceptable;
|
||
|
|
the cost is bytes, not complexity.
|
||
|
|
- The OCI manifest model uses SHA-256 as the canonical digest in
|
||
|
|
practice. ADR-0001's `digest_sha256` column satisfies this; the
|
||
|
|
native primary digest can still be BLAKE3.
|
||
|
|
|
||
|
|
## What this ADR does NOT commit to
|
||
|
|
|
||
|
|
- It does not commit to implementing OCI Distribution in v1.
|
||
|
|
- It does not commit to OCI as the *only* wire format. The native API
|
||
|
|
remains the richer interface.
|
||
|
|
- It does not commit to specific OCI media types for evidence packages.
|
||
|
|
Media-type assignment is the subject of a later workplan.
|
||
|
|
|
||
|
|
## Review trigger
|
||
|
|
|
||
|
|
Every schema-affecting workplan (anything that touches the data model
|
||
|
|
or the manifest shape) must include an explicit one-paragraph review
|
||
|
|
against this ADR. Reject changes that introduce OCI-incompatible
|
||
|
|
invariants without superseding this ADR.
|