@camstack/addon-pipeline 1.2.213 → 1.2.215

package/dist/pipeline-runner/index.js

@@ -2,14 +2,13 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-CyfP2nFh.js");
-const require_node = require("../node-CkBqyM-0.js");
-const require_default_detection_model = require("../default-detection-model-BZTjgdod.js");
-const require_worker_protocol = require("../worker-protocol-CYopQrkK.js");
+const require_dist = require("../dist-DoHcimdu.js");
+const require_node = require("../node-6uF72wri.js");
+const require_default_detection_model = require("../default-detection-model-f0PImZnh.js");
+const require_worker_protocol = require("../worker-protocol-BWO2WNjw.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
-const require_lazy_sharp = require("../lazy-sharp-BawPy_a9.js");
+const require_lazy_sharp = require("../lazy-sharp-BeeQGCUu.js");
 const require_restream_intent = require("../restream-intent-B1Difcnq.js");
-const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-DaUBcb13.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 let node_os = require("node:os");
 node_os = require_dist.__toESM(node_os);
@@ -18,6 +17,7 @@ let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 let node_url = require("node:url");
 let node_perf_hooks = require("node:perf_hooks");
+let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 //#region src/session-decode/fork-decode-worker.ts
 /** Absolute path to the built decode-worker child entry (a vite build entry). */
 var CHILD_ENTRY_PATH = (0, node_url.fileURLToPath)(new URL("../session-decode/decode-worker-child.js", require("url").pathToFileURL(__filename).href));
@@ -1010,6 +1010,7 @@ var SessionDecodeSession = class {
 	frameTimeoutMs;
 	firstFrameMaxWaitMs;
 	onDialTiming;
+	onPreRollReport;
 	pendingPull = null;
 	pendingToBuffers = /* @__PURE__ */ new Map();
 	/** Outstanding `nativeCrop` requests, keyed by the monotonic `requestId`. */
@@ -1023,7 +1024,7 @@ var SessionDecodeSession = class {
 	firstFrameReceived = false;
 	/** `Date.now()` of the FIRST `pull` — the origin of the cold-start ceiling. */
 	firstPullAt = 0;
-	constructor(child, logger, deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, onDialTiming) {
+	constructor(child, logger, deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, onDialTiming, onPreRollReport) {
 		this.child = child;
 		this.logger = logger;
 		this.deviceId = deviceId;
@@ -1031,6 +1032,7 @@ var SessionDecodeSession = class {
 		this.frameTimeoutMs = frameTimeoutMs;
 		this.firstFrameMaxWaitMs = firstFrameMaxWaitMs;
 		this.onDialTiming = onDialTiming;
+		this.onPreRollReport = onPreRollReport;
 		this.child.on("message", (m) => this.handleMessage(m));
 		this.child.on("exit", (m) => this.handleExit(toWorkerExitInfo(m)));
 	}
@@ -1221,6 +1223,17 @@ var SessionDecodeSession = class {
 					streamInfoProbed: raw.streamInfoProbed
 				});
 				return;
+			case "preRollReport":
+				this.onPreRollReport?.({
+					offered: raw.offered,
+					inferred: raw.inferred,
+					dropped: raw.dropped,
+					droppedByReason: raw.droppedByReason,
+					strideMs: raw.strideMs,
+					subsampled: raw.subsampled,
+					spanMs: raw.spanMs
+				});
+				return;
 		}
 	}
 	handleExit(info) {
@@ -1445,7 +1458,7 @@ function createSessionDecodeCoordinator(deps) {
 	const frameTimeoutMs = deps.frameTimeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;
 	const firstFrameMaxWaitMs = Math.max(deps.firstFrameMaxWaitMs ?? DEFAULT_FIRST_FRAME_MAX_WAIT_MS, firstFrameTimeoutMs);
 	return { async *generateVideoFrames(source, opts) {
-		const session = new SessionDecodeSession(deps.fork(source), deps.logger, source.deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, deps.onDialTiming);
+		const session = new SessionDecodeSession(deps.fork(source), deps.logger, source.deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, deps.onDialTiming, deps.onPreRollReport);
 		session.start(source, opts);
 		try {
 			while (true) {
@@ -1454,7 +1467,9 @@ function createSessionDecodeCoordinator(deps) {
 				const { reply } = outcome;
 				yield {
 					timestamp: reply.timestamp,
-					image: buildFrameImage(session, reply)
+					image: buildFrameImage(session, reply),
+					...reply.capturedAt !== void 0 ? { capturedAt: reply.capturedAt } : {},
+					...reply.preRoll === true ? { preRoll: true } : {}
 				};
 			}
 		} finally {
@@ -1468,10 +1483,18 @@ function createSessionDecodeCoordinator(deps) {
 * Build a {@link DecodedFrame} from one pulled {@link VideoFrame}. Downscales to
 * the detection working width (see {@link resolveWorkingResize}) so the ROI
 * scaler ships a small frame instead of the full source resolution.
-* `capturedAt` is set to `Date.now()` so downstream frameAge metrics diff
-* against the wall clock (mirrors the shm-ring source, which stamps commit
-* time) — this is what lets Step 5 MEASURE session-decode frameAge vs the
-* shm-ring cameras.
+* `capturedAt` is the frame's OWN moment: the worker's media clock when it has
+* one (`media-clock.ts`), else `Date.now()` as before, so downstream frameAge
+* metrics keep diffing against the wall clock (mirroring the shm-ring source,
+* which stamps commit time) — this is what lets Step 5 MEASURE session-decode
+* frameAge vs the shm-ring cameras.
+*
+* The fallback is deliberate and must stay: a `Date.now()` here for a frame
+* replayed out of ~4 s of retained history would date its detections, its
+* track's `firstSeen`, its media and the notification's instant at SESSION
+* OPEN. That is a silently wrong timestamp — nothing downstream can tell it
+* from a right one — and it is a worse failure than the late birth the pre-roll
+* pass exists to fix.
 */
 async function toDecodedFrame(frame, format, viewSpec) {
 	const geometry = viewSpec ? require_default_detection_model.resolveFrameViewGeometry(frame.image.width, frame.image.height, viewSpec) : void 0;
@@ -1486,7 +1509,8 @@ async function toDecodedFrame(frame, format, viewSpec) {
 		height: geometry?.output.height ?? frame.image.height,
 		format: viewSpec?.format ?? format,
 		timestamp: frame.timestamp,
-		capturedAt: Date.now()
+		capturedAt: frame.capturedAt ?? Date.now(),
+		...frame.preRoll === true ? { preRoll: true } : {}
 	};
 }
 /**
@@ -1507,7 +1531,8 @@ function startSessionDecodePump(deps) {
 			dialTiming = timing;
 		},
 		...deps.firstFrameTimeoutMs !== void 0 ? { firstFrameTimeoutMs: deps.firstFrameTimeoutMs } : {},
-		...deps.frameTimeoutMs !== void 0 ? { frameTimeoutMs: deps.frameTimeoutMs } : {}
+		...deps.frameTimeoutMs !== void 0 ? { frameTimeoutMs: deps.frameTimeoutMs } : {},
+		...deps.onPreRollReport ? { onPreRollReport: deps.onPreRollReport } : {}
 	}).generateVideoFrames(deps.source, deps.opts);
 	let stopped = false;
 	let releaseSpawnSlot = null;
@@ -1549,7 +1574,7 @@ function startSessionDecodePump(deps) {
 				}
 				let imageOwnershipTransferred = false;
 				try {
-					if (deps.shouldMaterializeFrame && !deps.shouldMaterializeFrame()) continue;
+					if (deps.shouldMaterializeFrame && !deps.shouldMaterializeFrame(frame.preRoll === true)) continue;
 					const image = frame.image;
 					const cropFn = image.nativeCrop;
 					const nativeCrop = cropFn ? Object.assign((bbox, maxWidth) => cropFn(bbox, maxWidth), {
@@ -1558,7 +1583,7 @@ function startSessionDecodePump(deps) {
 						markInferred: () => image.markInferred?.()
 					}) : void 0;
 					if (deps.frameRegistry && deps.onFrameRef && deps.inlineWhen?.() !== true) {
-						const capturedAt = Date.now();
+						const capturedAt = frame.capturedAt ?? Date.now();
 						const ref = deps.frameRegistry.register(image, {
 							timestamp: frame.timestamp,
 							capturedAt
@@ -1572,7 +1597,8 @@ function startSessionDecodePump(deps) {
 							format: ref.format,
 							timestamp: ref.timestamp,
 							capturedAt,
-							frameRef: ref
+							frameRef: ref,
+							...frame.preRoll === true ? { preRoll: true } : {}
 						};
 						try {
 							if (!await deps.onFrameRef(lazyFrame, nativeCrop)) deps.frameRegistry.release(ref, "drop");
@@ -2425,7 +2451,7 @@ var EMPTY_SAMPLE = {
 */
 function applyStallTick(sample, lateByMs, gcWindow, reportThresholdMs) {
 	if (lateByMs < reportThresholdMs) return sample;
-	const verdict = require_event_loop_stall_monitor.attributeStall(lateByMs, Math.round(gcWindow.totalMs), gcWindow.count, Math.round(gcWindow.longestMs));
+	const verdict = (0, _camstack_system_addon_utils.attributeStall)(lateByMs, Math.round(gcWindow.totalMs), gcWindow.count, Math.round(gcWindow.longestMs));
 	return {
 		count: sample.count + 1,
 		maxMs: Math.max(sample.maxMs, lateByMs),
@@ -4703,6 +4729,44 @@ function ownFrame(frame) {
 	};
 }
 //#endregion
+//#region src/pipeline-runner/pre-roll-lane.ts
+var PreRollLane = class {
+	items = [];
+	capacity;
+	clone;
+	dispose;
+	_refused = 0;
+	constructor(options) {
+		this.capacity = Math.max(0, options.capacity);
+		this.clone = options.clone;
+		this.dispose = options.dispose;
+	}
+	/** Append one entry. `false` ⇒ the lane is full and the caller must log it. */
+	enqueue(item) {
+		if (this.items.length >= this.capacity) {
+			this._refused++;
+			return false;
+		}
+		this.items.push(this.clone(item));
+		return true;
+	}
+	/** Oldest first — the point of the lane. */
+	dequeue() {
+		return this.items.shift();
+	}
+	get size() {
+		return this.items.length;
+	}
+	/** Entries refused because the lane was full, for the session's report line. */
+	get refused() {
+		return this._refused;
+	}
+	clear() {
+		for (const item of this.items) this.dispose?.(item);
+		this.items.length = 0;
+	}
+};
+//#endregion
 //#region src/pipeline-runner/semaphore.ts
 /**
 * Counting semaphore with FIFO waiter queue. Used by the runner to bound
@@ -5021,8 +5085,6 @@ var PipelineTimingSampler = class {
 		this.audioSamples.clear();
 	}
 };
-//#endregion
-//#region src/pipeline-runner/runner.ts
 /**
 * Bound on one `processFrame` call. Chosen well above the slowest legitimate
 * inference seen in production (8 617 ms, GPU contention on the hub) so the
@@ -5197,6 +5259,14 @@ var PipelineRunner = class {
 			registration,
 			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");
+				}
+			}),
 			inferenceTimes: [],
 			shedFrames: 0,
 			inflight: 0,
@@ -5243,6 +5313,7 @@ var PipelineRunner = class {
 		if (state.phase === "active") this.detectionStreamHandler?.(deviceId, "unsubscribe");
 		state.motionQueue.clear();
 		state.detectionQueue.clear();
+		state.preRollQueue.clear();
 		this.timingSampler.clearDroppedFramesSource(deviceId);
 		this.cameras.delete(deviceId);
 		this.lastAdmittedAt.delete(deviceId);
@@ -5324,6 +5395,59 @@ var PipelineRunner = class {
 			maxInflightPerCamera: cap
 		};
 	}
+	/**
+	* Queue one PRE-ROLL frame — a frame decoded out of the restreamer's retained
+	* history at session open, carrying its own capture moment
+	* (`session-decode/media-clock.ts`), not the moment it was decoded.
+	*
+	* Deliberately NOT routed through {@link reserveDetectionFrame}: that gate
+	* paces on WALL CLOCK, and a catch-up burst delivers seconds of media inside
+	* milliseconds of wall clock, so the governor would reject the whole burst
+	* bar one frame. The burst's own bound is a MEDIA-time stride applied
+	* upstream, under an explicit frame + wall-clock budget
+	* (`session-decode/pre-roll-burst.ts`); by the time a frame reaches here it
+	* has already been chosen.
+	*
+	* `false` means the lane is full or the camera is not taking detection
+	* frames. The caller LOGS that: a burst silently truncated by the lane and a
+	* burst that fit read identically otherwise, and this is a branch that drops
+	* work.
+	*/
+	enqueuePreRollFrame(deviceId, frame, handle) {
+		const state = this.cameras.get(deviceId);
+		if (!state || state.phase !== "active") return false;
+		return state.preRollQueue.enqueue({
+			frame,
+			handle
+		});
+	}
+	/**
+	* Whether one more history frame would be taken. Asked BEFORE pixels are
+	* materialized so a burst that has already filled the lane costs no RGB
+	* conversion, no IPC and no retention work — the same pixel-free discipline
+	* the live path gets from `reserveDetectionFrame`.
+	*/
+	preRollLaneAccepting(deviceId) {
+		const state = this.cameras.get(deviceId);
+		if (!state || state.phase !== "active") return false;
+		return state.preRollQueue.size < (this.config.maxPreRollQueueDepth ?? 12);
+	}
+	/** Frames of history waiting for a spare permit, for the session report line. */
+	preRollQueueDepth(deviceId) {
+		return this.cameras.get(deviceId)?.preRollQueue.size ?? 0;
+	}
+	/** Frames this camera lane REFUSED because it was full. */
+	preRollRefusedCount(deviceId) {
+		return this.cameras.get(deviceId)?.preRollQueue.refused ?? 0;
+	}
+	/**
+	* Whether the node has a permit to spare for history right now — i.e. one
+	* would still be free after the burst took one. See
+	* {@link PRE_ROLL_PERMIT_RESERVE}.
+	*/
+	preRollDispatchable() {
+		return this.semaphore.available > 1;
+	}
 	enqueueReservedDetectionFrame(deviceId, frame, handle) {
 		const state = this.cameras.get(deviceId);
 		if (!state || state.phase !== "active") return false;
@@ -5754,7 +5878,7 @@ var PipelineRunner = class {
 			entry: state.detectionQueue.dequeue(),
 			state
 		};
-		if (this.defaultRoundRobinKeys.length === 0) return null;
+		if (this.defaultRoundRobinKeys.length === 0) return this.pickNextPreRollFrame();
 		const startIndex = this.defaultRoundRobinIndex;
 		for (let i = 0; i < this.defaultRoundRobinKeys.length; i++) {
 			const idx = (startIndex + i) % this.defaultRoundRobinKeys.length;
@@ -5773,6 +5897,30 @@ var PipelineRunner = class {
 				};
 			}
 		}
+		return this.pickNextPreRollFrame();
+	}
+	/**
+	* The catch-up lane, reached ONLY after every camera's live queue came back
+	* empty. That ordering IS the priority rule: a live frame is always picked
+	* first, so a pre-roll frame can never delay one — and the burst simply
+	* stops progressing while the camera is busy, which is the correct behaviour
+	* for one-shot work whose value does not decay.
+	*/
+	pickNextPreRollFrame() {
+		if (!this.preRollDispatchable()) return null;
+		for (const [deviceId, state] of this.cameras) {
+			if (state.phase !== "active") continue;
+			if (state.preRollQueue.size === 0) continue;
+			if (state.detectionQueue.size > 0) continue;
+			if (state.inflight >= this.maxInflightPerCamera()) continue;
+			const entry = state.preRollQueue.dequeue();
+			if (!entry) continue;
+			return {
+				deviceId,
+				entry,
+				state
+			};
+		}
 		return null;
 	}
 };
@@ -8576,10 +8724,23 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	/** Attach → first decoded detection frame, one line per attach. See
 	*  {@link FirstDetectionFrameTimer}. */
 	firstDetectionFrame = new FirstDetectionFrameTimer();
+	/**
+	* Frames this camera's pre-roll catch-up burst may send to inference.
+	*
+	* The switch and the budget are ONE number here on purpose: `false` and
+	* `0` mean the same thing to every layer below (no burst is constructed, the
+	* history is decoded to reach a GOP and then discarded exactly as it was
+	* before D411), and two independent ways to say it is two ways to disagree.
+	*/
+	preRollBudgetFor(config) {
+		if (!config.preRollInferenceEnabled) return 0;
+		const frames = config.preRollInferenceFrames;
+		return Number.isFinite(frames) && frames > 0 ? frames : 0;
+	}
 	enqueueSharedDetectionFrame(deviceId, frame, handle, reservation) {
 		const runner = this.runner;
 		if (!runner) return false;
-		const admitted = reservation ? reservation.detection && runner.enqueueReservedDetectionFrame(deviceId, frame, handle) : runner.enqueueDetectionFrame(deviceId, frame, handle);
+		const admitted = frame.preRoll === true ? runner.enqueuePreRollFrame(deviceId, frame, handle) : reservation ? reservation.detection && runner.enqueueReservedDetectionFrame(deviceId, frame, handle) : runner.enqueueDetectionFrame(deviceId, frame, handle);
 		if (admitted) {
 			const latencyMs = this.firstDetectionFrame.takeLatency(deviceId, Date.now());
 			if (latencyMs !== null) this.ctx?.logger.info("session-decode: first detection frame after attach", {
@@ -8697,9 +8858,19 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 					source,
 					opts: {
 						fps: config.detectionFps,
-						format: "rgb"
+						format: "rgb",
+						preRollMs: require_restream_intent.preRollRequestOf(source.restreamUrl),
+						preRollMaxFrames: this.preRollBudgetFor(config)
 					},
-					shouldMaterializeFrame: () => {
+					shouldMaterializeFrame: (preRoll) => {
+						if (preRoll) {
+							const accepting = runner.preRollLaneAccepting(config.deviceId);
+							reservation = {
+								detection: accepting,
+								motion: false
+							};
+							return accepting;
+						}
 						reservation = this.reserveSharedDetectionFrame(config.deviceId);
 						const materialize = reservation.detection || reservation.motion;
 						this.retention?.noteFrame({
@@ -8733,7 +8904,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 								materialized: false,
 								workerToRunnerBytes: 0
 							});
-							const admitted = current.detection && runner.enqueueReservedDetectionFrame(config.deviceId, frame, handle);
+							const admitted = current.detection && (frame.preRoll === true ? runner.enqueuePreRollFrame(config.deviceId, frame, handle) : runner.enqueueReservedDetectionFrame(config.deviceId, frame, handle));
 							if (admitted) nativeCrop?.markInferred();
 							if (current.motion) {
 								const motion = await resolveMotionFrameView(require_default_detection_model.localFrameRegistry, frame.frameRef);
@@ -8750,6 +8921,24 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 						}
 					} : { inlineViewSpec: SPLIT_DETECTION_VIEW },
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
+					onPreRollReport: (report) => {
+						log.info("session-decode: pre-roll catch-up burst", {
+							tags: { deviceId: config.deviceId },
+							meta: {
+								streamId: config.detectionStreamId,
+								requestedMs: require_restream_intent.preRollRequestOf(source.restreamUrl),
+								spanMs: report.spanMs,
+								offered: report.offered,
+								inferred: report.inferred,
+								dropped: report.dropped,
+								droppedByReason: report.droppedByReason,
+								strideMs: report.strideMs,
+								subsampled: report.subsampled,
+								laneRefused: runner.preRollRefusedCount(config.deviceId),
+								budgetFrames: this.preRollBudgetFor(config)
+							}
+						});
+					},
 					onFirstFrame: (timing) => {
 						const phaseActiveAt = this.lastMotionAt.get(config.deviceId);
 						log.info("session-decode: detection first frame", {
@@ -9698,6 +9887,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			frame: result,
 			nodeId: this.nodeId,
 			frameHandle: handle,
+			emittedAt: Date.now(),
 			...typeof capturedAt === "number" && capturedAt > 0 ? { capturedAt } : {},
 			...detailSteps && detailSteps.length > 0 ? { detailSteps } : {}
 		};