Evidence export

An evidence pack is a zip export of a scene at a revision, built so a third party can verify every claim in it. It bundles the diagram, its canonical source, its change history, and the provenance of every change - who authored it, and for approved proposals, who approved it.

What’s in the pack

GET /v1/scenes/:id/evidence?revision=N&from=M returns:

FileContents
scene.jsonThe canonical scene document at revision N
render.svg / render.pngThe rendered diagram. The revision watermark is forced ON: scene id, revision, and date are stamped on the image, tying the artifact to the record
changes.mdHuman-readable changelog from revision M to N: per-revision timestamp, author (agent / human / derive, plus the proposal id and approver where a proposal produced the revision), message, and element-level changes
provenance.jsonThe revision chain with full provenance fields, a scope block (revision range, coversFrom, effectiveAt), per-revision source lineage for derive-created revisions (snapshot format + server-attested SHA-256), the SHA-256 and byte size of every artifact, and the generator version. Pack formatVersion 2
manifest.jsonFile inventory with SHA-256 hashes, including provenance.json - the outermost integrity layer

revision defaults to the current revision; from defaults to 1 (full history). ?asOf=2026-06-30 (end of day UTC, or a full ISO timestamp) resolves to the revision at that instant and produces a pack byte-identical to the equivalent ?revision=N export; the batch form accepts the same asOf in its body, applied to every scene.

Determinism: re-exports reproduce identical bytes

The pack is a pure function of the revision history, the parameters, and the generator version. Nothing in it reads a clock at export time - every timestamp comes from the revisions themselves, and the zip is written store-only with fixed entry times. Export the same unchanged scene twice and you get byte-identical files, hash for hash.

That property is what makes old exports durable: anyone holding a pack can re-request the same revision later and confirm the bytes still match, or recompute any sha256 in provenance.json against the bundled files with shasum -a 256 <file>. The mechanisms behind every provenance claim, and how to verify each independently, are catalogued on the evidence integrity page.

Multi-scene batches

POST /v1/workspaces/evidence with { "sceneIds": ["a", "b"], "from": 1 } returns one zip covering up to 50 owned scenes, each under scenes/<id>/ with the same per-scene contents, plus a top-level manifest.json binding the batch through each scene’s manifest hash. Ownership is checked on every scene before anything is built - one unknown id fails the whole batch.

Revisions are subject to the workspace plan’s retention window - on the free plan, revisions older than 30 days are purged (the current revision is always kept). For a scene used as audit evidence that is the wrong default: an evidence pack attests to a history the platform might later trim.

PATCH /v1/scenes/:id/legal-hold with { "legalHold": true } exempts a scene from the automated purge entirely, whatever the plan says. Every pack’s provenance.json carries a retention block stating whether the scene is held, so a reader can tell whether the platform-side history behind the pack is protected.

The toggle is a ratchet, like scene protection: any authenticated owner may SET a hold, but releasing one requires a signed-in human session, so an agent can never clear the flag keeping evidence alive.

Legal hold defends against automated purging only. Deleting a scene, deleting a workspace, or deleting your account removes held scenes along with everything else - your right to delete your data outranks our retention. Packs you already downloaded are yours and stay valid; we keep no copy of them.

Notes