docs(canon): ADR-012 — make the repository the unit of reconstruction
Refines decision 7. Per-repository rebuild is not a convenience over a fleet-wide operation: the repository is the unit, and the fleet-wide form is defined as iteration over it. It follows from the source — each forge repository has its own history and head, so its projection is derivable and provable in isolation. It bounds blast radius, which is what makes "routine" achievable: a rebuild that only runs fleet-wide is one nobody runs casually and therefore nobody runs, which is how ADR-010's never-executed reconstruction claim came to be believed. It is also the only form that composes with the refusals. A repository holding projection-only records can be held back while healthy ones rebuild; an all-or-nothing reset is blocked permanently by a single bad repository. The refusal is therefore evaluated per repository, and a fleet run skips and reports rather than aborting. The fleet-wide form must share the per-repository implementation, so the rare dangerous path is exercised by the common safe one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
9162f7e530
commit
8c2825f4c3
1 changed files with 38 additions and 2 deletions
|
|
@ -128,8 +128,37 @@ Three properties make it real rather than ceremonial:
|
|||
- **Routine, not emergency.** It should be run deliberately and often enough that
|
||||
it is known to work, not discovered under pressure. A reset that has never been
|
||||
performed is indistinguishable from one that does not work.
|
||||
- **Scoped.** Per repository as well as fleet-wide. Rebuilding one repository's
|
||||
records must not require discarding everything, or it will never be used.
|
||||
- **Per repository is the unit.** Not a convenience over a fleet-wide operation —
|
||||
the repository *is* the unit of reconstruction, and the fleet-wide form is
|
||||
defined as iteration over it.
|
||||
|
||||
This follows from the source. Each repository is a separate forge repository
|
||||
with its own history and its own head commit, so its projection is derivable in
|
||||
isolation and provable in isolation: fetch that repository, rebuild its
|
||||
records, compare against that repository's head. Nothing about that requires
|
||||
knowing the state of any other repository, and a design that made it require so
|
||||
would be inventing a dependency the source does not have.
|
||||
|
||||
It also bounds the blast radius, which is what makes decision 7's "routine"
|
||||
achievable. A rebuild that can only run fleet-wide is an operation nobody runs
|
||||
casually, and therefore an operation nobody runs — which is precisely how
|
||||
`ADR-010`'s never-executed reconstruction claim came to be believed. Scoped to
|
||||
one repository, a rebuild is small enough to be ordinary, and ordinary is the
|
||||
only state in which it stays known-working.
|
||||
|
||||
It is also the only form that composes with the refusals below. A repository
|
||||
holding projection-only records can be held back and dispositioned while every
|
||||
healthy repository around it is rebuilt; an all-or-nothing reset is blocked
|
||||
entirely by a single bad repository, which in practice means it is blocked
|
||||
permanently.
|
||||
|
||||
With contributors, per-repository scope is what keeps one person's rebuild from
|
||||
touching another person's records.
|
||||
|
||||
The fleet-wide form must therefore be a loop over the per-repository form,
|
||||
sharing one implementation. The rarely-used dangerous path and the frequently
|
||||
used safe path must be the same code, so the rare one is exercised by the
|
||||
common one rather than trusted on the strength of never having been run.
|
||||
- **Idempotent and verifiable.** A reset followed by a reset produces the same
|
||||
projection, and the result can be compared against the forge to show it matches.
|
||||
Derived identifiers (`ADR-007`) are what make this possible: the same commit
|
||||
|
|
@ -147,6 +176,13 @@ local database, and a rebuild at that moment would have erased them. The reset
|
|||
path must detect that condition and stop, naming what would be lost, rather than
|
||||
proceed and report success.
|
||||
|
||||
The refusal is evaluated per repository, in keeping with the scope above. A
|
||||
repository whose records all exist in the forge is rebuildable regardless of what
|
||||
any other repository holds, and a fleet-wide run must skip and report the
|
||||
repositories it refuses rather than abort the whole pass. Otherwise one
|
||||
unresolved repository blocks reconstruction everywhere, and the capability decays
|
||||
back into the untested assumption this decision exists to prevent.
|
||||
|
||||
**8. Formal git review stays optional.** Deriving from the default branch gives a
|
||||
shared baseline without requiring pull requests. Review can be adopted per
|
||||
repository where it earns its keep; this ADR neither mandates nor forbids it.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue