diff --git a/docs/adr/0115-cellular-owner-perception-v8.md b/docs/adr/0115-cellular-owner-perception-v8.md new file mode 100644 index 0000000..69dbfa3 --- /dev/null +++ b/docs/adr/0115-cellular-owner-perception-v8.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index ed66a63..75efa49 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 46ce9c3..de024b5 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -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 diff --git a/include/evo/network/session_protocol.hpp b/include/evo/network/session_protocol.hpp index 6cfc42d..d06a29b 100644 --- a/include/evo/network/session_protocol.hpp +++ b/include/evo/network/session_protocol.hpp @@ -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 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 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 encode_session(const SessionMessage& message); [[nodiscard]] std::vector encode_session(const SessionMessage& message, diff --git a/schemas/network/session-v8-cellular-perception.md b/schemas/network/session-v8-cellular-perception.md new file mode 100644 index 0000000..b390ed3 --- /dev/null +++ b/schemas/network/session-v8-cellular-perception.md @@ -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. diff --git a/src/network/protocol/session_protocol.cpp b/src/network/protocol/session_protocol.cpp index 35439c2..2673e16 100644 --- a/src/network/protocol/session_protocol.cpp +++ b/src/network/protocol/session_protocol.cpp @@ -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 encode_session(const SessionMessage& message) { std::holds_alternative(message) || std::holds_alternative(message) || std::holds_alternative(message); - const auto version = std::holds_alternative(message) ? session_protocol_v7 + const auto version = std::holds_alternative(message) ? session_protocol_v8 + : std::holds_alternative(message) ? session_protocol_v7 : std::holds_alternative(message) ? session_protocol_v6 : is_life ? session_protocol_v5 : session_protocol_version; return encode_session(message, version); @@ -112,7 +115,8 @@ std::vector encode_session(const SessionMessage& message) { std::vector 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(message) || @@ -122,11 +126,27 @@ std::vector encode_session(const SessionMessage& message, std::uin return {}; if (version != session_protocol_v6 && std::holds_alternative(message)) return {}; - if (version != session_protocol_v7 && std::holds_alternative(message)) + if (version != session_protocol_v7 && version != session_protocol_v8 && + std::holds_alternative(message)) return {}; - if (version != session_protocol_v7 && std::holds_alternative(message) && + if (version != session_protocol_v7 && version != session_protocol_v8 && + std::holds_alternative(message) && std::get(message).result == ActionResult::committed) return {}; + if (version != session_protocol_v8 && std::holds_alternative(message)) + return {}; + if (const auto* perception = std::get_if(&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 operator()(const SessionHello& m) const { @@ -191,6 +211,23 @@ std::vector encode_session(const SessionMessage& message, std::uin put(out, m.intake_y_um, 4); return out; } + std::vector 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 operator()(const IntentionReceipt& m) const { auto out = header(SessionMessageType::intention_receipt, intention_receipt_bytes, version); @@ -322,7 +359,8 @@ std::expected decode_session(std::span(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 decode_session(std::span(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 decode_session(std::span(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(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(get(payload, offset, 4)); + patch.y_um = static_cast(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(SessionMessageType::intention_receipt): { if (!expect(intention_receipt_bytes)) return std::unexpected(SessionCodecError::wrong_length); @@ -464,7 +535,7 @@ std::expected decode_session(std::span(ActionResult::committed_no_effect) || payload[8] > static_cast(ActionResult::committed) || (payload[8] == static_cast(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(payload[8]), get(payload, 9, 8), get(payload, 17, 8)}; diff --git a/tests/cellular_intent_protocol_tests.cpp b/tests/cellular_intent_protocol_tests.cpp index 0dada0a..75d11d6 100644 --- a/tests/cellular_intent_protocol_tests.cpp +++ b/tests/cellular_intent_protocol_tests.cpp @@ -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(*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(*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;