Files
aevolution/docs/adr/0108-cellular-checkpoint-profile.md
T
dingo d652291126
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 5m28s
Foundation / checks (checks) (push) Canceled after 7m39s
Foundation / checks (client) (push) Canceled after 7m39s
Persist fed mutation offers in cellular v2
2026-10-11 04:51:55 -04:00

100 lines
5.7 KiB
Markdown

# 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 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 ordinary successor keeps
the exact profile and version bundle of its predecessor; the only exception
is the explicit no-tick profile-4 migration defined by
[ADR-0119](0119-cellular-profile-version-migration.md).
- 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](0109-cellular-region-conservation-closure.md)).
Restore performs full validation and requires byte-identical canonical
re-encoding before readiness.
- Cap the envelope at 16 MiB ([ADR-0110](0110-cellular-checkpoint-payload-bound.md)), 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](0111-cellular-durable-action-identity.md). 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.