diff --git a/cmake/Network.cmake b/cmake/Network.cmake index ca65e0b..a0062b7 100644 --- a/cmake/Network.cmake +++ b/cmake/Network.cmake @@ -68,8 +68,8 @@ if(BUILD_TESTING) add_executable(evo-cellular-intent-protocol-tests tests/cellular_intent_protocol_tests.cpp) target_link_libraries(evo-cellular-intent-protocol-tests PRIVATE evo_network_protocol) evo_owned_target(evo-cellular-intent-protocol-tests) - add_test(NAME cellular-intention-protocol-v6 COMMAND evo-cellular-intent-protocol-tests) - set_tests_properties(cellular-intention-protocol-v6 PROPERTIES TIMEOUT 30 LABELS "network") + add_test(NAME cellular-session-protocol-v6-v7 COMMAND evo-cellular-intent-protocol-tests) + set_tests_properties(cellular-session-protocol-v6-v7 PROPERTIES TIMEOUT 30 LABELS "network") add_executable(evo-cellular-intent-admission-tests tests/cellular_intent_admission_tests.cpp) target_link_libraries(evo-cellular-intent-admission-tests PRIVATE evo_network_protocol) evo_owned_target(evo-cellular-intent-admission-tests) diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 8e2ce43..f17fce0 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -175,8 +175,12 @@ scoped change before starting the next segment. and only provisional receipts, so they cannot satisfy ADR-0108's exact retry requirement after reconnect. ADR-0111 keeps v6 frozen and specifies a reliable v7 action with stable account/action identity and commit-bound input/result - bytes. Durable host work is paused at this contract boundary until the v7 - codec and store records are implemented. + bytes. The codec is now implemented; durable input records, recovery and + atomic publication remain required before the host may consume it. +- 11.3d-5a: protocol v7 now defines a reliable 48-byte cellular action carrying + 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. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 8ce0b84..7f0a493 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6108,3 +6108,22 @@ records the resolution: preserve v6 unchanged and use a reliable v7 cellular action whose canonical input and final result commit with the cellular checkpoint. No implementation or tests were run for this documentation-only contract; durable host coding follows it. + +## 2026-10-10 — M11.3d-5a reliable v7 cellular action codec (CI pending) + +Added the v7 reliable-stream `CellularAction` wire value with stable nonzero +account/action identity, intended tick, signed movement fields and optional +patch target. Admission owns movement bounds. Added `ActionResult::committed` +for cellular actions and kept it +v7-only; v6 cellular intentions and their bytes remain unchanged. The schema +defines the exact 48-byte layout and identifies server-side checks still owned +by admission and durable publication. + +Executed locally: warning-as-error MSVC 19.44 direct compile and run of +`tests/cellular_intent_protocol_tests.cpp` with the protocol codec (v6 and v7 +round trips, version gates, zero identity, reserved bytes and absent-target +canonicality passed), plus `git diff --check`. The CMake/Ninja target regenerated +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. diff --git a/include/evo/network/session_protocol.hpp b/include/evo/network/session_protocol.hpp index 84252b6..3f069f3 100644 --- a/include/evo/network/session_protocol.hpp +++ b/include/evo/network/session_protocol.hpp @@ -25,6 +25,8 @@ inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN". inline constexpr std::uint16_t session_protocol_version = 4; inline constexpr std::uint16_t session_protocol_v5 = 5; inline constexpr std::uint16_t session_protocol_v6 = 6; +// v7 adds stable-id reliable cellular actions; v1-v6 wire layouts stay frozen. +inline constexpr std::uint16_t session_protocol_v7 = 7; inline constexpr std::size_t session_address_bytes = 64; // Endpoint or server name field. inline constexpr std::size_t session_datagram_bytes = 1200; // Whole message, ADR-0089. inline constexpr std::size_t session_header_bytes = 8; @@ -52,7 +54,8 @@ enum class SessionMessageType : std::uint8_t { primitive_life_receipt, primitive_life_outcome, primitive_life_query, - cellular_intention = 22 + cellular_intention = 22, + cellular_action = 23 }; // Admission answers for intentions and actions (wire 0..10). enum class AdmitStatus : std::uint8_t { @@ -76,7 +79,8 @@ enum class ActionResult : std::uint8_t { committed_no_effect = 1, // Durable in commit `commit_sequence`; changed nothing. not_committed, // Final: never part of a committed batch. pending, // Query answer only: admitted, not yet final. - unknown // Query answer only: no record of this action id. + unknown, // Query answer only: no record of this action id. + committed // Cellular action committed; inspect the authoritative view (v7). }; // Wire values 1..13. `connection_lost` is local only (the transport ended without a Close). enum class SessionCloseReason : std::uint8_t { @@ -147,6 +151,15 @@ struct CellularIntention { std::uint32_t intake_x_um{}, intake_y_um{}; friend bool operator==(const CellularIntention&, const CellularIntention&) = default; }; +// 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 { + std::uint64_t session{}, epoch{}, action_id{}, 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 CellularAction&, const CellularAction&) = default; +}; struct IntentionReceipt { std::uint64_t sequence{}; AdmitStatus status{}; @@ -175,7 +188,7 @@ struct ActionReceipt { struct ActionOutcome { std::uint64_t action_id{}; ActionResult result{}; - std::uint64_t tick{}, commit_sequence{}; // Zero unless committed_no_effect. + std::uint64_t tick{}, commit_sequence{}; // Zero unless a committed result is returned. friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default; }; struct ActionQuery { @@ -259,7 +272,7 @@ struct SessionRedirect { }; using SessionMessage = std::variant; diff --git a/schemas/network/session-v7-cellular-action.md b/schemas/network/session-v7-cellular-action.md new file mode 100644 index 0000000..ebc6d69 --- /dev/null +++ b/schemas/network/session-v7-cellular-action.md @@ -0,0 +1,33 @@ +# Session protocol v7 cellular action + +ADR-0111 defines this reliable-stream input. It uses session message type 23 and +an exactly 48-byte little-endian payload under the existing 8-byte `EVSN` +header. The version is 7 and flags are zero. Versions 1–6 retain their wire +layouts and behavior. + +| Payload offset | Size | Field | +|---:|---:|---| +| 0 | 8 | authenticated session id, nonzero | +| 8 | 8 | control epoch, nonzero | +| 16 | 8 | stable per-account action id, nonzero | +| 24 | 8 | intended simulation tick, nonzero | +| 32 | 2 | signed movement X component | +| 34 | 2 | signed movement Y component | +| 36 | 1 | intake target present: 0 or 1 | +| 37 | 3 | reserved, all zero | +| 40 | 4 | target patch lower-left X in μm | +| 44 | 4 | target patch lower-left Y in μm | + +When the target flag is zero, both coordinates must be zero. The codec rejects +zero identity fields, invalid flags, nonzero reserved bytes, noncanonical +absent-target coordinates, truncated/trailing payloads and versions other than +7. Movement bounds, patch alignment, timing, session authority and biological +effects are checked by admission and the authoritative cellular host. + +The action id is durable account-scoped identity, not a connection sequence. +Clients retry the same id only with byte-identical canonical input. A receipt +means admission only. `ActionOutcome::committed` (wire value 5) means the action +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. diff --git a/src/network/protocol/session_protocol.cpp b/src/network/protocol/session_protocol.cpp index 138fd55..bbce35b 100644 --- a/src/network/protocol/session_protocol.cpp +++ b/src/network/protocol/session_protocol.cpp @@ -12,6 +12,7 @@ constexpr std::size_t refresh_result_bytes = 1 + 8; constexpr std::size_t close_bytes = 1; constexpr std::size_t intention_bytes = (std::size_t{4} * 8) + 4; constexpr std::size_t cellular_intention_bytes = (std::size_t{4} * 8) + 4 + 1 + 3 + 8; +constexpr std::size_t cellular_action_bytes = (std::size_t{4} * 8) + 4 + 1 + 3 + 8; constexpr std::size_t intention_receipt_bytes = 8 + 1 + 8; constexpr std::size_t simulated_bytes = std::size_t{3} * 8; constexpr std::size_t action_bytes = (std::size_t{3} * 8) + 2 + 8; @@ -103,15 +104,15 @@ std::vector encode_session(const SessionMessage& message) { std::holds_alternative(message) || std::holds_alternative(message) || std::holds_alternative(message); - const auto version = std::holds_alternative(message) ? session_protocol_v6 - : is_life ? session_protocol_v5 - : session_protocol_version; + const auto version = std::holds_alternative(message) ? session_protocol_v7 + : std::holds_alternative(message) ? session_protocol_v6 + : is_life ? session_protocol_v5 : session_protocol_version; return encode_session(message, version); } std::vector encode_session(const SessionMessage& message, std::uint16_t version) { if (version != session_protocol_version && version != session_protocol_v5 && - version != session_protocol_v6) + version != session_protocol_v6 && version != session_protocol_v7) return {}; if (version == session_protocol_version && (std::holds_alternative(message) || @@ -121,6 +122,11 @@ std::vector encode_session(const SessionMessage& message, std::uin return {}; if (version != session_protocol_v6 && std::holds_alternative(message)) return {}; + if (version != session_protocol_v7 && std::holds_alternative(message)) + return {}; + if (version != session_protocol_v7 && std::holds_alternative(message) && + std::get(message).result == ActionResult::committed) + return {}; struct Encoder { std::uint16_t version; std::vector operator()(const SessionHello& m) const { @@ -173,6 +179,18 @@ std::vector encode_session(const SessionMessage& message, std::uin put(out, m.intake_y_um, 4); return out; } + std::vector operator()(const CellularAction& m) const { + auto out = header(SessionMessageType::cellular_action, cellular_action_bytes, version); + for (const auto v : {m.session, m.epoch, m.action_id, m.tick}) + put(out, v, 8); + put(out, static_cast(m.move_x), 2); + put(out, static_cast(m.move_y), 2); + out.push_back(m.has_intake_target ? 1 : 0); + put(out, 0, 3); + put(out, m.intake_x_um, 4); + put(out, m.intake_y_um, 4); + return out; + } std::vector operator()(const IntentionReceipt& m) const { auto out = header(SessionMessageType::intention_receipt, intention_receipt_bytes, version); @@ -304,7 +322,7 @@ std::expected decode_session(std::span(get(bytes, 4, 2)); if (wire_version != session_protocol_version && wire_version != session_protocol_v5 && - wire_version != session_protocol_v6) + wire_version != session_protocol_v6 && wire_version != session_protocol_v7) return std::unexpected(SessionCodecError::unsupported_version); if (version) *version = wire_version; @@ -366,7 +384,7 @@ std::expected decode_session(std::span(SessionMessageType::cellular_intention): { - if (wire_version < session_protocol_v6) + if (wire_version != session_protocol_v6) return std::unexpected(SessionCodecError::unsupported_version); if (!expect(cellular_intention_bytes)) return std::unexpected(SessionCodecError::wrong_length); @@ -386,6 +404,28 @@ std::expected decode_session(std::span(SessionMessageType::cellular_action): { + if (wire_version != session_protocol_v7) + return std::unexpected(SessionCodecError::unsupported_version); + if (!expect(cellular_action_bytes)) + return std::unexpected(SessionCodecError::wrong_length); + CellularAction m; + m.session = get(payload, 0, 8); + m.epoch = get(payload, 8, 8); + m.action_id = get(payload, 16, 8); + m.tick = get(payload, 24, 8); + m.move_x = static_cast(static_cast(get(payload, 32, 2))); + m.move_y = static_cast(static_cast(get(payload, 34, 2))); + if (payload[36] > 1 || payload[37] != 0 || payload[38] != 0 || payload[39] != 0) + return std::unexpected(SessionCodecError::invalid_value); + m.has_intake_target = payload[36] != 0; + m.intake_x_um = static_cast(get(payload, 40, 4)); + m.intake_y_um = static_cast(get(payload, 44, 4)); + if (!m.session || !m.epoch || !m.action_id || !m.tick || + (!m.has_intake_target && (m.intake_x_um || m.intake_y_um))) + return std::unexpected(SessionCodecError::invalid_value); + return m; + } case static_cast(SessionMessageType::intention_receipt): { if (!expect(intention_receipt_bytes)) return std::unexpected(SessionCodecError::wrong_length); @@ -422,10 +462,15 @@ std::expected decode_session(std::span(ActionResult::committed_no_effect) || - payload[8] > static_cast(ActionResult::unknown)) + payload[8] > static_cast(ActionResult::committed) || + (payload[8] == static_cast(ActionResult::committed) && + wire_version != session_protocol_v7)) return std::unexpected(SessionCodecError::invalid_value); - return ActionOutcome{get(payload, 0, 8), static_cast(payload[8]), - get(payload, 9, 8), get(payload, 17, 8)}; + const ActionOutcome m{get(payload, 0, 8), static_cast(payload[8]), + get(payload, 9, 8), get(payload, 17, 8)}; + if (m.result == ActionResult::committed && (!m.tick || !m.commit_sequence)) + return std::unexpected(SessionCodecError::invalid_value); + return m; } case static_cast(SessionMessageType::action_query): { if (!expect(action_query_bytes)) diff --git a/tests/cellular_intent_protocol_tests.cpp b/tests/cellular_intent_protocol_tests.cpp index 1bc1efe..909334c 100644 --- a/tests/cellular_intent_protocol_tests.cpp +++ b/tests/cellular_intent_protocol_tests.cpp @@ -1,5 +1,6 @@ #include "evo/network/session_protocol.hpp" +#include #include #include #include @@ -65,13 +66,43 @@ void malformed_frames_are_refused() { CHECK(!old_version && old_version.error() == SessionCodecError::unsupported_version); CHECK(encode_session(SessionMessage{CellularIntention{1, 2, 3, 4}}, 7).empty()); } + +void v7_reliable_action_is_stable_and_strict() { + const CellularAction action{17, 23, 29, 31, -707, 707, true, 4'000, 5'000}; + const auto bytes = encode_session(SessionMessage{action}); + CHECK(bytes.size() == session_header_bytes + 48); + std::uint16_t version{}; + const auto decoded = decode_session(bytes, &version); + CHECK(decoded && version == session_protocol_v7); + CHECK(std::get(*decoded) == action); + CHECK(encode_session(*decoded) == bytes); + CHECK(encode_session(SessionMessage{action}, session_protocol_v6).empty()); + + 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); + CHECK(encode_session(SessionMessage{outcome}, session_protocol_v6).empty()); + + auto bad = bytes; + std::fill(bad.begin() + static_cast(session_header_bytes + 16), + bad.begin() + static_cast(session_header_bytes + 24), + std::uint8_t{0}); + CHECK(!decode_session(bad)); // Stable action id cannot be zero. + bad = bytes; + bad[session_header_bytes + 37] = 1; + CHECK(!decode_session(bad)); // Reserved bytes are canonical. + 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. +} } // namespace int main() { try { round_trip_and_version_gate(); malformed_frames_are_refused(); - std::puts("PASS cellular intention protocol: v6 round trip and strict framing"); + v7_reliable_action_is_stable_and_strict(); + std::puts("PASS cellular protocol: v6 intention and v7 action strict framing"); } catch (const std::exception& error) { std::fprintf(stderr, "%s\n", error.what()); return 1;