Specify durable cellular action records
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / server-image (push) Successful in 4s
Foundation / postgres-tools (push) Successful in 5s
Foundation / image (push) Successful in 5s

This commit is contained in:
dingo
2026-10-10 22:58:18 -04:00
parent d1717410d6
commit 49f6fac3e7
4 changed files with 66 additions and 0 deletions
@@ -0,0 +1,49 @@
# 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`.
## 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.
+1
View File
@@ -12,6 +12,7 @@
- [ADR-0109: Cellular region-wide conservation closure](0109-cellular-region-conservation-closure.md) - corrects profile-4 accounting to conserved region totals per channel while retaining patch provenance.
- [ADR-0110: Cellular checkpoint payload bound](0110-cellular-checkpoint-payload-bound.md) - raises profile-4's maximum object size so the complete retained archive and corpse limits fit.
- [ADR-0111: Durable identity for cellular player inputs](0111-cellular-durable-action-identity.md) - specifies the reliable v7 action identity needed for commit-bound cellular outcomes and exact retries.
- [ADR-0112: Durable cellular action input records](0112-cellular-action-ledger-records.md) - specifies canonical retry bytes, persisted result identity and the isolated profile-4 publisher needed before v7 admission.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+5
View File
@@ -181,6 +181,11 @@ scoped change before starting the next segment.
stable per-account action identity, plus a distinct committed-cellular result.
The strict codec and round-trip/refusal tests are implemented; admission,
durable input records and atomic tick publication remain open.
- 11.3d-5b contract audit: the existing durable ledger omits canonical input,
so it cannot reject changed bytes for a retried id after restart. ADR-0112
defines a 24-byte canonical biological input, profile-4 commit action block,
and isolated cellular publisher. V7 server admission remains refused until
this input-aware ledger and exact-retry resolution are implemented.
## Exit boundary
+11
View File
@@ -6127,3 +6127,14 @@ successfully but idled without starting compilation; direct compilation was
used. `clang-format` and `clang-tidy` are unavailable on this Windows PATH. CI,
server admission, action ledger input bytes, durable publication and restart
recovery remain pending.
## 2026-10-10 — M11.3d-5b cellular action ledger contract (documentation)
The server-routing audit confirmed that migration-11 action rows keep only the
stable id and committed tick/sequence, so they cannot compare retried cellular
input after reconnect or process restart. ADR-0112 specifies the canonical
24-byte biological input, immutable per-commit action block, per-action final
result, exact-byte duplicate rule and isolated profile-4 publisher. V7 login
and action admission remain disabled until these records and the recovery path
are implemented. This contract-only segment was checked with `git diff --check`;
the migration and PostgreSQL process checks are pending.