Wire M10.8c-1 region handoff: protocol v4, durable probes, crossing, ghosts
Foundation / checks (deploy) (push) Successful in 3m29s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (client) (push) Successful in 12m51s
Foundation / checks (network) (push) Successful in 13m0s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 32m4s
Foundation / checks (postgres) (push) Canceled after 19m13s

ADR-0096. Session protocol v4 (v3 is deployed and frozen) adds HandoffOffer,
SessionRedirect, close reasons handed_off and moved, and ghost marker records.
Sessions use the durable probe record: logins open it where it was saved
(redirected when it lives elsewhere), and session ends save it. A marker
crossing into a neighbour's area is frozen, prepared, its control released
and a signed ticket offered; uncommitted transfers are aborted after the
ticket's lifetime. The destination shows arriving probes as ghosts (schema
v13 incoming_probe_transfers) and opens the marker where it crossed.

Refreshes the dev session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 21:24:42 -04:00
co-authored by Claude Opus 5.5
parent 97a3756e46
commit a7a3d12283
39 changed files with 1315 additions and 68 deletions
+2 -1
View File
@@ -68,11 +68,12 @@ struct InterpolationLimits {
struct RemoteMarker {
std::uint64_t id{};
network::motion::State state;
bool ghost{}; // A probe being handed to this region (ADR-0096): read-only.
};
struct PresentedMarker {
std::uint64_t id{};
double x{}, y{}; // Micrometres.
bool extrapolated{}, stale{};
bool extrapolated{}, stale{}, ghost{};
};
struct InterpolationStats {
std::uint64_t snapshots{}, ignored{}, extrapolated_frames{}, stale_frames{}, gap_snaps{};
+5
View File
@@ -74,6 +74,11 @@ class RegionSessionClient {
[[nodiscard]] RegionSessionState state() const noexcept;
[[nodiscard]] const std::optional<network::SessionWelcome>& welcome() const noexcept;
[[nodiscard]] std::optional<network::SessionCloseReason> close_reason() const noexcept;
// v4 (ADR-0096): the offer to continue at another region (kept until taken; the session
// then closes with handed_off), and where the account's probe is when a login was closed
// with moved.
[[nodiscard]] std::optional<network::HandoffOffer> take_handoff();
[[nodiscard]] const std::optional<network::RegionAddress>& redirect() const noexcept;
// Why the QUIC connection itself ended (e.g. `untrusted`: the server answered but its
// certificate failed the pinned check), when it ended without a session Close.
[[nodiscard]] std::optional<network::quic::CloseCause> transport_cause() const noexcept;
+8 -1
View File
@@ -133,13 +133,20 @@ enum class HandoffLedgerError : std::uint8_t {
fenced, // This region's lease is not current.
unavailable // Not decided (database unreachable, timeout, unknown outcome): retry later.
};
// What the destination now owns: the account's control lease and the probe's state after
// the committed switch (its generation and position, in micrometres).
struct HandoffAdmission {
ControlLease lease;
std::uint64_t generation{};
std::int64_t x{}, y{};
};
class HandoffLedger {
public:
HandoffLedger() = default;
HandoffLedger(const HandoffLedger&) = delete;
HandoffLedger& operator=(const HandoffLedger&) = delete;
virtual ~HandoffLedger() = default;
[[nodiscard]] virtual std::expected<ControlLease, HandoffLedgerError>
[[nodiscard]] virtual std::expected<HandoffAdmission, HandoffLedgerError>
admit(const TicketClaims& ticket, std::uint64_t session) = 0;
protected:
+26
View File
@@ -1,9 +1,11 @@
#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#include <deque>
#include <expected>
#include <optional>
#include <span>
#include <vector>
// M10.6 probe-motion experiment (ADR-0094). EXPERIMENT, not a game rule: one
@@ -47,6 +49,16 @@ struct Marker {
std::uint64_t id{}, session{};
State state;
std::uint64_t applied_sequence{}; // Newest intention whose vector is in `state`.
// M10.8c (ADR-0096): frozen markers neither move nor take intentions (a handoff is being
// prepared); ghosts are read-only copies of probes being handed to this region (no
// session, never moving).
bool frozen{}, ghost{};
};
// A probe arriving here, shown read-only until its transfer commits (keyed by transfer id).
struct Ghost {
std::array<std::uint8_t, 16> transfer{};
std::int64_t x{}, y{};
friend bool operator==(const Ghost&, const Ghost&) = default;
};
enum class MarkerError : std::uint8_t { no_area, unknown_session, full, invalid };
class ProbeMarkers {
@@ -61,6 +73,15 @@ class ProbeMarkers {
}
// A marker for the session, at the spawn, holding no movement.
[[nodiscard]] std::expected<std::uint64_t, MarkerError> open(std::uint64_t session);
// The same at a given position (a durable probe's, clamped into the area).
[[nodiscard]] std::expected<std::uint64_t, MarkerError> open_at(std::uint64_t session,
std::int64_t x, std::int64_t y);
// Moves the session's marker to a position (clamped into the area), keeping its vector.
void place(std::uint64_t session, std::int64_t x, std::int64_t y);
// Stops the session's marker where it is: no motion and no new intentions.
void freeze(std::uint64_t session);
// Replaces the ghosts (stable ids per transfer; at most max_markers).
void set_ghosts(std::span<const Ghost> ghosts);
void close(std::uint64_t session);
// Removes every marker and forgets the tick (a new epoch may restart at an earlier one).
void clear() noexcept;
@@ -90,11 +111,16 @@ class ProbeMarkers {
Marker marker;
std::deque<Scheduled> scheduled; // Ascending tick, then sequence.
};
struct GhostEntry {
Ghost ghost;
std::uint64_t id{};
};
std::size_t max_markers_, max_scheduled_;
std::optional<Area> area_;
std::int64_t spawn_x_{}, spawn_y_{};
std::vector<Marker> markers_; // Mirror of entries_ for readers, in id order.
std::vector<Entry> entries_;
std::vector<GhostEntry> ghosts_;
std::uint64_t tick_{}, next_id_{1};
void publish();
};
+1
View File
@@ -120,6 +120,7 @@ struct ReplicatedMarker {
motion::State state;
std::int64_t z{};
bool own{};
bool ghost{}; // v4: a probe being handed to this region, read-only (ADR-0096).
std::uint64_t applied_sequence{};
motion::Area area;
friend bool operator==(const ReplicatedMarker&, const ReplicatedMarker&) = default;
+34 -5
View File
@@ -4,6 +4,7 @@
#include <cstdint>
#include <expected>
#include <span>
#include <string>
#include <variant>
#include <vector>
@@ -17,9 +18,12 @@
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; no new message
// types. v1 and v2 were deployed to evolution-dev and are frozen; only v3 is accepted.
inline constexpr std::uint16_t session_protocol_version = 3;
// 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; only v4 is accepted.
inline constexpr std::uint16_t session_protocol_version = 4;
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;
@@ -39,7 +43,9 @@ enum class SessionMessageType : std::uint8_t {
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).
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).
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
@@ -80,6 +86,8 @@ enum class SessionCloseReason : std::uint8_t {
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 {
@@ -184,10 +192,31 @@ 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, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck>;
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck,
HandoffOffer, SessionRedirect>;
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
// Exactly one message; any other length for its type rejects.
+12
View File
@@ -5,6 +5,7 @@
#include <cstdint>
#include <expected>
#include <optional>
#include <vector>
// Linux-only calls to the probe record and handoff functions of schema v12 (ADR-0096,
// migrations/0012_probe_handoff.sql). EXPERIMENT: probes are non-biological engineering
@@ -75,4 +76,15 @@ abort_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const
[[nodiscard]] std::expected<std::optional<ProbeTransfer>, ProbeStoreFailure>
find_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer,
std::chrono::milliseconds timeout);
// Schema v13: the open (prepared or staged) transfers addressed to the caller's region, for
// read-only ghosts (at most 256, oldest first).
struct IncomingTransfer {
Uuid transfer{}, account{};
std::uint64_t source{};
std::int64_t x{}, y{}, z{};
friend bool operator==(const IncomingTransfer&, const IncomingTransfer&) = default;
};
[[nodiscard]] std::expected<std::vector<IncomingTransfer>, ProbeStoreFailure>
incoming_probe_transfers(Postgres& db, RegionKey key, const LeaseGrant& lease,
std::chrono::milliseconds timeout);
} // namespace evo::persistence
+33 -1
View File
@@ -2,10 +2,12 @@
#include "evo/network/handoff_ticket.hpp"
#include "evo/persistence/probe_store.hpp"
#include "evo/server/pg_slot.hpp"
#include "evo/server/probe_ledger.hpp"
#include <chrono>
#include <functional>
#include <optional>
#include <utility>
#include <vector>
// M10.8b destination side of a ticket login over PostgreSQL (ADR-0096, schema v12). Linux
// only; owned by the region host's thread, on its own connection slot. For a verified ticket:
@@ -21,7 +23,7 @@ class PostgresHandoffLedger final : public network::HandoffLedger {
std::chrono::milliseconds duration = std::chrono::milliseconds{20000},
std::chrono::milliseconds timeout = std::chrono::milliseconds{2000})
: db_{&db}, key_{key}, lease_{std::move(lease)}, duration_{duration}, timeout_{timeout} {}
[[nodiscard]] std::expected<network::ControlLease, network::HandoffLedgerError>
[[nodiscard]] std::expected<network::HandoffAdmission, network::HandoffLedgerError>
admit(const network::TicketClaims& ticket, std::uint64_t session) override;
private:
@@ -30,4 +32,34 @@ class PostgresHandoffLedger final : public network::HandoffLedger {
LeaseSource lease_;
std::chrono::milliseconds duration_, timeout_;
};
// M10.8c the region's durable probe records over PostgreSQL (ADR-0096, schema v12-13), on the
// host's lease and its own connection slot. Undecided or failed calls report `unavailable`
// (the session layer retries or refuses); a fenced lease reports `fenced`.
class PostgresProbeLedger final : public ProbeLedger {
public:
using LeaseSource = std::function<std::optional<persistence::LeaseGrant>()>;
static constexpr std::uint64_t inventory = 1000; // EXPERIMENT test inventory per probe.
PostgresProbeLedger(PgSlot& db, persistence::RegionKey key, LeaseSource lease,
std::chrono::milliseconds timeout = std::chrono::milliseconds{2000})
: db_{&db}, key_{key}, lease_{std::move(lease)}, timeout_{timeout} {}
[[nodiscard]] std::expected<ProbeHome, ProbeLedgerError> open(const network::AccountId& account,
std::int64_t x, std::int64_t y,
std::int64_t z) override;
void save(const network::AccountId& account, std::uint64_t generation, std::int64_t x,
std::int64_t y, std::int64_t z) override;
[[nodiscard]] std::expected<void, ProbeLedgerError>
prepare(const network::AccountId& account, std::uint64_t generation,
const network::TransferId& transfer, std::uint64_t destination, std::int64_t x,
std::int64_t y, std::int64_t z) override;
[[nodiscard]] std::expected<bool, ProbeLedgerError>
abort(const network::TransferId& transfer) override;
[[nodiscard]] std::expected<std::vector<IncomingProbe>, ProbeLedgerError> incoming() override;
private:
PgSlot* db_;
persistence::RegionKey key_;
LeaseSource lease_;
std::chrono::milliseconds timeout_;
};
} // namespace evo::server
+51
View File
@@ -0,0 +1,51 @@
#pragma once
#include "evo/network/handoff_ticket.hpp"
#include "evo/network/session_control.hpp"
#include <cstdint>
#include <expected>
#include <vector>
// M10.8c (ADR-0096): the region's durable probe records as the session layer uses them.
// Transport-neutral; the host implements it over PostgreSQL (PostgresProbeLedger), tests use
// fakes. EXPERIMENT: probes are non-biological engineering entities (ADR-0094).
namespace evo::server {
struct ProbeHome {
std::uint64_t owner{}, generation{};
std::int64_t x{}, y{};
bool frozen{}; // An open transfer: neither this region nor the owner may act yet.
};
struct IncomingProbe {
network::TransferId transfer{};
std::int64_t x{}, y{};
};
enum class ProbeLedgerError : std::uint8_t { fenced, unavailable };
class ProbeLedger {
public:
ProbeLedger() = default;
ProbeLedger(const ProbeLedger&) = delete;
ProbeLedger& operator=(const ProbeLedger&) = delete;
virtual ~ProbeLedger() = default;
// The account's probe, created here at the position when the world has none.
[[nodiscard]] virtual std::expected<ProbeHome, ProbeLedgerError>
open(const network::AccountId& account, std::int64_t x, std::int64_t y, std::int64_t z) = 0;
// Best effort: the owned, active probe's position (session end).
virtual void save(const network::AccountId& account, std::uint64_t generation, std::int64_t x,
std::int64_t y, std::int64_t z) = 0;
// Freezes the probe at its final position for `destination`.
[[nodiscard]] virtual std::expected<void, ProbeLedgerError>
prepare(const network::AccountId& account, std::uint64_t generation,
const network::TransferId& transfer, std::uint64_t destination, std::int64_t x,
std::int64_t y, std::int64_t z) = 0;
// Abandons a transfer whose client never arrived: true when aborted (the probe is active
// here again), false when it had been committed.
[[nodiscard]] virtual std::expected<bool, ProbeLedgerError>
abort(const network::TransferId& transfer) = 0;
// Open transfers addressed to this region (shown as ghosts).
[[nodiscard]] virtual std::expected<std::vector<IncomingProbe>, ProbeLedgerError>
incoming() = 0;
protected:
ProbeLedger(ProbeLedger&&) = default;
ProbeLedger& operator=(ProbeLedger&&) = default;
};
} // namespace evo::server
+17 -1
View File
@@ -7,6 +7,7 @@
#include "evo/network/session_control.hpp"
#include "evo/network/session_grant.hpp"
#include "evo/network/session_protocol.hpp"
#include "evo/server/probe_ledger.hpp"
#include <chrono>
#include <cstddef>
#include <cstdint>
@@ -46,6 +47,11 @@ struct IssuerKey {
std::uint32_t key_id{};
network::GrantPublicKey public_key{};
};
// A region whose area adjoins this one: where its clients dial and the area it owns.
struct Neighbour {
network::RegionAddress address;
network::motion::Area area; // Micrometres, same slice as this region's.
};
// A neighbouring region's handoff public key (ADR-0096): tickets it signs are accepted here.
struct HandoffKey {
std::uint64_t source_region{};
@@ -73,6 +79,15 @@ struct RegionSessionsConfig {
// ticket also needs a HandoffLedger (control must move durably with the transfer).
std::vector<HandoffKey> handoff_keys;
network::HandoffLedger* handoff{};
// M10.8c: with probe records, a session's marker is the account's durable probe (it opens
// where it was saved, a login whose probe lives elsewhere is redirected). With this
// region's handoff key and neighbours as well, a marker crossing into a neighbour's area
// is frozen, prepared and handed over with a ticket.
ProbeLedger* probes{};
std::shared_ptr<const network::HandoffSigningKey> handoff_key;
std::vector<Neighbour> neighbours;
std::uint64_t ticket_lifetime{30}; // Seconds a handoff ticket is valid.
std::chrono::milliseconds ghost_poll{1000}; // Incoming transfers read this often.
};
// The region host's authority, read once per poll.
struct HostFacts {
@@ -119,7 +134,8 @@ class RegionSessions {
const network::Perceives& perceives = {});
[[nodiscard]] network::ReplicationStats replication_stats() const;
// Where probe markers live and spawn (ADR-0094); sessions already established receive a
// marker. False for an invalid area.
// marker. False for an invalid area. With neighbours (ADR-0096), markers move within the
// bounding box of this area and the neighbours' areas, and leaving this area hands off.
[[nodiscard]] bool set_motion_area(const network::motion::Area& area, std::int64_t spawn_x,
std::int64_t spawn_y);
[[nodiscard]] const network::motion::ProbeMarkers& markers() const noexcept;