@camstack/addon-pipeline 1.2.237 → 1.2.239

package/dist/pipeline-runner/index.js

@@ -5791,19 +5791,27 @@ var PipelineRunner = class {
 			if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
 		});
 		const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
+		const preRollQueue = new PreRollLane({
+			capacity: this.config.maxPreRollQueueDepth ?? 12,
+			clone: ownDetectionEntry,
+			dispose: (entry) => {
+				if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
+				if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
+			}
+		});
+		this.logger?.info("camera registered: root detectors", {
+			tags: { deviceId },
+			meta: {
+				detectionSources: registration.detectionSources ?? null,
+				...planDetectionSources(registration.detectionSources)
+			}
+		});
 		const state = {
 			registration,
 			onboardSlot: null,
 			motionQueue,
 			detectionQueue,
-			preRollQueue: new PreRollLane({
-				capacity: this.config.maxPreRollQueueDepth ?? 12,
-				clone: ownDetectionEntry,
-				dispose: (entry) => {
-					if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
-					if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
-				}
-			}),
+			preRollQueue,
 			inferenceTimes: [],
 			shedFrames: 0,
 			inflight: 0,

package/dist/pipeline-runner/index.mjs

@@ -5783,19 +5783,27 @@ var PipelineRunner = class {
 			if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
 		});
 		const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
+		const preRollQueue = new PreRollLane({
+			capacity: this.config.maxPreRollQueueDepth ?? 12,
+			clone: ownDetectionEntry,
+			dispose: (entry) => {
+				if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
+				if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
+			}
+		});
+		this.logger?.info("camera registered: root detectors", {
+			tags: { deviceId },
+			meta: {
+				detectionSources: registration.detectionSources ?? null,
+				...planDetectionSources(registration.detectionSources)
+			}
+		});
 		const state = {
 			registration,
 			onboardSlot: null,
 			motionQueue,
 			detectionQueue,
-			preRollQueue: new PreRollLane({
-				capacity: this.config.maxPreRollQueueDepth ?? 12,
-				clone: ownDetectionEntry,
-				dispose: (entry) => {
-					if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
-					if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
-				}
-			}),
+			preRollQueue,
 			inferenceTimes: [],
 			shedFrames: 0,
 			inflight: 0,

package/dist/session-decode/decode-worker-child.js

@@ -1323,6 +1323,126 @@ function resolveRgbCropSource(plane, planeStride, region) {
 		stride: tightStride
 	};
 }
