reactor-effect-client 0.7.1 → 0.8.0

package/NOTICE

@@ -7,8 +7,13 @@ The canonical wire definitions and selected protocol behavior derive from:
 - reactor-runtime, commit 8e98536c6daedca298700dc45cbb5fd9e3676f16
 Their upstream licenses and notices are retained under notices/.
 The repository's packages/client/wire/proto directory contains the selected
-canonical protocol sources. The generated wire module also incorporates
-Google's protobuf Struct descriptor; see notices/google-protobuf-LICENSE.
+canonical protocol sources; protoc-gen-es generates the wire module from them.
+
+The wire module runs on @bufbuild/protobuf, a runtime dependency licensed
+Apache-2.0 AND BSD-3-Clause: Buf Technologies' Apache terms are retained in
+notices/bufbuild-protobuf-LICENSE, and the BSD terms of the Google protobuf
+code it incorporates, including the Struct descriptor, in
+notices/google-protobuf-LICENSE.
 
 Session, correlation and observation implementations incorporate the
 user-supplied reactor-effect-client reference source. Reusable H3, coordinator,

package/README.md

@@ -1,8 +1,8 @@
 # reactor-effect-client
 
-An independent Effect SDK for scoped Reactor sessions, H3 provider state and explicit orchestration. This is the portable core of the [reactor-effect workspace](https://github.com/mannyc2/reactor-effect-client); browser and native transports are the separate `reactor-effect-browser` and `reactor-effect-native` packages.
+An independent Effect SDK for Reactor's real-time video models: scoped sessions, the H3 provider, a playout that airs a keyed schedule across renewing sessions, and Reactor simulated in memory for tests. This is the portable core of the [reactor-effect workspace](https://github.com/mannyc2/reactor-effect-client); the browser and native transports are the separate `reactor-effect-browser` and `reactor-effect-native` packages.
 
-One canonical `Session` owns each allocation or attachment, its commands, connection generations, and cleanup evidence. Host packages select transport capabilities. H3 consumes that same session and exposes provider state. Applications opt into the separate orchestration and simulation modules when they need scheduling, sequence affinity, or renewal.
+One `Session` owns each allocation or attachment: its commands, connection generations and cleanup evidence. `H3` reads that session and never allocates one. `Playout` gets its sessions from a source and never allocates around it. Application scheduling, pricing, personas and proof of presented output stay with the application.
 
 This is not an official Reactor SDK. Protocol material is attributed in [NOTICE](./NOTICE) and [`notices/`](./notices/).
 
@@ -12,197 +12,159 @@ This is not an official Reactor SDK. Protocol material is attributed in [NOTICE]
 npm install reactor-effect-client effect@4.0.0-rc.117
 ```
 
-Effect `4.0.0-rc.117` is a peer dependency (`^4.0.0-rc.117`); later rc releases are accepted without a forced SDK bump. Every module in this package is portable: importing it selects no host and loads no native code. Add `reactor-effect-browser` or `reactor-effect-native` for a transport.
+Effect is a peer dependency at exactly `4.0.0-rc.117`: Effect's release candidates can move modules, and `4.0.0-rc.118` moved the `effect/unstable/*` modules this package imports, so a later rc needs a new SDK release. An application that adds `@effect/platform-node` itself should install it with `--save-exact`, since a later rc of it peers on a later Effect. The platform depends on `@effect/platform-node-shared` with a caret range, under which npm installs a later rc that fails to load on this Effect, so an application without `reactor-effect-native`, which peers on that package exactly, should pin it in its own manifest: `"overrides": { "@effect/platform-node-shared": "4.0.0-rc.117" }`. Every module in this package is portable: importing it selects no host and loads no native code. Add `reactor-effect-browser` or `reactor-effect-native` for a transport, or run on `ReactorTest` without one.
 
 ## Modules
 
-| Import                                | Purpose                                                                                        |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `reactor-effect-client`               | Canonical `Client`, `Session`, `make`/`layer`, errors, `Coordinator`, `Peers`, and `FetchHttp` |
-| `reactor-effect-client/h3`            | H3 provider contract, state/queue/clip evidence, controls, and reference validation            |
-| `reactor-effect-client/orchestration` | Scheduling, renewal, source adaptation, references, submissions, and sequences                 |
-| `reactor-effect-client/simulation`    | Production simulation source, factory, and Effect service layer                                |
-| `reactor-effect-client/testing`       | Reusable fault, PNG and WAV fixtures                                                           |
-| `reactor-effect-client/wire`          | Generated protocol messages and wire encoding/decoding                                         |
-| `reactor-effect-client/host`          | Host transport extension surface used by the first-party host packages                         |
+Each module is its own subpath, `reactor-effect-client/<Module>`, and the root exports every one as a namespace: `import { Playout, Reactor } from "reactor-effect-client"`. Nothing under `internal/` is reachable.
 
-These seven paths are the complete public export map. Internal file layout does not create additional supported deep imports. `/host` is published for `reactor-effect-browser` and `reactor-effect-native`, which pin this exact version; applications compose hosts through those packages and never need it.
+| Module         | What it is                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Reactor`      | The service that acquires sessions: `create` allocates one this process owns, `attach` joins one                |
+| `Session`      | One session: its status, events, commands, uploads, recordings, media and close report                          |
+| `Coordinator`  | Reactor's HTTP API: pricing, tokens (`Tokens`, `fixedTokens`), inspection, termination and recordings           |
+| `H3`           | The H3 provider over a session: its state and queue, its commands, acceptance evidence and reference validation |
+| `Playout`      | Airs keyed items in priority lanes across sessions it renews, and reports what aired                            |
+| `H3Source`     | A paid H3 session as a playout source: `open`, `resume` and the owner record `Allocation`                       |
+| `LocalSource`  | A playout source rendered in this process by the application's hooks                                            |
+| `Media`        | Decoded frames and platform tracks of one connection generation, and `recorder`                                 |
+| `Peer`         | The transport port a host implements, and the `PeerFactory` service                                             |
+| `ReactorError` | Every failure the client raises, its tagged reason and its dispatch outcome                                     |
+| `ReactorTest`  | Reactor simulated in memory: the coordinator, peers and an H3 model, driven by the Effect clock                 |
 
-## Session ownership
+The modules' doc comments state each option's default and bound; this page is the map.
 
-The root exports the `Client` service and its `make` and `layer` constructors. They require Effect HTTP and crypto services plus a `PeerFactory`. `create` allocates a remote session; `attach` identifies an existing session without taking ownership of its remote lifetime, unless it is given `adopt: true`, which takes that lifetime over: the adopted session is `owned`, so closing it, or a failed `attachConnected`, terminates it, as a process resuming a session its dead owner recorded needs. Both return the same scope-owned `Session` contract, and `session.connect` starts WebRTC. `createConnected` and `attachConnected` combine those steps and clean up a partial acquisition before reporting failure.
+## Sessions
 
-Releasing an owned session attempts and independently confirms remote termination. Releasing an attached session closes its local resources and publication claims. `session.close` returns a `CloseReport` that retains local cleanup errors and remote termination uncertainty. Supervisors can inspect that evidence without allocating another owner.
+`Reactor.layer()` needs a `Coordinator` and a host's `PeerFactory`; `Coordinator.layer(options)` and `Coordinator.layerConfig` (`REACTOR_API_URL`, and the API key from `REACTOR_API_KEY`) need an Effect `HttpClient`. `reactor.create` returns a connected session in the caller's scope, and closing the scope closes it:
 
 ```ts
-import { Effect, Redacted } from "effect";
-import * as Reactor from "reactor-effect-client";
-
-const useSession = Effect.gen(function* () {
-  const client = yield* Reactor.Client;
-  const session = yield* client.create({
-    model: "your-model",
-    jwt: Redacted.make("session-token"),
-  });
-
-  yield* session.connect;
-  return yield* session.current;
-});
-```
-
-The surrounding application supplies the `Client` layer and Effect platform services. Credentials, HTTP policy, scopes, and host transport selection stay visible in composition. A host package supplies the `PeerFactory`:
-
-```ts
-import { Effect, Layer } from "effect";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import * as Reactor from "reactor-effect-client";
-import * as Native from "reactor-effect-native";
+import { Effect, Layer } from "effect";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { Coordinator, H3, Reactor } from "reactor-effect-client";
+import { NativePeer } from "reactor-effect-native";
+
+const firstClip = Effect.gen(function* () {
+  const coordinator = yield* Coordinator.Coordinator;
+  const reactor = yield* Reactor.Reactor;
+  const session = yield* reactor.create({
+    model: H3.modelName,
+    tokens: coordinator.tokens({ modelName: H3.modelName, maxSessionDuration: "5 minutes" }),
+  });
+  const provider = yield* H3.make(session);
+  return yield* provider.enqueue({ prompt: "A slow camera move through a sunlit garden" });
+}).pipe(Effect.scoped);
 
-const clientLayer = Reactor.layer().pipe(
-  Layer.provide(Layer.mergeAll(Reactor.FetchHttp.layer, NodeServices.layer, Native.layer())),
+const ReactorLive = Reactor.layer().pipe(
+  Layer.provideMerge(Layer.mergeAll(Coordinator.layerConfig, NativePeer.layer())),
+  Layer.provide(FetchHttpClient.layer),
 );
 
-// useSession is the operation above. Acquiring a real session can be billable;
-// the repository's ordinary verification uses controlled local peers instead.
-const main = Effect.scoped(useSession).pipe(Effect.provide(clientLayer));
+// The application's entry point provides the layers once. Running it allocates a paid session.
+export const main = firstClip.pipe(Effect.provide(Layer.mergeAll(ReactorLive, NodeServices.layer)));
 ```
 
-Building a host layer is its preflight: `Native.layer()` loads and verifies the native library, and `Browser.layer` detects WebRTC, so an unsupported host fails while the layer is built, before any `Client` exists to allocate a remote session. Constructing a factory makes no allocation. HTTP and crypto services remain explicit. The root session constructor has no filesystem or path requirement. A custom host provides `PeerFactory` itself: `make` returns a fresh `Peer` for each connection generation, and an optional `check` fails when the host cannot create one right now; the factory runs it before every remote allocation.
-
-Browser and native media values stay bound to their negotiated generation. A reconnect creates a new generation; existing readers end or fail with their source. Applications obtain the new media generation explicitly, or opt into orchestration's recovering media streams. Each `VideoFrame` declares its pixel `format` (`"BGRA"` from the native host); nothing converts between formats implicitly. A recorder reads a track directly and sees loss before admission as a rise in `pressure`'s `droppedVideo`/`droppedAudio`, and a reader that falls behind its bound fails with `Overflow` and counts in `readerOverflows`. Every frame carries its admission `sequence` on its track, so `recorder(stream)` yields each frame plus a `Lost { after, count }` wherever the host dropped frames, at their position. A preview keeps only the newest frame with `Stream.buffer({ capacity: 1, strategy: "sliding" })`.
-
-## Errors
-
-Every failure the client raises is one of four classes, each with its own `_tag`, so `Effect.catchTag` and a Schema union tell them apart:
+Building a host layer is its preflight: `NativePeer.layer()` loads the addon and `BrowserPeer.layer` detects WebRTC, so a host that cannot run fails before anything is allocated, and the factory's `check` runs again before every allocation. Over `FetchHttpClient`, every coordinator request omits ambient credentials and refuses redirects.
 
-- `ReactorError`: a session, coordinator or host failure;
-- `CommandFailure`: a failed command, with the dispatch evidence its owner established;
-- `AcquisitionFailure`: a failed acquisition, with the `cleanup` report of its partial lease, kept by reference;
-- `PolicyFailure`, from `/orchestration`: a local refusal, which was never dispatched.
+**Ownership.** `create` allocates a session this process owns: closing it terminates the session and confirms the end with an independent read, since a `DELETE` response alone proves nothing. `onAllocated` runs after allocation and before connecting, so a supervisor can record the owner first; if it fails, the session is closed and the acquisition fails with an `AcquisitionFailure` carrying the close report, the hook's own error kept in its `Redacted` `context.detail`. `attach` joins a session without its remote lifetime; with `adopt: true` it takes that lifetime over, as a process resuming a dead owner's session does. `session.close` returns a `CloseReport`, a Schema you can persist, with the termination verdict and every local cleanup error; a failed acquisition's `AcquisitionFailure` carries the same report. `Session.mayStillBill(report)` says whether its session may still be billing: one this process owned that no read confirmed ended, or an allocation whose outcome, and so whose id, never arrived. Reconnecting keeps a session billing through its drops: an owned session its application never closed, or one a viewer holds after its owner has gone, runs on for as long as the process holding it does, to its cap if it has one; `Reactor.layer({ reconnect: false })` lets a drop end it 30 seconds later. The library keeps no pool of sessions: Effect's `Pool.makeWithTTL` over `reactor.create`, with `min: 0`, and a short `timeToLive`, closes a session left idle, where `Pool.make` keeps every session, and its bill, until the pool's scope closes.
 
-`isReactorFailure` recognizes any of them, and each class has an `is` guard. Re-raise a known failure through a guard rather than `instanceof ReactorError`, which none of the other three satisfies.
+**Tokens.** A session never sees the API key. It runs on `Tokens`: `create`, a token that may create one session, and `bind(sessionId)`, a fresh token bound to an open session. The session keeps one token for all its calls and mints the next with `bind` a minute before it expires, or a quarter of a shorter token's life, so it outlives any one token; Reactor keeps a token at most six hours. `coordinator.tokens({ modelName, maxSessionDuration })` mints both with the key the Coordinator holds. `maxSessionDuration` is required, a duration or `"unlimited"`, because an uncapped session bills until something ends it. `coordinator.mintToken` takes `bind` and `maxSessions` directly and refuses a grant Reactor echoes wider than asked. `Coordinator.fixedTokens(grant)` serves a session shorter than its token, and a browser gets its tokens from a server that holds the key (see the [browser example](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/browser/examples)); that server should bind only sessions its caller created, since a bound token commands, watches and ends its session. Each call has its own credential: `mintToken` and `tokens` use the API key; `inspect`, `terminate` and `downloadClip` use the Coordinator's `credential`, or the key when none is set, so a server holding the key can read and end any session of its account; and a session's own calls use its token.
 
-Each carries a tagged `reason`: route on `reason._tag`, with `Effect.catchReason`, `catchReasons` or `unwrapReason`. A `ReactorError`, `CommandFailure` or `AcquisitionFailure` reason is `Failure`, whose tag is a code such as `Timeout`, `Disconnected` or `InvalidInput`, or one of the reasons with fields of their own: `Http` (`status`, `retryAfter`, `body`), `Remote` and `RecorderDisabled` (`remoteCode`, `body`), `Native` (`status`, a Redacted `backendMessage`), `IceFailed` (`pairs`, `candidateTypes`) and `TransportFailed` (`pairs`). `ErrorCode` is the union of those tags. A `PolicyFailure` reason is a `Refusal` such as `QueueFull`, `SessionRecovering` or `Busy`, `Missing` with the request field whose clip has no known owner, or `Sequence` with the sequence's code.
+**Lifecycle.** A session reads `INACTIVE` while its last connection is gone; it is still live and billed, and Reactor ends it 30 seconds later unless a connection returns. Only `CLOSED` is terminal (`Coordinator.isTerminal`). A session reconnects a dropped connection on its own, owned or attached, whoever reads it: one attempt at once, then more on the `reconnect` schedule, until a connection has stayed ready 10 seconds, the schedule stops, the session is closing or Reactor or moderation ended it, Reactor refuses this client's protocol (`VersionMismatch`), or `reconnectTimeout` (30 seconds) has passed since the drop. A connection that drops sooner is a failed attempt of the same reconnect, so one that keeps dropping is tried on the schedule, not at once. The session stops trying 30 seconds after the first drop, or, if a connection is up then, once that connection drops before it has been ready 10 seconds; Reactor ends the session 30 seconds after its last connection drops. By default the second attempt comes 250 ms after the first fails and each wait doubles, to at most 4 seconds, jittered, and never sooner than a refusal's `Retry-After`, from which it is jittered only upward; a refusal that may lift, a 401 or 403 included, is tried again, with a fresh token only from its `Tokens`, once the current one nears its expiry. A schedule with no delay of its own tries again at once for all of `reconnectTimeout`, with a new peer each time, so space its attempts as the default does. Each failed attempt is a `Diagnostic` event, and a reconnect out of time stops with `Timeout`, the last attempt's failure, or why the connection up as the time ran out dropped, in its `Redacted` `context.detail`. Each attempt is a new connection generation of the same session: it allocates nothing and never replays a command. Meanwhile the status goes `disconnected`, then `connecting`, `waiting` and `ready` on the new generation, and the snapshot's `reconnecting` is true from the drop until a connection is ready or the session stops trying; `disconnected` without it is lasting, and `lastError` says why; a drop no attempt could get past (moderation or Reactor ended the session, or Reactor refuses this client's protocol) is lasting from the drop on. `Reactor.layer({ reconnect: false })` leaves a dropped connection down. `session.reconnect` opens a new connection generation at once, from a ready connection or a lasting drop, within `reconnectTimeout`, and never replays a command. While the session reconnects on its own, `session.reconnect` joins that reconnect rather than begin another: it succeeds once a connection is ready again, and fails as the reconnect stops, with the session's `lastError`, or with `Closed` if the session closes first. One whose connection is replaced while it makes its peer, as the session reconnects a drop or another reconnect asked for takes over, begins nothing either: it succeeds once a later connection is ready, and fails with the session's `lastError` once a later one is down for good, as the session's own reconnect stops or as another reconnect asked for fails meanwhile, whose failure it then takes. It fails with `InvalidState` while another reconnect asked for is under way. It fails with `Closed`, not submitted, if the session's close has begun before it takes the session over, or once its connection is open and becoming ready; one the close overtakes earlier in its negotiation fails with `Aborted`. What a host dies of as it fences or shuts down a peer never fails the session's work: a `ReactorError` is a `Diagnostic` event on that peer's generation, and any other defect goes to the `ErrorReporter`, except at the session's close, whose `CloseReport` keeps it in `localErrors`. A reconnect goes on past a replaced peer that fails to shut down, and a failed attempt fails with its own failure alone. Each generation's media and replies belong to it: a reconnect ends the old generation's readers, and a late reply is published labelled `stale-generation`. A `Moderation` event reports a content-moderation verdict; after `terminate` Reactor ends the session and it is not reconnected (`Moderated`). `session.snapshot`, `session.changes` and `session.observe` read the status: `changes` gives the snapshot at every change, in order, to a reader that falls behind too (its status, generation, `reconnecting`, `lastError`, received tracks and close as that change left them, the rest as the reader takes it), and `observe` pairs a snapshot with every event after it, with no gap.
 
-`context.outcome` says whether the remote may have applied the request: `not-submitted`, `unknown` or `replied`. A `PolicyFailure`'s outcome is always `not-submitted`, so an `EngineError = CommandFailure | PolicyFailure` is read without narrowing. `isRetryable` is true for local backpressure, a connection lost before dispatch, an HTTP refusal that names a delay, and the `QueueFull` and `SessionRecovering` refusals, and never when the outcome is `unknown`; `retryAfter` is the delay an `Http` reason named.
+**Deadlines.** `Reactor.layer(options)` sets the session deadlines: `replyTimeout`, `uploadTimeout`, `connectTimeout` (3 minutes, the wait for a GPU included, which is not billed), `reconnectTimeout`, `readyTimeout` and `heartbeatInterval`; `reconnect` is the `Schedule` a session reconnects a dropped connection on, or `false` (see Lifecycle). `connectTimeout` and `reconnectTimeout` cut the allocation and the negotiation, not the host's work on either side of them: making a peer, and shutting one down, which the native peer bounds by its `shutdownTimeout`. Every duration is a `Duration.Input`, and a bare number is milliseconds, so write the unit. One that is not a finite, non-negative duration fails with `InvalidInput`, not submitted. `replyTimeout` is the library's own deadline for a reply, not a caller's wait: after dispatch its expiry fails with `Timeout`, outcome `unknown`, and the request stays attributable. To stop waiting without abandoning a command, fork it and bound the join:
 
 ```ts
-const admission = (failure: EngineError) =>
-  failure.context.outcome === "unknown" ? "reconcile" : failure.isRetryable ? "defer" : "reject";
-
-const enqueued = engine.enqueue(request).pipe(
-  Effect.catchReasons("PolicyFailure", {
-    QueueFull: () => Effect.succeed("wait for a free generation slot"),
-    SessionRecovering: () => Effect.succeed("wait for the session to recover"),
-  }),
-);
-```
-
-`message` is written by the library and never contains provider or payload text, so spans and logs that record it stay payload-free. Provider and backend text is kept only for explicit inspection: `Http.body`, `Remote.body`, the Redacted `Native.backendMessage` and `context.detail`. Diagnostic JSON leaves all of them out, and none of them is part of the cause chain that exporters render.
-
-## Tracing
-
-The client traces through Effect's `Tracer`, so any tracer the application provides, such as `OtlpTracer`, receives its spans. An operation a caller can cancel has a client span at the call: `reactor.session.create` and `reactor.session.attach`, `reactor.session.connect` and `reactor.session.reconnect` (with an event per phase, from `reactor.connect.described` to `reactor.connect.ready`), `reactor.session.upload` and `reactor.session.close`, and in orchestration `reactor.orchestration.resume` and `reactor.orchestration.renewal.open`, `recover`, `replace` and `switch`. A request the session owns past its caller's wait, a command or control request (`reactor.session.command`, `reactor.session.control`) or an H3 enqueue (`reactor.h3.enqueue`, with `reactor.h3.reconcile`), has its span on its own execution, so the span ends with the request's outcome even after the caller stopped waiting. Termination returns a verdict rather than failing, so `reactor.coordinator.terminate` and `reactor.session.close` carry it as `reactor.termination.attempted`, `confirmed` and `evidence`: a span that ended without error does not mean a paid session stopped. Spans name identity and outcome only: never a credential, command input, a reply, an upload's name or bytes, or provider text. The renewal tick, frames, streams and heartbeats are not traced.
-
-## Time options
-
-Every time option is an Effect `Duration.Input` named by its role:
-
-- on the session, `connectTimeout`, `readyTimeout`, `heartbeatInterval`, `replyTimeout` and `uploadTimeout`;
-- on the coordinator, `requestTimeout` and the poll's `initialDelay` and `maxDelay`, and on a token, `maxSessionDuration` and `expiresAfter`, which must be whole seconds;
-- on H3, `replyTimeout`, `uploadTimeout`, `setupTimeout`, `reconcileWindow` and `resultHookTimeout`;
-- in orchestration, `lead`, `reconnectTimeout`, `handoffGrace` and the `lifetime` that `open` returns.
-
-A bare number is milliseconds, as everywhere in Effect, so write the unit: `lead: "30 seconds"`, because `lead: 30` is 30 milliseconds. `"Infinity"` disables the heartbeat and marks a source that never expires. A value that is NaN, negative, zero where zero means nothing, or longer than the option's maximum fails with `InvalidInput`, not submitted. Measurements, instants and media lengths stay numbers in the unit their name carries: `requestRecordingClip(seconds)`, `ClipRequest.durationSeconds`, a renewal's `ageSeconds`.
-
-`replyTimeout` is the session's own deadline for a reply. The session's default and a command's override share the key: `session.command(name, data, { uploads, replyTimeout })`. It is not a caller's wait. After dispatch it fails with `Timeout`, outcome `unknown`, and the command's `requestId`, and the request's slot stays held until a late reply or the connection generation retires. To stop waiting without abandoning the command, fork it and bound only the join:
-
-```ts
-const fiber = yield * Effect.forkScoped(session.command("set_seed", { seed: 1 }));
-const reply = yield * Fiber.join(fiber).pipe(Effect.timeout("2 seconds"));
-// Later, Fiber.await(fiber) still reads the command's own outcome.
-```
-
-When the command must be replayed rather than awaited, prepare it as an `Orchestration.Submission`.
-
-## Coordinator helpers
-
-`Coordinator` is a namespace on the root export. `Coordinator.make(configuration)` provides pricing, bounded token minting, session inspection, termination reports, and `downloadClip` for a prepared recording (`clip_ready`), which polls its HLS playlist and concatenates its segments within a caller wall deadline, through Effect HTTP services. Constructing this client makes no network request and requires no peer implementation. The root exports the Schemas the client decodes a session descriptor with, `SessionDescriptor`, `Capabilities`, `Track` and `Mapping`, and derives their types from them.
-
-## H3 provider
-
-`H3.make(session, options)` consumes an already connected canonical `Session`. It checks the deployment contract and exposes provider state, queue and clip messages, observations, command replies, and locally correlated acceptance evidence. Provider facts remain visible even when another client authored the clip. A command ACK establishes receipt; state changes require the corresponding model evidence.
-
-```ts
-import { Effect } from "effect";
+import { Effect, Fiber } from "effect";
 import type { Session } from "reactor-effect-client";
-import * as H3 from "reactor-effect-client/h3";
 
-const enqueueClip = (session: Session) =>
+export const seed = (session: Session.Session) =>
   Effect.gen(function* () {
-    const provider = yield* H3.make(session);
-    return yield* provider.enqueue({
-      prompt: "A slow camera move through a sunlit garden",
-      seconds: 5,
-    });
+    const fiber = yield* Effect.forkScoped(session.command("set_seed", { seed: 1 }));
+    // Later, Fiber.await(fiber) still reads the command's own outcome.
+    return yield* Fiber.join(fiber).pipe(Effect.timeout("2 seconds"));
   });
 ```
 
-Use a session created with `H3.modelName`. The adapter targets the documented `0.5.5` prompt-and-images subset of `reactor/h3-reference-to-video-turbo-realtime`, with reference audio. Prompt-only requests are supported. Image references accept owned bytes or explicit upload references; H3 itself requires no filesystem or path services. FastH3 `startingFrame`/`endingFrame` fields are absent from this contract.
+**Media.** `session.decoded` is the current generation's decoded media, from the native host or `ReactorTest`; `session.tracks` is its platform tracks, from the browser host. Every frame carries its admission `sequence` on its track, so `Media.recorder(stream)` yields each frame plus a `Lost { after, count }` wherever the host dropped frames. A reader that falls behind its bound fails alone with `Overflow` and is counted in `pressure`'s `readerOverflows`; a preview keeps only the newest frame with `Stream.buffer({ capacity: 1, strategy: "sliding" })`.
 
-`Request.audio` carries up to three audio references (`Audio 1`, `Audio 2`, ... in the prompt), sent as `reference_audios`: each 2–15 s of WAV, MP3, AAC/M4A, OGG/Opus, FLAC or WebM, mono or stereo, at most 25 MiB, as bytes or an existing upload. A clip with audio needs an image reference or `continueFrom`, and a continued clip takes at most two, since its continuation uses the third for the previous clip's soundtrack. The adapter identifies the container from the bytes and uploads it under that MIME type; it reads the length and channels of WAV and FLAC and refuses one outside the bounds, while H3 checks the other formats itself. Anything refused locally fails `not-submitted`, before an upload. `H3.validateAudioReference` validates one once for reuse, and `H3.audioReferenceLimits` lists the bounds. The `reference_audios` argument is optional in a deployment's schema: `provider.contract.referenceAudio` says whether this deployment declares it, and against one that does not, a request with audio fails `UnsupportedCapability` while every other request is unaffected. The accepted clip reports `has_reference_audio` and `reference_audio_count` when the deployment sends them. `ClipRequest.audio` takes `{ uri }` values for orchestration, loaded as image references are, and the simulation records them on the clip.
+Uploads (`session.upload`), recordings (`requestRecordingClip`, `recording`, then `coordinator.downloadClip`) and the deployment's OpenAPI document (`session.schema`) are on the session too.
 
-`provider.operation(submission)` keeps a committed clip's facts for as long as its scope holds them: `accepted`, `reached("generated" | "started")` and `ended` each resolve once, every fact naming the transport generation of its evidence, and a clip that fails or is popped first fails the phases it never reached with `ClipEnded`. Evidence arriving after the reconcile window, or in a later transport generation of the same session, still attributes an unknown enqueue. A commit reserves the operation's slot before it sends, so a table full of unresolved operations refuses new commits with `Overflow` instead of discarding evidence; releasing the scope frees the slot.
+## Errors
 
-The adapter exposes autoplay, flush, playback, reset, and other model controls as explicit operations. Creating it does not change those policies or initiate reconnect. Request `metadata` is a provider string; orchestration keeps its richer application annotation separately.
+Every failure is one of three classes, each with its own `_tag`: `ReactorError`, `CommandFailure` (a command, with the dispatch evidence its owner established) and `AcquisitionFailure` (a failed acquisition, with its cleanup report). `ReactorError.isReactorFailure` recognizes any of them. Each carries a tagged `reason`: route on it with `Effect.catchReason`, `catchReasons` or `unwrapReason`. A reason's tag is a code such as `Timeout`, `Disconnected`, `InvalidInput` or `Moderated`, or one of the reasons with fields of their own: `Http` (`status`, `retryAfter`, `body`), `Remote` and `RecorderDisabled` (`remoteCode`, `body`), `Native` (`backendMessage`), `IceFailed`, `TransportFailed` and `ClipEnded`.
 
-## Orchestration and simulation
+`context.outcome` says whether the remote may have applied the request: `not-submitted`, `unknown` or `replied`. `isRetryable` is true for backpressure, a connection lost before dispatch, and an HTTP refusal for now (a 5xx, 408, 429 or a named `Retry-After`), and never when the outcome is `unknown`, since the remote may already have applied it. A request whose token could not be had in time was never sent, and a create answered with a 5xx may have allocated a session, so its allocation is `unknown`.
 
-`reactor-effect-client/orchestration` owns opt-in scheduling, sequence routing, renewal, and recovering media. `fromH3Session(session, options)` builds a physical source from one connected session, deriving its H3 provider view (exposed as `source.provider`) and its decoded media from that session, so a source cannot pair one session's commands with another's media; it needs a host with decoded media (the native host), and `make({ open, ...options })` returns a handle with `engine`, `media`, `mediaState`, sequence operations, and joined cleanup reports. The `open` effect supplies each source and its lifetime budget. `openH3({ mint, onAllocated })` is that effect for paid H3 sessions: it mints the token, allocates the session, runs `onAllocated({ session, grant, allocation })` before connecting so the owner can be recorded durably, then connects and derives the source, with the granted length as its lifetime. The `allocation` is the record to persist (`Orchestration.Allocation`, without the token); its `endsAt` is when the granted length ends at the latest. `resumeH3({ allocation, jwt })` is the other half: after the owner died, it attaches to the recorded session with `adopt: true` and derives its source, sending only state and queue reads, never a canvas or other command a playing session refuses, with the time left until `endsAt` as its lifetime, so it is also a renewal `open`, and renewal terminates the session when it retires it. It refuses a record without `endsAt` or past it before anything is sent. `Orchestration.layer(options)` provides the handle's `Engine`, `Media` and `Handle` services from one orchestration; each build opens its own paid chain, so bind the layer to a `const`. `engine.observe(options)` is the engine's gap-free observation, as `session.observe` and `provider.observe` are for theirs: it subscribes before reading, returning the current `EngineState` with a stream of every later event (apply events idempotently by `clipId`; after an `Overflow`, observe again). `handle.observe(options)` extends it to the whole handle: the engine and media state, then engine events, renewals and media-state transitions in the one order they happened. `onRenewal` runs on its own reader and never holds the handle's command permit, and the orchestration logs through Effect's logger at debug level. Renewal measures elapsed time on Effect's monotonic clock: a source's age, its expiry, the lead, the retry cooldown and the recovery budget, as well as `BuildTiming`. A correction of the host's wall clock therefore moves no renewal and bends no build time. Recorded instants (every event's `at`, `startedAt`, `enqueuedAt` and `Allocation.endsAt`) stay epoch milliseconds of wall time. Renewal polls: each tick runs 100 ms after the previous one finished. Application scheduling, pricing, persona, and show policy stay outside the session and H3 layers.
+```ts
+import { Effect } from "effect";
+import type { H3 } from "reactor-effect-client";
+
+export const enqueue = (provider: H3.Provider, request: H3.Request) =>
+  provider.enqueue(request).pipe(
+    Effect.map((acceptance) => acceptance.clip.clip_id),
+    // Nothing was sent: this deployment takes no reference audio.
+    Effect.catchReason("CommandFailure", "UnsupportedCapability", () => Effect.succeed(undefined)),
+  );
+```
 
-`makeContinuous({ open, ...options })` is an opt-in constructor with the same Engine, media and sequence interfaces. `make`, `layer`, `Handle` and their complete `CleanupReport` keep their shape, and legacy renewal still defaults to a lifetime cap of 64 successful opens. Continuous renewal has no cumulative cap when `maxSessions` is omitted; an explicit value still caps successful opens (1..4096), and reaching it fails with `Overflow` at the next refused preparation, where legacy renewal reports a refused preparation as a failed setup and fails after three consecutive ones; a refused replacement for an expiring source fails at once. It owns at most two opening, active, recovering or retiring sources. For both constructors, close interrupts and joins every acquisition still in progress before it retires sources, and nothing is acquired once close begins or the owner's scope starts closing. Renewal, recovery and replacement stop at the same point, so an application finalizer that is slow to finish is not reported as failed renewal; commands stay admitted until close begins, so such a finalizer can still issue its last commands. Each acquisition runs on a fiber the handle owns, so an owner scope closed while the handle is still being constructed, including by a layer disposed during startup, stops the open and fails construction with a typed `Closed` refusal, or an `AcquisitionFailure` carrying its recorded lease; interrupting the construction itself stops the open before construction exits. Construction also fails with that refusal, and retires its first source, if the owner stops while that source is being activated. An open that fails only by interruption while the owner still admits sources fails as `InvalidState` ("Source acquisition was interrupted"), during construction and for a replacement. A failed first open keeps its typed failure, with any close defect beside it. Closing the handle from inside its own `open` does not complete. Bounding the owner scope's close, for example with a timeout while an application finalizer hangs, can skip the handle's own close and leave its sources open; close the handle first. A retirement or acquisition defect fails close and its owning scope with the original defect, reported once per failed attempt; cancellation by close is not a failure. Repeated close returns the same Exit, and `media.pressure` after close returns the final totals with `closed: true`. A stalled close or finalizer keeps its reservation; whole-handle close is not promised to finish within the local accounting budget. A defect or unexpected interruption in a recovery or polling worker fails `engine.failure`, observations and media readers with the original Effect Cause. While the owner remains open, state reads and subsequent commands also fail with that Cause; late recovery cannot reactivate it. Scheduler and item waiters receive it through observation without waiting for `unknownRecoveryTimeout`. Orderly scope cancellation is not a terminal failure. Explicit close still joins source cleanup, reports retirement/acquisition failures once, and leaves `mediaState` Closed; worker failure alone does not establish cleanup completion.
+`message` is written by the library and never holds provider or payload text, so spans and logs that record it stay payload-free. Provider and native text is kept only in `Redacted` fields for explicit inspection (`body`, `backendMessage`, `context.detail`) and never enters the cause chain that exporters render. Persist a failure as `ReactorError.FailureSummary`, never the error itself.
 
-Continuous adapters must supply globally unique physical source IDs and never reassign a clip ID during the handle's lifetime. Source and retained clip IDs are limited to 1024 UTF-16 code units. An oversized accepted or `Started` identity is never retained: the source is replaced as having broken its contract, and a sequence member with an oversized accepted identity becomes indeterminate. Live duplicate source IDs are rejected, but historical reuse after eviction cannot be detected with bounded memory. Private incarnation tokens fence selected preparations, source-fenced enqueues and sequence owners; an entirely unbound preparation still chooses current at first submit. A selected preparation whose route moved while its source is still live refuses with `RouteChanged`; `SessionRetired` means that source retired. Completed submissions retain their original Exit independently of the old source. Retired anchors no longer retained can refuse as missing rather than `SessionRetired`; that diagnostic limit does not permit dispatch to another conforming source.
+## Tracing
 
-`ContinuousOptions.retainedSuccessfulCleanups` retains the newest complete details (default 64, range 0..4096). `maxUnresolvedCleanups` bounds incomplete records plus outstanding cleanup reservations (default 16, range 2..4096); capacity is reserved before allocation and exhaustion fails closed with `Overflow`. Unknown committed outcomes occupy that ledger even when canonical remote termination is confirmed. Accounting `settled` means bookkeeping completed, not that every outcome became known. Each source separately bounds accepted and distinct Started identities at 4096, with accepted capacity reserved before dispatch; repeated Started observations do not consume another entry. Sequence history keeps its independent limits and explicit acknowledgement/release.
+The client traces through Effect's `Tracer`, so any tracer the application provides, such as `OtlpTracer`, receives its spans. An operation a caller can cancel has a client span at the call: `Reactor.create` and `Reactor.attach`, `Session.connect` and `Session.reconnect` (with an event per phase, from `reactor.connect.described` to `reactor.connect.ready`; each attempt of a session's own reconnect is a `Session.reconnect` span too, the root of a trace of its own, linked to the span of the `create` or `attach` that acquired the session; that reconnect runs with the tracer, `ErrorReporter`s and clock the acquisition ran with), `Session.upload` and `Session.close`, and `Coordinator.mintToken`, `pricing`, `inspect` and `terminate`. A request the session owns past its caller's wait, a command or control request (`Session.command`, `Session.control`) or an H3 enqueue (`H3.enqueue`, with `H3.reconcile`), has its span on its own execution, so the span ends with the request's outcome even after the caller stopped waiting. `Playout.submit` and the playout's other edits have spans, and so do `H3Source.open` and `H3Source.resume`. Termination returns a verdict rather than failing, so `Coordinator.terminate` and `Session.close` carry it as `reactor.termination.attempted`, `confirmed` and `evidence`: a span that ended without error does not mean a paid session stopped. Spans name identity and outcome only, never a credential, command input, a reply, an upload's name or bytes, or provider text. Frames, streams and heartbeats are not traced.
 
-`ContinuousHandleShape.close` returns the separate `CleanupSummary` Schema, with format `reactor-orchestration-cleanup-summary/v1` and no top-level `sessions`, so a legacy complete-history decoder rejects it. `retained` preserves canonical cleanup beside local accounting, scope and affinity evidence, including `unknownSubmissions`. Only proven complete rows may be omitted, counted separately in `omittedComplete.noAllocation`, `ownedTerminated` and `attachedDetached`; an attached detach is never counted as owned termination. `totalRetirements` equals retained rows plus omitted counts exactly; a reservation still outstanding when close concludes the summary is retained as an incomplete row, never omitted, and each row's accounting reflects its retirement's own join. Decoding rejects a row marked complete whose evidence does not prove it complete. Use `Schema.toCodecJson(CleanupSummary)` for bigint counts as decimal strings and errors as diagnostic JSON. Repeated successful close returns the same frozen summary. A defective close preserves its original Cause on every wait; `cleanup` exposes its factual summary only after retirement bookkeeping finishes and does not turn failed close into success.
+## H3
 
-`ClipRequest.sameSessionAs` targets the physical session that owns a known clip, including one already ready or playing, while leaving queue position unchanged. `before` requests insertion ahead of a clip still in the generation queue. Source affinity, insertion anchors, continuation, and sequence ownership must agree; missing, conflicting, retired, or recovering ownership fails locally with a `not-submitted` outcome. This keeps a dependent request on its required session during renewal without inventing an insertion point.
+`H3.make(session)` is the provider over a connected session created with `H3.modelName`. It targets the documented `0.5.5` schema of `reactor/h3-reference-to-video-turbo-realtime`: prompts with up to nine image references and three audio references, as owned bytes or earlier uploads. It reads the deployment's schema, requires only `enqueue`, `get_state` and `get_queue` to start, and fails any other command the deployment lacks as `UnsupportedCapability` before sending it (`provider.contract` says what it found). A request H3 would refuse is refused locally, `not-submitted`, before anything is uploaded; `H3.validateReference` and `H3.validateAudioReference` check a reference once for reuse, and the profile's constants (`requestSeconds`, `referenceLimits`, `audioReferenceLimits`, `canvases`) state the bounds.
 
-`Orchestration.makeScheduler(options)` is an opt-in clip scheduler over the `Engine`; `layerScheduler(options)` provides it as an Effect service. Apps submit stable keys into priority lanes, listed highest first. The `lineup(filler)` preset supplies one `line` lane above generated filler. Each lane is FIFO unless a deadline gives an earlier item priority for build admission. The scheduler admits one build at a time by default, keeps a floor and target of playable Ready seconds, and orders Ready clips within each physical session. Filler is generated by a pure `clip({ index, runwaySeconds, targetSeconds, durationSeconds })` callback and is never owed. `durationSeconds` is a suggested requested length within `filler.lengths` (H3's 5 to 15.084 seconds by default): before an `At` anchor, one of equal clips that tile the gap the runway leaves, adjusted by the measured actual over requested length, so filler ends on the anchor instead of running past it; otherwise the shortest length, since a shorter clip brings the next boundary, and a reaction, sooner. Choosing content by that context, a category for a long gap or an anchor ahead, stays with the callback. A replacement session has its own queue and runway during renewal; once an app clip is Ready there, the retiring session's Ready filler is withdrawn when no sequence keeps that session preferred and no old item is queued or building. The switch then follows its playing clip. It waits for that clip's missing video frames only for the renewal's `handoffGrace` past its `Ended`, or past the source first reporting nothing playing if `Ended` was lost: 250 ms by default and at most 5 seconds, since the retiring session running dry within it is not reported as `Starved`. Renewal checks every 100 ms, so the switch can come up to one check after the grace. A frame can land after `Ended`, but one the provider never sent never does. Frame loss, in that clip or earlier, and source drop totals remain on `Switched.tail`. Audio remains explicitly unverified. `EngineState.handoffReady` exposes this condition, and the `HandoffReady` engine event reports a final clip that arrived in full; neither establishes presented output. A submitted request cannot set `position`, `before`, `sameSessionAs`, `continueFrom` or sequence ownership, because those can override the scheduler's order. Continuity is asked for instead: `continuity: "previous"` on an item, group part, insert or replacement builds its clip continuing from the clip that airs just before it on its session (H3 `continue_from_clip_id`, which carries motion, camera and audio across the boundary). The scheduler resolves that clip when it builds: a Ready clip or item ranked just ahead of it, else the clip playing there. It waits while that item is not built yet, and builds the clip independently when there is none or the provider no longer offers it for continuation. If the continued build would be Ready only after that clip ends, the clips Ready behind it air first. The clip then continues from the one that will be playing by then, and airs right behind it, one clip later than its place, rather than after a clip it does not continue from. The build is projected from the scheduler's measured continued builds. Before one is measured, it is projected at 2.5 times an independent build: on hosted H3 a continued 5 s clip took 5.45 s against about 2.2 s. H3 continues only from a generated clip, so a clip still to be built is never chosen. Holding the last frame (`holdLastFrame`) makes a boundary gapless, not continuous; only continuity joins the picture. A clip that continues takes at most two audio references of its own. Continuity is fixed at build time, so a later insert between the two clips does not rebuild the one after it; replace that clip to continue from the insert.
+An enqueue is accepted by its correlated reply, or by the clip's metadata: metadata that came before the reply decides once the reply has stayed away `reconcileWindow` (5 seconds), and an enqueue whose reply is lost waits that long for it. One whose outcome stays `unknown` is never sent again, though later evidence within `reconcileWindow`, or on a later connection generation, can still prove its clip. `provider.operation(submission)` follows a committed clip through `accepted`, `reached("generated")`, `reached("started")` and `ended`, each naming the generation of its evidence. H3 replies to a command before it broadcasts the state the command changed, so a command that needs current facts waits for them; `snapshot`, `changes` and `observe` read them. A command's acknowledgement proves receipt, never a state change.
 
-Every planned `Switched` event includes immutable `handoff` evidence captured when the switch becomes eligible, before source-pressure and close waits. Its `sessionId` still names the retiring source; `handoff.replacementSessionId` names the new source. The decision is `no-observed-start`, `count-complete` or `grace-elapsed`, with the final clip's local decoded-frame counts and the observed grace origin (`Ended` or `Idle`) when available. `no-observed-start` means no local `Started` observation; it does not prove nothing played. Aggregate `tail` remains unchanged. The public `handoff` field is optional so historical event values remain assignable. These observations do not establish audio or presented-output completeness, and hosted qualification remains unrun.
+## Playout
 
-The `scheduler-renewal` qualification harness uses the public orchestration owner, `openH3`, scheduler and accepted drain. Its offline matrix exercises `make` and `makeContinuous`; paid qualification selects continuous with `retainedSuccessfulCleanups: 1`, `maxUnresolvedCleanups: 2` and `maxSessions: 2`. It retains both original source-cleanup reports and reconciles the compact summary. No paid scheduler-renewal run has occurred; hosted timing, audio completeness and presented or encoded output remain unqualified.
+`Playout.make(options)` (or `Playout.layer`) airs a schedule: the application submits keyed items into priority lanes, and one plan decides what to build, in what order, what to withdraw and when a replacement session takes over. A pure policy makes every decision; the service applies them one provider command at a time on each session, with sessions' commands running side by side, so a slow command, a filler enqueue's included, holds up only its own session. It wakes on a submission, a session's evidence or the plan's next deadline, and never polls. Sessions come from the `open` effect, called for the first session and for each replacement:
 
-`submit({ key, lane, request, window, start })` returns a handle with `started`, `outcome` and `firstDecisive` effects. `started` and `firstDecisive` retain the first observed start or definitive disposition; `outcome` waits for the end or definitive disposition. None settles on interim `Unknown`. Repeating a retained key and spec returns the same handle; a changed spec fails `KeyMismatch`. Active keys are retained until settled. `maxHistory` bounds completed key retention (4096 by default, zero disables history); older completed keys can be submitted anew once evicted. Handles already held by callers keep their original results. Applications needing longer deduplication retain their own key ledger. `window.notBefore` and `window.startBy` are relative monotonic durations, with firm deadlines dropped on expiry and soft deadlines recorded late at start. `start` defaults to `Follow` (the next boundary in its lane); `At` names an epoch millisecond anchor and a late policy (`nextBoundary`, `skipIfLaterThan`, or `drop`); `Asap` airs at the next boundary ahead of everything waiting in every lane and builds first; `Manual` is built ahead and held until `release(key)`, which sends it to the next boundary as `Asap`. A held item ranks behind everything, is not runway, and is built early only while filler keeps the runway at its floor; if it would still be next with less than 1.5 s of the playing clip left, it is removed and rebuilt, as a future `At` clip is. With filler off it is built once released. A drain withdraws a held item, since it cannot air without a release. `release` of a key that holds nothing fails with `InvalidRequest`. The scheduler fills toward an upcoming anchor, and cuts a playing clip only for a lane declared with `cut: true`. `WouldMissDeadline` rejects an item that cannot start before its deadline: after the rest of the playing clip and the Ready clips ranked ahead of it, and, once the scheduler has measured three builds, after its own build and every build that must go before it (the one in flight, higher lanes, a replacement or a started group in its lane, and earlier deadlines). A negative `startBy` offset is refused too. The projection is optimistic, so a refusal means the deadline cannot be met. After the same measurements, a firm item that can no longer start before its deadline, because work arrived ahead of it, is dropped as `late` before it takes the build slot. The scheduler measures each build from sending it to its clip being Ready, per requested second of clip, and the actual over the requested length; `state.estimates` reports the median and p95 of its recent builds, with continued builds measured apart as `continuedBuild`. A nonzero runway floor is raised to one p95 build of the next filler clip plus a second, so a refill started at the floor is Ready before the picture runs out; a zero floor still keeps filler off. The runway counts the playing clip from the engine's own start observation, so a new clip is never counted as empty while its Started event is being handled. A refused `At` removal is paced and retried; an uncertain removal waits for a fresh observation before retrying. Actual starts remain observable even when the provider could not hold the anchor. `withdraw(key)` waits for a provider-confirmed removal, including an in-flight build. A refused removal is not an outcome: the scheduler retries it a second later, and again after each refusal, until the clip is removed (`withdrawn`), starts (`already-started`) or settles another way (`not-found` for a failure, `already-started` if it ended or its start went unobserved). Only an unknown removal outcome fails the call, since the removal may already have taken effect. `drain()` stops admission, withdraws waiting clips and waits for the current clip to end. `drain({ finish: "accepted" })` lets all accepted items reach their disposition, including those still waiting to build, and keeps filler playing and refilling until every one of them is Ready, with its `At` anchor reached, has started or has settled, so a build in progress does not freeze the host. An `Unknown` item does not hold filler, but it holds successful drain completion until it settles. The scheduler's unknown-recovery deadline bounds waiter settlement if uncertainty remains; that failure does not establish remote cleanup completion. Both then stop filler admission, and both call `engine.stopRenewal` immediately, even while an enqueue is pending: new replacements cannot open, an opening replacement is cancelled and joined, and already acquired sources may finish. Expiry still retires a source and surfaces failure if no existing replacement can continue. The first drain call selects its mode. The owner closes its orchestration handle after drain completes.
+- `H3Source.open({ tokens, canvas, holdLastFrame, onAllocated })` mints a token, allocates, runs `onAllocated` with the owner record (`H3Source.Allocation`, without a token), connects and sets H3 up: autoplay off until the playout turns it on, the last frame held between clips unless `holdLastFrame: false` flushes to black, and the canvas set before the first enqueue. Its lifetime is what remains of the create token's cap when it returns, counted from the allocation request, so the playout never plans past the session's end; an uncapped session never expires and is replaced only when lost. Its session reconnects a dropped connection itself, and the source follows it once, whoever reads its events: it gives the session `recovery` (20 seconds) to be ready again and H3 to be read afresh, waiting out a connection that drops again during that read, and otherwise counts the session lost; a session that will not come back, with `reconnect: false`, once moderation ended it or once it stops trying, is lost at once, with no `Reconnecting` before the loss. The playout sends the session nothing meanwhile.
+- `H3Source.resume({ allocation, tokens })` adopts a session its dead owner recorded, with tokens bound to it; a session the owner already set up gets only reads.
+- `LocalSource.open({ build, present, lifetime })` renders clips in this process, with H3's autoplay semantics, for locally rendered material and demos. `build` makes a clip's value, and its built length when that differs (`LocalSource.Rendered`), and `present` plays that value into the source's `video` and `audio`. Both run in a scope the clip owns, which closes once the clip leaves the source, so a finalizer releases what they made. A hook that fails with the application's own error fails that clip alone, reason `Clip` with the error `Redacted` in `provider`; one that dies stops the source, and the playout replaces its session. Without hooks, `buildRatio` gives a stand-in whose clips build for that share of their length and play for their length. `lifetime` caps the session, as a paid one is capped, so the playout renews it; it is unending by default.
 
-`submitGroup({ key, lane, parts, window })` submits a group: parts, each with its own key and request, that build in order and air back to back, such as the beats of one spoken line. It returns a handle per part. Once a group's first part is admitted, its remaining parts build before any other item in its lane, so a deadline can move a whole group ahead of others in its lane but never split one. Once a part has started, the group's remaining Ready parts stay ahead of the rest of their lane. A higher lane can still go in at a boundary between parts. The window applies to the first part, and a group takes no `start` mode. `withdraw` accepts a group key, which withdraws every unstarted part, or a part key, which withdraws that part and every part after it; a part key's reply is that part's own outcome. A part that fails or is dropped, other than by being replaced, withdraws the parts after it, recorded as `Dropped` with reason `withdrawn`. Repeating a group key with the same parts returns the same handle. A changed group, or a key already used by an item or part, fails with `KeyMismatch`. A group holds at most 64 parts.
+What an application can ask for:
 
-`replace(key, { key, request })` amends a queued item or group part without leaving a gap. The new clip takes the old item's lane, group position, admission order, window and start, and builds first in its lane. An old item not yet admitted is swapped at once. Otherwise the old item stays in place until the new clip is Ready, then is withdrawn and settles as `Dropped` with reason `replaced`. If the old item starts first, the replacement is withdrawn instead. Replacing a group part never counts as breaking the group. A started or settled item, one already replaced, or one whose admission is uncertain cannot be replaced; the call fails with `InvalidRequest`. Repeating a replacement returns the same handle.
+- **Items** (`submit`) in lanes listed highest first. A lane queues (the default), replaces its waiting items make-before-break, or skips while busy (`LaneBusy`), and a `cut: true` lane stops a lower lane's playing clip once its own is Ready. An item starts `Follow` (its lane's next boundary), `Asap`, `Manual` (held until `release`) or `At` a wall-clock instant, within an optional `notBefore`/`startBy` window; `WouldMissDeadline` refuses one the plan cannot start in time. A request outside H3's documented limits, its references included and its metadata counted as sent, wrapped with the item's key and H3's own identity, is refused with `InvalidItem`, naming each field and limit, and nothing is sent for it.
+- **Edits**: `submitGroup` (parts that build in order and air back to back), `insert` before or after any item, `replace` a queued item make-before-break (if the item starts first, the replacement is dropped as `withdrawn`), `edit` for several edits applied together with the old clips as cover until the new ones are Ready, `withdraw` and `drain`. Keys are idempotent: the same spec returns the same handle, a changed one fails with `KeyMismatch`. Withdrawing a group key answers `withdrawn` if any part was, else `already-started` if any started; once the playout has stopped, a withdrawal answers from what became of the item or the parts.
+- **Filler** in the bottom lane keeps a runway of Ready seconds between `floor` and `target`, sized to tile the gap before an `At` anchor. Once three builds were measured, filler's counted, the floor covers one p95 build, so a refill started there is Ready in time. A tile asks for no less than its share, and H3 aligns it up to its frame grid, so the anchor may air up to 0.7 s late for each tile. By default (`protect: "air"`) filler also goes before queue order: an item whose p95 build, at the continued rate if it continues a clip, would outlast the air secured (`state.runwaySeconds`) waits for one filler clip that builds sooner than it does, long enough within `lengths` to cover the rest and a second more, and airing no longer than the item builds unless `lengths.min` is longer, and the floor covers the next such item's build and a second more. An item waits for one such clip at most, and once more on a session it is carried to. One with a time to meet goes at once: one with an `At` start or a `startBy`, and, as its time is now, one with an `Asap` start, a released `Manual` one, or one on a lane that cuts. `protect: "order"` builds each item as soon as it may: it airs sooner, but the air may go dark while it builds. A filler request outside H3's documented limits fails the playout with `InvalidFiller`, naming the clip's index, since asking again would get the same request. `Playout.lineup(filler)` is one `line` lane above it.
+- **Cues** fire at offsets from a clip's observed start or end, and `continuity: "previous"` builds a clip continuing from the one that airs before it.
 
-`SchedulerOptions.unknownRecoveryTimeout` defaults to 60 seconds and accepts a positive finite `Duration.Input` up to 10 minutes. It is read as caller data: an own or inherited data property is captured, while `null` or an accessor, on the option or inside its value, fails with `InvalidInput` without running. The original monotonic observation of an unknown dispatch starts the deadline when even one preferred-source reservation is uncertain, including with spare capacity and no waiting demand, or when its fate holds a drain. Duplicate submissions, later unknowns, snapshots and wall-clock changes do not extend an active episode. A usable Ready replacement or keyed proof can restore service; disappearance of the old source while replacement is unavailable cannot. A later drain blocked by older uncertainty uses its original age and can fail immediately. On expiry, an independent watchdog publishes the existing `Timeout` failure with `context.operation = "scheduler.unknownRecovery"`, settles item/control waiters through the terminal boundary and closes admission, even if the actor is waiting in `stopRenewal`. Unknown outcomes remain Unknown, and a build whose enqueue is already in flight settles as terminal `Unknown`, since the provider may still accept it. The deadline never releases uncertain capacity, replays a key, starts a new recovery policy or confirms remote cleanup; the orchestration owner still joins its actual cleanup. Canonical renewal already owns source replacement. Applications that relied on longer uncertainty waits must choose a larger finite budget or revise that service policy. The scheduler retains at most 4,096 uncertain filler identities and fails with `Overflow` before dispatching another.
+The playout reports what happened, kept apart from what was asked. `asRun` gives an item's statuses: Accepted, Building, Ready, Started, Ended, Dropped, Failed, `Unobserved` (acknowledged, start never seen) or `Unknown` (sent, acknowledgement never seen). An `Unknown` is never sent again and no time is invented for it. A handle's `started` resolves with the item's start or how it settled without one (`Playout.NotStarted`), and its `outcome` with how it settled (`Playout.Settled`): Ended, Dropped, Failed, Unobserved, or an `Unknown` once it is terminal. `Failed` says why with a tagged `reason`: `Clip` (the provider failed the clip; its own words stay `Redacted` in `provider`, out of `message`, logs and spans), `Command` (a command for it failed, with its `CommandFailure`; an enqueue refused unsent because its session was not ready is sent there again once what the session reports has changed, as a reconnect changes it, and fails only if refused again while the session reports itself ready), `Lost` (its session was lost while it played, or before it was built twice), `Moderated` (with the verdict's `categories`) or `Closed`. `events` adds cues, session events (`Opened`, `Switched`, `Replaced`, `SetupFailed`, `Moderated`, and `Reconnecting` and `Reconnected { afterMillis }` around a dropped connection), each filler clip's start and end (`Filler`), `ReaderOverflow` when a reader of a session's video or audio falls behind its bound (with the session's `MediaPressure`), and `Starved`. `state` gives the clip on air (`playing`: its key, `"filler"` or `"other"`, when its start was seen, and its length when known), the lanes, the sessions, the runway (the air secured, on the session on air and then on its replacement) and the build estimates it learned. `video` and `audio` are the on-air picture and sound across renewals, as decoded frames, and end when the playout stops; on a host with only platform tracks, such as a browser, they fail with `UnsupportedCapability`. `cleanup` holds the close reports of retired sessions and of opens that failed after allocating: every one that may still bill, and the latest others.
 
-`insert({ key, request, before | after, window })` places a clip immediately before or after an anchor: an item, a group part, or a group key, which means before the group's first part or after its last. Give exactly one of `before` and `after`. The clip takes the anchor's lane and start: after an `At` item it waits for the same anchor, and beside an `Asap` item it is `Asap` too. It builds in air order. Between two parts of a group it joins the group, so the group stays together, but it is an inserted part: its failure or withdrawal never breaks the group, and withdrawing its key withdraws only it. `after` may name the playing clip, which puts the insert at the next boundary. An insert that is not Ready when its place comes airs at the next boundary instead. Its window, like an item's, is relative to admission, and `WouldMissDeadline` counts only the Ready clips ahead of its place. An anchor that has settled, was replaced, is a held `Manual` item or whose admission is uncertain, or `before` a clip or group that has started, fails with `InvalidRequest`. Repeating an insert returns the same handle; a changed one fails with `KeyMismatch`.
+**Renewal.** A capped session builds only what airs before its cap. The replacement opens `lead` (30 seconds) before the cap ends, and never earlier, so what cannot air before the cap waits for it; it takes new work, and takes the air at a boundary once the retiring session is idle and a `grace` (250 ms) has passed since its last clip ended or failed on air. A session lost before a planned switch is closed, and the clips it never aired are rebuilt on the next one. An enqueue whose outcome stays unknown holds no build slot, since H3 builds in order, and after `unknownTimeout` (60 seconds) it makes its session indeterminate, so a replacement takes over. A failed setup, an open that fails or a session lost before any clip sent to it started, is followed by the next open a second later for each failure in a row, but at most `maxSetupFailures` (3) seconds later, and never sooner than a refusal's `Retry-After`. A run of failed setups ends only when a session airs its first clip; more clips on the session already on air don't end it. After `maxSetupFailures` that count, the playout fails and closes every session, unless a session still holds the air. An open refused with nothing allocated, such as with a 4xx, billed nothing: refused while a session holds the air, it counts neither then nor later, and it is asked again after its delay however often it is refused. Once enough that count have failed while a session holds the air, the playout airs on, opens nothing until that session ends, and tries once more, once the last failure's delay and `Retry-After` have passed.
 
-`edit([...])` applies several edits as one change: `Submit`, `SubmitGroup`, `Insert`, `Replace` and `Withdraw`, each tagged, such as an acknowledgement inserted after the playing clip together with a beat the event made wrong withdrawn, or a whole plan replaced by withdrawing what is queued and submitting the new line. Every edit is checked before any takes effect, so a refused edit fails the whole batch and admits nothing; a key may appear once per batch. The batch is make-before-break. What it withdraws keeps its clip as cover: it airs only when nothing else in its lane is Ready, so a clip the batch adds airs ahead of it as soon as that clip is Ready, and a Ready replacement airs in its place. Once every clip the batch adds is Ready or has settled, the batch takes effect: its withdrawals and replacements are requested together. A withdrawn item that nothing was built for yet goes at once, since it covers nothing. When a batch withdraws or replaces a clip that another pending batch adds, that batch also waits for this one's clips, so its cover stays until something replaces it. A replacement that has started takes its place at once, so the item it replaces never follows it. The handle has one result per edit, `Added`, `AddedGroup` or `Withdrawal` with its outcome, and `committed`, which resolves when the batch takes effect and fails if the scheduler closes first. A withdrawal of an item that aired as cover reports `already-started`. `WouldMissDeadline` for an added clip does not count what the batch withdraws or replaces.
+**Supervision.** `failure` completes with why the playout stopped: a session it could not open or keep, `InvalidFiller`, `Moderated`, or `Closed` when its scope closed. A defect that stopped it, such as a throwing `filler.clip`, is the defect `failure` dies with, and every defect the playout catches, in its plan, an open or a source, goes to Effect's `ErrorReporter`, a `Source` method that throws when called included. Whether that command applied is then unknown, and the playout goes on: an enqueue is never sent again, and a replacement takes over unless a read of the session's queues shows its clip within `unknownTimeout`; a `remove` is asked again once the session's queues change, and a `move` a second later; after a `setAutoplay` the session's autoplay is unknown, and the value the playout wants goes again, a second later if it is the one that died and at once if not, while that session is sent nothing else but, as it retires, the removal of its filler once its replacement has an item Ready; a `stop` or `play` ends its cut, and the cutter airs at the next boundary. A supervisor restarts a stopped playout by failing with its reason under a `Schedule`, which leaves a defect alone:
 
-Each lane can declare how it treats a new submission and whether it may cut. `conflict: "queue"`, the default, queues it behind the lane's waiting items. `conflict: "replace"` supersedes the lane's items still waiting, make-before-break: they stay only as cover until the new item is Ready, then settle `Dropped` as `replaced`, as for a status line where only the latest matters. `conflict: "skip"` refuses the submission with `LaneBusy` while the lane has an item waiting or playing. Inserts and replacements place themselves and are not affected. A lane with `cut: true` does not wait for a boundary: once one of its items is Ready at the front of its session, the scheduler cuts a playing clip of a strictly lower lane, or filler, unless that clip ends within a second; it never cuts a clip of its own lane. The engine's `cut(clipId)` stops the clip only if it is still playing; with autoplay on the provider then starts the next Ready clip, and the cut clip settles `Ended` with termination `stopped`. On H3 a cut is `stop`, which flushes to black or holds a frame until the next clip starts; whether that shows is unqualified on hosted H3, so an application that treats a held frame as a pause should leave cutting off. There is no parallel policy: a session plays one clip at a time.
+```ts
+import { Effect, Schedule } from "effect";
+import { Playout } from "reactor-effect-client";
 
-An item, group part, insert or replacement can carry up to 32 `cues`, secondary events such as an overlay, a caption or a browser action tied to its clip: each has a `name` and fires at an offset from the clip's observed start (`{ from: "start", offset }`) or back from its end (`{ from: "end", offset }`, measured from the provider's actual length). `scheduler.cues` publishes each `{ key, name, at }` once, within the scheduler's 100 ms turn of its time, while the clip plays. A cue that falls after a clip ended early, when it was cut, never fires, and a clip whose start was not observed fires none. A cue is a scheduling fact, not proof that the frame it names was presented.
+export const supervised = (options: Playout.Options) =>
+  Effect.gen(function* () {
+    const playout = yield* Playout.make(options);
+    // Submit the programme here; closing the scope closes the playout and its sessions.
+    return yield* Effect.flatMap(playout.failure, Effect.fail);
+  }).pipe(Effect.scoped, Effect.retry(Schedule.exponential("5 seconds")));
+```
 
-`asRun` is an unbounded per-item lifecycle stream: Accepted, Building, Ready, Started, Ended, Dropped, Failed, Unobserved or Unknown. The plan outlives a session: when renewal replaces a lost session, an item whose clip was queued, building or Ready there, and so never aired, is carried to the replacement and rebuilt under the same key, recorded as `Accepted` again with `carried: { sessionId }` for the lost session. An item whose clip is lost before it was built, with two sessions in a row, settles `Failed` instead. Reactor terminates a session given a flagged prompt, possibly after accepting the clip, so such a clip would end every session it was rebuilt on, each billed at least a minute. A clip that was built passed screening, and is rebuilt however often it is lost. A clip that was playing when its session was lost still settles `Failed`, since part of it aired, and an item whose enqueue outcome was unknown on the lost session still settles as terminal `Unknown`. Each item also has an `outcome` wait. `Started.durationSeconds` is the provider-observed duration. `Failed.reason` distinguishes `Clip` failure, `Command` refusal and `Scheduler` termination, retaining the original typed cause where available. `scheduler.failure` exposes the original terminal failure only after retained item waits, actor-owned control replies and `state.accepting = false` are committed, so a supervisor may immediately close its owner without stranding those waits. An owner closed from a handle wait or an `asRun` subscriber also finds each item's recorded evidence settled, not replaced, and evidence recorded before a terminal claim is on `asRun` before that claim's settlement and before `scheduler.failure` publishes. Typed termination retains terminal `Unknown` and already observed `Started`/`firstDecisive` evidence, and a withdrawal of an item already recorded `Dropped` replies `withdrawn`; unexpected defects or interruption preserve the original Cause. The signal does not wait for resumed callers or establish remote cleanup completion. Scope closure signals `Closed`, and pending or subsequent control calls fail with `SessionClosed`. `Started.at` and `Ended.at` are observed epoch times; elapsed airtime and deadline windows use Effect's monotonic clock. `Unobserved` means an acknowledged clip's start was not seen, including after observation overflow. `Unknown` means dispatch has no acknowledgment. A keyed clip observed later can still acquire its Ready or Started evidence. An absent queue snapshot cannot prove an unknown clip never played, so the scheduler never replays that key automatically. A replay would be safe only with proof that the provider never accepted the enqueue: a queue read the provider answered after processing it, which needs H3 to process commands in the order it receives them. Reactor does not document that ordering. Its runtime runs a model's command handlers between generation steps, and they may be asynchronous. Three prompt-only probes on hosted H3 found commands applied in the order sent, which does not cover an enqueue that uploads references. So an unknown key stays unknown; a clip lost with a replaced session is rebuilt because it was seen queued or Ready there and never started. The renewal engine fences each enqueue to its selected physical source before dispatch; an unknown outcome becomes terminal when that source retires without keyed proof. A custom engine that cannot fence its source retains uncertainty until keyed evidence or scheduler failure; the unknown-recovery deadline prevents indefinite scheduler service behind it. A withdrawal of that key fails with the original uncertain outcome unless a provider clip is found and removed. The scheduler carries an item key in library-owned provider metadata and leaves the app's request metadata untouched. As-run records provider evidence; an app that needs proof of presented or encoded output must gather that separately.
+**Moderation.** Reactor terminates a session given flagged content, and the verdict names no clip, category or request; hosted H3 sent it about a second after answering the enqueue. The playout blames the item whose enqueue was sent there last, settles it `Failed` with reason `Moderated` and never builds it again, and fails after `maxModerations` (2) moderated sessions rather than keep opening paid ones. A verdict need not come, so a clip lost unbuilt with two sessions in a row fails too; a clip that was built passed screening and is rebuilt however often it is lost.
 
-`Orchestration.Submission` models an inert prepared operation. Preparation may be interrupted before commit; once execution commits, callers joining or abandoning the result do not replay the dispatch. `CommandFailure.context` distinguishes `not-submitted`, `unknown`, and `replied` outcomes independently of the transport error category, and an engine command fails with `EngineError`, a `CommandFailure` or a local `PolicyFailure`.
+**On hosted H3.** `stop` names no clip and lands after its reply, so a cut is a step at a time: the playout turns autoplay off, stops the clip it cuts if that still plays, waits for H3 to report it ended, looks again, plays the cutter and restores autoplay. A cutter withdrawn meanwhile is removed instead of played. The stepped cut passed on hosted H3 (the 0.8.0 `show` run) with one `stop` and a 168 ms pause, with no dark frame. A continued build took 5.45 s against about 2.2 s for an independent 5 s clip, so the plan projects it and, when it would be late, continues from the clip that will be playing then. H3 falls back to an independent clip without saying so, so as-run never claims continuity. A `Started` event is a provider fact, not proof that a frame was presented or encoded.
 
-`Orchestration.Sequences` owns bounded sequence affinity and explicit member outcomes. Partial admission is represented member-by-member as accepted, rejected, or indeterminate, and a sequence remains bound to one owner until it is sealed/retired and explicitly released.
+## Testing with ReactorTest
 
-`reactor-effect-client/simulation` provides `make` and `layerSim` over the same orchestration engine and media contracts. Its source and renderer hooks support unpaid local execution and controlled failures. Reusable fault, image and audio fixtures (`pngBytes`, `wavBytes`) are available through the separate `reactor-effect-client/testing` entry point.
+`ReactorTest.layer({ timing })` provides the `HttpClient` and `PeerFactory` that `Coordinator.layer()` and `Reactor.layer()` need, backed by an in-memory coordinator and an H3 model that speaks the real wire protocol, so an application and every SDK layer above it run unchanged without a paid session. `layerCoordinator` is the HTTP API alone, with no host. Every delay is an `Effect.sleep` drawn from `timing`: `Timing.fixed` for a scenario that names the delays it depends on, `Timing.random({ seed })` for wide ranges that repeat for a seed, and `Timing.hosted` for the ranges paid runs measured, for demos. Under `TestClock`, fork `ReactorTest.flow()` into the test's scope and minutes of programme run in milliseconds; on the live clock it plays in real time.
 
-## Wire module
+`ReactorTest` keeps Reactor's documented rules and the facts paid runs observed: tokens bound to sessions, expiry and unbound tokens refused, the API key accepted as a bearer only to read and end sessions, several connections per session, `INACTIVE` for 30 seconds after the last one drops, five concurrent sessions and ten a minute refused with `429`, H3's request, reference and metadata limits, a `stop` that lands after its acknowledgement, moderation as observed and per-second billing. The `ReactorTest` service reports `sessions`, `billing` and a `log` of every command, message and request, and `inject` arms a `Fault`: a refused allocation, connect or reconnect, the last with a `Retry-After` if asked, a spent token that allocates again or answers with its session, a create reply that names no session or a create never answered, a dropped or late reply, a stalled or failed build, a disconnect or expiry, a cap Reactor ignores, a slow or ignored `DELETE`, a read that answers 404 for a session still running, black, frozen or absent video, no audio, an invalid image, an over-granting token, a late recording or a moderation verdict. `ReactorTest.pngBytes` and `wavBytes` make reference media H3's local checks accept, and `frameOf` names the clip a simulated frame belongs to. A session on `ReactorTest` reconnects a dropped connection on its own, as on Reactor; `Reactor.layer({ reconnect: false })` keeps a disconnect down.
 
-`reactor-effect-client/wire` is generated from the tracked canonical protocol sources under [`wire/`](./wire/README.md) by `wire/generate.py` (CPython 3.13, standard library only). `bun run generate:check` fails on any byte difference; `bun run generate:wire` rewrites the module. Do not format the generated file or edit it independently of its inputs.
+It models what H3 does, not hosted performance, billing, TURN relays or interop: those need the [hosted checks](https://github.com/mannyc2/reactor-effect-client/tree/main/integration/hosted).
 
 ## Declarations without DOM types
 
@@ -210,11 +172,11 @@ Effect `4.0.0-rc.117` itself references the global `TextDecoderOptions` type in
 
 ## Example
 
-[`examples/`](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/client/examples) is an application service written against the orchestration `Engine`, run and tested offline against the simulation on Effect's test clock: gap-free observation, retrying only what `isRetryable` allows, and never resending an enqueue whose outcome is `unknown`. The repository's [other examples](https://github.com/mannyc2/reactor-effect-client/tree/main/examples) include a server that broadcasts one renewing orchestration to many browsers.
+[`examples/`](https://github.com/mannyc2/reactor-effect-client/tree/main/packages/client/examples) is an application service written against `Playout`, run offline on `ReactorTest` and tested on Effect's test clock with faults standing in for a failed build and a lost reply. The repository's [other examples](https://github.com/mannyc2/reactor-effect-client/tree/main/examples) include a server that broadcasts one renewing playout to many browsers.
 
 ## Development
 
-This package is built and tested from the workspace root; see the repository [CONTRIBUTING](https://github.com/mannyc2/reactor-effect-client/blob/main/CONTRIBUTING.md). Inside `packages/client`, `bun run test` runs the portable suite under Vitest and `bun run typecheck` checks the source closure both with browser types and with Node types.
+This package is built and tested from the workspace root; see the repository [CONTRIBUTING](https://github.com/mannyc2/reactor-effect-client/blob/main/CONTRIBUTING.md). Inside `packages/client`, `bun run test` runs the portable suite under Vitest and `bun run typecheck` checks the source closure both with browser types and with Node types. The wire codec is generated from the protocol sources in [`wire/`](./wire/README.md).
 
 ## License