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
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>
149 lines
9.3 KiB
Markdown
149 lines
9.3 KiB
Markdown
# 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.
|