+var ADMITTED = { admitted: true };
+/**
+* Choose the media stride for one burst.
+*
+* `plannedFrames` is what the stride actually yields, so a caller can log the
+* intent next to the outcome — a budget that is never reached and a budget that
+* is always hit are different problems and used to read the same.
+*/
+function planPreRollBurst(input) {
+	const span = Number.isFinite(input.spanMs) && input.spanMs > 0 ? input.spanMs : 0;
+	const fps = Number.isFinite(input.detectionFps) && input.detectionFps > 0 ? input.detectionFps : 1;
+	const maxFrames = Number.isFinite(input.maxFrames) && input.maxFrames > 0 ? input.maxFrames : 0;
+	if (span === 0 || maxFrames === 0) return {
+		strideMs: Number.POSITIVE_INFINITY,
+		plannedFrames: 0,
+		subsampled: false
+	};
+	const cadenceMs = 1e3 / fps;
+	const budgetStrideMs = span / maxFrames;
+	const subsampled = budgetStrideMs > cadenceMs;
+	const strideMs = subsampled ? budgetStrideMs : cadenceMs;
+	return {
+		strideMs,
+		plannedFrames: Math.min(maxFrames, Math.max(1, Math.floor(span / strideMs))),
+		subsampled
+	};
+}
+/**
+* The live, per-session budget. Stateful by necessity — a stride is a decision
+* about the PREVIOUS admission — and deliberately free of any clock of its own:
+* both times are passed in, so a test can drive a catch-up burst without
+* pretending 4 s of media takes 4 s to decode.
+*/
+var PreRollBurst = class {
+	budget;
+	plan;
+	startedAtWall;
+	/** Widest lead a frame's moment took over the wall clock — the SERVED span. */
+	maxLeadMs = 0;
+	lastAdmittedMediaWall = null;
+	offered = 0;
+	inferred = 0;
+	done = false;
+	drops = {
+		stride: 0,
+		"budget-frames": 0,
+		"budget-wall-ms": 0,
+		"live-edge": 0
+	};
+	constructor(input) {
+		this.budget = input.budget;
+		this.plan = input.plan;
+		this.startedAtWall = input.startedAtWall;
+	}
+	/**
+	* How much history this burst actually carried, in ms of media — the number
+	* the broker knows as `preRollSpanMs` and that never reached this process.
+	*
+	* `null` until a frame has led the wall clock: a burst that saw none did not
+	* measure a short span, it measured NOTHING, and the difference is the whole
+	* reason the anchor was left alone rather than fabricated (D393).
+	*/
+	servedSpanMs() {
+		return this.maxLeadMs > 0 ? this.maxLeadMs : null;
+	}
+	/** True once the burst has ended — by budget, or by reaching the live edge. */
+	get finished() {
+		return this.done;
+	}
+	/**
+	* Offer one decoded history frame.
+	*
+	* `mediaWall` is the frame's OWN moment (see `media-clock.ts`); `nowWall` is
+	* the wall clock of the offer. The two are different by construction during
+	* catch-up, which is the whole reason this class exists.
+	*/
+	offer(mediaWall, nowWall) {
+		this.offered++;
+		if (this.done) return this.drop("budget-frames");
+		const leadMs = mediaWall - nowWall;
+		if (this.maxLeadMs > 0 && leadMs <= 100) {
+			this.done = true;
+			return this.drop("live-edge");
+		}
+		if (leadMs > this.maxLeadMs) this.maxLeadMs = leadMs;
+		if (nowWall - this.startedAtWall >= this.budget.maxWallMs) {
+			this.done = true;
+			return this.drop("budget-wall-ms");
+		}
+		if (this.inferred >= this.budget.maxFrames) {
+			this.done = true;
+			return this.drop("budget-frames");
+		}
+		if (this.lastAdmittedMediaWall !== null && mediaWall - this.lastAdmittedMediaWall < this.plan.strideMs) return this.drop("stride");
+		this.lastAdmittedMediaWall = mediaWall;
+		this.inferred++;
+		return ADMITTED;
+	}
+	/** End the burst without offering a frame (session torn down, decode ended). */
+	finish() {
+		this.done = true;
+	}
+	report() {
+		return {
+			offered: this.offered,
+			inferred: this.inferred,
+			dropped: this.offered - this.inferred,
+			droppedByReason: { ...this.drops },
+			strideMs: Math.round(this.plan.strideMs),
+			subsampled: this.plan.subsampled
+		};
+	}
+	drop(reason) {
+		this.drops[reason]++;
+		return {
+			admitted: false,
+			reason
+		};
+	}
+};
 //#endregion
 //#region src/session-decode/pull-demuxer-open.ts
 /**
@@ -1577,6 +1697,18 @@ var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
 var METRICS_INTERVAL_MS = 1e4;
 /**
+* Wall-clock ceiling on one pre-roll catch-up burst.
+*
+* A burst is a race against the live edge it is trying to get ahead of. Two
+* seconds in, the decoder has either caught up (the burst ended on its own) or
+* something is wrong — a cold GPU, a node under load, a camera whose GOP is
+* longer than its history — and continuing to spend inference on footage that
+* is now three or four seconds stale buys an operator nothing while a live
+* frame waits. The frame budget bounds the WORK; this bounds the WINDOW in
+* which that work is still worth doing.
+*/
+var PRE_ROLL_BURST_MAX_WALL_MS = 2e3;
+/**
 * Hard cap on the native-frame retention ring (native-res crop feature). Kept
 * DELIBERATELY TINY — its only job is to cover the detection→crop latency
 * (typically 1-4 frames), NOT the full shm ring depth. On the HW path every
@@ -3290,13 +3422,26 @@ var DecodeWorkerChild = class {
 		const ptsMs = this.frameMediaPtsMs(frame);
 		if (ptsMs === null) return now;
 		if (this.mediaClock === null || this.mediaClock.dialSeq !== this.dialSeq) {
-			const servedPreRollMs = 0;
-			if (this.preRollMs > 0) this.emitStderr(`[decode] pre-roll requested ${this.preRollMs}ms but the SERVED span does not reach this worker — burst suppressed, clock anchored at now (D411 follow-up)`);
 			this.mediaClock = mediaClockForDial(this.mediaClock, this.dialSeq, {
 				firstPtsMs: ptsMs,
-				preRollMs: servedPreRollMs,
+				preRollMs: 0,
 				nowWall: now
 			});
+			if (this.preRollMs > 0 && this.preRollMaxFrames > 0) {
+				const preRollCadenceMs = this.minIntervalMs > 0 ? this.minIntervalMs : 1e3;
+				this.preRollBurst = new PreRollBurst({
+					budget: {
+						maxFrames: this.preRollMaxFrames,
+						maxWallMs: PRE_ROLL_BURST_MAX_WALL_MS
+					},
+					plan: planPreRollBurst({
+						spanMs: this.preRollMaxFrames * preRollCadenceMs,
+						detectionFps: 1e3 / preRollCadenceMs,
+						maxFrames: this.preRollMaxFrames
+					}),
+					startedAtWall: now
+				});
+			}
 		}
 		return mediaWallClockOf(this.mediaClock.anchor, ptsMs, now);
 	}

package/dist/session-decode/decode-worker-child.mjs

@@ -1322,6 +1322,126 @@ function resolveRgbCropSource(plane, planeStride, region) {
 		stride: tightStride
 	};
 }
+var ADMITTED = { admitted: true };
+/**
+* Choose the media stride for one burst.
+*
+* `plannedFrames` is what the stride actually yields, so a caller can log the
+* intent next to the outcome — a budget that is never reached and a budget that
+* is always hit are different problems and used to read the same.
+*/
+function planPreRollBurst(input) {
+	const span = Number.isFinite(input.spanMs) && input.spanMs > 0 ? input.spanMs : 0;
+	const fps = Number.isFinite(input.detectionFps) && input.detectionFps > 0 ? input.detectionFps : 1;
+	const maxFrames = Number.isFinite(input.maxFrames) && input.maxFrames > 0 ? input.maxFrames : 0;
+	if (span === 0 || maxFrames === 0) return {
+		strideMs: Number.POSITIVE_INFINITY,
+		plannedFrames: 0,
+		subsampled: false
+	};
+	const cadenceMs = 1e3 / fps;
+	const budgetStrideMs = span / maxFrames;
+	const subsampled = budgetStrideMs > cadenceMs;
+	const strideMs = subsampled ? budgetStrideMs : cadenceMs;
+	return {
+		strideMs,
+		plannedFrames: Math.min(maxFrames, Math.max(1, Math.floor(span / strideMs))),
+		subsampled
+	};
+}
+/**
+* The live, per-session budget. Stateful by necessity — a stride is a decision
+* about the PREVIOUS admission — and deliberately free of any clock of its own:
+* both times are passed in, so a test can drive a catch-up burst without
+* pretending 4 s of media takes 4 s to decode.
+*/
+var PreRollBurst = class {
+	budget;
+	plan;
+	startedAtWall;
+	/** Widest lead a frame's moment took over the wall clock — the SERVED span. */
+	maxLeadMs = 0;
+	lastAdmittedMediaWall = null;
+	offered = 0;
+	inferred = 0;
+	done = false;
+	drops = {
+		stride: 0,
+		"budget-frames": 0,
+		"budget-wall-ms": 0,
+		"live-edge": 0
+	};
+	constructor(input) {
+		this.budget = input.budget;
+		this.plan = input.plan;
+		this.startedAtWall = input.startedAtWall;
+	}
+	/**
+	* How much history this burst actually carried, in ms of media — the number
+	* the broker knows as `preRollSpanMs` and that never reached this process.
+	*
+	* `null` until a frame has led the wall clock: a burst that saw none did not
+	* measure a short span, it measured NOTHING, and the difference is the whole
+	* reason the anchor was left alone rather than fabricated (D393).
+	*/
+	servedSpanMs() {
+		return this.maxLeadMs > 0 ? this.maxLeadMs : null;
+	}
+	/** True once the burst has ended — by budget, or by reaching the live edge. */
+	get finished() {
+		return this.done;
+	}
+	/**
+	* Offer one decoded history frame.
+	*
+	* `mediaWall` is the frame's OWN moment (see `media-clock.ts`); `nowWall` is
+	* the wall clock of the offer. The two are different by construction during
+	* catch-up, which is the whole reason this class exists.
+	*/
+	offer(mediaWall, nowWall) {
+		this.offered++;
+		if (this.done) return this.drop("budget-frames");
+		const leadMs = mediaWall - nowWall;
+		if (this.maxLeadMs > 0 && leadMs <= 100) {
+			this.done = true;
+			return this.drop("live-edge");
+		}
+		if (leadMs > this.maxLeadMs) this.maxLeadMs = leadMs;
+		if (nowWall - this.startedAtWall >= this.budget.maxWallMs) {
+			this.done = true;
+			return this.drop("budget-wall-ms");
+		}
+		if (this.inferred >= this.budget.maxFrames) {
+			this.done = true;
+			return this.drop("budget-frames");
+		}
+		if (this.lastAdmittedMediaWall !== null && mediaWall - this.lastAdmittedMediaWall < this.plan.strideMs) return this.drop("stride");
+		this.lastAdmittedMediaWall = mediaWall;
+		this.inferred++;
+		return ADMITTED;
+	}
+	/** End the burst without offering a frame (session torn down, decode ended). */
+	finish() {
+		this.done = true;
+	}
+	report() {
+		return {
+			offered: this.offered,
+			inferred: this.inferred,
+			dropped: this.offered - this.inferred,
+			droppedByReason: { ...this.drops },
+			strideMs: Math.round(this.plan.strideMs),
+			subsampled: this.plan.subsampled
+		};
+	}
+	drop(reason) {
+		this.drops[reason]++;
+		return {
+			admitted: false,
+			reason
+		};
+	}
+};
 //#endregion
 //#region src/session-decode/pull-demuxer-open.ts
 /**
@@ -1576,6 +1696,18 @@ var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
 var METRICS_INTERVAL_MS = 1e4;
 /**
+* Wall-clock ceiling on one pre-roll catch-up burst.
+*
+* A burst is a race against the live edge it is trying to get ahead of. Two
+* seconds in, the decoder has either caught up (the burst ended on its own) or
+* something is wrong — a cold GPU, a node under load, a camera whose GOP is
+* longer than its history — and continuing to spend inference on footage that
+* is now three or four seconds stale buys an operator nothing while a live
+* frame waits. The frame budget bounds the WORK; this bounds the WINDOW in
+* which that work is still worth doing.
+*/
+var PRE_ROLL_BURST_MAX_WALL_MS = 2e3;
+/**
 * Hard cap on the native-frame retention ring (native-res crop feature). Kept
 * DELIBERATELY TINY — its only job is to cover the detection→crop latency
 * (typically 1-4 frames), NOT the full shm ring depth. On the HW path every
@@ -3289,13 +3421,26 @@ var DecodeWorkerChild = class {
 		const ptsMs = this.frameMediaPtsMs(frame);
 		if (ptsMs === null) return now;
 		if (this.mediaClock === null || this.mediaClock.dialSeq !== this.dialSeq) {
-			const servedPreRollMs = 0;
-			if (this.preRollMs > 0) this.emitStderr(`[decode] pre-roll requested ${this.preRollMs}ms but the SERVED span does not reach this worker — burst suppressed, clock anchored at now (D411 follow-up)`);
 			this.mediaClock = mediaClockForDial(this.mediaClock, this.dialSeq, {
 				firstPtsMs: ptsMs,
-				preRollMs: servedPreRollMs,
+				preRollMs: 0,
 				nowWall: now
 			});
+			if (this.preRollMs > 0 && this.preRollMaxFrames > 0) {
+				const preRollCadenceMs = this.minIntervalMs > 0 ? this.minIntervalMs : 1e3;
+				this.preRollBurst = new PreRollBurst({
+					budget: {
+						maxFrames: this.preRollMaxFrames,
+						maxWallMs: PRE_ROLL_BURST_MAX_WALL_MS
+					},
+					plan: planPreRollBurst({
+						spanMs: this.preRollMaxFrames * preRollCadenceMs,
+						detectionFps: 1e3 / preRollCadenceMs,
+						maxFrames: this.preRollMaxFrames
+					}),
+					startedAtWall: now
+				});
+			}
 		}
 		return mediaWallClockOf(this.mediaClock.anchor, ptsMs, now);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-pipeline",
-  "version": "1.2.237",
+  "version": "1.2.239",
   "description": "Pipeline bundle — runner, detection, motion, audio + stream broker. Multi-entry npm package shipping pipeline addons under a single bundle.",
   "keywords": [
     "camstack",