#pragma once #include "evo/client/environment_view.hpp" #include "evo/client/input.hpp" #include "evo/client/organism_view.hpp" #include #include #include #include #include #include #include #include // M9.6 dev session protocol v1 (schemas/view/dev-session-v1.md, ADR-0082). // Explicit little-endian fields only: no native struct is ever copied to or from // the wire. Transport-neutral; the M9 channel carries frames inside TLS 1.3. namespace evo::network { inline constexpr std::uint32_t frame_magic = 0x53445645; // Bytes "EVDS". inline constexpr std::uint16_t protocol_version = 1; inline constexpr std::size_t frame_header_bytes = 12; inline constexpr std::size_t max_frame_payload = std::size_t{256} * 1024; inline constexpr std::size_t max_grant_bytes = 512; enum class MessageType : std::uint8_t { hello = 1, welcome, intent, intent_result, environment_view, organism_view, close, intent_outcome, heartbeat // Empty payload; proves liveness when no other frame flows (ADR-0083). }; enum class ProtocolError : std::uint8_t { truncated, bad_magic, unsupported_version, unknown_type, reserved_flags, oversized, malformed, invalid_value, trailing_bytes, unsupported_feature, wrong_type }; // A decoded frame borrows its payload from the input bytes. struct FrameView { MessageType type; std::span payload; }; struct OwnedFrame { MessageType type; std::vector payload; }; // Exactly one complete frame; trailing bytes reject. [[nodiscard]] std::expected decode_frame(std::span bytes); [[nodiscard]] std::vector encode_frame(MessageType type, std::span payload); // Accumulates a byte stream into frames. The header is validated as soon as it is // buffered, so an oversized or foreign frame is rejected before its payload is read. // Holds at most one frame (header + max payload). Errors latch. class FrameReader { public: // Consumes bytes up to the end of the current frame; returns how many were taken. [[nodiscard]] std::expected feed(std::span bytes); // The completed frame, if any; reading it resets the reader for the next frame. [[nodiscard]] std::optional take(); private: std::vector buffer_; std::size_t expected_{frame_header_bytes}; std::optional error_; }; // Client -> server. `required_features` must be zero in v1; the grant is opaque here. struct Hello { std::uint32_t required_features{}; std::vector grant; }; // Server -> client. Session ids identify, they do not authenticate (the channel does). struct Welcome { std::uint64_t session{}, world{}, frame{}, region{}, epoch{}; std::uint64_t server_tick{}, commit_watermark{}, grant_expires_at{}; std::uint32_t intent_window{}, window_ticks{}, max_intents_per_window{}; }; // Client -> server: one bounded movement intention (client::Intention on the wire). struct IntentMessage { std::uint64_t session{}, epoch{}, sequence{}, tick{}; std::int16_t move_x{}, move_y{}; }; enum class IntentStatus : std::uint8_t { admitted, unknown_session, stale_epoch, expired, invalid_vector, replayed, outside_window, rate_limited }; // "admitted" means accepted for scheduling at `tick`, not simulated or durable. struct IntentResult { std::uint64_t sequence{}; IntentStatus status{}; std::uint64_t server_tick{}; }; // Every view names the session/epoch it belongs to and the durable commit watermark. struct ViewHeader { std::uint64_t session{}, epoch{}, server_tick{}, commit_watermark{}, baseline{}; }; enum class CloseReason : std::uint8_t { normal, unsupported_version, malformed, unauthenticated, expired, duplicate_session, stale_epoch, rate_limited, server_shutdown, capacity, timeout }; // Final, after the host's durable commit (or loss): the M9.7 dev region has no // movable organism, so a committed intention has no biological effect. enum class IntentFinality : std::uint8_t { committed_no_effect, not_committed }; struct IntentOutcome { std::uint64_t sequence{}; IntentFinality finality{}; std::uint64_t tick{}, commit_sequence{}; // Zero when not committed. }; [[nodiscard]] std::expected, ProtocolError> encode(const Hello& m); [[nodiscard]] std::vector encode(const Welcome& m); [[nodiscard]] std::vector encode(const IntentMessage& m); [[nodiscard]] std::vector encode(const IntentResult& m); [[nodiscard]] std::vector encode(CloseReason reason); [[nodiscard]] std::vector encode(const IntentOutcome& m); [[nodiscard]] std::vector encode_heartbeat(); [[nodiscard]] std::vector encode(const ViewHeader& header, const client::EnvironmentPresentation& view); [[nodiscard]] std::vector encode(const ViewHeader& header, const client::OrganismPresentation& view); // Decoders take a complete frame and check its type. Views are rebuilt through the // validated presentation constructors, never trusted as decoded. [[nodiscard]] std::expected decode_hello(FrameView frame); [[nodiscard]] std::expected decode_welcome(FrameView frame); [[nodiscard]] std::expected decode_intent(FrameView frame); [[nodiscard]] std::expected decode_intent_result(FrameView frame); [[nodiscard]] std::expected decode_close(FrameView frame); [[nodiscard]] std::expected decode_intent_outcome(FrameView frame); [[nodiscard]] std::expected decode_heartbeat(FrameView frame); [[nodiscard]] std::expected, ProtocolError> decode_environment_view(FrameView frame); [[nodiscard]] std::expected, ProtocolError> decode_organism_view(FrameView frame); [[nodiscard]] IntentMessage make_intent(std::uint64_t session, std::uint64_t epoch, const client::Intention& intention) noexcept; } // namespace evo::network