Add cellular mutation action protocol v10
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m52s
Foundation / checks (checks) (push) Failing after 4m1s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (client) (push) Canceled after 11m9s
Foundation / checks (network) (push) Canceled after 9m18s
Foundation / checks (postgres) (push) Canceled after 7m18s

This commit is contained in:
dingo
2026-10-11 06:57:22 -04:00
parent 50b6e25c0c
commit 9da2bd37dd
6 changed files with 161 additions and 29 deletions
+2 -2
View File
@@ -68,8 +68,8 @@ if(BUILD_TESTING)
add_executable(evo-cellular-intent-protocol-tests tests/cellular_intent_protocol_tests.cpp)
target_link_libraries(evo-cellular-intent-protocol-tests PRIVATE evo_network_protocol)
evo_owned_target(evo-cellular-intent-protocol-tests)
add_test(NAME cellular-session-protocol-v6-v9 COMMAND evo-cellular-intent-protocol-tests)
set_tests_properties(cellular-session-protocol-v6-v9 PROPERTIES TIMEOUT 30 LABELS "network")
add_test(NAME cellular-session-protocol-v6-v10 COMMAND evo-cellular-intent-protocol-tests)
set_tests_properties(cellular-session-protocol-v6-v10 PROPERTIES TIMEOUT 30 LABELS "network")
add_executable(evo-cellular-intent-admission-tests tests/cellular_intent_admission_tests.cpp)
target_link_libraries(evo-cellular-intent-admission-tests PRIVATE evo_network_protocol)
evo_owned_target(evo-cellular-intent-admission-tests)
+7
View File
@@ -6800,3 +6800,10 @@ history, so the test now verifies the resulting v3 versions and history profile.
The remaining CI jobs had not completed when this correction was prepared; local
Windows builds have repeatedly stalled during Ninja without producing output.
The correction needs a fresh CI run.
The M11.4c mutation-choice v10 wire-codec slice adds message type 25 with a
fixed 64-byte canonical payload and strict decoder checks; v1-v9 remain frozen.
It does not enable v10 in the server or client runtime. The focused codec test
and schema are included, but local C++ builds stall during Ninja and
`clang-format` is not installed in this Windows environment. Linux CI is the
required compile, format, and test gate for this slice.
+15 -3
View File
@@ -15,7 +15,7 @@
// 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.
// 160-byte credentials here. Later M10/M11 segments add message types under new versions.
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.
@@ -32,6 +32,9 @@ inline constexpr std::uint16_t session_protocol_v7 = 7;
inline constexpr std::uint16_t session_protocol_v8 = 8;
// v9 adds owner-only current reserve and last committed tick effects to the v8 view.
inline constexpr std::uint16_t session_protocol_v9 = 9;
// v10 adds a reliable owner choice for a previously earned cellular mutation offer.
// Its durable effect is committed on the next cellular tick.
inline constexpr std::uint16_t session_protocol_v10 = 10;
inline constexpr std::size_t max_cellular_perceived_patches = 256;
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.
@@ -62,7 +65,8 @@ enum class SessionMessageType : std::uint8_t {
primitive_life_query,
cellular_intention = 22,
cellular_action = 23,
cellular_perception = 24
cellular_perception = 24,
cellular_mutation_action = 25
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
@@ -178,6 +182,14 @@ struct CellularAction {
std::uint32_t intake_x_um{}, intake_y_um{};
friend bool operator==(const CellularAction&, const CellularAction&) = default;
};
// v10 reliable choice. The server binds these values to the authenticated account and
// action id, revalidates the exact outstanding offer, and reserves successor identity.
struct CellularMutationAction {
std::uint64_t session{}, epoch{}, action_id{}, tick{};
std::uint64_t life_identity{}, event_index{}, offer_tick{};
std::uint16_t operator_id{};
friend bool operator==(const CellularMutationAction&, const CellularMutationAction&) = default;
};
// v8 server-to-owner view. Addresses and current inventory are already filtered by
// authoritative cell position/range; provenance and account identity are omitted.
struct CellularPerceivedPatch {
@@ -334,7 +346,7 @@ using SessionMessage =
SimulatedThrough, SessionAction, ActionReceipt, ActionOutcome, ActionQuery,
SessionInterest, SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect,
PrimitiveLifeRequest, PrimitiveLifeReceipt, PrimitiveLifeOutcome,
PrimitiveLifeQuery, CellularPerception>;
PrimitiveLifeQuery, CellularPerception, CellularMutationAction>;
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message,
@@ -0,0 +1,34 @@
# Session protocol v10 cellular mutation choice
ADR-0121 adds v10 as an additive extension. Versions 1–9 retain their exact
wire layouts and behavior. V10 retains the v9 owner diagnostics and adds a
reliable-stream mutation-choice action as message type 25. This message selects
an operator from an already earned offer; it supplies no genome, successor
identity, price, or biological state.
## Type 25
The standard 8-byte `EVSN` header uses version 10, type 25 and flags 0. The
payload is exactly 64 bytes, little-endian:
| Payload offset | Size | Field |
|---:|---:|---|
| 0 | 8 | authenticated session id, nonzero |
| 8 | 8 | control epoch, nonzero |
| 16 | 8 | stable per-account action id, nonzero |
| 24 | 8 | intended simulation tick, nonzero |
| 32 | 8 | stable life identity, nonzero |
| 40 | 8 | earned offer event index, nonzero |
| 48 | 8 | exact offer tick, nonzero and before the intended tick |
| 56 | 2 | offered operator id, nonzero |
| 58 | 6 | reserved, all zero |
The decoder rejects all zero identities, an offer tick at or after the target
tick, reserved bytes, wrong lengths, and use under versions 1–9. When server
admission is enabled, it must bind the action to the authenticated account,
verify the exact current offer and operator, reserve the successor identity
idempotently by `(world, account, action_id)`, then schedule the choice for that
advancing tick. The reliable receipt means admission only; the final outcome is
tied to the committed tick and its recovered cellular checkpoint. This document
defines the wire codec only; runtime admission remains disabled until its
durable reservation and publication path is complete.
+66 -23
View File
@@ -13,6 +13,7 @@ constexpr std::size_t close_bytes = 1;
constexpr std::size_t intention_bytes = (std::size_t{4} * 8) + 4;
constexpr std::size_t cellular_intention_bytes = (std::size_t{4} * 8) + 4 + 1 + 3 + 8;
constexpr std::size_t cellular_action_bytes = (std::size_t{4} * 8) + 4 + 1 + 3 + 8;
constexpr std::size_t cellular_mutation_action_bytes = (std::size_t{7} * 8) + 2 + 6;
constexpr std::size_t cellular_perception_prefix_bytes = 8 + 8 + 2;
constexpr std::size_t cellular_diagnostics_bytes = 64;
constexpr std::size_t cellular_perception_v9_prefix_bytes =
@@ -127,17 +128,19 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
std::holds_alternative<CellularPerception>(message)
? (std::get<CellularPerception>(message).diagnostics ? session_protocol_v9
: session_protocol_v8)
: std::holds_alternative<CellularAction>(message) ? session_protocol_v7
: std::holds_alternative<CellularIntention>(message) ? session_protocol_v6
: is_life ? session_protocol_v5
: session_protocol_version;
: std::holds_alternative<CellularAction>(message) ? session_protocol_v7
: std::holds_alternative<CellularMutationAction>(message) ? session_protocol_v10
: std::holds_alternative<CellularIntention>(message) ? session_protocol_v6
: is_life ? session_protocol_v5
: session_protocol_version;
return encode_session(message, version);
}
std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uint16_t version) {
if (version != session_protocol_version && version != session_protocol_v5 &&
version != session_protocol_v6 && version != session_protocol_v7 &&
version != session_protocol_v8 && version != session_protocol_v9)
version != session_protocol_v8 && version != session_protocol_v9 &&
version != session_protocol_v10)
return {};
if (version == session_protocol_version &&
(std::holds_alternative<PrimitiveLifeRequest>(message) ||
@@ -148,21 +151,25 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
if (version != session_protocol_v6 && std::holds_alternative<CellularIntention>(message))
return {};
if (version != session_protocol_v7 && version != session_protocol_v8 &&
version != session_protocol_v9 && std::holds_alternative<CellularAction>(message))
version != session_protocol_v9 && version != session_protocol_v10 &&
std::holds_alternative<CellularAction>(message))
return {};
if (version != session_protocol_v7 && version != session_protocol_v8 &&
version != session_protocol_v9 && std::holds_alternative<ActionOutcome>(message) &&
version != session_protocol_v9 && version != session_protocol_v10 &&
std::holds_alternative<ActionOutcome>(message) &&
std::get<ActionOutcome>(message).result == ActionResult::committed)
return {};
if (version != session_protocol_v10 && std::holds_alternative<CellularMutationAction>(message))
return {};
if (version != session_protocol_v8 && version != session_protocol_v9 &&
std::holds_alternative<CellularPerception>(message))
version != session_protocol_v10 && std::holds_alternative<CellularPerception>(message))
return {};
if (const auto* perception = std::get_if<CellularPerception>(&message)) {
if (!perception->tick || perception->patches.size() > max_cellular_perceived_patches ||
(!perception->life_identity && !perception->patches.empty()) ||
(version == session_protocol_v8 && perception->diagnostics) ||
(version == session_protocol_v9 && perception->life_identity &&
!perception->diagnostics) ||
((version == session_protocol_v9 || version == session_protocol_v10) &&
perception->life_identity && !perception->diagnostics) ||
(perception->life_identity == 0 && perception->diagnostics) ||
(perception->diagnostics && !valid_diagnostics(*perception->diagnostics)) ||
!std::ranges::is_sorted(perception->patches,
@@ -240,16 +247,27 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
put(out, m.intake_y_um, 4);
return out;
}
std::vector<std::uint8_t> operator()(const CellularMutationAction& m) const {
auto out = header(SessionMessageType::cellular_mutation_action,
cellular_mutation_action_bytes, version);
for (const auto value : {m.session, m.epoch, m.action_id, m.tick, m.life_identity,
m.event_index, m.offer_tick})
put(out, value, 8);
put(out, m.operator_id, 2);
put(out, 0, 6);
return out;
}
std::vector<std::uint8_t> operator()(const CellularPerception& m) const {
auto out = header(SessionMessageType::cellular_perception,
(version == session_protocol_v9 ? cellular_perception_v9_prefix_bytes
: cellular_perception_prefix_bytes) +
(version == session_protocol_v9 || version == session_protocol_v10
? cellular_perception_v9_prefix_bytes
: cellular_perception_prefix_bytes) +
m.patches.size() * cellular_perceived_patch_bytes,
version);
put(out, m.tick, 8);
put(out, m.life_identity, 8);
put(out, m.patches.size(), 2);
if (version == session_protocol_v9) {
if (version == session_protocol_v9 || version == session_protocol_v10) {
const auto& d = m.diagnostics;
put(out, d ? d->reserve_energy_pj : 0, 8);
for (const auto value : d ? d->reserve_matter_fg : std::array<std::uint64_t, 4>{})
@@ -404,7 +422,8 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
const auto wire_version = static_cast<std::uint16_t>(get(bytes, 4, 2));
if (wire_version != session_protocol_version && wire_version != session_protocol_v5 &&
wire_version != session_protocol_v6 && wire_version != session_protocol_v7 &&
wire_version != session_protocol_v8 && wire_version != session_protocol_v9)
wire_version != session_protocol_v8 && wire_version != session_protocol_v9 &&
wire_version != session_protocol_v10)
return std::unexpected(SessionCodecError::unsupported_version);
if (version)
*version = wire_version;
@@ -488,7 +507,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
}
case static_cast<std::uint8_t>(SessionMessageType::cellular_action): {
if (wire_version != session_protocol_v7 && wire_version != session_protocol_v8 &&
wire_version != session_protocol_v9)
wire_version != session_protocol_v9 && wire_version != session_protocol_v10)
return std::unexpected(SessionCodecError::unsupported_version);
if (!expect(cellular_action_bytes))
return std::unexpected(SessionCodecError::wrong_length);
@@ -509,12 +528,35 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
return std::unexpected(SessionCodecError::invalid_value);
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::cellular_perception): {
if (wire_version != session_protocol_v8 && wire_version != session_protocol_v9)
case static_cast<std::uint8_t>(SessionMessageType::cellular_mutation_action): {
if (wire_version != session_protocol_v10)
return std::unexpected(SessionCodecError::unsupported_version);
const auto prefix = wire_version == session_protocol_v9
? cellular_perception_v9_prefix_bytes
: cellular_perception_prefix_bytes;
if (!expect(cellular_mutation_action_bytes))
return std::unexpected(SessionCodecError::wrong_length);
CellularMutationAction m;
m.session = get(payload, 0, 8);
m.epoch = get(payload, 8, 8);
m.action_id = get(payload, 16, 8);
m.tick = get(payload, 24, 8);
m.life_identity = get(payload, 32, 8);
m.event_index = get(payload, 40, 8);
m.offer_tick = get(payload, 48, 8);
m.operator_id = static_cast<std::uint16_t>(get(payload, 56, 2));
if (!m.session || !m.epoch || !m.action_id || !m.tick || !m.life_identity ||
!m.event_index || !m.offer_tick || m.offer_tick >= m.tick || !m.operator_id ||
std::ranges::any_of(payload.subspan(58, 6),
[](std::uint8_t value) { return value != 0; }))
return std::unexpected(SessionCodecError::invalid_value);
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::cellular_perception): {
if (wire_version != session_protocol_v8 && wire_version != session_protocol_v9 &&
wire_version != session_protocol_v10)
return std::unexpected(SessionCodecError::unsupported_version);
const auto prefix =
wire_version == session_protocol_v9 || wire_version == session_protocol_v10
? cellular_perception_v9_prefix_bytes
: cellular_perception_prefix_bytes;
if (payload.size() < prefix)
return std::unexpected(SessionCodecError::wrong_length);
const auto count = static_cast<std::size_t>(get(payload, 16, 2));
@@ -526,7 +568,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
m.life_identity = get(payload, 8, 8);
if (!m.tick || (!m.life_identity && count))
return std::unexpected(SessionCodecError::invalid_value);
if (wire_version == session_protocol_v9) {
if (wire_version == session_protocol_v9 || wire_version == session_protocol_v10) {
CellularLifeDiagnostics d;
d.reserve_energy_pj = get(payload, 18, 8);
for (std::size_t channel = 0; channel < d.reserve_matter_fg.size(); ++channel)
@@ -553,7 +595,8 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
d.intake != CellularIntakeResult::not_reported)
return std::unexpected(SessionCodecError::invalid_value);
}
if (wire_version == session_protocol_v9 && m.life_identity && !m.diagnostics)
if ((wire_version == session_protocol_v9 || wire_version == session_protocol_v10) &&
m.life_identity && !m.diagnostics)
return std::unexpected(SessionCodecError::invalid_value);
if (m.diagnostics && !valid_diagnostics(*m.diagnostics))
return std::unexpected(SessionCodecError::invalid_value);
@@ -613,7 +656,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
payload[8] > static_cast<std::uint8_t>(ActionResult::committed) ||
(payload[8] == static_cast<std::uint8_t>(ActionResult::committed) &&
wire_version != session_protocol_v7 && wire_version != session_protocol_v8 &&
wire_version != session_protocol_v9))
wire_version != session_protocol_v9 && wire_version != session_protocol_v10))
return std::unexpected(SessionCodecError::invalid_value);
const ActionOutcome m{get(payload, 0, 8), static_cast<ActionResult>(payload[8]),
get(payload, 9, 8), get(payload, 17, 8)};
+37 -1
View File
@@ -182,6 +182,40 @@ void v9_perception_carries_only_valid_owner_diagnostics() {
CHECK(!clear_bytes.empty());
CHECK(std::get<CellularPerception>(*decode_session(clear_bytes)) == cleared);
}
void v10_mutation_choice_is_a_strict_reliable_action() {
const CellularMutationAction action{17, 23, 29, 53, 37, 41, 43, 47};
const auto bytes = encode_session(SessionMessage{action});
CHECK(!bytes.empty() && bytes.size() == session_header_bytes + 64);
std::uint16_t version{};
const auto decoded = decode_session(bytes, &version);
CHECK(decoded && version == session_protocol_v10);
CHECK(std::get<CellularMutationAction>(*decoded) == action);
CHECK(encode_session(*decoded) == bytes);
CHECK(encode_session(SessionMessage{action}, session_protocol_v9).empty());
auto malformed = bytes;
std::fill(malformed.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 16),
malformed.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 24),
std::uint8_t{0});
CHECK(!decode_session(malformed)); // The action id is the retry identity.
malformed = bytes;
malformed[session_header_bytes + 58] = 1;
CHECK(!decode_session(malformed)); // Reserved bytes stay canonical.
malformed = bytes;
std::fill(malformed.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 48),
malformed.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 56),
std::uint8_t{0xFF});
CHECK(!decode_session(malformed)); // Offer must precede the scheduled tick.
malformed = bytes;
malformed[4] = static_cast<std::uint8_t>(session_protocol_v9);
CHECK(!decode_session(malformed)); // v1-v9 do not know this message.
const ActionOutcome outcome{29, ActionResult::committed, 31, 41};
const auto outcome_bytes = encode_session(SessionMessage{outcome}, session_protocol_v10);
CHECK(!outcome_bytes.empty());
CHECK(std::get<ActionOutcome>(*decode_session(outcome_bytes)) == outcome);
}
} // namespace
int main() {
@@ -191,7 +225,9 @@ int main() {
v7_reliable_action_is_stable_and_strict();
v8_perception_is_bounded_and_canonical();
v9_perception_carries_only_valid_owner_diagnostics();
std::puts("PASS cellular protocol: v6 intention, v7 action, v8/v9 perception framing");
v10_mutation_choice_is_a_strict_reliable_action();
std::puts(
"PASS cellular protocol: v6 intention, v7 action, v8-v10 perception/action framing");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;