Define cellular intention session protocol v6
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m54s
Foundation / checks (client) (push) Failing after 4m23s
Foundation / checks (network) (push) Failing after 3m5s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 11s
Foundation / checks (postgres) (push) Canceled after 57s
Foundation / checks (checks) (push) Canceled after 5m23s

This commit is contained in:
dingo
2026-10-10 21:29:59 -04:00
parent 1ccc0ce476
commit ae0a3cdae5
10 changed files with 245 additions and 11 deletions
+5
View File
@@ -65,6 +65,11 @@ add_executable(evo-dev-session apps/evo-dev-session/main.cpp)
target_link_libraries(evo-dev-session PRIVATE evo_network_session)
evo_owned_target(evo-dev-session)
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_executable(evo-network-tests tests/network_protocol.cpp tests/network_tls.cpp
tests/network_session.cpp tests/network_control.cpp tests/network_replication.cpp
tests/network_motion.cpp tests/network_interpolation.cpp tests/network_main.cpp)
@@ -0,0 +1,45 @@
# ADR-0105: Cellular session intention protocol v6
## Status
Accepted wire-contract direction for M11.3 (2026-10-10). The codec is being
implemented first; server admission and durable resolution remain separate gates.
## Context
The deployed session wire versions 1–4 are frozen, and v5 adds only reliable
primitive-life creation/query messages. In primitive v5 mode the current server
rejects movement datagrams, probe actions and M10 interest. M11.3 needs a client
to request bounded movement and choose one nearby food patch without claiming
position, speed, energy or inventory.
## Decision
- Add session protocol v6 while preserving the exact v1–v5 encodings. V6 retains
the existing session, control epoch, movement vector, sequence and scheduled
tick fields, and adds an optional target patch address in micrometres.
- The v6 `CellularIntention` is a fixed 48-byte little-endian datagram payload.
The strict layout and canonical absent-target form are in
[session-v6-cellular-intention](../../schemas/network/session-v6-cellular-intention.md).
- The target is an intention only. The server checks authenticated session and
epoch, tick and sequence window, movement norm, patch alignment and visibility;
it resolves position and contact, then derives any costs or acquired stock.
- A cellular client must negotiate v6 explicitly. The current session server
remains unchanged until it has a cellular handler; the codec alone does not
authorize gameplay.
## Alternatives considered
- **Reuse the M10 marker intention:** rejected because its simulation path moves
a non-biological probe at a fixed speed and has no energy, habitat or life.
- **Send a position or inventory delta:** rejected because it would let the
client claim authoritative state.
- **Change v5 in place:** rejected because v5 life creation is an existing
versioned contract and must retain its exact bytes and primitive-only scope.
## Consequences
V6 provides a bounded, explicit wire value for the next server integration. It
does not implement admission, durable tick publication, a life view, client UI
or cross-region owner routing; M11.3 remains incomplete until those pieces work
end to end.
+1
View File
@@ -5,6 +5,7 @@
- [ADR-0102: Bounded cellular space and locomotion trial](0102-cellular-spatial-trial.md) - accepted M11.3 trial direction for finite 2D region bounds, phenotype-limited movement and organism contact; tunable arena dimensions are not world geometry.
- [ADR-0103: Cellular resource perception trial](0103-cellular-perception-trial.md) - accepted M11.3 exploratory direction for a 5 mm footprint-based sensor range and exact nearby patch stock; provenance and out-of-range stock remain hidden.
- [ADR-0104: Cellular single-life tick order trial](0104-cellular-single-life-tick-order.md) - accepted M11.3 order for maintenance, funded movement and one contact-gated intake proposal; shared-stock contention and durable publication remain open.
- [ADR-0105: Cellular session intention protocol v6](0105-cellular-session-intention-v6.md) - accepted M11.3 wire direction for movement plus an optional food-patch target; v1-v5 remain frozen and v6 server admission is still to be implemented.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+5 -2
View File
@@ -106,8 +106,8 @@ scoped change before starting the next segment.
- 11.3a contract direction: ADR-0101 selects finite 1 mm cellular food patches;
ADR-0102 defines bounded non-wrapping movement and footprint contact. The
complete living-set checkpoint, perception contract and server profile remain
open.
complete living-set checkpoint and server profile remain open; ADR-0103 now
defines the perception trial contract.
- 11.3b-1: pure phenotype-derived movement proposal and square-footprint contact
helper are implemented and locally tested. Session inputs, server state,
replication and durable movement publication remain open.
@@ -127,6 +127,9 @@ scoped change before starting the next segment.
affordable movement and one targeted contact intake into a detached candidate.
Shared-stock contention, starvation/death closure, owner commit and checkpoint
recovery remain open; this helper is not yet a multi-life tick.
- 11.3b-3: ADR-0105 and the v6 codec define cellular intention bytes for movement
and an optional food-patch target. Server admission, durable simulation and
client presentation are still open.
## Exit boundary
+18
View File
@@ -5931,3 +5931,21 @@ Executed locally: warning-as-error MSVC Debug and Release `NDEBUG` compile/run,
focused cellular CTest, clang-format 19.1.5, clang-tidy 19.1.5 with MSVC
`/std:c++latest`, and `git diff --check`. CI and integration with durable
intent/outcome publication remain pending.
## 2026-10-10 — M11.3b-3 cellular intention v6 codec (CI pending)
ADR-0105 and `schemas/network/session-v6-cellular-intention.md` define a strict
fixed-size datagram carrying only session/epoch, sequence/tick, movement intent
and an optional intake patch address. V1-v5 encodings remain unchanged. Decode
rejects noncanonical absent targets and reserved bytes. The codec intentionally
does not admit this message in `RegionSessions`; that server path is not yet
implemented.
Executed locally: warning-as-error MSVC 19.44 Release compile/run, CTest
`cellular-intention-protocol-v6` (1/1 passed), compile-only MSVC check for the
existing `network_control.cpp` regression case, clang-format 19.1.5 on changed
ranges, clang-tidy 19.1.5 with MSVC `/std:c++latest`, and `git diff --check`.
The CMake/Ninja build of `evo-network-tests` remained idle for about 90 seconds
(cmake 0.02 CPU seconds, ninja 0.09, no `cl`/`link` child), so I interrupted it;
the full M10 network suite and server admission/QUIC integration remain pending.
Linux network CI has not yet qualified this version.
+16 -5
View File
@@ -24,6 +24,7 @@ inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN".
// are frozen; v4 remains the default. v5 adds reliable primitive-life operations.
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;
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;
@@ -50,7 +51,8 @@ enum class SessionMessageType : std::uint8_t {
primitive_life_request = 18,
primitive_life_receipt,
primitive_life_outcome,
primitive_life_query
primitive_life_query,
cellular_intention = 22
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
@@ -136,6 +138,15 @@ struct SessionIntention {
std::int16_t move_x{}, move_y{};
friend bool operator==(const SessionIntention&, const SessionIntention&) = default;
};
// v6 biological input only: movement intent plus an optional address of a patch
// the client wants to feed from. The server checks range, contact and costs.
struct CellularIntention {
std::uint64_t session{}, epoch{}, sequence{}, 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 CellularIntention&, const CellularIntention&) = default;
};
struct IntentionReceipt {
std::uint64_t sequence{};
AdmitStatus status{};
@@ -248,10 +259,10 @@ struct SessionRedirect {
};
using SessionMessage =
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
SessionIntention, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck,
HandoffOffer, SessionRedirect, PrimitiveLifeRequest, PrimitiveLifeReceipt,
PrimitiveLifeOutcome, PrimitiveLifeQuery>;
SessionIntention, CellularIntention, IntentionReceipt, SimulatedThrough,
SessionAction, ActionReceipt, ActionOutcome, ActionQuery, SessionInterest,
SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect, PrimitiveLifeRequest,
PrimitiveLifeReceipt, PrimitiveLifeOutcome, PrimitiveLifeQuery>;
[[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,30 @@
# Session protocol v6 cellular intention datagram
ADR-0105 defines this message. It is not admitted by the currently integrated
region session server until its v6 cellular-life handler is enabled.
Each frame starts with the existing 8-byte `EVSN` header. The version is 6, the
type is 22 (`cellular_intention`), and header flags are zero. Payload length is
exactly 48 bytes; all integers are little-endian.
| Payload offset | Size | Field |
|---:|---:|---|
| 0 | 8 | authenticated session id (nonzero; admission checks connection match) |
| 8 | 8 | control epoch (nonzero; admission checks current authority) |
| 16 | 8 | per-session intention sequence (nonzero and increasing) |
| 24 | 8 | intended simulation tick (admission checks the future window) |
| 32 | 2 | signed movement X component; server validates the norm and bounds |
| 34 | 2 | signed movement Y component; server validates the norm and bounds |
| 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. When set, the
coordinates identify a requested patch, not a position, speed or stock claim.
The authoritative host validates patch alignment, perception at the applicable
tick and footprint contact before intake. No target means no requested intake.
Movement remains an intention only; the server derives position, costs and
resource balances. Truncated frames, trailing bytes, nonzero reserved bytes,
invalid flags, noncanonical absent-target coordinates and versions below 6 are
refused by the codec.
+45 -3
View File
@@ -11,6 +11,7 @@ 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 cellular_intention_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;
@@ -102,11 +103,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);
return encode_session(message, is_life ? session_protocol_v5 : session_protocol_version);
const auto version = 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)
if (version != session_protocol_version && version != session_protocol_v5 &&
version != session_protocol_v6)
return {};
if (version == session_protocol_version &&
(std::holds_alternative<PrimitiveLifeRequest>(message) ||
@@ -114,6 +119,8 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
std::holds_alternative<PrimitiveLifeOutcome>(message) ||
std::holds_alternative<PrimitiveLifeQuery>(message)))
return {};
if (version != session_protocol_v6 && std::holds_alternative<CellularIntention>(message))
return {};
struct Encoder {
std::uint16_t version;
std::vector<std::uint8_t> operator()(const SessionHello& m) const {
@@ -153,6 +160,19 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message, std::uin
put(out, static_cast<std::uint16_t>(m.move_y), 2);
return out;
}
std::vector<std::uint8_t> operator()(const CellularIntention& m) const {
auto out =
header(SessionMessageType::cellular_intention, cellular_intention_bytes, version);
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);
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);
@@ -283,7 +303,8 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
if (get(bytes, 0, 4) != session_magic)
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)
if (wire_version != session_protocol_version && wire_version != session_protocol_v5 &&
wire_version != session_protocol_v6)
return std::unexpected(SessionCodecError::unsupported_version);
if (version)
*version = wire_version;
@@ -344,6 +365,27 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
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::cellular_intention): {
if (wire_version < session_protocol_v6)
return std::unexpected(SessionCodecError::unsupported_version);
if (!expect(cellular_intention_bytes))
return std::unexpected(SessionCodecError::wrong_length);
CellularIntention 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)));
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.has_intake_target && (m.intake_x_um != 0 || m.intake_y_um != 0))
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);
+79
View File
@@ -0,0 +1,79 @@
#include "evo/network/session_protocol.hpp"
#include <cstdio>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
using namespace evo::network;
void check(bool value, std::source_location at = std::source_location::current()) {
if (!value)
throw std::runtime_error("cellular intent protocol line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
void round_trip_and_version_gate() {
const CellularIntention targeted{17, 23, 29, 31, -707, 707, true, 4'000, 5'000};
const SessionMessage message{targeted};
const auto bytes = encode_session(message);
CHECK(!bytes.empty() && bytes.size() == session_header_bytes + 48);
std::uint16_t version{};
const auto decoded = decode_session(bytes, &version);
CHECK(decoded && version == session_protocol_v6);
CHECK(std::get<CellularIntention>(*decoded) == targeted);
CHECK(encode_session(*decoded) == bytes);
CHECK(encode_session(message, session_protocol_v5).empty());
const CellularIntention no_target{1, 2, 3, 4, 0, -1, false, 0, 0};
const auto no_target_bytes = encode_session(SessionMessage{no_target});
CHECK(std::get<CellularIntention>(*decode_session(no_target_bytes)) == no_target);
}
void malformed_frames_are_refused() {
const auto bytes =
encode_session(SessionMessage{CellularIntention{1, 2, 3, 4, 0, 0, true, 1'000, 2'000}});
for (std::size_t size = 0; size < bytes.size(); ++size) {
const auto truncated = decode_session(std::span{bytes}.first(size));
CHECK(!truncated);
CHECK(truncated.error() == (size < session_header_bytes ? SessionCodecError::truncated
: SessionCodecError::wrong_length));
}
auto bad = bytes;
bad.at(6) = 255; // Unknown message type.
const auto wrong_type = decode_session(bad);
CHECK(!wrong_type && wrong_type.error() == SessionCodecError::unknown_type);
bad = bytes;
bad.at(session_header_bytes + 36) = 2;
const auto bad_flag = decode_session(bad);
CHECK(!bad_flag && bad_flag.error() == SessionCodecError::invalid_value);
bad = bytes;
bad.at(session_header_bytes + 38) = 1;
const auto bad_reserved = decode_session(bad);
CHECK(!bad_reserved && bad_reserved.error() == SessionCodecError::invalid_value);
bad = encode_session(SessionMessage{CellularIntention{1, 2, 3, 4, 0, 0, false, 0, 0}});
bad.at(session_header_bytes + 40) = 1; // Coordinates must be zero when target is absent.
const auto noncanonical = decode_session(bad);
CHECK(!noncanonical && noncanonical.error() == SessionCodecError::invalid_value);
bad = bytes;
bad.at(4) = static_cast<std::uint8_t>(session_protocol_v5);
const auto old_version = decode_session(bad);
CHECK(!old_version && old_version.error() == SessionCodecError::unsupported_version);
CHECK(encode_session(SessionMessage{CellularIntention{1, 2, 3, 4}}, 7).empty());
}
} // 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");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
}
+1 -1
View File
@@ -371,7 +371,7 @@ void session_codec() {
mutated.at(0) ^= 1;
CHECK(refused(decode_session(mutated), SessionCodecError::bad_magic));
mutated = bytes;
mutated.at(4) = 6; // A future version.
mutated.at(4) = 7; // A future version.
CHECK(refused(decode_session(mutated), SessionCodecError::unsupported_version));
mutated = bytes;
mutated.at(7) = 1;