Files
aevolution/docs/adr/0108-cellular-checkpoint-profile.md
T
dingo d0c7a938f1
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / postgres-tools (push) Successful in 5s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 5s
Specify durable cellular action identity
2026-10-10 22:51:37 -04:00

5.6 KiB

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. The in-memory snapshot/restore codec and portable profile-4 manifest allowlist are implemented; SQL validation, durable tick publication 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 region-wide opening totals, 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. Every current owner reconciles per channel to the explicit region-wide opening totals; patch source labels remain opening provenance and are not propagated through mixed inventories (ADR-0109). Restore performs full validation and requires byte-identical canonical re-encoding before readiness.
  • Cap the envelope at 16 MiB (ADR-0110), 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 player inputs, final outcomes and exact retries are transactionally bound to the checkpoint head under ADR-0111. V6 datagram receipts are provisional and cannot advance persistent cellular state; the durable host consumes a reliable v7 action with stable account/action identity. These records 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 16 MiB, and retaining corpses and lineage grows the payload; any later compaction requires a separate proof that historical identity and conservation remain closed.

Consequences

The profile codec, portable manifest allowlist and bounded SQL parser are now implemented. The database still rejects progressing profile-4 commits until the reliable v7 input/result records and dedicated atomic publisher are in place. Then add 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.