@camstack/addon-pipeline 1.2.76 → 1.2.78

package/dist/stream-broker/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-CZLjObZZ.js");
+const require_dist = require("../dist-BdVCXl5n.js");
 const require_remote_restream = require("../remote-restream-BYbAsgUf.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_dist.__toESM(node_crypto, 1);
@@ -973,7 +973,93 @@ var DerivedStreamFeeder = class extends FfmpegPushReader {
 * deleted, and with it the two hacks this module needed to bend it into shape:
 * a sink-retargeting string surgery on the tail of the arg list, and a fake
 * `inputFormat` chosen only to defeat smart-copy.
+*
+* ## The audio rule, and the outage that wrote it
+*
+* A derived stream is a self-contained MPEG-TS, so its audio must travel
+* IN-BAND — `passthrough` (`-an`, right for WebRTC, where werift carries audio
+* out of band) silently drops the track. That was fixed on 2026-07-17 by
+* remapping `passthrough` → `-c:a copy`, and the track stayed missing anyway,
+* because a copy has to survive TWO hops and it only clears the first:
+*
+*   1. the MPEG-TS MUXER. Measured with ffmpeg 7.1: a `pcm_mulaw` track copied
+*      into `-f mpegts` does not fail the invocation. ffmpeg logs
+*      `Stream 1, codec pcm_mulaw, is muxed as a private data stream and may
+*      not be recognized upon reading` and writes stream_type `0x06` — which
+*      is why the derived stream looked perfectly healthy: video never
+*      stopped;
+*   2. {@link MpegTsDemux}, which adopts an elementary audio PID only for
+*      stream_type `0x0f` (AAC) or `0x03`/`0x04` (MP2). `0x06` is not audio to
+*      it, so no audio packet was ever forwarded, `onAudioInfo` never fired,
+*      the derived broker never learned it had audio, and its probe read
+*      `audio: null` forever.
+*
+* Every camera in this fleet speaks G.711 (PCMU/PCMA), so the copy could never
+* work for any of them: no `derived:*` stream has EVER carried audio, and
+* camera 618 — whose `low` (motion, and therefore audio) profile is mapped to
+* a derived stream — went silent the day it was remapped.
+*
+* So the carrier decides, explicitly and loudly, not the profile: source audio
+* is COPIED when it is already AAC, and RE-ENCODED to AAC otherwise (including
+* when the source codec is unknown — the safe direction, since an unknown that
+* guesses `copy` mutes the camera). The decision is returned to the caller so
+* it can be logged per camera; it is never taken silently.
+*/
+/**
+* Audio codecs that survive BOTH hops of the derived carrier untouched: a
+* standard MPEG-TS stream type AND a stream type {@link MpegTsDemux} adopts.
+*
+* AAC only, deliberately. MP2 clears both hops as a container matter, but the
+* broker's push-audio path has no MP2 decode (`StreamBroker.pushAudioInfo` →
+* `buildAudioCodecSessionConfigFromPush` handles `aac`/`opus`), so a copied
+* MP2 track would arrive as an announced-but-undecodable stream — a second way
+* to be silent, with a track descriptor to make it look fine.
+*/
+var TS_COPYABLE_AUDIO_CODECS = new Set(["aac"]);
+/**
+* The AAC re-encode used when the source cannot be copied. Mono, and
+* deliberately WITHOUT a forced sample rate: a G.711 camera mic is 8 kHz, and
+* upsampling it to the 48 kHz camera preset would spend bitrate on nothing.
+* ffmpeg's native AAC encoder accepts 8 kHz, the ADTS header carries whatever
+* rate came out, and `parseAdtsAudioParams` reads it back for the broker.
+*/
+var DERIVED_AAC_RECODE = {
+	codec: "aac",
+	channels: 1
+};
+/** `true` when this profile audio means "carry whatever the source has". */
+function wantsSourceAudio(audio) {
+	return audio === "passthrough" || audio.codec === "copy";
+}
+/**
+* Decide the derived stream's audio from the profile's intent and the SOURCE's
+* observed codec. Pure; see this module's header for why `copy` is not the
+* default answer to "carry the source's audio".
+*
+* `sourceAudioCodec` is matched case-insensitively (`BrokerStats.audio.codec`
+* is upper-cased, SDP spellings are not).
 */
+function resolveDerivedAudio(profileAudio, sourceAudioCodec) {
+	if (!wantsSourceAudio(profileAudio)) return {
+		audio: profileAudio,
+		decision: { kind: "profile" }
+	};
+	const observed = sourceAudioCodec?.toLowerCase() ?? null;
+	if (observed !== null && TS_COPYABLE_AUDIO_CODECS.has(observed)) return {
+		audio: { codec: "copy" },
+		decision: {
+			kind: "copy",
+			sourceCodec: observed
+		}
+	};
+	return {
+		audio: DERIVED_AAC_RECODE,
+		decision: {
+			kind: "recode-aac",
+			sourceCodec: observed
+		}
+	};
+}
 /**
 * Build the ffmpeg argv that reads a source loopback RTSP url, transcodes it
 * per `profile`, and writes `-f mpegts pipe:1` (what the feeder's `MpegTsDemux`
@@ -982,37 +1068,33 @@ var DerivedStreamFeeder = class extends FfmpegPushReader {
 * Two things are specific to a derived stream and are expressed as first-class
 * builder inputs rather than post-hoc edits:
 *
-* - `forceReencode` — a derived stream ALWAYS applies its profile; that is its
-*   entire reason to exist. Without it the builder's smart-copy would elide
-*   the encode whenever the source already spoke the target codec. A `copy`
-*   profile still copies (a legitimate derived remux).
-* - audio `copy` in place of `passthrough` — a derived stream is a
-*   self-contained MPEG-TS, so its audio MUST travel in-band. `passthrough`
-*   means `-an`, which is right for WebRTC (werift carries audio out-of-band)
-*   but silently DROPS the track here.
-*
-* `decodeHwAccel` is threaded from the caller. It used to be hardcoded `null`;
-* the derived source is a local loopback restream, but decoding 4K in software
-* to re-encode it is exactly the cost the hub's working vaapi exists to avoid.
-* The caller resolves it through `resolveEgressDecodeHwAccel`, and the shared
-* `FfmpegProcess` retries in software — loudly — if the hardware child dies.
+* - `forceReencode` — a derived stream ALWAYS applies its video profile; that
+*   is its entire reason to exist. Without it the builder's smart-copy would
+*   elide the encode whenever the source already spoke the target codec. A
+*   `copy` profile still copies (a legitimate derived remux).
+* - the audio plan from {@link resolveDerivedAudio} in place of the profile's
+*   own — the MPEG-TS carrier, not the operator, decides whether the source
+*   track can be copied.
 */
-function buildDerivedTranscodeArgs(profile, loopbackUrl, decodeHwAccel = null) {
-	const audio = profile.audio === "passthrough" ? { codec: "copy" } : profile.audio;
-	return require_dist.buildFfmpegArgs(require_dist.invocationFromEncodeProfile({
-		profile: {
-			...profile,
-			audio
-		},
-		sourceCodec: "h264",
-		forceReencode: true,
-		sourceUrl: loopbackUrl,
-		sink: {
-			kind: "stdout",
-			container: "mpegts"
-		},
-		decodeHwAccel
-	}));
+function buildDerivedTranscodeArgs(input) {
+	const audio = resolveDerivedAudio(input.profile.audio, input.sourceAudioCodec);
+	return {
+		args: require_dist.buildFfmpegArgs(require_dist.invocationFromEncodeProfile({
+			profile: {
+				...input.profile,
+				audio: audio.audio
+			},
+			sourceCodec: "h264",
+			forceReencode: true,
+			sourceUrl: input.loopbackUrl,
+			sink: {
+				kind: "stdout",
+				container: "mpegts"
+			},
+			decodeHwAccel: input.decodeHwAccel ?? null
+		})),
+		audio
+	};
 }
 /**
 * Ceiling for a configured pre-roll.
@@ -17957,7 +18039,19 @@ var StreamBrokerManager = class StreamBrokerManager {
 			loopbackUrl = entry.url;
 			release = async () => {};
 		}
-		const args = buildDerivedTranscodeArgs(encodeProfile, loopbackUrl);
+		const sourceAudioCodec = this.observedSourceAudioCodec(deviceId, source);
+		const { args, audio } = buildDerivedTranscodeArgs({
+			profile: encodeProfile,
+			loopbackUrl,
+			sourceAudioCodec
+		});
+		if (audio.decision.kind === "recode-aac") this.logger.info("derived audio re-encoded to AAC — MPEG-TS cannot copy this source codec", {
+			tags: { deviceId },
+			meta: {
+				camStreamId,
+				sourceAudioCodec: audio.decision.sourceCodec ?? "unknown"
+			}
+		});
 		const feeder = new DerivedStreamFeeder({
 			ffmpegPath: this.ffmpegConfig.binaryPath,
 			args,
@@ -17992,6 +18086,21 @@ var StreamBrokerManager = class StreamBrokerManager {
 		};
 	}
 	/**
+	* The audio codec the derived stream's SOURCE broker has actually observed,
+	* or `null` when there is nothing to read (source not resolved, broker not
+	* created yet, cold dial, no audio track).
+	*
+	* Only ever an input to "can this track be COPIED into the derived MPEG-TS".
+	* `null` resolves to the AAC re-encode, so every failure of this read lands
+	* on the branch that still produces audible audio — the read can never mute
+	* a camera, which is the direction that cost 618 four silent days.
+	*/
+	observedSourceAudioCodec(deviceId, source) {
+		const camStreamId = source.kind === "camStream" ? source.camStreamId : this.assignments.get(deviceId)?.map[source.profile] ?? null;
+		if (camStreamId === null) return null;
+		return this.brokers.get(brokerIdFor(deviceId, camStreamId))?.getStats().audio?.codec ?? null;
+	}
+	/**
 	* Whether a stream is warmed BY DEFAULT (no explicit override): the device's
 	* `high` profile, on a non-battery camera, from a source that is worth
 	* keeping hot. Single source of truth used by both the broker-config default
@@ -22285,7 +22394,10 @@ var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 		m: require_dist._enum(["fine", "coarse"]).optional(),
 		v: require_dist.number().optional()
 	}),
-	require_dist.object({ t: require_dist.literal("scrubAck") }),
+	require_dist.object({
+		t: require_dist.literal("scrubAck"),
+		seq: require_dist.number().optional()
+	}),
 	require_dist.object({
 		t: require_dist.literal("warm"),
 		epoch: require_dist.number(),
@@ -22330,7 +22442,8 @@ var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 	}),
 	require_dist.object({
 		t: require_dist.literal("position"),
-		epochMs: require_dist.number()
+		epochMs: require_dist.number(),
+		seq: require_dist.number().optional()
 	}),
 	require_dist.object({
 		t: require_dist.literal("liveProfile"),
@@ -22426,11 +22539,19 @@ var MonotonicClock = class {
 		this.rate = rate;
 	}
 };
+var SCRUB_FRAGMENT_CACHE_MAX_BYTES = 2 * 1024 * 1024;
+/** Demuxed bytes an entry holds — what the byte bound actually counts. */
+function fragmentBytes(frag) {
+	let total = 0;
+	for (const au of frag.aus) total += au.data.length;
+	return total;
+}
 var ScrubFragmentCache = class {
-	max;
+	maxBytes;
 	map = /* @__PURE__ */ new Map();
-	constructor(max = 8) {
-		this.max = max;
+	bytes = 0;
+	constructor(maxBytes = SCRUB_FRAGMENT_CACHE_MAX_BYTES) {
+		this.maxBytes = maxBytes;
 	}
 	key(profile, startMs) {
 		return `${profile}|${startMs}`;
@@ -22461,17 +22582,26 @@ var ScrubFragmentCache = class {
 		}
 		return null;
 	}
-	/** Insert (or refresh) a fragment, evicting the oldest past the bound. */
+	/** Insert (or refresh) a fragment, evicting the oldest past the byte bound. */
 	put(profile, frag) {
 		const k = this.key(profile, frag.startMs);
+		const held = this.map.get(k);
+		if (held) this.bytes -= fragmentBytes(held);
 		this.map.delete(k);
 		this.map.set(k, frag);
-		while (this.map.size > this.max) {
+		this.bytes += fragmentBytes(frag);
+		while (this.bytes > this.maxBytes && this.map.size > 4) {
 			const oldest = this.map.keys().next().value;
 			if (oldest === void 0) break;
+			const evicted = this.map.get(oldest);
 			this.map.delete(oldest);
+			if (evicted) this.bytes -= fragmentBytes(evicted);
 		}
 	}
+	/** Demuxed bytes currently held — the number the MB bound governs. */
+	get byteSize() {
+		return this.bytes;
+	}
 	get size() {
 		return this.map.size;
 	}
@@ -22537,6 +22667,10 @@ var ScrubDragStats = class {
 	wholeReads = 0;
 	readBytes = 0;
 	parks = 0;
+	prefetchReads = 0;
+	prefetchBytes = 0;
+	prefetchHits = 0;
+	ackTimeouts = 0;
 	failures = 0;
 	firstPushMs = null;
 	creditEndedAt = null;
@@ -22583,6 +22717,19 @@ var ScrubDragStats = class {
 	recordPark() {
 		this.parks += 1;
 	}
+	/** One speculative GOP read and what it cost the disk. */
+	recordPrefetchRead(bytes) {
+		this.prefetchReads += 1;
+		this.prefetchBytes += bytes;
+	}
+	/** A tick served by a fragment speculation had already landed. */
+	recordPrefetchHit() {
+		this.prefetchHits += 1;
+	}
+	/** Pushes written off after the ack timeout — dropped work, never silent. */
+	recordAckTimeout(pushes) {
+		this.ackTimeouts += pushes;
+	}
 	/** A swallowed `scrubTick` throw — the branch where a dark failure hides. */
 	recordFailure() {
 		this.failures += 1;
@@ -22632,6 +22779,10 @@ var ScrubDragStats = class {
 			travel: this.travel,
 			bytes: this.bytes,
 			parks: this.parks,
+			prefetchReads: this.prefetchReads,
+			prefetchBytes: this.prefetchBytes,
+			prefetchHits: this.prefetchHits,
+			ackTimeouts: this.ackTimeouts,
 			failures: this.failures,
 			creditEndedAt: this.creditEndedAt,
 			acks: ack.n,
@@ -22726,6 +22877,24 @@ var SCRUB_JUMP_TRAVEL_MAX_STILLS = 3;
 */
 var SCRUB_PREFETCH_DIR_THRESHOLD = 2;
 /**
+* How many speculative GOP reads may be in flight at once, i.e. how many drag
+* steps ahead the feeder reads.
+*
+* The scrub tick IS the read: measured on salone 590 over `low`,
+* `tickMsP50 = 270` of which `readMsP50 = 263` — a cold ~135 KB fragment off
+* the HDD array through shfs/FUSE, `demuxMsP50 = 1`. One read at a time is a
+* hard ~3.8 push/s ceiling no cache can lift, because a drag whose steps are
+* tens of seconds apart revisits nothing. Reading N steps ahead is the only
+* thing that converts wall-clock the drag is ALREADY spending into pushes.
+*
+* 2 and not more: these reads land on the same spindles the recorder is writing
+* every camera to, and past a small number concurrent random reads stop
+* overlapping and start thrashing. Raise it only against a measured
+* `prefetchHits` / `readMsP50` pair — it is the knob, and the census carries
+* both halves of the evidence.
+*/
+var SCRUB_PREFETCH_MAX_INFLIGHT = 2;
+/**
 * Max forward TARGET delta (ms of timeline, between consecutive drag targets)
 * that SWEEPS predicted frames instead of jumping. A steady forward drag is
 * playback with a moving target: once a keyframe decoded, the predicted frames
@@ -22738,16 +22907,37 @@ var SCRUB_PREFETCH_DIR_THRESHOLD = 2;
 */
 var SCRUB_SWEEP_WINDOW_MS = 4e3;
 /**
-* Receiver-credit cap for scrub pushes: at most this many keyframes may be
-* OUTSTANDING (pushed onto the track but not yet acknowledged as RENDERED by
-* the viewer via `scrubAck`). The coalescing window above shapes the INPUT; on
-* a thin pipe it is not backpressure — pushing a ~45 KB keyframe every 60 ms
-* floods a link that delivers one every 500 ms, RTP drops, and nothing paints.
-* Backpressure is the receiver's: a push spends a credit, a rendered frame
-* restores one, and with zero credit the newest target PARKS on
-* `scrubPendingEpochMs` until an ack arrives — a timer never releases work.
+* 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
+* is not backpressure — pushing a ~45 KB keyframe every 60 ms floods a link
+* that delivers one every 500 ms, RTP drops, and nothing paints. Backpressure
+* is the receiver's: a push spends a credit, the first ack naming it restores
+* that credit, and with zero credit the newest target PARKS on
+* `scrubPendingEpochMs` until an ack (or {@link SCRUB_ACK_TIMEOUT_MS}) arrives.
+*
+* THE UNIT IS THE PUSH, NOT THE FRAME — and getting that wrong is what made a
+* slowed drag die. A push carries one AU in `jump` mode but a whole sweep (~25
+* AUs at 25 fps over a 1 s step) in `sweep` mode, while the viewer emits ONE
+* position per push. Charging one credit per push and repaying one per FRAME
+* meant two sweeps drained the cap against a viewer that could only ever send
+* two acks: the drag parked permanently at the exact moment the operator
+* slowed down to look at something.
 */
 var SCRUB_CREDIT_CAP = 2;
+/**
+* How long an outstanding push may go unacknowledged before the feeder writes
+* it off and takes its credit back.
+*
+* The credit gate is released by an ack and by nothing else — which is right
+* while acks flow and fatal when one is lost: the drag parks with no timer to
+* release it, and `beginScrub` (the only other reset) is a documented no-op
+* mid-drag. Generous on purpose: this is not pacing, it is the bound that
+* makes a lost ack cost one stalled tick instead of the rest of the gesture.
+* Every write-off is logged and counted (`ackTimeouts` on the drag census) —
+* dropped work is never silent.
+*/
+var SCRUB_ACK_TIMEOUT_MS = 2e3;
 /** Minimum gap between two lines of the same pathological kind, per drag. */
 var SCRUB_PATHOLOGY_LOG_INTERVAL_MS = 1e3;
 /**
@@ -22845,13 +23035,27 @@ var RecordedFeeder = class {
 	/** Remaining receiver credit for scrub pushes — see {@link SCRUB_CREDIT_CAP}. */
 	scrubCredit = SCRUB_CREDIT_CAP;
 	/**
-	* Frames still unrendered, per outstanding PUSH, oldest first. A jump enqueues
-	* `1`; a sweep enqueues however many predicted frames it put on the wire. Each
-	* `scrubAck` settles one frame off the head, and the credit that push spent
-	* comes back only when the head reaches zero — so a sweep cannot be refunded
-	* once per frame for the single credit it cost.
+	* The pushes on the wire and not yet settled, OLDEST FIRST (and therefore
+	* ascending in both `seq` and `pushedAtMs` — every settle and every write-off
+	* takes a prefix). One entry per push, whatever it carried: the first
+	* `scrubAck` naming it returns its credit.
 	*/
 	scrubOutstanding = [];
+	/**
+	* The push sequence the viewer echoes on `scrubAck`. Monotonic for the life of
+	* the feeder — see {@link OutstandingPush} for why it must NOT restart per
+	* drag.
+	*/
+	scrubPushSeq = 0;
+	/**
+	* The write-off timer for the oldest outstanding push
+	* ({@link SCRUB_ACK_TIMEOUT_MS}). Separate from `scrubTimer` on purpose: that
+	* one is the coalescing slot, and an ack arriving while this is pending must
+	* be able to schedule a leading-edge tick without waiting on it.
+	*/
+	scrubAckTimer = null;
+	/** One `scrub-feeder:ack-timeout` line per drag — the count is on the census. */
+	scrubAckTimeoutLogged = false;
 	/** The newest un-processed drag target (null when the tick cycle has drained). */
 	scrubPendingEpochMs = null;
 	/** The mapping hint that came with the newest target (latest-wins with it). */
@@ -22909,12 +23113,25 @@ var RecordedFeeder = class {
 	*/
 	scrubDirRun = 0;
 	/**
-	* The SECOND bounded concurrency slot: `true` while a direction-aware prefetch
-	* demux is in flight. At most one prefetch runs at a time and it only fills
-	* `scrubCache` — it never pushes, never touches the pending/timer/latest-wins
-	* state, and never blocks the live coalesced tick.
+	* Prefetch reads in flight. Bounded by {@link SCRUB_PREFETCH_MAX_INFLIGHT}:
+	* these are the SPECULATIVE concurrency slots, and they only fill
+	* `scrubCache` — they never push, never touch the pending/timer/latest-wins
+	* state, and never block the live coalesced tick.
+	*
+	* More than one because the read IS the tick (263 of 270 ms measured): with a
+	* single slot the drag can never go faster than one cold read, however well
+	* the speculation guesses.
+	*/
+	scrubPrefetchInFlight = 0;
+	/** Probe instants currently being read, so two horizons never duplicate one. */
+	scrubPrefetchProbes = /* @__PURE__ */ new Set();
+	/**
+	* Fragment starts this drag put in the cache SPECULATIVELY. A later tick that
+	* hits one of them is what makes speculation provably worth its I/O
+	* (`prefetchHits`) — without this the feeder could double the load on the disk
+	* that is the bottleneck and the census would look calm.
 	*/
-	scrubPrefetchInFlight = false;
+	scrubPrefetched = /* @__PURE__ */ new Set();
 	constructor(deps) {
 		this.deps = deps;
 		this.audioClock = new MonotonicClock(deps.audioClockRateHz ?? 8e3);
@@ -22952,6 +23169,7 @@ var RecordedFeeder = class {
 			this.scrubSegment = null;
 			this.scrubCursor = null;
 			this.scrubOutstanding = [];
+			this.clearScrubAckTimeout();
 			this.scrubPendingHint = null;
 			this.scrubPrevTarget = null;
 			this.scrubDirRun = 0;
@@ -23203,10 +23421,13 @@ var RecordedFeeder = class {
 		this.scrubCredit = SCRUB_CREDIT_CAP;
 		this.scrubPrevTarget = null;
 		this.scrubDirRun = 0;
+		this.scrubPrefetched = /* @__PURE__ */ new Set();
 		this.scrubCursor = null;
 		this.scrubNoFootageLogged = false;
 		this.scrubParkLogged = false;
 		this.scrubOutstanding = [];
+		this.clearScrubAckTimeout();
+		this.scrubAckTimeoutLogged = false;
 		this.scrubPendingHint = null;
 		this.scrubStartedAtMs = performance.now();
 		this.scrubStats = new ScrubDragStats(this.scrubStartedAtMs);
@@ -23233,28 +23454,97 @@ var RecordedFeeder = class {
 		if (this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
 	}
 	/**
-	* Receiver credit: the viewer RENDERED a scrub frame. Restores one push
-	* credit (capped — over-acking never banks a burst) and, when a target sat
-	* parked on an exhausted budget, resumes the tick. This — not any timer — is
-	* what paces scrub pushes to what the link actually delivers.
+	* Receiver credit: the viewer received a pushed scrub frame. Settles the push
+	* `seq` names — and every older one still outstanding, since the channel is
+	* ordered — restores their credit (capped: over-acking never banks a burst)
+	* and, when a target sat parked on an exhausted budget, resumes the tick.
+	* This — not any timer — is what paces scrub pushes to what the link
+	* actually delivers; {@link SCRUB_ACK_TIMEOUT_MS} is only the bound for when
+	* an ack never comes.
+	*
+	* THE UNIT IS THE PUSH. A sweep puts ~25 AUs on the wire under ONE position
+	* message, so a viewer without `requestVideoFrameCallback` can only ever send
+	* ONE ack for it; the old per-FRAME settle waited for 25 and the drag parked
+	* forever the moment the operator slowed down. A viewer WITH rvfc sends one
+	* ack per rendered frame instead — those surplus acks all name the same
+	* settled `seq` and are no-ops, which is what `seq` is for.
+	*
+	* A `seq` no outstanding push matches (a late ack from a drag that already
+	* ended) banks nothing. An ack without `seq` comes from a viewer older than
+	* the field: it settles the oldest outstanding push, which can only repay too
+	* early — never strand the drag.
 	*/
-	scrubAck() {
+	scrubAck(seq) {
 		if (this.disposed) return;
+		const settled = seq === void 0 ? this.scrubOutstanding.length > 0 ? 1 : 0 : this.scrubOutstanding.filter((p) => p.seq <= seq).length;
+		if (settled === 0) return;
+		const now = performance.now();
+		for (const push of this.scrubOutstanding.slice(0, settled)) this.scrubStats?.recordAckRtt(Math.round(now - push.pushedAtMs));
+		this.scrubOutstanding = this.scrubOutstanding.slice(settled);
+		this.scrubCredit = Math.min(SCRUB_CREDIT_CAP, this.scrubCredit + settled);
+		this.resumeScrubTick();
+	}
+	/**
+	* Resume a parked drag: the newest target is still pending and the coalescing
+	* slot is free, so run a leading-edge tick. Never touches a LIVE slot — a
+	* pending re-arm is this tick cycle's own coalescing window and pre-empting it
+	* would push faster than {@link SCRUB_COALESCE_MS}.
+	*/
+	resumeScrubTick() {
+		if (this.scrubbing && this.scrubPendingEpochMs !== null && this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
+	}
+	/**
+	* Arm the write-off timer for the OLDEST outstanding push, if one is not
+	* already pending. Newer entries are always due later, so a timer armed for
+	* an entry that gets settled first simply fires early and re-arms — one
+	* harmless wakeup, no bookkeeping.
+	*/
+	armScrubAckTimeout() {
+		if (this.scrubAckTimer !== null) return;
 		const head = this.scrubOutstanding[0];
 		if (head === void 0) return;
+		const dueInMs = Math.max(0, SCRUB_ACK_TIMEOUT_MS - (performance.now() - head.pushedAtMs));
+		this.scrubAckTimer = setTimeout(() => {
+			this.scrubAckTimer = null;
+			this.expireScrubAcks();
+		}, dueInMs);
+	}
+	/** Drop the ack timer (drag exit / teardown). */
+	clearScrubAckTimeout() {
+		if (this.scrubAckTimer === null) return;
+		clearTimeout(this.scrubAckTimer);
+		this.scrubAckTimer = null;
+	}
+	/**
+	* Write off every push that has waited longer than
+	* {@link SCRUB_ACK_TIMEOUT_MS}, give its credit back, and resume the drag.
+	*
+	* This is DROPPED WORK — a frame the viewer may never have painted — so it is
+	* counted on the census every time and logged once per drag. Without it a
+	* single lost ack ends the gesture: the gate is released by acks alone, and
+	* `beginScrub` (its only other reset) is a no-op mid-drag.
+	*/
+	expireScrubAcks() {
+		if (this.disposed || !this.scrubbing) return;
 		const now = performance.now();
-		if (head.firstAckAtMs === null) this.scrubStats?.recordAckRtt(Math.round(now - head.pushedAtMs));
-		if (head.frames > 1) {
-			this.scrubOutstanding = [{
-				frames: head.frames - 1,
-				pushedAtMs: head.pushedAtMs,
-				firstAckAtMs: head.firstAckAtMs ?? now
-			}, ...this.scrubOutstanding.slice(1)];
-			return;
+		const expired = this.scrubOutstanding.filter((p) => now - p.pushedAtMs >= SCRUB_ACK_TIMEOUT_MS).length;
+		if (expired > 0) {
+			const frames = this.scrubOutstanding.slice(0, expired).reduce((sum, p) => sum + p.frames, 0);
+			this.scrubOutstanding = this.scrubOutstanding.slice(expired);
+			this.scrubCredit = Math.min(SCRUB_CREDIT_CAP, this.scrubCredit + expired);
+			this.scrubStats?.recordAckTimeout(expired);
+			if (!this.scrubAckTimeoutLogged) {
+				this.scrubAckTimeoutLogged = true;
+				this.deps.onLog?.("scrub-feeder:ack-timeout", {
+					pushes: expired,
+					frames,
+					timeoutMs: SCRUB_ACK_TIMEOUT_MS,
+					pendingEpochMs: this.scrubPendingEpochMs
+				});
+			}
+			this.resumeScrubTick();
 		}
-		this.scrubOutstanding = this.scrubOutstanding.slice(1);
-		this.scrubCredit = Math.min(SCRUB_CREDIT_CAP, this.scrubCredit + 1);
-		if (this.scrubbing && this.scrubPendingEpochMs !== null && this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
+		this.armScrubAckTimeout();
 	}
 	/**
 	* One coalesced feeder-scrub push. Captures the newest pending target + the
@@ -23307,7 +23597,10 @@ var RecordedFeeder = class {
 				coverage = "memo";
 			} else {
 				seg = this.scrubCache.covering(this.deps.profile, target);
-				if (seg) coverage = "cache";
+				if (seg) {
+					coverage = "cache";
+					if (this.scrubPrefetched.has(seg.startMs)) this.scrubStats?.recordPrefetchHit();
+				}
 			}
 			if (!seg) {
 				const locateStartMs = performance.now();
@@ -23427,12 +23720,14 @@ var RecordedFeeder = class {
 			else if (crossesFragment && this.clockHasAdvanced) this.clock.markSeek();
 			for (const au of aus) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
 			const pushedAtMs = performance.now();
+			const pushSeq = ++this.scrubPushSeq;
 			this.scrubOutstanding = [...this.scrubOutstanding, {
+				seq: pushSeq,
 				frames: jumpTravel.length + aus.length,
-				pushedAtMs,
-				firstAckAtMs: null
+				pushedAtMs
 			}];
 			this.scrubCredit -= 1;
+			this.armScrubAckTimeout();
 			this.clockHasAdvanced = true;
 			let runBytes = 0;
 			for (const s of jumpTravel) runBytes += s.au.data.length;
@@ -23479,7 +23774,7 @@ var RecordedFeeder = class {
 					tickMs: Math.round(pushedAtMs - tickStartMs)
 				});
 			}
-			this.deps.onPosition(this.clampIntoSegment(seg, effTarget));
+			this.deps.onPosition(this.clampIntoSegment(seg, effTarget), pushSeq);
 			this.maybeScrubPrefetch(seg, effTarget, gen);
 		} catch (err) {
 			this.scrubStats?.recordFailure();
@@ -23727,28 +24022,41 @@ var RecordedFeeder = class {
 			this.scrubDirRun = 0;
 			return;
 		}
-		const dir = target > prev ? 1 : target < prev ? -1 : 0;
+		const stepMs = target - prev;
+		const dir = stepMs > 0 ? 1 : stepMs < 0 ? -1 : 0;
 		if (dir === 0) {
 			this.scrubDirRun = 0;
 			return;
 		}
 		this.scrubDirRun = Math.sign(this.scrubDirRun) === dir ? this.scrubDirRun + dir : dir;
 		if (Math.abs(this.scrubDirRun) < SCRUB_PREFETCH_DIR_THRESHOLD) return;
-		if (this.scrubPrefetchInFlight) return;
-		const probeMs = dir === 1 ? seg.startMs + seg.durMs + 1 : seg.startMs - 1;
-		if (probeMs < 0) return;
-		this.scrubPrefetch(probeMs, gen);
+		const aheadMs = Math.max(Math.abs(stepMs), seg.durMs + 1);
+		const horizons = Math.abs(stepMs) > seg.durMs ? SCRUB_PREFETCH_MAX_INFLIGHT : 1;
+		for (let horizon = 1; horizon <= horizons; horizon++) {
+			if (this.scrubPrefetchInFlight >= SCRUB_PREFETCH_MAX_INFLIGHT) return;
+			const probeMs = target + dir * aheadMs * horizon;
+			if (probeMs < 0) continue;
+			if (this.scrubPrefetchProbes.has(probeMs)) continue;
+			if (this.scrubCache.covering(this.deps.profile, probeMs)) continue;
+			this.scrubPrefetch(probeMs, gen);
+		}
 	}
 	/**
-	* Background (second-slot) prefetch: locate + read + demux the fragment
-	* covering `probeMs` into `scrubCache`. Bounded to one in flight; aborts at any
+	* Speculative read: locate + read + demux the fragment covering `probeMs` into
+	* `scrubCache`. Bounded by {@link SCRUB_PREFETCH_MAX_INFLIGHT}; aborts at any
 	* teardown (`disposed` / left scrub / a bumped `scrubToken`); a failure is
-	* swallowed (the neighbour just demuxes on demand). Never pushes and never
+	* swallowed (the fragment just demuxes on demand). Never pushes and never
 	* mutates latest-wins state.
+	*
+	* Every read it issues is COUNTED (`prefetchReads` / `prefetchBytes`), and the
+	* fragment it lands is remembered so a later tick hitting it counts as a
+	* `prefetchHit`. Speculation that cannot be shown to pay for itself is just
+	* load on the disk the drag is already waiting for.
 	*/
 	async scrubPrefetch(probeMs, gen) {
-		if (this.scrubPrefetchInFlight) return;
-		this.scrubPrefetchInFlight = true;
+		if (this.scrubPrefetchInFlight >= SCRUB_PREFETCH_MAX_INFLIGHT) return;
+		this.scrubPrefetchInFlight += 1;
+		this.scrubPrefetchProbes.add(probeMs);
 		try {
 			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
 			if (this.scrubCache.covering(this.deps.profile, probeMs)) return;
@@ -23761,9 +24069,12 @@ var RecordedFeeder = class {
 			if (loc.kind !== "segment") return;
 			const load = await this.loadScrubFragment(loc, probeMs);
 			if (this.disposed || !this.scrubbing || gen !== this.scrubToken || load === null) return;
+			this.scrubStats?.recordPrefetchRead(load.readBytes);
 			this.scrubCache.put(this.deps.profile, load.seg);
+			this.scrubPrefetched.add(load.seg.startMs);
 		} catch {} finally {
-			this.scrubPrefetchInFlight = false;
+			this.scrubPrefetchInFlight -= 1;
+			this.scrubPrefetchProbes.delete(probeMs);
 		}
 	}
 	/**
@@ -24192,6 +24503,7 @@ var RecordedFeeder = class {
 		this.scrubNoFootageLogged = false;
 		this.scrubParkLogged = false;
 		this.scrubOutstanding = [];
+		this.clearScrubAckTimeout();
 		this.scrubPendingHint = null;
 		if (this.scrubTimer) {
 			clearTimeout(this.scrubTimer);
@@ -24271,7 +24583,7 @@ var TimelineSession = class {
 				break;
 			}
 			case "scrubAck":
-				if (this.mode === "recorded") this.feeder?.scrubAck();
+				if (this.mode === "recorded") this.feeder?.scrubAck(msg.seq);
 				break;
 			case "setRate":
 				this.rate = msg.rate;
@@ -24319,12 +24631,18 @@ var TimelineSession = class {
 			state
 		}));
 	}
-	/** Emit seam: the broker wires the feeder's onPosition callback to this. */
-	_emitPosition(epochMs) {
+	/** Emit seam: the broker wires the feeder's onPosition callback to this.
+	*  `pushSeq` rides along only on the position a scrub push emitted — the
+	*  viewer echoes it on `scrubAck` so the credit is repaid to the right push. */
+	_emitPosition(epochMs, pushSeq) {
 		this.lastPositionMs = epochMs;
-		this.deps.session.sendControl(serializeServerMessage({
+		this.deps.session.sendControl(serializeServerMessage(pushSeq === void 0 ? {
 			t: "position",
 			epochMs
+		} : {
+			t: "position",
+			epochMs,
+			seq: pushSeq
 		}));
 	}
 	emitLiveProfile() {
@@ -33002,7 +33320,7 @@ var BrokerWebrtcServer = class {
 							} });
 							timeline._emitState(s);
 						},
-						onPosition: (epochMs) => timeline._emitPosition(epochMs),
+						onPosition: (epochMs, pushSeq) => timeline._emitPosition(epochMs, pushSeq),
 						onLog: (msg, data) => sessionLogger.info(msg, {
 							tags: { deviceId },
 							meta: {