Files
aevolution/include/evo/network/intent_admission.hpp
T
dingoandClaude Opus 5.5 69f3ad7cf8
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m47s
Foundation / checks (network) (push) Successful in 9m30s
Foundation / checks (client) (push) Successful in 12m19s
Foundation / checks (tsan) (push) Successful in 7m43s
Foundation / checks (checks) (push) Successful in 31m29s
Foundation / checks (postgres) (push) Successful in 36m39s
Foundation / postgres-tools (push) Successful in 19s
Foundation / image (push) Successful in 2m15s
Foundation / server-image (push) Successful in 20m37s
Add M10.4b durable action records (schema v11)
Each batch's actions are recorded in the same statement as its checkpoint: one
region_actions row per (world, account, action id) and the block in an append-only
table, compared on exact retries and resolution. The region host attaches actions to
the ticks they ride and reports acknowledgements and drops, keeping unknown-outcome
batches unresolved. Outcomes come from the durable record via ActionLedger, so
crashes before or after a commit, unknown publications and cross-region moves all
resolve to one answer; a repeated id keeps its first record instead of stalling a
region. ADR-0092.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 22:53:38 -04:00

147 lines
7.2 KiB
C++

#pragma once
#include "evo/network/session_control.hpp"
#include "evo/network/session_protocol.hpp"
#include <cstddef>
#include <cstdint>
#include <deque>
#include <expected>
#include <optional>
#include <span>
#include <utility>
#include <vector>
// 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.
std::uint64_t watermark_every{20}; // Ticks between repeats of an unchanged watermark.
};
// 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<std::optional<ActionOutcome>, 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<IntentAdmission, IntentConfigError>
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.
[[nodiscard]] std::vector<std::pair<std::uint64_t, SimulatedThrough>>
simulated(const AdmissionFacts& facts);
// Scheduled actions whose tick is <= `tick`: they ride that tick's batch from now on.
[[nodiscard]] std::vector<CarriedAction> 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<AccountOutcome> committed(std::span<const CarriedAction> 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<AccountOutcome> dropped(std::span<const CarriedAction> 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<AccountOutcome> abandon();
// The current session of an account, for delivering outcomes.
[[nodiscard]] std::optional<std::uint64_t> 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> 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<Session> sessions_;
std::vector<Action> actions_;
std::deque<AccountOutcome> finals_;
ActionLedger* ledger_{};
};
} // namespace evo::network