reactor-effect-client 0.6.0 → 0.7.1

package/dist/orchestration/scheduler-policy.js

@@ -1,11 +1,98 @@
 import * as Option from "effect/Option";
+/**
+ * The indexes of a playing clip's cues that fall due by `untilMs` and have not fired, in
+ * the order they fall: an offset from its start, or back from the end of its length.
+ */
+export const dueCues = (cues, fired, startedAtMs, durationSeconds, untilMs) => cues
+    .map((cue, index) => ({
+    index,
+    atMs: cue.from === "start"
+        ? startedAtMs + cue.offsetMs
+        : startedAtMs + durationSeconds * 1000 - cue.offsetMs,
+}))
+    .filter(({ index, atMs }) => !fired.has(index) && atMs <= untilMs)
+    .sort((a, b) => a.atMs - b.atMs)
+    .map(({ index }) => index);
+/**
+ * The requested length for the next filler clip. Before an anchor, equal clips that tile the
+ * uncovered gap within the provider's lengths, so filler ends on the anchor; otherwise the
+ * shortest clip, which keeps boundaries, and so reactions, frequent. `ratio` is a built
+ * clip's actual over requested length.
+ */
+export const fillLength = (uncoveredSeconds, lengths, ratio) => {
+    const clamp = (requested) => Math.min(lengths.max, Math.max(lengths.min, requested));
+    if (!(uncoveredSeconds > 0))
+        return lengths.min;
+    const pieces = Math.max(1, Math.ceil(uncoveredSeconds / (lengths.max * ratio)));
+    return clamp(uncoveredSeconds / pieces / ratio);
+};
+/** A held clip that would be next within this many seconds is removed and rebuilt. */
+const exposureMarginSeconds = 1.5;
+/** Enough measured builds to act on. */
+export const minimumSamples = 3;
+const quantile = (values, q) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+};
+const spreadOf = (samples) => samples.length < minimumSamples
+    ? undefined
+    : { median: quantile(samples, 0.5), p95: quantile(samples, 0.95) };
+/**
+ * Estimates from recent samples: build seconds per requested second, of independent and of
+ * continued clips, and actual over requested length.
+ */
+export const estimatesFrom = (build, length, continued = []) => {
+    const continuedBuild = spreadOf(continued);
+    return {
+        build: spreadOf(build),
+        ...(continuedBuild === undefined ? {} : { continuedBuild }),
+        length: length.length === 0 ? 1 : quantile(length, 0.5),
+    };
+};
+/**
+ * Until a continued build is measured, one is projected at this multiple of an independent
+ * build. On hosted H3 a continued 5 s clip took 5.45 s to build, against 2.1 to 2.2 s for
+ * independent ones (the 0.7.0 `scheduler-edits` run).
+ */
+const continuedBuildFactor = 2.5;
+/**
+ * Build seconds per requested second that a continued build is projected at, erring long:
+ * the p95 of measured continued builds, or their longest while there are fewer than three;
+ * failing those, the same of independent builds times `continuedBuildFactor`. Undefined
+ * before any build was measured.
+ */
+export const continuedBuildRate = (build, continued) => {
+    const long = (samples) => samples.length >= minimumSamples ? quantile(samples, 0.95) : Math.max(...samples);
+    if (continued.length > 0)
+        return long(continued);
+    if (build.length > 0)
+        return long(build) * continuedBuildFactor;
+    return undefined;
+};
+/**
+ * Seconds added to the measured p95 build time before a refill counts as early enough: the
+ * scheduler's 100 ms turn, a command round trip, and the provider's delay in starting the
+ * next clip (30 to 110 ms on hosted H3).
+ */
+const lookaheadMarginSeconds = 1;
+/** Items that pending batches withdraw. */
+export const supersededBy = (batches) => new Set(batches.flatMap((batch) => batch.targets.map((target) => target.key)));
+/** A clip ending within this many seconds is left to end rather than cut. */
+const cutMarginSeconds = 1;
 const preferredSession = (state) => Option.getOrUndefined(state.preferredSessionId);
