#pragma once #include #include #include #include #include #include #include // M10 session protocol v1 (ADR-0091 session, ADR-0092 intentions and actions; // schemas/network/session-v1.md). Session, action and outcome messages travel on the QUIC // reliable stream (one message per framed QUIC message); intentions, their receipts and the // 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. namespace evo::network { inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN". inline constexpr std::uint16_t session_protocol_version = 1; inline constexpr std::size_t session_header_bytes = 8; inline constexpr std::size_t session_grant_wire_bytes = 160; enum class SessionMessageType : std::uint8_t { hello = 1, // Client -> server: grant. welcome, // Server -> client. refresh, // Client -> server: newer grant for the open session. refresh_result, // Server -> client. close, // Either way, then the sender closes the connection. intention, // Client -> server, datagram: realtime movement intention. intention_receipt, // Server -> client, datagram. simulated_through, // Server -> client, datagram: cumulative simulated watermark. action, // Client -> server, stream: discrete action with a stable id. action_receipt, // Server -> client, stream. action_outcome, // Server -> client, stream: final. action_query // Client -> server, stream: resolve an action by id. }; // Admission answers for intentions and actions (wire 0..10). enum class AdmitStatus : std::uint8_t { admitted = 0, unknown_session, // Not this connection's session. stale_epoch, outside_window, // Tick not in server_tick + 1 ..= server_tick + window. rate_limited, // Every attempt counts toward the window budget. replayed, // Intention sequence not above the last admitted one. invalid_vector, too_many_unresolved, invalid_action, // Unknown kind or zero action id. duplicate, // Action id already known for this account: its state follows. not_ready // The region has no current authority (starting, recovering, draining). }; // Wire u16 (SessionAction::kind carries the raw value; admission validates it). enum class ActionKind : std::uint8_t { probe = 1 // No effect on biology: proves admission, scheduling and durability (M10.4). }; 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. }; // Wire values 1..13. `connection_lost` is local only (the transport ended without a Close). enum class SessionCloseReason : std::uint8_t { client_closed = 1, superseded, // A newer grant for the same account opened another session. expired, stale_epoch, unauthenticated, wrong_scope, // Environment, world or region. stale_grant, // Replayed or older than a grant already presented. rate_limited, capacity, protocol, timeout, // No Hello before the deadline. unsupported_version, shutdown, connection_lost = 255 }; enum class SessionCodecError : std::uint8_t { truncated, bad_magic, unsupported_version, unknown_type, reserved_flags, wrong_length, invalid_value }; using WireGrant = std::array; struct SessionHello { std::uint32_t required_features{}; // Must be zero in v1. WireGrant grant{}; }; struct SessionWelcome { std::uint64_t session{}, epoch{}, world{}, frame{}, region{}, expires_at{}; std::uint64_t server_seconds{}; // Server wall clock at Welcome, for refresh timing. std::uint64_t server_tick{}; // Simulated tick at Welcome, for scheduling. friend bool operator==(const SessionWelcome&, const SessionWelcome&) = default; }; struct SessionRefresh { WireGrant grant{}; }; // accepted: 0 and the new expiry. Otherwise a refusal reason (stale_grant, // unauthenticated, wrong_scope, expired, rate_limited); the session keeps its expiry. struct SessionRefreshResult { std::uint8_t status{}; std::uint64_t expires_at{}; friend bool operator==(const SessionRefreshResult&, const SessionRefreshResult&) = default; }; struct SessionClose { SessionCloseReason reason{}; }; // A movement intention carries only what the player wants: never position, energy or any // other state claim. Vector components within the M9 bound (norm <= 1000). struct SessionIntention { std::uint64_t session{}, epoch{}, sequence{}, tick{}; std::int16_t move_x{}, move_y{}; friend bool operator==(const SessionIntention&, const SessionIntention&) = default; }; struct IntentionReceipt { std::uint64_t sequence{}; AdmitStatus status{}; std::uint64_t server_tick{}; friend bool operator==(const IntentionReceipt&, const IntentionReceipt&) = default; }; // Every admitted intention up to `sequence` whose tick is <= `tick` has been simulated in // `epoch` (cumulative, so a lost datagram is covered by the next). struct SimulatedThrough { std::uint64_t epoch{}, sequence{}, tick{}; friend bool operator==(const SimulatedThrough&, const SimulatedThrough&) = default; }; struct SessionAction { std::uint64_t session{}, epoch{}, action_id{}; std::uint16_t kind{}; // Raw wire value: an unknown kind is refused by admission. std::uint64_t tick{}; friend bool operator==(const SessionAction&, const SessionAction&) = default; }; // Receipt only: admitted means scheduled for `tick`, never simulated or durable. struct ActionReceipt { std::uint64_t action_id{}; AdmitStatus status{}; std::uint64_t server_tick{}, tick{}; friend bool operator==(const ActionReceipt&, const ActionReceipt&) = default; }; struct ActionOutcome { std::uint64_t action_id{}; ActionResult result{}; std::uint64_t tick{}, commit_sequence{}; // Zero unless committed_no_effect. friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default; }; struct ActionQuery { std::uint64_t action_id{}; friend bool operator==(const ActionQuery&, const ActionQuery&) = default; }; using SessionMessage = std::variant; [[nodiscard]] std::vector encode_session(const SessionMessage& message); // Exactly one message; any other length for its type rejects. [[nodiscard]] std::expected decode_session(std::span bytes); } // namespace evo::network