diff --git a/docs/adr/0108-cellular-checkpoint-profile.md b/docs/adr/0108-cellular-checkpoint-profile.md new file mode 100644 index 0000000..99c1afb --- /dev/null +++ b/docs/adr/0108-cellular-checkpoint-profile.md @@ -0,0 +1,89 @@ +# ADR-0108: Cellular life checkpoint profile + +## Status + +Accepted M11.3 engineering direction (2026-10-10). This is an additive format +contract; it does not change gameplay constants selected by ADR-0098. Profile +implementation, SQL validation and recovery fault tests remain incomplete. + +## Context + +Profile 3 (`primitive-lives-v1`) durably records funded creation and lineage, +but intentionally has no movement, feeding or progressing biology. ADR-0101's +finite habitat and ADR-0102's position cannot be attached as optional sections +to profile 3: that would make old bytes ambiguous and let missing state look +like defaults. A cellular tick changes life inventories and habitat stock +together, and ADR-0107 additionally produces corpses and a heat transfer. + +## Decision + +- Add a distinct `cellular-lives-v1` checkpoint profile (profile value 4) with + its own canonical envelope and restore path. Profile 3 bytes, cap, versions, + genesis rules and SQL behavior remain unchanged. A region's successor keeps + the exact profile and version bundle of its predecessor. +- The envelope is a complete single-region state closure, not a tick delta. It + binds world, region, frame, the current 50 ms simulation tick and the cellular + rule/version bundle. It contains the finite habitat and its explicit opening + totals by source, every living life, every retained corpse, accumulated heat, + and the complete lineage archive. No field may be reconstructed from an + absent section or a default. +- Each living record binds its life/account identity (when player-controlled) + to organism and genome identities, birth tick, growth state, micrometre + position, body and reserve inventories, and every timer introduced by the + selected rules. Phenotype and metabolic budgets are recomputed from the + archived genome and growth state during restore; encoded copies, if used for + acceleration, must compare exactly with recomputation. Heat is a separate + energy-only region account. A corpse retains the dead organism identity, + contact position and transferable body/reserve inventory; accumulated heat + cannot be re-ingested. +- Closure requires the archive's living organisms to equal the checkpoint's + living organism set; every live genome reference resolves; every birth/death + is no later than the checkpoint tick; player account bindings are unique; all + positions and footprints are inside the finite area; and all inventories, + corpses, habitat stock and heat satisfy their channel rules. For each source, + current stock plus all downstream holdings must reconcile to its explicit + opening total. Restore performs full validation and requires byte-identical + canonical re-encoding before readiness. +- Cap the envelope at 8 MiB, with at most 256 living cells, 4,096 provisioned + patches and 65,536 retained organisms/corpses. Validate lengths and counts + before allocation. The existing archive and habitat codecs are nested with + their formats and checksums; the manifest SHA-256 remains the integrity + binding. Profile-specific version slots must explicitly pin the cellular + rule, envelope, habitat, coordinate, genome, development, founder and archive + formats before the profile is admitted by `supported()` or PostgreSQL. +- Canonical cellular intentions, final outcomes and exact retries remain in + the existing durable decision/publication records, transactionally bound to + the checkpoint head. They are not a client-authored state section. A session + reconnect never advances biology; only the fenced region owner may publish a + tick. Profile-4 cloning stays unsupported until its identity and source-total + remapping rules are specified. + +## Alternatives considered + +- **Add optional cellular fields to profile 3:** rejected because old profile-3 + data would be reinterpreted and a missing life/habitat section could be + mistaken for an empty one. +- **Persist only active cells and the habitat:** rejected because death would + erase ancestry, corpses or already-accounted heat from recovery closure. +- **Keep action retry state only in worker memory:** rejected because an + uncertain database response could repeat an intake or terminal outcome. +- **Let restore repair missing fields from founder defaults:** rejected because + that can change a paid body, position, reserve or lineage after a crash. + +## Benefits and costs + +One verified object contains every biological owner affected by a tick, so the +existing fenced head publication can make the habitat transfer, life result, +corpse, heat and lineage visible together. The format is bounded and reuses +existing genome, archive and habitat validators. Each batch rewrites up to +8 MiB, and retaining corpses and lineage grows the payload; any later compaction +requires a separate proof that historical identity and conservation remain +closed. + +## Consequences + +Implement the profile codec and restore validator before admitting it to the +manifest allowlist. Then extend the SQL profile parser/caps and add process +publication, uncertain-commit, kill/restart and profile-3 compatibility tests. +Until those gates pass, no cellular state is durably playable and M11.3d/e stay +open. diff --git a/docs/adr/README.md b/docs/adr/README.md index 992a562..f8d2c36 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,6 +8,7 @@ - [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 has an opt-in admission path. - [ADR-0106: Cellular contested patch arbitration trial](0106-cellular-contested-patch-arbitration.md) - accepted M11.3 trial resolves same-tick finite-stock claims by stable life identity, independent of connection order. - [ADR-0107: Cellular starvation and corpse transfer trial](0107-cellular-starvation-and-corpse-transfer.md) - accepted M11.3 death closure transfers body/reserve to a corpse and accumulated heat to the region heat owner. +- [ADR-0108: Cellular life checkpoint profile](0108-cellular-checkpoint-profile.md) - accepted additive profile-4 state-closure direction; codec, SQL admission and recovery remain open. - [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index bedab87..94e11e0 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -74,6 +74,11 @@ No new dependency or renderer is required. If the selected spatial, checkpoint, or publication design conflicts with accepted architecture, stop that affected implementation and resolve the contract first. +ADR-0108 and `schemas/cellular-lives-v1.md` define an additive profile-4 state +closure while preserving profile 3. This is a contract only: codec/restore, SQL +allowlisting, a cellular region owner and crash-recovery evidence are still +required before the first hands-on cellular probe. + ## Delivery segments For each segment, name affected modules, run its applicable tests and checks, @@ -145,6 +150,9 @@ scoped change before starting the next segment. - 11.3c-5: ADR-0107 closes unaffordable maintenance in the same tick, moving body and reserve into a corpse candidate and accumulated heat to an explicit output. The durable heat owner and lineage/checkpoint publication remain open. +- 11.3d contract: ADR-0108 and `schemas/cellular-lives-v1.md` define a separate + profile-4 checkpoint closure for lives, habitat, corpses, heat and lineage. + No profile-4 code or durable tick publication is implemented yet. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 0a49325..9f49a5d 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6019,3 +6019,11 @@ identities; and `git diff --check`. `clang-format` and `clang-tidy` were not ins available on PATH in this Windows environment. CTest, Linux sanitizer/CI qualification, durable heat ownership, lineage and checkpoint publication remain pending. + +## 2026-10-10 — M11.3d profile-4 closure contract (implementation pending) + +ADR-0108 and `schemas/cellular-lives-v1.md` specify an additive complete +cellular checkpoint while preserving profile 3. This is documentation only; +no codec, SQL admission or recovery behavior is implemented or validated by +this entry. `git diff --check` is the applicable local check. Profile-4 code, +PostgreSQL CI and crash/restart tests remain required. diff --git a/schemas/cellular-lives-v1.md b/schemas/cellular-lives-v1.md new file mode 100644 index 0000000..cba26f1 --- /dev/null +++ b/schemas/cellular-lives-v1.md @@ -0,0 +1,60 @@ +# Cellular lives checkpoint envelope v1 + +This schema is specified by [ADR-0108](../docs/adr/0108-cellular-checkpoint-profile.md). +It is the complete payload for region checkpoint profile 4, +`cellular-lives-v1`. Profile 3 remains the independent creation-only +`primitive-lives-v1` format. + +## State closure + +The canonical little-endian envelope carries explicit lengths and versions for +the region identity, 50 ms current tick, finite cellular area, provisioned +habitat and source opening totals, ordered living-cell records, ordered corpse +records, region heat and the complete lineage archive. Integers have fixed +widths; records are sorted by stable identity/address. Decoders reject unknown +versions, nonzero reserved fields, duplicate or noncanonical records, +overflow, trailing bytes, malformed checksums and any count or length above the +caps before allocating from untrusted lengths. + +The state is complete at one committed tick. It contains no pending or +client-authored intentions. Durable action requests and outcomes remain in the +fenced database batch records that publish the matching checkpoint. + +Each living record retains player-account binding when present, life and +organism identity, current genome identity, birth tick, growth state, position, +body matter, reserve energy/matter and every timer required by the selected +cellular rule version. Extent, phenotype and metabolic budgets are derived from +the archived genome and growth state. Restore recomputes them; a stored cache +must exactly match or the payload is refused. + +Each corpse retains the dead organism identity, death tick, final position and +transferable body/reserve inventory. Heat is a separate energy-only region +account. The habitat carries its finite patch stock and provenance plus the +explicit opening total for each source. For every ledger channel and source, +opening holdings must reconcile exactly to current habitat, living bodies and +reserves, corpses and heat according to the declared transfers. + +Restore requires exact world/region/frame and end-tick agreement with the +manifest, complete organism/genome/archive closure, unique player bindings, +in-bounds footprints, valid energy/matter channels, and canonical byte-identical +re-encoding. Genesis contains no living cells or corpses. Profile-4 clone genesis +is unsupported until an identity-remapping contract exists. + +## Bounds + +| Component | Maximum | +|---|---:| +| Total payload | 8 MiB | +| Living cells | 256 | +| Provisioned food patches | 4,096 | +| Retained organisms and corpses | 65,536 | + +Every nested format/version is pinned by profile 4's manifest version bundle. +The manifest SHA-256 verifies the immutable object; nested checksums are for +early corruption detection and canonical decoding, not authentication. + +## Implementation status + +This document records the approved closure direction only. No profile-4 codec, +SQL admission or recovery implementation is claimed until the corresponding +code and tests land.