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_actionand 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::committedand include the tick and commit sequence; clients inspect the authoritative cellular view for state. Probe rows continue to usecommitted_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.