diff --git a/cmake/Network.cmake b/cmake/Network.cmake index 65d6f91..5a78b6c 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-session-protocol-v6-v9 COMMAND evo-cellular-intent-protocol-tests) - set_tests_properties(cellular-session-protocol-v6-v9 PROPERTIES TIMEOUT 30 LABELS "network") + add_test(NAME cellular-session-protocol-v6-v10 COMMAND evo-cellular-intent-protocol-tests) + set_tests_properties(cellular-session-protocol-v6-v10 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/VALIDATION.md b/docs/engineering/VALIDATION.md index 04ac2f4..1c6edbb 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6800,3 +6800,10 @@ history, so the test now verifies the resulting v3 versions and history profile. The remaining CI jobs had not completed when this correction was prepared; local Windows builds have repeatedly stalled during Ninja without producing output. The correction needs a fresh CI run. + +The M11.4c mutation-choice v10 wire-codec slice adds message type 25 with a +fixed 64-byte canonical payload and strict decoder checks; v1-v9 remain frozen. +It does not enable v10 in the server or client runtime. The focused codec test +and schema are included, but local C++ builds stall during Ninja and +`clang-format` is not installed in this Windows environment. Linux CI is the +required compile, format, and test gate for this slice. diff --git a/include/evo/network/session_protocol.hpp b/include/evo/network/session_protocol.hpp index abb6b0a..5994272 100644 --- a/include/evo/network/session_protocol.hpp +++ b/include/evo/network/session_protocol.hpp @@ -15,7 +15,7 @@ // simulated watermark travel as QUIC DATAGRAMs. // Each starts with an 8-byte header: magic "EVSN", version u16, type u8, flags u8 (0); // every payload has a fixed size and explicit little-endian fields. Grants are opaque -// 160-byte credentials here. Later M10 segments add message types under a new version. +// 160-byte credentials here. Later M10/M11 segments add message types under new versions. namespace evo::network { inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN". // v2 (M10.5, ADR-0093): v1 plus interest, snapshot chunks and snapshot acks. @@ -32,6 +32,9 @@ inline constexpr std::uint16_t session_protocol_v7 = 7; inline constexpr std::uint16_t session_protocol_v8 = 8; // v9 adds owner-only current reserve and last committed tick effects to the v8 view. inline constexpr std::uint16_t session_protocol_v9 = 9; +// v10 adds a reliable owner choice for a previously earned cellular mutation offer. +// Its durable effect is committed on the next cellular tick. +inline constexpr std::uint16_t session_protocol_v10 = 10; inline constexpr std::size_t max_cellular_perceived_patches = 256; 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. @@ -62,7 +65,8 @@ enum class SessionMessageType : std::uint8_t { primitive_life_query, cellular_intention = 22, cellular_action = 23, - cellular_perception = 24 + cellular_perception = 24, + cellular_mutation_action = 25 }; // Admission answers for intentions and actions (wire 0..10). enum class AdmitStatus : std::uint8_t { @@ -178,6 +182,14 @@ struct CellularAction { std::uint32_t intake_x_um{}, intake_y_um{}; friend bool operator==(const CellularAction&, const CellularAction&) = default; }; +// v10 reliable choice. The server binds these values to the authenticated account and +// action id, revalidates the exact outstanding offer, and reserves successor identity. +struct CellularMutationAction { + std::uint64_t session{}, epoch{}, action_id{}, tick{}; + std::uint64_t life_identity{}, event_index{}, offer_tick{}; + std::uint16_t operator_id{}; + friend bool operator==(const CellularMutationAction&, const CellularMutationAction&) = default; +}; // v8 server-to-owner view. Addresses and current inventory are already filtered by // authoritative cell position/range; provenance and account identity are omitted. struct CellularPerceivedPatch { @@ -334,7 +346,7 @@ using SessionMessage = SimulatedThrough, SessionAction, ActionReceipt, ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect, PrimitiveLifeRequest, PrimitiveLifeReceipt, PrimitiveLifeOutcome, - PrimitiveLifeQuery, CellularPerception>; + PrimitiveLifeQuery, CellularPerception, CellularMutationAction>; [[nodiscard]] std::vector encode_session(const SessionMessage& message); [[nodiscard]] std::vector encode_session(const SessionMessage& message, diff --git a/schemas/network/session-v10-cellular-mutation-action.md b/schemas/network/session-v10-cellular-mutation-action.md new file mode 100644 index 0000000..19a821f --- /dev/null +++ b/schemas/network/session-v10-cellular-mutation-action.md @@ -0,0 +1,34 @@ +# Session protocol v10 cellular mutation choice + +ADR-0121 adds v10 as an additive extension. Versions 1–9 retain their exact +wire layouts and behavior. V10 retains the v9 owner diagnostics and adds a +reliable-stream mutation-choice action as message type 25. This message selects +an operator from an already earned offer; it supplies no genome, successor +identity, price, or biological state. + +## Type 25 + +The standard 8-byte `EVSN` header uses version 10, type 25 and flags 0. The +payload is exactly 64 bytes, little-endian: + +| 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 | 8 | stable life identity, nonzero | +| 40 | 8 | earned offer event index, nonzero | +| 48 | 8 | exact offer tick, nonzero and before the intended tick | +| 56 | 2 | offered operator id, nonzero | +| 58 | 6 | reserved, all zero | + +The decoder rejects all zero identities, an offer tick at or after the target +tick, reserved bytes, wrong lengths, and use under versions 1–9. When server +admission is enabled, it must bind the action to the authenticated account, +verify the exact current offer and operator, reserve the successor identity +idempotently by `(world, account, action_id)`, then schedule the choice for that +advancing tick. The reliable receipt means admission only; the final outcome is +tied to the committed tick and its recovered cellular checkpoint. This document +defines the wire codec only; runtime admission remains disabled until its +durable reservation and publication path is complete. diff --git a/src/network/protocol/session_protocol.cpp b/src/network/protocol/session_protocol.cpp index ceb6129..01d9f3c 100644 --- a/src/network/protocol/session_protocol.cpp +++ b/src/network/protocol/session_protocol.cpp @@ -13,6 +13,7 @@ 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 cellular_mutation_action_bytes = (std::size_t{7} * 8) + 2 + 6; constexpr std::size_t cellular_perception_prefix_bytes = 8 + 8 + 2; constexpr std::size_t cellular_diagnostics_bytes = 64; constexpr std::size_t cellular_perception_v9_prefix_bytes = @@ -127,17 +128,19 @@ std::vector encode_session(const SessionMessage& message) { std::holds_alternative(message) ? (std::get(message).diagnostics ? session_protocol_v9 : session_protocol_v8) - : std::holds_alternative(message) ? session_protocol_v7 - : std::holds_alternative(message) ? session_protocol_v6 - : is_life ? session_protocol_v5 - : session_protocol_version; + : std::holds_alternative(message) ? session_protocol_v7 + : std::holds_alternative(message) ? session_protocol_v10 + : 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_v7 && - version != session_protocol_v8 && version != session_protocol_v9) + version != session_protocol_v8 && version != session_protocol_v9 && + version != session_protocol_v10) return {}; if (version == session_protocol_version && (std::holds_alternative(message) || @@ -148,21 +151,25 @@ std::vector encode_session(const SessionMessage& message, std::uin if (version != session_protocol_v6 && std::holds_alternative(message)) return {}; if (version != session_protocol_v7 && version != session_protocol_v8 && - version != session_protocol_v9 && std::holds_alternative(message)) + version != session_protocol_v9 && version != session_protocol_v10 && + std::holds_alternative(message)) return {}; if (version != session_protocol_v7 && version != session_protocol_v8 && - version != session_protocol_v9 && std::holds_alternative(message) && + version != session_protocol_v9 && version != session_protocol_v10 && + std::holds_alternative(message) && std::get(message).result == ActionResult::committed) return {}; + if (version != session_protocol_v10 && std::holds_alternative(message)) + return {}; if (version != session_protocol_v8 && version != session_protocol_v9 && - std::holds_alternative(message)) + version != session_protocol_v10 && std::holds_alternative(message)) return {}; if (const auto* perception = std::get_if(&message)) { if (!perception->tick || perception->patches.size() > max_cellular_perceived_patches || (!perception->life_identity && !perception->patches.empty()) || (version == session_protocol_v8 && perception->diagnostics) || - (version == session_protocol_v9 && perception->life_identity && - !perception->diagnostics) || + ((version == session_protocol_v9 || version == session_protocol_v10) && + perception->life_identity && !perception->diagnostics) || (perception->life_identity == 0 && perception->diagnostics) || (perception->diagnostics && !valid_diagnostics(*perception->diagnostics)) || !std::ranges::is_sorted(perception->patches, @@ -240,16 +247,27 @@ std::vector encode_session(const SessionMessage& message, std::uin put(out, m.intake_y_um, 4); return out; } + std::vector operator()(const CellularMutationAction& m) const { + auto out = header(SessionMessageType::cellular_mutation_action, + cellular_mutation_action_bytes, version); + for (const auto value : {m.session, m.epoch, m.action_id, m.tick, m.life_identity, + m.event_index, m.offer_tick}) + put(out, value, 8); + put(out, m.operator_id, 2); + put(out, 0, 6); + return out; + } std::vector operator()(const CellularPerception& m) const { auto out = header(SessionMessageType::cellular_perception, - (version == session_protocol_v9 ? cellular_perception_v9_prefix_bytes - : cellular_perception_prefix_bytes) + + (version == session_protocol_v9 || version == session_protocol_v10 + ? cellular_perception_v9_prefix_bytes + : cellular_perception_prefix_bytes) + m.patches.size() * cellular_perceived_patch_bytes, version); put(out, m.tick, 8); put(out, m.life_identity, 8); put(out, m.patches.size(), 2); - if (version == session_protocol_v9) { + if (version == session_protocol_v9 || version == session_protocol_v10) { const auto& d = m.diagnostics; put(out, d ? d->reserve_energy_pj : 0, 8); for (const auto value : d ? d->reserve_matter_fg : std::array{}) @@ -404,7 +422,8 @@ 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_v7 && - wire_version != session_protocol_v8 && wire_version != session_protocol_v9) + wire_version != session_protocol_v8 && wire_version != session_protocol_v9 && + wire_version != session_protocol_v10) return std::unexpected(SessionCodecError::unsupported_version); if (version) *version = wire_version; @@ -488,7 +507,7 @@ std::expected decode_session(std::span(SessionMessageType::cellular_action): { if (wire_version != session_protocol_v7 && wire_version != session_protocol_v8 && - wire_version != session_protocol_v9) + wire_version != session_protocol_v9 && wire_version != session_protocol_v10) return std::unexpected(SessionCodecError::unsupported_version); if (!expect(cellular_action_bytes)) return std::unexpected(SessionCodecError::wrong_length); @@ -509,12 +528,35 @@ std::expected decode_session(std::span(SessionMessageType::cellular_perception): { - if (wire_version != session_protocol_v8 && wire_version != session_protocol_v9) + case static_cast(SessionMessageType::cellular_mutation_action): { + if (wire_version != session_protocol_v10) return std::unexpected(SessionCodecError::unsupported_version); - const auto prefix = wire_version == session_protocol_v9 - ? cellular_perception_v9_prefix_bytes - : cellular_perception_prefix_bytes; + if (!expect(cellular_mutation_action_bytes)) + return std::unexpected(SessionCodecError::wrong_length); + CellularMutationAction 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.life_identity = get(payload, 32, 8); + m.event_index = get(payload, 40, 8); + m.offer_tick = get(payload, 48, 8); + m.operator_id = static_cast(get(payload, 56, 2)); + if (!m.session || !m.epoch || !m.action_id || !m.tick || !m.life_identity || + !m.event_index || !m.offer_tick || m.offer_tick >= m.tick || !m.operator_id || + std::ranges::any_of(payload.subspan(58, 6), + [](std::uint8_t value) { return value != 0; })) + return std::unexpected(SessionCodecError::invalid_value); + return m; + } + case static_cast(SessionMessageType::cellular_perception): { + if (wire_version != session_protocol_v8 && wire_version != session_protocol_v9 && + wire_version != session_protocol_v10) + return std::unexpected(SessionCodecError::unsupported_version); + const auto prefix = + wire_version == session_protocol_v9 || wire_version == session_protocol_v10 + ? cellular_perception_v9_prefix_bytes + : cellular_perception_prefix_bytes; if (payload.size() < prefix) return std::unexpected(SessionCodecError::wrong_length); const auto count = static_cast(get(payload, 16, 2)); @@ -526,7 +568,7 @@ std::expected decode_session(std::span decode_session(std::span decode_session(std::span static_cast(ActionResult::committed) || (payload[8] == static_cast(ActionResult::committed) && wire_version != session_protocol_v7 && wire_version != session_protocol_v8 && - wire_version != session_protocol_v9)) + wire_version != session_protocol_v9 && wire_version != session_protocol_v10)) return std::unexpected(SessionCodecError::invalid_value); const ActionOutcome m{get(payload, 0, 8), static_cast(payload[8]), get(payload, 9, 8), get(payload, 17, 8)}; diff --git a/tests/cellular_intent_protocol_tests.cpp b/tests/cellular_intent_protocol_tests.cpp index af57acb..e2dab67 100644 --- a/tests/cellular_intent_protocol_tests.cpp +++ b/tests/cellular_intent_protocol_tests.cpp @@ -182,6 +182,40 @@ void v9_perception_carries_only_valid_owner_diagnostics() { CHECK(!clear_bytes.empty()); CHECK(std::get(*decode_session(clear_bytes)) == cleared); } + +void v10_mutation_choice_is_a_strict_reliable_action() { + const CellularMutationAction action{17, 23, 29, 53, 37, 41, 43, 47}; + const auto bytes = encode_session(SessionMessage{action}); + CHECK(!bytes.empty() && bytes.size() == session_header_bytes + 64); + std::uint16_t version{}; + const auto decoded = decode_session(bytes, &version); + CHECK(decoded && version == session_protocol_v10); + CHECK(std::get(*decoded) == action); + CHECK(encode_session(*decoded) == bytes); + CHECK(encode_session(SessionMessage{action}, session_protocol_v9).empty()); + + auto malformed = bytes; + std::fill(malformed.begin() + static_cast(session_header_bytes + 16), + malformed.begin() + static_cast(session_header_bytes + 24), + std::uint8_t{0}); + CHECK(!decode_session(malformed)); // The action id is the retry identity. + malformed = bytes; + malformed[session_header_bytes + 58] = 1; + CHECK(!decode_session(malformed)); // Reserved bytes stay canonical. + malformed = bytes; + std::fill(malformed.begin() + static_cast(session_header_bytes + 48), + malformed.begin() + static_cast(session_header_bytes + 56), + std::uint8_t{0xFF}); + CHECK(!decode_session(malformed)); // Offer must precede the scheduled tick. + malformed = bytes; + malformed[4] = static_cast(session_protocol_v9); + CHECK(!decode_session(malformed)); // v1-v9 do not know this message. + + const ActionOutcome outcome{29, ActionResult::committed, 31, 41}; + const auto outcome_bytes = encode_session(SessionMessage{outcome}, session_protocol_v10); + CHECK(!outcome_bytes.empty()); + CHECK(std::get(*decode_session(outcome_bytes)) == outcome); +} } // namespace int main() { @@ -191,7 +225,9 @@ int main() { v7_reliable_action_is_stable_and_strict(); v8_perception_is_bounded_and_canonical(); v9_perception_carries_only_valid_owner_diagnostics(); - std::puts("PASS cellular protocol: v6 intention, v7 action, v8/v9 perception framing"); + v10_mutation_choice_is_a_strict_reliable_action(); + std::puts( + "PASS cellular protocol: v6 intention, v7 action, v8-v10 perception/action framing"); } catch (const std::exception& error) { std::fprintf(stderr, "%s\n", error.what()); return 1;