@camstack/addon-pipeline 1.2.201 → 1.2.203

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

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_worker_protocol = require("../worker-protocol--PcFsRrE.js");
-const require_lazy_sharp = require("../lazy-sharp-B4KrLp0u.js");
+const require_worker_protocol = require("../worker-protocol-B4C4seRh.js");
+const require_lazy_sharp = require("../lazy-sharp-AhHg_Hb-.js");
 //#region src/session-decode/color-conversion.ts
 /**
 * Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
@@ -656,20 +656,6 @@ var NativeLeaseStore = class {
 	}
 };
 //#endregion
-//#region src/session-decode/to-buffer-miss.ts
-/** Which rung lost the frame, from what the worker knows at the miss. */
-function toBufferMissRung(facts) {
-	if (facts.reservedFrameId !== null && facts.frameId > facts.reservedFrameId) return "not-yet-delivered";
-	if (!facts.marked) return "never-leased";
-	if (facts.leaseFrames >= facts.holdFrames) return "hold-full";
-	return "released";
-}
-/** The error line the runner sees: the rung first, the numbers after it. */
-function describeToBufferMiss(facts) {
-	const rung = toBufferMissRung(facts);
-	return `decode-worker-child: toBuffer miss for frameId ${facts.frameId} — ${rung} {reserved=${facts.reservedFrameId ?? "none"} marked=${facts.marked} leaseFrames=${facts.leaseFrames}/${facts.holdFrames} holdOverflow=${facts.holdOverflow}${facts.unmarkedBy !== void 0 ? ` unmarkedBy=${facts.unmarkedBy}` : ""}}`;
-}
-//#endregion
 //#region src/session-decode/native-tile-geometry.ts
 /**
 * Pure geometry for the **native subject tile** — the compressed, subject-sized
@@ -921,6 +907,127 @@ var NativeTileStore = class {
 		this.bytes -= entry.bytes;
 	}
 };
+/**
+* The set of tile cuts currently between "I have this frame's pixels" and
+* "the stores can answer for it", plus the latency of the ones that finished.
+*/
+var PendingCuts = class {
+	waitMs;
+	now;
+	latencySampleCap;
+	cuts = /* @__PURE__ */ new Map();
+	/** Insertion-ordered ring of completed cut latencies (ms). */
+	latencies = [];
+	constructor(options) {
+		this.waitMs = Math.max(0, options.waitMs);
+		this.now = options.now ?? Date.now;
+		this.latencySampleCap = Math.max(1, options.latencySamples ?? 256);
+	}
+	/** Cuts currently in flight (tests / metrics). */
+	get inFlight() {
+		return this.cuts.size;
+	}
+	/**
+	* A cut for `frameId` has started. Call BEFORE the first `await` in the cut,
+	* so no request can observe the gap this module exists to cover.
+	*
+	* A duplicate id should never occur (frame ids are monotonic); settling the
+	* prior entry rather than replacing it keeps any waiter on it from hanging.
+	*/
+	begin(frameId) {
+		this.settle(frameId);
+		let finish = () => {};
+		const done = new Promise((resolve) => {
+			finish = resolve;
+		});
+		this.cuts.set(frameId, {
+			startedAt: this.now(),
+			done,
+			finish
+		});
+	}
+	/**
+	* The cut for `frameId` is over — the stores now hold whatever it produced.
+	* Call from the cut's `finally`, so a throwing encode releases waiters too.
+	* Idempotent.
+	*/
+	settle(frameId) {
+		const cut = this.cuts.get(frameId);
+		if (!cut) return;
+		this.cuts.delete(frameId);
+		this.noteLatency(this.now() - cut.startedAt);
+		cut.finish();
+	}
+	/**
+	* Wait for `frameId`'s cut to land, bounded.
+	*
+	* `none` means there was nothing in flight, and the caller must NOT read that
+	* as "wait exhausted" — it is the ordinary answer for a frame whose cut has
+	* already finished or never ran.
+	*/
+	async waitFor(frameId) {
+		const cut = this.cuts.get(frameId);
+		if (!cut) return "none";
+		if (this.waitMs === 0) return "timeout";
+		let timer;
+		const expired = new Promise((resolve) => {
+			timer = setTimeout(() => resolve("timeout"), this.waitMs);
+			timer.unref?.();
+		});
+		try {
+			return await Promise.race([cut.done.then(() => "settled"), expired]);
+		} finally {
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	}
+	/**
+	* Release every waiter and forget every in-flight cut — re-dial and teardown.
+	* A waiter left behind here would outlive the worker that could settle it.
+	*/
+	clear() {
+		for (const cut of this.cuts.values()) cut.finish();
+		this.cuts.clear();
+	}
+	/**
+	* The `percentile`-th cut latency in ms over the retained samples, or `null`
+	* when nothing has completed yet. `null` rather than 0: a worker that has cut
+	* nothing and a worker that cuts instantly must not read the same.
+	*/
+	latencyMs(percentile) {
+		if (this.latencies.length === 0) return null;
+		const sorted = [...this.latencies].sort((a, b) => a - b);
+		const clamped = Math.min(100, Math.max(0, percentile));
+		const index = Math.min(sorted.length - 1, Math.ceil(clamped / 100 * sorted.length) - 1);
+		return sorted[Math.max(0, index)] ?? null;
+	}
+	noteLatency(ms) {
+		this.latencies.push(Math.max(0, ms));
+		while (this.latencies.length > this.latencySampleCap) this.latencies.shift();
+	}
+};
+/**
+* Serve a frame's retained tiles, waiting for an in-flight cut ONLY when
+* waiting could change the answer.
+*
+* The order is the whole point. Anything already retained is served at once —
+* a cut in flight for a LATER subject of the same frame must not delay a
+* request the stores can already answer. Only an empty store consults
+* {@link PendingCuts}, and only then is a success attributable to the wait.
+*/
+async function attemptTileServe(pending, frameId, source) {
+	if (source.hasRetained()) return {
+		served: await source.serve(),
+		wait: "none",
+		resolvedByWait: false
+	};
+	const wait = await pending.waitFor(frameId);
+	const served = await source.serve();
+	return {
+		served,
+		wait,
+		resolvedByWait: served !== null && wait === "settled"
+	};
+}
 //#endregion
 //#region src/session-decode/planar-crop-source.ts
 /** Layout a detection `toBuffer` can read, or `null` when it must name the
@@ -950,6 +1057,19 @@ function nativeCropSourceTag(format) {
 		case "rgb24": return "rgb:";
 	}
 }
+/**
+* Bytes a crop of `rows` rows actually reads, measured from the crop's ORIGIN.
+*
+* The LAST row needs only its own `rowBytes`, never a whole stride — the stride
+* is the distance to the NEXT row, and for the last row there is no next row.
+* Demanding `stride * rows` instead overshoots the plane's end by exactly the
+* horizontal offset, which is invisible everywhere except where the crop's
+* bottom IS the frame's bottom. See {@link resolvePlanarCropSource}.
+*/
+function planarSpan(rows, stride, rowBytes) {
+	if (rows <= 0) return 0;
+	return (rows - 1) * stride + rowBytes;
+}
 /** A plane view starting at `offset`, or `null` when the plane is too short. */
 function viewAt(plane, offset, requiredSpan) {
 	if (!plane) return null;
@@ -968,6 +1088,28 @@ function viewAt(plane, offset, requiredSpan) {
 * An odd origin is floored onto the chroma grid rather than rejected: the
 * geometry helper already aligns to even, and flooring reads the chroma sample
 * that CONTAINS the origin instead of inventing a half sample.
+*
+* ## The bottom edge (2026-09-07)
+*
+* The span demanded from each plane used to be `stride * region.height` from
+* the crop ORIGIN. A stride is the distance to the NEXT row, and the last row
+* of a crop has no next row — it needs only `left + width` bytes. So the demand
+* overshot the plane's end by exactly `left`, which is invisible everywhere
+* except when the crop's bottom IS the frame's last row. `resolveNativeTileRegion`
+* clamps a padded box to precisely that, and `clampEven` floors both `top` and
+* `height`, so a bottom-clamped tile lands flush every time.
+*
+* The result was that every subject standing near the camera — the biggest, the
+* closest, the best shot — lost its native tile, and the hold path threw for
+* the same rectangles. Measured over 6 h on the live cluster: **100 of 100**
+* logged `missing plane data` geometries had `top + height === frameHeight`
+* with `left > 0`, 101 of 102 on dev:590 (salone, 3840x2160).
+*
+* The check is now the region's real extent, so a crop that genuinely runs past
+* a plane — one row too tall, or a last row reaching past the stride — is still
+* refused. The views handed back are unchanged: `subarray(offset)` always ran
+* to the plane's true end, so nothing here ever sized a buffer, and tightening
+* the predicate cannot shorten one.
 */
 function resolvePlanarCropSource(kind, planes, strides, region) {
 	if (!planes || planes.length < PLANE_COUNT[kind]) return null;
@@ -978,10 +1120,11 @@ function resolvePlanarCropSource(kind, planes, strides, region) {
 	const left = Math.max(0, region.left);
 	const chromaRow = Math.floor(top / 2);
 	const chromaHeight = Math.ceil(region.height / 2);
-	const y = viewAt(planes[0], top * yStride + left, yStride * region.height);
+	const chromaWidth = Math.ceil(Math.max(0, region.width) / 2);
+	const y = viewAt(planes[0], top * yStride + left, planarSpan(region.height, yStride, region.width));
 	if (kind === "nv12") {
 		const uvOffset = chromaRow * cStride + Math.floor(left / 2) * 2;
-		const uv = viewAt(planes[1], uvOffset, cStride * chromaHeight);
+		const uv = viewAt(planes[1], uvOffset, planarSpan(chromaHeight, cStride, chromaWidth * 2));
 		if (!y || !uv) return null;
 		return {
 			planes: [y, uv],
@@ -990,8 +1133,8 @@ function resolvePlanarCropSource(kind, planes, strides, region) {
 	}
 	const vStride = strides?.[2] ?? cStride;
 	const chromaOffset = chromaRow * cStride + Math.floor(left / 2);
-	const u = viewAt(planes[1], chromaOffset, cStride * chromaHeight);
-	const v = viewAt(planes[2], chromaRow * vStride + Math.floor(left / 2), vStride * chromaHeight);
+	const u = viewAt(planes[1], chromaOffset, planarSpan(chromaHeight, cStride, chromaWidth));
+	const v = viewAt(planes[2], chromaRow * vStride + Math.floor(left / 2), planarSpan(chromaHeight, vStride, chromaWidth));
 	if (!y || !u || !v) return null;
 	return {
 		planes: [
@@ -1331,6 +1474,20 @@ async function cutSubjectTiles(frame, bboxes, ports) {
 	return tiles;
 }
 //#endregion
+//#region src/session-decode/to-buffer-miss.ts
+/** Which rung lost the frame, from what the worker knows at the miss. */
+function toBufferMissRung(facts) {
+	if (facts.reservedFrameId !== null && facts.frameId > facts.reservedFrameId) return "not-yet-delivered";
+	if (!facts.marked) return "never-leased";
+	if (facts.leaseFrames >= facts.holdFrames) return "hold-full";
+	return "released";
+}
+/** The error line the runner sees: the rung first, the numbers after it. */
+function describeToBufferMiss(facts) {
+	const rung = toBufferMissRung(facts);
+	return `decode-worker-child: toBuffer miss for frameId ${facts.frameId} — ${rung} {reserved=${facts.reservedFrameId ?? "none"} marked=${facts.marked} leaseFrames=${facts.leaseFrames}/${facts.holdFrames} holdOverflow=${facts.holdOverflow}${facts.unmarkedBy !== void 0 ? ` unmarkedBy=${facts.unmarkedBy}` : ""}}`;
+}
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /** Wrap a software YUV420P frame as a lease entry (byte size ≈ w×h×1.5). */
 function toLeasedNavFrame(frame) {
@@ -1458,6 +1615,28 @@ var NATIVE_TILE_MAX_PER_FRAME = (() => {
 /** JPEG quality for a retained tile. High: this is a MODEL INPUT, not a preview. */
 var NATIVE_TILE_JPEG_QUALITY = 90;
 /**
+* How long a native-crop request waits for a tile cut that is still ENCODING.
+*
+* The cut reads its pixels synchronously at `FrameResult` time but only writes
+* the stores after N JPEG encodes; a request landing in between reads two empty
+* stores and is told `no retained tile for this frame` — the same sentence a
+* frame that was never cut gets. Measured 2026-09-07: misses onset at ~100 ms
+* (only 0.1% below it) and peak at 500-1000 ms, on cameras that cut a tile for
+* 99.7% of their inferred frames, so the window — not any lifetime — is what
+* they are landing in.
+*
+* 500 ms deliberately, not more: the confirmation gate bounds each crop attempt
+* at 300 ms and the capture scheduler drops an enrichment request older than
+* 3 s, so a miss held too long stops being a fast retryable `null` and becomes
+* an upstream timeout. Widen it via `CAMSTACK_SESSION_TILE_CUT_WAIT_MS` only
+* once `cutLatencyMs` on the metrics line says what the encode window really
+* is; `0` disables the wait and restores the pre-2026-09-07 miss profile.
+*/
+var TILE_CUT_WAIT_MS = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_TILE_CUT_WAIT_MS"]);
+	return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 500;
+})();
+/**
 * Demand window (ms) for the lease-capture {@link LeaseActivityGate}: eager
 * per-frame native downloads run only within this window of the last
 * native-crop request (or dial start). `0` disables the GATE (legacy always-on
@@ -1598,6 +1777,14 @@ function errMessage(err) {
 	return String(err);
 }
 /**
+* Render a cut-latency percentile for the metrics line. `-` when nothing has
+* been cut yet: a worker that cut nothing and one that cuts in 0 ms must not
+* read the same, or the number that sizes {@link TILE_CUT_WAIT_MS} is a guess.
+*/
+function formatLatency(ms) {
+	return ms === null ? "-" : String(Math.round(ms));
+}
+/**
 * RTSP low-latency demuxer options — mirrors
 * `addon-decoder-nodeav/src/pull-demuxer-options.ts` (duplicated here rather
 * than cross-imported: this file is a standalone forked entry point, not an
@@ -1802,6 +1989,19 @@ var DecodeWorkerChild = class {
 	tileHits = 0;
 	tileMisses = 0;
 	tileCutFailures = 0;
+	/**
+	* Serves that produced pixels ONLY because the request waited for a cut that
+	* was still encoding — i.e. misses before {@link TILE_CUT_WAIT_MS} existed.
+	*
+	* This is the counter the write-gap hypothesis stands or falls on. If it
+	* stays near zero while `tileMisses` does not move, the misses were never a
+	* timing race and the question becomes WHICH frames get cut at all.
+	*/
+	tileMissesResolvedByWait = 0;
+	/** Requests that gave up on an in-flight cut at the bound — dropped work. */
+	tileWaitTimeouts = 0;
+	/** Cuts between "I have the pixels" and "the stores can answer". */
+	pendingCuts = new PendingCuts({ waitMs: TILE_CUT_WAIT_MS });
 	/** Scene tiles cut / served, on the throughput line. */
 	scenesCut = 0;
 	sceneHits = 0;
@@ -2058,7 +2258,7 @@ var DecodeWorkerChild = class {
 		const skipped = this.framesSkipped + this.frames.droppedCount;
 		const rssMb = Math.round(process.memoryUsage().rss / 1048576);
 		const ageS = Math.round((now - this.startedAt) / 1e3);
-		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, leaseOffered:${this.admission.offered}, leaseAdmitted:${this.admission.admitted}, leaseMarks:${this.admission.marks}, leaseUnmarkedCrops:${this.admission.unmarkedCrops}, leaseAdmission:${NATIVE_LEASE_KNOBS.values.admission}, leaseMb:${Math.round(this.leaseStore.totalBytes / 1048576)}, leaseFrames:${this.leaseStore.size}, holdOverflow:${this.leaseStore.overflowCount}, leaseReleased:${this.leaseReleased}, leaseReleaseMisses:${this.leaseReleaseMisses}, leaseReleasedEarly:${this.leaseReleasedEarly}, tilesCut:${this.tilesCut}, tileHits:${this.tileHits}, tileMisses:${this.tileMisses}, tileCutFailures:${this.tileCutFailures}, tileMb:${Math.round(this.tileStore.totalBytes / 1048576)}, tileFrames:${this.tileStore.frameCount}, scenesCut:${this.scenesCut}, sceneHits:${this.sceneHits}, sceneRefused:${this.sceneRefused}, sceneUnclassified:${this.sceneUnclassified}, sceneEvicted:${this.sceneStore.evictedCount}, sceneMb:${Math.round(this.sceneStore.totalBytes / 1048576)}, sceneFrames:${this.sceneStore.frameCount}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, leaseOffered:${this.admission.offered}, leaseAdmitted:${this.admission.admitted}, leaseMarks:${this.admission.marks}, leaseUnmarkedCrops:${this.admission.unmarkedCrops}, leaseAdmission:${NATIVE_LEASE_KNOBS.values.admission}, leaseMb:${Math.round(this.leaseStore.totalBytes / 1048576)}, leaseFrames:${this.leaseStore.size}, holdOverflow:${this.leaseStore.overflowCount}, leaseReleased:${this.leaseReleased}, leaseReleaseMisses:${this.leaseReleaseMisses}, leaseReleasedEarly:${this.leaseReleasedEarly}, tilesCut:${this.tilesCut}, tileHits:${this.tileHits}, tileMisses:${this.tileMisses}, tileCutFailures:${this.tileCutFailures}, tileMissesResolvedByWait:${this.tileMissesResolvedByWait}, tileWaitTimeouts:${this.tileWaitTimeouts}, cutLatencyMsP50:${formatLatency(this.pendingCuts.latencyMs(50))}, cutLatencyMsP95:${formatLatency(this.pendingCuts.latencyMs(95))}, cutsInFlight:${this.pendingCuts.inFlight}, tileMb:${Math.round(this.tileStore.totalBytes / 1048576)}, tileFrames:${this.tileStore.frameCount}, scenesCut:${this.scenesCut}, sceneHits:${this.sceneHits}, sceneRefused:${this.sceneRefused}, sceneUnclassified:${this.sceneUnclassified}, sceneEvicted:${this.sceneStore.evictedCount}, sceneMb:${Math.round(this.sceneStore.totalBytes / 1048576)}, sceneFrames:${this.sceneStore.frameCount}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 		if (!this.warnedLarge && rssMb >= WORKER_RSS_WARN_MB) {
@@ -2210,10 +2410,16 @@ var DecodeWorkerChild = class {
 	*/
 	async serveTileFallback(requestId, frameId, bbox, maxWidth) {
 		try {
-			const served = await this.serveFromTile(frameId, bbox, maxWidth);
+			const attempt = await attemptTileServe(this.pendingCuts, frameId, {
+				hasRetained: () => this.tileStore.get(frameId).length > 0 || this.sceneStore.get(frameId).length > 0,
+				serve: () => this.serveFromTile(frameId, bbox, maxWidth)
+			});
+			const served = attempt.served;
+			if (attempt.wait === "timeout") this.tileWaitTimeouts += 1;
 			if (served) {
 				this.tileHits += 1;
 				this.nativeCropHits++;
+				if (attempt.resolvedByWait) this.tileMissesResolvedByWait += 1;
 				this.send({
 					kind: "nativeCropResult",
 					requestId,
@@ -2229,7 +2435,7 @@ var DecodeWorkerChild = class {
 			this.send({
 				kind: "nativeCropMiss",
 				requestId,
-				reason: this.tileMissReason(frameId)
+				reason: this.tileMissReason(frameId, attempt.wait)
 			});
 		} catch (err) {
 			this.tileMisses += 1;
@@ -2249,7 +2455,8 @@ var DecodeWorkerChild = class {
 	* "the rectangle is outside every container" are three different sentences,
 	* and one "not retained" hid all of them.
 	*/
-	tileMissReason(frameId) {
+	tileMissReason(frameId, wait) {
+		if (wait === "timeout") return `frame ${frameId} released and its tile cut did not finish within ${TILE_CUT_WAIT_MS} ms — the request outran the encode, not the retention`;
 		if (!this.tileStore.enabled && !this.sceneStore.enabled) return `frame ${frameId} released and retention is DISABLED (tileBudgetMb 0, sceneBudgetMb 0)`;
 		if (!this.sceneStore.enabled) return `frame ${frameId} released and no retained subject tile contains the requested rectangle; scene tiles are DISABLED (sceneBudgetMb 0), so a full-frame request cannot be served at all`;
 		if (!this.tileStore.enabled) return `frame ${frameId} released and subject tiles are DISABLED (tileBudgetMb 0)`;
@@ -2281,6 +2488,7 @@ var DecodeWorkerChild = class {
 	*    explanation, which is the failure this whole redesign exists to remove.
 	*/
 	async handleCutTiles(frameId, bboxes) {
+		this.pendingCuts.begin(frameId);
 		try {
 			if (!this.tileStore.enabled && !this.sceneStore.enabled || bboxes.length === 0) return;
 			const wanted = this.tileStore.enabled ? bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME) : [];
@@ -2362,6 +2570,7 @@ var DecodeWorkerChild = class {
 				this.sceneStore.put(frameId, [scene]);
 			}
 		} finally {
+			this.pendingCuts.settle(frameId);
 			this.noteLeaseRelease(frameId, this.leaseStore.release(frameId), "cut");
 		}
 	}
@@ -3144,6 +3353,7 @@ var DecodeWorkerChild = class {
 		this.leaseStore.clear();
 		this.tileStore.clear();
 		this.sceneStore.clear();
+		this.pendingCuts.clear();
 		this.tileFrameWidth = 0;
 		this.tileFrameHeight = 0;
 		this.nativeLeaseDownloadFilter?.close();