Add owner-filtered cellular perception protocol
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (checks) (push) Failing after 39s
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 (ecs) (push) Canceled after 1m48s
Foundation / checks (network) (push) Canceled after 1m18s
Foundation / checks (client) (push) Canceled after 1m58s

This commit is contained in:
dingo
2026-10-11 01:06:05 -04:00
parent 10b042309e
commit 5419a579e8
7 changed files with 209 additions and 10 deletions
@@ -0,0 +1,52 @@
# ADR-0115: Owner-filtered cellular perception protocol v8
## Status
Accepted M11.3e engineering direction under the maintainer's standing
authorization to proceed with recommendations and revisit decisions after
implementation. It adds no biological or gameplay rule; it carries the exact
view already specified by ADR-0103.
## Context
The profile-4 owner can derive a canonical list of nearby patch addresses and
stocks for one life. The current cellular session replicates organism snapshots
to every session with spatial interest, so it cannot carry that private list
without leaking one player's sensor view to another. No existing client session
negotiates a cellular-aware protocol that receives this view.
## Decision
- Add protocol v8 while keeping v1-v7 byte layouts and admission behavior
unchanged. V8 retains the reliable cellular action and final-outcome behavior
of v7, and adds one bounded server-to-client `CellularPerception` stream
message.
- The server derives the view from the authenticated account's current live
life and the existing ADR-0103 perception function. It routes the result only
to that account's current v8 session. The message omits account identity and
patch provenance; it contains the simulation tick, life identity, and the
canonical address-ordered list of exact visible patch inventories.
- A zero life identity with an empty patch list clears the client's previous
view. Nonzero life identity and tick are required for an active view. Duplicate
or out-of-order addresses, more than 256 patches, invalid lengths, and v8-only
messages on earlier versions are refused.
- This message communicates the existing sensor result; it does not let the
client set position, range, intake or authoritative inventory. Movement and
feeding remain reliable v8 actions resolved by the server.
## Alternatives considered
- **Include food in shared spatial snapshots:** rejected because session interest
is not the same as the controlled life, and one player's sensor range must not
disclose stock to another account.
- **Add perception to v7:** rejected because its frozen behavior is already
deployed and adding a new required view could break existing v7 clients.
- **Send the full microhabitat:** rejected by ADR-0103; it reveals unseen stock.
## Consequences
V8 clients receive bounded exact local resource information on the reliable
stream. The server must resolve the owner-life binding for each send and tests
must prove that another account cannot receive the message. Until client input
and presentation are wired, v8 alone does not make the cellular stage
playable.
+1
View File
@@ -15,6 +15,7 @@
- [ADR-0112: Durable cellular action input records](0112-cellular-action-ledger-records.md) - specifies canonical retry bytes, persisted result identity and the isolated profile-4 publisher needed before v7 admission.
- [ADR-0113: Cellular replay trace](0113-cellular-replay-trace.md) - specifies bounded per-tick life intentions for deterministic profile-4 replay and durable action reconciliation.
- [ADR-0114: First player life in cellular profile 4](0114-cellular-first-life-publication.md) - accepted M11.3 engineering direction: preserve empty genesis and add an allocator-backed, durable profile-4 birth operation so the 11.3e probe can start through the normal player path.
- [ADR-0115: Owner-filtered cellular perception protocol v8](0115-cellular-owner-perception-v8.md) - carries the existing exact sensor view only to its authenticated owner without changing v1-v7 behavior.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+5
View File
@@ -353,6 +353,11 @@ scoped change before starting the next segment.
with the Linux/PostgreSQL CMake preset or run against a region. Exact patch
perception and the engineering-client controls/view are still required for
the exploratory 11.3e playtest.
- 11.3e-1: ADR-0115 defines a frozen v8 stream message for the existing
owner-filtered ADR-0103 patch view. The codec accepts a bounded canonical
address-ordered inventory list and keeps v1-v7 layouts unchanged. The server
still needs to route each view to its authenticated owner; the client needs
cellular input and presentation before the hands-on probe.
## Exit boundary
+21 -2
View File
@@ -27,6 +27,9 @@ 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;
// v8 adds the authenticated owner's exact, bounded cellular perception view.
inline constexpr std::uint16_t session_protocol_v8 = 8;
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.
inline constexpr std::size_t session_header_bytes = 8;
@@ -55,7 +58,8 @@ enum class SessionMessageType : std::uint8_t {
primitive_life_outcome,
primitive_life_query,
cellular_intention = 22,
cellular_action = 23
cellular_action = 23,
cellular_perception = 24
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
@@ -171,6 +175,20 @@ struct CellularAction {
std::uint32_t intake_x_um{}, intake_y_um{};
friend bool operator==(const CellularAction&, const CellularAction&) = 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 {
std::uint32_t x_um{}, y_um{};
std::uint64_t energy_pj{};
std::array<std::uint64_t, 4> matter_fg{};
friend bool operator==(const CellularPerceivedPatch&, const CellularPerceivedPatch&) =
default;
};
struct CellularPerception {
std::uint64_t tick{}, life_identity{}; // zero life plus no patches clears the view.
std::vector<CellularPerceivedPatch> patches; // strictly ordered by (x_um, y_um).
friend bool operator==(const CellularPerception&, const CellularPerception&) = default;
};
struct IntentionReceipt {
std::uint64_t sequence{};
AdmitStatus status{};
@@ -286,7 +304,8 @@ using SessionMessage =
SessionIntention, CellularIntention, CellularAction, IntentionReceipt, SimulatedThrough,
SessionAction, ActionReceipt, ActionOutcome, ActionQuery, SessionInterest,
SnapshotChunk, SnapshotAck, HandoffOffer, SessionRedirect, PrimitiveLifeRequest,
PrimitiveLifeReceipt, PrimitiveLifeOutcome, PrimitiveLifeQuery>;
PrimitiveLifeReceipt, PrimitiveLifeOutcome, PrimitiveLifeQuery,
CellularPerception>;
[[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,24 @@
# Session protocol v8 cellular perception
V8 preserves the v7 reliable cellular action and final outcome contract. It adds
message type 24, `CellularPerception`, server to client on the reliable stream.
Types and layouts from v1-v7 remain unchanged. The new view follows ADR-0103 and
ADR-0115; it contains no account ID or patch provenance.
## Message 24
The 8-byte standard `EVSN` header uses version 8, type 24 and flags 0. The payload
begins with `tick u64`, `life_identity u64`, and `patch_count u16`, followed by
`patch_count` records. Tick is nonzero. An active view has a nonzero life identity;
identity zero is reserved for an empty view and requires zero patches.
Each 48-byte record contains `x_um u32`, `y_um u32`, `energy_pj u64`, then four
`matter_fg u64` values in carbon, nitrogen, phosphorus, other order. Records are
strictly ordered by `(x_um, y_um)` with no duplicate address. At most 256 records
are allowed. The total message is at most 12,314 bytes including the header.
The server sends the view only to the authenticated account's current v8 session,
using that account's currently bound living cell and the server's ADR-0103 sensor
query. An empty active list means the cell currently perceives no provisioned
patches; a zero identity clears the previous owner view. The client cannot submit
or enlarge this view. Versions below 8 reject type 24.
+78 -7
View File
@@ -13,6 +13,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 cellular_perception_prefix_bytes = 8 + 8 + 2;
constexpr std::size_t cellular_perceived_patch_bytes = 8 + 8 + (4 * 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;
@@ -104,7 +106,8 @@ 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<CellularAction>(message) ? session_protocol_v7
const auto version = std::holds_alternative<CellularPerception>(message) ? 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;
return encode_session(message, version);
@@ -112,7 +115,8 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
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_v6 && version != session_protocol_v7 &&
version != session_protocol_v8)
return {};
if (version == session_protocol_version &&
(std::holds_alternative<PrimitiveLifeRequest>(message) ||
@@ -122,11 +126,27 @@ 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))
if (version != session_protocol_v7 && version != session_protocol_v8 &&
std::holds_alternative<CellularAction>(message))
return {};
if (version != session_protocol_v7 && std::holds_alternative<ActionOutcome>(message) &&
if (version != session_protocol_v7 && version != session_protocol_v8 &&
std::holds_alternative<ActionOutcome>(message) &&
std::get<ActionOutcome>(message).result == ActionResult::committed)
return {};
if (version != session_protocol_v8 && 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()) ||
!std::ranges::is_sorted(perception->patches, [](const auto& a, const auto& b) {
return std::pair{a.x_um, a.y_um} < std::pair{b.x_um, b.y_um};
}) ||
std::adjacent_find(perception->patches.begin(), perception->patches.end(),
[](const auto& a, const auto& b) {
return a.x_um == b.x_um && a.y_um == b.y_um;
}) != perception->patches.end())
return {};
}
struct Encoder {
std::uint16_t version;
std::vector<std::uint8_t> operator()(const SessionHello& m) const {
@@ -191,6 +211,23 @@ 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 CellularPerception& m) const {
auto out = header(SessionMessageType::cellular_perception,
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);
for (const auto& patch : m.patches) {
put(out, patch.x_um, 4);
put(out, patch.y_um, 4);
put(out, patch.energy_pj, 8);
for (const auto matter : patch.matter_fg)
put(out, matter, 8);
}
return out;
}
std::vector<std::uint8_t> operator()(const IntentionReceipt& m) const {
auto out =
header(SessionMessageType::intention_receipt, intention_receipt_bytes, version);
@@ -322,7 +359,8 @@ 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_v7)
wire_version != session_protocol_v6 && wire_version != session_protocol_v7 &&
wire_version != session_protocol_v8)
return std::unexpected(SessionCodecError::unsupported_version);
if (version)
*version = wire_version;
@@ -405,7 +443,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::cellular_action): {
if (wire_version != session_protocol_v7)
if (wire_version != session_protocol_v7 && wire_version != session_protocol_v8)
return std::unexpected(SessionCodecError::unsupported_version);
if (!expect(cellular_action_bytes))
return std::unexpected(SessionCodecError::wrong_length);
@@ -426,6 +464,39 @@ 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)
return std::unexpected(SessionCodecError::unsupported_version);
if (payload.size() < cellular_perception_prefix_bytes)
return std::unexpected(SessionCodecError::wrong_length);
const auto count = static_cast<std::size_t>(get(payload, 16, 2));
if (count > max_cellular_perceived_patches ||
payload.size() != cellular_perception_prefix_bytes +
count * cellular_perceived_patch_bytes)
return std::unexpected(SessionCodecError::wrong_length);
CellularPerception m;
m.tick = get(payload, 0, 8);
m.life_identity = get(payload, 8, 8);
if (!m.tick || (!m.life_identity && count))
return std::unexpected(SessionCodecError::invalid_value);
m.patches.reserve(count);
std::size_t offset = cellular_perception_prefix_bytes;
for (std::size_t i = 0; i < count; ++i) {
CellularPerceivedPatch patch;
patch.x_um = static_cast<std::uint32_t>(get(payload, offset, 4));
patch.y_um = static_cast<std::uint32_t>(get(payload, offset + 4, 4));
patch.energy_pj = get(payload, offset + 8, 8);
for (std::size_t channel = 0; channel < patch.matter_fg.size(); ++channel)
patch.matter_fg[channel] = get(payload, offset + 16 + channel * 8, 8);
if (!m.patches.empty() &&
!(std::pair{m.patches.back().x_um, m.patches.back().y_um} <
std::pair{patch.x_um, patch.y_um}))
return std::unexpected(SessionCodecError::invalid_value);
m.patches.push_back(patch);
offset += cellular_perceived_patch_bytes;
}
return m;
}
case static_cast<std::uint8_t>(SessionMessageType::intention_receipt): {
if (!expect(intention_receipt_bytes))
return std::unexpected(SessionCodecError::wrong_length);
@@ -464,7 +535,7 @@ std::expected<SessionMessage, SessionCodecError> decode_session(std::span<const
if (payload[8] < static_cast<std::uint8_t>(ActionResult::committed_no_effect) ||
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_v7 && wire_version != session_protocol_v8))
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)};
+28 -1
View File
@@ -115,6 +115,32 @@ void v7_reliable_action_is_stable_and_strict() {
std::fill(malformed_input.begin(), malformed_input.begin() + 8, std::uint8_t{0});
CHECK(!decode_cellular_action_input(malformed_input));
}
void v8_perception_is_bounded_and_canonical() {
const CellularPerception perception{
19, 42, {{1'000, 2'000, 3, {4, 5, 6, 7}}, {1'000, 3'000, 8, {9, 10, 11, 12}}}};
const auto bytes = encode_session(SessionMessage{perception});
CHECK(!bytes.empty() && bytes.size() == session_header_bytes + 18 + 2 * 48);
std::uint16_t version{};
const auto decoded = decode_session(bytes, &version);
CHECK(decoded && version == session_protocol_v8);
CHECK(std::get<CellularPerception>(*decoded) == perception);
CHECK(encode_session(*decoded) == bytes);
CHECK(encode_session(SessionMessage{perception}, session_protocol_v7).empty());
CHECK(!decode_session(std::span{bytes}.first(bytes.size() - 1)));
auto reversed = perception;
std::ranges::reverse(reversed.patches);
CHECK(encode_session(SessionMessage{reversed}).empty());
auto duplicate = perception;
duplicate.patches[1] = duplicate.patches[0];
CHECK(encode_session(SessionMessage{duplicate}).empty());
CHECK(encode_session(SessionMessage{CellularPerception{19, 0, {perception.patches[0]}}})
.empty());
const CellularPerception cleared{19, 0, {}};
const auto clear_bytes = encode_session(SessionMessage{cleared});
CHECK(std::get<CellularPerception>(*decode_session(clear_bytes)) == cleared);
}
} // namespace
int main() {
@@ -122,7 +148,8 @@ int main() {
round_trip_and_version_gate();
malformed_frames_are_refused();
v7_reliable_action_is_stable_and_strict();
std::puts("PASS cellular protocol: v6 intention and v7 action strict framing");
v8_perception_is_bounded_and_canonical();
std::puts("PASS cellular protocol: v6 intention, v7 action, v8 perception framing");
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;