@camstack/addon-pipeline 1.2.107 → 1.2.118

package/dist/pipeline-runner/index.mjs

@@ -1,6 +1,6 @@
-import { At as nodePin, Bt as literal, F as customAction, Ft as _enum, Ht as object, It as array, Kt as EventCategory, L as defineCustomActions, Lt as boolean, Tt as createEvent, Vt as number, Wt as string, et as pickDetailCropConvention, ht as errMsg, p as DEVICE_BACKEND_TO_FORMAT, rt as pipelineRunnerCapability, tt as pickNativeLeaseOverride, u as DEFAULT_DETAIL_CROP_CONVENTION, xt as BaseAddon, z as deriveDetailCropRect, zt as lazy } from "../dist-CkXAzTZ2.mjs";
-import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-fHkfgmlw.mjs";
-import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-bEipQT9l.mjs";
+import { At as nodePin, Bt as literal, F as customAction, Ft as _enum, Ht as object, It as array, Kt as EventCategory, L as defineCustomActions, Lt as boolean, Tt as createEvent, Vt as number, Wt as string, et as pickDetailCropConvention, ht as errMsg, p as DEVICE_BACKEND_TO_FORMAT, rt as pipelineRunnerCapability, tt as pickNativeLeaseOverride, u as DEFAULT_DETAIL_CROP_CONVENTION, xt as BaseAddon, z as deriveDetailCropRect, zt as lazy } from "../dist-B763E61Y.mjs";
+import { i as resolveFrameViewGeometry, r as localFrameRegistry, t as attributeStall, u as getStepDefinition } from "../event-loop-stall-monitor-CYEvvp2Z.mjs";
+import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-D_2QaXYr.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-6oymT_yf.mjs";
 import { n as withDetectionIntent } from "../restream-intent-B4BXZra7.mjs";
@@ -297,6 +297,48 @@ var NativeCropRegistry = class {
 		}
 	}
 };
+//#endregion
+//#region src/session-decode/retained-content-fallback.ts
+/**
+* Honest ≤640 RAM fallback for `getNativeCrop` full-frame misses.
+* Content-sized contain (16:9 → 640×360, 4:3 → 640×480, square → 640×640),
+* never a detection default and never a cross-process ref. Task 3 owns
+* whether this rung stays after telemetry.
+*/
+var RETAINED_FALLBACK_VIEW = {
+	content: {
+		width: 640,
+		height: 640
+	},
+	fit: "contain",
+	format: "rgb"
+};
+/** Resolve a content-sized RGB view from the process-local registry on demand. */
+function createRetainedContentFallback(registry, ref) {
+	return { async materialize() {
+		const lease = registry.acquire(ref);
+		if (!lease) return null;
+		let reason = "error";
+		try {
+			const view = await lease.resolve(RETAINED_FALLBACK_VIEW);
+			if (view.kind !== "view" || view.format !== "rgb" || view.data.byteLength === 0) {
+				reason = "drop";
+				return null;
+			}
+			reason = "success";
+			return {
+				data: Buffer.from(view.data.buffer, view.data.byteOffset, view.data.byteLength),
+				width: view.width,
+				height: view.height,
+				format: "rgb",
+				timestamp: ref.timestamp,
+				...ref.capturedAt !== void 0 ? { capturedAt: ref.capturedAt } : {}
+			};
+		} finally {
+			lease.release(reason);
+		}
+	} };
+}
 /** {@link RETAINED_FRAME_BUDGET_MB} in bytes. */
 var RETAINED_FRAME_BUDGET_BYTES = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_RETAIN_MB"]);
@@ -344,12 +386,24 @@ var RETAINED_FRAME_KEY_PREFIX = "ram:";
 function keyOf(handle) {
 	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
 }
