Complete M7.9b upgrade barrier and durability qualification

Schema v8 binds authority to builds (ADR-0068): acquisition names the
host build and only retained, unretired builds may hold a lease; no
commit may name a retired build; upgrade_barrier retires a build and
fences every holder in one transaction, while build-less pre-v8 hosts
keep working until the first barrier. Tests cover a writer surviving a
failed and then a real online migration, old-writer fencing on every
path, whole-history recovery by the new build, and the M7 qualification
fixture (19.6 s SIGKILL-to-ready under the production lease, no lost
acknowledgements).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-29 07:31:04 -04:00
co-authored by Claude Opus 5.5
parent 703f67834f
commit f59cca2c3b
24 changed files with 893 additions and 52 deletions
+96
View File
@@ -0,0 +1,96 @@
# ADR-0068: Upgrade barrier, build-bound authority and durability qualification
## Status
Accepted for M7.9b, 2026-09-29. It completes M7.9 with ADR-0067 (clones). It
changes the ADR-0060 acquisition contract (schema v8). Rules and format
conversions remain unimplemented: no converter exists, so every change is
refused explicitly.
## Context
M7.9 requires:
- explicit rule and format rejection or migration;
- evidence for a migration failure and for fencing old writers;
- measured recovery and batching latency.
PERSISTENCE_ARCHITECTURE's upgrade path is: barrier, clone, migrate, compare,
approve, then a compatible deployment at a world barrier. That implies:
- A new build must be able to take over a region.
- Every writer of the old build must be stopped for good, including one that is
paused, idle, or restarted from an old image.
- History written by the old build must stay recoverable.
Before v8, any retained build could publish, and acquisition did not name a
build. A fenced old host could therefore re-acquire an idle region and renew it
forever.
## Decision
**Build-bound authority (schema v8).**
- `retained_builds.retired_at` marks a build as retired from publication. The
row, and so the recoverability of its history, stays.
- A `region_commits` insert trigger refuses any new commit that names a retired
build (EVL06). This covers publications, provisioned geneses and clone
geneses.
- `acquire_region_lease(world, region, duration, build)` grants authority only to
a retained, unretired build (EVL06 otherwise). The C++ API takes the build. The
host quarantines on `unsupported` (exit 4): a retired image never serves or
holds an idle lease.
- The build-less 3-argument form remains for pre-v8 hosts during a rolling
schema upgrade. It refuses once any build has been retired.
- Both forms wrap the internal `grant_region_lease`, which the runtime cannot
execute. The runtime audit now covers twelve functions.
**Barrier.** The owner-only `upgrade_barrier(build)` retires one build and clears
every current lease holder in the database, in one transaction:
- Existing holders are fenced at their next renewal or publication.
- They cannot re-acquire by either form.
- A commit already waiting on a lease row is judged after the barrier commits.
- Retiring the last current build is refused.
- Epochs are kept, so the next acquisition takes a fresh one.
Operator order:
1. Migrate the schema. Old hosts keep their leases, because renew and publish are
unchanged.
2. Retain the new build.
3. Deploy hosts with `--build new --retained old`.
4. Run the barrier for the old build.
**Explicit rejection.** A region never changes profile, versions, quantum or
history profile (EVL06 at publication; `unsupported` at recovery). A clone
inherits them unchanged. No rules or format converter is registered. Adding one
requires a new ADR, a versioned conversion that is replayed and compared on a
clone, and approval. Retirement is irreversible through this interface. Undoing
it is an audited owner break-glass action, valid only while formats and rules are
identical.
**Qualification fixture.** The fixture is:
- the production lease policy (20 s lease, 5 s renewal, 2 s margin) and a 1 s flush;
- one lineage region paced at 50 ms per tick;
- a local socket and filesystem, on WSL2.
It measures:
- acknowledgement latency;
- the time from SIGKILL to the successor's readiness, against the proposed 60 s
target (asserted for this fixture only);
- head verification, full audit and clone cost.
The results are in engineering/DURABILITY_QUALIFICATION.md.
## Consequences
- Recovery after losing a worker is dominated by the lease: a successor waits out
the dead holder's remaining lease, up to 20 s, and verification adds
milliseconds. Shortening the lease trades that time against false fencing
under database latency (ADR-0060).
- Migrations run in one transaction under an advisory lock and a 5 s lock timeout.
A publication waiting on migration locks may become ambiguous; resolution
handles it (ADR-0063). A failed migration leaves the previous schema exactly.
- Binaries built before M7.9b (3-argument acquisition) work against v8 until the
first barrier. Binaries from M7.9b onwards require schema v8.
## Alternatives rejected
- **Retirement only, checked at publication.** An idle old host could still hold
a lease forever.
- **Bumping epochs without retirement.** Old hosts would simply re-acquire.
- **Dropping the 3-argument acquisition in v8.** Every old host would be stranded
mid-upgrade before the new build was deployed.
- **In-place rules migration of a live region.** It would change physical laws
without the clone-and-compare approval that the vision requires.
+1
View File
@@ -78,3 +78,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0065: Recovery before readiness](0065-recovery-before-readiness.md) - accepted for M7.7 head tail replay verification, schema v6 commit lookup and real kill-boundary tests.
- [ADR-0066: Operations endpoints](0066-operations-endpoints.md) - accepted for M7.8 liveness vs authority readiness, bounded metrics, dependency-free responder and the server image.
- [ADR-0067: Region clones and retained-history audit](0067-region-clones.md) - accepted for M7.9a re-identified clone genesis naming its source cut, isolated clone databases and full-chain retention audit.
- [ADR-0068: Upgrade barrier and durability qualification](0068-upgrade-barrier.md) - accepted for M7.9b build-bound authority, retirement barrier fencing old writers, explicit refusal of rule/format changes and the measured recovery fixture.