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.