@camstack/addon-pipeline 1.2.131 → 1.2.133

package/dist/{segment-demux-js-skhsAZx6.mjs → segment-demux-js-0NZ9TXro.mjs}

@@ -1,5 +1,5 @@
 import { r as __toESM, t as __commonJSMin } from "./chunk-DnnnRqeS.mjs";
-import { gt as errMsg } from "./dist-DO0UVhOk.mjs";
+import { yt as errMsg } from "./dist-7Uc6NdFm.mjs";
 import { spawn } from "node:child_process";
 //#region ../../node_modules/mp4box/dist/mp4box.all.js
 var require_mp4box_all = /* @__PURE__ */ __commonJSMin(((exports) => {

package/dist/{segment-demux-js-Cu0oDMUL.js → segment-demux-js-DKcc0bxA.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-CqoMNE1e.js");
+const require_dist = require("./dist-DsnZUYTs.js");
 let node_child_process = require("node:child_process");
 //#region ../../node_modules/mp4box/dist/mp4box.all.js
 var require_mp4box_all = /* @__PURE__ */ require_dist.__commonJSMin(((exports) => {

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-G3HXTY8z.js");
-const require_lazy_sharp = require("../lazy-sharp-BGrpS8yi.js");
+const require_worker_protocol = require("../worker-protocol-DzRUHIcM.js");
+const require_lazy_sharp = require("../lazy-sharp-UzEUL79V.js");
 //#region src/session-decode/color-conversion.ts
 /**
 * Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
@@ -792,11 +792,24 @@ var NativeTileStore = class {
 	ttlMs;
 	now;
 	bytes = 0;
+	/**
+	* Frames whose tiles were dropped by the BUDGET before their TTL ran out.
+	*
+	* Counted, not silent: budget eviction is the one path here that destroys
+	* retained work, and on the scene store a dropped entry is a key frame that
+	* can never be captured again. `0` means the TTL is what bounds this store —
+	* anything else is the signal that its budget is the binding limit.
+	*/
+	evicted = 0;
 	constructor(options) {
 		this.budgetBytes = options.budgetBytes;
 		this.ttlMs = options.ttlMs;
 		this.now = options.now ?? Date.now;
 	}
+	/** Frames dropped by the byte budget rather than by the TTL (tests / metrics). */
+	get evictedCount() {
+		return this.evicted;
+	}
 	/** `false` when tiles are disabled (`budgetBytes <= 0`). */
 	get enabled() {
 		return this.budgetBytes > 0;
@@ -837,6 +850,7 @@ var NativeTileStore = class {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0 || oldest === frameId) break;
 			this.drop(oldest);
+			this.evicted += 1;
 		}
 		return true;
 	}
@@ -1078,6 +1092,107 @@ function resolveRgbCropSource(plane, planeStride, region) {
 	};
 }
 //#endregion
+//#region src/session-decode/scene-tile.ts
+/**
+* The whole frame, in the same normalized space every other cut uses. Identical
+* to the bbox `getNativeCrop`'s full-frame callers send, which is the point —
+* the rectangle asked for and the rectangle retained are the same one.
+*/
+var SCENE_TILE_BBOX = {
+	x: 0,
+	y: 0,
+	w: 1,
+	h: 1
+};
+/**
+* Plan one frame's cut.
+*
+* The scene rectangle is appended to the SAME cut rather than taken separately,
+* because `subject-tile-cut.ts` reads every rectangle in one synchronous turn:
+* a second read after the first cut's encodes have awaited is exactly the
+* eviction window that once cut subject 1 of each frame and lost the rest.
+*
+* A frame that detected NOTHING gets nothing, scene tile included. That
+* asymmetry is what keeps this tier affordable — the frames a key-frame capture
+* can ever name are the frames that carried a best detection, and on this
+* cluster those are ~0.4/s per camera against ~2.1/s delivered.
+*/
+function planFrameCuts(subjects, conditions) {
+	if (!conditions.sceneEnabled || !conditions.hasDetections) return {
+		bboxes: subjects,
+		scene: false
+	};
+	return {
+		bboxes: [...subjects, SCENE_TILE_BBOX],
+		scene: true
+	};
+}
+/**
+* Does this region cover the whole frame?
+*
+* Judged on the RESOLVED region rather than on the position in the cut list,
+* because `cutSubjectTiles` drops a rectangle whose read or encode failed and
+* positional identity does not survive that. Unknown frame dimensions (a freed
+* node-av frame reports 0×0) are `false` — classifying against those would file
+* every subject tile as the scene.
+*/
+function isSceneRegion(region, frameWidth, frameHeight) {
+	if (frameWidth <= 0 || frameHeight <= 0) return false;
+	return region.left <= 0 && region.top <= 0 && region.width >= frameWidth && region.height >= frameHeight;
+}
+/**
+* Route each cut tile to the store that owns it.
+*
+* The FIRST frame-spanning tile is the scene; any later one stays a subject. A
+* padded subject that already covers the frame genuinely IS the scene, and both
+* stores are consulted on a serve, so claiming one of them costs no hit and
+* keeps the two stores from holding the same pixels twice.
+*/
+function partitionSceneTile(tiles, frameWidth, frameHeight) {
+	const subjects = [];
+	let scene = null;
+	for (const tile of tiles) {
+		if (scene === null && isSceneRegion(tile.region, frameWidth, frameHeight)) {
+			scene = tile;
+			continue;
+		}
+		subjects.push(tile);
+	}
+	return {
+		subjects,
+		scene
+	};
+}
+/**
+* Pick the retained tile that CONTAINS `rect`, subject tiles first.
+*
+* The order is the whole of the policy and it is not cosmetic. Both rungs are
+* native-resolution, so either would be honest — but a subject tile is
+* ~60-120 KB against a scene tile's ~1.5-2.5 MB, and the extract runs on
+* whatever it is handed. Asking the subject store first keeps an ordinary
+* face/plate crop off the 20×-larger raster; the scene tile is consulted only
+* for the rectangles no subject tile could ever contain, which is exactly the
+* set that had no rung at all before it existed.
+*
+* `null` means no retained rung contains the rectangle — a MISS, never a clamp
+* into the nearest tile ([D52](../../../../docs/decisions/adr-0052.md)).
+*/
+function selectRetainedTile(subjects, scenes, rect) {
+	const fromSubject = selectTileForRect(subjects, rect);
+	if (fromSubject) return {
+		tile: fromSubject.tile,
+		local: fromSubject.local,
+		source: "subject"
+	};
+	const fromScene = selectTileForRect(scenes, rect);
+	if (fromScene) return {
+		tile: fromScene.tile,
+		local: fromScene.local,
+		source: "scene"
+	};
+	return null;
+}
+//#endregion
 //#region src/session-decode/subject-tile-cut.ts
 function failureReason(err) {
 	return err instanceof Error ? err.message : String(err);
@@ -1226,6 +1341,14 @@ var NATIVE_LEASE_HOLD_FRAMES = NATIVE_LEASE_KNOBS.values.holdFrames;
 */
 var NATIVE_TILE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.tileBudgetMb * 1024 * 1024;
 /**
+* Hard RAM budget (bytes) for the SCENE TILE store — one JPEG of the whole
+* native frame per detection-bearing frame, which is the only thing that can
+* answer a FULL-FRAME native request after the hold ends. Separate from the
+* subject budget so a key frame can never evict a face tile. `0` disables the
+* rung. See `scene-tile.ts` for the measurements that sized it.
+*/
+var NATIVE_SCENE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.sceneBudgetMb * 1024 * 1024;
+/**
 * How long a subject tile is served. A TTL is honest HERE and dishonest on the
 * hold: nothing is waiting on a tile, it is speculative retention against a
 * request that may never come. Sized an order of magnitude above the measured
@@ -1563,11 +1686,33 @@ var DecodeWorkerChild = class {
 		budgetBytes: NATIVE_TILE_BUDGET_BYTES,
 		ttlMs: NATIVE_TILE_TTL_MS
 	});
+	/**
+	* What survives a held frame for a FULL-FRAME request: one JPEG of the whole
+	* native raster, cut in the SAME synchronous read phase as the subject tiles.
+	*
+	* A separate store, not a fifth entry in {@link tileStore}, because a scene
+	* tile is ~20× a subject tile: one shared budget would let a busy camera's
+	* key frames evict the face/plate tiles the recognisers live on. Two stores
+	* make starving that tier impossible rather than unlikely.
+	*/
+	sceneStore = new NativeTileStore({
+		budgetBytes: NATIVE_SCENE_BUDGET_BYTES,
+		ttlMs: NATIVE_TILE_TTL_MS
+	});
 	/** Tiles cut / served / refused-for-containment, on the throughput line. */
 	tilesCut = 0;
 	tileHits = 0;
 	tileMisses = 0;
 	tileCutFailures = 0;
+	/** Scene tiles cut / served, on the throughput line. */
+	scenesCut = 0;
+	sceneHits = 0;
+	/**
+	* Full-frame cuts NOT taken because the rung is switched off
+	* (`sceneBudgetMb: 0`). A branch that drops work counts it — this one drops a
+	* key frame that can never be captured again.
+	*/
+	sceneRefused = 0;
 	/**
 	* Native frame dimensions the retained tiles were cut from. A session's
 	* resolution does not change (a re-dial clears the store), so ONE pair is
@@ -1653,6 +1798,9 @@ var DecodeWorkerChild = class {
 	* un-guarded version a log flood rather than a diagnosis.
 	*/
 	warnedTileEncoderUnavailable = false;
+	/** One-shot: the scene rung is off by configuration, which cannot change under
+	*  a running worker. The VOLUME lives on `sceneRefused`. */
+	warnedSceneDisabled = false;
 	/**
 	* The last subject-tile-cut failure REASON logged — see
 	* {@link reportTileCutFailure}. Compared, not counted: the count lives on the
@@ -1781,7 +1929,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}, tilesCut:${this.tilesCut}, tileHits:${this.tileHits}, tileMisses:${this.tileMisses}, tileCutFailures:${this.tileCutFailures}, tileMb:${Math.round(this.tileStore.totalBytes / 1048576)}, tileFrames:${this.tileStore.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}, 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}, 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) {
@@ -1923,7 +2071,7 @@ var DecodeWorkerChild = class {
 			this.send({
 				kind: "nativeCropMiss",
 				requestId,
-				reason: this.tileStore.enabled ? `frame ${frameId} released and no retained subject tile contains the requested rectangle` : `frame ${frameId} released and subject tiles are DISABLED (tileBudgetMb 0)`
+				reason: this.tileMissReason(frameId)
 			});
 		} catch (err) {
 			this.tileMisses += 1;
@@ -1937,6 +2085,18 @@ var DecodeWorkerChild = class {
 			});
 		}
 	}
+	/**
+	* Why nothing retained could answer — named per RUNG, because they have
+	* different fixes. "Subject tiles are off" and "the scene rung is off" and
+	* "the rectangle is outside every container" are three different sentences,
+	* and one "not retained" hid all of them.
+	*/
+	tileMissReason(frameId) {
+		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)`;
+		return `frame ${frameId} released and no retained subject or scene tile contains the requested rectangle`;
+	}
 	/** The GPU-ring or reserved-slot frame for `frameId` (hold-disabled / newest paths). */
 	resolveRetainedFrame(frameId) {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
@@ -1963,8 +2123,8 @@ var DecodeWorkerChild = class {
 	*/
 	async handleCutTiles(frameId, bboxes) {
 		try {
-			if (!this.tileStore.enabled || bboxes.length === 0) return;
-			const wanted = bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME);
+			if (!this.tileStore.enabled && !this.sceneStore.enabled || bboxes.length === 0) return;
+			const wanted = this.tileStore.enabled ? bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME) : [];
 			if (bboxes.length > wanted.length) this.emitStderr(`decode-worker-child: tile cut capped at ${NATIVE_TILE_MAX_PER_FRAME} of ${bboxes.length} subjects on frame ${frameId} — the rest fall back to the ≤640 tier\n`);
 			const sharp = await this.tileEncoder();
 			const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
@@ -1983,7 +2143,18 @@ var DecodeWorkerChild = class {
 			}
 			this.tileFrameWidth = frame.width;
 			this.tileFrameHeight = frame.height;
-			const tiles = await cutSubjectTiles(frame, wanted, {
+			const plan = planFrameCuts(wanted, {
+				sceneEnabled: this.sceneStore.enabled,
+				hasDetections: bboxes.length > 0
+			});
+			if (!plan.scene) {
+				this.sceneRefused += 1;
+				if (!this.warnedSceneDisabled) {
+					this.warnedSceneDisabled = true;
+					this.emitStderr("decode-worker-child: scene tiles DISABLED (sceneBudgetMb 0) — every late FULL-FRAME request (native keyFrame, detail frameJpeg, gallery fallback) will miss once this frame is released; refusals are counted as sceneRefused\n");
+				}
+			}
+			const cut = await cutSubjectTiles(frame, plan.bboxes, {
 				isLive: (f) => this.isRetainedFrameLive(f),
 				cutRaw: (f, bbox) => {
 					const { region } = resolveNativeTileRegion(f.width, f.height, bbox, NATIVE_TILE_PADDING_RATIO);
@@ -2017,10 +2188,18 @@ var DecodeWorkerChild = class {
 					this.reportTileCutFailure(frameId, reason);
 				}
 			});
-			this.tileCutFailures += wanted.length - tiles.length;
-			if (tiles.length > 0) {
-				this.tilesCut += tiles.length;
-				this.tileStore.put(frameId, tiles);
+			this.tileCutFailures += plan.bboxes.length - cut.length;
+			const { subjects, scene } = plan.scene ? partitionSceneTile(cut, frame.width, frame.height) : {
+				subjects: cut,
+				scene: null
+			};
+			if (subjects.length > 0) {
+				this.tilesCut += subjects.length;
+				this.tileStore.put(frameId, subjects);
+			}
+			if (scene !== null) {
+				this.scenesCut += 1;
+				this.sceneStore.put(frameId, [scene]);
 			}
 		} finally {
 			this.leaseStore.release(frameId);
@@ -2103,14 +2282,16 @@ var DecodeWorkerChild = class {
 	* which would enrich a different part of the scene and error nowhere.
 	*/
 	async serveFromTile(frameId, bbox, maxWidth) {
+		const scenes = this.sceneStore.get(frameId);
 		const tiles = this.tileStore.get(frameId);
-		if (tiles.length === 0) return null;
+		if (tiles.length === 0 && scenes.length === 0) return null;
 		const width = this.tileFrameWidth;
 		const height = this.tileFrameHeight;
 		if (width <= 0 || height <= 0) return null;
 		const { region, target } = resolveNativeCropGeometry(width, height, bbox, maxWidth);
-		const served = selectTileForRect(tiles, region);
+		const served = selectRetainedTile(tiles, scenes, region);
 		if (!served) return null;
+		if (served.source === "scene") this.sceneHits += 1;
 		let pipeline = (await require_lazy_sharp.getSharp())(served.tile.bytes).extract({
 			left: served.local.left,
 			top: served.local.top,
@@ -2767,6 +2948,7 @@ var DecodeWorkerChild = class {
 		this.nativeRing.clear();
 		this.leaseStore.clear();
 		this.tileStore.clear();
+		this.sceneStore.clear();
 		this.tileFrameWidth = 0;
 		this.tileFrameHeight = 0;
 		this.nativeLeaseDownloadFilter?.close();

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

@@ -1,4 +1,4 @@
-import { i as formatNativeLeaseKnobs, n as isWorkerRequest, o as resolveNativeLeaseKnobs, r as logLevelForLine } from "../worker-protocol-_Ujvj1hl.mjs";
+import { i as formatNativeLeaseKnobs, n as isWorkerRequest, o as resolveNativeLeaseKnobs, r as logLevelForLine } from "../worker-protocol-CMDUAqvX.mjs";
 import { n as setSharpWarnSink, r as hostExternalEntryUrls, t as getSharp } from "../lazy-sharp-BtT5x-qP.mjs";
 //#region src/session-decode/color-conversion.ts
 /**
@@ -791,11 +791,24 @@ var NativeTileStore = class {
 	ttlMs;
 	now;
 	bytes = 0;
+	/**
+	* Frames whose tiles were dropped by the BUDGET before their TTL ran out.
+	*
+	* Counted, not silent: budget eviction is the one path here that destroys
+	* retained work, and on the scene store a dropped entry is a key frame that
+	* can never be captured again. `0` means the TTL is what bounds this store —
+	* anything else is the signal that its budget is the binding limit.
+	*/
+	evicted = 0;
 	constructor(options) {
 		this.budgetBytes = options.budgetBytes;
 		this.ttlMs = options.ttlMs;
 		this.now = options.now ?? Date.now;
 	}
+	/** Frames dropped by the byte budget rather than by the TTL (tests / metrics). */
+	get evictedCount() {
+		return this.evicted;
+	}
 	/** `false` when tiles are disabled (`budgetBytes <= 0`). */
 	get enabled() {
 		return this.budgetBytes > 0;
@@ -836,6 +849,7 @@ var NativeTileStore = class {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0 || oldest === frameId) break;
 			this.drop(oldest);
+			this.evicted += 1;
 		}
 		return true;
 	}
@@ -1077,6 +1091,107 @@ function resolveRgbCropSource(plane, planeStride, region) {
 	};
 }
 //#endregion
+//#region src/session-decode/scene-tile.ts
+/**
+* The whole frame, in the same normalized space every other cut uses. Identical
+* to the bbox `getNativeCrop`'s full-frame callers send, which is the point —
+* the rectangle asked for and the rectangle retained are the same one.
+*/
+var SCENE_TILE_BBOX = {
+	x: 0,
+	y: 0,
+	w: 1,
+	h: 1
+};
+/**
+* Plan one frame's cut.
+*
+* The scene rectangle is appended to the SAME cut rather than taken separately,
+* because `subject-tile-cut.ts` reads every rectangle in one synchronous turn:
+* a second read after the first cut's encodes have awaited is exactly the
+* eviction window that once cut subject 1 of each frame and lost the rest.
+*
+* A frame that detected NOTHING gets nothing, scene tile included. That
+* asymmetry is what keeps this tier affordable — the frames a key-frame capture
+* can ever name are the frames that carried a best detection, and on this
+* cluster those are ~0.4/s per camera against ~2.1/s delivered.
+*/
+function planFrameCuts(subjects, conditions) {
+	if (!conditions.sceneEnabled || !conditions.hasDetections) return {
+		bboxes: subjects,
+		scene: false
+	};
+	return {
+		bboxes: [...subjects, SCENE_TILE_BBOX],
+		scene: true
+	};
+}
+/**
+* Does this region cover the whole frame?
+*
+* Judged on the RESOLVED region rather than on the position in the cut list,
+* because `cutSubjectTiles` drops a rectangle whose read or encode failed and
+* positional identity does not survive that. Unknown frame dimensions (a freed
+* node-av frame reports 0×0) are `false` — classifying against those would file
+* every subject tile as the scene.
+*/
+function isSceneRegion(region, frameWidth, frameHeight) {
+	if (frameWidth <= 0 || frameHeight <= 0) return false;
+	return region.left <= 0 && region.top <= 0 && region.width >= frameWidth && region.height >= frameHeight;
+}
+/**
+* Route each cut tile to the store that owns it.
+*
+* The FIRST frame-spanning tile is the scene; any later one stays a subject. A
+* padded subject that already covers the frame genuinely IS the scene, and both
+* stores are consulted on a serve, so claiming one of them costs no hit and
+* keeps the two stores from holding the same pixels twice.
+*/
+function partitionSceneTile(tiles, frameWidth, frameHeight) {
+	const subjects = [];
+	let scene = null;
+	for (const tile of tiles) {
+		if (scene === null && isSceneRegion(tile.region, frameWidth, frameHeight)) {
+			scene = tile;
+			continue;
+		}
+		subjects.push(tile);
+	}
+	return {
+		subjects,
+		scene
+	};
+}
+/**
+* Pick the retained tile that CONTAINS `rect`, subject tiles first.
+*
+* The order is the whole of the policy and it is not cosmetic. Both rungs are
+* native-resolution, so either would be honest — but a subject tile is
+* ~60-120 KB against a scene tile's ~1.5-2.5 MB, and the extract runs on
+* whatever it is handed. Asking the subject store first keeps an ordinary
+* face/plate crop off the 20×-larger raster; the scene tile is consulted only
+* for the rectangles no subject tile could ever contain, which is exactly the
+* set that had no rung at all before it existed.
+*
+* `null` means no retained rung contains the rectangle — a MISS, never a clamp
+* into the nearest tile ([D52](../../../../docs/decisions/adr-0052.md)).
+*/
+function selectRetainedTile(subjects, scenes, rect) {
+	const fromSubject = selectTileForRect(subjects, rect);
+	if (fromSubject) return {
+		tile: fromSubject.tile,
+		local: fromSubject.local,
+		source: "subject"
+	};
+	const fromScene = selectTileForRect(scenes, rect);
+	if (fromScene) return {
+		tile: fromScene.tile,
+		local: fromScene.local,
+		source: "scene"
+	};
+	return null;
+}
+//#endregion
 //#region src/session-decode/subject-tile-cut.ts
 function failureReason(err) {
 	return err instanceof Error ? err.message : String(err);
@@ -1225,6 +1340,14 @@ var NATIVE_LEASE_HOLD_FRAMES = NATIVE_LEASE_KNOBS.values.holdFrames;
 */
 var NATIVE_TILE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.tileBudgetMb * 1024 * 1024;
 /**
+* Hard RAM budget (bytes) for the SCENE TILE store — one JPEG of the whole
+* native frame per detection-bearing frame, which is the only thing that can
+* answer a FULL-FRAME native request after the hold ends. Separate from the
+* subject budget so a key frame can never evict a face tile. `0` disables the
+* rung. See `scene-tile.ts` for the measurements that sized it.
+*/
+var NATIVE_SCENE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.sceneBudgetMb * 1024 * 1024;
+/**
 * How long a subject tile is served. A TTL is honest HERE and dishonest on the
 * hold: nothing is waiting on a tile, it is speculative retention against a
 * request that may never come. Sized an order of magnitude above the measured
@@ -1562,11 +1685,33 @@ var DecodeWorkerChild = class {
 		budgetBytes: NATIVE_TILE_BUDGET_BYTES,
 		ttlMs: NATIVE_TILE_TTL_MS
 	});
+	/**
+	* What survives a held frame for a FULL-FRAME request: one JPEG of the whole
+	* native raster, cut in the SAME synchronous read phase as the subject tiles.
+	*
+	* A separate store, not a fifth entry in {@link tileStore}, because a scene
+	* tile is ~20× a subject tile: one shared budget would let a busy camera's
+	* key frames evict the face/plate tiles the recognisers live on. Two stores
+	* make starving that tier impossible rather than unlikely.
+	*/
+	sceneStore = new NativeTileStore({
+		budgetBytes: NATIVE_SCENE_BUDGET_BYTES,
+		ttlMs: NATIVE_TILE_TTL_MS
+	});
 	/** Tiles cut / served / refused-for-containment, on the throughput line. */
 	tilesCut = 0;
 	tileHits = 0;
 	tileMisses = 0;
 	tileCutFailures = 0;
+	/** Scene tiles cut / served, on the throughput line. */
+	scenesCut = 0;
+	sceneHits = 0;
+	/**
+	* Full-frame cuts NOT taken because the rung is switched off
+	* (`sceneBudgetMb: 0`). A branch that drops work counts it — this one drops a
+	* key frame that can never be captured again.
+	*/
+	sceneRefused = 0;
 	/**
 	* Native frame dimensions the retained tiles were cut from. A session's
 	* resolution does not change (a re-dial clears the store), so ONE pair is
@@ -1652,6 +1797,9 @@ var DecodeWorkerChild = class {
 	* un-guarded version a log flood rather than a diagnosis.
 	*/
 	warnedTileEncoderUnavailable = false;
+	/** One-shot: the scene rung is off by configuration, which cannot change under
+	*  a running worker. The VOLUME lives on `sceneRefused`. */
+	warnedSceneDisabled = false;
 	/**
 	* The last subject-tile-cut failure REASON logged — see
 	* {@link reportTileCutFailure}. Compared, not counted: the count lives on the
@@ -1780,7 +1928,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}, tilesCut:${this.tilesCut}, tileHits:${this.tileHits}, tileMisses:${this.tileMisses}, tileCutFailures:${this.tileCutFailures}, tileMb:${Math.round(this.tileStore.totalBytes / 1048576)}, tileFrames:${this.tileStore.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}, 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}, 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) {
@@ -1922,7 +2070,7 @@ var DecodeWorkerChild = class {
 			this.send({
 				kind: "nativeCropMiss",
 				requestId,
-				reason: this.tileStore.enabled ? `frame ${frameId} released and no retained subject tile contains the requested rectangle` : `frame ${frameId} released and subject tiles are DISABLED (tileBudgetMb 0)`
+				reason: this.tileMissReason(frameId)
 			});
 		} catch (err) {
 			this.tileMisses += 1;
@@ -1936,6 +2084,18 @@ var DecodeWorkerChild = class {
 			});
 		}
 	}
+	/**
+	* Why nothing retained could answer — named per RUNG, because they have
+	* different fixes. "Subject tiles are off" and "the scene rung is off" and
+	* "the rectangle is outside every container" are three different sentences,
+	* and one "not retained" hid all of them.
+	*/
+	tileMissReason(frameId) {
+		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)`;
+		return `frame ${frameId} released and no retained subject or scene tile contains the requested rectangle`;
+	}
 	/** The GPU-ring or reserved-slot frame for `frameId` (hold-disabled / newest paths). */
 	resolveRetainedFrame(frameId) {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
@@ -1962,8 +2122,8 @@ var DecodeWorkerChild = class {
 	*/
 	async handleCutTiles(frameId, bboxes) {
 		try {
-			if (!this.tileStore.enabled || bboxes.length === 0) return;
-			const wanted = bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME);
+			if (!this.tileStore.enabled && !this.sceneStore.enabled || bboxes.length === 0) return;
+			const wanted = this.tileStore.enabled ? bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME) : [];
 			if (bboxes.length > wanted.length) this.emitStderr(`decode-worker-child: tile cut capped at ${NATIVE_TILE_MAX_PER_FRAME} of ${bboxes.length} subjects on frame ${frameId} — the rest fall back to the ≤640 tier\n`);
 			const sharp = await this.tileEncoder();
 			const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
@@ -1982,7 +2142,18 @@ var DecodeWorkerChild = class {
 			}
 			this.tileFrameWidth = frame.width;
 			this.tileFrameHeight = frame.height;
-			const tiles = await cutSubjectTiles(frame, wanted, {
+			const plan = planFrameCuts(wanted, {
+				sceneEnabled: this.sceneStore.enabled,
+				hasDetections: bboxes.length > 0
+			});
+			if (!plan.scene) {
+				this.sceneRefused += 1;
+				if (!this.warnedSceneDisabled) {
+					this.warnedSceneDisabled = true;
+					this.emitStderr("decode-worker-child: scene tiles DISABLED (sceneBudgetMb 0) — every late FULL-FRAME request (native keyFrame, detail frameJpeg, gallery fallback) will miss once this frame is released; refusals are counted as sceneRefused\n");
+				}
+			}
+			const cut = await cutSubjectTiles(frame, plan.bboxes, {
 				isLive: (f) => this.isRetainedFrameLive(f),
 				cutRaw: (f, bbox) => {
 					const { region } = resolveNativeTileRegion(f.width, f.height, bbox, NATIVE_TILE_PADDING_RATIO);
@@ -2016,10 +2187,18 @@ var DecodeWorkerChild = class {
 					this.reportTileCutFailure(frameId, reason);
 				}
 			});
-			this.tileCutFailures += wanted.length - tiles.length;
-			if (tiles.length > 0) {
-				this.tilesCut += tiles.length;
-				this.tileStore.put(frameId, tiles);
+			this.tileCutFailures += plan.bboxes.length - cut.length;
+			const { subjects, scene } = plan.scene ? partitionSceneTile(cut, frame.width, frame.height) : {
+				subjects: cut,
+				scene: null
+			};
+			if (subjects.length > 0) {
+				this.tilesCut += subjects.length;
+				this.tileStore.put(frameId, subjects);
+			}
+			if (scene !== null) {
+				this.scenesCut += 1;
+				this.sceneStore.put(frameId, [scene]);
 			}
 		} finally {
 			this.leaseStore.release(frameId);
@@ -2102,14 +2281,16 @@ var DecodeWorkerChild = class {
 	* which would enrich a different part of the scene and error nowhere.
 	*/
 	async serveFromTile(frameId, bbox, maxWidth) {
+		const scenes = this.sceneStore.get(frameId);
 		const tiles = this.tileStore.get(frameId);
-		if (tiles.length === 0) return null;
+		if (tiles.length === 0 && scenes.length === 0) return null;
 		const width = this.tileFrameWidth;
 		const height = this.tileFrameHeight;
 		if (width <= 0 || height <= 0) return null;
 		const { region, target } = resolveNativeCropGeometry(width, height, bbox, maxWidth);
-		const served = selectTileForRect(tiles, region);
+		const served = selectRetainedTile(tiles, scenes, region);
 		if (!served) return null;
+		if (served.source === "scene") this.sceneHits += 1;
 		let pipeline = (await getSharp())(served.tile.bytes).extract({
 			left: served.local.left,
 			top: served.local.top,
@@ -2766,6 +2947,7 @@ var DecodeWorkerChild = class {
 		this.nativeRing.clear();
 		this.leaseStore.clear();
 		this.tileStore.clear();
+		this.sceneStore.clear();
 		this.tileFrameWidth = 0;
 		this.tileFrameHeight = 0;
 		this.nativeLeaseDownloadFilter?.close();

package/dist/stream-broker/_stub.js

@@ -1,7 +1,7 @@
-import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, p as c, r as l, s as u, t as d, u as f } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_ui_mf_2_library__loadShare__.js-CQKwHIHI.mjs";
+import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, p as c, r as l, s as u, t as d, u as f } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_ui_mf_2_library__loadShare__.js-77rGxv1J.mjs";
 import { a as p, i as m, n as h, o as g, r as _, t as v } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react__loadShare__.js-C9j-2lBe.mjs";
 import { n as y, r as b, t as x } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react_mf_1_jsx_mf_2_runtime__loadShare__.js-XO0-Pyu6.mjs";
-import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-Bme2OZQp.mjs";
+import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-CVBnNONy.mjs";
 import { n as C, t as w } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_tanstack_mf_1_react_mf_2_query__loadShare__.js-BO7TIbJV.mjs";
 //#region ../../node_modules/lucide-react/dist/esm/shared/src/utils.js
 var T = (e) => e.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase(), E = (e) => e.replace(/^([A-Z])|[\s-_]+(\w)/g, (e, t, n) => n ? n.toUpperCase() : t.toLowerCase()), D = (e) => {