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
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:
+2
-2
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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))
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user