From d057e5ba04f72ec66761c83afea2b976a5d1bec4 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 23:18:32 -0400 Subject: [PATCH] Bind cellular actions to replay traces --- docs/engineering/M11_3_DELIVERY_PLAN.md | 6 + docs/engineering/VALIDATION.md | 12 ++ .../evo/server/lifecycle/cellular_batch.hpp | 20 +++ src/server/lifecycle/cellular_batch.cpp | 114 ++++++++++++++++++ tests/cellular_lives_tests.cpp | 16 +++ 5 files changed, 168 insertions(+) diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 4a8238c..77ccf7c 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -229,6 +229,12 @@ scoped change before starting the next segment. only profile-4 trace bounds and adds lease-fenced loading of the immutable action block. Codec, migration, and store-adapter tests are added; CI execution is pending. Action-to-life reconciliation and process recovery remain open. +- 11.3d-6d: a portable 48-byte cellular action-block codec now matches the + PostgreSQL representation. It validates canonical input/order and proves each + durable action names a life in the predecessor and exactly matches that life's + per-tick replay intention. Tests cover successful matching and changed-input + refusal. Durable action result reconciliation and full checkpoint recovery + remain open; CI execution is pending. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 70252b2..cbac518 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6243,3 +6243,15 @@ PostgreSQL store test covers lease-bound absence for an unknown commit. `git dif --check` passes. C++ compilation, PostgreSQL tests, and Linux sanitizers are pending CI because this Windows environment has no compiler or local PostgreSQL runtime on `PATH`. + +## 2026-10-10 — M11.3d-6d cellular action/trace binding (CI pending) + +Added a portable canonical 48-byte action-block encoder/decoder matching the +PostgreSQL record layout. It enforces account/action identity, input shape, +tick-range membership, canonical order, uniqueness, and the 1,024-record cap. +The trace matcher requires each durable action to resolve to a living account in +the predecessor and to match the exact movement and optional patch target for its +tick. Lifecycle tests cover exact match and changed-input refusal. + +`git diff --check` passes. C++ compilation and Linux sanitizer/CI tests are still +pending; this Windows environment has no C++ compiler in `PATH`. diff --git a/include/evo/server/lifecycle/cellular_batch.hpp b/include/evo/server/lifecycle/cellular_batch.hpp index e0fe4ca..9d663d3 100644 --- a/include/evo/server/lifecycle/cellular_batch.hpp +++ b/include/evo/server/lifecycle/cellular_batch.hpp @@ -28,6 +28,12 @@ struct CellularBatch { std::vector ticks; friend bool operator==(const CellularBatch&, const CellularBatch&) = default; }; +struct CellularActionRecord { + std::array account{}; + std::uint64_t action_id{}; + std::array input{}; + friend bool operator==(const CellularActionRecord&, const CellularActionRecord&) = default; +}; inline constexpr std::uint32_t cellular_batch_format = 1; inline constexpr std::size_t cellular_batch_header_bytes = 112; @@ -38,6 +44,9 @@ inline constexpr std::size_t max_cellular_batch_bytes = cellular_batch_header_by max_cellular_batch_ticks * (cellular_batch_tick_header_bytes + biology::max_cellular_tick_lives * cellular_batch_intent_bytes); enum class CellularBatchError : std::uint8_t { format, version, scope, state }; +inline constexpr std::size_t cellular_action_record_bytes = 48; +inline constexpr std::size_t max_cellular_action_records = 1'024; +enum class CellularActionBlockError : std::uint8_t { format, mismatch }; // Canonical replay input: one bounded, life-ID-ordered intention set per tick. [[nodiscard]] std::expected, CellularBatchError> @@ -49,4 +58,15 @@ decode_cellular_batch(std::span bytes); // Every tick must cover its living set; the caller compares the returned snapshot. [[nodiscard]] std::expected, CellularBatchError> replay_cellular_batch(const CellularLives& base, const CellularBatch& batch); +[[nodiscard]] std::expected, CellularActionBlockError> +encode_cellular_action_block(std::span actions, + std::uint64_t begin_tick, std::uint64_t end_tick); +[[nodiscard]] std::expected, CellularActionBlockError> +decode_cellular_action_block(std::span bytes, std::uint64_t begin_tick, + std::uint64_t end_tick); +// Every durable action must match the canonical input for that account's life +// in the corresponding replay tick. An action cannot create a life or intent. +[[nodiscard]] std::expected +match_cellular_actions_to_trace(const CellularLives& predecessor, const CellularBatch& batch, + std::span actions); } // namespace evo::server diff --git a/src/server/lifecycle/cellular_batch.cpp b/src/server/lifecycle/cellular_batch.cpp index 3727d83..82051fa 100644 --- a/src/server/lifecycle/cellular_batch.cpp +++ b/src/server/lifecycle/cellular_batch.cpp @@ -4,6 +4,7 @@ #include #include #include +#include #include namespace evo::server { @@ -49,6 +50,45 @@ bool valid_ticks(std::span ticks) { } return true; } +std::uint64_t action_tick(const CellularActionRecord& action) { + return get(action.input, 0, 8); +} +bool valid_action_input(const CellularActionRecord& action, std::uint64_t begin_tick, + std::uint64_t end_tick) { + const auto input = std::span{action.input}; + const auto tick = action_tick(action); + const auto move_x = std::bit_cast( + static_cast(get(input, 8, 2))); + const auto move_y = std::bit_cast( + static_cast(get(input, 10, 2))); + return !all_zero(action.account) && action.action_id != 0 && tick > begin_tick && + tick <= end_tick && move_x >= -movement_limit && move_x <= movement_limit && + move_y >= -movement_limit && move_y <= movement_limit && input[12] <= 1 && + all_zero(input.subspan(13, 3)) && + (input[12] == 1 || all_zero(input.subspan(16, 8))); +} +bool action_less(const CellularActionRecord& a, const CellularActionRecord& b) { + const auto a_tick = action_tick(a); + const auto b_tick = action_tick(b); + return a_tick < b_tick || + (a_tick == b_tick && (a.account < b.account || + (a.account == b.account && a.action_id < b.action_id))); +} +bool valid_actions(std::span actions, std::uint64_t begin_tick, + std::uint64_t end_tick) { + if (end_tick <= begin_tick || actions.size() > max_cellular_action_records) + return false; + for (std::size_t i = 0; i < actions.size(); ++i) { + if (!valid_action_input(actions[i], begin_tick, end_tick) || + (i > 0 && !action_less(actions[i - 1], actions[i]))) + return false; + for (std::size_t j = 0; j < i; ++j) + if (actions[j].account == actions[i].account && + actions[j].action_id == actions[i].action_id) + return false; + } + return true; +} void put_intent(std::vector& out, const CellularLifeIntent& life) { put(out, life.life_id, 8); put(out, static_cast(life.intent.movement.x), 2); @@ -181,4 +221,78 @@ replay_cellular_batch(const CellularLives& base, const CellularBatch& batch) { return std::unexpected{CellularBatchError::state}; return std::move(*replay); } + +std::expected, CellularActionBlockError> +encode_cellular_action_block(std::span actions, + std::uint64_t begin_tick, std::uint64_t end_tick) { + if (!valid_actions(actions, begin_tick, end_tick)) + return std::unexpected{CellularActionBlockError::format}; + std::vector out; + out.reserve(actions.size() * cellular_action_record_bytes); + for (const auto& action : actions) { + out.insert(out.end(), action.account.begin(), action.account.end()); + put(out, action.action_id, 8); + out.insert(out.end(), action.input.begin(), action.input.end()); + } + return out; +} + +std::expected, CellularActionBlockError> +decode_cellular_action_block(std::span bytes, std::uint64_t begin_tick, + std::uint64_t end_tick) { + if (end_tick <= begin_tick || bytes.size() % cellular_action_record_bytes != 0 || + bytes.size() / cellular_action_record_bytes > max_cellular_action_records) + return std::unexpected{CellularActionBlockError::format}; + std::vector out(bytes.size() / cellular_action_record_bytes); + std::size_t offset{}; + for (auto& action : out) { + const auto record = bytes.subspan(offset, cellular_action_record_bytes); + std::ranges::copy(record.first(16), action.account.begin()); + action.action_id = get(record, 16, 8); + std::ranges::copy(record.subspan(24, 24), action.input.begin()); + offset += cellular_action_record_bytes; + } + if (!valid_actions(out, begin_tick, end_tick)) + return std::unexpected{CellularActionBlockError::format}; + return out; +} + +std::expected +match_cellular_actions_to_trace(const CellularLives& predecessor, const CellularBatch& batch, + std::span actions) { + if (!valid_header(batch.header, batch.ticks.size()) || !valid_ticks(batch.ticks) || + !valid_actions(actions, batch.header.begin_tick, batch.header.end_tick)) + return std::unexpected{CellularActionBlockError::format}; + if (predecessor.world() != batch.header.world || predecessor.region() != batch.header.region || + predecessor.frame() != batch.header.frame || predecessor.tick() != batch.header.begin_tick) + return std::unexpected{CellularActionBlockError::mismatch}; + for (const auto& action : actions) { + const auto life = std::ranges::find(predecessor.lives(), action.account, + &CellularOwnedLife::account); + if (life == predecessor.lives().end()) + return std::unexpected{CellularActionBlockError::mismatch}; + const auto index = static_cast(action_tick(action) - batch.header.begin_tick - 1); + const auto& intents = batch.ticks[index].lives; + const auto intent = std::ranges::lower_bound( + intents, life->identity.life, {}, [](const CellularLifeIntent& value) { + return value.life_id; + }); + if (intent == intents.end() || intent->life_id != life->identity.life) + return std::unexpected{CellularActionBlockError::mismatch}; + const auto input = std::span{action.input}; + const auto target = input[12] == 0 + ? std::optional{} + : std::optional{ + biology::CellularPatchAddress{ + static_cast(get(input, 16, 4)), + static_cast(get(input, 20, 4))}}; + if (intent->intent.movement.x != std::bit_cast( + static_cast(get(input, 8, 2))) || + intent->intent.movement.y != std::bit_cast( + static_cast(get(input, 10, 2))) || + intent->intent.intake_target != target) + return std::unexpected{CellularActionBlockError::mismatch}; + } + return {}; +} } // namespace evo::server diff --git a/tests/cellular_lives_tests.cpp b/tests/cellular_lives_tests.cpp index 8a6c06d..defec2c 100644 --- a/tests/cellular_lives_tests.cpp +++ b/tests/cellular_lives_tests.cpp @@ -125,6 +125,22 @@ void owner_advances_and_closes_death_atomically() { CHECK(batch_bytes && batch_bytes->size() <= max_cellular_batch_bytes); const auto decoded_batch = decode_cellular_batch(*batch_bytes); CHECK(decoded_batch && *decoded_batch == replay_batch); + CellularActionRecord action; + action.account = owner.lives()[0].account; + action.action_id = 17; + action.input[0] = static_cast(owner.tick() + 1); + const std::array actions{action}; + const auto action_bytes = encode_cellular_action_block(actions, owner.tick(), owner.tick() + 2); + CHECK(action_bytes && action_bytes->size() == cellular_action_record_bytes); + const auto decoded_actions = decode_cellular_action_block( + *action_bytes, owner.tick(), owner.tick() + 2); + CHECK(decoded_actions && *decoded_actions == std::vector{action}); + CHECK(match_cellular_actions_to_trace(owner, *decoded_batch, *decoded_actions)); + auto changed_action = action; + changed_action.input[8] = 1; + const std::array changed_actions{changed_action}; + CHECK(match_cellular_actions_to_trace(owner, *decoded_batch, changed_actions).error() == + CellularActionBlockError::mismatch); const auto replayed_batch = replay_cellular_batch(owner, *decoded_batch); CHECK(replayed_batch && (*replayed_batch)->tick() == owner.tick() + 2); CHECK((*replayed_batch)->current_total() == owner.opening_total());