@camstack/addon-pipeline 1.2.127 → 1.2.129

package/dist/stream-broker/index.js

@@ -2,11 +2,11 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-BZUXb5S5.js");
+const require_dist = require("../dist-D9x2_csL.js");
 const require_restream_intent = require("../restream-intent-Cv9x3jmu.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_retire_root_keys = require("../retire-root-keys-KE6D6Xh_.js");
-const require_segment_demux_js = require("../segment-demux-js-DRutggd6.js");
+const require_segment_demux_js = require("../segment-demux-js-DiLDoV9_.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_dist.__toESM(node_crypto, 1);
 let node_child_process = require("node:child_process");
@@ -390,6 +390,83 @@ var STREAM_BROKER_RETIRED_ROOT_KEYS = [
 	}
 ];
 //#endregion
+//#region src/stream-broker/stream-broker/ffmpeg-args-common.ts
+/** The `-hide_banner -loglevel <level>` preamble every broker ffmpeg site opens with. */
+function logBannerArgs(level) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		level
+	];
+}
+//#endregion
+//#region src/shared/ffmpeg-decode-args.ts
+/**
+* Canonical decode-hwaccel preference order for the ffmpeg-subprocess decoder.
+*
+* `vaapi` is ranked ABOVE `qsv` deliberately: on the Intel hub the `qsv` decode
+* child exits early (`code=171`, no frames) while the `vaapi` path decodes 8MP
+* h264 cleanly at ~50fps. The kernel probe (`resolveHwAccel`) tends to surface
+* `qsv` first on Intel, so we re-rank its result through this table before
+* building the attempt chain. `videotoolbox` leads for macOS; `cuda` / `nvdec`
+* trail for NVIDIA. A method not listed here keeps its incoming relative order,
+* placed AFTER every ranked one.
+*/
+var DECODE_HWACCEL_RANK = [
+	"videotoolbox",
+	"vaapi",
+	"qsv",
+	"cuda",
+	"nvdec",
+	"d3d11va",
+	"dxva2",
+	"amf",
+	"vdpau",
+	"drm"
+];
+/** Rank index for {@link DECODE_HWACCEL_RANK} — unranked methods sort last. */
+function decodeHwAccelRankIndex(method) {
+	const idx = DECODE_HWACCEL_RANK.indexOf(method.toLowerCase());
+	return idx < 0 ? DECODE_HWACCEL_RANK.length : idx;
+}
+/**
+* Build the ORDERED list of hardware `-hwaccel` methods to attempt for an
+* `'auto'` decode session, best-first. The session walks this chain on an
+* early-exit-with-no-frames and only falls to software once it is exhausted.
+*
+* Strategy:
+* - Seed candidates from the kernel-preferred order UNION the canonical rank
+*   UNION the build's supported list, so a method the kernel omitted but the
+*   build supports (the Intel `vaapi` case — kernel surfaces only `qsv`) is
+*   still attempted.
+* - When the build's supported-method list is known (non-empty), keep only
+*   methods it actually offers; on a probe miss (empty) keep just the kernel
+*   preferences (avoid blindly spawning every backend).
+* - Re-rank the survivors by {@link DECODE_HWACCEL_RANK} so `vaapi` precedes
+*   `qsv`. A supported method not in the rank table keeps its position AFTER
+*   every ranked one (stable sort). Returns lowercased method names; empty ⇒
+*   pure software.
+*/
+function rankDecodeHwAccels(preferred, supportedMethods) {
+	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
+	const hasSupportList = supported.size > 0;
+	const pool = hasSupportList ? [
+		...preferred,
+		...DECODE_HWACCEL_RANK,
+		...supportedMethods
+	] : [...preferred];
+	const seen = /* @__PURE__ */ new Set();
+	const candidates = [];
+	for (const raw of pool) {
+		const method = raw.toLowerCase();
+		if (seen.has(method)) continue;
+		seen.add(method);
+		if (hasSupportList && !supported.has(method)) continue;
+		candidates.push(method);
+	}
+	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
+}
+//#endregion
 //#region src/stream-broker/battery-wake-on-play.ts
 /**
 * Wake-on-play — pressing play on a sleeping battery camera wakes it, and the
@@ -592,83 +669,6 @@ async function wakeBatteryDeviceForPlay(deviceId, deps) {
 	throw new BatteryStreamUnavailableError(deviceId, outcome, wake.awoke ? "it acknowledged the wake but no stream had appeared yet — try again in a few seconds" : "it did not answer the wake in time — try again");
 }
 //#endregion
-//#region src/stream-broker/stream-broker/ffmpeg-args-common.ts
-/** The `-hide_banner -loglevel <level>` preamble every broker ffmpeg site opens with. */
-function logBannerArgs(level) {
-	return [
-		"-hide_banner",
-		"-loglevel",
-		level
-	];
-}
-//#endregion
-//#region src/shared/ffmpeg-decode-args.ts
-/**
-* Canonical decode-hwaccel preference order for the ffmpeg-subprocess decoder.
-*
-* `vaapi` is ranked ABOVE `qsv` deliberately: on the Intel hub the `qsv` decode
-* child exits early (`code=171`, no frames) while the `vaapi` path decodes 8MP
-* h264 cleanly at ~50fps. The kernel probe (`resolveHwAccel`) tends to surface
-* `qsv` first on Intel, so we re-rank its result through this table before
-* building the attempt chain. `videotoolbox` leads for macOS; `cuda` / `nvdec`
-* trail for NVIDIA. A method not listed here keeps its incoming relative order,
-* placed AFTER every ranked one.
-*/
-var DECODE_HWACCEL_RANK = [
-	"videotoolbox",
-	"vaapi",
-	"qsv",
-	"cuda",
-	"nvdec",
-	"d3d11va",
-	"dxva2",
-	"amf",
-	"vdpau",
-	"drm"
-];
-/** Rank index for {@link DECODE_HWACCEL_RANK} — unranked methods sort last. */
-function decodeHwAccelRankIndex(method) {
-	const idx = DECODE_HWACCEL_RANK.indexOf(method.toLowerCase());
-	return idx < 0 ? DECODE_HWACCEL_RANK.length : idx;
-}
-/**
-* Build the ORDERED list of hardware `-hwaccel` methods to attempt for an
-* `'auto'` decode session, best-first. The session walks this chain on an
-* early-exit-with-no-frames and only falls to software once it is exhausted.
-*
-* Strategy:
-* - Seed candidates from the kernel-preferred order UNION the canonical rank
-*   UNION the build's supported list, so a method the kernel omitted but the
-*   build supports (the Intel `vaapi` case — kernel surfaces only `qsv`) is
-*   still attempted.
-* - When the build's supported-method list is known (non-empty), keep only
-*   methods it actually offers; on a probe miss (empty) keep just the kernel
-*   preferences (avoid blindly spawning every backend).
-* - Re-rank the survivors by {@link DECODE_HWACCEL_RANK} so `vaapi` precedes
-*   `qsv`. A supported method not in the rank table keeps its position AFTER
-*   every ranked one (stable sort). Returns lowercased method names; empty ⇒
-*   pure software.
-*/
-function rankDecodeHwAccels(preferred, supportedMethods) {
-	const supported = new Set(supportedMethods.map((m) => m.toLowerCase()));
-	const hasSupportList = supported.size > 0;
-	const pool = hasSupportList ? [
-		...preferred,
-		...DECODE_HWACCEL_RANK,
-		...supportedMethods
-	] : [...preferred];
-	const seen = /* @__PURE__ */ new Set();
-	const candidates = [];
-	for (const raw of pool) {
-		const method = raw.toLowerCase();
-		if (seen.has(method)) continue;
-		seen.add(method);
-		if (hasSupportList && !supported.has(method)) continue;
-		candidates.push(method);
-	}
-	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
-}
-//#endregion
 //#region src/stream-broker/derived/cycle-check.ts
 /**
 * Would assigning `derivedCamStreamId` to `targetProfile` create a cycle?
@@ -16279,7 +16279,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		}
 		let devices;
 		try {
-			devices = await api.deviceManager.listAll.query({});
+			devices = await api.deviceManager.listAll.query({ projection: "slim" });
 		} catch (err) {
 			this.logger.warn("profile-map prune skipped — deviceManager.listAll failed", { meta: {
 				persistedCount,
@@ -16604,7 +16604,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (!this.api) return;
 		let devices;
 		try {
-			devices = await this.api.deviceManager.listAll.query({});
+			devices = await this.api.deviceManager.listAll.query({ projection: "slim" });
 		} catch (err) {
 			this.logger.debug("reconcileAllCatalogs: deviceManager.listAll failed — will retry", { meta: { error: require_dist.errMsg(err) } });
 			return;
@@ -16744,7 +16744,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (!this.api) return false;
 		let devices;
 		try {
-			devices = await this.api.deviceManager.listAll.query({});
+			devices = await this.api.deviceManager.listAll.query({ projection: "slim" });
 		} catch {
 			return false;
 		}
@@ -23797,6 +23797,9 @@ var ScrubDragStats = class {
 	prefetchHits = 0;
 	prefetchSuppressed = 0;
 	ackTimeouts = 0;
+	deadlineMisses = 0;
+	retargets = 0;
+	resolveJoins = 0;
 	failures = 0;
 	firstPushMs = null;
 	creditEndedAt = null;
@@ -23806,6 +23809,9 @@ var ScrubDragStats = class {
 	demuxMs = new PhaseSamples();
 	tickMs = new PhaseSamples();
 	ackMs = new PhaseSamples();
+	leadMs = new PhaseSamples();
+	oversizeSegments = 0;
+	degradedProfile = null;
 	constructor(startedAtMs) {
 		this.startedAtMs = startedAtMs;
 	}
@@ -23860,6 +23866,30 @@ var ScrubDragStats = class {
 	recordAckTimeout(pushes) {
 		this.ackTimeouts += pushes;
 	}
+	/** A frame abandoned on its deadline — dropped work, counted every time. */
+	recordDeadlineMiss() {
+		this.deadlineMisses += 1;
+	}
+	/** A landing re-aimed at the newer finger position it also covered. */
+	recordRetarget() {
+		this.retargets += 1;
+	}
+	/** A whole-segment read that had to degrade to a GOP range on size. */
+	recordOversizeSegment() {
+		this.oversizeSegments += 1;
+	}
+	/** This drag is not running on the scrub profile — every gate is off. */
+	recordProfileDegraded(profile) {
+		this.degradedProfile = profile;
+	}
+	/** One read aimed ahead of the finger, and by how much. */
+	recordLead(leadMs) {
+		this.leadMs.add(Math.abs(leadMs));
+	}
+	/** A tick served by the read another tick already had in flight. */
+	recordResolveJoin() {
+		this.resolveJoins += 1;
+	}
 	/** A swallowed `scrubTick` throw — the branch where a dark failure hides. */
 	recordFailure() {
 		this.failures += 1;
@@ -23875,6 +23905,7 @@ var ScrubDragStats = class {
 		const dmx = this.demuxMs.summary();
 		const tick = this.tickMs.summary();
 		const ack = this.ackMs.summary();
+		const lead = this.leadMs.summary();
 		return {
 			ticks: this.ticks,
 			dragMs: Math.round(dragMs),
@@ -23914,6 +23945,13 @@ var ScrubDragStats = class {
 			prefetchHits: this.prefetchHits,
 			prefetchSuppressed: this.prefetchSuppressed,
 			ackTimeouts: this.ackTimeouts,
+			deadlineMisses: this.deadlineMisses,
+			retargets: this.retargets,
+			resolveJoins: this.resolveJoins,
+			leadMsP50: lead.p50Ms,
+			leadMsMax: lead.maxMs,
+			oversizeSegments: this.oversizeSegments,
+			degradedProfile: this.degradedProfile,
 			failures: this.failures,
 			creditEndedAt: this.creditEndedAt,
 			acks: ack.n,
@@ -24068,11 +24106,29 @@ var SCRUB_PREFETCH_MAX_INFLIGHT = 2;
 */
 var SCRUB_WHOLE_SEGMENT_PROFILE = "low";
 /**
-* Safety ceiling on the whole-segment read. `low` is ~230 KB per 10 s, so this
-* is ~6× headroom for a camera whose substream is unusually fat — but a
-* segment past it (a mis-pinned `high` at ~5 MB) falls back to the GOP range,
-* because reading 5 MB to push one keyframe is the trade this change exists to
-* avoid, in the other direction.
+* Safety ceiling on ONE scrub read, in bytes.
+*
+* `low` is ~230 KB per 10 s, so this is ~6× headroom for a camera whose
+* substream is unusually fat — but a segment past it (a mis-pinned `high` at
+* ~5 MB) falls back to the GOP range, because reading 5 MB to push one
+* keyframe is the trade this change exists to avoid, in the other direction.
+*
+* ⚠️ THIS NUMBER IS TIED TO THE SEGMENT DURATION AND THE TIE IS NOT ENFORCED.
+* It was tuned against a 10-second `low` segment. At the 60-second segments
+* the 2026-08-25 teardown proposes, a NATIVE `low` is ~1.4 MB (just inside,
+* and the whole-segment read gets six times better — one seek leaves a minute
+* of access units behind) while a DERIVED `low` is ~4.8 MB (outside, and every
+* scrub read silently degrades to a 3-seek GOP range that leaves nothing
+* behind). Same constant, opposite outcomes, no signal either way — which is
+* why the degradation is now COUNTED and LOGGED
+* (`scrub-feeder:oversize-segment`, `oversizeSegments` on the drag census)
+* instead of being inferred from a falling hit rate.
+*
+* The real fix, when 60 s segments land, is a read unit that is a BYTE BUDGET
+* over the fragment's own keyframe table — "as many consecutive GOPs as fit in
+* N bytes" — which needs a provider method we do not have
+* (`readGopBytes` reads exactly one GOP). Until then this is an absolute cap
+* on a single read and the log is the guard.
 */
 var SCRUB_WHOLE_SEGMENT_MAX_BYTES = 15e5;
 /**
@@ -24133,6 +24189,115 @@ var SCRUB_SLOW_READ_MS = 600;
 */
 var SCRUB_SWEEP_WINDOW_MS = 4e3;
 /**
+* THE DEADLINE ON ONE SCRUB FRAME — and the reason it is not
+* {@link SEGMENT_TIMEOUT_MS}.
+*
+* A scrub tick used to be bounded only by the 8 s per-RPC timeout, against a
+* cold read measured at p50 531 ms, p95 1.4–2 s and a 9.2 s max (census
+* 2026-08-25). So the feeder WAITED. The frame it eventually pushed was for a
+* finger position from seconds earlier, and the gesture spent its whole
+* duration on a handful of stale frames — the operator's "quasi 0 frame, e
+* l'immagine insegue il dito".
+*
+* The reference design (Scrypted NVR, teardown 2026-08-25) spends at most
+* ~1000 ms on the WHOLE scrub animation and gives every single frame the
+* REMAINING window as its deadline: a frame that cannot be produced in time is
+* dropped, never awaited. This is the same contract on our constraints.
+*
+* 700 ms and not 1000: the deadline must be shorter than the gesture's own
+* animation window or it can never fire twice inside one, and it must be above
+* the cold-read p50 (531 ms) or the median frame would be dropped — a deadline
+* that drops the median makes the picture WORSE, not fresher. 700 ms sits
+* between: it serves the p50–p60 of cold reads and cuts the p90 tail that used
+* to eat the gesture.
+*
+* Dropping is never silent: `deadlineMisses` on the drag aggregate plus one
+* `scrub-feeder:deadline-miss` line per drag.
+*/
+var SCRUB_TICK_DEADLINE_MS = 700;
+/**
+* The FIRST frame of a drag gets a longer deadline, because nothing is painted
+* yet.
+*
+* Every later frame has a predecessor on screen, so dropping it costs
+* freshness. The first one has none: dropping it costs the whole picture, and
+* the operator reads a blank recorded view as "playback parte dopo una vita".
+* The reference design has the same asymmetry for the same reason — its
+* animation frames are deadline-dropped while the LANDING seek is unbounded.
+*
+* 2500 ms covers the cold-read p95 (1.4–2 s) and still cuts the 9.2 s tail.
+*/
+var SCRUB_FIRST_TICK_DEADLINE_MS = 2500;
+/**
+* How far a new target may be from an in-flight read's target and still RIDE
+* it instead of starting a second one.
+*
+* A `low` segment is ~10 s of timeline and the read unit is the whole segment
+* ({@link SCRUB_WHOLE_SEGMENT_PROFILE}), so a target within one segment of the
+* one being read is very likely already inside the bytes on their way. Riding
+* costs nothing and saves a random seek on the spindle that is the bottleneck;
+* being wrong costs one wasted deadline, which is now cheap by construction.
+*/
+var SCRUB_RIDE_WINDOW_MS = 1e4;
+/**
+* Hard bound on concurrent fragment resolutions for one drag.
+*
+* A deadline that drops frames is only safe if dropping does not multiply the
+* work: without this bound a drag over slow footage would abandon a read every
+* {@link SCRUB_TICK_DEADLINE_MS} and start another, turning one saturated
+* spindle into N. Two: the one that is landing, and the one the finger has
+* moved on to. At the cap, a tick rides the newest in-flight read instead.
+*/
+var SCRUB_RESOLVE_MAX_INFLIGHT = 2;
+/**
+* READ-AHEAD LEAD — the fix for "the picture chases the finger".
+*
+* A scrub frame is always the frame a read STARTED for, one read time ago.
+* On this disk that is 531 ms of wall clock (p50, census 2026-08-25), and on
+* a wide window 531 ms of gesture is TWENTY MINUTES of timeline: measured in
+* the drag bench, the median painted frame on a 2 h fling was 1 220 000 ms
+* behind the finger. Nothing about that is I/O — it is aiming at where the
+* finger WAS.
+*
+* So a steady drag reads where the finger WILL BE: `mediaVelocity ×
+* medianRecentReadMs`. It costs nothing (the same one read, at a different
+* offset), and it is bounded by the two things that make it a prediction
+* rather than a guess:
+*
+*  - a direction RUN of at least {@link SCRUB_LEAD_MIN_DIR_RUN} POINTER
+*    samples, so a jittery or reversing drag never leads. Pointer samples and
+*    not pushes: on this disk a 3 s drag produces ~75 pointer samples and only
+*    ~4 pushes, so a gate counted in pushes has no runway inside the gesture
+*    it is supposed to help — measured in the drag bench, it engaged once, at
+*    the very end;
+*  - at least {@link SCRUB_LEAD_MIN_READ_SAMPLES} measured read, so the lead
+*    is derived from this disk right now and not from a constant. ONE is
+*    enough: against a read cost that is unknown, a one-sample estimate is not
+*    a good prediction — it is simply a far better one than assuming zero.
+*
+* Overshoot is self-correcting: the retarget below serves the newest target
+* the landed fragment covers, so a lead that is slightly long lands on the
+* finger exactly, and one that is wrong costs the same single read it would
+* have cost anyway.
+*/
+var SCRUB_LEAD_MIN_READ_SAMPLES = 1;
+/**
+* Smoothing for the media-velocity estimate (ms of timeline per ms of wall
+* clock), folded on every pointer sample. Half-and-half: fast enough to track
+* a fling that starts mid-gesture, slow enough that one jittery sample cannot
+* aim a read an hour away.
+*/
+var SCRUB_VELOCITY_EMA = .5;
+/** Same-direction POINTER samples required before a read may aim ahead. */
+var SCRUB_LEAD_MIN_DIR_RUN = 2;
+/**
+* Pointer-sample gaps outside this range do not update the velocity estimate:
+* below it the delta is dominated by timer jitter, above it the finger has
+* effectively paused and the "velocity" is an artefact of the pause.
+*/
+var SCRUB_VELOCITY_MIN_GAP_MS = 10;
+var SCRUB_VELOCITY_MAX_GAP_MS = 500;
+/**
 * Receiver-credit cap for scrub pushes: at most this many PUSHES may be
 * OUTSTANDING (on the track, not yet acknowledged by the viewer via
 * `scrubAck`). The coalescing window above shapes the INPUT; on a thin pipe it
@@ -24389,6 +24554,28 @@ var RecordedFeeder = class {
 	scrubWarmGen = 0;
 	/** Tick demand-read in flight: the fill waits so the finger wins the spindle. */
 	scrubTickReadInFlight = false;
+	/**
+	* The newest fragment resolution in flight for this drag — what a later tick
+	* rides instead of issuing its own read. Cleared by the resolution itself.
+	*/
+	scrubResolve = null;
+	/** Concurrent resolutions, bounded by {@link SCRUB_RESOLVE_MAX_INFLIGHT}. */
+	scrubResolvesInFlight = 0;
+	/** One `deadline-miss` line per drag; the count lives on the aggregate. */
+	scrubDeadlineLogged = false;
+	/** One `oversize-segment` line per drag; the count lives on the aggregate. */
+	scrubOversizeLogged = false;
+	/** One `profile-degraded` line per drag — the `low` pin is lost. */
+	scrubProfileLogged = false;
+	/** Has this drag put a frame on the wire? Gates the first-frame deadline. */
+	scrubPushedThisDrag = false;
+	/** Smoothed media-ms per wall-ms of the drag, signed. Null until measurable. */
+	scrubVelocity = null;
+	/** Previous pointer sample, for the velocity estimate above. */
+	scrubLastSampleMs = null;
+	scrubLastSampleAtMs = 0;
+	/** Signed run of consecutive same-direction POINTER samples. */
+	scrubVelRun = 0;
 	/** One fill walker per drag — a fling retargets it, it does not spawn another. */
 	scrubFillLoopActive = false;
 	scrubWarmBackMs = SCRUB_WARM_BACK_MS;
@@ -24762,12 +24949,21 @@ var RecordedFeeder = class {
 		this.scrubCursor = null;
 		this.scrubNoFootageLogged = false;
 		this.scrubParkLogged = false;
+		this.scrubDeadlineLogged = false;
+		this.scrubOversizeLogged = false;
+		this.scrubProfileLogged = false;
+		this.scrubPushedThisDrag = false;
+		this.scrubResolve = null;
+		this.scrubVelocity = null;
+		this.scrubLastSampleMs = null;
+		this.scrubVelRun = 0;
 		this.scrubOutstanding = [];
 		this.clearScrubAckTimeout();
 		this.scrubAckTimeoutLogged = false;
 		this.scrubPendingHint = null;
 		this.scrubStartedAtMs = performance.now();
 		this.scrubStats = new ScrubDragStats(this.scrubStartedAtMs);
+		this.reportProfileDegradation();
 		this.scrubDemuxMark = this.deps.demuxTally?.counts() ?? null;
 		this.scrubLastPushLogAtMs = 0;
 		this.scrubLastSlowLocateLogAtMs = 0;
@@ -24982,6 +25178,7 @@ var RecordedFeeder = class {
 	*/
 	scrubTo(epochMs, hint) {
 		if (this.disposed || !this.scrubbing) return;
+		this.noteScrubSample(epochMs);
 		this.scrubPendingEpochMs = epochMs;
 		this.scrubPendingHint = hint ?? null;
 		if (this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
@@ -25107,7 +25304,7 @@ var RecordedFeeder = class {
 			return;
 		}
 		const target = this.scrubPendingEpochMs;
-		const hint = this.scrubPendingHint;
+		let hint = this.scrubPendingHint;
 		this.scrubPendingEpochMs = null;
 		this.scrubPendingHint = null;
 		if (target === null) {
@@ -25136,70 +25333,57 @@ var RecordedFeeder = class {
 				}
 			}
 			if (!seg) {
-				this.scrubTickReadInFlight = true;
-				try {
-					this.maybeRecenterScrubWarm(target);
-					const locateStartMs = performance.now();
-					let loc = await this.withTimeout(this.deps.locate({
-						deviceId: this.deps.deviceId,
-						profile: this.deps.profile,
-						epochMs: target
-					}));
-					locateCalls += 1;
-					locateMs = performance.now() - locateStartMs;
-					this.maybeLogSlowLocate(target, locateMs);
-					if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
-					if (loc.kind === "gap") {
-						const decision = resolveSnapTarget(loc, target);
-						if (decision.kind !== "snap") {
-							if (!this.scrubNoFootageLogged) {
-								this.scrubNoFootageLogged = true;
-								if (decision.kind === "too-far") this.deps.onLog?.("scrub-feeder:snap-too-far", {
-									epochMs: target,
-									nearestMs: decision.snapMs,
-									distanceMs: decision.distanceMs
-								});
-								else this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
-							}
-							return;
-						}
-						const snapStartMs = performance.now();
-						const snapped = await this.withTimeout(this.deps.locate({
-							deviceId: this.deps.deviceId,
-							profile: this.deps.profile,
-							epochMs: decision.snapMs
-						}));
-						locateCalls += 1;
-						locateMs = (locateMs ?? 0) + (performance.now() - snapStartMs);
-						if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
-						if (snapped.kind !== "segment") {
-							if (!this.scrubNoFootageLogged) {
-								this.scrubNoFootageLogged = true;
-								this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
-							}
-							return;
-						}
-						this.deps.onLog?.("scrub-feeder:snapped", {
-							requestedMs: target,
-							snappedMs: decision.snapMs
+				const cfg = this.deps.scrubDeadline;
+				const rideWindowMs = cfg?.rideWindowMs ?? SCRUB_RIDE_WINDOW_MS;
+				const inFlight = this.scrubResolve;
+				let entry;
+				if (inFlight !== null && (Math.abs(target - inFlight.target) <= rideWindowMs || this.scrubResolvesInFlight >= SCRUB_RESOLVE_MAX_INFLIGHT)) {
+					entry = inFlight;
+					this.scrubStats?.recordResolveJoin();
+				} else {
+					const leadMs = this.scrubLeadMs();
+					if (leadMs !== 0) this.scrubStats?.recordLead(leadMs);
+					const readTarget = target + leadMs;
+					entry = {
+						target: readTarget,
+						promise: this.startScrubResolve(readTarget, gen)
+					};
+					this.scrubResolve = entry;
+				}
+				const deadlineMs = this.scrubPushedThisDrag ? cfg?.tickMs ?? SCRUB_TICK_DEADLINE_MS : cfg?.firstTickMs ?? SCRUB_FIRST_TICK_DEADLINE_MS;
+				const res = await this.raceDeadline(entry.promise, performance.now() + deadlineMs);
+				if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
+				if (res === "deadline") {
+					this.scrubStats?.recordDeadlineMiss();
+					if (this.scrubPendingEpochMs === null) this.scrubPendingEpochMs = target;
+					if (!this.scrubDeadlineLogged) {
+						this.scrubDeadlineLogged = true;
+						this.deps.onLog?.("scrub-feeder:deadline-miss", {
+							epochMs: target,
+							deadlineMs,
+							first: !this.scrubPushedThisDrag,
+							inFlight: this.scrubResolvesInFlight
 						});
-						loc = snapped;
-						effTarget = decision.snapMs;
 					}
-					seg = this.scrubCache.covering(this.deps.profile, effTarget);
-					if (!seg) {
-						const load = await this.loadScrubFragment(loc, effTarget);
-						if (this.disposed || !this.scrubbing || gen !== this.scrubToken || load === null) return;
-						seg = load.seg;
-						readMs = load.readMs;
-						readBytes = load.readBytes;
-						demuxMs = load.demuxMs;
-						wholeSegmentRead = load.wholeSegmentRead;
-						this.scrubCache.put(this.deps.profile, seg);
-					}
-				} finally {
-					this.scrubTickReadInFlight = false;
+					return;
 				}
+				if (res === null) return;
+				seg = res.seg;
+				const newest = this.scrubPendingEpochMs;
+				if (res.effTarget !== res.requested) effTarget = res.effTarget;
+				else if (newest !== null && fragmentCovers(seg, newest)) {
+					effTarget = newest;
+					hint = this.scrubPendingHint;
+					this.scrubPendingEpochMs = null;
+					this.scrubPendingHint = null;
+				} else effTarget = newest ?? target;
+				if (effTarget !== res.effTarget) this.scrubStats?.recordRetarget();
+				locateCalls = res.locateCalls;
+				locateMs = res.locateMs;
+				readMs = res.readMs;
+				readBytes = res.readBytes;
+				demuxMs = res.demuxMs;
+				wholeSegmentRead = res.wholeSegmentRead;
 			}
 			this.scrubSegment = seg;
 			const prevTarget = this.scrubPrevTarget;
@@ -25266,6 +25450,7 @@ var RecordedFeeder = class {
 				pushedAtMs
 			}];
 			this.scrubCredit -= 1;
+			this.scrubPushedThisDrag = true;
 			this.armScrubAckTimeout();
 			this.clockHasAdvanced = true;
 			let runBytes = 0;
@@ -25327,6 +25512,107 @@ var RecordedFeeder = class {
 		}
 	}
 	/**
+	* ONE fragment resolution for the drag: locate (with gap snapping), read,
+	* demux, cache. Deliberately NOT bound to the tick that started it.
+	*
+	* The tick races this with the frame's deadline and may walk away; this
+	* promise then finishes on its own and puts the fragment in the session
+	* cache, because the read is already on the wire and abandoning its RESULT
+	* as well would turn a dropped frame into wasted disk. That is what makes
+	* the deadline cheap: the tick after a miss is usually a cache hit.
+	*
+	* Null ⇒ nothing to serve (dead zone, superseded generation, or a load the
+	* seek token invalidated). Throws propagate to the tick's `tick-failed`.
+	*/
+	async startScrubResolve(target, gen) {
+		this.scrubResolvesInFlight += 1;
+		this.scrubTickReadInFlight = true;
+		let locateCalls = 0;
+		let locateMs = null;
+		try {
+			this.maybeRecenterScrubWarm(target);
+			const locateStartMs = performance.now();
+			let loc = await this.withTimeout(this.deps.locate({
+				deviceId: this.deps.deviceId,
+				profile: this.deps.profile,
+				epochMs: target
+			}));
+			locateCalls += 1;
+			locateMs = performance.now() - locateStartMs;
+			this.maybeLogSlowLocate(target, locateMs);
+			if (this.disposed || gen !== this.scrubToken) return null;
+			let effTarget = target;
+			if (loc.kind === "gap") {
+				const decision = resolveSnapTarget(loc, target);
+				if (decision.kind !== "snap") {
+					if (!this.scrubNoFootageLogged) {
+						this.scrubNoFootageLogged = true;
+						if (decision.kind === "too-far") this.deps.onLog?.("scrub-feeder:snap-too-far", {
+							epochMs: target,
+							nearestMs: decision.snapMs,
+							distanceMs: decision.distanceMs
+						});
+						else this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
+					}
+					return null;
+				}
+				const snapStartMs = performance.now();
+				const snapped = await this.withTimeout(this.deps.locate({
+					deviceId: this.deps.deviceId,
+					profile: this.deps.profile,
+					epochMs: decision.snapMs
+				}));
+				locateCalls += 1;
+				locateMs = (locateMs ?? 0) + (performance.now() - snapStartMs);
+				if (this.disposed || gen !== this.scrubToken) return null;
+				if (snapped.kind !== "segment") {
+					if (!this.scrubNoFootageLogged) {
+						this.scrubNoFootageLogged = true;
+						this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
+					}
+					return null;
+				}
+				this.deps.onLog?.("scrub-feeder:snapped", {
+					requestedMs: target,
+					snappedMs: decision.snapMs
+				});
+				loc = snapped;
+				effTarget = decision.snapMs;
+			}
+			const warm = this.scrubCache.covering(this.deps.profile, effTarget);
+			if (warm) return {
+				seg: warm,
+				requested: target,
+				effTarget,
+				locateCalls,
+				locateMs,
+				readMs: null,
+				readBytes: null,
+				demuxMs: null,
+				wholeSegmentRead: false
+			};
+			const load = await this.loadScrubFragment(loc, effTarget);
+			if (this.disposed || load === null) return null;
+			this.scrubCache.put(this.deps.profile, load.seg);
+			if (gen !== this.scrubToken) return null;
+			return {
+				seg: load.seg,
+				requested: target,
+				effTarget,
+				locateCalls,
+				locateMs,
+				readMs: load.readMs,
+				readBytes: load.readBytes,
+				demuxMs: load.demuxMs,
+				wholeSegmentRead: load.wholeSegmentRead
+			};
+		} finally {
+			this.scrubResolvesInFlight -= 1;
+			if (this.scrubResolvesInFlight === 0) this.scrubTickReadInFlight = false;
+			if (this.scrubResolve?.target === target) this.scrubResolve = null;
+		}
+	}
+	/**
 	* Index of the nearest AU at-or-before the drag target within `seg`
 	* (default 0 — the fragment's params-fused IDR, which the demux contract
 	* guarantees). `keyframesOnly` restricts the pick to sync frames — the JUMP
@@ -25419,7 +25705,20 @@ var RecordedFeeder = class {
 	*/
 	readsWholeSegment(loc) {
 		if (this.deps.profile !== SCRUB_WHOLE_SEGMENT_PROFILE) return false;
-		return loc.bytes === void 0 || loc.bytes <= SCRUB_WHOLE_SEGMENT_MAX_BYTES;
+		if (loc.bytes === void 0 || loc.bytes <= SCRUB_WHOLE_SEGMENT_MAX_BYTES) return true;
+		this.scrubStats?.recordOversizeSegment();
+		if (!this.scrubOversizeLogged) {
+			this.scrubOversizeLogged = true;
+			this.deps.onLog?.("scrub-feeder:oversize-segment", {
+				profile: this.deps.profile,
+				startMs: loc.startMs,
+				durMs: loc.durMs,
+				bytes: loc.bytes,
+				maxBytes: SCRUB_WHOLE_SEGMENT_MAX_BYTES,
+				bytesPerSecond: loc.durMs > 0 ? Math.round(loc.bytes / (loc.durMs / 1e3)) : null
+			});
+		}
+		return false;
 	}
 	/**
 	* Fold one read into the recent-read window that governs speculation. The
@@ -25430,15 +25729,84 @@ var RecordedFeeder = class {
 		this.scrubReadMsWindow = [...this.scrubReadMsWindow, readMs].slice(-5);
 	}
 	/**
-	* Is the disk the problem right now? Median of the recent reads against
+	* A drag that is NOT on the scrub profile runs with every scrub optimisation
+	* off: the whole-segment read unit, the 48 MB fragment-cache budget and the
+	* entry warm are all gated on the exact string `low`
+	* ({@link SCRUB_WHOLE_SEGMENT_PROFILE}). A momentary hole in `low` therefore
+	* turns a drag into 3-seek GOP reads over ~5 MB `high` segments — measured at
+	* 2 642 ms cold — and the client cannot repair it.
+	*
+	* It used to be indistinguishable from a slow disk. Now it says so, once per
+	* drag, and the census carries the flag beside the numbers it explains.
+	*/
+	reportProfileDegradation() {
+		if (this.deps.profile === SCRUB_WHOLE_SEGMENT_PROFILE) return;
+		this.scrubStats?.recordProfileDegraded(this.deps.profile);
+		if (this.scrubProfileLogged) return;
+		this.scrubProfileLogged = true;
+		this.deps.onLog?.("scrub-feeder:profile-degraded", {
+			profile: this.deps.profile,
+			scrubProfile: SCRUB_WHOLE_SEGMENT_PROFILE
+		});
+	}
+	/**
+	* Median of the recent reads — what a read costs on this disk RIGHT NOW.
+	* Null until there are enough samples to call it anything: a single cold
+	* first read is not a median, and acting on it would aim a whole gesture.
+	*/
+	scrubReadMedianMs() {
+		if (this.scrubReadMsWindow.length < SCRUB_LEAD_MIN_READ_SAMPLES) return null;
+		const sorted = this.scrubReadMsWindow.toSorted((a, b) => a - b);
+		return sorted[Math.floor(sorted.length / 2)] ?? null;
+	}
+	/**
+	* Is the disk the problem right now? The recent-read median against
 	* {@link SCRUB_SLOW_READ_MS}. Median and not mean because one slow read is
 	* noise and the decision must not swing on it; and never before a few
 	* samples, or a cold first read would suppress the whole drag.
 	*/
 	scrubReadsAreSlow() {
-		if (this.scrubReadMsWindow.length < 3) return false;
-		const sorted = this.scrubReadMsWindow.toSorted((a, b) => a - b);
-		return (sorted[Math.floor(sorted.length / 2)] ?? 0) >= (this.deps.slowReadMs ?? SCRUB_SLOW_READ_MS);
+		const median = this.scrubReadMedianMs();
+		if (median === null) return false;
+		return median >= (this.deps.slowReadMs ?? SCRUB_SLOW_READ_MS);
+	}
+	/**
+	* Fold one pointer sample into the drag's media velocity (ms of timeline per
+	* ms of wall clock, signed). Cheap on purpose: this runs at pointer rate.
+	*/
+	noteScrubSample(epochMs) {
+		const now = performance.now();
+		const prev = this.scrubLastSampleMs;
+		const prevAt = this.scrubLastSampleAtMs;
+		this.scrubLastSampleMs = epochMs;
+		this.scrubLastSampleAtMs = now;
+		if (prev === null) return;
+		const gapMs = now - prevAt;
+		if (gapMs < SCRUB_VELOCITY_MIN_GAP_MS || gapMs > SCRUB_VELOCITY_MAX_GAP_MS) return;
+		const deltaMs = epochMs - prev;
+		const dir = Math.sign(deltaMs);
+		if (dir === 0) {
+			this.scrubVelRun = 0;
+			return;
+		}
+		this.scrubVelRun = Math.sign(this.scrubVelRun) === dir ? this.scrubVelRun + dir : dir;
+		const v = deltaMs / gapMs;
+		this.scrubVelocity = this.scrubVelocity === null ? v : this.scrubVelocity * (1 - SCRUB_VELOCITY_EMA) + v * SCRUB_VELOCITY_EMA;
+	}
+	/**
+	* How far AHEAD of the finger this read should aim — see the
+	* {@link SCRUB_LEAD_MIN_READ_SAMPLES} docblock for why this exists and what
+	* bounds it. Zero whenever the prediction is not earned: no measured reads,
+	* no sustained direction, or a velocity whose sign disagrees with the run.
+	*/
+	scrubLeadMs() {
+		const velocity = this.scrubVelocity;
+		if (velocity === null) return 0;
+		if (Math.abs(this.scrubVelRun) < SCRUB_LEAD_MIN_DIR_RUN) return 0;
+		if (Math.sign(velocity) !== Math.sign(this.scrubVelRun)) return 0;
+		const readMs = this.scrubReadMedianMs();
+		if (readMs === null) return 0;
+		return Math.round(velocity * readMs);
 	}
 	/**
 	* A single slow `locate` gets its own line, throttled per drag. Reserved for
@@ -26163,6 +26531,14 @@ var RecordedFeeder = class {
 		this.scrubCursor = null;
 		this.scrubNoFootageLogged = false;
 		this.scrubParkLogged = false;
+		this.scrubDeadlineLogged = false;
+		this.scrubOversizeLogged = false;
+		this.scrubProfileLogged = false;
+		this.scrubPushedThisDrag = false;
+		this.scrubResolve = null;
+		this.scrubVelocity = null;
+		this.scrubLastSampleMs = null;
+		this.scrubVelRun = 0;
 		this.scrubOutstanding = [];
 		this.clearScrubAckTimeout();
 		this.scrubPendingHint = null;