reactor-effect-client 0.4.0 → 0.6.0

package/dist/orchestration/types.d.ts

@@ -3,7 +3,7 @@ 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 Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import type * as Stream from "effect/Stream";
@@ -67,6 +67,8 @@ export declare const BuildTiming: {
 /** A provider clip is visible even when this application never submitted it. */
 export interface ClipRecord {
     readonly clipId: ClipId;
+    /** Physical session that owns this clip, including during a renewal overlap. */
+    readonly sessionId: string;
     readonly durationSeconds: number;
     readonly provider: Clip;
     readonly request?: ClipRequest;
@@ -91,9 +93,26 @@ export interface Playback {
      * monotonic clock instead.
      */
     readonly startedAt: Option.Option<number>;
+    /** Monotonic start observation, available only when this process saw Started. */
+    readonly startedAtMonotonicMillis?: number;
 }
 export interface EngineState {
     readonly availability: "Ready" | "Synchronizing" | "Unavailable";
+    /** Every live physical source, including one with no clips yet. */
+    readonly sessions: readonly {
+        readonly sessionId: string;
+        readonly availability: EngineState["availability"];
+    }[];
+    /** The source that receives an unconstrained new request. */
+    readonly preferredSessionId: Option.Option<string>;
+    /** The source draining ahead of a ready replacement, if there is one. */
+    readonly retiringSessionId: Option.Option<string>;
+    /**
+     * The retiring source can hand off once idle: no sequence holds it
+     * preferred, it is not recovering, and its media cannot hold the switch past
+     * the final clip's grace. Absent on physical sources.
+     */
+    readonly handoffReady?: boolean;
     readonly queued: readonly ClipRecord[];
     /** Provider queue order, including an independently observed active build. */
     readonly generationOrder: readonly ClipId[];
@@ -132,10 +151,15 @@ export type EngineEvent = {
     readonly durationSeconds: number;
     /** Epoch milliseconds of the local observation, as every event's `at` is. */
     readonly at: number;
+    /** Monotonic instant captured with `at`, for elapsed as-run accounting. */
+    readonly atMonotonicMillis?: number;
 } | {
     readonly _tag: "Ended";
     readonly clipId: ClipId;
     readonly termination: "finished" | "stopped";
+    /** Local observation time of the end, when the source provides it. */
+    readonly at?: number;
+    readonly atMonotonicMillis?: number;
 } | {
     readonly _tag: "Failed";
     readonly clipId: ClipId;
@@ -144,12 +168,21 @@ export type EngineEvent = {
 } | {
     readonly _tag: "Starved";
     readonly at: number;
+}
+/**
+ * The retiring source's final clip arrived in full while a replacement is
+ * Ready. An observation only: a short clip still switches once its grace
+ * past Ended elapses, without this event.
+ */
+ | {
+    readonly _tag: "HandoffReady";
+    readonly sessionId: string;
 } | {
     readonly _tag: "SessionFailed";
     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<{
+    readonly $is: <Tag extends "Building" | "Ended" | "Failed" | "HandoffReady" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved">(tag: Tag) => (u: unknown) => u is Extract<{
         readonly _tag: "Queued";
         readonly clipId: ClipId;
         readonly durationSeconds: number;
@@ -174,12 +207,17 @@ export declare const EngineEvent: {
         readonly durationSeconds: number;
         /** Epoch milliseconds of the local observation, as every event's `at` is. */
         readonly at: number;
+        /** Monotonic instant captured with `at`, for elapsed as-run accounting. */
+        readonly atMonotonicMillis?: number;
     }, {
         readonly _tag: Tag;
     }> | Extract<{
         readonly _tag: "Ended";
         readonly clipId: ClipId;
         readonly termination: "finished" | "stopped";
+        /** Local observation time of the end, when the source provides it. */
+        readonly at?: number;
+        readonly atMonotonicMillis?: number;
     }, {
         readonly _tag: Tag;
     }> | Extract<{
@@ -194,6 +232,11 @@ export declare const EngineEvent: {
         readonly at: number;
     }, {
         readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "HandoffReady";
+        readonly sessionId: string;
+    }, {
+        readonly _tag: Tag;
     }> | Extract<{
         readonly _tag: "SessionFailed";
         readonly failure: ReactorFailure;
@@ -201,12 +244,12 @@ export declare const EngineEvent: {
         readonly _tag: Tag;
     }>;
     readonly $match: {
-        <Cases extends { readonly [Tag in "Building" | "Ended" | "Failed" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]: (args: Extract<EngineEvent, {
+        <Cases extends { readonly [Tag in "Building" | "Ended" | "Failed" | "HandoffReady" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]: (args: Extract<EngineEvent, {
             readonly _tag: Tag;
-        }>) => any; }>(cases: Cases): (value: EngineEvent) => import("effect/Unify").Unify<ReturnType<Cases["Building" | "Ended" | "Failed" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]>>;
-        <Cases extends { readonly [Tag in "Building" | "Ended" | "Failed" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]: (args: Extract<EngineEvent, {
+        }>) => any; }>(cases: Cases): (value: EngineEvent) => import("effect/Unify").Unify<ReturnType<Cases["Building" | "Ended" | "Failed" | "HandoffReady" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]>>;
+        <Cases extends { readonly [Tag in "Building" | "Ended" | "Failed" | "HandoffReady" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]: (args: Extract<EngineEvent, {
             readonly _tag: Tag;
-        }>) => any; }>(value: EngineEvent, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Building" | "Ended" | "Failed" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]>>;
+        }>) => any; }>(value: EngineEvent, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Building" | "Ended" | "Failed" | "HandoffReady" | "Queued" | "Ready" | "SessionFailed" | "Started" | "Starved"]>>;
     };
     readonly Building: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "Building";
@@ -217,6 +260,9 @@ export declare const EngineEvent: {
         readonly _tag: "Ended";
         readonly clipId: ClipId;
         readonly termination: "finished" | "stopped";
+        /** Local observation time of the end, when the source provides it. */
+        readonly at?: number;
+        readonly atMonotonicMillis?: number;
     }, "_tag">;
     readonly Failed: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "Failed";
@@ -224,6 +270,10 @@ export declare const EngineEvent: {
         readonly reason: string;
         readonly sessionId?: string;
     }, "_tag">;
+    readonly HandoffReady: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "HandoffReady";
+        readonly sessionId: string;
+    }, "_tag">;
     readonly Queued: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "Queued";
         readonly clipId: ClipId;
@@ -245,6 +295,8 @@ export declare const EngineEvent: {
         readonly durationSeconds: number;
         /** Epoch milliseconds of the local observation, as every event's `at` is. */
         readonly at: number;
+        /** Monotonic instant captured with `at`, for elapsed as-run accounting. */
+        readonly atMonotonicMillis?: number;
     }, "_tag">;
     readonly Starved: Data.TaggedEnum.ConstructorFrom<{
         readonly _tag: "Starved";
@@ -273,6 +325,12 @@ export type ObserveEngine = (options?: ObservationOptions) => Effect.Effect<Engi
 export interface EngineShape {
     readonly prepare: (request: ClipRequest) => Effect.Effect<Submission<ClipId, EngineError>, EngineError>;
     readonly enqueue: (request: ClipRequest) => Effect.Effect<ClipId, EngineError>;
+    /** Refuse before dispatch if routing would select another physical source. */
+    readonly enqueueOnSource?: ((request: ClipRequest, expectedSessionId: string) => Effect.Effect<ClipId, EngineError>) | undefined;
+    /**
+     * The current state. After an owned renewal worker's defect or unexpected
+     * interruption, it fails with that worker's Cause until close begins.
+     */
     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>;
@@ -280,11 +338,18 @@ export interface EngineShape {
     /**
      * The terminal failure, as it was raised: a session's `ReactorError`, a
      * replacement's `AcquisitionFailure` with its cleanup, or the failed command.
+     * An owned renewal worker's defect or unexpected interruption fails this
+     * effect and observations with the original Cause instead of a typed error.
+     * A waiter that must act on either, such as one that closes the handle,
+     * handles the whole Cause (`Effect.catchCause`), not only this value.
      */
     readonly failure: Effect.Effect<ReactorFailure>;
+    /** Permanently stop new renewal allocations; already acquired sources may finish. */
+    readonly stopRenewal: Effect.Effect<void, EngineError>;
     readonly setAutoplay: (enabled: boolean) => Effect.Effect<void, EngineError>;
     readonly pauseAndStop: Effect.Effect<void, EngineError>;
     readonly remove: (id: ClipId) => Effect.Effect<RemoveOutcome, EngineError>;
+    /** A global rank within this clip's physical session range in the chosen queue. */
     readonly move: (id: ClipId, position: number, queue: "generation" | "playout") => Effect.Effect<void, EngineError>;
     readonly setCanvas: (canvas: Canvas) => Effect.Effect<void, EngineError>;
 }
@@ -372,6 +437,29 @@ export type Renewal = {
     readonly sessionId: string;
     readonly ageSeconds: number;
     readonly tail: MediaTail;
+    /** Eligibility facts captured before retirement waits; absent on historical event values. */
+    readonly handoff?: {
+        readonly replacementSessionId: string;
+        readonly decision: "no-observed-start" | "count-complete" | "grace-elapsed";
+        /** Local decoded-frame accounting, not presentation or audio completeness. */
+        readonly finalClip: {
+            readonly _tag: "NoObservedStart";
+        } | {
+            readonly _tag: "Observed";
+            readonly clipId: ClipId;
+            readonly expectedVideoFrames: number;
+            readonly receivedVideoFrames: number;
+            readonly videoStatus: "count-complete" | "incomplete";
+        };
+        readonly grace: {
+            readonly _tag: "NotObserved";
+        } | {
+            readonly _tag: "Observed";
+            readonly origin: "Ended" | "Idle";
+            readonly elapsedMs: number;
+            readonly limitMs: number;
+        };
+    };
 } | {
     readonly _tag: "Replaced";
     readonly reason: string;
@@ -848,6 +936,451 @@ export declare const CleanupReport: Schema.Struct<{
 }>;
 export interface CleanupReport extends Schema.Schema.Type<typeof CleanupReport> {
 }
+/** The facts that decide whether a retirement is proven complete. */
+interface RetirementEvidence {
+    readonly source?: {
+        readonly sessionId: string;
+    } | undefined;
+    readonly cleanup?: SourceCleanup | undefined;
+    readonly conflictingCleanup?: SourceCleanup | undefined;
+    readonly retirement: {
+        readonly accounting: "settled" | "timed-out" | "not-applicable";
+        readonly scope: "closed" | "failed";
+        readonly affinity: "retired" | "failed" | "not-applicable";
+        readonly errors: readonly unknown[];
+        readonly unknownSubmissions: bigint;
+    };
+}
+/**
+ * The omitted-complete counter a proven complete retirement belongs to, or
+ * undefined when its evidence is incomplete. The retention owner classifies
+ * with it and the summary codec checks rows marked complete against it, so
+ * decoded evidence cannot present an incomplete retirement as compacted.
+ */
+export declare const completeKind: (evidence: RetirementEvidence) => "noAllocation" | "ownedTerminated" | "attachedDetached" | undefined;
+/**
+ * Continuous cleanup is explicitly summarized. The absence of `sessions` makes
+ * legacy complete-history decoders reject it instead of accepting truncated evidence.
+ * JSON codecs encode its exact counts and ordinals as decimal strings.
+ */
+export declare const CleanupSummary: Schema.Struct<{
+    readonly format: Schema.Literal<"reactor-orchestration-cleanup-summary/v1">;
+    readonly totalRetirements: Schema.BigInt;
+    readonly omittedComplete: Schema.Struct<{
+        readonly noAllocation: Schema.BigInt;
+        readonly ownedTerminated: Schema.BigInt;
+        readonly attachedDetached: Schema.BigInt;
+    }>;
+    readonly retained: Schema.$Array<Schema.Struct<{
+        readonly ordinal: Schema.BigInt;
+        readonly source: Schema.optionalKey<Schema.Struct<{
+            readonly sessionId: Schema.String;
+            readonly incarnation: Schema.BigInt;
+        }>>;
+        readonly cleanup: Schema.optionalKey<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>]>>;
+            }>>;
+        }>>;
+        readonly conflictingCleanup: Schema.optionalKey<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>]>>;
+            }>>;
+        }>>;
+        readonly retirement: Schema.Struct<{
+            readonly accounting: Schema.Literals<readonly ["settled", "timed-out", "not-applicable"]>;
+            readonly scope: Schema.Literals<readonly ["closed", "failed"]>;
+            readonly affinity: Schema.Literals<readonly ["retired", "failed", "not-applicable"]>;
+            readonly errors: 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>>;
+            /** Settled bookkeeping can still record an unknown dispatch outcome. */
+            readonly unknownSubmissions: Schema.BigInt;
+        }>;
+        readonly disposition: Schema.Literals<readonly ["complete", "incomplete"]>;
+    }>>;
+    readonly exhausted: Schema.Boolean;
+}>;
+export interface CleanupSummary extends Schema.Schema.Type<typeof CleanupSummary> {
+}
 /** Resolved by the one router; the full request remains a local annotation. */
 export interface RoutedRequest {
     readonly request: ClipRequest;
@@ -880,6 +1413,7 @@ export interface Source {
 export interface HandleShape {
     readonly engine: EngineShape;
     readonly media: MediaShape;
+    /** The current media state; like `engine.state`, it fails with a renewal worker's Cause until close begins. */
     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>;
@@ -888,6 +1422,11 @@ export interface HandleShape {
     readonly cleanup: Effect.Effect<Option.Option<CleanupReport>>;
     readonly sequences: Pick<Affinity<string>, "get" | "snapshots" | "seal" | "acknowledgeIndeterminate" | "release">;
 }
+/** Opt-in continuous renewal retains bounded cleanup evidence in a distinct report. */
+export interface ContinuousHandleShape extends Omit<HandleShape, "close" | "cleanup"> {
+    readonly close: Effect.Effect<CleanupSummary>;
+    readonly cleanup: Effect.Effect<Option.Option<CleanupSummary>>;
+}
 declare const Engine_base: Context.ServiceClass<Engine, "reactor-effect-client/Orchestration/Engine", EngineShape>;
 export declare class Engine extends Engine_base {
 }