Files
aevolution/docs/adr/0113-cellular-replay-trace.md
T
dingo b4fe9e7628
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
Record cellular births in replay traces
2026-10-11 00:28:49 -04:00

3.1 KiB
Raw Blame History

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.