#pragma once #include #include #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/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. // v3 (M10.6, ADR-0094): v2 plus probe marker records inside snapshot chunks. // v4 (M10.8c, ADR-0096): v3 plus HandoffOffer and SessionRedirect (stream), close reasons // handed_off and moved, and ghost marker records. v1-v3 were deployed to evolution-dev and // 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; // v7 adds stable-id reliable cellular actions; v1-v6 wire layouts stay frozen. inline constexpr std::uint16_t session_protocol_v7 = 7; // v8 adds the authenticated owner's exact, bounded cellular perception view. 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. 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. interest, // Client -> server, stream: spatial focus (v2). snapshot_chunk, // Server -> client, datagram: part of one snapshot (v2). snapshot_ack, // Client -> server, datagram: newest complete snapshot (v2). handoff_offer, // Server -> client, stream: continue at another region (v4). redirect, // Server -> client, stream: the account's probe is elsewhere (v4). primitive_life_request = 18, primitive_life_receipt, primitive_life_outcome, primitive_life_query, cellular_intention = 22, cellular_action = 23, cellular_perception = 24, cellular_mutation_action = 25, cellular_mutation_offer = 26, // Server -> owner, stream (v10). cellular_life_ended = 27 // Server -> owner, stream (v10). }; // 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). cellular = 2 // v7 biological input, committed with profile-4 state (ADR-0111/0112). }; 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. 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 { 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, handed_off, // v4: the probe crossed to another region; a HandoffOffer preceded this. moved, // v4: the account's probe is owned by another region (a Redirect may precede). 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; }; // 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; }; // Canonical biological input saved with a durable cellular action. Transport session, // epoch and action id are deliberately absent so the same retry survives reconnects. // Byte 12 is the target kind (ADR-0124): 0 none, 1 patch intake, 2 engulf with zero // coordinates. Kind 2 is carried only by v10 sessions. struct CellularActionInput { std::uint64_t tick{}; std::int16_t move_x{}, move_y{}; bool has_intake_target{}; std::uint32_t intake_x_um{}, intake_y_um{}; bool engulf{}; bool bud{}; // Kind 3 (ADR-0125): fund one wildlife bud, zero coordinates, v10 only. friend bool operator==(const CellularActionInput&, const CellularActionInput&) = default; }; inline constexpr std::size_t cellular_action_input_bytes = 24; // 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{}; // v10 (ADR-0124): engulf a smaller contacted cell; exclusive with an intake target. bool engulf{}; // v10 (ADR-0125): fund one wildlife bud; exclusive with intake and engulfment. bool bud{}; 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; }; // v10 server-to-owner offer (ADR-0121, 11.4d): the life's outstanding earned offer, its // candidates in stable operator order (never ranked). Each candidate states the successor's // actual tradeoffs: its capability value and its maintenance and total mass. No candidates // (and zero event/offer) clears a consumed or absent offer. struct CellularOfferedCandidate { std::uint16_t operator_id{}; std::uint8_t capability{}, effect{}; // biology::Capability, biology::MutationEffect. std::uint32_t parameter{}; // The successor's value; zero when shed. std::uint64_t maintenance{}, total_mass{}; // What choosing it costs this cell from its reserve (ADR-0129): construction energy and // the matter each channel must add. Compare with the reserve in the diagnostics. std::uint64_t cost_energy_pj{}; std::array cost_matter_fg{}; friend bool operator==(const CellularOfferedCandidate&, const CellularOfferedCandidate&) = default; }; inline constexpr std::size_t max_cellular_offered_candidates = 8; struct CellularMutationOffer { std::uint64_t tick{}, life_identity{}, event_index{}, offer_tick{}; std::vector candidates; friend bool operator==(const CellularMutationOffer&, const CellularMutationOffer&) = default; }; // v10 (ADR-0129): the owner's life ended in ick. Cause 1 starved, 2 engulfed, 0 not // recorded (rules below 3). Death is final; a new life is a new request. enum class CellularDeathReason : std::uint8_t { unrecorded, starved, engulfed }; struct CellularLifeEnded { std::uint64_t tick{}, life_identity{}; CellularDeathReason cause{}; friend bool operator==(const CellularLifeEnded&, const CellularLifeEnded&) = 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 { std::uint32_t x_um{}, y_um{}; std::uint64_t energy_pj{}; std::array matter_fg{}; friend bool operator==(const CellularPerceivedPatch&, const CellularPerceivedPatch&) = default; }; enum class CellularMovementResult : std::uint8_t { not_reported, no_movement, moved, blocked, insufficient_energy }; enum class CellularIntakeResult : std::uint8_t { not_reported, not_requested, acquired, missing_patch, out_of_contact }; // v10 tick effects (ADR-0129): what an engulf or bud intention did. v9 never reports them. enum class CellularEngulfResult : std::uint8_t { not_reported, not_requested, engulfed, no_eligible_prey, // No longer sent: one of the three reasons below is. unsupported, no_contact, // No other cell touched it. prey_too_large, // Touching cells were too large even with the thinnest membrane. membrane_too_thick // A touching cell was small enough, but its membrane defended it. }; enum class CellularBudOutcome : std::uint8_t { not_reported, not_requested, budded, not_able, // No reproduction capability, not fully grown, damaged, or suspended. insufficient_funding, no_placement }; struct CellularLifeDiagnostics { std::uint64_t reserve_energy_pj{}; std::array reserve_matter_fg{}; std::uint64_t maintenance_cost_pj{}, movement_cost_pj{}; CellularMovementResult movement{CellularMovementResult::not_reported}; CellularIntakeResult intake{CellularIntakeResult::not_reported}; bool has_tick_effects{}; CellularEngulfResult engulf{CellularEngulfResult::not_reported}; // v10 only. CellularBudOutcome bud{CellularBudOutcome::not_reported}; // v10 only. // v10 only (ADR-0129 amendment): what one bud takes from the reserve once the cell is // fully grown: construction and provision energy plus matter per channel. All zero // when this cell's genome cannot bud. Independent of tick effects. std::uint64_t bud_cost_energy_pj{}; std::array bud_cost_matter_fg{}; friend bool operator==(const CellularLifeDiagnostics&, const CellularLifeDiagnostics&) = default; }; struct CellularPerception { std::uint64_t tick{}, life_identity{}; // zero life plus no patches clears the view. std::vector patches; // strictly ordered by (x_um, y_um). // Present only on v9 for an active life. The values are authoritative observations, // not client claims or additional simulation state. std::optional diagnostics; friend bool operator==(const CellularPerception&, const CellularPerception&) = 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 a committed result is returned. friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default; }; struct ActionQuery { std::uint64_t action_id{}; friend bool operator==(const ActionQuery&, const ActionQuery&) = default; }; enum class PrimitiveLifeResult : std::uint8_t { born = 1, insufficient_funding = 2, no_placement = 3, existing_life = 4, cancelled = 5, pending = 6, unknown = 7 }; struct PrimitiveLifeRequest { std::uint64_t session{}, epoch{}, request_id{}; friend bool operator==(const PrimitiveLifeRequest&, const PrimitiveLifeRequest&) = default; }; struct PrimitiveLifeReceipt { std::uint64_t request_id{}; AdmitStatus status{}; std::uint64_t server_tick{}; friend bool operator==(const PrimitiveLifeReceipt&, const PrimitiveLifeReceipt&) = default; }; struct PrimitiveLifeOutcome { std::uint64_t request_id{}; PrimitiveLifeResult result{}; std::uint64_t life_identity{}, commit_sequence{}; friend bool operator==(const PrimitiveLifeOutcome&, const PrimitiveLifeOutcome&) = default; }; struct PrimitiveLifeQuery { std::uint64_t request_id{}; friend bool operator==(const PrimitiveLifeQuery&, const PrimitiveLifeQuery&) = default; }; // The client's spatial focus: one Z slice, a centre and a radius in cells. The server // clamps the radius to its maximum and filters authoritatively (ADR-0093). struct SessionInterest { std::int64_t x{}, y{}, z{}; std::uint16_t radius{}; friend bool operator==(const SessionInterest&, const SessionInterest&) = default; }; // One self-contained part of snapshot `tick`, a delta against snapshot `baseline` (0: a // fresh baseline). `records` are whole entity records (replication.hpp); the snapshot is // complete when all `count` chunks arrived. struct SnapshotChunk { std::uint64_t epoch{}, tick{}, baseline{}, field_revision{}, organism_revision{}; std::uint32_t mask{}; std::int64_t slice_z{}; std::uint8_t index{}, count{}; std::vector records; friend bool operator==(const SnapshotChunk&, const SnapshotChunk&) = default; }; inline constexpr std::size_t snapshot_chunk_header_bytes = (5 * 8) + 4 + 8 + 2; inline constexpr std::size_t max_snapshot_records_bytes = session_datagram_bytes - session_header_bytes - snapshot_chunk_header_bytes; // The newest snapshot the client assembled completely and applied. struct SnapshotAck { std::uint64_t epoch{}, tick{}; friend bool operator==(const SnapshotAck&, const SnapshotAck&) = default; }; // A region's public address as a client dials it: "host:port" and the certificate name, // printable ASCII (no spaces), 1-64 characters each. struct RegionAddress { std::uint64_t region{}; std::string endpoint, server_name; friend bool operator==(const RegionAddress&, const RegionAddress&) = default; }; // v4 (ADR-0096): the session's probe crossed into `destination`; log in there with `ticket` // (a handoff ticket, used in Hello's grant slot). The source then closes with handed_off. struct HandoffOffer { std::array transfer{}; RegionAddress destination; WireGrant ticket{}; friend bool operator==(const HandoffOffer&, const HandoffOffer&) = default; }; // v4: at login, the account's probe is owned by `owner`; log in there with a grant for it. struct SessionRedirect { RegionAddress owner; friend bool operator==(const SessionRedirect&, const SessionRedirect&) = default; }; using SessionMessage = std::variant; [[nodiscard]] std::vector encode_session(const SessionMessage& message); [[nodiscard]] std::vector encode_session(const SessionMessage& message, std::uint16_t version); // Exactly one message; any other length for its type rejects. [[nodiscard]] std::expected decode_session(std::span bytes); [[nodiscard]] std::expected decode_session(std::span bytes, std::uint16_t* version); [[nodiscard]] std::array encode_cellular_action_input(const CellularActionInput& input); [[nodiscard]] std::expected decode_cellular_action_input(std::span bytes); } // namespace evo::network