Define cellular checkpoint profile closure
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
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 4s
Foundation / image (push) Successful in 5s

This commit is contained in:
dingo
2026-10-10 22:01:00 -04:00
parent d5ffade82a
commit 09c4d3f62c
5 changed files with 166 additions and 0 deletions
@@ -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.
+1
View File
@@ -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.
+8
View File
@@ -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
+8
View File
@@ -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.
+60
View File
@@ -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.