reactor-effect-client 0.2.0 → 0.3.0

package/dist/orchestration/types.d.ts

@@ -1,13 +1,16 @@
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
+import type * as Duration from "effect/Duration";
 import type * as Effect from "effect/Effect";
 import type * as Option from "effect/Option";
 import type * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
 import type * as Stream from "effect/Stream";
-import type { ReactorError } from "../errors.js";
+import type { ReactorError, ReactorFailure } from "../errors.js";
+import type { ObservationOptions } from "../observation.js";
 import type { Clip } from "../h3/messages.js";
-import type { CommandFailure } from "../session/commands.js";
-import type { CloseReport } from "../SessionTypes.js";
+import type { CommandFailure, PolicyFailure } from "../errors.js";
 import type { AudioFrame, VideoFrame, MediaPressure } from "../session/media.js";
 import type { Submission } from "../Submission.js";
 import type { Affinity } from "../Sequence.js";
@@ -131,7 +134,7 @@ export type EngineEvent = {
     readonly at: number;
 } | {
     readonly _tag: "SessionFailed";
-    readonly failure: ReactorError;
+    readonly failure: ReactorFailure;
 };
 export declare const EngineEvent: {
     readonly $is: <Tag extends "Building" | "Ended" | "Failed" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved">(tag: Tag) => (u: unknown) => u is Extract<{
@@ -180,7 +183,7 @@ export declare const EngineEvent: {
         readonly _tag: Tag;
     }> | Extract<{
         readonly _tag: "SessionFailed";
-        readonly failure: ReactorError;
+        readonly failure: ReactorFailure;
     }, {
         readonly _tag: Tag;
     }>;
@@ -221,7 +224,7 @@ export declare const EngineEvent: {
     }, "_tag">;
     readonly SessionFailed: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "SessionFailed";
-        readonly failure: ReactorError;
+        readonly failure: ReactorFailure;
     }, "_tag">;
     readonly Started: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "Started";
@@ -235,23 +238,66 @@ export declare const EngineEvent: {
     }, "_tag">;
 };
 export type RemoveOutcome = "unstarted" | "in_flight" | "generation" | "ready";
-export type EnqueueError = CommandFailure;
-export type CommandError = CommandFailure;
+/**
+ * What an orchestration command can fail with: a dispatched or undispatched
+ * command's `CommandFailure`, or a local `PolicyFailure` refusal. Both carry
+ * `context.outcome`, so a caller reads the dispatch evidence without narrowing.
+ */
+export type EngineError = CommandFailure | PolicyFailure;
+/**
+ * An engine's state and every event after it, with no gap between them: the
+ * subscription is acquired before the state is read. An event may repeat what
+ * `initial` already reflects, so apply events idempotently by `clipId`. The
+ * stream is bounded per observer like any observation; after an `Overflow`,
+ * observe again for a fresh state and subscription.
+ */
+export interface EngineObservation {
+    readonly initial: EngineState;
+    readonly events: Stream.Stream<EngineEvent, ReactorError>;
+}
+export type ObserveEngine = (options?: ObservationOptions) => Effect.Effect<EngineObservation, ReactorError, Scope.Scope>;
 export interface EngineShape {
-    readonly prepare: (request: ClipRequest) => Effect.Effect<Submission<ClipId, CommandFailure>, CommandFailure>;
-    readonly enqueue: (request: ClipRequest) => Effect.Effect<ClipId, CommandFailure>;
+    readonly prepare: (request: ClipRequest) => Effect.Effect<Submission<ClipId, EngineError>, EngineError>;
+    readonly enqueue: (request: ClipRequest) => Effect.Effect<ClipId, EngineError>;
     readonly state: Effect.Effect<EngineState>;
+    /** Later events only, subscribed when the stream runs; use `observe` to pair them with a state. */
     readonly events: Stream.Stream<EngineEvent, ReactorError>;
-    readonly failure: Effect.Effect<ReactorError>;
-    readonly setAutoplay: (enabled: boolean) => Effect.Effect<void, CommandFailure>;
-    readonly pauseAndStop: Effect.Effect<void, CommandFailure>;
-    readonly remove: (id: ClipId) => Effect.Effect<RemoveOutcome, CommandFailure>;
-    readonly move: (id: ClipId, position: number, queue: "generation" | "playout") => Effect.Effect<void, CommandFailure>;
-    readonly setCanvas: (canvas: Canvas) => Effect.Effect<void, CommandFailure>;
+    readonly observe: ObserveEngine;
+    /**
+     * The terminal failure, as it was raised: a session's `ReactorError`, a
+     * replacement's `AcquisitionFailure` with its cleanup, or the failed command.
+     */
+    readonly failure: Effect.Effect<ReactorFailure>;
+    readonly setAutoplay: (enabled: boolean) => Effect.Effect<void, EngineError>;
+    readonly pauseAndStop: Effect.Effect<void, EngineError>;
+    readonly remove: (id: ClipId) => Effect.Effect<RemoveOutcome, EngineError>;
+    readonly move: (id: ClipId, position: number, queue: "generation" | "playout") => Effect.Effect<void, EngineError>;
+    readonly setCanvas: (canvas: Canvas) => Effect.Effect<void, EngineError>;
 }
