[Reviewed] # ADR-0083: Dev region sessions, no-effect intentions and the session drill ## Status The engineering client's remote mode moved to M10 sessions in M10.5c (ADR-0093); this ADR's server path and `evo-dev-session` remain for their own tests. Listener/Service rule narrowly superseded for evolution-dev by ADR-0087 (dev session route), effective only when that route is enabled; until then this ADR applies as is. Accepted for M9.7 (engineering client to one authoritative **dev** region). Decisions confirmed with the maintainer on 2026-10-01: durable no-effect intentions, an explicitly empty organism presentation, local real-process evidence plus a dev deployment path. No biology, gameplay, format or production identity decision. ## Context ADR-0082 defined protocol v1, admission, dev grants and TLS. M9.7 needs a real desktop-to-region connection, view display, a minimal admitted intention whose final outcome reflects the server's durable acknowledgement, and recovery after restarts. Findings that constrain the design: - The roadmap lists M8-dev/stage as a dependency; it is **not passed** (live gates open). The maintainer chose to proceed: local real-process evidence now, cluster evidence through a drill they run. - The region (`LineageRegion` over `EnvironmentalCommunity`) has pooled producer and consumer inventories driven by host facts. There is no movable organism, so an intention cannot have a biological effect without new rules and formats. - The region has real field/terrain stores (environment views are derivable) but no placed individuals (no honest organism presentation). - Dev runs without synthetic inputs in Git (ADR-0073); NodePort/LoadBalancer are forbidden and network policy is default-deny (ADR-0069). No kubeconfig exists on the implementing workstation. ## Decision **Session server in the region process.** `SessionServer` (src/network/session) is host-agnostic and non-blocking; `evo-server` calls it from its existing single-thread loop (as it does the ops server). It never mutates host state. Per connection: all output goes through the TLS channel's bounded queue (1 MiB; an interrupted TLS record is retried with identical arguments, later frames wait behind it; a full queue drops the slow consumer), the newest view replaces an unsent one, 1 s Close flush deadline, 5 s accept-to-Welcome deadline, 64 KiB/s input limit, heartbeat after 1 s without output and `timeout` close after 5 s without input, session bound to its connection (a connection can only speak for its own session). At most 4 connections/sessions. New epochs close existing sessions (`stale_epoch`) and discard intentions not yet carried. **Views.** Every new simulated tick (and new epoch), the bridge queries the region's own stores (`query_environment` over the sites in the first site's Z slice, all fields) and publishes an `EnvironmentPresentation` plus an **empty** `OrganismPresentation`. View headers carry session, epoch, simulated tick and the committed tick as the durable watermark. Every session starts from the latest view. **Intentions.** Sessions require `--synthetic-inputs development-v1`. An admitted intention is queued and rides the next synthetic input whose tick is at or after its intended tick under a fresh **server-issued carrier id** `'I','N' | epoch (48 bits) | ordinal (64 bits)`, never derived from client values; the client sequence is kept separately for replies. Epochs beyond 48 bits are refused at Hello (`capacity`) and ordinal exhaustion stops carrying; nothing wraps or truncates. The input's **content stays the host-chosen development input**. The host's FinalAck for that request yields `IntentOutcome{committed_no_effect, tick, commit_sequence}`; a dropped input yields `not_committed`. The driver looks ahead 8 ticks (instead of 64) when sessions are on, matching the admission window. **Protocol v1 amendment.** Before any v1 peer was deployed, v1 gained message types 8 `IntentOutcome` and 9 `Heartbeat` (empty) and close reasons 9 `capacity` and 10 `timeout` (schemas/view/dev-session-v1.md). Once a dev deployment runs, further changes need a new version. **Grant consumption survives restarts.** Consumed grant ids are appended to a durable ledger (`--session-grant-ledger`; `/objects/dev-session-grants.v1` in dev, outside the object namespaces and ignored by backups) and fsynced **before** Welcome; a failed write refuses the session and keeps the grant consumed in memory. A replacement process loads unexpired entries into admission at startup. Before any read or rewrite, an opener obtains a nonblocking exclusive OS lock on a stable sibling `.lock` file (POSIX flock / Windows share-denied handle), held until the append handle closes. A competing opener fails before mutation, including failed duplicate server starts. The lock file is never removed during normal operation: replacing it could split ownership. OS process exit releases the lock; no stale-lock deletion is needed. Records must end with LF and contain at most 37 bytes before it. Incomplete tails and oversized records are rejected before compaction, leaving ledger bytes intact. The text format has no checksum: syntactically valid corruption or removal of entire records is not detected; this is not a tamper-evident ledger. Corrupt content, I/O failure or more than 65536 entries fail closed. The ledger does not survive a restore-to-bundle (a rewind) or a lost volume; grants expire within an hour. **Client.** `SessionClient` connects, verifies the pinned dev CA, consumes one single-use grant per Hello (except after `server_shutdown`/`capacity`, which the server refuses before recording the grant), and on Welcome resets both layers (fresh baseline). It heartbeats when idle and treats 5 s without any server frame as loss. On loss it keeps the last presentation marked stale, reports every sent-but-unresolved intention as `unknown` (sent without a result, or admitted without an outcome), and retries with capped exponential backoff until grants run out (explicit `exhausted`). `send` is bounded: at most 256 unresolved intentions and the channel queue's capacity; beyond that it refuses rather than buffers. Intended tick = newest view tick + 4. The desktop app sends an intention only when its vector changes, at most once per view tick. `evo-client --connect ... --ca ... --grants ...` replaces the local fixture. **Credentials and grants.** `evo-dev-session credentials` writes a dev CA, server certificate/key and a grant HMAC key (secrets owner-only, never overwritten, refused outside dev). `evo-dev-session grants` issues up to 64 single-use grants (lifetime <= 1 h) on the operator machine, so clients never hold the HMAC key. **Dev deployment.** The region Deployment gains a drill-time `REGION_SESSION` override (empty in Git, enforced by the policy check), an optional 0440 Secret `evolution-dev-session`, and a listener bound to **127.0.0.1:7400** inside the pod: reachable only by `kubectl port-forward`, never a Service. `tools/ops/session-drill.sh` (evolution-dev only) enables inputs and sessions, runs `evo-dev-session probe --expect-restart` through a port-forward (durable ack, forced pod deletion, reconnect at a newer epoch, second durable ack) and restores Git values on exit. Mbed TLS build changes: upstream `-Werror` disabled for upstream sources (owned code keeps warnings-as-errors), and TLS context serialization compiled out. ## Alternatives considered - Map intentions onto `EnvironmentalInput` (bites/temperature): lets clients author biological inputs; rejected. - Add a movable organism now: new rules, persisted format and converter; deferred. - Synthesize organisms from pools: fabricated presentation; rejected. - Admission result only: does not reflect durable outcomes; rejected. - Expose the dev region via NodePort/Ingress: violates ADR-0069 and widens exposure. - Enable synthetic inputs and sessions permanently in dev: contradicts ADR-0073 and grows dev history continuously; drill-time only instead. - Separate gateway process: needs host IPC for acks and views; unnecessary for one dev region. ## Benefits Real authority path end to end (TLS, admission, durable ack, recovery) without new game rules; honest presentation; dev identity and listener cannot reach stage/World0. ## Costs Intentions are delayed until a carrier input (up to ~9 ticks); one intention per carried tick; sessions require synthetic inputs; the session drill needs an operator. ## Risks Port-forward reachability depends on cluster tooling; the drill's evidence is only as complete as its logs. A session id is bound to its connection but grants are bearer tokens: anyone holding an unused grant (or the dev key) can open a dev session. Restart gaps: an intention admitted just before a crash has an unknown outcome until the client reconnects (reported as such, never assumed). ## Review corrections (2026-10-02) The M9.4-M9.7 review (`.cache/reviews/M9.4-M9.7-review.md`, not in Git) reproduced and this revision fixes: TLS retry with changed arguments losing queued frames; carrier ids aliasing sequences 2^32 apart (the original low-32-bit packing above was unsafe and is withdrawn); consumed grants becoming valid again after a restart; no liveness after Welcome; and the `ci-client` configure missing its C compiler. Each has a regression test (engineering/VALIDATION.md). ## Consequences M9.8 packages the client and qualifies the presentation. M10 replaces the carrier with real intention semantics once organisms move, and reopens transport choice.