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
100 lines
5.7 KiB
Markdown
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.
|