Add M10.4a intentions, actions and admission
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m45s
Foundation / checks (network) (push) Successful in 9m37s
Foundation / checks (client) (push) Successful in 12m14s
Foundation / checks (tsan) (push) Successful in 7m39s
Foundation / checks (checks) (push) Successful in 31m15s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 32m59s

Session protocol v1 (not yet deployed, amended in place) gains realtime intentions on
datagrams with receipts and a cumulative simulated watermark, and account-scoped
actions with stable ids, receipts, final outcomes and queries. IntentAdmission
enforces session binding, rate, authority, epoch, vector, sequence, tick window,
duplicates and the unresolved bound; RegionSessions and the client carry it over
QUIC. Intentions and actions have no biological effect yet. ADR-0092.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-03 22:09:06 -04:00
co-authored by Claude Opus 5.5
parent 890c57a77f
commit e2f6208433
18 changed files with 1155 additions and 48 deletions
+20 -1
View File
@@ -6,13 +6,16 @@
#include <expected>
#include <memory>
#include <optional>
#include <vector>
// M10.3b client-side session login over QUIC (ADR-0091, schemas/network/session-v1.md).
// Owned by one thread, which calls poll(). Sends Hello with the grant once the pinned
// connection is up (then forgets the grant), waits for Welcome or Close, and can renew
// the session in place with a newer grant. A Close from the server, a malformed message,
// the Welcome deadline or a lost transport ends the session; reconnecting needs a new
// client and a fresh grant (ADR-0089). Intentions and views are later segments.
// client and a fresh grant (ADR-0089). M10.4 (ADR-0092): intentions as datagrams with
// receipts and a simulated watermark; actions with stable ids, receipts and final outcomes.
// The client never treats a receipt or the watermark as a final outcome. Views are 10.5.
namespace evo::client {
struct RegionSessionClientConfig {
network::quic::ClientConfig transport;
@@ -36,6 +39,22 @@ class RegionSessionClient {
[[nodiscard]] std::optional<network::SessionRefreshResult> take_refresh_result();
// Sends Close{client_closed} and closes the connection.
void close();
// Realtime intention for `tick` (server_tick + 1 ..= + 8); returns its sequence, or
// nothing unless established and sent. Datagrams may be lost: no receipt is not a refusal.
[[nodiscard]] std::optional<std::uint64_t>
send_intention(std::uint64_t tick, std::int16_t move_x, std::int16_t move_y);
// A discrete action with a caller-chosen id, unique for the account (stable across
// retries and reconnects). False unless established and sent.
[[nodiscard]] bool send_action(std::uint64_t action_id, network::ActionKind kind,
std::uint64_t tick);
[[nodiscard]] bool query_action(std::uint64_t action_id);
[[nodiscard]] std::vector<network::IntentionReceipt> take_intention_receipts();
[[nodiscard]] std::vector<network::ActionReceipt> take_action_receipts();
[[nodiscard]] std::vector<network::ActionOutcome> take_action_outcomes();
// Newest simulated watermark of this session's epoch.
[[nodiscard]] std::optional<network::SimulatedThrough> simulated() const noexcept;
// Latest server tick seen (Welcome, receipts, watermarks); 0 before Welcome.
[[nodiscard]] std::uint64_t server_tick() const noexcept;
[[nodiscard]] RegionSessionState state() const noexcept;
[[nodiscard]] const std::optional<network::SessionWelcome>& welcome() const noexcept;
[[nodiscard]] std::optional<network::SessionCloseReason> close_reason() const noexcept;
+107
View File
@@ -0,0 +1,107 @@
#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 <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 };
class IntentAdmission {
public:
[[nodiscard]] static std::expected<IntentAdmission, IntentConfigError>
create(IntentLimits limits);
// 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);
// What this process knows about an action of the session's account.
[[nodiscard]] ActionOutcome query(std::uint64_t session, const ActionQuery& m) const;
// 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);
// A commit covering ticks up to `end_tick` is durable: its carried actions are final.
[[nodiscard]] std::vector<AccountOutcome> committed(std::uint64_t end_tick,
std::uint64_t commit_sequence);
// Authority lost or epoch advanced: actions never carried are final (not_committed);
// carried ones stay unresolved until a durable record decides them (10.4b).
[[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{};
};
explicit IntentAdmission(IntentLimits limits) : limits_{limits} {}
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_;
};
} // namespace evo::network
+86 -8
View File
@@ -7,8 +7,10 @@
#include <variant>
#include <vector>
// M10 session protocol v1, session part (ADR-0091, schemas/network/session-v1.md).
// Messages travel on the QUIC reliable stream (one message per framed QUIC message).
// 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 segments add message types under a new version.
@@ -19,11 +21,42 @@ 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.
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.
};
// 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).
};
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.
};
// Wire values 1..13. `connection_lost` is local only (the transport ended without a Close).
enum class SessionCloseReason : std::uint8_t {
@@ -60,6 +93,7 @@ struct SessionHello {
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 {
@@ -75,8 +109,52 @@ struct SessionRefreshResult {
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;
};
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 committed_no_effect.
friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default;
};
struct ActionQuery {
std::uint64_t action_id{};
friend bool operator==(const ActionQuery&, const ActionQuery&) = default;
};
using SessionMessage =
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose>;
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
SessionIntention, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
ActionOutcome, ActionQuery>;
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
// Exactly one message; any other length for its type rejects.
+22 -4
View File
@@ -1,4 +1,5 @@
#pragma once
#include "evo/network/intent_admission.hpp"
#include "evo/network/quic_transport.hpp"
#include "evo/network/session_control.hpp"
#include "evo/network/session_grant.hpp"
@@ -18,7 +19,11 @@
// public keys and admitted by SessionControl. A newer grant for an account closes the
// account's previous connection with `superseded`. Refusals and closes send Close with a
// reason, then the connection is closed after a short flush. Intentions and views are
// later segments (10.4, 10.5). Events carry account log labels only, never grants.
// later segments (10.5). Events carry account log labels only, never grants.
// M10.4 (ADR-0092): established sessions send intentions (datagrams) and actions (stream);
// IntentAdmission answers with receipts, simulated watermarks and final action outcomes.
// The host reports its authority each poll, takes carried actions for its batches and
// reports durable commits.
// With a ControlLedger, control is durable and unique per world: a session that loses its
// durable control (another region accepted a newer grant) closes with `superseded`, and
// one whose control cannot be renewed in time closes with `shutdown`.
@@ -39,6 +44,13 @@ struct RegionSessionsConfig {
// `renew_interval` and closes before its control can lapse (`safety_margin`).
network::ControlLedger* ledger{};
std::chrono::milliseconds renew_interval{5000}, safety_margin{2000};
network::IntentLimits intents{}; // max_sessions follows control.max_sessions.
};
// The region host's authority, read once per poll.
struct HostFacts {
bool ready{}; // Current authority, recovered, not draining.
std::uint64_t epoch{}; // Ownership epoch; a newer one closes every session.
std::uint64_t simulated_tick{};
};
enum class RegionSessionsError : std::uint8_t { configuration, keys, transport };
struct RegionSessionEvent {
@@ -55,10 +67,16 @@ class RegionSessions {
RegionSessions(const RegionSessions&) = delete;
RegionSessions& operator=(const RegionSessions&) = delete;
~RegionSessions();
// `epoch` is the region's current ownership epoch: a newer one closes every session
// (stale_epoch). `now_seconds` is wall time for grants, `now` monotonic for deadlines.
void poll(std::uint64_t epoch, std::uint64_t now_seconds,
// A newer epoch closes every session (stale_epoch) and abandons unscheduled actions.
// `now_seconds` is wall time for grants, `now` monotonic for deadlines.
void poll(const HostFacts& facts, std::uint64_t now_seconds,
std::chrono::steady_clock::time_point now);
// Actions scheduled for ticks <= `tick`, to be recorded durably with the batch that
// simulates that tick (10.4b). Each action is returned once.
[[nodiscard]] std::vector<network::CarriedAction> carry(std::uint64_t tick);
// A commit covering ticks up to `end_tick` is durable: carried actions become final and
// their outcomes are sent to each account's current session.
void committed(std::uint64_t end_tick, std::uint64_t commit_sequence);
// Closes every connection with `shutdown` (flushed by later polls).
void shutdown(std::chrono::steady_clock::time_point now);
[[nodiscard]] std::vector<RegionSessionEvent> take_events();