Files
aevolution/docs/adr/0167-retained-plan-checkpoint-upgrade.md
T
dingo 39509ecd40
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
feat(persistence): define retained-plan checkpoint upgrade candidates
2026-10-19 14:17:41 -04:00

4.3 KiB

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.