ADR-0082: Every published version is listed, and what it shipped is read from its own payload

Status: Accepted Date: 2026-09-20

Decisions

D-167 The publish surface lists every snapshot, and a version's contents are read from the payload that version stored

GET /v1/curation/snapshots answers every published snapshot in publish order: version, published at, document count, and which one devices are pulling now. GET /v1/curation/snapshots/:version answers the documents that version shipped — identity triple, section count, span count per document — read out of that snapshot's stored payload.

Not from the live rows. The payload is what the gate checked and what devices received (ADR-0056); the live rows are what the Corpus says today, and for any version but the current one those differ the moment curation continues. A history that renders today's text under last week's version number is the divergence ADR-0056 was written to close, reintroduced on a screen.

Both routes are on the curation prefix, and so are loopback-only (D-110). A device has no business with the Corpus's publication history.

Context

The publish surface could publish and could name the current version, and could answer nothing about what had been published before. A curator testing it asked how many versions exist and what is in each — which is the question a curator has to answer before republishing, and the question a supervisor asks about a corpus that ships to a plant.

The data was already there. CorpusSnapshot keeps every row with its payload, CorpusSnapshotDocument link rows survive later publishes, and the schema's own comment says that is what makes a past snapshot inspectable. Nothing read it.

Decision

Two read routes and a list-plus-drill-in surface, both reading the stored payload.

Rejected options

• Join the link rows to the live Sds rows — rejected: simpler query, one code path, and it shows a past version containing text that version never shipped.
• A list with counts and no drill-in — rejected: it answers how many and when, and leaves "what is in it" to the database, which is where the question started.

This ruling may not be re-decided

If your change contradicts an Accepted ADR: stop and raise it. Do not implement over it. Superseding requires a new ADR that says so; never edit an Accepted one.

Consequences

"What did version 2026-09-11.1 ship" has an answer on a screen, and the answer cannot drift, because it is read from bytes that are never rewritten.

What becomes hard: the detail surface parses a stored payload rather than querying rows, so a change to the payload's shape now has a reader outside the sync path. The payload's shape is versioned by the snapshot it sits in, so an old payload must stay readable by whatever reads a new one.

Coverage

No upstream finding lands here. The ruling came from a curator's prototype test on 2026-09-20 and from the snapshot schema's stated purpose (D-104).