Session protocol v10 adds type 26: the life's earned offer with its unranked candidates in operator order and each successor's capability value, maintenance and total mass. The cellular bridge sends it when the offer or the owner's session changes and clears a consumed offer; the client keeps the latest one for the maintainer's choice UI (ADR-0121, 11.4d server half). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
389 lines
18 KiB
C++
389 lines
18 KiB
C++
#pragma once
|
|
#include <array>
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <expected>
|
|
#include <optional>
|
|
#include <span>
|
|
#include <string>
|
|
#include <variant>
|
|
#include <vector>
|
|
|
|
// 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).
|
|
};
|
|
// 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<std::uint8_t, session_grant_wire_bytes>;
|
|
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{};
|
|
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{};
|
|
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{};
|
|
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<CellularOfferedCandidate> candidates;
|
|
friend bool operator==(const CellularMutationOffer&, const CellularMutationOffer&) = 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<std::uint64_t, 4> 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
|
|
};
|
|
struct CellularLifeDiagnostics {
|
|
std::uint64_t reserve_energy_pj{};
|
|
std::array<std::uint64_t, 4> 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{};
|
|
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<CellularPerceivedPatch> 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<CellularLifeDiagnostics> 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<std::uint8_t> 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<std::uint8_t, 16> 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<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
|
|
SessionIntention, CellularIntention, CellularAction, IntentionReceipt,
|
|
SimulatedThrough, SessionAction, ActionReceipt, ActionOutcome, ActionQuery,
|
|
SessionInterest, SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect,
|
|
PrimitiveLifeRequest, PrimitiveLifeReceipt, PrimitiveLifeOutcome,
|
|
PrimitiveLifeQuery, CellularPerception, CellularMutationAction,
|
|
CellularMutationOffer>;
|
|
|
|
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message,
|
|
std::uint16_t version);
|
|
// Exactly one message; any other length for its type rejects.
|
|
[[nodiscard]] std::expected<SessionMessage, SessionCodecError>
|
|
decode_session(std::span<const std::uint8_t> bytes);
|
|
[[nodiscard]] std::expected<SessionMessage, SessionCodecError>
|
|
decode_session(std::span<const std::uint8_t> bytes, std::uint16_t* version);
|
|
[[nodiscard]] std::array<std::uint8_t, cellular_action_input_bytes>
|
|
encode_cellular_action_input(const CellularActionInput& input);
|
|
[[nodiscard]] std::expected<CellularActionInput, SessionCodecError>
|
|
decode_cellular_action_input(std::span<const std::uint8_t> bytes);
|
|
} // namespace evo::network
|