docs(canon): amend ADR-012 decision 7 — reset retires, it does not delete
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 2s

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 <noreply@anthropic.com>
This commit is contained in:
codex 2026-08-25 23:46:51 +02:00
parent d5013ae48c
commit 0a1cf56414

View file

@ -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