@camstack/addon-pipeline 1.2.287 → 1.2.290

package/dist/stream-broker/index.js

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-DiLFfaYv.js");
-const require_node = require("../node-Beq3CXsJ.js");
+const require_dist = require("../dist-BIlnUdBn.js");
+const require_node = require("../node-CVlJhqng.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
-const require_segment_demux_js = require("../segment-demux-js-Cd4K5AFm.js");
+const require_segment_demux_js = require("../segment-demux-js-D0mqN4RC.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -26564,6 +26564,22 @@ function gapReachable(gap, epochMs) {
 }
 //#endregion
 //#region src/stream-broker/recorded/control-protocol.ts
+/**
+* The rates a clip may be OFFERED at — re-exported from the capability, which
+* is where the one list lives (D612). The broker owns the clamp; the cap owns
+* the ladder; a second list here would be the second authority D62 forbids.
+*
+* Declared at the top of the file because the clamp and the `setRate` bound
+* are DERIVED from its ends (D621). They were three literals — this array, a
+* `Math.min(4, …)` and a `.max(4)` — and that is precisely how 8 and 16 came
+* to be offered while the clamp served 4 with no line anywhere saying so. One
+* decision now has one place to be written down.
+*/
+var BROKER_PACED_RATES = require_dist.CLIP_BROKER_PACED_RATES;
+/** The slowest offered rate. Anything slower is clamped up to it. */
+var MIN_PACED_RATE = Math.min(...BROKER_PACED_RATES);
+/** The fastest offered rate. Anything faster is refused at the wire. */
+var MAX_PACED_RATE = Math.max(...BROKER_PACED_RATES);
 var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	require_dist.object({
 		t: require_dist.literal("playRecorded"),
@@ -26630,7 +26646,7 @@ var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	}),
 	require_dist.object({
 		t: require_dist.literal("setRate"),
-		rate: require_dist.number().min(0).max(4)
+		rate: require_dist.number().min(0).max(MAX_PACED_RATE)
 	}),
 	require_dist.object({
 		t: require_dist.literal("stepFrame"),
@@ -26643,14 +26659,40 @@ var ControlMessageSchema = require_dist.discriminatedUnion("t", [
 	})
 ]);
 /**
-* Clamp a requested playback rate onto the supported domain: {0} ∪ [0.25, 4].
-* 0 (and any non-finite / non-positive input) pauses; anything else is a
-* continuous rate clamped into [0.25, 4]. Single server-side authority — the
-* feeder applies it to every inbound `setRate`.
+* Clamp a requested playback rate onto the supported domain:
+* {0} ∪ [{@link MIN_PACED_RATE}, {@link MAX_PACED_RATE}] — the ends of
+* {@link BROKER_PACED_RATES} itself. 0 (and any non-finite / non-positive
+* input) pauses; anything else is a continuous rate clamped into that band.
+* Single server-side authority — the feeder applies it to every inbound
+* `setRate`.
+*
+* That every ladder entry survives this unchanged is now structural rather
+* than a discipline. What is NOT structural, and is therefore the gate that
+* matters, is whether the pacer really empties a clip `rate` times faster:
+* `clip-stream-feeder.spec` drives every entry and measures it.
 */
 function clampPlaybackRate(rate) {
 	if (!Number.isFinite(rate) || rate <= 0) return 0;
-	return Math.min(4, Math.max(.25, rate));
+	return Math.min(MAX_PACED_RATE, Math.max(MIN_PACED_RATE, rate));
+}
+/**
+* Does a clip carry SOUND at this rate?
+*
+* ONE predicate, read by the branch that DROPS the audio
+* (`ClipStreamFeeder.pushNextAudio`) and by the branch that TELLS the viewer
+* why it is silent — because a second copy of `rate !== 1` is exactly the
+* disagreeing second switch D62 forbids, and the telling would then be able
+* to describe a drop that did not happen (or miss one that did).
+*
+* *"L'audio non serve in velocità non 1x!!!"* — the operator, 2026-09-23.
+* Resampling would need a decoder this path has not got, and pitch-shifted
+* sound is worse than none.
+*
+* Rate 0 is PAUSE, not a rate: nothing plays at all there, so it is not this
+* predicate's business and callers hold their last non-zero rate instead.
+*/
+function audioPlaysAtRate(rate) {
+	return rate === 1;
 }
 var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 	require_dist.object({
@@ -26693,12 +26735,12 @@ var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 		durationMs: require_dist.number().positive()
 	}),
 	require_dist.object({
-		t: require_dist.literal("clipTransport"),
+		t: require_dist.literal("clipIncomplete"),
 		clipId: require_dist.string().min(1),
-		/** `forward` = only ahead of the playhead. `free` = anywhere. */
-		seek: require_dist._enum(["forward", "free"]),
-		/** Frame-step BACKWARD is meaningful. Forward always is. */
-		stepBack: require_dist.boolean()
+		code: require_dist._enum(["stream-short", "stream-empty"]),
+		/** The provider's own sentence, already Latin-1 safe. Shown where the
+		*  stream error is shown. */
+		reason: require_dist.string().min(1)
 	}),
 	require_dist.object({
 		t: require_dist.literal("clipAudio"),
@@ -26712,8 +26754,23 @@ var ServerMessageSchema = require_dist.discriminatedUnion("t", [
 			"no-audio-track",
 			"unsupported-codec",
 			"codec-mismatch",
-			"stream-failed"
-		]).optional()
+			"stream-failed",
+			"rate"
+		]).optional(),
+		/**
+		* The rate the sound is suppressed AT. Present iff `reason` is `rate`,
+		* and refused otherwise — see the check below.
+		*/
+		rate: require_dist.number().positive().optional()
+	}).check((ctx) => {
+		const value = ctx.value;
+		if (value.reason === "rate" === (value.rate !== void 0)) return;
+		ctx.issues.push({
+			code: "custom",
+			message: "`rate` is present exactly when `reason` is `rate`",
+			input: value,
+			path: ["rate"]
+		});
 	})
 ]);
 function parseControlMessage(raw) {
@@ -27685,7 +27742,7 @@ var RecordedFeeder = class {
 	/** Audio clock (PCMU 8 kHz / Opus 48 kHz); re-anchored together with video. */
 	audioClock;
 	clockHasAdvanced = false;
-	/** Playback rate: 0 (paused) or a continuous factor in [0.25, 4]. */
+	/** Playback rate: 0 (paused) or a continuous factor in [0.25, 8]. */
 	rate = 1;
 	disposed = false;
 	seekToken = 0;
@@ -28266,7 +28323,7 @@ var RecordedFeeder = class {
 	}
 	/**
 	* Set playback rate. 0 pauses in place (the pacing loop aborts on its next
-	* guard check); any other value is clamped to [0.25, 4].
+	* guard check); any other value is clamped to [0.25, 8].
 	*
 	* Rate-change strategy (documented choice): every transition TO a non-zero
 	* rate — resume from pause AND a playing→playing rate change — re-enters via
@@ -30131,58 +30188,102 @@ var TimelineSession = class {
 		this.lastPositionMs = null;
 		const feeder = this.enterRecorded();
 		await feeder.seek(offsetMs);
-		this.reportClipTransport(clipId, feeder);
-		await Promise.all([this.reportClipDuration(clipId, feeder), this.reportClipAudio(clipId, feeder)]);
+		await Promise.all([
+			this.reportClipDuration(clipId, feeder),
+			this.reportClipAudio(clipId, feeder),
+			this.reportClipIncomplete(clipId, feeder)
+		]);
 	}
 	/**
-	* Tell the viewer what this clip can be driven to do.
+	* Tell the viewer whether this clip has sound.
 	*
-	* A clip served from the provider's stream is forward-only; one fetched as
-	* a file is not. Without the answer the viewer draws the same progress bar
-	* for both, and on the stream a backward drag is refused and the position
-	* re-sent — a control that visibly undoes the operator's gesture, which
-	* reads as broken rather than as unavailable (D62).
+	* Silence has causes the operator cannot tell apart by listening — a camera
+	* with no microphone, a transport that carried no audio, a session that
+	* negotiated none, and (D621) a clip playing at anything but 1×, where the
+	* broker drops every frame on purpose — so the viewer is told which. Every
+	* branch that sends nothing says so (D391): a feeder that cannot answer, an
+	* answer that rejected, and an answer that landed after the pointer had left
+	* the clip, which must not be pinned on whatever came next.
 	*
-	* A feeder that does not say sends nothing: silence is "the freedom you
-	* always had", and claiming `free` for a feeder that never answered would
-	* be this surface inventing a capability.
+	* The first answer SETTLES; the rate does not, so this also subscribes for
+	* as long as the clip is on the pointer.
 	*/
-	reportClipTransport(clipId, feeder) {
-		const report = feeder.transport;
-		if (report === void 0) {
-			this.deps.onLog?.("clip playback: transport not reported — this feeder cannot say", {
+	async reportClipAudio(clipId, feeder) {
+		if (feeder.audio === void 0) {
+			this.deps.onLog?.("clip playback: audio not reported — this feeder cannot say", {
 				deviceId: this.deps.deviceId,
 				clipId
 			});
 			return;
 		}
-		if (this.clip?.clipId !== clipId) return;
-		this.deps.onLog?.("clip playback: transport reported", {
+		let report;
+		try {
+			report = await feeder.audio();
+		} catch (err) {
+			this.deps.onLog?.("clip playback: audio not reported — the answer failed", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return;
+		}
+		this.sendClipAudio(clipId, report);
+		feeder.watchAudio?.((later) => this.sendClipAudio(clipId, later));
+	}
+	/**
+	* Send one `clipAudio`, or say why nothing was sent.
+	*
+	* ONE place, for the settle and for every later change: they are the same
+	* statement about the same clip, and a second builder is how the two would
+	* come to disagree about what `reason` means. The clip-identity guard lives
+	* here too — a report that lands after the pointer has left names a clip
+	* nobody is playing, and the viewer would mute whatever came next.
+	*/
+	sendClipAudio(clipId, report) {
+		if (this.clip?.clipId !== clipId) {
+			this.deps.onLog?.("clip playback: audio dropped — the pointer has left this clip", {
+				deviceId: this.deps.deviceId,
+				clipId,
+				carried: report.carried,
+				reason: report.reason
+			});
+			return;
+		}
+		this.deps.onLog?.("clip playback: audio reported", {
 			deviceId: this.deps.deviceId,
 			clipId,
-			seek: report.seek,
-			stepBack: report.stepBack
+			carried: report.carried,
+			codec: report.codec,
+			reason: report.reason,
+			rate: report.rate,
+			detail: report.detail
 		});
 		this.deps.session.sendControl(serializeServerMessage({
-			t: "clipTransport",
+			t: "clipAudio",
 			clipId,
-			seek: report.seek,
-			stepBack: report.stepBack
+			carried: report.carried,
+			...report.codec !== null ? { codec: report.codec } : {},
+			...report.reason !== null ? { reason: report.reason } : {},
+			...report.reason === "rate" && report.rate !== void 0 ? { rate: report.rate } : {}
 		}));
 	}
 	/**
-	* Tell the viewer whether this clip has sound.
+	* Tell the operator that the clip he is watching did not arrive whole
+	* (D623), in the surface that already shows him a stream error.
 	*
-	* Silence has three causes the operator cannot tell apart by listening —
-	* a camera with no microphone, a transport that carried no audio, and a
-	* session that negotiated none — so the viewer is told which. Every branch
-	* that sends nothing says so (D391): a feeder that cannot answer, an answer
-	* that rejected, and an answer that landed after the pointer had left the
-	* clip, which must not be pinned on whatever came next.
+	* Awaited AFTER the stream ends, which is when the provider gets to speak,
+	* and guarded by the clip identity for the same reason the audio report is:
+	* a late answer names a clip nobody is playing and the viewer would put the
+	* complaint on whatever came next.
+	*
+	* There is no retry here and there must not be one. *"Se cade la sessione
+	* cade non fa niente"* — the operator, 2026-09-23. A second dial would
+	* contend for the camera's single replay lane exactly while that lane is
+	* already failing.
 	*/
-	async reportClipAudio(clipId, feeder) {
-		if (feeder.audio === void 0) {
-			this.deps.onLog?.("clip playback: audio not reported — this feeder cannot say", {
+	async reportClipIncomplete(clipId, feeder) {
+		if (feeder.incomplete === void 0) {
+			this.deps.onLog?.("clip playback: completeness not reported — this feeder cannot ask the provider", {
 				deviceId: this.deps.deviceId,
 				clipId
 			});
@@ -30190,37 +30291,35 @@ var TimelineSession = class {
 		}
 		let report;
 		try {
-			report = await feeder.audio();
+			report = await feeder.incomplete();
 		} catch (err) {
-			this.deps.onLog?.("clip playback: audio not reported — the answer failed", {
+			this.deps.onLog?.("clip playback: completeness not reported — the answer failed", {
 				deviceId: this.deps.deviceId,
 				clipId,
 				error: err instanceof Error ? err.message : String(err)
 			});
 			return;
 		}
+		if (report === null) return;
 		if (this.clip?.clipId !== clipId) {
-			this.deps.onLog?.("clip playback: audio dropped — the pointer has left this clip", {
+			this.deps.onLog?.("clip playback: completeness dropped — the pointer has left this clip", {
 				deviceId: this.deps.deviceId,
 				clipId,
-				carried: report.carried
+				code: report.code
 			});
 			return;
 		}
-		this.deps.onLog?.("clip playback: audio reported", {
+		this.deps.onLog?.("clip playback: the clip did not arrive whole", {
 			deviceId: this.deps.deviceId,
 			clipId,
-			carried: report.carried,
-			codec: report.codec,
-			reason: report.reason,
-			detail: report.detail
+			code: report.code,
+			reason: report.reason
 		});
 		this.deps.session.sendControl(serializeServerMessage({
-			t: "clipAudio",
+			t: "clipIncomplete",
 			clipId,
-			carried: report.carried,
-			...report.codec !== null ? { codec: report.codec } : {},
-			...report.reason !== null ? { reason: report.reason } : {}
+			code: report.code,
+			reason: report.reason
 		}));
 	}
 	/**
@@ -30807,7 +30906,7 @@ function createRefusedClipFeeder(deps) {
 	};
 	return {
 		seek: async () => refuse("seek"),
-		setRate: () => {},
+		setRate: () => refuse("setRate"),
 		stepFrame: () => refuse("stepFrame"),
 		beginScrub: () => refuse("beginScrub"),
 		scrubTo: () => {},
@@ -31622,7 +31721,7 @@ function createFmp4StreamDemuxer(options = {}) {
 *   faster than the camera sends.
 * - `stepFrame(-1)` and the scrub verbs are refused by name; `stepFrame(+1)`
 *   pushes the next buffered unit.
-* - `setRate` is the PLAYER's rate over frames already here ({0} ∪ [0.25, 4],
+* - `setRate` is the PLAYER's rate over frames already here ({0} ∪ [0.25, 8],
 *   the recorded domain). The camera's own `playSpeed` (8, 16 — real, the app
 *   reopens the replay at 8) is a different mechanism and is NOT wired: it
 *   would go on the dial (`videoclips.dialClipStream` → the cmd-5 replay's
@@ -31688,6 +31787,11 @@ function createFmp4StreamDemuxer(options = {}) {
 * `data`, which the broker's `onLog` puts in `tags`.
 */
 /**
+* The reason an in-flight open is abandoned, carried on the abort so the
+* opener's refusal and the provider's log line say the same thing.
+*/
+var CLIP_STREAM_ABANDONED = "clip-stream-abandoned";
+/**
 * The same ceiling as the file path (`CLIP_SOURCE_MAX_BYTES`): a clip the
 * file path would refuse `too-large` is one this path stops taking. Frames
 * behind the head are released as they are pushed, so the backlog is the
@@ -31708,18 +31812,10 @@ function createClipStreamFeeder(deps) {
 }
 var ClipStreamFeeder = class {
 	deps;
-	/**
-	* Forward-only, and no backward frame-step: the bytes behind the head were
-	* never kept, and the camera offers no replay-from-offset. Stated here so
-	* the viewer can DISABLE those verbs rather than offer them and have every
-	* use refused — the whole content of this report.
-	*/
-	transport = {
-		seek: "forward",
-		stepBack: false
-	};
 	phase = "idle";
 	connection = null;
+	/** Armed for the length of one `open()`; aborted by {@link teardown}. */
+	opening = null;
 	demuxer;
 	clock = new MonotonicClock();
 	/** The RTP rate the audio sender negotiated — a CONVERSION, not a clock. */
@@ -31732,10 +31828,28 @@ var ClipStreamFeeder = class {
 	audioPushed = 0;
 	audioDroppedLate = 0;
 	audioDroppedRate = 0;
+	/**
+	* The last report handed to a caller — the settle promise's value, or the
+	* newest one {@link watchAudio}'s listener was given. What a change is
+	* measured against, so the same answer is never announced twice.
+	*/
+	audioEmitted = null;
+	/**
+	* The last NON-ZERO rate. Pause is the absence of a rate, not a rate: a
+	* `clipAudio` blaming the speed while the clip is stopped would be false,
+	* and un-pausing would have to take it back.
+	*/
+	audioRate = 1;
+	audioListener = null;
 	audioDroppedSeek = 0;
 	firstAudioLogged = false;
 	audioReport = null;
 	audioWaiters = [];
+	/** The provider's last word, and whether it has been given. Settled is not
+	*  the same as non-null: a whole stream settles `null` (D623). */
+	incompleteSettled = false;
+	incompleteReport = null;
+	incompleteWaiters = [];
 	clockHasAdvanced = false;
 	rate = 1;
 	queue = [];
@@ -31758,6 +31872,8 @@ var ClipStreamFeeder = class {
 	lastAnnounced = null;
 	scrubRefusedFor = void 0;
 	pushed = 0;
+	/** How many times the pacer wanted a frame the stream had not produced. */
+	starved = 0;
 	dropped = 0;
 	bytesIn = 0;
 	dialedAt = null;
@@ -31765,12 +31881,16 @@ var ClipStreamFeeder = class {
 	firstFrameLogged = false;
 	maxBufferedBytes;
 	stallTimeoutMs;
+	prerollMs;
+	/** True while the pacer is waiting for the cushion to refill after a starve. */
+	rebuffering = false;
 	now;
 	tags;
 	constructor(deps) {
 		this.deps = deps;
 		this.maxBufferedBytes = deps.maxBufferedBytes ?? CLIP_STREAM_BUFFER_MAX_BYTES;
 		this.stallTimeoutMs = deps.stallTimeoutMs ?? 15e3;
+		this.prerollMs = deps.prerollMs ?? 600;
 		this.now = deps.now ?? (() => Date.now());
 		this.tags = {
 			deviceId: deps.handle.deviceId,
@@ -31853,6 +31973,11 @@ var ClipStreamFeeder = class {
 	}
 	setRate(rate) {
 		const next = clampPlaybackRate(rate);
+		if (next !== rate) this.log("clip-stream:rate-not-delivered", {
+			requested: rate,
+			applied: next,
+			deliverable: BROKER_PACED_RATES
+		});
 		if (next === 0) {
 			this.rate = 0;
 			this.stopPacing();
@@ -31863,6 +31988,8 @@ var ClipStreamFeeder = class {
 		this.clock.setRate(next);
 		const wasPaused = this.rate === 0;
 		this.rate = next;
+		this.audioRate = next;
+		this.refreshAudioReport();
 		if (this.phase !== "streaming" || this.pendingSeekMs !== null) return;
 		if (wasPaused) this.emitState("playing", "set-rate-resume", this.seekToken);
 		this.startPacing();
@@ -31897,6 +32024,19 @@ var ClipStreamFeeder = class {
 		return new Promise((resolve) => this.durationWaiters.push(resolve));
 	}
 	/**
+	* Did the provider deliver this clip whole? (D623)
+	*
+	* Resolves `null` for a whole stream AND for one that never got to say —
+	* cut, disposed, or opened against a provider that adds no trailer. Both are
+	* "nothing to tell the operator", and neither may be reported as a defect:
+	* a cut already announces itself as `state: error`, and inventing a second
+	* complaint for it would file one fault twice.
+	*/
+	incomplete() {
+		if (this.incompleteSettled) return Promise.resolve(this.incompleteReport);
+		return new Promise((resolve) => this.incompleteWaiters.push(resolve));
+	}
+	/**
 	* What this clip turned out to carry as sound — the answer the viewer needs
 	* to say "this clip has no audio" rather than leave the operator wondering.
 	*
@@ -31906,15 +32046,31 @@ var ClipStreamFeeder = class {
 	*/
 	audio() {
 		const settled = this.audioReport;
-		if (settled !== null) return Promise.resolve(settled);
+		if (settled !== null) return Promise.resolve(this.audioNow(settled));
 		return new Promise((resolve) => this.audioWaiters.push(resolve));
 	}
+	/**
+	* Follow the audio answer for as long as this clip is on the pointer.
+	*
+	* {@link audio} settles ONCE, because what the stream carries is decided
+	* once — at the `moov`. The RATE is not: it moves under the operator's
+	* finger, and a one-shot report cannot say that the clip which had sound a
+	* second ago is silent now because he pressed 2×. The listener is told only
+	* when the answer really changes, never the settle it already awaited.
+	*
+	* One listener, replaced rather than added to: there is one session behind
+	* one clip, and a list would outlive the pointer.
+	*/
+	watchAudio(listener) {
+		this.audioListener = listener;
+	}
 	dispose() {
 		if (this.phase === "disposed") return;
 		const before = this.phase;
 		this.phase = "disposed";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -31985,13 +32141,15 @@ var ClipStreamFeeder = class {
 				audioReason: answer.audioReason ?? null
 			});
 		}
+		const abandon = new AbortController();
+		this.opening = abandon;
 		let opened;
 		try {
 			opened = await this.deps.open(answer.url, {
 				onData: (chunk) => this.onData(chunk),
-				onEnd: () => this.onEnd(),
+				onEnd: (report) => this.onEnd(report),
 				onError: (err) => this.cut("stream-failed", err.message)
-			});
+			}, abandon.signal);
 		} catch (err) {
 			opened = {
 				kind: "refused",
@@ -32000,8 +32158,15 @@ var ClipStreamFeeder = class {
 				detail: describe(err)
 			};
 		}
+		if (this.opening === abandon) this.opening = null;
 		if (this.phase !== "opening") {
 			if (opened.kind === "open") opened.connection.destroy();
+			this.log("clip-stream:open-abandoned", {
+				phase: this.phase,
+				opened: opened.kind,
+				sinceDialMs: this.now() - (this.dialedAt ?? this.now()),
+				...opened.kind === "refused" ? { code: opened.code } : {}
+			});
 			return;
 		}
 		if (opened.kind === "refused") {
@@ -32021,6 +32186,7 @@ var ClipStreamFeeder = class {
 		this.phase = "refused";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -32142,14 +32308,29 @@ var ClipStreamFeeder = class {
 			return;
 		}
 		while (this.rate === 0 && this.pendingSteps > 0 && this.pushNext()) this.pendingSteps -= 1;
-		if (this.rate > 0 && this.paceTimer === null) this.tick();
+		if (this.rate === 0) return;
+		if (this.rebuffering) {
+			if (this.cushionShortfallMs() > 0) return;
+			this.rebuffering = false;
+			this.log("clip-stream:refilled", {
+				headMs: this.headMs,
+				arrivedMs: this.arrivedMs,
+				queued: this.queue.length,
+				starved: this.starved
+			});
+			this.startPacing();
+			return;
+		}
+		if (this.paceTimer === null) this.tick();
 	}
-	onEnd() {
+	onEnd(report) {
 		if (!this.takesBytes()) return;
+		this.settleIncomplete(report);
 		this.streamEnded = true;
 		this.clearStall();
 		this.streamEnd = this.demuxer.end();
 		this.log("clip-stream:ended", {
+			starved: this.starved,
 			samples: this.streamEnd.samples,
 			durationMs: this.streamEnd.durationMs,
 			bytesIn: this.bytesIn,
@@ -32162,13 +32343,20 @@ var ClipStreamFeeder = class {
 			this.resolvePendingSeek(this.seekToken);
 			return;
 		}
-		if (this.rate > 0 && this.paceTimer === null) this.tick();
+		if (this.rate === 0) return;
+		if (this.rebuffering || this.anchorWall > this.now()) {
+			this.rebuffering = false;
+			this.startPacing();
+			return;
+		}
+		if (this.paceTimer === null) this.tick();
 	}
 	cut(reason, detail) {
 		if (this.phase !== "streaming" && this.phase !== "opening") return;
 		this.phase = "cut";
 		this.teardown();
 		this.settleDuration(null);
+		this.settleIncomplete(null);
 		this.settleAudio({
 			carried: false,
 			codec: null,
@@ -32302,9 +32490,24 @@ var ClipStreamFeeder = class {
 		this.audioQueue = this.audioQueue.slice(drop);
 		this.audioDroppedSeek += drop;
 	}
+	/**
+	* How much of the cushion is MISSING, in milliseconds of media.
+	*
+	* Zero once the stream has ended — there is nothing more coming, so waiting
+	* for it would hang the clip — and zero for any source that already holds
+	* more than the cushion, which is every fast one.
+	*/
+	cushionShortfallMs() {
+		if (this.streamEnded) return 0;
+		const head = this.headMs;
+		const arrived = this.arrivedMs;
+		if (head === null || arrived === null) return this.prerollMs;
+		return Math.max(0, this.prerollMs - (arrived - head));
+	}
 	startPacing() {
 		this.stopPacing();
-		this.anchorWall = this.now();
+		const shortfall = this.cushionShortfallMs();
+		this.anchorWall = this.now() + shortfall;
 		this.anchorPts = this.headMs ?? this.queue[0]?.ptsMs ?? 0;
 		this.startPositionReports();
 		this.tick();
@@ -32329,6 +32532,10 @@ var ClipStreamFeeder = class {
 			const audio = this.audioQueue[0];
 			if (video === void 0 && audio === void 0) {
 				if (this.streamEnded) this.finish();
+				else {
+					this.rebuffering = true;
+					this.noteStarved();
+				}
 				return;
 			}
 			const takeVideo = video !== void 0 && (audio === void 0 || video.ptsMs <= audio.ptsMs);
@@ -32364,7 +32571,7 @@ var ClipStreamFeeder = class {
 		if (frame === void 0) return false;
 		this.audioQueue = this.audioQueue.slice(1);
 		this.audioQueuedBytes -= frame.data.byteLength;
-		if (this.rate !== 1) {
+		if (!audioPlaysAtRate(this.rate)) {
 			this.audioDroppedRate += 1;
 			return true;
 		}
@@ -32462,11 +32669,53 @@ var ClipStreamFeeder = class {
 			audioQueued: this.audioQueue.length
 		};
 	}
+	/** One-shot, like the duration beside it: the provider speaks once, at the
+	*  end of the body, and a cut settles `null` so nobody waits for ever. */
+	settleIncomplete(report) {
+		if (this.incompleteSettled) return;
+		this.incompleteSettled = true;
+		this.incompleteReport = report;
+		if (report !== null) this.log("clip-stream:incomplete", {
+			code: report.code,
+			reason: report.reason
+		});
+		for (const resolve of this.incompleteWaiters.splice(0)) resolve(report);
+	}
 	settleAudio(report) {
 		if (this.audioReport !== null) return;
 		this.audioReport = report;
+		const now = this.audioNow(report);
+		this.audioEmitted = now;
 		const waiters = this.audioWaiters.splice(0);
-		for (const resolve of waiters) resolve(report);
+		for (const resolve of waiters) resolve(now);
+	}
+	/**
+	* The audio answer AS IT STANDS — the stream's own settled fact, with the
+	* rate laid over it.
+	*
+	* The overlay only ever applies to a clip that really is carrying sound. A
+	* clip whose camera has no microphone is silent at 1× too, and replacing
+	* `no-audio-track` with `rate` would swap the true cause for a transient
+	* one and send the operator to the speed chip.
+	*/
+	audioNow(settled) {
+		if (!settled.carried || audioPlaysAtRate(this.audioRate)) return settled;
+		return {
+			carried: false,
+			codec: null,
+			reason: "rate",
+			rate: this.audioRate
+		};
+	}
+	/** Tell the listener when — and only when — the answer has actually moved. */
+	refreshAudioReport() {
+		const settled = this.audioReport;
+		if (settled === null) return;
+		const next = this.audioNow(settled);
+		const last = this.audioEmitted;
+		if (last !== null && last.reason === next.reason && last.rate === next.rate) return;
+		this.audioEmitted = next;
+		this.audioListener?.(next);
 	}
 	settleDuration(value) {
 		if (this.duration !== null) return;
@@ -32481,10 +32730,40 @@ var ClipStreamFeeder = class {
 		this.stopPacing();
 		this.stopPositionReports();
 		this.clearStall();
+		const opening = this.opening;
+		this.opening = null;
+		opening?.abort(/* @__PURE__ */ new Error(CLIP_STREAM_ABANDONED));
 		const connection = this.connection;
 		this.connection = null;
 		connection?.destroy();
 	}
+	/**
+	* The pacer asked for a frame the stream has not produced yet.
+	*
+	* **A branch that accepts work and produces nothing is the same branch as
+	* one that drops it** (D391), and this is the one that hid Hikvision's whole
+	* acceleration defect: an RTSP replay arrives at 1×, so a pacer set to 2×
+	* or 4× eats the queue faster than the socket fills it, stops, waits, and
+	* says nothing at all. The picture froze, the operator reported *"pare non
+	* funzionare"*, and the only line anywhere was the provider's `peer-stalled`
+	* ten seconds later — which names the wrong end of the pipe.
+	*
+	* ONE line per run, not one per starve. At rate 1 against a realtime source
+	* the queue legitimately empties between frames, so a line per occurrence is
+	* the storm that buries the line that matters; the count travels on the
+	* run's own end.
+	*/
+	noteStarved() {
+		this.starved += 1;
+		if (this.starved > 1) return;
+		this.log("clip-stream:starved", {
+			rate: this.rate,
+			headMs: this.headMs,
+			arrivedMs: this.arrivedMs,
+			bytesIn: this.bytesIn,
+			pushed: this.pushed
+		});
+	}
 	log(msg, data) {
 		this.deps.onLog?.(msg, {
 			...this.tags,
@@ -32495,6 +32774,62 @@ var ClipStreamFeeder = class {
 function describe(err) {
 	return err instanceof Error ? err.message : String(err);
 }
+//#endregion
+//#region src/stream-broker/recorded/clip-stream-http.ts
+/**
+* clip-stream-http — the `node:http` half of {@link ClipStreamOpener}.
+*
+* Dials the URL `videoclips.dialClipStream` handed back — plain HTTP on the
+* provider's own token-gated listener, never the hub's proxy (an addon holds
+* no user credential, and the hub proxy takes only those) — and turns the
+* response into what the feeder drives: `pause`/`resume`/`destroy` on the
+* socket and the three events.
+*
+* A status other than 200 is a REFUSAL, named by the provider's own headers
+* (`x-camstack-reason-code`, `x-camstack-reason`), never a stream of nothing.
+* A 200 that does not declare `x-camstack-clip-transport: forward-only` is
+* refused too: it means the URL is not the stream route, and playing a
+* progressive file through a forward-only feeder would look like it worked
+* until the first seek.
+*/
+/**
+* The codes a provider may add AFTER its body, and the only two this hop
+* carries onward.
+*
+* A stream's status line is spent on its first fragment, so a serve the camera
+* cut short has nothing left to say it with but a trailer — and a trailer this
+* reader did not know about would be read as a whole clip, which is the defect
+* D623 is about, one hop further out. Anything else a provider writes there is
+* ITS diagnostic and stays in ITS log: a viewer is shown what it can act on.
+*/
+var CARRIED_TRAILER_CODES = ["stream-short", "stream-empty"];
+function trailerText(trailers, name) {
+	const value = trailers[name];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* What the provider said about its own stream once the last byte was out.
+*
+* `null` for a stream that added nothing, which is a whole one — the absence
+* is the statement, and it is never read as "unknown". A code with no sentence
+* is still reported, with the code standing in for one: a consumer that
+* branches on the code must not lose the branch because the prose was dropped
+* by a proxy.
+*/
+function readClipStreamTrailers(trailers) {
+	const code = trailerText(trailers, require_dist.CLIP_STILL_REASON_CODE_HEADER);
+	if (code === void 0 || !CARRIED_TRAILER_CODES.includes(code)) return null;
+	return {
+		code: code === "stream-empty" ? "stream-empty" : "stream-short",
+		reason: trailerText(trailers, "x-camstack-reason") ?? code
+	};
+}
+/** The abort's reason, as a sentence the provider's log can be matched against. */
+function describeReason(reason) {
+	if (reason instanceof Error) return reason.message;
+	if (typeof reason === "string") return reason;
+	return "the clip stream was abandoned before it opened";
+}
 function headerText(res, name) {
 	const value = res.headers[name];
 	if (Array.isArray(value)) return value[0];
@@ -32502,14 +32837,26 @@ function headerText(res, name) {
 }
 function createHttpClipStreamOpener(options = {}) {
 	const headersTimeoutMs = options.headersTimeoutMs ?? 3e4;
-	return (url, handlers) => new Promise((resolve) => {
+	return (url, handlers, signal) => new Promise((resolve) => {
 		let settled = false;
+		let onAbort = null;
 		const settle = (value) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(timer);
+			if (onAbort !== null) signal.removeEventListener("abort", onAbort);
 			resolve(value);
 		};
+		const abandoned = () => ({
+			kind: "refused",
+			status: 0,
+			code: "abandoned",
+			detail: describeReason(signal.reason)
+		});
+		if (signal.aborted) {
+			resolve(abandoned());
+			return;
+		}
 		let target;
 		try {
 			target = new URL(url);
@@ -32538,7 +32885,16 @@ function createHttpClipStreamOpener(options = {}) {
 		const timer = setTimeout(() => {
 			req.destroy(/* @__PURE__ */ new Error(`no status line in ${headersTimeoutMs} ms`));
 		}, headersTimeoutMs);
+		onAbort = () => {
+			req.destroy(new Error(describeReason(signal.reason)));
+			settle(abandoned());
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
 		req.on("error", (err) => {
+			if (signal.aborted) {
+				settle(abandoned());
+				return;
+			}
 			settle({
 				kind: "refused",
 				status: 0,
@@ -32569,7 +32925,7 @@ function createHttpClipStreamOpener(options = {}) {
 				return;
 			}
 			res.on("data", (chunk) => handlers.onData(chunk));
-			res.on("end", () => handlers.onEnd());
+			res.on("end", () => handlers.onEnd(readClipStreamTrailers(res.trailers)));
 			res.on("error", (err) => handlers.onError(err));
 			settle({
 				kind: "open",
@@ -35904,8 +36260,8 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					clearTimeout(timer);
 				}
 			},
-			locateRecordedSegment: (args) => this.ctx.api.recording.locateSegment.query(args),
-			readRecordedSegmentBytes: async (args) => (await this.ctx.api.recording.readSegmentBytes.query(args)).data,
+			locateRecordedSegment: (args) => this.ctx.api.recordingArchive.locateSegment.query(args),
+			readRecordedSegmentBytes: async (args) => (await this.ctx.api.recordingArchive.readSegmentBytes.query(args)).data,
 			readClipBytes: async (args) => {
 				const res = await this.ctx.api.videoclips.readClipBytes.query({
 					deviceId: args.deviceId,
@@ -35938,7 +36294,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 			},
 			readRecordedGopBytes: async (args) => {
 				try {
-					return await this.ctx.api.recording.readGopBytes.query({
+					return await this.ctx.api.recordingArchive.readGopBytes.query({
 						deviceId: args.deviceId,
 						profile: args.profile,
 						startMs: args.startMs,
@@ -35953,7 +36309,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 						});
 					}
 					return {
-						data: (await this.ctx.api.recording.readSegmentBytes.query({
+						data: (await this.ctx.api.recordingArchive.readSegmentBytes.query({
 							deviceId: args.deviceId,
 							profile: args.profile,
 							startMs: args.startMs