+/**
+ * An orchestration's recovering media output, one logical track per kind that
+ * continues across reconnects and source replacements, and ends with the
+ * orchestration's terminal failure.
+ *
+ * - Consumption is mandatory: while it runs, the orchestration buffers what the
+ *   reader has not taken (by default 96 video frames and 192,000 audio
+ *   samples; see `maxQueuedVideoFrames` and `maxQueuedAudioSamples`), and an
+ *   output that stays undrained past that fails the orchestration with
+ *   `Overflow`. That failure is terminal.
+ * - Each output has one reader at a time. A second concurrent reader fails
+ *   with `AlreadyReading` rather than silently splitting the frames; a reader
+ *   that ends releases the output, and a later reader resumes from what is
+ *   retained. A preview that wants only the newest frame derives it per
+ *   consumer with `Stream.buffer({ capacity: 1, strategy: "sliding" })`.
+ * - `pressure` reports the loss of the logical output: `droppedVideo`,
+ *   `droppedAudio` and `readerOverflows` accumulate across generations and
+ *   across source replacements, counting each source only while it fed this
+ *   output. A total that cannot be read fails `pressure` with `InvalidState`
+ *   rather than reporting zero.
+ */
 export interface MediaShape {
-    readonly video: Stream.Stream<VideoFrame, ReactorError>;
-    readonly audio: Stream.Stream<AudioFrame, ReactorError>;
+    readonly video: Stream.Stream<VideoFrame, ReactorFailure>;
+    readonly audio: Stream.Stream<AudioFrame, ReactorFailure>;
     readonly pressure: Effect.Effect<MediaPressure, ReactorError>;
     readonly videoFramesPerSecond: number;
 }
@@ -262,27 +308,531 @@ export type MediaState = {
 } | {
     readonly _tag: "Recovering";
     readonly sessionId: string;
-    readonly cause: ReactorError;
+    readonly cause: ReactorFailure;
 } | {
     readonly _tag: "Failed";
-    readonly cause: ReactorError;
+    readonly cause: ReactorFailure;
 } | {
     readonly _tag: "Closed";
 };
