Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-051: Authenticated transitions and explicit source drift

Date: 2026-10-12 Status: Accepted (design; implementation tracked separately) Author: Rômulo Febasi

Context

INV-1 compares a deterministic projection of Markdown with a rebuilt index. INV-5-lite checks declared supersession edges, not every historical mutation. Existing git/hash-chain/checkpoint primitives preserve useful evidence, but a faithful rebuild of edited files cannot prove that an edit was authorized. ADR-036 correctly rejects reconstruction from a hash-only log.

Decision

Record governed changes in a versioned transition journal binding full source pre/post manifests and retrievable content images to proposals, actor keys and policy/context revisions. Verify current Markdown against the sealed accepted head, and require external signed witnessing for stronger rewrite/truncation detection.

Consequences

  • Positive: changes without a recorded transition become explicit Unattested drift.
  • Negative: journal recovery, content retention/encryption and migration add complexity.
  • Limit: the promise covers a sealed suffix from an acknowledged baseline; history before that boundary remains unknown.
  • Threat model: an attacker holding every signing key and controlling all witnesses may forge a consistent history. This remains tamper-evident under stated trust assumptions, not universally tamper-proof.

Alternatives considered

  • Hash current Markdown only: authenticates bytes but does not establish a sequence of authorized changes.
  • Replay the legacy hash-only audit as a complete store: contradicts ADR-036 and lacks content/preimages.
  • Blockchain for every write: adds availability, cost and privacy obligations without proving fact truth or authorization.
  • Silently reconcile direct edits by reindexing: erases the distinction between accepted transitions and arbitrary source drift.

Implementation contract

A transition binds schema/algorithm, workspace UUID, operation/event ID, actor/device key ID, previous accepted head/producer sequence, proposal/rule/context digests, canonical before/after manifests, content references and observed timestamps. Keys include entity type plus ID/path; cover create, update, delete and rename. Define domain-separated canonical encodings with test vectors; use exact integers/digests, not free-form ML floats.

Markdown stays the content source for reindex. Journal/receipts are authoritative evidence of governed transitions, not a hidden replacement database. Legacy events are not retroactively attested. Snapshot the explicit baseline under owner acknowledgment and begin the sealed suffix.

Use a writer lock and durable prepare/commit recovery record across filesystem/index/journal/receipt boundaries. A success acknowledgment follows a durable committed transition. On crash, recover idempotently or quarantine; fail closed on digest mismatch. Test power-loss boundaries, not merely Rust Drop rollback.

An independent witness retains signed workspace head/count/checkpoint evidence. Merkle inclusion/consistency proofs are an optional scaling primitive inspired by RFC-9162, not a claim of implementing Certificate Transparency. Fork/equivocation detection needs witness comparison/retained prior heads. A later blockchain anchor adapter may commit an approved privacy-preserving checkpoint commitment only; no raw document/identity or blindly hashed low-entropy secret is published.

References