ADR-057: Governed Markdown suffix and independently retained witnesses

Status: Accepted Date: 2026-10-13 Task: SYN-324 (#309)

Decision and scope

Opt into a limited baseline through an explicit acknowledgement of unknown preceding history and plaintext historical retention. Markdown remains current content. Scope workspace-markdown/1 covers regular .md files recursively, excluding .git and .synapse directory components regardless of ASCII case. Reject symlinks, non-UTF8/unportable names, excessive depth and budgets rather than silently omit ambiguous content. Indexes, keys, attachments and arbitrary non-Markdown files are outside the evidence claim.

Persist raw SHA-256 content-addressed images under private metadata permissions. Retention is manual with no automatic GC; filesystem encryption/access controls are the operator’s responsibility. Deleted content remains retrievable history. No encryption, confidentiality from a privileged host or historical source permission proof is inferred from a hash. No raw content or commitment is published to a blockchain or remote service by this slice.

A fixed-order compact UTF-8 JSON transition binds workspace/event identity, monotonic sequence, parent digest, baseline/mutation/reconciliation kind, local observation time, explicit actor/input claims and complete before/observed/after manifests. Prefix canonical bytes with synapse.governed-transition/1 and NUL. All fields, including nulls, are present. Map keys sort by exact UTF-8 bytes; strings are not Unicode-normalized. Unsigned integer values fit exact JSON integers; floats, unknown fields and invalid digests are rejected. Actor claims remain unverified until the separate authority/receipt layers check them.

Store a prospective transition in prepare-v2 before filesystem installation. The exact SQLite prepare digest commits index and transition intent together. After COMMIT, publish immutable record then accepted head before acknowledging success. Recovery repeats that publication if interrupted. Read old prepare-v1 intents as ungoverned; an old binary refuses v2 rather than discard evidence.

In an opted-in workspace, a mutation requires current source to match the last accepted complete manifest. Reindex cannot erase the discrepancy. Explicit reconciliation records prior accepted state and the actual externally edited source separately. Expected parent checks and unique event IDs reject conflicting or repeated transitions. Crash recovery repeats an identical decision safely.

An exported Ed25519 witness binds baseline and accepted prefix tip/count. Retain it independently and pin its public key from a trusted source; its embedded key alone is insufficient. Comparing the retained prefix detects truncation, rewritten suffixes, reorder or forks relative to that observation. Absence of a retained witness is explicitly local consistency, not non-rewrite proof.

Limits and budgets

Advisory locking cannot constrain external editors; source may change after a check. Future verification detects differences from the accepted head. The evidence proves bytes/causal ordering, not semantic truth, comprehensive natural language consistency or current organizational permission. Local timestamps are not trusted timestamps; signatures do not prove an agent followed instructions. Strict-local/team verification and authenticated shared admission are subsequent SYN-325/326/231 layers, not claims of this native record format.

Bound snapshots to10000 files/64MiB total,16MiB per file; prepare/record JSON to 16MiB; suffix verification to10000 records/64MiB metadata. Missing/purged images lose reconstruction coverage and fail verification explicitly. Larger workspaces require a reviewed scope/version/budget change rather than silent truncation.

Verification

Golden canonical vectors, all create/update/delete/rename manifests, actual crashes including record/head publication, repeated recovery, external edits followed by reindex, explicit reconciliation, tampering/missing payloads, independent witness/pin and predecessor/event conflicts. CLI and MCP call the same core operations; no network/model inference is part of acceptance.