+/**
+ * When the playing clip started on the monotonic clock. Engine state can show a new clip
+ * playing before its Started event is handled, so the state's own observation fills in.
+ */
+const playingSince = (playing, playingStartedMs) => playing === undefined
+    ? undefined
+    : (playingStartedMs.get(playing.clipId) ?? playing.startedAtMonotonicMillis);
 /** Ready material on a retiring source is not runway for the replacement. */
 export const runwaySeconds = (state, nowMs, playingStartedMs, owned, items) => {
     const preferred = preferredSession(state);
     const playing = Option.getOrUndefined(state.playing);
     const record = playing === undefined ? undefined : Option.getOrUndefined(playing.record);
-    const started = playing === undefined ? undefined : playingStartedMs.get(playing.clipId);
+    const started = playingSince(playing, playingStartedMs);
     const rest = record === undefined || started === undefined
         ? 0
         : Math.max(0, record.durationSeconds - (nowMs - started) / 1000);
@@ -18,22 +105,295 @@ export const runwaySeconds = (state, nowMs, playingStartedMs, owned, items) => {
             if (owner?._tag !== "Item")
                 return true;
             const item = items.find((candidate) => candidate.key === owner.key);
-            return item?.atMs === undefined || item.atMs <= nowMs;
+            return item?.held !== true && (item?.atMs === undefined || item.atMs <= nowMs);
         })
             .reduce((seconds, clip) => seconds + clip.durationSeconds, 0));
 };
