docs/design/flybus.md

@@ -1,73 +0,0 @@
-# flybus: the communications bus
-
-Status: **crate landed, nothing wired onto it**. Written 2026-09-22. Index only; the
-authority for the API and the wire format is the crate's own
-[README](../../services/flysim/crates/flybus/README.md).
-
-## What it is
-
-`flybus` is a local RPC and pub/sub bus for Tokio processes on one host, with immutable
-file-backed artifacts for large payloads. One library, one router, one wire protocol:
-messages are small strict-JSON envelopes carrying metadata and artifact references, while
-bulk bytes (frames, audio, spike bitsets) live in a store directory the router owns.
-Ownership follows deliveries and explicit holds; the router moves messages and tracks
-ownership and does not interpret them. It implements the Flybus v1 draft (`bus-v1`, draft 1
-of 2026-09-18) over the `ipc-v1` scalar encodings.
-
-Transports are an in-memory pair, an accepted `AsyncRead + AsyncWrite` stream, or a Unix
-socket. Identity is bound by the launcher before Hello and checked against a `Policy` of
-per-client grants; open/unbound mode is for trusted tests only and is not authentication.
-
-Nothing in the crate is specific to a game, a brain or a stream.
-
-## What it is meant to replace
-
-Today the three processes talk over two ad-hoc loopback surfaces:
-
-| Today | Under the bus |
-| --- | --- |
-| Feed: WebSocket `127.0.0.1:7400/feed`, one binary message per snapshot at 30 Hz, header plus RGBA frame, audio and spike attachments, re-serialized per consumer | One `latest`-mode topic per stream, with the frame as a sealed artifact shared by fan-out instead of copied per subscriber |
-| Control: loopback HTTP `127.0.0.1:7401` (`/stimulate`, `/chat`, `/checkpoint`, `/pause`, `/status`, ...) | RPC services with per-client grants, FIFO dispatch, explicit cancel states and backpressure |
-| Per-surface limits, rate limits and timeouts written twice | `Limits` and `Policy` in one place, negotiated at Hello |
-
-The feed and control contracts in [feed-protocol.md](../feed-protocol.md) and
-[control-api.md](../control-api.md) stay binding until a migration replaces them. The bus
-does not change any published contract by existing.
-
-## Crate layout
-
-`services/flysim/crates/flybus`, a workspace member of the flysim workspace; no other crate
-depends on it yet.
-
-| Module | Contents |
-| --- | --- |
-| `wire` | Scalars, strict JSON, `Envelope`, `ArtifactRef`, `Attachment`, `Location`, framing, `CONTRACT` and `contract_digest()` |
-| `error` | `ErrorCode`, `Dispatch`, `BusError` |
-| `limits` | `Limits` and its hello encoding |
-| `policy` | `Policy`, `Grants`, `Pattern` |
-| `router` | `Router`, `RouterConfig`, `RouterStats`, `UnixListenerHandle`; the state machine in `router/state.rs` |
-| `client` | `Client` and the handle types |
-| `store` | The router-side file store and client-side location resolution |
-| `transport` | `Transport` and the `Stream` trait |
-
-Dependencies are already in the workspace lockfile: `tokio`, `serde`, `serde_json`, `sha2`,
-`libc`. Tests run every integration case twice, once in memory and once over a Unix socket:
-wire negotiation, RPC authority and cancellation, pub/sub credits and retention, artifact
-allocate/seal/read with quotas and router restarts, plus the conformance suites and an
-`--ignored` perf measurement.
-
-## Wiring still pending
-
-- **flysim publisher.** Router startup inside the sim service, a store root under its
-  runtime directory, and snapshot publication as artifact plus header envelope.
-- **flysim control services.** The control endpoints as RPC services with grants, so the
-  "no button endpoint" structural guarantee is expressed as a grant table.
-- **Stage and bridge clients.** Both are TypeScript/Node; the crate is Rust only, so either
-  a binding or a thin translating edge process is required before they leave the WebSocket
-  and HTTP surfaces.
-- **Sizing.** `max_store_bytes`, `max_retained_bytes` and `max_latest_in_flight` need values
-  chosen for 1.2 MB frames at 30 to 60 Hz with a slow consumer, not the defaults.
-- **Lifecycle.** Orphaned store directories are cleaned only when a new router starts on the
-  same root, so service restart order and the store root's location need a decision.
-- **Migration order.** The feed is the cheaper first move; control should follow only once
-  the bus carries the feed in production for a full session.

docs/design/malecns-modular-implementation.md

@@ -1,268 +0,0 @@
-# Implementation backlog: MaleCNS and modular sessions
-
-Status: **planned, not started**. Written 2026-09-18. Companion to the
-[design and code analysis](malecns-modular-sessions.md), based on `f7bc13a`.
-
-This is the execution order for that proposal. It does not authorize deployment or a live
-stream. Reconcile the baseline with merged macro/shop/recovery work before implementation.
-Existing feed/control contracts and TypeScript oracle rules remain binding.
-
-Concrete second-game audit: [Melee framework and emulator plan](melee-framework-audit.md).
-Its MELEE-01/02 spikes specialize EMULATOR-01 below and can proceed alongside framework
-extraction; they do not depend on importing MaleCNS first.
-
-The [session framework contract set](session-framework/README.md) now specifies the new
-multi-process architecture. Its [implementation guide](session-framework/implementation.md)
-breaks RUNTIME/WIRE/STATE work into concrete schema, transport, coordinator and worker slices.
-
-**Communications decision:** build [Flybus](session-framework/bus-v1.md), one Rust RPC/pub-sub
-router with immutable external artifacts, delivery guards and last-owner GC. It serves workers,
-application supervision, presentation and storage. No second direct-RPC system or NATS broker.
-Application-specific orchestration and frontend are developed together; native frames leave
-the environment, while resizing/compositing/streaming belongs to presentation.
-
-## 1. Delivery strategy
-
-Deliver working vertical slices; keep the existing FAFB/Game Boy composition usable throughout.
-
-1. Establish a behavior baseline and explicit dataset/profile identities.
-   Independently build the generic Flybus example; it needs neither dataset nor emulator.
-2. In parallel workstreams, characterize MaleCNS and extract the single-agent session runtime.
-3. Demonstrate two isolated brains driving one ROM-free shared environment.
-4. Expose that session through versioned feed/control contracts and a multi-agent broadcast.
-5. Integrate a specifically chosen alternative emulator after its capability spike passes.
-6. Finish physical package reorganization once the second consumer proves the boundaries.
-
-**First milestone:** a reproducible headless MaleCNS run and a reusable single-agent session.
-**Second milestone:** two flies in a synthetic arena with coherent resume and a local broadcast.
-**Third milestone:** two flies in the chosen fighting game, with documented task scaffolding.
-
-No elapsed-time estimate is committed before the import and emulator spikes establish their
-unknowns. Split an item further when its contract and implementation cannot be reviewed together.
-
-## 2. Work queue
-
-Every item starts pending. Branch names are suggested implementation branches, not branches
-already created. Builders use separate worktrees; the coordinator reviews contracts and results.
-
-### FOUNDATION-01 — Pin existing behavior
-
-- **Branch:** `test/session-baseline`
-- **Depends on:** reconciliation with current main and related open work.
-- Record effective legacy configuration, fingerprint, version strings and frame ordering.
-- Add a ROM-free transition harness around the service's frame orchestration; capture brain
-  ticks, decoded actions, reward application and recovery effects with explicit clocks.
-- Distinguish exact numerical replay from intentional macro/hold/transient reset on restore.
-- **Done:** existing goldens pass; a trace fixture detects reordered vision/reward application;
-  legacy feed/API fixtures and compatibility identity are unchanged.
-
-### FOUNDATION-02 — Specify bundle and behavior identities
-
-- **Branch:** `feat/brain-profile-contract`
-- **Depends on:** FOUNDATION-01.
-- Specify dataset manifests, original-ID mapping, anatomical roles, sensory bindings,
-  readout bindings and composite behavior identity in a focused contract.
-- Add profile resolution/validation around the existing core in TypeScript and Rust.
-- Keep schema-1 fingerprinting and the legacy macro-role exception behind the legacy path.
-- Add strict graph validation for new bundles, shared invalid fixtures and profile mismatch tests.
-- **Done:** empty required populations, malformed CSR and incorrect profile restores fail;
-  legacy FAFB artifacts and default numerical version strings remain unchanged.
-
-### DATA-01 — Acquire and normalize MaleCNS
-
-- **Branch:** `feat/malecns-import`
-- **Depends on:** FOUNDATION-02.
-- Build a source-specific importer from official v1.0 tables with checksummed source locks.
-- Reconcile the Codex versus neuPrint inventories, or explicitly select and document one.
-- Preserve raw contact counts, transmitter evidence, original IDs and missing-data indicators.
-- Emit deterministic graph bundles, weight≥1/weight≥5 comparison variants, and an exclusion/
-  clipping/coverage report. Decide schema-1 feasibility from measured weight ranges.
-- Add attribution and license records with actual artifacts; keep raw downloads out of git.
-- **Done:** repeated builds match; endpoint/role/index invariants pass; both loaders agree;
-  no service startup or ordinary unit test needs a download.
-
-### DATA-02 — Characterize MaleCNS in the current kernel
-
-- **Branch:** `feat/malecns-baseline-profile`
-- **Depends on:** DATA-01.
-- Audit L1 geometry, hemisphere handling, KC/MBON/PAM mappings and brain-versus-VNC motor roles.
-- Define a versioned fixed readout; keep task action partitions out of anatomical truth.
-- Run learning-off first, then learning-on, using fixed sensory traces and multiple seeds.
-- Generate TS reference goldens and compare Rust exactly; measure activity, saturation,
-  initialization, memory and per-phase latency for both graph thresholds.
-- **Done:** publish a reproducible characterization report and profile choice. Stop task
-  integration if required mappings are missing or dynamics are unusable; any recalibration
-  becomes a named profile rather than an edit to the legacy model.
-
-### RUNTIME-01 — Separate environment execution from task interpretation
-
-- **Branch:** `refactor/environment-task-boundary`
-- **Depends on:** FOUNDATION-02.
-- Specify controller ports, digital/analog controls, rational cadence, media descriptors,
-  observation ownership and backend capabilities.
-- Wrap binjgb as the first environment; retain Game Boy FFI/cache/state behavior.
-- Keep Pokémon memory inspection, objective routing, macros and reward rules in its task.
-- The executor receives coherent current game state, progress/objective view and clock on
-  every step. This richer context is not implicitly passed to the neural sensory encoder.
-- Preserve existing imports through a facade; avoid simultaneous directory moves.
-- **Done:** existing single-agent action/reward traces match and a fake environment can be
-  driven through the same boundary without importing binjgb or task-specific addresses.
-
-### RUNTIME-02 — Extract the single-agent session
-
-- **Branch:** `refactor/session-runtime`
-- **Depends on:** RUNTIME-01 and BUS-01..03 from the contract implementation guide.
-- Move deterministic agent/environment/task orchestration out of `Sim` into a library.
-- Keep HTTP, WebSocket serialization, wall-clock publication and process supervision in flysim.
-- Route internal worker calls and observations through Flybus; keep public compatibility
-  adapters at the application edge. Domain caches own artifact handles for replay.
-- Give session clock, action executor, task ledger and recovery state explicit owners.
-- Wrap the existing composition with legacy ordering, checkpoint and reset semantics.
-- **Done:** headless bus client runs a session without Twitch/browser; the legacy composition
-  passes its traces and restore tests; a slow snapshot consumer cannot stall simulation.
-
-### RUNTIME-03 — Add synchronized multi-agent sessions
-
-- **Branch:** `feat/multi-agent-arena`
-- **Depends on:** RUNTIME-02.
-- Implement a ROM-free two-player arena and per-port controller ownership.
-- Evaluate both brains against one observation boundary; apply one complete action batch;
-  advance the world once. Start sequentially, then verify parallel execution equivalence.
-- Isolate RNG, stimulation, decoder holds, gains, traces and rewards per agent; share only
-  immutable topology. Enforce a total worker budget and single-dispatcher pool ownership.
-- Define participant failure, lateness and episode reset policies.
-- **Done:** no cross-agent state leakage; swapping evaluation order leaves results unchanged;
-  one failed participant cannot accidentally advance a half-controlled match.
-
-### STATE-01 — Capture and resume whole sessions
-
-- **Branch:** `feat/session-checkpoints`
-- **Depends on:** RUNTIME-03; specify the state contract during RUNTIME-02.
-- Define the new envelope/manifest and preserve the `FLYSIM01` reader.
-- Capture all agents, environment, task/executor/admission state and clock remainders at one
-  boundary. Bound off-thread write jobs and retain atomic manifest commit semantics.
-- Validate all components before installing any restored state; define external-backend staging.
-- **Done:** uninterrupted and resumed synthetic matches agree; corrupting any participant
-  refuses the generation without partial restore; crash-injection fallback tests pass.
-
-### WIRE-01 — Introduce session feed/control v2
-
-- **Branch:** `feat/session-protocol-v2`
-- **Depends on:** FOUNDATION-02, RUNTIME-02; use RUNTIME-03 fixtures for integration.
-- Write binding contracts before consumer implementation: descriptors, scoped agents/events,
-  media IDs/timestamps, task progress, targeted stimulation and retry/idempotency behavior.
-- Implement Rust/TS codecs, schemas and a fake server; preserve the legacy v1 surface.
-- Specify descriptor reconnect behavior, asset/index identity, bounded message sizes and audio gaps.
-- **Done:** cross-language fixtures pass for unequal neuron counts and shared/private views;
-  duplicate attachment kinds no longer collide; ambiguous targets and incompatible schemas fail.
-
-### PRESENTATION-01 — Compose multi-agent stage and bridge
-
-- **Branch:** `feat/multi-agent-broadcast`
-- **Depends on:** WIRE-01, RUNTIME-03.
-- Replace stage store/scaler singletons with session/agent instances and one paint scheduler.
-- Combine framework descriptors/measurements with application-owned state/cues over the bus.
-  Rendering may retain an artifact after message drop; last-use release returns delivery credit.
-- Resolve geometry from hashed descriptors, preserve the Game Boy presentation, and add a
-  shared-match layout with explicit audio ownership.
-- Route bridge commands/redemptions to persistent session/agent identities; test lost responses,
-  retries and restart without applying an interaction twice or to a different agent.
-- **Done:** local synthetic match broadcast works; two-agent PNGs receive operator review;
-  browser/fixture/legibility checks pass; bridge remains template-only and quiet-mode capable.
-
-### DATA-03 — Run MaleCNS through the complete application
-
-- **Branch:** `feat/malecns-session`
-- **Depends on:** DATA-02 and descriptor-aware assets from WIRE-01/PRESENTATION-01.
-- Expose explicit profile selection and create a fresh MaleCNS state namespace.
-- Verify task/controller bindings, stimulation capability and displayed anatomy identity.
-- A narrow single-agent descriptor extension may ship earlier only with matching v1 contract
-  and consumer updates; do not publish MaleCNS spikes as implicit FAFB indices.
-- **Done:** local one-hour soak and restore drill pass; paired learning-off/on observations
-  are recorded without claiming improved play; FAFB remains available unchanged.
-
-### EMULATOR-01 — Establish the alternative backend's capabilities
-
-- **Branch:** `spike/fighting-game-backend`
-- **Depends on:** RUNTIME-01; can proceed alongside later runtime work.
-- Choose the exact game/version and emulator; Melee/Dolphin is a candidate, not a commitment.
-- Prove pause/step, simultaneous ports, analog input, frame/audio capture, state inspection,
-  save/restore, process lifecycle and achievable cadence with synthetic controller traces.
-- Prefer a bus-connected helper if embedding would leak emulator internals into the session
-  library. Its native emulator protocol is an implementation detail, not a second framework API.
-- **Done:** capability report includes pinned backend/content identity and reproducible results.
-  If bounded stepping or coherent restore fails, stop and revise the backend/requirements
-  before writing neural game logic. No game content enters repository fixtures.
-
-### EMULATOR-02 — Build the two-fly fighting-game slice
-
-- **Branch:** `feat/two-fly-fighting-game`
-- **Depends on:** EMULATOR-01, STATE-01, PRESENTATION-01.
-- Implement fixed controller mapping, match/round interpretation, positive attributed rewards,
-  observation policy and episode recovery. Display selected actions and actual controls.
-- Validate one fly, two flies, round transitions, backend failure and resume in that order.
-- Run side swaps and repeated seeds; compare learning-off and simple control baselines before
-  interpreting win rates. Separate show settings from controlled evaluation settings.
-- **Done:** repeated local matches sustain declared cadence; restoration/failure policies work;
-  scaffold, interventions and limits are documented; reviewed match presentation is legible.
-
-### PACKAGE-01 — Finalize reusable packages and release compositions
-
-- **Branch:** `refactor/reusable-package-layout`
-- **Depends on:** a useful second backend plus PRESENTATION-01.
-- Extract proven crate/package boundaries from the design's module table; preserve facades.
-- Move the Rust workspace only in a mechanical follow-up if it makes library consumption clearer.
-- Update CI/build/vendor/golden paths, dataset/view asset packaging and compatibility preflight.
-- Add minimal external-style Rust/TS consumers and a synthetic example composition.
-- Reconcile current docs, stale template explanations and licensing/asset attribution.
-- **Done:** both legacy and new compositions package successfully; incompatible state is
-  rejected before release selection; libraries run without importing broadcast services.
-
-## 3. Dependency map and first execution batch
-
-```text
-FOUNDATION-01 → FOUNDATION-02 ┬→ DATA-01 → DATA-02 ───────────────→ DATA-03
-                            └→ RUNTIME-01 → RUNTIME-02 → RUNTIME-03 → STATE-01
-                                  │             └→ WIRE-01 ───────┐
-                                  └→ EMULATOR-01          PRESENTATION-01
-                                                              │
-                         STATE-01 + EMULATOR-01 + PRESENTATION-01 → EMULATOR-02
-                                         second backend + presentation → PACKAGE-01
-```
-
-The item dependency lists are authoritative; the diagram is a reading aid. The detailed
-contract guide adds BUS-01 (RPC), BUS-02 (pub/sub) and BUS-03 (artifacts/GC) before the
-distributed RUNTIME-02/03 slices. These can proceed independently of MaleCNS import.
-
-Start the preservation track at FOUNDATION-01; the generic bus track can start with the
-contract guide's small RPC/pub-sub/artifact example. Then review FOUNDATION-02's contract
-before assigning DATA-01 and RUNTIME-01 to independent worktrees.
-Contract/schema authorship is serialized to avoid conflicting definitions. Deployment host
-work remains serialized under the repository's claim protocol.
-
-## 4. Definition of done for every implementation branch
-
-- Scope and intentional behavior changes are stated; compatibility impact is explicit.
-- Meaningful boundary tests cover the changed behavior; the TS oracle is not adjusted to
-  accommodate Rust output. Existing committed real-data goldens stay mandatory.
-- `npm test`, `npm run typecheck`, `cargo test --workspace` (Rust workspace) and
-  `infra/tests/lint.sh` pass before merge. Visual changes also pass applicable Playwright
-  checks and PNG review. Optional full-MaleCNS/ROM runs record skips honestly.
-- Performance-sensitive changes report representative activity, agent count, thread budget,
-  memory and tail latency. New experiments state what is modeled versus handwritten.
-- Review the complete diff, merge with `--no-ff` when authorized, and update this queue with
-  commit, evidence and unresolved follow-ups. Rollback includes compatible state, not just code.
-
-## 5. Decisions needed before the relevant work starts
-
-| Decision | Deadline | Default recommendation |
-| --- | --- | --- |
-| MaleCNS inventory/filter policy | DATA-01 completion | Official versioned source; retain both threshold variants until measured |
-| MaleCNS sensory/readout profile | DATA-02 | Audited L1 mapping with existing numerical model first |
-| Exact fighting game and backend | EMULATOR-01 | Evaluate one concrete title/backend rather than supporting a console family at once |
-| Number of flies and target resource budget | RUNTIME-03 performance gate | Two first; characterize four before promising it |
-| Learning retention and sugar in matches | EMULATOR-02 task contract | Retention explicit; stimulation disabled in controlled comparisons |
-| Package publication versus monorepo reuse | PACKAGE-01 | Monorepo libraries/examples first; public package publishing later |
-
-There is no need to resolve these now to plan another feature. This backlog is ready for
-resumption at FOUNDATION-01 and the independent BUS-01..03 track.

docs/design/malecns-modular-sessions.md

@@ -1,918 +0,0 @@
-# MaleCNS and reusable streamed simulation sessions
-
-Status: **proposal, not an implemented contract**. Written 2026-09-18 against `f7bc13a`
-on `main`. This document covers two related projects: adding MaleCNS v1.0 as another
-connectome, and extracting reusable modules for other emulators, embodied environments,
-and multiple flies. No dataset, neural semantics, deployed configuration, or wire contract
-is changed by this document.
-
-The binding [feed](../feed-protocol.md) and [control](../control-api.md) contracts take
-precedence. The TypeScript brain remains the oracle. Existing default versions
-`lif-1ms-f64-v2` and `fly-kc-mbon-rstdp-v2` remain pinned.
-
-Reading map: sections 2–3 contain the code audit and MaleCNS analysis; sections 4–6
-define the proposed module/session boundaries; sections 7–8 give the extraction order,
-implementation workstreams and acceptance gates; sections 9–10 record open questions and
-sources.
-
-Execution queue: [implementation backlog](malecns-modular-implementation.md), with branch-sized
-deliverables, dependencies and completion criteria. Start at FOUNDATION-01 when work resumes.
-
-Concrete follow-up: [Melee emulator and multi-fly framework audit](melee-framework-audit.md),
-including source-checked Dolphin/libmelee integration options and full-stack performance gates.
-
-Implementation contracts: [session framework](session-framework/README.md), defining private
-Flybus RPC/pub-sub, lockstep phases, worker methods, artifact ownership, recovery and publication.
-The [bus specification](session-framework/bus-v1.md) is the selected communications design:
-one small Rust router, external immutable artifacts and delivery-scoped GC. Application
-orchestration/presentation are developed together; tournaments are examples, not framework types.
-
-## 1. Recommendation
-
-1. **Add MaleCNS as a dataset/profile combination, not a replacement neural model.**
-   First run it through the existing LIF semantics with explicit, independently versioned
-   sensory, population, and readout mappings. Study different neuron dynamics separately.
-2. **Make a session the unit of simulation ownership.** A session has one environment and
-   one or more independently stateful agents bound to its control ports. A shared match
-   advances once after all players have chosen actions from the same observation boundary.
-3. **Extract along ownership and timing boundaries.** Separate anatomy, neural dynamics,
-   sensor encoding, action decoding, environment execution, task semantics, persistence,
-   observation transport, presentation, and audience interaction. Preserve current behavior
-   through a legacy composition while extracting these modules.
-4. **Prove the design on a ROM-free two-player arena before a larger emulator.** Then build
-   a frame-stepped emulator integration. For “flies play Smash,” the first candidate should
-   be a specifically chosen title/backend, such as Melee with a pinned Dolphin integration;
-   “Smash” alone is not an emulator requirement.
-5. **Retain a monorepo and one Rust workspace initially.** Reusable libraries do not require
-   a network of microservices, dynamic native plugins, or publishing unstable packages.
-
-The two tracks can progress independently after the identity/profile boundary is established.
-MaleCNS does not require multiplayer; multiplayer does not require MaleCNS. The first useful
-deliverables are a reproducible MaleCNS characterization run and a behavior-preserving
-single-agent session API, not a wholesale rewrite.
-
-## 2. What the code actually does today
-
-Paths below are relative to the repository root. Rust paths beginning `core/`, `gb/`, or
-`sim/` in this document abbreviate `services/flysim/crates/flybrain-core/`,
-`services/flysim/crates/flybrain-gb/`, and `services/flysim/crates/flysim/` respectively.
-These aliases refer to **current** paths, not proposed directories.
-
-| Boundary | Evidence inspected | Consequence |
-| --- | --- | --- |
-| Reference brain | `packages/brain/src/agent/agent.ts`; `core/src/agent.rs` | `NeuralAgent` composes network and decoder; image size and milliseconds/frame are configurable, but defaults are Game Boy-specific. It is already more reusable than the service. |
-| Anatomy | `packages/brain/src/dataset/format.ts`; `core/src/dataset.rs` | CSR graph dimensions are dynamic. Weights are signed `i16`; roles and a two-dimensional visual-column table are part of the model input. Validation currently checks array lengths, not every graph invariant. |
-| Dataset construction | `tools/build_flywire.py` | Five checksum-pinned Codex exports; stable indices from sorted root IDs; directed-pair aggregation; transmitter signs; clipping to ±32767; FAFB-specific role and L1-column extraction. Game macro populations are also generated here. |
-| Neural dynamics | `core/src/lif.rs`; `packages/brain/src/model/lif.ts` | One-ms ticks, configurable gain/noise, role stimulation, image drive, and up to 64 tracked rate roles. It is not a general multimodal sensory API. |
-| Learning | `core/src/plasticity.rs` | Strongest positive pre-role→post-role edges, default KC→MBON budget 16,384; gains/eligibility are per-agent. A caller supplies the reward scalar; PAM spikes do not generate it. |
-| Parallelism | `core/src/lif.rs` (`SweepPlan`); `core/src/pool.rs` | Persistent deterministic within-brain pool. `broadcast` has one shared job slot and assumes one dispatcher at a time; cloning a plan is not permission to dispatch it concurrently. |
-| Game interface | `gb/src/adapter.rs` | `GameAdapter` mixes reward detection, progress, decoder preset, recovery, ROM checks, and Pokémon-like tile/exit/objective queries. `MemoryReader::read8(u16)` is specifically a Game Boy-shaped interface. |
-| Emulator | `gb/src/emulator.rs` | Concrete binjgb wrapper, 160×144 RGBA, eight-bit pad, one frame step, audio conversion, native save-state format. Explicit handles and `Send` allow multiple instances; `Sync` is deliberately absent. |
-| Session ownership | `sim/src/simloop.rs` (`Sim`, `step_frame`) | One agent, emulator, adapter, ratchet, button mask, framebuffer, audio queue, sugar state, chat ring, and set of clocks. Application orchestration and game behavior share a large struct. |
-| Actions | `sim/src/macros.rs`; `gb/src/macros.rs`; `gb/src/pokemon_red/macros/` | Neural channels select available macros, but the game-specific executor owns button sequences. The title screen uses raw input; scene handling, routing and targets are engineered behavior. |
-| Recovery | `gb/src/recovery.rs`; `gb/src/ratchet.rs` | Game-only rewind retains brain clock, membrane, RNG, and gains; clears holds/eligibility and refreshes vision. A scalar progress ladder chooses a best save. This is not a general multiplayer reset policy. |
-| Persistence | `sim/src/store.rs`; `gb/src/compatibility.rs` | Durable atomic envelope and manifest commit are reusable. Payload is one agent plus one emulator and ratchet. Compatibility names binjgb and `pokered`; native state identity includes size and target. |
-| Public observation | `sim/src/snapshot.rs`; `packages/feed/src/{types,codec}.ts` | One flat brain/game snapshot; one attachment per kind; Game Boy buttons, fixed frame dimensions, Pokémon-shaped reward counters and a closed game-mode set. |
-| Stage | `apps/stage/src/{App.tsx,feed/store.ts,feed/decode.ts}` | Good hot/paint/cold clock split, but mutable stores/scalers are singletons and the decoder checks 160×144 frames. Dataset URL is fixed to FAFB. |
-| Game presentation | `apps/stage/src/games/` | A useful registry already exists, but config relabels v1 counters rather than declaring independent task schemas. |
-| Twitch bridge | `services/bridge/src/{index,sim,commands,redemptions,templates}.ts` | Transport/client abstraction, test fakes, templates, rate limits, and redemption persistence are valuable. There is one sim URL and no agent target identity. |
-| Packaging | `apps/stage/vite.config.ts`; `infra/build/package-release.sh`; `infra/05-deploy.sh` | Stage build copies FAFB artifacts; packaging defaults to FAFB; deploy preflights one compatibility string. Runtime/data/frontend are still one release composition. |
-
-### 2.1 Behaviors to preserve before extracting
-
-`Sim::step_frame` advances the brain from the previous visual input, decodes, applies
-buttons, steps the emulator, sets the new visual input, samples rewards, stimulates per
-reward event, reinforces their sum, updates macro availability, and observes the ratchet.
-Control commands are drained before the frame step. This ordering is part of behavior.
-
-Do not replace this with `NeuralAgent::tick` merely because it looks like a convenient
-wrapper: the service currently orchestrates substeps to sample reward from the frame just
-produced. Moving reward or visual drive across that boundary changes trajectories.
-
-Other invariants:
-
-- Deterministic arithmetic and per-target propagation order, including across thread counts.
-- Browser/network clients never stall the sim; snapshots are latest-value/drop-oldest.
-- Checkpoint capture is coherent; encoding and storage happen off the sim thread.
-- Failed restore does not silently reset a run. Existing legacy restore policies remain exact.
-- No public control endpoint for button presses or game-memory writes.
-- Sugar and learning reward are distinct mechanisms. Chat text never becomes neural input.
-- The current positive-only reward doctrine remains the default for all shipped tasks.
-
-### 2.2 Existing compatibility gaps to handle deliberately
-
-The dataset fingerprint hashes metadata (including anatomical circuit roles) and six arrays.
-`macro_*` roles are merged **after** hashing to preserve old checkpoints. Both language
-implementations document that changing those populations could restore rates onto different
-neurons without invalidating the checkpoint. The kernel parameter version also omits role
-names; the service compatibility string does not fully identify the decoder/action mapping.
-
-Keep these historical behaviors in the legacy reader. For new profiles, add an explicit
-behavior identity covering population bindings, sensor encoding, decoder configuration,
-action executor, and reward catalog. Do not repair the old hash by changing it in place.
-
-Open macro/shop and recovery branches existed when this proposal was written. Before
-implementation, rebase the inventory against their merged state and rerun characterization;
-this proposal neither incorporates nor supersedes their unmerged changes.
-
-## 3. MaleCNS: anatomy, connectivity, and model are different things
-
-### 3.1 Dataset comparison and evidence limits
-
-| Property | FAFB v783 used here | MaleCNS v1.0 |
-| --- | --- | --- |
-| Specimen | Adult female | Adult male, independently imaged/reconstructed |
-| Territory | Brain including optic lobes | Central brain, optic lobes, ventral nerve cord (VNC), intact neck connective |
-| Local artifact | 139,255 neurons; 2,700,513 directed-pair edges | None imported in this repository |
-| Available inventory counts | Codex lists 139,255 neurons | Codex lists 166,700; the Minecraft project's neuPrint `:Neuron` export reports 176,422. Selection rules must be reconciled before fixing a local count. |
-| Input labels | Codex `root_id`, classification, consolidated types, column assignment | neuPrint/flat export `bodyId`/body IDs, class hierarchy, transmitter properties, sides, neuropils, cross-dataset type annotations |
-| Added anatomical opportunity | Brain sensory→descending circuits | Brain↔VNC circuits, local motor circuitry, ascending feedback, additional sensory and motor populations |
-| License evidence | Repository attribution: CC BY-NC 4.0 | Official MaleCNS download site: CC-BY; verify and retain the exact release license text when importing |
-
-MaleCNS is not FlyWire with extra neurons appended. IDs and dense array indices do not
-correspond. Homologous cell types and registered anatomical spaces enable comparisons, not
-automatic one-to-one neuron matching, state transfer, or graph concatenation. Male-specific
-and sexually dimorphic circuits make a universal matching assumption especially misleading.
-
-The official MaleCNS site describes a finished, proofread and annotated CNS reconstruction.
-This does not mean every synapse, cell type, or sensory column is equally certain. The
-Minecraft derivative reports asymmetric visual-column coverage and missing soma positions;
-our import must quantify coverage from its own pinned source. A connectome also does not
-supply all synaptic physiology, electrical coupling, neuromodulation, body dynamics, or
-behavioral competence.
-
-### 3.2 What “connections” means
-
-Separate these quantities in metadata, reports, and on-screen claims:
-
-1. Source neuron/segment inventory and the chosen included-neuron inventory.
-2. Individual synaptic contacts/partner pairs (and separately pre-sites and post-sites).
-3. Directed neuron-pair edges after aggregation.
-4. Retained edges and retained synaptic weight after confidence/weight filtering.
-5. Effective signed weights after the simulation's transmitter and clipping policy.
-
-The FAFB builder aggregates export rows by `(pre, post)` across rows, drops endpoints not
-in its classification inventory, assigns a sign, and clips the summed magnitude. It adds
-no explicit five-synapse threshold of its own. The source exports may already be filtered;
-the builder cannot recover contacts absent upstream. Codex headline connection counts are
-not necessarily the local aggregated graph's edge count.
-
-The Minecraft project's provenance reports ~25.9 million MaleCNS neuron-pair edges at
-weight ≥1 and a bundled derivative of 6,287,749 edges at weight ≥5, representing
-90,296,905 of 125,024,863 neuron-to-neuron synapses. It removes 40 autapses. Those are
-**that project's reported query/build results**, not counts independently reproduced here.
-Its five-contact cutoff retains roughly 24% of edges but 72% of synaptic weight. It is a
-performance/modeling choice, not the definition of a complete CNS.
-
-The official bulk weight table includes **segments**, not only curated neurons. Loading
-all rows as if they were all validated neurons would be a different experiment. Likewise,
-neuPrint ROI-level adjacency rows must not be summed together with their already-aggregated
-totals. Specify one authoritative edge representation and count every exclusion.
-
-### 3.3 Acquisition and reproducible construction
-
-Prefer official versioned bulk tables for the repeatable build, with a neuPrint query tool
-for inspection and cross-checking. The official download page lists:
-
-- `body-annotations-male-cns-v1.0-minconf-0.5.feather` — curated annotations.
-- `body-neurotransmitters-male-cns-v1.0.feather` — neuron-level transmitter information.
-- `body-stats-male-cns-v1.0-minconf-0.5.feather` — segment statistics; large and broader than
-  the curated neuron list.
-- `connectome-weights-male-cns-v1.0-minconf-0.5.feather` — full segment connection graph,
-  approximately 1.1 GB as listed by upstream.
-
-The much larger synaptic-point and partner tables are unnecessary for an initial point-neuron
-simulation. Download them only for a question requiring synapse-level geometry. Neither
-research downloads nor anatomy conversion belong in service startup or ordinary unit tests.
-
-Proposed build stages:
-
-```text
-release manifest + checksummed source cache
-  → source-specific parser
-  → normalized neuron/edge tables + exclusion report
-  → selected anatomical graph
-  → model-specific signed-weight transform
-  → runtime CSR bundle + profile bindings + separate viewer bundle
-```
-
-Each stage records source release, database revision if queried, query/filter definitions,
-source byte hashes, tool revision, and output hashes. Fetch time is provenance, not a random
-input to the semantic graph hash. Sort body IDs numerically; encode original IDs as strings
-in JSON so this common format also preserves FAFB IDs beyond JavaScript's safe integer range.
-Preserve original annotations and cross-dataset type aliases separately from normalized roles.
-
-The first import report must reconcile the Codex/neuPrint count difference, or explicitly
-choose and document one inventory without claiming equivalence. It must also report missing
-IDs, unannotated neurons, empty required populations, missing geometry, unknown sides,
-transmitter confidence/fallback counts, duplicate edges, autapses, clipped weights, and
-retained contacts by region and threshold.
-
-Use deterministic serialization and gzip headers, following our existing reproducible
-builder rather than copying the Minecraft artifact's timestamp-dependent container format.
-Keep the source cache outside tracked artifacts; pin published runtime bundles by digest.
-
-When adding actual data, update `NOTICE`, `LICENSES.md` and bundle-local attribution/license
-files in the same change. Keep FAFB-derived assets under their existing terms; a separately
-licensed MaleCNS bundle does not relicense mixed fixtures, old goldens or viewer assets.
-
-### 3.4 Graph and sign policy
-
-Keep raw positive contact counts and transmitter evidence in the normalized data. Sign is a
-model transform, not a measured property that should overwrite the source evidence.
-
-The legacy policy assigns GABA/GLUT negative and other/unknown transmitters positive;
-conflicting per-edge transmitter rows become `MIXED`, then positive. Do not silently extend
-that policy to histaminergic photoreceptor input. A MaleCNS policy must explicitly define
-histamine, monoamines, mixed/unknown labels, confidence fallbacks, and whether transmitter
-is chosen per neuron or per connection. None implies receptor-specific physiology.
-
-Recommended first profiles:
-
-- **`malecns-v1-lif-baseline`**: existing kernel, explicitly versioned sign policy and L1
-  input mapping, fixed readout, plasticity initially disabled for characterization.
-- **`malecns-v1-lif-learning`**: same anatomy/input/readout plus audited KC→MBON selection
-  and the existing reward rule. Learning is an experimental condition, not an assumed gain.
-- Later **sensorimotor research profiles**: photoreceptors, mechanosensation, VNC outputs,
-  and possibly another neural model, each with its own identity and validation.
-
-Build weight≥1 and weight≥5 variants as **different graph identities** for the benchmark.
-Do not select a production cutoff until activity, retained connectivity, memory and speed
-have been measured. Preserve autapses by default in the new canonical graph; if an experiment
-removes them, record the policy. The claim that point-neuron models have no use for autapses
-is not a reason to discard observed connectivity silently.
-
-Schema-1 `i16` weights may be sufficient, but measure overflow rather than assume it. For
-the first existing-kernel comparison, emit a schema-1-compatible runtime view only if its
-quantization/clipping is explicitly reported. If wider weights are needed, implement an
-additive format/loader and matching oracle path; do not reinterpret old `weights.binz`.
-
-Strengthen validation before constructing a network: CSR starts at zero, is monotone, ends
-at edge count; targets/roles/visual indices are in range; required populations are present;
-geometry is finite where marked valid; array lengths and index widths are representable;
-declared hashes and artifact sizes match. Test the same invalid fixtures in both languages.
-
-### 3.5 Population and sensory mapping
-
-Existing role predicates cannot be copied unchanged. The current builder recognizes Codex
-names such as `Kenyon_Cell`, `brain_motor_neuron`, `DAN` and `PAM*`; MaleCNS uses another
-annotation vocabulary. Maintain a reviewed mapping table with source predicates, resulting
-counts, hemisphere policy, aliases, and citations. Resolve each profile's required roles
-at startup; an absent role must be an unsupported capability, not a silent empty population.
-
-In particular:
-
-- **Brain motor ≠ all motor.** Current macro pools combine 96 MBONs and 110 brain motor
-  neurons. Adding hundreds of VNC motor neurons under `motor` would silently change that
-  behavior. Use qualified roles such as `brain.motor`, `vnc.motor`, `brain.descending`,
-  `mb.kenyon`, `mb.output`, and `mb.pam` in new profiles, with legacy aliases only as needed.
-- **Action groups are not anatomical facts.** `command_*` buckets use index modulo eight;
-  `macro_*` groups use a round-robin MBON/brain-motor pool. Move their construction into a
-  versioned task readout profile, outside the anatomy builder. Do not describe those groups
-  as natural “attack,” “jump,” or game-objective circuits.
-- **Rate budgets are finite.** Both kernels currently cap tracked populations at 64. A
-  full CNS has many more interesting populations. Select a bounded control/telemetry set
-  initially; arbitrary bulk population analysis belongs in offline tooling. A larger mask
-  is a measured, oracle-tested change, not an unbounded string map in the tick loop.
-- **L1 first, photoreceptors later.** Reuse the existing luminance projection only after
-  auditing MaleCNS L1 hex coordinates, both sides, and a declared hex→2D transform. Soma
-  coordinates are not visual-field coordinates. Missing columns remain explicitly missing;
-  do not synthesize them from array order or infer them from another specimen's neuron IDs.
-- **Input profile and display view differ.** A game image may be resized/cropped for the
-  agent while the full frame is shown to viewers. Record crop, orientation, color transform,
-  and sampling geometry. Neither player may accidentally receive another player's private
-  view or adapter-only task observations.
-
-The existing `set_visual_frame` and `stimulate` API cannot represent a general collection of
-odor/touch/proprioceptive inputs. A later sensory-drive interface needs explicit units,
-target populations, additive/overriding rules, tick ordering, and deterministic noise streams.
-It must be specified in TypeScript before a matching Rust implementation. Keep the old
-image/stimulation path available byte-for-byte through its compatibility facade.
-
-### 3.6 What MaleCNS lets us investigate
-
-| Experiment | New capability | What still needs engineering/measurement |
-| --- | --- | --- |
-| Same game, another connectome | Compare datasets under a matched task interface | Cell-type mapping, gain/activity calibration, readout comparability, multiple seeds |
-| Brain↔VNC control | Read actual descending, ascending and motor populations | Body/control mapping; gamepad commands are not muscles |
-| Embodied fly arena | World smell/taste/touch/vision mapped into annotated sensory populations | Sensor transduction, proprioception and body dynamics; identify every reflex shortcut |
-| Mixed-dataset two-fly match | FAFB and MaleCNS agents share one environment | Balanced observations, controller mapping, compute budgets, intervention rules |
-| Circuit perturbation | Compare full graph with VNC feedback or defined pathways ablated | Separate graph identities; activity and behavioral controls; no biological claims from gameplay alone |
-
-The Minecraft project is a useful engineering comparison, not our validation oracle. It uses
-a Shiu-style current-based LIF model with synaptic dynamics/delay, reports gain calibration,
-and explicitly supplies odor-approach reflexes and higher-level looming drive where its
-simulated pathways do not work. Its source graph, numerical model and embodiment differ
-from ours simultaneously. Do not attribute its behavior solely to MaleCNS.
-
-### 3.7 Identity, restore, and performance
-
-Name the components independently:
-
-```text
-anatomyId     = source release + included inventory + graph/filter digest
-modelId       = numerical semantics + effective numeric configuration
-sensorId      = input encoding + anatomical binding digest
-readoutId     = population partition + decoder + action mapping digest
-learningId    = rule + selected-edge topology + reward-catalog identity
-viewerId      = positions/geometry + index mapping digest (presentation only)
-```
-
-The composite behavioral identity covers all behavior-affecting components; original source
-IDs and display geometry cannot replace it. Same neuron count does not establish compatibility.
-No FAFB neural checkpoint is restored into MaleCNS. A deliberately fresh MaleCNS brain may
-start from a compatible game-only save, with a new run identity, clean calibration and reward
-baselining; that is a new experiment, not continuation of the old fly. Gains are not mapped
-between specimens by cell-type name.
-
-For rough capacity planning, the current CSR is `4(N+1) + 6E` bytes, excluding roles,
-geometry, derived propagation structures and mutable state. At 176,422 neurons that is
-about 38.4 MB for 6.29 M edges, or 156.1 MB for 25.9 M edges (decimal MB). This is roughly
-2.3× or 9.6× our edge count, not a prediction of the same slowdown. Spike activity, fan-out,
-plasticity selection, memory bandwidth and sharding determine runtime cost. Checkpoint
-copies and renderer assets also need separate memory budgets.
-
-`LifNetwork` accepts shared `Arc<BrainDataset>` already. Reuse immutable anatomy across
-same-profile agents; keep membrane, refractory state, RNG, rates, decoder holds, stimulation,
-eligibility and learned gains private. Audit constructor-derived caches before moving them
-into a shared topology object. Never share mutable gains merely because graphs match.
-
-Measure headless one-, two-, and four-agent runs with plasticity on/off, fixed inputs and
-representative activity. Record resident/peak memory, initialization, state capture cost,
-per-phase p50/p95/p99, spike distribution, and real-time factor. Existing CUDA code is an
-optional backend requiring its own new-dataset equivalence/capacity gate, not assumed capacity.
-
-## 4. Reusable architecture
-
-### 4.1 Define the nouns first
-
-- **Dataset bundle:** immutable anatomical graph and source annotations.
-- **Brain profile:** dataset plus numerical model, sensory/readout bindings and learning rule.
-- **Agent:** one independently stateful brain, encoder, decoder and action executor.
-- **Environment:** the world being advanced: one emulator instance, a linked-emulator group,
-  or an embodied simulator. Owns controller ports, world state, media, and native clock.
-- **Task:** interpretation of environment state: rewards, progress, episode endings, allowed
-  macro actions and recovery policy. Pokémon is a task, not an environment API.
-- **Session:** one environment plus agents, port assignments, scheduler, task state and clocks.
-- **Application:** composes sessions/components and their presentation; owns supervision,
-  persistent identities/history, run/intervention rules and application-specific schemas.
-- **Bus:** generic RPC/pub-sub routing and artifact ownership, with no game/simulation semantics.
-- **Broadcast:** presentation of one or several sessions, plus chat and audience interactions.
-
-An agent ID is not a Twitch username, controller port, array position or dataset ID. Session,
-episode, agent, port, view, and event identities must be explicit and stable across restore.
-
-### 4.2 Dependency direction
-
-```text
-source importers → dataset bundles
-                         ↓
-                  neural core (TS oracle / Rust runtime)
-                         ↓
-             agent composition: sensors + readout + executor
-                         ↓
-environment backend + task plugin → session runtime → observations/checkpoints
-                                           ↑                  ↓
-                                    command admission   protocol adapters
-                                           ↑                  ↓
-                                      Twitch bridge        stage / recorder
-```
-
-The neural core knows no emulator, task, network socket, chat, or UI. The environment knows
-no neural populations or Twitch. The task may inspect backend-specific state through a
-typed inspector, but neither inspection nor public presentation gives clients a memory-write
-or controller-write API. Only the session commits agent-produced controls.
-
-### 4.3 Proposed modules and staged layout
-
-These are target responsibilities, not instructions to create every package immediately.
-Start as modules; extract crates/packages once a second consumer demonstrates the boundary.
-Keep the Rust workspace under `services/flysim` during semantic extraction so paths and
-behavior do not change together. A later mechanical move can place reusable crates at the
-root, updating CI/build/golden paths in one dedicated change.
-
-| Module / eventual location | Owns | Extraction source |
-| --- | --- | --- |
-| `packages/brain` | Reference numerical behavior and legacy public facade | Existing package; keep imports compatible |
-| `crates/flybrain-core` | Rust numerical kernel, plasticity, generic population decoder | Existing `core/`; leave compatibility re-exports for presets |
-| `crates/fly-dataset` | Manifest validation, artifact loading, source-ID/index mapping | `core/src/dataset.rs`; retain legacy fingerprint implementation |
-| `crates/flybus` | One Rust RPC/pub-sub client/router, immutable artifact store, delivery guards and GC | New generic library; embedded router or small executable, no separate worker transport |
-| `tools/datasets/{fafb,malecns}` | Source-specific conversion to common bundles | Existing Python builder plus new importer; existing CLI wrapper remains |
-| `crates/fly-session` | Agent ownership, clock coordination, action commit, event/reward routing | Orchestration extracted from `sim/src/simloop.rs` |
-| `crates/fly-environment` | Backend capabilities, ports, observations, media, save-state interfaces | New small contract proven with binjgb and synthetic arena |
-| `crates/fly-env-gb` | binjgb FFI, memory inspector and native save-state identity | `gb/src/{emulator,ffi}.rs`, build glue and vendor boundary |
-| `crates/fly-task-pokemon`, `fly-task-platformer` | Audited reward rules, semantic state, macros, progress/recovery | `gb/src/{pokemon_red,platformer}/`; do not generalize tile routing into the core |
-| `crates/fly-checkpoint` | Atomic storage and session envelope; legacy payload adapter | `sim/src/store.rs` plus core envelope helpers |
-| `crates/fly-protocol` / `packages/feed` | Versioned wire schemas/codecs, legacy adapters, synthetic fixtures | `sim/src/snapshot.rs`, existing feed package; canonical schema with cross-language tests |
-| `services/flysim` | Composition/config, HTTP/WS, process lifecycle, metrics | Thin host over reusable session library |
-| `packages/stage-runtime` | Feed ingestion, per-session stores, paint loop, audio, fixture clock | Extract from `apps/stage/src/{feed,paint,audio,motion}` after multi-view prototype |
-| `apps/stage` + presentation plugins | Layout, branding, task panels, audience-facing explanations | Existing page with legacy layout preserved |
-| `services/bridge` + audience client module | Twitch transport/auth/redemptions; session-targeted interaction client | Existing bridge; extract provider-independent logic only when reused |
-| `infra/` | Release composition, process supervision, capture, recordings | Existing tooling parameterized by session/broadcast manifest |
-
-Use static Rust composition or a small closed registry initially, with trait boundaries at
-backend/task seams. Do not require stable native dynamic-plugin ABI. An out-of-process
-emulator helper implements the backend through Flybus RPC, using the same bus as application
-events and publication. Native emulator protocols stay inside its adapter. This is not a
-new public action API or a reason to maintain a second framework transport.
-Keep backend-specific memory access private to its task implementation instead of widening
-`read8(u16)` into a supposedly universal game-state abstraction.
-
-### 4.4 Environment and agent contracts
-
-Illustrative interfaces; concrete types must be written with tests during contract work:
-
-```rust
-trait Environment {
-    fn descriptor(&self) -> &EnvironmentDescriptor;
-    fn observe(&mut self) -> Result<WorldObservation>;
-    fn advance(&mut self, actions: &ActionBatch) -> Result<WorldStep>;
-    fn capture(&mut self) -> Result<EnvironmentCheckpoint>;
-    fn restore(&mut self, state: &EnvironmentCheckpoint) -> Result<()>;
-}
-
-// One decision boundary, one action per configured controller port.
-struct ActionBatch {
-    session_tick: u64,
-    ports: Vec<PortAction>,
-}
-```
-
-`descriptor` declares rational step duration, controller schemas, views, audio streams,
-save/restore availability, task inspection capabilities and determinism level. Capture and
-restore return an explicit unsupported error when unavailable; configuration validates that
-the chosen recovery policy can work. `WorldObservation` is a frame-boundary snapshot or
-immutable handle, not an object allowing agents to advance the backend.
-
-Control schemas support digital buttons and bounded analog axes/triggers, with neutral
-values, axis ranges, dead zones, and mutually exclusive directions where appropriate.
-Preserve the Game Boy mask as one concrete codec. Analog controls need a fixed, versioned
-decoder mapping; an 800-ms direction hold is not a sensible default for every fighting game.
-
-Separate three observation surfaces:
-
-1. **Agent sensory view:** pixels or declared synthetic senses the profile may consume.
-2. **Task inspector:** audited state for reward/macro/episode logic. Access is part of the
-   disclosed scaffold, not implicitly available to the neural encoder.
-3. **Broadcast view:** media and summaries for viewers, potentially richer than either player's
-   allowed sensory input.
-
-Readout produces semantic channel activations or continuous signals. A task-local action
-executor translates these into port actions, optionally running a selected macro. It is
-explicitly resettable/checkpointable and reports selected action versus actual controller
-output. Pokémon pathfinding, dialog logic, and objective catalogs stay in its task plugin.
-
-Task outputs become scoped `RewardEvent`, `Progress`, `EpisodeEvent` and `ActionAvailability`.
-Progress is a tagged value (`ladder`, `score`, `match`, `exploration`, or task extension), not
-always a scalar rank. Rewards carry recipient agent/team, rule ID, event ID and observation
-tick. A task cannot mutate neural state directly; the session routes accepted rewards once.
-
-An agent-facing API similarly separates `advance_brain(interval)`, `decide(observation,
-availability)`, `encode_next(sensory_view)`, and `apply_outcome(rewards, stimulation)`.
-The session owns their order. Agents cannot call `Environment::advance`, select another
-port, or inspect another agent's mutable state. Start with a concrete LIF agent composition;
-introduce a controller trait when synthetic controllers or a second neural model require it.
-Test controllers implement the same decision surface but are identified as non-neural agents
-in descriptors and experiment records.
-
-### 4.5 Example composition
-
-Illustrative configuration, not syntax supported by today's `flysim.toml`:
-
-```toml
-[session]
-id = "arena-demo"
-environment = "synthetic-arena-v1"
-task = "two-player-rounds-v1"
-scheduler = "lockstep-v1"
-master_seed = 1234
-recovery = "round-reset-keep-gains-v1"
-
-[[agents]]
-id = "fly-a"
-port = "player-1"
-profile = "fafb-arena-baseline-v1"
-sensory_view = "shared-camera"
-
-[[agents]]
-id = "fly-b"
-port = "player-2"
-profile = "malecns-arena-baseline-v1"
-sensory_view = "shared-camera"
-
-[broadcast]
-layout = "shared-match-two-agents"
-audio = "world"
-audience_stimulation = false
-```
-
-Resolve profile IDs through a local, digest-pinned registry. Both agents may instead select
-the same profile and share immutable topology while retaining independent state. The host
-validates unique agent IDs and exclusive port ownership, view accessibility, profile/controller
-compatibility, recovery capability and resource budget before starting. An independent-games
-broadcast composes two such sessions; it does not misrepresent them as ports in one world.
-
-## 5. Multiple flies: concurrency is not multiplayer
-
-### 5.1 Three supported arrangements
-
-| Arrangement | Ownership / synchronization | First use |
-| --- | --- | --- |
-| Independent flies in independent games | One session/process each; optional broadcast composition | Parallel streams and experiments; existing deployment pattern generalizes easily |
-| Several flies in one game | One environment, several ports, one session barrier | Local fighting/multiplayer games |
-| Linked emulator instances | One composite environment owns all instances and link state | A later link-cable experiment; requires cycle-accurate link support, not two independent frame loops |
-
-For a shared arena there must not be one `Sim` loop per player, each calling `run_frame`.
-That advances the world multiple times and gives an ordering advantage to one agent.
-
-### 5.2 Shared-world step semantics
-
-For decision boundary `t`, freeze observation `O[t]`, then:
-
-1. Admit queued audience/operator commands against stable session/agent identities; log their
-   effective tick. Chat remains presentation state.
-2. Each agent advances its brain for the same environment interval, using its previously
-   encoded sensory input. Its clock remainder and RNG are private.
-3. Each agent decodes and advances its action executor using the same `O[t]` task boundary.
-4. Barrier: collect all port actions, validate ownership/ranges, and commit one complete batch.
-5. Advance the environment **once** to obtain `O[t+1]` and timestamped media.
-6. Encode the next sensory inputs, evaluate task events from the completed transition, apply
-   explicitly routed stimulation and rewards, and compute next action availability.
-7. Apply any whole-session episode/recovery transition; capture coherent state and publish.
-
-Preserve the detailed legacy ordering inside the legacy single-agent composition. New
-profiles identify their scheduling semantics explicitly rather than silently adopting a
-different reward phase. Use rational environment time and integer substep accumulation for
-new sessions; keep the legacy floating remainder arithmetic for old trajectories. The neural
-clock may lead environment time by warm-up; persist that offset instead of pretending all
-clocks start at zero. Rendering, physics and decision cadence may differ, but the backend
-must define their relationship.
-
-Start with sequential agent evaluation for reproducibility. Then compare parallel agent
-evaluation against the same action trace. Cap total worker budget: `agents × brain_threads`
-can otherwise oversubscribe the machine. Use private pools for concurrent agents or serialize
-dispatch into a pool; the current `WorkerPool` must not be concurrently reused through a
-cloned `SweepPlan`. Sharing immutable graph buffers is independent of scheduling workers.
-
-If one agent is late, the default is to slow the **whole session** and report lag. A crashed
-agent pauses/fails the match rather than silently becoming a neutral or scripted opponent.
-A realtime external world that cannot pause requires a separate declared deadline/hold-last
-policy, dropped-action telemetry and a different determinism claim. Do not hide that policy
-inside the environment adapter or use wall-clock completion order as an action tie-breaker.
-
-### 5.3 Match state and learning
-
-Every agent has its own seed, calibration, gain vector, eligibility, reward totals and
-stimulation cooldown. Derive seeds deterministically from a stored master seed and stable
-agent ID; do not use thread scheduling or the default identical seed for every fly.
-
-For an initial fighting-game task:
-
-- Both agents receive the same shared camera unless the game has genuine private views.
-- Controller-port swaps and seed repeats are part of evaluation; wins alone are confounded
-  by character, spawn, arena, action interface and side advantage.
-- Award positive, explicitly attributed events such as a scored hit/round win; define
-  damage/self-damage/team attribution and duplicate detection before turning learning on.
-  A loss need not produce a negative reward; changing reward doctrine is a separate decision.
-- Episode transitions may retain learned gains while clearing transient traces, or create
-  fresh brains for controlled trials. Record which policy was selected.
-- Do not select a “best checkpoint” separately for each player in a shared world. There is
-  one world state. Tournament scores and historical results should not rewind with a match.
-- Disable sugar for balanced evaluation. If enabled for a show, target a named agent under
-  a documented rule and log the intervention; do not call that an uncontrolled fair benchmark.
-
-### 5.4 Checkpoint and recovery semantics
-
-Distinguish three operations:
-
-| Operation | Restored/reset state |
-| --- | --- |
-| Crash resume | Coherent environment, every agent, scheduler remainders, task ledgers, pending actions/commands and executor state at one boundary |
-| Task recovery | Policy-defined world rewind/reset and per-agent transient clearing; continued gains/brain clocks only when declared, as in the legacy ratchet |
-| New episode | Task initial world state, explicit retained/fresh agent policy, new episode identity; session event sequence remains monotonic |
-
-Use a new session envelope version with a manifest mapping stable agent IDs to chunks and
-listing graph/model/profile/backend/content/task/state-format identities. The current
-envelope restricts chunk names to letters; do not simply append `agent/1/membrane` to it.
-Specify a new container format or an explicit manifest-to-valid-chunk-name indirection.
-
-Validate every participant into staged state before mutating any live participant. A failed
-environment import must not leave half the brains restored. For an external emulator,
-restore a replacement stopped process when transactional in-place validation is impossible.
-Capture at the action barrier with no backend step in flight. Reuse atomic payload write,
-manifest commit, hot/durable tiers and off-thread serialization; bound outstanding snapshot
-jobs so repeated copies cannot exhaust memory under slow storage.
-
-Exact replay requires action-executor and admission state, not just the neural envelope.
-Legacy macros intentionally discard transient execution on restart; preserve that behavior
-for v1 and label it as legacy continuation semantics, not exact session replay. New sessions
-persist all behavior-affecting state or explicitly restart an episode under a documented rule.
-
-Keep `FLYSIM01` readable through a legacy adapter. Never silently rewrite a checkpoint on
-read. Conversion is an explicit offline operation writing a new directory and run record.
-Environment identity includes title/content digest, backend build/configuration, relevant
-platform/native state format, and patch/symbol provenance; state size alone is not sufficient.
-
-## 6. Feed, stage and audience modules
-
-### 6.1 Feed v2 is required
-
-V1 is not a generic multi-agent format. Its attachment map forbids duplicate kinds, so two
-`spikes` arrays cannot coexist; its button mask and 160×144 image are Game Boy-specific.
-Platformer counters are currently folded onto names such as `pokedex` and `wildwin`.
-Extending those conventions to fighting games would preserve syntax while losing meaning.
-
-Keep v1 stable for the legacy session. Introduce a negotiated v2 or a separate `/v2/feed`
-endpoint, with a descriptor delivered before dependent snapshots and available on reconnect.
-This is the application's browser/presentation gateway over Flybus, not another internal
-bus. Native participants use the same RPC/pub-sub protocol for all framework communication.
-The contract change must update Rust, TypeScript, schema, fake service, fixture player,
-stage and bridge together. Proposed shape:
-
-```text
-SessionDescriptor
-  sessionId, protocol, descriptorRevision, environment/task identities, clock definition
-  agents[{agentId, profileId, datasetId, neuronCount, roles, controlPort}]
-  ports[{portId, controllerSchema}]
-  views[{viewId, dimensions, pixelFormat, sensory/broadcast use}]
-  audioStreams[{streamId, sampleRate, channels}]
-  assets[{id, contentHash, datasetIndexHash, localUrl, license/credit}]
-
-SessionSnapshot
-  descriptorRevision, seq, sessionTick, episodeId, environmentTime, wallTime, status
-  agents[{agentId, brainTime, rates, learning, selectedAction, actualControls, stimulation}]
-  progress: tagged task payload; events: scoped and sequenced
-  attachments[{id, kind, ownerId, byteLength, format, mediaTimestamp}]
-```
-
-Use bounded, schema-validated tagged payloads/namespaced task extensions, not arbitrary
-unlimited JSON or executable server-supplied UI. Dataset identity and neuron index mapping
-must accompany spike geometry: matching bitset length alone cannot establish alignment.
-Include descriptor revision in every snapshot and reject stale/mismatched buffers. Large
-monotonic IDs/times use a specified safe-integer bound or decimal strings across languages.
-
-Publish one shared camera/audio stream once, not once per agent. Independent sessions may
-have independent streams. Timestamp audio/video to the session clock; define discontinuities
-on reset, reconnect and lag. Latest-value video/telemetry may drop, while audio needs a
-bounded timestamped buffer and explicit gap handling. Durable event IDs permit recovering
-missed events; a drop-oldest snapshot feed is not an exactly-once event log.
-
-At 640×480 RGBA, native frame production is 36.864 MB/s at 30 Hz or 73.728 MB/s at 60 Hz.
-Publish one immutable artifact and pass owned references through Flybus to all consumers.
-Bytes stay outside router messages; producer/read/copy costs still need measurement. A
-renderer retains its handle past message drop; cached RPC results and latest retention also
-own data until release. Last-owner GC replaces coordinator-managed slots/reader acknowledgments.
-Resizing, overlays, codecs and streaming are presentation-layer choices, not bus requirements.
-
-### 6.2 Stage composition
-
-Extract `createSessionStore()` rather than adding `agent2` fields to the singleton `hot`.
-Own rate scalers, button afterglow, ticker state, fixture clock and audio queues per session/
-agent. Keep one page paint scheduler; register surfaces against explicit view/agent IDs.
-Geometry is loaded by descriptor/hash through an asset manifest, replacing the hardcoded
-FAFB route in both `App.tsx` and `vite.config.ts`.
-
-Retain the existing Game Boy layout as a presentation plugin. Add composition primitives for
-a shared match view with two agent summaries, or independent session tiles with one focused
-audio source. A generic fallback shows status, media, controls and task labels without
-inventing Pokémon counters. Unknown optional extensions can be omitted; unknown required
-capabilities or mismatched descriptors must be visible rather than silently showing Pokémon.
-
-Combine common framework measurements with application-owned state/events. Describe values
-by owner, type, units, range and timestamp; distinguish zero, unknown, unsupported and stale.
-Game-specific progress/collections remain validated schema extensions. The application defines
-its supervisory/story behavior alongside its UI, not inside a mandatory generic Director service.
-
-Keep UI runtime dependencies out of the numerical package. The current `@flybrain/brain`
-view exports and optional Three.js peer can remain compatibility re-exports when viewer
-geometry/helpers move to a dedicated view module. Controller labels belong in controller
-schemas, not a UI import of the neural package's Game Boy preset.
-
-Review actual layout proposals as PNGs under `apps/stage/mockups/`, with existing legibility,
-phone-scale and browser gates. This document proposes data/layout boundaries, not screen
-copy or a replacement for visual sign-off.
-
-### 6.3 Audience interaction
-
-Keep Twitch authentication/EventSub and template-only replies in the application bridge. Extract a
-session-targeted interaction client with explicit `sessionId`, optional `agentId`, interaction
-kind and idempotency key. A multi-agent request with no target is rejected unless a fixed,
-declared target policy exists; presentation focus must never choose the recipient.
-
-Service admission owns per-session, per-agent and global limits. A profile advertises its
-supported stimulation capability; an agent without PAM support returns unsupported rather
-than pretending to accept “sugar.” `!stuck` becomes task-aware (ladder time versus round
-time), while chat remains broadcast-scoped and independent of neural state. Future boons
-use task/backend-declared capabilities with explicit target, timing and outcome; gifts do
-not automatically become earned learning rewards. These need separate capability/admission
-contracts before enabling them, carried over the same bus rather than an arbitrary write API.
-
-For redemptions, persist the resolved target and request identity before retrying. Distinguish
-an RPC timeout (HTTP on legacy v1) from a definite refusal: it may occur after the sim accepted the
-effect. V2 needs a durable or explicitly recoverable deduplication/status contract so bridge
-restart cannot apply the same pulse twice or retarget a redemption to a new match. Do not
-promise exactly-once behavior from the bridge intent log alone. Existing v1 remains as-is.
-
-### 6.4 Deployment and observability
-
-A deployable composition selects runtime binary, backend/task, agent profiles, dataset
-bundles, view assets, session state namespace and broadcast layout. Generate service config
-from that manifest plus the operator's external environment. Keep tokens and network-specific
-values outside this repository. Package viewer artifacts separately from the full simulation
-graph so the browser does not need every edge.
-
-Preserve existing process isolation: sim, bridge, browser, capture, local relay and Twitch
-push can restart independently. One coordinator/session with separate worker processes is
-the default composition; a shared match remains one logical failure/recovery group across
-those workers. A worker restart cannot silently rejoin. Router failure also invalidates its
-ephemeral handles/routes. Multi-session placement and presentation composition are application
-deployment concerns; router scope sets an explicit shared-failure boundary.
-
-Metrics distinguish session lag, environment step cost, per-agent step cost, barrier wait,
-snapshot drops, audio discontinuities, checkpoint queue age and resource budget. Bound agent
-labels to configured IDs; never label metrics by viewer name or arbitrary event text.
-Health must distinguish paused, slow, disconnected backend and dead agent. A generic
-watchdog cannot treat “no new Pokémon tiles” as a stall detector for all tasks.
-
-Deployment preflight checks every referenced profile/bundle and complete checkpoint identity
-before selecting a release. Switching the binary back does not convert newer state: retain
-the previous release's state namespace for rollback. Twitch publishing still requires the
-operator's explicit approval for that run; implementation benchmarks use local sinks.
-
-## 7. Cleanup strategy: extract, then reorganize
-
-Prioritize coupling that prevents a second application, rather than renaming everything.
-
-1. **Characterize behavior and identify state owners.** Capture deterministic synthetic
-   observation→action→reward traces and legacy restore outcomes before moving code.
-2. **Remove task construction from anatomy.** Introduce separately hashed readout bindings;
-   leave the current artifact and macro-role merge path frozen for legacy compatibility.
-3. **Extract orchestration from transport.** A session step returns observations/events and
-   capture requests; it does not serialize HTTP/feed headers. `flysim` owns listener setup,
-   wall-clock publication and systemd integration.
-4. **Split emulator from task.** Move binjgb behind an environment implementation, preserving
-   FFI/cache behavior. Move map/exit/objective queries into Pokémon task interfaces rather
-   than forcing every future game to implement them.
-5. **Split task recovery from storage.** The ratchet decides a task transition; storage
-   commits an opaque coherent capture. Matches use round resets, not milestone archives.
-6. **Version observation/control at the boundary.** Internal typed session snapshots become
-   v1 or v2 through adapters; core modules do not depend on wire enums.
-7. **Make stage state instantiable and assets descriptor-driven.** Preserve hot/cold cadence
-   and fixture determinism while removing singletons and hardcoded dataset selection.
-8. **Only then move directories/extract packages.** Keep re-exports/CLI wrappers during the
-   move, fix build/CI/vendor paths, and compile tiny consumers proving Rust/TS libraries can
-   be used without starting Twitch, a browser, or an emulator.
-9. **Reconcile documentation.** Separate current contracts/reference from dated deployment
-   history. Audit contradictory “raw buttons only,” weighted-macro, throughput, token/setup,
-   and training-improvement claims against code. Update templates and scientific limitations
-   with actual profile capabilities, not a new generic claim of biological fidelity.
-
-Do not introduce a generic reward engine, universal memory address model, central plugin
-marketplace, or per-neuron network transport. Those abstractions have no demonstrated second
-consumer and would obscure the useful, small seams already present.
-
-## 8. Implementation plan and acceptance gates
-
-Each row is a reviewable change or small workstream, not one large feature branch. Follow
-the repository's branch/worktree build-and-review workflow. Contract changes precede their
-consumers. No estimate here assumes an emulator backend or biological mapping already works.
-
-| Phase | Deliverable and principal files | Dependencies | Acceptance / stop condition |
-| --- | --- | --- | --- |
-| P0 — baseline | Trace fixtures and boundary tests around `Sim::step_frame`, restore, dataset loader, stage singleton behavior; current-state documentation inventory | None; reconcile open branches first | Current TS/Rust goldens and legacy API/feed fixtures pinned; behavior ledger distinguishes intentional transient reset from exact replay |
-| P1 — identities | Dataset/profile manifest, role resolver, behavior hash, synthetic fixtures; new strict validators in both languages | P0 | Missing/ambiguous roles fail; wrong profile refuses restore; FAFB legacy fingerprints/version strings unchanged |
-| B1 — Flybus | Small Rust router/client with RPC, pub/sub, owned artifacts and GC; see BUS-01..03 in the contract implementation guide | Can start alongside P0/P1; no dataset/emulator dependency | Same semantics in-memory/Unix sockets; cache/retention holds safe; 480p three-reader test; no raw binary in message envelopes |
-| M1 — MaleCNS import | `tools/datasets/malecns`, source lock, inventory/exclusion report, schema-compatible baseline bundle, attribution | P1 | Counts reconcile to selected inventory; reproducible output hashes; graph invariants and both loaders agree; no runtime downloads |
-| M2 — headless characterization | Profile-specific L1/sensor binding, role/readout audit, learning-off/on benches and new goldens | M1 | Stable/finite activity measured over repeated seeds; no silent empty populations; exact TS/Rust state agreement; unsupported inputs remain marked unsupported |
-| M3 — task integration | Explicit MaleCNS profile selected by service config and matching stage assets, fresh state namespace | M2 and minimal descriptor/asset support from P5 | Fresh brain on audited game state; sugar capability verified; stage index/geometry identity correct; one-hour local soak plus restore drill; no automatic promotion over FAFB |
-| P2 — environment/task split | Environment contract, binjgb wrapper, task-specific inspector; facade for existing `flybrain-gb` imports | P1 | Legacy action/reward traces identical; ROM-free tests pass; optional ROM-backed sample confirms stepping/audio/state behavior |
-| P3 — session library | Single-agent session owns clocks, agent/task/executor state; service composes bus-connected workers | P2, B1 | Same legacy order and compatibility; renderer/bridge restart leaves run intact; fake backend runs without binjgb/ROM/Twitch |
-| P4 — multi-agent + persistence | Two-agent synthetic arena, action barrier, isolated state, session envelope/recovery and failure behavior | P3 | One world step per batch; no port/order advantage; resume/parallel-vs-sequential equivalence; failure cannot partly commit a match |
-| P5 — feed/control v2 | Descriptor, scoped snapshots/events/media, targeted stimulation and idempotency, TS/Rust schema fixtures/fake server | P1, P3; validate with P4 fixture | V1 still works for legacy; multi-agent attachments cannot collide; unknown target/profile rejected; retry/reconnect tests pass |
-| P6 — modular stage/bridge | Instantiable stores, dataset assets, shared/independent views, target-aware commands/redemptions | P4–P5 | PNG review for two-agent layout; browser legibility/fixture tests; correct audio ownership and no agent cross-talk |
-| E1 — new emulator spike | Select title/backend; bus-connected helper or native wrapper; record native frame, ports, inspection and restore capabilities | P2, can run beside P4–P6; framework integration uses B1 | Reliable bounded step + simultaneous controls, pinned content/backend identity, reproducible state round trip; stop before task implementation if unavailable |
-| E2 — fighting-game vertical slice | Two flies, chosen game task, analog/digital readout, episode logic, attributed rewards, match view | E1, P4–P6 | Repeated local matches and side swaps; measured compute headroom; documented scaffold and interventions; win-rate claims require controls |
-| P7 — packaging/reorg | Optional root Rust workspace move, library consumers, profile-based release/asset manifests, updated infra and docs | Useful second backend + P6 | Four merge suites and affected browser gates pass; old composition deploys locally; preflight rejects incompatible multi-agent state |
-
-M3 may use a small v1-compatible **additive descriptor extension**, if contracts and both
-consumers are updated and the existing frame semantics stay unchanged. It must not publish
-MaleCNS spikes under implicit FAFB geometry. Full multi-agent publishing still requires v2.
-
-### 8.1 A concrete first alternative-emulator spike
-
-Before committing to Melee/Dolphin or an N64 backend, establish:
-
-- An exact title/version and backend revision, available to the operator externally.
-- A supported pause/advance boundary with all configured controller ports applied together.
-- Whether rendering is required for stepping and whether frame capture is synchronous.
-- Sample rate/channel metadata, audio latency and timestamps.
-- Analog sticks/triggers and button semantics; neutral state on disconnect.
-- Save-state completeness, version/platform constraints and reproducibility after restore.
-- Supported task-state inspection (match/round/port state) without guessing memory offsets.
-- Headless/runtime packaging, process lifecycle, resource cost and failure behavior.
-
-A library used for competitive tooling may expose controller and game-state APIs without
-supporting arbitrary frame stepping or faithful visual capture. Verify capabilities instead
-of assuming its name solves integration. Prefer a pinned private backend process if native
-embedding would force emulator internals into our Rust runtime. Desktop keyboard automation
-is unsuitable for simultaneous deterministic multi-port input.
-
-Start with synthetic constant/alternating controller traces and a test opponent before neural
-control. Such traces are backend tests, not public “fly playing” footage. Then validate one
-agent, two agents, episode boundaries, crashes and resume in that order. No copyrighted game
-content is added to source control or test fixtures.
-
-### 8.2 Validation matrix
-
-**Numerical/format:** existing `core/tests/golden_{toy,real,agent,restore,platformer,versions}.rs`
-remain gates. Add pinned MaleCNS subgraph fixtures and a full-artifact optional golden run,
-with generated TS goldens and exact Rust comparisons. Include malformed CSR, missing roles,
-wide IDs, hemisphere/coordinate errors, overflowing weights, and graph/profile mismatch.
-The subgraph tests prove arithmetic/loader agreement, not full-CNS dynamics.
-
-**Scheduler:** synthetic backend asserts one advance per complete batch; swap agent evaluation
-order, vary worker count, and inject a late/failing participant. Check equal observation
-boundaries, deterministic seeds, no cross-agent gains/holds/stimulation, correct tick remainder,
-and no reward twice at an episode boundary. Mixed profiles are allowed only if their clocks
-and capabilities satisfy the same session contract.
-
-**Persistence:** kill/fault injection around capture/write/manifest commit; corrupt one agent
-chunk, backend state or profile hash; verify all-or-none restore and fallback reporting.
-Compare uninterrupted and resumed new-session action/state traces. For legacy runs compare
-against the documented transient-reset behavior instead of demanding a newly invented one.
-
-**Protocol/UI/bridge:** cross-language v1/v2 fixtures; two agents with different neuron counts;
-shared and private views; out-of-order descriptor/media, missing optional attachments, stale
-snapshots and reconnect; replay seeking; duplicate redemption, lost HTTP response and bridge
-restart; explicitly unsupported stimulation. Visual changes require PNG review and browser
-tests, not prose approval of a hypothetical layout.
-
-**Performance/science:** benchmark full graph and thresholded graph with learning disabled
-and enabled, fixed sensory traces, multiple seeds and side swaps. For game-performance
-claims compare against random/readout baselines and learning-off, reporting scaffold,
-recovery, intervention and episode policies. Measure sustained real-time factor and tail
-latency under two/four flies plus actual browser/capture load; do not extrapolate a single
-kernel throughput figure to an entire show. Initial target is ≥1.0× sustained at the declared
-agent count with p99 step time within its cadence budget and no growing queues; select a
-resource/headroom margin from the measured backend before release.
-
-Before each merge run the repository-required `npm test`, `npm run typecheck`,
-`cargo test --workspace` from the Rust workspace, and `infra/tests/lint.sh`. Run affected
-Playwright/PNG gates for stage changes. The existing committed FAFB real-data goldens remain
-mandatory. New full-MaleCNS integration jobs and ROM-backed tests are explicit optional jobs
-with recorded skips, never a hidden network/ROM dependency of normal CI.
-
-## 9. Decisions and open questions
-
-**Recommended decisions now:** preserve FAFB as the baseline; use official MaleCNS provenance;
-freeze legacy arithmetic/identities; version profile behavior independently; make environment
-and agent separate objects; use one session barrier for a shared match; retain static plugins
-and process/session isolation; introduce v2 instead of stretching Game Boy fields indefinitely.
-
-**Questions answered by spikes rather than assumptions:**
-
-1. Which MaleCNS neuron inventory and confidence/threshold policy will be the published bundle?
-   Can we explain the differing inventories and quantify left/right sensory coverage?
-2. Do existing LIF parameters give useful, stable activity on MaleCNS? If not, which explicit
-   profile calibration is justified, and does a different neural model warrant separate work?
-3. Are verified L1 mappings adequate, or is the intended project really an embodied sensory
-   simulation requiring new encoders and VNC feedback?
-4. Which Smash title/backend can satisfy deterministic stepping, simultaneous ports, media
-   capture and restoration at acceptable cost?
-5. How many simultaneous brains fit the actual budget, with which mix of within-brain versus
-   between-brain workers? Is a compressed media path required?
-6. Which match reset/learning/intervention policy defines the show, and which defines a
-   controlled comparison? They should be separate run configurations.
-
-Success is not just “another connectome loads” or “a second pad moves.” It is a new session
-assembled from modules whose anatomy, numerical model, controller, task, recovery and
-presentation assumptions are explicit, testable and reusable without changing the old fly.
-
-## 10. Sources and scope of the analysis
-
-Repository evidence is enumerated in section 2 and tied to the baseline commit above. Existing
-reference documents: [dataset format](../dataset-format.md), [model](../model.md),
-[plasticity](../plasticity.md), [readout](../readout.md), [limitations](../limitations.md),
-[macros](macros.md), [architecture tour](../architecture-tour.md), and
-[contribution/compatibility rules](../../CONTRIBUTING.md). Historical status notes are not
-evidence that an unmeasured experiment succeeded.
-
-External sources inspected 2026-09-18:
-
-- [Official MaleCNS overview](https://www.janelia.org/project-team/flyem/male-cns-connectome):
-  anatomical coverage, collaboration, release dates and licensing statement.
-- [Official MaleCNS downloads](https://male-cns.janelia.org/download): versioned bulk tables,
-  confidence cutoffs, segment versus neuron distinction, coordinate units and API guidance.
-- [FlyWire overview](https://flywire.ai/): FAFB reconstruction provenance and brain coverage.
-- [Codex dataset listing](https://codex.flywire.ai/): portal inventory counts, which are not
-  assumed to be identical to neuPrint query inventories or local runtime graphs.
-- [Minecraft fly README](https://github.com/blendi-remade/fly-brain-minecraft/blob/main/README.md)
-  and [provenance](https://github.com/blendi-remade/fly-brain-minecraft/blob/main/PROVENANCE.md):
-  a separately authored MaleCNS derivative, thresholding and mapping decisions, and disclosed
-  sensory/motor limitations. These moving links are comparison material, not a locked data
-  dependency; M1 must acquire its own official source lock.
-
-This analysis reads the current implementation and upstream documentation. It does not
-download/build the full MaleCNS dataset, independently validate the Minecraft benchmarks,
-run a new emulator, or establish a performance/behavioral improvement. Those are explicit
-deliverables with gates above.

docs/design/melee-framework-audit.md

@@ -1,766 +0,0 @@
-# Melee: multi-fly runtime, emulator and broadcast audit
-
-Status: **research and proposed implementation plan**. Written 2026-09-18 against local
-`f7bc13a`. Extends the [modular-session design](malecns-modular-sessions.md) and
-[implementation backlog](malecns-modular-implementation.md) with a concrete second game.
-Existing [feed](../feed-protocol.md) and [control](../control-api.md) contracts still win.
-No emulator, game image, deployment host or live broadcast was run for this audit.
-
-Follow-on [session framework contracts](session-framework/README.md) define the concrete
-multi-process synchronization and worker interfaces this backend will implement.
-The subsequent [Flybus decision](session-framework/bus-v1.md) selects one small Rust router
-for RPC and pub/sub, with immutable artifacts outside messages and delivery-scoped GC.
-The application owns supervisory/presentation behavior; the bus owns no game or stream logic.
-
-## 1. Executive decision
-
-**Use Dolphin, initially a pinned mainline-based Slippi Dolphin build, as a separate backend
-process. Use the maintained libmelee fork to accelerate the integration spike. Keep the
-brains and session coordinator in Rust.** Prove its synchronization, rendered sensory input,
-and recovery behavior before selecting a production build. Keep stock Dolphin plus a narrow
-backend hook as the fallback if the Slippi path cannot satisfy those requirements cleanly.
-
-Do not port Melee to native code, embed Dolphin into the neural crate, run one emulator per
-fighter, or assume “libmelee has `step()`” supplies the complete environment contract.
-
-Recommended first target:
-
-- Melee US 1.02, local two-player versus, one emulator and two independently stateful flies.
-- Existing FAFB brains first. MaleCNS is an independent axis of experimentation, not a
-  prerequisite for solving the emulator and multiplayer problems.
-- Fixed declared characters, stage, stock/time rules and input profiles; no netplay rollback.
-- Pixel-based sensory input with an explicit resolution/aspect transform; state inspection
-  is for task measurement, match lifecycle and display, not a hidden fighting policy.
-- Fixed GameCube controller readout with bounded analog values and short frame-based holds.
-- Native-resolution rendering initially, local broadcast at 30 fps first; simulation/input
-  continue at the backend's approximately 60-Hz cadence. Promote to a 60-fps show only after
-  the full media path and encoder are verified.
-- Two-fly synthetic arena remains the framework test case before game integration.
-
-The important scaling change is **one environment with many agents**, not simply a larger
-ROM. Disc size is mostly a loading/storage concern. Runtime cost comes from PowerPC emulation,
-graphics/audio, multiple neural simulations, synchronization and media copies.
-
-### Confidence labels used below
-
-- **Observed in source:** checked implementation or explicit upstream documentation.
-- **Recommended:** proposed architecture/configuration, not implemented here.
-- **Must measure:** cannot be established by reading code, including throughput, latency,
-  correct input-to-frame association and reliable recovery on the target platform.
-
-## 2. What the Melee decompilation gives us
-
-The supplied [doldecomp/melee](https://github.com/doldecomp/melee) repository is a matching
-decompilation of **US 1.02**. Its README is `.github/README.md`, not the repository-root
-`README.md`. The inspected revision is recorded in section 13.
-
-The README and `config/GALE01/config.yml` identify the matching `main.dol` SHA-1 as
-`08e0bf20134dfcb260699671004527b2d6bb1a45`. That identifies the executable, **not the entire
-disc image**. Our run manifest must separately identify externally supplied game content,
-effective executable, modifications, emulator build and task interpretation.
-
-The decomp builds a GameCube executable, not a supported desktop port or emulator replacement.
-The `dolphin` code within that source tree refers to Nintendo's SDK, not the Dolphin emulator
-project. Rebuilding/relocating a DOL for instrumentation changes address identity; never use
-stock symbol addresses on a shifted build.
-
-### 2.1 Useful inspection map
-
-| Upstream source | What was observed | How it helps our task |
-| --- | --- | --- |
-| `config/GALE01/{config.yml,symbols.txt}`; `docs/symbols.md` | Matching binary identity and named symbols with addresses, sections and attributes | Reproducible symbol/inspection manifest analogous to the Pokémon symbol generator |
-| `src/melee/pl/player.h` and `player.c` | `StaticPlayer`, getters for stocks/damage/controller index, KO-by-player counters and self-destructs | Distinguish controller port, player slot and match attribution instead of assuming they are identical |
-| `src/melee/ft/types.h` | `Fighter`, player/controller identifiers, buffered sticks/triggers/buttons, pressed/released edges, damage state, source-player field and move-instance information | Audit controls and potential reward attribution; source fields are hypotheses to validate against live transitions |
-| `src/melee/gm/types.h` | Match frame/timer fields, `MatchEnd`, winner arrays and exit/results structures | Episode boundaries, timeout/results interpretation, one-time terminal rewards |
-| `src/melee/gm/gmvsmelee.h` | Character/stage select, versus entry/exit, sudden-death and results transitions | An explicit lifecycle model instead of treating every screen as a playable frame |
-| `src/melee/{cm,gr,mp,it}/` | Camera, stages, map/collision and item subsystems identified by upstream module structure | Follow-up inspection points for view geometry, hazards and projectiles; not all audited in this pass |
-
-Examples of concrete distinctions:
-
-- `StaticPlayer` has a controller index, a player ID and up to two sub-fighter entities.
-  Ice Climbers and transformations defeat “one visible fighter object = one agent.”
-- The input struct tracks three-entry analog/button histories plus pressed/released buttons
-  and threshold timers. A constant button hold and a sequence of taps are different actions.
-- Damage includes an annotated source-player number, but it must be checked for projectiles,
-  stale ownership, self-damage and indirect KOs before it becomes a reward source.
-- The match structures include winner counts/arrays. A terminal result is not safely inferred
-  from whichever player's stock decrement happened to be sampled first.
-
-### 2.2 How to use it without making the framework Melee-specific
-
-Create a **task-local** inspection catalog: field name, binary/decomp revision, symbol or
-pointer traversal, type/endianness, valid scenes, tested transitions and unsupported cases.
-Prefer Slippi telemetry for fields it supplies reliably; use decomp-grounded inspection for
-missing fields only after verification. Do not expose all emulator memory to every agent.
-
-If memory inspection is needed, decode big-endian integer/float fields and emulated 32-bit
-pointers explicitly. Never cast emulated bytes to a native Rust/C struct whose layout,
-pointer width or bitfield ordering is different. Sample a consistent backend boundary rather
-than reading a moving process asynchronously. Accessors named in the decomp explain semantics;
-they are not functions our host process can call in place of an adapter.
-
-Derive small constant/schema outputs and synthetic fixtures where appropriate. Do not vendor
-the entire decomp, game executable, assets or save states merely to read stocks and damage.
-The first working backend does not require rebuilding Melee. Custom hooks or patches are
-separately identified scaffold and enter the run's behavior/content identity.
-
-## 3. Emulator options and recommendation
-
-All candidates below emulate GameCube software. The differentiator is the host integration,
-not whether Melee can theoretically boot.
-
-| Candidate | Evidence / useful capability | Gap or cost | Decision |
-| --- | --- | --- | --- |
-| **Mainline-based Slippi Dolphin + maintained libmelee** | Structured game/port events, controller pipes, explicit blocking-input support; Linux rendered path available in the ecosystem | Pixel/audio access and coherent external save-state control still need integration; pin emulator, Gecko codes and parser together | **First spike and preferred initial integration** |
-| **Stock Dolphin + narrow host hook** | Source has `Core::DoFrameStep`, CPU-thread coordination and `State::{SaveToBuffer,LoadFromBuffer}` | These are internal APIs, not a stable remote environment SDK; own a small patch and state parser/telemetry bridge | Fallback or eventual generic Dolphin backend if its maintenance cost is justified |
-| **Felk Python-scripting Dolphin branch** | Inspected stubs expose controller/memory/save-state scripting and rendered-frame events | Historical branch; `await frameadvance()` is documented as waiting for a rendered-frame event, not proof of a paused one-step transaction | Research reference or temporary probe, not default production dependency |
-| **Custom EXI/fast-forward Slippi-Ishiiruka** | Maintained libmelee README describes accelerated ML mode and EXI inputs | That documented fast path disables rendering; inspected libmelee rejects non-Null graphics for the EXI_AI build | Useful for explicitly state-driven offline research, not the pixel-fed live baseline |
-| **Libretro Dolphin core** | Potential common frontend ABI | No core-specific synchronization/state/render benchmark was performed; another integration layer does not remove task semantics | Defer rather than introduce an unverified second dependency stack |
-| **Native game port built from the decomp** | Source enables modding/research | Matching DOL compilation is not native execution; graphics, OS/SDK, timing and assets remain substantial work | Outside this project's first Melee phase |
-
-Use the maintained **`vladfi1/libmelee`**, not a floating install selected by an old tutorial.
-`altf4/libmelee` says it is archived and points there. The maintained fork says it became
-the PyPI `melee` source starting at 0.45.0; pin the actual chosen package/source revision and
-its dependencies instead of assuming an unversioned `pip install melee` reproduces a run.
-
-The maintained README describes raw-state compatibility, but the inspected `Console.step()`
-still invokes `__fixframeindexing` and `__fixiasa`. Therefore, confirm field semantics from
-the installed source and observation fixtures rather than trusting README wording. Our
-adapter identifies parser/normalization revision as part of task identity.
-
-### 3.1 What the blocking path actually does
-
-**Observed in source:**
-
-1. `libmelee.Console` defaults `blocking_input=False`. Setting it true writes
-   `Slippi/BlockingPipes` for its mainline backend.
-2. `Console.step()` flushes its registered controllers and then dispatches game/menu events
-   until a frame boundary. It is not a method returning RGBA pixels or arbitrary game state.
-3. Slippi's `EXI_DeviceSlippi.cpp` sets `g_need_input_for_frame` on game setup, menu frames
-   and frame bookends.
-4. `Pipes.cpp::UpdateInput` checks the blocking setting and flag, waiting for commands through
-   `FLUSH`. Its Linux wait path uses `select`; the inspected Windows wait helper is not implemented.
-5. `ControllerInterface::UpdateInput` updates devices and only then clears the flag. The
-   `FLUSH` handler explicitly avoids clearing it before the other devices have been read.
-
-That is strong evidence for trying a Linux multi-port blocking backend. It is **not yet a
-measurement** that action batch `t` affects exactly our desired frame `t+1`, that menu/game
-boundaries behave identically, or that rendering/audio are coherent with the telemetry.
-
-Keep at most **one batch outstanding**. The pipe implementation consumes buffered commands,
-and a backlog of frame batches must not collapse into a latest-state input. Create an isolated
-Dolphin user directory containing only the intended pipe devices: unused/abandoned devices
-can participate in updates and leave blocking input waiting on a controller nobody drives.
-
-For two flies, stage both full controller states before calling the single owner's
-`Console.step()`. Do not give each agent a `Console` loop. Verify which input sample corresponds
-to returned pre/post-frame telemetry with distinguishable action pulses and deliberate delays
-on each port. “Both bots sent commands” is weaker than “both commands landed on one frame.”
-
-### 3.2 What libmelee does not establish for us
-
-- No framebuffer-returning or whole-session save/load interface was found in the inspected
-  `Console` API. `DumpConfig` configures media dumping; a dump is not automatically a bounded,
-  timestamped sensory-frame transport.
-- GameCube pad values are stateful. Unchanged buttons remain held; the backend must emit an
-  explicit complete state or compute trustworthy deltas, including release/neutral values.
-- The library applies analog normalization (`fix_analog_stick`, `fix_analog_trigger`). Define
-  our canonical ranges and apply conversion exactly once; test round trips at neutral,
-  extremes, diagonals, dead zones and trigger-click thresholds.
-- Rollback skipping and internal controller flushes are present. Use local offline matches
-  first; do not confuse filtered rollback frames with advancing brains through speculative time.
-- Initial game events can flush neutral input internally. Record startup as lifecycle scaffold;
-  do not attribute that to a neural decision.
-- Spectator transport keepalive, pipe blocking and process liveness are separate. A healthy
-  connection does not prove the match or renderer is advancing.
-
-## 4. Audit of our current system: keep, extract, replace
-
-Rust path aliases: `core/`, `gb/`, `sim/` mean the respective crates under
-`services/flysim/crates/` named `flybrain-core`, `flybrain-gb`, and `flysim`.
-
-| Finding | Current evidence | Required change for Melee/multiple flies | Priority |
-| --- | --- | --- | --- |
-| Single world and brain bundled together | `sim/src/simloop.rs::Sim` owns one `NeuralAgent`, concrete `Emulator`, adapter and ratchet | Session owns one environment plus agent collection and explicit port map | Blocking |
-| Direct Game Boy calls in frame loop | `step_frame`, `to_button_mask`, `set_buttons(u8)`, `run_frame`, fixed framebuffer copy | Backend interface with full action batch, rational cadence, observations and media capabilities | Blocking |
-| Task trait carries Pokémon concepts | `gb/src/adapter.rs` includes `read8(u16)`, map/exit/objective hooks | Keep inspector and macros task-local; use generic reward/episode/progress outputs | Blocking |
-| Timing defaults embed Game Boy | `core/src/agent.rs`, `sim/src/config.rs` | Session clock derived from backend, per-agent neural remainders; preserve old arithmetic in legacy facade | Blocking |
-| Decoder tuned to walking through Pokémon maps | `packages/brain/src/readout/presets/gameboy.ts`: 800-ms directions, 85-ms A/B pulses with 480-ms cooldown | New fixed GameCube mapping; frame-scale controls, analog sticks/triggers, concurrent movement/action | Blocking |
-| Neural code is already independently useful | `core/src/lif.rs`, `agent.rs`, `plasticity.rs`; TS counterparts | Reuse exact kernel and private per-agent state; do not replace neural semantics to integrate a game | Keep |
-| Graph can be shared, pool cannot be concurrently dispatched | `Arc<BrainDataset>`, `SweepPlan`, `core/src/pool.rs` shared job slot | Immutable topology shared; distinct mutable state and controlled total scheduling budget | Blocking |
-| CUDA exists but not an automatic service optimization | `core/src/lif/cuda.rs`; no `enable_cuda` call found in `sim/src/simloop.rs` | Explicit backend selection, equivalence/restore tests, profile first; don't promise GPU brains from graphics availability | Measured option |
-| Snapshot header is a single Pokémon-shaped view | `sim/src/snapshot.rs`, `packages/feed/src/{types,codec}.ts` | Session descriptors, multiple agents/ports, task-specific progress, named attachments/media | Blocking for proper broadcast |
-| Stage assumes Game Boy geometry and one fly | `apps/stage/src/{App.tsx,feed/store.ts,feed/decode.ts,lib/geometry.ts}` | Per-session/agent store instances, dynamic view aspect/dimensions, multi-agent match layout | Blocking for proper broadcast |
-| Browser owns game audio | `apps/stage/src/audio/engine.ts`, 48-kHz feed, Pulse capture | Explicit audio producer and media-clock policy; do not play native Dolphin audio and forwarded PCM twice | Blocking |
-| Capture already offers NVENC | `infra/bin/flycast-launch` | Reuse encode/relay/recording; measure new compositor/readback cost and revise 60-fps settings | Keep with changes |
-| Encoder hardcodes H.264 level 4.1 | Both encoder functions in `flycast-launch` | 1080p60 needs a suitable level (normally 4.2 or automatic selection); changing only `FLY_FPS` is insufficient | Required for 1080p60 |
-| Existing checkpoint payload is single-agent/binary-specific | `sim/src/store.rs`, `gb/src/compatibility.rs` | Coherent all-agent/world checkpoint plus backend/parser/patch/controller identity | Blocking for exact resume |
-| Checkpoint writer queue is unbounded | `Sim::start_writer` uses `std::sync::mpsc::channel` | Bound/coalesce background work; larger emulator captures and several brain copies must not grow an unlimited queue | High |
-| Existing “saved” event precedes durable commit | `checkpoint_with_reply` emits after enqueue; writer updates durable metrics on success | Distinguish capture/enqueue/commit/failure events; public status must not report a queued Melee save as durable | High |
-| Recovery assumes a best progress ladder | `gb/src/{ratchet,recovery}.rs` | Match/episode reset policy; never rewind one player's world independently | Blocking |
-| Health is mostly loop heartbeat | `sim/src/simloop.rs::Shared`, `sim/src/lib.rs` | Distinguish waiting at input barrier, intentional pause, backend timeout and deadlock; keep host supervision responsive | High |
-| Deployment resource partitions reflect the old stack | `infra/units/flysim.service`, deploy cpuset construction | Budget Dolphin CPU/GPU plus N brains and media; measure and set new memory/process limits | Required before release |
-| Bridge targets one sim | `services/bridge/src/{sim,commands,redemptions}.ts` | Explicit stable agent targeting and intervention policy; no viewer control-port endpoint | Before interactive show |
-
-Do not interpret dated CPU/GPU measurements in the repository as current free capacity.
-The records identify bandwidth contention and graphics-sharing constraints, but this audit
-does not inspect the host or establish that it can run two brains plus Dolphin in real time.
-
-## 5. A framework architecture that survives a third game
-
-### 5.1 Four runtime components, not one enormous adapter
-
-```text
-Application / supervisory logic                 Presentation / recording
-                   \                              /
-                         Flybus RPC + pub/sub
-                   /             |                \
-       Session coordinator   Agent workers      Backend helper
-       clock / barrier       brain / encoder    Python + libmelee initially
-       task + executors      fixed readout      owns Dolphin process/user dir
-       episode policy                           native pipes, parser, media/state hooks
-                   \             |                /
-                      owned artifact references
-                                |
-                       immutable local store
-
-Presentation owns stage/compositor → capture → local relay → optional Twitch push.
-```
-
-The helper is an **internal backend implementation**, not an audience-accessible controller
-service. The session remains the sole authority assigning actions to ports. Python never
-simulates the neurons or selects actions. Keep it if measurements say its overhead is small;
-replace its internals with Rust only when an actual bottleneck or maintenance
-requirement justifies it.
-Its Flybus binding uses the same protocol as every component. Dolphin-specific input pipes
-stay behind the environment adapter, not a second framework communications system.
-
-An external emulator is a normal `Environment` implementation, not a special `if melee`
-branch sprinkled throughout the session. For Game Boy, the same interface has an in-process
-implementation. For an embodied world, it may be a native physics engine. Consumers do not
-need to know which one owns the world.
-
-### 5.2 Framework contracts to extract
-
-| Contract | Owns | Must not know |
-| --- | --- | --- |
-| `Brain` / numerical core | Tick semantics, state, spikes, rates, learning updates | Game, process, controller labels or viewer |
-| `SensorEncoder` | Declared observation→neural drive transform | Reward inspector state not declared as input |
-| `Readout` | Fixed rate/signal→control-channel mapping | Opponent strategy, game addresses or pathfinding |
-| `ActionExecutor` | Selected action + coherent game state + task progress + clock → controller state | Authority to invent a winning action when brain is silent |
-| `Environment` | Native clock, port schema, action commit, observations/media, snapshot capabilities | Neural roles, Twitch or task reward weights |
-| `Task` | Typed state interpretation, rewards, progress and episode outcomes | Direct neural mutation or direct controller writes |
-| `EpisodePolicy` | Start/end/reset/recovery semantics | Hidden per-player rewind in a shared world |
-| `Session` | Barrier, identity, agent isolation, routing, state capture and supervision | Melee memory offsets or Pokémon map IDs |
-| `Flybus` | RPC/pub-sub routing, bounded deliveries, artifact ownership and GC | Game timing, neural roles, presentation/stream semantics |
-| `Presentation` | Descriptor-driven layout, media/audio and task panels | Emulator stepping or access to controller pipes |
-
-Use modules first, then crates/packages as second consumers appear. The existing monorepo
-and Rust workspace can stay in place during extraction. Keep static compiled registries
-initially; a stable dynamic-plugin ABI and public package registry are not prerequisites.
-
-**Framework acceptance test:** adding a synthetic third environment/task requires a backend
-implementation, a task/profile and a composition manifest, not edits to the session loop,
-neural core, protocol enums or generic stage store. A game-specific presentation plugin is
-allowed. Wire extensions must be namespaced/schema-validated, not hardcoded into every panel.
-
-### 5.3 Backend RPCs over the common bus
-
-Use Flybus for these conceptual capabilities; do not implement another socket/message
-envelope. Exact method names/bodies are in the session-framework contracts. Pause/Resume
-are session lifecycle intents; an environment adapter holds its boundary between Advances.
-
-```text
-Hello → backend build/content/patch identity, capabilities, cadence, ports, views
-Initialize(runConfig) → Ready(epoch, observationBoundary)
-Advance(epoch, expectedBoundary, completePortBatch)
-    → StepResult(epoch, newBoundary, appliedBatchId, observation, mediaRefs)
-Pause / Resume → explicit acknowledgment
-Capture(epoch, boundary) → capture token + state digest + snapshot bytes/reference
-Restore(captureToken) → new epoch + restored observation + success/failure
-Shutdown → acknowledgment or bounded forced process termination
-```
-
-Only advertise `Capture/Restore` if implemented and tested. Otherwise expose an explicit
-`restart_episode` capability and visible aborted-match policy; never claim exact resume.
-Port batches use canonical buttons plus sticks in [-1,1] and triggers in [0,1], converted
-once by the backend. Descriptor/schema versions pin conversions and active ports.
-
-Commands and pub/sub envelopes contain metadata and ArtifactRefs; native media/checkpoint
-bytes live in Flybus's managed immutable store. Include producing epoch/frame/sample identity
-and format in domain descriptors. DeliveryGuard keeps bytes alive beyond message drop if an
-encoder/renderer retains a handle. Cached RPC replies own handles for retry; last-owner GC
-reclaims data. Start file-backed; pooled shared-memory reuse is an optional later optimization.
-Router restart invalidates routes/handles and requires coherent session recovery.
-
-One request in flight, explicit timeouts, bounded queues. After an uncertain `Advance`
-response, do **not** resend blindly: the world may already have advanced. Resolve batch ID/
-boundary through an idempotent reply cache or fail/recover the session. A pipe transport with
-no application acknowledgment needs validation against returned input telemetry, not a claim
-of atomicity it cannot prove.
-
-Separate lifecycle I/O from the blocked advance operation so diagnostics/shutdown stay alive.
-Do not issue a save operation scheduled on Dolphin's CPU thread while that same thread is
-waiting forever for pipe input. Capture/pause needs a backend-owned quiescent point where
-both the simulation and pending input consumption have known state.
-
-## 6. Multiple flies and the timing contract
-
-### 6.1 One match, one world clock
-
-Two flies in Melee normally means two controller ports in **one Dolphin instance**. Four
-flies means four ports, not four copies of Melee joined through netplay. Several independent
-matches are separate sessions/process trees, orchestrated by application code developed with
-its presentation. A tournament director is one example, not a mandatory framework service.
-
-For each committed boundary:
-
-1. Freeze each agent's allowed observation from the same world state.
-2. Advance every brain by the environment's elapsed emulated time using its private remainder.
-3. Decode independent actions; step any declared executors; assemble a complete port batch.
-4. Commit the batch once and let the backend advance to the next acknowledged boundary.
-5. Associate rendered sensory frames and telemetry with their actual producing boundary.
-6. Route task events/rewards exactly once; encode the next input and publish a snapshot.
-
-Warm-up settles/calibrates brains with learning off while the environment is held at its
-initial boundary. The next observation must not be from a game that ran freely through the
-warm-up. Fixed offsets between brain and environment clocks are recorded.
-
-Use the selected backend's rational emulated cadence, not `GAMEBOY_MS_PER_FRAME` or an
-unexamined exact 60. An approximately 60-Hz budget is about 16.7 ms, but logical game frame,
-video interrupt, input poll, rendered presentation and Slippi frame bookend are distinct
-events until the spike establishes their mapping. Session ticks are monotonic even when
-Melee's signed frame number resets, starts before zero, or changes across menu scenes.
-
-### 6.2 Render latency and agent fairness
-
-Dual-threaded graphics can present frame `n` after telemetry for `n` is available. Label the
-actual frame; do not attach “latest screenshot” to current state and assume equivalence.
-Start with one declared fixed observation latency shared by all agents, and measure it.
-If a pipeline deliberately adds one frame of latency, record that in the sensor profile.
-The full-resolution spectator view may be delayed separately, provided overlays use the
-matching presentation timestamps rather than future task data.
-
-Also test a potential pipeline deadlock: the helper waits for a rendered image while Dolphin
-is waiting for the next controller flush needed to reach that presentation event. Fix the
-backend's rendezvous or select a declared previous-frame sensory latency; do not unblock it
-with an undisclosed neutral gameplay input. Game-state bookends alone do not prove the GPU
-has completed a matching frame.
-
-Do not reduce brain integration from 1,000 to 500 ticks per emulated second to meet wall-clock
-deadlines. That changes the model. A declared action-repeat interval can reduce decisions,
-but normally still requires all neural ticks and correctly accumulated intermediate task
-events; it does not halve the principal neural cost. Rendering every second game frame is
-also a sensor change if the brain otherwise sees each frame, not merely a broadcast setting.
-
-On slow compute, the default is to slow the entire local match and report real-time factor.
-Do not let one fly continue while the other misses turns. On a dead participant/backend,
-pause or abort the match visibly; neutral fallback play is not silently substituted.
-
-### 6.3 No rollback netplay in the first release
-
-Slippi supports online play, but we do not need it to connect two local flies. Online rollback
-would require rewinding **all** neural states, RNG, decoder/executor state, reward ledgers
-and admission decisions at the same speculative boundary as the game, then replaying inputs.
-Filtering repeated frames in libmelee is not that system. Keep offline local matches and
-assert monotonic committed observations per epoch; classify unexpected rollback as an error
-or explicit recovery transition rather than double-rewarding it.
-
-## 7. Controller, sensory and learning design
-
-### 7.1 A GameCube controller is not an eight-bit pad
-
-Support independent main and C sticks, analog shoulders, digital trigger clicks, face
-buttons, start and D-pad. Movement and attack can overlap. Canonical neutral/release state
-must be complete, so a missing command cannot accidentally leave attack or shield held.
-
-At about 60 Hz, the current 800-ms direction hold is roughly **48 game frames** and the
-85-ms pulse roughly five. Reusing these values would dominate the fly's behavior regardless
-of the dataset. Create a fixed Melee readout with explicit decisions in integer game frames,
-bounded analog mappings, dead zones, tie handling and pulse/hold policies. Start with a small
-declared set of stick magnitudes and directions if that makes validation easier; continuously
-valued mappings can follow as a separate profile.
-
-Audit tap-jump, directional aerials/smash attacks, jump release, shields, simultaneous axes,
-and conflicting inputs. Don't add state-conditioned auto-aim, automatic edge recovery or
-combo execution under the label “controller mapping.” If later desired, publish those as
-separate macro/assistance profiles with their own identity and comparison baseline.
-
-Start/system controls are lifecycle-sensitive. During an active match the profile may omit
-pause entirely; initial match setup and between-match reset are disclosed episode scaffolding.
-This is not permission for an API to press buttons. Specify whether setup uses an audited
-initial state, internal deterministic menu setup, or a reset hook, and mark those frames as
-non-neural setup with learning disabled. That expands the legacy “all presses” phrasing and
-requires a deliberate task-policy/documentation decision before shipping it.
-
-### 7.2 What the fly sees
-
-For the initial pixel profile, both flies receive the same shared game camera with fixed
-crop/aspect treatment, independent of spectator overlays. The legacy 160×144 input should
-not stretch a 4:3 scene silently. Compare an aspect-preserving downsample/letterbox transform
-with a separately versioned input-size profile; changing kernel retina dimensions currently
-affects the numeric configuration identity.
-
-Current L1 projection samples luminance at 1,572 columns. Higher broadcast resolution does
-not produce more sensory neurons, color recognition, motion estimation or knowledge of which
-fighter the fly controls. Test whether each selected character remains visible across zoom
-and stage movement; record the sparse sensory representation rather than assuming a human-
-readable video is an adequate neural input.
-
-Three distinct modes must not be conflated:
-
-| Mode | Neural observation | Rendering implications |
-| --- | --- | --- |
-| Pixel baseline | Actual game image through fixed encoder | Needs real rendered frames even if no desktop GUI is shown |
-| Structured-state experiment | Explicitly encoded positions, velocities, stocks, etc. | Can potentially use Null/fast-forward, but it is a new privileged-input model |
-| Spectator-only rendering | Whatever the profile specifies; video for audience | May be independently compressed/delayed, never silently substituted for sensory input |
-
-“Headless” can mean no GUI while still rendering; “Null graphics” generally means no useful
-pixel observation. The documented EXI fast-forward speed path cannot be advertised as the
-performance of our pixel-fed broadcast.
-
-### 7.3 Reward and outcome attribution
-
-Implement a `MeleeTask` with typed per-player observations, match state, a ledger and positive
-reward events. Its schema belongs to the task, not a generic `GameMode` enum. Start small:
-
-- Terminal match outcome, once, based on validated results/termination reason.
-- Opponent damage and credited KOs only after verified ownership information is available.
-- No reward for mere button activation, for losing a stock, or for scripted setup.
-
-Do not reward A for every increase in B's percent: self-damage, stage effects, reflected
-projectiles, teams and another sub-fighter can invalidate that inference. The decomp's source-
-player and KO tables guide inspection, but no runtime correctness is claimed until tested.
-Unknown attribution produces a logged observation without a guessed reward. Keep fractional
-damage until the rule deliberately quantizes; HUD damage and fighter damage may differ.
-
-Deduplication keys include epoch/match, producing frame and event identity. Handle multihits,
-trades, simultaneous KOs, respawn percent reset, timeout, sudden death and disconnection as
-separate cases. If source telemetry cannot distinguish a required case, narrow the first
-ruleset or add a specific audited observation hook.
-
-Learning remains private per fly and synthetic reward modulation remains distinct from PAM
-stimulation. Disable learning during kernel/controller/backend characterization; later compare
-learning-on with learning-off, repeat seeds and swap sides/characters. Retaining gains between
-rounds is a run policy. Competitive success is not guaranteed by increased model complexity.
-
-## 8. Performance plan: measure the actual critical path
-
-### 8.1 Budget equation
-
-For a lockstep pixel-fed match, approximate the critical wall-time interval as:
-
-```text
-T_step = T_brains + T_readout/task + T_bus_RPC
-       + T_emulation_to_observation + T_required_render_readback + T_boundary_overhead
-
-T_brains ≈ sum(T_agent_i)                 [sequential evaluation]
-T_brains ≳ max(T_agent_i) + barrier cost  [parallel with sufficient independent resources]
-```
-
-The parallel estimate is a lower bound, not a promise: shared caches, memory bandwidth,
-GPU contention and scheduling can make every brain slower. Media publication/encoding and
-storage should be off the critical path, but their resource use and state capture still
-affect it. Do not obtain a “60 fps” claim solely from Dolphin's display counter while the
-brains advance fewer milliseconds or repeat stale observations.
-
-Proposed capacity gate: warm full-stack **unthrottled** throughput at least 1.2× the selected
-game cadence for two flies, then a paced one-hour soak with no growing queues/lag and a
-24-hour local endurance run before release. In the paced run, distinguish intentional wait
-from compute time; report p50/p95/p99/max compute interval and deadline misses. The 1.2×
-margin is a proposed engineering target, not a measured capability of current hardware.
-
-### 8.2 CPU/GPU strategy
-
-1. **Keep the first two brains on CPU.** Establish Dolphin JIT/render/media cost separately.
-   The repository's current service is CPU-composed even though a CUDA kernel exists.
-2. **Allocate a total physical-core budget.** Compare sequential agents with modest within-
-   brain pools against agents running concurrently on disjoint core groups. Include Dolphin's
-   CPU/JIT thread, graphics worker, helper, browser, encoder and storage in the budget. Do not
-   launch four copies of the current per-brain pool size by default.
-3. **Use native-resolution hardware rendering first.** Compare OpenGL/Vulkan on the chosen
-   build/platform; no blanket claim that one is faster. Measure render correctness and readback.
-   JIT is the performance baseline; an interpreter is a diagnostic baseline, not the live plan.
-4. **Benchmark shader compilation and caches.** Report cold and warm starts separately. Choose
-   supported shader modes from measurements; a cache that hides startup hitches is not a
-   guarantee that a new stage/character will not compile something mid-match.
-5. **Use NVENC where available, with a measured fallback policy.** Its encode engine does not
-   remove GPU rendering, memory allocation, color conversion or framebuffer-readback cost.
-   Automatic fallback to x264 can consume the cores the brains/emulator need; expose the
-   resulting degradation and test whether the declared session can still meet cadence.
-6. **Only then test CUDA brains.** The current backend retains RNG/plasticity observation/rate
-   work on the host, uploads state inputs, and by default synchronizes membrane/refractory
-   state back each batch. It also allocates device graph/state per backend instance. Measure
-   two/four agents alongside Dolphin, browser graphics and NVENC; zero-copy shared graphs and
-   a GPU-wide scheduler are possible later work, not present features.
-
-For CUDA, preserve bit-exactness, gain-update ordering and checkpoint synchronization.
-Batching across a future game action boundary is not valid just because it improves kernel
-throughput. Keep the TypeScript oracle and existing version strings intact.
-
-The existing VirtualGL/Xvfb result demonstrates one Chromium rendering path, not that
-Dolphin Vulkan/OpenGL works or is performant in the same container. Test the complete selected
-graphics path. Reusing GPU passthrough requires no assumption of exclusive VRAM availability.
-Resource availability must be measured in an approved, serialized deployment-host session.
-
-### 8.3 Media bandwidth and copies
-
-Uncompressed RGBA estimates, before copies/framing:
-
-| Image/cadence | Bytes per second |
-| --- | ---: |
-| Existing 160×144 at 30 fps | 2.76 MB/s |
-| 640×480 at 30 fps | 36.86 MB/s |
-| 640×480 at 60 fps | 73.73 MB/s |
-| 1920×1080 at 60 fps | 497.66 MB/s |
-
-640×480 is a planning example, not an asserted fixed Dolphin framebuffer size. The backend
-advertises actual dimensions/format/aspect. One shared camera is delivered once for the
-match; two flies can sample one immutable image without duplicating its transport. If their
-sensor transforms differ, encode separately against the same source frame.
-
-Start with native frames as immutable artifacts: 480p is not an automatic reason for a codec
-or second transport. Flybus carries handles only; multiple readers map the same object. Measure
-renderer readback, optional seal copy and consumer reads separately from router overhead.
-Sensor downsampling remains a declared profile operation (optionally optimized near capture
-after measurement). Viewer scaling/composition/encoding belongs to presentation. Last-use
-handles, not receipt acknowledgments, govern GC; required sensory input cannot be coalesced.
-
-### 8.4 Benchmark ladder and decision records
-
-| Run | Configuration | Question / recorded output |
-| --- | --- | --- |
-| B0 | Synthetic two-port backend plus common Flybus, no neurons | Routed RPC latency, pub/sub fairness, step barrier, timeout and artifact-GC behavior |
-| B1 | Dolphin with fixed input traces, rendering/audio on, no brains | Cold/warm emulator cost, step timing, port alignment, render-to-state latency |
-| B2 | Same run + helper/media extraction | Incremental parsing, copying, downsampling and audio cost |
-| B3 | One FAFB brain | End-to-end reference and per-phase costs |
-| B4 | Two FAFB brains, sequential vs parallel schedules | CPU/cache/bandwidth limits, balanced observation and input timing |
-| B5 | B4 + actual stage, capture, relay, recording, checkpoints | Full critical path, A/V drift, encoder fallback and queue growth |
-| B6 | Four brains and four active ports | Capacity characterization only until this independently passes the same gates |
-| B7 | Matched MaleCNS and optional CUDA variants | Dataset and backend effects, measured independently before combined variants |
-
-Record backend/content/patch/profile digests, physical-core allocation, exact graphics settings,
-sensor/broadcast resolutions, all clock rates, resident/peak memory, VRAM, thread usage,
-real-time factor, latency distributions, audio under/overruns and dropped frames by purpose.
-Store operator-specific machine details externally and publish only the portable methodology
-and non-identifying results. No measurements were performed by this document-writing task.
-
-## 9. Broadcast architecture and audio ownership
-
-### 9.1 Two viable routes
-
-Both routes are **application/presentation implementations**, not additional framework buses.
-The environment emits native frame/audio artifacts through Flybus in either case.
-
-**Route A — stage receives game media.** A presentation gateway subscribes to native artifacts,
-delivers them to the browser, and the stage composites game/overlays for capture. Start with
-native uncompressed artifacts internally. Browser-edge delivery can remain raw or use a codec
-after measurement; avoid encode→decode→encode unless its tradeoff is justified. The gateway
-holds artifacts through conversion/use and then releases them; browser backpressure cannot
-pin required sensory state without a bound. Overlay timestamps track displayed video.
-
-**Route B — compositor combines native game output and stage overlay.** Dolphin supplies its
-rendered output to a compositor; the browser supplies a separate overlay surface. This can
-avoid moving full-resolution game pixels through JavaScript, but requires an explicit shared
-clock and a new capture composition. The fly's sensory image still needs a frame-identified
-path from the backend. Capturing a desktop window on a wall clock is insufficient to establish
-which image a brain used at a given game boundary.
-
-**Recommendation:** prototype Route A for the two-player local slice; benchmark Route B in
-the media spike before committing to the long-run high-resolution pipeline. Preserve media
-as a capability behind the environment interface so the choice does not change brain/task code.
-The browser-facing v2 contract can reference media streams; it does not dictate the internal
-bus, native sensor format or artifact-store implementation.
-
-### 9.2 Audio and clock policy
-
-Today the page plays binjgb PCM and stream SFX into the Pulse sink. With Dolphin, select one
-of these explicitly:
-
-- Dolphin PCM is captured/forwarded and played by the page, with native device output muted.
-- Dolphin renders audio to the capture sink directly, and the page contributes only SFX.
-
-Do not run both. Declare sample format/rate, resampling location, timestamps, buffering and
-discontinuity handling. Pause/reset/restore must flush or relabel buffered old-episode audio.
-If wall time falls behind, measure pitch/time-stretch behavior; do not let “async resample”
-hide minutes of simulation lag. Game timestamps, not arbitrary browser receipt time, define
-the intended A/V relationship.
-
-Keep 30-fps broadcast and approximately 60-Hz gameplay as independent settings. For 1080p60,
-the existing H.264 level 4.1 is too low for the normal macroblock-rate requirement; use a
-compatible level such as 4.2 or encoder-selected level and validate the actual stream. Also
-measure capture/compositor cadence, bitrate quality, encoder lookahead/latency, local recording
-and audio synchronization. `FLY_FPS=60` alone is not a completed performance upgrade.
-
-### 9.3 Presentation changes
-
-The generic stage needs descriptor-driven game aspect ratio, two/four agent cards, per-port
-button/stick indicators, per-agent learning/sugar state, shared match stocks/percent/results,
-and scoped events. Neither “badges” nor “highest ladder rung” describes a match.
-
-Separate task data schema from layout. Keep one compositor clock and one selected world audio
-stream; keep neural maps and rate scalers private per agent/dataset identity. Defer expensive
-four-avatar/whole-connectome rendering until measured. All actual layout decisions require
-PNG mockups and existing legibility/browser checks. This text does not approve a screen.
-
-## 10. Persistence and unattended operation
-
-### 10.1 Savestates are a capability, not a libmelee assumption
-
-Dolphin source provides buffer/file state operations, but `State.h` documents that operations
-called off its CPU thread may be scheduled rather than executed immediately. An external
-“save requested” is therefore not proof of a consistent capture at our agent boundary.
-Slippi's internal rollback save-state commands likewise do not constitute an audited public
-multi-agent checkpoint API.
-
-The selected backend must supply acknowledgment of the frozen boundary, resulting state
-digest and completion. Save every brain, RNG, rate/calibration state, learning state, sensor/
-executor state, pending action identity, task ledger and environment together. Clock and
-media epochs change on restore; discard pre-restore spectator/parser buffers.
-
-Re-create or explicitly reinitialize libmelee's parser caches and controller history after
-restore. An emulator savestate does not include an external helper's `_frame`, previous
-game state, normalization state or queued pipe data. Test how game-start metadata is supplied
-when loading into mid-match; some telemetry protocols may need reseeding or restarting.
-
-When exact mid-match capture is unavailable, an initial prototype may visibly abort and
-restart a match while retaining a declared brain checkpoint. Mark `resume=episode-restart`
-in the descriptor. That is a deliberate narrower capability, not equivalent to crash resume.
-It is not ready for a release that promises uninterrupted exact match continuation.
-
-### 10.2 Storage and health
-
-Bound pending captures and coalesce replaceable hot checkpoints. A durable request either
-completes with a commit acknowledgment or fails explicitly; never drop it while reporting
-success. Match-end result records are append-only and independent of world rewind.
-
-Keep backend/helper/brain health separate from “game frame did not advance.” An intentional
-pause or waiting barrier is not a crash; a dead helper must not keep the session green by
-merely refreshing an HTTP heartbeat. Export last completed boundary, in-flight request age,
-barrier participant status and renderer progress. A hard stall has a timeout and explicit
-match abort/recovery path, not repeated blind restarts of unrelated services.
-
-Manage Dolphin under the session's lifecycle or an explicitly coordinated systemd unit. If
-Dolphin restarts, the session cannot keep sending frame `t+1` to a fresh match. Allocate unique
-user directories, pipe names, telemetry ports and state namespaces per independent session.
-Use deterministic configuration provisioning and checksums instead of reusing a developer's
-desktop Dolphin settings or permitting auto-updates.
-
-The existing `flysim.service` memory ceiling and CPU partition were sized for a different
-process graph. Set new cgroup/resource limits from measured high-water marks; account for
-backend process, multiple brain copies and checkpoint transients. Release preflight checks
-the complete backend/game/patch/parser/profile identity. Rollback retains compatible state
-as well as the old executable.
-
-## 11. Staged implementation and go/no-go gates
-
-This specializes the existing backlog rather than replacing its foundation/session work.
-Melee-specific spikes can start before the full framework reorganization is finished.
-
-| Item | Work and dependency | Evidence required before the next step |
-| --- | --- | --- |
-| **MELEE-01: backend selection spike** | Specializes EMULATOR-01. Pin mainline Slippi + maintained libmelee, content and Gecko codes; use isolated user config and two synthetic controllers | Boot/render/audio; block one then both ports; one batch/frame mapping; menu→match→results lifecycle; cleanup/restart. Choose this build or stock Dolphin + narrow hook based on results |
-| **MELEE-02: capture/restore spike** | Alongside MELEE-01; prove sensory-frame identity, media export and save/load acknowledgment independently | Fixed pixel↔telemetry latency, bounded media storage, correct input after restore, parser/cache recovery. Explicit decision: exact resume or prototype-only episode restart |
-| **MELEE-03: task observation audit** | Pin decomp; build field catalog, typed parser/inspector, lifecycle and synthetic event fixtures | Verified port/player/sub-fighter mapping; stocks/results; no guessed rewards; content/patch mismatches visibly disable unsupported semantic interpretation |
-| **FRAMEWORK-01: generic backend + session** | Existing FOUNDATION-01/02, BUS-01..03 and RUNTIME-01/02; all workers/application events use Flybus | Same legacy Game Boy traces; synthetic environment uses identical session API; artifact-backed requests/results and no Melee logic in router/core |
-| **FRAMEWORK-02: multi-agent and state** | Existing RUNTIME-03/STATE-01; integrate complete action batches, worker budget and chosen backend recovery capability | No cross-agent state leakage; one world step; changed evaluation order invariant; failed restore cannot partly install a match |
-| **MELEE-04: fixed readout and sensory profile** | MELEE-01/02 + framework boundary; TS specification then Rust implementation for any new decoder semantics | Neutral/release, analog conversion, tap/hold/direction combinations, aspect-preserved neural input and recorded latency; no hidden combo/aim policy |
-| **MELEE-05: first two-fly match** | MELEE-03/04 + FRAMEWORK-02; learning off, then audited positive rewards | Recorded action/observation timelines; paired side/seed trials; match terminal deduplication and visible reset/failure semantics |
-| **MEDIA-01: full local show** | Existing WIRE-01/PRESENTATION-01; compare Route A/B, define audio owner and 30/60-fps profiles | PNG review, fake multi-agent fixtures, measured copies/latency/A/V drift; sustained media pipeline under checkpoint and shader-load events |
-| **PERF-01: two-fly capacity gate** | Benchmark ladder B0–B5; optimize measured limiting phase | ≥1.2× warm unthrottled capacity target, one-hour paced soak and 24-hour local endurance; no queue/lag growth; documented CPU/GPU/memory envelope |
-| **MELEE-06: expand carefully** | Passing two-fly slice | Four ports/teams, broader characters/stages, MaleCNS and CUDA are separate experiments, each with new tests and its own capacity result |
-| **FRAMEWORK-03: finish packaging** | Existing PACKAGE-01 after useful second backend | Example third backend can be added without core/session/schema edits; isolated compositions package and preflight correctly |
-
-**Stop conditions:** no dependable step/input barrier; no identifiable pixel source for a
-pixel-input claim; inability to attribute rewards under the claimed ruleset; unsupported
-restore marketed as exact resume; or sustained capacity below the declared cadence.
-Respond by changing the explicit supported scope, backend or resources—not by quietly skipping
-neural ticks, adding a gameplay bot, hiding game stalls or reporting guessed measurements.
-
-### 11.1 Suggested first experiment script
-
-The first implementation should be a local measurement harness, not the final stream:
-
-1. Launch one pinned backend with known local content and two configured bot pads.
-2. Enter a fixed local match through the declared setup procedure; record episode boundary.
-3. Send distinct short left/right and A/jump pulse patterns on each port, including neutral
-   frames; log intended batches and observed raw/processed controller values.
-4. Delay one port by a controlled wall-clock interval and verify no game boundary commits
-   until the complete batch is available. Repeat with port order reversed and four ports.
-5. Capture a sequence of images/telemetry with frame identities; measure their association.
-6. Save/restore at a known barrier if supported, replay the same actions, and compare task/
-   input traces; verify helper state and buffered media are reset coherently.
-7. Kill the helper/backend separately and verify bounded failure without accidental continued
-   play or permanent hangs. Test paused-state health independently.
-8. Measure compute with no brains, one brain, two brains, then the full broadcast stack.
-
-Synthetic controller traces are test machinery, not footage presented as neural play. Keep
-game content and environment-specific records outside source control; store portable metrics,
-synthetic schemas and independently authored tests in the repository.
-
-### 11.2 Test matrix that catches Melee-specific failures
-
-- **Input:** two/four ports, inactive slots, delayed/missing flush, stale buffered commands,
-  full release, analog endpoints/deadzones, short taps, pressed versus held edges.
-- **Identity:** controller↔player mapping, swapped ports, sub-fighters, transformations,
-  character/stage changes, wrong game revision, changed patch/parser normalization.
-- **Events:** multi-hit, trade, self-damage, projectile ownership, stock reset, simultaneous
-  KO, timeout, sudden death, results re-entry, disconnect, restart after accepted reward.
-- **Clocks/media:** game-frame reset, renderer lag, stale artifact/store identity, last-use GC, dropped
-  spectator frame versus required sensory frame, paused audio, mismatched overlay timestamps.
-- **Recovery:** all-agent atomic validation, one corrupt state chunk, backend import failure,
-  helper parser not reinitialized, asynchronous save completion, hot-store coalescing and
-  durable-write failure. Test new exact resume separately from legacy transient-reset behavior.
-- **Performance:** cold/warm shaders, high-activity matches, checkpoint capture bursts, CPU
-  encoder fallback, browser reconnect, two/four neural agents and measured GPU contention.
-
-All implementation merges retain repository-required TS tests/typecheck, Rust workspace
-tests and infra lint; UI changes add Playwright and PNG review. Game-backed jobs are explicit
-operator-provided tests. Normal CI uses synthetic observations/backends and existing goldens.
-
-## 12. Decisions to carry into implementation
-
-| Question | Recommended answer now | Still requires evidence/choice |
-| --- | --- | --- |
-| Which emulator? | Dolphin, first trying mainline-based Slippi + maintained libmelee | Exact build selected by synchronized-input/media/state spikes |
-| Use the decomp to run the game natively? | No; use it to audit task/state/controller semantics | Custom instrumentation only for specifically missing observations |
-| One emulator per fly? | No for one match; one per independent session | Four-port capability must be tested, not inferred from two ports |
-| Which brain? | Two existing FAFB agents for integration baseline | MaleCNS comparison after mappings/dynamics pass their independent gates |
-| CPU or GPU brain? | CPU baseline, share immutable graph | CUDA versus CPU benchmark under Dolphin + capture, not in isolation |
-| Inputs to the brain? | Pixels with explicit fixed transform | Structured state is a distinct optional research profile |
-| Start with macros? | Fixed controller mapping, no hidden aim/combo policy | Any later assist profile is separately disclosed and evaluated |
-| How fast? | Backend-native gameplay/input cadence, 30-fps initial show | Full-stack two-agent capacity; optional 60-fps broadcast and four flies |
-| How to resume? | Whole-session coherent state where supported | Episode-restart prototype if exact state interface is not yet available |
-| How generic? | Concrete environment/task/agent/session contracts and composition examples | Extract public packages only after second/third consumers prove the seam |
-
-The first operator choices needed are the initial characters/stage/ruleset, desired show
-cadence, and whether a visibly restarted match is acceptable during the prototype. They do
-not block the synthetic framework work or source-level backend spike design.
-
-## 13. Sources and audit scope
-
-Local code evidence appears in section 4. Additional local files inspected include
-`core/src/lif/cuda.rs`, `sim/src/pacing.rs`, `sim/src/simloop.rs::start_writer`,
-`packages/brain/src/readout/presets/{gameboy,platformer}.ts`,
-`apps/stage/src/audio/engine.ts`, `infra/bin/flycast-launch`,
-`infra/units/flysim.service`, and the profiling/VirtualGL methods under `infra/docs/`.
-
-External source snapshots inspected on 2026-09-18 (pin actual dependencies again at spike start):
-
-| Repository/ref | Observed revision | Files used |
-| --- | --- | --- |
-| [doldecomp/melee](https://github.com/doldecomp/melee/tree/b9ec8a2eb48520753b2f8159ccc94d033fbf60ea) `master` | `b9ec8a2eb48520753b2f8159ccc94d033fbf60ea` | `.github/README.md`, `docs/symbols.md`, config, player/fighter/match headers and player implementation |
-| [vladfi1/libmelee](https://github.com/vladfi1/libmelee/tree/bce21f09984b286e6d36bfd2939e4cd4691f94c2) `master` | `bce21f09984b286e6d36bfd2939e4cd4691f94c2` | README, `melee/console.py`, `melee/controller.py`, license metadata |
-| [project-slippi/dolphin](https://github.com/project-slippi/dolphin/tree/41a7a3a110ed52999486ae1901c8fbb9a63d4f13) `slippi` | `41a7a3a110ed52999486ae1901c8fbb9a63d4f13` | Pipe backend, controller update loop, Slippi EXI events, `Core/State.h` |
-| [dolphin-emu/dolphin](https://github.com/dolphin-emu/dolphin/tree/ee018d00e60b9eb727489908a8daec5c537f44a8) `master` | `ee018d00e60b9eb727489908a8daec5c537f44a8` | `Source/Core/Core/Core.h`, state/core module inventory |
-| [Felk/dolphin](https://github.com/Felk/dolphin/tree/46b7eacd5c810c2d21ec5fe51ea1a9c61a7ceb3d) historical `scripting` branch | `46b7eacd5c810c2d21ec5fe51ea1a9c61a7ceb3d` | Scripting README, `python-stubs/dolphin/{event,savestate}.pyi` |
-| [altf4/libmelee](https://github.com/altf4/libmelee/tree/1da979657122facd0750ea99cf6858255e198326) `main` | `1da979657122facd0750ea99cf6858255e198326` | Archive notice directing users to maintained fork |
-
-Dolphin files inspected carry GPL-2.0-or-later headers; libmelee repository metadata reports
-LGPL-3.0. Pin and retain actual dependency licenses/notices when packaging. A separate process
-is an architectural boundary, not an assertion that distribution obligations disappear.
-
-Source inspection supports the integration hypotheses and concrete constraints above. It
-does not establish Dolphin throughput on the deployment hardware, verify any game-memory
-field live, demonstrate a new neural behavior, or prove exact multi-port/frame/save semantics.
-Those are the measured deliverables of MELEE-01/02 and the performance ladder.

docs/design/session-framework/README.md

@@ -1,122 +0,0 @@
-# Application and session framework: architecture and contracts
-
-Status: **implementation specification, draft 2**, 2026-09-18. This is a guide for future
-agents; none of the new runtime is implemented yet. Baseline code is `83090a9` on
-`docs/improvement-suggestions`. MUST/SHOULD requirements apply to the proposed new path, not
-retroactively to existing [public feed](../../feed-protocol.md),
-[control API](../../control-api.md), or legacy numerical/checkpoint behavior.
-
-## Decisions from the architecture discussion
-
-1. **Applications orchestrate components and develop their presentation alongside them.**
-   “Director” is application code, not a mandatory framework service. A tournament is an
-   example application, not the system's organizing data model.
-2. **One lightweight Rust bus supports RPC and pub/sub everywhere internally.** Flybus replaces
-   separate direct worker transports and an application broker. No NATS dependency.
-3. **Messages stay small; large artifacts live in managed storage.** Delivery guards and
-   explicit cache/retention owners keep data alive until its last actual use, then GC reclaims it.
-4. **The router moves messages and tracks generic ownership.** It never schedules game frames,
-   understands macro actions, composites video or operates a stream.
-5. **Sessions synchronize worlds; agent workers compute in parallel.** One logical clock is
-   not one execution thread. The coordinator alone commits complete world-control batches.
-6. **Game-aware executors receive current game state and task progress.** Rich inspection data
-   does not become undeclared neural input.
-7. **Native observations are framework outputs.** Resizing, overlays, browser delivery, audio
-   mixing, encoding, narration and streaming belong to the application/presentation layer.
-
-## Read in this order
-
-1. [Flybus v1](bus-v1.md) — authoritative wire/routing/RPC/pub-sub/artifact lifecycle contract.
-2. [Session RPCs](ipc-v1.md) — domain payloads, worker capability negotiation and safe retries.
-3. [Step protocol](step-v1.md) — session state machine, ordering and clocks.
-4. [Worker/task interfaces](workers-v1.md) — exact method bodies and game-aware executor boundary.
-5. [Session media/state](state-media-v1.md) — observation timing and coherent recovery.
-6. [Application/presentation boundary](publishing-v1.md) — snapshots, flexible data and effects.
-7. [Implementation guide](implementation.md) — sequenced build tasks and acceptance tests.
-
-For context: [modular-session analysis](../malecns-modular-sessions.md) and
-[Melee audit](../melee-framework-audit.md). Each contract owns its named subject; step ordering
-wins over an informal diagram, and Flybus owns transport/resource rules. Resolve contradictions
-before implementation. The [existing HTML report](report.html) is an overview, not a contract.
-
-## 1. Composition and processes
-
-```text
-Application / supervisor                 Application presentation
-  run policies, identity, history           UI, media composition, audience, stream
-                \                           /
-                   Flybus: RPC + pub/sub
-                /          |              \
-        Session        Agent workers      Environment worker
-      coordinator      brain + encoder    emulator/world + native observations
-      task/executors    + fixed readout
-                           |
-                  artifact store (same bus API)
-```
-
-This diagram is connectivity, not execution order. The step contract defines causal order.
-One router can host several independent sessions and application consumers; a deployment may
-choose one router per application for fault isolation. A router crash affects all its clients,
-so choose that boundary deliberately. In-process mode still exercises routing and ownership.
-
-Defaults: coordinator per session, worker per fly, environment worker per world. Task and
-per-agent executors begin as coordinator-local libraries. An environment helper may own a
-separate emulator child process and adapt its native protocol. There is no second framework
-socket/lease API between those logical components.
-
-Multiple players in one game share one environment/barrier. Independent games use independent
-sessions. Linked emulators require a composite backend with link-appropriate timing.
-
-## 2. Ownership and authority
-
-| Owner | State and responsibility |
-| --- | --- |
-| Application | Composition, persistent personas/brain lineage, lifecycle policies, supported interventions, application schema/history |
-| Session | Clock/epoch, port assignments, admission, task ledger, executor state, barriers and coherent recovery |
-| Agent | Private membrane, RNG, rates, learning, sensory encoding, decoder and tick remainder |
-| Environment | World, actual controller application, backend parser, native media and state capabilities |
-| Flybus | Opaque endpoint/topic routing, delivery/call correlation, bounded queues, artifact-owner graph and GC |
-| Storage client | Durable event/checkpoint writes and replay APIs; owns artifact handles during writes |
-| Presentation | Application UI, display focus, clocks/buffers, media processing, audio/stream output and narrative cues |
-
-Immutable graph data can be shared; neural mutable state cannot. Do not concurrently dispatch
-the existing single-job WorkerPool through cloned handles from different brains.
-
-Applications use declared session capabilities, not arbitrary emulator writes. Bus registration
-and method privileges preserve a single controller authority for a session. Browser/audience
-clients do not gain controller access by knowing a service name. Existing public rules remain.
-
-## 3. Domain independence
-
-The kernel knows no task or bus. The environment knows no neuron populations. A task interprets
-game state and requests outcomes/recovery; its executor translates a selected decision using
-read-only current game/progress context. The coordinator orders and applies these results.
-The bus handles no such semantics. Presentation combines framework observations with an
-application-owned schema and can change without changing simulation behavior.
-
-Persistent AssetRefs identify installed release content. Transient Flybus ArtifactRefs identify
-live bytes with ownership. Domain epoch/step identity and bus route/store incarnation are
-different: the first protects simulation order, the second protects delivery/resource validity.
-Never substitute game-frame number, persona identity or array position for either.
-
-## 4. Initial scope and compatibility
-
-First build a generic bus example (RPC + pub/sub + artifact retained beyond message lifetime),
-then a synthetic two-agent session using it. One local machine, Unix sockets/in-memory parity,
-immutable file-backed artifacts, fixed cadence, 1-ms LIF, direct control and exact-checkpoint
-synthetic backend are sufficient. Dolphin, MaleCNS and richer effects are later integrations.
-
-Deferred: cross-machine artifact access, durable broker queues, wildcard/queue-group routing,
-dynamic native plugins, hot-join, speculative netplay rollback and pooled GPU buffers.
-
-Keep legacy-gameboy-v1 distinct from lockstep-v1. Preserve TypeScript as oracle, existing default
-versions, historical arithmetic/fingerprints and FLYSIM01 reader. New identities include sensor,
-readout/executor/task/scheduler semantics. New public feed v2 is an application/presentation
-gateway contract built on the same internal bus; it does not replace the bus or expose it raw.
-
-## 5. Reuse criterion
-
-Adding a third environment/application requires a backend, task/profile, composition and
-application presentation. It must not require game-specific edits to the coordinator, router,
-artifact manager, kernel, generic stores or transport. Schematized task extensions are valid;
-an unchecked data blob or universal tournament schema is not a substitute for interfaces.

docs/design/session-framework/bus-v1.md

@@ -1,486 +0,0 @@
-# Flybus v1: a small Rust RPC and pub/sub bus
-
-Status: **draft 1**, 2026-09-18. Selected architecture for the new framework, not implemented
-runtime code. This document supersedes the earlier proposal for direct worker sockets plus
-a separate application bus and coordinator-owned buffer release protocol.
-
-**One library, one router, one wire protocol. Small messages carry metadata and artifact
-handles; large immutable bytes live in a managed local store. Ownership follows deliveries
-and explicit retention.** The router moves messages and tracks generic resource ownership.
-Applications own orchestration, presentation, effects and streaming. Sessions own simulation
-ordering. The bus knows nothing about brains, game frames, matches or Twitch.
-
-## 1. Scope and implementation shape
-
-Start with a Rust/Tokio library, an embeddable router and an optional small router executable.
-The same client API supports an in-memory test transport and Unix-domain stream sockets.
-All participants use router semantics even when colocated; there is no separate fast-path
-RPC protocol to maintain. Python helpers may implement a thin binding to the same schema;
-browser integration belongs to the application's presentation gateway.
-
-```text
-Application / supervisor ─┐
-Session coordinator ──────┤                 managed artifact store
-Agent workers ────────────┼── Flybus router ── immutable bytes
-Environment backend ──────┤                 handles in messages
-Presentation / recording ─┤
-Audience adapter ─────────┘
-```
-
-V1 supports one trusted local deployment with a shared local store. It does not require NATS,
-a service mesh, durable broker queues, cross-machine artifact transfer, load-balanced stateful
-workers, global transactions, dynamic plugins or a video codec. A private backend adapter may
-still speak an emulator's native pipes/protocol internally; that is not a second framework bus.
-
-Suggested crate: `flybus`, with `wire`, `router`, `client`, `artifact`, and `transport` modules.
-Split crates only when useful. Keep session/game types out of this library. Use Tokio, serde
-and a checked framing layer; persistent histories/checkpoints stay in application/session storage.
-
-## 2. Client API
-
-Illustrative Rust surface (not yet implemented):
-
-```rust
-let bus = Client::connect(config).await?;
-let service = bus.register("agent.fly-a", service_config).await?;
-let reply = bus.call(target, "Agent.Prepare", payload, attachments, budget).await?;
-let subscription = bus.subscribe("session.demo.snapshots", subscription_config).await?;
-bus.publish("session.demo.snapshots", payload, attachments).await?;
-
-let mut writer = bus.artifacts().allocate(size, content_type).await?;
-writer.write_all(&pixels)?;
-let frame = writer.seal().await?; // consumes writer; immutable Artifact handle
-bus.publish("world.demo.frame", metadata, [("frame", frame.clone())]).await?;
-
-let message = subscription.next().await?;
-let image = message.artifact("frame")?;
-drop(message);                 // image still owns the delivery guard
-render(image).await?;          // last handle drop releases ownership
-```
-
-RPC, pub/sub and artifacts all use this client/connection. The artifact store is a data
-structure/storage backend of the bus, not another messaging service. Bulk data does not
-pass through the router's socket payloads or require a separate application data-transfer API.
-
-`Artifact` is a read-only, cloneable handle. `ArtifactWriter` is unique and not cloneable;
-sealing consumes its writable lifetime. Mapped slices cannot outlive their handle. Rust RAII
-automates releases; other language bindings provide equivalent explicit close/context-manager
-behavior. Garbage collection means reclaiming an unowned artifact, not inspecting game state.
-
-## 3. Addressing and identities
-
-| Type | Meaning |
-| --- | --- |
-| `routerId` | Fresh router/store incarnation; changes after restart |
-| `clientId`, `clientIncarnation` | Configured participant identity and SDK client lifetime; reconnect creates a new incarnation |
-| `connectionId` | Fresh connection; v1 does not resume its queues or delivery owners |
-| `service`, `serviceIncarnation` | Named endpoint and opaque router-issued registration identity |
-| `callId` | Unique RPC correlation ID for this client incarnation; not a domain operation ID |
-| `topic`, `topicIncarnation`, `topicSequence` | Exact topic, declaration lifetime and acceptance order within it |
-| `deliveryId` | One recipient's message delivery and artifact ownership root |
-| `artifactId`, `generation` | Immutable byte object identity within a store incarnation |
-| `ownerId` | A connection-owned delivery or explicit artifact hold |
-
-Identifiers are bounded ASCII strings; scalar Id and U64 encodings match the common types
-in [session RPC contracts](ipc-v1.md). Service/topic names use 1..192 characters from
-`[a-z0-9._-]`, with no empty dot-separated segment. Exact names only in v1; wildcard routing
-and queue groups are deferred. The router treats names as opaque addresses.
-
-One live registration owns a service name. Duplicate registration fails; there is no implicit
-round-robin balancing or replacement of a stateful agent. Registration returns the incarnation.
-Callers pin it after discovery. If it changes, calls fail with `TARGET_CHANGED` rather than
-silently reaching another brain/environment. `Worker.Hello` remains a domain capability RPC,
-distinct from transport connection negotiation.
-
-Service/topic access is configured per participant by the launcher/application. Presentation
-subscribes to observations; it does not receive authority to invoke environment Advance.
-Audience effects go through application/session admission. Naming a target is not authority
-to control it. Public feed/control interfaces remain separate compatibility boundaries.
-
-## 4. Wire envelope and framing
-
-One connection handles both directions and every operation:
-
-```text
-u32 little-endian JSON byte length | UTF-8 JSON object
-```
-
-```ts
-interface BusEnvelope {
-  protocol: "flybus"; major: 1; minor: 0;
-  id: Id; replyTo: Id | null;
-  kind: "command" | "reply" | "delivery" | "notice";
-  op: string;
-  body: object;
-  attachments: Attachment[];
-}
-interface ArtifactRef {
-  storeId: Id; artifactId: Id; generation: U64;
-  byteLength: U64; contentType: string;
-  digest: Digest | null;
-}
-interface Attachment {
-  name: Id; ref: ArtifactRef; ownerId: Id;
-}
-```
-
-Maximum total JSON envelope is **65,536 bytes**. Up to 32 attachments, with unique names;
-contentType is a nonempty ASCII string <=127 bytes. No pixel/base64/checkpoint bytes in JSON.
-Artifact sizes are independent of envelope size. Domain schemas referencing artifacts MUST
-enumerate every referenced artifact in attachments; generated client bindings enforce this.
-The router validates attachment declarations/ownership, not the contents of domain payloads.
-
-Commands have unique monotonically issued `id` serials per connection (canonical `msg-<U64>`).
-Replies correlate with `replyTo`; routing notices/deliveries have router-generated IDs.
-The router supplies authenticated sender/target metadata on deliveries; senders cannot forge
-it by putting another participant's name in body. Domain `requestId` and callId remain distinct.
-
-Reject duplicate JSON keys, invalid UTF-8, NaN/Infinity, unknown envelope fields, zero/oversize
-frames and invalid ranges. Read length before allocating. Handle partial reads/writes and
-serialize one writer per connection. There are no ancillary-FD tricks in the first file-backed
-implementation. A future memory backend must retain the same client/ownership API.
-
-### Connection negotiation
-
-First command `bus.hello` has body `{clientId, clientIncarnation, supportedMajors}` and no
-attachments. Its reply reports `{routerId, connectionId, selectedMajor, selectedMinor,
-contractDigest, limits}`. The launcher provides expected client/registration privileges and
-local endpoint/store configuration. Refuse incompatible majors or identity mismatch before
-registration. Changes to these draft schemas change contractDigest; incompatible released
-schemas require a major version bump.
-
-The connection reader must dispatch incoming replies and requests without blocking on user
-handlers. Blocking neural computation runs on dedicated workers; artifact I/O/hashing runs
-outside the router's routing critical section. No mutable routing-state lock across slow I/O.
-
-Example RPC command (the counter service is a generic test, not a built-in router feature):
-
-```json
-{
-  "protocol": "flybus", "major": 1, "minor": 0,
-  "id": "msg-7", "replyTo": null, "kind": "command", "op": "rpc.call",
-  "body": {
-    "callId": "call-2", "target": "example.counter", "expectedIncarnation": "service-a",
-    "method": "Counter.Increment", "payload": { "amount": 1 }
-  },
-  "attachments": []
-}
-```
-
-An image-bearing publish has the same envelope shape. Its payload contains dimensions/time
-and an application-defined attachment binding; its attachment entry contains ArtifactRef and
-ownerId. byteLength may be `"1228800"`, while the entire message remains a small JSON object.
-
-## 5. Operation registry
-
-All operations use the envelope above. Replies are `{ok:true, value:object}` or
-`{ok:false, error:{code, message, dispatch}}`, where dispatch is `not-dispatched`, `dispatched`
-or `unknown`. Message length includes this wrapper. Transport error != domain error.
-
-| Command | Body / reply value | Semantics |
-| --- | --- | --- |
-| `service.register` | `{name, maxQueued, maxInFlight}` → `{serviceIncarnation}` | Exclusive endpoint, bounded capacities |
-| `service.unregister` | `{name, serviceIncarnation}` → `{removed}` | Stop new calls; queued calls fail; dispatched results follow §6 |
-| `rpc.call` | `{callId, target, expectedIncarnation:null|Id, method, payload}` → `{accepted, serviceIncarnation}` | Admission acknowledgment only, eventual rpc.result follows |
-| `rpc.reply` | `{callId, requestDeliveryId, outcome}` → `{routed}` | Reply only by the registered recipient; outcome is domain success/error |
-| `rpc.cancel` | `{callId}` → `{state}` | Best effort; only canceled-before-dispatch establishes no invocation |
-| `topic.declare` | `{name, retained:"none"|"latest"}` → `{declared, topicIncarnation}` | Compatible redeclaration allowed; conflicting settings fail |
-| `topic.clear` | `{name}` → `{cleared}` | Release retained topic root; does not invalidate deliveries |
-| `topic.delete` | `{name}` → `{deleted}` | Only when no subscribers; releases retained state |
-| `subscribe` | `{topic, mode:"latest"|"bounded", maxQueued, maxInFlight, replayLatest}` → `{subscriptionId, topicIncarnation}` | Exact topic; no durable history |
-| `unsubscribe` | `{subscriptionId}` → `{removed}` | Discard queued messages; already delivered handles remain valid |
-| `publish` | `{topic, payload}` → `{topicSequence, subscribers, replaced}` | Atomic publication admission/fan-out, not consumption |
-| `delivery.consumed` | `{deliveryIds:Id[]}` → `{released}` | Idempotent; processing and all local artifact uses have finished |
-| `artifact.allocate` | `{byteLength, contentType}` → `{artifactId, generation, ownerId, writeLocation}` | Reserve quota and private writable staging storage |
-| `artifact.seal` | `{artifactId, generation, ownerId, digest:null|Digest}` → `{ref, ownerId}` | Finish immutable publication; writeLocation no longer valid |
-| `artifact.open` | `{ref, ownerId}` → `{readLocation}` | Resolve an owned sealed object for read-only mapping, never return its bytes |
-| `artifact.retain` | `{ref, ownerId}` → `{ownerId}` | Create independent explicit hold while source ownership still exists |
-| `artifact.release` | `{ownerIds:Id[]}` → `{released}` | Drop explicit holds/staging writers; not another client's owners |
-
-Names/arrays/ranges follow §3/4/9. Release batches contain 1..64 IDs. No attachments are
-allowed on management commands except rpc.call/rpc.reply/publish. `outcome` is a bounded
-domain object; an incoming RPC result has its own attachments and delivery ownership.
-
-`accepted`, `routed`, `removed`, `declared`, `cleared`, `deleted`, `replayLatest` are booleans;
-`subscribers`, `replaced`, `released` are U64 counts. Released counts count newly released
-roots, so an idempotent repeat may report zero. Queue/credit requests are integers 1..65535
-and cannot exceed configured limits. Method strings are 1..128 printable ASCII characters.
-call target is a service name; expectedIncarnation is its registration ID, not worker process ID.
-Location grants are `{storeId, relativePath}` resolved by the client beneath the configured
-local store root; absolute paths, parent traversal and symlink escapes are rejected. They
-are SDK-private and do not appear in the application's ArtifactRef. Runtime paths are not
-committed into application schemas or source configuration.
-
-Deliveries:
-
-- `rpc.request`: `{deliveryId, callId, caller, target, serviceIncarnation, method, payload}`.
-- `rpc.result`: `{deliveryId, callId, responder, serviceIncarnation, outcome}`.
-- `topic.message`: `{deliveryId, subscriptionId, topic, topicIncarnation, topicSequence, replaced, payload}`.
-
-`caller`/`responder` include clientId and clientIncarnation. Delivery attachment ownerIds are
-replaced by the recipient's deliveryId; source owner tokens are never delegated verbatim.
-`topicSequence` and counters are U64 strings. The router assigns these IDs; the SDK exposes
-typed payloads plus Artifact handles. Required bounded notices are route removal, subscription
-closure and call failure. If even notice capacity is exhausted, close the connection instead
-of silently losing control-plane correctness; disconnect is itself a typed client failure.
-
-## 6. RPC behavior
-
-callId uses `call-<U64>` with increasing serials per connected client. Keep an admission
-watermark plus active-call entries; reused/retired call IDs are rejected, never executed again.
-Reconnecting creates a new clientIncarnation/connection rather than reviving its old calls.
-An RPC targets one registered service, not a broadcast subject. Preserve first-dispatch FIFO
-per caller/service; responses may complete out of order and correlate by callId. Service
-dispatchers can answer status concurrently with a long mutation, subject to their domain
-state rules. The router does not implement frame barriers or numerical ordering.
-
-Admission validates route, pinned incarnation, size, quotas and every source artifact owner.
-It establishes request-delivery roots atomically before accepting. Rejection establishes no
-delivery and drops any provisional roots. An accepted call is not proof that its handler ran.
-Before any request bytes can reach the target, mark it dispatched; subsequent transport loss
-is conservatively an unknown execution outcome.
-
-The service publishes a reply with its own owned artifact handles. The router establishes
-caller-result ownership before accepting that reply. It keeps only bounded call correlation
-metadata until result delivery is consumed or the caller detaches/disconnects. It is not an
-indefinite RPC result cache. A second rpc.reply for the same call is rejected, not routed twice.
-Responding does not release the request's delivery guard; the handler does so when finished.
-
-**No automatic retry or failover.** A deadline belongs to the calling client. On timeout the
-client may send rpc.cancel, but cancellation after dispatch cannot undo work. Domain retries
-use a fresh bus callId containing the **same domain requestId/body**, pinned to the same
-service incarnation. Endpoint-level deduplication supplies safe replay; the router does not
-infer it from method names. Never route a retry automatically to a restarted worker.
-
-Queued cancellation releases its queued artifact roots and returns `cancelled-before-dispatch`.
-After dispatch return `execution-unknown`; keep the recipient's delivery alive until consumed
-or disconnected. A later reply to a detached call returns `routed:false`, with no caller-result
-roots. The service still owns any retained result; domain state may have changed.
-If a terminal result is already admitted, cancellation reports `completed`; the client drains
-and consumes any result it no longer exposes to its caller. A retired/unknown correlation
-reports `call-gone`. These four strings are the complete rpc.cancel state enum. None authorizes
-re-execution, and cancelling a future does not abandon incoming delivery ownership.
-
-To replay an artifact-bearing response safely, endpoint code caches **Artifact handles plus
-payload**, not bare references. That cache owns explicit holds or delivery guards until domain
-acknowledgment/eviction. Re-delivery gets new delivery IDs pointing to the same immutable bytes.
-Once the domain cache expires it returns RESULT_EXPIRED; it cannot regenerate the operation
-merely because the transport correlation entry was removed.
-
-## 7. Pub/sub semantics
-
-Topic declaration does not teach the router what a topic means. An application can publish
-session observations, presentation cues, dataset jobs or unrelated typed events through the
-same API. There are no hardcoded frame/brain topics inside the router.
-
-- `latest`: one queued value per subscription, replacing only an **undelivered** value.
-  Replacing it releases that queue entry's artifact roots. Already delivered/in-use messages
-  are never reclaimed early. maxQueued is exactly 1 in this mode.
-- `bounded`: FIFO queue, no coalescing or silent loss. When required queue/owner capacity
-  is unavailable, reject the publication with BACKPRESSURE before admitting any deliveries.
-- maxInFlight credits are returned only by delivery.consumed, not socket write completion.
-  A latest subscriber with all credits in use still has one replaceable queued value.
-
-Take an atomic subscriber/retention snapshot at admission. Validate and reserve all required
-queue entries and artifact-owner budgets before accepting. For a bounded subscriber overflow,
-reject the **whole publish**; no partial fan-out or retained-latest update. On acceptance,
-assign one topicSequence and create roots for every delivery and optional retained value.
-Different topics have no total ordering. Multiple publishers on one topic follow router
-acceptance order, which is not automatically a deterministic application event order.
-
-Publication reply counts accepted subscriptions/replaced queue entries, not consumers that
-processed data. `replaced` on a delivery reports how many undelivered messages were coalesced
-since that subscription's preceding delivery. Sequence gaps can also arise from joining late;
-they are not evidence of a simulation step being skipped.
-
-Optional `retained:latest` holds one last message and its artifacts independent of subscribers.
-New subscriptions with replayLatest enqueue it before subsequent accepted publications;
-bounded mode preserves that order, while latest mode may coalesce it before delivery under
-the ordinary latest rule. Replay uses the original topicSequence, a fresh deliveryId and
-explicit roots. Without retention,
-zero-subscriber publication retains no artifact ownership after admission. Clearing a topic
-releases only its retained root, not active consumers. Topic count and retained bytes are capped.
-
-There is no durable replay, automatic redelivery, or exactly-once processing claim in v1.
-Deleting/redeclaring a topic creates a fresh topicIncarnation; a reset sequence cannot be
-mistaken for continuation of the deleted topic. Old subscription deliveries retain their
-original incarnation and ownership until consumed.
-If an application requires history, its recorder persists events and exposes a normal RPC
-for recovery/query. Bus admission, message consumption and durable storage acknowledgment
-are three different events. The bus must not conflate them.
-
-## 8. Artifact lifecycle and garbage collection
-
-### 8.1 Immutable object lifecycle
-
-```text
-ALLOCATED / WRITING → SEALED → referenced by owners → last owner drops → COLLECTED
-              └─ writer abandoned/disconnected ──────────────────────→ COLLECTED
-```
-
-`ArtifactRef` is an identity, not an address, filename or authority to read. Opening it requires
-a current ownership root belonging to that connection. storeId is the router/store incarnation;
-old handles fail after restart. V1 does not reuse an artifact ID/inode; generation is 1 and
-remains in the contract for future pool implementations. Content hashes are optional for live
-frames and mandatory for checkpoint/durable-content handoff, as specified by domain contracts.
-
-The first storage backend uses runtime-configured local files, optionally on tmpfs. Producer
-writes staging storage outside the message stream. Seal closes writable mappings/handles in
-the SDK, checks length and any requested digest, then finishes an immutable store-owned
-object before acknowledging. A correctness-first implementation may copy into a fresh sealed
-inode; account for both allocations during sealing. No per-frame fsync for transient media.
-
-Consumers resolve a store-issued readLocation through artifact.open and map/read it read-only.
-Locations are private grants; they are not placed in application bodies or public browser feeds.
-All filesystem access stays behind the client Artifact API. Do not inline binary data or create
-a second bulk-transfer server just because it is stored outside the socket.
-
-### 8.2 What owns an artifact?
-
-The store tracks an ownership graph, not only a naive refcount incremented by every packet:
-
-| Root | Lifetime |
-| --- | --- |
-| Producer explicit hold / active writer | Until last local handle releases, seal transfers its unique writer, or connection is lost |
-| Accepted queued delivery | Until replaced/cancelled or transferred into recipient delivery ownership |
-| In-flight delivery | Until message processing AND all extracted artifact uses finish |
-| Retained latest topic | Until replaced, cleared, deleted, or router stops |
-| Explicit retained hold | Until release; used for caches, rendering, checkpoint writes and forwarding |
-
-Admission creates destination roots before the sender may relinquish source roots. A forward
-or reply uses a live handle/owner; the client holds it until admission succeeds or definitively
-fails. A timeout must not drop a source guard while an unsent operation might still be admitted.
-The client cancels/discards the unsent frame or retains the guard until the transport outcome
-is known; connection teardown ends that ambiguity for the old connection.
-
-Every envelope must list its complete artifact set. Duplicate references in one delivery are
-counted once. A retained topic and several consumers can reference the same physical bytes.
-The router performs metadata updates only; it does not copy image bytes for fan-out.
-
-### 8.3 Consumed means no remaining use
-
-The incoming message owns a shared **DeliveryGuard**. Extracting an Artifact clones the guard;
-dropping the message alone does not consume the delivery while a renderer/encoder still uses
-its artifact. Local handle clones do not each require a bus round trip. Dropping the last
-guard queues delivery.consumed through a bounded control lane.
-
-V1 deliberately owns at delivery granularity: keeping one artifact from a message may keep
-the other attachments alive too. For independent long-lived retention, artifact.retain creates
-a specific explicit hold before the original guard is dropped. Domain RPC caches must use
-that hold when they outlive message processing/credits. An acknowledgment of domain success
-does not implicitly drop either the incoming guard or cached outgoing holds.
-
-If an allocation/seal grant arrives after its caller abandoned the future, the SDK reactor
-still processes and releases that grant. It must not leak an owner the application never saw.
-An in-progress seal/copy has a bounded internal I/O hold; on producer disconnect it either
-finishes cleanup or aborts safely, never publishes an ownerless object into a new connection.
-
-Async task cancellation/drop of a response future is not necessarily consumption: the client
-must own queued results until surfaced, explicitly discarded, or disconnected. Receivers must
-await completion of asynchronous CPU/GPU use before releasing its guard. A pointer extracted
-from a mapping cannot outlive its Artifact; FFI wrappers must enforce this lifetime explicitly.
-
-Release commands are batched, idempotent and scoped to the connection that owns the IDs.
-Delivery/hold IDs use monotonic per-connection serials. Keep issued watermarks plus active
-owner maps; releasing an already retired ID is a no-op, a never-issued/future ID is an error.
-This avoids a tombstone per frame forever. Control-lane exhaustion closes the connection
-instead of silently losing releases and leaking an unbounded ownership graph.
-
-### 8.4 Crash, disconnect and safe physical reclamation
-
-On disconnect, unregister services/subscriptions; cancel queued deliveries and release that
-connection's active writers/explicit/delivery roots. Retained topic roots remain router-owned.
-Late replies and releases cannot attach to a new connection or service incarnation.
-
-GC removes the registry entry and unlinks/closes the sealed object after its final root is
-gone. Existing immutable file mappings may remain valid until the OS closes the last mapping;
-do not overwrite their inode or reuse their bytes. Logical reclamation is not proof that a
-disconnected process released its physical pages. The supervisor handles stuck processes;
-resource measurements include OS mappings and client memory, not just registry totals.
-
-No TTL may reclaim a live owned artifact. Limits may disconnect a consumer, triggering the
-explicit cleanup above, but cannot overwrite memory under a renderer. Future pooled shared
-memory must prove equivalent lifetime/generation safety before replacing immutable files.
-
-Router restart creates a new routerId/storeId, loses routes/queues/retention and invalidates
-all old handles. Live sessions fail their current epoch and use coherent recovery. Persistent
-artifacts come from the application's durable store and are re-imported as new bus objects.
-Orphan files from a stopped router are cleaned without treating them as durable checkpoints.
-
-## 9. Bounds, scheduling and failure reporting
-
-Configure limits explicitly; these defaults are a prototype starting point, not capacity data:
-
-| Resource | Default |
-| --- | ---: |
-| Connected clients / services / topics | 64 / 256 / 512 |
-| Subscriptions per client / total | 128 / 1024 |
-| Control envelope | 64 KiB |
-| Active calls per client | 64 |
-| Service queued / in-flight calls | 16 / 16; worker dispatcher further limits mutations |
-| Latest subscription queued / in-flight deliveries | 1 / 2 |
-| Bounded subscription queued / in-flight deliveries | 64 / 16 |
-| Active owners per client | 256 |
-| Total artifact storage / per object | 512 MiB / 128 MiB |
-| Per-client ordinary queued envelope bytes | 1 MiB |
-| Reserved management/reply lane | 128 frames and 1 MiB per client |
-
-Reserve an owner allowance for lifecycle/results separately from ordinary telemetry; memory
-quotas account for staging/seal copies, queued deliveries and caches. Ownership metadata is
-bounded even if many roots share one artifact. Disk-full, allocation failure or hash mismatch
-returns a typed artifact error and cleans provisional storage/roots.
-
-The router fairly services clients. Replies, release, cancellation and route-health control
-cannot be starved by telemetry. Preserve FIFO for calls to a target despite lane scheduling;
-classification is an explicit generic envelope operation/policy, not a topic-name heuristic.
-No indefinite wait inside the router on subscriber readiness or artifact I/O. Admission is
-bounded; rejected callers choose their own retry/fail/pause policy.
-
-Transport errors include `INVALID_ENVELOPE`, `VERSION_MISMATCH`, `NOT_AUTHORIZED`,
-`NO_SERVICE`, `TARGET_CHANGED`, `BACKPRESSURE`, `CALL_GONE`, `ARTIFACT_UNSEALED`,
-`ARTIFACT_GONE`, `OWNER_INVALID`, `QUOTA_EXCEEDED`, `STORE_FAILURE`, `ROUTER_LOST`.
-Before admission use dispatch:not-dispatched. Once dispatch might have occurred, report
-unknown/dispatched conservatively; a caller-side timeout must not imply no mutation.
-
-Bounded event subscriptions can reject publication; latest spectator subscriptions cannot
-hold a required session transaction indefinitely. Per-client credit/owner budgets and
-supervision enforce that distinction. Sustained pinned-artifact quota exhaustion is surfaced
-as resource pressure, not solved by freeing live data. Session/app policies choose whether to
-disconnect an observer, pause, or fail; the router does not know which outcome is appropriate.
-
-## 10. Native-frame bandwidth check
-
-At 640×480 RGBA, a frame is 1,228,800 bytes. At 60 fps, production is **73.728 MB/s**
-(decimal); at 30 fps, 36.864 MB/s. These are planning dimensions; a backend advertises its
-actual output. Two agent workers plus one presentation consumer can read the same immutable
-frame object. Bus messages contain only references; there is no 3× byte fan-out through the
-router. Readers still incur memory traffic/page faults, and renderer readback/seal copying
-remain real costs. This is not a claim of zero-copy GPU capture or measured host performance.
-
-The environment emits native game frames/audio. The application/presentation layer owns
-resizing, overlays, compositing, browser delivery, codec choice and stream output. Do not put
-1080p rendering, Twitch publishing or game-specific sampling logic in Flybus. A presentation
-pipeline may itself exchange large artifacts through this same bus if useful.
-
-## 11. Acceptance tests and implementation sequence
-
-1. **Wire/router:** schema/framing, Hello, exclusive routes, pinned incarnations, request/reply,
-   disconnect and bounds. In-memory transport must pass the same tests as Unix sockets.
-2. **Pub/sub:** exact topics, FIFO/bounded rejection, latest coalescing, retained replay/clear,
-   atomic fan-out and fair control/reply delivery under a saturated subscriber.
-3. **Artifacts:** allocate/seal/read; publication before seal fails; fan-out owns one physical
-   object; last consumer releases; retaining an extracted frame after message drop works.
-4. **Faults:** sender drops after admission; consumer dies mid-read; reply is lost; queued frame
-   is replaced; subscription closes with in-use deliveries; router restarts; old release arrives.
-   No double-free, use-after-reuse, unbounded tombstones or hidden operation replay.
-5. **RPC cache:** endpoint retains an artifact-bearing result, original caller consumes it,
-   and a domain retry still returns valid bytes. Eviction drops the last cache hold correctly.
-6. **Integration:** two parallel fake agents, complete-batch environment RPC, committed snapshot
-   publication and a deliberately slow presentation consumer over the same router.
-7. **Performance:** 640×480×60 artifact production with three consumers, one delayed; measure
-   p50/p95/p99 RPC latency, router CPU, copy/readback cost separately, RSS, store live/peak bytes,
-   outstanding roots, collection lag and queue lengths. Compare one/two/four agent schedules.
-
-The first executable example should show a counter RPC, a pub/sub observer, and a frame
-artifact held past message consumption in one small Rust program. No game or browser required.
-Distributed simulation ordering remains the [session contract's](step-v1.md) responsibility.

docs/design/session-framework/implementation.md

@@ -1,270 +0,0 @@
-# Future-agent implementation guide
-
-Status: **draft 2**, paired with the [contract index](README.md). This is the execution guide
-for the new process architecture; it refines the broader
-[MaleCNS/modular backlog](../malecns-modular-implementation.md), not a request to implement
-every future feature in one branch.
-
-## 1. Start here
-
-Before coding:
-
-1. Read repository instructions, the architecture tour, public feed/control contracts, and all
-   documents in this directory. Reconcile any newer main/feature-branch changes with this baseline.
-2. Record what the next slice will change, its compatibility surface and expected tests.
-3. Use a dedicated branch/worktree. Follow the repository's coordinator/build/review roles.
-4. Preserve the TypeScript oracle, default numerical version strings and legacy deployment.
-5. Resolve contract contradictions before implementing; do not fill gaps with an implicit
-   asynchronous best-effort policy or a public controller API.
-
-The immediate target is **one small Rust Flybus example with RPC, pub/sub and a frame artifact
-held beyond the message object's lifetime**. Then build the synthetic two-agent session over
-that same router using in-memory and Unix-socket transports. No separate worker transport,
-NATS service, coordinator-owned lease manager or raw-frame socket channel is to be implemented.
-
-## 2. Proposed implementation map
-
-Begin under the existing Rust workspace; extract physical package locations separately.
-The following are proposed names, not files that exist today:
-
-```text
-services/flysim/crates/
-  fly-session-types/     scopes, contracts, schema validation, canonical digests
-  flybus/               generic router/client/wire/artifact store; embedded or standalone
-  fly-session-rpc/       domain schemas/deduplication over flybus; NOT another transport
-  fly-session/           phase machine, coordinator, admission, task/executor traits
-  fly-session-worker/    dispatch shell, status/shutdown, agent/environment adapters
-  fly-session-store/     participant captures, manifest commit, group recovery
-
-services/flysim/crates/flysim/
-  legacy/               compatibility composition (extract without changing behavior)
-  composition/          new config/registries and worker launching
-
-packages/feed/          existing public v1, later public v2 schemas/fixtures
-packages/brain/         reference model/readout and new contract-relevant golden generators
-```
-
-Do not create empty crates to satisfy this tree. In the first slice, types/transport/coordinator
-may be modules in one small crate; split when dependencies and consumers justify it. Keep
-Melee parser/codecs and Game Boy FFI out of the session-types crate. Worker executables can
-be subcommands of one binary initially; process boundaries do not require separate repos.
-
-## 3. Ordered slices
-
-### CONTRACT-01 — Executable schemas and trace format
-
-**Inputs:** [bus spec](bus-v1.md), session RPC, step, worker, state/media and publishing documents.
-
-**Implement:** Flybus wire schema separately from session domain schemas; common scalar types,
-closed enums, method payload validation and schemas;
-canonical digests; fixture loaders in Rust/TypeScript. Specify seed derivation and exact
-checkpoint envelope bytes before their respective real-agent/store slices. Create the trace
-format from step-v1 section 8, distinguishing behavior fields from operational IDs/time.
-
-**Acceptance:**
-
-- JSON round trips across both languages; U64/float boundaries reject correctly.
-- Duplicate keys, invalid UTF-8, envelopes over 64 KiB and unknown required fields fail.
-- Distinguish bus callId, domain requestId, artifact identity and delivery/hold owner tokens.
-- Fixtures include rational zero/reduced form, overflow, duplicate ports and analog limits.
-- Contract digest is generated from a documented canonical schema set, not source formatting.
-
-**Stop:** do not wire a real worker until payload ambiguities and retry identity rules agree.
-
-### BUS-01 — Router and RPC, in-memory and Unix socket parity
-
-**Depends on:** CONTRACT-01.
-
-**Implement:** one flybus crate with bounded framing, bus.hello, exclusive service registration,
-incarnation-pinned RPC/reply/cancel, typed route/admission errors and independent read/write
-dispatch. Begin with artifact-free calls; do not claim full bus conformance until BUS-03.
-
-**Acceptance:**
-
-- Partial frames/writes, disconnect after request, lost result and retransmission fixtures.
-- No automatic retry/failover; timeout/cancel-after-dispatch reports uncertain execution.
-- Service incarnation replacement is visible. Request/reply correlation survives out-of-order
-  replies; status RPC can respond while another handler is delayed. Saturation is bounded.
-- Both transports produce equivalent behavior traces for the same scenario.
-
-### BUS-02 — Pub/sub, retention and backpressure
-
-**Depends on:** BUS-01.
-
-**Implement:** exact topics, subscribe/unsubscribe, bounded FIFO and latest policies, optional
-retained latest/clear, per-recipient delivery IDs/consumption credits and fair control lanes.
-
-**Acceptance:** overflow rejects a bounded publication before partial fan-out; latest replaces
-only queued messages; delivery consumption returns credits; unsubscribe preserves already-
-delivered ownership; retained replay is ordered; stalled observers cannot starve RPC replies.
-Durable event history is a storage client, not a second broker built into Flybus.
-
-### BUS-03 — Artifact-backed messages and automatic lifetimes
-
-**Depends on:** BUS-02.
-
-**Implement:** immutable file-backed store, allocate/seal/open, bus attachment validation,
-producer/queue/delivery/retention owners, RAII DeliveryGuard and explicit cache holds. Root
-creation/admission is atomic. Start with ordinary local files/tmpfs; no pooled slot reuse yet.
-
-**Acceptance:** last owner collects; extracted handle survives message drop; forward-before-
-release is safe; lost replies/cache replay remain valid; disconnect releases logical ownership
-without mutating still-mapped bytes; retained latest and queue replacement release correct roots.
-Measure 640×480 RGBA×60 with three readers: one stored image, no raw pixels in router messages,
-bounded CPU/RSS/owners/queues. Record reader/copy costs rather than claiming zero-copy capture.
-
-### SESSION-01 — Synthetic sequential transaction
-
-**Depends on:** BUS-03.
-
-**Implement:** small fake agent workers, one counter/arena environment, identity executors
-and a deterministic task. Follow Prepare→Advance→Evaluate→Commit exactly. Use explicit seeds
-and rational clock accumulation; the fake model must expose a mutation counter for tests.
-Implement domain request deduplication/result caches over bus calls; retaining result artifacts
-is an endpoint responsibility. Domain Acknowledge differs from bus delivery.consumed.
-
-**Acceptance:**
-
-- One world advance per complete batch; every agent Prepared before Advance.
-- Task evaluates once; every agent commits before next Prepare or committed publication.
-- A synthetic 60-Hz/1-ms profile produces 16,17,17 ticks and remainder zero after three steps.
-- Pause mid-step completes the step and pauses at its committed boundary.
-- Bootstrap/warm-up cannot advance the environment or produce gameplay rewards.
-- Domain retries use a new callId with the original requestId; they never repeat ticks/reward.
-
-### SESSION-02 — Parallel processes and fault behavior
-
-**Depends on:** SESSION-01.
-
-**Implement:** one agent process per fly and one environment process under the coordinator;
-compare with in-process and dedicated-thread variants. Enforce total thread budgets and
-configured agent/port identities. Failure stops the epoch rather than neutralizing a player.
-
-**Acceptance:** sequential, reversed order and parallel completion produce equivalent traces;
-delayed one-agent result holds the world; worker/helper death has a bounded diagnosed outcome;
-an uncertain Advance never creates a second batch; partial Commit never permits next-step play.
-
-### MEDIA-01 — Native observation schemas and presentation handoff
-
-**Depends on:** SESSION-02.
-
-**Implement:** view/sample descriptors and producing-step validation on top of bus ArtifactRef,
-not a second buffer system. Environment outputs native media; sensor transforms remain agent
-profiles, while presentation owns viewer resizing/composition/audio/streaming.
-
-**Acceptance:** bad strides/lengths/producer times fail; shared image reaches both agents through
-owned attachments; spectators use latest subscriptions and cannot corrupt sensory state;
-delayed rendering retains its handle. Distinguish AssetRef from transient ArtifactRef.
-
-### AGENT-01 — Existing neural core worker
-
-**Depends on:** SESSION-02, MEDIA-01 and the profile/identity foundation in the broader backlog.
-
-**Implement:** adapter over existing LIF, plasticity, retina and fixed readout primitives;
-reference-first composition/goldens; independently seeded agent state and shared immutable data.
-Avoid using the old whole-frame `tick` wrapper if it changes the specified phase ordering.
-
-**Acceptance:** per-agent state agrees with the reference across Prepare/Commit, stimulation,
-zero/nonzero reward, warm-up and pauses. Two agents cannot share gains/RNG/holds; swapping
-dispatch order and varying worker count preserves results. Keep 64-role limits explicit.
-
-### ENV-01 — Game Boy compatibility environment
-
-**Depends on:** AGENT-01 and environment/task extraction in the broader backlog.
-
-**Implement:** binjgb environment, task-local memory inspector and identity/existing action
-adapter. Keep `legacy-gameboy-v1` separately routed with exact old ordering/hash semantics.
-
-**Acceptance:** legacy fixtures/goldens/restore outcomes unchanged; the new composition has
-its own identity and public adapter selection. No console-specific state enters generic
-session types. ROM-backed checks are optional explicit jobs, not required downloads.
-
-### STATE-01 — Coherent all-participant checkpoint/recovery
-
-**Depends on:** SESSION-02, MEDIA-01; validate with fake agents first, then AGENT-01/ENV-01.
-
-**Implement:** exact new envelope schema, compatibility manifest, Capture/StageRestore/
-ActivateRestore, bounded writer, durable commit acknowledgments and fresh-epoch fencing.
-Keep old `FLYSIM01` reader separate. Payloads and coordinator state must refer to one boundary.
-
-**Acceptance:** uninterrupted versus resumed synthetic/real-agent traces match after accounting
-for new epoch metadata; corrupt any participant and installation fails as a group; lost save
-reply doesn't advance durable metadata; failure during activation cannot resume half a world.
-Checkpoint queue stress remains bounded; verify old media/parser data cannot cross recovery.
-
-### PUBLISH-01 — Committed snapshots and observer isolation
-
-**Depends on:** SESSION-02, MEDIA-01; public v2 contract work is a separate prerequisite to
-publishing a supported multi-agent browser feed.
-
-**Implement:** internal [publication boundary](publishing-v1.md) over the SAME bus, latest-value
-observations, application-owned state/cues, bounded events, descriptor repair/query and a fake
-multi-agent consumer. Presentation gateway owns browser delivery; no generic show/tournament
-service or codec is added to the router. Then implement
-the approved public v2 wire schemas/fixtures and stage adapters together.
-
-**Acceptance:** browser disconnect/backpressure never advances/stalls the world; future agent
-state is not mixed with old media; descriptor/index mismatch is visible; committed actions
-are labeled as the transition that just ended. PNG/browser review gates apply to actual UI.
-
-### DOLPHIN-01 — Substitute the backend, not the coordinator
-
-**Depends on:** measured MELEE-01/02 spikes from the [Melee audit](../melee-framework-audit.md),
-SESSION-02, MEDIA-01 and declared recovery support.
-
-**Implement:** bus-connected helper over pinned Dolphin/libmelee or the chosen narrow hook,
-complete port batch adapter, frame-identified sensory output and task-local Melee inspection.
-Keep actual rendering/input/save semantics behind the same Environment API.
-
-**Acceptance:** all generic backend conformance tests plus delayed-port/flush ordering,
-game-frame reset, parser recovery, pixel latency and neutral/release tests. If exact snapshot
-is unsupported, advertise episode-restart and use only the matching prototype policy.
-
-## 4. Failure injection checklist
-
-Tests must deliberately inject these cases; success-path demos are insufficient:
-
-| Injection | Required invariant |
-| --- | --- |
-| Duplicate Prepare after lost reply | No extra ticks, RNG draws, stimulation or decode |
-| Same batch with altered controls | Conflict, never a second world mutation |
-| Lost Advance result after world step | Resolve same operation or fail epoch |
-| One Commit fails after another succeeds | No next world step; coherent recovery only |
-| Old worker replies after restore | Stale epoch/incarnation rejected |
-| Message drops while extracted image is rendering | DeliveryGuard keeps bytes alive through last use |
-| First agent releases a shared image early | Artifact remains until every other owner finishes |
-| Cached RPC artifact is consumed by its first caller | Domain cache still owns it for retry |
-| Latest queued frame is replaced | Only that queue root drops; in-use images remain valid |
-| Router restarts during a world advance | Old handles/routes invalid; epoch fails and restores coherently |
-| Viewer holds output indefinitely | Only spectator data is dropped/disconnected |
-| Backend waits for input while capture is requested | No deadlock; capture only at valid quiescent boundary |
-| Capture writer stalls | Finite queue/memory, honest durable status |
-| StageRestore validates three participants, fourth fails | Nothing is resumed |
-| ActivateRestore fails halfway | Group remains fenced, no new gameplay |
-| Old epoch audio arrives after reset | Discontinuity handling; no stale playback as current |
-
-## 5. Verification and handoff
-
-Before each implementation merge, run the repository's required `npm test`,
-`npm run typecheck`, `cargo test --workspace` from the Rust workspace, and
-`infra/tests/lint.sh`. Run affected browser/PNG gates for presentation changes. Keep the
-existing committed FAFB real-data goldens mandatory; larger new datasets and game-backed
-jobs report explicit optional skips.
-
-Performance checks report total physical-core allocation, one/two/four agents, within-agent
-worker count, router/RPC latency, artifact production/read/copy time, critical-path percentiles,
-memory peaks, owner/GC statistics and
-bounded queue behavior. No host capacity claim follows from a local synthetic timing test.
-Deployment-host work is separately authorized/claimed/serialized under repository rules.
-
-Every completed slice leaves:
-
-1. The implemented contract/schema revision and compatibility decisions.
-2. A minimal runnable synthetic example and exact test commands/results.
-3. Behavior traces demonstrating its acceptance criteria.
-4. Known unsupported capabilities and remaining measured questions.
-5. Updated planning status, with no claims that a stub provides real emulator semantics.
-
-Do not start by moving every directory, adding a service mesh, or rewriting the model. The
-first useful deliverable is the small artifact-backed bus example, followed by the synthetic
-distributed step transaction using it. No one-off communication stack per component.

docs/design/session-framework/ipc-v1.md

@@ -1,207 +0,0 @@
-# Session RPC contracts over Flybus
-
-Status: **draft 2**, 2026-09-18. The filename is retained for existing links. This document
-now defines **domain contracts carried by [Flybus v1](bus-v1.md)**. It no longer defines a
-separate socket protocol, direct worker connections, or coordinator-owned buffer service.
-The [architecture index](README.md) states scope and precedence. Public feed/control v1 stay
-unchanged; this is the new internal session path.
-
-## 1. One transport, domain-specific meaning
-
-Every session/worker RPC is a Flybus call to a named, incarnation-pinned service. Pub/sub,
-application supervision and artifact bookkeeping use the same bus. The router moves messages;
-the receiver validates its method payload and the [session step machine](step-v1.md).
-
-The bus owns framing, connection identity, route registration, bounded delivery and artifact
-ownership. This document owns Scope, model-related scalar types, worker capability negotiation,
-domain operation deduplication and errors. Domain request identity is independent of the bus
-callId: a safe retry has a new transport callId but the original domain requestId/body.
-
-## 2. Common domain types
-
-```ts
-type Id = string;       // ^[a-z0-9][a-z0-9._-]{0,63}$
-type U64 = string;      // "0" or [1-9][0-9]*; <= 18446744073709551615
-type Digest = string;   // 64 lowercase hexadecimal digits (SHA-256)
-interface Scope { sessionId: Id; epoch: Id; step: U64 }
-interface RationalNs { numerator: U64; denominator: U64 }
-interface SchemaRef { id: Id; version: number; digest: Digest }
-interface TypedValue { schema: SchemaRef; value: object }
-interface SessionRpcRequest { requestId: Id; scope: Scope | null; params: object }
-```
-
-All fields are required unless marked `?`. Schema version is integer 1..65535. Fractions
-are reduced, denominators positive, durations positive; zero is encoded 0/1. Arithmetic is
-checked. JSON numbers representing rates/rewards/controls are finite. Counters/clocks use
-decimal strings. Task/profile schemas bound collections and numeric ranges before mutation.
-First session composition limit: 4 agents, 4 ports and 64 rate roles per agent; these are
-session/model limits, not limits on the number of application personas or generic bus clients.
-
-Each TypedValue has a canonical JSON size limit of **32 KiB**, while the complete envelope
-must still fit Flybus's 64-KiB maximum. Large typed state goes in a listed Artifact attachment
-under an explicit schema, not an oversized inline object. Changing the old draft's 1-MiB
-worker envelope to Flybus must not silently truncate a payload.
-
-## 3. Request/reply mapping
-
-Illustrative client call:
-
-```text
-bus.call(
-  target = {service: "agent.fly-a", expectedIncarnation: pinnedRegistration},
-  method = "Agent.Prepare",
-  payload = {requestId: "req-41", scope: {sessionId, epoch, step: "41"}, params},
-  attachments = ownedArtifactHandles
-)
-```
-
-Flybus's eventual rpc.result `outcome` is one of:
-
-```ts
-interface SessionRpcSuccess {
-  type: "result"; requestId: Id; workerId: Id; incarnationId: Id;
-  scope: Scope | null; result: object;
-}
-interface SessionRpcFailure {
-  type: "error"; requestId: Id; workerId: Id; incarnationId: Id;
-  scope: Scope | null;
-  error: { code: ErrorCode; message: string; mutation: "none" | "applied" | "unknown" };
-}
-```
-
-Replies echo the original scope. The receiver identity and bus service incarnation must
-match the negotiated worker. Bus route/admission failure is not a SessionRpcFailure produced
-by the handler. A bus admission acknowledgment is not an Agent.Prepare/Environment.Advance
-completion. Only a matching terminal domain reply resolves a simulation phase.
-
-ArtifactRefs inside request/result payloads must be declared in bus attachments and backed by
-live owned handles. Domain canonical-body digests include the references but exclude changing
-bus callIds, deliveryIds and owner tokens. A cached result owns Artifact handles independently
-of the first delivery; it is not a JSON object holding unowned pointers.
-
-## 4. Worker negotiation and status
-
-After bus connection/registration, call Worker.Hello (`scope:null`):
-
-```ts
-interface HelloParams {
-  sessionId: Id; expectedWorkerId: Id;
-  role: "agent" | "environment" | "coordinator";
-  supportedMajors: number[];
-}
-interface HelloResult {
-  selectedMajor: 1; selectedMinor: 0;
-  workerId: Id; incarnationId: Id; role: "agent" | "environment" | "coordinator";
-  buildDigest: Digest; contractDigest: Digest;
-  capabilities: Id[];
-  limits: { maxAgents: number; maxPorts: number };
-}
-```
-
-The bus supplies caller identity; do not accept a forged caller in params. Bind a worker's
-session authority to the expected coordinator identity/incarnation during negotiation and
-initialization. Wrong worker/role, no common major or missing required capability refuses
-the composition. Required capabilities are agent-step-v1 and world-step-v1 for their roles;
-checkpoint-v1 and pixel-observation-v1 are conditional. Artifact transport capability is
-negotiated once by Flybus, not as another worker memory API.
-
-Worker.Status has params `{}` and the caller's last known scope (null before initialization):
-
-```ts
-interface StatusResult {
-  state: "uninitialized" | "ready" | "preparing" | "prepared" | "advancing"
-       | "committing" | "capturing" | "staged-restore" | "restoring"
-       | "failed" | "stopping";
-  currentScope: Scope | null;
-  activeRequestId: Id | null; lastCompletedRequestId: Id | null;
-  lastBatchId: Id | null; progressCounter: U64;
-}
-```
-
-ProgressCounter advances on computational/phase progress, not on status queries. Dispatch
-Status through the same service without waiting for a long numerical operation. One mutation
-executes at a time; at most one may be pending, and normal stepping pipelines neither. The
-router's larger RPC capacity is not permission to overlap worker mutations. Never hold a
-simulation lock while waiting for network I/O, artifact resolution or release bookkeeping.
-
-## 5. Domain idempotency and retention
-
-`requestId` is `req-` plus a canonical U64 serial, increasing for newly issued operations
-per caller/worker pair. Retries reuse it unchanged even though bus callId changes. Flybus
-preserves first-dispatch order per caller/service; worker handlers maintain that request
-admission order while allowing read-only status alongside compute.
-
-The operation key for step mutations is `(sessionId, epoch, step, method, workerId)`.
-There is at most one Prepare, Commit or Advance for that key.
-
-- Same key/request/body returns its cached reply, with fresh bus delivery ownership over
-  retained artifacts. It never repeats ticks, stimulation, controller execution or reward.
-- Changed ID/body for an existing key is CONFLICT. Canonical comparison uses RFC 8785 over
-  method, scope and validated params. A rejected duplicate does not undo the earlier result.
-- Check retained request identity before phase checks or artifact dereferencing. A duplicate
-  may arrive after the original input delivery was consumed; it needs only the cached result.
-- Keep current/immediately previous step result records. Eviction never enables reexecution:
-  highest-issued request serial and step watermarks reject expired retries/old steps.
-- Original expired serial → RESULT_EXPIRED; fresh serial naming an old step → STALE_STEP.
-
-An exact duplicate arriving while execution is active receives the terminal domain error
-IN_PROGRESS for that **bus call**. The original bus call still completes normally. Retry or
-query Status later; no second mutation is started. This avoids multiple terminal replies to
-one bus call and does not mistake IN_PROGRESS for the original operation's failure.
-
-Lifecycle/capture replies are retained until Worker.Acknowledge:
-`params:{requestIds:Id[]}` (1..16), result `{acknowledged:Id[]}`. It drops domain cache handles,
-not another consumer's bus delivery. Already released/unknown IDs are ignored. Serial
-watermarks reject reuse after acknowledgment without an unbounded tombstone list.
-
-Bound unacknowledged lifecycle replies at 16, then BUSY before application. Status and
-Acknowledge use a cache of their last 16 replies; current/previous step records have their
-separate finite retention. Caches containing big artifacts consume bus owner/byte budgets;
-configure capture limits consistently. Never evict a promised replay artifact but keep a
-successful pointer-only reply. An intentionally expired result returns RESULT_EXPIRED.
-
-## 6. Timeout and failure handling
-
-Timeouts are measured on the caller's monotonic clock. Prototype defaults: probe after two
-seconds without reply, fail after ten seconds without progress; long boot/capture have separate
-budgets. These are failure-detection values, not a gameplay latency goal.
-
-After an uncertain call:
-
-1. Stop further world-step dispatch.
-2. If the same bus/service/worker incarnation still exists, query Status or issue a fresh
-   bus call with the original domain requestId/body and retained input attachments.
-3. Resolve only a matching terminal result. Never repeat an Advance with a new domain ID.
-4. If routes/ownership were lost, incarnation changed or retained result expired, fail the
-   epoch and restore/reset the group.
-
-Endpoint crash or bus restart is not covered by in-memory deduplication. Router/store restart
-invalidates all transient artifacts and routes. Worker disconnect also invalidates its bus
-owners and registration; v1 does not silently reattach that worker to an active epoch.
-Recover coherently even if an OS process survived with some numerical state in memory.
-
-## 7. Domain errors
-
-| Code | Meaning |
-| --- | --- |
-| INVALID_ARGUMENT | Invalid schema/range, before mutation |
-| UNSUPPORTED | Missing method/capability |
-| IDENTITY_MISMATCH | Wrong session/profile/port/build/asset identity |
-| STALE_EPOCH / STALE_STEP / FUTURE_STEP | Timeline/order mismatch |
-| INVALID_PHASE | Wrong worker phase |
-| CONFLICT | Existing logical operation with changed ID/body |
-| IN_PROGRESS | Original operation still executing; duplicate bus call did not start work |
-| BUSY | Domain capacity unavailable before admission |
-| BUFFER_INVALID | Missing/unowned/mismatched artifact or invalid media shape |
-| RESULT_EXPIRED | Safe replay is no longer available; never recompute to replace it |
-| INCOMPATIBLE_STATE | Restore validation failed before activation |
-| BACKEND_FAILURE / INTERNAL | Runtime fault, with explicit mutation certainty |
-
-Messages are <=512 code points and exclude raw game memory/credentials. Errors after partial
-mutation use unknown unless completion is established. No error authorizes skipping a fly,
-pressing fallback controls, or continuing a partially committed match.
-
-Worker.Shutdown, params `{reason:Id}`, returns `{stopping:true}` if responsive and terminates
-the worker after replying. It does not imply saved state. Only configured supervisors may
-invoke it; workers have no authority to shut down the coordinator. Shutdown/release notifications
-travel on the same bus; there is no reverse lease socket or Buffer.Release/Reclaim RPC.

docs/design/session-framework/publishing-v1.md

@@ -1,184 +0,0 @@
-# Application, presentation and audience contracts
-
-Status: **draft 2**, 2026-09-18. All internal communication uses [Flybus](bus-v1.md). This
-document defines ownership and logical data contracts, not the public feed v2 byte format.
-Existing public v1 contracts remain unchanged for the legacy application.
-
-## 1. Applications orchestrate; presentation owns the show
-
-Fly Plays Pokémon is an application assembled from simulation and presentation components.
-Its supervisory code and interface share an application-owned, versioned state/event schema.
-A Melee competition or ecosystem can choose another schema. Director, tournament, bracket,
-cast of 32 personas and story segments are examples, not mandatory framework services/types.
-
-The framework supplies sessions, agents, backend/task interfaces, capability descriptions,
-native observations and generic UI/client primitives. The application chooses lifecycle,
-profiles, game-aware macros/recovery, identities/history, interventions and narrative behavior.
-Frame-by-frame scheduling remains inside the session; the application need not RPC each tick.
-
-Presentation owns selection/layout, resizing, overlays, compositing, audio mixing, encoding,
-browser-facing delivery, recording choices and stream output. Native 480p game data is a
-perfectly valid framework output. Neither the router nor generic session assumes Twitch,
-1920×1080, particular colors, specific React components or an automatic tournament dashboard.
-
-## 2. One bus, complementary data sources
-
-```text
-Session ── committed observations/events + artifact handles ──┐
-                                                           ├─ Flybus ── presentation application
-Application ── own state/events/presentation cues ────────────┘
-Presentation gateway ── application-defined browser delivery ── frontend
-```
-
-Example addresses (chosen by composition, not recognized by router code):
-
-| Address | Pattern / purpose |
-| --- | --- |
-| `session.demo` | RPC: domain lifecycle/status/capabilities; exact methods require session API schemas |
-| `session.demo.descriptor` | Pub/sub, retained latest: framework descriptor |
-| `session.demo.snapshots` | Pub/sub, latest: committed simulation values and native media refs |
-| `session.demo.events` | Pub/sub, bounded: scoped domain events; not a durable log |
-| `app.pokemon.state` | Pub/sub, retained latest: application-specific state |
-| `app.pokemon.cues` | Pub/sub: application narrative/presentation events under declared delivery policy |
-| `app.pokemon` | RPC: application queries/admission, e.g. restore UI state or request a supported effect |
-
-Descriptor revisions and scope link observations to schemas. Cross-topic ordering is not
-guaranteed; a subscriber receiving an unknown descriptor revision must fetch it through the
-application/session query contract or buffer a bounded number of snapshots, not infer shape.
-Latest retained descriptors accelerate startup; RPC querying remains the repair path.
-
-## 3. Common simulation descriptors and committed values
-
-Types use [session RPC](ipc-v1.md), [workers](workers-v1.md), [state/media](state-media-v1.md):
-
-```ts
-interface SessionDescriptor {
-  sessionId: Id; revision: U64; compositionDigest: Digest;
-  schedulerId: "lockstep-v1";
-  environment: EnvironmentDescriptor; taskSchema: SchemaRef;
-  agents: {
-    agentId: Id; portId: Id; profileDigest: Digest;
-    datasetDigest: Digest; indexDigest: Digest; neuronCount: U64;
-    rateRoles: Id[]; supportedStimuli: Id[];
-  }[];
-  assets: AssetRef[];
-}
-interface CommittedSnapshot {
-  descriptorRevision: U64; publisherIncarnation: Id;
-  scope: Scope; episodeId: Id; sequence: U64; worldTime: RationalNs;
-  agents: {
-    agentId: Id; telemetry: AgentTelemetry;
-    selectedDecision: TypedValue | null;
-    appliedControls: PortControl | null;
-  }[];
-  progress: TypedValue;
-  media: { views: ViewRef[]; audio: AudioRef[] };
-  eventIds: Id[];
-}
-```
-
-Publish only after all agent commits establish Ready(k). Decisions/controls describe the
-transition ending at that boundary, null at initial boundary 0. Health updates are separate
-and never claim an uncommitted future boundary. Every transient media reference is a declared
-bus attachment held through publication admission. Ordinary snapshot publication is latest/
-bounded and never waits for a spectator to consume it.
-
-Publication sequence is monotonic within publisherIncarnation. Epoch determines simulation
-timeline; router topicSequence only determines bus acceptance order. Never equate these.
-Geometry/spike mapping requires indexDigest, not merely the same number of neurons. Persistent
-AssetRefs survive release packaging; ephemeral ArtifactRefs never become permanent asset URLs.
-
-## 4. Flexible data, authored UI
-
-Common UI primitives should understand media, agents, controllers, typed measurements,
-progressions, collections and events. Descriptors change infrequently; values change frequently.
-Application-specific structures remain namespaced, schema-validated extensions, such as
-`pokemon.progress.v1` or `melee.match.v1`. They are not mandatory fields on every snapshot.
-
-Proposed measurement vocabulary to formalize with public v2 schemas:
-
-```text
-Definition: id, owner, label, kind, unit, optional range, schema revision
-Sample: id, producing scope/time, validity, value
-Validity: measured | unknown | unsupported | stale
-```
-
-Kinds include number/counter, gauge, duration, state, progression and collection with typed
-item schemas. A measured zero is distinct from unknown. Stale values retain original timestamps.
-Units/ranges are metadata, not pixel sizes. Unknown optional extensions may be omitted or shown
-generically; unsupported required schemas are visible errors. No remote executable UI payloads.
-
-Application state carries whatever the experience needs: progress history, featured fly,
-competition records, season state or sponsor effects. It is developed with its presentation,
-not forced into a framework-wide “show state”/tournament schema. An application can reuse
-generic components and add its own panels without changing worker/transport contracts.
-
-## 5. Artifact consumption and browser boundary
-
-The native presentation client is a regular bus subscriber. Its renderer may hold an extracted
-Artifact after dropping the message; the SDK delays consumption until actual use finishes.
-Latest coalescing only drops queued values. A stalled consumer is constrained by finite credits,
-owners and store budgets; it cannot make the router overwrite an in-use image.
-
-The browser does not receive private owner tokens or local storage paths. A presentation
-gateway resolves/copies/encodes artifacts into its chosen browser transport and then drops
-its bus handles. That is an application-edge adapter, not a second framework communications
-stack. Compositor/encoder/recorder processes inside the application can exchange their own
-artifacts through the same bus when useful.
-
-Dense spike publication is optional and identifies agent, index digest and covered ticks.
-The runtime need not publish every neuron every millisecond. Required sensory data and
-optional spectator data have distinct budgets; UI focus never changes an agent's input,
-controller assignment or an already resolved stimulation/effect target.
-
-## 6. Events, persistence and recovery visibility
-
-Events identify session/epoch, source boundary, episode, optional agent, kind and typed payload.
-Task events are emitted after committed transitions; capture/admission events describe their
-actual phase. Bus publish acceptance and delivery consumption are not durable acknowledgments.
-
-When durability is required, call a configured event-store client/service (over the same bus)
-and await its append/commit acknowledgment under the session's configured policy. Pub/sub
-remains useful for live observers; reconnecting clients query durable history through ordinary
-RPCs. The initial conformance policy pauses at the next safe boundary if durable event
-admission/commit fails, retaining only a bounded pending batch. No hidden durable broker queue.
-
-After rollback publish old/new epochs, checkpoint identity and abandoned step ranges.
-Application history can mark outcomes aborted/superseded; it does not erase records merely
-because emulator time moved backward. Media reports the corresponding discontinuity.
-
-## 7. Supervisory and audience effects
-
-Application supervision uses bus RPCs for configured lifecycle/intervention capabilities
-and pub/sub for application state/cues. The Twitch adapter can be a constrained bus client
-of the application's admission service; viewers/browser clients never obtain worker control.
-Legacy HTTP bridge behavior remains until deliberately migrated.
-
-Effects are declared by the task/backend/profile: valid targets, parameter schema, timing,
-duration/stacking, implementation capability and outcome events. Examples include neural
-stimulation or future game items/modifiers, where verified implementations exist. Generic
-game boons and a public v2 admission schema are follow-on work; initially new-session audience
-effects remain disabled. No arbitrary controller/game-memory write endpoint is introduced.
-
-```text
-requested → rejected
-          → accepted(target, epoch, earliestStep) → scheduled → applied → expired
-                                                └─ failed / cancelled
-                                                    applied → rolled-back
-```
-
-The application persists interaction identity/target and defines retry, redemption, refund
-and recovery policy. A gift is an intervention, not automatically an earned neural reward.
-Presentation cues may be immediate; simulation effects apply at declared boundaries. The
-supervisor does not bypass the complete-batch step barrier. Chat text remains presentation
-data; template-only replies/quiet mode and existing no-public-button rules continue.
-
-## 8. Presentation acceptance criteria
-
-- Per-agent/session stores and rate/afterglow state, not one mutable global fly.
-- Framework plus application schema streams, with descriptor repair/reconnect behavior.
-- Native view dimensions and aspect; application-controlled output resolution and composition.
-- Explicit audio ownership, timestamped overlays and bounded queues/discontinuities.
-- Last-use artifact release, cached/replay-safe references and slow-observer isolation.
-- Game-specific labels/views without Pokémon fields in generic runtime/router schemas.
-- Actual UI changes reviewed as PNGs with browser/legibility gates. This contract is not screen approval.

docs/design/session-framework/state-media-v1.md

@@ -1,212 +0,0 @@
-# Session artifacts, native media and recovery
-
-Status: **draft 2**, 2026-09-18. [Flybus](bus-v1.md) owns generic artifact storage, delivery
-ownership, retention and garbage collection. This document specifies the **domain meaning**
-of those artifacts: native observations, clock association and coherent session checkpoints.
-Read [session RPC](ipc-v1.md), [step ordering](step-v1.md) and [worker interfaces](workers-v1.md).
-
-## 1. Use the bus ArtifactRef
-
-Large payload fields use `ArtifactRef` from bus-v1, and every referenced artifact is listed
-in the surrounding bus attachments. There is no separate BinaryRef, buffer-region registry,
-coordinator lease endpoint, or Buffer.Release/Reclaim protocol. Profile/dataset release assets
-use `AssetRef` (a persistent content identity); transient bus ArtifactRefs are not those assets.
-
-The environment publishes one immutable native image. The coordinator may forward the same
-owned handle to multiple agent Commit calls and publish it for presentation. Flybus creates
-destination ownership before releasing the source. It does not send another copy of the
-pixel bytes per recipient through its sockets.
-
-An agent consumes/encodes pixels during Initialize/Commit and drops its handle when no longer
-used. A renderer may keep its extracted handle after dropping the message; the DeliveryGuard
-keeps the artifact alive until rendering has finished. A domain cached RPC result keeps its
-own handles so replay remains valid after the original recipient consumes its delivery.
-
-Content digests are optional on transient live frames, mandatory on checkpoint payloads and
-persistent asset import. Ownership/index/byte-shape validation is always required. A digest
-does not replace epoch or observation-time identity.
-
-## 2. Native observation types
-
-```ts
-interface ViewDescriptor {
-  viewId: Id;
-  width: number; height: number;
-  format: "rgba8"; rowStride: number;
-  pixelAspect: { numerator: number; denominator: number };
-  observationDelaySteps: number;
-}
-interface ViewRef { viewId: Id; producedStep: U64; pixels: ArtifactRef }
-interface AudioDescriptor {
-  streamId: Id; sampleRate: number; channels: number;
-  format: "f32le-interleaved";
-}
-interface AudioRef {
-  streamId: Id; firstSample: U64; sampleFrames: number;
-  samples: ArtifactRef; discontinuity: boolean;
-}
-```
-
-Epoch is inherited from the domain observation; the bus treats it as opaque payload. View
-dimensions are integers 1..4096, rowStride exactly 4×width, no padded rows in v1. Pixel aspect
-numerator/denominator are positive integers <=65535; observationDelaySteps is integer 0..8.
-Pixels are top-left RGBA8 and artifact length equals rowStride×height. Other formats require
-a media-schema change, not special-case code inside the router.
-
-Required sensory views have producedStep equal to
-`max(0, observation.boundary - observationDelaySteps)`. Bootstrap may repeat O[0] until the
-declared pipeline delay fills. Beyond that, missing/extra-delay sensory input is a step
-failure, not an arbitrary latest frame. Observer publication may omit/coalesce frames while
-preserving each artifact's actual producing boundary.
-
-Audio sampleRate is integer 8000..192000, channels 1..8, sampleFrames 0..192000 per chunk.
-Samples are finite f32; artifact length is sampleFrames×channels×4. firstSample identifies
-the sample position relative to the episode's configured audio origin, with intended PTS
-firstSample/sampleRate. Crash restore preserves sample position under a new epoch; first
-chunk marks discontinuity. Within an epoch, chunks cannot overlap or go backwards.
-
-The environment provides **native game output**. Sensor transformations belong to the agent
-profile. Resizing for viewers, overlays, composition, audio mixing/resampling, encoding,
-browser delivery and streaming belong to the application/presentation layer. No bus or
-generic session configuration assumes a 1080p show or Twitch output.
-
-640×480 RGBA at 60 fps produces 73.728 MB/s of raw image data. Artifact fan-out references
-one stored object; reads and any staging/seal copy still consume memory bandwidth. This is
-reasonable to measure before introducing codecs or pooled GPU buffers. Native dimensions
-come from the backend, not a hardcoded GameCube or broadcast resolution.
-
-## 3. Domain retention and backpressure
-
-Use the same bus call/publish API for observations and artifacts. Bus ownership tracks bytes;
-the session decides which observations are required and when they have been used.
-
-| Use | Rule |
-| --- | --- |
-| Required agent input | Retain through encoding/Commit; no coalescing or overwrite |
-| Step-result replay | Retain in the endpoint's current/previous-step cache until domain eviction |
-| Spectator snapshot | Latest subscription, finite in-flight credits; release after actual use |
-| Long rendering/storage job | Explicit artifact hold with a finite byte/count budget |
-| Hot checkpoint | Coalesce only queued replaceable captures, releasing their holds |
-| Durable checkpoint | Acknowledge after durable commit; reject/defer before capture when saturated |
-
-Initial session defaults: two outstanding coherent captures and at most the bus-configured
-latest/in-flight frame credits per observer. Presentation audio can target 250 ms and cap at
-one second, but that is a presentation policy, not a bus or brain-clock requirement.
-
-Budget cached step observations, active agent deliveries, retained latest and spectator holds
-together. The producer dropping its handle does not free cached/queued/in-use objects.
-A slow spectator exhausts its own credits; new latest messages replace its queued value.
-If it violates configured resource policy, disconnect/restart that observer instead of freeing
-live data or silently skipping simulation input. Global store exhaustion is an explicit fault
-or pause condition; the router cannot guess that a particular live object is disposable.
-
-No coordinator tracks per-reader socket acknowledgments or calls a producer's reclaim method.
-The SDK and bus perform that bookkeeping. File-backed immutable mappings are safe after
-unlink; physical pages disappear when all OS mappings close. Pooled reuse is deferred until
-it provides equivalent safety. Bare handles in history are not persistent saved bytes.
-
-## 4. Checkpoint identity and content
-
-Exact-checkpoint sessions capture at Ready(k) or Paused(k), after all Agent.Commit replies,
-with no Advance in flight. Block next Prepare until all participants supply immutable captures.
-
-The manifest records:
-
-- Envelope version, checkpoint ID and source session/epoch/step/episode/world time.
-- Coordinator scheduler/configuration identity and exact port-to-agent map.
-- Backend/content/patch/controller/parser/state-format compatibility.
-- Per-agent profile/dataset/model identities, seed, tick count/remainder and payload digests.
-- Task ledger, prior world inspection, per-agent executor state, next sensory/decision state
-  or reproducible reconstruction inputs, admission state and event watermarks.
-- Payload names, lengths and hashes, including external-helper state required for exact resume.
-
-Use a new envelope version; specify exact byte layout before production files. The historical
-letter-only chunk-name constraint is not silently widened, and FLYSIM01 remains separately
-readable. Persist payload **bytes and durable content identity**, not transient bus storeId,
-artifact IDs, ownership tokens, mappings or pointers.
-
-A checkpoint writer owns the bus Artifact handles until bytes are committed or the job fails.
-It then drops them; durable files are outside Flybus's ephemeral GC. On restore, the durable
-store imports fresh immutable bus artifacts. sourceScope is provenance, while the new handles
-belong to the current router/store. Broker retention is never a substitute for a checkpoint.
-
-## 5. State RPCs over the bus
-
-Common to workers advertising checkpoint-v1:
-
-```ts
-interface CaptureParams { checkpointId: Id }
-interface CaptureResult {
-  checkpointId: Id; boundary: U64;
-  compatibilityDigest: Digest;
-  payload: ArtifactRef; // listed attachment; digest required
-}
-interface StageRestoreParams {
-  checkpointId: Id; sourceScope: Scope;
-  compatibilityDigest: Digest;
-  payload: ArtifactRef; // newly imported owned attachment
-}
-interface StageRestoreResult { checkpointId: Id; restoreToken: Id }
-interface ActivateRestoreParams { restoreToken: Id }
-interface ActivateRestoreResult {
-  committedStep: U64; checkpointId: Id;
-  observation: WorldObservation | null; // environment required, agent null
-}
-```
-
-State.Capture uses the committed scope. It completes after immutable capture exists, not when
-a backend save was requested. The cached reply retains its artifact until Worker.Acknowledge.
-The coordinator/writer obtains its own live ownership before acknowledging that cache.
-
-State.StageRestore uses a proposed **new epoch** at source boundary k and is allowed only
-on an uninitialized replacement or a quiescent worker. Launcher configuration supplies the
-expected profile/backend identities; no implicit warm-up/reinitialization changes the saved
-brain. It validates into replacement state, without exposing mutations to the live session.
-
-After every participant and coordinator state validates, State.ActivateRestore installs
-each staged token under that new scope without advancing a tick. Tokens are bound to scope/
-payload/checkpoint and can activate only once; duplicate domain requests replay the cached
-reply, while a fresh request trying to reuse an activated token is a conflict.
-
-The environment returns the coherent restored observation with fresh artifact references and
-restored time. It cannot advance gameplay to manufacture it. Capture/reconstruction therefore
-covers render/inspection state and any pending sensor pipeline. Agent state agrees with it;
-do not replay reward or recalibrate merely to fill missing cached data.
-
-If emulator validation requires mutation, stage a stopped replacement emulator. If that cannot
-provide externally atomic resume, advertise episode-restart, not exact-checkpoint. After all
-activation acknowledgments, install the coordinator's staged task/executor/admission state
-and establish Paused(new epoch,k). Failure during activation never permits half a group to run.
-
-## 6. Durable commit, router failure and recovery
-
-Write payload/envelope temporary generation, fsync, rename, fsync directory, then atomically
-write/fsync/rename the store manifest and fsync its directory. **Manifest commit is the durable
-commit point.** Unreferenced temporary generations are not automatic restore candidates.
-
-Publish distinct captured/queued/committed/failed/superseded events over the same bus. Only
-durable completion produces a saved acknowledgment/high-water mark. Failed writes release
-owned ephemeral captures according to retry policy, without reporting false durability.
-
-After participant/coordinator/router failure:
-
-1. Stop steps, abandon the epoch and fence old participants/routes.
-2. Connect to a live router and select a complete compatible durable checkpoint.
-3. Import its payloads as new artifacts; stage/activate every participant and coordinator.
-4. Verify identity/boundary, flush old media/parser queues and publish recovery/discontinuity.
-5. Establish Paused(k), then resume only after the group invariant holds.
-
-A router restart loses ephemeral topics, queues, roots and correlations. Continuing with
-old handles is invalid even if some mapped bytes survived. Reconnect is not transparent
-mid-step recovery. The durable log records old/new epochs and abandoned step ranges; rollback
-can lose post-checkpoint work. Durable input replay requires a separate application/session
-journal policy, not an exactly-once claim about Flybus.
-
-## 7. Episode reset
-
-Reset differs from crash restore. The application selects a policy; the coordinator records
-the old episode's result/abort and creates a new epoch/episode at step zero. World initial
-state and retained/fresh brain components are explicit. Gain retention, eligibility/hold
-clearing, calibration and first sensory input are part of the policy, tested independently.
-Legacy Pokémon ratchet behavior remains in the legacy composition. Shared competitive worlds
-never restore one player's environment independently of the other players.

docs/design/session-framework/step-v1.md

@@ -1,226 +0,0 @@
-# Lockstep step protocol v1
-
-Status: **draft 2**. This is the authoritative new-session ordering contract. All method
-arrows below are RPCs through the same [Flybus router](bus-v1.md); the router itself never
-implements the barrier. Read [architecture](README.md) and [session RPC](ipc-v1.md) first. Method payloads are in
-[worker interfaces](workers-v1.md).
-
-## 1. Committed boundary
-
-At `Ready(epoch, k)`:
-
-- Environment state is at boundary `k`, with no outstanding action batch.
-- Every agent has consumed the outcome of transition `k-1 → k`, including its new encoded
-  sensory input and rewards, and is ready to compute the decision for transition `k → k+1`.
-- Task ledger, action-executor state, event identity and agent tick remainders agree with `k`.
-- The current sensory observation may have a declared fixed render delay; its producing
-  boundary is explicit. “Ready” does not imply latest wall-clock screenshot.
-- No normal step operation from an older boundary may mutate the session.
-
-Only a committed boundary is eligible for a coherent checkpoint or normal pause. Boot/reset
-establishes the same invariant with no preceding reward. The public snapshot represents this
-boundary, not an in-progress combination of some new agent states and an old world.
-
-## 2. State machine
-
-```text
-Starting → Ready(k) → Preparing(k) → Applying(k) → Observing(k+1)
-              ↑                                      │
-              └──────────── Ready(k+1) ← Committing(k) ┘
-
-Ready(k) → Paused(k) → Ready(k)
-Ready(k) / Paused(k) → Capturing(k) → same boundary
-any unresolved partial failure → Failed → Restoring(new epoch) → Paused(k)
-terminal episode → Paused(k) → Resetting(new epoch) → Ready(0)
-```
-
-`Committing(k)` refers to completing transition `k → k+1`. Requests throughout that
-transition carry `scope.step=k`; result fields identify `nextStep=k+1` where applicable.
-Do not send Agent.Commit with step `k+1` merely because the observation is newer.
-
-## 3. Transaction sequence
-
-### Phase A: prepare all agents concurrently
-
-At Ready(k), freeze the task's per-agent decision contexts and the coordinator's admitted
-pre-step stimulation list. Inputs accepted after this cut wait for the next boundary.
-
-Send `Agent.Prepare(scope=k)` to every active agent. Each worker:
-
-1. Verifies its committed boundary/profile/context and applies admitted pre-step stimulation
-   in deterministic command sequence order. Chat text is never included.
-2. Advances the numerical model for the environment interval, using the input encoded at
-   the preceding Commit (or initialization).
-3. Reads rates and performs the fixed readout with the declared decision context.
-4. Stores and returns `PreparedDecision`; it then enters Prepared(k) and waits for Commit.
-
-This operation **mutates** the brain, RNG, clock and decoder. “Prepare” does not mean a
-database transaction that can be rolled back cheaply. If another agent fails, do not ask a
-prepared agent to prepare again or advance to the next step. Resolve/recover the whole session.
-
-All agents see the same environment interval and the same world boundary, with only their
-permitted view/context differences. Their completion order never affects port/action order.
-
-### Phase B: build and apply one complete batch
-
-After every PreparedDecision arrives:
-
-1. Validate agent IDs, intent schemas and profile identities.
-2. Run each task-local action executor once, in sorted agent-ID order, against coherent current
-   game state, task progress/objectives and clock from this boundary.
-   Direct-control profiles use an identity executor. Macro profiles are explicit extensions.
-3. Assemble all configured port controls in descriptor port order; reject duplicates/missing
-   ports. Uncontrolled ports are configured neutral before the epoch, not supplied ad hoc.
-4. Send exactly one `Environment.Advance(scope=k, batchId, controls)`.
-
-The environment applies all controls at its agreed boundary, advances exactly one interval,
-and returns StepResult for `k+1`. It MUST NOT advance another interval while waiting for
-the next request. Transport/control scaffolding may have a measured fixed latency; it must
-be declared in its descriptor and conformance tests.
-
-### Phase C: observe and evaluate the task
-
-The coordinator receives the environment result and verifies batch identity, boundary,
-cadence, inspection schema and required sensory views. A missing spectator frame is tolerable;
-a missing required sensory input is not silently replaced.
-
-Call the task's `evaluate_transition` once with old/new inspection observations and applied
-controls. It returns scoped rewards/stimulation, next decision contexts, progress/events and
-an optional episode request. Commit its ledger update in memory and retain the result for
-this transition. No task output directly writes controllers or neural state.
-
-### Phase D: commit all agent outcomes concurrently
-
-Send `Agent.Commit(scope=k)` with that agent's next sensory observation and routed outcomes.
-Each agent, in this order:
-
-1. Encodes/installs the next sensory input for the following Prepare.
-2. Applies task-derived stimulation in returned event order.
-3. Sums that agent's reward values in returned event order and calls reinforcement once at
-   its current brain time when learning is enabled. A zero sum still follows the profile's
-   specified legacy-equivalent reinforce behavior; do not optimize it away without evidence.
-4. Retains the next decision context/digest and acknowledges committed boundary `k+1`.
-
-There are no additional neural ticks in Commit. Sugar accepted for a future Prepare is not
-silently merged with task reward modulation. The default synthetic learning mechanism remains
-separate from the neural stimulation path.
-
-Once **all** commits succeed, the coordinator advances its committed boundary to `k+1`,
-finalizes the observation snapshot and scoped events, drops no-longer-needed artifact handles and
-allows the next Prepare. If one Commit fails after others succeeded, the epoch is failed;
-there is no partial-match continuation.
-
-These phases establish logical coordination, not a distributed durable two-phase commit.
-Crash recovery returns to the last complete checkpoint, not necessarily the last displayed step.
-
-## 4. Sequence example
-
-```text
-Coordinator         Agent A          Agent B          Environment
-    | Prepare(k) ------>|                |                  |
-    | Prepare(k) ----------------------->|                  |
-    |<-- Prepared(A) ---|                |                  |
-    |<-- Prepared(B) --------------------|                  |
-    | [executor + complete port batch]                      |
-    | Advance(k, batch-x) --------------------------------->|
-    |<-------------------- StepResult(k+1, batch-x) ----------|
-    | [task evaluation; route each reward once]              |
-    | Commit(k, O[k+1], R_A) ->|           |                 |
-    | Commit(k, O[k+1], R_B) ------------>|                 |
-    |<-- Committed(k+1) -----|            |                 |
-    |<-- Committed(k+1) -----------------|                 |
-    | [Ready(k+1); publish; next boundary]                   |
-```
-
-The shared camera is one immutable artifact forwarded through bus-owned deliveries; both
-workers can encode it without two renders or routing two full images through sockets.
-Domain RPC replay caches retain handles, so consumption by one client cannot invalidate a
-promised replay. Publication uses bus pub/sub and never waits for spectator consumption.
-The coordinator retains each domain request's input handles until its terminal outcome is
-resolved, beyond the shorter bus-admission lifetime, so safe domain retries still have valid
-attachments. If ownership is lost, fail/recover instead of sending bare expired references.
-The coordinator cannot publish a committed state as soon as the faster agent answers.
-
-## 5. Time and pacing
-
-The environment descriptor supplies a fixed reduced `stepDuration: RationalNs`. Each agent
-profile supplies `tickDuration: RationalNs`. The existing LIF adapter uses exactly one ms.
-
-For each Prepare:
-
-```text
-accumulator += environment step duration
-ticks = floor(accumulator / model tick duration)
-accumulator -= ticks * model tick duration
-```
-
-Use checked rational/integer arithmetic; remainder is always >=0 and < one model tick.
-Do not accumulate rounded microseconds or nanoseconds for a fractional frame period.
-Persist remainder, executed tick count and warm-up offset. Language implementations must
-agree on remainder fixtures. Conversion to the legacy model's f64 millisecond clock must
-preserve its representable integral ticks; refuse a run exceeding the supported exact range.
-
-Example: a synthetic 60-Hz environment with a 1-ms model tick produces 16,17,17 ticks
-over three steps, totaling 50. A real backend's measured/declared emulated cadence may
-differ; never substitute this example's duration for Game Boy or Dolphin clocks.
-
-Wall time is only for pacing, health and presentation. The coordinator schedules absolute
-deadlines after committed boundaries; when behind, it omits sleep and reports lag. It does
-not skip world steps, drop neural ticks, or let one agent advance more slowly than another.
-Only one pacing authority is active. Backend throttling and coordinator pacing must be
-configured/tested so they do not unintentionally double-throttle the session.
-
-First-version profiles have a fixed cadence within an epoch. Supporting variable-duration
-world advances requires a new capability and tests before enabling it.
-
-## 6. Initialization, pause and episodes
-
-Initialize the environment first while stopped, obtaining observation O[0]. Bootstrap the
-task and initial decision contexts, then initialize agent workers with their permitted inputs.
-Agent warm-up has learning disabled; calibration occurs on settled rates; no warm-up actions
-advance the environment. All required acknowledgments establish Ready(0).
-
-A normal pause request arriving mid-step means “finish this transition, then pause.” It does
-not truncate neural computation or capture half an action batch. If completing the transition
-is impossible, use failure/recovery, not an apparently successful Pause acknowledgment.
-Paused workers retain state and answer Status; world controls do not advance the world.
-
-Task terminal events are evaluated and their final rewards committed once. Before another
-gameplay transition, enter Paused and apply the declared episode policy. Reset uses a new
-epoch/episode and step 0. A profile may retain learned gains/brain state, but must identify
-exactly what is retained, cleared, warmed or recalibrated. No worker independently resets.
-
-Changing port assignment, agent membership, model/profile, cadence or task schema requires
-a new composition/epoch. Hot-join and hot-swap during an active match are not v1 capabilities.
-
-## 7. Failure rules
-
-| Failure point | Required response |
-| --- | --- |
-| Before any Prepare admitted | Reject request/config or remain Ready; nothing advanced |
-| Some agents Prepared | Stop dispatch; resolve matching requests or fail epoch/group restore |
-| Advance acknowledgment lost | Query/retransmit same request to same incarnation; never new batch |
-| World advanced, sensory data unavailable | Fail transition; do not reward/continue using guessed input |
-| Task interpretation fails | Fail epoch; prepared brains/world already changed |
-| Some Commit replies missing | Resolve exact requests; no next world step until all committed |
-| Worker incarnation changes | All live participants belong to an invalid epoch; restore/reset together |
-| Publisher/browser disconnected | Simulation continues; bound/drop spectator work |
-| Durable storage fails | Report actual failure; apply configured pause/continue-with-stale-checkpoint policy |
-
-Retries return original results; they never recompute a decision with updated rates or new
-world data. A coordinator restart has no authority to assume any remote participant's phase;
-recover from a coherent checkpoint into a new epoch or start an explicitly new episode.
-
-## 8. Required trace assertions
-
-The synthetic integration test must record, for every transition:
-
-- Scope, Prepare request IDs, agent/profile IDs, tick counts/remainders and decision digests.
-- Complete batch ID/control digest and acknowledged world boundary.
-- Observation producing boundaries and task event/outcome IDs in order.
-- All Commit acknowledgments and published committed boundary.
-
-Evaluate agents sequentially, concurrently, and in reversed dispatch/completion order. All
-committed state/action/reward results must match, excluding wall time, request IDs and other
-explicitly operational metadata. Delayed/lost/duplicate messages must not add a neural tick,
-world step, reward update or controller flush corresponding to another logical step.

docs/design/session-framework/workers-v1.md

@@ -1,367 +0,0 @@
-# Worker and task interfaces v1
-
-Status: **draft 2**. Uses [Flybus](bus-v1.md) for every call/publication and the domain
-types/outcomes in [session RPC](ipc-v1.md), ordering in
-[step protocol](step-v1.md), and binary/state types in [state and media](state-media-v1.md).
-All method results below are the `result` object inside the domain result carried by a bus
-rpc.result. Large inputs/outputs use owned bus attachments, never another worker data channel.
-
-## Method registry
-
-| Method | Caller → receiver | State/owner |
-| --- | --- | --- |
-| `Worker.Hello` | Authorized caller → named worker service | Domain identity/capabilities after bus negotiation |
-| `Worker.Status` | Authorized caller → named worker service | Read-only; responsive during compute |
-| `Worker.Acknowledge` | Coordinator → worker | Bounded lifecycle-result retention |
-| `Worker.Shutdown` | Coordinator → worker | Terminal lifecycle request |
-| `Agent.Initialize` | Coordinator → agent | Uninitialized → Ready(0) |
-| `Agent.Prepare` | Coordinator → agent | Ready(k) → Prepared(k) |
-| `Agent.Commit` | Coordinator → agent | Prepared(k) → Ready(k+1) |
-| `Environment.Initialize` | Coordinator → environment | Uninitialized → boundary 0 |
-| `Environment.Advance` | Coordinator → environment | Boundary k → boundary k+1 |
-| `State.Capture` | Coordinator → agent/environment | Immutable snapshot of committed boundary |
-| `State.StageRestore` | Coordinator → agent/environment | Validate replacement state under new epoch |
-| `State.ActivateRestore` | Coordinator → agent/environment | Install staged state; remain quiescent |
-
-State methods have payloads in [state and media](state-media-v1.md). Artifact lifetime and
-message consumption are bus operations managed by the SDK, not Worker/Coordinator methods.
-Worker.Acknowledge releases a domain result cache, distinct from consuming a bus delivery.
-Task/executor interfaces below are local library methods, not extra communication protocols.
-
-## 1. Shared data model
-
-```ts
-interface AssetRef {
-  id: Id; digest: Digest; byteLength: U64; format: Id;
-}
-interface SensoryInput {
-  boundary: U64;           // environment boundary being observed
-  views: ViewRef[];        // only the views this agent is allowed to consume
-  structured: TypedValue | null;
-}
-interface Stimulus {
-  id: Id; kindId: Id; durationMs: number;
-}
-interface Reward {
-  eventId: Id; ruleId: Id; value: number;
-}
-interface AgentTelemetry {
-  brainTicks: U64;
-  populationRateHz: number;
-  rates: { roleId: Id; hz: number }[];
-  learning: { enabled: boolean; updates: U64; changed: U64; signal: number };
-}
-```
-
-`AssetRef` names persistent content in a preprovisioned local registry; it is not an arbitrary path or
-URL for a worker to fetch. A profile artifact contains all effective numerical, sensory,
-readout, learning and schema identities. Dataset artifacts must already be installed and
-verified. No implicit runtime network download or latest-version selection is allowed.
-
-Transient `ArtifactRef` is instead defined by Flybus and resolves only through owned handles.
-Views and structured input are separate capabilities. A pixel-only profile rejects non-null
-structured input. Max views per sensory input: 8; any individual TypedValue is at most 32 KiB
-of canonical JSON, and the complete bus envelope must fit 64 KiB. Larger typed state uses
-an explicit artifact-backed schema. Frame bytes never go into JSON.
-
-`Stimulus.kindId` resolves through a profile-declared capability to an anatomical binding
-and fixed drive, including supported duration bounds. A caller cannot specify arbitrary
-neuron indices or change drive values. `durationMs` must be finite and >0. Arrays of stimuli
-or rewards are bounded to 64 per operation and retain their supplied order.
-
-Rates must be finite/nonnegative, unique by role ID and in profile-defined order, at most
-64 entries. Learning values must be finite; integer counters fit U64. Reward values are
-finite; shipped positive-only task profiles reject negatives. Empty rewards do not imply a
-different numerical rule. `id`/`eventId` is unique within its outcome or command namespace;
-the coordinator assigns stable IDs before sending a mutating request.
-
-## 2. Agent methods
-
-### Agent.Initialize
-
-Allowed only on an uninitialized agent with negotiated `agent-step-v1`. Scope is the new
-epoch at step `0`; restore uses the state interface instead of Initialize.
-
-```ts
-interface AgentInitializeParams {
-  agentId: Id;
-  profile: AssetRef;
-  seed: number;             // signed 32-bit integer, matching current RNG input
-  initialInput: SensoryInput;
-  initialDecisionContext: TypedValue;
-  workerThreads: number;    // integer >=1; within launcher allocation
-}
-interface AgentInitializeResult {
-  agentId: Id; profileDigest: Digest; tickDuration: RationalNs;
-  warmupTicks: U64; committedStep: U64; // committedStep == "0"
-  decisionContextDigest: Digest;
-  telemetry: AgentTelemetry;
-}
-```
-
-The profile fixes warm-up/calibration behavior and supported schema versions. Validate inputs
-and required roles before model construction. Install the initial sensory input, warm the
-brain with learning disabled, calibrate the fixed readout and establish Ready(0). Do not
-generate gameplay rewards or controls that advance the world during warm-up.
-
-Seed is persisted as run configuration and state; the coordinator derives independent seeds
-from its recorded master seed and stable agent IDs under a versioned derivation algorithm.
-That algorithm is part of composition identity and MUST be specified/tested before the real
-agent slice; hand-selected explicit seeds are supported for the first synthetic composition.
-Identical explicit seeds are allowed only when the experiment intentionally declares them.
-The profile artifact digest identifies the profile definition; the capture compatibility
-digest additionally covers the resolved seed, numerical model version and effective instance
-configuration. Never assume identical profile digests make differently initialized state
-interchangeable without matching that instance configuration.
-
-### Agent.Prepare
-
-Allowed from Ready(k), or as an exact domain retry under the session RPC deduplication rules.
-
-```ts
-interface PrepareParams {
-  agentId: Id; profileDigest: Digest;
-  interval: RationalNs;
-  decisionContextDigest: Digest;
-  preStepStimulations: Stimulus[];
-}
-interface PreparedDecision {
-  agentId: Id;
-  ticksAdvanced: U64; brainTicks: U64; remainder: RationalNs;
-  decision: TypedValue;
-}
-```
-
-Verify the cached context digest from Initialize/last Commit, expected agent/profile and
-interval. Apply pre-step stimuli, advance ticks and decode as specified by the step protocol.
-The returned decision schema is the profile's registered intent schema. It may describe a
-controller state or selected semantic action, but cannot assign a port or include hidden
-task-inspection fields. Context may mask declared available actions; it cannot change the
-readout weights, invent a default winner or inject arbitrary neural observations.
-
-Successful response leaves the worker at Prepared(k). A duplicate returns the same decision,
-ticks and remainder. It MUST NOT resample randomness, repeat stimulation or calibrate again.
-
-### Agent.Commit
-
-Allowed only at Prepared(k), matching the current transition and exact Prepare request.
-
-```ts
-interface CommitParams {
-  agentId: Id;
-  preparedRequestId: Id;
-  nextInput: SensoryInput;             // boundary == k+1
-  nextDecisionContext: TypedValue;
-  rewards: Reward[];
-  taskStimulations: Stimulus[];
-}
-interface AgentCommitResult {
-  agentId: Id; committedStep: U64;     // k+1
-  decisionContextDigest: Digest;
-  telemetry: AgentTelemetry;
-}
-```
-
-Validate the complete request and required owned artifacts before applying it. Follow exact input→
-stimulation→reinforcement ordering in the step protocol. A missing required view is an error,
-not zero input. An outcome requesting unsupported learning/stimulation is an error, not a
-silent no-op. Disabled learning is a declared profile/run state, not “unsupported.”
-
-No tick is executed in Commit. Cache its response before accepting the following Prepare.
-The next context is retained for that Prepare; its canonical digest is returned and checked.
-After encoding/copying and all asynchronous use finish, the worker drops its input Artifact
-handles. The SDK consumes the delivery when the last associated guard disappears. A stored
-input pointer must retain its handle. Cached replies retain their own artifact ownership.
-
-### Agent interface implementation boundary
-
-An agent worker bundles numerical model, sensor encoder and readout. It need not copy the
-legacy `NeuralAgent::tick` call order: the existing service already orchestrates substeps.
-Use a small adapter over the reference primitives and preserve the new specified ordering.
-New numerical semantics require reference-first implementation and new model identities;
-this protocol is not permission to change the pinned default kernel.
-
-## 3. Environment methods
-
-### Controller and descriptor types
-
-```ts
-interface ControllerSchema {
-  schema: SchemaRef;
-  buttons: Id[]; // <=32, unique, fixed order
-  axes: { id: Id; range: "bipolar" | "unit"; neutral: number }[]; // <=16
-}
-interface PortControl {
-  portId: Id;
-  buttons: { id: Id; down: boolean }[];
-  axes: { id: Id; value: number }[];
-}
-interface EnvironmentDescriptor {
-  backendDigest: Digest; contentDigest: Digest; configurationDigest: Digest;
-  stepDuration: RationalNs;
-  ports: { portId: Id; controls: ControllerSchema }[];
-  inspectionSchema: SchemaRef;
-  views: ViewDescriptor[];
-  audio: AudioDescriptor[];
-  recovery: "exact-checkpoint" | "episode-restart";
-  determinism: "fixed-build" | "unverified";
-}
-```
-
-Every active port control must include every declared button and axis in descriptor order.
-All IDs must match exactly; no duplicates, extra controls or omissions. Bipolar axes are
-finite [-1,1]; unit axes [0,1]. Neutral lies in range. Do not silently clamp an out-of-range
-caller value. Hardware-specific quantization/dead zones are backend configuration, applied
-exactly once and tested against observed controls.
-
-`fixed-build` asserts tested repeatability under the pinned configuration, not universal
-bit-exact behavior across CPU architectures, GPU drivers or emulator versions. Those limits
-must be in the backend implementation guide and run manifest. `unverified` cannot satisfy
-an exact-replay production composition without an explicit scope change.
-
-### Environment.Initialize
-
-```ts
-interface EnvironmentInitializeParams {
-  backendConfig: AssetRef;
-  taskConfig: AssetRef;
-  episodeId: Id;
-  portBindings: { portId: Id; agentId: Id }[];
-}
-interface EnvironmentInitializeResult {
-  descriptor: EnvironmentDescriptor;
-  observation: WorldObservation; // boundary 0, worldTime zero
-}
-interface WorldObservation {
-  boundary: U64;
-  worldTime: RationalNs;         // logical time since episode start; preserved on crash restore
-  engineFrame: string | null;    // backend-defined signed counter; <=64 characters
-  sensoryViews: ViewRef[];
-  inspection: TypedValue;
-  broadcastViews: ViewRef[];
-  audio: AudioRef[];
-}
-```
-
-Scope is new epoch step 0. Backend/task config artifacts identify exact game content,
-patches, initial-state/setup policy, graphics/timing/parser and controller conversion.
-No unresolved “latest” settings. Environment setup may be application-specific, but it is
-declared lifecycle scaffold, not actions attributed to a fly. The environment is stopped
-when it returns O[0] and cannot free-run during brain initialization.
-
-The environment only needs backend-relevant portions of task setup, not reward rules or
-neural policies. `taskConfig` resolves a declared setup configuration; the complete task
-implementation and ledger stay in the coordinator.
-
-### Environment.Advance
-
-```ts
-interface AdvanceParams {
-  batchId: Id;
-  controls: PortControl[];
-}
-interface StepResult {
-  batchId: Id;
-  appliedFromStep: U64; nextStep: U64;
-  appliedControlsDigest: Digest;
-  observation: WorldObservation;
-}
-```
-
-Validate scope k, complete controls and identities before releasing a backend input barrier.
-Batch IDs are unique within an epoch; reusing one for a different request/step is a conflict.
-Apply the complete batch to its interval and advance one framework step. Record batch ID,
-result and next boundary before acknowledging. StepResult's control digest is over validated
-canonical requested controls; backend quantization does not silently change that definition.
-Observed game-pad values, if provided, are separately schema-labeled inspection data.
-
-The environment returns exactly boundary k+1, worldTime advanced by its stepDuration, and
-the required sensory views or a typed failure. An adapter with measured input latency must
-describe it in its versioned backend config and prove its frame mapping; it cannot claim an
-unmeasured same-frame response. An emulator may execute internal cycles/polls, but cannot
-hide multiple framework steps behind one result.
-
-### Environment pause behavior
-
-At a committed world boundary the backend already awaits the next Advance; normal session
-pause does not need a separate per-frame RPC. When an emulator requires an explicit hardware/
-CPU pause to hold that invariant, the adapter owns it and must prove it. Status/Shutdown
-remain responsive. A render/audio worker may drain already-produced data while stopped,
-but no new gameplay state may advance.
-
-## 4. Coordinator-local task and executor interfaces
-
-These are library interfaces in v1, not additional bus services. Equivalent typed interfaces
-may be implemented in Rust; names below specify semantics rather than compilable code.
-
-```text
-Task.bootstrap(initialInspection, bindings)
-  → perAgentDecisionContexts, progress, initialEvents
-
-Task.evaluate_transition(scope, oldInspection, newInspection, appliedControls)
-  → perAgentOutcomes, perAgentNextDecisionContexts, progress, events, episodeRequest
-
-ActionExecutor.apply(scope, agentDecision, currentGameState, progressView, clock)
-  → ControllerIntent, executionEvents
-
-Task.capture / validate_restore / install_restore
-ActionExecutor.capture / validate_restore / install_restore
-```
-
-Task owns a checkpointable ledger. The coordinator calls each transition evaluation exactly
-once after its acknowledged world step and retains the output until all agent commits finish.
-If task mutation is followed by failure, restore the group; never reevaluate against a later
-observation. Task-produced outcomes are keyed by configured agent ID; unknown/missing agents
-are errors. Every agent receives explicit outcome arrays, including empty ones.
-
-`ControllerIntent` contains buttons/axes conforming to the assigned port's controller schema,
-but not a port assignment. The coordinator supplies the port. Per-agent executor state is
-private; a running macro may emit controls according to its declared policy, but only after
-neural selection. The first implementation supports the stateless identity executor only.
-
-The executor's currentGameState is a coherent read-only inspector view at this boundary;
-progressView supplies task history/objectives. It updates its selected action every step
-(movement, path replanning, interaction, completion), not merely replaying a blind button
-sequence. These game-aware inputs stay in the task/executor layer. For an external backend,
-they arrive as typed observation/artifact data over the same bus, not per-byte remote reads.
-
-Task contexts sent to the neural readout are typed, bounded, versioned and allowlisted by its profile.
-They may express boot state or available actions. They are distinct from neural sensory
-input and broadcast telemetry. A profile using game-state features as neural input must
-explicitly declare structured sensing; the task cannot smuggle it into an opaque context.
-
-Task events carry `{id, kindId, sourceStep, agentId:null|Id, payload:TypedValue}`. Event order
-is task-defined and deterministic; `sourceStep` is the newly reached boundary k+1 for a
-transition event (0 for bootstrap events). Event IDs are derived deterministically from
-epoch, source step, task/rule and event ordinal, encoded as an Id. Rewards and stimulation
-referencing these events must
-have a configured recipient. Broadcast text is generated by task/presentation templates,
-not arbitrary raw inspector memory or incoming chat.
-
-`episodeRequest` is either null or `{kind:"terminal", reason:Id, outcome:TypedValue}`.
-It requests a coordinator-owned policy transition after final reward commit; it cannot reset
-the environment directly. Generic progress is a TypedValue, not mandatory Pokémon ladder data.
-
-## 5. Admission and audience boundary
-
-The first synthetic implementation has no audience input. Later integration maps permitted
-public requests into a coordinator admission record containing stable interaction ID, agent
-ID, accepted epoch/earliest step and profile-supported stimulus. Only the coordinator can
-place that stimulus in Prepare. Viewer names/chat never enter the neural worker contract.
-
-Rate limits and target resolution occur before the step's command cut. A later-selected
-UI focus or new match cannot retarget an already accepted interaction. Bus/domain RPC deduplication
-does not itself define payment/redemption semantics across epoch recovery; a future public
-v2 contract must specify accepted/applied/rolled-back/aborted states and reconciliation before
-paid interactions are enabled. Do not inherit a claim of durable exactly-once stimulation
-from these in-memory worker request caches.
-
-## 6. Health, shutdown and extensions
-
-All workers implement the common Hello/Status/Shutdown/Acknowledge methods. Capture/restore
-methods are in the state contract and mandatory only when exact-checkpoint capability is
-advertised. Unsupported methods return `UNSUPPORTED`, mutation none.
-
-New task-specific fields belong in registered TypedValue schemas. New worker capabilities,
-variable-duration stepping, subscriptions or additional sensor modalities require a contract
-change and shared fixtures. An unconstrained plugin dictionary is not a substitute for that.

services/flysim/Cargo.lock

@@ -441,18 +441,6 @@ dependencies = [
  "sha2",
 ]
 
-[[package]]
-name = "flybus"
-version = "0.1.1"
-dependencies = [
- "libc",
- "serde",
- "serde_json",
- "sha2",
- "tempfile",
- "tokio",
-]
-
 [[package]]
 name = "flysim"
 version = "0.1.1"

services/flysim/Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "3"
-members = ["crates/flybrain-core", "crates/flybrain-gb", "crates/flybus", "crates/flysim"]
+members = ["crates/flybrain-core", "crates/flybrain-gb", "crates/flysim"]
 
 [workspace.package]
 version = "0.1.1"

services/flysim/crates/flybus/Cargo.toml

@@ -1,21 +0,0 @@
-[package]
-name = "flybus"
-version.workspace = true
-edition = "2024"
-rust-version.workspace = true
-license.workspace = true
-publish = false
-description = "A small local RPC and pub/sub bus with immutable file-backed artifacts."
-
-[dependencies]
-# `flock`, `posix_fallocate` and `O_NOFOLLOW`; everything else is std or Tokio.
-libc = "0.2"
-serde = { workspace = true }
-serde_json = { workspace = true }
-sha2 = { workspace = true }
-tokio = { version = "1", features = ["rt", "net", "io-util", "sync", "time", "macros"] }
-
-[dev-dependencies]
-sha2 = { workspace = true }
-tempfile = "3"
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "time"] }

services/flysim/crates/flybus/README.md

@@ -1,370 +0,0 @@
-# flybus
-
-A small local RPC and pub/sub bus with immutable file-backed artifacts, for Tokio.
-
-One library, one router, one wire protocol. Messages are small JSON envelopes carrying
-metadata and artifact references. Large immutable bytes live in a file store the router
-manages. Ownership follows deliveries and explicit holds. The router moves messages and tracks
-ownership; it does not know what the messages mean.
-
-This crate implements the Flybus v1 draft (session-framework design, `bus-v1`, draft 1 of
-2026-09-18), using the scalar encodings of its companion `ipc-v1` (`Id`, `U64`, `Digest`).
-Where this crate narrows or extends the draft, the difference is listed under
-[Differences from the draft](#differences-from-the-draft).
-
-Nothing in the crate is specific to a game, a brain or a stream. It is a workspace member and
-no other crate depends on it yet.
-
-## Layout
-
-| Module | Contents |
-| --- | --- |
-| `wire` (public) | Scalars, strict JSON, `Envelope`, `ArtifactRef`, `Attachment`, `Location`, framing, `CONTRACT` and `contract_digest()` |
-| `error` (public) | `ErrorCode`, `Dispatch`, `BusError` |
-| `limits` (public) | `Limits` and its hello encoding |
-| `policy` (public) | `Policy`, `Grants`, `Pattern` |
-| `router` | `Router`, `RouterConfig`, `RouterStats`, `UnixListenerHandle`; the state machine in `router/state.rs` |
-| `client` | `Client` and every handle type |
-| `store` | The file store (router side) and location resolution (client side) |
-| `transport` | `Transport`, the `Stream` trait |
-
-Dependencies: `tokio`, `serde`, `serde_json`, `sha2` and `libc` (for `flock`,
-`posix_fallocate` and `O_NOFOLLOW`), all already in the workspace lockfile.
-
-## API
-
-### Router
-
-```rust
-let mut config = RouterConfig::new("/run/example/bus-store"); // default Limits, closed Policy
-config.policy = Policy::closed()
-    .client("coordinator", Grants { call: vec![Pattern::prefix("agent.")], ..Grants::default() })
-    .client("agent-a", Grants { register: vec![Pattern::exact("agent.fly-a")], ..Grants::default() });
-let router = Router::new(config)?;                 // creates <root>/<storeId>, cleans orphans
-let listener = router.listen_unix_as("/run/example/coordinator.sock", "coordinator").await?;
-let transport = router.connect_in_memory_as("coordinator");
-router.serve_as(any_async_read_write_stream, "coordinator");
-router.stats();                                    // RouterStats (logical registry counters)
-router.shutdown();                                 // notices, then closes every connection
-```
-
-- `Router` is `Clone`; all clones are one router. `serve_as`, `connect_in_memory_as` and
-  `listen_unix_as` bind the launcher's expected participant id to the transport before Hello.
-  A mismatching Hello is refused before registration or routing.
-- The unbound `serve`, `connect_in_memory` and `listen_unix` entry points are only for explicit
-  `Policy::open()` trusted/test deployments. Restricted policies refuse unbound transports.
-  Identity in open/unbound mode is self-asserted and is not authentication.
-- `RouterConfig::hello_timeout` defaults to 5 seconds. `max_clients` counts all accepted
-  connections, pending and active.
-- `router_id()`, `store_id()`, `store_root()` and `store_dir()` report the incarnation and
-  paths.
-- `RouterStats` has `connections`, `services`, `topics`, `subscriptions`, `calls` (correlation
-  records, detached included), `active_calls`, `artifacts`, `sealed_artifacts`,
-  `artifact_roots`, `owners`, `reply_capabilities`, `queued`, `store_bytes` and
-  `retained_bytes`.
-- `Limits` (defaults in brackets): `max_clients` [64], `max_services` [256], `max_topics`
-  [512], `max_subscriptions_per_client` [128], `max_subscriptions` [1024],
-  `max_active_calls_per_client` [64], `max_service_queued` / `max_service_in_flight` [16 / 16],
-  `max_latest_in_flight` [2], `max_bounded_queued` / `max_bounded_in_flight` [64 / 16],
-  `max_owners_per_client` [256], `reserved_owners_per_client` [64], `max_store_bytes`
-  [512 MiB], `max_artifact_bytes` [128 MiB], `max_retained_bytes` [128 MiB],
-  `max_queued_bytes_per_client` [1 MiB], `max_control_frames` / `max_control_bytes`
-  [128 / 1 MiB]. `Router::new` refuses a configuration `Limits::validate` rejects.
-- `Policy::open()` explicitly enables trusted unbound transports and admits any client id with
-  every grant. `Policy::closed()` admits only the
-  ids added with `.client(id, grants)`. `.with_default(Some(grants))` admits unlisted ids too.
-  `Grants` lists `register`, `call`, `publish`, `subscribe` and `manage_topics` (declare, clear,
-  delete) as `Pattern::Any`, `Pattern::exact(name)` or `Pattern::prefix(prefix)`. An empty list
-  grants nothing.
-
-### Client
-
-```rust
-let bus = Client::connect(transport, ClientConfig::new("coordinator", store_root)).await?;
-let bus = Client::connect_unix(socket_path, ClientConfig::new("coordinator", store_root)).await?;
-bus.info();          // SessionInfo: router_id, connection_id, identity, selected_major,
-                     // selected_minor, contract_digest, limits
-bus.closed();        // Some(reason) once the connection has closed
-bus.control_errors();// fire-and-forget releases/consumes/unregisters the router refused
-bus.close().await;   // flush queued releases, close, wait for the reader to stop
-```
-
-`ClientConfig` has `client_id`, `client_incarnation` (generated when `None`; a reconnect needs a
-new one), `store_root` (the router's) and `control_lane_capacity` [4096]. `Client` is `Clone`.
-The connection closes when the client and every handle made from it are dropped, or on
-`close()`. After that, handles are inert and the router has released what they owned.
-
-#### RPC
-
-```rust
-let mut svc = bus.register("agent.fly-a", ServiceConfig { max_queued: 16, max_in_flight: 16 }).await?;
-while let Some(req) = svc.next().await {           // Request
-    req.method(); req.payload(); req.caller();     // authenticated only on a launcher-bound transport
-    let frame = req.artifact("frame")?;            // shares the request's delivery guard
-    req.reply(outcome_map, &[("result", &artifact)]).await?; // Ok(true) routed, Ok(false) detached
-}                                                  // dropping a Request consumes its delivery
-
-let mut pending = bus.call("agent.fly-a", Some(&incarnation), "Agent.Prepare", payload, &[("frame", &frame)]).await?;
-let result = pending.result().await?;              // RpcResult: outcome(), responder(), artifact()
-let state = pending.cancel().await?;               // CancelState
-let result = bus.call_and_wait(service, pin, method, payload, &attachments).await?;
-```
-
-- `register` is exclusive; `Service::incarnation()` is the id callers pin. Dropping the
-  `Service` unregisters it.
-- `call` returns once the router has admitted the call. The `PendingCall` then yields exactly
-  one terminal outcome. `result()` is cancel-safe: wrap it in `tokio::time::timeout`, then call
-  it again or `cancel()`. There is no deadline parameter; the deadline belongs to the caller.
-- `cancel()` returns `CancelledBeforeDispatch`, `ExecutionUnknown`, `Completed` or `CallGone`.
-  After any state except `Completed`, `result()` fails with `CALL_GONE`. The error's dispatch is
-  `not-dispatched` only for `CancelledBeforeDispatch`.
-- Dropping an unfinished `PendingCall` sends a best-effort `rpc.cancel`. The reactor consumes
-  any result that still arrives.
-- `Request::responder()` returns a `Responder` that can reply after the request itself has
-  been dropped. Request delivery credit returns normally; a separate router-visible reply
-  capability preserves correlation until the last `Request`/`Responder` is dropped or a reply
-  is admitted. If the final capability is dropped while the caller is still attached, the call
-  terminates with `CALL_GONE` and dispatch `dispatched` while the route remains live, or the
-  existing `NO_SERVICE`/`dispatched` terminal if the route has ended. Capabilities share the
-  service connection's owner bound.
-- A call fails with `call.failed` data in its `BusError`:
-  - Queued calls whose service unregisters or disconnects fail with `NO_SERVICE` and dispatch
-    `not-dispatched`.
-  - Dispatched calls whose service disconnects without replying fail with `NO_SERVICE` and
-    dispatch `dispatched`.
-  - Dispatched calls whose last responder is released without replying fail with `CALL_GONE`
-    and dispatch `dispatched`.
-  - A lost connection fails pending calls with `ROUTER_LOST` and dispatch `unknown`.
-
-#### Pub/sub
-
-```rust
-bus.declare_topic("session.demo.snapshots", Retained::Latest).await?;  // TopicInfo
-bus.clear_topic(name).await?;    // bool: a retained value was released
-bus.delete_topic(name).await?;   // bool; CONFLICT while it has subscribers
-let mut sub = bus.subscribe(name, SubscriptionConfig::latest().in_flight(1).replay(true)).await?;
-let receipt = bus.publish(name, payload, &[("frame", &frame)]).await?; // topic_sequence, subscribers, replaced
-let msg = sub.next().await;      // Option<Message>; try_next() does not wait
-msg.topic_sequence(); msg.replaced(); msg.topic_incarnation(); msg.payload(); msg.artifact("frame")?;
-```
-
-- `SubscriptionConfig::latest()` is 1 queued and 2 in flight. `SubscriptionConfig::bounded()`
-  is 64 queued and 16 in flight. `.queued(n)`, `.in_flight(n)` and `.replay(bool)` adjust them.
-- A credit returns only when the delivery is consumed: when the `Message` and every artifact
-  or `ArtifactFile` taken from it have been dropped.
-- A retained replay into a bounded subscription is admitted atomically under the same queued
-  envelope-byte quota as an ordinary bounded publication. Latest replay remains outside that
-  byte pool and is bounded by one slot per subscription.
-- Dropping a `Subscription` unsubscribes and discards its queue. Messages already handed out
-  stay valid.
-
-#### Artifacts
-
-```rust
-let mut writer = bus.artifacts().allocate(len, "image/x-rgba").await?; // ArtifactWriter: io::Write
-writer.write_all(&pixels)?;
-let frame = writer.seal().await?;              // or seal_with_digest(Some(sha256_hex))
-frame.reference();                             // ArtifactRef
-let bytes = frame.read_all().await?;           // Vec<u8>
-let file = frame.open().await?;                // ArtifactFile: io::Read + io::Seek, keeps the handle
-let kept = frame.retain().await?;              // an independent explicit hold
-```
-
-- `Artifact` is a read-only, cloneable handle on one owner: a delivery or an explicit hold.
-  Its last clone (including any `ArtifactFile`) releases that owner.
-- `ArtifactWriter` is unique. Dropping it unsealed releases the staging storage. Writes past
-  the allocated length fail. Unwritten bytes read as zeros.
-- Sealing copies staging into a fresh read-only (0444) file and unlinks staging. A descriptor
-  the producer kept or duplicated afterwards writes only to the unlinked staging inode. Sealing
-  therefore needs quota for both copies while it runs.
-
-### Errors
-
-`BusError { code: ErrorCode, message, dispatch: Dispatch }`. The codes are the draft's
-`INVALID_ENVELOPE`, `VERSION_MISMATCH`, `NOT_AUTHORIZED`, `NO_SERVICE`, `TARGET_CHANGED`,
-`BACKPRESSURE`, `CALL_GONE`, `ARTIFACT_UNSEALED`, `ARTIFACT_GONE`, `OWNER_INVALID`,
-`QUOTA_EXCEEDED`, `STORE_FAILURE` and `ROUTER_LOST`, plus `CONFLICT`, `NO_TOPIC` and
-`ARTIFACT_MISMATCH`. `Dispatch` is `not-dispatched`, `dispatched` or `unknown`. Refusals
-before admission are `not-dispatched`. A command in flight when the connection is lost reports
-`unknown`.
-
-## Wire summary
-
-- Frames are a `u32` little-endian length followed by 1..=65,536 bytes of UTF-8 JSON. The length
-  is checked before any allocation.
-- Every frame is parsed strictly:
-  - Duplicate keys at any depth, invalid UTF-8, non-finite numbers and trailing bytes are
-    refused. Nesting is limited to 128 levels.
-  - Unknown fields are refused in the envelope, attachments, references and every management
-    body. `payload` and `outcome` are opaque objects.
-- Frame or envelope errors close the connection after a `connection.closing` notice. They
-  include a bad length, bad JSON, an unknown envelope field, a wrong kind, a non-null `replyTo`,
-  a command id that is not canonical or does not increase, a command before `bus.hello`, a
-  second hello, and a major/minor other than 1.0 after hello. A body-level error (unknown op,
-  bad field, out-of-range value, attachments on a management op) gets an `INVALID_ENVELOPE`
-  reply and the connection stays up.
-- The SDK applies symmetric checks to router frames: exact 1.0 version, strictly increasing
-  canonical `bus-<U64>` ids, kind/replyTo/attachment direction rules, expected reply operation,
-  delivery correlations and complete strict reply, delivery and notice body parsing.
-- Ids:
-  - Commands: `msg-<U64>`, strictly increasing per connection.
-  - Router envelopes: `bus-<n>`. Connections: `conn-<n>`. Services: `svc-<n>`. Topics:
-    `top-<n>`. Subscriptions: `sub-<n>`. Calls: `call-<U64>`, increasing per client.
-  - Artifacts: `a-<n>`. Deliveries: `dlv-<n>`. Holds and writers: `own-<n>`.
-  - `routerId` is `router-<16 hex>` and `storeId` is `store-<16 hex>` (same tag).
-  - Delivery and hold serials have separate per-connection watermarks.
-- Notices:
-  - `call.failed {callId, code, message, dispatch}`
-  - `route.removed {name, serviceIncarnation, reason}`
-  - `subscription.closed {subscriptionId, topic, topicIncarnation, reason}`
-  - `connection.closing {code, message}`
-- The hello reply's `limits` object gives counts as JSON integers and byte sizes as U64 strings.
-  Its fields: `maxEnvelopeBytes`, `maxAttachments`, `maxBatch`, `maxClients`, `maxServices`,
-  `maxTopics`, `maxSubscriptionsPerClient`, `maxSubscriptions`, `maxActiveCallsPerClient`,
-  `maxServiceQueued`, `maxServiceInFlight`, `maxLatestInFlight`, `maxBoundedQueued`,
-  `maxBoundedInFlight`, `maxOwnersPerClient`, `reservedOwnersPerClient`, `maxControlFrames`,
-  `maxStoreBytes`, `maxArtifactBytes`, `maxRetainedBytes`, `maxQueuedBytesPerClient` and
-  `maxControlBytes`.
-- `contractDigest` is the SHA-256 of `wire::CONTRACT`, a text listing of every operation,
-  delivery and notice shape. The client refuses a router whose digest differs from its own.
-
-## Semantics worth knowing
-
-- **Admission is all or nothing.** `rpc.call`, `rpc.reply` and `publish` validate every
-  attachment and every bound before changing any state. A refused publication creates no
-  delivery, does not move the retained value and spends no topic sequence number. A refused
-  syntactically valid call id advances the issued-id watermark even when semantic admission is
-  refused, while creating no call, delivery or root. Reuse or decrease is rejected.
-- **Ownership.** Each sealed artifact has a root count. Roots are held by queued deliveries,
-  delivered-but-unconsumed deliveries, explicit holds and a retained topic value. A delivery
-  that names one artifact twice holds one root. Fan-out adds roots and never copies bytes. When
-  the last root goes, the artifact leaves the quota and its file is unlinked, outside the router
-  lock. A process that still has the file open keeps its pages until it closes it.
-- **Owner budget.** `max_owners_per_client` counts deliveries handed to the client and not
-  consumed, explicit holds and writers. Topic deliveries, holds and writers may use all but
-  `reserved_owners_per_client`; the reserve is for RPC requests and results. A topic delivery
-  over budget waits in its queue. A hold or allocation over budget fails with `QUOTA_EXCEEDED`.
-  Request reply capabilities consume the same finite bound independently of request delivery
-  credit, preventing retained responders from growing detached correlation state without limit.
-- **Lanes.** The router sends each client its replies and notices first, then RPC requests and
-  results, then topic messages. Topic messages still get one frame after 16 consecutive
-  higher-priority frames. Router envelope ids are assigned only after this scheduler selects
-  the next item, so they increase in actual write order. Replies and notices waiting for one client are bounded by
-  `max_control_frames` / `max_control_bytes`; exceeding either closes that client with a
-  `connection.closing` notice. The client sends consumes, releases and cancels ahead of
-  ordinary commands and batches up to 64 ids per command. A full client control lane closes the
-  connection rather than drop a release.
-- **No waiting on readers.** A client that stops reading stalls only its own writer task. The
-  router keeps admitting until that client's queues refuse, then returns `BACKPRESSURE` to
-  publishers of bounded topics. Connection teardown is synchronized with each synchronous
-  `poll_write`/`poll_flush` call without holding a mutex across an await. Teardown either observes
-  a complete frame before reclaiming its delivery owner, or marks a partial frame canceled before
-  cleanup and appends no final notice to the truncated stream. At a frame boundary, normal final
-  notices are still attempted.
-- **RPC.** First dispatch is FIFO per service, which includes per caller. A call is marked
-  dispatched when its bytes are about to be written. Replies correlate by call id and may
-  arrive in any order. A second reply to one call fails with `CALL_GONE`. A reply to a detached
-  call returns `routed:false` and creates no roots. Unregistering a service fails its queued
-  calls; dispatched calls can still be answered while a `Request` or `Responder` retains reply
-  capability. Both cancel/consume orderings retire cleanly.
-- **Seals** copy (and hash, when a digest was given) on Tokio's blocking pool, alongside the
-  connection's reader, so a large copy does not hold up that client's releases. If the writer is released or disconnects
-  mid-seal, the copy is discarded and the artifact is never published.
-
-## Differences from the draft
-
-1. **Extra error codes.** `CONFLICT` covers a duplicate registration, a conflicting topic
-   redeclaration and deleting a topic that has subscribers. `NO_TOPIC` covers publishing or
-   subscribing to an undeclared topic. `ARTIFACT_MISMATCH` covers a seal whose length or digest
-   is wrong, and a reference that disagrees with the artifact it names.
-2. **Topics must be declared.** Publish and subscribe fail with `NO_TOPIC` otherwise.
-   `topic.delete` of an unknown topic returns `deleted:false`. `topic.clear` of an unknown
-   topic returns `NO_TOPIC`.
-3. **When notices are sent.**
-   - `subscription.closed` is sent only when the router shuts down, because `topic.delete`
-     requires no subscribers and nothing else closes a subscription.
-   - `route.removed` goes to callers with queued or dispatched calls on the removed
-     registration, not to every client.
-   - `connection.closing` is an extra notice that precedes every router-initiated close.
-4. **Byte budgets.**
-   - `max_queued_bytes_per_client` counts only `bounded` subscriptions. A `latest` slot is bounded
-     by subscription count times envelope size.
-   - `max_retained_bytes` (not in the draft's table) counts the artifact bytes pinned by
-     retained values, once per topic.
-5. **Delivery size.** Admission computes the delivery's size with the router-added ids at their
-   longest. If that would exceed 65,536 bytes it refuses with `INVALID_ENVELOPE`, so an inbound
-   envelope near the limit can be refused even though it fits.
-6. **Identity.** One live connection per client id. The router remembers each client id's last
-   incarnation and refuses its reuse. Launcher-bound `*_as` endpoints authenticate the Hello id;
-   trusted open/unbound endpoints do not. With an open policy this is one small record per
-   distinct client id ever seen.
-7. **Seal reply.** The reply's `ownerId` is the writer's own id, now an explicit hold.
-8. **No `budget` argument on calls, and no router executable.** Timeouts are the caller's
-   (`tokio::time::timeout` plus `cancel`). The draft's executable is optional; embed `Router`.
-9. **Wire strictness.** Management bodies reject unknown fields. After hello, envelopes must
-   carry `minor: 0`.
-10. **Reply capability release.** The SDK sends `rpc.responder.release {callId,
-    requestDeliveryId} -> {released}` when the last local reply capability is dropped. This
-    keeps request consumption independent from late-reply correlation while bounding that
-    correlation under the service connection's owner limit. For an attached dispatched call,
-    final release atomically retires the correlation and caller slot and emits `call.failed`
-    with dispatch `dispatched`: `CALL_GONE` while the route remains live, or `NO_SERVICE` after
-    route loss.
-
-## Limitations
-
-- **One host, one user.** Clients must run as the router's user and see the same store root.
-  The store directory is 0700, staging files 0600, sealed files 0444 and the socket 0600. Bus
-  authority (grants, connection-scoped owner ids, location grants) is enforced on bus
-  operations, not on the filesystem: a process running as the same user can read, mutate,
-  replace, chmod or unlink store files directly and can deny service. Mode 0600 authenticates
-  only the shared OS user, not a Flybus participant.
-- **No memory maps.** Artifacts are read through `std::fs::File` (`ArtifactFile`) or
-  `read_all()`; there is no mmap API. `ArtifactFile` reads are blocking I/O.
-- **Stats are logical.** `RouterStats` counts registry entries. Unlinked files that are still
-  open, client memory and OS pages are not in it.
-- **Fairness is modest.** Fairness between clients is Tokio's scheduling plus a yield after
-  every 32 commands a connection sends. Within a connection, subscriptions and services are
-  served round robin. There is no weighting.
-- **Orphan cleanup needs a restart.** Store directories left by a stopped router are removed
-  only when a new router starts on the same root. A directory counts as orphaned when it carries
-  the store marker and its `flock` is free.
-- **Rust only.** There are no other language bindings.
-- **Two perf runs.** `tests/perf.rs` (ignored by default) measured 640x480 RGBA frames at
-  60 Hz over a Unix socket to three latest-mode consumers, one delayed 40 ms per frame. It ran
-  twice, on a laptop under WSL, release build, router and clients in one process. Allocate,
-  write and seal took p50 1.2 to 1.3 ms and p99 1.5 to 2.0 ms per 1.2 MB frame. Publish
-  admission took p50 0.2 ms. The RPC round trip took p50 0.24 / 0.29 to 0.31 / 0.50 ms with
-  1 / 2 / 4 agents. The whole process used 0.18 to 0.25 cores and about 15 MB RSS. The store
-  peaked at 3.7 MB. These are two runs, not capacity data.
-
-## Tests
-
-```text
-cargo test -p flybus                                              # unit + integration
-cargo test --release -p flybus --test perf -- --ignored --nocapture  # the measurement above
-cargo run -p flybus --example demo                                # counter RPC, observer, held frame
-```
-
-Every integration test runs twice, once over the in-memory transport and once over a Unix
-socket, through the same router code:
-
-- `tests/wire.rs`: hello negotiation and refusals, malformed frames of every kind, body errors
-  that keep the connection, the exact 65,536-byte limit and control-lane exhaustion.
-- `tests/rpc.rs`: exclusive and pinned registration, authority, FIFO dispatch with
-  out-of-order completion, backpressure, all four cancel states, single replies, service
-  disconnect and unregister, forged replies and call ids, an endpoint cache replaying an
-  artifact result, and abandoned calls.
-- `tests/sol_review_races.rs`: launcher-bound identity and Hello resource bounds, detached RPC
-  orderings, responder/service teardown, reply/cancel races, replay admission, call-id
-  watermarking, strict client router validation, unsent rollback and shared task shutdown.
-- `tests/pubsub.rs`: bounded FIFO with atomic backpressure, latest coalescing, credits,
-  retention and incarnations, zero-subscriber publication, unsubscribe, validation, quotas, a
-  saturated subscriber that does not block RPC, and shutdown notices.
-- `tests/artifacts.rs`: allocate, seal and read; unsealed use; immutability against live
-  writable descriptors; length and digest checks; quotas; one physical object shared by
-  fan-out and collected after the last consumer; extracted artifacts and holds; atomic
-  admission; release watermarks; connection-scoped owners; abandoned futures; disconnects; and
-  router restarts.
-- `tests/integration.rs`: two agents called in parallel with a forwarded frame, an environment
-  service, committed snapshot publication, a slow latest consumer and a bounded recorder.

services/flysim/crates/flybus/examples/demo.rs

@@ -1,99 +0,0 @@
-//! A counter RPC, a pub/sub observer and a frame artifact held past its message, in one
-//! process over the in-memory transport (bus-v1 section 11).
-//!
-//! ```text
-//! cargo run -p flybus --example demo
-//! ```
-
-use std::io::Write;
-
-use flybus::{
-    Client, ClientConfig, Policy, Retained, Router, RouterConfig, ServiceConfig, SubscriptionConfig,
-};
-use serde_json::{Map, Value, json};
-
-fn obj(v: Value) -> Map<String, Value> {
-    v.as_object().cloned().unwrap_or_default()
-}
-
-#[tokio::main(flavor = "current_thread")]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let root = std::env::temp_dir().join(format!("flybus-demo-{}", std::process::id()));
-    let mut config = RouterConfig::new(&root);
-    config.policy = Policy::open();
-    let router = Router::new(config)?;
-    let connect = |id: &str| {
-        Client::connect(
-            router.connect_in_memory_as(id),
-            ClientConfig::new(id, &root),
-        )
-    };
-
-    // A counter service.
-    let counter = connect("counter").await?;
-    let mut svc = counter
-        .register("example.counter", ServiceConfig::default())
-        .await?;
-    tokio::spawn(async move {
-        let mut total = 0;
-        while let Some(req) = svc.next().await {
-            total += req.payload()["amount"].as_i64().unwrap_or(0);
-            let _ = req.reply(obj(json!({ "total": total })), &[]).await;
-        }
-    });
-    let app = connect("app").await?;
-    for _ in 0..3 {
-        let res = app
-            .call_and_wait(
-                "example.counter",
-                None,
-                "Counter.Increment",
-                obj(json!({"amount": 2})),
-                &[],
-            )
-            .await?;
-        println!("counter total = {}", res.outcome()["total"]);
-    }
-
-    // An observer of a frame topic.
-    app.declare_topic("world.demo.frame", Retained::None)
-        .await?;
-    let observer = connect("observer").await?;
-    let mut frames = observer
-        .subscribe("world.demo.frame", SubscriptionConfig::latest())
-        .await?;
-
-    let mut writer = app
-        .artifacts()
-        .allocate(160 * 144 * 4, "image/x-rgba")
-        .await?;
-    writer.write_all(&vec![0x7f; 160 * 144 * 4])?;
-    let frame = writer.seal().await?;
-    let receipt = app
-        .publish(
-            "world.demo.frame",
-            obj(json!({"width": 160, "height": 144})),
-            &[("frame", &frame)],
-        )
-        .await?;
-    println!(
-        "published sequence {} to {} subscriber(s)",
-        receipt.topic_sequence, receipt.subscribers
-    );
-    drop(frame);
-
-    let message = frames.next().await.ok_or("subscription closed")?;
-    let image = message.artifact("frame")?;
-    drop(message); // the extracted handle still owns the delivery
-    let bytes = image.read_all().await?;
-    println!(
-        "read {} bytes after the message was dropped; router: {:?}",
-        bytes.len(),
-        router.stats()
-    );
-    drop(image); // the last handle: the delivery is consumed and the frame collected
-
-    router.shutdown();
-    std::fs::remove_dir_all(&root)?;
-    Ok(())
-}

services/flysim/crates/flybus/src/client/handles.rs

@@ -1,677 +0,0 @@
-//! RAII handles: artifacts, writers, deliveries, services, subscriptions and pending calls.
-//!
-//! Every owner the router tracks for this client is behind one `OwnerGuard`. Its last clone
-//! dropping queues `delivery.consumed` (for a delivery) or `artifact.release` (for a hold or
-//! writer). A message, the artifacts extracted from it and any open files share the message's
-//! guard, so a delivery is consumed only when all of them are gone.
-
-use std::fs::File;
-use std::io::{self, Read, Seek, SeekFrom, Write};
-use std::sync::Arc;
-
-use serde_json::{Map, Value};
-use tokio::sync::{mpsc, oneshot};
-
-use super::reactor::{CallSlot, ClientConn, Control, Extra, Hook, OutCommand};
-use crate::error::{BusError, Dispatch, ErrorCode};
-use crate::store::{open_read, resolve};
-use crate::wire::{ArtifactRef, Attachment, Fields, GENERATION, Identity, Location};
-
-pub(crate) struct OwnerGuard {
-    pub id: String,
-    pub delivery: bool,
-    pub conn: Arc<ClientConn>,
-}
-
-impl Drop for OwnerGuard {
-    fn drop(&mut self) {
-        let id = std::mem::take(&mut self.id);
-        let item = if self.delivery {
-            Control::Consumed(id)
-        } else {
-            Control::Release(id)
-        };
-        self.conn.shared.push_control(item);
-    }
-}
-
-pub(crate) fn attachment_list(
-    list: &[(&str, &Artifact)],
-) -> (Vec<Attachment>, Vec<Arc<OwnerGuard>>) {
-    let atts = list
-        .iter()
-        .map(|(name, a)| Attachment {
-            name: (*name).to_owned(),
-            reference: a.reference.as_ref().clone(),
-            owner_id: a.owner.id.clone(),
-        })
-        .collect();
-    let keep = list.iter().map(|(_, a)| a.owner.clone()).collect();
-    (atts, keep)
-}
-
-fn find(
-    list: &[(String, ArtifactRef)],
-    guard: &Arc<OwnerGuard>,
-    name: &str,
-) -> Result<Artifact, BusError> {
-    list.iter()
-        .find(|(n, _)| n == name)
-        .map(|(_, r)| Artifact {
-            reference: Arc::new(r.clone()),
-            owner: guard.clone(),
-        })
-        .ok_or_else(|| BusError::invalid(format!("no attachment named {name:?}")))
-}
-
-// ---------------------------------------------------------------------------------------------
-// Artifacts
-
-/// A read-only, cloneable handle on an immutable artifact. While any clone (or a file opened
-/// from it) lives, the owner it came from keeps the bytes alive.
-#[derive(Clone)]
-pub struct Artifact {
-    pub(crate) reference: Arc<ArtifactRef>,
-    pub(crate) owner: Arc<OwnerGuard>,
-}
-
-impl std::fmt::Debug for Artifact {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("Artifact")
-            .field("reference", &self.reference)
-            .field("owner", &self.owner.id)
-            .finish()
-    }
-}
-
-impl Artifact {
-    pub fn reference(&self) -> &ArtifactRef {
-        &self.reference
-    }
-
-    /// The router-side owner this handle rides on: a delivery id or an explicit hold id.
-    pub fn owner_id(&self) -> &str {
-        &self.owner.id
-    }
-
-    /// Opens the sealed bytes read-only. The file keeps this handle (and so its owner) alive.
-    pub async fn open(&self) -> Result<ArtifactFile, BusError> {
-        let mut body = Map::new();
-        body.insert("ref".into(), self.reference.to_json());
-        body.insert("ownerId".into(), self.owner.id.clone().into());
-        let shared = &self.owner.conn.shared;
-        let reply = shared
-            .command(
-                "artifact.open",
-                body,
-                Vec::new(),
-                vec![self.owner.clone()],
-                Hook::None,
-            )
-            .await?;
-        let loc = Location::from_json(Fields::of(&reply.value, "reply").value("readLocation")?)?;
-        if loc.store_id != self.reference.store_id {
-            return Err(BusError::new(
-                ErrorCode::ArtifactGone,
-                "read location names another store",
-            ));
-        }
-        let path = resolve(&shared.store_root, &loc.store_id, &loc)?;
-        let file = open_read(&path)
-            .map_err(|e| BusError::new(ErrorCode::StoreFailure, format!("open: {e}")))?;
-        let len = file
-            .metadata()
-            .map_err(|e| BusError::new(ErrorCode::StoreFailure, e.to_string()))?
-            .len();
-        if len != self.reference.byte_length {
-            return Err(BusError::new(
-                ErrorCode::ArtifactMismatch,
-                "sealed file length disagrees with the reference",
-            ));
-        }
-        Ok(ArtifactFile {
-            file,
-            _artifact: self.clone(),
-        })
-    }
-
-    /// Reads the whole artifact (on the blocking pool).
-    pub async fn read_all(&self) -> Result<Vec<u8>, BusError> {
-        let mut file = self.open().await?;
-        tokio::task::spawn_blocking(move || {
-            let mut out = Vec::with_capacity(file.len() as usize);
-            file.read_to_end(&mut out).map(|_| out)
-        })
-        .await
-        .map_err(|e| BusError::new(ErrorCode::StoreFailure, e.to_string()))?
-        .map_err(|e| BusError::new(ErrorCode::StoreFailure, e.to_string()))
-    }
-
-    /// Creates an independent explicit hold, so the bytes outlive this handle's delivery.
-    pub async fn retain(&self) -> Result<Artifact, BusError> {
-        let mut body = Map::new();
-        body.insert("ref".into(), self.reference.to_json());
-        body.insert("ownerId".into(), self.owner.id.clone().into());
-        let shared = &self.owner.conn.shared;
-        let reply = shared
-            .command(
-                "artifact.retain",
-                body,
-                Vec::new(),
-                vec![self.owner.clone()],
-                Hook::Owner,
-            )
-            .await?;
-        match reply.extra {
-            Extra::Owner(owner) => Ok(Artifact {
-                reference: self.reference.clone(),
-                owner,
-            }),
-            _ => Err(BusError::lost("retain reply without an owner")),
-        }
-    }
-}
-
-/// An open, read-only sealed file. Holds its [`Artifact`].
-pub struct ArtifactFile {
-    file: File,
-    _artifact: Artifact,
-}
-
-impl ArtifactFile {
-    pub fn len(&self) -> u64 {
-        self._artifact.reference.byte_length
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.len() == 0
-    }
-
-    pub fn artifact(&self) -> &Artifact {
-        &self._artifact
-    }
-}
-
-impl Read for ArtifactFile {
-    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
-        self.file.read(buf)
-    }
-}
-
-impl Seek for ArtifactFile {
-    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
-        self.file.seek(pos)
-    }
-}
-
-/// The unique writer of a freshly allocated artifact. Not cloneable. Dropping it unsealed
-/// releases the staging storage; [`ArtifactWriter::seal`] consumes it.
-pub struct ArtifactWriter {
-    pub(crate) file: Option<File>,
-    pub(crate) owner: Arc<OwnerGuard>,
-    pub(crate) artifact_id: String,
-    pub(crate) byte_length: u64,
-    pub(crate) written: u64,
-}
-
-impl ArtifactWriter {
-    pub fn artifact_id(&self) -> &str {
-        &self.artifact_id
-    }
-
-    pub fn byte_length(&self) -> u64 {
-        self.byte_length
-    }
-
-    /// Closes the writable handle and seals, returning the immutable artifact on an explicit
-    /// hold. Bytes not written read as zeros: the staging file is preallocated.
-    pub async fn seal(self) -> Result<Artifact, BusError> {
-        self.seal_with_digest(None).await
-    }
-
-    /// As [`seal`](Self::seal), and the router refuses the seal unless the content's SHA-256
-    /// (lowercase hex) equals `digest`.
-    pub async fn seal_with_digest(mut self, digest: Option<String>) -> Result<Artifact, BusError> {
-        drop(self.file.take());
-        let mut body = Map::new();
-        body.insert("artifactId".into(), self.artifact_id.clone().into());
-        body.insert("generation".into(), GENERATION.to_string().into());
-        body.insert("ownerId".into(), self.owner.id.clone().into());
-        body.insert("digest".into(), digest.map_or(Value::Null, Value::String));
-        let shared = &self.owner.conn.shared;
-        let reply = shared
-            .command(
-                "artifact.seal",
-                body,
-                Vec::new(),
-                vec![self.owner.clone()],
-                Hook::None,
-            )
-            .await?;
-        let reference = ArtifactRef::from_json(Fields::of(&reply.value, "reply").value("ref")?)?;
-        Ok(Artifact {
-            reference: Arc::new(reference),
-            owner: self.owner.clone(),
-        })
-    }
-}
-
-impl Write for ArtifactWriter {
-    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
-        let room = self.byte_length - self.written;
-        if buf.len() as u64 > room {
-            return Err(io::Error::new(
-                io::ErrorKind::InvalidInput,
-                "write past the allocated length",
-            ));
-        }
-        let file = self
-            .file
-            .as_mut()
-            .ok_or_else(|| io::Error::other("writer is closed"))?;
-        let n = file.write(buf)?;
-        self.written += n as u64;
-        Ok(n)
-    }
-
-    fn flush(&mut self) -> io::Result<()> {
-        self.file.as_mut().map_or(Ok(()), |f| f.flush())
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Deliveries
-
-/// One `topic.message` delivery. Dropping it, and every artifact taken from it, consumes the
-/// delivery and returns its credit.
-pub struct Message {
-    pub(crate) guard: Arc<OwnerGuard>,
-    pub(crate) subscription_id: String,
-    pub(crate) topic: String,
-    pub(crate) topic_incarnation: String,
-    pub(crate) topic_sequence: u64,
-    pub(crate) replaced: u64,
-    pub(crate) payload: Map<String, Value>,
-    pub(crate) attachments: Vec<(String, ArtifactRef)>,
-}
-
-impl Message {
-    pub fn delivery_id(&self) -> &str {
-        &self.guard.id
-    }
-    pub fn subscription_id(&self) -> &str {
-        &self.subscription_id
-    }
-    pub fn topic(&self) -> &str {
-        &self.topic
-    }
-    pub fn topic_incarnation(&self) -> &str {
-        &self.topic_incarnation
-    }
-    pub fn topic_sequence(&self) -> u64 {
-        self.topic_sequence
-    }
-    /// Undelivered messages coalesced into this one since the previous delivery.
-    pub fn replaced(&self) -> u64 {
-        self.replaced
-    }
-    pub fn payload(&self) -> &Map<String, Value> {
-        &self.payload
-    }
-    pub fn attachment_names(&self) -> impl Iterator<Item = &str> {
-        self.attachments.iter().map(|(n, _)| n.as_str())
-    }
-    /// An artifact handle sharing this delivery's guard.
-    pub fn artifact(&self, name: &str) -> Result<Artifact, BusError> {
-        find(&self.attachments, &self.guard, name)
-    }
-}
-
-/// An incoming `rpc.request`. Dropping it (and its artifacts) consumes the request delivery;
-/// that is independent of replying.
-pub struct Request {
-    pub(crate) guard: Arc<OwnerGuard>,
-    pub(crate) reply_guard: Arc<ReplyGuard>,
-    pub(crate) call_id: String,
-    pub(crate) caller: Identity,
-    pub(crate) target: String,
-    pub(crate) service_incarnation: String,
-    pub(crate) method: String,
-    pub(crate) payload: Map<String, Value>,
-    pub(crate) attachments: Vec<(String, ArtifactRef)>,
-}
-
-impl Request {
-    pub fn delivery_id(&self) -> &str {
-        &self.guard.id
-    }
-    pub fn call_id(&self) -> &str {
-        &self.call_id
-    }
-    /// The caller identity supplied by the router. It is authenticated only when the router
-    /// accepted this connection through a launcher-bound `*_as` transport entry point.
-    pub fn caller(&self) -> &Identity {
-        &self.caller
-    }
-    pub fn target(&self) -> &str {
-        &self.target
-    }
-    pub fn service_incarnation(&self) -> &str {
-        &self.service_incarnation
-    }
-    pub fn method(&self) -> &str {
-        &self.method
-    }
-    pub fn payload(&self) -> &Map<String, Value> {
-        &self.payload
-    }
-    pub fn artifact(&self, name: &str) -> Result<Artifact, BusError> {
-        find(&self.attachments, &self.guard, name)
-    }
-    /// A reply capability that keeps bounded router correlation alive independently of the
-    /// request delivery credit.
-    pub fn responder(&self) -> Responder {
-        Responder {
-            guard: self.reply_guard.clone(),
-            call_id: self.call_id.clone(),
-            request_delivery_id: self.guard.id.clone(),
-        }
-    }
-    /// Replies. `Ok(true)` if routed to the caller, `Ok(false)` if the caller had detached.
-    pub async fn reply(
-        &self,
-        outcome: Map<String, Value>,
-        attachments: &[(&str, &Artifact)],
-    ) -> Result<bool, BusError> {
-        self.responder().reply(outcome, attachments).await
-    }
-}
-
-/// Replies to one request, whether or not the request delivery is still held.
-#[derive(Clone)]
-pub struct Responder {
-    guard: Arc<ReplyGuard>,
-    call_id: String,
-    request_delivery_id: String,
-}
-
-impl Responder {
-    pub async fn reply(
-        &self,
-        outcome: Map<String, Value>,
-        attachments: &[(&str, &Artifact)],
-    ) -> Result<bool, BusError> {
-        let (atts, keep) = attachment_list(attachments);
-        let mut body = Map::new();
-        body.insert("callId".into(), self.call_id.clone().into());
-        body.insert(
-            "requestDeliveryId".into(),
-            self.request_delivery_id.clone().into(),
-        );
-        body.insert("outcome".into(), Value::Object(outcome));
-        let reply = self
-            .guard
-            .conn
-            .shared
-            .command("rpc.reply", body, atts, keep, Hook::None)
-            .await?;
-        Ok(Fields::of(&reply.value, "reply").boolean("routed")?)
-    }
-}
-
-pub(crate) struct ReplyGuard {
-    pub conn: Arc<ClientConn>,
-    pub call_id: String,
-    pub request_delivery_id: String,
-}
-
-impl Drop for ReplyGuard {
-    fn drop(&mut self) {
-        self.conn.shared.push_control(Control::ResponderReleased {
-            call_id: self.call_id.clone(),
-            request_delivery_id: self.request_delivery_id.clone(),
-        });
-    }
-}
-
-/// A terminal `rpc.result`. Dropping it (and its artifacts) consumes the result delivery.
-pub struct RpcResult {
-    pub(crate) guard: Arc<OwnerGuard>,
-    pub(crate) call_id: String,
-    pub(crate) responder: Identity,
-    pub(crate) service_incarnation: String,
-    pub(crate) outcome: Map<String, Value>,
-    pub(crate) attachments: Vec<(String, ArtifactRef)>,
-}
-
-impl RpcResult {
-    pub fn delivery_id(&self) -> &str {
-        &self.guard.id
-    }
-    pub fn call_id(&self) -> &str {
-        &self.call_id
-    }
-    pub fn responder(&self) -> &Identity {
-        &self.responder
-    }
-    pub fn service_incarnation(&self) -> &str {
-        &self.service_incarnation
-    }
-    pub fn outcome(&self) -> &Map<String, Value> {
-        &self.outcome
-    }
-    pub fn artifact(&self, name: &str) -> Result<Artifact, BusError> {
-        find(&self.attachments, &self.guard, name)
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Services, subscriptions, calls
-
-pub(crate) struct ServiceGuard {
-    pub conn: Arc<ClientConn>,
-    pub incarnation: String,
-}
-
-/// A registered service endpoint. Dropping it unregisters.
-pub struct Service {
-    pub(crate) name: String,
-    pub(crate) rx: mpsc::UnboundedReceiver<Request>,
-    pub(crate) guard: ServiceGuard,
-}
-
-impl Service {
-    pub fn name(&self) -> &str {
-        &self.name
-    }
-    pub fn incarnation(&self) -> &str {
-        &self.guard.incarnation
-    }
-    /// The next request, or `None` once the connection is closed.
-    pub async fn next(&mut self) -> Option<Request> {
-        self.rx.recv().await
-    }
-}
-
-impl Drop for Service {
-    fn drop(&mut self) {
-        let shared = &self.guard.conn.shared;
-        let tx = shared.lock().services.remove(&self.guard.incarnation);
-        drop(tx);
-        // Route removal must precede abandoning buffered requests, whose last responder drops
-        // queue responder-release controls. This preserves NO_SERVICE as their terminal cause.
-        shared.push_control(Control::Unregister {
-            name: self.name.clone(),
-            service_incarnation: self.guard.incarnation.clone(),
-        });
-        self.rx.close();
-        while let Ok(request) = self.rx.try_recv() {
-            drop(request);
-        }
-    }
-}
-
-pub(crate) struct SubscriptionGuard {
-    pub conn: Arc<ClientConn>,
-    pub id: String,
-}
-
-/// An exact-topic subscription. Dropping it unsubscribes; messages already handed out stay
-/// valid.
-pub struct Subscription {
-    pub(crate) rx: mpsc::UnboundedReceiver<Message>,
-    pub(crate) guard: SubscriptionGuard,
-    pub(crate) topic_incarnation: String,
-}
-
-impl Subscription {
-    pub fn id(&self) -> &str {
-        &self.guard.id
-    }
-    pub fn topic_incarnation(&self) -> &str {
-        &self.topic_incarnation
-    }
-    /// The next message, or `None` once the subscription or connection is closed.
-    pub async fn next(&mut self) -> Option<Message> {
-        self.rx.recv().await
-    }
-    /// A message already delivered to this client, without waiting.
-    pub fn try_next(&mut self) -> Option<Message> {
-        self.rx.try_recv().ok()
-    }
-}
-
-impl Drop for Subscription {
-    fn drop(&mut self) {
-        let shared = &self.guard.conn.shared;
-        let tx = shared.lock().subscriptions.remove(&self.guard.id);
-        drop(tx);
-        let mut body = Map::new();
-        body.insert("subscriptionId".into(), self.guard.id.clone().into());
-        let cmd = OutCommand {
-            op: "unsubscribe",
-            body,
-            attachments: Vec::new(),
-            respond: None,
-            hook: Hook::None,
-            keep: Vec::new(),
-        };
-        let _ = shared.enqueue(cmd);
-    }
-}
-
-pub(crate) struct CallGuard {
-    pub conn: Arc<ClientConn>,
-    pub call_id: String,
-    pub done: bool,
-}
-
-impl Drop for CallGuard {
-    fn drop(&mut self) {
-        if self.done {
-            return;
-        }
-        let shared = &self.conn.shared;
-        let waiting = {
-            let mut st = shared.lock();
-            match st.calls.remove(&self.call_id) {
-                Some(slot @ CallSlot::Waiting(_)) => {
-                    st.calls.insert(self.call_id.clone(), CallSlot::Abandoned);
-                    Some(slot)
-                }
-                other => {
-                    if let Some(o) = other {
-                        st.calls.insert(self.call_id.clone(), o);
-                    }
-                    None
-                }
-            }
-        };
-        if waiting.is_some() {
-            // Best effort; a result that still arrives is consumed by the reactor.
-            shared.push_control(Control::Cancel(self.call_id.clone(), None));
-        }
-    }
-}
-
-macro_rules! debug_fields {
-    ($ty:ident, |$s:ident| { $($name:literal => $val:expr),* $(,)? }) => {
-        impl std::fmt::Debug for $ty {
-            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-                let $s = self;
-                f.debug_struct(stringify!($ty))$(.field($name, &$val))*.finish()
-            }
-        }
-    };
-}
-
-debug_fields!(ArtifactFile, |s| { "artifact" => s._artifact });
-debug_fields!(ArtifactWriter, |s| { "artifact_id" => s.artifact_id, "byte_length" => s.byte_length, "owner" => s.owner.id });
-debug_fields!(Message, |s| {
-    "delivery_id" => s.guard.id, "topic" => s.topic, "topic_sequence" => s.topic_sequence, "replaced" => s.replaced,
-});
-debug_fields!(Request, |s| { "delivery_id" => s.guard.id, "call_id" => s.call_id, "method" => s.method });
-debug_fields!(RpcResult, |s| { "delivery_id" => s.guard.id, "call_id" => s.call_id });
-debug_fields!(Responder, |s| { "call_id" => s.call_id, "request_delivery_id" => s.request_delivery_id });
-debug_fields!(Service, |s| { "name" => s.name, "incarnation" => s.guard.incarnation });
-debug_fields!(Subscription, |s| { "id" => s.guard.id, "topic_incarnation" => s.topic_incarnation });
-debug_fields!(PendingCall, |s| { "call_id" => s.guard.call_id, "service_incarnation" => s.service_incarnation });
-
-/// The router's answer to `rpc.cancel`.
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum CancelState {
-    CancelledBeforeDispatch,
-    ExecutionUnknown,
-    Completed,
-    CallGone,
-}
-
-/// An admitted call. [`result`](Self::result) waits for the terminal result. Dropping it
-/// unfinished sends a best-effort `rpc.cancel` and consumes any result that still arrives.
-pub struct PendingCall {
-    pub(crate) guard: CallGuard,
-    pub(crate) rx: oneshot::Receiver<Result<RpcResult, BusError>>,
-    pub(crate) service_incarnation: String,
-}
-
-impl PendingCall {
-    pub fn call_id(&self) -> &str {
-        &self.guard.call_id
-    }
-
-    pub fn service_incarnation(&self) -> &str {
-        &self.service_incarnation
-    }
-
-    /// Waits for the result. Cancel-safe: wrap it in a timeout and call it again, or cancel.
-    pub async fn result(&mut self) -> Result<RpcResult, BusError> {
-        if self.guard.done {
-            return Err(BusError::new(ErrorCode::CallGone, "result already taken"));
-        }
-        let r = (&mut self.rx)
-            .await
-            .unwrap_or_else(|_| Err(BusError::lost("connection closed")));
-        self.guard.done = true;
-        r
-    }
-
-    /// Asks the router to cancel. Only `CancelledBeforeDispatch` establishes that the handler
-    /// never ran. After any state but `Completed`, [`result`](Self::result) fails with
-    /// `CALL_GONE`.
-    pub async fn cancel(&self) -> Result<CancelState, BusError> {
-        let (tx, rx) = oneshot::channel();
-        let shared = &self.guard.conn.shared;
-        shared.push_control(Control::Cancel(self.guard.call_id.clone(), Some(tx)));
-        let reply = rx
-            .await
-            .unwrap_or_else(|_| Err(BusError::lost("connection closed")))?;
-        match Fields::of(&reply.value, "reply").string("state")? {
-            "cancelled-before-dispatch" => Ok(CancelState::CancelledBeforeDispatch),
-            "execution-unknown" => Ok(CancelState::ExecutionUnknown),
-            "completed" => Ok(CancelState::Completed),
-            "call-gone" => Ok(CancelState::CallGone),
-            other => Err(BusError::lost(format!("unknown cancel state {other:?}"))
-                .with_dispatch(Dispatch::Unknown)),
-        }
-    }
-}

services/flysim/crates/flybus/src/client/mod.rs

@@ -1,598 +0,0 @@
-//! The client SDK: one connection for RPC, pub/sub and artifacts.
-
-mod handles;
-mod reactor;
-
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::time::{SystemTime, UNIX_EPOCH};
-
-use serde_json::{Map, Value};
-use sha2::{Digest as _, Sha256};
-use tokio::sync::oneshot;
-
-use handles::attachment_list;
-pub use handles::{
-    Artifact, ArtifactFile, ArtifactWriter, CancelState, Message, PendingCall, Request, Responder,
-    RpcResult, Service, Subscription,
-};
-use reactor::{CallSlot, ClientConn, Extra, Hook, OutCommand, Shared};
-
-use crate::error::{BusError, Dispatch, ErrorCode};
-use crate::limits::Limits;
-use crate::store::{open_write, resolve};
-use crate::transport::Transport;
-use crate::wire::{
-    Envelope, Fields, Identity, Kind, Location, MAJOR, contract_digest, hex, is_content_type,
-    is_id, parse_serial_id, read_frame, serial_id, write_frame,
-};
-
-/// How a participant connects.
-#[derive(Clone, Debug)]
-pub struct ClientConfig {
-    /// The configured participant identity the launcher's policy knows.
-    pub client_id: String,
-    /// This SDK client's lifetime; generated when `None`. Reconnecting needs a new one.
-    pub client_incarnation: Option<String>,
-    /// The router's store root, as configured for the router.
-    pub store_root: PathBuf,
-    /// Queued consumes, releases and cancels before the client gives up on the connection.
-    pub control_lane_capacity: usize,
-}
-
-impl ClientConfig {
-    pub fn new(client_id: &str, store_root: impl Into<PathBuf>) -> ClientConfig {
-        ClientConfig {
-            client_id: client_id.to_owned(),
-            client_incarnation: None,
-            store_root: store_root.into(),
-            control_lane_capacity: 4096,
-        }
-    }
-}
-
-/// What `bus.hello` negotiated.
-#[derive(Clone, Debug)]
-pub struct SessionInfo {
-    pub router_id: String,
-    pub connection_id: String,
-    pub identity: Identity,
-    pub selected_major: u64,
-    pub selected_minor: u64,
-    pub contract_digest: String,
-    pub limits: Limits,
-}
-
-/// `publish` admission: counts, not consumption.
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub struct PublishReceipt {
-    pub topic_sequence: u64,
-    pub subscribers: u64,
-    pub replaced: u64,
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct TopicInfo {
-    /// False when an identical declaration already existed.
-    pub declared: bool,
-    pub topic_incarnation: String,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum Retained {
-    None,
-    Latest,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum Mode {
-    /// One replaceable queued value; `max_queued` is always 1.
-    Latest,
-    /// FIFO; a full queue refuses the whole publication.
-    Bounded,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub struct SubscriptionConfig {
-    pub mode: Mode,
-    pub max_queued: u32,
-    pub max_in_flight: u32,
-    pub replay_latest: bool,
-}
-
-impl SubscriptionConfig {
-    /// `latest`, 1 queued, 2 in flight.
-    pub fn latest() -> SubscriptionConfig {
-        SubscriptionConfig {
-            mode: Mode::Latest,
-            max_queued: 1,
-            max_in_flight: 2,
-            replay_latest: false,
-        }
-    }
-
-    /// `bounded`, 64 queued, 16 in flight.
-    pub fn bounded() -> SubscriptionConfig {
-        SubscriptionConfig {
-            mode: Mode::Bounded,
-            max_queued: 64,
-            max_in_flight: 16,
-            replay_latest: false,
-        }
-    }
-
-    pub fn queued(mut self, n: u32) -> SubscriptionConfig {
-        self.max_queued = n;
-        self
-    }
-
-    pub fn in_flight(mut self, n: u32) -> SubscriptionConfig {
-        self.max_in_flight = n;
-        self
-    }
-
-    pub fn replay(mut self, replay: bool) -> SubscriptionConfig {
-        self.replay_latest = replay;
-        self
-    }
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub struct ServiceConfig {
-    pub max_queued: u32,
-    pub max_in_flight: u32,
-}
-
-impl Default for ServiceConfig {
-    fn default() -> ServiceConfig {
-        ServiceConfig {
-            max_queued: 16,
-            max_in_flight: 16,
-        }
-    }
-}
-
-/// A connected participant. Cheap to clone; the connection closes when the client, and every
-/// handle made from it, is dropped, or on [`close`](Client::close).
-#[derive(Clone)]
-pub struct Client {
-    conn: Arc<ClientConn>,
-}
-
-impl std::fmt::Debug for Client {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("Client").field("info", self.info()).finish()
-    }
-}
-
-fn fresh_incarnation() -> String {
-    static COUNTER: AtomicU64 = AtomicU64::new(0);
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |d| d.as_nanos());
-    let mut h = Sha256::new();
-    h.update(std::process::id().to_le_bytes());
-    h.update(nanos.to_le_bytes());
-    h.update(COUNTER.fetch_add(1, Ordering::Relaxed).to_le_bytes());
-    format!("inc-{}", hex(&h.finalize()[..8]))
-}
-
-fn field<'a>(m: &'a Map<String, Value>) -> Fields<'a> {
-    Fields::of(m, "reply")
-}
-
-impl Client {
-    /// Connects over a transport and negotiates `bus.hello`. Must run inside a Tokio runtime.
-    pub async fn connect(transport: Transport, config: ClientConfig) -> Result<Client, BusError> {
-        if !is_id(&config.client_id) {
-            return Err(BusError::invalid("client id is not a valid id"));
-        }
-        let incarnation = config
-            .client_incarnation
-            .clone()
-            .unwrap_or_else(fresh_incarnation);
-        if !is_id(&incarnation) {
-            return Err(BusError::invalid("client incarnation is not a valid id"));
-        }
-        let (mut rd, mut wr) = tokio::io::split(transport);
-        let mut body = Map::new();
-        body.insert("clientId".into(), config.client_id.clone().into());
-        body.insert("clientIncarnation".into(), incarnation.clone().into());
-        body.insert("supportedMajors".into(), Value::Array(vec![MAJOR.into()]));
-        let hello = Envelope::new(serial_id("msg", 1), Kind::Command, "bus.hello", body);
-        let lost = |e: String| BusError::lost(format!("hello: {e}"));
-        write_frame(&mut wr, &hello.encode()?)
-            .await
-            .map_err(|e| lost(e.to_string()))?;
-        let bytes = read_frame(&mut rd)
-            .await
-            .map_err(|e| lost(e.to_string()))?
-            .ok_or_else(|| lost("connection closed".into()))?;
-        let env = Envelope::decode(&bytes).map_err(|e| lost(e.0))?;
-        let hello_router_serial = parse_serial_id("bus", &env.id)
-            .filter(|n| *n > 0)
-            .ok_or_else(|| lost("hello reply id is not canonical bus-<U64>".into()))?;
-        if env.major != MAJOR
-            || env.minor != crate::wire::MINOR
-            || env.kind != Kind::Reply
-            || env.reply_to.as_deref() != Some("msg-1")
-            || env.op != "bus.hello"
-            || !env.attachments.is_empty()
-        {
-            return Err(lost("expected the hello reply".into()));
-        }
-        let mut f = Fields::of(&env.body, "reply");
-        if !f.boolean("ok")? {
-            let e = f.object("error")?;
-            let mut g = Fields::of(e, "error");
-            let code = ErrorCode::parse(g.string("code")?)
-                .ok_or_else(|| BusError::lost("hello error has unknown code"))?;
-            let message = g.string("message")?.to_owned();
-            let dispatch = Dispatch::parse(g.string("dispatch")?)
-                .ok_or_else(|| BusError::lost("hello error has unknown dispatch"))?;
-            g.finish()?;
-            f.finish()?;
-            return Err(BusError {
-                code,
-                message,
-                dispatch,
-            });
-        }
-        let value = f.object("value")?;
-        let mut v = Fields::of(value, "hello");
-        let info = SessionInfo {
-            router_id: v.id("routerId")?,
-            connection_id: v.id("connectionId")?,
-            identity: Identity {
-                client_id: config.client_id.clone(),
-                client_incarnation: incarnation,
-            },
-            selected_major: v.int("selectedMajor", 0, u64::MAX)?,
-            selected_minor: v.int("selectedMinor", 0, u64::MAX)?,
-            contract_digest: v.string("contractDigest")?.to_owned(),
-            limits: Limits::from_json(v.value("limits")?)?,
-        };
-        v.finish()?;
-        f.finish()?;
-        if info.selected_major != MAJOR
-            || info.selected_minor != crate::wire::MINOR
-            || info.contract_digest != contract_digest()
-        {
-            return Err(BusError::new(
-                ErrorCode::VersionMismatch,
-                "router speaks a different contract",
-            ));
-        }
-        let shared = Arc::new(Shared::new(
-            info,
-            config.store_root,
-            config.control_lane_capacity.max(1),
-            1,
-            hello_router_serial,
-        ));
-        let conn = Arc::new(ClientConn {
-            shared: shared.clone(),
-        });
-        tokio::spawn(reactor::read_loop(
-            shared.clone(),
-            Arc::downgrade(&conn),
-            rd,
-        ));
-        tokio::spawn(reactor::write_loop(shared, wr));
-        Ok(Client { conn })
-    }
-
-    /// Connects to a router's Unix-domain socket.
-    pub async fn connect_unix(
-        path: impl AsRef<Path>,
-        config: ClientConfig,
-    ) -> Result<Client, BusError> {
-        let t = Transport::unix(path)
-            .await
-            .map_err(|e| BusError::lost(format!("connect: {e}")))?;
-        Client::connect(t, config).await
-    }
-
-    fn shared(&self) -> &Shared {
-        &self.conn.shared
-    }
-
-    pub fn info(&self) -> &SessionInfo {
-        &self.shared().info
-    }
-
-    /// Why the connection closed, once it has.
-    pub fn closed(&self) -> Option<BusError> {
-        self.shared().lock().closed.clone()
-    }
-
-    /// Replies to fire-and-forget releases, consumes and unregisters that came back as
-    /// errors. Nonzero means the client and router disagreed about ownership.
-    pub fn control_errors(&self) -> u64 {
-        self.shared().lock().control_errors
-    }
-
-    /// Flushes queued releases, closes the connection and waits until the reader has stopped.
-    /// Handles that outlive this become inert; the router releases what they owned.
-    pub async fn close(self) {
-        let shared = self.conn.shared.clone();
-        shared.begin_shutdown();
-        let mut done = shared.done.subscribe();
-        drop(self);
-        let _ = done.wait_for(|v| *v).await;
-    }
-
-    // ---- services and RPC
-
-    /// Registers an exclusive service endpoint.
-    pub async fn register(&self, name: &str, config: ServiceConfig) -> Result<Service, BusError> {
-        let mut body = Map::new();
-        body.insert("name".into(), name.into());
-        body.insert("maxQueued".into(), config.max_queued.into());
-        body.insert("maxInFlight".into(), config.max_in_flight.into());
-        let reply = self
-            .shared()
-            .command(
-                "service.register",
-                body,
-                Vec::new(),
-                Vec::new(),
-                Hook::Register,
-            )
-            .await?;
-        match reply.extra {
-            Extra::Service(guard, rx) => Ok(Service {
-                name: name.to_owned(),
-                rx,
-                guard,
-            }),
-            _ => Err(BusError::lost("register reply without a service")),
-        }
-    }
-
-    /// Calls `method` on `service`, pinned to `expected_incarnation` when given. Returns once
-    /// the router has admitted the call; the result arrives through the [`PendingCall`].
-    pub async fn call(
-        &self,
-        service: &str,
-        expected_incarnation: Option<&str>,
-        method: &str,
-        payload: Map<String, Value>,
-        attachments: &[(&str, &Artifact)],
-    ) -> Result<PendingCall, BusError> {
-        let (atts, keep) = attachment_list(attachments);
-        let (tx, rx) = oneshot::channel();
-        let (reply_tx, reply_rx) = oneshot::channel();
-        let shared = self.shared();
-        // The call id, its result slot and its queue position are fixed together, so call ids
-        // reach the router in increasing order.
-        let rejected = {
-            let mut st = shared.lock();
-            if let Some(e) = &st.closed {
-                Some((e.clone(), keep))
-            } else {
-                st.next_call += 1;
-                let call_id = serial_id("call", st.next_call);
-                let mut body = Map::new();
-                body.insert("callId".into(), call_id.clone().into());
-                body.insert("target".into(), service.into());
-                body.insert(
-                    "expectedIncarnation".into(),
-                    expected_incarnation.map_or(Value::Null, Value::from),
-                );
-                body.insert("method".into(), method.into());
-                body.insert("payload".into(), Value::Object(payload));
-                st.calls
-                    .insert(call_id.clone(), CallSlot::Waiting(Some(tx)));
-                st.ordinary.push_back(OutCommand {
-                    op: "rpc.call",
-                    body,
-                    attachments: atts,
-                    respond: Some(reply_tx),
-                    hook: Hook::Call(call_id),
-                    keep,
-                });
-                None
-            }
-        };
-        if let Some((e, keep)) = rejected {
-            drop(keep);
-            return Err(e);
-        }
-        shared.wake();
-        let reply = reply_rx
-            .await
-            .unwrap_or_else(|_| Err(BusError::lost("connection closed")))?;
-        let service_incarnation = field(&reply.value).id("serviceIncarnation")?;
-        match reply.extra {
-            Extra::Call(guard) => Ok(PendingCall {
-                guard,
-                rx,
-                service_incarnation,
-            }),
-            _ => Err(BusError::lost("call reply without a call handle")),
-        }
-    }
-
-    /// Admits a call and waits for its result.
-    pub async fn call_and_wait(
-        &self,
-        service: &str,
-        expected_incarnation: Option<&str>,
-        method: &str,
-        payload: Map<String, Value>,
-        attachments: &[(&str, &Artifact)],
-    ) -> Result<RpcResult, BusError> {
-        let mut pending = self
-            .call(service, expected_incarnation, method, payload, attachments)
-            .await?;
-        pending.result().await
-    }
-
-    // ---- topics
-
-    pub async fn declare_topic(
-        &self,
-        name: &str,
-        retained: Retained,
-    ) -> Result<TopicInfo, BusError> {
-        let mut body = Map::new();
-        body.insert("name".into(), name.into());
-        body.insert(
-            "retained".into(),
-            if retained == Retained::Latest {
-                "latest"
-            } else {
-                "none"
-            }
-            .into(),
-        );
-        let reply = self
-            .shared()
-            .command("topic.declare", body, Vec::new(), Vec::new(), Hook::None)
-            .await?;
-        let mut f = field(&reply.value);
-        Ok(TopicInfo {
-            declared: f.boolean("declared")?,
-            topic_incarnation: f.id("topicIncarnation")?,
-        })
-    }
-
-    /// Releases the retained value. `false` if there was none.
-    pub async fn clear_topic(&self, name: &str) -> Result<bool, BusError> {
-        let mut body = Map::new();
-        body.insert("name".into(), name.into());
-        let reply = self
-            .shared()
-            .command("topic.clear", body, Vec::new(), Vec::new(), Hook::None)
-            .await?;
-        Ok(field(&reply.value).boolean("cleared")?)
-    }
-
-    /// Deletes a topic with no subscribers. `false` if it did not exist.
-    pub async fn delete_topic(&self, name: &str) -> Result<bool, BusError> {
-        let mut body = Map::new();
-        body.insert("name".into(), name.into());
-        let reply = self
-            .shared()
-            .command("topic.delete", body, Vec::new(), Vec::new(), Hook::None)
-            .await?;
-        Ok(field(&reply.value).boolean("deleted")?)
-    }
-
-    pub async fn subscribe(
-        &self,
-        topic: &str,
-        config: SubscriptionConfig,
-    ) -> Result<Subscription, BusError> {
-        let mut body = Map::new();
-        body.insert("topic".into(), topic.into());
-        body.insert(
-            "mode".into(),
-            if config.mode == Mode::Latest {
-                "latest"
-            } else {
-                "bounded"
-            }
-            .into(),
-        );
-        body.insert("maxQueued".into(), config.max_queued.into());
-        body.insert("maxInFlight".into(), config.max_in_flight.into());
-        body.insert("replayLatest".into(), config.replay_latest.into());
-        let reply = self
-            .shared()
-            .command("subscribe", body, Vec::new(), Vec::new(), Hook::Subscribe)
-            .await?;
-        let topic_incarnation = field(&reply.value).id("topicIncarnation")?;
-        match reply.extra {
-            Extra::Subscription(guard, rx) => Ok(Subscription {
-                rx,
-                guard,
-                topic_incarnation,
-            }),
-            _ => Err(BusError::lost("subscribe reply without a subscription")),
-        }
-    }
-
-    /// Publishes. The attachments' owners are held until the router has answered.
-    pub async fn publish(
-        &self,
-        topic: &str,
-        payload: Map<String, Value>,
-        attachments: &[(&str, &Artifact)],
-    ) -> Result<PublishReceipt, BusError> {
-        let (atts, keep) = attachment_list(attachments);
-        let mut body = Map::new();
-        body.insert("topic".into(), topic.into());
-        body.insert("payload".into(), Value::Object(payload));
-        let reply = self
-            .shared()
-            .command("publish", body, atts, keep, Hook::None)
-            .await?;
-        let mut f = field(&reply.value);
-        Ok(PublishReceipt {
-            topic_sequence: f.u64_string("topicSequence")?,
-            subscribers: f.u64_string("subscribers")?,
-            replaced: f.u64_string("replaced")?,
-        })
-    }
-
-    // ---- artifacts
-
-    pub fn artifacts(&self) -> Artifacts<'_> {
-        Artifacts { client: self }
-    }
-}
-
-/// The artifact half of the client API.
-pub struct Artifacts<'a> {
-    client: &'a Client,
-}
-
-impl Artifacts<'_> {
-    /// Reserves `byte_length` bytes of private staging storage and opens it for writing.
-    pub async fn allocate(
-        &self,
-        byte_length: u64,
-        content_type: &str,
-    ) -> Result<ArtifactWriter, BusError> {
-        if !is_content_type(content_type) {
-            return Err(BusError::invalid(
-                "contentType must be 1..=127 printable ASCII characters",
-            ));
-        }
-        let shared = self.client.shared();
-        let mut body = Map::new();
-        body.insert("byteLength".into(), byte_length.to_string().into());
-        body.insert("contentType".into(), content_type.into());
-        let reply = shared
-            .command(
-                "artifact.allocate",
-                body,
-                Vec::new(),
-                Vec::new(),
-                Hook::Owner,
-            )
-            .await?;
-        let Extra::Owner(owner) = reply.extra else {
-            return Err(BusError::lost("allocate reply without an owner"));
-        };
-        let mut f = field(&reply.value);
-        let artifact_id = f.id("artifactId")?;
-        if parse_serial_id("a", &artifact_id).is_none() {
-            return Err(BusError::lost("router issued a malformed artifact id"));
-        }
-        let loc = Location::from_json(f.value("writeLocation")?)?;
-        let path = resolve(&shared.store_root, &loc.store_id, &loc)?;
-        let file = open_write(&path)
-            .map_err(|e| BusError::new(ErrorCode::StoreFailure, format!("staging: {e}")))?;
-        Ok(ArtifactWriter {
-            file: Some(file),
-            owner,
-            artifact_id,
-            byte_length,
-            written: 0,
-        })
-    }
-}

services/flysim/crates/flybus/src/client/reactor.rs

@@ -1,992 +0,0 @@
-//! The client's connection reactor: one reader task, one writer task, and the shared state
-//! they and every handle use.
-//!
-//! Lanes: the writer sends queued control items (consumes, releases, cancels) before ordinary
-//! commands, so dropping handles is never stuck behind a burst of publishes. Command ids are
-//! assigned when a command is written, which keeps them strictly increasing on the wire
-//! whatever order the lanes interleave in.
-//!
-//! Locking rule: nothing that can own a guard is dropped while the state mutex is held, because
-//! guard drops lock it. Values are taken out under the lock and dropped after it is released.
-
-use std::collections::{HashMap, VecDeque};
-use std::path::PathBuf;
-use std::sync::{Arc, Mutex, MutexGuard, Weak};
-use std::time::Duration;
-
-use serde_json::{Map, Value};
-use tokio::io::{AsyncWriteExt, ReadHalf, WriteHalf};
-use tokio::sync::{Notify, mpsc, oneshot, watch};
-
-use super::SessionInfo;
-use super::handles::{
-    CallGuard, Message, OwnerGuard, ReplyGuard, Request, RpcResult, ServiceGuard, SubscriptionGuard,
-};
-use crate::error::{BusError, Dispatch, ErrorCode};
-use crate::transport::Transport;
-use crate::wire::{
-    ArtifactRef, Attachment, Envelope, Fields, GENERATION, Identity, Kind, MAJOR, MAX_BATCH, MINOR,
-    WireError, parse_serial_id, parse_u64, read_frame, serial_id, write_frame,
-};
-
-pub(crate) type Responder = oneshot::Sender<Result<Reply, BusError>>;
-
-/// A successful reply, plus whatever handle the reactor built from it.
-pub(crate) struct Reply {
-    pub value: Map<String, Value>,
-    pub extra: Extra,
-}
-
-pub(crate) enum Extra {
-    None,
-    Owner(Arc<OwnerGuard>),
-    Service(ServiceGuard, mpsc::UnboundedReceiver<Request>),
-    Subscription(SubscriptionGuard, mpsc::UnboundedReceiver<Message>),
-    Call(CallGuard),
-}
-
-/// What the reactor does with a reply before handing it over. Handles are built here, inside
-/// the reactor, so a caller that abandoned its future cannot leak an owner it never saw: the
-/// handle drops with the undelivered reply and releases itself.
-pub(crate) enum Hook {
-    None,
-    /// `value.ownerId` is a new explicit hold.
-    Owner,
-    Register,
-    Subscribe,
-    Call(String),
-    Cancel(String),
-}
-
-pub(crate) struct OutCommand {
-    pub op: &'static str,
-    pub body: Map<String, Value>,
-    pub attachments: Vec<Attachment>,
-    pub respond: Option<Responder>,
-    pub hook: Hook,
-    /// Source owners held until the router has answered (bus-v1 section 8.2).
-    pub keep: Vec<Arc<OwnerGuard>>,
-}
-
-pub(crate) enum Control {
-    Consumed(String),
-    Release(String),
-    Cancel(String, Option<Responder>),
-    Unregister {
-        name: String,
-        service_incarnation: String,
-    },
-    ResponderReleased {
-        call_id: String,
-        request_delivery_id: String,
-    },
-}
-
-pub(crate) enum CallSlot {
-    Waiting(Option<oneshot::Sender<Result<RpcResult, BusError>>>),
-    Abandoned,
-}
-
-struct Pending {
-    op: &'static str,
-    respond: Option<Responder>,
-    hook: Hook,
-    _keep: Vec<Arc<OwnerGuard>>,
-}
-
-pub(crate) struct ClientState {
-    pub closed: Option<BusError>,
-    pub shutting_down: bool,
-    pub control: VecDeque<Control>,
-    pub ordinary: VecDeque<OutCommand>,
-    next_msg: u64,
-    last_router: u64,
-    last_delivery: u64,
-    pending: HashMap<u64, Pending>,
-    pub services: HashMap<String, mpsc::UnboundedSender<Request>>,
-    pub subscriptions: HashMap<String, mpsc::UnboundedSender<Message>>,
-    pub calls: HashMap<String, CallSlot>,
-    pub next_call: u64,
-    pub control_errors: u64,
-}
-
-pub(crate) struct Shared {
-    pub info: SessionInfo,
-    pub store_root: PathBuf,
-    state: Mutex<ClientState>,
-    wake: Notify,
-    control_capacity: usize,
-    pub done: watch::Sender<bool>,
-    shutdown: watch::Sender<bool>,
-}
-
-/// The connection's lifetime token. Every public handle holds one; the connection closes when
-/// the last is dropped (or on [`crate::Client::close`]).
-pub(crate) struct ClientConn {
-    pub shared: Arc<Shared>,
-}
-
-impl Drop for ClientConn {
-    fn drop(&mut self) {
-        self.shared.begin_shutdown();
-    }
-}
-
-impl Shared {
-    pub(crate) fn new(
-        info: SessionInfo,
-        store_root: PathBuf,
-        control_capacity: usize,
-        next_msg: u64,
-        last_router: u64,
-    ) -> Shared {
-        Shared {
-            info,
-            store_root,
-            state: Mutex::new(ClientState {
-                closed: None,
-                shutting_down: false,
-                control: VecDeque::new(),
-                ordinary: VecDeque::new(),
-                next_msg,
-                last_router,
-                last_delivery: 0,
-                pending: HashMap::new(),
-                services: HashMap::new(),
-                subscriptions: HashMap::new(),
-                calls: HashMap::new(),
-                next_call: 0,
-                control_errors: 0,
-            }),
-            wake: Notify::new(),
-            control_capacity,
-            done: watch::Sender::new(false),
-            shutdown: watch::Sender::new(false),
-        }
-    }
-
-    pub(crate) fn lock(&self) -> MutexGuard<'_, ClientState> {
-        self.state.lock().unwrap_or_else(|e| e.into_inner())
-    }
-
-    pub(crate) fn wake(&self) {
-        self.wake.notify_one();
-    }
-
-    pub(crate) fn begin_shutdown(&self) {
-        self.lock().shutting_down = true;
-        self.wake.notify_one();
-    }
-
-    /// Queues a control item. A full control lane closes the connection rather than lose a
-    /// release (bus-v1 section 8.3).
-    pub(crate) fn push_control(&self, item: Control) {
-        let overflow = {
-            let mut st = self.lock();
-            if st.closed.is_some() {
-                Some(item)
-            } else if st.control.len() >= self.control_capacity {
-                st.closed = Some(BusError::lost("client control lane exhausted"));
-                Some(item)
-            } else {
-                st.control.push_back(item);
-                None
-            }
-        };
-        self.wake.notify_one();
-        drop(overflow);
-    }
-
-    /// Queues an ordinary command, or hands it back with the reason it cannot be sent.
-    pub(crate) fn enqueue(&self, cmd: OutCommand) -> Result<(), BusError> {
-        let rejected = {
-            let mut st = self.lock();
-            match &st.closed {
-                Some(e) => Some((e.clone().with_dispatch(Dispatch::NotDispatched), cmd)),
-                None => {
-                    st.ordinary.push_back(cmd);
-                    None
-                }
-            }
-        };
-        self.wake.notify_one();
-        match rejected {
-            Some((e, cmd)) => {
-                drop(cmd);
-                Err(e)
-            }
-            None => Ok(()),
-        }
-    }
-
-    /// Queues a command and waits for its reply.
-    pub(crate) async fn command(
-        &self,
-        op: &'static str,
-        body: Map<String, Value>,
-        attachments: Vec<Attachment>,
-        keep: Vec<Arc<OwnerGuard>>,
-        hook: Hook,
-    ) -> Result<Reply, BusError> {
-        let (tx, rx) = oneshot::channel();
-        self.enqueue(OutCommand {
-            op,
-            body,
-            attachments,
-            respond: Some(tx),
-            hook,
-            keep,
-        })?;
-        rx.await
-            .unwrap_or_else(|_| Err(BusError::lost("connection closed")))
-    }
-
-    /// Fails everything outstanding. Values are dropped after the lock is released.
-    fn fail_all(&self, reason: BusError) {
-        let (pending, calls, services, subscriptions, control, ordinary, reason) = {
-            let mut st = self.lock();
-            let reason = st.closed.get_or_insert(reason).clone();
-            (
-                std::mem::take(&mut st.pending),
-                std::mem::take(&mut st.calls),
-                std::mem::take(&mut st.services),
-                std::mem::take(&mut st.subscriptions),
-                std::mem::take(&mut st.control),
-                std::mem::take(&mut st.ordinary),
-                reason,
-            )
-        };
-        for (_, p) in pending {
-            if let Some(tx) = p.respond {
-                let _ = tx.send(Err(reason.clone().with_dispatch(Dispatch::Unknown)));
-            }
-        }
-        for (_, slot) in calls {
-            if let CallSlot::Waiting(Some(tx)) = slot {
-                let _ = tx.send(Err(reason.clone().with_dispatch(Dispatch::Unknown)));
-            }
-        }
-        for cmd in ordinary {
-            if let Some(tx) = cmd.respond {
-                let _ = tx.send(Err(reason.clone().with_dispatch(Dispatch::NotDispatched)));
-            }
-        }
-        for item in control {
-            if let Control::Cancel(_, Some(tx)) = item {
-                let _ = tx.send(Err(reason.clone().with_dispatch(Dispatch::NotDispatched)));
-            }
-        }
-        drop((services, subscriptions));
-        self.done.send_replace(true);
-    }
-
-    fn terminate(&self, reason: BusError) {
-        self.fail_all(reason);
-        self.shutdown.send_replace(true);
-        self.wake.notify_waiters();
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Writer
-
-enum Next {
-    Send(Vec<u8>),
-    Failed(OutCommand, BusError),
-    Idle,
-    Exit,
-}
-
-fn take_batch(control: &mut VecDeque<Control>) -> Option<OutCommand> {
-    let first = control.pop_front()?;
-    let (op, key, mut ids) = match first {
-        Control::Cancel(call_id, respond) => {
-            let mut body = Map::new();
-            body.insert("callId".into(), call_id.clone().into());
-            let hook = Hook::Cancel(call_id);
-            return Some(OutCommand {
-                op: "rpc.cancel",
-                body,
-                attachments: Vec::new(),
-                respond,
-                hook,
-                keep: Vec::new(),
-            });
-        }
-        Control::ResponderReleased {
-            call_id,
-            request_delivery_id,
-        } => {
-            let mut body = Map::new();
-            body.insert("callId".into(), call_id.into());
-            body.insert("requestDeliveryId".into(), request_delivery_id.into());
-            return Some(OutCommand {
-                op: "rpc.responder.release",
-                body,
-                attachments: Vec::new(),
-                respond: None,
-                hook: Hook::None,
-                keep: Vec::new(),
-            });
-        }
-        Control::Unregister {
-            name,
-            service_incarnation,
-        } => {
-            let mut body = Map::new();
-            body.insert("name".into(), name.into());
-            body.insert("serviceIncarnation".into(), service_incarnation.into());
-            return Some(OutCommand {
-                op: "service.unregister",
-                body,
-                attachments: Vec::new(),
-                respond: None,
-                hook: Hook::None,
-                keep: Vec::new(),
-            });
-        }
-        Control::Consumed(id) => ("delivery.consumed", "deliveryIds", vec![id]),
-        Control::Release(id) => ("artifact.release", "ownerIds", vec![id]),
-    };
-    while ids.len() < MAX_BATCH {
-        match (control.front(), op) {
-            (Some(Control::Consumed(_)), "delivery.consumed")
-            | (Some(Control::Release(_)), "artifact.release") => match control.pop_front() {
-                Some(Control::Consumed(id) | Control::Release(id)) => ids.push(id),
-                _ => unreachable!("front was checked"),
-            },
-            _ => break,
-        }
-    }
-    let mut body = Map::new();
-    body.insert(
-        key.into(),
-        Value::Array(ids.into_iter().map(Value::String).collect()),
-    );
-    Some(OutCommand {
-        op,
-        body,
-        attachments: Vec::new(),
-        respond: None,
-        hook: Hook::None,
-        keep: Vec::new(),
-    })
-}
-
-fn next_outgoing(shared: &Shared) -> Next {
-    let mut st = shared.lock();
-    if st.closed.is_some() {
-        return Next::Exit;
-    }
-    let cmd = match take_batch(&mut st.control).or_else(|| st.ordinary.pop_front()) {
-        Some(cmd) => cmd,
-        None if st.shutting_down => {
-            st.closed = Some(BusError::lost("client closed"));
-            return Next::Exit;
-        }
-        None => return Next::Idle,
-    };
-    st.next_msg += 1;
-    let n = st.next_msg;
-    let mut env = Envelope::new(serial_id("msg", n), Kind::Command, cmd.op, cmd.body.clone());
-    env.attachments = cmd.attachments.clone();
-    match env.encode() {
-        Ok(bytes) => {
-            st.pending.insert(
-                n,
-                Pending {
-                    op: cmd.op,
-                    respond: cmd.respond,
-                    hook: cmd.hook,
-                    _keep: cmd.keep,
-                },
-            );
-            Next::Send(bytes)
-        }
-        Err(e) => Next::Failed(cmd, e.into()),
-    }
-}
-
-pub(crate) async fn write_loop(shared: Arc<Shared>, mut wr: WriteHalf<Transport>) {
-    let mut shutdown = shared.shutdown.subscribe();
-    loop {
-        match next_outgoing(&shared) {
-            Next::Send(bytes) => {
-                let result = tokio::select! {
-                    result = write_frame(&mut wr, &bytes) => result,
-                    _ = shutdown.wait_for(|v| *v) => break,
-                };
-                if result.is_err() {
-                    shared.terminate(BusError::lost("write to router failed"));
-                    break;
-                }
-            }
-            Next::Failed(cmd, e) => {
-                let slot = match &cmd.hook {
-                    Hook::Call(call_id) => shared.lock().calls.remove(call_id),
-                    _ => None,
-                };
-                drop(slot);
-                if let Some(tx) = cmd.respond {
-                    let _ = tx.send(Err(e));
-                }
-            }
-            Next::Idle => {
-                tokio::select! {
-                    _ = shared.wake.notified() => {}
-                    _ = shutdown.wait_for(|v| *v) => break,
-                }
-            }
-            Next::Exit => break,
-        }
-    }
-    tokio::select! {
-        _ = wr.shutdown() => {}
-        _ = shutdown.wait_for(|v| *v) => {}
-        _ = tokio::time::sleep(Duration::from_secs(1)) => {}
-    }
-    let reason = shared
-        .lock()
-        .closed
-        .clone()
-        .unwrap_or_else(|| BusError::lost("client writer stopped"));
-    shared.terminate(reason);
-}
-
-// ---------------------------------------------------------------------------------------------
-// Reader
-
-pub(crate) async fn read_loop(
-    shared: Arc<Shared>,
-    conn: Weak<ClientConn>,
-    mut rd: ReadHalf<Transport>,
-) {
-    let mut shutdown = shared.shutdown.subscribe();
-    let reason = loop {
-        let frame = tokio::select! {
-            frame = read_frame(&mut rd) => frame,
-            _ = shutdown.wait_for(|v| *v) => return,
-        };
-        let bytes = match frame {
-            Ok(Some(b)) => b,
-            Ok(None) => break BusError::lost("router closed the connection"),
-            Err(e) => break BusError::lost(format!("router connection failed: {e}")),
-        };
-        let env = match Envelope::decode(&bytes) {
-            Ok(env) => env,
-            Err(e) => break BusError::lost(format!("router sent an invalid envelope: {e}")),
-        };
-        if let Err(e) = on_envelope(&shared, &conn, env) {
-            break BusError::lost(format!("router protocol violation: {e}"));
-        }
-    };
-    shared.terminate(reason);
-}
-
-fn on_envelope(
-    shared: &Arc<Shared>,
-    conn: &Weak<ClientConn>,
-    env: Envelope,
-) -> Result<(), WireError> {
-    if env.major != MAJOR || env.minor != MINOR {
-        return Err(WireError(format!(
-            "router envelope version is not {MAJOR}.{MINOR}"
-        )));
-    }
-    let router_serial = parse_serial_id("bus", &env.id)
-        .filter(|n| *n > 0)
-        .ok_or_else(|| WireError("router envelope id is not canonical bus-<U64>".into()))?;
-    {
-        let mut st = shared.lock();
-        if router_serial <= st.last_router {
-            return Err(WireError(
-                "router envelope ids must strictly increase".into(),
-            ));
-        }
-        st.last_router = router_serial;
-    }
-    match env.kind {
-        Kind::Reply => {
-            if !env.attachments.is_empty() {
-                return Err(WireError("router replies cannot carry attachments".into()));
-            }
-            let n = env
-                .reply_to
-                .as_deref()
-                .and_then(|r| parse_serial_id("msg", r));
-            let n = n.ok_or_else(|| WireError("reply without a command id".into()))?;
-            let pending = {
-                let mut st = shared.lock();
-                let Some(pending) = st.pending.get(&n) else {
-                    return Err(WireError(format!("reply to unknown command msg-{n}")));
-                };
-                if env.op != pending.op {
-                    return Err(WireError(format!(
-                        "reply operation {:?} does not match {:?}",
-                        env.op, pending.op
-                    )));
-                }
-                st.pending.remove(&n)
-            };
-            let pending =
-                pending.ok_or_else(|| WireError(format!("reply to unknown command msg-{n}")))?;
-            let result = parse_reply(&env.body)?;
-            if let Ok(value) = &result {
-                validate_reply_value(pending.op, value)?;
-            }
-            complete(shared, conn, pending, result)
-        }
-        Kind::Delivery => {
-            if env.reply_to.is_some() {
-                return Err(WireError("deliveries must have null replyTo".into()));
-            }
-            on_delivery(shared, conn, env)
-        }
-        Kind::Notice => {
-            if env.reply_to.is_some() || !env.attachments.is_empty() {
-                return Err(WireError(
-                    "notices must have null replyTo and no attachments".into(),
-                ));
-            }
-            on_notice(shared, env)
-        }
-        Kind::Command => Err(WireError("routers do not send commands".into())),
-    }
-}
-
-fn parse_reply(
-    body: &Map<String, Value>,
-) -> Result<Result<Map<String, Value>, BusError>, WireError> {
-    let mut f = Fields::of(body, "reply");
-    if f.boolean("ok")? {
-        let value = f.object("value")?.clone();
-        f.finish()?;
-        return Ok(Ok(value));
-    }
-    let e = parse_error(f.object("error")?)?;
-    f.finish()?;
-    Ok(Err(e))
-}
-
-fn parse_error(m: &Map<String, Value>) -> Result<BusError, WireError> {
-    let mut g = Fields::of(m, "error");
-    let code = ErrorCode::parse(g.string("code")?)
-        .ok_or_else(|| WireError("unknown error code".into()))?;
-    let message = g.string("message")?.to_owned();
-    let dispatch = Dispatch::parse(g.string("dispatch")?)
-        .ok_or_else(|| WireError("unknown dispatch".into()))?;
-    g.finish()?;
-    Ok(BusError {
-        code,
-        message,
-        dispatch,
-    })
-}
-
-fn serial_field(f: &mut Fields<'_>, key: &'static str, prefix: &str) -> Result<String, WireError> {
-    let id = f.id(key)?;
-    parse_serial_id(prefix, &id)
-        .ok_or_else(|| WireError(format!("{key} is not canonical {prefix}-<U64>")))?;
-    Ok(id)
-}
-
-fn validate_reply_value(op: &str, value: &Map<String, Value>) -> Result<(), WireError> {
-    let mut f = Fields::of(value, "reply value");
-    match op {
-        "service.register" => {
-            serial_field(&mut f, "serviceIncarnation", "svc")?;
-        }
-        "service.unregister" => {
-            f.boolean("removed")?;
-        }
-        "rpc.call" => {
-            if !f.boolean("accepted")? {
-                return Err(WireError(
-                    "an admitted rpc.call must say accepted:true".into(),
-                ));
-            }
-            serial_field(&mut f, "serviceIncarnation", "svc")?;
-        }
-        "rpc.reply" => {
-            f.boolean("routed")?;
-        }
-        "rpc.responder.release" => {
-            f.boolean("released")?;
-        }
-        "rpc.cancel" => match f.string("state")? {
-            "cancelled-before-dispatch" | "execution-unknown" | "completed" | "call-gone" => {}
-            _ => return Err(WireError("unknown rpc.cancel state".into())),
-        },
-        "topic.declare" => {
-            f.boolean("declared")?;
-            serial_field(&mut f, "topicIncarnation", "top")?;
-        }
-        "topic.clear" => {
-            f.boolean("cleared")?;
-        }
-        "topic.delete" => {
-            f.boolean("deleted")?;
-        }
-        "subscribe" => {
-            serial_field(&mut f, "subscriptionId", "sub")?;
-            serial_field(&mut f, "topicIncarnation", "top")?;
-        }
-        "unsubscribe" => {
-            f.boolean("removed")?;
-        }
-        "publish" => {
-            f.u64_string("topicSequence")?;
-            f.u64_string("subscribers")?;
-            f.u64_string("replaced")?;
-        }
-        "delivery.consumed" | "artifact.release" => {
-            f.u64_string("released")?;
-        }
-        "artifact.allocate" => {
-            serial_field(&mut f, "artifactId", "a")?;
-            if f.u64_string("generation")? != GENERATION {
-                return Err(WireError("unsupported artifact generation".into()));
-            }
-            serial_field(&mut f, "ownerId", "own")?;
-            crate::wire::Location::from_json(f.value("writeLocation")?)?;
-        }
-        "artifact.seal" => {
-            ArtifactRef::from_json(f.value("ref")?)?;
-            serial_field(&mut f, "ownerId", "own")?;
-        }
-        "artifact.open" => {
-            crate::wire::Location::from_json(f.value("readLocation")?)?;
-        }
-        "artifact.retain" => {
-            serial_field(&mut f, "ownerId", "own")?;
-        }
-        _ => return Err(WireError(format!("reply for unknown operation {op:?}"))),
-    }
-    f.finish()
-}
-
-fn owner_guard(conn: &Weak<ClientConn>, id: String, delivery: bool) -> Option<Arc<OwnerGuard>> {
-    Some(Arc::new(OwnerGuard {
-        id,
-        delivery,
-        conn: conn.upgrade()?,
-    }))
-}
-
-fn complete(
-    shared: &Arc<Shared>,
-    conn: &Weak<ClientConn>,
-    pending: Pending,
-    result: Result<Map<String, Value>, BusError>,
-) -> Result<(), WireError> {
-    let Pending {
-        respond,
-        hook,
-        _keep,
-        ..
-    } = pending;
-    let reply = match (hook, result) {
-        (Hook::Call(call_id), Err(e)) => {
-            let slot = shared.lock().calls.remove(&call_id);
-            drop(slot);
-            Err(e)
-        }
-        (_, Err(e)) => Err(e),
-        (Hook::None, Ok(value)) => Ok(Reply {
-            value,
-            extra: Extra::None,
-        }),
-        (Hook::Owner, Ok(value)) => {
-            let id = Fields::of(&value, "reply").id("ownerId")?;
-            match owner_guard(conn, id, false) {
-                Some(g) => Ok(Reply {
-                    value,
-                    extra: Extra::Owner(g),
-                }),
-                None => Err(BusError::lost("client closed")),
-            }
-        }
-        (Hook::Register, Ok(value)) => {
-            let inc = Fields::of(&value, "reply").id("serviceIncarnation")?;
-            match conn.upgrade() {
-                Some(conn) => {
-                    let (tx, rx) = mpsc::unbounded_channel();
-                    shared.lock().services.insert(inc.clone(), tx);
-                    let guard = ServiceGuard {
-                        conn,
-                        incarnation: inc,
-                    };
-                    Ok(Reply {
-                        value,
-                        extra: Extra::Service(guard, rx),
-                    })
-                }
-                None => Err(BusError::lost("client closed")),
-            }
-        }
-        (Hook::Subscribe, Ok(value)) => {
-            let id = Fields::of(&value, "reply").id("subscriptionId")?;
-            match conn.upgrade() {
-                Some(conn) => {
-                    let (tx, rx) = mpsc::unbounded_channel();
-                    shared.lock().subscriptions.insert(id.clone(), tx);
-                    let guard = SubscriptionGuard { conn, id };
-                    Ok(Reply {
-                        value,
-                        extra: Extra::Subscription(guard, rx),
-                    })
-                }
-                None => Err(BusError::lost("client closed")),
-            }
-        }
-        (Hook::Call(call_id), Ok(value)) => match conn.upgrade() {
-            Some(conn) => Ok(Reply {
-                value,
-                extra: Extra::Call(CallGuard {
-                    conn,
-                    call_id,
-                    done: false,
-                }),
-            }),
-            None => Err(BusError::lost("client closed")),
-        },
-        (Hook::Cancel(call_id), Ok(value)) => {
-            let state = Fields::of(&value, "reply").string("state")?.to_owned();
-            if state != "completed" {
-                // No result will follow: resolve whoever still waits for one.
-                let slot = shared.lock().calls.remove(&call_id);
-                if let Some(CallSlot::Waiting(Some(tx))) = slot {
-                    let dispatch = if state == "cancelled-before-dispatch" {
-                        Dispatch::NotDispatched
-                    } else {
-                        Dispatch::Unknown
-                    };
-                    let e = BusError::new(ErrorCode::CallGone, format!("cancelled: {state}"))
-                        .with_dispatch(dispatch);
-                    let _ = tx.send(Err(e));
-                }
-            }
-            Ok(Reply {
-                value,
-                extra: Extra::None,
-            })
-        }
-    };
-    match respond {
-        Some(tx) => {
-            // If the caller is gone the reply, and any handle in it, drops here and releases.
-            let _ = tx.send(reply);
-        }
-        None => {
-            if reply.is_err() {
-                shared.lock().control_errors += 1;
-            }
-        }
-    }
-    Ok(())
-}
-
-fn attachments(env: &Envelope, delivery_id: &str) -> Result<Vec<(String, ArtifactRef)>, WireError> {
-    env.attachments
-        .iter()
-        .map(|a| {
-            if a.owner_id != delivery_id {
-                return Err(WireError(
-                    "delivery attachment owner is not the delivery".into(),
-                ));
-            }
-            Ok((a.name.clone(), a.reference.clone()))
-        })
-        .collect()
-}
-
-fn u64_field(f: &mut Fields<'_>, key: &'static str) -> Result<u64, WireError> {
-    let s = f.string(key)?;
-    parse_u64(s).ok_or_else(|| WireError(format!("{key} is not a U64")))
-}
-
-fn on_delivery(
-    shared: &Arc<Shared>,
-    conn: &Weak<ClientConn>,
-    env: Envelope,
-) -> Result<(), WireError> {
-    let mut f = Fields::of(&env.body, "delivery");
-    let delivery_id = f.id("deliveryId")?;
-    let delivery_serial = parse_serial_id("dlv", &delivery_id)
-        .filter(|n| *n > 0)
-        .ok_or_else(|| WireError("delivery id is not canonical dlv-<U64>".into()))?;
-    let atts = attachments(&env, &delivery_id)?;
-    // Without a live connection handle there is nobody to hand this to.
-    let Some(guard) = owner_guard(conn, delivery_id.clone(), true) else {
-        return Ok(());
-    };
-    match env.op.as_str() {
-        "rpc.request" => {
-            let call_id = f.id("callId")?;
-            if parse_serial_id("call", &call_id).is_none() {
-                return Err(WireError("rpc.request callId is not call-<U64>".into()));
-            }
-            let caller = Identity::from_json(f.value("caller")?)?;
-            let target = f.name("target")?;
-            let service_incarnation = f.id("serviceIncarnation")?;
-            if parse_serial_id("svc", &service_incarnation).is_none() {
-                return Err(WireError("service incarnation is not svc-<U64>".into()));
-            }
-            let method = f.method("method")?;
-            let payload = f.object("payload")?.clone();
-            f.finish()?;
-            accept_delivery_serial(shared, delivery_serial)?;
-            let req = Request {
-                reply_guard: Arc::new(ReplyGuard {
-                    conn: guard.conn.clone(),
-                    call_id: call_id.clone(),
-                    request_delivery_id: delivery_id.clone(),
-                }),
-                guard,
-                call_id,
-                caller,
-                target,
-                service_incarnation,
-                method,
-                payload,
-                attachments: atts,
-            };
-            let tx = shared
-                .lock()
-                .services
-                .get(&req.service_incarnation)
-                .cloned();
-            if let Some(tx) = tx {
-                let _ = tx.send(req);
-            }
-        }
-        "rpc.result" => {
-            let call_id = f.id("callId")?;
-            if parse_serial_id("call", &call_id).is_none() {
-                return Err(WireError("rpc.result callId is not call-<U64>".into()));
-            }
-            let responder = Identity::from_json(f.value("responder")?)?;
-            let service_incarnation = f.id("serviceIncarnation")?;
-            if parse_serial_id("svc", &service_incarnation).is_none() {
-                return Err(WireError("service incarnation is not svc-<U64>".into()));
-            }
-            let outcome = f.object("outcome")?.clone();
-            f.finish()?;
-            accept_delivery_serial(shared, delivery_serial)?;
-            let res = RpcResult {
-                guard,
-                call_id,
-                responder,
-                service_incarnation,
-                outcome,
-                attachments: atts,
-            };
-            let slot = shared.lock().calls.remove(&res.call_id);
-            match slot {
-                Some(CallSlot::Waiting(Some(tx))) => {
-                    let _ = tx.send(Ok(res));
-                }
-                // Abandoned or unknown: dropping it consumes the delivery.
-                other => drop((other, res)),
-            }
-        }
-        "topic.message" => {
-            let subscription_id = f.id("subscriptionId")?;
-            if parse_serial_id("sub", &subscription_id).is_none() {
-                return Err(WireError("subscription id is not sub-<U64>".into()));
-            }
-            let topic = f.name("topic")?;
-            let topic_incarnation = f.id("topicIncarnation")?;
-            if parse_serial_id("top", &topic_incarnation).is_none() {
-                return Err(WireError("topic incarnation is not top-<U64>".into()));
-            }
-            let topic_sequence = u64_field(&mut f, "topicSequence")?;
-            let replaced = u64_field(&mut f, "replaced")?;
-            let payload = f.object("payload")?.clone();
-            f.finish()?;
-            accept_delivery_serial(shared, delivery_serial)?;
-            let msg = Message {
-                guard,
-                subscription_id,
-                topic,
-                topic_incarnation,
-                topic_sequence,
-                replaced,
-                payload,
-                attachments: atts,
-            };
-            let tx = shared
-                .lock()
-                .subscriptions
-                .get(&msg.subscription_id)
-                .cloned();
-            if let Some(tx) = tx {
-                let _ = tx.send(msg);
-            }
-        }
-        other => return Err(WireError(format!("unknown delivery {other:?}"))),
-    }
-    Ok(())
-}
-
-fn accept_delivery_serial(shared: &Shared, serial: u64) -> Result<(), WireError> {
-    let mut st = shared.lock();
-    if serial <= st.last_delivery {
-        return Err(WireError("delivery ids must strictly increase".into()));
-    }
-    st.last_delivery = serial;
-    Ok(())
-}
-
-fn on_notice(shared: &Arc<Shared>, env: Envelope) -> Result<(), WireError> {
-    let mut f = Fields::of(&env.body, "notice");
-    match env.op.as_str() {
-        "call.failed" => {
-            let call_id = f.id("callId")?;
-            if parse_serial_id("call", &call_id).is_none() {
-                return Err(WireError("call.failed callId is not call-<U64>".into()));
-            }
-            let code = ErrorCode::parse(f.string("code")?)
-                .ok_or_else(|| WireError("unknown error code".into()))?;
-            let message = f.string("message")?.to_owned();
-            let dispatch = Dispatch::parse(f.string("dispatch")?)
-                .ok_or_else(|| WireError("unknown dispatch".into()))?;
-            f.finish()?;
-            let slot = shared.lock().calls.remove(&call_id);
-            if let Some(CallSlot::Waiting(Some(tx))) = slot {
-                let _ = tx.send(Err(BusError {
-                    code,
-                    message,
-                    dispatch,
-                }));
-            }
-        }
-        "route.removed" => {
-            f.name("name")?;
-            serial_field(&mut f, "serviceIncarnation", "svc")?;
-            f.string("reason")?;
-            f.finish()?;
-        }
-        "subscription.closed" => {
-            let id = serial_field(&mut f, "subscriptionId", "sub")?;
-            f.name("topic")?;
-            serial_field(&mut f, "topicIncarnation", "top")?;
-            f.string("reason")?;
-            f.finish()?;
-            let tx = shared.lock().subscriptions.remove(&id);
-            drop(tx);
-        }
-        "connection.closing" => {
-            let code = ErrorCode::parse(f.string("code")?)
-                .ok_or_else(|| WireError("unknown error code".into()))?;
-            let message = f.string("message")?.to_owned();
-            f.finish()?;
-            let mut st = shared.lock();
-            if st.closed.is_none() {
-                st.closed = Some(BusError::new(code, message).with_dispatch(Dispatch::Unknown));
-            }
-        }
-        other => return Err(WireError(format!("unknown notice {other:?}"))),
-    }
-    Ok(())
-}

services/flysim/crates/flybus/src/error.rs

@@ -1,154 +0,0 @@
-//! Transport error codes and the error value every fallible call returns.
-
-use std::fmt;
-
-/// Transport error codes (bus-v1 section 9, plus the three this crate adds; see the README).
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
-pub enum ErrorCode {
-    InvalidEnvelope,
-    VersionMismatch,
-    NotAuthorized,
-    NoService,
-    TargetChanged,
-    Backpressure,
-    CallGone,
-    ArtifactUnsealed,
-    ArtifactGone,
-    OwnerInvalid,
-    QuotaExceeded,
-    StoreFailure,
-    RouterLost,
-    /// Addition: a name is already registered, a redeclaration disagrees, or a topic still has
-    /// subscribers.
-    Conflict,
-    /// Addition: publish or subscribe named a topic nobody declared.
-    NoTopic,
-    /// Addition: a seal found the wrong length or digest, or a reference disagrees with the
-    /// artifact it names.
-    ArtifactMismatch,
-}
-
-impl ErrorCode {
-    pub const ALL: [ErrorCode; 16] = [
-        ErrorCode::InvalidEnvelope,
-        ErrorCode::VersionMismatch,
-        ErrorCode::NotAuthorized,
-        ErrorCode::NoService,
-        ErrorCode::TargetChanged,
-        ErrorCode::Backpressure,
-        ErrorCode::CallGone,
-        ErrorCode::ArtifactUnsealed,
-        ErrorCode::ArtifactGone,
-        ErrorCode::OwnerInvalid,
-        ErrorCode::QuotaExceeded,
-        ErrorCode::StoreFailure,
-        ErrorCode::RouterLost,
-        ErrorCode::Conflict,
-        ErrorCode::NoTopic,
-        ErrorCode::ArtifactMismatch,
-    ];
-
-    pub fn as_str(self) -> &'static str {
-        match self {
-            ErrorCode::InvalidEnvelope => "INVALID_ENVELOPE",
-            ErrorCode::VersionMismatch => "VERSION_MISMATCH",
-            ErrorCode::NotAuthorized => "NOT_AUTHORIZED",
-            ErrorCode::NoService => "NO_SERVICE",
-            ErrorCode::TargetChanged => "TARGET_CHANGED",
-            ErrorCode::Backpressure => "BACKPRESSURE",
-            ErrorCode::CallGone => "CALL_GONE",
-            ErrorCode::ArtifactUnsealed => "ARTIFACT_UNSEALED",
-            ErrorCode::ArtifactGone => "ARTIFACT_GONE",
-            ErrorCode::OwnerInvalid => "OWNER_INVALID",
-            ErrorCode::QuotaExceeded => "QUOTA_EXCEEDED",
-            ErrorCode::StoreFailure => "STORE_FAILURE",
-            ErrorCode::RouterLost => "ROUTER_LOST",
-            ErrorCode::Conflict => "CONFLICT",
-            ErrorCode::NoTopic => "NO_TOPIC",
-            ErrorCode::ArtifactMismatch => "ARTIFACT_MISMATCH",
-        }
-    }
-
-    pub fn parse(s: &str) -> Option<ErrorCode> {
-        ErrorCode::ALL.into_iter().find(|c| c.as_str() == s)
-    }
-}
-
-impl fmt::Display for ErrorCode {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(self.as_str())
-    }
-}
-
-/// Whether the operation may have reached its target (bus-v1 section 5).
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
-pub enum Dispatch {
-    NotDispatched,
-    Dispatched,
-    Unknown,
-}
-
-impl Dispatch {
-    pub fn as_str(self) -> &'static str {
-        match self {
-            Dispatch::NotDispatched => "not-dispatched",
-            Dispatch::Dispatched => "dispatched",
-            Dispatch::Unknown => "unknown",
-        }
-    }
-
-    pub fn parse(s: &str) -> Option<Dispatch> {
-        match s {
-            "not-dispatched" => Some(Dispatch::NotDispatched),
-            "dispatched" => Some(Dispatch::Dispatched),
-            "unknown" => Some(Dispatch::Unknown),
-            _ => None,
-        }
-    }
-}
-
-/// A transport error: code, a short message and the dispatch certainty.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct BusError {
-    pub code: ErrorCode,
-    pub message: String,
-    pub dispatch: Dispatch,
-}
-
-impl BusError {
-    /// An error raised before anything could have been dispatched.
-    pub fn new(code: ErrorCode, message: impl Into<String>) -> BusError {
-        BusError {
-            code,
-            message: message.into(),
-            dispatch: Dispatch::NotDispatched,
-        }
-    }
-
-    pub fn with_dispatch(mut self, dispatch: Dispatch) -> BusError {
-        self.dispatch = dispatch;
-        self
-    }
-
-    pub(crate) fn invalid(message: impl Into<String>) -> BusError {
-        BusError::new(ErrorCode::InvalidEnvelope, message)
-    }
-
-    pub(crate) fn lost(message: impl Into<String>) -> BusError {
-        BusError::new(ErrorCode::RouterLost, message).with_dispatch(Dispatch::Unknown)
-    }
-}
-
-impl fmt::Display for BusError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(
-            f,
-            "{} ({}): {}",
-            self.code,
-            self.dispatch.as_str(),
-            self.message
-        )
-    }
-}
-
-impl std::error::Error for BusError {}

services/flysim/crates/flybus/src/lib.rs

@@ -1,37 +0,0 @@
-//! `flybus`: a small local RPC and pub/sub bus with immutable file-backed artifacts.
-//!
-//! One library, one router, one wire protocol. Small JSON messages carry metadata and
-//! artifact references; large immutable bytes live in a file store the router manages, and
-//! ownership follows deliveries and explicit holds. The router moves messages and tracks
-//! ownership; it knows nothing about what the messages mean.
-//!
-//! ```text
-//!  Client ── Transport (in-memory pipe or Unix socket) ── Router ── State (one mutex)
-//!    │                                                      │
-//!    └── Artifact / ArtifactWriter ── files ──────────── Store (<root>/<storeId>/...)
-//! ```
-//!
-//! The draft contract this implements is bus-v1 (the session-framework design); the README
-//! lists the API, the limits and every place the implementation narrows or extends the draft.
-
-pub mod error;
-pub mod limits;
-pub mod policy;
-pub mod wire;
-
-mod client;
-mod router;
-mod store;
-mod transport;
-
-pub use client::{
-    Artifact, ArtifactFile, ArtifactWriter, Artifacts, CancelState, Client, ClientConfig, Message,
-    Mode, PendingCall, PublishReceipt, Request, Responder, Retained, RpcResult, Service,
-    ServiceConfig, SessionInfo, Subscription, SubscriptionConfig, TopicInfo,
-};
-pub use error::{BusError, Dispatch, ErrorCode};
-pub use limits::Limits;
-pub use policy::{Grants, Pattern, Policy};
-pub use router::{Router, RouterConfig, RouterStats, UnixListenerHandle};
-pub use transport::{Stream, Transport};
-pub use wire::{ArtifactRef, Identity};

services/flysim/crates/flybus/src/limits.rs

@@ -1,183 +0,0 @@
-//! Router limits (bus-v1 section 9). The defaults are the draft's prototype starting point,
-//! not capacity data.
-
-use serde_json::{Map, Value};
-
-use crate::wire::{Fields, MAX_ATTACHMENTS, MAX_BATCH, MAX_CREDIT, MAX_ENVELOPE_BYTES, WireError};
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Limits {
-    pub max_clients: usize,
-    pub max_services: usize,
-    pub max_topics: usize,
-    pub max_subscriptions_per_client: usize,
-    pub max_subscriptions: usize,
-    /// Calls a client may have admitted and not yet finished (result consumed, failed or
-    /// cancelled before dispatch). A call detached by a post-dispatch cancel no longer counts.
-    pub max_active_calls_per_client: usize,
-    /// Upper bounds on what `service.register` may ask for.
-    pub max_service_queued: u64,
-    pub max_service_in_flight: u64,
-    /// Upper bound on a `latest` subscription's credits; its queue is always exactly 1.
-    pub max_latest_in_flight: u64,
-    pub max_bounded_queued: u64,
-    pub max_bounded_in_flight: u64,
-    /// Owners (deliveries handed to the client and not consumed, explicit holds and staging
-    /// writers) a connection may have at once.
-    pub max_owners_per_client: usize,
-    /// Of those, how many only RPC request/result deliveries may use. Topic deliveries, holds
-    /// and writers are refused (holds, writers) or wait (deliveries) beyond
-    /// `max_owners_per_client - reserved_owners_per_client`.
-    pub reserved_owners_per_client: usize,
-    /// Bytes of staging, sealing copies and sealed objects the store may hold.
-    pub max_store_bytes: u64,
-    pub max_artifact_bytes: u64,
-    /// Artifact bytes pinned by retained topic values, counted once per topic.
-    pub max_retained_bytes: u64,
-    /// Envelope bytes queued for a client's `bounded` subscriptions and not yet delivered.
-    pub max_queued_bytes_per_client: usize,
-    /// Replies and notices waiting to be written to one client. Exceeding either closes it.
-    pub max_control_frames: usize,
-    pub max_control_bytes: usize,
-}
-
-impl Default for Limits {
-    fn default() -> Limits {
-        Limits {
-            max_clients: 64,
-            max_services: 256,
-            max_topics: 512,
-            max_subscriptions_per_client: 128,
-            max_subscriptions: 1024,
-            max_active_calls_per_client: 64,
-            max_service_queued: 16,
-            max_service_in_flight: 16,
-            max_latest_in_flight: 2,
-            max_bounded_queued: 64,
-            max_bounded_in_flight: 16,
-            max_owners_per_client: 256,
-            reserved_owners_per_client: 64,
-            max_store_bytes: 512 << 20,
-            max_artifact_bytes: 128 << 20,
-            max_retained_bytes: 128 << 20,
-            max_queued_bytes_per_client: 1 << 20,
-            max_control_frames: 128,
-            max_control_bytes: 1 << 20,
-        }
-    }
-}
-
-impl Limits {
-    /// Refuses a configuration the router could not honour.
-    pub fn validate(&self) -> Result<(), String> {
-        let credits = [
-            ("max_service_queued", self.max_service_queued),
-            ("max_service_in_flight", self.max_service_in_flight),
-            ("max_latest_in_flight", self.max_latest_in_flight),
-            ("max_bounded_queued", self.max_bounded_queued),
-            ("max_bounded_in_flight", self.max_bounded_in_flight),
-        ];
-        for (name, v) in credits {
-            if !(1..=MAX_CREDIT).contains(&v) {
-                return Err(format!("{name} must be in 1..={MAX_CREDIT}"));
-            }
-        }
-        if self.reserved_owners_per_client >= self.max_owners_per_client {
-            return Err("reserved_owners_per_client must be below max_owners_per_client".into());
-        }
-        if self.max_artifact_bytes > self.max_store_bytes {
-            return Err("max_artifact_bytes must not exceed max_store_bytes".into());
-        }
-        if self.max_control_frames == 0 || self.max_control_bytes < MAX_ENVELOPE_BYTES {
-            return Err("the control lane must hold at least one full envelope".into());
-        }
-        Ok(())
-    }
-
-    /// The `limits` object in the hello reply. Counts are JSON integers; byte sizes are U64
-    /// strings.
-    pub fn to_json(&self) -> Value {
-        let mut m = Map::new();
-        let mut n = |k: &str, v: u64| {
-            m.insert(k.into(), Value::from(v));
-        };
-        n("maxEnvelopeBytes", MAX_ENVELOPE_BYTES as u64);
-        n("maxAttachments", MAX_ATTACHMENTS as u64);
-        n("maxBatch", MAX_BATCH as u64);
-        n("maxClients", self.max_clients as u64);
-        n("maxServices", self.max_services as u64);
-        n("maxTopics", self.max_topics as u64);
-        n(
-            "maxSubscriptionsPerClient",
-            self.max_subscriptions_per_client as u64,
-        );
-        n("maxSubscriptions", self.max_subscriptions as u64);
-        n(
-            "maxActiveCallsPerClient",
-            self.max_active_calls_per_client as u64,
-        );
-        n("maxServiceQueued", self.max_service_queued);
-        n("maxServiceInFlight", self.max_service_in_flight);
-        n("maxLatestInFlight", self.max_latest_in_flight);
-        n("maxBoundedQueued", self.max_bounded_queued);
-        n("maxBoundedInFlight", self.max_bounded_in_flight);
-        n("maxOwnersPerClient", self.max_owners_per_client as u64);
-        n(
-            "reservedOwnersPerClient",
-            self.reserved_owners_per_client as u64,
-        );
-        n("maxControlFrames", self.max_control_frames as u64);
-        let mut s = |k: &str, v: u64| {
-            m.insert(k.into(), Value::from(v.to_string()));
-        };
-        s("maxStoreBytes", self.max_store_bytes);
-        s("maxArtifactBytes", self.max_artifact_bytes);
-        s("maxRetainedBytes", self.max_retained_bytes);
-        s(
-            "maxQueuedBytesPerClient",
-            self.max_queued_bytes_per_client as u64,
-        );
-        s("maxControlBytes", self.max_control_bytes as u64);
-        Value::Object(m)
-    }
-
-    /// Reads the hello reply's `limits` object back.
-    pub fn from_json(v: &Value) -> Result<Limits, WireError> {
-        let mut f = Fields::new(v, "limits")?;
-        let big = u64::MAX;
-        for (k, want) in [
-            ("maxEnvelopeBytes", MAX_ENVELOPE_BYTES as u64),
-            ("maxAttachments", MAX_ATTACHMENTS as u64),
-            ("maxBatch", MAX_BATCH as u64),
-        ] {
-            if f.int(k, 0, big)? != want {
-                return Err(WireError(format!(
-                    "limits: {k} disagrees with this implementation"
-                )));
-            }
-        }
-        let limits = Limits {
-            max_clients: f.int("maxClients", 0, big)? as usize,
-            max_services: f.int("maxServices", 0, big)? as usize,
-            max_topics: f.int("maxTopics", 0, big)? as usize,
-            max_subscriptions_per_client: f.int("maxSubscriptionsPerClient", 0, big)? as usize,
-            max_subscriptions: f.int("maxSubscriptions", 0, big)? as usize,
-            max_active_calls_per_client: f.int("maxActiveCallsPerClient", 0, big)? as usize,
-            max_service_queued: f.int("maxServiceQueued", 1, MAX_CREDIT)?,
-            max_service_in_flight: f.int("maxServiceInFlight", 1, MAX_CREDIT)?,
-            max_latest_in_flight: f.int("maxLatestInFlight", 1, MAX_CREDIT)?,
-            max_bounded_queued: f.int("maxBoundedQueued", 1, MAX_CREDIT)?,
-            max_bounded_in_flight: f.int("maxBoundedInFlight", 1, MAX_CREDIT)?,
-            max_owners_per_client: f.int("maxOwnersPerClient", 0, big)? as usize,
-            reserved_owners_per_client: f.int("reservedOwnersPerClient", 0, big)? as usize,
-            max_control_frames: f.int("maxControlFrames", 0, big)? as usize,
-            max_store_bytes: f.u64_string("maxStoreBytes")?,
-            max_artifact_bytes: f.u64_string("maxArtifactBytes")?,
-            max_retained_bytes: f.u64_string("maxRetainedBytes")?,
-            max_queued_bytes_per_client: f.u64_string("maxQueuedBytesPerClient")? as usize,
-            max_control_bytes: f.u64_string("maxControlBytes")? as usize,
-        };
-        f.finish()?;
-        Ok(limits)
-    }
-}

services/flysim/crates/flybus/src/policy.rs

@@ -1,108 +0,0 @@
-//! Launcher-provided access policy (bus-v1 section 3): which configured participants may
-//! connect, and what each may register, call, publish, subscribe to and manage. Naming a
-//! target is not authority to control it.
-
-use std::collections::HashMap;
-
-/// A set of service or topic names.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum Pattern {
-    Any,
-    Exact(String),
-    /// Every name that starts with this string, e.g. `"session.demo."`.
-    Prefix(String),
-}
-
-impl Pattern {
-    pub fn exact(name: &str) -> Pattern {
-        Pattern::Exact(name.to_owned())
-    }
-
-    pub fn prefix(prefix: &str) -> Pattern {
-        Pattern::Prefix(prefix.to_owned())
-    }
-
-    pub fn matches(&self, name: &str) -> bool {
-        match self {
-            Pattern::Any => true,
-            Pattern::Exact(n) => n == name,
-            Pattern::Prefix(p) => name.starts_with(p.as_str()),
-        }
-    }
-}
-
-/// What one participant may do. Empty lists grant nothing.
-#[derive(Clone, Debug, Default, PartialEq, Eq)]
-pub struct Grants {
-    /// Service names it may register.
-    pub register: Vec<Pattern>,
-    /// Service names it may call.
-    pub call: Vec<Pattern>,
-    pub publish: Vec<Pattern>,
-    pub subscribe: Vec<Pattern>,
-    /// Topic names it may declare, clear and delete.
-    pub manage_topics: Vec<Pattern>,
-}
-
-impl Grants {
-    pub fn all() -> Grants {
-        let any = vec![Pattern::Any];
-        Grants {
-            register: any.clone(),
-            call: any.clone(),
-            publish: any.clone(),
-            subscribe: any.clone(),
-            manage_topics: any,
-        }
-    }
-
-    pub(crate) fn allows(list: &[Pattern], name: &str) -> bool {
-        list.iter().any(|p| p.matches(name))
-    }
-}
-
-/// Who may connect and with what grants.
-#[derive(Clone, Debug, Default)]
-pub struct Policy {
-    clients: HashMap<String, Grants>,
-    default: Option<Grants>,
-    trusted_unbound: bool,
-}
-
-impl Policy {
-    /// Admits any client id with every grant. For tests and single-purpose local deployments.
-    pub fn open() -> Policy {
-        Policy {
-            clients: HashMap::new(),
-            default: Some(Grants::all()),
-            trusted_unbound: true,
-        }
-    }
-
-    /// Admits only the clients added with [`Policy::client`].
-    pub fn closed() -> Policy {
-        Policy::default()
-    }
-
-    pub fn client(mut self, client_id: &str, grants: Grants) -> Policy {
-        self.clients.insert(client_id.to_owned(), grants);
-        self
-    }
-
-    /// Grants for clients not listed by id; `None` refuses them at hello.
-    pub fn with_default(mut self, grants: Option<Grants>) -> Policy {
-        self.default = grants;
-        self
-    }
-
-    pub(crate) fn grants_for(&self, client_id: &str) -> Option<Grants> {
-        self.clients
-            .get(client_id)
-            .cloned()
-            .or_else(|| self.default.clone())
-    }
-
-    pub(crate) fn permits_unbound_transport(&self) -> bool {
-        self.trusted_unbound
-    }
-}

services/flysim/crates/flybus/src/router/mod.rs

@@ -1,502 +0,0 @@
-//! The embeddable router: connection tasks around the [`state`] machine.
-//!
-//! Each connection has a reader task, which decodes one command at a time and applies it under
-//! the state lock, and a writer task, which pulls its next frame from the state and writes it
-//! with the lock released. Staging creation and seal copies run on the blocking pool; seals
-//! run beside the reader, so a large copy never holds up that client's releases. The router
-//! never waits on a subscriber: a slow reader only stalls its own writer task.
-
-mod state;
-
-use std::io;
-use std::os::unix::fs::PermissionsExt;
-use std::path::{Path, PathBuf};
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::{Arc, Mutex};
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
-
-use sha2::{Digest as _, Sha256};
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
-use tokio::net::UnixListener;
-use tokio::sync::watch;
-use tokio::task::JoinHandle;
-
-pub use state::RouterStats;
-use state::{ConnKey, ConnSignals, NextFrame, Outcome, State};
-
-use crate::limits::Limits;
-use crate::policy::Policy;
-use crate::store::{SealFailure, Store};
-use crate::transport::{Stream, Transport};
-use crate::wire::{Envelope, FrameError, contract_digest, hex, read_frame, write_frame};
-
-/// How the launcher configures a router.
-#[derive(Clone, Debug)]
-pub struct RouterConfig {
-    /// Directory under which the store creates its per-incarnation directory. Put it on tmpfs
-    /// for transient media. Clients must be given the same root.
-    pub store_root: PathBuf,
-    pub limits: Limits,
-    pub policy: Policy,
-    /// Maximum time an accepted transport may remain pending before completing `bus.hello`.
-    pub hello_timeout: Duration,
-}
-
-impl RouterConfig {
-    /// Default limits and a closed policy: add clients with [`Policy::client`].
-    pub fn new(store_root: impl Into<PathBuf>) -> RouterConfig {
-        RouterConfig {
-            store_root: store_root.into(),
-            limits: Limits::default(),
-            policy: Policy::closed(),
-            hello_timeout: Duration::from_secs(5),
-        }
-    }
-}
-
-struct Inner {
-    state: Mutex<State>,
-    store: Store,
-    store_root: PathBuf,
-    router_id: String,
-    store_id: String,
-    stop: watch::Sender<bool>,
-    hello_timeout: Duration,
-}
-
-impl Inner {
-    /// Runs `f` under the state lock, then unlinks whatever it released, outside the lock.
-    fn with_state<R>(&self, f: impl FnOnce(&mut State) -> R) -> R {
-        let mut st = self.state.lock().unwrap_or_else(|e| e.into_inner());
-        let r = f(&mut st);
-        let unlinks = st.take_unlinks();
-        drop(st);
-        for rel in unlinks {
-            self.store.remove(&rel);
-        }
-        r
-    }
-}
-
-/// A router and its artifact store. Cheap to clone; every clone is the same router.
-#[derive(Clone)]
-pub struct Router {
-    inner: Arc<Inner>,
-}
-
-fn fresh_tag() -> String {
-    static COUNTER: AtomicU64 = AtomicU64::new(0);
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |d| d.as_nanos());
-    let mut h = Sha256::new();
-    h.update(std::process::id().to_le_bytes());
-    h.update(nanos.to_le_bytes());
-    h.update(COUNTER.fetch_add(1, Ordering::Relaxed).to_le_bytes());
-    hex(&h.finalize()[..8])
-}
-
-impl Router {
-    /// Creates the store directory (deleting orphans of stopped routers under the same root)
-    /// and a router with a fresh `routerId`/`storeId`.
-    pub fn new(config: RouterConfig) -> io::Result<Router> {
-        config.limits.validate().map_err(io::Error::other)?;
-        let tag = fresh_tag();
-        let router_id = format!("router-{tag}");
-        let store_id = format!("store-{tag}");
-        let store = Store::create(&config.store_root, &store_id)?;
-        let state = State::new(
-            router_id.clone(),
-            store_id.clone(),
-            contract_digest(),
-            config.limits,
-            config.policy,
-        );
-        Ok(Router {
-            inner: Arc::new(Inner {
-                state: Mutex::new(state),
-                store,
-                store_root: config.store_root,
-                router_id,
-                store_id,
-                stop: watch::Sender::new(false),
-                hello_timeout: config.hello_timeout,
-            }),
-        })
-    }
-
-    pub fn router_id(&self) -> &str {
-        &self.inner.router_id
-    }
-
-    pub fn store_id(&self) -> &str {
-        &self.inner.store_id
-    }
-
-    pub fn store_root(&self) -> &Path {
-        &self.inner.store_root
-    }
-
-    /// `<store_root>/<store_id>`.
-    pub fn store_dir(&self) -> &Path {
-        self.inner.store.dir()
-    }
-
-    pub fn stats(&self) -> RouterStats {
-        self.inner.with_state(|s| s.stats())
-    }
-
-    /// Serves an explicitly trusted, unbound connection. This is refused unless the router
-    /// uses [`Policy::open`]; Hello identity is self-asserted in this mode.
-    pub fn serve<S: Stream>(&self, stream: S) {
-        tokio::spawn(run_connection(self.inner.clone(), stream, None));
-    }
-
-    /// Serves one launcher-bound participant. Hello must name `expected_client_id`.
-    pub fn serve_as<S: Stream>(&self, stream: S, expected_client_id: &str) {
-        tokio::spawn(run_connection(
-            self.inner.clone(),
-            stream,
-            Some(expected_client_id.to_owned()),
-        ));
-    }
-
-    /// A connected in-memory transport for a client in this process.
-    pub fn connect_in_memory(&self) -> Transport {
-        let (client, router) = Transport::pair();
-        self.serve(router);
-        client
-    }
-
-    /// A connected in-memory transport bound to `expected_client_id` out of band.
-    pub fn connect_in_memory_as(&self, expected_client_id: &str) -> Transport {
-        let (client, router) = Transport::pair();
-        self.serve_as(router, expected_client_id);
-        client
-    }
-
-    /// Listens on a new Unix-domain socket (mode 0600) until the returned handle is dropped or
-    /// the router shuts down.
-    pub async fn listen_unix(&self, path: impl AsRef<Path>) -> io::Result<UnixListenerHandle> {
-        self.listen_unix_inner(path.as_ref(), None).await
-    }
-
-    /// Listens on a launcher-created endpoint dedicated to `expected_client_id`.
-    pub async fn listen_unix_as(
-        &self,
-        path: impl AsRef<Path>,
-        expected_client_id: &str,
-    ) -> io::Result<UnixListenerHandle> {
-        self.listen_unix_inner(path.as_ref(), Some(expected_client_id.to_owned()))
-            .await
-    }
-
-    async fn listen_unix_inner(
-        &self,
-        path: &Path,
-        expected_client_id: Option<String>,
-    ) -> io::Result<UnixListenerHandle> {
-        let path = path.to_path_buf();
-        let listener = UnixListener::bind(&path)?;
-        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
-        let inner = self.inner.clone();
-        let mut stop = self.inner.stop.subscribe();
-        let task = tokio::spawn(async move {
-            loop {
-                tokio::select! {
-                    accepted = listener.accept() => match accepted {
-                        Ok((stream, _)) => {
-                            tokio::spawn(run_connection(inner.clone(), stream, expected_client_id.clone()));
-                        }
-                        // Out of descriptors and the like: back off rather than spin.
-                        Err(_) => tokio::time::sleep(Duration::from_millis(10)).await,
-                    },
-                    _ = stopped(&mut stop) => break,
-                }
-            }
-        });
-        Ok(UnixListenerHandle { path, task })
-    }
-
-    /// Closes every connection, releases retained values and refuses new connections. A
-    /// connection at a frame boundary gets final notices; one inside a partial frame is closed
-    /// without appending another frame. The store directory is removed once the last connection
-    /// task and seal have finished and every `Router` clone is dropped.
-    pub fn shutdown(&self) {
-        self.inner.stop.send_replace(true);
-        self.inner.with_state(|s| s.shutdown());
-    }
-}
-
-/// Stops the listener and removes its socket file when dropped.
-pub struct UnixListenerHandle {
-    path: PathBuf,
-    task: JoinHandle<()>,
-}
-
-impl UnixListenerHandle {
-    pub fn path(&self) -> &Path {
-        &self.path
-    }
-}
-
-impl Drop for UnixListenerHandle {
-    fn drop(&mut self) {
-        self.task.abort();
-        let _ = std::fs::remove_file(&self.path);
-    }
-}
-
-/// Resolves once the flag is true (or its sender is gone).
-async fn stopped(rx: &mut watch::Receiver<bool>) {
-    let _ = rx.wait_for(|v| *v).await;
-}
-
-async fn run_connection<S: Stream>(
-    inner: Arc<Inner>,
-    stream: S,
-    expected_client_id: Option<String>,
-) {
-    let signals = Arc::new(ConnSignals::new());
-    let Some(c) = inner.with_state(|s| s.add_conn(signals.clone(), expected_client_id)) else {
-        return;
-    };
-    let (rd, wr) = tokio::io::split(stream);
-    let writer = tokio::spawn(write_loop(inner.clone(), c, signals.clone(), wr));
-    read_loop(&inner, c, &signals, rd).await;
-    // A no-op if the state already closed it.
-    inner.with_state(|s| s.close_conn(c, []));
-    let _ = writer.await;
-}
-
-async fn read_loop<R: AsyncRead + Unpin>(
-    inner: &Arc<Inner>,
-    c: ConnKey,
-    signals: &ConnSignals,
-    mut rd: R,
-) {
-    let mut shutdown = signals.shutdown.subscribe();
-    let hello_deadline = tokio::time::sleep(inner.hello_timeout);
-    tokio::pin!(hello_deadline);
-    let mut negotiated = false;
-    let mut handled: u32 = 0;
-    loop {
-        let frame = tokio::select! {
-            f = read_frame(&mut rd) => f,
-            _ = stopped(&mut shutdown) => return,
-            _ = &mut hello_deadline, if !negotiated => {
-                inner.with_state(|s| s.reject_frame(c, "bus.hello deadline expired".into()));
-                return;
-            }
-        };
-        let bytes = match frame {
-            Ok(Some(b)) => b,
-            Ok(None) | Err(FrameError::Io(_)) | Err(FrameError::Truncated) => return,
-            Err(e) => {
-                inner.with_state(|s| s.reject_frame(c, e.to_string()));
-                return;
-            }
-        };
-        let env = match Envelope::decode(&bytes) {
-            Ok(env) => env,
-            Err(e) => {
-                inner.with_state(|s| s.reject_frame(c, e.0));
-                return;
-            }
-        };
-        let was_hello = !negotiated && env.op == "bus.hello";
-        match inner.with_state(|s| s.handle(c, env)) {
-            Outcome::Done => {}
-            Outcome::Close => return,
-            Outcome::Allocate(job) => {
-                let (i, serial, len) = (inner.clone(), job.serial, job.len);
-                let created =
-                    tokio::task::spawn_blocking(move || i.store.create_staging(serial, len))
-                        .await
-                        .unwrap_or_else(|e| Err(io::Error::other(e)));
-                inner.with_state(|s| s.finish_allocate(job, created));
-            }
-            Outcome::Seal(job) => {
-                let inner = inner.clone();
-                tokio::spawn(async move {
-                    let (i, serial, len, digest) =
-                        (inner.clone(), job.serial, job.len, job.digest.clone());
-                    let result = tokio::task::spawn_blocking(move || {
-                        let r = i.store.seal(serial, len, digest.as_deref());
-                        // Staging is finished with either way; unlink it before anyone can
-                        // see the outcome.
-                        i.store.remove(&crate::store::staging_rel(serial));
-                        r
-                    })
-                    .await
-                    .unwrap_or_else(|e| Err(SealFailure::Io(io::Error::other(e))));
-                    inner.with_state(|s| s.finish_seal(job, result));
-                });
-            }
-        }
-        if was_hello {
-            negotiated = true;
-        }
-        handled = handled.wrapping_add(1);
-        if handled.is_multiple_of(32) {
-            // Fairness: a client flooding commands yields to the others.
-            tokio::task::yield_now().await;
-        }
-    }
-}
-
-/// How long a closing connection gets to write final notices and shut down the transport.
-const CLOSING_WRITE: Duration = Duration::from_secs(2);
-
-enum SelectedWrite {
-    Complete,
-    Closing { partial: bool },
-    Failed,
-}
-
-/// Writes one selected frame while serializing each synchronous transport poll with teardown.
-/// The standard mutex is released after every poll and is never held across an await.
-async fn write_selected<W: AsyncWrite + Unpin>(
-    wr: &mut W,
-    bytes: &[u8],
-    signals: &ConnSignals,
-) -> SelectedWrite {
-    let mut frame = Vec::with_capacity(bytes.len() + 4);
-    frame.extend_from_slice(&(bytes.len() as u32).to_le_bytes());
-    frame.extend_from_slice(bytes);
-    {
-        let mut gate = signals.write_gate.lock().unwrap_or_else(|e| e.into_inner());
-        if !gate.begin_frame(frame.len()) {
-            return SelectedWrite::Closing {
-                partial: gate.cut_partial(),
-            };
-        }
-    }
-
-    let mut written = 0;
-    while written < frame.len() {
-        let polled = std::future::poll_fn(|cx| {
-            let mut gate = signals.write_gate.lock().unwrap_or_else(|e| e.into_inner());
-            if gate.closing() {
-                return std::task::Poll::Ready(Err(io::Error::new(
-                    io::ErrorKind::Interrupted,
-                    "connection closing",
-                )));
-            }
-            match std::pin::Pin::new(&mut *wr).poll_write(cx, &frame[written..]) {
-                std::task::Poll::Ready(Ok(0)) => std::task::Poll::Ready(Err(io::Error::new(
-                    io::ErrorKind::WriteZero,
-                    "failed to write router frame",
-                ))),
-                std::task::Poll::Ready(Ok(n)) => {
-                    gate.wrote(n);
-                    std::task::Poll::Ready(Ok(n))
-                }
-                other => other,
-            }
-        })
-        .await;
-        match polled {
-            Ok(n) => written += n,
-            Err(e) if e.kind() == io::ErrorKind::Interrupted => {
-                let gate = signals.write_gate.lock().unwrap_or_else(|e| e.into_inner());
-                return SelectedWrite::Closing {
-                    partial: gate.cut_partial(),
-                };
-            }
-            Err(_) => return SelectedWrite::Failed,
-        }
-    }
-
-    let flushed = std::future::poll_fn(|cx| {
-        let gate = signals.write_gate.lock().unwrap_or_else(|e| e.into_inner());
-        if gate.closing() {
-            return std::task::Poll::Ready(Err(io::Error::new(
-                io::ErrorKind::Interrupted,
-                "connection closing",
-            )));
-        }
-        std::pin::Pin::new(&mut *wr).poll_flush(cx)
-    })
-    .await;
-    if let Err(e) = flushed {
-        if e.kind() == io::ErrorKind::Interrupted {
-            let gate = signals.write_gate.lock().unwrap_or_else(|e| e.into_inner());
-            return SelectedWrite::Closing {
-                partial: gate.cut_partial(),
-            };
-        }
-        return SelectedWrite::Failed;
-    }
-    signals
-        .write_gate
-        .lock()
-        .unwrap_or_else(|e| e.into_inner())
-        .finish_frame();
-    SelectedWrite::Complete
-}
-
-async fn write_loop<W: AsyncWrite + Unpin>(
-    inner: Arc<Inner>,
-    c: ConnKey,
-    signals: Arc<ConnSignals>,
-    mut wr: W,
-) {
-    let mut shutdown = signals.shutdown.subscribe();
-    // False once a frame was cut short: nothing more may be written on this stream.
-    let mut aligned = true;
-    loop {
-        match inner.with_state(|s| s.next_frame(c)) {
-            NextFrame::Frame(bytes) => {
-                let write = write_selected(&mut wr, &bytes, &signals);
-                tokio::pin!(write);
-                let selected = tokio::select! {
-                    result = &mut write => result,
-                    _ = stopped(&mut shutdown) => {
-                        let gate = signals
-                            .write_gate
-                            .lock()
-                            .unwrap_or_else(|e| e.into_inner());
-                        SelectedWrite::Closing { partial: gate.cut_partial() }
-                    }
-                };
-                match selected {
-                    SelectedWrite::Complete => {}
-                    SelectedWrite::Closing { partial } => {
-                        aligned = !partial;
-                        break;
-                    }
-                    SelectedWrite::Failed => {
-                        aligned = false;
-                        inner.with_state(|s| s.close_conn(c, []));
-                        break;
-                    }
-                }
-            }
-            NextFrame::Idle => {
-                tokio::select! {
-                    _ = signals.wake.notified() => {}
-                    _ = stopped(&mut shutdown) => {}
-                }
-            }
-            NextFrame::Gone => break,
-        }
-    }
-    let finals = std::mem::take(
-        &mut *signals
-            .final_frames
-            .lock()
-            .unwrap_or_else(|e| e.into_inner()),
-    );
-    if aligned {
-        let _ = tokio::time::timeout(CLOSING_WRITE, async {
-            for f in &finals {
-                if write_frame(&mut wr, f).await.is_err() {
-                    break;
-                }
-            }
-        })
-        .await;
-    }
-    let _ = tokio::time::timeout(CLOSING_WRITE, wr.shutdown()).await;
-}

services/flysim/crates/flybus/src/store.rs

@@ -1,366 +0,0 @@
-//! The file-backed artifact store (bus-v1 section 8).
-//!
-//! Layout under the configured root, one directory per store incarnation:
-//!
-//! ```text
-//! <root>/<storeId>/.flybus-store   marker: this directory belongs to a flybus store
-//! <root>/<storeId>/.lock           flock()ed by the live router for its whole life
-//! <root>/<storeId>/staging/a-<n>   producer-writable staging file, preallocated
-//! <root>/<storeId>/sealed/a-<n>    immutable copy, mode 0444, never rewritten
-//! ```
-//!
-//! Sealing copies staging into a fresh inode rather than renaming it, so a writable handle a
-//! producer kept (or duplicated) after sealing reaches only the unlinked staging inode, never
-//! the sealed bytes. A store directory whose lock nobody holds is an orphan of a stopped
-//! router and is deleted when the next router starts on the same root.
-
-use std::fs::{self, File, OpenOptions};
-use std::io::{self, Read, Write};
-use std::os::fd::AsRawFd;
-use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt, PermissionsExt};
-use std::path::{Component, Path, PathBuf};
-
-use sha2::{Digest as _, Sha256};
-
-use crate::error::{BusError, ErrorCode};
-use crate::wire::{Location, hex};
-
-const MARKER: &str = ".flybus-store";
-const LOCK: &str = ".lock";
-
-pub(crate) fn staging_rel(serial: u64) -> String {
-    format!("staging/a-{serial}")
-}
-
-pub(crate) fn sealed_rel(serial: u64) -> String {
-    format!("sealed/a-{serial}")
-}
-
-pub(crate) enum SealFailure {
-    Mismatch(String),
-    Io(io::Error),
-}
-
-impl From<io::Error> for SealFailure {
-    fn from(e: io::Error) -> SealFailure {
-        SealFailure::Io(e)
-    }
-}
-
-pub(crate) struct Store {
-    dir: PathBuf,
-    // Held open for the flock; closing it releases the lock.
-    _lock: File,
-}
-
-fn try_lock(file: &File) -> bool {
-    // SAFETY: flock on a valid, owned descriptor.
-    unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) == 0 }
-}
-
-impl Store {
-    /// Creates `<root>/<store_id>`, first deleting orphaned store directories under `root`.
-    pub(crate) fn create(root: &Path, store_id: &str) -> io::Result<Store> {
-        fs::DirBuilder::new()
-            .recursive(true)
-            .mode(0o700)
-            .create(root)?;
-        clean_orphans(root)?;
-        let dir = root.join(store_id);
-        let mut builder = fs::DirBuilder::new();
-        builder.mode(0o700);
-        builder.create(&dir)?;
-        builder.create(dir.join("staging"))?;
-        builder.create(dir.join("sealed"))?;
-        File::create(dir.join(MARKER))?;
-        let lock = OpenOptions::new()
-            .read(true)
-            .write(true)
-            .create_new(true)
-            .mode(0o600)
-            .open(dir.join(LOCK))?;
-        if !try_lock(&lock) {
-            return Err(io::Error::other("could not lock a fresh store directory"));
-        }
-        Ok(Store { dir, _lock: lock })
-    }
-
-    pub(crate) fn dir(&self) -> &Path {
-        &self.dir
-    }
-
-    pub(crate) fn path(&self, rel: &str) -> PathBuf {
-        self.dir.join(rel)
-    }
-
-    /// Creates the staging file and reserves its blocks, so a full disk fails here and not in
-    /// the producer's write.
-    pub(crate) fn create_staging(&self, serial: u64, len: u64) -> io::Result<()> {
-        let path = self.path(&staging_rel(serial));
-        let file = OpenOptions::new()
-            .write(true)
-            .create_new(true)
-            .mode(0o600)
-            .custom_flags(libc::O_NOFOLLOW)
-            .open(&path)?;
-        let reserve = || -> io::Result<()> {
-            if len == 0 {
-                return Ok(());
-            }
-            let off_len = libc::off_t::try_from(len)
-                .map_err(|_| io::Error::other("length overflows off_t"))?;
-            // SAFETY: posix_fallocate on a valid descriptor opened for writing.
-            let rc = unsafe { libc::posix_fallocate(file.as_raw_fd(), 0, off_len) };
-            match rc {
-                0 => Ok(()),
-                libc::EOPNOTSUPP | libc::EINVAL => file.set_len(len),
-                e => Err(io::Error::from_raw_os_error(e)),
-            }
-        };
-        let result = reserve();
-        if result.is_err() {
-            let _ = fs::remove_file(&path);
-        }
-        result
-    }
-
-    /// Copies exactly `len` staging bytes into a fresh sealed file, checking the length and,
-    /// when given, the SHA-256. On failure the partial sealed file is removed; the staging file
-    /// is left for the caller either way.
-    pub(crate) fn seal(
-        &self,
-        serial: u64,
-        len: u64,
-        digest: Option<&str>,
-    ) -> Result<(), SealFailure> {
-        let mut src = OpenOptions::new()
-            .read(true)
-            .custom_flags(libc::O_NOFOLLOW)
-            .open(self.path(&staging_rel(serial)))?;
-        let dst_path = self.path(&sealed_rel(serial));
-        let mut dst = OpenOptions::new()
-            .write(true)
-            .create_new(true)
-            .mode(0o600)
-            .custom_flags(libc::O_NOFOLLOW)
-            .open(&dst_path)?;
-        let result = copy_exact(&mut src, &mut dst, len, digest).and_then(|()| {
-            dst.set_permissions(fs::Permissions::from_mode(0o444))?;
-            Ok(())
-        });
-        if result.is_err() {
-            let _ = fs::remove_file(&dst_path);
-        }
-        result
-    }
-
-    /// Unlinks a store file; a missing file is not an error.
-    pub(crate) fn remove(&self, rel: &str) {
-        let _ = fs::remove_file(self.path(rel));
-    }
-}
-
-impl Drop for Store {
-    fn drop(&mut self) {
-        let _ = fs::remove_dir_all(&self.dir);
-    }
-}
-
-fn read_retry(r: &mut File, buf: &mut [u8]) -> io::Result<usize> {
-    loop {
-        match r.read(buf) {
-            Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
-            other => return other,
-        }
-    }
-}
-
-fn copy_exact(
-    src: &mut File,
-    dst: &mut File,
-    len: u64,
-    digest: Option<&str>,
-) -> Result<(), SealFailure> {
-    let mut hasher = digest.map(|_| Sha256::new());
-    let mut buf = vec![0u8; 256 * 1024];
-    let mut remaining = len;
-    while remaining > 0 {
-        let want = remaining.min(buf.len() as u64) as usize;
-        let n = read_retry(src, &mut buf[..want])?;
-        if n == 0 {
-            return Err(SealFailure::Mismatch(format!(
-                "staging holds {} of {len} declared bytes",
-                len - remaining
-            )));
-        }
-        if let Some(h) = hasher.as_mut() {
-            h.update(&buf[..n]);
-        }
-        dst.write_all(&buf[..n])?;
-        remaining -= n as u64;
-    }
-    if read_retry(src, &mut buf[..1])? != 0 {
-        return Err(SealFailure::Mismatch(format!(
-            "staging holds more than the declared {len} bytes"
-        )));
-    }
-    if let (Some(h), Some(want)) = (hasher, digest) {
-        let got = hex(&h.finalize());
-        if got != want {
-            return Err(SealFailure::Mismatch(format!(
-                "digest mismatch: content hashes to {got}"
-            )));
-        }
-    }
-    Ok(())
-}
-
-/// Deletes store directories under `root` that carry the marker and whose lock is free.
-/// Directories without the marker are never touched.
-fn clean_orphans(root: &Path) -> io::Result<()> {
-    for entry in fs::read_dir(root)? {
-        let entry = entry?;
-        let path = entry.path();
-        if !entry.file_type()?.is_dir() || !path.join(MARKER).is_file() {
-            continue;
-        }
-        let stale = match OpenOptions::new()
-            .read(true)
-            .custom_flags(libc::O_NOFOLLOW)
-            .open(path.join(LOCK))
-        {
-            Ok(lock) => try_lock(&lock),
-            Err(e) if e.kind() == io::ErrorKind::NotFound => true,
-            Err(e) => return Err(e),
-        };
-        if stale {
-            fs::remove_dir_all(&path)?;
-        }
-    }
-    Ok(())
-}
-
-// ---------------------------------------------------------------------------------------------
-// Client side
-
-/// Resolves a location grant beneath `<root>/<store_id>`. Absolute paths, `..`, anything but
-/// plain `[a-z0-9._-]` components, and symlinks that lead outside the store are refused.
-pub(crate) fn resolve(root: &Path, store_id: &str, loc: &Location) -> Result<PathBuf, BusError> {
-    if loc.store_id != store_id {
-        return Err(BusError::new(
-            ErrorCode::ArtifactGone,
-            "location names another store incarnation",
-        ));
-    }
-    let refuse =
-        |why: &str| BusError::new(ErrorCode::StoreFailure, format!("location refused: {why}"));
-    let rel = Path::new(&loc.relative_path);
-    if loc.relative_path.is_empty() || rel.is_absolute() {
-        return Err(refuse("not a relative path"));
-    }
-    for c in rel.components() {
-        match c {
-            Component::Normal(s) => {
-                let s = s.to_str().unwrap_or("");
-                if s.is_empty()
-                    || !s.bytes().all(|b| {
-                        b.is_ascii_lowercase()
-                            || b.is_ascii_digit()
-                            || matches!(b, b'.' | b'_' | b'-')
-                    })
-                {
-                    return Err(refuse("unexpected path component"));
-                }
-            }
-            _ => return Err(refuse("parent, root or current-directory component")),
-        }
-    }
-    let base = root.join(&loc.store_id);
-    let base = base
-        .canonicalize()
-        .map_err(|e| refuse(&format!("store directory: {e}")))?;
-    let full = base.join(rel).canonicalize().map_err(|e| match e.kind() {
-        io::ErrorKind::NotFound => BusError::new(ErrorCode::ArtifactGone, "artifact file is gone"),
-        _ => refuse(&e.to_string()),
-    })?;
-    if !full.starts_with(&base) {
-        return Err(refuse("escapes the store"));
-    }
-    Ok(full)
-}
-
-pub(crate) fn open_read(path: &Path) -> io::Result<File> {
-    OpenOptions::new()
-        .read(true)
-        .custom_flags(libc::O_NOFOLLOW)
-        .open(path)
-}
-
-pub(crate) fn open_write(path: &Path) -> io::Result<File> {
-    OpenOptions::new()
-        .write(true)
-        .custom_flags(libc::O_NOFOLLOW)
-        .open(path)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn loc(p: &str) -> Location {
-        Location {
-            store_id: "store-x".into(),
-            relative_path: p.into(),
-        }
-    }
-
-    #[test]
-    fn resolve_refuses_escapes() {
-        let root = tempfile::tempdir().unwrap();
-        let store = root.path().join("store-x");
-        fs::create_dir_all(store.join("sealed")).unwrap();
-        fs::write(store.join("sealed/a-1"), b"ok").unwrap();
-        fs::write(root.path().join("secret"), b"no").unwrap();
-        std::os::unix::fs::symlink(root.path().join("secret"), store.join("sealed/a-2")).unwrap();
-        assert!(resolve(root.path(), "store-x", &loc("sealed/a-1")).is_ok());
-        for bad in [
-            "",
-            "/etc/passwd",
-            "../secret",
-            "sealed/../../secret",
-            "./sealed/a-1",
-            "sealed/A-1",
-            "sealed/a-2",
-        ] {
-            assert!(
-                resolve(root.path(), "store-x", &loc(bad)).is_err(),
-                "{bad:?}"
-            );
-        }
-        let other = Location {
-            store_id: "store-y".into(),
-            relative_path: "sealed/a-1".into(),
-        };
-        assert_eq!(
-            resolve(root.path(), "store-x", &other).unwrap_err().code,
-            ErrorCode::ArtifactGone
-        );
-    }
-
-    #[test]
-    fn orphans_are_removed_and_live_stores_kept() {
-        let root = tempfile::tempdir().unwrap();
-        let live = Store::create(root.path(), "store-live").unwrap();
-        let orphan = root.path().join("store-dead");
-        fs::create_dir_all(orphan.join("sealed")).unwrap();
-        fs::write(orphan.join(MARKER), b"").unwrap();
-        fs::write(orphan.join(LOCK), b"").unwrap();
-        let unrelated = root.path().join("keep-me");
-        fs::create_dir_all(&unrelated).unwrap();
-        let second = Store::create(root.path(), "store-next").unwrap();
-        assert!(!orphan.exists());
-        assert!(live.dir().exists() && second.dir().exists() && unrelated.exists());
-        drop(live);
-        assert!(!root.path().join("store-live").exists());
-    }
-}

services/flysim/crates/flybus/src/transport.rs

@@ -1,67 +0,0 @@
-//! Byte-stream transports. Both carry the same framed protocol to the same router code: the
-//! in-memory transport is a Tokio duplex pipe, the other a Unix-domain stream socket.
-
-use std::io;
-use std::path::Path;
-use std::pin::Pin;
-use std::task::{Context, Poll};
-
-use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
-use tokio::net::UnixStream;
-
-/// Anything a connection can run over.
-pub trait Stream: AsyncRead + AsyncWrite + Send + Unpin + 'static {}
-
-impl<T: AsyncRead + AsyncWrite + Send + Unpin + 'static> Stream for T {}
-
-/// One end of a connection to a router.
-pub struct Transport {
-    inner: Box<dyn Stream>,
-}
-
-impl Transport {
-    pub fn from_stream<S: Stream>(stream: S) -> Transport {
-        Transport {
-            inner: Box::new(stream),
-        }
-    }
-
-    /// Connects to a router's Unix-domain socket.
-    pub async fn unix(path: impl AsRef<Path>) -> io::Result<Transport> {
-        Ok(Transport::from_stream(UnixStream::connect(path).await?))
-    }
-
-    /// An in-memory pipe pair: one end for a router, the other for a client.
-    pub(crate) fn pair() -> (Transport, Transport) {
-        let (a, b) = tokio::io::duplex(64 * 1024);
-        (Transport::from_stream(a), Transport::from_stream(b))
-    }
-}
-
-impl AsyncRead for Transport {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        Pin::new(&mut *self.inner).poll_read(cx, buf)
-    }
-}
-
-impl AsyncWrite for Transport {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        Pin::new(&mut *self.inner).poll_write(cx, buf)
-    }
-
-    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut *self.inner).poll_flush(cx)
-    }
-
-    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut *self.inner).poll_shutdown(cx)
-    }
-}

services/flysim/crates/flybus/src/wire.rs

@@ -1,816 +0,0 @@
-//! The wire: scalar encodings, strict JSON, the envelope and its framing (bus-v1 section 4).
-//!
-//! A frame is a `u32` little-endian byte count followed by that many bytes of UTF-8 JSON. The
-//! JSON is parsed strictly: duplicate keys at any depth, invalid UTF-8, non-finite numbers,
-//! trailing bytes and unknown envelope fields are all refused. Both ends use this module, so
-//! the router and the client agree byte for byte on what is valid.
-
-use std::collections::HashSet;
-use std::fmt;
-
-use serde::de::{self, DeserializeSeed, MapAccess, SeqAccess, Visitor};
-use serde_json::{Map, Value};
-use sha2::{Digest as _, Sha256};
-use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
-
-use crate::error::BusError;
-
-pub const PROTOCOL: &str = "flybus";
-pub const MAJOR: u64 = 1;
-pub const MINOR: u64 = 0;
-/// Largest JSON envelope, in bytes, not counting the four-byte length prefix.
-pub const MAX_ENVELOPE_BYTES: usize = 65_536;
-pub const MAX_ATTACHMENTS: usize = 32;
-/// Release and consume batches carry 1..=64 ids.
-pub const MAX_BATCH: usize = 64;
-/// Queue and credit requests are integers in 1..=65535.
-pub const MAX_CREDIT: u64 = 65_535;
-pub const MAX_NAME_LEN: usize = 192;
-pub const MAX_METHOD_LEN: usize = 128;
-pub const MAX_CONTENT_TYPE_LEN: usize = 127;
-/// The one artifact generation v1 issues; ids and inodes are never reused.
-pub const GENERATION: u64 = 1;
-
-/// The operations, delivery and notice shapes this implementation speaks. `contractDigest` is
-/// the SHA-256 of this text, so any change to it changes the digest a client sees in hello.
-pub const CONTRACT: &str = "flybus 1.0
-frame: u32le length, 1..=65536 bytes of strict UTF-8 JSON
-envelope: protocol major minor id replyTo kind op body attachments
-attachment: name ref ownerId
-ref: storeId artifactId generation byteLength contentType digest
-reply: ok value | ok error{code message dispatch}
-bus.hello: clientId clientIncarnation supportedMajors -> routerId connectionId selectedMajor selectedMinor contractDigest limits
-service.register: name maxQueued maxInFlight -> serviceIncarnation
-service.unregister: name serviceIncarnation -> removed
-rpc.call: callId target expectedIncarnation method payload -> accepted serviceIncarnation
-rpc.reply: callId requestDeliveryId outcome -> routed
-rpc.responder.release: callId requestDeliveryId -> released; final attached release emits call.failed dispatched (CALL_GONE, or NO_SERVICE after route loss)
-rpc.cancel: callId -> state(cancelled-before-dispatch|execution-unknown|completed|call-gone)
-topic.declare: name retained(none|latest) -> declared topicIncarnation
-topic.clear: name -> cleared
-topic.delete: name -> deleted
-subscribe: topic mode(latest|bounded) maxQueued maxInFlight replayLatest -> subscriptionId topicIncarnation
-unsubscribe: subscriptionId -> removed
-publish: topic payload -> topicSequence subscribers replaced
-delivery.consumed: deliveryIds -> released
-artifact.allocate: byteLength contentType -> artifactId generation ownerId writeLocation
-artifact.seal: artifactId generation ownerId digest -> ref ownerId
-artifact.open: ref ownerId -> readLocation
-artifact.retain: ref ownerId -> ownerId
-artifact.release: ownerIds -> released
-delivery rpc.request: deliveryId callId caller target serviceIncarnation method payload
-delivery rpc.result: deliveryId callId responder serviceIncarnation outcome
-delivery topic.message: deliveryId subscriptionId topic topicIncarnation topicSequence replaced payload
-notice call.failed: callId code message dispatch
-notice route.removed: name serviceIncarnation reason
-notice subscription.closed: subscriptionId topic topicIncarnation reason
-notice connection.closing: code message
-";
-
-/// SHA-256 of [`CONTRACT`], lowercase hex.
-pub fn contract_digest() -> String {
-    hex(&Sha256::digest(CONTRACT.as_bytes()))
-}
-
-pub(crate) fn hex(bytes: &[u8]) -> String {
-    let mut s = String::with_capacity(bytes.len() * 2);
-    for b in bytes {
-        s.push_str(&format!("{b:02x}"));
-    }
-    s
-}
-
-/// A wire-level validation failure. Always maps to `INVALID_ENVELOPE`.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct WireError(pub String);
-
-impl fmt::Display for WireError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.0)
-    }
-}
-
-impl std::error::Error for WireError {}
-
-impl From<WireError> for BusError {
-    fn from(e: WireError) -> BusError {
-        BusError::invalid(e.0)
-    }
-}
-
-fn err<T>(message: impl Into<String>) -> Result<T, WireError> {
-    Err(WireError(message.into()))
-}
-
-// ---------------------------------------------------------------------------------------------
-// Scalars
-
-/// `Id`: `^[a-z0-9][a-z0-9._-]{0,63}$`.
-pub fn is_id(s: &str) -> bool {
-    let b = s.as_bytes();
-    !b.is_empty()
-        && b.len() <= 64
-        && (b[0].is_ascii_lowercase() || b[0].is_ascii_digit())
-        && b.iter().all(|&c| {
-            c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, b'.' | b'_' | b'-')
-        })
-}
-
-/// `U64`: `"0"` or `[1-9][0-9]*`, at most `u64::MAX`.
-pub fn parse_u64(s: &str) -> Option<u64> {
-    let b = s.as_bytes();
-    if b.is_empty() || b.len() > 20 || (b.len() > 1 && b[0] == b'0') {
-        return None;
-    }
-    let mut n: u64 = 0;
-    for &c in b {
-        if !c.is_ascii_digit() {
-            return None;
-        }
-        n = n.checked_mul(10)?.checked_add(u64::from(c - b'0'))?;
-    }
-    Some(n)
-}
-
-/// `Digest`: 64 lowercase hexadecimal digits.
-pub fn is_digest(s: &str) -> bool {
-    s.len() == 64
-        && s.bytes()
-            .all(|c| c.is_ascii_digit() || (b'a'..=b'f').contains(&c))
-}
-
-/// Service and topic names: 1..=192 of `[a-z0-9._-]`, no empty dot-separated segment.
-pub fn is_name(s: &str) -> bool {
-    !s.is_empty()
-        && s.len() <= MAX_NAME_LEN
-        && s.bytes().all(|c| {
-            c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, b'.' | b'_' | b'-')
-        })
-        && s.split('.').all(|seg| !seg.is_empty())
-}
-
-/// RPC method: 1..=128 printable ASCII characters.
-pub fn is_method(s: &str) -> bool {
-    !s.is_empty() && s.len() <= MAX_METHOD_LEN && s.bytes().all(|c| (0x20..=0x7e).contains(&c))
-}
-
-/// Content type: 1..=127 printable ASCII characters.
-pub fn is_content_type(s: &str) -> bool {
-    !s.is_empty()
-        && s.len() <= MAX_CONTENT_TYPE_LEN
-        && s.bytes().all(|c| (0x20..=0x7e).contains(&c))
-}
-
-/// Operation names: 1..=64 of `[a-z.]`.
-pub fn is_op(s: &str) -> bool {
-    !s.is_empty() && s.len() <= 64 && s.bytes().all(|c| c.is_ascii_lowercase() || c == b'.')
-}
-
-/// `<prefix>-<U64>`, the canonical form of every serial-numbered id on the bus.
-pub fn serial_id(prefix: &str, n: u64) -> String {
-    format!("{prefix}-{n}")
-}
-
-/// Parses `<prefix>-<U64>`; `None` unless canonical.
-pub fn parse_serial_id(prefix: &str, s: &str) -> Option<u64> {
-    s.strip_prefix(prefix)?
-        .strip_prefix('-')
-        .and_then(parse_u64)
-}
-
-// ---------------------------------------------------------------------------------------------
-// Strict JSON
-
-/// Parses one JSON value, refusing duplicate object keys at any depth, invalid UTF-8,
-/// non-finite numbers and trailing data. Nesting depth is bounded by serde_json's recursion
-/// limit (128).
-pub fn parse_json_strict(bytes: &[u8]) -> Result<Value, WireError> {
-    if std::str::from_utf8(bytes).is_err() {
-        return err("invalid UTF-8");
-    }
-    let mut de = serde_json::Deserializer::from_slice(bytes);
-    let value = StrictSeed
-        .deserialize(&mut de)
-        .map_err(|e| WireError(format!("invalid JSON: {e}")))?;
-    de.end()
-        .map_err(|e| WireError(format!("invalid JSON: {e}")))?;
-    Ok(value)
-}
-
-struct StrictSeed;
-
-impl<'de> DeserializeSeed<'de> for StrictSeed {
-    type Value = Value;
-
-    fn deserialize<D: de::Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
-        d.deserialize_any(StrictVisitor)
-    }
-}
-
-struct StrictVisitor;
-
-impl<'de> Visitor<'de> for StrictVisitor {
-    type Value = Value;
-
-    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str("a JSON value")
-    }
-
-    fn visit_bool<E>(self, v: bool) -> Result<Value, E> {
-        Ok(Value::Bool(v))
-    }
-
-    fn visit_i64<E>(self, v: i64) -> Result<Value, E> {
-        Ok(Value::from(v))
-    }
-
-    fn visit_u64<E>(self, v: u64) -> Result<Value, E> {
-        Ok(Value::from(v))
-    }
-
-    fn visit_f64<E: de::Error>(self, v: f64) -> Result<Value, E> {
-        serde_json::Number::from_f64(v)
-            .map(Value::Number)
-            .ok_or_else(|| E::custom("non-finite number"))
-    }
-
-    fn visit_str<E>(self, v: &str) -> Result<Value, E> {
-        Ok(Value::String(v.to_owned()))
-    }
-
-    fn visit_string<E>(self, v: String) -> Result<Value, E> {
-        Ok(Value::String(v))
-    }
-
-    fn visit_unit<E>(self) -> Result<Value, E> {
-        Ok(Value::Null)
-    }
-
-    fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
-        let mut out = Vec::new();
-        while let Some(v) = seq.next_element_seed(StrictSeed)? {
-            out.push(v);
-        }
-        Ok(Value::Array(out))
-    }
-
-    fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Value, A::Error> {
-        let mut out = Map::new();
-        while let Some(key) = map.next_key::<String>()? {
-            if out.contains_key(&key) {
-                return Err(de::Error::custom(format!("duplicate key {key:?}")));
-            }
-            let v = map.next_value_seed(StrictSeed)?;
-            out.insert(key, v);
-        }
-        Ok(Value::Object(out))
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Exact-field object reader
-
-/// Reads the fields of one JSON object, then refuses any it did not read.
-pub struct Fields<'a> {
-    map: &'a Map<String, Value>,
-    seen: HashSet<&'static str>,
-    what: &'static str,
-}
-
-impl<'a> Fields<'a> {
-    pub fn new(v: &'a Value, what: &'static str) -> Result<Fields<'a>, WireError> {
-        match v {
-            Value::Object(map) => Ok(Fields::of(map, what)),
-            _ => err(format!("{what} must be an object")),
-        }
-    }
-
-    pub fn of(map: &'a Map<String, Value>, what: &'static str) -> Fields<'a> {
-        Fields {
-            map,
-            seen: HashSet::new(),
-            what,
-        }
-    }
-
-    pub fn value(&mut self, key: &'static str) -> Result<&'a Value, WireError> {
-        self.seen.insert(key);
-        match self.map.get(key) {
-            Some(v) => Ok(v),
-            None => err(format!("{}: missing field {key:?}", self.what)),
-        }
-    }
-
-    pub fn string(&mut self, key: &'static str) -> Result<&'a str, WireError> {
-        let what = self.what;
-        self.value(key)?
-            .as_str()
-            .ok_or_else(|| WireError(format!("{what}: {key} must be a string")))
-    }
-
-    fn checked(
-        &mut self,
-        key: &'static str,
-        ok: fn(&str) -> bool,
-        kind: &str,
-    ) -> Result<String, WireError> {
-        let s = self.string(key)?;
-        if ok(s) {
-            Ok(s.to_owned())
-        } else {
-            err(format!("{}: {key} is not a valid {kind}", self.what))
-        }
-    }
-
-    pub fn id(&mut self, key: &'static str) -> Result<String, WireError> {
-        self.checked(key, is_id, "id")
-    }
-
-    pub fn nullable_id(&mut self, key: &'static str) -> Result<Option<String>, WireError> {
-        match self.value(key)? {
-            Value::Null => Ok(None),
-            _ => self.id(key).map(Some),
-        }
-    }
-
-    pub fn name(&mut self, key: &'static str) -> Result<String, WireError> {
-        self.checked(key, is_name, "name")
-    }
-
-    pub fn method(&mut self, key: &'static str) -> Result<String, WireError> {
-        self.checked(key, is_method, "method")
-    }
-
-    pub fn u64_string(&mut self, key: &'static str) -> Result<u64, WireError> {
-        let s = self.string(key)?;
-        parse_u64(s).ok_or_else(|| {
-            WireError(format!(
-                "{}: {key} is not a canonical U64 string",
-                self.what
-            ))
-        })
-    }
-
-    /// A JSON integer in `lo..=hi`.
-    pub fn int(&mut self, key: &'static str, lo: u64, hi: u64) -> Result<u64, WireError> {
-        let what = self.what;
-        match self.value(key)?.as_u64() {
-            Some(n) if (lo..=hi).contains(&n) => Ok(n),
-            _ => err(format!("{what}: {key} must be an integer in {lo}..={hi}")),
-        }
-    }
-
-    pub fn boolean(&mut self, key: &'static str) -> Result<bool, WireError> {
-        let what = self.what;
-        self.value(key)?
-            .as_bool()
-            .ok_or_else(|| WireError(format!("{what}: {key} must be a boolean")))
-    }
-
-    pub fn object(&mut self, key: &'static str) -> Result<&'a Map<String, Value>, WireError> {
-        let what = self.what;
-        self.value(key)?
-            .as_object()
-            .ok_or_else(|| WireError(format!("{what}: {key} must be an object")))
-    }
-
-    pub fn array(
-        &mut self,
-        key: &'static str,
-        lo: usize,
-        hi: usize,
-    ) -> Result<&'a Vec<Value>, WireError> {
-        let what = self.what;
-        match self.value(key)?.as_array() {
-            Some(a) if (lo..=hi).contains(&a.len()) => Ok(a),
-            _ => err(format!(
-                "{what}: {key} must be an array of {lo}..={hi} items"
-            )),
-        }
-    }
-
-    /// Refuses fields that were not read.
-    pub fn finish(self) -> Result<(), WireError> {
-        if let Some(extra) = self.map.keys().find(|k| !self.seen.contains(k.as_str())) {
-            return err(format!("{}: unknown field {extra:?}", self.what));
-        }
-        Ok(())
-    }
-}
-
-/// An array of ids, each `<prefix>-<U64>`, 1..=64 of them.
-pub fn id_batch(v: &[Value], what: &str) -> Result<Vec<String>, WireError> {
-    let mut out = Vec::with_capacity(v.len());
-    for item in v {
-        match item.as_str() {
-            Some(s) if is_id(s) => out.push(s.to_owned()),
-            _ => return err(format!("{what}: every entry must be an id")),
-        }
-    }
-    Ok(out)
-}
-
-// ---------------------------------------------------------------------------------------------
-// Shared structures
-
-/// An immutable artifact's identity. Not an address and not authority to read.
-#[derive(Clone, Debug, PartialEq, Eq, Hash)]
-pub struct ArtifactRef {
-    pub store_id: String,
-    pub artifact_id: String,
-    pub generation: u64,
-    pub byte_length: u64,
-    pub content_type: String,
-    pub digest: Option<String>,
-}
-
-impl ArtifactRef {
-    pub fn to_json(&self) -> Value {
-        let mut m = Map::new();
-        m.insert("storeId".into(), self.store_id.clone().into());
-        m.insert("artifactId".into(), self.artifact_id.clone().into());
-        m.insert("generation".into(), self.generation.to_string().into());
-        m.insert("byteLength".into(), self.byte_length.to_string().into());
-        m.insert("contentType".into(), self.content_type.clone().into());
-        m.insert(
-            "digest".into(),
-            self.digest.clone().map_or(Value::Null, Value::String),
-        );
-        Value::Object(m)
-    }
-
-    pub fn from_json(v: &Value) -> Result<ArtifactRef, WireError> {
-        let mut f = Fields::new(v, "ref")?;
-        let store_id = f.id("storeId")?;
-        let artifact_id = f.id("artifactId")?;
-        let generation = f.u64_string("generation")?;
-        let byte_length = f.u64_string("byteLength")?;
-        let content_type = f.string("contentType")?;
-        if !is_content_type(content_type) {
-            return err("ref: contentType must be 1..=127 printable ASCII characters");
-        }
-        let digest = match f.value("digest")? {
-            Value::Null => None,
-            Value::String(s) if is_digest(s) => Some(s.clone()),
-            _ => return err("ref: digest must be null or 64 lowercase hex digits"),
-        };
-        f.finish()?;
-        Ok(ArtifactRef {
-            store_id,
-            artifact_id,
-            generation,
-            byte_length,
-            content_type: content_type.to_owned(),
-            digest,
-        })
-    }
-}
-
-/// One attachment entry: an application name, the reference and the sender's owner token.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Attachment {
-    pub name: String,
-    pub reference: ArtifactRef,
-    pub owner_id: String,
-}
-
-impl Attachment {
-    pub fn to_json(&self) -> Value {
-        let mut m = Map::new();
-        m.insert("name".into(), self.name.clone().into());
-        m.insert("ref".into(), self.reference.to_json());
-        m.insert("ownerId".into(), self.owner_id.clone().into());
-        Value::Object(m)
-    }
-
-    pub fn from_json(v: &Value) -> Result<Attachment, WireError> {
-        let mut f = Fields::new(v, "attachment")?;
-        let name = f.id("name")?;
-        let reference = ArtifactRef::from_json(f.value("ref")?)?;
-        let owner_id = f.id("ownerId")?;
-        f.finish()?;
-        Ok(Attachment {
-            name,
-            reference,
-            owner_id,
-        })
-    }
-}
-
-/// A store location grant: a path relative to `<store root>/<storeId>`. SDK-private.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Location {
-    pub store_id: String,
-    pub relative_path: String,
-}
-
-impl Location {
-    pub fn to_json(&self) -> Value {
-        let mut m = Map::new();
-        m.insert("storeId".into(), self.store_id.clone().into());
-        m.insert("relativePath".into(), self.relative_path.clone().into());
-        Value::Object(m)
-    }
-
-    pub fn from_json(v: &Value) -> Result<Location, WireError> {
-        let mut f = Fields::new(v, "location")?;
-        let store_id = f.id("storeId")?;
-        let relative_path = f.string("relativePath")?.to_owned();
-        f.finish()?;
-        Ok(Location {
-            store_id,
-            relative_path,
-        })
-    }
-}
-
-/// A participant identity as the router reports it on deliveries. It is authenticated only
-/// when the connection was accepted through a launcher-bound transport entry point.
-#[derive(Clone, Debug, PartialEq, Eq, Hash)]
-pub struct Identity {
-    pub client_id: String,
-    pub client_incarnation: String,
-}
-
-impl Identity {
-    pub fn to_json(&self) -> Value {
-        let mut m = Map::new();
-        m.insert("clientId".into(), self.client_id.clone().into());
-        m.insert(
-            "clientIncarnation".into(),
-            self.client_incarnation.clone().into(),
-        );
-        Value::Object(m)
-    }
-
-    pub fn from_json(v: &Value) -> Result<Identity, WireError> {
-        let mut f = Fields::new(v, "identity")?;
-        let client_id = f.id("clientId")?;
-        let client_incarnation = f.id("clientIncarnation")?;
-        f.finish()?;
-        Ok(Identity {
-            client_id,
-            client_incarnation,
-        })
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Envelope
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum Kind {
-    Command,
-    Reply,
-    Delivery,
-    Notice,
-}
-
-impl Kind {
-    pub fn as_str(self) -> &'static str {
-        match self {
-            Kind::Command => "command",
-            Kind::Reply => "reply",
-            Kind::Delivery => "delivery",
-            Kind::Notice => "notice",
-        }
-    }
-
-    fn parse(s: &str) -> Option<Kind> {
-        match s {
-            "command" => Some(Kind::Command),
-            "reply" => Some(Kind::Reply),
-            "delivery" => Some(Kind::Delivery),
-            "notice" => Some(Kind::Notice),
-            _ => None,
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq)]
-pub struct Envelope {
-    pub major: u64,
-    pub minor: u64,
-    pub id: String,
-    pub reply_to: Option<String>,
-    pub kind: Kind,
-    pub op: String,
-    pub body: Map<String, Value>,
-    pub attachments: Vec<Attachment>,
-}
-
-impl Envelope {
-    pub fn new(id: String, kind: Kind, op: &str, body: Map<String, Value>) -> Envelope {
-        Envelope {
-            major: MAJOR,
-            minor: MINOR,
-            id,
-            reply_to: None,
-            kind,
-            op: op.to_owned(),
-            body,
-            attachments: Vec::new(),
-        }
-    }
-
-    /// Decodes and validates one frame's bytes.
-    pub fn decode(bytes: &[u8]) -> Result<Envelope, WireError> {
-        if bytes.is_empty() {
-            return err("empty envelope");
-        }
-        if bytes.len() > MAX_ENVELOPE_BYTES {
-            return err(format!(
-                "envelope of {} bytes exceeds {MAX_ENVELOPE_BYTES}",
-                bytes.len()
-            ));
-        }
-        let v = parse_json_strict(bytes)?;
-        let mut f = Fields::new(&v, "envelope")?;
-        if f.string("protocol")? != PROTOCOL {
-            return err("envelope: protocol must be \"flybus\"");
-        }
-        let major = f.int("major", 0, MAX_CREDIT)?;
-        let minor = f.int("minor", 0, MAX_CREDIT)?;
-        let id = f.id("id")?;
-        let reply_to = f.nullable_id("replyTo")?;
-        let kind = Kind::parse(f.string("kind")?)
-            .ok_or_else(|| WireError("envelope: unknown kind".into()))?;
-        let op = f.string("op")?;
-        if !is_op(op) {
-            return err("envelope: op must be 1..=64 of [a-z.]");
-        }
-        let op = op.to_owned();
-        let body = f.object("body")?.clone();
-        let raw = f.array("attachments", 0, MAX_ATTACHMENTS)?;
-        let mut attachments = Vec::with_capacity(raw.len());
-        let mut names = HashSet::new();
-        for a in raw {
-            let a = Attachment::from_json(a)?;
-            if !names.insert(a.name.clone()) {
-                return err(format!("envelope: duplicate attachment name {:?}", a.name));
-            }
-            attachments.push(a);
-        }
-        f.finish()?;
-        Ok(Envelope {
-            major,
-            minor,
-            id,
-            reply_to,
-            kind,
-            op,
-            body,
-            attachments,
-        })
-    }
-
-    pub fn to_value(&self) -> Value {
-        let mut m = Map::new();
-        m.insert("protocol".into(), PROTOCOL.into());
-        m.insert("major".into(), self.major.into());
-        m.insert("minor".into(), self.minor.into());
-        m.insert("id".into(), self.id.clone().into());
-        m.insert(
-            "replyTo".into(),
-            self.reply_to.clone().map_or(Value::Null, Value::String),
-        );
-        m.insert("kind".into(), self.kind.as_str().into());
-        m.insert("op".into(), self.op.clone().into());
-        m.insert("body".into(), Value::Object(self.body.clone()));
-        m.insert(
-            "attachments".into(),
-            Value::Array(self.attachments.iter().map(Attachment::to_json).collect()),
-        );
-        Value::Object(m)
-    }
-
-    /// Serializes, refusing anything over [`MAX_ENVELOPE_BYTES`].
-    pub fn encode(&self) -> Result<Vec<u8>, WireError> {
-        let bytes = serde_json::to_vec(&self.to_value()).map_err(|e| WireError(e.to_string()))?;
-        if bytes.len() > MAX_ENVELOPE_BYTES {
-            return err(format!(
-                "envelope of {} bytes exceeds {MAX_ENVELOPE_BYTES}",
-                bytes.len()
-            ));
-        }
-        Ok(bytes)
-    }
-}
-
-// ---------------------------------------------------------------------------------------------
-// Framing
-
-#[derive(Debug)]
-pub enum FrameError {
-    Io(std::io::Error),
-    /// A zero length prefix.
-    Empty,
-    /// The length prefix exceeds the limit; nothing was allocated for it.
-    TooLarge(u32),
-    /// End of stream inside a frame.
-    Truncated,
-}
-
-impl fmt::Display for FrameError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            FrameError::Io(e) => write!(f, "I/O error: {e}"),
-            FrameError::Empty => f.write_str("zero-length frame"),
-            FrameError::TooLarge(n) => write!(f, "frame of {n} bytes exceeds {MAX_ENVELOPE_BYTES}"),
-            FrameError::Truncated => f.write_str("stream ended inside a frame"),
-        }
-    }
-}
-
-impl std::error::Error for FrameError {}
-
-/// Reads one frame. `Ok(None)` is a clean end of stream at a frame boundary. The length is
-/// checked against [`MAX_ENVELOPE_BYTES`] before any buffer is allocated.
-pub async fn read_frame<R: AsyncRead + Unpin>(r: &mut R) -> Result<Option<Vec<u8>>, FrameError> {
-    let mut len = [0u8; 4];
-    let mut got = 0;
-    while got < 4 {
-        let n = r.read(&mut len[got..]).await.map_err(FrameError::Io)?;
-        if n == 0 {
-            return if got == 0 {
-                Ok(None)
-            } else {
-                Err(FrameError::Truncated)
-            };
-        }
-        got += n;
-    }
-    let len = u32::from_le_bytes(len);
-    if len == 0 {
-        return Err(FrameError::Empty);
-    }
-    if len as usize > MAX_ENVELOPE_BYTES {
-        return Err(FrameError::TooLarge(len));
-    }
-    let mut buf = vec![0u8; len as usize];
-    r.read_exact(&mut buf).await.map_err(|e| match e.kind() {
-        std::io::ErrorKind::UnexpectedEof => FrameError::Truncated,
-        _ => FrameError::Io(e),
-    })?;
-    Ok(Some(buf))
-}
-
-/// Writes one frame: the length prefix and the bytes, as one buffer.
-pub async fn write_frame<W: AsyncWrite + Unpin>(w: &mut W, bytes: &[u8]) -> std::io::Result<()> {
-    debug_assert!(!bytes.is_empty() && bytes.len() <= MAX_ENVELOPE_BYTES);
-    let mut buf = Vec::with_capacity(bytes.len() + 4);
-    buf.extend_from_slice(&(bytes.len() as u32).to_le_bytes());
-    buf.extend_from_slice(bytes);
-    w.write_all(&buf).await?;
-    w.flush().await
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn scalars() {
-        assert!(is_id("a") && is_id("msg-7") && is_id("0.a_b-c"));
-        assert!(!is_id("") && !is_id("-a") && !is_id("A") && !is_id(&"a".repeat(65)));
-        assert!(is_id(&"a".repeat(64)));
-        assert_eq!(parse_u64("0"), Some(0));
-        assert_eq!(parse_u64("18446744073709551615"), Some(u64::MAX));
-        for bad in ["", "01", "18446744073709551616", "-1", "1.0", "+1", " 1"] {
-            assert_eq!(parse_u64(bad), None, "{bad:?}");
-        }
-        assert!(is_name("session.demo.snapshots") && is_name(&"a".repeat(192)));
-        for bad in ["", ".a", "a.", "a..b", "A", "a/b", &"a".repeat(193)] {
-            assert!(!is_name(bad), "{bad:?}");
-        }
-        assert!(is_digest(&"0f".repeat(32)) && !is_digest(&"0F".repeat(32)) && !is_digest("00"));
-        assert_eq!(parse_serial_id("msg", "msg-12"), Some(12));
-        assert_eq!(parse_serial_id("msg", "msg-012"), None);
-        assert_eq!(parse_serial_id("msg", "msgx-1"), None);
-        assert!(is_method("Counter.Increment") && !is_method("a\u{7f}") && !is_method(""));
-    }
-
-    #[test]
-    fn strict_json() {
-        assert!(parse_json_strict(br#"{"a":{"b":[{"c":1,"d":2}]}}"#).is_ok());
-        for bad in [
-            &br#"{"a":1,"a":2}"#[..],
-            br#"{"a":{"b":[{"c":1,"c":2}]}}"#,
-            br#"[{"x":1},{"y":{"z":1,"z":1}}]"#,
-            br#"{"a":NaN}"#,
-            br#"{"a":Infinity}"#,
-            br#"{"a":1e400}"#,
-            br#"{"a":"\ud800"}"#,
-            br#"{"a":1} x"#,
-            b"{\"a\":\"\xff\"}",
-        ] {
-            assert!(
-                parse_json_strict(bad).is_err(),
-                "{:?}",
-                String::from_utf8_lossy(bad)
-            );
-        }
-        let deep = format!("{}{}", "[".repeat(200), "]".repeat(200));
-        assert!(parse_json_strict(deep.as_bytes()).is_err());
-    }
-}

services/flysim/crates/flybus/tests/artifacts.rs

@@ -1,704 +0,0 @@
-//! Artifacts: allocate/seal/read, immutability against live writable handles, ownership
-//! through fan-out and retention, quotas, atomic admission, watermarked releases, abandoned
-//! futures, disconnects and router restarts.
-
-mod common;
-
-use std::io::{Seek, SeekFrom, Write};
-use std::os::unix::fs::PermissionsExt;
-use std::time::Duration;
-
-use common::{Via, code, env, env_with, obj, quiet, sealed, within};
-use flybus::{
-    ErrorCode, Limits, Policy, Retained, Router, RouterConfig, ServiceConfig, SubscriptionConfig,
-};
-use serde_json::{Value, json};
-use sha2::{Digest, Sha256};
-
-fn sha(bytes: &[u8]) -> String {
-    Sha256::digest(bytes)
-        .iter()
-        .map(|b| format!("{b:02x}"))
-        .collect()
-}
-
-async fn allocate_write_seal_read(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    let data: Vec<u8> = (0..100_000u32).map(|i| (i % 251) as u8).collect();
-    let mut w = c
-        .artifacts()
-        .allocate(data.len() as u64, "application/octet-stream")
-        .await
-        .unwrap();
-    assert!(
-        w.write_all(&[0; 100_001]).is_err(),
-        "writes past the allocation are refused"
-    );
-    w.write_all(&data).unwrap();
-    assert_eq!(e.files("staging"), 1);
-    let art = w.seal_with_digest(Some(sha(&data))).await.unwrap();
-    let r = art.reference();
-    assert_eq!(
-        (r.generation, r.byte_length, r.digest.clone()),
-        (1, 100_000, Some(sha(&data)))
-    );
-    assert_eq!(r.store_id, e.router.store_id());
-    assert_eq!(art.read_all().await.unwrap(), data);
-    assert_eq!((e.files("staging"), e.files("sealed")), (0, 1));
-    let meta = std::fs::metadata(e.router.store_dir().join("sealed").join(&r.artifact_id)).unwrap();
-    assert_eq!(
-        meta.permissions().mode() & 0o222,
-        0,
-        "sealed files are read-only"
-    );
-
-    let empty = c
-        .artifacts()
-        .allocate(0, "text/plain")
-        .await
-        .unwrap()
-        .seal()
-        .await
-        .unwrap();
-    assert!(empty.read_all().await.unwrap().is_empty());
-    assert_eq!(
-        c.artifacts().allocate(1, "").await.unwrap_err().code,
-        ErrorCode::InvalidEnvelope
-    );
-    drop((art, empty));
-    e.settle("collected", |s| s.artifacts == 0 && s.store_bytes == 0)
-        .await;
-    e.settle_files("sealed", 0).await;
-}
-
-async fn unsealed_artifacts_cannot_be_used(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("raw").await;
-    assert_eq!(
-        code(
-            &raw.call("topic.declare", json!({"name": "t.x", "retained": "none"}))
-                .await
-        ),
-        "OK"
-    );
-    let (a, _) = raw.allocate(8).await;
-    let store = a["writeLocation"]["storeId"].clone();
-    let reference = json!({"storeId": store, "artifactId": a["artifactId"], "generation": "1", "byteLength": "8",
-        "contentType": "application/octet-stream", "digest": null});
-    let att = json!([{"name": "x", "ref": reference, "ownerId": a["ownerId"]}]);
-    let r = raw
-        .call_with("publish", json!({"topic": "t.x", "payload": {}}), att)
-        .await;
-    assert_eq!(code(&r), "ARTIFACT_UNSEALED");
-    let r = raw
-        .call(
-            "artifact.open",
-            json!({"ref": reference, "ownerId": a["ownerId"]}),
-        )
-        .await;
-    assert_eq!(code(&r), "ARTIFACT_UNSEALED");
-    let r = raw
-        .call(
-            "artifact.retain",
-            json!({"ref": reference, "ownerId": a["ownerId"]}),
-        )
-        .await;
-    assert_eq!(code(&r), "ARTIFACT_UNSEALED");
-    assert_eq!(code(&raw.seal(&a, Value::Null).await), "OK");
-    assert_eq!(
-        code(&raw.seal(&a, Value::Null).await),
-        "OWNER_INVALID",
-        "a writer seals once"
-    );
-    assert_eq!(
-        code(
-            &raw.call(
-                "artifact.allocate",
-                json!({"byteLength": "01", "contentType": "x"})
-            )
-            .await
-        ),
-        "INVALID_ENVELOPE"
-    );
-}
-
-/// A producer that kept (or duplicated) its writable descriptor cannot change sealed bytes.
-async fn seal_is_immune_to_live_writable_handles(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("raw").await;
-    let (a, path) = raw.allocate(8).await;
-    let mut kept = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
-    kept.write_all(b"AAAAAAAA").unwrap();
-    let mut dup = kept.try_clone().unwrap();
-    let sealed = raw.seal(&a, json!(sha(b"AAAAAAAA"))).await.unwrap();
-    // Both descriptors still write, into an inode the store no longer uses.
-    dup.seek(SeekFrom::Start(0)).unwrap();
-    let _ = dup.write_all(b"BBBBBBBB");
-    let _ = kept.write_all(b"CCCC");
-    assert!(!path.exists(), "staging is unlinked after sealing");
-    let open = raw
-        .call(
-            "artifact.open",
-            json!({"ref": sealed["ref"], "ownerId": sealed["ownerId"]}),
-        )
-        .await
-        .unwrap();
-    let read_path = raw.path(&open["readLocation"]);
-    assert_eq!(std::fs::read(&read_path).unwrap(), b"AAAAAAAA");
-    assert_eq!(
-        std::fs::metadata(&read_path).unwrap().permissions().mode() & 0o222,
-        0
-    );
-}
-
-async fn seal_checks_length_and_digest(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("raw").await;
-    let (short, path) = raw.allocate(4).await;
-    std::fs::OpenOptions::new()
-        .write(true)
-        .open(&path)
-        .unwrap()
-        .set_len(2)
-        .unwrap();
-    assert_eq!(
-        code(&raw.seal(&short, Value::Null).await),
-        "ARTIFACT_MISMATCH"
-    );
-    let (long, path) = raw.allocate(4).await;
-    std::fs::OpenOptions::new()
-        .write(true)
-        .open(&path)
-        .unwrap()
-        .set_len(6)
-        .unwrap();
-    assert_eq!(
-        code(&raw.seal(&long, Value::Null).await),
-        "ARTIFACT_MISMATCH"
-    );
-    let (bad, _) = raw.allocate(4).await;
-    assert_eq!(
-        code(&raw.seal(&bad, json!("XYZ")).await),
-        "INVALID_ENVELOPE"
-    );
-    assert_eq!(
-        code(&raw.seal(&bad, json!("0".repeat(64))).await),
-        "ARTIFACT_MISMATCH"
-    );
-    // Failed seals clean up both the staging file and the copy.
-    let s = e.settle("failed seals cleaned", |s| s.artifacts == 0).await;
-    assert_eq!((s.store_bytes, s.owners), (0, 0));
-    e.settle_files("staging", 0).await;
-    e.settle_files("sealed", 0).await;
-
-    let c = e.client("c").await;
-    let mut w = c.artifacts().allocate(3, "text/plain").await.unwrap();
-    w.write_all(b"abc").unwrap();
-    let err = w.seal_with_digest(Some(sha(b"abd"))).await.unwrap_err();
-    assert_eq!(err.code, ErrorCode::ArtifactMismatch);
-    e.settle("sdk seal cleaned", |s| {
-        s.artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-}
-
-async fn quotas_are_enforced(via: Via) {
-    let limits = Limits {
-        max_store_bytes: 1000,
-        max_artifact_bytes: 600,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let c = e.client("c").await;
-    assert_eq!(
-        c.artifacts().allocate(601, "x/y").await.unwrap_err().code,
-        ErrorCode::QuotaExceeded
-    );
-    let w = c.artifacts().allocate(600, "x/y").await.unwrap();
-    assert_eq!(
-        c.artifacts().allocate(401, "x/y").await.unwrap_err().code,
-        ErrorCode::QuotaExceeded
-    );
-    // Sealing copies, so it needs room for both; failing releases the staging object.
-    assert_eq!(w.seal().await.unwrap_err().code, ErrorCode::QuotaExceeded);
-    e.settle("staging released", |s| s.store_bytes == 0 && s.owners == 0)
-        .await;
-
-    let limits = Limits {
-        max_store_bytes: 1200,
-        max_artifact_bytes: 600,
-        max_owners_per_client: 4,
-        reserved_owners_per_client: 1,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let c = e.client("c").await;
-    let art = c
-        .artifacts()
-        .allocate(600, "x/y")
-        .await
-        .unwrap()
-        .seal()
-        .await
-        .unwrap();
-    assert_eq!(e.stats().store_bytes, 600);
-    let _w1 = c.artifacts().allocate(1, "x/y").await.unwrap();
-    let _w2 = c.artifacts().allocate(1, "x/y").await.unwrap();
-    assert_eq!(
-        c.artifacts().allocate(1, "x/y").await.unwrap_err().code,
-        ErrorCode::QuotaExceeded
-    );
-    assert_eq!(
-        art.retain().await.unwrap_err().code,
-        ErrorCode::QuotaExceeded
-    );
-}
-
-async fn fan_out_shares_one_object_and_the_last_consumer_collects(via: Via) {
-    let e = env(via).await;
-    let camera = e.client("camera").await;
-    camera
-        .declare_topic("world.demo.frame", Retained::None)
-        .await
-        .unwrap();
-    let mut viewers = Vec::new();
-    for i in 0..3 {
-        let c = e.client(&format!("viewer-{i}")).await;
-        let s = c
-            .subscribe("world.demo.frame", SubscriptionConfig::bounded())
-            .await
-            .unwrap();
-        viewers.push((c, s));
-    }
-    let frame: Vec<u8> = (0..640 * 480 * 4).map(|i| (i % 256) as u8).collect();
-    let art = sealed(&camera, &frame, "image/x-rgba").await;
-    let r = camera
-        .publish(
-            "world.demo.frame",
-            obj(json!({"width": 640, "height": 480})),
-            &[("frame", &art)],
-        )
-        .await
-        .unwrap();
-    assert_eq!(r.subscribers, 3);
-    drop(art);
-    let mut messages = Vec::new();
-    for (_, s) in viewers.iter_mut() {
-        let m = within("frame", s.next()).await.unwrap();
-        assert_eq!(
-            m.artifact("frame").unwrap().read_all().await.unwrap(),
-            frame
-        );
-        messages.push(m);
-    }
-    let s = e
-        .settle("three deliveries of one object", |s| s.artifact_roots == 3)
-        .await;
-    assert_eq!((s.sealed_artifacts, s.store_bytes), (1, frame.len() as u64));
-    assert_eq!(e.files("sealed"), 1, "fan-out never copies bytes");
-    let path = e.router.store_dir().join("sealed").join(
-        &messages[0]
-            .artifact("frame")
-            .unwrap()
-            .reference()
-            .artifact_id,
-    );
-    for (i, m) in messages.drain(..).enumerate() {
-        drop(m);
-        let left = 2 - i as u64;
-        e.settle("one root per consumer", |s| s.artifact_roots == left)
-            .await;
-        if left > 0 {
-            assert!(
-                path.exists(),
-                "collected while {left} consumers still hold it"
-            );
-        }
-    }
-    e.settle_files("sealed", 0).await;
-    e.settle("collected", |s| s.artifacts == 0 && s.store_bytes == 0)
-        .await;
-}
-
-async fn extracted_artifacts_outlive_their_message(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    let r = e.client("r").await;
-    p.declare_topic("t.hold", Retained::None).await.unwrap();
-    let mut sub = r
-        .subscribe("t.hold", SubscriptionConfig::bounded().in_flight(1))
-        .await
-        .unwrap();
-    for i in 0..3 {
-        let a = sealed(&p, format!("f{i}").as_bytes(), "text/plain").await;
-        p.publish("t.hold", obj(json!({})), &[("f", &a)])
-            .await
-            .unwrap();
-    }
-    let m = within("first", sub.next()).await.unwrap();
-    let image = m.artifact("f").unwrap();
-    drop(m);
-    // The extracted handle still owns the delivery, so the credit is not back yet.
-    quiet("credit held by the extracted artifact", sub.next()).await;
-    assert_eq!(image.read_all().await.unwrap(), b"f0");
-    let file = image.open().await.unwrap();
-    drop(image);
-    quiet("credit held by the open file", sub.next()).await;
-    drop(file);
-    let m = within("second", sub.next()).await.unwrap();
-    // An explicit hold outlives the delivery and does not keep its credit.
-    let kept = m.artifact("f").unwrap().retain().await.unwrap();
-    drop(m);
-    let third = within("third", sub.next()).await.unwrap();
-    assert_eq!(kept.read_all().await.unwrap(), b"f1");
-    drop((third, kept));
-    e.settle("collected", |s| s.artifacts == 0 && s.owners == 0)
-        .await;
-}
-
-async fn failed_admission_is_atomic(via: Via) {
-    let e = env(via).await;
-    let reader = e.client("reader").await;
-    let server = e.client("server").await;
-    let mut raw = e.raw_hello("raw").await;
-    assert_eq!(
-        code(
-            &raw.call(
-                "topic.declare",
-                json!({"name": "t.atomic", "retained": "latest"})
-            )
-            .await
-        ),
-        "OK"
-    );
-    let mut sub = reader
-        .subscribe("t.atomic", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let mut svc = server
-        .register("example.atomic", ServiceConfig::default())
-        .await
-        .unwrap();
-    let (a, path) = raw.allocate(3).await;
-    std::fs::write(&path, b"abc").unwrap();
-    let s = raw.seal(&a, Value::Null).await.unwrap();
-    let good = |name: &str| json!({"name": name, "ref": s["ref"], "ownerId": s["ownerId"]});
-    let before = e.stats();
-    let mut wrong_len = s["ref"].clone();
-    wrong_len["byteLength"] = json!("4");
-    let mut other_store = s["ref"].clone();
-    other_store["storeId"] = json!("store-0000000000000000");
-    let cases = [
-        (
-            json!([good("a"), {"name": "b", "ref": s["ref"], "ownerId": "own-7"}]),
-            "OWNER_INVALID",
-        ),
-        (
-            json!([good("a"), {"name": "b", "ref": wrong_len, "ownerId": s["ownerId"]}]),
-            "ARTIFACT_MISMATCH",
-        ),
-        (
-            json!([good("a"), {"name": "b", "ref": other_store, "ownerId": s["ownerId"]}]),
-            "ARTIFACT_GONE",
-        ),
-    ];
-    for (i, (atts, want)) in cases.iter().enumerate() {
-        let r = raw
-            .call_with(
-                "publish",
-                json!({"topic": "t.atomic", "payload": {}}),
-                atts.clone(),
-            )
-            .await;
-        assert_eq!(code(&r), *want);
-        let call = json!({"callId": format!("call-{}", i + 1), "target": "example.atomic", "expectedIncarnation": null, "method": "M", "payload": {}});
-        let r = raw.call_with("rpc.call", call, atts.clone()).await;
-        assert_eq!(
-            code(&r),
-            *want,
-            "semantic refusal advances correlation history but preserves the refusal reason"
-        );
-    }
-    assert_eq!(
-        e.stats(),
-        before,
-        "refused admissions leave no roots, calls or retained values"
-    );
-    quiet("no partial delivery", sub.next()).await;
-    quiet("no partial request", svc.next()).await;
-    // Two names for one object: both are delivered, one root is held.
-    let r = raw
-        .call_with(
-            "publish",
-            json!({"topic": "t.atomic", "payload": {}}),
-            json!([good("a"), good("b")]),
-        )
-        .await
-        .unwrap();
-    assert_eq!(
-        r["topicSequence"], "1",
-        "refused publications spent no sequence number"
-    );
-    let m = within("delivery", sub.next()).await.unwrap();
-    assert_eq!(m.attachment_names().collect::<Vec<_>>(), ["a", "b"]);
-    assert_eq!(m.artifact("b").unwrap().read_all().await.unwrap(), b"abc");
-    // Hold, retained value, delivery: three roots, not four.
-    e.settle("one root per holder", |s| s.artifact_roots == 3)
-        .await;
-}
-
-async fn release_ids_are_watermarked(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("raw").await;
-    let (a1, _) = raw.allocate(4).await;
-    let (a2, _) = raw.allocate(4).await;
-    let rel = |ids: Value| json!({ "ownerIds": ids });
-    assert_eq!(
-        code(
-            &raw.call("artifact.release", rel(json!([a2["ownerId"], "own-99"])))
-                .await
-        ),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        e.stats().artifacts,
-        2,
-        "a batch with a future id releases nothing"
-    );
-    assert_eq!(
-        raw.call("artifact.release", rel(json!([a1["ownerId"]])))
-            .await
-            .unwrap()["released"],
-        "1"
-    );
-    assert_eq!(
-        raw.call("artifact.release", rel(json!([a1["ownerId"]])))
-            .await
-            .unwrap()["released"],
-        "0"
-    );
-    assert_eq!(
-        code(&raw.call("artifact.release", rel(json!(["dlv-1"]))).await),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        code(&raw.call("artifact.release", rel(json!([]))).await),
-        "INVALID_ENVELOPE"
-    );
-    let many: Vec<String> = (1..=65).map(|i| format!("own-{i}")).collect();
-    assert_eq!(
-        code(&raw.call("artifact.release", rel(json!(many))).await),
-        "INVALID_ENVELOPE"
-    );
-    let consumed = |ids: Value| json!({ "deliveryIds": ids });
-    assert_eq!(
-        code(
-            &raw.call("delivery.consumed", consumed(json!(["dlv-3"])))
-                .await
-        ),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        code(
-            &raw.call("delivery.consumed", consumed(json!([a2["ownerId"]])))
-                .await
-        ),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        raw.call(
-            "artifact.release",
-            rel(json!([a2["ownerId"], a2["ownerId"]]))
-        )
-        .await
-        .unwrap()["released"],
-        "1"
-    );
-    e.settle("all released", |s| s.artifacts == 0 && s.store_bytes == 0)
-        .await;
-}
-
-async fn owners_are_scoped_to_their_connection(via: Via) {
-    let e = env(via).await;
-    let owner = e.client("owner").await;
-    let art = sealed(&owner, b"private", "text/plain").await;
-    let reference = art.reference().to_json();
-    let mut thief = e.raw_hello("thief").await;
-    let open = |owner_id: &str| json!({"ref": reference, "ownerId": owner_id});
-    // Naming the victim's owner id means nothing on another connection.
-    assert_eq!(
-        code(&thief.call("artifact.open", open(art.owner_id())).await),
-        "OWNER_INVALID"
-    );
-    let (mine, _) = thief.allocate(1).await;
-    let my_owner = mine["ownerId"].as_str().unwrap().to_owned();
-    assert_eq!(
-        code(&thief.call("artifact.open", open(&my_owner)).await),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        code(&thief.call("artifact.retain", open(&my_owner)).await),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        code(
-            &thief
-                .call("artifact.release", json!({"ownerIds": [art.owner_id()]}))
-                .await
-        ),
-        "OK"
-    );
-    assert_eq!(
-        art.read_all().await.unwrap(),
-        b"private",
-        "another connection cannot release it"
-    );
-}
-
-async fn abandoned_futures_do_not_leak_owners(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    // Each future is polled once (its command is sent) and then dropped.
-    let _ = tokio::time::timeout(Duration::ZERO, c.artifacts().allocate(1000, "x/y")).await;
-    e.settle("abandoned allocation released", |s| {
-        s.artifacts == 0 && s.owners == 0 && s.store_bytes == 0
-    })
-    .await;
-    e.settle_files("staging", 0).await;
-
-    let mut w = c.artifacts().allocate(4, "x/y").await.unwrap();
-    w.write_all(b"seal").unwrap();
-    let _ = tokio::time::timeout(Duration::ZERO, w.seal()).await;
-    e.settle("abandoned seal released", |s| {
-        s.artifacts == 0 && s.owners == 0
-    })
-    .await;
-
-    let art = sealed(&c, b"keep", "x/y").await;
-    let _ = tokio::time::timeout(Duration::ZERO, art.retain()).await;
-    e.settle("abandoned retain released", |s| s.owners == 1)
-        .await;
-    drop(art);
-    e.settle("all released", |s| s.artifacts == 0 && s.owners == 0)
-        .await;
-    assert_eq!(c.control_errors(), 0);
-}
-
-async fn writer_drop_releases_staging(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    let mut w = c.artifacts().allocate(1000, "x/y").await.unwrap();
-    w.write_all(&[1; 10]).unwrap();
-    assert_eq!(e.files("staging"), 1);
-    drop(w);
-    e.settle("staging released", |s| {
-        s.artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-    e.settle_files("staging", 0).await;
-}
-
-async fn disconnect_releases_all_but_retained(via: Via) {
-    let e = env(via).await;
-    let producer = e.client("producer").await;
-    let reader = e.client("reader").await;
-    producer
-        .declare_topic("t.keep", Retained::Latest)
-        .await
-        .unwrap();
-    let mut sub = reader
-        .subscribe("t.keep", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let a1 = sealed(&producer, b"retained", "x/y").await;
-    let a2 = sealed(&producer, b"held", "x/y").await;
-    let w3 = producer.artifacts().allocate(10, "x/y").await.unwrap();
-    producer
-        .publish("t.keep", obj(json!({})), &[("a", &a1)])
-        .await
-        .unwrap();
-    let m = within("delivery", sub.next()).await.unwrap();
-    // Close both while handles are still alive; the router releases what they owned.
-    producer.close().await;
-    reader.close().await;
-    let s = e
-        .settle("connections gone", |s| s.connections == 0 && s.owners == 0)
-        .await;
-    assert_eq!(
-        (s.artifacts, s.artifact_roots, s.store_bytes),
-        (1, 1, 8),
-        "only the retained value survives"
-    );
-    // Handles that outlived their connection are inert.
-    assert_eq!(a2.read_all().await.unwrap_err().code, ErrorCode::RouterLost);
-    drop((a1, a2, w3, m, sub));
-    let admin = e.client("admin").await;
-    assert!(admin.clear_topic("t.keep").await.unwrap());
-    e.settle("retained released", |s| {
-        s.artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-}
-
-async fn router_restart_invalidates_old_handles(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    c.declare_topic("t.r", Retained::None).await.unwrap();
-    let mut sub = c
-        .subscribe("t.r", SubscriptionConfig::latest())
-        .await
-        .unwrap();
-    let art = sealed(&c, b"old", "x/y").await;
-    e.router.shutdown();
-    assert!(within("subscription closed", sub.next()).await.is_none());
-    let err = art.read_all().await.unwrap_err();
-    assert_eq!(err.code, ErrorCode::RouterLost);
-    assert!(c.closed().is_some());
-    assert_eq!(
-        e.try_client("late").await.unwrap_err().code,
-        ErrorCode::RouterLost
-    );
-
-    // A restarted router on the same root is a new store incarnation.
-    let mut cfg = RouterConfig::new(e.router.store_root());
-    cfg.policy = Policy::open();
-    let second = Router::new(cfg).unwrap();
-    assert_ne!(second.store_id(), e.router.store_id());
-    let mut raw = common::Raw::over(second.connect_in_memory(), second.store_root());
-    raw.hello("new").await.unwrap();
-    let (mine, _) = raw.allocate(1).await;
-    // An old reference is refused even alongside an owner that is live on the new router.
-    let r = raw
-        .call(
-            "artifact.open",
-            json!({"ref": art.reference().to_json(), "ownerId": mine["ownerId"]}),
-        )
-        .await;
-    assert_eq!(code(&r), "ARTIFACT_GONE");
-    let client = flybus::Client::connect(
-        second.connect_in_memory(),
-        flybus::ClientConfig::new("sdk", second.store_root()),
-    )
-    .await
-    .unwrap();
-    let fresh = sealed(&client, b"new", "x/y").await;
-    assert_eq!(fresh.read_all().await.unwrap(), b"new");
-}
-
-both_transports!(
-    allocate_write_seal_read,
-    unsealed_artifacts_cannot_be_used,
-    seal_is_immune_to_live_writable_handles,
-    seal_checks_length_and_digest,
-    quotas_are_enforced,
-    fan_out_shares_one_object_and_the_last_consumer_collects,
-    extracted_artifacts_outlive_their_message,
-    failed_admission_is_atomic,
-    release_ids_are_watermarked,
-    owners_are_scoped_to_their_connection,
-    abandoned_futures_do_not_leak_owners,
-    writer_drop_releases_staging,
-    disconnect_releases_all_but_retained,
-    router_restart_invalidates_old_handles,
-);

services/flysim/crates/flybus/tests/common/mod.rs

@@ -1,416 +0,0 @@
-//! Shared harness: a router on a temporary store, reached over either transport, plus a raw
-//! protocol client for adversarial frames the SDK would never send.
-
-#![allow(dead_code)]
-
-use std::future::Future;
-use std::path::{Path, PathBuf};
-use std::sync::Mutex;
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::time::Duration;
-
-use flybus::wire::{Envelope, Kind, Location, read_frame};
-use flybus::{
-    Artifact, Client, ClientConfig, Limits, Policy, Router, RouterConfig, RouterStats, Transport,
-    UnixListenerHandle,
-};
-use serde_json::{Map, Value, json};
-use tokio::io::{AsyncWriteExt, ReadHalf, WriteHalf};
-
-pub const WAIT: Duration = Duration::from_secs(10);
-
-/// Generates one test per transport from an `async fn name(via: Via)`.
-#[macro_export]
-macro_rules! both_transports {
-    ($($name:ident),* $(,)?) => {
-        mod in_memory {
-            $(
-                #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-                async fn $name() {
-                    super::$name($crate::common::Via::Memory).await
-                }
-            )*
-        }
-        mod unix_socket {
-            $(
-                #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-                async fn $name() {
-                    super::$name($crate::common::Via::Unix).await
-                }
-            )*
-        }
-    };
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum Via {
-    Memory,
-    Unix,
-}
-
-pub struct Env {
-    pub router: Router,
-    pub via: Via,
-    pub dir: tempfile::TempDir,
-    listeners: Mutex<Vec<UnixListenerHandle>>,
-    next_socket: AtomicU64,
-}
-
-pub async fn env(via: Via) -> Env {
-    env_with(via, Limits::default(), Policy::open()).await
-}
-
-pub async fn env_with(via: Via, limits: Limits, policy: Policy) -> Env {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path().join("store"));
-    config.limits = limits;
-    config.policy = policy;
-    let router = Router::new(config).unwrap();
-    Env {
-        router,
-        via,
-        dir,
-        listeners: Mutex::new(Vec::new()),
-        next_socket: AtomicU64::new(0),
-    }
-}
-
-impl Env {
-    pub async fn transport(&self) -> Transport {
-        match self.via {
-            Via::Memory => self.router.connect_in_memory(),
-            Via::Unix => {
-                let n = self.next_socket.fetch_add(1, Ordering::Relaxed);
-                let path = self.dir.path().join(format!("unbound-{n}.sock"));
-                let listener = self.router.listen_unix(&path).await.unwrap();
-                let transport = Transport::unix(&path).await.unwrap();
-                self.listeners.lock().unwrap().push(listener);
-                transport
-            }
-        }
-    }
-
-    pub async fn transport_as(&self, id: &str) -> Transport {
-        self.try_transport_as(id).await.unwrap()
-    }
-
-    async fn try_transport_as(&self, id: &str) -> std::io::Result<Transport> {
-        match self.via {
-            Via::Memory => Ok(self.router.connect_in_memory_as(id)),
-            Via::Unix => {
-                let n = self.next_socket.fetch_add(1, Ordering::Relaxed);
-                let path = self.dir.path().join(format!("bound-{n}.sock"));
-                let listener = self.router.listen_unix_as(&path, id).await?;
-                let transport = Transport::unix(&path).await?;
-                self.listeners.lock().unwrap().push(listener);
-                Ok(transport)
-            }
-        }
-    }
-
-    pub fn config(&self, id: &str) -> ClientConfig {
-        ClientConfig::new(id, self.router.store_root())
-    }
-
-    pub async fn try_client(&self, id: &str) -> Result<Client, flybus::BusError> {
-        let transport = self.try_transport_as(id).await.map_err(|e| {
-            flybus::BusError::new(flybus::ErrorCode::RouterLost, format!("connect: {e}"))
-        })?;
-        Client::connect(transport, self.config(id)).await
-    }
-
-    pub async fn client(&self, id: &str) -> Client {
-        self.try_client(id).await.unwrap()
-    }
-
-    pub async fn raw(&self) -> Raw {
-        Raw::over(self.transport().await, self.router.store_root())
-    }
-
-    pub async fn raw_as(&self, id: &str) -> Raw {
-        Raw::over(self.transport_as(id).await, self.router.store_root())
-    }
-
-    pub async fn raw_hello(&self, id: &str) -> Raw {
-        let mut raw = self.raw_as(id).await;
-        raw.hello(id).await.unwrap();
-        raw
-    }
-
-    pub fn stats(&self) -> RouterStats {
-        self.router.stats()
-    }
-
-    /// Polls the router until `ok` holds; panics with the last stats after [`WAIT`].
-    pub async fn settle(&self, what: &str, ok: impl Fn(&RouterStats) -> bool) -> RouterStats {
-        let deadline = tokio::time::Instant::now() + WAIT;
-        loop {
-            let s = self.stats();
-            if ok(&s) {
-                return s;
-            }
-            if tokio::time::Instant::now() > deadline {
-                panic!("{what}: router never settled: {s:?}");
-            }
-            tokio::time::sleep(Duration::from_millis(5)).await;
-        }
-    }
-
-    /// Files currently in the store's `sealed/` or `staging/` directory.
-    pub fn files(&self, sub: &str) -> usize {
-        std::fs::read_dir(self.router.store_dir().join(sub))
-            .map(|d| d.count())
-            .unwrap_or(0)
-    }
-
-    /// Waits for the file count to reach `n`. Unlinks follow the registry update, outside the
-    /// router lock, so a file can briefly outlive its entry.
-    pub async fn settle_files(&self, sub: &str, n: usize) {
-        let deadline = tokio::time::Instant::now() + WAIT;
-        while self.files(sub) != n {
-            assert!(
-                tokio::time::Instant::now() < deadline,
-                "{sub}: {} files, wanted {n}",
-                self.files(sub)
-            );
-            tokio::time::sleep(Duration::from_millis(5)).await;
-        }
-    }
-}
-
-pub fn obj(v: Value) -> Map<String, Value> {
-    match v {
-        Value::Object(m) => m,
-        _ => panic!("not an object"),
-    }
-}
-
-pub async fn within<T>(what: &str, f: impl Future<Output = T>) -> T {
-    match tokio::time::timeout(WAIT, f).await {
-        Ok(v) => v,
-        Err(_) => panic!("{what}: timed out"),
-    }
-}
-
-/// Asserts nothing arrives for a short while.
-pub async fn quiet<T: std::fmt::Debug>(what: &str, f: impl Future<Output = Option<T>>) {
-    if let Ok(Some(v)) = tokio::time::timeout(Duration::from_millis(150), f).await {
-        panic!("{what}: unexpected {v:?}");
-    }
-}
-
-pub async fn sealed(client: &Client, bytes: &[u8], content_type: &str) -> Artifact {
-    use std::io::Write;
-    let mut w = client
-        .artifacts()
-        .allocate(bytes.len() as u64, content_type)
-        .await
-        .unwrap();
-    w.write_all(bytes).unwrap();
-    w.seal().await.unwrap()
-}
-
-/// The write half of a [`Raw`], for a task that floods the router.
-pub struct RawWriter {
-    wr: WriteHalf<Transport>,
-}
-
-impl RawWriter {
-    /// Sends one frame; false once the router has gone.
-    pub async fn send(&mut self, bytes: &[u8]) -> bool {
-        let mut buf = (bytes.len() as u32).to_le_bytes().to_vec();
-        buf.extend_from_slice(bytes);
-        self.wr.write_all(&buf).await.is_ok()
-    }
-}
-
-/// A client speaking the wire protocol by hand.
-pub struct Raw {
-    rd: ReadHalf<Transport>,
-    wr: Option<WriteHalf<Transport>>,
-    pub next: u64,
-    pub stash: Vec<Envelope>,
-    store_root: PathBuf,
-}
-
-pub type Reply = Result<Map<String, Value>, (String, String)>;
-
-impl Raw {
-    pub fn over(transport: Transport, store_root: &Path) -> Raw {
-        let (rd, wr) = tokio::io::split(transport);
-        Raw {
-            rd,
-            wr: Some(wr),
-            next: 0,
-            stash: Vec::new(),
-            store_root: store_root.to_path_buf(),
-        }
-    }
-
-    pub fn take_writer(&mut self) -> RawWriter {
-        RawWriter {
-            wr: self.wr.take().expect("writer already taken"),
-        }
-    }
-
-    fn wr(&mut self) -> &mut WriteHalf<Transport> {
-        self.wr.as_mut().expect("writer was taken")
-    }
-
-    pub async fn send_bytes(&mut self, bytes: &[u8]) {
-        let mut buf = (bytes.len() as u32).to_le_bytes().to_vec();
-        buf.extend_from_slice(bytes);
-        let _ = self.wr().write_all(&buf).await;
-        let _ = self.wr().flush().await;
-    }
-
-    pub async fn send_prefix(&mut self, len: u32) {
-        let _ = self.wr().write_all(&len.to_le_bytes()).await;
-        let _ = self.wr().flush().await;
-    }
-
-    /// Sends a command with the next id; returns the id.
-    pub async fn command(&mut self, op: &str, body: Value, attachments: Value) -> String {
-        self.next += 1;
-        let id = format!("msg-{}", self.next);
-        let env = json!({
-            "protocol": "flybus", "major": 1, "minor": 0,
-            "id": id, "replyTo": null, "kind": "command", "op": op,
-            "body": body, "attachments": attachments,
-        });
-        self.send_bytes(&serde_json::to_vec(&env).unwrap()).await;
-        id
-    }
-
-    /// The next envelope, `None` at end of stream.
-    pub async fn recv(&mut self) -> Option<Envelope> {
-        if !self.stash.is_empty() {
-            return Some(self.stash.remove(0));
-        }
-        self.read().await
-    }
-
-    async fn read(&mut self) -> Option<Envelope> {
-        match within("raw read", read_frame(&mut self.rd)).await {
-            Ok(Some(bytes)) => Some(Envelope::decode(&bytes).expect("router frames are valid")),
-            _ => None,
-        }
-    }
-
-    /// Waits for the reply to `id`, stashing anything else.
-    pub async fn reply(&mut self, id: &str) -> Reply {
-        if let Some(i) = self
-            .stash
-            .iter()
-            .position(|e| e.reply_to.as_deref() == Some(id))
-        {
-            return parse_reply(self.stash.remove(i));
-        }
-        loop {
-            let env = self
-                .read()
-                .await
-                .unwrap_or_else(|| panic!("closed while waiting for {id}"));
-            if env.reply_to.as_deref() == Some(id) {
-                return parse_reply(env);
-            }
-            self.stash.push(env);
-        }
-    }
-
-    pub async fn call(&mut self, op: &str, body: Value) -> Reply {
-        let id = self.command(op, body, json!([])).await;
-        self.reply(&id).await
-    }
-
-    pub async fn call_with(&mut self, op: &str, body: Value, attachments: Value) -> Reply {
-        let id = self.command(op, body, attachments).await;
-        self.reply(&id).await
-    }
-
-    pub async fn hello(&mut self, id: &str) -> Reply {
-        self.call(
-            "bus.hello",
-            json!({"clientId": id, "clientIncarnation": "inc-raw", "supportedMajors": [1]}),
-        )
-        .await
-    }
-
-    /// Reads to end of stream and returns the last `connection.closing` notice, if any.
-    pub async fn closing(&mut self) -> Option<Map<String, Value>> {
-        let mut last = None;
-        while let Some(env) = self.recv().await {
-            if env.kind == Kind::Notice && env.op == "connection.closing" {
-                last = Some(env.body);
-            }
-        }
-        last
-    }
-
-    /// The next delivery or notice, from the stash first.
-    pub async fn event(&mut self) -> Envelope {
-        if let Some(i) = self.stash.iter().position(|e| e.kind != Kind::Reply) {
-            return self.stash.remove(i);
-        }
-        loop {
-            let env = self
-                .read()
-                .await
-                .expect("closed while waiting for an event");
-            if env.kind != Kind::Reply {
-                return env;
-            }
-            self.stash.push(env);
-        }
-    }
-
-    pub fn path(&self, loc: &Value) -> PathBuf {
-        let loc = Location::from_json(loc).unwrap();
-        self.store_root.join(loc.store_id).join(loc.relative_path)
-    }
-
-    /// Allocates and writes an artifact by hand; returns (ref-less allocate value, staging path).
-    pub async fn allocate(&mut self, len: u64) -> (Map<String, Value>, PathBuf) {
-        let v = self
-            .call(
-                "artifact.allocate",
-                json!({"byteLength": len.to_string(), "contentType": "application/octet-stream"}),
-            )
-            .await
-            .unwrap();
-        let path = self.path(&v["writeLocation"]);
-        (v, path)
-    }
-
-    pub async fn seal(&mut self, alloc: &Map<String, Value>, digest: Value) -> Reply {
-        self.call(
-            "artifact.seal",
-            json!({"artifactId": alloc["artifactId"], "generation": "1", "ownerId": alloc["ownerId"], "digest": digest}),
-        )
-        .await
-    }
-}
-
-pub fn parse_reply(env: Envelope) -> Reply {
-    assert_eq!(env.kind, Kind::Reply);
-    if env.body["ok"] == json!(true) {
-        Ok(env.body["value"].as_object().unwrap().clone())
-    } else {
-        let e = &env.body["error"];
-        Err((
-            e["code"].as_str().unwrap().to_owned(),
-            e["dispatch"].as_str().unwrap().to_owned(),
-        ))
-    }
-}
-
-pub fn code(r: &Reply) -> &str {
-    match r {
-        Ok(_) => "OK",
-        Err((c, _)) => c,
-    }
-}
-
-pub fn store_path(root: &Path, store_id: &str, rel: &str) -> PathBuf {
-    root.join(store_id).join(rel)
-}

services/flysim/crates/flybus/tests/conformance_artifacts.rs

@@ -1,788 +0,0 @@
-//! Black-box conformance tests for artifact ownership (bus-v1 section 8): allocate/seal/open,
-//! immutability past a stale writable handle, ownership surviving message drop, explicit
-//! retain/release, final-owner collection, root accounting across queued/latest/retained
-//! delivery, forward-before-release ordering, admission rollback, disconnect cleanup, and
-//! rejection of stale or forged references and owners. Every test runs over both transports.
-//!
-//! These tests use only the public `flybus` API (plus the `common::Raw` protocol harness for
-//! adversarial frames no well-behaved SDK client would send) and generic bytes over synthetic
-//! messages; nothing here depends on any application on top of the bus.
-
-mod common;
-
-use std::io::Write;
-
-use common::{Via, code, env, env_with, obj, sealed, within};
-use flybus::{ErrorCode, Limits, Policy, Retained, ServiceConfig, SubscriptionConfig};
-use serde_json::{Value, json};
-
-// -------------------------------------------------------------------------------------------
-// Allocate / seal / open
-
-async fn allocate_write_seal_open_roundtrip_and_mismatches(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-
-    let mut w = c.artifacts().allocate(5, "text/plain").await.unwrap();
-    assert_eq!(w.byte_length(), 5);
-    w.write_all(b"hello").unwrap();
-    assert!(
-        w.write(b"!").is_err(),
-        "a write past the declared length must fail locally"
-    );
-    let art = w.seal().await.unwrap();
-    assert_eq!(art.reference().byte_length, 5);
-    assert_eq!(art.reference().content_type, "text/plain");
-    assert_eq!(art.read_all().await.unwrap(), b"hello");
-    drop(art);
-    e.settle("sealed object collected", |s| s.sealed_artifacts == 0)
-        .await;
-
-    // Sealing declares more bytes than were actually staged: rejected, not silently truncated.
-    let mut raw = e.raw_hello("raw").await;
-    let (alloc, path) = raw.allocate(10).await;
-    std::fs::write(&path, b"short").unwrap();
-    assert_eq!(
-        code(&raw.seal(&alloc, Value::Null).await),
-        "ARTIFACT_MISMATCH"
-    );
-
-    // A syntactically valid but wrong digest is refused too.
-    let (alloc2, path2) = raw.allocate(4).await;
-    std::fs::write(&path2, b"data").unwrap();
-    assert_eq!(
-        code(&raw.seal(&alloc2, json!("0".repeat(64))).await),
-        "ARTIFACT_MISMATCH"
-    );
-}
-
-/// Sealing copies staging into a fresh inode; a producer's writable handle that survives the
-/// seal (or a duplicate of it) can only reach the abandoned staging file, never the sealed
-/// bytes (bus-v1 section 8.1 and the store module's own contract).
-async fn seal_is_immutable_despite_a_stale_writable_handle(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("producer").await;
-    let (alloc, path) = raw.allocate(7).await;
-    let mut stale = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
-    stale.write_all(b"before1").unwrap();
-    stale.flush().unwrap();
-
-    let sealed_reply = raw.seal(&alloc, Value::Null).await.unwrap();
-    // Tamper through the handle only after the router has answered the seal: the sealed copy
-    // already exists and the staging file is already unlinked.
-    stale.write_all(b"AFTER!!").unwrap();
-
-    let open_reply = raw
-        .call(
-            "artifact.open",
-            json!({"ref": sealed_reply["ref"], "ownerId": sealed_reply["ownerId"]}),
-        )
-        .await
-        .unwrap();
-    let sealed_path = raw.path(&open_reply["readLocation"]);
-    assert_eq!(
-        std::fs::read(sealed_path).unwrap(),
-        b"before1",
-        "a post-seal write must never reach the sealed copy"
-    );
-}
-
-// -------------------------------------------------------------------------------------------
-// Ownership surviving drop, explicit retain/release, final-owner collection
-
-/// The doc's own illustrative snippet (bus-v1 section 2): `drop(message)` alone must not
-/// consume the delivery while an artifact extracted from it is still held.
-async fn extracted_artifact_outlives_the_message_it_came_from(via: Via) {
-    let e = env(via).await;
-    let camera = e.client("camera").await;
-    let viewer = e.client("viewer").await;
-    camera
-        .declare_topic("world.demo.frame", Retained::None)
-        .await
-        .unwrap();
-    let mut sub = viewer
-        .subscribe("world.demo.frame", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let frame = sealed(&camera, b"pixels", "image/x-rgba").await;
-    camera
-        .publish("world.demo.frame", obj(json!({})), &[("frame", &frame)])
-        .await
-        .unwrap();
-    drop(frame);
-
-    let message = within("frame delivered", sub.next()).await.unwrap();
-    let image = message.artifact("frame").unwrap();
-    drop(message);
-    e.settle("the delivery still owns its artifact", |s| {
-        s.owners == 1 && s.sealed_artifacts == 1
-    })
-    .await;
-    assert_eq!(
-        image.read_all().await.unwrap(),
-        b"pixels",
-        "the surviving handle still reads fine"
-    );
-    drop(image);
-    e.settle("dropping the last handle finally consumes it", |s| {
-        s.owners == 0 && s.sealed_artifacts == 0
-    })
-    .await;
-}
-
-async fn explicit_retain_outlives_the_original_hold(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    let original = sealed(&c, b"payload", "application/octet-stream").await;
-    let retained = original.retain().await.unwrap();
-    assert_eq!(
-        retained.reference().artifact_id,
-        original.reference().artifact_id
-    );
-    assert_ne!(
-        retained.owner_id(),
-        original.owner_id(),
-        "retain creates an independent owner"
-    );
-
-    drop(original);
-    e.settle("the retained hold keeps it sealed", |s| {
-        s.sealed_artifacts == 1 && s.artifact_roots == 1
-    })
-    .await;
-    assert_eq!(retained.read_all().await.unwrap(), b"payload");
-    drop(retained);
-    e.settle("collected once the last owner drops", |s| {
-        s.sealed_artifacts == 0 && s.owners == 0
-    })
-    .await;
-}
-
-async fn collection_waits_for_every_retained_owner(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    let a = sealed(&c, b"payload", "application/octet-stream").await;
-    let h1 = a.retain().await.unwrap();
-    let h2 = a.retain().await.unwrap();
-    drop(a);
-    e.settle("two independent holds remain", |s| {
-        s.owners == 2 && s.sealed_artifacts == 1
-    })
-    .await;
-    drop(h1);
-    e.settle("one hold remains", |s| {
-        s.owners == 1 && s.sealed_artifacts == 1
-    })
-    .await;
-    drop(h2);
-    e.settle("the final owner's drop collects it", |s| {
-        s.owners == 0 && s.sealed_artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-    assert_eq!(e.files("sealed"), 0);
-}
-
-// -------------------------------------------------------------------------------------------
-// Root accounting across queued, latest and retained delivery (bus-v1 section 8.2)
-
-/// A message queued behind a saturated credit already holds a root at admission time, before
-/// it is ever dispatched to the client; dispatch transfers that root into an owner, it does
-/// not add a second one.
-async fn queued_deliveries_hold_roots_before_dispatch(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    let r = e.client("r").await;
-    p.declare_topic("t.queued", Retained::None).await.unwrap();
-    let mut sub = r
-        .subscribe(
-            "t.queued",
-            SubscriptionConfig::bounded().in_flight(1).queued(4),
-        )
-        .await
-        .unwrap();
-
-    let a1 = sealed(&p, b"m1", "application/octet-stream").await;
-    let a2 = sealed(&p, b"m2", "application/octet-stream").await;
-    p.publish("t.queued", obj(json!({})), &[("x", &a1)])
-        .await
-        .unwrap();
-    p.publish("t.queued", obj(json!({})), &[("x", &a2)])
-        .await
-        .unwrap();
-    drop((a1, a2));
-    e.settle("one dispatched owner, two roots", |s| {
-        s.artifact_roots == 2 && s.owners == 1 && s.sealed_artifacts == 2
-    })
-    .await;
-
-    let held = within("dispatched message", sub.next()).await.unwrap();
-    assert_eq!(held.artifact("x").unwrap().read_all().await.unwrap(), b"m1");
-    drop(held);
-    let second = within("previously queued message", sub.next())
-        .await
-        .unwrap();
-    assert_eq!(
-        second.artifact("x").unwrap().read_all().await.unwrap(),
-        b"m2"
-    );
-    e.settle("dispatch moved the root, it did not add one", |s| {
-        s.artifact_roots == 1 && s.owners == 1
-    })
-    .await;
-    drop(second);
-    e.settle("fully collected", |s| {
-        s.artifact_roots == 0 && s.owners == 0 && s.sealed_artifacts == 0
-    })
-    .await;
-}
-
-/// `latest` never queues more than one undelivered value; coalescing releases the replaced
-/// root immediately, and the already-dispatched value stays independent of it.
-async fn latest_mode_holds_at_most_two_roots_delivered_plus_queued(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    let r = e.client("r").await;
-    p.declare_topic("t.latest", Retained::None).await.unwrap();
-    let mut sub = r
-        .subscribe("t.latest", SubscriptionConfig::latest().in_flight(1))
-        .await
-        .unwrap();
-    for i in 0..3u8 {
-        let a = sealed(&p, &[i], "application/octet-stream").await;
-        p.publish("t.latest", obj(json!({})), &[("x", &a)])
-            .await
-            .unwrap();
-    }
-    // i=0 was already dispatched (an owner); i=1 was coalesced away by i=2 while still queued.
-    e.settle(
-        "a delivered root plus one coalesced-survivor root, no more",
-        |s| s.artifact_roots == 2 && s.owners == 1 && s.sealed_artifacts == 2,
-    )
-    .await;
-
-    let first = within("delivered", sub.next()).await.unwrap();
-    assert_eq!(first.artifact("x").unwrap().read_all().await.unwrap(), &[0]);
-    drop(first);
-    let last = within("coalesced survivor", sub.next()).await.unwrap();
-    assert_eq!(last.artifact("x").unwrap().read_all().await.unwrap(), &[2]);
-    drop(last);
-    e.settle("fully collected", |s| {
-        s.artifact_roots == 0 && s.owners == 0 && s.sealed_artifacts == 0
-    })
-    .await;
-}
-
-/// A retained topic value is a root the router itself keeps; it has no per-connection owner,
-/// so nothing about a subscriber connecting, reading or disconnecting can move it.
-async fn retained_topic_value_holds_a_root_independent_of_subscribers(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    p.declare_topic("t.retained", Retained::Latest)
-        .await
-        .unwrap();
-    let a = sealed(&p, b"snapshot", "application/octet-stream").await;
-    let r = p
-        .publish("t.retained", obj(json!({})), &[("x", &a)])
-        .await
-        .unwrap();
-    assert_eq!(r.subscribers, 0);
-    drop(a);
-    e.settle("a retained root with no owner", |s| {
-        s.artifact_roots == 1 && s.owners == 0 && s.sealed_artifacts == 1
-    })
-    .await;
-    assert!(p.clear_topic("t.retained").await.unwrap());
-    e.settle("clearing releases the retained root", |s| {
-        s.artifact_roots == 0 && s.sealed_artifacts == 0
-    })
-    .await;
-}
-
-// -------------------------------------------------------------------------------------------
-// Forward before release (bus-v1 section 8.2: destination roots before source release)
-
-/// A forward or reply must use a still-live source owner; once a delivery is released its
-/// artifacts cannot source a new admission, but forwarding *before* releasing is exactly what
-/// keeps bytes alive once the original delivery finally goes.
-async fn forward_requires_the_source_owner_still_live(via: Via) {
-    let e = env(via).await;
-    let caller = e.client("caller").await;
-    let consumer = e.client("consumer").await;
-    consumer
-        .declare_topic("t.relay", Retained::None)
-        .await
-        .unwrap();
-    let mut sub = consumer
-        .subscribe("t.relay", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let mut server = e.raw_hello("server").await;
-    assert_eq!(
-        code(
-            &server
-                .call(
-                    "service.register",
-                    json!({"name": "agent.relay", "maxQueued": 4, "maxInFlight": 4})
-                )
-                .await
-        ),
-        "OK"
-    );
-
-    // Round 1: release the request delivery, then try to forward using its stale owner.
-    let art1 = sealed(&caller, b"payload-1", "application/octet-stream").await;
-    let _c1 = caller
-        .call(
-            "agent.relay",
-            None,
-            "Relay",
-            obj(json!({})),
-            &[("in", &art1)],
-        )
-        .await
-        .unwrap();
-    let req1 = within("request 1", server.event()).await;
-    let delivery1 = req1.body["deliveryId"].as_str().unwrap().to_owned();
-    let att1 = req1.attachments[0].clone();
-    assert_eq!(
-        code(
-            &server
-                .call("delivery.consumed", json!({"deliveryIds": [delivery1]}))
-                .await
-        ),
-        "OK"
-    );
-    e.settle("the request delivery is released", |s| s.owners == 1)
-        .await; // only art1's own hold remains
-    let refused = server
-        .call_with(
-            "publish",
-            json!({"topic": "t.relay", "payload": {}}),
-            json!([{"name": "out", "ref": att1.reference.to_json(), "ownerId": att1.owner_id}]),
-        )
-        .await;
-    assert_eq!(
-        code(&refused),
-        "OWNER_INVALID",
-        "a released delivery cannot source a forward"
-    );
-    drop(art1);
-
-    // Round 2: forward while the request delivery is still live, then release it.
-    let art2 = sealed(&caller, b"payload-2", "application/octet-stream").await;
-    let _c2 = caller
-        .call(
-            "agent.relay",
-            None,
-            "Relay",
-            obj(json!({})),
-            &[("in", &art2)],
-        )
-        .await
-        .unwrap();
-    let req2 = within("request 2", server.event()).await;
-    let delivery2 = req2.body["deliveryId"].as_str().unwrap().to_owned();
-    let att2 = req2.attachments[0].clone();
-    let forwarded = server
-        .call_with(
-            "publish",
-            json!({"topic": "t.relay", "payload": {}}),
-            json!([{"name": "out", "ref": att2.reference.to_json(), "ownerId": att2.owner_id}]),
-        )
-        .await
-        .unwrap();
-    assert_eq!(forwarded["subscribers"], "1");
-    assert_eq!(
-        code(
-            &server
-                .call("delivery.consumed", json!({"deliveryIds": [delivery2]}))
-                .await
-        ),
-        "OK"
-    );
-    drop(art2);
-
-    let msg = within("relayed", sub.next()).await.unwrap();
-    assert_eq!(
-        msg.artifact("out").unwrap().read_all().await.unwrap(),
-        b"payload-2"
-    );
-}
-
-// -------------------------------------------------------------------------------------------
-// Failed admission rollback (bus-v1 section 6/7: rejection establishes no root)
-
-async fn rejected_publish_creates_no_roots(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    let r = e.client("r").await;
-    p.declare_topic("t.rollback", Retained::None).await.unwrap();
-    let mut sub = r
-        .subscribe(
-            "t.rollback",
-            SubscriptionConfig::bounded().queued(1).in_flight(1),
-        )
-        .await
-        .unwrap();
-    p.publish("t.rollback", obj(json!({})), &[]).await.unwrap();
-    let held = within("first delivered", sub.next()).await.unwrap(); // consumes the one in-flight credit
-    p.publish("t.rollback", obj(json!({})), &[]).await.unwrap(); // fills the one queue slot
-
-    let art = sealed(&p, b"payload", "application/octet-stream").await;
-    let before = e.stats();
-    let refused = p
-        .publish("t.rollback", obj(json!({})), &[("x", &art)])
-        .await
-        .unwrap_err();
-    assert_eq!(refused.code, ErrorCode::Backpressure);
-    assert_eq!(
-        e.stats(),
-        before,
-        "a refused publish must not touch any existing root, owner or byte count"
-    );
-
-    drop(held);
-    p.declare_topic("t.rollback.ok", Retained::None)
-        .await
-        .unwrap();
-    let receipt = p
-        .publish("t.rollback.ok", obj(json!({})), &[("x", &art)])
-        .await
-        .unwrap();
-    assert_eq!(
-        receipt.subscribers, 0,
-        "the untouched artifact is still usable after the rejection"
-    );
-}
-
-async fn rejected_call_creates_no_roots(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "agent.rollback",
-            ServiceConfig {
-                max_queued: 1,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let _c1 = caller
-        .call("agent.rollback", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let dispatched = within("dispatched", svc.next()).await.unwrap();
-    let _c2 = caller
-        .call("agent.rollback", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap(); // fills the queue
-
-    let art = sealed(&caller, b"payload", "application/octet-stream").await;
-    let before = e.stats();
-    let refused = caller
-        .call(
-            "agent.rollback",
-            None,
-            "Work",
-            obj(json!({})),
-            &[("x", &art)],
-        )
-        .await
-        .unwrap_err();
-    assert_eq!(refused.code, ErrorCode::Backpressure);
-    assert_eq!(
-        e.stats(),
-        before,
-        "a refused call must not touch any existing root, owner or byte count"
-    );
-    drop(dispatched);
-}
-
-// -------------------------------------------------------------------------------------------
-// Disconnect cleanup (bus-v1 section 8.4)
-
-/// An abrupt disconnect (no `artifact.release` ever sent) must still abandon an unsealed
-/// writer's staging reservation.
-async fn disconnect_abandons_an_unsealed_writer(via: Via) {
-    let e = env(via).await;
-    {
-        let mut raw = e.raw_hello("producer").await;
-        let (_alloc, path) = raw.allocate(64).await;
-        std::fs::write(&path, [7u8; 64]).unwrap();
-        e.settle("writer visible", |s| {
-            s.artifacts == 1 && s.store_bytes == 64
-        })
-        .await;
-        // `raw` drops here without ever releasing anything.
-    }
-    e.settle("disconnect abandoned the writer", |s| {
-        s.artifacts == 0 && s.store_bytes == 0 && s.owners == 0
-    })
-    .await;
-    assert_eq!(e.files("staging"), 0);
-}
-
-/// An abrupt disconnect must release an explicit hold too, when it was the object's only root.
-async fn disconnect_releases_an_explicit_hold(via: Via) {
-    let e = env(via).await;
-    {
-        let mut raw = e.raw_hello("producer").await;
-        let (alloc, path) = raw.allocate(5).await;
-        std::fs::write(&path, b"hello").unwrap();
-        let reply = raw.seal(&alloc, Value::Null).await.unwrap();
-        assert!(reply.contains_key("ref"));
-    }
-    e.settle("disconnect released the only hold", |s| {
-        s.sealed_artifacts == 0 && s.owners == 0 && s.store_bytes == 0
-    })
-    .await;
-    assert_eq!(e.files("sealed"), 0);
-}
-
-/// A vanished subscriber must give up both a delivery it already holds and one still queued
-/// behind it, never issued to the wire.
-async fn disconnect_releases_queued_and_dispatched_deliveries(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    p.declare_topic("t.gone", Retained::None).await.unwrap();
-    {
-        let mut raw = e.raw_hello("subscriber").await;
-        assert_eq!(
-            code(&raw.call("subscribe", json!({"topic": "t.gone", "mode": "bounded", "maxQueued": 4, "maxInFlight": 1, "replayLatest": false})).await),
-            "OK"
-        );
-        let a1 = sealed(&p, b"m1", "application/octet-stream").await;
-        let a2 = sealed(&p, b"m2", "application/octet-stream").await;
-        p.publish("t.gone", obj(json!({})), &[("x", &a1)])
-            .await
-            .unwrap();
-        p.publish("t.gone", obj(json!({})), &[("x", &a2)])
-            .await
-            .unwrap();
-        drop((a1, a2));
-        let delivered = within("dispatched delivery", raw.event()).await;
-        assert_eq!(delivered.op, "topic.message");
-        e.settle("one dispatched, one still queued", |s| {
-            s.artifact_roots == 2 && s.sealed_artifacts == 2
-        })
-        .await;
-        // `raw` drops here without ever consuming the dispatched delivery.
-    }
-    e.settle("disconnect released both", |s| {
-        s.artifact_roots == 0 && s.owners == 0 && s.sealed_artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-}
-
-// -------------------------------------------------------------------------------------------
-// Stale references, stale generations and forged/borrowed owners
-
-async fn stale_store_incarnation_and_generation_are_rejected(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("c").await;
-    let (alloc, path) = raw.allocate(4).await;
-    std::fs::write(&path, b"data").unwrap();
-    let sealed_reply = raw.seal(&alloc, Value::Null).await.unwrap();
-
-    let mut bad_store_ref = sealed_reply["ref"].clone();
-    bad_store_ref["storeId"] = json!("store-does-not-exist");
-    let r = raw
-        .call(
-            "artifact.open",
-            json!({"ref": bad_store_ref, "ownerId": sealed_reply["ownerId"]}),
-        )
-        .await;
-    assert_eq!(
-        code(&r),
-        "ARTIFACT_GONE",
-        "a reference naming another store incarnation is stale"
-    );
-
-    let (alloc2, path2) = raw.allocate(4).await;
-    std::fs::write(&path2, b"more!").unwrap();
-    let bad_generation = raw
-        .call("artifact.seal", json!({"artifactId": alloc2["artifactId"], "generation": "2", "ownerId": alloc2["ownerId"], "digest": Value::Null}))
-        .await;
-    assert_eq!(
-        code(&bad_generation),
-        "ARTIFACT_GONE",
-        "v1 has exactly one generation"
-    );
-}
-
-async fn owner_ids_are_scoped_to_their_connection(via: Via) {
-    let e = env(via).await;
-    let mut a = e.raw_hello("a").await;
-    let mut b = e.raw_hello("b").await;
-    let (alloc, path) = a.allocate(4).await;
-    std::fs::write(&path, b"data").unwrap();
-    let sealed_reply = a.seal(&alloc, Value::Null).await.unwrap();
-    let (reference, owner_id) = (sealed_reply["ref"].clone(), sealed_reply["ownerId"].clone());
-
-    // `b` was never issued this owner id; a real owner id from another connection is just as
-    // invalid as one that was never issued at all.
-    assert_eq!(
-        code(
-            &b.call(
-                "artifact.open",
-                json!({"ref": reference, "ownerId": owner_id})
-            )
-            .await
-        ),
-        "OWNER_INVALID"
-    );
-    assert_eq!(
-        code(
-            &b.call(
-                "artifact.retain",
-                json!({"ref": reference, "ownerId": owner_id})
-            )
-            .await
-        ),
-        "OWNER_INVALID"
-    );
-
-    // The writer's own owner id cannot open before sealing.
-    let (alloc2, path2) = a.allocate(4).await;
-    std::fs::write(&path2, b"data").unwrap();
-    let unsealed_ref = json!({
-        "storeId": alloc2["writeLocation"]["storeId"], "artifactId": alloc2["artifactId"], "generation": "1",
-        "byteLength": "4", "contentType": "application/octet-stream", "digest": Value::Null,
-    });
-    assert_eq!(
-        code(
-            &a.call(
-                "artifact.open",
-                json!({"ref": unsealed_ref, "ownerId": alloc2["ownerId"]})
-            )
-            .await
-        ),
-        "ARTIFACT_UNSEALED"
-    );
-
-    // A malformed owner id is refused outright, not treated as an unknown serial.
-    assert_eq!(
-        code(
-            &a.call(
-                "artifact.open",
-                json!({"ref": reference, "ownerId": "not-an-owner"})
-            )
-            .await
-        ),
-        "OWNER_INVALID"
-    );
-}
-
-// -------------------------------------------------------------------------------------------
-// Bounds, quotas and path containment (bus-v1 section 4/9)
-
-async fn artifact_bounds_and_owner_budget_are_enforced(via: Via) {
-    let limits = Limits {
-        max_artifact_bytes: 100,
-        max_store_bytes: 160,
-        max_owners_per_client: 4,
-        reserved_owners_per_client: 1,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let c = e.client("c").await;
-
-    let too_big = c
-        .artifacts()
-        .allocate(101, "application/octet-stream")
-        .await
-        .unwrap_err();
-    assert_eq!(
-        too_big.code,
-        ErrorCode::QuotaExceeded,
-        "byteLength exceeds the per-object limit"
-    );
-
-    let a = sealed(&c, &[0u8; 80], "application/octet-stream").await;
-    let before = e.stats();
-    let no_room = c
-        .artifacts()
-        .allocate(90, "application/octet-stream")
-        .await
-        .unwrap_err();
-    assert_eq!(no_room.code, ErrorCode::QuotaExceeded, "the store is full");
-    assert_eq!(
-        e.stats(),
-        before,
-        "a rejected allocation must not charge the store"
-    );
-
-    // Owner budget: 4 total minus 1 reserved leaves room for 3 ordinary owners; `a` itself is
-    // already one of them, so exactly two more retains fit.
-    let h1 = a.retain().await.unwrap();
-    let h2 = a.retain().await.unwrap();
-    let over = a.retain().await.unwrap_err();
-    assert_eq!(
-        over.code,
-        ErrorCode::QuotaExceeded,
-        "owner budget exhausted"
-    );
-    drop((h1, h2, a));
-}
-
-/// Every location the router issues stays a plain relative path under the store; the router
-/// never hands the client anything to escape with (store.rs enforces this on the resolving
-/// side; this checks the issuing side never even offers an unsafe shape).
-async fn issued_locations_are_relative_and_contained(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("c").await;
-    let (alloc, path) = raw.allocate(4).await;
-    let assert_safe = |loc: &Value| {
-        assert_eq!(loc["storeId"].as_str().unwrap(), e.router.store_id());
-        let rel = loc["relativePath"].as_str().unwrap();
-        assert!(
-            !rel.starts_with('/') && !rel.contains(".."),
-            "{rel:?} escapes the store"
-        );
-        assert!(
-            rel.bytes().all(|b| b.is_ascii_lowercase()
-                || b.is_ascii_digit()
-                || matches!(b, b'.' | b'_' | b'-' | b'/')),
-            "{rel:?} has an unexpected character"
-        );
-    };
-    assert_safe(&alloc["writeLocation"]);
-
-    std::fs::write(&path, b"data").unwrap();
-    let sealed_reply = raw.seal(&alloc, Value::Null).await.unwrap();
-    let open_reply = raw
-        .call(
-            "artifact.open",
-            json!({"ref": sealed_reply["ref"], "ownerId": sealed_reply["ownerId"]}),
-        )
-        .await
-        .unwrap();
-    assert_safe(&open_reply["readLocation"]);
-    assert_eq!(
-        std::fs::read(raw.path(&open_reply["readLocation"])).unwrap(),
-        b"data"
-    );
-}
-
-both_transports!(
-    allocate_write_seal_open_roundtrip_and_mismatches,
-    seal_is_immutable_despite_a_stale_writable_handle,
-    extracted_artifact_outlives_the_message_it_came_from,
-    explicit_retain_outlives_the_original_hold,
-    collection_waits_for_every_retained_owner,
-    queued_deliveries_hold_roots_before_dispatch,
-    latest_mode_holds_at_most_two_roots_delivered_plus_queued,
-    retained_topic_value_holds_a_root_independent_of_subscribers,
-    forward_requires_the_source_owner_still_live,
-    rejected_publish_creates_no_roots,
-    rejected_call_creates_no_roots,
-    disconnect_abandons_an_unsealed_writer,
-    disconnect_releases_an_explicit_hold,
-    disconnect_releases_queued_and_dispatched_deliveries,
-    stale_store_incarnation_and_generation_are_rejected,
-    owner_ids_are_scoped_to_their_connection,
-    artifact_bounds_and_owner_budget_are_enforced,
-    issued_locations_are_relative_and_contained,
-);

services/flysim/crates/flybus/tests/conformance_routing.rs

@@ -1,596 +0,0 @@
-//! Routing conformance: adversarial contract cases for bus-v1 sections 5-8, deliberately not
-//! duplicating the happy paths already covered by `rpc.rs` and `pubsub.rs`. Generic synthetic
-//! services and topics only; no application/session semantics. Every test runs over both the
-//! in-memory transport and a Unix socket.
-
-mod common;
-
-use common::{Via, env, obj, quiet, sealed, within};
-use flybus::{CancelState, Dispatch, ErrorCode, Retained, ServiceConfig, SubscriptionConfig};
-use serde_json::json;
-
-/// bus-v1 section 5: "One live registration owns a service name." A client re-registering a
-/// name it already owns is a duplicate too, not an idempotent no-op, and the failed attempt
-/// must not disturb the live registration.
-async fn duplicate_registration_by_owner_itself_is_rejected(via: Via) {
-    let e = env(via).await;
-    let a = e.client("a").await;
-    let caller = e.client("caller").await;
-    let mut svc = a
-        .register("agent.self", ServiceConfig::default())
-        .await
-        .unwrap();
-    let incarnation = svc.incarnation().to_owned();
-    let dup = a
-        .register("agent.self", ServiceConfig::default())
-        .await
-        .unwrap_err();
-    assert_eq!(dup.code, ErrorCode::Conflict);
-    assert_eq!(
-        svc.incarnation(),
-        incarnation,
-        "the failed self-duplicate did not replace the live registration"
-    );
-    let mut pending = caller
-        .call("agent.self", Some(&incarnation), "M", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    assert!(req.reply(obj(json!({"ok": true})), &[]).await.unwrap());
-    assert_eq!(
-        within("result", pending.result()).await.unwrap().outcome()["ok"],
-        true
-    );
-}
-
-/// bus-v1 section 3: "Callers pin it after discovery." An unpinned call made *after* the name
-/// changes hands must resolve to the new incarnation, never linger on the old one.
-async fn unpinned_call_after_incarnation_replacement_reaches_the_new_holder(via: Via) {
-    let e = env(via).await;
-    let a = e.client("a").await;
-    let b = e.client("b").await;
-    let caller = e.client("caller").await;
-    let first = a
-        .register("agent.fly", ServiceConfig::default())
-        .await
-        .unwrap();
-    let old = first.incarnation().to_owned();
-    drop(first);
-    // Unregistration is asynchronous; wait for the name to come free.
-    let mut second = loop {
-        match b.register("agent.fly", ServiceConfig::default()).await {
-            Ok(s) => break s,
-            Err(err) => assert_eq!(err.code, ErrorCode::Conflict),
-        }
-    };
-    assert_ne!(second.incarnation(), old);
-    let mut pending = caller
-        .call("agent.fly", None, "M", obj(json!({})), &[])
-        .await
-        .unwrap();
-    assert_eq!(
-        pending.service_incarnation(),
-        second.incarnation(),
-        "unpinned discovery resolves to the current holder"
-    );
-    let req = within("request", second.next()).await.unwrap();
-    assert_eq!(req.service_incarnation(), second.incarnation());
-    assert!(
-        req.reply(obj(json!({"from": "second"})), &[])
-            .await
-            .unwrap()
-    );
-    assert_eq!(
-        within("result", pending.result()).await.unwrap().outcome()["from"],
-        "second"
-    );
-}
-
-/// bus-v1 section 6: "responses may complete out of order and correlate by callId." Two callers
-/// interleave calls to the same service and the service answers in reverse admission order;
-/// every result must reach the caller it belongs to, never a sibling's.
-async fn out_of_order_replies_correlate_across_concurrent_callers(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let alice = e.client("alice").await;
-    let bob = e.client("bob").await;
-    let mut svc = server
-        .register(
-            "example.multi",
-            ServiceConfig {
-                max_queued: 8,
-                max_in_flight: 4,
-            },
-        )
-        .await
-        .unwrap();
-    let mut a1 = alice
-        .call(
-            "example.multi",
-            None,
-            "M",
-            obj(json!({"who": "alice", "n": 1})),
-            &[],
-        )
-        .await
-        .unwrap();
-    let mut b1 = bob
-        .call(
-            "example.multi",
-            None,
-            "M",
-            obj(json!({"who": "bob", "n": 1})),
-            &[],
-        )
-        .await
-        .unwrap();
-    let mut a2 = alice
-        .call(
-            "example.multi",
-            None,
-            "M",
-            obj(json!({"who": "alice", "n": 2})),
-            &[],
-        )
-        .await
-        .unwrap();
-    let mut b2 = bob
-        .call(
-            "example.multi",
-            None,
-            "M",
-            obj(json!({"who": "bob", "n": 2})),
-            &[],
-        )
-        .await
-        .unwrap();
-    let mut reqs = Vec::new();
-    for _ in 0..4 {
-        reqs.push(within("request", svc.next()).await.unwrap());
-    }
-    // Reply in the reverse of admission order.
-    for r in reqs.iter().rev() {
-        let who = r.payload()["who"].clone();
-        let n = r.payload()["n"].clone();
-        assert!(
-            r.reply(obj(json!({"who": who, "n": n})), &[])
-                .await
-                .unwrap()
-        );
-    }
-    drop(reqs);
-    let ra1 = within("a1", a1.result()).await.unwrap();
-    let rb1 = within("b1", b1.result()).await.unwrap();
-    let ra2 = within("a2", a2.result()).await.unwrap();
-    let rb2 = within("b2", b2.result()).await.unwrap();
-    assert_eq!(
-        (ra1.outcome()["who"].as_str(), ra1.outcome()["n"].clone()),
-        (Some("alice"), json!(1))
-    );
-    assert_eq!(
-        (rb1.outcome()["who"].as_str(), rb1.outcome()["n"].clone()),
-        (Some("bob"), json!(1))
-    );
-    assert_eq!(
-        (ra2.outcome()["who"].as_str(), ra2.outcome()["n"].clone()),
-        (Some("alice"), json!(2))
-    );
-    assert_eq!(
-        (rb2.outcome()["who"].as_str(), rb2.outcome()["n"].clone()),
-        (Some("bob"), json!(2))
-    );
-}
-
-/// bus-v1 section 5: "Queued cancellation releases its queued artifact roots." Not exercised by
-/// `cancellation_states`, which never attaches artifacts.
-async fn cancel_before_dispatch_releases_queued_artifact_roots(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "example.holdup",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let _held = caller
-        .call("example.holdup", None, "Work", obj(json!({"n": 1})), &[])
-        .await
-        .unwrap();
-    let req1 = within("request 1", svc.next()).await.unwrap();
-    let art = sealed(&caller, b"queued-payload", "text/plain").await;
-    let queued = caller
-        .call(
-            "example.holdup",
-            None,
-            "Work",
-            obj(json!({"n": 2})),
-            &[("x", &art)],
-        )
-        .await
-        .unwrap();
-    drop(art); // only the queued call's own root should keep the bytes alive now
-    e.settle("the queued call's attachment is rooted", |s| {
-        s.artifacts == 1 && s.artifact_roots >= 1
-    })
-    .await;
-    assert_eq!(
-        queued.cancel().await.unwrap(),
-        CancelState::CancelledBeforeDispatch
-    );
-    e.settle("cancelling before dispatch released the queued root", |s| {
-        s.artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-    drop(req1);
-}
-
-/// bus-v1 section 6: after a post-dispatch cancel, "a later reply to a detached call returns
-/// `routed:false`, with no caller-result roots" — including when that late reply carries an
-/// artifact the caller must never see rooted.
-async fn cancel_after_dispatch_then_late_reply_with_artifact_is_not_routed(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.late", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut dispatched = caller
-        .call("example.late", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    assert_eq!(
-        dispatched.cancel().await.unwrap(),
-        CancelState::ExecutionUnknown
-    );
-    let art = sealed(&server, b"late-with-artifact", "text/plain").await;
-    let routed = req.reply(obj(json!({})), &[("a", &art)]).await.unwrap();
-    assert!(
-        !routed,
-        "a detached call must not be routed, artifact attached or not"
-    );
-    drop((req, art));
-    e.settle("no caller-side roots leaked from a detached reply", |s| {
-        s.artifacts == 0 && s.owners == 0
-    })
-    .await;
-    let after = within("result of a cancelled call", dispatched.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (after.code, after.dispatch),
-        (ErrorCode::CallGone, Dispatch::Unknown)
-    );
-}
-
-/// bus-v1 section 8.4: a caller's full disconnection (not merely dropping its pending future)
-/// detaches its dispatched call, and the service itself keeps serving other callers afterward.
-async fn caller_disconnect_detaches_dispatched_call_but_service_keeps_serving(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.vanish", ServiceConfig::default())
-        .await
-        .unwrap();
-    let pending = caller
-        .call("example.vanish", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    caller.close().await;
-    e.settle("caller gone", |s| s.connections == 1).await;
-    drop(pending); // inert now: must not panic or double-release
-    let routed = req.reply(obj(json!({"late": true})), &[]).await.unwrap();
-    assert!(!routed, "the vanished caller cannot receive the reply");
-    drop(req);
-    e.settle("everything the vanished caller held is cleaned up", |s| {
-        s.calls == 0 && s.owners == 0
-    })
-    .await;
-    let other = e.client("other").await;
-    let mut fresh = other
-        .call("example.vanish", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req2 = within("second request", svc.next()).await.unwrap();
-    assert!(req2.reply(obj(json!({"ok": true})), &[]).await.unwrap());
-    assert_eq!(
-        within("result", fresh.result()).await.unwrap().outcome()["ok"],
-        true
-    );
-}
-
-/// bus-v1 section 8.4: disconnect "release[s] that connection's active writers/explicit/delivery
-/// roots", for a subscriber holding both delivered-but-unconsumed and still-queued artifacts,
-/// while a topic's retained value (owned by the topic, not the connection) survives untouched.
-async fn subscriber_disconnect_releases_queued_and_delivered_artifacts_but_not_retention(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let reader = e.client("reader").await;
-    publisher
-        .declare_topic("t.gone", Retained::Latest)
-        .await
-        .unwrap();
-    let mut sub = reader
-        .subscribe(
-            "t.gone",
-            SubscriptionConfig::bounded().queued(4).in_flight(4),
-        )
-        .await
-        .unwrap();
-    for i in 0..3 {
-        let a = sealed(&publisher, format!("m{i}").as_bytes(), "text/plain").await;
-        publisher
-            .publish("t.gone", obj(json!({})), &[("m", &a)])
-            .await
-            .unwrap();
-    }
-    let first = within("first delivered", sub.next()).await.unwrap();
-    e.settle("three sealed objects, all rooted", |s| {
-        s.sealed_artifacts == 3
-    })
-    .await;
-    drop(first);
-    reader.close().await;
-    e.settle(
-        "everything the reader held is gone; only retention remains",
-        |s| s.sealed_artifacts == 1 && s.subscriptions == 0 && s.connections == 1,
-    )
-    .await;
-    let art = sealed(&publisher, b"after-disconnect", "text/plain").await;
-    publisher
-        .publish("t.gone", obj(json!({})), &[("m", &art)])
-        .await
-        .unwrap();
-    drop(art);
-    e.settle("retention alone carries the new value", |s| {
-        s.sealed_artifacts == 1 && s.artifact_roots == 1
-    })
-    .await;
-}
-
-/// bus-v1 section 7: "reject the whole publish; no partial fan-out or retained-latest update."
-/// Not exercised with attachments by `bounded_fifo_and_atomic_backpressure`: a refused publish
-/// must leave no artifact root anywhere, on any subscriber. `maxQueued` and `maxInFlight` are
-/// separate counters, so filling `tight`'s single in-flight credit does not yet overflow it;
-/// its one queue slot has to fill too before a third publish overflows it.
-async fn bounded_overflow_rolls_back_all_artifact_roots(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let roomy = e.client("roomy").await;
-    let tight = e.client("tight").await;
-    publisher
-        .declare_topic("t.atomic", Retained::None)
-        .await
-        .unwrap();
-    let mut a = roomy
-        .subscribe(
-            "t.atomic",
-            SubscriptionConfig::bounded().queued(4).in_flight(4),
-        )
-        .await
-        .unwrap();
-    let _tight_sub = tight
-        .subscribe(
-            "t.atomic",
-            SubscriptionConfig::bounded().queued(1).in_flight(1),
-        )
-        .await
-        .unwrap();
-    let art1 = sealed(&publisher, b"one", "text/plain").await;
-    publisher
-        .publish("t.atomic", obj(json!({})), &[("x", &art1)])
-        .await
-        .unwrap(); // fills tight's in-flight credit
-    drop(art1);
-    let art2 = sealed(&publisher, b"two", "text/plain").await;
-    publisher
-        .publish("t.atomic", obj(json!({})), &[("x", &art2)])
-        .await
-        .unwrap(); // fills tight's one queue slot
-    drop(art2);
-    e.settle("two objects rooted before the overflow attempt", |s| {
-        s.sealed_artifacts == 2
-    })
-    .await;
-    let art3 = sealed(&publisher, b"three", "text/plain").await;
-    let refused = publisher
-        .publish("t.atomic", obj(json!({})), &[("x", &art3)])
-        .await
-        .unwrap_err();
-    assert_eq!(refused.code, ErrorCode::Backpressure);
-    drop(art3);
-    e.settle(
-        "the refused publish left no trace: still exactly the first two objects",
-        |s| s.sealed_artifacts == 2,
-    )
-    .await;
-    let m1 = within("a's first", a.next()).await.unwrap();
-    assert_eq!(m1.artifact("x").unwrap().read_all().await.unwrap(), b"one");
-    let m2 = within("a's second", a.next()).await.unwrap();
-    assert_eq!(m2.artifact("x").unwrap().read_all().await.unwrap(), b"two");
-    quiet("a never saw the refused publish", a.next()).await;
-}
-
-/// bus-v1 section 7: "New subscriptions with replayLatest enqueue it before subsequent accepted
-/// publications." A fresh `latest` subscription's replay claims its first in-flight credit
-/// immediately (there is nothing else competing for it yet), so a publish accepted right after
-/// subscribing must still be observed strictly after the replay, never ahead of or merged with
-/// it: each keeps its own delivery.
-async fn latest_replay_is_ordered_ahead_of_a_racing_publish(via: Via) {
-    let e = env(via).await;
-    let admin = e.client("admin").await;
-    let reader = e.client("reader").await;
-    admin
-        .declare_topic("t.replay-race", Retained::Latest)
-        .await
-        .unwrap();
-    admin
-        .publish("t.replay-race", obj(json!({"v": "old"})), &[])
-        .await
-        .unwrap();
-    let mut sub = reader
-        .subscribe(
-            "t.replay-race",
-            SubscriptionConfig::latest().in_flight(1).replay(true),
-        )
-        .await
-        .unwrap();
-    admin
-        .publish("t.replay-race", obj(json!({"v": "new"})), &[])
-        .await
-        .unwrap();
-    let first = within("the replay arrives first", sub.next())
-        .await
-        .unwrap();
-    assert_eq!(first.payload()["v"], "old");
-    drop(first); // the sole in-flight credit must return before the queued second value moves
-    let second = within("the racing publish follows, not coalesced away", sub.next())
-        .await
-        .unwrap();
-    assert_eq!(second.payload()["v"], "new");
-}
-
-/// bus-v1 section 7: clearing releases only the retained root; a later `replayLatest`
-/// subscription must see nothing until a fresh publish, not a stale or resurrected value.
-async fn cleared_topic_gives_no_replay_until_a_fresh_publish(via: Via) {
-    let e = env(via).await;
-    let admin = e.client("admin").await;
-    let reader = e.client("reader").await;
-    admin
-        .declare_topic("t.clear-replay", Retained::Latest)
-        .await
-        .unwrap();
-    admin
-        .publish("t.clear-replay", obj(json!({"v": 1})), &[])
-        .await
-        .unwrap();
-    assert!(admin.clear_topic("t.clear-replay").await.unwrap());
-    let mut sub = reader
-        .subscribe("t.clear-replay", SubscriptionConfig::bounded().replay(true))
-        .await
-        .unwrap();
-    quiet("nothing retained to replay after a clear", sub.next()).await;
-    admin
-        .publish("t.clear-replay", obj(json!({"v": 2})), &[])
-        .await
-        .unwrap();
-    let m = within("a fresh publish arrives normally", sub.next())
-        .await
-        .unwrap();
-    assert_eq!(m.payload()["v"], 2);
-}
-
-/// bus-v1 section 8.3: "dropping the message alone does not consume the delivery while a
-/// renderer/encoder still uses its artifact." `latest_coalesces_only_undelivered_values` proves
-/// this for `latest` mode; delivery-credit accounting must honour it for `bounded` mode too.
-async fn bounded_credit_waits_for_every_extracted_artifact(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let reader = e.client("reader").await;
-    publisher
-        .declare_topic("t.credit-hold", Retained::None)
-        .await
-        .unwrap();
-    let mut sub = reader
-        .subscribe(
-            "t.credit-hold",
-            SubscriptionConfig::bounded().in_flight(1).queued(4),
-        )
-        .await
-        .unwrap();
-    let a0 = sealed(&publisher, b"m0", "text/plain").await;
-    let a1 = sealed(&publisher, b"m1", "text/plain").await;
-    publisher
-        .publish("t.credit-hold", obj(json!({})), &[("x", &a0)])
-        .await
-        .unwrap();
-    publisher
-        .publish("t.credit-hold", obj(json!({})), &[("x", &a1)])
-        .await
-        .unwrap();
-    drop((a0, a1));
-    let m0 = within("first", sub.next()).await.unwrap();
-    let held = m0.artifact("x").unwrap();
-    drop(m0); // the message struct is gone, but `held` still shares its delivery guard
-    quiet(
-        "credit withheld while an extracted artifact is still alive",
-        sub.next(),
-    )
-    .await;
-    drop(held);
-    let m1 = within("second, only after the real release", sub.next())
-        .await
-        .unwrap();
-    assert_eq!(m1.artifact("x").unwrap().read_all().await.unwrap(), b"m1");
-}
-
-/// Subscription ids are serials local to the issuing connection (`sub-<n>`), not a global
-/// namespace: a second connection quoting another connection's literal id string has no route
-/// to that subscription at all, so it can only ever land on (at most) its own same-numbered
-/// subscription, never the owner's. `unsubscribe` reports this as `removed:false`, not an
-/// error, and the owner's subscription keeps receiving messages untouched.
-async fn unsubscribe_cannot_reach_another_connections_subscription_id(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    publisher
-        .declare_topic("t.owned", Retained::None)
-        .await
-        .unwrap();
-    let mut owner_raw = e.raw_hello("owner").await;
-    let sub_id = {
-        let r = owner_raw
-            .call("subscribe", json!({"topic": "t.owned", "mode": "bounded", "maxQueued": 4, "maxInFlight": 4, "replayLatest": false}))
-            .await
-            .unwrap();
-        r["subscriptionId"].as_str().unwrap().to_owned()
-    };
-    let mut intruder = e.raw_hello("intruder").await;
-    let r = intruder
-        .call("unsubscribe", json!({"subscriptionId": sub_id.clone()}))
-        .await
-        .unwrap();
-    assert_eq!(
-        r["removed"],
-        json!(false),
-        "the intruder issued no such subscription itself"
-    );
-
-    // The owner's subscription is unaffected by the intruder's attempt.
-    let art = sealed(&publisher, b"still-mine", "text/plain").await;
-    publisher
-        .publish("t.owned", obj(json!({})), &[("x", &art)])
-        .await
-        .unwrap();
-    drop(art);
-    let delivered = owner_raw.event().await;
-    assert_eq!(delivered.op, "topic.message");
-
-    let removed = owner_raw
-        .call("unsubscribe", json!({"subscriptionId": sub_id}))
-        .await
-        .unwrap();
-    assert_eq!(removed["removed"], json!(true));
-}
-
-both_transports!(
-    duplicate_registration_by_owner_itself_is_rejected,
-    unpinned_call_after_incarnation_replacement_reaches_the_new_holder,
-    out_of_order_replies_correlate_across_concurrent_callers,
-    cancel_before_dispatch_releases_queued_artifact_roots,
-    cancel_after_dispatch_then_late_reply_with_artifact_is_not_routed,
-    caller_disconnect_detaches_dispatched_call_but_service_keeps_serving,
-    subscriber_disconnect_releases_queued_and_delivered_artifacts_but_not_retention,
-    bounded_overflow_rolls_back_all_artifact_roots,
-    latest_replay_is_ordered_ahead_of_a_racing_publish,
-    cleared_topic_gives_no_replay_until_a_fresh_publish,
-    bounded_credit_waits_for_every_extracted_artifact,
-    unsubscribe_cannot_reach_another_connections_subscription_id,
-);

services/flysim/crates/flybus/tests/conformance_wire.rs

@@ -1,640 +0,0 @@
-//! Wire and transport conformance (bus-v1 §4 and §11 acceptance test 1): bounded
-//! little-endian framing, partial reads/writes, strict JSON (duplicate keys at any depth,
-//! invalid UTF-8, unknown fields), malformed ids/u64s, connection negotiation, and behavioral
-//! parity between the in-memory and Unix-domain transports.
-//!
-//! This suite speaks the raw protocol by hand rather than going through the SDK: it sends
-//! frames no correct client would ever construct, so it can check what the router does with a
-//! hostile or merely buggy peer, not just what a well-behaved one gets back.
-
-mod common;
-
-use std::io;
-use std::pin::Pin;
-use std::task::{Context, Poll};
-use std::time::Duration;
-
-use common::{Via, code, env, obj, within};
-use flybus::Limits;
-use flybus::wire::{Envelope, Kind, MAX_ENVELOPE_BYTES, contract_digest, read_frame, write_frame};
-use serde_json::{Map, Value, json};
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf};
-
-// -------------------------------------------------------------------------------------------
-// Low-level helpers: a hand-rolled connection independent of `common::Raw`, for the framing
-// tests that need control over individual bytes and reads that `Raw`'s all-at-once
-// `send_bytes` cannot express.
-
-/// Forces every read through this wrapper to surface at most one byte, so a caller reading a
-/// frame through it can only succeed by looping the way [`read_frame`] does — never by
-/// getting lucky with one big read.
-struct Trickle<R> {
-    inner: R,
-}
-
-impl<R: AsyncRead + Unpin> AsyncRead for Trickle<R> {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        let this = self.get_mut();
-        let mut one = [0u8; 1];
-        let mut small = ReadBuf::new(&mut one);
-        match Pin::new(&mut this.inner).poll_read(cx, &mut small) {
-            Poll::Ready(Ok(())) => {
-                let n = small.filled().len();
-                if n > 0 {
-                    buf.put_slice(&one[..n]);
-                }
-                Poll::Ready(Ok(()))
-            }
-            other => other,
-        }
-    }
-}
-
-async fn send_envelope(
-    wr: &mut (impl AsyncWrite + Unpin),
-    id: &str,
-    op: &str,
-    body: Map<String, Value>,
-) {
-    let env = Envelope::new(id.to_owned(), Kind::Command, op, body);
-    write_frame(wr, &env.encode().unwrap()).await.unwrap();
-}
-
-/// Writes the same frame [`send_envelope`] would, one byte at a time, flushing and yielding
-/// between every byte.
-async fn send_envelope_byte_by_byte(
-    wr: &mut (impl AsyncWrite + Unpin),
-    id: &str,
-    op: &str,
-    body: Map<String, Value>,
-) {
-    let env = Envelope::new(id.to_owned(), Kind::Command, op, body);
-    let bytes = env.encode().unwrap();
-    let len = (bytes.len() as u32).to_le_bytes();
-    for byte in len.iter().chain(bytes.iter()) {
-        wr.write_all(std::slice::from_ref(byte)).await.unwrap();
-        wr.flush().await.unwrap();
-        tokio::task::yield_now().await;
-    }
-}
-
-async fn recv_envelope(rd: &mut (impl AsyncRead + Unpin)) -> Envelope {
-    let bytes = within("frame", read_frame(rd))
-        .await
-        .unwrap()
-        .expect("stream open");
-    Envelope::decode(&bytes).unwrap()
-}
-
-/// A hand-rolled `bus.hello`, sent as command `msg-1`. Returns the reply's `value` object.
-async fn manual_hello(
-    rd: &mut (impl AsyncRead + Unpin),
-    wr: &mut (impl AsyncWrite + Unpin),
-    id: &str,
-    slow: bool,
-) -> Map<String, Value> {
-    let body = obj(
-        json!({"clientId": id, "clientIncarnation": format!("inc-{id}"), "supportedMajors": [1]}),
-    );
-    if slow {
-        send_envelope_byte_by_byte(wr, "msg-1", "bus.hello", body).await;
-    } else {
-        send_envelope(wr, "msg-1", "bus.hello", body).await;
-    }
-    let reply = recv_envelope(rd).await;
-    assert_eq!(reply.kind, Kind::Reply);
-    assert_eq!(reply.reply_to.as_deref(), Some("msg-1"));
-    assert_eq!(
-        reply.body["ok"],
-        json!(true),
-        "hello failed: {:?}",
-        reply.body
-    );
-    reply.body["value"].as_object().unwrap().clone()
-}
-
-// -------------------------------------------------------------------------------------------
-// Bounded little-endian framing (bus-v1 §4: "Reject ... zero/oversize frames. Read length
-// before allocating.")
-
-async fn zero_length_frame_closes_the_connection(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("zerolen").await;
-    raw.send_prefix(0).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("a zero-length frame must close the connection with a notice");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// The length prefix is checked, and the frame refused, before any body bytes are read. We
-/// announce an oversize frame and never send its body: an implementation that read the length
-/// after allocating (or tried to read the body anyway) would hang here instead of refusing
-/// promptly, and `closing`'s bounded wait turns that into a loud failure rather than a stall.
-async fn oversize_length_prefix_is_rejected_before_reading_body(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("oversize").await;
-    raw.send_prefix((MAX_ENVELOPE_BYTES as u32) + 1).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("an oversize frame must be refused, not hung waiting for a body that never comes");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// A frame at exactly the envelope ceiling decodes and dispatches normally; the same shape one
-/// byte past it is refused before any JSON parsing.
-async fn frame_at_the_size_ceiling_is_accepted_one_byte_over_is_not(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("ceiling").await;
-    // Pad an otherwise-ordinary rpc.call to an exact byte count: measure the unpadded shape
-    // once, then fill the gap with a string needing no escaping, so each character costs
-    // exactly one byte and the target length is hit without any search.
-    let shape = |pad: usize| {
-        json!({
-            "protocol": "flybus", "major": 1, "minor": 0,
-            "id": "msg-9", "replyTo": null, "kind": "command", "op": "rpc.call",
-            "body": {
-                "callId": "call-1", "target": "no.such.service", "expectedIncarnation": null,
-                "method": "M", "payload": {"pad": "a".repeat(pad)},
-            },
-            "attachments": [],
-        })
-    };
-    let base_len = serde_json::to_vec(&shape(0)).unwrap().len();
-    let exact = serde_json::to_vec(&shape(MAX_ENVELOPE_BYTES - base_len)).unwrap();
-    assert_eq!(exact.len(), MAX_ENVELOPE_BYTES);
-    raw.send_bytes(&exact).await;
-    let reply = raw.reply("msg-9").await;
-    // Decoded and dispatched fine: an ordinary domain reply (no such service), not a refusal.
-    assert_eq!(code(&reply), "NO_SERVICE");
-
-    let mut over_raw = e.raw_hello("overceiling").await;
-    let over = serde_json::to_vec(&shape(MAX_ENVELOPE_BYTES - base_len + 1)).unwrap();
-    assert_eq!(over.len(), MAX_ENVELOPE_BYTES + 1);
-    over_raw.send_bytes(&over).await;
-    let body = over_raw
-        .closing()
-        .await
-        .expect("a frame one byte over the ceiling must be refused, not parsed");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// bus-v1 §4 specifies "u32 little-endian" explicitly. The prefix is built by hand here,
-/// independent of the library's own `to_le_bytes` call, for a frame long enough (over 255
-/// bytes) that a big-endian misreading would produce a huge, unmistakably wrong length. A
-/// byte-order regression shows up as a bounded timeout below, not a silent pass.
-async fn length_prefix_is_little_endian(via: Via) {
-    let e = env(via).await;
-    let (mut rd, mut wr) = tokio::io::split(e.transport().await);
-    manual_hello(&mut rd, &mut wr, "byteorder", false).await;
-
-    let body = obj(json!({"name": "a".repeat(190), "retained": "none"}));
-    let frame_env = Envelope::new("msg-2".into(), Kind::Command, "topic.declare", body);
-    let bytes = frame_env.encode().unwrap();
-    assert!(
-        bytes.len() > 255,
-        "the padding must force a non-trivial high byte in the length"
-    );
-    let len = bytes.len() as u32;
-    let prefix = [
-        (len & 0xFF) as u8,
-        ((len >> 8) & 0xFF) as u8,
-        ((len >> 16) & 0xFF) as u8,
-        ((len >> 24) & 0xFF) as u8,
-    ];
-    assert_eq!(
-        prefix,
-        len.to_le_bytes(),
-        "sanity: the hand-built prefix matches the standard LE encoding"
-    );
-    let mut frame = prefix.to_vec();
-    frame.extend_from_slice(&bytes);
-    wr.write_all(&frame).await.unwrap();
-    wr.flush().await.unwrap();
-
-    let reply = tokio::time::timeout(Duration::from_secs(5), recv_envelope(&mut rd))
-        .await
-        .expect("the router must read the length as little-endian, not hang reinterpreting it");
-    assert_eq!(reply.body["ok"], json!(true), "{:?}", reply.body);
-    assert_eq!(reply.body["value"]["declared"], json!(true));
-}
-
-// -------------------------------------------------------------------------------------------
-// Partial reads and writes (bus-v1 §4: "Handle partial reads/writes.")
-
-/// A stream that ends mid-frame is a clean disconnect, not a panic and not a phantom command:
-/// the router just stops reading and tears the connection down, the same as for a client that
-/// vanishes between frames.
-async fn truncated_frame_disconnects_cleanly(via: Via) {
-    let e = env(via).await;
-    {
-        let mut raw = e.raw_hello("truncated").await;
-        // Announce a 64-byte body, then drop the connection before sending any of it.
-        raw.send_prefix(64).await;
-    }
-    e.settle("the truncated connection is gone", |s| s.connections == 0)
-        .await;
-}
-
-/// A frame written to the router one byte at a time, with a yield between every byte, decodes
-/// exactly as if it had arrived in one write.
-async fn a_frame_written_one_byte_at_a_time_still_decodes(via: Via) {
-    let e = env(via).await;
-    let (mut rd, mut wr) = tokio::io::split(e.transport().await);
-    let value = manual_hello(&mut rd, &mut wr, "trickle-writer", true).await;
-    assert_eq!(value["selectedMajor"], json!(1));
-    assert_eq!(value["contractDigest"], json!(contract_digest()));
-}
-
-/// The same guarantee on the reading side: a reply read one byte at a time through
-/// [`read_frame`] — the exact function both the router and the client SDK use — reassembles
-/// correctly.
-async fn a_reply_read_one_byte_at_a_time_still_decodes(via: Via) {
-    let e = env(via).await;
-    let (rd, mut wr) = tokio::io::split(e.transport().await);
-    let mut trickle = Trickle { inner: rd };
-    let value = manual_hello(&mut trickle, &mut wr, "trickle-reader", false).await;
-    assert_eq!(value["selectedMajor"], json!(1));
-}
-
-// -------------------------------------------------------------------------------------------
-// Strict JSON: duplicate keys at any depth, invalid UTF-8.
-
-/// bus-v1 §4: "Reject duplicate JSON keys" — the same rule at the top level, nested inside
-/// `body`, and nested inside an array element within it.
-async fn duplicate_json_keys_are_rejected_at_every_depth(via: Via) {
-    let e = env(via).await;
-    let cases: [&[u8]; 4] = [
-        br#"{"protocol":"flybus","protocol":"flybus","major":1,"minor":0,"id":"msg-1","replyTo":null,"kind":"command","op":"bus.hello","body":{"clientId":"x","clientIncarnation":"y","supportedMajors":[1]},"attachments":[]}"#,
-        br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-1","replyTo":null,"kind":"command","op":"bus.hello","body":{"clientId":"x","clientId":"z","clientIncarnation":"y","supportedMajors":[1]},"attachments":[]}"#,
-        br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-1","replyTo":null,"kind":"command","op":"rpc.call","body":{"callId":"call-1","target":"a.b","expectedIncarnation":null,"method":"M","payload":{"n":{"d":1,"d":2}}},"attachments":[]}"#,
-        br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-1","replyTo":null,"kind":"command","op":"rpc.call","body":{"callId":"call-1","target":"a.b","expectedIncarnation":null,"method":"M","payload":{"items":[{"x":1,"x":2}]}},"attachments":[]}"#,
-    ];
-    for (i, case) in cases.iter().enumerate() {
-        let mut raw = e.raw().await;
-        raw.send_bytes(case).await;
-        let body = raw.closing().await;
-        assert!(
-            body.is_some(),
-            "case {i}: duplicate keys must close the connection"
-        );
-        assert_eq!(body.unwrap()["code"], json!("INVALID_ENVELOPE"), "case {i}");
-    }
-}
-
-/// Invalid UTF-8 anywhere in the frame is refused before JSON parsing starts, whether it falls
-/// inside a string value, trails a complete object, or leads the buffer.
-async fn invalid_utf8_is_rejected(via: Via) {
-    let e = env(via).await;
-    let cases: [&[u8]; 3] = [
-        b"{\"protocol\":\"flybus\",\"major\":1,\"minor\":0,\"id\":\"msg-1\",\"replyTo\":null,\"kind\":\"command\",\"op\":\"bus.hello\",\"body\":{\"clientId\":\"\xff\",\"clientIncarnation\":\"y\",\"supportedMajors\":[1]},\"attachments\":[]}",
-        b"{\"protocol\":\"flybus\",\"major\":1,\"minor\":0,\"id\":\"msg-1\",\"replyTo\":null,\"kind\":\"command\",\"op\":\"bus.hello\",\"body\":{\"clientId\":\"x\",\"clientIncarnation\":\"y\",\"supportedMajors\":[1]},\"attachments\":[]}\xff",
-        b"\xc0\x80{\"protocol\":\"flybus\"}",
-    ];
-    for (i, case) in cases.iter().enumerate() {
-        let mut raw = e.raw().await;
-        raw.send_bytes(case).await;
-        let body = raw.closing().await;
-        assert!(
-            body.is_some(),
-            "case {i}: invalid UTF-8 must close the connection"
-        );
-        assert_eq!(body.unwrap()["code"], json!("INVALID_ENVELOPE"), "case {i}");
-    }
-}
-
-// -------------------------------------------------------------------------------------------
-// Unknown envelope fields: a transport-level refusal at the envelope's own level, an ordinary
-// domain error inside an operation's body.
-
-async fn unknown_top_level_field_closes_the_connection(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    let v = json!({
-        "protocol": "flybus", "major": 1, "minor": 0,
-        "id": "msg-1", "replyTo": null, "kind": "command", "op": "bus.hello",
-        "body": {"clientId": "x", "clientIncarnation": "y", "supportedMajors": [1]},
-        "attachments": [],
-        "extra": true,
-    });
-    raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("an unknown envelope field must close the connection");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// A field the *operation* does not recognize is a normal `ok:false` reply, not a transport
-/// violation: only the envelope's own shape is the wire's concern, so the connection stays
-/// open and keeps working afterward.
-async fn unknown_body_field_is_a_domain_error_not_a_disconnect(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("unknownfield").await;
-    let bogus = json!({
-        "callId": "call-1", "target": "no.such.service", "expectedIncarnation": null,
-        "method": "M", "payload": {}, "bogus": true,
-    });
-    let reply = raw.call("rpc.call", bogus).await;
-    assert_eq!(code(&reply), "INVALID_ENVELOPE");
-    let ok = raw
-        .call(
-            "topic.declare",
-            json!({"name": "still.alive", "retained": "none"}),
-        )
-        .await;
-    assert_eq!(code(&ok), "OK");
-}
-
-// -------------------------------------------------------------------------------------------
-// Malformed ids and u64s.
-
-/// Every envelope-level scalar the wire validates before dispatch: a malformed `id`, an
-/// unparseable `kind`, and an `op` outside its `[a-z.]` alphabet. Each is refused at decode,
-/// before hello state or operation semantics are consulted at all.
-async fn malformed_envelope_scalars_are_rejected(via: Via) {
-    let e = env(via).await;
-    let hello_body = json!({"clientId": "x", "clientIncarnation": "y", "supportedMajors": [1]});
-    let base = |id: &str, kind: &str, op: &str| {
-        json!({
-            "protocol": "flybus", "major": 1, "minor": 0,
-            "id": id, "replyTo": null, "kind": kind, "op": op,
-            "body": hello_body, "attachments": [],
-        })
-    };
-    let cases = [
-        (base("", "command", "bus.hello"), "empty id"),
-        (base("MSG-1", "command", "bus.hello"), "uppercase id"),
-        (
-            base("-x", "command", "bus.hello"),
-            "id starting with a separator",
-        ),
-        (
-            base(&"a".repeat(65), "command", "bus.hello"),
-            "id over 64 characters",
-        ),
-        (base("msg-1", "bogus", "bus.hello"), "unknown kind"),
-        (base("msg-1", "command", "Bus.Hello"), "uppercase op"),
-        (base("msg-1", "command", "bus.hello1"), "digit in op"),
-    ];
-    for (v, what) in cases {
-        let mut raw = e.raw().await;
-        raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-        let body = raw.closing().await;
-        assert!(body.is_some(), "{what}: must close the connection");
-        assert_eq!(body.unwrap()["code"], json!("INVALID_ENVELOPE"), "{what}");
-    }
-}
-
-async fn non_null_reply_to_on_a_command_is_rejected(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("replyto").await;
-    let v = json!({
-        "protocol": "flybus", "major": 1, "minor": 0,
-        "id": "msg-2", "replyTo": "msg-1", "kind": "command", "op": "topic.declare",
-        "body": {"name": "a.b", "retained": "none"}, "attachments": [],
-    });
-    raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("a non-null replyTo on a command must close the connection");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// `msg-<U64>` is canonical, not merely `Id`-shaped: no leading zero, no missing digits, no
-/// other prefix.
-async fn non_canonical_command_ids_are_rejected(via: Via) {
-    let e = env(via).await;
-    for bad in ["msg-01", "msg-abc", "notmsg-1", "msg--1", "msg-"] {
-        let mut raw = e.raw().await;
-        let v = json!({
-            "protocol": "flybus", "major": 1, "minor": 0,
-            "id": bad, "replyTo": null, "kind": "command", "op": "bus.hello",
-            "body": {"clientId": "x", "clientIncarnation": "y", "supportedMajors": [1]},
-            "attachments": [],
-        });
-        raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-        let body = raw.closing().await;
-        assert!(
-            body.is_some(),
-            "{bad}: a non-canonical command id must close the connection"
-        );
-        assert_eq!(body.unwrap()["code"], json!("INVALID_ENVELOPE"), "{bad}");
-    }
-}
-
-async fn non_increasing_command_ids_are_rejected(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("nonincreasing").await; // hello already spent msg-1
-    let v = json!({
-        "protocol": "flybus", "major": 1, "minor": 0,
-        "id": "msg-1", "replyTo": null, "kind": "command", "op": "topic.declare",
-        "body": {"name": "a.b", "retained": "none"}, "attachments": [],
-    });
-    raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("a repeated command id must close the connection");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-/// Below the envelope's own `id`, an operation's own ids (`callId`) get the same canonical-U64
-/// treatment, but as an ordinary domain reply: the connection is unharmed by a bad one.
-async fn malformed_call_id_is_a_domain_error(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("badcallid").await;
-    for bad in ["call-01", "call-abc", "callx-1", ""] {
-        let reply =
-            raw.call("rpc.call", json!({"callId": bad, "target": "a.b", "expectedIncarnation": null, "method": "M", "payload": {}})).await;
-        assert_eq!(code(&reply), "INVALID_ENVELOPE", "{bad:?}");
-    }
-}
-
-/// U64-string fields (`ipc-v1.md` §2: `"0"` or `[1-9][0-9]*`, at most `u64::MAX`) reject a
-/// leading zero, a non-digit, an empty string, whitespace, a decimal point and an overflow —
-/// each as a domain error the connection survives.
-async fn malformed_u64_fields_are_a_domain_error(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("badu64").await;
-    for bad in ["01", "-1", "abc", "", "18446744073709551616", " 1", "1.0"] {
-        let reply = raw
-            .call(
-                "artifact.allocate",
-                json!({"byteLength": bad, "contentType": "application/octet-stream"}),
-            )
-            .await;
-        assert_eq!(code(&reply), "INVALID_ENVELOPE", "{bad:?}");
-    }
-    let ok = raw
-        .call(
-            "artifact.allocate",
-            json!({"byteLength": "1", "contentType": "application/octet-stream"}),
-        )
-        .await;
-    assert_eq!(code(&ok), "OK");
-}
-
-// -------------------------------------------------------------------------------------------
-// Negotiation (bus-v1 §4, "Connection negotiation").
-
-async fn first_command_must_be_hello(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    raw.command(
-        "service.register",
-        json!({"name": "x.y", "maxQueued": 1, "maxInFlight": 1}),
-        json!([]),
-    )
-    .await;
-    let body = raw
-        .closing()
-        .await
-        .expect("a non-hello first command must close the connection");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-async fn hello_refuses_an_unsupported_major(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    let reply = raw.call("bus.hello", json!({"clientId": "futuristic", "clientIncarnation": "inc-1", "supportedMajors": [2, 3]})).await;
-    assert_eq!(code(&reply), "VERSION_MISMATCH");
-    assert!(
-        raw.recv().await.is_none(),
-        "the connection must close right after refusing the major"
-    );
-}
-
-async fn hello_refuses_attachments(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    let attachments = json!([{
-        "name": "a",
-        "ref": {
-            "storeId": "s", "artifactId": "a-1", "generation": "1",
-            "byteLength": "1", "contentType": "x", "digest": null,
-        },
-        "ownerId": "o",
-    }]);
-    let reply = raw
-        .call_with(
-            "bus.hello",
-            json!({"clientId": "attacher", "clientIncarnation": "inc-1", "supportedMajors": [1]}),
-            attachments,
-        )
-        .await;
-    assert_eq!(code(&reply), "INVALID_ENVELOPE");
-}
-
-async fn a_second_hello_on_the_same_connection_is_rejected(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("rehello").await;
-    let v = json!({
-        "protocol": "flybus", "major": 1, "minor": 0,
-        "id": "msg-2", "replyTo": null, "kind": "command", "op": "bus.hello",
-        "body": {"clientId": "rehello", "clientIncarnation": "inc-2", "supportedMajors": [1]},
-        "attachments": [],
-    });
-    raw.send_bytes(&serde_json::to_vec(&v).unwrap()).await;
-    let body = raw
-        .closing()
-        .await
-        .expect("a second bus.hello must close the connection");
-    assert_eq!(body["code"], json!("INVALID_ENVELOPE"));
-}
-
-async fn hello_reports_the_contract_digest_and_valid_limits(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    let reply = raw.hello("reporter").await.unwrap();
-    assert_eq!(reply["selectedMajor"], json!(1));
-    assert_eq!(reply["selectedMinor"], json!(0));
-    assert_eq!(reply["contractDigest"], json!(contract_digest()));
-    assert!(reply["routerId"].as_str().unwrap().starts_with("router-"));
-    assert!(reply["connectionId"].as_str().unwrap().starts_with("conn-"));
-    let limits = Limits::from_json(&reply["limits"])
-        .expect("the router's own limits object must round-trip");
-    assert_eq!(limits, Limits::default());
-}
-
-both_transports!(
-    zero_length_frame_closes_the_connection,
-    oversize_length_prefix_is_rejected_before_reading_body,
-    frame_at_the_size_ceiling_is_accepted_one_byte_over_is_not,
-    length_prefix_is_little_endian,
-    truncated_frame_disconnects_cleanly,
-    a_frame_written_one_byte_at_a_time_still_decodes,
-    a_reply_read_one_byte_at_a_time_still_decodes,
-    duplicate_json_keys_are_rejected_at_every_depth,
-    invalid_utf8_is_rejected,
-    unknown_top_level_field_closes_the_connection,
-    unknown_body_field_is_a_domain_error_not_a_disconnect,
-    malformed_envelope_scalars_are_rejected,
-    non_null_reply_to_on_a_command_is_rejected,
-    non_canonical_command_ids_are_rejected,
-    non_increasing_command_ids_are_rejected,
-    malformed_call_id_is_a_domain_error,
-    malformed_u64_fields_are_a_domain_error,
-    first_command_must_be_hello,
-    hello_refuses_an_unsupported_major,
-    hello_refuses_attachments,
-    a_second_hello_on_the_same_connection_is_rejected,
-    hello_reports_the_contract_digest_and_valid_limits,
-);
-
-// -------------------------------------------------------------------------------------------
-// bus-v1 §11 acceptance test 1: "In-memory transport must pass the same tests as Unix
-// sockets." Every test above already runs on both (that is what `both_transports!` is for);
-// this one drives the identical raw script over both side by side in a single test, so a
-// transport-specific quirk in one implementation cannot hide behind "it still passes its own
-// copy of the suite."
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn memory_and_unix_negotiate_the_identical_contract() {
-    let mem = env(Via::Memory).await;
-    let unix = env(Via::Unix).await;
-    let mut raw_mem = mem.raw().await;
-    let mut raw_unix = unix.raw().await;
-
-    let hm = raw_mem.hello("parity").await.unwrap();
-    let hu = raw_unix.hello("parity").await.unwrap();
-    assert_eq!(hm["selectedMajor"], hu["selectedMajor"]);
-    assert_eq!(hm["selectedMinor"], hu["selectedMinor"]);
-    assert_eq!(hm["contractDigest"], hu["contractDigest"]);
-    assert_eq!(hm["limits"], hu["limits"]);
-
-    let cm = raw_mem
-        .call(
-            "topic.declare",
-            json!({"name": "parity.topic", "retained": "latest"}),
-        )
-        .await
-        .unwrap();
-    let cu = raw_unix
-        .call(
-            "topic.declare",
-            json!({"name": "parity.topic", "retained": "latest"}),
-        )
-        .await
-        .unwrap();
-    assert_eq!(cm["declared"], cu["declared"]);
-    assert!(cm["topicIncarnation"].as_str().unwrap().starts_with("top-"));
-    assert!(cu["topicIncarnation"].as_str().unwrap().starts_with("top-"));
-
-    // The identical malformed frame gets the identical transport-level refusal on both.
-    let mut bad_mem = mem.raw_hello("parity-bad").await;
-    let mut bad_unix = unix.raw_hello("parity-bad").await;
-    let bad_frame = br#"{"a":1,"a":2}"#;
-    bad_mem.send_bytes(bad_frame).await;
-    bad_unix.send_bytes(bad_frame).await;
-    let bm = bad_mem.closing().await.unwrap();
-    let bu = bad_unix.closing().await.unwrap();
-    assert_eq!(bm["code"], bu["code"]);
-}

services/flysim/crates/flybus/tests/integration.rs

@@ -1,272 +0,0 @@
-//! bus-v1 section 11 item 6: two parallel fake agents, complete-batch environment RPC,
-//! committed snapshot publication and a deliberately slow presentation consumer, all over one
-//! router. Generic services only; nothing here knows what a brain or a game is.
-
-mod common;
-
-use std::io::Write;
-use std::time::Duration;
-
-use common::{Via, env_with, obj, within};
-use flybus::{
-    Client, ErrorCode, Grants, Limits, Pattern, Policy, Retained, ServiceConfig, SubscriptionConfig,
-};
-use serde_json::json;
-
-const STEPS: u64 = 20;
-const FRAME: usize = 160 * 144 * 4;
-
-fn grants(f: impl FnOnce(&mut Grants)) -> Grants {
-    let mut g = Grants::default();
-    f(&mut g);
-    g
-}
-
-/// An environment service: each Advance produces a frame artifact filled with the step number.
-fn spawn_environment(client: Client, mut svc: flybus::Service) -> tokio::task::JoinHandle<()> {
-    tokio::spawn(async move {
-        while let Some(req) = svc.next().await {
-            let step = req.payload()["step"].as_u64().unwrap();
-            let mut w = client
-                .artifacts()
-                .allocate(FRAME as u64, "image/x-rgba")
-                .await
-                .unwrap();
-            w.write_all(&vec![step as u8; FRAME]).unwrap();
-            let frame = w.seal().await.unwrap();
-            req.reply(
-                obj(json!({"step": step, "width": 160, "height": 144})),
-                &[("frame", &frame)],
-            )
-            .await
-            .unwrap();
-        }
-    })
-}
-
-/// An agent service: checks the frame it was sent and answers with a digest of it.
-fn spawn_agent(name: &'static str, mut svc: flybus::Service) -> tokio::task::JoinHandle<()> {
-    tokio::spawn(async move {
-        while let Some(req) = svc.next().await {
-            let step = req.payload()["step"].as_u64().unwrap();
-            let bytes = req.artifact("frame").unwrap().read_all().await.unwrap();
-            let ok = bytes.len() == FRAME && bytes.iter().all(|b| *b == step as u8);
-            req.reply(
-                obj(json!({"agent": name, "step": step, "frameOk": ok})),
-                &[],
-            )
-            .await
-            .unwrap();
-        }
-    })
-}
-
-async fn session_over_one_router(via: Via) {
-    let policy = Policy::closed()
-        .client(
-            "coordinator",
-            grants(|g| {
-                g.call = vec![Pattern::prefix("agent."), Pattern::exact("env.demo")];
-                g.publish = vec![Pattern::prefix("session.demo.")];
-                g.manage_topics = vec![Pattern::prefix("session.demo.")];
-            }),
-        )
-        .client(
-            "agent-a",
-            grants(|g| g.register = vec![Pattern::exact("agent.fly-a")]),
-        )
-        .client(
-            "agent-b",
-            grants(|g| g.register = vec![Pattern::exact("agent.fly-b")]),
-        )
-        .client(
-            "environment",
-            grants(|g| g.register = vec![Pattern::exact("env.demo")]),
-        )
-        .client(
-            "presenter",
-            grants(|g| g.subscribe = vec![Pattern::prefix("session.demo.")]),
-        )
-        .client(
-            "recorder",
-            grants(|g| g.subscribe = vec![Pattern::prefix("session.demo.")]),
-        );
-    let e = env_with(via, Limits::default(), policy).await;
-
-    let environment = e.client("environment").await;
-    let env_svc = environment
-        .register(
-            "env.demo",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let env_inc = env_svc.incarnation().to_owned();
-    let env_task = spawn_environment(environment.clone(), env_svc);
-    let a = e.client("agent-a").await;
-    let b = e.client("agent-b").await;
-    let a_svc = a
-        .register("agent.fly-a", ServiceConfig::default())
-        .await
-        .unwrap();
-    let b_svc = b
-        .register("agent.fly-b", ServiceConfig::default())
-        .await
-        .unwrap();
-    let (a_inc, b_inc) = (
-        a_svc.incarnation().to_owned(),
-        b_svc.incarnation().to_owned(),
-    );
-    let agents = [spawn_agent("fly-a", a_svc), spawn_agent("fly-b", b_svc)];
-
-    let coordinator = e.client("coordinator").await;
-    coordinator
-        .declare_topic("session.demo.snapshots", Retained::Latest)
-        .await
-        .unwrap();
-
-    let presenter = e.client("presenter").await;
-    // Observers cannot drive the environment.
-    let denied = presenter
-        .call(
-            "env.demo",
-            None,
-            "Environment.Advance",
-            obj(json!({"step": 0})),
-            &[],
-        )
-        .await
-        .unwrap_err();
-    assert_eq!(denied.code, ErrorCode::NotAuthorized);
-    let mut slow = presenter
-        .subscribe(
-            "session.demo.snapshots",
-            SubscriptionConfig::latest().in_flight(1),
-        )
-        .await
-        .unwrap();
-    let presenting = tokio::spawn(async move {
-        let mut seen = Vec::new();
-        while let Some(m) = slow.next().await {
-            let frame = m.artifact("frame").unwrap();
-            drop(m);
-            tokio::time::sleep(Duration::from_millis(25)).await; // a slow renderer
-            let bytes = frame.read_all().await.unwrap();
-            let step = bytes[0] as u64;
-            seen.push((step, frame.reference().artifact_id.clone()));
-            if step == STEPS {
-                break;
-            }
-        }
-        seen
-    });
-    let recorder = e.client("recorder").await;
-    let mut all = recorder
-        .subscribe("session.demo.snapshots", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let recording = tokio::spawn(async move {
-        let mut seq = Vec::new();
-        while let Some(m) = all.next().await {
-            seq.push((m.topic_sequence(), m.payload()["step"].as_u64().unwrap()));
-            if seq.len() as u64 == STEPS {
-                break;
-            }
-        }
-        seq
-    });
-
-    for step in 1..=STEPS {
-        let advanced = coordinator
-            .call_and_wait(
-                "env.demo",
-                Some(&env_inc),
-                "Environment.Advance",
-                obj(json!({"step": step})),
-                &[],
-            )
-            .await
-            .unwrap();
-        // Forward the delivery-owned frame to both agents at once.
-        let frame = advanced.artifact("frame").unwrap();
-        let attachments = [("frame", &frame)];
-        let (ra, rb) = tokio::join!(
-            coordinator.call_and_wait(
-                "agent.fly-a",
-                Some(&a_inc),
-                "Agent.Prepare",
-                obj(json!({"step": step})),
-                &attachments
-            ),
-            coordinator.call_and_wait(
-                "agent.fly-b",
-                Some(&b_inc),
-                "Agent.Prepare",
-                obj(json!({"step": step})),
-                &attachments
-            ),
-        );
-        for r in [ra.unwrap(), rb.unwrap()] {
-            assert_eq!(
-                (
-                    r.outcome()["step"].as_u64(),
-                    r.outcome()["frameOk"].as_bool()
-                ),
-                (Some(step), Some(true))
-            );
-        }
-        let receipt = coordinator
-            .publish(
-                "session.demo.snapshots",
-                obj(json!({"step": step})),
-                &[("frame", &frame)],
-            )
-            .await
-            .unwrap();
-        assert_eq!(receipt.topic_sequence, step);
-    }
-
-    let recorded = within("recorder", recording).await.unwrap();
-    assert_eq!(
-        recorded,
-        (1..=STEPS).map(|s| (s, s)).collect::<Vec<_>>(),
-        "the bounded recorder misses nothing"
-    );
-    let presented = within("presenter", presenting).await.unwrap();
-    assert_eq!(
-        presented.last().unwrap().0,
-        STEPS,
-        "the slow consumer ends on the latest snapshot"
-    );
-    assert!(
-        presented.len() < STEPS as usize,
-        "the slow consumer skipped snapshots: {presented:?}"
-    );
-    assert!(presented.windows(2).all(|w| w[0].0 < w[1].0));
-
-    for t in agents {
-        t.abort();
-    }
-    env_task.abort();
-    drop((a, b, environment, presenter, recorder));
-    // Only the retained snapshot's frame is left once everyone is gone.
-    let s = e
-        .settle("session torn down", |s| {
-            s.calls == 0 && s.sealed_artifacts == 1 && s.owners == 0
-        })
-        .await;
-    assert_eq!(s.store_bytes, FRAME as u64);
-    assert!(
-        coordinator
-            .clear_topic("session.demo.snapshots")
-            .await
-            .unwrap()
-    );
-    e.settle("retained frame collected", |s| s.artifacts == 0)
-        .await;
-}
-
-both_transports!(session_over_one_router);

services/flysim/crates/flybus/tests/perf.rs

@@ -1,213 +0,0 @@
-//! bus-v1 section 11 item 7, as a measurement rather than a gate: 640x480 RGBA frames at
-//! 60 Hz over a Unix socket to three consumers (one delayed), with 1, 2 and 4 agent services
-//! pinged every frame. Router and clients share this process, so CPU and RSS are the whole
-//! process. Run with:
-//!
-//! ```text
-//! cargo test --release -p flybus --test perf -- --ignored --nocapture
-//! ```
-
-mod common;
-
-use std::io::Write;
-use std::time::{Duration, Instant};
-
-use common::{Via, env, obj};
-use flybus::{Client, Retained, ServiceConfig, SubscriptionConfig};
-use serde_json::json;
-
-const W: usize = 640;
-const H: usize = 480;
-const HZ: u64 = 60;
-const SECONDS: u64 = 2;
-
-fn proc_cpu_seconds() -> f64 {
-    // utime + stime, fields 14 and 15 of /proc/self/stat, in clock ticks (100 Hz on Linux).
-    let stat = std::fs::read_to_string("/proc/self/stat").unwrap_or_default();
-    let after = stat.rsplit_once(')').map_or("", |(_, rest)| rest);
-    let f: Vec<&str> = after.split_whitespace().collect();
-    let ticks = |i: usize| f.get(i).and_then(|v| v.parse::<f64>().ok()).unwrap_or(0.0);
-    (ticks(11) + ticks(12)) / 100.0
-}
-
-fn proc_status(key: &str) -> String {
-    let status = std::fs::read_to_string("/proc/self/status").unwrap_or_default();
-    status
-        .lines()
-        .find(|l| l.starts_with(key))
-        .map_or("?".into(), |l| l[key.len()..].trim().to_owned())
-}
-
-fn pct(sorted: &[Duration], p: f64) -> Duration {
-    if sorted.is_empty() {
-        return Duration::ZERO;
-    }
-    sorted[((sorted.len() - 1) as f64 * p).round() as usize]
-}
-
-async fn consumer(client: Client, delay: Duration) -> (u64, u64) {
-    let mut sub = client
-        .subscribe("world.demo.frame", SubscriptionConfig::latest())
-        .await
-        .unwrap();
-    let (mut seen, mut replaced) = (0, 0);
-    while let Some(m) = sub.next().await {
-        if m.payload().get("end").is_some() {
-            break;
-        }
-        replaced += m.replaced();
-        let frame = m.artifact("frame").unwrap();
-        drop(m);
-        let bytes = frame.read_all().await.unwrap();
-        assert_eq!(bytes.len(), W * H * 4);
-        tokio::time::sleep(delay).await;
-        seen += 1;
-    }
-    (seen, replaced)
-}
-
-async fn run(agents: usize) {
-    let e = env(Via::Unix).await;
-    let producer = e.client("producer").await;
-    producer
-        .declare_topic("world.demo.frame", Retained::None)
-        .await
-        .unwrap();
-    let mut consumers = Vec::new();
-    for (i, delay) in [0u64, 0, 40].into_iter().enumerate() {
-        let c = e.client(&format!("consumer-{i}")).await;
-        consumers.push(tokio::spawn(consumer(c, Duration::from_millis(delay))));
-    }
-    let mut services = Vec::new();
-    for k in 0..agents {
-        let c = e.client(&format!("agent-{k}")).await;
-        let mut svc = c
-            .register(&format!("agent.a{k}"), ServiceConfig::default())
-            .await
-            .unwrap();
-        services.push(tokio::spawn(async move {
-            let _c = c;
-            while let Some(req) = svc.next().await {
-                req.reply(obj(json!({})), &[]).await.unwrap();
-            }
-        }));
-    }
-    let caller = e.client("coordinator").await;
-    // Let every subscription land before the first frame.
-    e.settle("subscribed", |s| s.subscriptions == 3).await;
-
-    let pixels: Vec<u8> = (0..W * H * 4).map(|i| (i % 253) as u8).collect();
-    let frames = HZ * SECONDS;
-    let period = Duration::from_nanos(1_000_000_000 / HZ);
-    let (mut produce, mut publish, mut rpc) = (Vec::new(), Vec::new(), Vec::new());
-    let (mut peak_bytes, mut peak_roots, mut peak_queued, mut late) = (0u64, 0u64, 0usize, 0u32);
-    let cpu0 = proc_cpu_seconds();
-    let start = Instant::now();
-    for n in 0..frames {
-        let deadline = start + period * n as u32;
-        let t = Instant::now();
-        let mut w = producer
-            .artifacts()
-            .allocate(pixels.len() as u64, "image/x-rgba")
-            .await
-            .unwrap();
-        w.write_all(&pixels).unwrap();
-        let frame = w.seal().await.unwrap();
-        produce.push(t.elapsed());
-        let t = Instant::now();
-        producer
-            .publish(
-                "world.demo.frame",
-                obj(json!({"n": n})),
-                &[("frame", &frame)],
-            )
-            .await
-            .unwrap();
-        publish.push(t.elapsed());
-        drop(frame);
-        let mut calls = Vec::new();
-        for k in 0..agents {
-            let caller = caller.clone();
-            calls.push(tokio::spawn(async move {
-                let t = Instant::now();
-                caller
-                    .call_and_wait(&format!("agent.a{k}"), None, "Ping", obj(json!({})), &[])
-                    .await
-                    .unwrap();
-                t.elapsed()
-            }));
-        }
-        for c in calls {
-            rpc.push(c.await.unwrap());
-        }
-        let s = e.stats();
-        peak_bytes = peak_bytes.max(s.store_bytes);
-        peak_roots = peak_roots.max(s.artifact_roots);
-        peak_queued = peak_queued.max(s.queued);
-        let next = deadline + period;
-        if Instant::now() > next {
-            late += 1;
-        } else {
-            tokio::time::sleep_until(next.into()).await;
-        }
-    }
-    let wall = start.elapsed().as_secs_f64();
-    let cpu = proc_cpu_seconds() - cpu0;
-    let end = Instant::now();
-    producer
-        .publish("world.demo.frame", obj(json!({"end": true})), &[])
-        .await
-        .unwrap();
-    let mut results = Vec::new();
-    for c in consumers {
-        results.push(c.await.unwrap());
-    }
-    e.settle("collected", |s| s.store_bytes == 0).await;
-    let collect_lag = end.elapsed();
-    for s in services {
-        s.abort();
-    }
-    for v in [&mut produce, &mut publish, &mut rpc] {
-        v.sort();
-    }
-    let ms = |d: Duration| format!("{:.2}", d.as_secs_f64() * 1000.0);
-    println!("agents={agents} frames={frames} over {wall:.2}s, late frames {late}");
-    println!(
-        "  produce (allocate+write+seal copy) ms p50/p95/p99: {}/{}/{}",
-        ms(pct(&produce, 0.5)),
-        ms(pct(&produce, 0.95)),
-        ms(pct(&produce, 0.99))
-    );
-    println!(
-        "  publish admission ms p50/p95/p99: {}/{}/{}",
-        ms(pct(&publish, 0.5)),
-        ms(pct(&publish, 0.95)),
-        ms(pct(&publish, 0.99))
-    );
-    println!(
-        "  rpc round trip ms p50/p95/p99: {}/{}/{}",
-        ms(pct(&rpc, 0.5)),
-        ms(pct(&rpc, 0.95)),
-        ms(pct(&rpc, 0.99))
-    );
-    println!(
-        "  process cpu {:.2} cores; VmRSS {} VmHWM {}",
-        cpu / wall,
-        proc_status("VmRSS:"),
-        proc_status("VmHWM:")
-    );
-    println!(
-        "  store peak {:.1} MB, peak roots {peak_roots}, peak queued {peak_queued}, drain+collect {:.1} ms",
-        peak_bytes as f64 / 1e6,
-        collect_lag.as_secs_f64() * 1000.0
-    );
-    println!("  consumers (frames seen, replaced): {results:?}");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
-#[ignore = "measurement; run with --release -- --ignored --nocapture"]
-async fn frames_at_60hz_with_three_consumers() {
-    for agents in [1, 2, 4] {
-        run(agents).await;
-    }
-}

services/flysim/crates/flybus/tests/pubsub.rs

@@ -1,545 +0,0 @@
-//! Pub/sub: exact topics, bounded FIFO with whole-publication backpressure, latest coalescing,
-//! credits, retention, incarnations and fair control delivery under a saturated subscriber.
-
-mod common;
-
-use std::time::Duration;
-
-use common::{Via, code, env, env_with, obj, quiet, sealed, within};
-use flybus::{ErrorCode, Limits, Mode, Policy, Retained, ServiceConfig, SubscriptionConfig};
-use serde_json::json;
-
-async fn bounded_fifo_and_atomic_backpressure(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let slow = e.client("slow").await;
-    let fast = e.client("fast").await;
-    publisher
-        .declare_topic("session.demo.events", Retained::Latest)
-        .await
-        .unwrap();
-    let mut a = slow
-        .subscribe(
-            "session.demo.events",
-            SubscriptionConfig::bounded().queued(2).in_flight(1),
-        )
-        .await
-        .unwrap();
-    let mut b = fast
-        .subscribe("session.demo.events", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let p = |n: u64| obj(json!({ "n": n }));
-
-    let r1 = publisher
-        .publish("session.demo.events", p(1), &[])
-        .await
-        .unwrap();
-    assert_eq!((r1.topic_sequence, r1.subscribers, r1.replaced), (1, 2, 0));
-    let m1 = within("a gets 1", a.next()).await.unwrap();
-    publisher
-        .publish("session.demo.events", p(2), &[])
-        .await
-        .unwrap();
-    publisher
-        .publish("session.demo.events", p(3), &[])
-        .await
-        .unwrap();
-    // a holds 1 in flight and 2, 3 queued: the next publication would overflow it, so nobody
-    // gets it, the retained value does not move and no sequence number is spent.
-    let full = publisher
-        .publish("session.demo.events", p(4), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(full.code, ErrorCode::Backpressure);
-    for n in 1..=3u64 {
-        let m = within("b in order", b.next()).await.unwrap();
-        assert_eq!(
-            (m.payload()["n"].as_u64(), m.topic_sequence()),
-            (Some(n), n)
-        );
-    }
-    quiet("b gets no partial fan-out", b.next()).await;
-    let mut late = fast
-        .subscribe(
-            "session.demo.events",
-            SubscriptionConfig::bounded().replay(true),
-        )
-        .await
-        .unwrap();
-    let replayed = within("replay", late.next()).await.unwrap();
-    assert_eq!(
-        replayed.payload()["n"],
-        3,
-        "the refused publication did not become the retained value"
-    );
-    drop(m1);
-    let m2 = within("credit returned", a.next()).await.unwrap();
-    assert_eq!(m2.payload()["n"], 2);
-    let r5 = publisher
-        .publish("session.demo.events", p(5), &[])
-        .await
-        .unwrap();
-    assert_eq!(r5.topic_sequence, 4);
-}
-
-async fn latest_coalesces_only_undelivered_values(via: Via) {
-    let e = env(via).await;
-    let camera = e.client("camera").await;
-    let viewer = e.client("viewer").await;
-    camera
-        .declare_topic("world.demo.frame", Retained::None)
-        .await
-        .unwrap();
-    let mut sub = viewer
-        .subscribe(
-            "world.demo.frame",
-            SubscriptionConfig::latest().in_flight(1),
-        )
-        .await
-        .unwrap();
-    let frames: Vec<_> = futures_join(&camera, 4).await;
-    let r = camera
-        .publish(
-            "world.demo.frame",
-            obj(json!({"n": 1})),
-            &[("frame", &frames[0])],
-        )
-        .await
-        .unwrap();
-    assert_eq!(r.replaced, 0);
-    let first = within("first frame", sub.next()).await.unwrap();
-    let held = first.artifact("frame").unwrap();
-    let mut replaced = 0;
-    for (i, f) in frames.iter().enumerate().skip(1) {
-        let r = camera
-            .publish(
-                "world.demo.frame",
-                obj(json!({"n": i + 1})),
-                &[("frame", f)],
-            )
-            .await
-            .unwrap();
-        replaced += r.replaced;
-    }
-    assert_eq!(
-        replaced, 2,
-        "frames 2 and 3 were replaced while undelivered"
-    );
-    drop(frames);
-    // Replaced queue entries released their roots; the delivered frame and the queued one stay.
-    e.settle("replaced frames collected", |s| s.sealed_artifacts == 2)
-        .await;
-    assert_eq!(
-        held.read_all().await.unwrap(),
-        b"frame-0",
-        "delivered data is never reclaimed early"
-    );
-    drop((first, held));
-    let last = within("latest frame", sub.next()).await.unwrap();
-    assert_eq!((last.topic_sequence(), last.replaced()), (4, 2));
-    assert_eq!(
-        last.artifact("frame").unwrap().read_all().await.unwrap(),
-        b"frame-3"
-    );
-    drop(last);
-    e.settle("all collected", |s| s.artifacts == 0 && s.owners == 0)
-        .await;
-}
-
-async fn futures_join(client: &flybus::Client, n: usize) -> Vec<flybus::Artifact> {
-    let mut out = Vec::new();
-    for i in 0..n {
-        out.push(sealed(client, format!("frame-{i}").as_bytes(), "image/x-rgba").await);
-    }
-    out
-}
-
-async fn credits_return_only_on_consume(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let reader = e.client("reader").await;
-    publisher
-        .declare_topic("t.credits", Retained::None)
-        .await
-        .unwrap();
-    let mut sub = reader
-        .subscribe("t.credits", SubscriptionConfig::bounded().in_flight(2))
-        .await
-        .unwrap();
-    for n in 0..5 {
-        publisher
-            .publish("t.credits", obj(json!({"n": n})), &[])
-            .await
-            .unwrap();
-    }
-    let m0 = within("0", sub.next()).await.unwrap();
-    let m1 = within("1", sub.next()).await.unwrap();
-    quiet("third while two are held", sub.next()).await;
-    drop(m0);
-    let m2 = within("2 after a consume", sub.next()).await.unwrap();
-    assert_eq!(m2.payload()["n"], 2);
-    quiet("fourth while two are held", sub.next()).await;
-    drop((m1, m2));
-    assert_eq!(within("3", sub.next()).await.unwrap().payload()["n"], 3);
-}
-
-async fn retained_replay_clear_delete_and_incarnations(via: Via) {
-    let e = env(via).await;
-    let admin = e.client("admin").await;
-    let reader = e.client("reader").await;
-    let info = admin
-        .declare_topic("session.demo.snapshots", Retained::Latest)
-        .await
-        .unwrap();
-    assert!(info.declared);
-    let again = admin
-        .declare_topic("session.demo.snapshots", Retained::Latest)
-        .await
-        .unwrap();
-    assert_eq!(
-        (again.declared, &again.topic_incarnation),
-        (false, &info.topic_incarnation)
-    );
-    let conflict = admin
-        .declare_topic("session.demo.snapshots", Retained::None)
-        .await
-        .unwrap_err();
-    assert_eq!(conflict.code, ErrorCode::Conflict);
-
-    let snap = sealed(&admin, b"snapshot-1", "application/octet-stream").await;
-    let r = admin
-        .publish(
-            "session.demo.snapshots",
-            obj(json!({"step": "1"})),
-            &[("state", &snap)],
-        )
-        .await
-        .unwrap();
-    assert_eq!(r.subscribers, 0);
-    drop(snap);
-    e.settle("retention holds the only root", |s| {
-        s.sealed_artifacts == 1 && s.artifact_roots == 1
-    })
-    .await;
-
-    let mut plain = reader
-        .subscribe("session.demo.snapshots", SubscriptionConfig::bounded())
-        .await
-        .unwrap();
-    let mut replay = reader
-        .subscribe(
-            "session.demo.snapshots",
-            SubscriptionConfig::latest().replay(true),
-        )
-        .await
-        .unwrap();
-    let m = within("replay", replay.next()).await.unwrap();
-    assert_eq!(m.topic_sequence(), 1, "replay keeps the original sequence");
-    assert_eq!(
-        m.artifact("state").unwrap().read_all().await.unwrap(),
-        b"snapshot-1"
-    );
-    quiet("no replay without replayLatest", plain.next()).await;
-
-    assert!(admin.clear_topic("session.demo.snapshots").await.unwrap());
-    assert!(!admin.clear_topic("session.demo.snapshots").await.unwrap());
-    // Clearing does not invalidate the delivery still held.
-    assert_eq!(
-        m.artifact("state").unwrap().read_all().await.unwrap(),
-        b"snapshot-1"
-    );
-    drop(m);
-    e.settle("cleared value collected", |s| s.artifacts == 0)
-        .await;
-
-    let busy = admin
-        .delete_topic("session.demo.snapshots")
-        .await
-        .unwrap_err();
-    assert_eq!(busy.code, ErrorCode::Conflict);
-    admin
-        .publish("session.demo.snapshots", obj(json!({"step": "2"})), &[])
-        .await
-        .unwrap();
-    let old = within("before delete", plain.next()).await.unwrap();
-    drop((plain, replay));
-    e.settle("unsubscribed", |s| s.subscriptions == 0).await;
-    assert!(admin.delete_topic("session.demo.snapshots").await.unwrap());
-    assert!(!admin.delete_topic("session.demo.snapshots").await.unwrap());
-    let fresh = admin
-        .declare_topic("session.demo.snapshots", Retained::Latest)
-        .await
-        .unwrap();
-    assert_ne!(fresh.topic_incarnation, info.topic_incarnation);
-    assert_eq!(
-        old.topic_incarnation(),
-        info.topic_incarnation,
-        "old deliveries keep their incarnation"
-    );
-    let r = admin
-        .publish("session.demo.snapshots", obj(json!({})), &[])
-        .await
-        .unwrap();
-    assert_eq!(
-        r.topic_sequence, 1,
-        "a fresh incarnation restarts its sequence"
-    );
-}
-
-async fn zero_subscriber_publish_retains_nothing(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    p.declare_topic("t.void", Retained::None).await.unwrap();
-    let art = sealed(&p, &[7u8; 4096], "application/octet-stream").await;
-    let r = p
-        .publish("t.void", obj(json!({})), &[("x", &art)])
-        .await
-        .unwrap();
-    assert_eq!(r.subscribers, 0);
-    drop(art);
-    e.settle("no owner left", |s| s.artifacts == 0 && s.store_bytes == 0)
-        .await;
-}
-
-async fn unsubscribe_discards_queue_but_not_deliveries(via: Via) {
-    let e = env(via).await;
-    let p = e.client("p").await;
-    let r = e.client("r").await;
-    p.declare_topic("t.unsub", Retained::None).await.unwrap();
-    let mut sub = r
-        .subscribe("t.unsub", SubscriptionConfig::bounded().in_flight(1))
-        .await
-        .unwrap();
-    for i in 0..3 {
-        let a = sealed(&p, format!("m{i}").as_bytes(), "text/plain").await;
-        p.publish("t.unsub", obj(json!({})), &[("m", &a)])
-            .await
-            .unwrap();
-    }
-    let first = within("first", sub.next()).await.unwrap();
-    e.settle("three objects", |s| s.sealed_artifacts == 3).await;
-    drop(sub);
-    e.settle("queued entries released", |s| {
-        s.sealed_artifacts == 1 && s.subscriptions == 0
-    })
-    .await;
-    assert_eq!(
-        first.artifact("m").unwrap().read_all().await.unwrap(),
-        b"m0"
-    );
-    drop(first);
-    e.settle("delivered entry released", |s| s.artifacts == 0)
-        .await;
-}
-
-async fn subscription_and_topic_validation(via: Via) {
-    let e = env(via).await;
-    let c = e.client("c").await;
-    let missing = c
-        .subscribe("t.missing", SubscriptionConfig::latest())
-        .await
-        .unwrap_err();
-    assert_eq!(missing.code, ErrorCode::NoTopic);
-    assert_eq!(
-        c.publish("t.missing", obj(json!({})), &[])
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::NoTopic
-    );
-    c.declare_topic("t.ok", Retained::None).await.unwrap();
-    let bad = SubscriptionConfig {
-        mode: Mode::Latest,
-        max_queued: 2,
-        max_in_flight: 1,
-        replay_latest: false,
-    };
-    assert_eq!(
-        c.subscribe("t.ok", bad).await.unwrap_err().code,
-        ErrorCode::InvalidEnvelope
-    );
-    let over = SubscriptionConfig::latest().in_flight(3);
-    assert_eq!(
-        c.subscribe("t.ok", over).await.unwrap_err().code,
-        ErrorCode::QuotaExceeded
-    );
-    let zero = SubscriptionConfig::bounded().in_flight(0);
-    assert_eq!(
-        c.subscribe("t.ok", zero).await.unwrap_err().code,
-        ErrorCode::InvalidEnvelope
-    );
-    assert_eq!(
-        c.declare_topic("t..bad", Retained::None)
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::InvalidEnvelope
-    );
-    assert_eq!(
-        c.declare_topic("T.upper", Retained::None)
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::InvalidEnvelope
-    );
-    // The connection survives every refusal above.
-    assert!(
-        c.subscribe("t.ok", SubscriptionConfig::bounded())
-            .await
-            .is_ok()
-    );
-}
-
-async fn topic_and_retention_quotas(via: Via) {
-    let limits = Limits {
-        max_topics: 2,
-        max_retained_bytes: 100,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let c = e.client("c").await;
-    c.declare_topic("t.a", Retained::Latest).await.unwrap();
-    c.declare_topic("t.b", Retained::Latest).await.unwrap();
-    assert_eq!(
-        c.declare_topic("t.c", Retained::None)
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::QuotaExceeded
-    );
-    let small = sealed(&c, &[1u8; 60], "application/octet-stream").await;
-    let big = sealed(&c, &[2u8; 50], "application/octet-stream").await;
-    c.publish("t.a", obj(json!({})), &[("x", &small)])
-        .await
-        .unwrap();
-    // Two names for one object count once.
-    c.publish("t.a", obj(json!({})), &[("x", &small), ("y", &small)])
-        .await
-        .unwrap();
-    assert_eq!(e.stats().retained_bytes, 60);
-    let over = c
-        .publish("t.b", obj(json!({})), &[("x", &big)])
-        .await
-        .unwrap_err();
-    assert_eq!(over.code, ErrorCode::QuotaExceeded);
-    assert_eq!(
-        e.stats().retained_bytes,
-        60,
-        "a refused publication changes nothing"
-    );
-    // Replacing a topic's own retained value is measured net of the old one.
-    c.publish("t.a", obj(json!({})), &[("x", &big)])
-        .await
-        .unwrap();
-    assert_eq!(e.stats().retained_bytes, 50);
-}
-
-/// A subscriber that never reads its socket must not slow anyone else: publications are
-/// admitted until its queue refuses them, and RPC and control traffic between other clients
-/// (and to a client that merely holds its credits) keep flowing.
-async fn saturated_subscriber_does_not_block_control(via: Via) {
-    let e = env(via).await;
-    let publisher = e.client("publisher").await;
-    let busy = e.client("busy").await;
-    let caller = e.client("caller").await;
-    publisher
-        .declare_topic("t.flood", Retained::None)
-        .await
-        .unwrap();
-
-    // 1. A raw subscriber that never reads.
-    let mut stuck = e.raw_hello("stuck").await;
-    let r = stuck
-        .call("subscribe", json!({"topic": "t.flood", "mode": "bounded", "maxQueued": 64, "maxInFlight": 16, "replayLatest": false}))
-        .await;
-    assert_eq!(code(&r), "OK");
-    // 2. An SDK subscriber that reads but never consumes, and also serves RPC.
-    let _held = busy
-        .subscribe("t.flood", SubscriptionConfig::bounded().in_flight(16))
-        .await
-        .unwrap();
-    let mut svc = busy
-        .register("busy.status", ServiceConfig::default())
-        .await
-        .unwrap();
-    let server = tokio::spawn(async move {
-        while let Some(req) = svc.next().await {
-            req.reply(obj(json!({"alive": true})), &[]).await.unwrap();
-        }
-    });
-
-    let blob = "x".repeat(60_000);
-    let mut accepted = 0;
-    let refused = loop {
-        match within(
-            "publish",
-            publisher.publish("t.flood", obj(json!({"blob": blob})), &[]),
-        )
-        .await
-        {
-            Ok(_) => accepted += 1,
-            Err(err) => break err,
-        }
-        assert!(accepted < 1000, "publications were never refused");
-    };
-    assert_eq!(refused.code, ErrorCode::Backpressure);
-    assert!(accepted >= 16, "only {accepted} publications were admitted");
-    for _ in 0..20 {
-        let res = tokio::time::timeout(
-            Duration::from_secs(2),
-            caller.call_and_wait("busy.status", None, "Status", obj(json!({})), &[]),
-        )
-        .await
-        .expect("RPC to a client whose subscription is saturated")
-        .unwrap();
-        assert_eq!(res.outcome()["alive"], true);
-    }
-    // The saturated subscriber's own control lane still answers once it reads again.
-    let id = stuck
-        .command(
-            "topic.declare",
-            json!({"name": "t.other", "retained": "none"}),
-            json!([]),
-        )
-        .await;
-    assert_eq!(code(&stuck.reply(&id).await), "OK");
-    server.abort();
-}
-
-async fn router_shutdown_closes_subscriptions_with_notices(via: Via) {
-    let e = env(via).await;
-    let admin = e.client("admin").await;
-    admin.declare_topic("t.stop", Retained::None).await.unwrap();
-    let mut raw = e.raw_hello("raw").await;
-    let sub = raw
-        .call("subscribe", json!({"topic": "t.stop", "mode": "latest", "maxQueued": 1, "maxInFlight": 1, "replayLatest": false}))
-        .await
-        .unwrap();
-    e.router.shutdown();
-    let closed = raw.event().await;
-    assert_eq!(
-        (closed.op.as_str(), &closed.body["subscriptionId"]),
-        ("subscription.closed", &sub["subscriptionId"])
-    );
-    assert_eq!(closed.body["reason"], "router-stopping");
-    let last = raw.event().await;
-    assert_eq!(
-        (last.op.as_str(), last.body["code"].as_str()),
-        ("connection.closing", Some("ROUTER_LOST"))
-    );
-    assert!(raw.recv().await.is_none());
-}
-
-both_transports!(
-    router_shutdown_closes_subscriptions_with_notices,
-    bounded_fifo_and_atomic_backpressure,
-    latest_coalesces_only_undelivered_values,
-    credits_return_only_on_consume,
-    retained_replay_clear_delete_and_incarnations,
-    zero_subscriber_publish_retains_nothing,
-    unsubscribe_discards_queue_but_not_deliveries,
-    subscription_and_topic_validation,
-    topic_and_retention_quotas,
-    saturated_subscriber_does_not_block_control,
-);

services/flysim/crates/flybus/tests/rpc.rs

@@ -1,660 +0,0 @@
-//! RPC: exclusive registration, pinned incarnations, request/reply, FIFO, bounds,
-//! cancellation, disconnects and an endpoint-side result cache. Every test runs over both the
-//! in-memory transport and a Unix socket.
-
-mod common;
-
-use std::collections::HashMap;
-use std::io::Write;
-
-use common::{Via, code, env, env_with, obj, quiet, sealed, within};
-use flybus::{CancelState, Dispatch, ErrorCode, Grants, Limits, Pattern, Policy, ServiceConfig};
-use serde_json::json;
-
-async fn request_reply_roundtrip(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.counter", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut pending = caller
-        .call(
-            "example.counter",
-            Some(svc.incarnation()),
-            "Counter.Increment",
-            obj(json!({"amount": 1})),
-            &[],
-        )
-        .await
-        .unwrap();
-    assert_eq!(pending.service_incarnation(), svc.incarnation());
-    let req = within("request", svc.next()).await.unwrap();
-    assert_eq!(req.method(), "Counter.Increment");
-    assert_eq!(req.payload()["amount"], 1);
-    assert_eq!(req.target(), "example.counter");
-    // The router, not the body, says who called.
-    assert_eq!(req.caller(), &caller.info().identity);
-    assert!(req.reply(obj(json!({"value": 1})), &[]).await.unwrap());
-    drop(req);
-    let res = within("result", pending.result()).await.unwrap();
-    assert_eq!(res.outcome()["value"], 1);
-    assert_eq!(res.responder(), &server.info().identity);
-    assert_eq!(res.call_id(), pending.call_id());
-    drop(res);
-    e.settle("everything consumed", |s| s.calls == 0 && s.owners == 0)
-        .await;
-}
-
-async fn registration_is_exclusive_and_pinned(via: Via) {
-    let e = env(via).await;
-    let a = e.client("a").await;
-    let b = e.client("b").await;
-    let caller = e.client("caller").await;
-    let first = a
-        .register("agent.fly-a", ServiceConfig::default())
-        .await
-        .unwrap();
-    let dup = b
-        .register("agent.fly-a", ServiceConfig::default())
-        .await
-        .unwrap_err();
-    assert_eq!(dup.code, ErrorCode::Conflict);
-    let old = first.incarnation().to_owned();
-    drop(first);
-    // Unregistration is asynchronous; wait for the name to come free.
-    let second = loop {
-        match b.register("agent.fly-a", ServiceConfig::default()).await {
-            Ok(s) => break s,
-            Err(err) => assert_eq!(err.code, ErrorCode::Conflict),
-        }
-    };
-    assert_ne!(second.incarnation(), old);
-    let changed = caller
-        .call(
-            "agent.fly-a",
-            Some(&old),
-            "Agent.Prepare",
-            obj(json!({})),
-            &[],
-        )
-        .await
-        .unwrap_err();
-    assert_eq!(changed.code, ErrorCode::TargetChanged);
-    assert_eq!(changed.dispatch, Dispatch::NotDispatched);
-    let missing = caller
-        .call("agent.nobody", None, "Agent.Prepare", obj(json!({})), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(missing.code, ErrorCode::NoService);
-    let over = b
-        .register(
-            "agent.big",
-            ServiceConfig {
-                max_queued: 17,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap_err();
-    assert_eq!(over.code, ErrorCode::QuotaExceeded);
-}
-
-async fn authority_is_enforced(via: Via) {
-    let policy = Policy::closed()
-        .client(
-            "server",
-            Grants {
-                register: vec![Pattern::exact("a.svc")],
-                ..Grants::default()
-            },
-        )
-        .client(
-            "caller",
-            Grants {
-                call: vec![Pattern::prefix("a.")],
-                ..Grants::default()
-            },
-        );
-    let e = env_with(via, Limits::default(), policy).await;
-    assert_eq!(
-        e.try_client("stranger").await.unwrap_err().code,
-        ErrorCode::NotAuthorized
-    );
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    // One live connection per configured identity.
-    assert_eq!(
-        e.try_client("caller").await.unwrap_err().code,
-        ErrorCode::NotAuthorized
-    );
-    assert_eq!(
-        server
-            .register("b.svc", ServiceConfig::default())
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::NotAuthorized
-    );
-    let _svc = server
-        .register("a.svc", ServiceConfig::default())
-        .await
-        .unwrap();
-    assert_eq!(
-        caller
-            .register("a.other", ServiceConfig::default())
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::NotAuthorized
-    );
-    assert_eq!(
-        caller
-            .call("b.svc", None, "M", obj(json!({})), &[])
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::NotAuthorized
-    );
-    assert_eq!(
-        caller
-            .declare_topic("a.t", flybus::Retained::None)
-            .await
-            .unwrap_err()
-            .code,
-        ErrorCode::NotAuthorized
-    );
-    assert!(
-        caller
-            .call("a.svc", None, "M", obj(json!({})), &[])
-            .await
-            .is_ok()
-    );
-    // A reconnect must present a new incarnation.
-    let mut cfg = e.config("server");
-    cfg.client_incarnation = Some(server.info().identity.client_incarnation.clone());
-    drop(_svc);
-    server.close().await;
-    e.settle("server gone", |s| s.connections == 1).await;
-    let reused = flybus::Client::connect(e.transport_as("server").await, cfg)
-        .await
-        .unwrap_err();
-    assert_eq!(reused.code, ErrorCode::NotAuthorized);
-    assert!(e.try_client("server").await.is_ok());
-}
-
-async fn fifo_dispatch_and_out_of_order_completion(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.echo", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut calls = Vec::new();
-    for i in 0..6 {
-        calls.push(
-            caller
-                .call("example.echo", None, "Echo", obj(json!({"i": i})), &[])
-                .await
-                .unwrap(),
-        );
-    }
-    let mut reqs = Vec::new();
-    for i in 0..6 {
-        let r = within("request", svc.next()).await.unwrap();
-        assert_eq!(r.payload()["i"], i, "first dispatch is FIFO per caller");
-        reqs.push(r);
-    }
-    for r in reqs.iter().rev() {
-        assert!(
-            r.reply(obj(json!({"echo": r.payload()["i"]})), &[])
-                .await
-                .unwrap()
-        );
-    }
-    drop(reqs);
-    for (i, mut c) in calls.into_iter().enumerate() {
-        let res = within("result", c.result()).await.unwrap();
-        assert_eq!(res.outcome()["echo"], i, "results correlate by call id");
-    }
-}
-
-async fn service_queue_backpressure(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "example.slow",
-            ServiceConfig {
-                max_queued: 1,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let _c1 = caller
-        .call("example.slow", None, "Work", obj(json!({"n": 1})), &[])
-        .await
-        .unwrap();
-    let held = within("first request", svc.next()).await.unwrap();
-    let _c2 = caller
-        .call("example.slow", None, "Work", obj(json!({"n": 2})), &[])
-        .await
-        .unwrap();
-    let full = caller
-        .call("example.slow", None, "Work", obj(json!({"n": 3})), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(full.code, ErrorCode::Backpressure);
-    assert_eq!(full.dispatch, Dispatch::NotDispatched);
-    // In-flight credit returns only when the request delivery is consumed.
-    quiet("second request while the first is held", svc.next()).await;
-    drop(held);
-    let second = within("second request", svc.next()).await.unwrap();
-    assert_eq!(second.payload()["n"], 2);
-}
-
-async fn cancellation_states(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "example.worker",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-
-    let mut dispatched = caller
-        .call("example.worker", None, "Work", obj(json!({"n": 1})), &[])
-        .await
-        .unwrap();
-    let req1 = within("request 1", svc.next()).await.unwrap();
-    let mut queued = caller
-        .call("example.worker", None, "Work", obj(json!({"n": 2})), &[])
-        .await
-        .unwrap();
-
-    assert_eq!(
-        queued.cancel().await.unwrap(),
-        CancelState::CancelledBeforeDispatch
-    );
-    let gone = within("cancelled result", queued.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (gone.code, gone.dispatch),
-        (ErrorCode::CallGone, Dispatch::NotDispatched)
-    );
-
-    assert_eq!(
-        dispatched.cancel().await.unwrap(),
-        CancelState::ExecutionUnknown
-    );
-    let unknown = within("detached result", dispatched.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (unknown.code, unknown.dispatch),
-        (ErrorCode::CallGone, Dispatch::Unknown)
-    );
-    // The handler still finishes; its reply reaches nobody and is not an error.
-    assert!(!req1.reply(obj(json!({"late": true})), &[]).await.unwrap());
-    drop(req1);
-
-    let mut done = caller
-        .call("example.worker", None, "Work", obj(json!({"n": 3})), &[])
-        .await
-        .unwrap();
-    let req3 = within("request 3", svc.next()).await.unwrap();
-    assert_eq!(
-        req3.payload()["n"],
-        3,
-        "the cancelled call was never dispatched"
-    );
-    assert!(req3.reply(obj(json!({"ok": 3})), &[]).await.unwrap());
-    // Wait for the result to be admitted before cancelling.
-    e.settle("result admitted", |s| s.calls == 1).await;
-    let state = done.cancel().await.unwrap();
-    assert_eq!(state, CancelState::Completed);
-    let res = within("completed result", done.result()).await.unwrap();
-    assert_eq!(res.outcome()["ok"], 3);
-    drop((res, req3));
-    e.settle("calls retired", |s| s.calls == 0).await;
-    assert_eq!(done.cancel().await.unwrap(), CancelState::CallGone);
-}
-
-async fn replies_are_single_and_independent_of_the_request_guard(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.once", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut pending = caller
-        .call("example.once", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    let responder = req.responder();
-    drop(req); // consumed before replying
-    assert!(
-        responder
-            .reply(obj(json!({"first": true})), &[])
-            .await
-            .unwrap()
-    );
-    let again = responder
-        .reply(obj(json!({"second": true})), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(again.code, ErrorCode::CallGone);
-    let res = within("result", pending.result()).await.unwrap();
-    assert_eq!(res.outcome()["first"], true);
-}
-
-async fn service_disconnect_fails_calls(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "example.fragile",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let mut c1 = caller
-        .call("example.fragile", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let held = within("request", svc.next()).await.unwrap();
-    let mut c2 = caller
-        .call("example.fragile", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    // Keep the first delivery credit occupied until unregister has synchronously failed the
-    // queued call. Otherwise consuming it may truthfully dispatch call 2 before unregister.
-    drop(svc);
-    let r2 = within("queued call", c2.result()).await.unwrap_err();
-    assert_eq!(
-        (r2.code, r2.dispatch),
-        (ErrorCode::NoService, Dispatch::NotDispatched)
-    );
-    drop(held);
-    server.close().await;
-    let r1 = within("dispatched call", c1.result()).await.unwrap_err();
-    assert_eq!(
-        (r1.code, r1.dispatch),
-        (ErrorCode::NoService, Dispatch::Dispatched)
-    );
-    e.settle("nothing left", |s| s.calls == 0 && s.services == 0)
-        .await;
-}
-
-async fn unregister_fails_queued_but_dispatched_may_reply(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register(
-            "example.leaving",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 1,
-            },
-        )
-        .await
-        .unwrap();
-    let mut c1 = caller
-        .call("example.leaving", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    let mut c2 = caller
-        .call("example.leaving", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    drop(svc);
-    let r2 = within("queued call", c2.result()).await.unwrap_err();
-    assert_eq!(
-        (r2.code, r2.dispatch),
-        (ErrorCode::NoService, Dispatch::NotDispatched)
-    );
-    assert!(req.reply(obj(json!({"done": true})), &[]).await.unwrap());
-    assert_eq!(
-        within("dispatched call", c1.result())
-            .await
-            .unwrap()
-            .outcome()["done"],
-        true
-    );
-}
-
-async fn raw_call_ids_and_forged_replies(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let mut svc = server
-        .register("example.raw", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut raw = e.raw_hello("rawcaller").await;
-    let call = |id: &str| json!({"callId": id, "target": "example.raw", "expectedIncarnation": null, "method": "M", "payload": {}});
-    assert_eq!(code(&raw.call("rpc.call", call("call-5")).await), "OK");
-    assert_eq!(
-        code(&raw.call("rpc.call", call("call-5")).await),
-        "INVALID_ENVELOPE"
-    );
-    assert_eq!(
-        code(&raw.call("rpc.call", call("call-3")).await),
-        "INVALID_ENVELOPE"
-    );
-    assert_eq!(
-        code(&raw.call("rpc.call", call("call-05")).await),
-        "INVALID_ENVELOPE"
-    );
-    // Identity comes from the connection; a body cannot claim one.
-    let mut forged = call("call-6");
-    forged["caller"] = json!({"clientId": "server", "clientIncarnation": "x"});
-    assert_eq!(
-        code(&raw.call("rpc.call", forged).await),
-        "INVALID_ENVELOPE"
-    );
-    assert_eq!(code(&raw.call("rpc.call", call("call-6")).await), "OK");
-    let req = within("request", svc.next()).await.unwrap();
-    assert_eq!(req.caller().client_id, "rawcaller");
-    // A third party cannot answer someone else's request.
-    let mut other = e.raw_hello("intruder").await;
-    let r = other
-        .call(
-            "rpc.reply",
-            json!({"callId": req.call_id(), "requestDeliveryId": req.delivery_id(), "outcome": {}}),
-        )
-        .await;
-    assert_eq!(code(&r), "OWNER_INVALID");
-    assert!(req.reply(obj(json!({"real": true})), &[]).await.unwrap());
-    let result = raw.event().await;
-    assert_eq!(result.op, "rpc.result");
-    assert_eq!(result.body["outcome"]["real"], true);
-    assert_eq!(result.body["responder"]["clientId"], "server");
-}
-
-/// bus-v1 section 6: an endpoint caches Artifact handles plus payload; a domain retry with a
-/// fresh call id gets fresh delivery ownership over the same immutable bytes.
-async fn endpoint_cache_replays_artifact_results(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("agent.cached", ServiceConfig::default())
-        .await
-        .unwrap();
-    let service = tokio::spawn(async move {
-        let mut cache: HashMap<String, flybus::Artifact> = HashMap::new();
-        let mut executions = 0;
-        while let Some(req) = svc.next().await {
-            if req.method() == "Cache.Evict" {
-                cache.clear();
-                req.reply(obj(json!({})), &[]).await.unwrap();
-                continue;
-            }
-            let rid = req.payload()["requestId"].as_str().unwrap().to_owned();
-            if !cache.contains_key(&rid) {
-                executions += 1;
-                let bytes = format!("result of {rid}").into_bytes();
-                let mut w = server
-                    .artifacts()
-                    .allocate(bytes.len() as u64, "text/plain")
-                    .await
-                    .unwrap();
-                w.write_all(&bytes).unwrap();
-                cache.insert(rid.clone(), w.seal().await.unwrap());
-            }
-            let art = cache[&rid].clone();
-            req.reply(obj(json!({"executions": executions})), &[("state", &art)])
-                .await
-                .unwrap();
-        }
-    });
-    let mut ids = Vec::new();
-    for _ in 0..2 {
-        let res = within(
-            "result",
-            caller.call_and_wait(
-                "agent.cached",
-                None,
-                "Agent.Prepare",
-                obj(json!({"requestId": "req-41"})),
-                &[],
-            ),
-        )
-        .await
-        .unwrap();
-        assert_eq!(
-            res.outcome()["executions"],
-            1,
-            "the retry did not re-execute"
-        );
-        let art = res.artifact("state").unwrap();
-        assert_eq!(art.read_all().await.unwrap(), b"result of req-41");
-        ids.push((
-            res.delivery_id().to_owned(),
-            art.reference().artifact_id.clone(),
-        ));
-    }
-    assert_ne!(ids[0].0, ids[1].0, "each replay is a fresh delivery");
-    assert_eq!(ids[0].1, ids[1].1, "of the same immutable object");
-    e.settle("cache holds the only root", |s| {
-        s.sealed_artifacts == 1 && s.artifact_roots == 1
-    })
-    .await;
-    caller
-        .call_and_wait("agent.cached", None, "Cache.Evict", obj(json!({})), &[])
-        .await
-        .unwrap();
-    e.settle("eviction collects", |s| {
-        s.artifacts == 0 && s.store_bytes == 0
-    })
-    .await;
-    e.settle_files("sealed", 0).await;
-    service.abort();
-}
-
-async fn dropped_call_is_cancelled_and_late_result_consumed(via: Via) {
-    let e = env(via).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut svc = server
-        .register("example.abandon", ServiceConfig::default())
-        .await
-        .unwrap();
-    let art = sealed(&server, b"payload", "text/plain").await;
-    let pending = caller
-        .call("example.abandon", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    drop(pending);
-    e.settle("call detached", |s| s.calls == 1 && s.active_calls == 0)
-        .await;
-    // Detached: the reply is not routed and creates no caller-side roots.
-    let routed = req.reply(obj(json!({})), &[("a", &art)]).await.unwrap();
-    assert!(!routed);
-    drop((req, art));
-    e.settle("nothing retained", |s| {
-        s.calls == 0 && s.artifacts == 0 && s.owners == 0
-    })
-    .await;
-
-    // A result that arrives after its caller stopped waiting is consumed by the reactor.
-    let pending = caller
-        .call("example.abandon", None, "Do", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let req = within("request", svc.next()).await.unwrap();
-    let art = sealed(&server, b"late", "text/plain").await;
-    req.reply(obj(json!({})), &[("a", &art)]).await.unwrap();
-    drop((req, art));
-    e.settle("result delivered", |s| s.calls == 1 && s.owners == 1)
-        .await;
-    drop(pending);
-    e.settle("result consumed", |s| {
-        s.calls == 0 && s.artifacts == 0 && s.owners == 0
-    })
-    .await;
-    assert_eq!(caller.control_errors(), 0);
-}
-
-async fn active_call_limit(via: Via) {
-    let limits = Limits {
-        max_active_calls_per_client: 2,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let _svc = server
-        .register("example.limit", ServiceConfig::default())
-        .await
-        .unwrap();
-    let _a = caller
-        .call("example.limit", None, "M", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let _b = caller
-        .call("example.limit", None, "M", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let c = caller
-        .call("example.limit", None, "M", obj(json!({})), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(c.code, ErrorCode::Backpressure);
-}
-
-both_transports!(
-    request_reply_roundtrip,
-    registration_is_exclusive_and_pinned,
-    authority_is_enforced,
-    fifo_dispatch_and_out_of_order_completion,
-    service_queue_backpressure,
-    cancellation_states,
-    replies_are_single_and_independent_of_the_request_guard,
-    service_disconnect_fails_calls,
-    unregister_fails_queued_but_dispatched_may_reply,
-    raw_call_ids_and_forged_replies,
-    endpoint_cache_replays_artifact_results,
-    dropped_call_is_cancelled_and_late_result_consumed,
-    active_call_limit,
-);

services/flysim/crates/flybus/tests/sol_rereview_regressions.rs

@@ -1,876 +0,0 @@
-mod common;
-
-use std::io;
-use std::pin::Pin;
-use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
-use std::sync::{Arc, Condvar, Mutex};
-use std::task::{Context, Poll, Waker};
-use std::time::Duration;
-
-use common::{Raw, Via, env, env_with, obj, sealed, within};
-use flybus::wire::parse_serial_id;
-use flybus::{
-    Client, ClientConfig, Dispatch, ErrorCode, Limits, Policy, Retained, Router, RouterConfig,
-    ServiceConfig, SubscriptionConfig, Transport,
-};
-use serde_json::json;
-use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
-use tokio::sync::Notify;
-
-struct WriteProbe<S> {
-    inner: S,
-    state: Arc<Mutex<ProbeState>>,
-    first: Arc<Notify>,
-}
-
-#[derive(Default)]
-struct ProbeState {
-    armed: bool,
-    released: bool,
-    first_written: bool,
-    writer: Option<Waker>,
-    bytes: Vec<u8>,
-    ops: Vec<String>,
-}
-
-impl<S> WriteProbe<S> {
-    fn new(inner: S) -> (WriteProbe<S>, WriteProbeHandle) {
-        let state = Arc::new(Mutex::new(ProbeState::default()));
-        let first = Arc::new(Notify::new());
-        (
-            WriteProbe {
-                inner,
-                state: state.clone(),
-                first: first.clone(),
-            },
-            WriteProbeHandle { state, first },
-        )
-    }
-}
-
-#[derive(Clone)]
-struct WriteProbeHandle {
-    state: Arc<Mutex<ProbeState>>,
-    first: Arc<Notify>,
-}
-
-impl WriteProbeHandle {
-    fn arm(&self) {
-        let mut state = self.state.lock().unwrap();
-        state.armed = true;
-        state.released = false;
-        state.first_written = false;
-        state.writer = None;
-        state.bytes.clear();
-        state.ops.clear();
-    }
-
-    fn release(&self) {
-        let mut state = self.state.lock().unwrap();
-        state.released = true;
-        if let Some(waker) = state.writer.take() {
-            waker.wake();
-        }
-    }
-
-    async fn wait_first(&self) {
-        loop {
-            let notified = self.first.notified();
-            if self.state.lock().unwrap().first_written {
-                return;
-            }
-            tokio::time::timeout(Duration::from_secs(2), notified)
-                .await
-                .expect("router never wrote the first byte");
-        }
-    }
-
-    fn ops(&self) -> Vec<String> {
-        self.state.lock().unwrap().ops.clone()
-    }
-}
-
-impl<S: AsyncRead + Unpin> AsyncRead for WriteProbe<S> {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_read(cx, buf)
-    }
-}
-
-impl<S: AsyncWrite + Unpin> AsyncWrite for WriteProbe<S> {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        {
-            let mut state = self.state.lock().unwrap();
-            if state.armed && !state.released && state.first_written {
-                state.writer = Some(cx.waker().clone());
-                return Poll::Pending;
-            }
-        }
-        let limit = if self.state.lock().unwrap().armed {
-            1
-        } else {
-            buf.len()
-        };
-        match Pin::new(&mut self.inner).poll_write(cx, &buf[..limit]) {
-            Poll::Ready(Ok(n)) => {
-                let mut state = self.state.lock().unwrap();
-                state.bytes.extend_from_slice(&buf[..n]);
-                while state.bytes.len() >= 4 {
-                    let len = u32::from_le_bytes(state.bytes[..4].try_into().unwrap()) as usize;
-                    if state.bytes.len() < len + 4 {
-                        break;
-                    }
-                    let frame = state.bytes.drain(..len + 4).collect::<Vec<_>>();
-                    let envelope = flybus::wire::Envelope::decode(&frame[4..]).unwrap();
-                    state.ops.push(envelope.op);
-                }
-                if state.armed && !state.first_written && n > 0 {
-                    state.first_written = true;
-                    self.first.notify_waiters();
-                }
-                Poll::Ready(Ok(n))
-            }
-            other => other,
-        }
-    }
-
-    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_flush(cx)
-    }
-
-    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_shutdown(cx)
-    }
-}
-
-struct PollHold<S> {
-    inner: S,
-    state: Arc<(Mutex<PollHoldState>, Condvar)>,
-    entered: Arc<Notify>,
-}
-
-#[derive(Default)]
-struct PollHoldState {
-    armed: bool,
-    entered: bool,
-    released: bool,
-}
-
-#[derive(Clone)]
-struct PollHoldHandle {
-    state: Arc<(Mutex<PollHoldState>, Condvar)>,
-    entered: Arc<Notify>,
-}
-
-impl<S> PollHold<S> {
-    fn new(inner: S) -> (PollHold<S>, PollHoldHandle) {
-        let state = Arc::new((Mutex::new(PollHoldState::default()), Condvar::new()));
-        let entered = Arc::new(Notify::new());
-        (
-            PollHold {
-                inner,
-                state: state.clone(),
-                entered: entered.clone(),
-            },
-            PollHoldHandle { state, entered },
-        )
-    }
-}
-
-impl PollHoldHandle {
-    fn arm(&self) {
-        self.state.0.lock().unwrap().armed = true;
-    }
-
-    async fn wait_entered(&self) {
-        loop {
-            let notified = self.entered.notified();
-            if self.state.0.lock().unwrap().entered {
-                return;
-            }
-            tokio::time::timeout(Duration::from_secs(2), notified)
-                .await
-                .expect("transport poll_write was never entered");
-        }
-    }
-
-    fn release(&self) {
-        let mut state = self.state.0.lock().unwrap();
-        state.released = true;
-        self.state.1.notify_all();
-    }
-}
-
-impl<S: AsyncRead + Unpin> AsyncRead for PollHold<S> {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_read(cx, buf)
-    }
-}
-
-impl<S: AsyncWrite + Unpin> AsyncWrite for PollHold<S> {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        let should_hold = {
-            let mut state = self.state.0.lock().unwrap();
-            if state.armed && !state.entered {
-                state.entered = true;
-                self.entered.notify_waiters();
-                true
-            } else {
-                false
-            }
-        };
-        if should_hold {
-            let mut state = self.state.0.lock().unwrap();
-            while !state.released {
-                state = self.state.1.wait(state).unwrap();
-            }
-            cx.waker().wake_by_ref();
-            return Poll::Pending;
-        }
-        Pin::new(&mut self.inner).poll_write(cx, &buf[..1])
-    }
-
-    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_flush(cx)
-    }
-
-    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.inner).poll_shutdown(cx)
-    }
-}
-
-async fn wait_for_single_delivery_owner(router: &Router) {
-    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
-    loop {
-        let stats = router.stats();
-        if stats.owners == 1 && stats.artifact_roots == 1 {
-            return;
-        }
-        assert!(
-            tokio::time::Instant::now() < deadline,
-            "source hold was not released before teardown: {stats:?}"
-        );
-        tokio::task::yield_now().await;
-    }
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn dropping_last_attached_responder_settles_the_call() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.abandoned", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut pending = caller
-        .call("example.abandoned", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-
-    let request = within("request", service.next()).await.unwrap();
-    drop(request);
-    tokio::time::sleep(Duration::from_millis(100)).await;
-
-    let stats = e.stats();
-    assert_eq!(stats.reply_capabilities, 0);
-    assert_eq!(stats.owners, 0);
-    assert_eq!(stats.calls, 0, "the last reply capability was released");
-    assert_eq!(stats.active_calls, 0, "the caller slot was not retired");
-    let error = tokio::time::timeout(Duration::from_millis(250), pending.result())
-        .await
-        .expect("the caller was left waiting after all reply authority was gone")
-        .unwrap_err();
-    assert_eq!(
-        (error.code, error.dispatch),
-        (ErrorCode::CallGone, Dispatch::Dispatched)
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn dropping_last_attached_responder_releases_request_attachments() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.abandoned-artifact", ServiceConfig::default())
-        .await
-        .unwrap();
-    let artifact = sealed(&caller, b"request", "application/octet-stream").await;
-    let mut pending = caller
-        .call(
-            "example.abandoned-artifact",
-            None,
-            "Work",
-            obj(json!({})),
-            &[("data", &artifact)],
-        )
-        .await
-        .unwrap();
-    drop(artifact);
-
-    let request = within("artifact request", service.next()).await.unwrap();
-    drop(request);
-    let error = within("abandoned artifact call", pending.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (error.code, error.dispatch),
-        (ErrorCode::CallGone, Dispatch::Dispatched)
-    );
-    e.settle("abandoned artifact released", |stats| {
-        stats.calls == 0
-            && stats.active_calls == 0
-            && stats.reply_capabilities == 0
-            && stats.owners == 0
-            && stats.artifacts == 0
-    })
-    .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn dropping_last_responder_clone_settles_the_call() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.abandoned-clone", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut pending = caller
-        .call("example.abandoned-clone", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-
-    let request = within("clone request", service.next()).await.unwrap();
-    let responder = request.responder();
-    drop(request);
-    e.settle("clone retains reply capability", |stats| {
-        stats.calls == 1
-            && stats.active_calls == 1
-            && stats.reply_capabilities == 1
-            && stats.owners == 0
-    })
-    .await;
-    drop(responder);
-    let error = within("clone release failure", pending.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (error.code, error.dispatch),
-        (ErrorCode::CallGone, Dispatch::Dispatched)
-    );
-    e.settle("clone release retired call", |stats| {
-        stats.calls == 0 && stats.active_calls == 0 && stats.reply_capabilities == 0
-    })
-    .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn dropping_last_responder_clone_with_attachment_settles_the_call() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.abandoned-clone-artifact", ServiceConfig::default())
-        .await
-        .unwrap();
-    let artifact = sealed(&caller, b"request", "application/octet-stream").await;
-    let mut pending = caller
-        .call(
-            "example.abandoned-clone-artifact",
-            None,
-            "Work",
-            obj(json!({})),
-            &[("data", &artifact)],
-        )
-        .await
-        .unwrap();
-    drop(artifact);
-
-    let request = within("clone artifact request", service.next())
-        .await
-        .unwrap();
-    let responder = request.responder();
-    drop(request);
-    e.settle("clone keeps only reply capability", |stats| {
-        stats.calls == 1
-            && stats.active_calls == 1
-            && stats.reply_capabilities == 1
-            && stats.owners == 0
-            && stats.artifacts == 0
-    })
-    .await;
-    drop(responder);
-    let error = within("clone artifact release failure", pending.result())
-        .await
-        .unwrap_err();
-    assert_eq!(
-        (error.code, error.dispatch),
-        (ErrorCode::CallGone, Dispatch::Dispatched)
-    );
-    e.settle("clone artifact release retired call", |stats| {
-        stats.calls == 0 && stats.active_calls == 0 && stats.reply_capabilities == 0
-    })
-    .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn fair_topic_insertion_preserves_router_envelope_order() {
-    let limits = Limits {
-        max_control_frames: 4096,
-        max_control_bytes: 16 << 20,
-        ..Limits::default()
-    };
-    let e = env_with(Via::Memory, limits, Policy::open()).await;
-    let publisher = e.client("publisher").await;
-    publisher
-        .declare_topic("t.order", Retained::None)
-        .await
-        .unwrap();
-
-    let mut raw = e.raw_hello("reader").await;
-    raw.call(
-        "subscribe",
-        json!({"topic": "t.order", "mode": "latest", "maxQueued": 1, "maxInFlight": 1, "replayLatest": false}),
-    )
-    .await
-    .unwrap();
-    let mut writer = raw.take_writer();
-    let flood = tokio::spawn(async move {
-        for n in 3..3000u64 {
-            let envelope = json!({
-                "protocol": "flybus", "major": 1, "minor": 0,
-                "id": format!("msg-{n}"), "replyTo": null, "kind": "command",
-                "op": "no.such.op", "body": {}, "attachments": []
-            });
-            if !writer.send(&serde_json::to_vec(&envelope).unwrap()).await {
-                break;
-            }
-        }
-    });
-
-    tokio::time::sleep(Duration::from_millis(200)).await;
-    publisher
-        .publish("t.order", obj(json!({"ready": true})), &[])
-        .await
-        .unwrap();
-
-    let mut last = 0;
-    let mut saw_delivery = false;
-    for _ in 0..2500 {
-        let envelope = within("router frame", raw.recv()).await.unwrap();
-        let serial = parse_serial_id("bus", &envelope.id).unwrap();
-        assert!(
-            serial > last,
-            "router emitted {} after bus-{last}",
-            envelope.id
-        );
-        last = serial;
-        saw_delivery |= envelope.op == "topic.message";
-        if saw_delivery && envelope.kind == flybus::wire::Kind::Reply {
-            break;
-        }
-    }
-    assert!(
-        saw_delivery,
-        "fair scheduling never inserted the topic message"
-    );
-    flood.abort();
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn sdk_accepts_fair_topic_insertion_through_saturated_control_backlog() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    config.limits.max_control_frames = 4096;
-    config.limits.max_control_bytes = 16 << 20;
-    let router = Router::new(config).unwrap();
-    let publisher = Client::connect(
-        router.connect_in_memory_as("publisher"),
-        ClientConfig::new("publisher", dir.path()),
-    )
-    .await
-    .unwrap();
-    publisher
-        .declare_topic("t.sdk-order", Retained::None)
-        .await
-        .unwrap();
-
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (probed, probe) = WriteProbe::new(router_stream);
-    router.serve_as(probed, "reader");
-    let reader = Client::connect(
-        Transport::from_stream(client_stream),
-        ClientConfig::new("reader", dir.path()),
-    )
-    .await
-    .unwrap();
-    let mut subscription = reader
-        .subscribe("t.sdk-order", SubscriptionConfig::latest().in_flight(1))
-        .await
-        .unwrap();
-    probe.arm();
-
-    let mut backlog = Vec::new();
-    let completed = Arc::new(AtomicUsize::new(0));
-    for n in 0..256 {
-        let client = reader.clone();
-        let completed = completed.clone();
-        backlog.push(tokio::spawn(async move {
-            let result = client
-                .declare_topic(&format!("t.backlog-{n}"), Retained::None)
-                .await;
-            completed.fetch_add(1, Ordering::SeqCst);
-            result
-        }));
-    }
-    probe.wait_first().await;
-    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
-    while router.stats().topics < 257 {
-        assert!(
-            tokio::time::Instant::now() < deadline,
-            "control backlog was not admitted"
-        );
-        tokio::task::yield_now().await;
-    }
-    assert_eq!(
-        completed.load(Ordering::SeqCst),
-        0,
-        "writer was not blocked"
-    );
-    publisher
-        .publish("t.sdk-order", obj(json!({"ready": true})), &[])
-        .await
-        .unwrap();
-    assert_eq!(router.stats().queued, 1, "topic delivery was not queued");
-
-    probe.release();
-    let message = within("SDK fair delivery", subscription.next())
-        .await
-        .expect("subscription closed on router envelope ordering");
-    assert_eq!(message.payload()["ready"], true);
-    assert!(
-        reader.closed().is_none(),
-        "strict SDK rejected router output"
-    );
-    for task in backlog {
-        task.await.unwrap().unwrap();
-    }
-    let ops = probe.ops();
-    let topic = ops
-        .iter()
-        .position(|op| op == "topic.message")
-        .expect("instrumented stream did not carry the topic delivery");
-    assert!(
-        ops[topic + 1..].iter().any(|op| op == "topic.declare"),
-        "topic delivery was not fairly inserted ahead of remaining controls: {ops:?}"
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn shutdown_does_not_deliver_a_frame_after_releasing_its_owner() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    let router = Router::new(config).unwrap();
-    let publisher = Client::connect(
-        router.connect_in_memory_as("publisher"),
-        ClientConfig::new("publisher", dir.path()),
-    )
-    .await
-    .unwrap();
-    publisher
-        .declare_topic("t.shutdown", Retained::None)
-        .await
-        .unwrap();
-
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (probed, probe) = WriteProbe::new(router_stream);
-    router.serve_as(probed, "reader");
-    let mut raw = Raw::over(Transport::from_stream(client_stream), dir.path());
-    raw.hello("reader").await.unwrap();
-    raw.call(
-        "subscribe",
-        json!({"topic": "t.shutdown", "mode": "latest", "maxQueued": 1, "maxInFlight": 1, "replayLatest": false}),
-    )
-    .await
-    .unwrap();
-    probe.arm();
-
-    let artifact = sealed(&publisher, b"still-owned", "application/octet-stream").await;
-    publisher
-        .publish("t.shutdown", obj(json!({})), &[("data", &artifact)])
-        .await
-        .unwrap();
-    drop(artifact);
-    probe.wait_first().await;
-    wait_for_single_delivery_owner(&router).await;
-    let before = router.stats();
-    assert_eq!((before.owners, before.artifact_roots), (1, 1));
-
-    router.shutdown();
-    assert_eq!(
-        router.stats().owners,
-        0,
-        "shutdown released the selected owner"
-    );
-    assert_eq!(
-        router.stats().artifacts,
-        0,
-        "shutdown collected its attachment"
-    );
-    assert!(
-        within("truncated topic frame", raw.recv()).await.is_none(),
-        "a complete frame was appended after a partial topic delivery"
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn protocol_close_cancels_partial_topic_frame_before_reclaiming_attachment() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    let router = Router::new(config).unwrap();
-    let publisher = Client::connect(
-        router.connect_in_memory_as("publisher"),
-        ClientConfig::new("publisher", dir.path()),
-    )
-    .await
-    .unwrap();
-    publisher
-        .declare_topic("t.close", Retained::None)
-        .await
-        .unwrap();
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (probed, probe) = WriteProbe::new(router_stream);
-    router.serve_as(probed, "reader");
-    let mut raw = Raw::over(Transport::from_stream(client_stream), dir.path());
-    raw.hello("reader").await.unwrap();
-    raw.call(
-        "subscribe",
-        json!({"topic": "t.close", "mode": "latest", "maxQueued": 1, "maxInFlight": 1, "replayLatest": false}),
-    )
-    .await
-    .unwrap();
-    probe.arm();
-
-    let artifact = sealed(&publisher, b"close", "application/octet-stream").await;
-    publisher
-        .publish("t.close", obj(json!({})), &[("data", &artifact)])
-        .await
-        .unwrap();
-    drop(artifact);
-    probe.wait_first().await;
-    wait_for_single_delivery_owner(&router).await;
-
-    raw.next = 0;
-    raw.command("topic.declare", json!({}), json!([])).await;
-    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
-    while router.stats().connections != 1 {
-        assert!(
-            tokio::time::Instant::now() < deadline,
-            "protocol close did not finish"
-        );
-        tokio::task::yield_now().await;
-    }
-    assert_eq!(router.stats().owners, 0);
-    assert_eq!(router.stats().artifacts, 0);
-    assert!(
-        within("protocol-close truncated frame", raw.recv())
-            .await
-            .is_none(),
-        "a final notice was appended after a partial frame"
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
-async fn teardown_waits_for_an_active_transport_poll_before_reclaiming() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    let router = Router::new(config).unwrap();
-    let publisher = Client::connect(
-        router.connect_in_memory_as("publisher"),
-        ClientConfig::new("publisher", dir.path()),
-    )
-    .await
-    .unwrap();
-    publisher
-        .declare_topic("t.poll-gate", Retained::None)
-        .await
-        .unwrap();
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (held, hold) = PollHold::new(router_stream);
-    router.serve_as(held, "reader");
-    let mut raw = Raw::over(Transport::from_stream(client_stream), dir.path());
-    raw.hello("reader").await.unwrap();
-    raw.call(
-        "subscribe",
-        json!({"topic": "t.poll-gate", "mode": "latest", "maxQueued": 1, "maxInFlight": 1, "replayLatest": false}),
-    )
-    .await
-    .unwrap();
-    hold.arm();
-
-    let artifact = sealed(&publisher, b"poll", "application/octet-stream").await;
-    let sealed_path = router
-        .store_dir()
-        .join("sealed")
-        .join(&artifact.reference().artifact_id);
-    publisher
-        .publish("t.poll-gate", obj(json!({})), &[("data", &artifact)])
-        .await
-        .unwrap();
-    drop(artifact);
-    hold.wait_entered().await;
-    wait_for_single_delivery_owner(&router).await;
-
-    let done = Arc::new(AtomicBool::new(false));
-    let shutdown_done = done.clone();
-    let shutdown_router = router.clone();
-    let shutdown = std::thread::spawn(move || {
-        shutdown_router.shutdown();
-        shutdown_done.store(true, Ordering::SeqCst);
-    });
-    tokio::time::sleep(Duration::from_millis(50)).await;
-    assert!(
-        !done.load(Ordering::SeqCst),
-        "teardown completed while poll_write was active"
-    );
-    assert!(
-        sealed_path.exists(),
-        "artifact was reclaimed while poll_write was active"
-    );
-
-    hold.release();
-    shutdown.join().unwrap();
-    assert!(done.load(Ordering::SeqCst));
-    assert_eq!(router.stats().owners, 0);
-    assert_eq!(router.stats().artifacts, 0);
-    assert!(!sealed_path.exists());
-    while let Some(envelope) = within("poll-gate close", raw.recv()).await {
-        assert_ne!(
-            envelope.op, "topic.message",
-            "delivery completed after teardown reclaimed its owner"
-        );
-    }
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn shutdown_cancels_partial_rpc_request_before_reclaiming_attachment() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    let router = Router::new(config).unwrap();
-    let caller = Client::connect(
-        router.connect_in_memory_as("caller"),
-        ClientConfig::new("caller", dir.path()),
-    )
-    .await
-    .unwrap();
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (probed, probe) = WriteProbe::new(router_stream);
-    router.serve_as(probed, "server");
-    let mut raw = Raw::over(Transport::from_stream(client_stream), dir.path());
-    raw.hello("server").await.unwrap();
-    raw.call(
-        "service.register",
-        json!({"name": "example.partial-request", "maxQueued": 1, "maxInFlight": 1}),
-    )
-    .await
-    .unwrap();
-    probe.arm();
-
-    let artifact = sealed(&caller, b"request", "application/octet-stream").await;
-    let _pending = caller
-        .call(
-            "example.partial-request",
-            None,
-            "Work",
-            obj(json!({})),
-            &[("data", &artifact)],
-        )
-        .await
-        .unwrap();
-    drop(artifact);
-    probe.wait_first().await;
-    wait_for_single_delivery_owner(&router).await;
-    let before = router.stats();
-    assert_eq!((before.owners, before.artifact_roots), (1, 1));
-
-    router.shutdown();
-    assert_eq!(router.stats().owners, 0);
-    assert_eq!(router.stats().artifacts, 0);
-    assert!(
-        within("truncated request frame", raw.recv())
-            .await
-            .is_none(),
-        "a complete frame was appended after a partial RPC request"
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn shutdown_cancels_partial_rpc_result_before_reclaiming_attachment() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.policy = Policy::open();
-    let router = Router::new(config).unwrap();
-    let server = Client::connect(
-        router.connect_in_memory_as("server"),
-        ClientConfig::new("server", dir.path()),
-    )
-    .await
-    .unwrap();
-    let mut service = server
-        .register("example.partial-result", ServiceConfig::default())
-        .await
-        .unwrap();
-    let (client_stream, router_stream) = tokio::io::duplex(64 * 1024);
-    let (probed, probe) = WriteProbe::new(router_stream);
-    router.serve_as(probed, "caller");
-    let mut raw = Raw::over(Transport::from_stream(client_stream), dir.path());
-    raw.hello("caller").await.unwrap();
-    raw.call(
-        "rpc.call",
-        json!({"callId": "call-1", "target": "example.partial-result", "expectedIncarnation": null, "method": "Work", "payload": {}}),
-    )
-    .await
-    .unwrap();
-    probe.arm();
-    let request = within("result request", service.next()).await.unwrap();
-    let artifact = sealed(&server, b"result", "application/octet-stream").await;
-    request
-        .reply(obj(json!({})), &[("data", &artifact)])
-        .await
-        .unwrap();
-    drop((artifact, request));
-    probe.wait_first().await;
-    wait_for_single_delivery_owner(&router).await;
-    let before = router.stats();
-    assert_eq!((before.owners, before.artifact_roots), (1, 1));
-
-    router.shutdown();
-    assert_eq!(router.stats().owners, 0);
-    assert_eq!(router.stats().artifacts, 0);
-    assert!(
-        within("truncated result frame", raw.recv()).await.is_none(),
-        "a complete frame was appended after a partial RPC result"
-    );
-}

services/flysim/crates/flybus/tests/sol_review_races.rs

@@ -1,819 +0,0 @@
-mod common;
-
-use common::{Via, env, env_with, obj, within};
-use flybus::wire::{Envelope, Kind, contract_digest, read_frame, write_frame};
-use flybus::{
-    CancelState, Client, ClientConfig, Dispatch, ErrorCode, Limits, Policy, Retained, Router,
-    RouterConfig, ServiceConfig, SubscriptionConfig, Transport,
-};
-use serde_json::{Map, Value, json};
-use std::io;
-use std::pin::Pin;
-use std::task::{Context, Poll, Waker};
-use std::time::Duration;
-use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
-use tokio::sync::oneshot;
-
-struct WriteFailsAfterHello {
-    response: Vec<u8>,
-    read: usize,
-    writes: usize,
-}
-
-impl AsyncRead for WriteFailsAfterHello {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        if self.read == self.response.len() {
-            return Poll::Pending;
-        }
-        let n = buf.remaining().min(self.response.len() - self.read);
-        let end = self.read + n;
-        buf.put_slice(&self.response[self.read..end]);
-        self.read = end;
-        Poll::Ready(Ok(()))
-    }
-}
-
-impl AsyncWrite for WriteFailsAfterHello {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        if self.writes == 0 {
-            self.writes = 1;
-            Poll::Ready(Ok(buf.len()))
-        } else {
-            Poll::Ready(Err(io::Error::new(io::ErrorKind::BrokenPipe, "injected")))
-        }
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-
-    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-}
-
-struct WriteBlocksAsReaderFails {
-    response: Vec<u8>,
-    read: usize,
-    hello_written: bool,
-    command_write_started: bool,
-    reader_waker: Option<Waker>,
-    dropped: Option<oneshot::Sender<()>>,
-}
-
-impl Drop for WriteBlocksAsReaderFails {
-    fn drop(&mut self) {
-        if let Some(dropped) = self.dropped.take() {
-            let _ = dropped.send(());
-        }
-    }
-}
-
-impl AsyncRead for WriteBlocksAsReaderFails {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        if self.read < self.response.len() {
-            let n = buf.remaining().min(self.response.len() - self.read);
-            let end = self.read + n;
-            buf.put_slice(&self.response[self.read..end]);
-            self.read = end;
-            return Poll::Ready(Ok(()));
-        }
-        if self.command_write_started {
-            return Poll::Ready(Err(io::Error::new(
-                io::ErrorKind::ConnectionReset,
-                "injected reader failure",
-            )));
-        }
-        self.reader_waker = Some(cx.waker().clone());
-        Poll::Pending
-    }
-}
-
-impl AsyncWrite for WriteBlocksAsReaderFails {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        if !self.hello_written {
-            self.hello_written = true;
-            return Poll::Ready(Ok(buf.len()));
-        }
-        self.command_write_started = true;
-        if let Some(waker) = self.reader_waker.take() {
-            waker.wake();
-        }
-        Poll::Pending
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-
-    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Poll::Pending
-    }
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn responder_survives_cancel_then_request_drop() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.race", ServiceConfig::default())
-        .await
-        .unwrap();
-    let pending = caller
-        .call("example.race", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let request = within("request", service.next()).await.unwrap();
-    let responder = request.responder();
-
-    assert_eq!(
-        pending.cancel().await.unwrap(),
-        CancelState::ExecutionUnknown
-    );
-    drop(request);
-    e.settle("request consumed", |s| s.owners == 0).await;
-
-    let routed = responder.reply(obj(json!({"done": true})), &[]).await;
-    assert_eq!(routed, Ok(false), "a detached reply is still a valid reply");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn cancel_after_request_consumption_retires_correlation() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.leak", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut pending = caller
-        .call("example.leak", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let request = within("request", service.next()).await.unwrap();
-    drop(request);
-    let failure = within("last responder terminal failure", pending.result()).await;
-    let failure = failure.unwrap_err();
-    assert_eq!(
-        (failure.code, failure.dispatch),
-        (ErrorCode::CallGone, Dispatch::Dispatched)
-    );
-    e.settle("consumed call retired", |s| {
-        s.calls == 0 && s.active_calls == 0 && s.owners == 0 && s.reply_capabilities == 0
-    })
-    .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn retained_replay_obeys_bounded_queue_byte_quota() {
-    let limits = Limits {
-        max_queued_bytes_per_client: 1,
-        max_owners_per_client: 2,
-        reserved_owners_per_client: 1,
-        ..Limits::default()
-    };
-    let e = env_with(Via::Memory, limits, Policy::open()).await;
-    let publisher = e.client("publisher").await;
-    let reader = e.client("reader").await;
-    publisher
-        .declare_topic("t.replay", Retained::Latest)
-        .await
-        .unwrap();
-    publisher
-        .publish("t.replay", obj(json!({"large": "x".repeat(1024)})), &[])
-        .await
-        .unwrap();
-
-    // Exhaust the reader's ordinary-owner allowance so replay cannot immediately dispatch.
-    let _hold = reader
-        .artifacts()
-        .allocate(0, "application/octet-stream")
-        .await
-        .unwrap()
-        .seal()
-        .await
-        .unwrap();
-    let replay = reader
-        .subscribe("t.replay", SubscriptionConfig::bounded().replay(true))
-        .await;
-    assert_eq!(replay.unwrap_err().code, ErrorCode::Backpressure);
-    assert_eq!(e.stats().subscriptions, 0, "failed replay is atomic");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn latest_replay_remains_bounded_outside_the_bounded_byte_pool() {
-    let limits = Limits {
-        max_queued_bytes_per_client: 1,
-        max_owners_per_client: 2,
-        reserved_owners_per_client: 1,
-        ..Limits::default()
-    };
-    let e = env_with(Via::Memory, limits, Policy::open()).await;
-    let publisher = e.client("publisher").await;
-    let reader = e.client("reader").await;
-    publisher
-        .declare_topic("t.latest", Retained::Latest)
-        .await
-        .unwrap();
-    publisher
-        .publish("t.latest", obj(json!({"large": "x".repeat(1024)})), &[])
-        .await
-        .unwrap();
-    let _hold = reader
-        .artifacts()
-        .allocate(0, "application/octet-stream")
-        .await
-        .unwrap()
-        .seal()
-        .await
-        .unwrap();
-    let sub = reader
-        .subscribe("t.latest", SubscriptionConfig::latest().replay(true))
-        .await
-        .unwrap();
-    assert_eq!(e.stats().subscriptions, 1);
-    drop(sub);
-    e.settle("latest replay released", |s| s.subscriptions == 0)
-        .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn pending_connections_are_bounded_and_hello_expires() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut config = RouterConfig::new(dir.path());
-    config.limits.max_clients = 1;
-    config.hello_timeout = Duration::from_millis(40);
-    config.policy = Policy::closed()
-        .client("first", flybus::Grants::all())
-        .client("second", flybus::Grants::all());
-    let router = Router::new(config).unwrap();
-
-    let pending = router.connect_in_memory_as("first");
-    tokio::time::timeout(Duration::from_millis(20), async {
-        while router.stats().connections != 1 {
-            tokio::task::yield_now().await;
-        }
-    })
-    .await
-    .unwrap();
-    assert_eq!(router.stats().connections, 1);
-    let refused = Client::connect(
-        router.connect_in_memory_as("second"),
-        ClientConfig::new("second", dir.path()),
-    )
-    .await;
-    assert_eq!(refused.unwrap_err().code, ErrorCode::RouterLost);
-    tokio::time::sleep(Duration::from_millis(80)).await;
-    assert_eq!(router.stats().connections, 0, "pending Hello timed out");
-    drop(pending);
-
-    let second = Client::connect(
-        router.connect_in_memory_as("second"),
-        ClientConfig::new("second", dir.path()),
-    )
-    .await
-    .unwrap();
-    second.close().await;
-    let unbound = Client::connect(
-        router.connect_in_memory(),
-        ClientConfig::new("first", dir.path()),
-    )
-    .await;
-    assert_eq!(unbound.unwrap_err().code, ErrorCode::RouterLost);
-}
-
-fn reply_body(value: Value) -> Map<String, Value> {
-    obj(json!({"ok": true, "value": value}))
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn client_rejects_wrong_version_and_operation_from_router() {
-    let dir = tempfile::tempdir().unwrap();
-    let (client_stream, mut fake_router) = tokio::io::duplex(64 * 1024);
-    let server = tokio::spawn(async move {
-        let hello = read_frame(&mut fake_router).await.unwrap().unwrap();
-        let hello = Envelope::decode(&hello).unwrap();
-        let hello_reply = Envelope {
-            major: 1,
-            minor: 0,
-            id: "bus-1".into(),
-            reply_to: Some(hello.id),
-            kind: Kind::Reply,
-            op: "bus.hello".into(),
-            body: reply_body(json!({
-                "routerId": "router-fake",
-                "connectionId": "conn-1",
-                "selectedMajor": 1,
-                "selectedMinor": 0,
-                "contractDigest": contract_digest(),
-                "limits": Limits::default().to_json(),
-            })),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &hello_reply.encode().unwrap())
-            .await
-            .unwrap();
-
-        let command = read_frame(&mut fake_router).await.unwrap().unwrap();
-        let command = Envelope::decode(&command).unwrap();
-        let invalid_reply = Envelope {
-            major: 2,
-            minor: 0,
-            id: "bus-1".into(),
-            reply_to: Some(command.id),
-            kind: Kind::Reply,
-            op: "publish".into(),
-            body: reply_body(json!({
-                "declared": true,
-                "topicIncarnation": "top-1",
-            })),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &invalid_reply.encode().unwrap())
-            .await
-            .unwrap();
-    });
-
-    let client = Client::connect(
-        Transport::from_stream(client_stream),
-        ClientConfig::new("client", dir.path()),
-    )
-    .await
-    .unwrap();
-    let result = client.declare_topic("t.x", Retained::None).await;
-    assert!(
-        result.is_err(),
-        "invalid router envelope was accepted: {result:?}"
-    );
-    server.await.unwrap();
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn client_strictly_validates_hello_envelope() {
-    for case in ["version", "operation", "id", "attachments"] {
-        let dir = tempfile::tempdir().unwrap();
-        let (client_stream, mut fake_router) = tokio::io::duplex(64 * 1024);
-        let server = tokio::spawn(async move {
-            let hello =
-                Envelope::decode(&read_frame(&mut fake_router).await.unwrap().unwrap()).unwrap();
-            let mut reply = Envelope {
-                major: 1,
-                minor: 0,
-                id: "bus-1".into(),
-                reply_to: Some(hello.id),
-                kind: Kind::Reply,
-                op: "bus.hello".into(),
-                body: reply_body(json!({
-                    "routerId": "router-fake",
-                    "connectionId": "conn-1",
-                    "selectedMajor": 1,
-                    "selectedMinor": 0,
-                    "contractDigest": contract_digest(),
-                    "limits": Limits::default().to_json(),
-                })),
-                attachments: Vec::new(),
-            };
-            match case {
-                "version" => reply.major = 2,
-                "operation" => reply.op = "publish".into(),
-                "id" => reply.id = "msg-1".into(),
-                "attachments" => reply.attachments.push(flybus::wire::Attachment {
-                    name: "x".into(),
-                    reference: flybus::ArtifactRef {
-                        store_id: "store-fake".into(),
-                        artifact_id: "a-1".into(),
-                        generation: 1,
-                        byte_length: 0,
-                        content_type: "x/y".into(),
-                        digest: None,
-                    },
-                    owner_id: "own-1".into(),
-                }),
-                _ => unreachable!(),
-            }
-            write_frame(&mut fake_router, &reply.encode().unwrap())
-                .await
-                .unwrap();
-        });
-        let result = Client::connect(
-            Transport::from_stream(client_stream),
-            ClientConfig::new("client", dir.path()),
-        )
-        .await;
-        assert!(result.is_err(), "invalid Hello case {case} was accepted");
-        server.await.unwrap();
-    }
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn client_rejects_unknown_reply_fields_and_invalid_direction_rules() {
-    let dir = tempfile::tempdir().unwrap();
-    let (client_stream, mut fake_router) = tokio::io::duplex(64 * 1024);
-    let server = tokio::spawn(async move {
-        let hello =
-            Envelope::decode(&read_frame(&mut fake_router).await.unwrap().unwrap()).unwrap();
-        let hello_reply = Envelope {
-            major: 1,
-            minor: 0,
-            id: "bus-1".into(),
-            reply_to: Some(hello.id),
-            kind: Kind::Reply,
-            op: "bus.hello".into(),
-            body: reply_body(json!({
-                "routerId": "router-fake",
-                "connectionId": "conn-1",
-                "selectedMajor": 1,
-                "selectedMinor": 0,
-                "contractDigest": contract_digest(),
-                "limits": Limits::default().to_json(),
-            })),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &hello_reply.encode().unwrap())
-            .await
-            .unwrap();
-        let command =
-            Envelope::decode(&read_frame(&mut fake_router).await.unwrap().unwrap()).unwrap();
-        let invalid = Envelope {
-            major: 1,
-            minor: 0,
-            id: "bus-2".into(),
-            reply_to: Some(command.id),
-            kind: Kind::Reply,
-            op: "topic.declare".into(),
-            body: reply_body(json!({
-                "declared": true,
-                "topicIncarnation": "top-1",
-                "extra": true,
-            })),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &invalid.encode().unwrap())
-            .await
-            .unwrap();
-    });
-    let client = Client::connect(
-        Transport::from_stream(client_stream),
-        ClientConfig::new("client", dir.path()),
-    )
-    .await
-    .unwrap();
-    assert!(client.declare_topic("t.x", Retained::None).await.is_err());
-    server.await.unwrap();
-
-    let (client_stream, mut fake_router) = tokio::io::duplex(64 * 1024);
-    let server = tokio::spawn(async move {
-        let hello =
-            Envelope::decode(&read_frame(&mut fake_router).await.unwrap().unwrap()).unwrap();
-        let hello_reply = Envelope {
-            major: 1,
-            minor: 0,
-            id: "bus-1".into(),
-            reply_to: Some(hello.id),
-            kind: Kind::Reply,
-            op: "bus.hello".into(),
-            body: reply_body(json!({
-                "routerId": "router-fake",
-                "connectionId": "conn-1",
-                "selectedMajor": 1,
-                "selectedMinor": 0,
-                "contractDigest": contract_digest(),
-                "limits": Limits::default().to_json(),
-            })),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &hello_reply.encode().unwrap())
-            .await
-            .unwrap();
-        let invalid_notice = Envelope {
-            major: 1,
-            minor: 0,
-            id: "bus-2".into(),
-            reply_to: Some("msg-99".into()),
-            kind: Kind::Notice,
-            op: "connection.closing".into(),
-            body: obj(json!({"code": "ROUTER_LOST", "message": "bad direction"})),
-            attachments: Vec::new(),
-        };
-        write_frame(&mut fake_router, &invalid_notice.encode().unwrap())
-            .await
-            .unwrap();
-    });
-    let client = Client::connect(
-        Transport::from_stream(client_stream),
-        ClientConfig::new("client", dir.path()),
-    )
-    .await
-    .unwrap();
-    tokio::time::timeout(Duration::from_secs(1), async {
-        while client.closed().is_none() {
-            tokio::task::yield_now().await;
-        }
-    })
-    .await
-    .unwrap();
-    server.await.unwrap();
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn writer_failure_terminates_reader_and_pending_work() {
-    let dir = tempfile::tempdir().unwrap();
-    let hello_reply = Envelope {
-        major: 1,
-        minor: 0,
-        id: "bus-1".into(),
-        reply_to: Some("msg-1".into()),
-        kind: Kind::Reply,
-        op: "bus.hello".into(),
-        body: reply_body(json!({
-            "routerId": "router-fake",
-            "connectionId": "conn-1",
-            "selectedMajor": 1,
-            "selectedMinor": 0,
-            "contractDigest": contract_digest(),
-            "limits": Limits::default().to_json(),
-        })),
-        attachments: Vec::new(),
-    }
-    .encode()
-    .unwrap();
-    let mut response = (hello_reply.len() as u32).to_le_bytes().to_vec();
-    response.extend(hello_reply);
-    let client = Client::connect(
-        Transport::from_stream(WriteFailsAfterHello {
-            response,
-            read: 0,
-            writes: 0,
-        }),
-        ClientConfig::new("client", dir.path()),
-    )
-    .await
-    .unwrap();
-    let result = tokio::time::timeout(
-        Duration::from_secs(1),
-        client.declare_topic("t.x", Retained::None),
-    )
-    .await
-    .expect("writer failure left command pending");
-    assert_eq!(result.unwrap_err().code, ErrorCode::RouterLost);
-    tokio::time::timeout(Duration::from_secs(1), client.close())
-        .await
-        .expect("writer failure left close waiting");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn reader_failure_cancels_blocked_write_and_drops_transport() {
-    let dir = tempfile::tempdir().unwrap();
-    let hello_reply = Envelope {
-        major: 1,
-        minor: 0,
-        id: "bus-1".into(),
-        reply_to: Some("msg-1".into()),
-        kind: Kind::Reply,
-        op: "bus.hello".into(),
-        body: reply_body(json!({
-            "routerId": "router-fake",
-            "connectionId": "conn-1",
-            "selectedMajor": 1,
-            "selectedMinor": 0,
-            "contractDigest": contract_digest(),
-            "limits": Limits::default().to_json(),
-        })),
-        attachments: Vec::new(),
-    }
-    .encode()
-    .unwrap();
-    let mut response = (hello_reply.len() as u32).to_le_bytes().to_vec();
-    response.extend(hello_reply);
-    let (dropped, transport_dropped) = oneshot::channel();
-    let client = Client::connect(
-        Transport::from_stream(WriteBlocksAsReaderFails {
-            response,
-            read: 0,
-            hello_written: false,
-            command_write_started: false,
-            reader_waker: None,
-            dropped: Some(dropped),
-        }),
-        ClientConfig::new("client", dir.path()),
-    )
-    .await
-    .unwrap();
-
-    let result = tokio::time::timeout(
-        Duration::from_secs(1),
-        client.declare_topic("t.x", Retained::None),
-    )
-    .await
-    .expect("reader failure left command pending");
-    assert_eq!(result.unwrap_err().code, ErrorCode::RouterLost);
-    tokio::time::timeout(Duration::from_secs(1), transport_dropped)
-        .await
-        .expect("reader failure left writer blocked")
-        .expect("transport drop signal was discarded");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn rejected_call_id_still_advances_monotonic_watermark() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let _service = server
-        .register("example.ids", ServiceConfig::default())
-        .await
-        .unwrap();
-    let mut raw = e.raw_hello("caller").await;
-
-    let rejected = raw
-        .call(
-            "rpc.call",
-            json!({"callId": "call-5", "target": "missing.service", "expectedIncarnation": null, "method": "M", "payload": {}}),
-        )
-        .await;
-    assert_eq!(common::code(&rejected), "NO_SERVICE");
-    let decreasing = raw
-        .call(
-            "rpc.call",
-            json!({"callId": "call-4", "target": "example.ids", "expectedIncarnation": null, "method": "M", "payload": {}}),
-        )
-        .await;
-    assert_eq!(common::code(&decreasing), "INVALID_ENVELOPE");
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn unsent_oversized_call_rolls_back_its_local_slot() {
-    let limits = Limits {
-        max_active_calls_per_client: 1,
-        ..Limits::default()
-    };
-    let e = env_with(Via::Memory, limits, Policy::open()).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.rollback", ServiceConfig::default())
-        .await
-        .unwrap();
-    let oversized = caller
-        .call(
-            "example.rollback",
-            None,
-            "Work",
-            obj(json!({"blob": "x".repeat(70_000)})),
-            &[],
-        )
-        .await;
-    assert_eq!(oversized.unwrap_err().code, ErrorCode::InvalidEnvelope);
-
-    let mut pending = caller
-        .call("example.rollback", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let request = within("request after rollback", service.next())
-        .await
-        .unwrap();
-    request.reply(obj(json!({"ok": true})), &[]).await.unwrap();
-    assert_eq!(pending.result().await.unwrap().outcome()["ok"], true);
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn caller_disconnect_cleanup_works_before_and_after_consumption() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let mut service = server
-        .register("example.detach", ServiceConfig::default())
-        .await
-        .unwrap();
-
-    let caller = e.client("caller-a").await;
-    let pending = caller
-        .call("example.detach", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let request = within("request a", service.next()).await.unwrap();
-    let responder = request.responder();
-    drop(request);
-    e.settle("request consumed with responder", |s| {
-        s.owners == 0 && s.reply_capabilities == 1
-    })
-    .await;
-    caller.close().await;
-    drop(pending);
-    assert!(!responder.reply(obj(json!({})), &[]).await.unwrap());
-    drop(responder);
-    e.settle("retained responder retired", |s| {
-        s.calls == 0 && s.reply_capabilities == 0
-    })
-    .await;
-
-    let caller = e.client("caller-b").await;
-    let pending = caller
-        .call("example.detach", None, "Work", obj(json!({})), &[])
-        .await
-        .unwrap();
-    let request = within("request b", service.next()).await.unwrap();
-    drop(request);
-    e.settle("capability released first", |s| s.reply_capabilities == 0)
-        .await;
-    caller.close().await;
-    drop(pending);
-    e.settle("consumed call retired on disconnect", |s| s.calls == 0)
-        .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn dropping_service_with_buffered_requests_retires_every_call() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let service = server
-        .register(
-            "example.buffered",
-            ServiceConfig {
-                max_queued: 4,
-                max_in_flight: 4,
-            },
-        )
-        .await
-        .unwrap();
-    let mut calls = Vec::new();
-    for _ in 0..4 {
-        calls.push(
-            caller
-                .call("example.buffered", None, "Work", obj(json!({})), &[])
-                .await
-                .unwrap(),
-        );
-    }
-    e.settle("requests buffered in SDK", |s| s.reply_capabilities == 4)
-        .await;
-    drop(service);
-    for call in &mut calls {
-        let error = within("buffered call failure", call.result())
-            .await
-            .unwrap_err();
-        assert_eq!(
-            (error.code, error.dispatch),
-            (ErrorCode::NoService, flybus::Dispatch::Dispatched)
-        );
-    }
-    e.settle("buffered calls retired", |s| {
-        s.calls == 0 && s.reply_capabilities == 0 && s.owners == 0
-    })
-    .await;
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn reply_racing_cancel_has_only_the_two_contract_outcomes() {
-    let e = env(Via::Memory).await;
-    let server = e.client("server").await;
-    let caller = e.client("caller").await;
-    let mut service = server
-        .register("example.reply-race", ServiceConfig::default())
-        .await
-        .unwrap();
-    for _ in 0..32 {
-        let mut pending = caller
-            .call("example.reply-race", None, "Work", obj(json!({})), &[])
-            .await
-            .unwrap();
-        let request = within("racing request", service.next()).await.unwrap();
-        let responder = request.responder();
-        let (cancel, reply) = tokio::join!(
-            pending.cancel(),
-            responder.reply(obj(json!({"ok": true})), &[])
-        );
-        match (cancel.unwrap(), reply.unwrap()) {
-            (CancelState::Completed, true) => {
-                assert_eq!(pending.result().await.unwrap().outcome()["ok"], true);
-            }
-            (CancelState::ExecutionUnknown, false) => {
-                assert_eq!(
-                    pending.result().await.unwrap_err().code,
-                    ErrorCode::CallGone
-                );
-            }
-            other => panic!("invalid cancel/reply race outcome: {other:?}"),
-        }
-        drop((request, responder));
-    }
-    e.settle("race calls retired", |s| {
-        s.calls == 0 && s.reply_capabilities == 0 && s.owners == 0
-    })
-    .await;
-}

services/flysim/crates/flybus/tests/wire.rs

@@ -1,355 +0,0 @@
-//! Wire and connection: hello negotiation, strict frame and envelope validation, body errors
-//! that keep the connection, envelope size limits and control-lane exhaustion.
-
-mod common;
-
-use std::time::Duration;
-
-use common::{Raw, Via, code, env, env_with, obj};
-use flybus::wire::{Kind, MAX_ENVELOPE_BYTES, contract_digest};
-use flybus::{ErrorCode, Limits, Policy, Retained};
-use serde_json::{Value, json};
-
-async fn hello_negotiation(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw().await;
-    let v = raw.hello("probe").await.unwrap();
-    assert_eq!(v["routerId"], e.router.router_id());
-    assert_eq!(
-        (v["selectedMajor"].as_u64(), v["selectedMinor"].as_u64()),
-        (Some(1), Some(0))
-    );
-    assert_eq!(v["contractDigest"], contract_digest());
-    assert!(v["connectionId"].as_str().unwrap().starts_with("conn-"));
-    assert_eq!(
-        flybus::Limits::from_json(&v["limits"]).unwrap(),
-        Limits::default()
-    );
-    let c = e.client("sdk").await;
-    assert_eq!(c.info().router_id, e.router.router_id());
-    assert_ne!(c.info().connection_id, v["connectionId"]);
-}
-
-async fn expect_closed(raw: &mut Raw, want: &str) {
-    let notice = raw
-        .closing()
-        .await
-        .unwrap_or_else(|| panic!("no connection.closing notice (wanted {want})"));
-    assert_eq!(notice["code"], want, "{notice:?}");
-}
-
-async fn hello_refusals(via: Via) {
-    let e = env_with(
-        via,
-        Limits::default(),
-        Policy::closed().client("known", flybus::Grants::all()),
-    )
-    .await;
-    let mut raw = e.raw_as("known").await;
-    raw.command(
-        "topic.declare",
-        json!({"name": "t.x", "retained": "none"}),
-        json!([]),
-    )
-    .await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-
-    let mut raw = e.raw_as("known").await;
-    let r = raw
-        .call(
-            "bus.hello",
-            json!({"clientId": "known", "clientIncarnation": "i-1", "supportedMajors": [2, 3]}),
-        )
-        .await;
-    assert_eq!(code(&r), "VERSION_MISMATCH");
-    assert!(
-        raw.recv().await.is_none(),
-        "refused hello closes the connection"
-    );
-
-    let mut raw = e.raw_as("known").await;
-    assert_eq!(code(&raw.hello("stranger").await), "NOT_AUTHORIZED");
-    assert!(raw.recv().await.is_none());
-
-    let mut raw = e.raw_as("known").await;
-    let r = raw.call("bus.hello", json!({"clientId": "known", "clientIncarnation": "i-2", "supportedMajors": [1], "admin": true})).await;
-    assert_eq!(code(&r), "INVALID_ENVELOPE");
-
-    let mut raw = e.raw_as("known").await;
-    raw.hello("known").await.unwrap();
-    raw.command(
-        "bus.hello",
-        json!({"clientId": "known", "clientIncarnation": "i-3", "supportedMajors": [1]}),
-        json!([]),
-    )
-    .await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-    e.settle("all refused connections released", |s| s.connections == 0)
-        .await;
-}
-
-fn envelope(id: &str, body: Value) -> Value {
-    json!({"protocol": "flybus", "major": 1, "minor": 0, "id": id, "replyTo": null, "kind": "command",
-        "op": "publish", "body": body, "attachments": []})
-}
-
-async fn malformed_frames_close_the_connection(via: Via) {
-    let e = env(via).await;
-    let admin = e.client("admin").await;
-    admin.declare_topic("t.x", Retained::None).await.unwrap();
-    let publish = |id: &str| envelope(id, json!({"topic": "t.x", "payload": {}}));
-    let text = |v: Value| serde_json::to_string(&v).unwrap();
-    let att = |name: &str| {
-        json!({"name": name, "ref": {"storeId": "s", "artifactId": "a-1", "generation": "1",
-        "byteLength": "1", "contentType": "x", "digest": null}, "ownerId": "own-1"})
-    };
-    let mut too_many = publish("msg-2");
-    too_many["attachments"] = Value::Array((0..33).map(|i| att(&format!("a{i}"))).collect());
-    let mut duplicate_names = publish("msg-2");
-    duplicate_names["attachments"] = json!([att("a"), att("a")]);
-    let mut unknown_field = publish("msg-2");
-    unknown_field["priority"] = json!(1);
-    let mut from_router = publish("msg-2");
-    from_router["kind"] = json!("reply");
-    let mut reply_to = publish("msg-2");
-    reply_to["replyTo"] = json!("msg-1");
-    let mut major = publish("msg-2");
-    major["major"] = json!(2);
-    let mut not_flybus = publish("msg-2");
-    not_flybus["protocol"] = json!("flybusx");
-
-    let cases: Vec<(&str, Vec<u8>)> = vec![
-        ("nested duplicate key", br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-2","replyTo":null,"kind":"command","op":"publish","body":{"topic":"t.x","payload":{"a":{"b":1,"b":2}}},"attachments":[]}"#.to_vec()),
-        ("top-level duplicate key", br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-2","id":"msg-3","replyTo":null,"kind":"command","op":"publish","body":{"topic":"t.x","payload":{}},"attachments":[]}"#.to_vec()),
-        ("NaN", br#"{"protocol":"flybus","major":1,"minor":0,"id":"msg-2","replyTo":null,"kind":"command","op":"publish","body":{"topic":"t.x","payload":{"v":NaN}},"attachments":[]}"#.to_vec()),
-        ("invalid UTF-8", [&text(publish("msg-2")).into_bytes()[..60], b"\xff\xfe", &text(publish("msg-2")).into_bytes()[62..]].concat()),
-        ("trailing bytes", [text(publish("msg-2")).into_bytes(), b" {}".to_vec()].concat()),
-        ("not an object", b"[1,2,3]".to_vec()),
-        ("non-canonical id", text(publish("msg-02")).into_bytes()),
-        ("too many attachments", text(too_many).into_bytes()),
-        ("duplicate attachment names", text(duplicate_names).into_bytes()),
-        ("unknown envelope field", text(unknown_field).into_bytes()),
-        ("reply kind from a client", text(from_router).into_bytes()),
-        ("non-null replyTo", text(reply_to).into_bytes()),
-        ("wrong major after hello", text(major).into_bytes()),
-        ("wrong protocol", text(not_flybus).into_bytes()),
-    ];
-    for (i, (what, bytes)) in cases.into_iter().enumerate() {
-        let mut raw = e.raw_hello(&format!("bad-{i}")).await;
-        raw.send_bytes(&bytes).await;
-        let notice = raw
-            .closing()
-            .await
-            .unwrap_or_else(|| panic!("{what}: no closing notice"));
-        assert_eq!(notice["code"], "INVALID_ENVELOPE", "{what}");
-        e.settle(what, |s| s.connections == 1).await;
-    }
-
-    // Ids must increase.
-    let mut raw = e.raw_hello("replay").await;
-    raw.send_bytes(&serde_json::to_vec(&publish("msg-5")).unwrap())
-        .await;
-    raw.send_bytes(&serde_json::to_vec(&publish("msg-5")).unwrap())
-        .await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-
-    // Framing: a zero length, and a length over the limit with no body behind it.
-    let mut raw = e.raw_hello("zero").await;
-    raw.send_prefix(0).await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-    let mut raw = e.raw_hello("huge").await;
-    raw.send_prefix(u32::MAX).await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-    // A frame cut short by the end of the stream just ends the connection.
-    let mut raw = e.raw_hello("short").await;
-    raw.send_prefix(100).await;
-    drop(raw);
-    e.settle("only the admin remains", |s| s.connections == 1)
-        .await;
-}
-
-async fn body_errors_keep_the_connection(via: Via) {
-    let e = env(via).await;
-    let mut raw = e.raw_hello("raw").await;
-    let cases = [
-        ("no.such.op", json!({}), json!([])),
-        (
-            "topic.declare",
-            json!({"name": "t.a", "retained": "none", "extra": 1}),
-            json!([]),
-        ),
-        (
-            "topic.declare",
-            json!({"name": "t..a", "retained": "none"}),
-            json!([]),
-        ),
-        (
-            "topic.declare",
-            json!({"name": "t.a", "retained": "sometimes"}),
-            json!([]),
-        ),
-        ("topic.declare", json!({"name": "t.a"}), json!([])),
-        (
-            "subscribe",
-            json!({"topic": "t.a", "mode": "bounded", "maxQueued": 0, "maxInFlight": 1, "replayLatest": false}),
-            json!([]),
-        ),
-        (
-            "subscribe",
-            json!({"topic": "t.a", "mode": "bounded", "maxQueued": 1.0, "maxInFlight": 1, "replayLatest": false}),
-            json!([]),
-        ),
-        (
-            "subscribe",
-            json!({"topic": "t.a", "mode": "bounded", "maxQueued": 65536, "maxInFlight": 1, "replayLatest": false}),
-            json!([]),
-        ),
-        (
-            "artifact.allocate",
-            json!({"byteLength": 5, "contentType": "x"}),
-            json!([]),
-        ),
-        (
-            "artifact.allocate",
-            json!({"byteLength": "18446744073709551616", "contentType": "x"}),
-            json!([]),
-        ),
-        (
-            "rpc.call",
-            json!({"callId": "call-1", "target": "a.b", "expectedIncarnation": null, "method": "", "payload": {}}),
-            json!([]),
-        ),
-        (
-            "rpc.call",
-            json!({"callId": "call-1", "target": "a.b", "expectedIncarnation": null, "method": "M", "payload": []}),
-            json!([]),
-        ),
-        (
-            "delivery.consumed",
-            json!({"deliveryIds": "dlv-1"}),
-            json!([]),
-        ),
-        (
-            "topic.declare",
-            json!({"name": "t.a", "retained": "none"}),
-            json!([{"name": "x", "ref": {"storeId": "s", "artifactId": "a-1", "generation": "1", "byteLength": "1", "contentType": "x", "digest": null}, "ownerId": "own-1"}]),
-        ),
-    ];
-    for (op, body, atts) in cases {
-        let r = raw.call_with(op, body.clone(), atts).await;
-        assert_eq!(
-            r,
-            Err(("INVALID_ENVELOPE".into(), "not-dispatched".into())),
-            "{op} {body}"
-        );
-    }
-    assert_eq!(
-        code(
-            &raw.call("topic.declare", json!({"name": "t.a", "retained": "none"}))
-                .await
-        ),
-        "OK"
-    );
-    assert_eq!(e.stats().connections, 1);
-}
-
-async fn envelope_size_limits(via: Via) {
-    let e = env(via).await;
-    // Exactly 65536 bytes is a frame the router reads (and answers); one more is not.
-    let sized = |id: &str, total: usize| {
-        let base = serde_json::to_vec(
-            &json!({"protocol": "flybus", "major": 1, "minor": 0, "id": id, "replyTo": null,
-            "kind": "command", "op": "no.such.op", "body": {"pad": ""}, "attachments": []}),
-        )
-        .unwrap();
-        let pad = "p".repeat(total - base.len());
-        let bytes = serde_json::to_vec(
-            &json!({"protocol": "flybus", "major": 1, "minor": 0, "id": id, "replyTo": null,
-            "kind": "command", "op": "no.such.op", "body": {"pad": pad}, "attachments": []}),
-        )
-        .unwrap();
-        assert_eq!(bytes.len(), total);
-        bytes
-    };
-    let mut raw = e.raw_hello("raw").await;
-    raw.send_bytes(&sized("msg-2", MAX_ENVELOPE_BYTES)).await;
-    assert_eq!(code(&raw.reply("msg-2").await), "INVALID_ENVELOPE");
-    raw.send_bytes(&sized("msg-3", MAX_ENVELOPE_BYTES + 1))
-        .await;
-    expect_closed(&mut raw, "INVALID_ENVELOPE").await;
-
-    // The SDK refuses to send an oversized envelope and the connection lives on.
-    let c = e.client("c").await;
-    c.declare_topic("t.big", Retained::None).await.unwrap();
-    let huge = c
-        .publish(
-            "t.big",
-            obj(json!({"blob": "x".repeat(MAX_ENVELOPE_BYTES)})),
-            &[],
-        )
-        .await
-        .unwrap_err();
-    assert_eq!(huge.code, ErrorCode::InvalidEnvelope);
-    // An envelope that fits but whose delivery (with its added ids) would not is refused at
-    // admission rather than truncated later.
-    let edge = c
-        .publish("t.big", obj(json!({"blob": "x".repeat(65_300)})), &[])
-        .await
-        .unwrap_err();
-    assert_eq!(edge.code, ErrorCode::InvalidEnvelope);
-    assert!(edge.message.contains("delivery"), "{edge}");
-    assert_eq!(
-        c.publish("t.big", obj(json!({"blob": "x".repeat(60_000)})), &[])
-            .await
-            .unwrap()
-            .topic_sequence,
-        1
-    );
-}
-
-/// A client that sends commands and never reads replies is closed once its control lane is
-/// full, with a notice, instead of the router buffering without bound.
-async fn control_lane_exhaustion_closes(via: Via) {
-    let limits = Limits {
-        max_control_frames: 4,
-        ..Limits::default()
-    };
-    let e = env_with(via, limits, Policy::open()).await;
-    let mut raw = e.raw_hello("flood").await;
-    let mut writer = raw.take_writer();
-    let flood = tokio::spawn(async move {
-        for i in 2..20_000u64 {
-            let env = json!({"protocol": "flybus", "major": 1, "minor": 0, "id": format!("msg-{i}"), "replyTo": null,
-                "kind": "command", "op": "no.such.op", "body": {}, "attachments": []});
-            if !writer.send(&serde_json::to_vec(&env).unwrap()).await {
-                break;
-            }
-        }
-    });
-    tokio::time::sleep(Duration::from_millis(300)).await;
-    let mut replies = 0;
-    let mut last = None;
-    while let Some(env) = raw.recv().await {
-        match env.kind {
-            Kind::Reply => replies += 1,
-            _ => last = Some(env),
-        }
-    }
-    let last = last.expect("a closing notice");
-    assert_eq!(
-        (last.op.as_str(), last.body["code"].as_str()),
-        ("connection.closing", Some("QUOTA_EXCEEDED"))
-    );
-    assert!(replies < 19_998, "the router stopped answering");
-    flood.abort();
-    e.settle("flooder released", |s| s.connections == 0).await;
-}
-
-both_transports!(
-    hello_negotiation,
-    hello_refusals,
-    malformed_frames_close_the_connection,
-    body_errors_keep_the_connection,
-    envelope_size_limits,
-    control_lane_exhaustion_closes,
-);