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
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:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user