Add durable cellular action protocol v7
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (checks) (push) Failing after 40s
Foundation / checks (postgres) (push) Canceled after 0s
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 1m16s
Foundation / checks (ecs) (push) Canceled after 1m8s
Foundation / checks (network) (push) Canceled after 37s

This commit is contained in:
dingo
2026-10-10 22:57:03 -04:00
parent d0c7a938f1
commit d1717410d6
7 changed files with 163 additions and 18 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-intention-protocol-v6 COMMAND evo-cellular-intent-protocol-tests)
set_tests_properties(cellular-intention-protocol-v6 PROPERTIES TIMEOUT 30 LABELS "network")
add_test(NAME cellular-session-protocol-v6-v7 COMMAND evo-cellular-intent-protocol-tests)
set_tests_properties(cellular-session-protocol-v6-v7 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)
+6 -2
View File
@@ -175,8 +175,12 @@ scoped change before starting the next segment.
and only provisional receipts, so they cannot satisfy ADR-0108's exact retry
requirement after reconnect. ADR-0111 keeps v6 frozen and specifies a reliable
v7 action with stable account/action identity and commit-bound input/result
bytes. Durable host work is paused at this contract boundary until the v7
codec and store records are implemented.
bytes. The codec is now implemented; durable input records, recovery and
atomic publication remain required before the host may consume it.
- 11.3d-5a: protocol v7 now defines a reliable 48-byte cellular action carrying
stable per-account action identity, plus a distinct committed-cellular result.
The strict codec and round-trip/refusal tests are implemented; admission,
durable input records and atomic tick publication remain open.
## Exit boundary
+19
View File
@@ -6108,3 +6108,22 @@ records the resolution: preserve v6 unchanged and use a reliable v7 cellular
action whose canonical input and final result commit with the cellular
checkpoint. No implementation or tests were run for this documentation-only
contract; durable host coding follows it.
## 2026-10-10 — M11.3d-5a reliable v7 cellular action codec (CI pending)
Added the v7 reliable-stream `CellularAction` wire value with stable nonzero
account/action identity, intended tick, signed movement fields and optional
patch target. Admission owns movement bounds. Added `ActionResult::committed`
for cellular actions and kept it
v7-only; v6 cellular intentions and their bytes remain unchanged. The schema
defines the exact 48-byte layout and identifies server-side checks still owned
by admission and durable publication.
Executed locally: warning-as-error MSVC 19.44 direct compile and run of
`tests/cellular_intent_protocol_tests.cpp` with the protocol codec (v6 and v7
round trips, version gates, zero identity, reserved bytes and absent-target
canonicality passed), plus `git diff --check`. The CMake/Ninja target regenerated
successfully but idled without starting compilation; direct compilation was
used. `clang-format` and `clang-tidy` are unavailable on this Windows PATH. CI,
server admission, action ledger input bytes, durable publication and restart
recovery remain pending.
+17 -4
View File
@@ -25,6 +25,8 @@ inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN".
inline constexpr std::uint16_t session_protocol_version = 4;
inline constexpr std::uint16_t session_protocol_v5 = 5;
inline constexpr std::uint16_t session_protocol_v6 = 6;
// v7 adds stable-id reliable cellular actions; v1-v6 wire layouts stay frozen.
inline constexpr std::uint16_t session_protocol_v7 = 7;
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;
@@ -52,7 +54,8 @@ enum class SessionMessageType : std::uint8_t {
primitive_life_receipt,
primitive_life_outcome,
primitive_life_query,
cellular_intention = 22
cellular_intention = 22,
cellular_action = 23
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
@@ -76,7 +79,8 @@ 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.
unknown, // Query answer only: no record of this action id.
committed // Cellular action committed; inspect the authoritative view (v7).
};
// Wire values 1..13. `connection_lost` is local only (the transport ended without a Close).
enum class SessionCloseReason : std::uint8_t {
@@ -147,6 +151,15 @@ struct CellularIntention {
std::uint32_t intake_x_um{}, intake_y_um{};
friend bool operator==(const CellularIntention&, const CellularIntention&) = default;
};
// v7 reliable input: stable account-scoped action id makes retries safe across reconnects.
// The server resolves the optional intake address and all biological effects.
struct CellularAction {
std::uint64_t session{}, epoch{}, action_id{}, tick{};
std::int16_t move_x{}, move_y{};
bool has_intake_target{};
std::uint32_t intake_x_um{}, intake_y_um{};
friend bool operator==(const CellularAction&, const CellularAction&) = default;
};
struct IntentionReceipt {
std::uint64_t sequence{};
AdmitStatus status{};
@@ -175,7 +188,7 @@ struct ActionReceipt {
struct ActionOutcome {
std::uint64_t action_id{};
ActionResult result{};
std::uint64_t tick{}, commit_sequence{}; // Zero unless committed_no_effect.
std::uint64_t tick{}, commit_sequence{}; // Zero unless a committed result is returned.
friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default;
};
struct ActionQuery {
@@ -259,7 +272,7 @@ struct SessionRedirect {
};
using SessionMessage =
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
SessionIntention, CellularIntention, IntentionReceipt, SimulatedThrough,
SessionIntention, CellularIntention, CellularAction, IntentionReceipt, SimulatedThrough,
SessionAction, ActionReceipt, ActionOutcome, ActionQuery, SessionInterest,
SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect, PrimitiveLifeRequest,
PrimitiveLifeReceipt, PrimitiveLifeOutcome, PrimitiveLifeQuery>;
@@ -0,0 +1,33 @@
# Session protocol v7 cellular action
ADR-0111 defines this reliable-stream input. It uses session message type 23 and
an exactly 48-byte little-endian payload under the existing 8-byte `EVSN`
header. The version is 7 and flags are zero. Versions 1–6 retain their wire
layouts and behavior.
| 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 | 2 | signed movement X component |
| 34 | 2 | signed movement Y component |
| 36 | 1 | intake target present: 0 or 1 |
| 37 | 3 | reserved, all zero |
| 40 | 4 | target patch lower-left X in μm |
| 44 | 4 | target patch lower-left Y in μm |
When the target flag is zero, both coordinates must be zero. The codec rejects
zero identity fields, invalid flags, nonzero reserved bytes, noncanonical
absent-target coordinates, truncated/trailing payloads and versions other than
7. Movement bounds, patch alignment, timing, session authority and biological
effects are checked by admission and the authoritative cellular host.
The action id is durable account-scoped identity, not a connection sequence.
Clients retry the same id only with byte-identical canonical input. A receipt
means admission only. `ActionOutcome::committed` (wire value 5) means the action
and its cellular state committed together; the client reads its authoritative
view for the resulting state. This result is accepted only in v7. Exact retry,
ID conflict, query, and commit resolution behavior follows ADR-0111 and the
durable cellular publication contract.
+54 -9
View File
@@ -12,6 +12,7 @@ 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 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 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;
@@ -103,15 +104,15 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
std::holds_alternative<PrimitiveLifeReceipt>(message) ||
std::holds_alternative<PrimitiveLifeOutcome>(message) ||
std::holds_alternative<PrimitiveLifeQuery>(message);
const auto version = std::holds_alternative<CellularIntention>(message) ? session_protocol_v6
: is_life ? session_protocol_v5
: session_protocol_version;
const auto version = std::holds_alternative<CellularAction>(message) ? session_protocol_v7
: 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_v6 && version != session_protocol_v7)
return {};
if (version == session_protocol_version &&
(std::holds_alternative<PrimitiveLifeRequest>(message) ||
@@ -121,6 +122,11 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
return {};
if (version != session_protocol_v6 && std::holds_alternative<CellularIntention>(message))
return {};
if (version != session_protocol_v7 && std::holds_alternative<CellularAction>(message))
return {};
if (version != session_protocol_v7 && std::holds_alternative<ActionOutcome>(message) &&
std::get<ActionOutcome>(message).result == ActionResult::committed)
return {};
struct Encoder {
std::uint16_t version;
std::vector<std::uint8_t> operator()(const SessionHello& m) const {
@@ -173,6 +179,18 @@ 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 CellularAction& m) const {
auto out = header(SessionMessageType::cellular_action, cellular_action_bytes, version);
for (const auto v : {m.session, m.epoch, m.action_id, 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);
out.push_back(m.has_intake_target ? 1 : 0);
put(out, 0, 3);
put(out, m.intake_x_um, 4);
put(out, m.intake_y_um, 4);
return out;
}
std::vector<std::uint8_t> operator()(const IntentionReceipt& m) const {
auto out =
header(SessionMessageType::intention_receipt, intention_receipt_bytes, version);
@@ -304,7 +322,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
return std::unexpected(SessionCodecError::bad_magic);
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_v6 && wire_version != session_protocol_v7)
return std::unexpected(SessionCodecError::unsupported_version);
if (version)
*version = wire_version;
@@ -366,7 +384,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
return m; // Ranges belong to admission, which answers with a status.
}
case static_cast<std::uint8_t>(SessionMessageType::cellular_intention): {
if (wire_version < session_protocol_v6)
if (wire_version != session_protocol_v6)
return std::unexpected(SessionCodecError::unsupported_version);
if (!expect(cellular_intention_bytes))
return std::unexpected(SessionCodecError::wrong_length);
@@ -386,6 +404,28 @@ 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_action): {
if (wire_version != session_protocol_v7)
return std::unexpected(SessionCodecError::unsupported_version);
if (!expect(cellular_action_bytes))
return std::unexpected(SessionCodecError::wrong_length);
CellularAction 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.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)
return std::unexpected(SessionCodecError::invalid_value);
m.has_intake_target = payload[36] != 0;
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 ||
(!m.has_intake_target && (m.intake_x_um || m.intake_y_um)))
return std::unexpected(SessionCodecError::invalid_value);
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::intention_receipt): {
if (!expect(intention_receipt_bytes))
return std::unexpected(SessionCodecError::wrong_length);
@@ -422,10 +462,15 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
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))
payload[8] > static_cast<std::uint8_t>(ActionResult::committed) ||
(payload[8] == static_cast<std::uint8_t>(ActionResult::committed) &&
wire_version != session_protocol_v7))
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)};
const ActionOutcome m{get(payload, 0, 8), static_cast<ActionResult>(payload[8]),
get(payload, 9, 8), get(payload, 17, 8)};
if (m.result == ActionResult::committed && (!m.tick || !m.commit_sequence))
return std::unexpected(SessionCodecError::invalid_value);
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::action_query): {
if (!expect(action_query_bytes))
+32 -1
View File
@@ -1,5 +1,6 @@
#include "evo/network/session_protocol.hpp"
#include <algorithm>
#include <cstdio>
#include <source_location>
#include <stdexcept>
@@ -65,13 +66,43 @@ void malformed_frames_are_refused() {
CHECK(!old_version && old_version.error() == SessionCodecError::unsupported_version);
CHECK(encode_session(SessionMessage{CellularIntention{1, 2, 3, 4}}, 7).empty());
}
void v7_reliable_action_is_stable_and_strict() {
const CellularAction action{17, 23, 29, 31, -707, 707, true, 4'000, 5'000};
const auto bytes = encode_session(SessionMessage{action});
CHECK(bytes.size() == session_header_bytes + 48);
std::uint16_t version{};
const auto decoded = decode_session(bytes, &version);
CHECK(decoded && version == session_protocol_v7);
CHECK(std::get<CellularAction>(*decoded) == action);
CHECK(encode_session(*decoded) == bytes);
CHECK(encode_session(SessionMessage{action}, session_protocol_v6).empty());
const auto outcome = ActionOutcome{29, ActionResult::committed, 31, 41};
const auto outcome_bytes = encode_session(SessionMessage{outcome}, session_protocol_v7);
CHECK(std::get<ActionOutcome>(*decode_session(outcome_bytes)) == outcome);
CHECK(encode_session(SessionMessage{outcome}, session_protocol_v6).empty());
auto bad = bytes;
std::fill(bad.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 16),
bad.begin() + static_cast<std::ptrdiff_t>(session_header_bytes + 24),
std::uint8_t{0});
CHECK(!decode_session(bad)); // Stable action id cannot be zero.
bad = bytes;
bad[session_header_bytes + 37] = 1;
CHECK(!decode_session(bad)); // Reserved bytes are canonical.
bad = encode_session(SessionMessage{CellularAction{1, 2, 3, 4, 0, 0, false, 0, 0}});
bad[session_header_bytes + 44] = 1;
CHECK(!decode_session(bad)); // An absent patch has no coordinates.
}
} // namespace
int main() {
try {
round_trip_and_version_gate();
malformed_frames_are_refused();
std::puts("PASS cellular intention protocol: v6 round trip and strict framing");
v7_reliable_action_is_stable_and_strict();
std::puts("PASS cellular protocol: v6 intention and v7 action strict framing");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;