Repository navigation
reconcile's words name system-versus-record drift, the record as the reference: linked, copied, absent, changed; orphan and missing retired #923
Description
Epic: #451 · Feature: #762 The writ lifecycle surface · Schedule: #916, lane 2, PR A · Waits on: #922 (lane 1)
The ruling
Reconcile restores the system to the record (#913).
The record is the desired state (ruled 2026-09-23): the layer checkout is only deploy's input, and becomes
the desired state by being deployed. reconcile compares the system to the record and to nothing else.
What the code says today
cmd/writ/writ/reconcile/report.go classifies each folded record against disk: linked, copied, orphan
(target present, source gone from the checkout), missing (target absent, source gone). The last two describe a
record that held things it should not -- files from earlier lifetimes -- and they compare against the checkout,
which is not the reference. With #922 in, the record is one lifetime and those rows never arise.
The change
Per record entry, reconcile says one of:
| Word | Meaning |
|---|---|
linked, copied |
the system matches the record, as today |
absent |
the record says a target is there and it is not |
changed |
the target is there but is not what the record says -- the etag moved, then the digest confirmed it |
dangling |
the source the record names does not resolve -- a link whose referent is gone, or a copy (a decrypted file, say) whose source is gone (ruled 2026-09-23, refined the same day: a reference that outlives its referent, for both kinds): repair deploy, because only deploy reads the checkout; reconcile reports it and leaves it |
stale |
the deployed thing is faithful to the record, its source resolves, and the source's content no longer matches the source digest the record holds (ruled 2026-09-23): a derivative behind an origin that still exists. Drift of the input, not of the system; its repair is upgrade, which updates the record |
orphan and missing are retired. Each drift finding keeps naming its repair in its Repair field; performing
the repair is lane 5's. The comparison reads the record only: no source path is stat'ed to decide a word.
Acceptance
-
reconcile's state vocabulary islinked,copied,absent,changed,dangling,stale, and no other word:TestBuildReport_Words(2026-09-23) - a removed target reports
absent; a target whose content moved reportschanged: the recorded digest decides it (TestBuildReport_Classifications); a touched-but-identical file hashes equal and is notchanged - no system-side word reads the layer checkout beyond the source the record names;
stalecompares the source's content to the recorded source digest -- joined through the newread_fromannotation, since the ledger records a source under the pinned snapshot path (found on the Linux VM 2026-09-23) -
5.1-reconciliation.md"Reconcile's words" and thewrit reconcileLong carry the six words and their meaning - the pages no longer say the checkout is the desired state:
5.1rewritten under deploy replaces the record: readback.Fold is bounded to the current lifetime, one writ deploy invocation across scopes #922 and reconcile's words name system-versus-record drift, the record as the reference: linked, copied, absent, changed; orphan and missing retired #923; §3.1'sreconcilerow names the words - both VMs (2026-09-23): Linux -- absent, stale, changed, dangling in turn, nothing else, clean after a deploy; Windows -- absent, changed, dangling through a link (no copy deploys there, so no
stale)
Plan and design documents
| Kind | Document |
|---|---|
| Plan | arrives with the branch |
| Design | docs/architecture/5.1-reconciliation.md |
Activity
reconcile's words name system-versus-record drift: linked, copied, ab…
Deploy replaces the record: the lifetime in the store, reconcile's si…
David-Noble-at-work commentedon Sep 24, 2026
Landed in PR #940 (merged 2026-09-24T06:13:59Z). The pull request body carried no closing keyword, so this is closed by hand.