Files

tegwick 747afc27a6 docs+plans: reconcile blueprint with ambition, add ADRs, sequence workplans

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>

2026-05-15 21:16:17 +02:00

2.8 KiB

Raw Blame History

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

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

2.8 KiB Raw Blame History