From 49f6fac3e756b384c350c7a46250a437074b7d65 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 22:58:18 -0400 Subject: [PATCH] Specify durable cellular action records --- .../0112-cellular-action-ledger-records.md | 49 +++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/M11_3_DELIVERY_PLAN.md | 5 ++ docs/engineering/VALIDATION.md | 11 +++++ 4 files changed, 66 insertions(+) create mode 100644 docs/adr/0112-cellular-action-ledger-records.md diff --git a/docs/adr/0112-cellular-action-ledger-records.md b/docs/adr/0112-cellular-action-ledger-records.md new file mode 100644 index 0000000..ecf53b6 --- /dev/null +++ b/docs/adr/0112-cellular-action-ledger-records.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 5ec33c8..71ca554 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index f17fce0..9f4ab46 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -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 diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 7f0a493..fe1d288 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.