coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

docs(canon): accept ADR-012 and retract the parts it supersedes
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details

Browse source 
ADR-012 accepted 2026-08-25.

ADR-010 — partially superseded, notes added inline:
  decision 1: "a reading of the repositories" never said which copy, and the
    answer was neither the forge nor a working copy but whichever checkout last
    synced. The hub holds no repository files and never reads one.
  decision 5: "central derives, does not accept pushes" was policy while the
    workstation pushed everything.
  decision 6: "preliminary" was named but never built.

ADR-003 — partially superseded:
  decision 2: fingerprints composed from filesystem mtime are invalidated in
    part. mtime is a property of one workstation, differs across clones, and
    says nothing about content. Evidence: git_fingerprint for the-custodian
    held the initial commit while last_state_synced_at was minutes old.
  decision 5: the rebuild principle was correct but never exercised, and its
    "without data loss" claim holds only while nothing exists solely in the hub
    — which was false for 111 records on 2026-08-25.

ADR-001, ADR-005, ADR-007 and ADR-011 reviewed and unaffected; ADR-007 is
reinforced, since derived identifiers let an overlay and a forge-derived
projection compute the same identity.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex 2026-08-25 21:44:14 +02:00
parent 8c2825f4c3
commit c0cead2169
3 changed files with 59 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

31
canon/architecture/adr-003-materialized-derived-state.md
View file

@ -16,7 +16,10 @@ tags: ["architecture", "state-hub", "caching", "read-model", "materialized-view"
## Status
Accepted.
Accepted, and **partially superseded by `ADR-012`** (accepted 2026-08-25).
Decision 2's fingerprint composition is invalidated in part; decision 5's rebuild
principle is given a concrete source and a required operation. See the notes on
each.
## Context
@ -84,6 +87,19 @@ the stored value is updated.
computation (repo record, related domain, goals, snapshots).
- Include the `mtime` (filesystem modification time) of every file that feeds
the computation (`SCOPE.md`, `CLAUDE.md`, lockfiles, `tpsc.yaml`, etc.).
> **Invalidated in part 2026-08-25 by `ADR-012` decisions 1 and 2.** Filesystem
> `mtime` is not a property of the source. It differs between machines, changes
> on a fresh clone, and says nothing about content — so a fingerprint built from
> it describes one workstation's filesystem rather than the repository. Under
> `ADR-012` the projection derives from the forge, and the commit that produced
> a record is both the correct input and the auditable one.
>
> This was not merely theoretical drift. `git_fingerprint` for `the-custodian`
> held the repository's *initial* commit while `last_state_synced_at` was minutes
> old: the field meant to identify what a projection reflects was wrong by the
> entire history of the repository, and nothing noticed. Replace `mtime` inputs
> with the source commit.
- Join all components with `|` as a pipe-separated string — no hashing needed
since the string is compared by equality, not transmitted to clients.
- If a file is absent, encode `filename:absent` rather than omitting it, so
@ -110,6 +126,19 @@ table's `max(snapshot_at)` directly rather than relying on the repo record.
Per ADR-001, the state-hub must be rebuildable from scratch by re-ingesting
all canonical sources. Materialised tables are **caches**, not records of
authority. They may be wiped and repopulated at any time without data loss.
> **Given concrete form 2026-08-25 by `ADR-012` decision 7.** This principle was
> correct and, until now, never exercised — an untested rebuild path is an
> assumption rather than a capability, and this one was believed for long enough
> that a divergence survived seven weeks behind it. `ADR-012` requires the
> reconstruction to exist as a routine operation, scoped per repository, sourced
> from the forge, and verifiable against it.
>
> The claim "without data loss" also needs its precondition stated: it holds only
> while the rule immediately below does. On 2026-08-25, 111 work records existed
> only in the hub, so a rebuild at that moment would have destroyed them.
> `ADR-012` therefore requires reset to refuse, per repository, when records have
> no counterpart in the forge.
This means:
- No materialised table may be the only copy of any information.
- Schema migrations that wipe a materialised table are safe and expected.