# 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.