-export interface MediaSource extends MediaShape {
+export interface MediaTail {
+    readonly video: {
+        readonly framesPerSecond: number;
+        readonly expectedFrames: number;
+        readonly receivedFrames: number;
+        readonly status: "not-started" | "count-complete" | "incomplete";
+    };
+    readonly audio: {
+        readonly receivedSamples: number;
+        readonly status: "unverified";
+    };
+    readonly sourceDrops: {
+        readonly video: bigint | null;
+        readonly audio: bigint | null;
+    };
+    readonly forwarded: {
+        readonly queuedVideoFrames: number;
+        readonly queuedAudioSamples: number;
+    };
+}
+export type Renewal = {
+    readonly _tag: "Opened";
+    readonly sessionId: string;
+    readonly lifetime: Duration.Duration;
+} | {
+    readonly _tag: "Prepared";
+} | {
+    readonly _tag: "SetupFailed";
+    readonly reason: string;
+    readonly consecutive: number;
+} | {
+    readonly _tag: "Recovering";
+    readonly sessionId: string;
+    readonly reason: string;
+} | {
+    readonly _tag: "Reconnected";
+    readonly sessionId: string;
+    readonly generation: bigint;
+} | {
+    readonly _tag: "Switched";
+    readonly sessionId: string;
+    readonly ageSeconds: number;
+    readonly tail: MediaTail;
+} | {
+    readonly _tag: "Replaced";
+    readonly reason: string;
+    readonly lostClips: number;
+    readonly sessionId: string;
+    readonly ageSeconds: number;
+    readonly tail: MediaTail;
+} | {
+    readonly _tag: "Failed";
+    readonly reason: string;
+};
+/**
+ * One handle's observation, in the order its changes happened: engine events,
+ * renewal events and media-state transitions from a single stream, so a
+ * `Replaced` follows the `Failed` events of the clips it lost and no media
+ * state arrives out of order.
+ */
+export type HandleEvent = {
+    readonly _tag: "Engine";
+    readonly event: EngineEvent;
+} | {
+    readonly _tag: "Renewal";
+    readonly event: Renewal;
+} | {
+    readonly _tag: "Media";
+    readonly state: MediaState;
+};
+/**
+ * The handle's current engine and media state, and every handle event after
+ * it. The subscription is acquired before the state is read, so no event falls
+ * between them; an event may repeat what `initial` already reflects.
+ */
+export interface HandleObservation {
+    readonly initial: {
+        readonly engine: EngineState;
+        readonly media: MediaState;
+    };
+    readonly events: Stream.Stream<HandleEvent, ReactorError>;
+}
+export interface MediaSource {
+    readonly video: Stream.Stream<VideoFrame, ReactorError>;
+    readonly audio: Stream.Stream<AudioFrame, ReactorError>;
+    readonly pressure: Effect.Effect<MediaPressure, ReactorError>;
+    readonly videoFramesPerSecond: number;
     readonly generation: bigint;
 }
-export interface PolicyCleanup {
-    readonly operation: string;
-    readonly result: Result.Result<void, CommandFailure>;
+export declare const PolicyCleanup: Schema.Struct<{
+    readonly operation: Schema.String;
+    readonly result: Schema.Result<Schema.Void, Schema.Union<readonly [Schema.decodeTo<Schema.declare<CommandFailure, CommandFailure>, Schema.Codec<{
+        readonly _tag: "CommandFailure";
+        readonly message: string;
+        readonly reason: {
+            readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+            readonly message: string;
+        } | {
+            readonly _tag: "Http";
+            readonly message: string;
+            readonly status?: number;
+            readonly retryAfterMillis?: number;
+        } | {
+            readonly _tag: "RecorderDisabled" | "Remote";
+            readonly message: string;
+            readonly remoteCode?: string;
+        } | {
+            readonly _tag: "Native";
+            readonly message: string;
+            readonly status?: number;
+        } | {
+            readonly _tag: "IceFailed";
+            readonly message: string;
+            readonly pairs: number;
+            readonly candidateTypes: readonly string[];
+        } | {
+            readonly _tag: "TransportFailed";
+            readonly message: string;
+            readonly pairs: number;
+        } | {
+            readonly _tag: "ClipEnded";
+            readonly message: string;
+            readonly clipId: string;
+            readonly lifecycle: "clip_failed" | "clip_popped";
+            readonly transportGeneration: string;
+        };
+        readonly context: {
+            readonly operation?: string;
+            readonly requestId?: string;
+            readonly sessionId?: string;
+            readonly generation?: string;
+            readonly outcome?: "not-submitted" | "replied" | "unknown";
+        };
+    }, unknown, never, never>, never, never>, Schema.decodeTo<Schema.declare<PolicyFailure, PolicyFailure>, Schema.Codec<{
+        readonly _tag: "PolicyFailure";
+        readonly message: string;
+        readonly reason: {
+            readonly _tag: "AnchorUnavailable" | "AnnotationCapacity" | "Busy" | "ContinuationUnavailable" | "IdentityExhausted" | "InvalidRequest" | "NotFound" | "OwnerConflict" | "PositionConflict" | "QueueChanged" | "QueueFull" | "RouteChanged" | "SessionClosed" | "SessionRecovering" | "SessionRetired" | "SubmissionCapacity";
+            readonly message: string;
+        } | {
+            readonly _tag: "Missing";
+            readonly message: string;
+            readonly purpose: "anchor" | "continuation" | "session_anchor";
+        } | {
+            readonly _tag: "Sequence";
+            readonly message: string;
+            readonly sequenceId: string;
+            readonly code: "capacity" | "indeterminate" | "member-capacity" | "member-duplicate" | "member-missing" | "missing" | "not-releasable" | "owner-mismatch" | "retired" | "sealed" | "sealing";
+        };
+        readonly context: {
+            readonly operation?: string;
+            readonly requestId?: string;
+            readonly sessionId?: string;
+            readonly generation?: string;
+            readonly outcome?: "not-submitted" | "replied" | "unknown";
+        };
+    }, unknown, never, never>, never, never>]>>;
+}>;
+export interface PolicyCleanup extends Schema.Schema.Type<typeof PolicyCleanup> {
 }
-export interface SourceCleanup {
+export declare const SourceCleanup: Schema.Struct<{
     /** The unmodified lifecycle owner's canonical cleanup evidence. */
-    readonly lease: CloseReport;
-    readonly policy: readonly PolicyCleanup[];
+    readonly lease: Schema.Struct<{
+        readonly localClosed: Schema.Boolean;
+        readonly allocation: Schema.Literals<readonly ["none", "known", "unknown"]>;
+        readonly ownership: Schema.optionalKey<Schema.Literals<readonly ["owned", "attached"]>>;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
+        readonly remote: Schema.Struct<{
+            readonly attempted: Schema.Boolean;
+            readonly responseReceived: Schema.Boolean;
+            readonly confirmed: Schema.Boolean;
+            readonly evidence: Schema.NullOr<Schema.Literals<readonly ["absent", "terminal"]>>;
+            readonly deleteStatus: Schema.NullOr<Schema.Int>;
+            readonly state: Schema.NullOr<Schema.String>;
+            readonly error: Schema.optionalKey<Schema.decodeTo<Schema.declare<ReactorError, ReactorError>, Schema.Codec<{
+                readonly _tag: "ReactorError";
+                readonly message: string;
+                readonly reason: {
+                    readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                    readonly message: string;
+                } | {
+                    readonly _tag: "Http";
+                    readonly message: string;
+                    readonly status?: number;
+                    readonly retryAfterMillis?: number;
+                } | {
+                    readonly _tag: "RecorderDisabled" | "Remote";
+                    readonly message: string;
+                    readonly remoteCode?: string;
+                } | {
+                    readonly _tag: "Native";
+                    readonly message: string;
+                    readonly status?: number;
+                } | {
+                    readonly _tag: "IceFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                    readonly candidateTypes: readonly string[];
+                } | {
+                    readonly _tag: "TransportFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                } | {
+                    readonly _tag: "ClipEnded";
+                    readonly message: string;
+                    readonly clipId: string;
+                    readonly lifecycle: "clip_failed" | "clip_popped";
+                    readonly transportGeneration: string;
+                };
+                readonly context: {
+                    readonly operation?: string;
+                    readonly requestId?: string;
+                    readonly sessionId?: string;
+                    readonly generation?: string;
+                    readonly outcome?: "not-submitted" | "replied" | "unknown";
+                };
+            }, unknown, never, never>, never, never>>;
+        }>;
+        readonly unpublishSubmitted: Schema.$Array<Schema.String>;
+        readonly unresolvedPublications: Schema.$Array<Schema.String>;
+        readonly localErrors: Schema.$Array<Schema.decodeTo<Schema.declare<ReactorError, ReactorError>, Schema.Codec<{
+            readonly _tag: "ReactorError";
+            readonly message: string;
+            readonly reason: {
+                readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                readonly message: string;
+            } | {
+                readonly _tag: "Http";
+                readonly message: string;
+                readonly status?: number;
+                readonly retryAfterMillis?: number;
+            } | {
+                readonly _tag: "RecorderDisabled" | "Remote";
+                readonly message: string;
+                readonly remoteCode?: string;
+            } | {
+                readonly _tag: "Native";
+                readonly message: string;
+                readonly status?: number;
+            } | {
+                readonly _tag: "IceFailed";
+                readonly message: string;
+                readonly pairs: number;
+                readonly candidateTypes: readonly string[];
+            } | {
+                readonly _tag: "TransportFailed";
+                readonly message: string;
+                readonly pairs: number;
+            } | {
+                readonly _tag: "ClipEnded";
+                readonly message: string;
+                readonly clipId: string;
+                readonly lifecycle: "clip_failed" | "clip_popped";
+                readonly transportGeneration: string;
+            };
+            readonly context: {
+                readonly operation?: string;
+                readonly requestId?: string;
+                readonly sessionId?: string;
+                readonly generation?: string;
+                readonly outcome?: "not-submitted" | "replied" | "unknown";
+            };
+        }, unknown, never, never>, never, never>>;
+    }>;
+    readonly policy: Schema.$Array<Schema.Struct<{
+        readonly operation: Schema.String;
+        readonly result: Schema.Result<Schema.Void, Schema.Union<readonly [Schema.decodeTo<Schema.declare<CommandFailure, CommandFailure>, Schema.Codec<{
+            readonly _tag: "CommandFailure";
+            readonly message: string;
+            readonly reason: {
+                readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                readonly message: string;
+            } | {
+                readonly _tag: "Http";
+                readonly message: string;
+                readonly status?: number;
+                readonly retryAfterMillis?: number;
+            } | {
+                readonly _tag: "RecorderDisabled" | "Remote";
+                readonly message: string;
+                readonly remoteCode?: string;
+            } | {
+                readonly _tag: "Native";
+                readonly message: string;
+                readonly status?: number;
+            } | {
+                readonly _tag: "IceFailed";
+                readonly message: string;
+                readonly pairs: number;
+                readonly candidateTypes: readonly string[];
+            } | {
+                readonly _tag: "TransportFailed";
+                readonly message: string;
+                readonly pairs: number;
+            } | {
+                readonly _tag: "ClipEnded";
+                readonly message: string;
+                readonly clipId: string;
+                readonly lifecycle: "clip_failed" | "clip_popped";
+                readonly transportGeneration: string;
+            };
+            readonly context: {
+                readonly operation?: string;
+                readonly requestId?: string;
+                readonly sessionId?: string;
+                readonly generation?: string;
+                readonly outcome?: "not-submitted" | "replied" | "unknown";
+            };
+        }, unknown, never, never>, never, never>, Schema.decodeTo<Schema.declare<PolicyFailure, PolicyFailure>, Schema.Codec<{
+            readonly _tag: "PolicyFailure";
+            readonly message: string;
+            readonly reason: {
+                readonly _tag: "AnchorUnavailable" | "AnnotationCapacity" | "Busy" | "ContinuationUnavailable" | "IdentityExhausted" | "InvalidRequest" | "NotFound" | "OwnerConflict" | "PositionConflict" | "QueueChanged" | "QueueFull" | "RouteChanged" | "SessionClosed" | "SessionRecovering" | "SessionRetired" | "SubmissionCapacity";
+                readonly message: string;
+            } | {
+                readonly _tag: "Missing";
+                readonly message: string;
+                readonly purpose: "anchor" | "continuation" | "session_anchor";
+            } | {
+                readonly _tag: "Sequence";
+                readonly message: string;
+                readonly sequenceId: string;
+                readonly code: "capacity" | "indeterminate" | "member-capacity" | "member-duplicate" | "member-missing" | "missing" | "not-releasable" | "owner-mismatch" | "retired" | "sealed" | "sealing";
+            };
+            readonly context: {
+                readonly operation?: string;
+                readonly requestId?: string;
+                readonly sessionId?: string;
+                readonly generation?: string;
+                readonly outcome?: "not-submitted" | "replied" | "unknown";
+            };
+        }, unknown, never, never>, never, never>]>>;
+    }>>;
+}>;
+export interface SourceCleanup extends Schema.Schema.Type<typeof SourceCleanup> {
 }
-export interface CleanupReport {
-    readonly sessions: readonly SourceCleanup[];
+/**
+ * An orchestration's cleanup evidence. As a Schema it encodes for persistence
+ * (`Schema.toCodecJson(CleanupReport)` for JSON); its failures encode as
+ * diagnostic JSON, without provider text.
+ */
+export declare const CleanupReport: Schema.Struct<{
+    readonly sessions: Schema.$Array<Schema.Struct<{
+        /** The unmodified lifecycle owner's canonical cleanup evidence. */
+        readonly lease: Schema.Struct<{
+            readonly localClosed: Schema.Boolean;
+            readonly allocation: Schema.Literals<readonly ["none", "known", "unknown"]>;
+            readonly ownership: Schema.optionalKey<Schema.Literals<readonly ["owned", "attached"]>>;
+            readonly sessionId: Schema.optionalKey<Schema.String>;
+            readonly remote: Schema.Struct<{
+                readonly attempted: Schema.Boolean;
+                readonly responseReceived: Schema.Boolean;
+                readonly confirmed: Schema.Boolean;
+                readonly evidence: Schema.NullOr<Schema.Literals<readonly ["absent", "terminal"]>>;
+                readonly deleteStatus: Schema.NullOr<Schema.Int>;
+                readonly state: Schema.NullOr<Schema.String>;
+                readonly error: Schema.optionalKey<Schema.decodeTo<Schema.declare<ReactorError, ReactorError>, Schema.Codec<{
+                    readonly _tag: "ReactorError";
+                    readonly message: string;
+                    readonly reason: {
+                        readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                        readonly message: string;
+                    } | {
+                        readonly _tag: "Http";
+                        readonly message: string;
+                        readonly status?: number;
+                        readonly retryAfterMillis?: number;
+                    } | {
+                        readonly _tag: "RecorderDisabled" | "Remote";
+                        readonly message: string;
+                        readonly remoteCode?: string;
+                    } | {
+                        readonly _tag: "Native";
+                        readonly message: string;
+                        readonly status?: number;
+                    } | {
+                        readonly _tag: "IceFailed";
+                        readonly message: string;
+                        readonly pairs: number;
+                        readonly candidateTypes: readonly string[];
+                    } | {
+                        readonly _tag: "TransportFailed";
+                        readonly message: string;
+                        readonly pairs: number;
+                    } | {
+                        readonly _tag: "ClipEnded";
+                        readonly message: string;
+                        readonly clipId: string;
+                        readonly lifecycle: "clip_failed" | "clip_popped";
+                        readonly transportGeneration: string;
+                    };
+                    readonly context: {
+                        readonly operation?: string;
+                        readonly requestId?: string;
+                        readonly sessionId?: string;
+                        readonly generation?: string;
+                        readonly outcome?: "not-submitted" | "replied" | "unknown";
+                    };
+                }, unknown, never, never>, never, never>>;
+            }>;
+            readonly unpublishSubmitted: Schema.$Array<Schema.String>;
+            readonly unresolvedPublications: Schema.$Array<Schema.String>;
+            readonly localErrors: Schema.$Array<Schema.decodeTo<Schema.declare<ReactorError, ReactorError>, Schema.Codec<{
+                readonly _tag: "ReactorError";
+                readonly message: string;
+                readonly reason: {
+                    readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                    readonly message: string;
+                } | {
+                    readonly _tag: "Http";
+                    readonly message: string;
+                    readonly status?: number;
+                    readonly retryAfterMillis?: number;
+                } | {
+                    readonly _tag: "RecorderDisabled" | "Remote";
+                    readonly message: string;
+                    readonly remoteCode?: string;
+                } | {
+                    readonly _tag: "Native";
+                    readonly message: string;
+                    readonly status?: number;
+                } | {
+                    readonly _tag: "IceFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                    readonly candidateTypes: readonly string[];
+                } | {
+                    readonly _tag: "TransportFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                } | {
+                    readonly _tag: "ClipEnded";
+                    readonly message: string;
+                    readonly clipId: string;
+                    readonly lifecycle: "clip_failed" | "clip_popped";
+                    readonly transportGeneration: string;
+                };
+                readonly context: {
+                    readonly operation?: string;
+                    readonly requestId?: string;
+                    readonly sessionId?: string;
+                    readonly generation?: string;
+                    readonly outcome?: "not-submitted" | "replied" | "unknown";
+                };
+            }, unknown, never, never>, never, never>>;
+        }>;
+        readonly policy: Schema.$Array<Schema.Struct<{
+            readonly operation: Schema.String;
+            readonly result: Schema.Result<Schema.Void, Schema.Union<readonly [Schema.decodeTo<Schema.declare<CommandFailure, CommandFailure>, Schema.Codec<{
+                readonly _tag: "CommandFailure";
+                readonly message: string;
+                readonly reason: {
+                    readonly _tag: "Aborted" | "AlreadyReading" | "ChannelClosed" | "Closed" | "Disconnected" | "Indeterminate" | "InvalidInput" | "InvalidState" | "Overflow" | "Protocol" | "SdpRejected" | "Shutdown" | "TerminalSession" | "Timeout" | "UnexpectedReply" | "UnsupportedCapability" | "UnsupportedHost" | "Upload" | "VersionMismatch";
+                    readonly message: string;
+                } | {
+                    readonly _tag: "Http";
+                    readonly message: string;
+                    readonly status?: number;
+                    readonly retryAfterMillis?: number;
+                } | {
+                    readonly _tag: "RecorderDisabled" | "Remote";
+                    readonly message: string;
+                    readonly remoteCode?: string;
+                } | {
+                    readonly _tag: "Native";
+                    readonly message: string;
+                    readonly status?: number;
+                } | {
+                    readonly _tag: "IceFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                    readonly candidateTypes: readonly string[];
+                } | {
+                    readonly _tag: "TransportFailed";
+                    readonly message: string;
+                    readonly pairs: number;
+                } | {
+                    readonly _tag: "ClipEnded";
+                    readonly message: string;
+                    readonly clipId: string;
+                    readonly lifecycle: "clip_failed" | "clip_popped";
+                    readonly transportGeneration: string;
+                };
+                readonly context: {
+                    readonly operation?: string;
+                    readonly requestId?: string;
+                    readonly sessionId?: string;
+                    readonly generation?: string;
+                    readonly outcome?: "not-submitted" | "replied" | "unknown";
+                };
+            }, unknown, never, never>, never, never>, Schema.decodeTo<Schema.declare<PolicyFailure, PolicyFailure>, Schema.Codec<{
+                readonly _tag: "PolicyFailure";
+                readonly message: string;
+                readonly reason: {
+                    readonly _tag: "AnchorUnavailable" | "AnnotationCapacity" | "Busy" | "ContinuationUnavailable" | "IdentityExhausted" | "InvalidRequest" | "NotFound" | "OwnerConflict" | "PositionConflict" | "QueueChanged" | "QueueFull" | "RouteChanged" | "SessionClosed" | "SessionRecovering" | "SessionRetired" | "SubmissionCapacity";
+                    readonly message: string;
+                } | {
+                    readonly _tag: "Missing";
+                    readonly message: string;
+                    readonly purpose: "anchor" | "continuation" | "session_anchor";
+                } | {
+                    readonly _tag: "Sequence";
+                    readonly message: string;
+                    readonly sequenceId: string;
+                    readonly code: "capacity" | "indeterminate" | "member-capacity" | "member-duplicate" | "member-missing" | "missing" | "not-releasable" | "owner-mismatch" | "retired" | "sealed" | "sealing";
+                };
+                readonly context: {
+                    readonly operation?: string;
+                    readonly requestId?: string;
+                    readonly sessionId?: string;
+                    readonly generation?: string;
+                    readonly outcome?: "not-submitted" | "replied" | "unknown";
+                };
+            }, unknown, never, never>, never, never>]>>;
+        }>>;
+    }>>;
+}>;
+export interface CleanupReport extends Schema.Schema.Type<typeof CleanupReport> {
 }
 /** Resolved by the one router; the full request remains a local annotation. */
 export interface RoutedRequest {
@@ -290,8 +840,8 @@ export interface RoutedRequest {
     readonly position: number | undefined;
 }
 export interface EnqueueHooks {
-    readonly commit?: (submissionId: string) => Effect.Effect<void, CommandFailure>;
-    readonly result?: (submissionId: string, result: Result.Result<ClipId, CommandFailure>) => Effect.Effect<void>;
+    readonly commit?: (submissionId: string) => Effect.Effect<void, EngineError>;
+    readonly result?: (submissionId: string, result: Result.Result<ClipId, EngineError>) => Effect.Effect<void>;
 }
 /**
  * One physical provider view or an explicit production simulator. It owns no
@@ -301,21 +851,24 @@ export interface Source {
     readonly id: string;
     readonly state: Effect.Effect<EngineState>;
     readonly events: Stream.Stream<EngineEvent, ReactorError>;
-    readonly prepareRouted: (request: RoutedRequest, hooks?: EnqueueHooks) => Effect.Effect<Submission<ClipId, CommandFailure>, CommandFailure>;
+    readonly observe: ObserveEngine;
+    readonly prepareRouted: (request: RoutedRequest, hooks?: EnqueueHooks) => Effect.Effect<Submission<ClipId, EngineError>, EngineError>;
     readonly media: Effect.Effect<MediaSource, ReactorError>;
-    readonly reconnect: Effect.Effect<void, ReactorError>;
-    readonly refresh: Effect.Effect<void, CommandFailure>;
-    readonly setAutoplay: (enabled: boolean) => Effect.Effect<void, CommandFailure>;
-    readonly stop: Effect.Effect<void, CommandFailure>;
-    readonly remove: (id: ClipId) => Effect.Effect<RemoveOutcome, CommandFailure>;
-    readonly move: (id: ClipId, position: number) => Effect.Effect<void, CommandFailure>;
-    readonly setCanvas: (canvas: Canvas) => Effect.Effect<void, CommandFailure>;
+    readonly reconnect: Effect.Effect<void, ReactorError | CommandFailure>;
+    readonly refresh: Effect.Effect<void, EngineError>;
+    readonly setAutoplay: (enabled: boolean) => Effect.Effect<void, EngineError>;
+    readonly stop: Effect.Effect<void, EngineError>;
+    readonly remove: (id: ClipId) => Effect.Effect<RemoveOutcome, EngineError>;
+    readonly move: (id: ClipId, position: number) => Effect.Effect<void, EngineError>;
+    readonly setCanvas: (canvas: Canvas) => Effect.Effect<void, EngineError>;
     readonly close: Effect.Effect<SourceCleanup>;
 }
 export interface HandleShape {
     readonly engine: EngineShape;
     readonly media: MediaShape;
     readonly mediaState: Effect.Effect<MediaState>;
+    /** Engine, renewal and media changes in one ordered stream, after the current state. */
+    readonly observe: (options?: ObservationOptions) => Effect.Effect<HandleObservation, ReactorError, Scope.Scope>;
     readonly sessionId: Effect.Effect<Option.Option<string>>;
     readonly close: Effect.Effect<CleanupReport>;
     readonly cleanup: Effect.Effect<Option.Option<CleanupReport>>;
@@ -330,5 +883,7 @@ export declare class Media extends Media_base {
 declare const Handle_base: Context.ServiceClass<Handle, "reactor-effect-client/Orchestration/Handle", HandleShape>;
 export declare class Handle extends Handle_base {
 }
+/** The three services of one handle, so its facets can never come from two orchestrations. */
+export declare const handleContext: (handle: HandleShape) => Context.Context<Engine | Media | Handle>;
 export {};
 //# sourceMappingURL=types.d.ts.map