- TLS: replace send() with a bounded queue/flush; an interrupted record is retried with identical arguments and later frames wait behind it, so no queued frame is lost or reordered; close() flushes first. - Carriers: server-issued 'I','N' | 48-bit epoch | 64-bit ordinal ids replace the aliasing low-32-bit packing; client sequences are kept separately for replies; out-of-range epochs are refused, never truncated. - Grants: a durable, fsynced, fail-closed consumed-grant ledger (--session-grant-ledger, /objects/dev-session-grants.v1 in dev) keeps single-use grants consumed across process and pod restarts. - Liveness: protocol v1 (undeployed) gains Heartbeat and the timeout close reason; both sides heartbeat when idle and treat 5 s of silence as dead. - Client sends are bounded and unresolved tracking starts at send time. - ci-client configures with an explicit C compiler. Each finding has a regression test; ADR-0083, the schema, operations doc and VALIDATION record the corrections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.5 KiB
Dev session protocol v1 (wire schema)
Decision: ADR-0082. Implementation:
include/evo/network/protocol.hpp, src/network/protocol/codec.cpp. Carried inside
TLS 1.3 only. All integers are little-endian, fixed width, with no padding or
alignment; i types are two's complement. Encodings are canonical: a decoded
message re-encodes to identical bytes (fuzz-tested).
Frame
| Offset | Field | Type | Rule |
|---|---|---|---|
| 0 | magic | u32 | 0x53445645 (bytes E V D S) |
| 4 | version | u16 | exactly 1, otherwise unsupported_version |
| 6 | type | u8 | 1..9, otherwise unknown_type |
| 7 | flags | u8 | 0, otherwise reserved_flags |
| 8 | length | u32 | payload bytes, <= 262144 (oversized) |
| 12 | payload | bytes | exactly length; short truncated, extra trailing_bytes |
Payload decoders also reject truncation, trailing bytes, out-of-range enum bytes
(invalid_value) and values failing the presentation contracts (invalid_value).
Messages
| Type | Name | Direction | Payload |
|---|---|---|---|
| 1 | Hello | C->S | required_features u32 (must be 0: unsupported_feature), grant_length u16 (1..512), grant bytes |
| 2 | Welcome | S->C | session, world, frame, region, epoch, server_tick, commit_watermark, grant_expires_at (u64 each); intent_window, window_ticks, max_intents_per_window (u32 each; session, window_ticks and max nonzero) |
| 3 | Intent | C->S | session, epoch, sequence, tick (u64); move_x, move_y (i16) — 36 bytes |
| 4 | IntentResult | S->C | sequence u64, status u8 (0..7), server_tick u64 |
| 5 | EnvironmentView | S->C | view header, environment presentation |
| 6 | OrganismView | S->C | view header, organism presentation |
| 7 | Close | both | reason u8 (0..10) |
| 8 | IntentOutcome | S->C | sequence u64, finality u8 (0 committed_no_effect, 1 not_committed), tick u64, commit_sequence u64; committed requires commit_sequence != 0, not_committed requires tick = commit_sequence = 0 |
| 9 | Heartbeat | both | empty (length 0); sent after 1 s without other output; 5 s of silence closes with timeout |
IntentStatus: 0 admitted, 1 unknown_session, 2 stale_epoch, 3 expired, 4 invalid_vector, 5 replayed, 6 outside_window, 7 rate_limited. CloseReason: 0 normal, 1 unsupported_version, 2 malformed, 3 unauthenticated, 4 expired, 5 duplicate_session, 6 stale_epoch, 7 rate_limited, 8 server_shutdown, 9 capacity, 10 timeout. Types 8-9 and reasons 9-10 were added in M9.7 before any v1 peer was deployed (ADR-0083); later changes require a new version.
View header (40 bytes): session, epoch, server_tick, commit_watermark, baseline (u64).
Environment presentation: world, frame, tick, field_revision (u64); mask u32;
slice_z i64; count u16 (<= 256); then per cell: x, y (i64; z = slice_z);
chunk_revision u64; habitat x, y, z, width, height, depth (u32 micrometres);
volume u64; substrate, terrain_material, terrain_fill (u16); for each of the ten
fields a presence u8 (0 not_requested, 1 missing, 2 present) followed by a u64
quantity only when present; moisture status u8 (0 not_requested, 1 missing_water,
2 zero_capacity, 3 available) followed by numerator, denominator (u64) only when
available. The cells are then validated by EnvironmentPresentation::create.
Organism presentation: world, frame, tick, revision (u64); slice_z i64; count u16
(<= 1024); then per cell: id u64; x, y (i64); offset x, y (u32 um); structural,
membrane, total mass (u64); extent u32; surface, maintenance (u64); movement
speed u32; ingestion rate u64; conversion, thermal shortfall (u32); realized,
damage (u32 per thousand); state u8 (0 alive, 1 dead). Validated by
OrganismPresentation::create. There is no controller, owner or label field.
Maximum payload sizes: Hello 518 bytes, environment view about 42 KiB at 256 cells, organism view about 105 KiB at 1024 cells; all within one frame.
Dev grant (opaque in Hello; 108 bytes)
| Offset | Field | Type |
|---|---|---|
| 0 | marker | EVO-DEV-ONLY + 4 zero bytes |
| 16 | version | u16 = 1 |
| 18 | environment | u8 = 1 (dev) |
| 19 | reserved | u8 = 0 |
| 20 | grant_id, subject, world, frame, region, issued_at, expires_at | u64 each |
| 76 | tag | HMAC-SHA256 over bytes 0..75 |
The tag is verified before any other field is interpreted.
Compatibility
v1 has no optional extensions: required_features and flags must be zero, and a
peer receiving another version closes with unsupported_version. Any field change
is a new version with an explicit compatibility decision; nothing is negotiated
silently. These messages are transient and never persisted.