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
+246
View File
@@ -0,0 +1,246 @@
#include "evo/network/intent_admission.hpp"
#include <algorithm>
namespace evo::network {
namespace {
constexpr std::int32_t max_component = 1000;
bool valid_vector(std::int16_t x, std::int16_t y) {
const std::int32_t ix = x, iy = y;
return ix * ix + iy * iy <= max_component * max_component;
}
bool in_window(std::uint64_t tick, std::uint64_t server_tick, std::uint32_t window) {
return tick > server_tick && tick - server_tick <= window;
}
} // namespace
std::expected<IntentAdmission, IntentConfigError> IntentAdmission::create(IntentLimits limits) {
if (limits.intent_window == 0 || limits.intent_window > 64 || limits.window_ticks == 0 ||
limits.max_intents_per_window == 0 || limits.max_actions_per_window == 0 ||
limits.max_unresolved == 0 || limits.max_unresolved > 4096 || limits.max_sessions == 0 ||
limits.max_sessions > 1024 || limits.max_finals == 0 || limits.watermark_every == 0)
return std::unexpected(IntentConfigError::invalid);
IntentAdmission admission{limits};
admission.sessions_.reserve(limits.max_sessions);
return admission;
}
IntentAdmission::Session* IntentAdmission::find(std::uint64_t session) {
const auto it =
std::ranges::find_if(sessions_, [&](const Session& s) { return s.id == session; });
return it == sessions_.end() ? nullptr : &*it;
}
const IntentAdmission::Session* IntentAdmission::find(std::uint64_t session) const {
const auto it =
std::ranges::find_if(sessions_, [&](const Session& s) { return s.id == session; });
return it == sessions_.end() ? nullptr : &*it;
}
bool IntentAdmission::open(std::uint64_t session, const AccountId& account) {
if (session == 0 || find(session) || sessions_.size() >= limits_.max_sessions)
return false;
Session s;
s.id = session;
s.account = account;
sessions_.push_back(std::move(s));
return true;
}
void IntentAdmission::close(std::uint64_t session) {
// Unsimulated intentions die with the session; actions belong to the account and stay.
std::erase_if(sessions_, [&](const Session& s) { return s.id == session; });
}
void IntentAdmission::count_window(Session& s, std::uint64_t server_tick) const {
if (server_tick < s.window_start || server_tick - s.window_start >= limits_.window_ticks) {
s.window_start = server_tick;
s.intent_attempts = 0;
s.action_attempts = 0;
}
}
std::size_t IntentAdmission::unresolved_of(const Session& s) const {
return s.pending.size() +
static_cast<std::size_t>(std::ranges::count_if(
actions_, [&](const Action& a) { return a.carried.account == s.account; }));
}
std::size_t IntentAdmission::unresolved(std::uint64_t session) const {
const auto* s = find(session);
return s ? unresolved_of(*s) : 0;
}
IntentionReceipt IntentAdmission::intention(std::uint64_t session, const SessionIntention& m,
const AdmissionFacts& facts) {
IntentionReceipt r{m.sequence, AdmitStatus::admitted, facts.server_tick};
auto* s = find(session);
if (!s) {
r.status = AdmitStatus::unknown_session;
return r;
}
count_window(*s, facts.server_tick);
const bool over = s->intent_attempts >= limits_.max_intents_per_window;
if (!over)
++s->intent_attempts;
const std::uint64_t last_tick = s->pending.empty() ? 0 : s->pending.back().tick;
if (over)
r.status = AdmitStatus::rate_limited;
else if (m.session != session)
r.status = AdmitStatus::unknown_session;
else if (!facts.ready)
r.status = AdmitStatus::not_ready;
else if (m.epoch != facts.epoch)
r.status = AdmitStatus::stale_epoch;
else if (!valid_vector(m.move_x, m.move_y))
r.status = AdmitStatus::invalid_vector;
else if (m.sequence <= s->last_sequence)
r.status = AdmitStatus::replayed;
// One intention per tick (ADR-0089): ticks advance with the sequence.
else if (!in_window(m.tick, facts.server_tick, limits_.intent_window) || m.tick <= last_tick)
r.status = AdmitStatus::outside_window;
else if (unresolved_of(*s) >= limits_.max_unresolved)
r.status = AdmitStatus::too_many_unresolved;
if (r.status == AdmitStatus::admitted) {
s->last_sequence = m.sequence;
s->pending.push_back({m.sequence, m.tick});
}
return r;
}
ActionReceipt IntentAdmission::action(std::uint64_t session, const SessionAction& m,
const AdmissionFacts& facts) {
ActionReceipt r{m.action_id, AdmitStatus::admitted, facts.server_tick, m.tick};
auto* s = find(session);
if (!s) {
r.status = AdmitStatus::unknown_session;
return r;
}
count_window(*s, facts.server_tick);
const bool over = s->action_attempts >= limits_.max_actions_per_window;
if (!over)
++s->action_attempts;
const auto& account = s->account;
const auto known_action = std::ranges::find_if(actions_, [&](const Action& a) {
return a.carried.account == account && a.carried.action_id == m.action_id;
});
const auto known_final = std::ranges::find_if(finals_, [&](const AccountOutcome& f) {
return f.account == account && f.outcome.action_id == m.action_id;
});
if (over)
r.status = AdmitStatus::rate_limited;
else if (m.session != session)
r.status = AdmitStatus::unknown_session;
else if (!facts.ready)
r.status = AdmitStatus::not_ready;
else if (m.epoch != facts.epoch)
r.status = AdmitStatus::stale_epoch;
else if (m.kind != static_cast<std::uint16_t>(ActionKind::probe) || m.action_id == 0)
r.status = AdmitStatus::invalid_action;
else if (known_action != actions_.end() || known_final != finals_.end()) {
// Never admitted twice; the receipt names the tick it was scheduled for.
r.status = AdmitStatus::duplicate;
r.tick =
known_action != actions_.end() ? known_action->carried.tick : known_final->outcome.tick;
} else if (!in_window(m.tick, facts.server_tick, limits_.intent_window))
r.status = AdmitStatus::outside_window;
else if (unresolved_of(*s) >= limits_.max_unresolved)
r.status = AdmitStatus::too_many_unresolved;
if (r.status == AdmitStatus::admitted)
actions_.push_back({{account, m.action_id, m.tick, ActionKind::probe}, Stage::scheduled});
return r;
}
ActionOutcome IntentAdmission::query(std::uint64_t session, const ActionQuery& m) const {
ActionOutcome o{m.action_id, ActionResult::unknown, 0, 0};
const auto* s = find(session);
if (!s)
return o;
const auto pending = std::ranges::find_if(actions_, [&](const Action& a) {
return a.carried.account == s->account && a.carried.action_id == m.action_id;
});
if (pending != actions_.end()) {
o.result = ActionResult::pending;
o.tick = pending->carried.tick;
return o;
}
const auto final = std::ranges::find_if(finals_, [&](const AccountOutcome& f) {
return f.account == s->account && f.outcome.action_id == m.action_id;
});
return final != finals_.end() ? final->outcome : o;
}
std::vector<std::pair<std::uint64_t, SimulatedThrough>>
IntentAdmission::simulated(const AdmissionFacts& facts) {
std::vector<std::pair<std::uint64_t, SimulatedThrough>> out;
for (auto& s : sessions_) {
while (!s.pending.empty() && s.pending.front().tick <= facts.server_tick) {
s.watermark = s.pending.front().sequence;
s.pending.pop_front();
}
const bool changed = s.watermark != s.sent_watermark;
const bool repeat =
s.watermark != 0 && (facts.server_tick < s.sent_at_tick ||
facts.server_tick - s.sent_at_tick >= limits_.watermark_every);
if (changed || repeat) {
s.sent_watermark = s.watermark;
s.sent_at_tick = facts.server_tick;
out.emplace_back(s.id, SimulatedThrough{facts.epoch, s.watermark, facts.server_tick});
}
}
return out;
}
std::vector<CarriedAction> IntentAdmission::carry(std::uint64_t tick) {
std::vector<CarriedAction> out;
for (auto& a : actions_)
if (a.stage == Stage::scheduled && a.carried.tick <= tick) {
a.stage = Stage::carried;
out.push_back(a.carried);
}
return out;
}
void IntentAdmission::remember(const AccountId& account, const ActionOutcome& outcome) {
finals_.push_back({account, outcome});
while (finals_.size() > limits_.max_finals)
finals_.pop_front();
}
std::vector<AccountOutcome> IntentAdmission::committed(std::uint64_t end_tick,
std::uint64_t commit_sequence) {
std::vector<AccountOutcome> out;
std::erase_if(actions_, [&](const Action& a) {
if (a.stage != Stage::carried || a.carried.tick > end_tick)
return false;
const ActionOutcome o{a.carried.action_id, ActionResult::committed_no_effect,
a.carried.tick, commit_sequence};
out.push_back({a.carried.account, o});
remember(a.carried.account, o);
return true;
});
return out;
}
std::vector<AccountOutcome> IntentAdmission::abandon() {
std::vector<AccountOutcome> out;
std::erase_if(actions_, [&](const Action& a) {
if (a.stage != Stage::scheduled)
return false;
const ActionOutcome o{a.carried.action_id, ActionResult::not_committed, 0, 0};
out.push_back({a.carried.account, o});
remember(a.carried.account, o);
return true;
});
for (auto& s : sessions_)
s.pending.clear(); // Superseding intentions of a lost epoch are simply dropped.
return out;
}
std::optional<std::uint64_t> IntentAdmission::session_of(const AccountId& account) const {
const auto it =
std::ranges::find_if(sessions_, [&](const Session& s) { return s.account == account; });
if (it == sessions_.end())
return std::nullopt;
return it->id;
}
} // namespace evo::network
+121 -5
View File
@@ -4,10 +4,18 @@
namespace evo::network {
namespace {
constexpr std::size_t hello_bytes = 4 + session_grant_wire_bytes;
constexpr std::size_t welcome_bytes = std::size_t{7} * 8;
constexpr std::size_t welcome_bytes = std::size_t{8} * 8;
constexpr std::size_t refresh_bytes = session_grant_wire_bytes;
constexpr std::size_t refresh_result_bytes = 1 + 8;
constexpr std::size_t close_bytes = 1;
constexpr std::size_t intention_bytes = (std::size_t{4} * 8) + 4;
constexpr std::size_t intention_receipt_bytes = 8 + 1 + 8;
constexpr std::size_t simulated_bytes = std::size_t{3} * 8;
constexpr std::size_t action_bytes = (std::size_t{3} * 8) + 2 + 8;
constexpr std::size_t action_receipt_bytes = 8 + 1 + 8 + 8;
constexpr std::size_t action_outcome_bytes = 8 + 1 + 8 + 8;
constexpr std::size_t action_query_bytes = 8;
constexpr std::uint8_t max_admit_status = static_cast<std::uint8_t>(AdmitStatus::not_ready);
void put(std::vector<std::uint8_t>& out, std::uint64_t v, std::size_t count) {
for (std::size_t i = 0; i < count; ++i)
@@ -49,8 +57,8 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
}
std::vector<std::uint8_t> operator()(const SessionWelcome& m) const {
auto out = header(SessionMessageType::welcome, welcome_bytes);
for (const auto v :
{m.session, m.epoch, m.world, m.frame, m.region, m.expires_at, m.server_seconds})
for (const auto v : {m.session, m.epoch, m.world, m.frame, m.region, m.expires_at,
m.server_seconds, m.server_tick})
put(out, v, 8);
return out;
}
@@ -70,6 +78,56 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
out.push_back(static_cast<std::uint8_t>(m.reason));
return out;
}
std::vector<std::uint8_t> operator()(const SessionIntention& m) const {
auto out = header(SessionMessageType::intention, intention_bytes);
for (const auto v : {m.session, m.epoch, m.sequence, m.tick})
put(out, v, 8);
put(out, static_cast<std::uint16_t>(m.move_x), 2);
put(out, static_cast<std::uint16_t>(m.move_y), 2);
return out;
}
std::vector<std::uint8_t> operator()(const IntentionReceipt& m) const {
auto out = header(SessionMessageType::intention_receipt, intention_receipt_bytes);
put(out, m.sequence, 8);
out.push_back(static_cast<std::uint8_t>(m.status));
put(out, m.server_tick, 8);
return out;
}
std::vector<std::uint8_t> operator()(const SimulatedThrough& m) const {
auto out = header(SessionMessageType::simulated_through, simulated_bytes);
for (const auto v : {m.epoch, m.sequence, m.tick})
put(out, v, 8);
return out;
}
std::vector<std::uint8_t> operator()(const SessionAction& m) const {
auto out = header(SessionMessageType::action, action_bytes);
for (const auto v : {m.session, m.epoch, m.action_id})
put(out, v, 8);
put(out, m.kind, 2);
put(out, m.tick, 8);
return out;
}
std::vector<std::uint8_t> operator()(const ActionReceipt& m) const {
auto out = header(SessionMessageType::action_receipt, action_receipt_bytes);
put(out, m.action_id, 8);
out.push_back(static_cast<std::uint8_t>(m.status));
put(out, m.server_tick, 8);
put(out, m.tick, 8);
return out;
}
std::vector<std::uint8_t> operator()(const ActionOutcome& m) const {
auto out = header(SessionMessageType::action_outcome, action_outcome_bytes);
put(out, m.action_id, 8);
out.push_back(static_cast<std::uint8_t>(m.result));
put(out, m.tick, 8);
put(out, m.commit_sequence, 8);
return out;
}
std::vector<std::uint8_t> operator()(const ActionQuery& m) const {
auto out = header(SessionMessageType::action_query, action_query_bytes);
put(out, m.action_id, 8);
return out;
}
};
return std::visit(Encoder{}, message);
}
@@ -99,8 +157,8 @@ decode_session(std::span<const std::uint8_t> bytes) {
if (!expect(welcome_bytes))
return std::unexpected(SessionCodecError::wrong_length);
SessionWelcome m;
std::uint64_t* fields[] = {&m.session, &m.epoch, &m.world, &m.frame,
&m.region, &m.expires_at, &m.server_seconds};
std::uint64_t* fields[] = {&m.session, &m.epoch, &m.world, &m.frame,
&m.region, &m.expires_at, &m.server_seconds, &m.server_tick};
for (std::size_t i = 0; i < std::size(fields); ++i)
*fields[i] = get(payload, 8 * i, 8);
if (m.session == 0 || m.epoch == 0)
@@ -127,6 +185,64 @@ decode_session(std::span<const std::uint8_t> bytes) {
return std::unexpected(SessionCodecError::invalid_value);
return SessionClose{static_cast<SessionCloseReason>(payload[0])};
}
case static_cast<std::uint8_t>(SessionMessageType::intention): {
if (!expect(intention_bytes))
return std::unexpected(SessionCodecError::wrong_length);
SessionIntention m;
m.session = get(payload, 0, 8);
m.epoch = get(payload, 8, 8);
m.sequence = get(payload, 16, 8);
m.tick = get(payload, 24, 8);
m.move_x = static_cast<std::int16_t>(static_cast<std::uint16_t>(get(payload, 32, 2)));
m.move_y = static_cast<std::int16_t>(static_cast<std::uint16_t>(get(payload, 34, 2)));
return m; // Ranges belong to admission, which answers with a status.
}
case static_cast<std::uint8_t>(SessionMessageType::intention_receipt): {
if (!expect(intention_receipt_bytes))
return std::unexpected(SessionCodecError::wrong_length);
if (payload[8] > max_admit_status)
return std::unexpected(SessionCodecError::invalid_value);
return IntentionReceipt{get(payload, 0, 8), static_cast<AdmitStatus>(payload[8]),
get(payload, 9, 8)};
}
case static_cast<std::uint8_t>(SessionMessageType::simulated_through): {
if (!expect(simulated_bytes))
return std::unexpected(SessionCodecError::wrong_length);
return SimulatedThrough{get(payload, 0, 8), get(payload, 8, 8), get(payload, 16, 8)};
}
case static_cast<std::uint8_t>(SessionMessageType::action): {
if (!expect(action_bytes))
return std::unexpected(SessionCodecError::wrong_length);
SessionAction m;
m.session = get(payload, 0, 8);
m.epoch = get(payload, 8, 8);
m.action_id = get(payload, 16, 8);
m.kind = static_cast<std::uint16_t>(get(payload, 24, 2)); // Admission checks it.
m.tick = get(payload, 26, 8);
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::action_receipt): {
if (!expect(action_receipt_bytes))
return std::unexpected(SessionCodecError::wrong_length);
if (payload[8] > max_admit_status)
return std::unexpected(SessionCodecError::invalid_value);
return ActionReceipt{get(payload, 0, 8), static_cast<AdmitStatus>(payload[8]),
get(payload, 9, 8), get(payload, 17, 8)};
}
case static_cast<std::uint8_t>(SessionMessageType::action_outcome): {
if (!expect(action_outcome_bytes))
return std::unexpected(SessionCodecError::wrong_length);
if (payload[8] < static_cast<std::uint8_t>(ActionResult::committed_no_effect) ||
payload[8] > static_cast<std::uint8_t>(ActionResult::unknown))
return std::unexpected(SessionCodecError::invalid_value);
return ActionOutcome{get(payload, 0, 8), static_cast<ActionResult>(payload[8]),
get(payload, 9, 8), get(payload, 17, 8)};
}
case static_cast<std::uint8_t>(SessionMessageType::action_query): {
if (!expect(action_query_bytes))
return std::unexpected(SessionCodecError::wrong_length);
return ActionQuery{get(payload, 0, 8)};
}
default:
return std::unexpected(SessionCodecError::unknown_type);
}