#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}; }; // 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{}; friend bool operator==(const CarriedAction&, const CarriedAction&) = default; }; struct AccountOutcome { AccountId account; ActionOutcome outcome; }; 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. enum class ActionLedgerError : std::uint8_t { unavailable }; 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; 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]] ActionReceipt action(std::uint64_t session, const SessionAction& m, 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 whenever its sequence advances. [[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. [[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{}; }; 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{}; }; enum class Stage : std::uint8_t { scheduled, carried }; struct Action { CarriedAction carried; Stage stage{}; bool unknown{}; // Carried in a batch whose outcome was unknown when authority was lost. }; 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; }; [[nodiscard]] Found lookup(const AccountId& account, std::uint64_t action_id) const; 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); IntentLimits limits_; std::vector sessions_; std::vector actions_; std::deque finals_; ActionLedger* ledger_{}; }; } // namespace evo::network