Files
aevolution/schemas/view/dev-session-v1.md
T
dingoandClaude Opus 5.5 c588be237c Fix M9.4-M9.7 review findings in the dev session stack
- 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>
2026-10-02 05:44:44 -04:00

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.