From a2e5cd5f68224bc8de16c7e1edabbb2a2da31d91 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 22:59:05 -0400 Subject: [PATCH] Add canonical cellular action input codec --- docs/engineering/M11_3_DELIVERY_PLAN.md | 5 +++ docs/engineering/VALIDATION.md | 14 ++++++++ include/evo/network/session_protocol.hpp | 14 ++++++++ schemas/network/session-v7-cellular-action.md | 6 ++++ src/network/protocol/session_protocol.cpp | 35 +++++++++++++++++++ tests/cellular_intent_protocol_tests.cpp | 20 +++++++++++ 6 files changed, 94 insertions(+) diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 9f4ab46..8ab30f4 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -186,6 +186,11 @@ scoped change before starting the next segment. 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. +- 11.3d-5c: the protocol library now exposes canonical 24-byte cellular input + encode/decode, excluding reconnect-specific session and epoch values. Focused + tests verify identical retry bytes and reject zero ticks, malformed flags, + reserved bytes and noncanonical absent-target addresses. Durable lookup and + publication remain open. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index fe1d288..924cd17 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6138,3 +6138,17 @@ 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. + +## 2026-10-10 — M11.3d-5c canonical cellular input bytes (CI pending) + +Added the exact 24-byte biological input codec from ADR-0112. It deliberately +omits session and epoch so identical retries across connections have identical +stored bytes. The focused test verifies round-trip and cross-session canonical +equality and rejects zero tick, invalid target flags, nonzero reserved bytes +and absent-target coordinates. + +Executed locally: warning-as-error MSVC 19.44 Debug and Release/NDEBUG direct +compile/run of the cellular protocol test and codec, plus `git diff --check`. +The CMake/Ninja target remains stalled before compilation. `clang-format` and +`clang-tidy` are unavailable on this Windows PATH. Durable ledger lookup, +PostgreSQL publication, crash resolution and CI remain pending. diff --git a/include/evo/network/session_protocol.hpp b/include/evo/network/session_protocol.hpp index 3f069f3..0e068da 100644 --- a/include/evo/network/session_protocol.hpp +++ b/include/evo/network/session_protocol.hpp @@ -151,6 +151,16 @@ struct CellularIntention { std::uint32_t intake_x_um{}, intake_y_um{}; friend bool operator==(const CellularIntention&, const CellularIntention&) = default; }; +// Canonical biological input saved with a durable cellular action. Transport session, +// epoch and action id are deliberately absent so the same retry survives reconnects. +struct CellularActionInput { + std::uint64_t tick{}; + std::int16_t move_x{}, move_y{}; + bool has_intake_target{}; + std::uint32_t intake_x_um{}, intake_y_um{}; + friend bool operator==(const CellularActionInput&, const CellularActionInput&) = default; +}; +inline constexpr std::size_t cellular_action_input_bytes = 24; // v7 reliable input: stable account-scoped action id makes retries safe across reconnects. // The server resolves the optional intake address and all biological effects. struct CellularAction { @@ -285,4 +295,8 @@ using SessionMessage = decode_session(std::span bytes); [[nodiscard]] std::expected decode_session(std::span bytes, std::uint16_t* version); +[[nodiscard]] std::array +encode_cellular_action_input(const CellularActionInput& input); +[[nodiscard]] std::expected +decode_cellular_action_input(std::span bytes); } // namespace evo::network diff --git a/schemas/network/session-v7-cellular-action.md b/schemas/network/session-v7-cellular-action.md index ebc6d69..f86a456 100644 --- a/schemas/network/session-v7-cellular-action.md +++ b/schemas/network/session-v7-cellular-action.md @@ -31,3 +31,9 @@ and its cellular state committed together; the client reads its authoritative view for the resulting state. This result is accepted only in v7. Exact retry, ID conflict, query, and commit resolution behavior follows ADR-0111 and the durable cellular publication contract. + +For persistence, the biological input is canonicalized separately as 24 bytes: +tick u64, movement X/Y i16, target flag u8, three zero bytes, and target X/Y +u32, all little-endian. Session, epoch and action id are excluded; the latter +is already the durable record key. Thus an exact reconnect retry yields the +same stored input bytes. diff --git a/src/network/protocol/session_protocol.cpp b/src/network/protocol/session_protocol.cpp index bbce35b..35439c2 100644 --- a/src/network/protocol/session_protocol.cpp +++ b/src/network/protocol/session_protocol.cpp @@ -581,4 +581,39 @@ std::expected decode_session(std::span +encode_cellular_action_input(const CellularActionInput& input) { + std::vector bytes; + bytes.reserve(cellular_action_input_bytes); + put(bytes, input.tick, 8); + put(bytes, static_cast(input.move_x), 2); + put(bytes, static_cast(input.move_y), 2); + bytes.push_back(input.has_intake_target ? 1 : 0); + put(bytes, 0, 3); + put(bytes, input.intake_x_um, 4); + put(bytes, input.intake_y_um, 4); + std::array out{}; + std::ranges::copy(bytes, out.begin()); + return out; +} + +std::expected +decode_cellular_action_input(std::span bytes) { + if (bytes.size() != cellular_action_input_bytes) + return std::unexpected(SessionCodecError::wrong_length); + if (bytes[12] > 1 || bytes[13] != 0 || bytes[14] != 0 || bytes[15] != 0) + return std::unexpected(SessionCodecError::invalid_value); + CellularActionInput input; + input.tick = get(bytes, 0, 8); + input.move_x = static_cast(static_cast(get(bytes, 8, 2))); + input.move_y = static_cast(static_cast(get(bytes, 10, 2))); + input.has_intake_target = bytes[12] != 0; + input.intake_x_um = static_cast(get(bytes, 16, 4)); + input.intake_y_um = static_cast(get(bytes, 20, 4)); + if (input.tick == 0 || + (!input.has_intake_target && (input.intake_x_um != 0 || input.intake_y_um != 0))) + return std::unexpected(SessionCodecError::invalid_value); + return input; +} } // namespace evo::network diff --git a/tests/cellular_intent_protocol_tests.cpp b/tests/cellular_intent_protocol_tests.cpp index 909334c..0dada0a 100644 --- a/tests/cellular_intent_protocol_tests.cpp +++ b/tests/cellular_intent_protocol_tests.cpp @@ -78,6 +78,15 @@ void v7_reliable_action_is_stable_and_strict() { CHECK(encode_session(*decoded) == bytes); CHECK(encode_session(SessionMessage{action}, session_protocol_v6).empty()); + const CellularActionInput input{31, -707, 707, true, 4'000, 5'000}; + const auto canonical = encode_cellular_action_input(input); + CHECK(canonical.size() == cellular_action_input_bytes); + CHECK(decode_cellular_action_input(canonical) == input); + const CellularAction retry{99, 101, 29, 31, -707, 707, true, 4'000, 5'000}; + CHECK(encode_cellular_action_input( + {retry.tick, retry.move_x, retry.move_y, retry.has_intake_target, + retry.intake_x_um, retry.intake_y_um}) == canonical); + const auto outcome = ActionOutcome{29, ActionResult::committed, 31, 41}; const auto outcome_bytes = encode_session(SessionMessage{outcome}, session_protocol_v7); CHECK(std::get(*decode_session(outcome_bytes)) == outcome); @@ -94,6 +103,17 @@ void v7_reliable_action_is_stable_and_strict() { bad = encode_session(SessionMessage{CellularAction{1, 2, 3, 4, 0, 0, false, 0, 0}}); bad[session_header_bytes + 44] = 1; CHECK(!decode_session(bad)); // An absent patch has no coordinates. + + auto malformed_input = canonical; + malformed_input[12] = 2; + CHECK(!decode_cellular_action_input(malformed_input)); + malformed_input = canonical; + malformed_input[13] = 1; + CHECK(!decode_cellular_action_input(malformed_input)); + malformed_input = canonical; + // The canonical biological input itself requires a nonzero tick. + std::fill(malformed_input.begin(), malformed_input.begin() + 8, std::uint8_t{0}); + CHECK(!decode_cellular_action_input(malformed_input)); } } // namespace