From 0a1cf56414811f8e2019b2adc776c86e0e5a890c Mon Sep 17 00:00:00 2001 From: codex Date: Tue, 25 Aug 2026 23:46:51 +0200 Subject: [PATCH] =?UTF-8?q?docs(canon):=20amend=20ADR-012=20decision=207?= =?UTF-8?q?=20=E2=80=94=20reset=20retires,=20it=20does=20not=20delete?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Discovered before implementation: discard-and-rebuild cannot exist. Progress events, tasks, decisions and review contracts reference workplans with ON DELETE RESTRICT, and 1067 of 1075 workplans carry such a reference. Deleting a workplan would delete the hub-native records attached to it, which ADR-010 decision 4 forbids and the schema refuses. The database is enforcing this ADR's own boundary one layer down. A progress event is a fact that happened; destroying it to tidy a derived projection loses hub-native truth to fix a derived-state problem. Reset now reconciles: create what is missing, update what differs, retire what no longer derives — and retirement must be visible rather than silent. Co-Authored-By: Claude Opus 5 --- ...ojection-source-and-preliminary-overlay.md | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/canon/architecture/adr-012-projection-source-and-preliminary-overlay.md b/canon/architecture/adr-012-projection-source-and-preliminary-overlay.md index 45b4f8c..6f7dd58 100644 --- a/canon/architecture/adr-012-projection-source-and-preliminary-overlay.md +++ b/canon/architecture/adr-012-projection-source-and-preliminary-overlay.md @@ -112,8 +112,27 @@ the gap where "central derives" was policy while "the laptop pushes" was practice. **7. The projection must be resettable from the forge, as a routine operation.** -There must be a supported way to discard the projection — for one repository or -for the whole fleet — and rebuild it from what Forgejo holds. +There must be a supported way to reconcile the projection — for one repository or +for the whole fleet — against what Forgejo holds: create what is missing, update +what differs, and **retire what no longer derives**. + +> **Amended 2026-08-25, before implementation.** This decision originally said +> *discard and rebuild*. That operation cannot exist, and the reason is a good +> one. `progress_events`, `tasks`, `decisions` and `review_contracts` all +> reference workplans with `ON DELETE RESTRICT`, and 1067 of 1075 workplans carry +> at least one such reference. Deleting a workplan would mean deleting the +> hub-native records attached to it — which `ADR-010` decision 4 forbids, and +> which the schema refuses to allow. +> +> The database is enforcing this ADR's own boundary one layer down. A progress +> event recording work on a workplan is a fact that happened; destroying it to +> tidy a derived projection would be losing hub-native truth to fix a +> derived-state problem, which is exactly backwards. +> +> Retirement achieves what reset is for — the projection converges on the forge, +> and records that no longer derive stop appearing as live work — without +> erasing anything that only the hub holds. Reset reconciles; it does not +> destroy. This is the decision that makes the others checkable rather than merely stated. A read model that cannot be rebuilt from its source is not a projection; it is a @@ -164,6 +183,11 @@ Three properties make it real rather than ceremonial: Derived identifiers (`ADR-007`) are what make this possible: the same commit yields the same record identities every time. +**Retirement must be visible, not silent.** A retired record states that the +forge no longer derives it, and remains inspectable — including from whatever +hub-native history is still attached. A record that merely disappears from a +listing is indistinguishable from one that was never there. + **Reset does not restore the preliminary overlay.** Overlay records exist precisely because the forge does not hold them, so a rebuild from the forge cannot reproduce them and must not pretend to. Reset therefore discards @@ -189,8 +213,8 @@ repository where it earns its keep; this ADR neither mandates nor forbids it. ## Consequences -**Positive.** The hub becomes provably a projection: rebuildable on demand, and -therefore knowable to be one. Truth becomes checkable by anyone, from anywhere, +**Positive.** The hub becomes provably a projection: reconcilable on demand +against its source, and therefore knowable to be one. Truth becomes checkable by anyone, from anywhere, without a clone. Multiple contributors share one baseline instead of overwriting each other's views. Provenance becomes auditable — every record can name its commit. The