feat(persistence): define retained-plan checkpoint upgrade candidates
Foundation / checks (ecs) (push) Successful in 2m51s
Foundation / checks (deploy) (push) Successful in 5m18s
Foundation / checks (network) (push) Successful in 25m49s
Foundation / checks (client) (push) Successful in 26m34s
Foundation / checks (tsan) (push) Successful in 37m12s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 47m59s
Foundation / checks (postgres) (push) Canceled after 47m53s

This commit is contained in:
dingo
2026-10-19 14:17:41 -04:00
parent c0c66fa11a
commit 39509ecd40
17 changed files with 629 additions and 11 deletions
@@ -0,0 +1,77 @@
# ADR-0167: Explicit retained-plan checkpoint upgrade
## Status and scope
Accepted portable checkpoint prerequisite for ADR-0163/0165/0166, 2026-10-19.
No SQL admission, automatic upgrade, provisioning mode, population support,
control handoff, NPC behavior policy or live deployment.
## Context
Owner 8/rules 10 and raw trace 4 now have qualified portable codecs and replay.
Bundle 11 still names owner 7/rules 9. Labeling the new state with that tuple or
creating a new opening would lose the meaning of retained biology and ancestry.
An explicit checkpoint contract is required before fenced durable admission.
Population/census/migration semantics for viable unexpressed plans remain open.
## Decision
Define raw-only cellular bundle 12 as `(10,8,2,1,1,4,3,2,1)`: rules, owner,
habitat, coordinates, genome, development, founder, archive and mutation state.
The raw profile remains 4, history profile 4, quantum 50 ms and manifest layout
360 bytes. Owner 8 contains the new plan references/history; archive 2 retains
its expressed-body meaning. Mutation offer layout is unchanged. Continuation
uses raw trace 4. Old tuples, trace defaults and successful bytes stay unchanged.
The sole upgrade is an explicit raw bundle 11 -> 12 no-tick candidate. Require
a supported, structurally valid raw predecessor at positive tick/sequence,
nonzero predecessor digest, distinct result commit, next sequence without wrap,
same-frame nonzero lease, build and bounded payload binding. Preserve identity,
profile, history, quantum and tick. Empty batch evidence marks this boundary;
an ordinary successor inherits its existing tuple and cannot perform an upgrade.
No genesis, skipped prerequisite, repeated upgrade, downgrade or profile change.
Restore the entire bundle-11 source and invoke ADR-0165's exact detached owner
upgrade. Preserve all expressed genomes, stocks, boundary flows, presence,
positions, growth/damage, mutation offers and archives. Initialize each local
living/corpse plan to its current expressed genome; invent no past selections.
The full candidate must restore canonically under the target manifest, and
future recorded biology must remain raw bundle 12 with trace 4.
Portable `supported()` means reader support, not database or publication
authority. The caller must independently verify manifest/payload SHA-256
bindings and current durable head/lease. These pure functions perform no I/O,
hashing, allocation reservation or publication. Existing SQL entry points and
their version allowlists are unchanged; no durable upgrade adapter is added.
The eventual durable segment must retain both exact manifests/objects, derive
the same complete target on recovery, reject pending intervals/handoffs, fence
the atomic evidence/result/head operation and qualify retries and crashes.
Bundle 12 has no population envelope mapping. Profile conversion, population
successors, migration and census must continue to refuse it. No terminal
extinction may be inferred from missing projection support. Legacy revision
bundle helpers remain the trace-3 admission set; the new raw reader handles
bundle 12 explicitly so existing durable consumers do not silently opt in.
## Alternatives, consequences and risks
Reusing bundle 11 changes retained save meaning; new genesis loses opening stock
history; upgrading a population before plan viability semantics are defined would
silently change census and migration. A separate raw tuple permits a bounded
reviewable prerequisite while preserving those boundaries.
Risks are mistaken publication authority, cross-version payload confusion and
lost legacy expression/offer history. Exact pair checks, full source restore and
canonical target comparison address the portable risks. Durable faults and
unexpressed-plan viability require subsequent integration; this closes no M12
product or persistence gate by itself.
## Qualification
Require real retained organisms, legacy expressed revisions and funded offspring,
unchanged source bytes, exact target equality with the owner upgrade, canonical
manifest/payload restore and trace-4 continuation. Refuse malformed bindings,
wrong profiles/tuples, sequence exhaustion, genesis, repeats and old/new payload
mislabeling. A fresh process must derive identical complete manifest/payload
proof bytes from the retained source. Run Release/NDEBUG, analysis, formatting
and relevant ASan/UBSan; do not replace existing goldens.
+2
View File
@@ -1,5 +1,7 @@
# Architecture decision records
- [ADR-0167: Explicit retained-plan checkpoint upgrade](0167-retained-plan-checkpoint-upgrade.md) - portable raw-only bundle 12 and exact no-tick bundle-11 source transformation; SQL/durable admission and population support remain separate.
- [ADR-0166: Retained-plan replay traces](0166-retained-plan-replay-traces.md) - explicit raw trace 4 for owner 8/rules 10, inherited-offer action matching and complete-result replay; durable admission remains separate.
- [ADR-0165: Retained cellular offspring plans](0165-retained-cellular-offspring-plans.md) - portable owner format 8/rules 10 keeps expressed bodies separate from earned inherited plans, repeated births and selection history; durable/control/UI integration pending.