generated from coulomb/repo-seed
tegwick
747afc27a6
Aligns the v1 architecture with the longer-horizon platform thesis so we can start implementation without the schema-level inconsistencies the prior review surfaced. ADRs (docs/adr/0001..0006): content-addressed dual-digest storage, append-only event log as source of truth, canonical CBOR manifests, control/data-plane contract, v1 tech stack (Python 3.12 / uv / FastAPI / SQLAlchemy Core + asyncpg / Alembic / cbor2 / blake3 / ruff / mypy / pytest / typer), OCI compatibility kept reachable. Architecture blueprint rewritten to v2: library-first (ffmpeg-shaped) module layout, materialised-view data model over the event log, upload-session and event-stream endpoints pinned, retrieval tiering promoted into the schema. Roadmap added (docs/ROADMAP.md) with three phases. WP-0001 rewritten as the Foundation plan (scaffold + kernels + local FS + minimal app). WP-0002..0005 created carrying the existing state_hub_task_ids forward semantically: ingestion API (T004), retention lifecycle (T005), S3-compatible backend (T006), guide-board pilot (T007). T001/T002/T003/T008 remain in WP-0001 with refined acceptance. README and AGENTS.md refreshed to reflect the new repo shape. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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.
|