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