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
+16
View File
@@ -1,5 +1,21 @@
# Project status and next steps
## Portable retained-plan checkpoint upgrade - 2026-10-19
[ADR-0167](adr/0167-retained-plan-checkpoint-upgrade.md) defines raw-only bundle
12 and an explicit no-tick upgrade from bundle 11. It restores the complete
source, preserves expressed mutations, funded descendants, inventories, presence
and archive history, and initializes each offspring plan from its expressed
genome. The checkpoint restores and continues through raw trace 4. No genesis,
skipped prerequisites, repeats or population conversion are admitted.
Full MSVC/GCC Release suites pass **89/89**. Analysis, formatting and focused
ASan/UBSan pass; separate-process upgrade proof bytes agree across compilers.
[Validation](engineering/VALIDATION.md) records exact evidence and limitations.
This is portable reader/upgrade support. SQL and fenced durable publication,
population/census/migration admission, control succession, retained NPC behavior
and choice UI remain open; M12 is still in progress.
## Portable inherited-plan replay - 2026-10-19
[ADR-0166](adr/0166-retained-plan-replay-traces.md) adds raw trace 4 exclusively
@@ -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.
@@ -1,5 +1,12 @@
# Persistence and region authority
[ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) defines portable
raw-only bundle 12 and the explicit no-tick bundle-11 -> 12 checkpoint candidate.
Full source restore preserves expressed biology/history while initializing
retained offspring plans. Reader support is separate from SQL publication;
there is no population mapping, automatic upgrade or new durable entry point.
See [the portable upgrade contract](../../schemas/cellular-inheritance-upgrade.md).
[ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable raw trace 4
exclusively for the retained-plan owner 8/rules 10. Replay and action matching
preserve expressed/inherited meanings and return outcomes only after the entire
+3 -1
View File
@@ -52,7 +52,9 @@ needs to distinguish traits that can also change during an existing life. Existi
durable bundles, census, population and migration refuse the new owner until
their plan semantics are qualified. [Trace 4](../../schemas/cellular-region-batch-v4.md)
supplies portable replay and inherited-offer action matching; old traces refuse
this owner. The birth-time control choice,
this owner. [Bundle 12](../../schemas/cellular-inheritance-upgrade.md) supplies
its portable raw checkpoint and exact retained-source upgrade; SQL publication
is still separate. The birth-time control choice,
persistent NPC behavior and UI remain unimplemented; default/DEV rules do not
opt into this owner.
+3 -1
View File
@@ -19,7 +19,9 @@ closure. [ADR-0165](../adr/0165-retained-cellular-offspring-plans.md) adds porta
retained plans and earned selections, unchanged expressed parents and repeated
funded births. [ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable
raw trace-4 replay, action matching and exact process restart. Existing same-genome
behavior remains. Durable plan/trace/bundle,
behavior remains. [ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) defines
the portable raw checkpoint tuple and exact retained-source upgrade. Durable
plan/trace/bundle admission,
population/migration/census admission, the in-life expression catalog, authority
handoff and NPC/UI integration are still required.
+53
View File
@@ -1,5 +1,58 @@
# Validation report
## 2026-10-19 - Portable retained-plan checkpoint upgrade
[ADR-0167](../adr/0167-retained-plan-checkpoint-upgrade.md) adds raw-only bundle
12 and the exact bundle-11 -> 12 manifest/payload candidate. The new tuple has
portable reader support, no genesis or population mapping, and no SQL admission.
Legacy revision/trace admission helpers remain unchanged. The payload operation
restores the whole source before invoking the detached owner upgrade; an ordinary
successor preserves bundle 12 and biological continuation requires trace 4.
Executed locally:
- MSVC 19.44 Release full CTest **89/89 passed, 22.32 s**, with NDEBUG.
- GCC 14.2 Release full CTest **89/89 passed, 17.33 s**, with NDEBUG.
- Clang 19.1 Debug new checkpoint/actual process-restart tests **2/2 passed,
2.28 s**, built with clang-tidy 19 enabled. Both changed implementations and
the test compiled under analysis; repository clang-format 19 and diff checks
pass. No golden or existing biological rule was changed.
- Clang 19.1 ASan/UBSan region checkpoints, inherited checkpoint upgrade, upgrade
process restart and population checkpoints **4/4 passed, 26.86 s**, without
reports.
- Optional GCC persistence and session consumers rebuilt; the session adapter
test passed **1/1, 0.14 s**. No new durable admission was enabled.
The finite-food fixture acquires an actual legacy expressed mutation, produces
funded offspring and suspends its parent before the upgrade. It checks unchanged
source bytes/manifests, equality with the full owner-upgrade oracle, retained
archive/stock/identities/presence and initial plans matching current expressed
genomes rather than immutable birth genomes. Continuation resumes the parent,
earns/consumes a real plan offer, compares direct execution to trace-4 replay,
and restores each resulting bundle-12 checkpoint. No state is replenished.
Tests refuse skipped/repeated upgrades, unknown history, sequence exhaustion,
zero/reused commit or digest/build bindings, invalid holder/epoch/frame, payload
bounds, corrupt/truncated source bytes, genesis, population admission and old/new
payload mislabeling. Manifest fields and the complete target re-encode exactly.
The process test saves a source owner and manifest, then a fresh process derives
the complete target manifest plus payload. MSVC and GCC proof bytes share SHA-256
`ee8fdf41a4fc132581cea2c74788f6517414a9444bb36efeda763beccafb1f11`.
That concatenation is a test comparison artifact, not a new production codec.
These tests use opaque nonzero digest inputs to exercise the storage-free API.
They do not verify cryptographic source binding, a committed database chain or
publication authority. The caller must independently hash/verify both immutable
manifests/objects and enforce the current head/lease. SQL schema, durable upgrade
and publication adapters are unchanged. No private database fault suite, live
deployment, target-host, TSan, actual-days, client/UI or M12 completion evidence
is claimed. Fenced admission/recovery and plan viability remain subsequent work.
The refreshed DEV window expires **2026-10-19 22:17:08 UTC**. Rendered deployment
policy passes: 75 objects in 74 files, 138 rendered objects in 17 overlays, zero
failures. The unchanged policy self-test matrix was not repeated. No deployment
or World0 operation occurred; unrelated untracked work was preserved.
## 2026-10-19 - Portable retained-plan trace replay
[ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds explicit raw trace 4