+/**
+* Node-level RAM store of retained rgb detection frames, keyed by
+* `FrameHandle` identity. Latest-wins with a byte budget.
+*/
+/** One retained frame plus the device it belongs to (for the per-device floor). */
+/**
+* Reserved footprint of a lazy contain ≤640 RGB view. Worst-case square
+* 640×640×3 so 4:3 and portrait never exceed the reservation; 16:9 hydrates
+* later settle to 640×360.
+*/
+var CONTENT_SIZED_RESERVE_BYTES = 640 * 640 * 3;
 var RetainedFrameStore = class RetainedFrameStore {
 	nodeId;
 	budgetBytes;
 	perDeviceFloor;
 	timeFloorMs;
 	now;
+	onEvict;
 	/** Insertion-ordered (Map) → globally oldest is `keys().next()`. */
 	entries = /* @__PURE__ */ new Map();
 	/**
@@ -368,6 +422,7 @@ var RetainedFrameStore = class RetainedFrameStore {
 		this.perDeviceFloor = options.perDeviceFloor ?? RETAINED_FRAME_PER_DEVICE_FLOOR;
 		this.timeFloorMs = options.timeFloorMs ?? RETAINED_FRAME_TIME_FLOOR_MS;
 		this.now = options.now ?? Date.now;
+		this.onEvict = options.onEvict;
 	}
 	/** Number of retained frames (tests / metrics). */
 	get size() {
@@ -384,35 +439,76 @@ var RetainedFrameStore = class RetainedFrameStore {
 	* decode-worker IPC delivers a fresh Buffer per frame, so no defensive copy
 	* is needed.
 	*/
-	write(deviceId, frame) {
+	write(deviceId, frame, fallback) {
 		if (frame.format !== "rgb") return null;
-		const seq = ++this.seq;
-		const byteLength = frame.data.byteLength;
-		const handle = {
-			shmId: `${RETAINED_FRAME_KEY_PREFIX}${this.nodeId}:${deviceId}`,
-			slot: seq % RetainedFrameStore.SLOT_SPREAD,
-			seq,
-			width: frame.width,
-			height: frame.height,
-			format: "rgb",
-			pts: performance.now(),
-			byteLength,
-			nodeId: this.nodeId,
-			slotCount: RetainedFrameStore.SLOT_SPREAD
-		};
-		const key = keyOf(handle);
-		this.entries.set(key, {
+		const pixelFree = frame.data.byteLength === 0;
+		const handle = this.mintHandle(deviceId, frame);
+		const reservedBytes = pixelFree ? CONTENT_SIZED_RESERVE_BYTES : handle.byteLength;
+		this.insert(handle, {
 			frame,
 			deviceId,
-			writtenAt: this.now()
+			writtenAt: this.now(),
+			reservedBytes,
+			...pixelFree && fallback ? { fallback } : {}
 		});
-		const deviceKeys = this.perDeviceKeys.get(deviceId);
-		if (deviceKeys) deviceKeys.push(key);
-		else this.perDeviceKeys.set(deviceId, [key]);
-		this.bytes += byteLength;
-		this.evictToBudget();
 		return handle;
 	}
+	/**
+	* Identity-only handle for native hold/tile. Does not retain pixels or
+	* reserve the content-sized worst-case slot — Task 3 continuous path.
+	*/
+	allocateHandle(deviceId, frame) {
+		if (frame.format !== "rgb") return null;
+		return this.mintHandle(deviceId, frame);
+	}
+	/**
+	* Remember a detection-only on-demand fallback. Reserves the content-sized
+	* worst case until hydrate replaces it with the real JPEG/RGB bytes so the
+	* budget can evict unrequested detections. A no-detection frame must never
+	* call this.
+	*/
+	rememberOnDemand(deviceId, handle, fallback) {
+		const key = keyOf(handle);
+		if (this.entries.has(key)) return;
+		this.insert(handle, {
+			frame: {
+				data: Buffer.alloc(0),
+				width: handle.width,
+				height: handle.height,
+				format: "rgb",
+				timestamp: 0
+			},
+			deviceId,
+			writtenAt: this.now(),
+			reservedBytes: CONTENT_SIZED_RESERVE_BYTES,
+			fallback
+		});
+	}
+	has(handle) {
+		return this.entries.has(keyOf(handle));
+	}
+	getDeviceId(handle) {
+		return this.entries.get(keyOf(handle))?.deviceId;
+	}
+	statsByDevice(deviceId) {
+		const keys = this.perDeviceKeys.get(deviceId) ?? [];
+		let bytes = 0;
+		for (const key of keys) bytes += this.entries.get(key)?.reservedBytes ?? 0;
+		return {
+			entries: keys.length,
+			bytes
+		};
+	}
+	deviceStats() {
+		return [...this.perDeviceKeys.keys()].map((deviceId) => ({
+			deviceId,
+			...this.statsByDevice(deviceId)
+		}));
+	}
+	/** Drop one handle (success/error/drop/detach). Idempotent. */
+	drop(handle) {
+		this.dropKey(keyOf(handle));
+	}
 	/** The retained frame for `handle`, or `null` if never retained / already evicted. */
 	getFrame(handle) {
 		return this.entries.get(keyOf(handle))?.frame ?? null;
@@ -427,11 +523,46 @@ var RetainedFrameStore = class RetainedFrameStore {
 	*/
 	crop(handle, bbox, maxWidth) {
 		const entry = this.entries.get(keyOf(handle));
-		if (!entry || entry.frame.format !== "rgb") return null;
+		if (!entry || entry.frame.data.byteLength === 0) return null;
+		if (entry.frame.format === "jpeg") {
+			if (!(bbox.x <= .001 && bbox.y <= .001 && bbox.w >= .999 && bbox.h >= .999)) return null;
+			return {
+				bytes: entry.frame.data,
+				width: entry.frame.width,
+				height: entry.frame.height
+			};
+		}
+		if (entry.frame.format !== "rgb") return null;
 		return cropRgb(entry.frame, bbox, maxWidth);
 	}
+	/**
+	* Full-frame / ROI crop that hydrates a pixel-free handle on demand.
+	* A missing fallback or failed materialize is an explicit miss — never a
+	* 0-byte raster.
+	*/
+	async cropAsync(handle, bbox, maxWidth) {
+		await this.ensureContent(handle);
+		return this.crop(handle, bbox, maxWidth);
+	}
+	/** Materialize a content-sized RGB view once, if the handle still has a fallback. */
+	async ensureContent(handle) {
+		const key = keyOf(handle);
+		const entry = this.entries.get(key);
+		if (!entry) return null;
+		if (entry.frame.data.byteLength > 0) return entry.frame;
+		if (entry.hydrating) return entry.hydrating;
+		if (!entry.fallback) return null;
+		entry.hydrating = this.hydrate(key, entry);
+		try {
+			return await entry.hydrating;
+		} finally {
+			const current = this.entries.get(key);
+			if (current) current.hydrating = void 0;
+		}
+	}
 	/** Drop every retained frame (node/addon shutdown). */
 	clear() {
+		for (const entry of this.entries.values()) entry.fallback?.release?.();
 		this.entries.clear();
 		this.perDeviceKeys.clear();
 		this.bytes = 0;
@@ -456,7 +587,7 @@ var RetainedFrameStore = class RetainedFrameStore {
 			if (!entry) continue;
 			if (this.timeFloorMs > 0 && nowMs - entry.writtenAt < this.timeFloorMs) continue;
 			const deviceKeys = this.perDeviceKeys.get(entry.deviceId);
-			if (deviceKeys && deviceKeys.length > this.perDeviceFloor) this.dropKey(key);
+			if (deviceKeys && deviceKeys.length > this.perDeviceFloor) this.dropKey(key, "evict");
 		}
 		if (this.bytes <= this.budgetBytes) return;
 		for (const key of oldestFirst) {
@@ -464,27 +595,68 @@ var RetainedFrameStore = class RetainedFrameStore {
 			const entry = this.entries.get(key);
 			if (!entry) continue;
 			const deviceKeys = this.perDeviceKeys.get(entry.deviceId);
-			if (deviceKeys && deviceKeys.length > this.perDeviceFloor) this.dropKey(key);
+			if (deviceKeys && deviceKeys.length > this.perDeviceFloor) this.dropKey(key, "evict");
 		}
 		if (this.bytes <= this.budgetBytes) return;
 		for (const key of oldestFirst) {
 			if (this.bytes <= this.budgetBytes || this.entries.size <= 1) break;
-			this.dropKey(key);
+			this.dropKey(key, "evict");
 		}
 		if (this.bytes < 0) this.bytes = 0;
 	}
+	async hydrate(key, entry) {
+		const view = await entry.fallback?.materialize();
+		const current = this.entries.get(key);
+		if (!current) return null;
+		if (!view || view.data.byteLength === 0) return null;
+		if (view.format !== "rgb" && view.format !== "jpeg") return null;
+		current.frame = view;
+		current.fallback = void 0;
+		this.bytes -= current.reservedBytes;
+		current.reservedBytes = view.data.byteLength;
+		this.bytes += current.reservedBytes;
+		this.evictToBudget();
+		return view;
+	}
+	mintHandle(deviceId, frame) {
+		const seq = ++this.seq;
+		const pixelFree = frame.data.byteLength === 0;
+		return {
+			shmId: `${RETAINED_FRAME_KEY_PREFIX}${this.nodeId}:${deviceId}`,
+			slot: seq % RetainedFrameStore.SLOT_SPREAD,
+			seq,
+			width: frame.width,
+			height: frame.height,
+			format: "rgb",
+			pts: performance.now(),
+			byteLength: pixelFree ? 0 : frame.data.byteLength,
+			nodeId: this.nodeId,
+			slotCount: RetainedFrameStore.SLOT_SPREAD
+		};
+	}
+	insert(handle, entry) {
+		const key = keyOf(handle);
+		this.entries.set(key, entry);
+		const deviceKeys = this.perDeviceKeys.get(entry.deviceId);
+		if (deviceKeys) deviceKeys.push(key);
+		else this.perDeviceKeys.set(entry.deviceId, [key]);
+		this.bytes += entry.reservedBytes;
+		this.evictToBudget();
+	}
 	/** Remove one frame by key, keeping the byte tally + per-device index exact. */
-	dropKey(key) {
+	dropKey(key, reason = "drop") {
 		const entry = this.entries.get(key);
 		if (!entry) return;
 		this.entries.delete(key);
-		this.bytes -= entry.frame.data.byteLength;
+		entry.fallback?.release?.();
+		this.bytes -= entry.reservedBytes;
 		const deviceKeys = this.perDeviceKeys.get(entry.deviceId);
 		if (deviceKeys) {
 			const idx = deviceKeys.indexOf(key);
 			if (idx >= 0) deviceKeys.splice(idx, 1);
 			if (deviceKeys.length === 0) this.perDeviceKeys.delete(entry.deviceId);
 		}
+		if (reason === "evict") this.onEvict?.(entry.deviceId);
 	}
 };
 /**
@@ -761,7 +933,8 @@ var SessionDecodeSession = class {
 				this.settleNativeCrop(raw.requestId, {
 					bytes: raw.bytes,
 					width: raw.width,
-					height: raw.height
+					height: raw.height,
+					...raw.source ? { source: raw.source } : {}
 				});
 				return;
 			case "nativeCropMiss":
@@ -1021,26 +1194,6 @@ function createSessionDecodeCoordinator(deps) {
 //#endregion
 //#region src/session-decode/session-decode-pump.ts
 /**
-* Detection working width cap — mirrors the shm decoder's
-* `initScaler` (`nodeav-decoder-session.ts`: `maxW = floor(640 / scale)`,
-* `scale = 1` default). The worker decodes full source resolution (e.g. a 4K
-* `native:main` stream); without this downscale `toBuffer` would ship a full
-* 3840×2160 rgb frame (~24 MB) over IPC per pull, which the detection path
-* cannot keep up with. Aspect ratio is preserved. A source already ≤ this
-* width (e.g. the small `native:sub` motion stream) is passed through
-* unscaled, exactly as the shm scaler's `min(srcW, maxW)` no-ops.
-*/
-var WORKING_MAX_WIDTH = 640;
-/** Aspect-preserving cap to {@link WORKING_MAX_WIDTH}; `undefined` when no downscale is needed. */
-function resolveWorkingResize(width, height) {
-	if (width <= WORKING_MAX_WIDTH || width <= 0) return void 0;
-	const outWidth = WORKING_MAX_WIDTH;
-	return {
-		width: outWidth,
-		height: Math.round(outWidth * height / width)
-	};
-}
-/**
 * 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.
@@ -1049,17 +1202,18 @@ function resolveWorkingResize(width, height) {
 * time) — this is what lets Step 5 MEASURE session-decode frameAge vs the
 * shm-ring cameras.
 */
-async function toDecodedFrame(frame, format) {
-	const resize = resolveWorkingResize(frame.image.width, frame.image.height);
-	const bytes = await frame.image.toBuffer({
-		format,
-		...resize ? { resize } : {}
-	});
+async function toDecodedFrame(frame, format, viewSpec) {
+	const geometry = viewSpec ? resolveFrameViewGeometry(frame.image.width, frame.image.height, viewSpec) : void 0;
+	const bytes = await frame.image.toBuffer(geometry ? {
+		crop: geometry.sourceCrop,
+		resize: geometry.output,
+		format: viewSpec?.format ?? format
+	} : { format });
 	return {
 		data: Buffer.from(bytes),
-		width: resize?.width ?? frame.image.width,
-		height: resize?.height ?? frame.image.height,
-		format,
+		width: geometry?.output.width ?? frame.image.width,
+		height: geometry?.output.height ?? frame.image.height,
+		format: viewSpec?.format ?? format,
 		timestamp: frame.timestamp,
 		capturedAt: Date.now()
 	};
@@ -1116,9 +1270,9 @@ function startSessionDecodePump(deps) {
 					frame.image.close();
 					break;
 				}
+				let imageOwnershipTransferred = false;
 				try {
 					if (deps.shouldMaterializeFrame && !deps.shouldMaterializeFrame()) continue;
-					const decoded = await toDecodedFrame(frame, format);
 					const image = frame.image;
 					const cropFn = image.nativeCrop;
 					const nativeCrop = cropFn ? Object.assign((bbox, maxWidth) => cropFn(bbox, maxWidth), {
@@ -1126,7 +1280,33 @@ function startSessionDecodePump(deps) {
 						release: () => image.releaseNativeLease?.(),
 						markInferred: () => image.markInferred?.()
 					}) : void 0;
-					deps.onDecodedFrame(decoded, nativeCrop);
+					if (deps.frameRegistry && deps.onFrameRef) {
+						const capturedAt = Date.now();
+						const ref = deps.frameRegistry.register(image, {
+							timestamp: frame.timestamp,
+							capturedAt
+						});
+						imageOwnershipTransferred = true;
+						if (!ref) continue;
+						const lazyFrame = {
+							data: Buffer.alloc(0),
+							width: ref.width,
+							height: ref.height,
+							format: ref.format,
+							timestamp: ref.timestamp,
+							capturedAt,
+							frameRef: ref
+						};
+						try {
+							if (!await deps.onFrameRef(lazyFrame, nativeCrop)) deps.frameRegistry.release(ref, "drop");
+						} catch (err) {
+							deps.frameRegistry.release(ref, "error");
+							throw err;
+						}
+					} else {
+						const decoded = await toDecodedFrame(frame, format, deps.inlineViewSpec);
+						deps.onDecodedFrame(decoded, nativeCrop);
+					}
 				} catch (err) {
 					deps.logger.debug("session-decode pump: skipped a frame (decode/consume error)", {
 						tags: { deviceId: deps.source.deviceId },
@@ -1136,7 +1316,7 @@ function startSessionDecodePump(deps) {
 						}
 					});
 				} finally {
-					frame.image.close();
+					if (!imageOwnershipTransferred) frame.image.close();
 				}
 			}
 		} catch (err) {
@@ -1526,6 +1706,424 @@ function buildBenchRunPipelineInput(req) {
 	};
 }
 //#endregion
+//#region src/pipeline-runner/frame-lazy-metrics.ts
+function emptyFrameLazyCounters() {
+	return {
+		framesDecoded: 0,
+		framesAdmitted: 0,
+		framesDroppedPixelFree: 0,
+		viewsMaterialized: 0,
+		viewsSkipped: 0,
+		workerToRunnerBytes: 0,
+		runnerToPoolRawBytes: 0,
+		runnerToPoolJpegBytes: 0,
+		onDemandFullFrameRequests: 0,
+		onDemandCropRequests: 0,
+		nativeHits: 0,
+		nativeMisses: 0,
+		tileHits: 0,
+		tileMisses: 0,
+		fallbackHits: 0,
+		fallbackMisses: 0,
+		retainedWritesAvoided: 0,
+		residentRefs: 0,
+		residentBytes: 0,
+		releases: 0,
+		evictions: 0,
+		staleMisses: 0
+	};
+}
+var FrameLazyTelemetry = class {
+	node = emptyFrameLazyCounters();
+	cameras = /* @__PURE__ */ new Map();
+	noteDecoded(deviceId) {
+		this.node.framesDecoded += 1;
+		this.camera(deviceId).framesDecoded += 1;
+	}
+	noteAdmitted(deviceId) {
+		this.node.framesAdmitted += 1;
+		this.camera(deviceId).framesAdmitted += 1;
+	}
+	noteDroppedPixelFree(deviceId) {
+		this.node.framesDroppedPixelFree += 1;
+		this.camera(deviceId).framesDroppedPixelFree += 1;
+	}
+	noteView(input) {
+		if (input.materialized) {
+			this.node.viewsMaterialized += 1;
+			this.camera(input.deviceId).viewsMaterialized += 1;
+		} else {
+			this.node.viewsSkipped += 1;
+			this.camera(input.deviceId).viewsSkipped += 1;
+		}
+		this.node.workerToRunnerBytes += input.workerToRunnerBytes;
+		this.camera(input.deviceId).workerToRunnerBytes += input.workerToRunnerBytes;
+	}
+	notePoolBytes(input) {
+		this.node.runnerToPoolRawBytes += input.raw;
+		this.node.runnerToPoolJpegBytes += input.jpeg;
+		this.camera(input.deviceId).runnerToPoolRawBytes += input.raw;
+		this.camera(input.deviceId).runnerToPoolJpegBytes += input.jpeg;
+	}
+	noteOnDemandRequest(input) {
+		if (input.kind === "full-frame") {
+			this.node.onDemandFullFrameRequests += 1;
+			this.camera(input.deviceId).onDemandFullFrameRequests += 1;
+		} else {
+			this.node.onDemandCropRequests += 1;
+			this.camera(input.deviceId).onDemandCropRequests += 1;
+		}
+	}
+	noteHit(kind, deviceId) {
+		this.addHit(this.node, kind, 1);
+		this.addHit(this.camera(deviceId), kind, 1);
+	}
+	noteMiss(kind, deviceId) {
+		this.addMiss(this.node, kind, 1);
+		this.addMiss(this.camera(deviceId), kind, 1);
+	}
+	noteAvoidedWrite(deviceId) {
+		this.node.retainedWritesAvoided += 1;
+		this.camera(deviceId).retainedWritesAvoided += 1;
+	}
+	noteRelease(deviceId) {
+		this.node.releases += 1;
+		if (deviceId !== void 0) this.camera(deviceId).releases += 1;
+	}
+	noteEviction(deviceId) {
+		this.node.evictions += 1;
+		if (deviceId !== void 0) this.camera(deviceId).evictions += 1;
+	}
+	noteStale(deviceId) {
+		this.node.staleMisses += 1;
+		if (deviceId !== void 0) this.camera(deviceId).staleMisses += 1;
+	}
+	/**
+	* Node occupancy. `residentRefs` is entry count (pending + store), not
+	* outstanding registry leases.
+	*/
+	setResident(input) {
+		this.node.residentRefs = input.refs;
+		this.node.residentBytes = input.bytes;
+	}
+	setCameraResident(deviceId, input) {
+		const counters = this.camera(deviceId);
+		counters.residentRefs = input.refs;
+		counters.residentBytes = input.bytes;
+	}
+	forgetCamera(deviceId) {
+		this.cameras.delete(deviceId);
+	}
+	/**
+	* Zero occupancy for already-tracked cameras absent from `present`.
+	* Does not create or delete entries — snapshot still does not prune,
+	* and detach still goes through {@link forgetCamera}.
+	*/
+	zeroAbsentResidents(present) {
+		for (const [deviceId, counters] of this.cameras) {
+			if (present.has(deviceId)) continue;
+			counters.residentRefs = 0;
+			counters.residentBytes = 0;
+		}
+	}
+	snapshot(deviceIds) {
+		return {
+			node: { ...this.node },
+			cameras: deviceIds.map((deviceId) => ({
+				deviceId,
+				...this.camera(deviceId)
+			}))
+		};
+	}
+	trackedCameraCount() {
+		return this.cameras.size;
+	}
+	camera(deviceId) {
+		const existing = this.cameras.get(deviceId);
+		if (existing) return existing;
+		const created = emptyFrameLazyCounters();
+		this.cameras.set(deviceId, created);
+		return created;
+	}
+	addHit(counters, kind, n) {
+		if (kind === "native") counters.nativeHits += n;
+		else if (kind === "tile") counters.tileHits += n;
+		else counters.fallbackHits += n;
+	}
+	addMiss(counters, kind, n) {
+		if (kind === "native") counters.nativeMisses += n;
+		else if (kind === "tile") counters.tileMisses += n;
+		else counters.fallbackMisses += n;
+	}
+};
+//#endregion
+//#region src/pipeline-runner/frame-ref-transport.ts
+/** A local ref never leaves the grouped process; inline remains rollback/split compatibility. */
+function selectExecutorFrameSource(coLocated, frameRef, inlineFrame) {
+	return coLocated && frameRef ? { frameRef } : { frame: inlineFrame };
+}
+//#endregion
+//#region src/session-decode/on-demand-jpeg-fallback.ts
+/** Single content-sized JPEG requested after a detection, never a continuous raw. */
+var ON_DEMAND_JPEG_VIEW = {
+	content: {
+		width: 640,
+		height: 640
+	},
+	fit: "contain",
+	format: "jpeg"
+};
+function createOnDemandJpegFallback(registry, ref) {
+	const lease = registry.acquire(ref);
+	let cached;
+	let released = false;
+	const releaseLease = (reason) => {
+		if (released) return;
+		released = true;
+		lease?.release(reason);
+	};
+	return {
+		async materialize() {
+			if (cached !== void 0) return cached;
+			if (!lease) {
+				cached = null;
+				return null;
+			}
+			try {
+				const view = await lease.resolve(ON_DEMAND_JPEG_VIEW);
+				if (view.kind !== "view" || view.format !== "jpeg" || view.data.byteLength === 0) {
+					cached = null;
+					releaseLease("drop");
+					return null;
+				}
+				cached = {
+					data: Buffer.from(view.data.buffer, view.data.byteOffset, view.data.byteLength),
+					width: view.width,
+					height: view.height,
+					format: "jpeg",
+					timestamp: ref.timestamp,
+					...ref.capturedAt !== void 0 ? { capturedAt: ref.capturedAt } : {}
+				};
+				releaseLease("success");
+				return cached;
+			} catch {
+				cached = null;
+				releaseLease("error");
+				return null;
+			}
+		},
+		release() {
+			releaseLease("eviction");
+		}
+	};
+}
+//#endregion
+//#region src/pipeline-runner/on-demand-retention.ts
+var CAMSTACK_CONTINUOUS_RETAIN = "CAMSTACK_CONTINUOUS_RETAIN";
+function isContinuousRetainEnabled(env = process.env) {
+	return env[CAMSTACK_CONTINUOUS_RETAIN] === "1";
+}
+function shouldRetainDetectionFrame(input) {
+	if (!input.admitted) return false;
+	if (input.continuousRetain) return true;
+	return input.hasDetection;
+}
+function encodeCrossNodeCrop(input) {
+	if (!input.jpeg) return null;
+	return { jpeg: input.jpeg };
+}
+function handleKey(handle) {
+	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
+}
+/**
+* Pending occupancy exists only admission → inference result. A detection
+* transfers to {@link RetainedFrameStore} (authoritative late-media owner).
+* No-detection leaves zero state. Store eviction owns fallback cleanup.
+*/
+var OnDemandRetentionSession = class {
+	store;
+	registry;
+	telemetry;
+	continuousRetain;
+	pending = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.store = options.store;
+		this.registry = options.registry;
+		this.telemetry = options.telemetry;
+		this.continuousRetain = options.continuousRetain;
+	}
+	get pendingSize() {
+		return this.pending.size;
+	}
+	hasPending(handle) {
+		return this.pending.has(handleKey(handle));
+	}
+	admitFrame(deviceId, frame) {
+		if (this.continuousRetain) {
+			const fallback = frame.frameRef ? createRetainedContentFallback(this.registry, frame.frameRef) : void 0;
+			const handle = this.store.write(deviceId, frame, fallback) ?? void 0;
+			if (handle) this.pending.set(handleKey(handle), {
+				deviceId,
+				ref: frame.frameRef
+			});
+			this.refreshResident();
+			return handle;
+		}
+		const handle = this.store.allocateHandle(deviceId, frame) ?? void 0;
+		if (!handle) return void 0;
+		this.pending.set(handleKey(handle), {
+			deviceId,
+			ref: frame.frameRef
+		});
+		this.telemetry.noteAvoidedWrite(deviceId);
+		this.refreshResident();
+		return handle;
+	}
+	noteFrame(input) {
+		if (input.decoded) this.telemetry.noteDecoded(input.deviceId);
+		if (input.admitted) this.telemetry.noteAdmitted(input.deviceId);
+		if (input.droppedPixelFree) this.telemetry.noteDroppedPixelFree(input.deviceId);
+	}
+	noteInferenceResult(deviceId, handle, result) {
+		if (!handle) return;
+		const key = handleKey(handle);
+		const pending = this.pending.get(key);
+		this.forgetPending(key);
+		if (!shouldRetainDetectionFrame({
+			admitted: true,
+			hasDetection: (result.detections?.length ?? 0) > 0,
+			continuousRetain: this.continuousRetain
+		})) {
+			this.refreshResident();
+			return;
+		}
+		if (this.continuousRetain) {
+			this.refreshResident();
+			return;
+		}
+		if (!pending?.ref) {
+			this.refreshResident();
+			return;
+		}
+		const fallback = createOnDemandJpegFallback(this.registry, pending.ref);
+		this.store.rememberOnDemand(deviceId, handle, fallback);
+		this.refreshResident();
+	}
+	async requestMedia(handle, request) {
+		const deviceId = this.store.getDeviceId(handle) ?? this.pending.get(handleKey(handle))?.deviceId ?? 0;
+		const kind = request.kind === "full-frame" ? "full-frame" : "crop";
+		this.telemetry.noteOnDemandRequest({
+			deviceId,
+			kind
+		});
+		if (request.nativeHit) {
+			this.telemetry.noteHit("native", deviceId);
+			return {
+				tier: "native",
+				bytes: request.nativeHit.bytes,
+				width: request.nativeHit.width,
+				height: request.nativeHit.height
+			};
+		}
+		this.telemetry.noteMiss("native", deviceId);
+		if (request.tileHit) {
+			this.telemetry.noteHit("tile", deviceId);
+			return {
+				tier: "tile",
+				bytes: request.tileHit.bytes,
+				jpeg: request.tileHit.jpeg ? request.tileHit.bytes : void 0,
+				width: request.tileHit.width,
+				height: request.tileHit.height
+			};
+		}
+		this.telemetry.noteMiss("tile", deviceId);
+		if (request.recordedStillHit) return {
+			tier: "recorded-still",
+			jpeg: request.recordedStillHit.jpeg,
+			width: request.recordedStillHit.width,
+			height: request.recordedStillHit.height
+		};
+		if (!this.continuousRetain && !this.store.has(handle)) {
+			this.telemetry.noteMiss("fallback", deviceId);
+			return { tier: "miss" };
+		}
+		const view = await this.store.ensureContent(handle);
+		if (view && view.data.byteLength > 0) {
+			this.telemetry.noteHit("fallback", deviceId);
+			this.refreshResident();
+			if (view.format === "jpeg") return {
+				tier: "fallback-jpeg",
+				jpeg: view.data,
+				width: view.width,
+				height: view.height
+			};
+			return {
+				tier: "fallback-jpeg",
+				bytes: view.data,
+				width: view.width,
+				height: view.height
+			};
+		}
+		this.telemetry.noteMiss("fallback", deviceId);
+		this.telemetry.noteStale(deviceId);
+		return { tier: "miss" };
+	}
+	/**
+	* Pending cleanup. Success never invalidates a store entry already
+	* transferred for late pull. Drop/error/detach drop the store only when the
+	* handle was still pending (not yet transferred). Eviction owns transferred
+	* fallback cleanup.
+	*/
+	release(handle, reason) {
+		const key = handleKey(handle);
+		const pending = this.pending.get(key);
+		this.forgetPending(key);
+		if (reason !== "success" && pending) this.store.drop(handle);
+		this.telemetry.noteRelease(pending?.deviceId ?? this.store.getDeviceId(handle));
+		this.refreshResident();
+	}
+	forgetDevice(deviceId) {
+		for (const [key, pending] of [...this.pending]) {
+			if (pending.deviceId !== deviceId) continue;
+			this.pending.delete(key);
+		}
+		this.telemetry.forgetCamera(deviceId);
+		this.refreshResident();
+	}
+	syncResident() {
+		this.refreshResident();
+	}
+	forgetPending(key) {
+		this.pending.delete(key);
+	}
+	refreshResident() {
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const pending of this.pending.values()) {
+			const cur = byDevice.get(pending.deviceId) ?? {
+				refs: 0,
+				bytes: 0
+			};
+			cur.refs += 1;
+			byDevice.set(pending.deviceId, cur);
+		}
+		for (const stats of this.store.deviceStats()) {
+			const cur = byDevice.get(stats.deviceId) ?? {
+				refs: 0,
+				bytes: 0
+			};
+			cur.refs += stats.entries;
+			cur.bytes += stats.bytes;
+			byDevice.set(stats.deviceId, cur);
+		}
+		this.telemetry.setResident({
+			refs: this.pending.size + this.store.size,
+			bytes: this.registry.estimatedBytes + this.store.retainedBytes
+		});
+		this.telemetry.zeroAbsentResidents(new Set(byDevice.keys()));
+		for (const [deviceId, stats] of byDevice) this.telemetry.setCameraResident(deviceId, stats);
+	}
+};
+//#endregion
 //#region src/pipeline-runner/capacity/capacity-runner.ts
 /**
 * Run ONE ramp step: `cameras` independent open-loop pacers for
@@ -2435,6 +3033,35 @@ function summarizeRunnerHardware(hardware, cpuCores = os.cpus().length) {
 	};
 }
 //#endregion
+//#region src/pipeline-runner/motion-frame-view.ts
+var MOTION_FRAME_VIEW = {
+	content: {
+		width: 320,
+		height: 320
+	},
+	fit: "contain",
+	format: "gray"
+};
+/**
+* Materialize the motion gray view under a short-lived registry lease.
+* Release is idempotent and always runs, including miss/error.
+*/
+async function resolveMotionFrameView(registry, ref) {
+	const lease = registry.acquire(ref);
+	if (!lease) return {
+		kind: "miss",
+		reason: ref.registryId === registry.registryId ? "stale-ref" : "foreign-registry"
+	};
+	let reason = "error";
+	try {
+		const view = await lease.resolve(MOTION_FRAME_VIEW);
+		reason = view.kind === "view" ? "success" : "drop";
+		return view;
+	} finally {
+		lease.release(reason);
+	}
+}
+//#endregion
 //#region src/pipeline-runner/motion-settle-governor.ts
 /**
 * MotionSettleGovernor — decides WHEN the root-plane `package-detection` step
@@ -2697,6 +3324,13 @@ function resolveNativeCropSource(isFullFrame, nativeHit) {
 	if (nativeHit) return "native";
 	return isFullFrame ? "ram-fullframe" : "miss";
 }
+/**
+* Runtime hit kind for telemetry. A worker tile is native-resolution quality
+* (public wire `tier` stays `native`) but must not increment `nativeHits`.
+*/
+function resolveNativeCropHitKind(source) {
+	return source === "tile" ? "tile" : "native";
+}
 //#endregion
 //#region src/pipeline-runner/native-lease-settings-source.ts
 /**
@@ -2879,18 +3513,23 @@ var FrameQueue = class {
 	latest = null;
 	_droppedFrames = 0;
 	clone;
+	dispose;
 	/**
 	* `clone` runs on every {@link enqueue} to detach a queue-owned copy from
 	* the (possibly borrowed) source — required by the D9 Task 7b ownership
 	* contract above. Motion call sites pass {@link ownFrame}; the detection
 	* path passes a clone that copies its inner frame's pixel buffer.
 	*/
-	constructor(maxSize, clone) {
+	constructor(maxSize, clone, dispose) {
 		this.maxSize = maxSize;
 		this.clone = clone;
+		this.dispose = dispose;
 	}
 	enqueue(item) {
-		if (this.latest !== null) this._droppedFrames++;
+		if (this.latest !== null) {
+			this._droppedFrames++;
+			this.dispose?.(this.latest);
+		}
 		this.latest = this.clone(item);
 	}
 	dequeue() {
@@ -2905,6 +3544,7 @@ var FrameQueue = class {
 		return this._droppedFrames;
 	}
 	clear() {
+		if (this.latest !== null) this.dispose?.(this.latest);
 		this.latest = null;
 	}
 };
@@ -3307,7 +3947,8 @@ function toFrameInput$1(frame) {
 		width: frame.width,
 		height: frame.height,
 		format: frame.format,
-		timestamp: frame.timestamp
+		timestamp: frame.timestamp,
+		...frame.frameRef ? { frameRef: frame.frameRef } : {}
 	};
 }
 /**
@@ -3406,7 +4047,10 @@ var PipelineRunner = class {
 	}
 	registerCamera(deviceId, registration) {
 		const motionQueue = new FrameQueue(this.config.maxQueueDepth, ownMotionEntry);
-		const detectionQueue = new FrameQueue(this.config.maxQueueDepth, ownDetectionEntry);
+		const detectionQueue = new FrameQueue(this.config.maxQueueDepth, ownDetectionEntry, (entry) => {
+			if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
+			if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
+		});
 		const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
 		const state = {
 			registration,
@@ -3804,9 +4448,13 @@ var PipelineRunner = class {
 		};
 		const semAcquiredAt = Date.now();
 		const executorHandle = state.detectionQueue.size <= HANDLE_PASSTHROUGH_MAX_QUEUE_DEPTH && this.semaphore.available > 0 ? handle : void 0;
+		let frameReleaseReason = "error";
 		try {
 			const result = await this.awaitInferenceBounded(deviceId, frameInput, executorHandle, release);
-			if (result === TIMED_OUT) return;
+			if (result === TIMED_OUT) {
+				frameReleaseReason = "drop";
+				return;
+			}
 			const inferDoneAt = Date.now();
 			const inferenceMs = inferDoneAt - semAcquiredAt;
 			state.inferenceTimes.push(inferenceMs);
@@ -3815,6 +4463,7 @@ var PipelineRunner = class {
 			if (result) {
 				if (result.shed === true) state.shedFrames++;
 				await this.notifyCallbacks(deviceId, frame, result, streamType, handle);
+				frameReleaseReason = "success";
 				const emittedAt = Date.now();
 				const capturedAt = frame.capturedAt;
 				this.timingSampler.addSample(deviceId, {
@@ -3826,9 +4475,16 @@ var PipelineRunner = class {
 					endToEnd: emittedAt - enqueuedAt,
 					detections: result.detections?.length ?? 0
 				});
-			}
+			} else frameReleaseReason = "drop";
+		} catch {
+			frameReleaseReason = "error";
 		} finally {
 			release();
+			try {
+				if (frameReleaseReason === "success" && handle && isContinuousRetainEnabled()) await this.config.hydrateRetainedFrame?.(handle);
+			} catch {}
+			if (handle) this.config.releaseRetention?.(handle, frameReleaseReason);
+			if (frame.frameRef) this.config.releaseFrameRef?.(frame.frameRef, frameReleaseReason);
 		}
 	}
 	/**
@@ -4178,6 +4834,20 @@ var DEFAULT_CONFIG = {
 *  than raw RGB — the hop transits the hub main process (UDS child↔child
 *  routing), which OOM'd under raw frames. */
 var DETECTION_HOP_JPEG_QUALITY = 82;
+var SPLIT_DETECTION_VIEW = {
+	content: {
+		width: 640,
+		height: 640
+	},
+	fit: "contain",
+	format: "rgb"
+};
+function writeRetainedDetectionFrame(store, deviceId, frame, retention) {
+	if (retention) return retention.admitFrame(deviceId, frame);
+	if (!store) return void 0;
+	if (!isContinuousRetainEnabled()) return store.allocateHandle(deviceId, frame) ?? void 0;
+	return store.write(deviceId, frame, frame.frameRef ? createRetainedContentFallback(localFrameRegistry, frame.frameRef) : void 0) ?? void 0;
+}
 var DETECTION_KEEPWARM_MS = 15e3;
 /**
 * Occupancy-burst safety timeout (both the dial path and the analyzer-tap
@@ -4498,6 +5168,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* Initialised in {@link onInitialize} once `nodeId` is known.
 	*/
 	retainedFrames = null;
+	frameLazy = new FrameLazyTelemetry();
+	retention = null;
 	attached = /* @__PURE__ */ new Map();
 	/**
 	* Detection decode workers parked across a detach, keyed by deviceId — see
@@ -4676,7 +5348,15 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.nodeId = raw.includes("/") ? raw.split("/")[0] : raw;
 		this.retainedFrames = new RetainedFrameStore({
 			nodeId: this.nodeId,
-			logger: this.ctx.logger.child("retained-frames")
+			logger: this.ctx.logger.child("retained-frames"),
+			onEvict: (deviceId) => this.frameLazy.noteEviction(deviceId)
+		});
+		this.retention = new OnDemandRetentionSession({
+			store: this.retainedFrames,
+			registry: localFrameRegistry,
+			telemetry: this.frameLazy,
+			nodeId: this.nodeId,
+			continuousRetain: isContinuousRetainEnabled()
 		});
 		this.runner = new PipelineRunner({
 			maxQueueDepth: this.config.maxQueueDepth,
@@ -4685,6 +5365,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			minThrottledFps: this.config.minThrottledFps,
 			processFrame: (deviceId, frame, handle) => this.runInference(deviceId, frame, handle),
 			analyzeMotion: (deviceId, frame, handle) => this.runMotionAnalysis(deviceId, frame, handle),
+			releaseFrameRef: (ref, reason) => localFrameRegistry.release(ref, reason),
+			releaseRetention: (handle, reason) => this.retention?.release(handle, reason),
+			hydrateRetainedFrame: (handle) => this.retainedFrames?.ensureContent(handle) ?? Promise.resolve(null),
 			onPhaseChanged: (deviceId, phase, meta) => this.handlePhaseChanged(deviceId, phase, meta),
 			logger: this.ctx.logger,
 			onOccupancyRecheck: (deviceId, frames) => {
@@ -4701,6 +5384,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			this.handleDetectionStreamChange(deviceId, action);
 		});
 		this.runner.onResult(async (deviceId, frame, result, _streamType, handle) => {
+			this.retention?.noteInferenceResult(deviceId, handle, result);
 			this.cutSubjectTiles(deviceId, result, handle);
 			this.emitInferenceResult(deviceId, frame, result, handle);
 			const detectionCount = result.detections?.length ?? 0;
@@ -4796,6 +5480,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.nativeCropRegistry.clear();
 		this.retainedFrames?.clear();
 		this.retainedFrames = null;
+		this.retention = null;
 	}
 	async cacheBenchFrame(input) {
 		const { data, info } = await (await getSharp())(Buffer.from(input.imageBase64, "base64")).raw().toBuffer({ resolveWithObject: true });
@@ -5548,11 +6233,22 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* resolve legitimately want the lower-RES honest frame).
 	*/
 	async getNativeCrop(input) {
+		const deviceId = this.nativeCropRegistry.deviceIdFor(input.handle) ?? 0;
+		const isFullFrame = input.bbox.x <= .001 && input.bbox.y <= .001 && input.bbox.w >= .999 && input.bbox.h >= .999;
+		this.frameLazy.noteOnDemandRequest({
+			deviceId,
+			kind: isFullFrame && input.maxWidth === void 0 ? "full-frame" : "crop"
+		});
 		const resolved = await this.resolveNativeCropPixels(input);
-		if (resolved.tier === "native" && resolved.pixels !== null) return this.encodeNativeCropResult(resolved.pixels, resolved.tier, input.encodeJpeg);
+		if (resolved.tier === "native" && resolved.pixels !== null) {
+			this.frameLazy.noteHit(resolveNativeCropHitKind(resolved.pixels.source), deviceId);
+			return this.encodeNativeCropResult(resolved.pixels, resolved.tier, input.encodeJpeg);
+		}
+		this.frameLazy.noteMiss("native", deviceId);
 		if (resolved.tier !== "ram-fullframe") return null;
-		const crop = this.retainedFrames?.crop(input.handle, input.bbox, input.maxWidth);
+		const crop = await this.retainedFrames?.cropAsync(input.handle, input.bbox, input.maxWidth);
 		if (!crop) {
+			this.frameLazy.noteMiss("fallback", deviceId);
 			this.ctx?.logger.warn("native full-frame miss — the retained store no longer holds this frame", {
 				tags: { deviceId: this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
 				meta: {
@@ -5566,6 +6262,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			});
 			return null;
 		}
+		this.frameLazy.noteHit("fallback", deviceId);
 		return this.encodeNativeCropResult({
 			bytes: crop.bytes,
 			width: crop.width,
@@ -5588,6 +6285,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	*/
 	cutSubjectTiles(deviceId, result, handle) {
 		const outcome = this.dispatchSubjectTiles(result, handle);
+		if ((result.detections?.length ?? 0) > 0) if (outcome === "sent") this.frameLazy.noteHit("tile", deviceId);
+		else this.frameLazy.noteMiss("tile", deviceId);
 		if (outcome === "sent") return;
 		const tally = this.tileCutDrops.get(deviceId) ?? {
 			handleless: 0,
@@ -5689,7 +6388,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				if (result) nativeResult = {
 					bytes: result.bytes,
 					width: result.width,
-					height: result.height
+					height: result.height,
+					...result.source ? { source: result.source } : {}
 				};
 				else missReason = "worker-lease-gone";
 			} else missReason = "no-registry-entry";
@@ -5728,6 +6428,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* (`null`) — the caller retries — never a silent raw-RGB cross-node fallback.
 	*/
 	async encodeNativeCropResult(crop, tier, encodeJpeg) {
+		if (crop.bytes.byteLength >= 2 && crop.bytes[0] === 255 && crop.bytes[1] === 216) {
+			const encoded = encodeCrossNodeCrop({ jpeg: Buffer.from(crop.bytes).toString("base64") });
+			if (!encoded) return null;
+			return {
+				jpeg: encoded.jpeg,
+				width: crop.width,
+				height: crop.height,
+				tier
+			};
+		}
 		if (encodeJpeg !== true) return {
 			bytes: crop.bytes,
 			width: crop.width,
@@ -5735,12 +6445,17 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			tier
 		};
 		try {
-			return {
+			const encoded = encodeCrossNodeCrop({
 				jpeg: (await (await getSharp())(Buffer.from(crop.bytes), { raw: {
 					width: crop.width,
 					height: crop.height,
 					channels: 3
 				} }).jpeg({ quality: 90 }).toBuffer()).toString("base64"),
+				bytes: crop.bytes
+			});
+			if (!encoded) return null;
+			return {
+				jpeg: encoded.jpeg,
 				width: crop.width,
 				height: crop.height,
 				tier
@@ -6081,6 +6796,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
+		this.retention?.forgetDevice(deviceId);
 		this.runner?.unregisterCamera(deviceId);
 		this.ctx?.logger.info("detachCamera", {
 			tags: { deviceId },
@@ -6275,9 +6991,11 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			avgInferenceTimeMs: 0,
 			queueDepth: 0
 		};
+		this.retention?.syncResident();
 		return {
 			nodeId: this.nodeId,
-			...m
+			...m,
+			frameLazy: this.frameLazy.snapshot(this.getLocalCameras())
 		};
 	}
 	async getCameraMetrics(input) {
@@ -6437,9 +7155,11 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config), true),
 			startPump: (source) => {
 				const dialMs = Date.now() - requestedAt;
+				const useLocalFrameRef = this.executorCoLocated() && process.env["CAMSTACK_DISABLE_LOCAL_FRAME_REF"] !== "1";
 				log.info("session-decode: detection routed through per-session decode worker (rgb)", { meta: {
 					streamId: config.detectionStreamId,
-					codec: source.codec
+					codec: source.codec,
+					transport: useLocalFrameRef ? "local-frame-ref" : "inline-compat"
 				} });
 				let reservation = null;
 				return startSessionDecodePump({
@@ -6452,8 +7172,52 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					},
 					shouldMaterializeFrame: () => {
 						reservation = this.reserveSharedDetectionFrame(config.deviceId);
-						return reservation.detection || reservation.motion;
+						const materialize = reservation.detection || reservation.motion;
+						this.retention?.noteFrame({
+							deviceId: config.deviceId,
+							decoded: true,
+							admitted: reservation.detection,
+							droppedPixelFree: !materialize
+						});
+						if (!materialize) this.frameLazy.noteView({
+							deviceId: config.deviceId,
+							materialized: false,
+							workerToRunnerBytes: 0
+						});
+						return materialize;
 					},
+					...useLocalFrameRef ? {
+						frameRegistry: localFrameRegistry,
+						onFrameRef: async (frame, nativeCrop) => {
+							const current = reservation;
+							reservation = null;
+							if (!current || !frame.frameRef) return false;
+							const handle = current.detection ? writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention) : void 0;
+							if (handle && nativeCrop) {
+								this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
+								this.bindFrameCutter(handle, nativeCrop);
+							}
+							this.frameLazy.noteView({
+								deviceId: config.deviceId,
+								materialized: false,
+								workerToRunnerBytes: 0
+							});
+							const admitted = current.detection && runner.enqueueReservedDetectionFrame(config.deviceId, frame, handle);
+							if (current.motion) {
+								const motion = await resolveMotionFrameView(localFrameRegistry, frame.frameRef);
+								if (motion.kind === "view") runner.enqueueMotionFrame(config.deviceId, {
+									data: Buffer.from(motion.data),
+									width: motion.width,
+									height: motion.height,
+									format: "gray",
+									timestamp: frame.timestamp,
+									capturedAt: frame.capturedAt
+								}, void 0);
+							}
+							if (admitted) nativeCrop?.markInferred();
+							return admitted;
+						}
+					} : { inlineViewSpec: SPLIT_DETECTION_VIEW },
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
 					onFirstFrame: (timing) => {
 						const phaseActiveAt = this.lastMotionAt.get(config.deviceId);
@@ -6475,7 +7239,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 						const current = reservation;
 						reservation = null;
 						if (!current) return;
-						const handle = current.detection ? retainedFrames?.write(config.deviceId, frame) ?? void 0 : void 0;
+						this.frameLazy.noteView({
+							deviceId: config.deviceId,
+							materialized: frame.data.byteLength > 0,
+							workerToRunnerBytes: frame.data.byteLength
+						});
+						const handle = current.detection ? writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention) : void 0;
 						if (handle && nativeCrop) {
 							this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 							this.bindFrameCutter(handle, nativeCrop);
@@ -6521,6 +7290,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 						fps: config.motionFps,
 						format: "gray"
 					},
+					inlineViewSpec: MOTION_FRAME_VIEW,
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "motion"),
 					onDecodedFrame: (frame) => {
 						runner.enqueueMotionFrame(config.deviceId, frame, void 0);
@@ -6694,7 +7464,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			}
 		}
 		let image;
-		if (!this.executorCoLocated()) {
+		const executorCoLocated = this.executorCoLocated();
+		if (!executorCoLocated) {
 			if (frame.format === "rgb") try {
 				const encoded = await sharp(frame.data, { raw: {
 					width: frame.width,
@@ -6706,10 +7477,25 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				log.debug("runInference: frame JPEG encode failed — falling back to raw pixels", { meta: { error: errMsg(err) } });
 			}
 		}
+		if (image !== void 0) this.frameLazy.notePoolBytes({
+			deviceId,
+			raw: 0,
+			jpeg: image.byteLength
+		});
+		else if (executorCoLocated && frame.frameRef) this.frameLazy.notePoolBytes({
+			deviceId,
+			raw: 0,
+			jpeg: 0
+		});
+		else this.frameLazy.notePoolBytes({
+			deviceId,
+			raw: frame.data.byteLength,
+			jpeg: 0
+		});
 		try {
 			return await api.pipelineExecutor.runPipeline.mutate({
 				steps: [...dispatchSteps],
-				...image !== void 0 ? { image } : { frame },
+				...image !== void 0 ? { image } : selectExecutorFrameSource(executorCoLocated, frame.frameRef, frame),
 				deviceId,
 				...camConfig?.deviceKey ? { deviceKey: camConfig.deviceKey } : {},
 				plane: "frame"
@@ -7065,31 +7851,53 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			logger: log,
 			admitWorker: this.buildLiveWorkerAdmit(deviceId, "occupancy"),
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:occupancy:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config)),
-			startPump: (source) => startSessionDecodePump({
-				fork: this.forkDecodeWorkerWithLease,
-				logger: log,
-				source,
-				opts: {
-					fps: config.detectionFps,
-					format: "rgb"
-				},
-				acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "occupancy"),
-				onEnded: () => cleanup(),
-				onDecodedFrame: (frame, nativeCrop) => {
-					if (settled) return;
-					const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
-					if (handle && nativeCrop) {
-						this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
-						this.bindFrameCutter(handle, nativeCrop);
-					}
-					if (runner.enqueueOccupancyFrame(deviceId, frame, handle)) nativeCrop?.markInferred();
-					count++;
-					if (count >= frames) {
-						clearTimeout(safetyTimer);
-						cleanup();
+			startPump: (source) => {
+				const useLocalFrameRef = this.executorCoLocated() && process.env["CAMSTACK_DISABLE_LOCAL_FRAME_REF"] !== "1";
+				return startSessionDecodePump({
+					fork: this.forkDecodeWorkerWithLease,
+					logger: log,
+					source,
+					opts: {
+						fps: config.detectionFps,
+						format: "rgb"
+					},
+					...useLocalFrameRef ? {
+						frameRegistry: localFrameRegistry,
+						onFrameRef: (frame, nativeCrop) => {
+							if (settled) return false;
+							const handle = writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention);
+							if (handle && nativeCrop) {
+								this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
+								this.bindFrameCutter(handle, nativeCrop);
+							}
+							const admitted = runner.enqueueOccupancyFrame(deviceId, frame, handle);
+							if (admitted) nativeCrop?.markInferred();
+							count++;
+							if (count >= frames) {
+								clearTimeout(safetyTimer);
+								cleanup();
+							}
+							return admitted;
+						}
+					} : { inlineViewSpec: SPLIT_DETECTION_VIEW },
+					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "occupancy"),
+					onEnded: () => cleanup(),
+					onDecodedFrame: (frame, nativeCrop) => {
+						if (settled) return;
+						const handle = writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention);
+						if (handle && nativeCrop) {
+							this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
+							this.bindFrameCutter(handle, nativeCrop);
+						}
+						if (runner.enqueueOccupancyFrame(deviceId, frame, handle)) nativeCrop?.markInferred();
+						count++;
+						if (count >= frames) {
+							clearTimeout(safetyTimer);
+							cleanup();
+						}
 					}
-				}
-			})
+				});
+			}
 		});
 		if (settled) {
 			clearTimeout(safetyTimer);