#pragma once #include "evo/network/session_control.hpp" #include "evo/network/session_protocol.hpp" #include #include #include #include #include #include #include #include // M10.4 admission of realtime intentions and discrete actions for one region (ADR-0092). // Transport-neutral and single-owner; the host serializes calls. Three distinct answers: // - receipt: admitted (scheduled for a tick) or a refusal, never more than that; // - simulated: the cumulative watermark of admitted intentions whose tick has run; // - final (actions only): committed_no_effect with its commit, or not_committed. // Intentions are per session (sequence strictly increasing, superseded by later ones). // Actions are per account, with client-chosen ids that are never admitted twice, so a // retry or a reconnect resolves to the same outcome. Neither changes biology in M10.4. namespace evo::network { struct IntentLimits { std::uint32_t intent_window{8}; // Ticks ahead of the server tick (ADR-0089). std::uint32_t window_ticks{8}; // Rate window. std::uint32_t max_intents_per_window{8}; // Every attempt counts. std::uint32_t max_actions_per_window{4}; // Every attempt counts. std::size_t max_unresolved{256}; // Intentions plus actions per session. std::size_t max_sessions{32}; std::size_t max_finals{2048}; // Recent final outcomes kept for duplicates and queries. // Ticks between watermarks to each session (1: every simulated tick). The watermark is // also every client's clock for the server tick until snapshots carry it (10.5). std::uint64_t watermark_every{1}; // M10.9d (ADR-0097): while a session's watermark advances, at most one per this many // ticks (it is cumulative: nothing is lost, "simulated" is learned up to N-1 ticks later). // 1 keeps one per advance. Datagram sends dominate the session layer under load. std::uint64_t watermark_coalesce{1}; }; // The host's authority as admission must see it. struct AdmissionFacts { bool ready{}; std::uint64_t epoch{}, server_tick{}; }; // An action the host must record durably with the batch that covers its tick. struct CarriedAction { AccountId account; std::uint64_t action_id{}, tick{}; ActionKind kind{}; std::optional> cellular_input; friend bool operator==(const CarriedAction&, const CarriedAction&) = default; }; struct AccountOutcome { AccountId account; ActionOutcome outcome; ActionKind kind{ActionKind::probe}; std::optional> cellular_input; }; struct ScheduledCellularIntention { AccountId account; CellularIntention intention; friend bool operator==(const ScheduledCellularIntention&, const ScheduledCellularIntention&) = default; }; enum class IntentConfigError : std::uint8_t { invalid }; // Durable action records (10.4b): the region host implements it over its lease (schema v11); // tests use fakes. `find` answers with the committed outcome, nothing when the action was // never committed, or `unavailable` when it cannot decide. `find_all` answers several in // order, all or nothing (M10.9d, ADR-0097: one store round trip instead of one per action); // the default asks `find` for each. enum class ActionLedgerError : std::uint8_t { unavailable }; struct ActionKey { AccountId account; std::uint64_t action_id{}; }; struct DurableActionRecord { ActionOutcome outcome; // Present only for cellular actions. This is the canonical 24-byte biological // input, independent of the session and epoch used to deliver a retry. std::optional> cellular_input; friend bool operator==(const DurableActionRecord&, const DurableActionRecord&) = default; }; class ActionLedger { public: ActionLedger() = default; ActionLedger(const ActionLedger&) = delete; ActionLedger& operator=(const ActionLedger&) = delete; virtual ~ActionLedger() = default; [[nodiscard]] virtual std::expected, ActionLedgerError> find(const AccountId& account, std::uint64_t action_id) = 0; [[nodiscard]] virtual std::expected>, ActionLedgerError> find_all(std::span keys); // Input-aware queries are used by v7 cellular actions. The compatibility // default preserves legacy ledgers; absence of cellular_input cannot prove // an exact cellular retry and must be treated as an identity conflict. [[nodiscard]] virtual std::expected, ActionLedgerError> find_record(const AccountId& account, std::uint64_t action_id); [[nodiscard]] virtual std::expected>, ActionLedgerError> find_all_records(std::span keys); protected: ActionLedger(ActionLedger&&) = default; ActionLedger& operator=(ActionLedger&&) = default; }; class IntentAdmission { public: [[nodiscard]] static std::expected create(IntentLimits limits); // Durable lookups for duplicates and unresolved actions; null keeps memory only. void attach(ActionLedger* ledger) noexcept { ledger_ = ledger; } // Session lifecycle, driven by session control (after Welcome, on any close). [[nodiscard]] bool open(std::uint64_t session, const AccountId& account); void close(std::uint64_t session); // `session` is the connection's authenticated session; a message naming another is // refused. Every attempt by a known session counts toward its rate. [[nodiscard]] IntentionReceipt intention(std::uint64_t session, const SessionIntention& m, const AdmissionFacts& facts); [[nodiscard]] IntentionReceipt intention(std::uint64_t session, const CellularIntention& m, const AdmissionFacts& facts); // Read-only pending inputs up to this tick, in deterministic tick/account/sequence order. // They remain available until simulated() advances the committed/simulated watermark. [[nodiscard]] std::vector scheduled_cellular_intentions(std::uint64_t tick) const; [[nodiscard]] ActionReceipt action(std::uint64_t session, const SessionAction& m, const AdmissionFacts& facts); // v7 path retains canonical biological bytes through scheduling and refuses a reused // account/action id whose input differs, including a final action still in memory. [[nodiscard]] ActionReceipt action(std::uint64_t session, const CellularAction& m, const AdmissionFacts& facts); // The same admission with the durable uniqueness check deferred (M10.9d): nothing when the // action awaits `verify`, which confirms every waiting action with one ledger request and // returns their receipts by session. Without a ledger, `admit` always answers at once. [[nodiscard]] std::optional admit(std::uint64_t session, const SessionAction& m, const AdmissionFacts& facts); [[nodiscard]] std::optional admit(std::uint64_t session, const CellularAction& m, const AdmissionFacts& facts); [[nodiscard]] std::vector> verify(const AdmissionFacts& facts); // An action of the session's account: final, pending or unknown. With a ledger, an action // whose batch outcome was unknown is decided from its durable record once this authority // is ready, and an action no longer in memory is looked up. [[nodiscard]] ActionOutcome query(std::uint64_t session, const ActionQuery& m, const AdmissionFacts& facts); // Watermarks to send after the host simulated through facts.server_tick: to every // session (sequence 0 before its first simulated intention) at least every // `watermark_every` ticks, and when its sequence advances (at most every // `watermark_coalesce` ticks). [[nodiscard]] std::vector> simulated(const AdmissionFacts& facts); // Scheduled actions whose tick is <= `tick`: they ride that tick's batch from now on. [[nodiscard]] std::vector carry(std::uint64_t tick); // These carried actions are durable in `commit_sequence`; `tick` is the tick each rode. // With a ledger, each outcome is taken from the action's durable record (one request). [[nodiscard]] std::vector committed(std::span actions, std::uint64_t commit_sequence); // The host dropped these carried actions. Final: never committed. Otherwise their batch's // outcome was unknown: they stay pending until their durable record decides them. [[nodiscard]] std::vector dropped(std::span actions, bool final); // Authority lost or epoch advanced: actions never carried are final (not_committed); // carried ones stay pending until committed, dropped or decided by their record. [[nodiscard]] std::vector abandon(); // The current session of an account, for delivering outcomes. [[nodiscard]] std::optional session_of(const AccountId& account) const; [[nodiscard]] std::size_t unresolved(std::uint64_t session) const; private: struct Pending { std::uint64_t sequence{}, tick{}, epoch{}; std::int16_t move_x{}, move_y{}; bool has_intake_target{}; std::uint32_t intake_x_um{}, intake_y_um{}; }; struct Session { std::uint64_t id{}; AccountId account; std::uint64_t last_sequence{}, window_start{}; std::uint32_t intent_attempts{}, action_attempts{}; std::deque pending; std::uint64_t watermark{}, sent_watermark{}, sent_at_tick{}; }; // verifying: admitted in memory, awaiting the durable uniqueness check (`verify`). enum class Stage : std::uint8_t { verifying, scheduled, carried }; struct Action { CarriedAction carried; Stage stage{}; bool unknown{}; // Carried in a batch whose outcome was unknown when authority was lost. // While verifying: the admitting session, and the epoch and tick of its admission. std::uint64_t session{}, epoch{}, admitted_at{}; }; explicit IntentAdmission(IntentLimits limits) : limits_{limits} {} // A ledger answer flattened: unavailable (or no ledger), absent, or committed. enum class Record : std::uint8_t { unavailable, absent, committed }; struct Found { Record state{Record::unavailable}; ActionOutcome outcome; std::optional> cellular_input; }; [[nodiscard]] Found lookup(const AccountId& account, std::uint64_t action_id) const; // The in-memory checks of an action; `check` is set when only the ledger can still // refuse it. [[nodiscard]] ActionReceipt screen(Session& s, const SessionAction& m, const AdmissionFacts& facts, bool& check, std::optional> cellular_input = std::nullopt); // Applies a durable answer to a receipt that passed `screen`. void decide(const AccountId& account, ActionReceipt& r, const Found& found, std::optional> cellular_input = std::nullopt); Session* find(std::uint64_t session); const Session* find(std::uint64_t session) const; void count_window(Session& s, std::uint64_t server_tick) const; [[nodiscard]] std::size_t unresolved_of(const Session& s) const; void remember(const AccountId& account, const ActionOutcome& outcome, ActionKind kind = ActionKind::probe, std::optional> cellular_input = std::nullopt); IntentLimits limits_; std::vector sessions_; std::vector actions_; std::deque finals_; ActionLedger* ledger_{}; }; } // namespace evo::network