reactor-effect-client 0.4.0 → 0.6.0

package/dist/orchestration/scheduler.js

@@ -0,0 +1,1680 @@
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { take as takeQueue } from "../_internal/queue.js";
+import { duration } from "../duration.js";
+import { parsedInput, ReactorError } from "../errors.js";
+import { monotonicMillis } from "./elapsed.js";
+import { captureRequest, PolicyFailure } from "./request.js";
+import { activeIds } from "./routing.js";
+import { fillerIndexFromKey, fillerKey, isReservedSchedulerKey, keyedRequest, keyFromProviderMetadata, } from "./scheduler-key.js";
+import { plan, runwaySeconds } from "./scheduler-policy.js";
+import { Engine } from "./types.js";
+/** Stable caller identity for a scheduled item. */
+export const ItemKey = Schema.NonEmptyString.pipe(Schema.brand("ItemKey"));
+const isFirstDecisive = (status) => status._tag === "Started" ||
+    status._tag === "Ended" ||
+    status._tag === "Dropped" ||
+    status._tag === "Failed" ||
+    status._tag === "Unobserved" ||
+    (status._tag === "Unknown" && status.terminal === true);
+export class KeyMismatch extends Schema.TaggedError()("KeyMismatch", {
+    key: ItemKey,
+}) {
+    static of(key) {
+        return new KeyMismatch({ key });
+    }
+}
+export class WouldMissDeadline extends Schema.TaggedError()("WouldMissDeadline", { key: ItemKey }) {
+    static of(key) {
+        return new WouldMissDeadline({ key });
+    }
+}
+const maxEarlyClipIds = 4096;
+const invalid = (message) => PolicyFailure.refuse("InvalidRequest", message, "submit");
+const ownedData = (input, fields, name) => {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        return Result.fail(invalid(`${name} must be an object`));
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    if (Object.getOwnPropertySymbols(input).length > 0 ||
+        Object.keys(descriptors).some((field) => !fields.includes(field) || !("value" in descriptors[field])))
+        return Result.fail(invalid(`${name} has unsupported fields or accessors`));
+    return Result.succeed(Object.fromEntries(Object.entries(descriptors).map(([field, descriptor]) => [field, descriptor.value])));
+};
+/** A Duration tuple or object read from own data properties; no accessor runs. */
+const durationData = (input) => {
+    if (Array.isArray(input)) {
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        if (Object.getOwnPropertySymbols(input).length > 0 ||
+            Object.keys(descriptors).some((field) => !["0", "1", "length"].includes(field) || !("value" in descriptors[field])) ||
+            descriptors.length?.value !== 2 ||
+            descriptors["0"] === undefined ||
+            descriptors["1"] === undefined)
+            return Result.fail(invalid("Duration tuple has unsupported fields or accessors"));
+        const seconds = descriptors["0"].value;
+        const nanos = descriptors["1"].value;
+        return Result.succeed([seconds, nanos]);
+    }
+    const fields = ownedData(input, ["weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds"], "Duration");
+    return Result.isFailure(fields) ? Result.fail(fields.failure) : Result.succeed(fields.success);
+};
+const captureDuration = (input) => Effect.gen(function* () {
+    if (input === null || typeof input !== "object" || Duration.isDuration(input))
+        return input;
+    return yield* Effect.fromResult(durationData(input));
+});
+/**
+ * A Duration option read as caller data: a data property, own or inherited,
+ * captured without running any accessor. Rejections throw for `parsedInput`.
+ */
+const optionDuration = (options, field, name) => {
+    let descriptor;
+    for (let owner = options; descriptor === undefined && owner !== null; owner = Object.getPrototypeOf(owner))
+        descriptor = Object.getOwnPropertyDescriptor(owner, field);
+    if (descriptor === undefined)
+        return undefined;
+    const reject = () => ReactorError.fromCode("InvalidInput", `${name} must be a Duration of data properties`);
+    if (!("value" in descriptor))
+        throw reject();
+    const value = descriptor.value;
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        throw reject();
+    if (typeof value !== "object" || Duration.isDuration(value))
+        return value;
+    const captured = durationData(value);
+    if (Result.isFailure(captured))
+        throw reject();
+    return captured.success;
+};
+const requestDuration = (input, name, allowZero = false) => Effect.gen(function* () {
+    const captured = yield* captureDuration(input);
+    return yield* parsedInput(() => Duration.toMillis(duration(captured, name, { allowZero, allowNegative: name === "startBy" })), "submit").pipe(Effect.mapError((error) => invalid(error.message)));
+});
+/** Capture scheduling fields before reading the request's placement fields. */
+const captureItem = (input, lanes) => Effect.gen(function* () {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        return yield* invalid("Scheduled item must be an object");
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    if (Object.getOwnPropertySymbols(input).length > 0 ||
+        Object.keys(descriptors).some((field) => !["key", "lane", "request", "window", "start"].includes(field) ||
+            !("value" in descriptors[field])))
+        return yield* invalid("Scheduled item has unsupported fields or accessors");
+    const key = yield* Schema.decodeUnknownEffect(ItemKey)(descriptors.key?.value).pipe(Effect.mapError(() => invalid("Scheduled item key must be nonempty")));
+    if (isReservedSchedulerKey(key))
+        return yield* invalid("Scheduled item key is reserved");
+    const lane = descriptors.lane?.value;
+    if (typeof lane !== "string" || !lanes.has(lane))
+        return yield* invalid("Scheduled item lane is not configured");
+    const rawRequest = descriptors.request?.value;
+    const request = yield* captureRequest(rawRequest);
+    if (request.position !== undefined ||
+        request.before !== undefined ||
+        request.sameSessionAs !== undefined ||
+        request.continueFrom !== undefined ||
+        request.sequence !== undefined)
+        return yield* invalid("Scheduler owns placement and source selection");
+    const rawWindow = descriptors.window?.value;
+    const window = rawWindow === undefined
+        ? undefined
+        : yield* Effect.fromResult(ownedData(rawWindow, ["notBefore", "startBy", "firm"], "Scheduled window"));
+    const notBeforeOffsetMs = window?.notBefore === undefined
+        ? undefined
+        : yield* requestDuration(window.notBefore, "notBefore", true);
+    const startByOffsetMs = window?.startBy === undefined
+        ? undefined
+        : yield* requestDuration(window.startBy, "startBy", true);
+    if (window !== undefined &&
+        (typeof window.firm !== "boolean" ||
+            (notBeforeOffsetMs !== undefined &&
+                startByOffsetMs !== undefined &&
+                startByOffsetMs >= 0 &&
+                notBeforeOffsetMs > startByOffsetMs)))
+        return yield* invalid("Scheduled window is inconsistent");
+    const rawStart = descriptors.start?.value;
+    const start = rawStart === undefined
+        ? undefined
+        : yield* Effect.fromResult(ownedData(rawStart, ["_tag", "time", "late"], "Scheduled start mode"));
+    let atWallMs;
+    let late = "nextBoundary";
+    if (start?._tag === "Follow" && (start.time !== undefined || start.late !== undefined))
+        return yield* invalid("Follow cannot contain an anchor or lateness policy");
+    if (start !== undefined && start._tag !== "Follow") {
+        if (start._tag !== "At" || !Number.isFinite(start.time))
+            return yield* invalid("Scheduled start mode is invalid");
+        atWallMs = start.time;
+        const policy = yield* Effect.fromResult(ownedData(start.late, ["_tag", "by"], "Scheduled lateness policy"));
+        if (policy._tag === "drop" && policy.by === undefined)
+            late = "drop";
+        else if (policy._tag === "skipIfLaterThan")
+            late = {
+                skipIfLaterThanMs: yield* requestDuration(policy.by, "skipIfLaterThan", true),
+            };
+        else if (policy._tag !== "nextBoundary" || policy.by !== undefined)
+            return yield* invalid("Scheduled lateness policy is invalid");
+    }
+    return {
+        key,
+        lane,
+        request,
+        notBeforeOffsetMs,
+        startByOffsetMs,
+        firm: window?.firm === true,
+        atWallMs,
+        late,
+        fingerprint: JSON.stringify({
+            lane,
+            request,
+            notBeforeOffsetMs,
+            startByOffsetMs,
+            firm: window?.firm === true,
+            atWallMs,
+            late,
+        }),
+    };
+});
+export const lineup = (filler) => ({
+    lanes: [{ name: "line" }],
+    filler,
+});
+export class Scheduler extends Context.Service()("reactor-effect-client/Orchestration/Scheduler") {
+    static lineup = lineup;
+}
+export const makeScheduler = (options) => Effect.gen(function* () {
+    const engine = yield* Engine;
+    const clock = yield* Clock.Clock;
+    const lanes = yield* parsedInput(() => {
+        if (options.lanes.length === 0 ||
+            options.lanes.some((lane) => typeof lane.name !== "string" || lane.name.length === 0) ||
+            new Set(options.lanes.map((lane) => lane.name)).size !== options.lanes.length)
+            throw ReactorError.fromCode("InvalidInput", "Scheduler lanes must be unique and nonempty");
+        return options.lanes.map((lane) => lane.name);
+    }, "makeScheduler");
+    const { floorSeconds, targetSeconds, maxBuildsInFlight, maxHistory, unknownRecoveryMs } = yield* parsedInput(() => {
+        const floorSeconds = Duration.toMillis(duration(options.filler.runway.floor, "runway floor", { allowZero: true })) / 1000;
+        const targetSeconds = Duration.toMillis(duration(options.filler.runway.target, "runway target")) / 1000;
+        const maxBuildsInFlight = options.maxBuildsInFlight ?? 1;
+        const maxHistory = options.maxHistory ?? 4096;
+        const unknownRecoveryMs = Duration.toMillis(duration(optionDuration(options, "unknownRecoveryTimeout", "Unknown recovery timeout") ??
+            "60 seconds", "unknown recovery timeout", { maximum: "10 minutes" }));
+        if (floorSeconds > targetSeconds ||
+            !Number.isSafeInteger(maxBuildsInFlight) ||
+            maxBuildsInFlight < 1 ||
+            maxBuildsInFlight > 1024 ||
+            !Number.isSafeInteger(maxHistory) ||
+            maxHistory < 0 ||
+            maxHistory > 65_536)
+            throw ReactorError.fromCode("InvalidInput", "Scheduler runway or build cap is invalid");
+        return { floorSeconds, targetSeconds, maxBuildsInFlight, maxHistory, unknownRecoveryMs };
+    }, "makeScheduler");
+    const captureFiller = (index, runway, targetSeconds) => Effect.gen(function* () {
+        const request = yield* captureRequest(options.filler.clip({
+            index,
+            runwaySeconds: runway,
+            ...(targetSeconds === undefined ? {} : { targetSeconds }),
+        }));
+        if (request.position !== undefined ||
+            request.before !== undefined ||
+            request.sameSessionAs !== undefined ||
+            request.continueFrom !== undefined ||
+            request.sequence !== undefined)
+            return yield* PolicyFailure.refuse("InvalidRequest", "Scheduler filler cannot choose placement or source");
+        return request;
+    });
+    let fillerIndex = 0;
+    let fillerRetryAtMs = 0;
+    const unknownFillers = new Map();
+    const maxUnknownFillers = 4096;
+    let upcomingFiller = yield* captureFiller(0, 0);
+    const inbox = yield* Queue.unbounded();
+    const commandQueue = yield* Queue.unbounded();
+    const events = yield* PubSub.unbounded();
+    yield* Effect.addFinalizer(() => Effect.gen(function* () {
+        yield* Queue.shutdown(commandQueue);
+        yield* Queue.shutdown(inbox);
+        yield* PubSub.shutdown(events);
+    }));
+    const stateRef = yield* SubscriptionRef.make({
+        accepting: true,
+        runwaySeconds: 0,
+        playing: null,
+        lanes: lanes.map((name) => ({ name, keys: [] })),
+        sessions: [],
+        starved: 0,
+    });
+    const initialized = yield* Deferred.make();
+    const stopped = yield* Deferred.make();
+    const settled = yield* Deferred.make();
+    const closedCall = Deferred.await(stopped).pipe(Effect.flatMap((cause) => PolicyFailure.refuse("SessionClosed", cause.message)));
+    const items = new Map();
+    const history = new Map();
+    const owned = new Map();
+    // An event can overtake its enqueue reply. Keep only the evidence needed to
+    // decide that clip's fate until the one in-flight command returns its ID.
+    const earlyClipEvents = new Map();
+    const removedIds = new Set();
+    const filler = new Map();
+    const playingStartedMs = new Map();
+    let admission = 0;
+    let accepting = true;
+    let starved = 0;
+    let refillActive = false;
+    let ended;
+    let drainFailure;
+    const drainReplies = [];
+    const pendingWithdrawals = new Map();
+    const pendingBuilds = new Set();
+    // A Build whose enqueue has started and whose result the worker has not
+    // yet seen. The provider may still accept it after the scheduler ends.
+    let dispatching;
+    const pendingAtDeferrals = new Set();
+    const pendingItemRemovals = new Set();
+    const pendingFillerRemovals = new Set();
+    const removalRetryAtMs = new Map();
+    const removalUnknownAtSerial = new Map();
+    let commandCount = 0;
+    let snapshotAcquiredSerial = 0;
+    let lastProcessedSnapshotSerial = 0;
+    let draining = false;
+    let finishAccepted = false;
+    let autoplayPaused = false;
+    let drained = false;
+    let observationReady = false;
+    let blockedMove;
+    const emit = (entry, status, terminal = false) => Effect.gen(function* () {
+        if (ended !== undefined && !terminal)
+            return;
+        if (JSON.stringify(entry.status) === JSON.stringify(status))
+            return;
+        entry.status = status;
+        entry.phase =
+            status._tag === "Accepted" ||
+                status._tag === "Building" ||
+                status._tag === "Ready" ||
+                status._tag === "Started"
+                ? status._tag
+                : status._tag === "Unknown" && status.terminal !== true
+                    ? "Unknown"
+                    : "Terminal";
+        // Publish in the step that records it (the PubSub is unbounded): a claim
+        // from another fiber cannot land between the two, so asRun never carries
+        // a settlement ahead of a recorded status, nor omits one.
+        PubSub.publishUnsafe(events, {
+            key: entry.key,
+            at: clock.currentTimeMillisUnsafe(),
+            status,
+        });
+        if (isFirstDecisive(status))
+            yield* Deferred.succeed(entry.firstDecisiveWaiter, status);
+        if (status._tag === "Started")
+            yield* Deferred.succeed(entry.startedWaiter, status);
+        if (status._tag === "Ended" ||
+            status._tag === "Dropped" ||
+            status._tag === "Failed" ||
+            status._tag === "Unobserved" ||
+            (status._tag === "Unknown" && status.terminal === true)) {
+            yield* Deferred.succeed(entry.startedWaiter, status);
+            yield* Deferred.succeed(entry.outcomeWaiter, status);
+        }
+    });
+    // The claim is synchronous; interruption masking alone would still allow
+    // two closers to publish conflicting results. Join only local bookkeeping,
+    // never the worker scope (a worker can itself own terminal settlement).
+    const terminate = (terminal) => Effect.suspend(() => {
+        if (ended !== undefined)
+            return Deferred.await(settled);
+        ended = terminal;
+        accepting = false;
+        // Wake the watchdog so an episode left armed by another owner cannot
+        // keep re-arming its timer.
+        Deferred.doneUnsafe(recoveryChanged, Exit.void);
+        return Effect.gen(function* () {
+            for (const item of items.values()) {
+                if (Exit.isFailure(terminal)) {
+                    yield* Deferred.failCause(item.startedWaiter, terminal.cause);
+                    yield* Deferred.failCause(item.outcomeWaiter, terminal.cause);
+                    yield* Deferred.failCause(item.firstDecisiveWaiter, terminal.cause);
+                    continue;
+                }
+                // emit records and publishes a status before completing its waits,
+                // and a claim can land in between: a completion can resume an
+                // observer that closes the owner, and another fiber can claim while
+                // the actor is preempted. Finish those waits from the record.
+                const recorded = item.status;
+                if (item.phase === "Started" || item.phase === "Terminal") {
+                    if (isFirstDecisive(recorded))
+                        yield* Deferred.succeed(item.firstDecisiveWaiter, recorded);
+                    yield* Deferred.succeed(item.startedWaiter, recorded);
+                }
+                if (item.phase === "Terminal")
+                    yield* Deferred.succeed(item.outcomeWaiter, recorded);
+                else
+                    yield* emit(item, item.phase === "Unknown" ||
+                        (item.clipId === undefined &&
+                            (item.unknownAtMs !== undefined || item.key === dispatching))
+                        ? { _tag: "Unknown", terminal: true }
+                        : { _tag: "Failed", reason: { _tag: "Scheduler", cause: terminal.value } }, true);
+            }
+            const closed = Exit.isSuccess(terminal)
+                ? Exit.fail(PolicyFailure.refuse("SessionClosed", terminal.value.message))
+                : Exit.failCause(terminal.cause);
+            for (const [key, pending] of pendingWithdrawals) {
+                // A drop recorded before the claim is the withdrawal's actual result.
+                const reply = Exit.isSuccess(terminal) && items.get(key)?.status._tag === "Dropped"
+                    ? Exit.succeed("withdrawn")
+                    : closed;
+                for (const waiter of pending.replies)
+                    yield* Deferred.done(waiter, reply);
+            }
+            pendingWithdrawals.clear();
+            for (const reply of drainReplies.splice(0))
+                yield* Deferred.done(reply, closed);
+            yield* SubscriptionRef.update(stateRef, (state) => ({ ...state, accepting: false }));
+            yield* Deferred.done(initialized, Exit.isFailure(terminal)
+                ? Exit.failCause(terminal.cause)
+                : Exit.fail(ReactorError.fromCode("Closed", terminal.value.message)));
+            // Supervisors may close the owner immediately when this wakes them.
+            yield* Deferred.done(stopped, terminal);
+        }).pipe(Effect.onExit((exit) => Effect.gen(function* () {
+            // A bookkeeping defect must release joiners with that Cause, never
+            // leave an unfinished latch or report a partial settlement as success.
+            yield* Deferred.done(settled, exit);
+            if (Exit.isFailure(exit)) {
+                yield* Deferred.failCause(initialized, exit.cause);
+                yield* Deferred.failCause(stopped, exit.cause);
+            }
+        })));
+    }).pipe(Effect.uninterruptible);
+    const closeActor = (cause) => terminate(Exit.succeed(cause));
+    let recoveryState;
+    let capacityRecovery;
+    let recoveryDeadline;
+    let recoveryChanged = Deferred.makeUnsafe();
+    // Retain the original age while Closing hides the old source and acquisition
+    // is still pending. Only accepted evidence or a Ready replacement clears it.
+    const updateRecovery = (state = recoveryState, fresh) => {
+        if (ended !== undefined)
+            return;
+        recoveryState = state;
+        const preferred = state === undefined ? undefined : Option.getOrUndefined(state.preferredSessionId);
+        const ready = preferred !== undefined &&
+            state?.sessions.some((source) => source.sessionId === preferred && source.availability === "Ready") === true;
+        let earliest;
+        let drainDeadline;
+        const consider = (atMs, sessionId, cause, newlyObserved = false) => {
+            const deadlineMs = atMs + unknownRecoveryMs;
+            if (((!ready && newlyObserved) || sessionId === undefined || sessionId === preferred) &&
+                (earliest === undefined || deadlineMs < earliest.deadlineMs))
+                earliest = { deadlineMs, sessionId, cause };
+            if (draining && (drainDeadline === undefined || deadlineMs < drainDeadline.deadlineMs))
+                drainDeadline = { deadlineMs, sessionId, cause };
+        };
+        for (const entry of unknownFillers.values())
+            consider(entry.atMs, entry.sessionId, entry.cause);
+        for (const item of items.values())
+            if (item.phase !== "Terminal" &&
+                item.clipId === undefined &&
+                item.unknownAtMs !== undefined &&
+                item.unknownCause !== undefined)
+                consider(item.unknownAtMs, item.unknownSessionId, item.unknownCause);
+        if (fresh !== undefined)
+            consider(fresh.atMs, fresh.sessionId, fresh.cause, true);
+        if (ready &&
+            (earliest === undefined ||
+                (capacityRecovery?.sessionId !== undefined && capacityRecovery.sessionId !== preferred)))
+            capacityRecovery = undefined;
+        if (earliest !== undefined &&
+            (capacityRecovery === undefined || earliest.deadlineMs < capacityRecovery.deadlineMs))
+            capacityRecovery = earliest;
+        const next = drainDeadline !== undefined &&
+            (capacityRecovery === undefined || drainDeadline.deadlineMs < capacityRecovery.deadlineMs)
+            ? drainDeadline
+            : capacityRecovery;
+        if (next?.deadlineMs !== recoveryDeadline?.deadlineMs ||
+            next?.cause !== recoveryDeadline?.cause) {
+            recoveryDeadline = next;
+            Deferred.doneUnsafe(recoveryChanged, Exit.void);
+        }
+    };
+    const provedUnknown = (atMs) => {
+        if (atMs !== undefined && capacityRecovery?.deadlineMs === atMs + unknownRecoveryMs)
+            capacityRecovery = undefined;
+    };
+    const watchdog = Effect.gen(function* () {
+        for (;;) {
+            // A committed result and its queued actor evidence can arrive in one
+            // turn. Coalesce those revisions before allocating a replacement timer;
+            // the original monotonic deadline remains unchanged.
+            yield* Effect.yieldNow;
+            if (ended !== undefined)
+                return;
+            recoveryChanged = Deferred.makeUnsafe();
+            const episode = recoveryDeadline;
+            if (episode === undefined) {
+                yield* Deferred.await(recoveryChanged);
+                continue;
+            }
+            yield* Deferred.await(recoveryChanged).pipe(Effect.timeoutOrElse({
+                duration: Math.max(0, episode.deadlineMs - monotonicMillis(clock)),
+                orElse: () => Effect.void,
+            }));
+            // A canceled timer may already have resumed. Recheck the retained
+            // identity without awaiting the actor, Engine state, or its permits.
+            if (ended === undefined &&
+                recoveryDeadline === episode &&
+                monotonicMillis(clock) >= episode.deadlineMs) {
+                const causes = new Set([episode.cause]);
+                for (const item of items.values())
+                    if (item.unknownCause !== undefined)
+                        causes.add(item.unknownCause);
+                for (const entry of unknownFillers.values())
+                    causes.add(entry.cause);
+                yield* closeActor(ReactorError.fromCode("Timeout", "Scheduler unknown recovery deadline elapsed", {
+                    operation: "scheduler.unknownRecovery",
+                    detail: [...causes],
+                }));
+                return;
+            }
+        }
+    });
+    const prune = (state) => {
+        const active = new Set(activeIds(state));
+        if (state.availability === "Ready") {
+            for (const id of removedIds)
+                if (!active.has(id))
+                    removedIds.delete(id);
+            for (const id of removalRetryAtMs.keys())
+                if (!active.has(id))
+                    removalRetryAtMs.delete(id);
+            for (const id of removalUnknownAtSerial.keys())
+                if (!active.has(id))
+                    removalUnknownAtSerial.delete(id);
+        }
+        for (const [key, item] of items) {
+            if (item.phase !== "Terminal" ||
+                pendingBuilds.has(key) ||
+                pendingWithdrawals.has(key) ||
+                pendingAtDeferrals.has(key) ||
+                pendingItemRemovals.has(key) ||
+                (item.clipId !== undefined && active.has(item.clipId)))
+                continue;
+            if (item.clipId !== undefined) {
+                owned.delete(item.clipId);
+                playingStartedMs.delete(item.clipId);
+            }
+            history.set(key, { fingerprint: item.fingerprint, handle: item.handle });
+            items.delete(key);
+        }
+        while (history.size > maxHistory)
+            history.delete(history.keys().next().value);
+    };
+    // Capture membership and public rows in one pass. A fresh token reads every
+    // source on every observation, including in-place changes to Engine arrays;
+    // frozen empty rows can be shared by every published state without treating
+    // array identity as proof.
+    const noReady = Object.freeze([]);
+    const sourceRows = new Map();
+    const projectSources = (state) => {
+        const seen = Symbol();
+        const sessions = state.sessions.map(({ sessionId }) => {
+            let cached = sourceRows.get(sessionId);
+            if (cached === undefined) {
+                cached = { empty: Object.freeze({ sessionId, ready: noReady }), seen };
+                sourceRows.set(sessionId, cached);
+            }
+            else
+                cached.seen = seen;
+            if (state.ready.length === 0)
+                return cached.empty;
+            return {
+                sessionId,
+                ready: state.ready
+                    .filter((clip) => clip.sessionId === sessionId)
+                    .map((clip) => {
+                    const owner = owned.get(clip.clipId);
+                    return owner === undefined ? "other" : owner._tag === "Filler" ? "filler" : owner.key;
+                }),
+            };
+        });
+        // Bound cached rows by snapshot size without scanning unchanged overlap.
+        // Membership still requires this observation's token, even before pruning.
+        if (sourceRows.size > state.sessions.length)
+            for (const [id, cached] of sourceRows)
+                if (cached.seen !== seen)
+                    sourceRows.delete(id);
+        // Only the serialized actor uses this membership view, before its next projection.
+        return { sessions, has: (id) => sourceRows.get(id)?.seen === seen };
+    };
+    const publishState = (state, sessions = projectSources(state).sessions) => {
+        const playing = Option.getOrUndefined(state.playing);
+        const playingOwner = playing === undefined ? undefined : owned.get(playing.clipId);
+        const playingKey = playing === undefined
+            ? null
+            : playingOwner === undefined
+                ? "other"
+                : playingOwner._tag === "Filler"
+                    ? "filler"
+                    : playingOwner.key;
+        return SubscriptionRef.set(stateRef, {
+            accepting,
+            runwaySeconds: runwaySeconds(state, monotonicMillis(clock), playingStartedMs, owned, [
+                ...items.values(),
+            ]),
+            playing: playingKey,
+            lanes: lanes.map((name) => ({
+                name,
+                keys: [...items.values()]
+                    .filter((item) => item.lane === name && item.phase !== "Terminal")
+                    .map((item) => item.key),
+            })),
+            sessions,
+            starved,
+        });
+    };
+    const activeRecords = (state) => [
+        ...state.queued,
+        ...state.ready,
+        ...Option.match(state.building, {
+            onNone: () => [],
+            onSome: (build) => [build.record],
+        }),
+        ...Option.match(state.playing, {
+            onNone: () => [],
+            onSome: (playing) => Option.match(playing.record, {
+                onNone: () => [],
+                onSome: (record) => [record],
+            }),
+        }),
+    ];
+    const knownRecord = (state, clipId) => activeRecords(state).find((record) => record.clipId === clipId);
+    const refreshAnchors = () => {
+        const nowMs = monotonicMillis(clock);
+        const wallMs = clock.currentTimeMillisUnsafe();
+        for (const item of items.values())
+            if (item.atWallMs !== undefined)
+                item.atMs = nowMs + item.atWallMs - wallMs;
+    };
+    const observed = (state, recoverMissing = false) => Effect.gen(function* () {
+        const active = new Set(activeIds(state));
+        if (recoverMissing) {
+            for (const [clipId, owner] of owned) {
+                if (owner._tag !== "Filler" || active.has(clipId))
+                    continue;
+                const tracked = filler.get(owner.index);
+                if (tracked?.clipId === clipId &&
+                    tracked?.acknowledgedAtSnapshotSerial !== undefined &&
+                    lastProcessedSnapshotSerial <= tracked.acknowledgedAtSnapshotSerial)
+                    continue;
+                const sessionId = owner.sessionId;
+                const source = state.sessions.find((entry) => entry.sessionId === sessionId);
+                if (sessionId === undefined
+                    ? state.availability !== "Ready"
+                    : source !== undefined && source.availability !== "Ready")
+                    continue;
+                owned.delete(clipId);
+                if (tracked?.clipId === clipId)
+                    filler.delete(owner.index);
+                playingStartedMs.delete(clipId);
+                pendingFillerRemovals.delete(clipId);
+            }
+        }
+        const keyed = new Map();
+        for (const record of activeRecords(state)) {
+            const key = keyFromProviderMetadata(record.provider.metadata);
+            if (key !== undefined && !removedIds.has(record.clipId))
+                keyed.set(key, record);
+            const index = fillerIndexFromKey(key);
+            if (index === undefined || removedIds.has(record.clipId))
+                continue;
+            const existing = owned.get(record.clipId);
+            if (existing?._tag === "Filler") {
+                if (existing.sessionId !== record.sessionId)
+                    owned.set(record.clipId, { ...existing, sessionId: record.sessionId });
+                const tracked = filler.get(index);
+                if (tracked?.clipId === record.clipId)
+                    tracked.sessionId = record.sessionId;
+                continue;
+            }
+            if (existing !== undefined)
+                continue;
+            owned.set(record.clipId, { _tag: "Filler", index, sessionId: record.sessionId });
+            filler.set(index, { index, clipId: record.clipId, sessionId: record.sessionId });
+            const priorIndex = fillerIndex;
+            fillerIndex = Math.max(fillerIndex, index + 1);
+            provedUnknown(unknownFillers.get(index)?.atMs);
+            unknownFillers.delete(index);
+            if (fillerIndex !== priorIndex)
+                upcomingFiller = undefined;
+        }
+        for (const item of items.values()) {
+            if (item.phase === "Terminal")
+                continue;
+            if (item.clipId === undefined) {
+                const resumed = keyed.get(item.key);
+                if (resumed !== undefined) {
+                    item.clipId = resumed.clipId;
+                    item.sessionId = resumed.sessionId;
+                    provedUnknown(item.unknownAtMs);
+                    item.unknownAtMs = undefined;
+                    item.unknownCause = undefined;
+                    item.unknownSessionId = undefined;
+                    owned.set(resumed.clipId, { _tag: "Item", key: item.key });
+                }
+            }
+            const clipId = item.clipId;
+            if (clipId === undefined)
+                continue;
+            const playing = Option.getOrUndefined(state.playing);
+            if (playing?.clipId === clipId) {
+                const record = Option.getOrUndefined(playing.record);
+                const at = Option.getOrUndefined(playing.startedAt);
+                const startedAtMonotonicMillis = playing.startedAtMonotonicMillis;
+                if (record !== undefined &&
+                    at !== undefined &&
+                    startedAtMonotonicMillis !== undefined &&
+                    item.phase !== "Started") {
+                    item.sessionId = record.sessionId;
+                    item.startedAtEpochMs = at;
+                    item.startedAtMonoMs = startedAtMonotonicMillis;
+                    playingStartedMs.set(clipId, startedAtMonotonicMillis);
+                    yield* emit(item, {
+                        _tag: "Started",
+                        at,
+                        sessionId: record.sessionId,
+                        durationSeconds: record.durationSeconds,
+                        ...((item.atMs ?? item.startByMs) === undefined ||
+                            startedAtMonotonicMillis <= (item.atMs ?? item.startByMs)
+                            ? {}
+                            : { lateByMillis: startedAtMonotonicMillis - (item.atMs ?? item.startByMs) }),
+                    });
+                }
+                else if (recoverMissing &&
+                    (record === undefined || at === undefined) &&
+                    item.phase !== "Started")
+                    yield* emit(item, { _tag: "Unobserved" });
+            }
+            else if (state.ready.some((record) => record.clipId === clipId)) {
+                const record = knownRecord(state, clipId);
+                item.sessionId = record.sessionId;
+                if (item.phase !== "Started")
+                    yield* emit(item, { _tag: "Ready", sessionId: record.sessionId });
+            }
+            else if (state.queued.some((record) => record.clipId === clipId) ||
+                state.generationOrder.includes(clipId) ||
+                Option.getOrUndefined(state.building)?.record.clipId === clipId) {
+                item.sessionId = knownRecord(state, clipId)?.sessionId ?? item.sessionId;
+                if (item.phase === "Accepted" || item.phase === "Unknown")
+                    yield* emit(item, { _tag: "Building" });
+            }
+            else if (state.failed.includes(clipId))
+                yield* emit(item, {
+                    _tag: "Failed",
+                    reason: { _tag: "Clip", message: "The clip failed unobserved" },
+                });
+            else if (recoverMissing &&
+                item.sessionId !== undefined &&
+                (state.sessions.find((source) => source.sessionId === item.sessionId)?.availability ??
+                    "Ready") === "Ready" &&
+                !active.has(clipId) &&
+                (item.acknowledgedAtSnapshotSerial === undefined ||
+                    lastProcessedSnapshotSerial > item.acknowledgedAtSnapshotSerial))
+                yield* emit(item, { _tag: "Unobserved" });
+        }
+        updateRecovery(state);
+    });
+    const onEvent = (event) => Effect.gen(function* () {
+        if (event._tag === "Starved")
+            starved++;
+        if (event._tag === "SessionFailed") {
+            yield* closeActor(event.failure);
+            return;
+        }
+        if (!("clipId" in event))
+            return;
+        if (commandCount > 0 &&
+            (event._tag === "Started" || event._tag === "Ended" || event._tag === "Failed")) {
+            const prior = earlyClipEvents.get(event.clipId);
+            if (prior === undefined) {
+                if (earlyClipEvents.size >= maxEarlyClipIds) {
+                    // A lost pre-ack start cannot be recast as a definite failure.
+                    for (const key of pendingBuilds) {
+                        const item = items.get(key);
+                        if (item !== undefined && item.phase !== "Terminal" && item.phase !== "Started") {
+                            yield* emit(item, { _tag: "Unknown", terminal: true });
+                            item.phase = "Terminal";
+                        }
+                    }
+                    yield* closeActor(ReactorError.fromCode("Overflow", "Unattributed clip evidence exceeded its bound"));
+                    return;
+                }
+                earlyClipEvents.set(event.clipId, [event]);
+            }
+            else if (!prior.some((seen) => event._tag === "Started"
+                ? seen._tag === "Started"
+                : seen._tag === "Ended" || seen._tag === "Failed"))
+                prior.push(event);
+        }
+        const owner = owned.get(event.clipId);
+        if (owner === undefined)
+            return;
+        if (owner._tag === "Filler") {
+            if (event._tag === "Started")
+                playingStartedMs.set(event.clipId, event.atMonotonicMillis ?? monotonicMillis(clock));
+            if (event._tag === "Ended" || event._tag === "Failed") {
+                owned.delete(event.clipId);
+                if (filler.get(owner.index)?.clipId === event.clipId)
+                    filler.delete(owner.index);
+                playingStartedMs.delete(event.clipId);
+            }
+            return;
+        }
+        const item = items.get(owner.key);
+        if (item === undefined || item.phase === "Terminal")
+            return;
+        switch (event._tag) {
+            case "Queued":
+            case "Building":
+                if (item.phase === "Accepted" || item.phase === "Unknown")
+                    yield* emit(item, { _tag: "Building" });
+                break;
+            case "Ready": {
+                const record = knownRecord(yield* engine.state, event.clipId);
+                if (record !== undefined) {
+                    item.sessionId = record.sessionId;
+                    if (item.phase !== "Started")
+                        yield* emit(item, { _tag: "Ready", sessionId: record.sessionId });
+                }
+                break;
+            }
+            case "Started": {
+                if (item.phase === "Started")
+                    break;
+                const state = yield* engine.state;
+                const record = knownRecord(state, event.clipId);
+                const sessionId = record?.sessionId ?? item.sessionId;
+                if (sessionId === undefined)
+                    yield* emit(item, { _tag: "Unobserved" });
+                else {
+                    item.sessionId = sessionId;
+                    const playing = Option.getOrUndefined(state.playing);
+                    item.startedAtMonoMs =
+                        event.atMonotonicMillis ??
+                            (playing?.clipId === event.clipId
+                                ? (playing.startedAtMonotonicMillis ?? monotonicMillis(clock))
+                                : monotonicMillis(clock));
+                    item.startedAtEpochMs = event.at;
+                    playingStartedMs.set(event.clipId, item.startedAtMonoMs);
+                    yield* emit(item, {
+                        _tag: "Started",
+                        at: event.at,
+                        sessionId,
+                        durationSeconds: event.durationSeconds,
+                        ...((item.atMs ?? item.startByMs) === undefined ||
+                            item.startedAtMonoMs <= (item.atMs ?? item.startByMs)
+                            ? {}
+                            : { lateByMillis: item.startedAtMonoMs - (item.atMs ?? item.startByMs) }),
+                    });
+                }
+                break;
+            }
+            case "Ended":
+                yield* emit(item, item.startedAtMonoMs === undefined
+                    ? { _tag: "Unobserved" }
+                    : {
+                        _tag: "Ended",
+                        at: event.at ?? clock.currentTimeMillisUnsafe(),
+                        termination: event.termination,
+                        airedSeconds: Math.max(0, ((event.atMonotonicMillis ?? monotonicMillis(clock)) - item.startedAtMonoMs) /
+                            1000),
+                    });
+                playingStartedMs.delete(event.clipId);
+                break;
+            case "Failed":
+                yield* emit(item, { _tag: "Failed", reason: { _tag: "Clip", message: event.reason } });
+                break;
+            default:
+                break;
+        }
+    });
+    const replayEarlyClipEvents = (clipId) => Effect.gen(function* () {
+        const saved = earlyClipEvents.get(clipId);
+        earlyClipEvents.delete(clipId);
+        if (saved === undefined)
+            return;
+        for (const event of saved)
+            yield* onEvent(event);
+    });
+    const executeCommand = (command) => {
+        switch (command._tag) {
+            case "Build":
+            case "BuildFiller":
+                return Effect.gen(function* () {
+                    if (command.sessionId === undefined ||
+                        Option.getOrUndefined((yield* engine.state).preferredSessionId) !== command.sessionId)
+                        return yield* PolicyFailure.refuse("RouteChanged", "The preferred source changed before dispatch");
+                    // Termination can be claimed while the route is read; its settlement
+                    // must not be followed by a new dispatch.
+                    if (ended !== undefined)
+                        return yield* PolicyFailure.refuse("SessionClosed", "The scheduler closed");
+                    if (command._tag === "Build")
+                        dispatching = command.key;
+                    return yield* engine.enqueueOnSource === undefined
+                        ? engine.enqueue(command.request)
+                        : engine.enqueueOnSource(command.request, command.sessionId);
+                });
+            case "RemoveItem":
+            case "RemoveFiller":
+            case "RemoveDuplicate":
+            case "DeferAt":
+                return engine.remove(command.clipId);
+            case "Order":
+                return engine.move(command.clipId, command.position, "playout");
+            case "PauseAutoplay":
+                return engine.setAutoplay(false);
+        }
+    };
+    const commandWorker = Effect.gen(function* () {
+        for (;;) {
+            const command = yield* takeQueue(commandQueue);
+            if (ended !== undefined)
+                continue;
+            const result = yield* Effect.result(executeCommand(command));
+            dispatching = undefined;
+            // Capture uncertainty before actor delivery: drain may be awaiting a
+            // permit in stopRenewal while this committed command finishes.
+            if (ended === undefined &&
+                Result.isFailure(result) &&
+                result.failure.context.outcome === "unknown") {
+                let fresh;
+                const sessionId = engine.enqueueOnSource === undefined ||
+                    (command._tag !== "Build" && command._tag !== "BuildFiller")
+                    ? undefined
+                    : command.sessionId;
+                if (command._tag === "Build") {
+                    const item = items.get(command.key);
+                    if (item !== undefined && item.phase !== "Terminal" && item.clipId === undefined) {
+                        item.unknownAtMs ??= monotonicMillis(clock);
+                        item.unknownCause = result.failure;
+                        item.unknownSessionId = sessionId;
+                        fresh = { sessionId, atMs: item.unknownAtMs, cause: result.failure };
+                    }
+                }
+                else if (command._tag === "BuildFiller" &&
+                    !filler.has(command.index) &&
+                    !unknownFillers.has(command.index)) {
+                    fresh = { sessionId, atMs: monotonicMillis(clock), cause: result.failure };
+                    unknownFillers.set(command.index, { ...fresh, index: command.index });
+                }
+                updateRecovery(recoveryState, fresh);
+            }
+            yield* Queue.offer(inbox, { _tag: "CommandDone", command, result });
+        }
+    });
+    const sendCommand = (command) => Effect.gen(function* () {
+        if (ended !== undefined)
+            return;
+        if (command._tag === "Build")
+            pendingBuilds.add(command.key);
+        if (command._tag === "DeferAt")
+            pendingAtDeferrals.add(command.key);
+        commandCount++;
+        yield* Queue.offer(commandQueue, command);
+    });
+    const canRetryRemoval = (clipId) => monotonicMillis(clock) >= (removalRetryAtMs.get(clipId) ?? 0) &&
+        (removalUnknownAtSerial.get(clipId) === undefined ||
+            lastProcessedSnapshotSerial > removalUnknownAtSerial.get(clipId));
+    const finishWithdrawal = (key, result) => Effect.gen(function* () {
+        const pending = pendingWithdrawals.get(key);
+        pendingWithdrawals.delete(key);
+        if (pending === undefined)
+            return;
+        for (const reply of pending.replies)
+            if (Result.isSuccess(result))
+                yield* Deferred.succeed(reply, result.success);
+            else
+                yield* Deferred.fail(reply, result.failure);
+    });
+    const sendItemRemoval = (item, reason) => Effect.gen(function* () {
+        if (item.clipId === undefined ||
+            pendingItemRemovals.has(item.key) ||
+            !canRetryRemoval(item.clipId))
+            return;
+        pendingItemRemovals.add(item.key);
+        yield* sendCommand({ _tag: "RemoveItem", key: item.key, clipId: item.clipId, reason });
+    });
+    const requestWithdrawal = (item, reason, reply) => Effect.gen(function* () {
+        if (item.phase === "Started" || item.phase === "Terminal") {
+            if (reply !== undefined)
+                yield* Deferred.succeed(reply, item.phase === "Started" ? "already-started" : "not-found");
+            return;
+        }
+        const pending = pendingWithdrawals.get(item.key);
+        if (pending !== undefined) {
+            if (reply !== undefined)
+                pending.replies.push(reply);
+            return;
+        }
+        pendingWithdrawals.set(item.key, { reason, replies: reply === undefined ? [] : [reply] });
+        if (pendingAtDeferrals.has(item.key))
+            return;
+        if (item.clipId === undefined) {
+            if (item.phase === "Unknown" || pendingBuilds.has(item.key))
+                return;
+            yield* emit(item, { _tag: "Dropped", reason });
+            yield* finishWithdrawal(item.key, Result.succeed("withdrawn"));
+            return;
+        }
+        yield* sendItemRemoval(item, reason);
+    });
+    const applyPolicy = (action, state) => Effect.gen(function* () {
+        switch (action._tag) {
+            case "Withdraw": {
+                const item = items.get(action.key);
+                if (item !== undefined)
+                    yield* requestWithdrawal(item, action.reason);
+                break;
+            }
+            case "DeferAt":
+                if (canRetryRemoval(action.clipId))
+                    yield* sendCommand({ _tag: "DeferAt", key: action.key, clipId: action.clipId });
+                break;
+            case "WithdrawFiller":
+                for (const clipId of action.clipIds)
+                    if (!pendingFillerRemovals.has(clipId) && canRetryRemoval(clipId)) {
+                        pendingFillerRemovals.add(clipId);
+                        yield* sendCommand({ _tag: "RemoveFiller", clipId });
+                    }
+                break;
+            case "Order": {
+                const signature = state.ready.map((record) => record.clipId).join(",") +
+                    ":" +
+                    action.clipId +
+                    ":" +
+                    action.position;
+                if (blockedMove !== signature)
+                    yield* sendCommand({
+                        _tag: "Order",
+                        clipId: action.clipId,
+                        position: action.position,
+                        signature,
+                    });
+                break;
+            }
+            case "Build": {
+                const item = items.get(action.key);
+                if (item?.phase !== "Accepted")
+                    break;
+                const prepared = yield* Effect.result(keyedRequest(item.request, item.key));
+                if (Result.isFailure(prepared)) {
+                    yield* emit(item, {
+                        _tag: "Failed",
+                        reason: { _tag: "Command", cause: prepared.failure },
+                    });
+                    break;
+                }
+                yield* sendCommand({
+                    _tag: "Build",
+                    key: item.key,
+                    request: prepared.success,
+                    sessionId: Option.getOrUndefined(state.preferredSessionId),
+                });
+                break;
+            }
+            case "BuildFiller": {
+                if (unknownFillers.size >= maxUnknownFillers) {
+                    yield* closeActor(ReactorError.fromCode("Overflow", "Scheduler uncertain filler ledger is full", {
+                        operation: "scheduler.unknownRecovery",
+                    }));
+                    break;
+                }
+                const captured = upcomingFiller === undefined
+                    ? yield* Effect.result(captureFiller(fillerIndex, runwaySeconds(state, monotonicMillis(clock), playingStartedMs, owned, [
+                        ...items.values(),
+                    ]), action.targetSeconds))
+                    : Result.succeed(upcomingFiller);
+                if (Result.isFailure(captured)) {
+                    yield* closeActor(captured.failure);
+                    break;
+                }
+                upcomingFiller = captured.success;
+                const prepared = yield* Effect.result(keyedRequest(captured.success, fillerKey(fillerIndex)));
+                if (Result.isFailure(prepared)) {
+                    yield* closeActor(prepared.failure);
+                    break;
+                }
+                yield* sendCommand({
+                    _tag: "BuildFiller",
+                    index: fillerIndex,
+                    request: prepared.success,
+                    sessionId: Option.getOrUndefined(state.preferredSessionId),
+                });
+                break;
+            }
+        }
+    });
+    const resolveRetiredUnknown = (item) => Effect.gen(function* () {
+        if (item.phase !== "Unknown" || item.clipId !== undefined)
+            return;
+        item.unknownSessionId = undefined;
+        // A retired source cannot play this key again, but it may have played
+        // during a missed observation. Preserve Unknown instead of replaying it.
+        yield* emit(item, { _tag: "Unknown", terminal: true });
+        item.phase = "Terminal";
+        const pending = pendingWithdrawals.get(item.key);
+        if (pending !== undefined)
+            yield* finishWithdrawal(item.key, Result.fail(item.unknownCause ??
+                PolicyFailure.refuse("SessionRecovering", "The original source retired without an enqueue result")));
+    });
+    const handleCommandDone = (command, result) => Effect.gen(function* () {
+        commandCount--;
+        if (ended !== undefined) {
+            if (command._tag === "Build")
+                pendingBuilds.delete(command.key);
+            if (command._tag === "DeferAt")
+                pendingAtDeferrals.delete(command.key);
+            if (command._tag === "RemoveItem")
+                pendingItemRemovals.delete(command.key);
+            if (command._tag === "RemoveFiller")
+                pendingFillerRemovals.delete(command.clipId);
+            return;
+        }
+        switch (command._tag) {
+            case "Build": {
+                const item = items.get(command.key);
+                pendingBuilds.delete(command.key);
+                if (item === undefined)
+                    break;
+                if (Result.isSuccess(result)) {
+                    const clipId = result.success;
+                    if (item.clipId !== undefined && item.clipId !== clipId) {
+                        yield* sendCommand({ _tag: "RemoveDuplicate", clipId });
+                        break;
+                    }
+                    item.clipId = clipId;
+                    item.acknowledgedAtSnapshotSerial = snapshotAcquiredSerial;
+                    owned.set(clipId, { _tag: "Item", key: item.key });
+                    item.sessionId =
+                        knownRecord(yield* engine.state, clipId)?.sessionId ??
+                            (engine.enqueueOnSource === undefined ? undefined : command.sessionId);
+                    provedUnknown(item.unknownAtMs);
+                    item.unknownAtMs = undefined;
+                    item.unknownSessionId = undefined;
+                    item.unknownCause = undefined;
+                    yield* replayEarlyClipEvents(clipId);
+                    const pending = pendingWithdrawals.get(item.key);
+                    if (pending !== undefined) {
+                        if (item.phase === "Started" ||
+                            item.status._tag === "Ended" ||
+                            item.status._tag === "Unobserved")
+                            yield* finishWithdrawal(item.key, Result.succeed("already-started"));
+                        else if (item.phase === "Terminal")
+                            yield* finishWithdrawal(item.key, Result.succeed("not-found"));
+                        else
+                            yield* sendItemRemoval(item, pending.reason);
+                    }
+                    else if (item.phase === "Accepted" || item.phase === "Unknown")
+                        yield* emit(item, { _tag: "Building" });
+                    yield* observed(yield* engine.state);
+                }
+                else if (result.failure.context.outcome === "unknown") {
+                    if (item.clipId === undefined) {
+                        // A generic engine may re-route between the state read and dispatch.
+                        // Only an owner-fenced enqueue can attribute its unknown result.
+                        item.unknownSessionId =
+                            engine.enqueueOnSource === undefined ? undefined : command.sessionId;
+                        item.unknownCause = result.failure;
+                        yield* emit(item, { _tag: "Unknown" });
+                    }
+                }
+                else {
+                    const pending = pendingWithdrawals.get(item.key);
+                    if (pending !== undefined) {
+                        yield* emit(item, { _tag: "Dropped", reason: pending.reason });
+                        yield* finishWithdrawal(item.key, Result.succeed("withdrawn"));
+                    }
+                    else if (result.failure.context.outcome !== "not-submitted" ||
+                        !["QueueFull", "SessionRecovering", "RouteChanged"].includes(result.failure.reason._tag))
+                        yield* emit(item, {
+                            _tag: "Failed",
+                            reason: { _tag: "Command", cause: result.failure },
+                        });
+                    else
+                        item.retryAtMs = monotonicMillis(clock) + 1_000;
+                }
+                break;
+            }
+            case "BuildFiller": {
+                if (Result.isSuccess(result)) {
+                    const clipId = result.success;
+                    const actualSessionId = knownRecord(yield* engine.state, clipId)?.sessionId ??
+                        (engine.enqueueOnSource === undefined ? undefined : command.sessionId);
+                    owned.set(clipId, {
+                        _tag: "Filler",
+                        index: command.index,
+                        sessionId: actualSessionId,
+                    });
+                    filler.set(command.index, {
+                        index: command.index,
+                        clipId,
+                        sessionId: actualSessionId,
+                        acknowledgedAtSnapshotSerial: snapshotAcquiredSerial,
+                    });
+                    fillerIndex = Math.max(fillerIndex, command.index + 1);
+                    upcomingFiller = undefined;
+                    yield* replayEarlyClipEvents(clipId);
+                }
+                else if (result.failure.context.outcome === "unknown") {
+                    // The worker already retained this identity and its original age.
+                }
+                else {
+                    fillerRetryAtMs = monotonicMillis(clock) + 1_000;
+                    if (result.failure.context.outcome === "replied") {
+                        fillerIndex = Math.max(fillerIndex, command.index + 1);
+                        upcomingFiller = undefined;
+                    }
+                }
+                yield* observed(yield* engine.state);
+                break;
+            }
+            case "RemoveItem": {
+                pendingItemRemovals.delete(command.key);
+                const item = items.get(command.key);
+                if (Result.isSuccess(result)) {
+                    removalRetryAtMs.delete(command.clipId);
+                    removalUnknownAtSerial.delete(command.clipId);
+                    removedIds.add(command.clipId);
+                    owned.delete(command.clipId);
+                    playingStartedMs.delete(command.clipId);
+                    if (item?.phase === "Started")
+                        yield* finishWithdrawal(command.key, Result.succeed("already-started"));
+                    else {
+                        if (item !== undefined && item.phase !== "Terminal")
+                            yield* emit(item, { _tag: "Dropped", reason: command.reason });
+                        yield* finishWithdrawal(command.key, Result.succeed("withdrawn"));
+                    }
+                }
+                else {
+                    removalRetryAtMs.set(command.clipId, monotonicMillis(clock) + 1_000);
+                    if (result.failure.context.outcome === "unknown")
+                        removalUnknownAtSerial.set(command.clipId, snapshotAcquiredSerial);
+                    if (item?.phase === "Started")
+                        yield* finishWithdrawal(command.key, Result.succeed("already-started"));
+                    else
+                        yield* finishWithdrawal(command.key, Result.fail(result.failure));
+                }
+                break;
+            }
+            case "RemoveFiller": {
+                pendingFillerRemovals.delete(command.clipId);
+                if (Result.isSuccess(result)) {
+                    removalRetryAtMs.delete(command.clipId);
+                    removalUnknownAtSerial.delete(command.clipId);
+                    removedIds.add(command.clipId);
+                    const owner = owned.get(command.clipId);
+                    if (owner?._tag === "Filler" && filler.get(owner.index)?.clipId === command.clipId)
+                        filler.delete(owner.index);
+                    owned.delete(command.clipId);
+                    playingStartedMs.delete(command.clipId);
+                }
+                else {
+                    removalRetryAtMs.set(command.clipId, monotonicMillis(clock) + 1_000);
+                    if (result.failure.context.outcome === "unknown")
+                        removalUnknownAtSerial.set(command.clipId, snapshotAcquiredSerial);
+                }
+                break;
+            }
+            case "RemoveDuplicate":
+                if (Result.isFailure(result))
+                    yield* closeActor(result.failure);
+                break;
+            case "DeferAt": {
+                pendingAtDeferrals.delete(command.key);
+                const item = items.get(command.key);
+                if (Result.isFailure(result)) {
+                    removalRetryAtMs.set(command.clipId, monotonicMillis(clock) + 1_000);
+                    if (result.failure.context.outcome === "unknown")
+                        removalUnknownAtSerial.set(command.clipId, snapshotAcquiredSerial);
+                    break;
+                }
+                removalRetryAtMs.delete(command.clipId);
+                removalUnknownAtSerial.delete(command.clipId);
+                owned.delete(command.clipId);
+                removedIds.add(command.clipId);
+                playingStartedMs.delete(command.clipId);
+                if (item === undefined || item.phase === "Started" || item.phase === "Terminal")
+                    break;
+                delete item.clipId;
+                item.sessionId = undefined;
+                const pending = pendingWithdrawals.get(command.key);
+                if (pending !== undefined) {
+                    yield* emit(item, { _tag: "Dropped", reason: pending.reason });
+                    yield* finishWithdrawal(command.key, Result.succeed("withdrawn"));
+                }
+                else
+                    yield* emit(item, { _tag: "Accepted" });
+                break;
+            }
+            case "Order":
+                blockedMove = Result.isFailure(result) ? command.signature : undefined;
+                break;
+            case "PauseAutoplay":
+                if (Result.isFailure(result)) {
+                    drainFailure = result.failure;
+                    const replies = drainReplies.splice(0);
+                    for (const reply of replies)
+                        yield* Deferred.fail(reply, result.failure);
+                }
+                break;
+        }
+    });
+    // An accepted drain still owes air to every line not yet Ready, and to a
+    // Ready line held for a future At anchor, which runway must reach. Filler
+    // is the only material that can cover either, so it keeps playing and
+    // refilling until nothing accepted can still leave the host frozen. An
+    // Unknown item does not count: without a fenced source it can stay open
+    // until the scheduler closes, and filler for it would never stop.
+    const fillerHeld = (nowMs) => draining &&
+        finishAccepted &&
+        [...items.values()].some((item) => item.phase === "Accepted" ||
+            item.phase === "Building" ||
+            (item.phase === "Ready" && item.atMs !== undefined && item.atMs > nowMs));
+    const drainPending = (state) => Effect.gen(function* () {
+        if (!draining)
+            return;
+        const playingId = Option.getOrUndefined(state.playing)?.clipId;
+        for (const item of items.values()) {
+            if (finishAccepted)
+                break;
+            if (item.phase === "Terminal" || item.phase === "Started")
+                continue;
+            if (item.clipId === playingId)
+                continue;
+            yield* requestWithdrawal(item, "withdrawn");
+        }
+        if (fillerHeld(monotonicMillis(clock)))
+            return;
+        for (const entry of filler.values()) {
+            if (entry.clipId !== undefined &&
+                entry.clipId !== playingId &&
+                !pendingFillerRemovals.has(entry.clipId) &&
+                canRetryRemoval(entry.clipId)) {
+                pendingFillerRemovals.add(entry.clipId);
+                yield* sendCommand({ _tag: "RemoveFiller", clipId: entry.clipId });
+            }
+        }
+    });
+    const projectedStartMs = (state, lane, nowMs) => {
+        const playing = Option.getOrUndefined(state.playing);
+        const playingRecord = playing === undefined ? undefined : Option.getOrUndefined(playing.record);
+        const started = playing === undefined ? undefined : playingStartedMs.get(playing.clipId);
+        const restMs = playingRecord === undefined || started === undefined
+            ? 0
+            : Math.max(0, playingRecord.durationSeconds * 1000 - (nowMs - started));
+        const laneRank = lanes.indexOf(lane);
+        const preferred = Option.getOrUndefined(state.preferredSessionId);
+        const aheadMs = state.ready.reduce((total, record) => {
+            if (record.sessionId !== preferred)
+                return total;
+            const owner = owned.get(record.clipId);
+            if (owner?._tag === "Filler")
+                return total;
+            if (owner?._tag === "Item") {
+                const prior = items.get(owner.key);
+                if (prior !== undefined && lanes.indexOf(prior.lane) > laneRank)
+                    return total;
+            }
+            return total + record.durationSeconds * 1000;
+        }, 0);
+        return nowMs + restMs + aheadMs;
+    };
+    const reconcile = Effect.gen(function* () {
+        const state = yield* engine.state;
+        if (ended !== undefined)
+            return;
+        prune(state);
+        refreshAnchors();
+        const sources = projectSources(state);
+        if (!observationReady) {
+            yield* publishState(state, sources.sessions);
+            return;
+        }
+        for (const uncertain of unknownFillers.values()) {
+            const sourceRetired = uncertain.sessionId !== undefined && !sources.has(uncertain.sessionId);
+            if (sourceRetired)
+                unknownFillers.delete(uncertain.index);
+            if (sourceRetired ||
+                (uncertain.sessionId !== undefined &&
+                    Option.getOrUndefined(state.preferredSessionId) !== uncertain.sessionId)) {
+                if (fillerIndex <= uncertain.index) {
+                    fillerIndex = uncertain.index + 1;
+                    upcomingFiller = undefined;
+                }
+            }
+        }
+        for (const [key, pending] of pendingWithdrawals) {
+            const item = items.get(key);
+            if (item === undefined)
+                continue;
+            if (item.phase === "Started")
+                yield* finishWithdrawal(key, Result.succeed("already-started"));
+            else if (item.clipId !== undefined)
+                yield* sendItemRemoval(item, pending.reason);
+        }
+        for (const item of items.values())
+            if (item.phase === "Unknown" &&
+                item.clipId === undefined &&
+                item.unknownSessionId !== undefined &&
+                !sources.has(item.unknownSessionId))
+                yield* resolveRetiredUnknown(item);
+        // After retirement, so a deadline no longer outlives the uncertainty that
+        // set it until the next message.
+        updateRecovery(state);
+        if (draining)
+            yield* drainPending(state);
+        const preferred = Option.getOrUndefined(state.preferredSessionId);
+        let unknownFillerCount = 0;
+        for (const entry of unknownFillers.values())
+            if (entry.sessionId === undefined || entry.sessionId === preferred)
+                unknownFillerCount++;
+        const decision = plan({
+            engine: state,
+            items: [...items.values()],
+            owned,
+            lanes,
+            nowMs: monotonicMillis(clock),
+            playingStartedMs,
+            floorSeconds,
+            targetSeconds,
+            refillActive,
+            maxBuildsInFlight,
+            accepting: accepting || (draining && finishAccepted),
+            fillerEnabled: !draining || fillerHeld(monotonicMillis(clock)),
+            fillerRetryAtMs,
+            unknownFillerCount,
+            blockedMove,
+        });
+        refillActive = decision.refillActive;
+        yield* publishState(state, sources.sessions);
+        if ((!draining || finishAccepted) && commandCount === 0 && decision.action !== undefined)
+            yield* applyPolicy(decision.action, state);
+        if (draining &&
+            finishAccepted &&
+            !autoplayPaused &&
+            commandCount === 0 &&
+            [...items.values()].every((item) => item.phase === "Terminal")) {
+            autoplayPaused = true;
+            yield* sendCommand({ _tag: "PauseAutoplay" });
+        }
+        if (drainFailure === undefined &&
+            drainReplies.length > 0 &&
+            commandCount === 0 &&
+            [...items.values()].every((item) => item.phase === "Terminal") &&
+            pendingWithdrawals.size === 0 &&
+            unknownFillers.size === 0) {
+            const after = yield* engine.state;
+            if (Option.isNone(after.playing) && !activeIds(after).some((clipId) => owned.has(clipId))) {
+                drained = true;
+                // A truthful completed drain no longer needs a replacement to resume
+                // service, even when retirement left a capacity episode behind.
+                capacityRecovery = undefined;
+                updateRecovery(after);
+                const replies = drainReplies.splice(0);
+                for (const reply of replies)
+                    yield* Deferred.succeed(reply, undefined);
+            }
+        }
+    });
+    const actor = Effect.gen(function* () {
+        for (;;) {
+            const message = yield* takeQueue(inbox);
+            // Queued public calls observe the same terminal result through closedCall.
+            if (ended !== undefined && message._tag !== "CommandDone")
+                continue;
+            switch (message._tag) {
+                case "Submit": {
+                    if (!accepting) {
+                        yield* Deferred.fail(message.reply, invalid("Scheduler is draining or closed"));
+                        break;
+                    }
+                    const existing = items.get(message.item.key) ?? history.get(message.item.key);
+                    if (existing !== undefined) {
+                        if (existing.fingerprint === message.item.fingerprint)
+                            yield* Deferred.succeed(message.reply, existing.handle);
+                        else
+                            yield* Deferred.fail(message.reply, KeyMismatch.of(message.item.key));
+                        break;
+                    }
+                    const nowMs = monotonicMillis(clock);
+                    const state = yield* engine.state;
+                    if (ended !== undefined)
+                        continue;
+                    const startByMs = message.item.startByOffsetMs === undefined
+                        ? undefined
+                        : nowMs + message.item.startByOffsetMs;
+                    const projectedMs = projectedStartMs(state, message.item.lane, nowMs);
+                    if (startByMs !== undefined && projectedMs > startByMs) {
+                        yield* Deferred.fail(message.reply, WouldMissDeadline.of(message.item.key));
+                        break;
+                    }
+                    // No yield from the terminal check above through admission and its
+                    // publication below: a claim either precedes the item or settles it
+                    // after its Accepted evidence.
+                    const startedWaiter = Deferred.makeUnsafe();
+                    const outcomeWaiter = Deferred.makeUnsafe();
+                    const firstDecisiveWaiter = Deferred.makeUnsafe();
+                    const handle = {
+                        key: message.item.key,
+                        started: Deferred.await(startedWaiter),
+                        outcome: Deferred.await(outcomeWaiter),
+                        firstDecisive: Deferred.await(firstDecisiveWaiter),
+                    };
+                    const item = {
+                        key: message.item.key,
+                        lane: message.item.lane,
+                        request: message.item.request,
+                        fingerprint: message.item.fingerprint,
+                        admission: ++admission,
+                        phase: "Accepted",
+                        status: { _tag: "Accepted" },
+                        ...(message.item.notBeforeOffsetMs === undefined
+                            ? {}
+                            : { notBeforeMs: nowMs + message.item.notBeforeOffsetMs }),
+                        ...(startByMs === undefined ? {} : { startByMs }),
+                        firm: message.item.firm,
+                        ...(message.item.atWallMs === undefined
+                            ? {}
+                            : {
+                                atWallMs: message.item.atWallMs,
+                                atMs: nowMs + message.item.atWallMs - clock.currentTimeMillisUnsafe(),
+                            }),
+                        late: message.item.late,
+                        sessionId: undefined,
+                        unknownSessionId: undefined,
+                        unknownCause: undefined,
+                        unknownAtMs: undefined,
+                        handle,
+                        startedWaiter,
+                        outcomeWaiter,
+                        firstDecisiveWaiter,
+                    };
+                    items.set(item.key, item);
+                    PubSub.publishUnsafe(events, {
+                        key: item.key,
+                        at: clock.currentTimeMillisUnsafe(),
+                        status: item.status,
+                    });
+                    yield* observed(state);
+                    // Submit returns its committed view; other messages publish once
+                    // through reconciliation after all their evidence is adopted.
+                    yield* publishState(state);
+                    yield* Deferred.succeed(message.reply, handle);
+                    break;
+                }
+                case "Withdraw": {
+                    const item = items.get(message.key);
+                    if (item === undefined)
+                        yield* Deferred.succeed(message.reply, "not-found");
+                    else
+                        yield* requestWithdrawal(item, "withdrawn", message.reply);
+                    break;
+                }
+                case "Drain": {
+                    if (drainFailure !== undefined) {
+                        yield* Deferred.fail(message.reply, drainFailure);
+                        break;
+                    }
+                    accepting = false;
+                    if (drained) {
+                        yield* Deferred.succeed(message.reply, undefined);
+                        break;
+                    }
+                    drainReplies.push(message.reply);
+                    if (!draining) {
+                        draining = true;
+                        finishAccepted = message.finish === "accepted";
+                        updateRecovery();
+                        // Renewal admission must stop even while an earlier enqueue is
+                        // awaiting its reply in the command worker.
+                        const stoppedRenewal = yield* Effect.result(engine.stopRenewal);
+                        if (ended !== undefined)
+                            break;
+                        if (Result.isFailure(stoppedRenewal)) {
+                            drainFailure = stoppedRenewal.failure;
+                            for (const reply of drainReplies.splice(0))
+                                yield* Deferred.fail(reply, stoppedRenewal.failure);
+                            break;
+                        }
+                        if (!finishAccepted) {
+                            autoplayPaused = true;
+                            yield* sendCommand({ _tag: "PauseAutoplay" });
+                        }
+                    }
+                    yield* drainPending(yield* engine.state);
+                    break;
+                }
+                case "Snapshot": {
+                    lastProcessedSnapshotSerial = message.acquiredSerial;
+                    observationReady = true;
+                    yield* observed(message.state, true);
+                    blockedMove = undefined;
+                    break;
+                }
+                case "Event":
+                    yield* onEvent(message.event);
+                    yield* observed(yield* engine.state);
+                    blockedMove = undefined;
+                    break;
+                case "Tick":
+                    break;
+                case "CommandDone":
+                    yield* handleCommandDone(message.command, message.result);
+                    if (commandCount === 0)
+                        earlyClipEvents.clear();
+                    break;
+                case "Closed":
+                    yield* closeActor(message.cause);
+                    yield* Deferred.fail(initialized, ReactorError.fromCode("Closed", message.cause.message));
+                    break;
+            }
+            if (ended === undefined)
+                yield* reconcile;
+            if (message._tag === "Snapshot")
+                yield* Deferred.succeed(initialized, undefined);
+        }
+    });
+    const observe = Effect.gen(function* () {
+        for (;;) {
+            const result = yield* Effect.result(Effect.scoped(Effect.gen(function* () {
+                // Claim the serial before acquiring the initial state. A snapshot
+                // begun before an enqueue result must not disprove its clip.
+                const acquiredSerial = ++snapshotAcquiredSerial;
+                const observation = yield* engine.observe({ capacity: 4096 });
+                yield* Queue.offer(inbox, {
+                    _tag: "Snapshot",
+                    state: observation.initial,
+                    acquiredSerial,
+                });
+                yield* Stream.runForEach(observation.events, (event) => Queue.offer(inbox, { _tag: "Event", event }));
+            })));
+            if (Result.isSuccess(result)) {
+                yield* Queue.offer(inbox, {
+                    _tag: "Closed",
+                    cause: ReactorError.fromCode("Closed", "The orchestration closed"),
+                });
+                return;
+            }
+            if (result.failure.reason._tag !== "Overflow") {
+                yield* Queue.offer(inbox, { _tag: "Closed", cause: result.failure });
+                return;
+            }
+        }
+    });
+    // Orderly scope teardown has already claimed and settled Closed before
+    // worker interruption; unexpected interruption retains its original Cause.
+    const supervise = (effect) => effect.pipe(Effect.onExit((exit) => Exit.isFailure(exit) && ended === undefined
+        ? terminate(Exit.failCause(exit.cause))
+        : Effect.void));
+    yield* Effect.forkScoped(supervise(watchdog));
+    yield* Effect.forkScoped(supervise(commandWorker));
+    yield* Effect.forkScoped(supervise(actor));
+    yield* Effect.forkScoped(supervise(observe));
+    yield* Effect.forkScoped(Effect.gen(function* () {
+        for (;;) {
+            yield* Effect.sleep("100 millis");
+            yield* Queue.offer(inbox, { _tag: "Tick" });
+        }
+    }));
+    yield* Queue.offer(inbox, { _tag: "Tick" });
+    yield* Effect.addFinalizer(() => closeActor(ReactorError.fromCode("Closed", "The scheduler closed")));
+    yield* Deferred.await(initialized);
+    const submit = (input) => Effect.gen(function* () {
+        if (yield* Deferred.isDone(stopped))
+            return yield* closedCall;
+        const item = yield* captureItem(input, new Set(lanes));
+        yield* Effect.annotateCurrentSpan("reactor.scheduler.item.key", item.key);
+        const reply = yield* Deferred.make();
+        if (!(yield* Queue.offer(inbox, { _tag: "Submit", item, reply })))
+            return yield* closedCall;
+        return yield* Deferred.await(reply).pipe(Effect.raceFirst(closedCall));
+    }).pipe(Effect.withSpan("Scheduler.submit", {}, { captureStackTrace: false }));
+    const withdraw = (key) => Effect.gen(function* () {
+        const reply = yield* Deferred.make();
+        if (!(yield* Queue.offer(inbox, { _tag: "Withdraw", key, reply })))
+            return yield* closedCall;
+        return yield* Deferred.await(reply).pipe(Effect.raceFirst(closedCall));
+    }).pipe(Effect.withSpan("Scheduler.withdraw", { attributes: { key } }, {
+        captureStackTrace: false,
+    }));
+    const drain = (options = {}) => Effect.gen(function* () {
+        const reply = yield* Deferred.make();
+        const finish = options.finish ?? "playing";
+        if (finish !== "playing" && finish !== "accepted")
+            return yield* invalid("Drain finish must be playing or accepted");
+        if (!(yield* Queue.offer(inbox, { _tag: "Drain", finish, reply })))
+            return yield* closedCall;
+        yield* Deferred.await(reply).pipe(Effect.raceFirst(closedCall));
+    }).pipe(Effect.withSpan("Scheduler.drain", {}, { captureStackTrace: false }));
+    return {
+        submit,
+        withdraw,
+        drain,
+        failure: Deferred.await(stopped),
+        state: SubscriptionRef.get(stateRef),
+        asRun: Stream.fromPubSub(events),
+    };
+}).pipe(Effect.provideServiceEffect(Scope.Scope, Effect.flatMap(Scope.Scope, (parent) => Scope.fork(parent, "sequential"))));
+export const layerScheduler = (options) => Layer.effect(Scheduler, makeScheduler(options));
+//# sourceMappingURL=scheduler.js.map