Files
aevolution/docs/adr/0112-cellular-action-ledger-records.md
dingo e83a6393b9
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (checks) (push) Failing after 38s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 43s
Foundation / checks (ecs) (push) Canceled after 54s
Foundation / checks (tsan) (push) Canceled after 24s
Add isolated cellular checkpoint publisher
2026-10-10 23:11:27 -04:00

3.2 KiB

ADR-0112: Durable cellular action input records

Status

Accepted engineering contract for M11.3d (2026-10-10). This extends the durable action record; it does not add gameplay rules.

Context

Protocol v7 supplies a stable per-account action id, but the current M10 action ledger stores only the id, tick and commit sequence. After a restart it cannot tell an exact cellular retry from a changed movement or intake request that reuses the same id. Enabling v7 admission against that ledger would violate ADR-0111 even if the checkpoint itself were durable.

Decision

  • Keep (world, account, action_id) as the global unique key shared by legacy probe actions and cellular actions. Extend the durable record with action kind, final result and optional canonical cellular input. Legacy probe rows retain their existing result and have no cellular input.
  • Canonical cellular input is 24 bytes: intended tick (u64 little-endian), signed movement X and Y (i16 little-endian), target flag (u8), three zero reserved bytes, and target patch X and Y (u32 little-endian). Session, epoch and action id are transport/authentication or key fields and are not part of this value. The reserved bytes and absent-target coordinates must be zero.
  • The profile-4 publication records each tick's ordered canonical cellular action block and per-account action rows atomically with the checkpoint and commit receipt. The action block participates in commit identity and exact retry resolution. The same action id with identical canonical input resolves to its existing pending/final state; changed bytes are refused as invalid_action and never scheduled.
  • Refactor the database checkpoint writer behind a private transaction helper. The existing profile-1/2/3 wrapper remains behaviorally frozen. A separate cellular wrapper accepts only profile 4 and validated cellular action blocks; runtime grants do not expose the helper or a bypass around either wrapper.
  • Recovery verifies the committed action block and outcomes against input records before replay. Cellular committed outcomes use ActionResult::committed and include the tick and commit sequence; clients inspect the authoritative cellular view for state. Probe rows continue to use committed_no_effect.

Publisher representation amendment (2026-10-10)

The profile-4 action block is a sequence of 48-byte records: account UUID bytes (16), action id (u64 little-endian), and canonical cellular input (24). Records are strictly ordered by (intended tick, account bytes, action id), contain no duplicate (account, action id), and are bounded to 1,024 records. PostgreSQL validates these constraints and binds result rows to the same input bytes. The private commit-block row is immutable and is required by the progressing profile-4 commit trigger; only the profile-4 publication wrapper can create it.

Consequences

The Postgres action lookup must return both outcome and canonical input for cellular rows. Admission must compare exact bytes before returning duplicate or scheduling a new action. Migration and process tests must cover altered-ID reuse, exact retry, ambiguous commit resolution, and restart replay. Until those paths exist, RegionSessions must refuse v7 login/action admission.