Carry the engulf intent on v10 sessions and the batch trace
Foundation / checks (ecs) (push) Successful in 2m28s
Foundation / checks (deploy) (push) Successful in 4m6s
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 6m47s
Foundation / checks (checks) (push) Canceled after 6m58s
Foundation / checks (client) (push) Canceled after 6m59s
Foundation / checks (tsan) (push) Canceled after 4m28s
Foundation / checks (network) (push) Canceled after 6m58s

ADR-0124: byte 12 of the canonical cellular input, the CellularAction
wire message and the batch trace record becomes a target kind (0 none,
1 patch, 2 engulf with zero coordinates). Kind 2 exists only on v10,
which no server admitted before; cellular servers now admit v10 with v9
behaviour plus engulf, and still refuse a v10 mutation choice until
11.4c. Admission, the session-batch adapter, trace codec, matcher and
action-block validator carry the kind.

The client session library accepts v10 and an engulf flag, and its send
no longer reports a message its version cannot encode as sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-13 19:04:46 -04:00
co-authored by Claude Opus 5.5
parent 02adc35fa2
commit e17ade8cb7
15 changed files with 175 additions and 39 deletions
+18 -11
View File
@@ -88,10 +88,11 @@ struct RegionSessionClient::Impl {
protocol_close("datagram unexpected", static_cast<int>(decoded->index()), bytes.size());
}
// An encoding refused for this session's version (empty) is never sent as success.
bool send(const network::SessionMessage& m) {
return connection != 0 &&
endpoint->send_message(connection, network::encode_session(m, protocol_version))
.has_value();
const auto bytes = network::encode_session(m, protocol_version);
return connection != 0 && !bytes.empty() &&
endpoint->send_message(connection, bytes).has_value();
}
// Ends the session locally; `tell` sends a Close first (best effort).
void end(SessionCloseReason why, bool tell) {
@@ -171,7 +172,8 @@ RegionSessionClient::connect(RegionSessionClientConfig config, Clock::time_point
config.protocol_version != network::session_protocol_v6 &&
config.protocol_version != network::session_protocol_v7 &&
config.protocol_version != network::session_protocol_v8 &&
config.protocol_version != network::session_protocol_v9)
config.protocol_version != network::session_protocol_v9 &&
config.protocol_version != network::session_protocol_v10)
return std::unexpected(network::quic::EndpointError::configuration);
auto endpoint = network::quic::Endpoint::connect(config.transport);
if (!endpoint)
@@ -274,16 +276,17 @@ bool RegionSessionClient::send_action(std::uint64_t action_id, network::ActionKi
bool RegionSessionClient::send_cellular_action(
std::uint64_t action_id, std::uint64_t tick, std::int16_t move_x, std::int16_t move_y,
std::optional<std::pair<std::uint32_t, std::uint32_t>> intake_target) {
std::optional<std::pair<std::uint32_t, std::uint32_t>> intake_target, bool engulf) {
auto& m = *impl_;
return (m.protocol_version == network::session_protocol_v7 ||
m.protocol_version == network::session_protocol_v8 ||
m.protocol_version == network::session_protocol_v9) &&
m.protocol_version == network::session_protocol_v9 ||
m.protocol_version == network::session_protocol_v10) &&
m.state == RegionSessionState::established && m.welcome && action_id != 0 && tick != 0 &&
m.send(network::CellularAction{m.welcome->session, m.welcome->epoch, action_id, tick,
move_x, move_y, intake_target.has_value(),
intake_target ? intake_target->first : 0,
intake_target ? intake_target->second : 0});
intake_target ? intake_target->second : 0, engulf});
}
bool RegionSessionClient::query_action(std::uint64_t action_id) {
@@ -291,7 +294,8 @@ bool RegionSessionClient::query_action(std::uint64_t action_id) {
return (m.protocol_version == network::session_protocol_version ||
m.protocol_version == network::session_protocol_v7 ||
m.protocol_version == network::session_protocol_v8 ||
m.protocol_version == network::session_protocol_v9) &&
m.protocol_version == network::session_protocol_v9 ||
m.protocol_version == network::session_protocol_v10) &&
m.state == RegionSessionState::established && m.send(network::ActionQuery{action_id});
}
@@ -299,7 +303,8 @@ bool RegionSessionClient::request_primitive_life(std::uint64_t request_id) {
auto& m = *impl_;
return (m.protocol_version == network::session_protocol_v5 ||
m.protocol_version == network::session_protocol_v8 ||
m.protocol_version == network::session_protocol_v9) &&
m.protocol_version == network::session_protocol_v9 ||
m.protocol_version == network::session_protocol_v10) &&
m.state == RegionSessionState::established && m.welcome && request_id != 0 &&
m.send(network::PrimitiveLifeRequest{m.welcome->session, m.welcome->epoch, request_id});
}
@@ -308,7 +313,8 @@ bool RegionSessionClient::query_primitive_life(std::uint64_t request_id) {
auto& m = *impl_;
return (m.protocol_version == network::session_protocol_v5 ||
m.protocol_version == network::session_protocol_v8 ||
m.protocol_version == network::session_protocol_v9) &&
m.protocol_version == network::session_protocol_v9 ||
m.protocol_version == network::session_protocol_v10) &&
m.state == RegionSessionState::established && request_id != 0 &&
m.send(network::PrimitiveLifeQuery{request_id});
}
@@ -346,7 +352,8 @@ bool RegionSessionClient::set_interest(const network::SessionInterest& interest)
return (m.protocol_version == network::session_protocol_version ||
m.protocol_version == network::session_protocol_v7 ||
m.protocol_version == network::session_protocol_v8 ||
m.protocol_version == network::session_protocol_v9) &&
m.protocol_version == network::session_protocol_v9 ||
m.protocol_version == network::session_protocol_v10) &&
m.state == RegionSessionState::established && m.send(interest);
}
+2 -2
View File
@@ -239,7 +239,7 @@ ActionReceipt IntentAdmission::action(std::uint64_t session, const CellularActio
const SessionAction base{m.session, m.epoch, m.action_id,
static_cast<std::uint16_t>(ActionKind::cellular), m.tick};
const auto bytes = encode_cellular_action_input(
{m.tick, m.move_x, m.move_y, m.has_intake_target, m.intake_x_um, m.intake_y_um});
{m.tick, m.move_x, m.move_y, m.has_intake_target, m.intake_x_um, m.intake_y_um, m.engulf});
auto* s = find(session);
if (!s)
return {m.action_id, AdmitStatus::unknown_session, facts.server_tick, m.tick};
@@ -280,7 +280,7 @@ std::optional<ActionReceipt> IntentAdmission::admit(std::uint64_t session, const
const SessionAction base{m.session, m.epoch, m.action_id,
static_cast<std::uint16_t>(ActionKind::cellular), m.tick};
const auto bytes = encode_cellular_action_input(
{m.tick, m.move_x, m.move_y, m.has_intake_target, m.intake_x_um, m.intake_y_um});
{m.tick, m.move_x, m.move_y, m.has_intake_target, m.intake_x_um, m.intake_y_um, m.engulf});
auto* s = find(session);
if (!s)
return ActionReceipt{m.action_id, AdmitStatus::unknown_session, facts.server_tick, m.tick};
+15 -6
View File
@@ -161,6 +161,11 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
return {};
if (version != session_protocol_v10 && std::holds_alternative<CellularMutationAction>(message))
return {};
if (const auto* action = std::get_if<CellularAction>(&message);
action && action->engulf &&
(version != session_protocol_v10 || action->has_intake_target || action->intake_x_um ||
action->intake_y_um))
return {};
if (version != session_protocol_v8 && version != session_protocol_v9 &&
version != session_protocol_v10 && std::holds_alternative<CellularPerception>(message))
return {};
@@ -241,7 +246,7 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
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);
out.push_back(m.has_intake_target ? 1 : 0);
out.push_back(m.has_intake_target ? 1 : m.engulf ? 2 : 0); // Target kind.
put(out, 0, 3);
put(out, m.intake_x_um, 4);
put(out, m.intake_y_um, 4);
@@ -518,9 +523,12 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
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)));
if (payload[36] > 1 || payload[37] != 0 || payload[38] != 0 || payload[39] != 0)
// Target kind: 0 none, 1 patch intake, 2 engulf (v10 only, ADR-0124).
if (payload[36] > (wire_version == session_protocol_v10 ? 2 : 1) || payload[37] != 0 ||
payload[38] != 0 || payload[39] != 0)
return std::unexpected(SessionCodecError::invalid_value);
m.has_intake_target = payload[36] != 0;
m.has_intake_target = payload[36] == 1;
m.engulf = payload[36] == 2;
m.intake_x_um = static_cast<std::uint32_t>(get(payload, 40, 4));
m.intake_y_um = static_cast<std::uint32_t>(get(payload, 44, 4));
if (!m.session || !m.epoch || !m.action_id || !m.tick ||
@@ -781,7 +789,7 @@ encode_cellular_action_input(const CellularActionInput& input) {
put(bytes, input.tick, 8);
put(bytes, static_cast<std::uint16_t>(input.move_x), 2);
put(bytes, static_cast<std::uint16_t>(input.move_y), 2);
bytes.push_back(input.has_intake_target ? 1 : 0);
bytes.push_back(input.has_intake_target ? 1 : input.engulf ? 2 : 0); // Target kind.
put(bytes, 0, 3);
put(bytes, input.intake_x_um, 4);
put(bytes, input.intake_y_um, 4);
@@ -794,13 +802,14 @@ std::expected<CellularActionInput, SessionCodecError>
decode_cellular_action_input(std::span<const std::uint8_t> bytes) {
if (bytes.size() != cellular_action_input_bytes)
return std::unexpected(SessionCodecError::wrong_length);
if (bytes[12] > 1 || bytes[13] != 0 || bytes[14] != 0 || bytes[15] != 0)
if (bytes[12] > 2 || bytes[13] != 0 || bytes[14] != 0 || bytes[15] != 0)
return std::unexpected(SessionCodecError::invalid_value);
CellularActionInput input;
input.tick = get(bytes, 0, 8);
input.move_x = static_cast<std::int16_t>(static_cast<std::uint16_t>(get(bytes, 8, 2)));
input.move_y = static_cast<std::int16_t>(static_cast<std::uint16_t>(get(bytes, 10, 2)));
input.has_intake_target = bytes[12] != 0;
input.has_intake_target = bytes[12] == 1;
input.engulf = bytes[12] == 2;
input.intake_x_um = static_cast<std::uint32_t>(get(bytes, 16, 4));
input.intake_y_um = static_cast<std::uint32_t>(get(bytes, 20, 4));
if (input.tick == 0 ||
+7 -6
View File
@@ -36,7 +36,7 @@ bool valid_intent(const CellularLifeIntent& life) {
const auto& step = life.intent;
return life.life_id != 0 && step.movement.x >= -movement_limit &&
step.movement.x <= movement_limit && step.movement.y >= -movement_limit &&
step.movement.y <= movement_limit;
step.movement.y <= movement_limit && !(step.engulf && step.intake_target);
}
bool valid_ticks(std::span<const CellularTickIntents> ticks) {
std::set<std::uint64_t> identities;
@@ -83,7 +83,7 @@ bool valid_action_input(const CellularActionRecord& action, std::uint64_t begin_
const auto move_y = std::bit_cast<std::int16_t>(static_cast<std::uint16_t>(get(input, 10, 2)));
return !all_zero(action.account) && action.action_id != 0 && tick > begin_tick &&
tick <= end_tick && move_x >= -movement_limit && move_x <= movement_limit &&
move_y >= -movement_limit && move_y <= movement_limit && input[12] <= 1 &&
move_y >= -movement_limit && move_y <= movement_limit && input[12] <= 2 &&
all_zero(input.subspan(13, 3)) && (input[12] == 1 || all_zero(input.subspan(16, 8)));
}
bool action_less(const CellularActionRecord& a, const CellularActionRecord& b) {
@@ -137,7 +137,7 @@ void put_intent(std::vector<std::uint8_t>& out, const CellularLifeIntent& life)
put(out, life.life_id, 8);
put(out, static_cast<std::uint16_t>(life.intent.movement.x), 2);
put(out, static_cast<std::uint16_t>(life.intent.movement.y), 2);
out.push_back(life.intent.intake_target ? 1 : 0);
out.push_back(life.intent.intake_target ? 1 : life.intent.engulf ? 2 : 0); // Target kind.
put(out, 0, 3);
put(out, life.intent.intake_target ? life.intent.intake_target->x_um : 0, 4);
put(out, life.intent.intake_target ? life.intent.intake_target->y_um : 0, 4);
@@ -287,7 +287,7 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
step.lives.reserve(static_cast<std::size_t>(count));
for (std::uint64_t i = 0; i < count; ++i) {
const auto record = bytes.subspan(offset, cellular_batch_intent_bytes);
if (record[12] > 1 || !all_zero(record.subspan(13, 3)))
if (record[12] > 2 || !all_zero(record.subspan(13, 3)))
return std::unexpected{CellularBatchError::format};
CellularLifeIntent life;
life.life_id = get(record, 0, 8);
@@ -302,6 +302,7 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
} else if (!all_zero(record.subspan(16, 8))) {
return std::unexpected{CellularBatchError::format};
}
life.intent.engulf = record[12] == 2; // ADR-0124 target kind.
if (!valid_intent(life) ||
(!step.lives.empty() && step.lives.back().life_id >= life.life_id))
return std::unexpected{CellularBatchError::format};
@@ -492,14 +493,14 @@ match_cellular_actions_to_trace(const CellularLives& predecessor, const Cellular
return std::unexpected{CellularActionBlockError::mismatch};
const auto input = std::span<const std::uint8_t>{action.input};
std::optional<biology::CellularPatchAddress> target;
if (input[12] != 0)
if (input[12] == 1)
target = biology::CellularPatchAddress{static_cast<std::uint32_t>(get(input, 16, 4)),
static_cast<std::uint32_t>(get(input, 20, 4))};
if (intent->intent.movement.x !=
std::bit_cast<std::int16_t>(static_cast<std::uint16_t>(get(input, 8, 2))) ||
intent->intent.movement.y !=
std::bit_cast<std::int16_t>(static_cast<std::uint16_t>(get(input, 10, 2))) ||
intent->intent.intake_target != target)
intent->intent.intake_target != target || intent->intent.engulf != (input[12] == 2))
return std::unexpected{CellularActionBlockError::mismatch};
}
return {};
@@ -72,6 +72,8 @@ prepare_cellular_session_tick(const CellularLives& state, std::uint64_t tick,
? std::optional<biology::CellularPatchAddress>{biology::CellularPatchAddress{
input->intake_x_um, input->intake_y_um}}
: std::nullopt;
// ADR-0124: a rules-2 region reports the intent unsupported and ignores it.
owned_intent->intent.engulf = input->engulf;
CellularActionRecord record;
record.account = action.account.bytes;
record.action_id = action.action_id;
+11 -6
View File
@@ -434,7 +434,8 @@ struct RegionSessions::Impl {
(config.accept_cellular_actions &&
(c.protocol_version == network::session_protocol_v7 ||
c.protocol_version == network::session_protocol_v8 ||
c.protocol_version == network::session_protocol_v9)))))
c.protocol_version == network::session_protocol_v9 ||
c.protocol_version == network::session_protocol_v10)))))
return close(c, SessionCloseReason::protocol, now);
if (const auto* ack = std::get_if<network::SnapshotAck>(&*decoded))
return replication.acknowledge(c.session, *ack);
@@ -602,9 +603,10 @@ struct RegionSessions::Impl {
(wire_version == network::session_protocol_v6 && !cellular_v6) ||
((wire_version == network::session_protocol_v7 ||
wire_version == network::session_protocol_v8 ||
wire_version == network::session_protocol_v9) &&
wire_version == network::session_protocol_v9 ||
wire_version == network::session_protocol_v10) &&
!cellular_actions) ||
wire_version > network::session_protocol_v9)
wire_version > network::session_protocol_v10)
return close(c, SessionCloseReason::unsupported_version, now);
} else if (wire_version != c.protocol_version) {
return close(c, SessionCloseReason::unsupported_version, now);
@@ -629,7 +631,8 @@ struct RegionSessions::Impl {
if (const auto* m = std::get_if<network::CellularAction>(&*decoded)) {
if (c.protocol_version != network::session_protocol_v7 &&
c.protocol_version != network::session_protocol_v8 &&
c.protocol_version != network::session_protocol_v9)
c.protocol_version != network::session_protocol_v9 &&
c.protocol_version != network::session_protocol_v10)
return close(c, SessionCloseReason::protocol, now);
if (const auto receipt = intents.admit(c.session, *m, admission()))
answer(c, *receipt);
@@ -898,7 +901,8 @@ bool RegionSessions::send_cellular_perception(const network::AccountId& account,
for (const auto& c : m.connections) {
if (c.state != Impl::State::established ||
(c.protocol_version != network::session_protocol_v8 &&
c.protocol_version != network::session_protocol_v9) ||
c.protocol_version != network::session_protocol_v9 &&
c.protocol_version != network::session_protocol_v10) ||
c.account_id != account)
continue;
auto delivered = perception;
@@ -919,7 +923,8 @@ void RegionSessions::clear_cellular_perceptions(std::uint64_t tick) {
for (const auto& c : m.connections)
if (c.state == Impl::State::established &&
(c.protocol_version == network::session_protocol_v8 ||
c.protocol_version == network::session_protocol_v9))
c.protocol_version == network::session_protocol_v9 ||
c.protocol_version == network::session_protocol_v10))
m.send(c, cleared);
}