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