-/** A pure, single-action policy. The actor re-reads Engine after each applied action. */
+/**
+ * Which of two waiting items the build slot takes first: Asap, then everything but held
+ * items, then lane, a replacement racing its item, a group already under way, the earlier
+ * deadline, and admission.
+ */
+const buildOrder = (lanes) => (a, b) => {
+    const asap = Number(b.asap === true) - Number(a.asap === true);
+    const held = Number(a.held === true) - Number(b.held === true);
+    const lane = lanes.indexOf(a.lane) - lanes.indexOf(b.lane);
+    // A replacement races the clip it replaces, so it builds first in its lane.
+    const replacing = Number(b.replaces !== undefined) - Number(a.replaces !== undefined);
+    // A deadline may move a whole group ahead in its lane, never into one being built.
+    const open = Number(b.group !== undefined && b.group.index > 0) -
+        Number(a.group !== undefined && a.group.index > 0);
+    return (asap ||
+        held ||
+        lane ||
+        replacing ||
+        open ||
+        (a.startByMs ?? Infinity) - (b.startByMs ?? Infinity) ||
+        a.admission - b.admission);
+};
+const compareRank = (left, right) => left[0] - right[0] || left[1] - right[1] || left[2] - right[2] || left[3] - right[3];
+/** Where a place sits among a group's parts, and whether a part must wait for the one before it. */
+const ordering = (items, lanes, nowMs, superseded, owned, 
+/** Ready clips that have not started: an item following one of them waits behind it. */
+waiting) => {
+    // A group's parts in order. A part already pruned has settled, so it counts as admitted.
+    const groups = new Map();
+    for (const item of items)
+        if (item.group !== undefined)
+            groups.set(item.group.key, [...(groups.get(item.group.key) ?? []), item]);
+    const previousAdmitted = (item) => {
+        if (item.group === undefined)
+            return true;
+        const index = item.group.index;
+        const parts = groups.get(item.group.key) ?? [];
+        const previous = Math.max(...parts.map((part) => part.group?.index ?? 0).filter((value) => value < index));
+        // The previous place may hold a part and its replacement; either one unadmitted holds this part.
+        return !parts.some((part) => part.group?.index === previous && part.phase === "Accepted");
+    };
+    // Once a group airs, its remaining parts stay ahead of the rest of their lane. A group
+    // whose first part was pruned has settled it, and a settled first part that did not
+    // air withdrew the others.
+    const begun = (item) => {
+        if (item?.group === undefined)
+            return false;
+        const parts = groups.get(item.group.key) ?? [];
+        return (parts.some((part) => part.startedAtMonoMs !== undefined) ||
+            Math.min(...parts.map((part) => part.group?.index ?? 0)) > 0);
+    };
+    // Within its place, a Ready replacement airs ahead of the item it replaces.
+    const byKey = new Map(items.map((item) => [item.key, item]));
+    /**
+     * The live item a replacement takes the place of. Replacing a replacement that was never
+     * built drops that one, so the chain leads back to the item still in the place.
+     */
+    const replacedOf = (item) => {
+        let old = item.replaces === undefined ? undefined : byKey.get(item.replaces);
+        while (old?.phase === "Terminal" && old.replaces !== undefined)
+            old = byKey.get(old.replaces);
+        return old;
+    };
+    const replacedReady = new Set(items.flatMap((item) => {
+        const old = item.phase === "Ready" || item.phase === "Started" ? replacedOf(item) : undefined;
+        return old === undefined ? [] : [old.key];
+    }));
+    const rankItem = (item) => {
+        const generation = item?.key !== undefined && replacedReady.has(item.key) ? Infinity : (item?.generation ?? 0);
+        if (item?.held === true || (item?.atMs !== undefined && nowMs < item.atMs))
+            return [lanes.length + 1, 1, item.admission, generation];
+        // It continues the clip it follows, so it airs right behind that clip until that starts.
+        if (item?.follows !== undefined && waiting.has(item.follows)) {
+            const behind = rankClip(item.follows);
+            return [behind[0], behind[1], behind[2], behind[3] + 0.5];
+        }
+        if (item?.asap === true)
+            return [-0.5, 0, item.admission, generation];
+        return [
+            Math.max(0, lanes.indexOf(item?.lane ?? "")),
+            item?.key !== undefined && superseded.has(item.key) ? 2 : begun(item) ? 0 : 1,
+            item?.admission ?? 0,
+            generation,
+        ];
+    };
+    const rankClip = (clipId) => {
+        const clip = owned.get(clipId);
+        if (clip === undefined)
+            return [-1, 0, 0, 0];
+        if (clip._tag === "Filler")
+            return [lanes.length, 1, clip.index, 0];
+        return rankItem(items.find((value) => value.key === clip.key));
+    };
+    return { previousAdmitted, begun, rankItem, rankClip, replacedOf };
+};
+/**
+ * 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 fillerHeldFor = (snapshot) => snapshot.drain === "accepted" &&
+    snapshot.items.some((item) => item.held !== true &&
+        (item.phase === "Accepted" ||
+            item.phase === "Building" ||
+            (item.phase === "Ready" && item.atMs !== undefined && item.atMs > snapshot.nowMs)));
+/**
+ * When a clip could start at the earliest if it took `place`, optimistically, so a refusal
+ * means it cannot make it: after the rest of the playing clip and every Ready clip on the
+ * preferred source ranked ahead, and after its own build, once builds have been measured.
+ * The build waits for the one in flight and for every build that must go first: higher
+ * lanes, a replacement or a group already under way in its lane, and earlier deadlines.
+ */
+export const projectedStartMs = (view, place) => {
+    const { engine, owned, nowMs } = view;
+    const playing = Option.getOrUndefined(engine.playing);
+    const playingRecord = playing === undefined ? undefined : Option.getOrUndefined(playing.record);
+    const started = playingSince(playing, view.playingStartedMs);
+    const restMs = playingRecord === undefined || started === undefined
+        ? 0
+        : Math.max(0, playingRecord.durationSeconds * 1000 - (nowMs - started));
+    const { rankItem, rankClip, previousAdmitted } = ordering(view.items, view.lanes, nowMs, supersededBy(view.batches), owned, new Set(engine.ready.map((clip) => clip.clipId)));
+    const rank = rankItem(place);
+    const preferred = preferredSession(engine);
+    const withdrawing = view.withdrawing ?? new Set();
+    const aheadMs = engine.ready.reduce((total, record) => {
+        if (record.sessionId !== preferred || compareRank(rankClip(record.clipId), rank) >= 0)
+            return total;
+        const owner = owned.get(record.clipId);
+        if (owner?._tag === "Item" && withdrawing.has(owner.key))
+            return total;
+        return total + record.durationSeconds * 1000;
+    }, 0);
+    const playable = nowMs + restMs + aheadMs;
+    const perSecond = view.estimates.build?.median;
+    if (perSecond === undefined || place.seconds === undefined)
+        return playable;
+    const buildMs = (seconds) => seconds * perSecond * 1000;
+    // The build slot is busy until the build in flight is done.
+    const inFlight = [
+        ...view.items.flatMap((item) => item.phase === "Building" && item.dispatchedAtMs !== undefined && item.key !== place.key
+            ? [item.dispatchedAtMs + buildMs(item.seconds ?? 0)]
+            : []),
+        ...(view.fillerDispatchedAtMs === undefined || view.fillerSeconds === undefined
+            ? []
+            : [view.fillerDispatchedAtMs + buildMs(view.fillerSeconds)]),
+    ];
+    // Only builds that can go now and that the build order puts first count, so the
+    // projection stays optimistic: not held, future or not-yet items, nor a group's parts
+    // after one not yet built.
+    const order = buildOrder(view.lanes);
+    const first = view.items
+        .filter((item) => item.phase === "Accepted" &&
+        item.key !== place.key &&
+        !withdrawing.has(item.key) &&
+        item.held !== true &&
+        (item.atMs === undefined || item.atMs <= nowMs) &&
+        (item.notBeforeMs === undefined || item.notBeforeMs <= nowMs) &&
+        previousAdmitted(item) &&
+        order(item, place) < 0)
+        .reduce((total, item) => total + buildMs(item.seconds ?? 0), 0);
+    const built = Math.max(nowMs, ...inFlight) + first + buildMs(place.seconds);
+    return Math.max(playable, built);
+};
+/**
+ * The pure policy: every withdrawal the plan wants now, and at most one serialized provider
+ * command. The actor re-reads Engine after each applied command.
+ */
 export const plan = (snapshot) => {
     const { engine, items, nowMs, owned } = snapshot;
+    const { previousAdmitted, rankClip, rankItem, replacedOf } = ordering(items, snapshot.lanes, nowMs, supersededBy(snapshot.batches), owned, new Set(engine.ready.map((clip) => clip.clipId)));
+    /**
+     * The clip that airs just before `item` if its continued build starts now: `predecessor`,
+     * unless that build is projected to be Ready only after `predecessor` ends. The clips Ready
+     * behind it then air first, and the item continues from, and follows, the one that will be
+     * playing when it is Ready, or the last of them. A clip it continues from must already be
+     * generated, so none that is still to be built is chosen.
+     */
+    const airsBefore = (item, predecessor, gone) => {
+        const rate = snapshot.continuedBuildRate;
+        if (rate === undefined || item.seconds === undefined)
+            return { clipId: predecessor };
+        const readyAtMs = nowMs + (rate * item.seconds + lookaheadMarginSeconds) * 1000;
+        const playing = Option.getOrUndefined(engine.playing);
+        const record = playing === undefined ? undefined : Option.getOrUndefined(playing.record);
+        const since = playingSince(playing, snapshot.playingStartedMs);
+        if (playing !== undefined && (record === undefined || since === undefined))
+            return { clipId: predecessor };
+        let endMs = record === undefined || since === undefined ? nowMs : since + record.durationSeconds * 1000;
+        // The preferred source's Ready clips in the order they air; held and future ones wait.
+        const queued = engine.ready
+            .filter((clip) => {
+            const owner = owned.get(clip.clipId);
+            return (clip.sessionId === preferredSession(engine) &&
+                !(owner?._tag === "Item" && gone.has(owner.key)) &&
+                rankClip(clip.clipId)[0] <= snapshot.lanes.length);
+        })
+            .sort((a, b) => compareRank(rankClip(a.clipId), rankClip(b.clipId)));
+        const after = playing?.clipId === predecessor
+            ? 0
+            : queued.findIndex((clip) => clip.clipId === predecessor) + 1;
+        if (after === 0 && playing?.clipId !== predecessor)
+            return { clipId: predecessor };
+        for (const clip of queued.slice(0, after))
+            endMs += clip.durationSeconds * 1000;
+        if (readyAtMs <= endMs)
+            return { clipId: predecessor };
+        const behind = queued.slice(after);
+        for (const [index, clip] of behind.entries()) {
+            endMs += clip.durationSeconds * 1000;
+            if (readyAtMs <= endMs || index === behind.length - 1)
+                return { clipId: clip.clipId, follows: clip.clipId };
+        }
+        return { clipId: predecessor };
+    };
+    /**
+     * What an item continuing from its predecessor continues from: the Ready clip or waiting
+     * item that airs just before it on the preferred source, else the clip playing there, or
+     * the one that will be by the time it is built (`airsBefore`). `wait` while that predecessor
+     * is not built yet; no clip when there is none, or when the provider no longer offers it
+     * for continuation.
+     */
+    const continuation = (item) => {
+        const place = rankItem(item);
+        // What will not air before it is no predecessor: the item it replaces, and what a batch
+        // or a withdrawal is taking off.
+        const gone = new Set([...supersededBy(snapshot.batches), ...snapshot.withdrawing]);
+        const replaced = replacedOf(item);
+        if (replaced !== undefined)
+            gone.add(replaced.key);
+        let best;
+        const consider = (rank, clipId) => {
+            if (compareRank(rank, place) < 0 && (best === undefined || compareRank(rank, best.rank) > 0))
+                best = clipId === undefined ? { rank } : { rank, clipId };
+        };
+        for (const clip of engine.ready) {
+            const owner = owned.get(clip.clipId);
+            if (clip.sessionId === preferredSession(engine) &&
+                !(owner?._tag === "Item" && gone.has(owner.key)))
+                consider(rankClip(clip.clipId), clip.clipId);
+        }
+        for (const other of items)
+            if (other.key !== item.key &&
+                !gone.has(other.key) &&
+                (other.phase === "Accepted" || other.phase === "Building" || other.phase === "Unknown"))
+                consider(rankItem(other), undefined);
+        if (best !== undefined && best.clipId === undefined)
+            return { _tag: "wait" };
+        const predecessor = best?.clipId ?? Option.getOrUndefined(engine.playing)?.clipId;
+        if (predecessor === undefined)
+            return { _tag: "from" };
+        const from = airsBefore(item, predecessor, gone);
+        return engine.continuable.includes(from.clipId) ? { _tag: "from", ...from } : { _tag: "from" };
+    };
     const runway = runwaySeconds(engine, nowMs, snapshot.playingStartedMs, owned, items);
     const nextAnchorMs = items
         .filter((item) => item.phase !== "Terminal" && item.atMs !== undefined && item.atMs > nowMs)
         .reduce((earliest, item) => Math.min(earliest, item.atMs ?? Infinity), Infinity);
     const anchorGapSeconds = nextAnchorMs === Infinity ? 0 : (nextAnchorMs - nowMs) / 1000;
-    const fillTarget = Math.max(snapshot.targetSeconds, anchorGapSeconds);
+    // A nonzero floor covers at least one measured p95 build of the next filler clip, so a
+    // refill started at the floor is Ready before the picture runs out. A zero floor keeps
+    // filler off.
+    const p95 = snapshot.estimates.build?.p95;
+    const floorSeconds = snapshot.floorSeconds > 0 && p95 !== undefined && snapshot.fillerSeconds !== undefined
+        ? Math.max(snapshot.floorSeconds, p95 * snapshot.fillerSeconds + lookaheadMarginSeconds)
+        : snapshot.floorSeconds;
+    const targetSeconds = Math.max(snapshot.targetSeconds, floorSeconds);
+    const fillTarget = Math.max(targetSeconds, anchorGapSeconds);
     const filling = anchorGapSeconds > runway ||
-        (snapshot.refillActive ? runway < snapshot.targetSeconds : runway < snapshot.floorSeconds);
-    const base = { runwaySeconds: runway, refillActive: filling };
+        (snapshot.refillActive ? runway < targetSeconds : runway < floorSeconds);
+    const playingId = Option.getOrUndefined(engine.playing)?.clipId;
+    const fillerHeld = fillerHeldFor(snapshot);
+    const withdraw = [];
+    const listed = new Set();
+    const drop = (item, reason) => {
+        if (snapshot.withdrawing.has(item.key) || listed.has(item.key))
+            return;
+        listed.add(item.key);
+        withdraw.push({ key: item.key, reason });
+    };
+    const waiting = (item) => item.phase === "Accepted" ||
+        item.phase === "Building" ||
+        item.phase === "Ready" ||
+        item.phase === "Unknown";
     // Sweep every status; expiry behind a nonexpired head must not be stranded.
     for (const item of items) {
         if (item.phase !== "Accepted" && item.phase !== "Building" && item.phase !== "Ready")
@@ -45,8 +405,74 @@ export const plan = (snapshot) => {
                 ? lateBy > 0
                 : lateBy > item.late.skipIfLaterThanMs;
         if ((item.firm && item.startByMs !== undefined && nowMs > item.startByMs) || atExpired)
-            return { ...base, action: { _tag: "Withdraw", key: item.key, reason: "late" } };
+            drop(item, "late");
+    }
+    // A firm item that cannot start before its deadline is dropped before it takes the build
+    // slot, once builds have been measured.
+    if (snapshot.estimates.build !== undefined)
+        for (const item of items)
+            if (item.firm &&
+                item.phase === "Accepted" &&
+                item.startByMs !== undefined &&
+                !snapshot.dispatched.has(item.key) &&
+                projectedStartMs(snapshot, item) > item.startByMs)
+                drop(item, "late");
+    // A part that failed or was dropped withdraws the parts after it.
+    for (const item of items) {
+        const brokenAt = item.group === undefined ? undefined : snapshot.brokenGroups.get(item.group.key);
+        if (brokenAt !== undefined && item.group.index > brokenAt && waiting(item))
+            drop(item, "withdrawn");
+    }
+    // A replacement takes the place once Ready, or at once if nothing was built for the item it
+    // replaces; a batch's replacement waits for its batch. If the replaced item starts first,
+    // the replacement goes.
+    const pendingReplacements = new Set(snapshot.batches.flatMap((batch) => batch.waitFor));
+    for (const item of items) {
+        if (item.replaces === undefined || item.phase === "Terminal")
+            continue;
+        const old = replacedOf(item);
+        if (old === undefined || old.phase === "Terminal")
+            continue;
+        if (old.phase === "Started") {
+            if (item.phase !== "Started")
+                drop(item, "withdrawn");
+        }
+        else if (
+        // A batch's Ready replacement waits for its batch, but one that has started takes
+        // the place at once, so the item it replaces never follows it.
+        (item.phase === "Ready" && !pendingReplacements.has(item.key)) ||
+            item.phase === "Started" ||
+            (old.phase === "Accepted" && !snapshot.dispatched.has(old.key)))
+            drop(old, "replaced");
     }
+    // A batch takes effect once everything it adds is Ready or has settled. Until then what it
+    // withdraws keeps its place, except an item nothing was built for, which covers nothing.
+    const commit = [];
+    for (const batch of snapshot.batches) {
+        const find = (key) => items.find((item) => item.key === key);
+        if (batch.waitFor.every((key) => {
+            const phase = find(key)?.phase;
+            return (phase === undefined || phase === "Ready" || phase === "Started" || phase === "Terminal");
+        }))
+            commit.push(batch.id);
+        else
+            for (const { key, reason } of batch.targets) {
+                const target = find(key);
+                if (target?.phase === "Accepted" && !snapshot.dispatched.has(key))
+                    drop(target, reason);
+            }
+    }
+    // A held item cannot air without a release a drain will not wait for.
+    if (snapshot.drain !== undefined)
+        for (const item of items)
+            if (item.held === true && waiting(item))
+                drop(item, "withdrawn");
+    // A drain that finishes only the playing clip withdraws everything waiting.
+    if (snapshot.drain === "playing")
+        for (const item of items)
+            if (waiting(item) && (item.clipId === undefined || item.clipId !== playingId))
+                drop(item, "withdrawn");
+    const withdrawFiller = [];
     const preferred = preferredSession(engine);
     const retiring = Option.getOrUndefined(engine.retiringSessionId);
     if (preferred !== undefined &&
@@ -56,14 +482,16 @@ export const plan = (snapshot) => {
         Option.getOrUndefined(engine.building)?.record.sessionId !== retiring &&
         !items.some((item) => (item.phase === "Building" || item.phase === "Unknown") &&
             (item.sessionId ?? item.unknownSessionId) === retiring) &&
-        engine.ready.some((clip) => clip.sessionId === preferred && owned.get(clip.clipId)?._tag === "Item")) {
-        const staleFiller = engine.ready.filter((clip) => clip.sessionId === retiring && owned.get(clip.clipId)?._tag === "Filler");
-        if (staleFiller.length > 0)
-            return {
-                ...base,
-                action: { _tag: "WithdrawFiller", clipIds: staleFiller.map((clip) => clip.clipId) },
-            };
-    }
+        engine.ready.some((clip) => clip.sessionId === preferred && owned.get(clip.clipId)?._tag === "Item"))
+        for (const clip of engine.ready)
+            if (clip.sessionId === retiring && owned.get(clip.clipId)?._tag === "Filler")
+                withdrawFiller.push(clip.clipId);
+    // A drain withdraws filler once nothing accepted still needs it to cover the wait.
+    if (snapshot.drain !== undefined && !fillerHeld)
+        for (const [clipId, owner] of owned)
+            if (owner._tag === "Filler" && clipId !== playingId && !withdrawFiller.includes(clipId))
+                withdrawFiller.push(clipId);
+    const base = { runwaySeconds: runway, refillActive: filling, withdraw, withdrawFiller, commit };
     // Physical sources are independent queues. A move never ranks across them.
     let offset = 0;
     for (const session of engine.ready.length === 0 ? [] : engine.sessions) {
@@ -74,22 +502,7 @@ export const plan = (snapshot) => {
         }
         if (actual.length === 0)
             continue;
-        const rank = (clipId) => {
-            const clip = owned.get(clipId);
-            if (clip === undefined)
-                return [-1, 0];
-            if (clip._tag === "Filler")
-                return [snapshot.lanes.length, clip.index];
-            const item = items.find((value) => value.key === clip.key);
-            if (item?.atMs !== undefined && nowMs < item.atMs)
-                return [snapshot.lanes.length + 1, item.admission];
-            return [Math.max(0, snapshot.lanes.indexOf(item?.lane ?? "")), item?.admission ?? 0];
-        };
-        const desired = [...actual].sort((a, b) => {
-            const left = rank(a.clipId);
-            const right = rank(b.clipId);
-            return left[0] - right[0] || left[1] - right[1];
-        });
+        const desired = [...actual].sort((a, b) => compareRank(rankClip(a.clipId), rankClip(b.clipId)));
         for (let index = 0; index < actual.length; index++) {
             if (actual[index]?.clipId === desired[index]?.clipId)
                 continue;
@@ -122,19 +535,51 @@ export const plan = (snapshot) => {
         }
         offset += actual.length;
     }
+    // A cut lane's Ready item at the front of its session cuts the playing clip there, once
+    // the provider has it at the front.
+    if (snapshot.cutLanes.size > 0) {
+        const current = Option.getOrUndefined(engine.playing);
+        const record = current === undefined ? undefined : Option.getOrUndefined(current.record);
+        const since = playingSince(current, snapshot.playingStartedMs);
+        const front = record === undefined
+            ? undefined
+            : engine.ready.find((clip) => clip.sessionId === record.sessionId);
+        const owner = front === undefined ? undefined : owned.get(front.clipId);
+        const cutter = owner?._tag === "Item" ? items.find((item) => item.key === owner.key) : undefined;
+        // Only filler or a clip of a strictly lower lane is cut, never a clip of the cutter's
+        // own lane, whatever its rank.
+        const playingOwner = current === undefined ? undefined : owned.get(current.clipId);
+        const playingItem = playingOwner?._tag === "Item"
+            ? items.find((item) => item.key === playingOwner.key)
+            : undefined;
+        const lower = cutter !== undefined &&
+            (playingOwner?._tag === "Filler" ||
+                (playingItem !== undefined &&
+                    snapshot.lanes.indexOf(playingItem.lane) > snapshot.lanes.indexOf(cutter.lane)));
+        if (current !== undefined &&
+            record !== undefined &&
+            since !== undefined &&
+            front !== undefined &&
+            cutter !== undefined &&
+            snapshot.cutLanes.has(cutter.lane) &&
+            snapshot.blockedCut !== current.clipId &&
+            lower &&
+            record.durationSeconds - (nowMs - since) / 1000 > cutMarginSeconds)
+            return { ...base, action: { _tag: "Cut", clipId: current.clipId } };
+    }
     // Reorder movable Ready runway before treating a future At clip as exposed.
     // A wall-clock correction can otherwise require removing and rebuilding it.
     const playing = Option.getOrUndefined(engine.playing);
     const playingRecord = playing === undefined ? undefined : Option.getOrUndefined(playing.record);
-    const playingStarted = playing === undefined ? undefined : snapshot.playingStartedMs.get(playing.clipId);
+    const playingStarted = playingSince(playing, snapshot.playingStartedMs);
     const playingRest = playingRecord === undefined || playingStarted === undefined
         ? 0
         : Math.max(0, playingRecord.durationSeconds - (nowMs - playingStarted) / 1000);
     const exposedAnchor = items.find((item) => {
+        const held = item.held === true;
         if (item.phase !== "Ready" ||
             item.clipId === undefined ||
-            item.atMs === undefined ||
-            item.atMs <= nowMs)
+            (!held && (item.atMs === undefined || item.atMs <= nowMs)))
             return false;
         const index = engine.ready.findIndex((clip) => clip.clipId === item.clipId);
         if (index < 0)
@@ -149,10 +594,12 @@ export const plan = (snapshot) => {
             if (owner?._tag !== "Item")
                 return true;
             const prior = items.find((candidate) => candidate.key === owner.key);
-            return prior?.atMs === undefined || prior.atMs <= nowMs;
+            return prior?.held !== true && (prior?.atMs === undefined || prior.atMs <= nowMs);
         })
             .reduce((seconds, clip) => seconds + clip.durationSeconds, 0);
-        return playingRest + ahead < (item.atMs - nowMs) / 1000;
+        return held
+            ? ahead === 0 && playingRest < exposureMarginSeconds
+            : playingRest + ahead < (item.atMs - nowMs) / 1000;
     });
     if (exposedAnchor?.clipId !== undefined)
         return {
@@ -160,7 +607,7 @@ export const plan = (snapshot) => {
             action: { _tag: "DeferAt", key: exposedAnchor.key, clipId: exposedAnchor.clipId },
         };
     const preferredAvailability = engine.sessions.find((session) => session.sessionId === preferred)?.availability;
-    if (!snapshot.accepting || preferredAvailability !== "Ready")
+    if (!(snapshot.accepting || snapshot.drain === "accepted") || preferredAvailability !== "Ready")
         return base;
     const activeFiller = [...owned.entries()].filter(([clipId, owner]) => owner._tag === "Filler" &&
         (owner.sessionId === undefined || owner.sessionId === preferred) &&
@@ -175,25 +622,46 @@ export const plan = (snapshot) => {
         return base;
     const eligible = items
         .filter((item) => item.phase === "Accepted" &&
+        !listed.has(item.key) &&
+        !snapshot.withdrawing.has(item.key) &&
+        previousAdmitted(item) &&
         (item.retryAtMs === undefined || nowMs >= item.retryAtMs) &&
         (item.notBeforeMs === undefined || nowMs >= item.notBeforeMs) &&
         // Autoplay cannot hold a Ready clip. Admit a future anchor only once
         // known material ahead of it covers the time until that anchor.
-        (item.atMs === undefined || item.atMs <= nowMs || runway >= (item.atMs - nowMs) / 1000))
-        .sort((a, b) => {
-        const lane = snapshot.lanes.indexOf(a.lane) - snapshot.lanes.indexOf(b.lane);
-        return (lane || (a.startByMs ?? Infinity) - (b.startByMs ?? Infinity) || a.admission - b.admission);
-    });
-    if (eligible[0] !== undefined)
-        return { ...base, action: { _tag: "Build", key: eligible[0].key } };
-    if (snapshot.fillerEnabled &&
+        (item.atMs === undefined || item.atMs <= nowMs || runway >= (item.atMs - nowMs) / 1000) &&
+        // A held item is built ahead only while filler keeps the runway at its floor.
+        (item.held !== true || (floorSeconds > 0 && runway >= floorSeconds)) &&
+        // A continuing clip waits for the clip it continues from to be built.
+        (item.continuity !== "previous" || continuation(item)._tag !== "wait"))
+        .sort(buildOrder(snapshot.lanes));
+    const next = eligible[0];
+    if (next !== undefined) {
+        const from = next.continuity === "previous" ? continuation(next) : undefined;
+        return {
+            ...base,
+            action: from?._tag === "from" && from.clipId !== undefined
+                ? {
+                    _tag: "Build",
+                    key: next.key,
+                    continueFrom: from.clipId,
+                    ...(from.follows === undefined ? {} : { follows: from.follows }),
+                }
+                : { _tag: "Build", key: next.key },
+        };
+    }
+    if ((snapshot.drain === undefined || fillerHeld) &&
         filling &&
         runway < fillTarget &&
         snapshot.unknownFillerCount === 0 &&
         nowMs >= snapshot.fillerRetryAtMs)
         return {
             ...base,
-            action: { _tag: "BuildFiller", targetSeconds: fillTarget - runway },
+            action: {
+                _tag: "BuildFiller",
+                targetSeconds: fillTarget - runway,
+                durationSeconds: fillLength(anchorGapSeconds - runway, snapshot.fillLengths, snapshot.estimates.length),
+            },
         };
     return base;
 };