Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (checks) (push) Failing after 39s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (postgres) (push) Failing after 52s
Foundation / checks (tsan) (push) Failing after 33s
Foundation / checks (network) (push) Failing after 3m4s
Foundation / checks (client) (push) Failing after 4m22s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
# ADR-0113: Cellular replay trace
|
||
|
||
## Status
|
||
|
||
Accepted engineering contract for M11.3d (2026-10-10). This records already
|
||
selected cellular intentions for recovery; it does not change their biological
|
||
meaning or add gameplay rules.
|
||
|
||
## Context
|
||
|
||
Profile 4 stores the complete post-tick cellular closure, but recovery also needs
|
||
to prove that the committed head follows from its predecessor. The existing
|
||
environmental trace cannot represent the changing set of cellular lives,
|
||
movement intentions, and optional patch targets. Durable v7 action records bind
|
||
player actions but do not by themselves describe the complete per-life inputs
|
||
needed to replay every tick in a batch.
|
||
|
||
## Decision
|
||
|
||
- Add a separate canonical profile-4 batch format. Its 112-byte header binds the
|
||
format, profile, world, region, frame, predecessor commit and digest, and the
|
||
batch tick range. It carries one record set for each simulated tick in
|
||
`(begin_tick, end_tick]`, in order.
|
||
- Each tick has a u32 life-intent count followed by at most 256 records, strictly
|
||
ordered by nonzero stable life ID. Each record is 24 bytes: life ID (u64 LE),
|
||
movement X/Y (signed i16 LE), target-present flag (u8), three zero reserved
|
||
bytes, and target patch X/Y (u32 LE). Absent targets encode zero coordinates.
|
||
- A batch covers 1–64 ticks. Decode validates the header, count bounds, ordering,
|
||
movement limits, flags, reserved bytes, absent-target encoding, and exact total
|
||
length before allocation. The caller binds the trace header's identity,
|
||
predecessor commit/digest, and tick range to trusted manifests before replay.
|
||
Replay clones the immutable predecessor through its canonical snapshot,
|
||
advances `CellularLives` once per tick, and refuses unless every tick's intents
|
||
cover its living set exactly. Recovery compares the resulting complete snapshot
|
||
byte for byte with the committed head.
|
||
- Maximum trace size is `112 + ticks * (4 + 256 * 24)` bytes; PostgreSQL validates
|
||
the minimum and maximum for the manifest's tick count. The exact durable v7
|
||
action block is loaded under the current region lease and checked against the
|
||
relevant player-life intents and action result rows during recovery.
|
||
|
||
## Consequences
|
||
|
||
Each checkpoint batch may retain at most 393,584 bytes of replay inputs. Replay is
|
||
deterministic and bounded, while the complete post-tick checkpoint remains the
|
||
authoritative recovery state. Profile 1–3 trace formats and manifest size rules
|
||
remain unchanged. Process-level uncertain-commit and restart tests are still
|
||
required before M11.3d can close.
|
||
|
||
ADR-0114 extends the profile-4 trace to format 2. It retains the 112-byte
|
||
header and per-tick life intentions, then records a bounded birth set sorted by
|
||
account and request. Each birth record is 40 bytes: account (16 bytes), request
|
||
ID, control generation, and allocator-issued identity (u64 LE each). The birth
|
||
is replayed after that tick's existing-life step. Format-1 traces remain
|
||
decodable for already committed checkpoints. The new maximum is
|
||
`112 + ticks * (8 + 256 * (24 + 40))` bytes; migration 22 adjusts the profile-4
|
||
manifest bound without changing other profiles.
|