diff --git a/cmake/Network.cmake b/cmake/Network.cmake index 791b19a..6d9a6b8 100644 --- a/cmake/Network.cmake +++ b/cmake/Network.cmake @@ -65,6 +65,11 @@ add_executable(evo-dev-session apps/evo-dev-session/main.cpp) target_link_libraries(evo-dev-session PRIVATE evo_network_session) evo_owned_target(evo-dev-session) 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_executable(evo-network-tests tests/network_protocol.cpp tests/network_tls.cpp tests/network_session.cpp tests/network_control.cpp tests/network_replication.cpp tests/network_motion.cpp tests/network_interpolation.cpp tests/network_main.cpp) diff --git a/docs/adr/0105-cellular-session-intention-v6.md b/docs/adr/0105-cellular-session-intention-v6.md new file mode 100644 index 0000000..52848a5 --- /dev/null +++ b/docs/adr/0105-cellular-session-intention-v6.md @@ -0,0 +1,45 @@ +# ADR-0105: Cellular session intention protocol v6 + +## Status + +Accepted wire-contract direction for M11.3 (2026-10-10). The codec is being +implemented first; server admission and durable resolution remain separate gates. + +## Context + +The deployed session wire versions 1–4 are frozen, and v5 adds only reliable +primitive-life creation/query messages. In primitive v5 mode the current server +rejects movement datagrams, probe actions and M10 interest. M11.3 needs a client +to request bounded movement and choose one nearby food patch without claiming +position, speed, energy or inventory. + +## Decision + +- Add session protocol v6 while preserving the exact v1–v5 encodings. V6 retains + the existing session, control epoch, movement vector, sequence and scheduled + tick fields, and adds an optional target patch address in micrometres. +- The v6 `CellularIntention` is a fixed 48-byte little-endian datagram payload. + The strict layout and canonical absent-target form are in + [session-v6-cellular-intention](../../schemas/network/session-v6-cellular-intention.md). +- The target is an intention only. The server checks authenticated session and + epoch, tick and sequence window, movement norm, patch alignment and visibility; + it resolves position and contact, then derives any costs or acquired stock. +- A cellular client must negotiate v6 explicitly. The current session server + remains unchanged until it has a cellular handler; the codec alone does not + authorize gameplay. + +## Alternatives considered + +- **Reuse the M10 marker intention:** rejected because its simulation path moves + a non-biological probe at a fixed speed and has no energy, habitat or life. +- **Send a position or inventory delta:** rejected because it would let the + client claim authoritative state. +- **Change v5 in place:** rejected because v5 life creation is an existing + versioned contract and must retain its exact bytes and primitive-only scope. + +## Consequences + +V6 provides a bounded, explicit wire value for the next server integration. It +does not implement admission, durable tick publication, a life view, client UI +or cross-region owner routing; M11.3 remains incomplete until those pieces work +end to end. diff --git a/docs/adr/README.md b/docs/adr/README.md index e7885d3..8561e1c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -5,6 +5,7 @@ - [ADR-0102: Bounded cellular space and locomotion trial](0102-cellular-spatial-trial.md) - accepted M11.3 trial direction for finite 2D region bounds, phenotype-limited movement and organism contact; tunable arena dimensions are not world geometry. - [ADR-0103: Cellular resource perception trial](0103-cellular-perception-trial.md) - accepted M11.3 exploratory direction for a 5 mm footprint-based sensor range and exact nearby patch stock; provenance and out-of-range stock remain hidden. - [ADR-0104: Cellular single-life tick order trial](0104-cellular-single-life-tick-order.md) - accepted M11.3 order for maintenance, funded movement and one contact-gated intake proposal; shared-stock contention and durable publication remain open. +- [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 server admission is still to be implemented. - [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 3fe84cb..4e009f4 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -106,8 +106,8 @@ scoped change before starting the next segment. - 11.3a contract direction: ADR-0101 selects finite 1 mm cellular food patches; ADR-0102 defines bounded non-wrapping movement and footprint contact. The - complete living-set checkpoint, perception contract and server profile remain - open. + complete living-set checkpoint and server profile remain open; ADR-0103 now + defines the perception trial contract. - 11.3b-1: pure phenotype-derived movement proposal and square-footprint contact helper are implemented and locally tested. Session inputs, server state, replication and durable movement publication remain open. @@ -127,6 +127,9 @@ scoped change before starting the next segment. affordable movement and one targeted contact intake into a detached candidate. Shared-stock contention, starvation/death closure, owner commit and checkpoint recovery remain open; this helper is not yet a multi-life tick. +- 11.3b-3: ADR-0105 and the v6 codec define cellular intention bytes for movement + and an optional food-patch target. Server admission, durable simulation and + client presentation are still open. ## Exit boundary diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 9da037c..cf9be02 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5931,3 +5931,21 @@ Executed locally: warning-as-error MSVC Debug and Release `NDEBUG` compile/run, focused cellular CTest, clang-format 19.1.5, clang-tidy 19.1.5 with MSVC `/std:c++latest`, and `git diff --check`. CI and integration with durable intent/outcome publication remain pending. + +## 2026-10-10 — M11.3b-3 cellular intention v6 codec (CI pending) + +ADR-0105 and `schemas/network/session-v6-cellular-intention.md` define a strict +fixed-size datagram carrying only session/epoch, sequence/tick, movement intent +and an optional intake patch address. V1-v5 encodings remain unchanged. Decode +rejects noncanonical absent targets and reserved bytes. The codec intentionally +does not admit this message in `RegionSessions`; that server path is not yet +implemented. + +Executed locally: warning-as-error MSVC 19.44 Release compile/run, CTest +`cellular-intention-protocol-v6` (1/1 passed), compile-only MSVC check for the +existing `network_control.cpp` regression case, clang-format 19.1.5 on changed +ranges, clang-tidy 19.1.5 with MSVC `/std:c++latest`, and `git diff --check`. +The CMake/Ninja build of `evo-network-tests` remained idle for about 90 seconds +(cmake 0.02 CPU seconds, ninja 0.09, no `cl`/`link` child), so I interrupted it; +the full M10 network suite and server admission/QUIC integration remain pending. +Linux network CI has not yet qualified this version. diff --git a/include/evo/network/session_protocol.hpp b/include/evo/network/session_protocol.hpp index 53e6792..84252b6 100644 --- a/include/evo/network/session_protocol.hpp +++ b/include/evo/network/session_protocol.hpp @@ -24,6 +24,7 @@ inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN". // are frozen; v4 remains the default. v5 adds reliable primitive-life operations. 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; 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; @@ -50,7 +51,8 @@ enum class SessionMessageType : std::uint8_t { primitive_life_request = 18, primitive_life_receipt, primitive_life_outcome, - primitive_life_query + primitive_life_query, + cellular_intention = 22 }; // Admission answers for intentions and actions (wire 0..10). enum class AdmitStatus : std::uint8_t { @@ -136,6 +138,15 @@ struct SessionIntention { std::int16_t move_x{}, move_y{}; friend bool operator==(const SessionIntention&, const SessionIntention&) = default; }; +// v6 biological input only: movement intent plus an optional address of a patch +// the client wants to feed from. The server checks range, contact and costs. +struct CellularIntention { + std::uint64_t session{}, epoch{}, sequence{}, 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 CellularIntention&, const CellularIntention&) = default; +}; struct IntentionReceipt { std::uint64_t sequence{}; AdmitStatus status{}; @@ -248,10 +259,10 @@ struct SessionRedirect { }; using SessionMessage = std::variant; + SessionIntention, CellularIntention, IntentionReceipt, SimulatedThrough, + SessionAction, ActionReceipt, ActionOutcome, ActionQuery, SessionInterest, + SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect, PrimitiveLifeRequest, + PrimitiveLifeReceipt, PrimitiveLifeOutcome, PrimitiveLifeQuery>; [[nodiscard]] std::vector encode_session(const SessionMessage& message); [[nodiscard]] std::vector encode_session(const SessionMessage& message, diff --git a/schemas/network/session-v6-cellular-intention.md b/schemas/network/session-v6-cellular-intention.md new file mode 100644 index 0000000..7926ca5 --- /dev/null +++ b/schemas/network/session-v6-cellular-intention.md @@ -0,0 +1,30 @@ +# Session protocol v6 cellular intention datagram + +ADR-0105 defines this message. It is not admitted by the currently integrated +region session server until its v6 cellular-life handler is enabled. + +Each frame starts with the existing 8-byte `EVSN` header. The version is 6, the +type is 22 (`cellular_intention`), and header flags are zero. Payload length is +exactly 48 bytes; all integers are little-endian. + +| Payload offset | Size | Field | +|---:|---:|---| +| 0 | 8 | authenticated session id (nonzero; admission checks connection match) | +| 8 | 8 | control epoch (nonzero; admission checks current authority) | +| 16 | 8 | per-session intention sequence (nonzero and increasing) | +| 24 | 8 | intended simulation tick (admission checks the future window) | +| 32 | 2 | signed movement X component; server validates the norm and bounds | +| 34 | 2 | signed movement Y component; server validates the norm and bounds | +| 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. When set, the +coordinates identify a requested patch, not a position, speed or stock claim. +The authoritative host validates patch alignment, perception at the applicable +tick and footprint contact before intake. No target means no requested intake. +Movement remains an intention only; the server derives position, costs and +resource balances. Truncated frames, trailing bytes, nonzero reserved bytes, +invalid flags, noncanonical absent-target coordinates and versions below 6 are +refused by the codec. diff --git a/src/network/protocol/session_protocol.cpp b/src/network/protocol/session_protocol.cpp index 90fc2b1..138fd55 100644 --- a/src/network/protocol/session_protocol.cpp +++ b/src/network/protocol/session_protocol.cpp @@ -11,6 +11,7 @@ constexpr std::size_t refresh_bytes = session_grant_wire_bytes; 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 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; @@ -102,11 +103,15 @@ std::vector encode_session(const SessionMessage& message) { std::holds_alternative(message) || std::holds_alternative(message) || std::holds_alternative(message); - return encode_session(message, is_life ? session_protocol_v5 : session_protocol_version); + const auto version = 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) + if (version != session_protocol_version && version != session_protocol_v5 && + version != session_protocol_v6) return {}; if (version == session_protocol_version && (std::holds_alternative(message) || @@ -114,6 +119,8 @@ std::vector encode_session(const SessionMessage& message, std::uin std::holds_alternative(message) || std::holds_alternative(message))) return {}; + if (version != session_protocol_v6 && std::holds_alternative(message)) + return {}; struct Encoder { std::uint16_t version; std::vector operator()(const SessionHello& m) const { @@ -153,6 +160,19 @@ std::vector encode_session(const SessionMessage& message, std::uin put(out, static_cast(m.move_y), 2); return out; } + std::vector operator()(const CellularIntention& m) const { + auto out = + header(SessionMessageType::cellular_intention, cellular_intention_bytes, version); + for (const auto v : {m.session, m.epoch, m.sequence, 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); @@ -283,7 +303,8 @@ std::expected decode_session(std::span(get(bytes, 4, 2)); - if (wire_version != session_protocol_version && wire_version != session_protocol_v5) + if (wire_version != session_protocol_version && wire_version != session_protocol_v5 && + wire_version != session_protocol_v6) return std::unexpected(SessionCodecError::unsupported_version); if (version) *version = wire_version; @@ -344,6 +365,27 @@ std::expected decode_session(std::span(static_cast(get(payload, 34, 2))); return m; // Ranges belong to admission, which answers with a status. } + case static_cast(SessionMessageType::cellular_intention): { + if (wire_version < session_protocol_v6) + return std::unexpected(SessionCodecError::unsupported_version); + if (!expect(cellular_intention_bytes)) + return std::unexpected(SessionCodecError::wrong_length); + CellularIntention m; + m.session = get(payload, 0, 8); + m.epoch = get(payload, 8, 8); + m.sequence = 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.has_intake_target && (m.intake_x_um != 0 || m.intake_y_um != 0)) + 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); diff --git a/tests/cellular_intent_protocol_tests.cpp b/tests/cellular_intent_protocol_tests.cpp new file mode 100644 index 0000000..1bc1efe --- /dev/null +++ b/tests/cellular_intent_protocol_tests.cpp @@ -0,0 +1,79 @@ +#include "evo/network/session_protocol.hpp" + +#include +#include +#include +#include + +namespace { +using namespace evo::network; +void check(bool value, std::source_location at = std::source_location::current()) { + if (!value) + throw std::runtime_error("cellular intent protocol line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) + +void round_trip_and_version_gate() { + const CellularIntention targeted{17, 23, 29, 31, -707, 707, true, 4'000, 5'000}; + const SessionMessage message{targeted}; + const auto bytes = encode_session(message); + CHECK(!bytes.empty() && bytes.size() == session_header_bytes + 48); + std::uint16_t version{}; + const auto decoded = decode_session(bytes, &version); + CHECK(decoded && version == session_protocol_v6); + CHECK(std::get(*decoded) == targeted); + CHECK(encode_session(*decoded) == bytes); + CHECK(encode_session(message, session_protocol_v5).empty()); + + const CellularIntention no_target{1, 2, 3, 4, 0, -1, false, 0, 0}; + const auto no_target_bytes = encode_session(SessionMessage{no_target}); + CHECK(std::get(*decode_session(no_target_bytes)) == no_target); +} + +void malformed_frames_are_refused() { + const auto bytes = + encode_session(SessionMessage{CellularIntention{1, 2, 3, 4, 0, 0, true, 1'000, 2'000}}); + for (std::size_t size = 0; size < bytes.size(); ++size) { + const auto truncated = decode_session(std::span{bytes}.first(size)); + CHECK(!truncated); + CHECK(truncated.error() == (size < session_header_bytes ? SessionCodecError::truncated + : SessionCodecError::wrong_length)); + } + auto bad = bytes; + bad.at(6) = 255; // Unknown message type. + const auto wrong_type = decode_session(bad); + CHECK(!wrong_type && wrong_type.error() == SessionCodecError::unknown_type); + + bad = bytes; + bad.at(session_header_bytes + 36) = 2; + const auto bad_flag = decode_session(bad); + CHECK(!bad_flag && bad_flag.error() == SessionCodecError::invalid_value); + + bad = bytes; + bad.at(session_header_bytes + 38) = 1; + const auto bad_reserved = decode_session(bad); + CHECK(!bad_reserved && bad_reserved.error() == SessionCodecError::invalid_value); + + bad = encode_session(SessionMessage{CellularIntention{1, 2, 3, 4, 0, 0, false, 0, 0}}); + bad.at(session_header_bytes + 40) = 1; // Coordinates must be zero when target is absent. + const auto noncanonical = decode_session(bad); + CHECK(!noncanonical && noncanonical.error() == SessionCodecError::invalid_value); + + bad = bytes; + bad.at(4) = static_cast(session_protocol_v5); + const auto old_version = decode_session(bad); + CHECK(!old_version && old_version.error() == SessionCodecError::unsupported_version); + CHECK(encode_session(SessionMessage{CellularIntention{1, 2, 3, 4}}, 7).empty()); +} +} // 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"); + } catch (const std::exception& error) { + std::fprintf(stderr, "%s\n", error.what()); + return 1; + } +} diff --git a/tests/network_control.cpp b/tests/network_control.cpp index 0d81e06..f317c26 100644 --- a/tests/network_control.cpp +++ b/tests/network_control.cpp @@ -371,7 +371,7 @@ void session_codec() { mutated.at(0) ^= 1; CHECK(refused(decode_session(mutated), SessionCodecError::bad_magic)); mutated = bytes; - mutated.at(4) = 6; // A future version. + mutated.at(4) = 7; // A future version. CHECK(refused(decode_session(mutated), SessionCodecError::unsupported_version)); mutated = bytes; mutated.at(7) = 1;