- 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>
84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# Dev session protocol v1 (wire schema)
|
|
|
|
Decision: [ADR-0082](../../docs/adr/0082-dev-session-transport.md). 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.
|