@camstack/addon-pipeline 1.2.214 → 1.2.217

package/dist/pipeline-runner/index.mjs

@@ -1,17 +1,17 @@
-import { $ as failureContributionCapability, It as errMsg, Qt as nodePin, R as customAction, U as deriveDetailCropRect, Ut as BaseAddon, V as defineCustomActions, _ as FailureCounters, _t as pickDetailCropConvention, an as boolean, bt as pipelineRunnerCapability, cn as literal, hn as EventCategory, in as array, it as loadContributionCapability, ln as number, m as DEVICE_BACKEND_TO_FORMAT, p as DEFAULT_NATIVE_LEASE_SETTINGS, pn as string, qt as createEvent, rn as _enum, sn as lazy, u as DEFAULT_DETAIL_CROP_CONVENTION, un as object, vt as pickNativeLeaseOverride } from "../dist-DttqKvsQ.mjs";
-import { i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node-NtM7__8q.mjs";
-import { i as resolveFrameViewGeometry, l as getStepDefinition, r as localFrameRegistry } from "../default-detection-model-C2vYSX3O.mjs";
-import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-BKwkLZWT.mjs";
+import { $ as failureContributionCapability, It as errMsg, Qt as nodePin, R as customAction, U as deriveDetailCropRect, Ut as BaseAddon, V as defineCustomActions, _ as FailureCounters, _t as pickDetailCropConvention, an as boolean, bt as pipelineRunnerCapability, cn as literal, hn as EventCategory, in as array, it as loadContributionCapability, ln as number, m as DEVICE_BACKEND_TO_FORMAT, p as DEFAULT_NATIVE_LEASE_SETTINGS, pn as string, qt as createEvent, rn as _enum, sn as lazy, u as DEFAULT_DETAIL_CROP_CONVENTION, un as object, vt as pickNativeLeaseOverride } from "../dist-DgeXZfwn.mjs";
+import { i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node-C9GcBrwk.mjs";
+import { i as resolveFrameViewGeometry, l as getStepDefinition, r as localFrameRegistry } from "../default-detection-model-BwNEV8Wl.mjs";
+import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-SzmaLNnP.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-DXsqwpph.mjs";
 import { a as preRollRequestOf, o as withDetectionIntent, t as DETECTION_PRE_ROLL_REQUEST_MS } from "../restream-intent-DWe2kInY.mjs";
-import { t as attributeStall } from "../event-loop-stall-monitor-DXLNBMkY.mjs";
 import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
 import * as os from "node:os";
 import { fork } from "node:child_process";
 import sharp from "sharp";
 import { fileURLToPath } from "node:url";
 import { PerformanceObserver } from "node:perf_hooks";
+import { attributeStall } from "@camstack/system/addon-utils";
 //#region src/session-decode/fork-decode-worker.ts
 /** Absolute path to the built decode-worker child entry (a vite build entry). */
 var CHILD_ENTRY_PATH = fileURLToPath(new URL("../session-decode/decode-worker-child.js", import.meta.url));
@@ -380,6 +380,84 @@ function positiveOrUndefined(value) {
 	return Number.isFinite(value) && value > 0 ? value : void 0;
 }
 //#endregion
+//#region src/session-decode/native-crop-lease-age.ts
+/**
+* THE age bound on a native crop lease (ADR-0419).
+*
+* ## The measurement
+*
+* Mac agent node (`MinidiGianluca.localdomain`), 2026-09-09, a 54-minute
+* window: 332 `native crop miss` lines, every one of them `worker-lease-gone`,
+* at a MEDIAN `handleAgeMs` of 30 099 ms — thirty seconds. The node-wide
+* {@link ../session-decode/native-crop-registry.NativeCropRegistry} sat pinned
+* at `registrySize 4096 / registryCap 4096` for the whole window. Measured
+* consequence: on track `d64ace88` (device 1443) the frontal-face frames never
+* reached the face detector, because every native fetch missed.
+*
+* ## Why an AGE bound and not a bigger cap
+*
+* The pinned cap is what the miss line shows, so raising it is the instinctive
+* move, and it is wrong twice. It keeps more full-resolution surfaces alive
+* (real RAM, on a ring that has leaked a VAAPI surface pool before), and it
+* only moves the threshold at which the same pinning returns. It also cannot
+* work: the decode worker's own tile store expires a frame's tiles at
+* `NATIVE_TILE_TTL_MS` (30 s), so a handle 30 s old has nothing behind it at
+* ANY registry size. The operator's decision, 2026-09-09: **a native lease
+* lives at most ten seconds**; a crop asked for later than that cannot be
+* useful, and the caller's detection-frame fallback — which
+* `native-frame-ring.ts` calls FREE and expected — is the right answer.
+*
+* ## Why the bound is enforced at the registry
+*
+* The registry is the only place in the system where a handle's registration
+* wall-clock exists: `FrameHandle` carries no correlatable clock (`pts` is
+* explicitly process-local and must never be compared against another), so
+* neither the hub-side requester nor the decode worker can decide this
+* question correctly. It is also the single node-wide chokepoint every native
+* path funnels through — the `getNativeCrop` cap, `getNativeCropForDetail`,
+* and `runDetailSubtree`'s rung 1 — so ONE rule covers all of them, and it
+* sits in-process, in FRONT of the round trip that the 332 misses paid for.
+* Refusing here makes the wasted work impossible rather than merely faster.
+*
+* Deliberately a constant and not an operator knob: it is a property of the
+* pipeline, not of a node's hardware (same argument as the lease knobs in
+* `@camstack/types` `pipeline/native-lease.ts`), and a per-node value would
+* make the same camera produce different crop quality depending on where the
+* balancer placed it.
+*/
+/**
+* How long a registered handle may be asked for a native crop. Inclusive: an
+* ask at exactly this age is still served, one millisecond later is refused.
+*
+* ## Ten seconds was tried on the fleet, and the fleet refused it
+*
+* The operator's number was ten seconds, chosen on the belief — stated in this
+* file's first version, and sourced from `@camstack/types`
+* `pipeline/native-lease.ts` sizing prose rather than from a measurement of
+* THIS path — that a p90 ask lands at 4.3 s and a p50 at 367 ms. Deployed
+* 2026-09-09 ~14:00, it produced, on the hub, **3 371 `no-registry-entry`
+* misses in fifteen minutes** (2 036 of them on `salone` alone) against
+* essentially ZERO in the half hour before the deploy: the registry held 46
+* entries where it had held 4 096, and the asks arriving between 10 s and 30 s
+* found nothing at all. The operator saw it as tracks with missing media.
+*
+* So the bound is the worker's own tile TTL (`NATIVE_TILE_TTL_MS`, 30 s,
+* `decode-worker-child.ts`) — the age past which there is provably nothing
+* behind the handle at ANY registry size. It still bounds the lease by AGE
+* rather than by a 4 096-entry capacity eviction, which is what D419 set out
+* to fix; it simply stops refusing asks the worker could still have answered.
+*
+* The real defect is caller-side and is not fixed here: a ~1 Hz
+* `TrackDetailDispatcher` re-asks a frozen handle for the life of a coasted
+* track, and `persistKeyFrames` / `offerGroupShot` are the only capture sites
+* that omit `staleAfterMs`. ADR-0419 named both as open; until they are fixed
+* a tighter bound cannot be told apart from a broken one.
+*/
+var NATIVE_CROP_LEASE_MAX_AGE_MS = 3e4;
+function classifyNativeCropLeaseAge(ageMs, maxAgeMs = NATIVE_CROP_LEASE_MAX_AGE_MS) {
+	return ageMs > maxAgeMs ? "expired" : "live";
+}
+//#endregion
 //#region src/session-decode/native-crop-registry.ts
 var DEFAULT_NATIVE_CROP_REGISTRY_CAP = (() => {
 	const raw = Number(process.env["CAMSTACK_NATIVE_CROP_REGISTRY_CAP"]);
@@ -393,9 +471,11 @@ function safeRelease(request) {
 }
 var NativeCropRegistry = class {
 	capacity;
+	maxAgeMs;
 	entries = /* @__PURE__ */ new Map();
-	constructor(capacity = DEFAULT_NATIVE_CROP_REGISTRY_CAP) {
+	constructor(capacity = DEFAULT_NATIVE_CROP_REGISTRY_CAP, maxAgeMs = NATIVE_CROP_LEASE_MAX_AGE_MS) {
 		this.capacity = capacity;
+		this.maxAgeMs = maxAgeMs;
 	}
 	/** Number of registered handles (tests / metrics). */
 	get size() {
@@ -410,6 +490,7 @@ var NativeCropRegistry = class {
 	* its worker-side RAM lease so a lease never outlives its registry entry.
 	*/
 	register(handle, request, deviceId) {
+		this.sweepExpired();
 		const k = this.key(handle);
 		this.entries.delete(k);
 		this.entries.set(k, {
@@ -420,27 +501,76 @@ var NativeCropRegistry = class {
 		while (this.entries.size > this.capacity) {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0) break;
-			this.releaseEntry(oldest);
+			this.releaseEntry(oldest, "capacity");
 		}
 	}
-	/** The requester for `handle`, or `null` if never registered / already evicted. */
-	get(handle) {
-		const entry = this.entries.get(this.key(handle));
-		if (entry === void 0) return null;
+	/**
+	* Resolve `handle`, applying the age bound (ADR-0419).
+	*
+	* The bound is applied HERE and not at the caller or the worker because this
+	* is the only place `registeredAt` exists — see `native-crop-lease-age.ts`.
+	* An expired handle is refused and released without the requester ever being
+	* invoked, so the doomed cross-process fetch does not happen at all.
+	*/
+	lookup(handle) {
+		const key = this.key(handle);
+		const entry = this.entries.get(key);
+		if (entry === void 0) {
+			const swept = this.sweptByAge.get(key);
+			if (swept === void 0) return { kind: "unknown" };
+			return {
+				kind: "expired",
+				deviceId: swept.deviceId,
+				ageMs: Date.now() - swept.registeredAt
+			};
+		}
+		const ageMs = Date.now() - entry.registeredAt;
+		if (classifyNativeCropLeaseAge(ageMs, this.maxAgeMs) === "expired") {
+			this.releaseEntry(key, "age");
+			return {
+				kind: "expired",
+				deviceId: entry.deviceId,
+				ageMs
+			};
+		}
 		return {
+			kind: "live",
 			request: entry.request,
 			deviceId: entry.deviceId,
-			ageMs: Date.now() - entry.registeredAt
+			ageMs
 		};
 	}
 	/**
+	* Drop every entry past the age bound, oldest first.
+	*
+	* The map is insertion-ordered and insertion order IS registration order, so
+	* the head is the oldest and the walk stops at the first live entry. Run on
+	* every `register`, which is the only path that reliably ticks on a busy
+	* node — a timer here would be a second owner of the same lifetime.
+	*
+	* It can never drop an entry a request would have been served from: anything
+	* it releases would have been refused by {@link lookup} in the same instant.
+	* What it buys is that the worker's lease is released when it stops being
+	* useful (10 s) instead of when 4 095 later handles have pushed it out of a
+	* capacity eviction (~30 s on this cluster) — the reason the registry sat
+	* pinned at `4096/4096`.
+	*/
+	sweepExpired() {
+		const now = Date.now();
+		for (const [key, entry] of this.entries) {
+			if (classifyNativeCropLeaseAge(now - entry.registeredAt, this.maxAgeMs) === "live") return;
+			this.releaseEntry(key, "age");
+		}
+	}
+	/**
 	* The deviceId a handle was registered under, even AFTER its entry was
 	* evicted — kept in a small parallel ring so a `no-registry-entry` miss can
 	* still be attributed to a camera (a miss line without `deviceId` cannot
 	* answer "why is 617 worse than 615?").
 	*/
 	deviceIdFor(handle) {
-		return this.evictedDeviceIds.get(this.key(handle)) ?? this.entries.get(this.key(handle))?.deviceId ?? null;
+		const key = this.key(handle);
+		return this.evictedDeviceIds.get(key) ?? this.sweptByAge.get(key)?.deviceId ?? this.entries.get(key)?.deviceId ?? null;
 	}
 	/**
 	* Release the worker-side RAM native lease for `handle` and drop its entry —
@@ -455,13 +585,24 @@ var NativeCropRegistry = class {
 		for (const entry of this.entries.values()) safeRelease(entry.request);
 		this.entries.clear();
 		this.evictedDeviceIds.clear();
+		this.sweptByAge.clear();
 	}
-	/** Release + drop one entry by its map key, remembering its camera. */
-	releaseEntry(key) {
+	/**
+	* Release + drop one entry by its map key, remembering WHY it left.
+	*
+	* `age` — past the lease bound (a `lookup` refusal or a `register` sweep):
+	* remembered with its registration clock, so a later ask for the same
+	* handle is still answered `expired` with a real age. `capacity` — the cap
+	* bound and pushed it out; `released` — the caller was done with it. Those
+	* two stay `unknown` on a later ask: neither is a late ask, and folding
+	* them into the refusal count would make the bound look tighter than it is.
+	*/
+	releaseEntry(key, cause = "released") {
 		const entry = this.entries.get(key);
 		if (!entry) return;
 		this.entries.delete(key);
-		this.rememberEvicted(key, entry.deviceId);
+		if (cause === "age") this.rememberSweptByAge(key, entry);
+		else this.rememberEvicted(key, entry.deviceId);
 		safeRelease(entry.request);
 	}
 	/** Bounded memory of evicted handles → deviceId, for miss attribution. */
@@ -474,6 +615,24 @@ var NativeCropRegistry = class {
 			this.evictedDeviceIds.delete(oldest);
 		}
 	}
+	/**
+	* Bounded memory of handles the AGE bound dropped, with the clock the
+	* refusal is measured from. Same capacity as the live map: at the busiest
+	* node's rate that is one more lease window of memory, after which a
+	* refusal degrades to `unknown` — an ask that late is not a bound question.
+	*/
+	sweptByAge = /* @__PURE__ */ new Map();
+	rememberSweptByAge(key, entry) {
+		this.sweptByAge.set(key, {
+			deviceId: entry.deviceId,
+			registeredAt: entry.registeredAt
+		});
+		while (this.sweptByAge.size > this.capacity) {
+			const oldest = this.sweptByAge.keys().next().value;
+			if (oldest === void 0) break;
+			this.sweptByAge.delete(oldest);
+		}
+	}
 };
 //#endregion
 //#region src/session-decode/node-decode-budget.ts
@@ -568,6 +727,160 @@ function createRetainedContentFallback(registry, ref) {
 		}
 	} };
 }
+//#endregion
+//#region src/session-decode/parked-frame-store.ts
+/** Per-camera parcel bound. 24 live tracks × two kinds on one camera is a
+*  crowd scene; past that the camera's oldest parcel leaves first. Read ONCE
+*  from `CAMSTACK_PARKED_FRAMES_PER_DEVICE`. */
+var PARKED_FRAMES_PER_DEVICE_MAX = (() => {
+	const raw = Number(process.env["CAMSTACK_PARKED_FRAMES_PER_DEVICE"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 48;
+})();
+/** {@link PARKED_FRAME_BUDGET_MB} in bytes. */
+var PARKED_FRAME_BUDGET_BYTES = (() => {
+	const raw = Number(process.env["CAMSTACK_PARKED_FRAME_MB"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 64;
+})() * 1024 * 1024;
+function keyOf$1(deviceId, trackId, kind) {
+	return `${deviceId}|${trackId}|${kind}`;
+}
+var ParkedFrameStore = class {
+	budgetBytes;
+	perDeviceMax;
+	maxAgeMs;
+	now;
+	onEvict;
+	/** Insertion-ordered → the head is the globally oldest park. A replace
+	*  re-inserts, so order IS park order. */
+	entries = /* @__PURE__ */ new Map();
+	/** Per-device keys in park order, mirroring {@link entries} for the bound. */
+	perDeviceKeys = /* @__PURE__ */ new Map();
+	totalBytes = 0;
+	constructor(options = {}) {
+		this.budgetBytes = options.budgetBytes ?? PARKED_FRAME_BUDGET_BYTES;
+		this.perDeviceMax = options.perDeviceMax ?? PARKED_FRAMES_PER_DEVICE_MAX;
+		this.maxAgeMs = options.maxAgeMs ?? 6e5;
+		this.now = options.now ?? Date.now;
+		this.onEvict = options.onEvict;
+	}
+	/** Number of parcels held (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** Bytes of JPEG held (tests / metrics). */
+	get bytes() {
+		return this.totalBytes;
+	}
+	/**
+	* Park one parcel. Replaces an existing parcel for the key unless the new
+	* one shows an OLDER frame instant (a racing loser). Sweeps the age ceiling,
+	* then enforces the per-device bound and the node budget — evicting the
+	* oldest of the offending scope, never refusing the new parcel.
+	*/
+	park(deviceId, trackId, kind, frame) {
+		const nowMs = this.now();
+		this.sweepExpired(nowMs);
+		const key = keyOf$1(deviceId, trackId, kind);
+		const existing = this.entries.get(key);
+		if (existing !== void 0 && frame.timestamp < existing.frame.timestamp) return "older-ignored";
+		if (existing !== void 0) this.remove(key);
+		this.entries.set(key, {
+			deviceId,
+			trackId,
+			kind,
+			frame,
+			parkedAt: nowMs
+		});
+		const deviceKeys = this.perDeviceKeys.get(deviceId);
+		if (deviceKeys) deviceKeys.push(key);
+		else this.perDeviceKeys.set(deviceId, [key]);
+		this.totalBytes += frame.jpeg.byteLength;
+		this.enforceDeviceBound(deviceId);
+		this.enforceBudget();
+		return existing === void 0 ? "stored" : "replaced";
+	}
+	/** The parcel for a key, or `null` — never anything else, never by handle. */
+	get(deviceId, trackId, kind) {
+		const entry = this.entries.get(keyOf$1(deviceId, trackId, kind));
+		if (entry === void 0) return null;
+		if (this.now() - entry.parkedAt > this.maxAgeMs) {
+			this.evict(keyOf$1(deviceId, trackId, kind), "age");
+			return null;
+		}
+		return {
+			...entry.frame,
+			parkedAt: entry.parkedAt
+		};
+	}
+	/** Drop every parcel of a track (the hub closed it). Returns how many left. */
+	release(deviceId, trackId) {
+		const keys = (this.perDeviceKeys.get(deviceId) ?? []).filter((key) => this.entries.get(key)?.trackId === trackId);
+		for (const key of keys) this.remove(key);
+		return keys.length;
+	}
+	/** What one camera is costing right now. */
+	statsByDevice(deviceId) {
+		const keys = this.perDeviceKeys.get(deviceId) ?? [];
+		let bytes = 0;
+		for (const key of keys) bytes += this.entries.get(key)?.frame.jpeg.byteLength ?? 0;
+		return {
+			parcels: keys.length,
+			bytes
+		};
+	}
+	/** Drop everything (addon shutdown). */
+	clear() {
+		this.entries.clear();
+		this.perDeviceKeys.clear();
+		this.totalBytes = 0;
+	}
+	/** Age sweep from the head — insertion order is park order, so it stops at
+	*  the first parcel still inside the ceiling. */
+	sweepExpired(nowMs) {
+		for (const [key, entry] of this.entries) {
+			if (nowMs - entry.parkedAt <= this.maxAgeMs) return;
+			this.evict(key, "age");
+		}
+	}
+	enforceDeviceBound(deviceId) {
+		const deviceKeys = this.perDeviceKeys.get(deviceId);
+		while (deviceKeys !== void 0 && deviceKeys.length > this.perDeviceMax) {
+			const oldest = deviceKeys[0];
+			if (oldest === void 0) break;
+			this.evict(oldest, "device-bound");
+		}
+	}
+	/** Globally oldest first, whatever its device; always keeps ≥ 1. */
+	enforceBudget() {
+		for (const key of [...this.entries.keys()]) {
+			if (this.totalBytes <= this.budgetBytes || this.entries.size <= 1) return;
+			this.evict(key, "node-budget");
+		}
+	}
+	evict(key, cause) {
+		const entry = this.entries.get(key);
+		if (entry === void 0) return;
+		this.remove(key);
+		this.onEvict?.({
+			deviceId: entry.deviceId,
+			trackId: entry.trackId,
+			kind: entry.kind,
+			cause
+		});
+	}
+	remove(key) {
+		const entry = this.entries.get(key);
+		if (entry === void 0) return;
+		this.entries.delete(key);
+		this.totalBytes -= entry.frame.jpeg.byteLength;
+		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);
+		}
+	}
+};
 /** {@link RETAINED_FRAME_BUDGET_MB} in bytes. */
 var RETAINED_FRAME_BUDGET_BYTES = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_RETAIN_MB"]);
@@ -6031,6 +6344,90 @@ function isUsable(bbox) {
 	return bbox.width > 0 && bbox.height > 0;
 }
 //#endregion
+//#region src/pipeline-runner/track-frame-park.ts
+/** Park one frame for one track. Never throws; a refusal is an answer. */
+async function parkTrackFrame(deps, input) {
+	const { deviceId, trackId, kind } = input;
+	const handleKey = `${input.handle.shmId}#${input.handle.slot}#${input.handle.seq}`;
+	const resolved = await deps.resolvePixels({
+		handle: input.handle,
+		bbox: input.bbox,
+		...input.maxWidth !== void 0 ? { maxWidth: input.maxWidth } : {}
+	});
+	if (resolved.pixels === null || resolved.tier !== "native") {
+		const missReason = resolved.missReason ?? "worker-lease-gone";
+		const detail = resolved.workerReason !== void 0 ? `${missReason}: ${resolved.workerReason}` : missReason;
+		deps.logger.warn("track frame park refused — the handle no longer resolves at park time", {
+			tags: { deviceId },
+			meta: {
+				trackId,
+				kind,
+				reason: "handle-gone",
+				missReason,
+				handleAgeMs: resolved.handleAgeMs,
+				servedTier: resolved.tier,
+				handle: handleKey,
+				...resolved.workerReason !== void 0 ? { workerReason: resolved.workerReason } : {}
+			}
+		});
+		return {
+			parked: false,
+			nodeId: deps.nodeId,
+			reason: "handle-gone",
+			handleAgeMs: resolved.handleAgeMs,
+			detail
+		};
+	}
+	const jpeg = await deps.encodeJpeg(resolved.pixels);
+	if (jpeg === null) {
+		deps.logger.warn("track frame park refused — JPEG encode failed", {
+			tags: { deviceId },
+			meta: {
+				trackId,
+				kind,
+				reason: "encode-failed",
+				handleAgeMs: resolved.handleAgeMs,
+				handle: handleKey,
+				width: resolved.pixels.width,
+				height: resolved.pixels.height
+			}
+		});
+		return {
+			parked: false,
+			nodeId: deps.nodeId,
+			reason: "encode-failed",
+			handleAgeMs: resolved.handleAgeMs
+		};
+	}
+	const verdict = deps.store.park(deviceId, trackId, kind, {
+		jpeg,
+		width: resolved.pixels.width,
+		height: resolved.pixels.height,
+		timestamp: input.timestamp
+	});
+	deps.logger.debug("track frame parked", {
+		tags: { deviceId },
+		meta: {
+			trackId,
+			kind,
+			verdict,
+			bytes: jpeg.byteLength,
+			width: resolved.pixels.width,
+			height: resolved.pixels.height,
+			handleAgeMs: resolved.handleAgeMs,
+			source: resolved.pixels.source ?? "lease"
+		}
+	});
+	return {
+		parked: true,
+		nodeId: deps.nodeId,
+		width: resolved.pixels.width,
+		height: resolved.pixels.height,
+		bytes: jpeg.byteLength,
+		replaced: verdict === "replaced"
+	};
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 /**
 * addon-pipeline-runner — per-node detection scheduler.
@@ -6100,6 +6497,8 @@ var PACKAGE_ZONE_UNION_TTL_MS = 6e4;
 var MAX_BOUND_FRAME_CUTTERS = 256;
 /** How often a camera reports its undispatched cuts. */
 var TILE_CUT_DROP_LOG_INTERVAL_MS = 6e4;
+/** How often a camera reports parcels that left without a release (D422). */
+var PARKED_EVICTION_LOG_INTERVAL_MS = 6e4;
 /**
 * How often a camera reports what carrying its birth evidence COST (D379).
 *
@@ -6129,7 +6528,6 @@ var DEFAULT_CONFIG = {
 * this window REUSES the warm worker instead of re-forking it — killing the
 * spawn/teardown churn (and its cold-start latency spike) that on-motion
 * cameras produced when every gate open/close forked and killed a worker.
-* Mirrors Scrypted's decode-fork ~15s idle-timeout.
 */
 /** JPEG quality for the runner→executor detection-frame hop. q82 keeps
 *  detector-relevant detail (source is h264 anyway) at ~10-15× less payload
@@ -6487,6 +6885,17 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* Initialised in {@link onInitialize} once `nodeId` is known.
 	*/
 	retainedFrames = null;
+	/**
+	* Per-track PARCELS (D422): one JPEG per `(deviceId, trackId, kind)`, cut
+	* from the native surface at the instant the hub judged the frame relevant,
+	* retrieved later by that key — never by handle, never by age. Bounded per
+	* device and per node in `parked-frame-store.ts`, where the numbers are
+	* stated. Initialised in {@link onInitialize} beside the retained store.
+	*/
+	parkedFrames = null;
+	/** Per-camera tally of parcels that left WITHOUT a release, by cause. */
+	parkedEvictions = /* @__PURE__ */ new Map();
+	parkedEvictionLoggedAt = /* @__PURE__ */ new Map();
 	frameLazy = new FrameLazyTelemetry();
 	retention = null;
 	attached = /* @__PURE__ */ new Map();
@@ -6717,6 +7126,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			nodeId: this.nodeId,
 			continuousRetain: isContinuousRetainEnabled()
 		});
+		this.parkedFrames = new ParkedFrameStore({ onEvict: (eviction) => this.noteParkedEviction(eviction.deviceId, eviction.cause) });
 		this.runner = new PipelineRunner({
 			maxQueueDepth: this.config.maxQueueDepth,
 			maxConcurrentInferences: this.config.maxConcurrentInferences,
@@ -6868,6 +7278,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.nativeCropRegistry.clear();
 		this.retainedFrames?.clear();
 		this.retainedFrames = null;
+		this.parkedFrames?.clear();
+		this.parkedFrames = null;
 		this.retention = null;
 	}
 	async cacheBenchFrame(input) {
@@ -7662,6 +8074,96 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		}, resolved.tier, input.encodeJpeg);
 	}
 	/**
+	* PARK a frame for a track (D422) — the hub judged it relevant, and this node
+	* still holds its pixels. Same native-lease resolve `getNativeCrop` uses,
+	* same single encoder; the parcel lives in {@link parkedFrames} under
+	* `(deviceId, trackId, kind)`. A refusal is an answer and a `deviceId`-tagged
+	* log line, never a retry.
+	*/
+	async parkTrackFrame(input) {
+		const store = this.parkedFrames;
+		if (store === null) return {
+			parked: false,
+			nodeId: this.nodeId,
+			reason: "handle-gone",
+			handleAgeMs: null,
+			detail: "runner not initialised"
+		};
+		return parkTrackFrame({
+			nodeId: this.nodeId,
+			store,
+			resolvePixels: (request) => this.resolveNativeCropPixels(request),
+			encodeJpeg: async (pixels) => {
+				const encoded = await this.encodeNativeCropResult(pixels, "native", true);
+				return encoded?.jpeg !== void 0 ? Buffer.from(encoded.jpeg, "base64") : null;
+			},
+			logger: this.ctx.logger
+		}, input);
+	}
+	/** A parcel by `(deviceId, trackId, kind)`; `null` = nothing parked here. */
+	async getParkedTrackFrame(input) {
+		const parcel = this.parkedFrames?.get(input.deviceId, input.trackId, input.kind) ?? null;
+		if (parcel === null) {
+			this.ctxIfReady?.logger.debug("parked frame miss — nothing under this key", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					trackId: input.trackId,
+					kind: input.kind,
+					...this.parkedFrames?.statsByDevice(input.deviceId) ?? {
+						parcels: 0,
+						bytes: 0
+					}
+				}
+			});
+			return null;
+		}
+		return {
+			jpeg: parcel.jpeg.toString("base64"),
+			width: parcel.width,
+			height: parcel.height,
+			timestamp: parcel.timestamp,
+			parkedAt: parcel.parkedAt
+		};
+	}
+	/** The hub closed a track: drop its parcels. Idempotent. */
+	async releaseParkedTrackFrames(input) {
+		return { released: this.parkedFrames?.release(input.deviceId, input.trackId) ?? 0 };
+	}
+	/**
+	* A parcel left without a release. Counted per camera by cause and reported
+	* one line per camera per minute: a camera whose parcels keep leaving under
+	* the device bound is a crowd, under the node budget is a neighbour's
+	* traffic, and under the age ceiling is a hub that stopped releasing.
+	*/
+	noteParkedEviction(deviceId, cause) {
+		const tally = this.parkedEvictions.get(deviceId) ?? {
+			deviceBound: 0,
+			nodeBudget: 0,
+			age: 0
+		};
+		if (cause === "device-bound") tally.deviceBound += 1;
+		else if (cause === "node-budget") tally.nodeBudget += 1;
+		else tally.age += 1;
+		this.parkedEvictions.set(deviceId, tally);
+		const now = Date.now();
+		if (now - (this.parkedEvictionLoggedAt.get(deviceId) ?? 0) < PARKED_EVICTION_LOG_INTERVAL_MS) return;
+		this.parkedEvictionLoggedAt.set(deviceId, now);
+		this.ctxIfReady?.logger.info("parked frames evicted without a release", {
+			tags: { deviceId },
+			meta: {
+				...tally,
+				lastCause: cause,
+				parcelsHeld: this.parkedFrames?.size ?? 0,
+				bytesHeld: this.parkedFrames?.bytes ?? 0
+			}
+		});
+		this.parkedEvictions.set(deviceId, {
+			deviceBound: 0,
+			nodeBudget: 0,
+			age: 0
+		});
+	}
+	/**
 	* Turn a finished frame into subject TILES and end its hold — the runner half
 	* of R2 (`docs/design/2026-08-13-native-lease-two-tier-redesign.md`).
 	*
@@ -7931,11 +8433,14 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		let nativeResult = null;
 		let missReason = null;
 		let handleAgeMs = null;
+		/** The camera the lookup attributed the handle to, live or expired. */
+		let deviceIdForMiss = null;
 		let workerReason;
 		if (!isUnboundedFullFrame) {
-			const found = this.nativeCropRegistry.get(input.handle);
-			handleAgeMs = found?.ageMs ?? null;
-			if (found) {
+			const found = this.nativeCropRegistry.lookup(input.handle);
+			handleAgeMs = found.kind === "unknown" ? null : found.ageMs;
+			deviceIdForMiss = found.kind === "unknown" ? null : found.deviceId;
+			if (found.kind === "live") {
 				const attempt = await found.request(input.bbox, input.maxWidth);
 				if (attempt.kind === "crop") nativeResult = {
 					bytes: attempt.crop.bytes,
@@ -7947,11 +8452,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					missReason = "worker-lease-gone";
 					workerReason = attempt.workerReason;
 				}
-			} else missReason = "no-registry-entry";
+			} else if (found.kind === "expired") missReason = "handle-expired";
+			else missReason = "no-registry-entry";
 			if (missReason !== null) {
 				const tierOnMiss = resolveNativeCropSource(isFullFrame, false);
 				const fields = {
-					tags: { deviceId: found?.deviceId ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
+					tags: { deviceId: deviceIdForMiss ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
 					meta: {
 						reason: missReason,
 						servedTier: tierOnMiss,
@@ -7963,8 +8469,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 						...workerReason !== void 0 ? { workerReason } : {}
 					}
 				};
-				if (tierOnMiss === "miss") this.ctx.logger.warn("native crop miss", fields);
-				else this.ctx.logger.debug("native crop miss", fields);
+				const message = missReason === "handle-expired" ? "native crop refused — the handle is past the lease age bound" : "native crop miss";
+				const withBound = missReason === "handle-expired" ? {
+					...fields,
+					meta: {
+						...fields.meta,
+						leaseMaxAgeMs: NATIVE_CROP_LEASE_MAX_AGE_MS
+					}
+				} : fields;
+				if (tierOnMiss === "miss") this.ctx.logger.warn(message, withBound);
+				else this.ctx.logger.debug(message, withBound);
 			}
 		}
 		return {
@@ -9880,6 +10394,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			frame: result,
 			nodeId: this.nodeId,
 			frameHandle: handle,
+			emittedAt: Date.now(),
 			...typeof capturedAt === "number" && capturedAt > 0 ? { capturedAt } : {},
 			...detailSteps && detailSteps.length > 0 ? { detailSteps } : {}
 		};