Files
aevolution/docs/adr/0083-dev-region-sessions.md
T
dingoandClaude Opus 5.5 1819ebc0ab
Foundation / checks (checks) (push) Successful in 32m47s
Foundation / checks (client) (push) Failing after 10m1s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
Foundation / checks (network) (push) Successful in 11m18s
Foundation / checks (postgres) (push) Successful in 40m20s
Foundation / checks (tsan) (push) Successful in 7m46s
Foundation / postgres-tools (push) Skipped
Foundation / image (push) Skipped
Foundation / server-image (push) Skipped
Switch the engineering client to M10 sessions (M10.5c)
evo-client's remote mode now runs over RegionSessionClient (QUIC, session
v2): snapshot-fed environment and organism views, the camera following the
server's view until the user moves it and then driving the interest, intention
records with a simulated state, and reconnects with the next grant of a bundle.
The launcher reads 160-byte M10 grants and defaults to the dev route.

- quic::resolve_ipv4 shared by the client and evo-session-probe
- evo-session-probe grants: owner-only bundles of 1-64 grants
- evo-server --m10-max-grant-lifetime (dev only, 60..3600 s)
- presets client-network/client-package build QUIC; msquic links the CRT
  fully static; msquic.dll and msquic/OpenSSL licences in the Windows package
- client-remote-session test against a loopback region
- ADR-0093/0091/0086 amendments, M10_CLIENT_SESSIONS guide, validation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 11:57:07 -04:00

9.3 KiB

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.