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

57 lines
3.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.