@camstack/addon-pipeline 1.2.42 → 1.2.44

package/dist/pipeline-runner/index.mjs

@@ -1,6 +1,6 @@
-import { $ as nodePin, C as defineCustomActions, F as pipelineRunnerCapability, J as createEvent, N as pickDetailCropConvention, U as errMsg, W as BaseAddon, at as array, c as DEVICE_BACKEND_TO_FORMAT, ct as lazy, dt as object, ht as EventCategory, it as _enum, lt as literal, ot as boolean, pt as string, s as DEFAULT_DETAIL_CROP_CONVENTION, ut as number, w as deriveDetailCropRect, x as customAction } from "../dist-COK_1Ot8.mjs";
-import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-CWOJtTNc.mjs";
-import { t as isWorkerReply } from "../worker-protocol-D7RzZIla.mjs";
+import { Ct as literal, Dt as string, G as pickDetailCropConvention, J as pipelineRunnerCapability, K as pickNativeLeaseOverride, M as deriveDetailCropRect, St as lazy, Tt as object, bt as boolean, c as DEFAULT_DETAIL_CROP_CONVENTION, ct as createEvent, it as BaseAddon, j as defineCustomActions, k as customAction, kt as EventCategory, pt as nodePin, rt as errMsg, u as DEVICE_BACKEND_TO_FORMAT, vt as _enum, wt as number, yt as array } from "../dist-DOu93i_g.mjs";
+import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-CShgQE6l.mjs";
+import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-BOXlUhWO.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-B-mb8uWx.mjs";
 import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
@@ -76,9 +76,28 @@ function wrapChild(child) {
 * Fork one decode-worker child. `source` is part of the coordinator's fork
 * signature (it forwards the same source in the subsequent `start` message);
 * the child entry itself is source-independent, so it is not consumed here.
+*
+* `leaseOverride` carries the operator's cluster-wide native-lease settings
+* (`pipeline-orchestrator` globals, read by `native-lease-settings-source.ts`)
+* into the child as environment variables — the child constructs its lease
+* store and demand gate at module load, before the first `start` message, so
+* the values have to be present at spawn. Only the knobs the operator actually
+* SET are emitted, which is what keeps the pre-settings env override
+* (`CAMSTACK_SESSION_NATIVE_LEASE_*`) working for the untouched ones; see
+* `native-lease-config.ts` for the full precedence.
+*
+* The inherited environment is SPREAD, never replaced: this child resolves
+* node-av through `CAMSTACK_FRAMEWORK_DIR` / `CAMSTACK_BUNDLED_ADDONS_DIR` on
+* agents, so a replaced env would silently break decoding off the hub.
 */
-function forkDecodeWorker(_source) {
-	return wrapChild(fork(CHILD_ENTRY_PATH, [], { serialization: "advanced" }));
+function forkDecodeWorker(_source, leaseOverride = {}) {
+	return wrapChild(fork(CHILD_ENTRY_PATH, [], {
+		serialization: "advanced",
+		env: {
+			...process.env,
+			...nativeLeaseSettingEnv(leaseOverride)
+		}
+	}));
 }
 //#endregion
 //#region src/session-decode/guarded-session-decode.ts
@@ -298,7 +317,7 @@ var RETAINED_FRAME_BUDGET_BYTES = (() => {
 * missing thumbnails/firstFrames concentrated on exactly those cameras).
 * 16 frames ≈ 0.64 s @25 fps (1.6 s @10 fps). Only ACTIVE cameras hold frames,
 * so the worst-case protected footprint stays well inside the byte budget for
-* realistic concurrency (4 active cams ≈ 44 MB of 96); the hard ceiling always
+* realistic concurrency (4 active cams ≈ 44 MB of 160); the hard ceiling always
 * overrides the floor regardless. Read ONCE from `CAMSTACK_SESSION_RETAIN_FLOOR`;
 * `0` disables the floor (pure global FIFO — the pre-2026-07-19 behaviour).
 */
@@ -650,6 +669,19 @@ var SessionDecodeSession = class {
 			frameId
 		});
 	}
+	/**
+	* Tell the worker `frameId` reached inference, so its native lease is worth
+	* keeping. Fire and forget, no reply. Ordering matters and is free here: the
+	* caller runs in the same turn that consumed the frame, and the pull that
+	* decides this frame's admission is issued after that turn returns.
+	*/
+	markInferred(frameId) {
+		if (this.exited) return;
+		this.trySend({
+			kind: "markInferred",
+			frameId
+		});
+	}
 	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
 	teardown() {
 		this.stopRequested = true;
@@ -870,6 +902,7 @@ function buildFrameImage(session, reply) {
 		},
 		nativeCrop: (bbox, maxWidth) => session.requestNativeCrop(reply.frameId, bbox, maxWidth),
 		releaseNativeLease: () => session.releaseLease(reply.frameId),
+		markInferred: () => session.markInferred(reply.frameId),
 		close: () => {
 			closed = true;
 		}
@@ -999,7 +1032,10 @@ function startSessionDecodePump(deps) {
 					const decoded = await toDecodedFrame(frame, format);
 					const image = frame.image;
 					const cropFn = image.nativeCrop;
-					const nativeCrop = cropFn ? Object.assign((bbox, maxWidth) => cropFn(bbox, maxWidth), { release: () => image.releaseNativeLease?.() }) : void 0;
+					const nativeCrop = cropFn ? Object.assign((bbox, maxWidth) => cropFn(bbox, maxWidth), {
+						release: () => image.releaseNativeLease?.(),
+						markInferred: () => image.markInferred?.()
+					}) : void 0;
 					deps.onDecodedFrame(decoded, nativeCrop);
 				} catch (err) {
 					deps.logger.debug("session-decode pump: skipped a frame (decode/consume error)", {
@@ -1780,7 +1816,121 @@ var CropConventionSource = class {
 	}
 };
 //#endregion
+//#region src/pipeline-runner/native-lease-settings-source.ts
+/**
+* Where the runner gets the cluster-wide native-frame LEASE knobs.
+*
+* ## Why a settings read and not the attach config
+*
+* Identical reasoning to `crop-convention-source.ts`, and worth restating
+* because the temptation is the same: `RunnerCameraConfig` is the obvious
+* orchestrator→runner channel and it is the wrong one. Eleven call sites build
+* one; a cluster-wide constant threaded through eleven builders eventually
+* reaches ten of them, and the cameras attached by the forgotten builder just
+* quietly run a different lease window. Instead the runner reads the OWNER
+* addon's global settings directly, hub-routed by `AddonCallGateway`, so an
+* agent runner transparently reads the hub-central store with no placement
+* branching.
+*
+* ## Deliberately NOT node-scoped
+*
+* The read passes no `nodeId`. With one, `addon-settings` would project that
+* node's scoped value and two nodes could hold different lease windows for the
+* same camera — so whether a stored crop is native pixels or the ≤640 fallback
+* would depend on where the balancer happened to place it, which is invisible
+* from the stored media.
+*
+* ## What it hands out
+*
+* A {@link NativeLeaseSettingsOverride} — only the knobs the operator SET. The
+* decode worker resolves the rest (env var, then the shipped default); see
+* `session-decode/native-lease-config.ts` for the precedence. Handing out a
+* fully-resolved triple here would erase the "operator set nothing" state and
+* with it the env-var escape hatch.
+*/
+/**
+* The addon whose GLOBAL settings own the knobs. `pipeline-orchestrator` is
+* hub-resident and neutral — the same owner as the detail-crop convention and
+* the per-node decoder-backend selector.
+*/
+var NATIVE_LEASE_OWNER_ADDON_ID = "pipeline-orchestrator";
+/**
+* Whether two overrides name the same knobs with the same values.
+*
+* **Every knob has to appear here.** This is the equality that decides whether
+* a re-read is ADOPTED at all: a knob missing from the comparison is read from
+* the hub, judged identical, and discarded, so the operator's change never
+* reaches a decode worker and nothing anywhere says so. `admission` shipped
+* missing from this list and did exactly that — the setting was stored, the
+* hub served it, the runner fetched it, and every worker kept spawning with the
+* old value.
+*/
+function sameOverride(a, b) {
+	return a.ttlMs === b.ttlMs && a.budgetMb === b.budgetMb && a.activityMs === b.activityMs && a.admission === b.admission;
+}
+/**
+* TTL-cached read of the cluster native-lease knobs.
+*
+* {@link current} is synchronous because the fork that consumes it is;
+* {@link refresh} is what talks to the hub, and the runner awaits it on the
+* path that precedes a decode-worker spawn.
+*/
+var NativeLeaseSettingsSource = class {
+	override = {};
+	lastReadAtMs = Number.NEGATIVE_INFINITY;
+	inFlight = null;
+	logger;
+	now;
+	ttlMs;
+	constructor(options) {
+		this.logger = options.logger;
+		this.now = options.now ?? (() => Date.now());
+		this.ttlMs = options.ttlMs ?? 3e4;
+	}
+	/** The operator's overrides as last read — `{}` until a read lands. */
+	current() {
+		return this.override;
+	}
+	/**
+	* Re-read if the cached value has expired. Concurrent callers share one
+	* in-flight read; a failure keeps the LAST KNOWN value rather than reverting
+	* to `{}`, because a revert would silently hand the next-spawned workers a
+	* different RAM profile than the ones already running.
+	*/
+	async refresh(api) {
+		if (api === void 0) return this.override;
+		if (this.now() - this.lastReadAtMs < this.ttlMs) return this.override;
+		this.inFlight ??= this.read(api).finally(() => {
+			this.inFlight = null;
+		});
+		await this.inFlight;
+		return this.override;
+	}
+	async read(api) {
+		try {
+			const next = pickNativeLeaseOverride(await api.addonSettings.getGlobalSettings.query({ addonId: NATIVE_LEASE_OWNER_ADDON_ID }));
+			this.lastReadAtMs = this.now();
+			if (sameOverride(next, this.override)) return;
+			this.logger.info("native lease settings changed — applies to NEW decode sessions", { meta: {
+				from: { ...this.override },
+				to: { ...next }
+			} });
+			this.override = next;
+		} catch (err) {
+			this.logger.warn("native lease settings read failed — keeping the last known value", { meta: {
+				owner: NATIVE_LEASE_OWNER_ADDON_ID,
+				inUse: { ...this.override },
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
 //#region src/pipeline-runner/detail-subtree.ts
+/** Did the native-lease fetch report a miss (rather than return pixels)? */
+function isNativeCropMiss(fetch) {
+	return "miss" in fetch;
+}
 /** Normalize a frame-space pixel rect to `[0,1]` by the given frame dims. */
 function normalizeRect(rect, frameWidth, frameHeight) {
 	return {
@@ -1866,6 +2016,15 @@ function encodeEmbeddingBase64(embedding) {
 function pickLabel(detection) {
 	return detection.labels.find((l) => !l.label.startsWith("embedding:"))?.label;
 }
+/**
+* Turn one executor detection into the cap's `DetailResult`, reprojecting its
+* crop-space bbox back onto the frame the crop came from.
+*
+* Exported because the STATELESS step path (`stateless-step.ts`) produces the
+* same shape from the same executor output and must not grow its own mapping —
+* a second reprojection is a second set of coordinates, and the two would agree
+* right up until one of them changed.
+*/
 function toDetailResult(detection, stepId, crop) {
 	const label = pickLabel(detection);
 	return {
@@ -1885,6 +2044,13 @@ function toDetailResult(detection, stepId, crop) {
 * traffic: before it existed the only way to feed stored pixels in was a
 * pre-cut tile, so the caller decided the rectangle and every caller decided
 * differently.
+*
+* Exported so the STATELESS step path can reach `deriveDetailCropRect` through
+* this function rather than importing it — `scripts/check-clip-crop-single-owner.ts`
+* permits exactly one importer, and that is the enforcement of
+* [D52](../../../../docs/decisions/adr-0052.md). A second caller of the
+* derivation is a second cutter no matter how similar its arithmetic looks
+* today.
 */
 async function cutFromFullFrame(frameJpegBase64, bbox, convention) {
 	const image = (await getSharp())(Buffer.from(frameJpegBase64, "base64"));
@@ -1892,7 +2058,7 @@ async function cutFromFullFrame(frameJpegBase64, bbox, convention) {
 	const frameWidth = meta.width ?? 0;
 	const frameHeight = meta.height ?? 0;
 	if (frameWidth <= 0 || frameHeight <= 0) return null;
-	const rect = deriveDetailCropRect(bbox, frameWidth, frameHeight, convention);
+	const rect = deriveDetailCropRect(bbox.kind === "frame-pixels" ? bbox.rect : denormalizeRect(bbox.rect, frameWidth, frameHeight), frameWidth, frameHeight, convention);
 	const left = Math.max(0, Math.min(Math.round(rect.x), frameWidth - 1));
 	const top = Math.max(0, Math.min(Math.round(rect.y), frameHeight - 1));
 	const width = Math.max(1, Math.min(Math.round(rect.w), frameWidth - left));
@@ -1916,37 +2082,82 @@ async function cutFromFullFrame(frameJpegBase64, bbox, convention) {
 	};
 }
 async function resolveCrop(deps, input, convention) {
+	let nativeMiss = null;
 	if (input.frameHandle) {
 		const normalized = normalizeRect(deriveDetailCropRect(input.parent.bbox, input.frameHandle.width, input.frameHandle.height, convention), input.frameHandle.width, input.frameHandle.height);
 		const native = await deps.getNativeCrop(input.deviceId, input.frameHandle, normalized);
-		if (native) return {
-			...native,
-			source: "native"
-		};
+		if (native !== null) {
+			if (!isNativeCropMiss(native)) return {
+				crop: {
+					...native,
+					source: "native"
+				},
+				nativeMiss
+			};
+			nativeMiss = native;
+		}
 	}
-	if (input.frameJpeg) return cutFromFullFrame(input.frameJpeg, input.parent.bbox, convention);
+	if (input.frameJpeg) return {
+		crop: await cutFromFullFrame(input.frameJpeg, {
+			kind: "frame-pixels",
+			rect: input.parent.bbox
+		}, convention),
+		nativeMiss
+	};
 	if (input.cropJpeg) {
 		const jpeg = Buffer.from(input.cropJpeg, "base64");
 		const meta = await (await getSharp())(jpeg).metadata();
 		const width = meta.width ?? 0;
 		const height = meta.height ?? 0;
-		if (width <= 0 || height <= 0) return null;
+		if (width <= 0 || height <= 0) return {
+			crop: null,
+			nativeMiss
+		};
 		return {
-			jpeg,
-			width,
-			height,
-			frameSpace: input.parent.bbox,
-			source: "fallback"
+			crop: {
+				jpeg,
+				width,
+				height,
+				frameSpace: input.parent.bbox,
+				source: "fallback"
+			},
+			nativeMiss
 		};
 	}
-	return null;
+	return {
+		crop: null,
+		nativeMiss
+	};
 }
 /**
-* Run the DETAIL subtree for a single tracked detection: resolve a crop
-* (native lease → `cropJpeg` fallback), run each matched top-level child
-* step's chain against it, and map every result bbox back to frame space.
-* Returns `null` when the camera isn't attached, no configured child
-* matches `input.parent.className`, or no crop source resolves.
+* Run the DETAIL subtree for a single tracked detection: resolve a crop, run
+* each matched top-level child step's chain against it, and map every result
+* bbox back to frame space. Returns `null` when the camera isn't attached, no
+* configured child matches `input.parent.className`, or no crop source
+* resolves.
+*
+* ## The three pixel sources, in the order they are tried
+*
+* The distinction between them is not the pixels — it is WHICH SIDE derives the
+* rectangle, and conflating that is how one vector index came to hold two
+* feature spaces ([D52](../../../../docs/decisions/adr-0052.md)):
+*
+* 1. `frameHandle` — the node-local native lease. Cheapest when it hits (no
+*    payload crosses anything) and the only rung that yields a `nativeCropRef`,
+*    so leaf children re-cut their ROI at native resolution. **The runner cuts.**
+* 2. `frameJpeg` — a FULL frame the caller still holds. **The runner cuts**, with
+*    the same `deriveDetailCropRect` and the same convention, so the rectangle is
+*    identical to what rung 1 would have asked for. Reached when the lease has
+*    already expired — which, for the live detail plane, is the common case: the
+*    dispatcher's tick plus a 500–900 ms inference routinely outlives a 1.2 s
+*    lease, and before this rung was wired the step was simply abandoned.
+* 3. `cropJpeg` — an ALREADY-CUT tile, used verbatim, no padding and no squaring.
+*    **The caller decided the rectangle**, so it is outside the single-derivation
+*    guarantee and is only for the lease-miss retry.
+*
+* A rung-1 miss is remembered even when a lower rung succeeds, and travels into
+* the drop line below: "the native lease never hits any more" is precisely the
+* condition that goes invisible once something else covers for it.
 *
 * STRICT `steps` semantics: when the caller names an explicit `input.steps`
 * set, each matched root's descendant chain is pruned to exactly those ids
@@ -1982,7 +2193,7 @@ async function runDetailSubtree(deps, input) {
 	}
 	const requested = input.steps;
 	const steps = requested === void 0 ? matched : matched.map((step) => pruneChildStepsToRequested(step, requested));
-	const crop = await resolveCrop(deps, input, deps.resolveCropConvention(input.deviceId));
+	const { crop, nativeMiss } = await resolveCrop(deps, input, deps.resolveCropConvention(input.deviceId));
 	if (!crop) {
 		deps.logger.warn("runDetailSubtree: no crop source resolved — the dispatch produced nothing", {
 			tags: { deviceId: input.deviceId },
@@ -1990,7 +2201,9 @@ async function runDetailSubtree(deps, input) {
 				parentClass: input.parent.className,
 				hadFrameHandle: input.frameHandle !== void 0,
 				hadFrameJpeg: input.frameJpeg !== void 0,
-				hadCropJpeg: input.cropJpeg !== void 0
+				hadCropJpeg: input.cropJpeg !== void 0,
+				nativeMissReason: nativeMiss?.miss ?? null,
+				nativeHandleAgeMs: nativeMiss?.handleAgeMs ?? null
 			}
 		});
 		return null;
@@ -2945,16 +3158,24 @@ var PipelineRunner = class {
 			handle
 		});
 	}
+	/**
+	* Returns whether the frame was ADMITTED to the detection queue — i.e.
+	* whether it will reach inference. The caller uses that to mark the frame's
+	* native lease worth keeping (`NativeCropRequester.markInferred`): a native
+	* crop can only ever name a frameId that rode an inference result, so a
+	* frame rejected here is one nobody can ask for. A `false` here is the whole
+	* saving; do not turn it back into `void` for tidiness.
+	*/
 	enqueueDetectionFrame(deviceId, frame, handle) {
 		const state = this.cameras.get(deviceId);
-		if (!state) return;
+		if (!state) return false;
 		this.arrivalCounts.set(deviceId, (this.arrivalCounts.get(deviceId) ?? 0) + 1);
-		if (state.phase !== "active") return;
+		if (state.phase !== "active") return false;
 		const interval = this.governor.minIntervalMs(deviceId);
 		if (interval > 0) {
 			const last = this.lastAdmittedAt.get(deviceId) ?? 0;
 			const now = Date.now();
-			if (now - last < interval) return;
+			if (now - last < interval) return false;
 			this.lastAdmittedAt.set(deviceId, now);
 		}
 		frame._enqueuedAt = Date.now();
@@ -2962,6 +3183,7 @@ var PipelineRunner = class {
 			frame,
 			handle
 		});
+		return true;
 	}
 	/**
 	* `handle` is optional (mirrors {@link DetectionQueueEntry.handle}) — the
@@ -2973,13 +3195,14 @@ var PipelineRunner = class {
 	*/
 	enqueueOccupancyFrame(deviceId, frame, handle) {
 		const state = this.cameras.get(deviceId);
-		if (!state) return;
-		if (state.phase !== "watching") return;
+		if (!state) return false;
+		if (state.phase !== "watching") return false;
 		frame._enqueuedAt = Date.now();
 		state.detectionQueue.enqueue({
 			frame,
 			handle
 		});
+		return true;
 	}
 	/**
 	* Report a motion event for a camera. Drives the unified phase
@@ -3389,6 +3612,83 @@ var PipelineRunner = class {
 	}
 };
 //#endregion
+//#region src/pipeline-runner/stateless-step.ts
+function modelServability(step, modelId, format) {
+	const entry = step.models.find((m) => m.id === modelId);
+	if (entry === void 0) return { kind: "custom-model" };
+	if (entry.formats[format] !== void 0) return { kind: "catalog-build" };
+	return {
+		kind: "no-build",
+		availableFormats: Object.keys(entry.formats)
+	};
+}
+/** Build the refusal answer, log it, and return it — never one without the other. */
+function refuse(deps, input, reason, detail) {
+	deps.logger.warn("runStatelessStep refused", {
+		tags: { deviceId: input.sourceDeviceId },
+		meta: {
+			nodeId: deps.nodeId,
+			stepId: input.stepId,
+			modelId: input.modelId,
+			reason,
+			detail
+		}
+	});
+	return {
+		kind: "refused",
+		nodeId: deps.nodeId,
+		reason,
+		detail
+	};
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Run one step over one subject. See the module header for the two invariants.
+*
+* Never throws: every failure mode is a named, logged refusal, because the
+* caller is a bulk pass whose counters are the only signal an operator gets and
+* a thrown error there reads as "the whole pass broke".
+*/
+async function runStatelessStep(deps, input) {
+	const definition = deps.lookupStep(input.stepId);
+	if (definition === null) return refuse(deps, input, "unknown-step", `this node's step catalog has no "${input.stepId}" — version skew, or a custom step that is not installed here`);
+	if (input.bbox.w <= 0 || input.bbox.h <= 0) return refuse(deps, input, "unreadable-frame", `degenerate normalized bbox ${JSON.stringify(input.bbox)} — nothing to crop`);
+	const format = await deps.executionFormat();
+	if (format === null) return refuse(deps, input, "model-not-servable", "this node could not report the engine format it would dispatch on, so the model pin cannot be verified — running anyway would risk a silent format substitution");
+	const servability = modelServability(definition, input.modelId, format);
+	if (servability.kind === "no-build") return refuse(deps, input, "model-not-servable", `model "${input.modelId}" has no ${format} build (catalog ships: ${servability.availableFormats.join(", ") || "none"}) — this node would have substituted the ${format} default`);
+	let decodeError = null;
+	const crop = await cutFromFullFrame(input.frameJpeg, {
+		kind: "normalized",
+		rect: input.bbox
+	}, deps.resolveCropConvention()).catch((err) => {
+		decodeError = errorMessage(err);
+		return null;
+	});
+	if (crop === null) return refuse(deps, input, "unreadable-frame", decodeError ?? "the supplied frame decoded to no readable dimensions");
+	const steps = [{
+		addonId: input.stepId,
+		modelId: input.modelId,
+		enabled: true
+	}];
+	let result;
+	try {
+		result = await deps.runPipeline(steps, crop.jpeg, input.sourceDeviceId);
+	} catch (err) {
+		return refuse(deps, input, "execution-failed", errorMessage(err));
+	}
+	if (result === null) return refuse(deps, input, "execution-failed", "the executor returned no frame result for the crop");
+	const details = result.detections.map((detection) => toDetailResult(detection, input.stepId, crop));
+	return {
+		kind: "ran",
+		nodeId: deps.nodeId,
+		modelId: input.modelId,
+		details
+	};
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
@@ -4665,13 +4965,38 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* resolve legitimately want the lower-RES honest frame).
 	*/
 	async getNativeCrop(input) {
+		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 !== "ram-fullframe") return null;
+		const crop = this.retainedFrames?.crop(input.handle, input.bbox, input.maxWidth);
+		if (!crop) return null;
+		return this.encodeNativeCropResult({
+			bytes: crop.bytes,
+			width: crop.width,
+			height: crop.height
+		}, resolved.tier, input.encodeJpeg);
+	}
+	/**
+	* The native-lease half of {@link getNativeCrop}, extracted so the DETAIL path
+	* can keep the miss REASON the cap's `null` return has no room for. Both
+	* callers share this one decision — a second copy of the tier arithmetic is
+	* how a quality tier starts differing by caller.
+	*
+	* Logging level follows the CONSEQUENCE, not the event: a native miss that the
+	* RAM tier is allowed to serve (a full-frame resolve) cost nobody anything and
+	* stays at debug; a miss the caller is handed as `null` is lost work and is a
+	* warn, carrying the numbers that decide the fix.
+	*/
+	async resolveNativeCropPixels(input) {
 		const b = input.bbox;
 		const isFullFrame = b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999;
 		const isUnboundedFullFrame = isFullFrame && input.maxWidth === void 0;
 		let nativeResult = null;
 		let missReason = null;
+		let handleAgeMs = null;
 		if (!isUnboundedFullFrame) {
 			const found = this.nativeCropRegistry.get(input.handle);
+			handleAgeMs = found?.ageMs ?? null;
 			if (found) {
 				const result = await found.request(input.bbox, input.maxWidth);
 				if (result) nativeResult = {
@@ -4681,28 +5006,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				};
 				else missReason = "worker-lease-gone";
 			} else missReason = "no-registry-entry";
-			if (missReason !== null) this.ctx.logger.debug("native crop miss", {
-				tags: { deviceId: found?.deviceId ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
-				meta: {
-					reason: missReason,
-					handle: `${input.handle.shmId}#${input.handle.slot}#${input.handle.seq}`,
-					handleNodeId: input.handle.nodeId,
-					handleAgeMs: found?.ageMs ?? null,
-					registrySize: this.nativeCropRegistry.size,
-					registryCap: DEFAULT_NATIVE_CROP_REGISTRY_CAP
-				}
-			});
+			if (missReason !== null) {
+				const tierOnMiss = resolveNativeCropSource(isFullFrame, false);
+				const fields = {
+					tags: { deviceId: found?.deviceId ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
+					meta: {
+						reason: missReason,
+						servedTier: tierOnMiss,
+						handle: `${input.handle.shmId}#${input.handle.slot}#${input.handle.seq}`,
+						handleNodeId: input.handle.nodeId,
+						handleAgeMs,
+						registrySize: this.nativeCropRegistry.size,
+						registryCap: DEFAULT_NATIVE_CROP_REGISTRY_CAP
+					}
+				};
+				if (tierOnMiss === "miss") this.ctx.logger.warn("native crop miss", fields);
+				else this.ctx.logger.debug("native crop miss", fields);
+			}
 		}
-		const tier = resolveNativeCropSource(isFullFrame, nativeResult !== null);
-		if (tier === "native" && nativeResult) return this.encodeNativeCropResult(nativeResult, tier, input.encodeJpeg);
-		if (tier !== "ram-fullframe") return null;
-		const crop = this.retainedFrames?.crop(input.handle, input.bbox, input.maxWidth);
-		if (!crop) return null;
-		return this.encodeNativeCropResult({
-			bytes: crop.bytes,
-			width: crop.width,
-			height: crop.height
-		}, tier, input.encodeJpeg);
+		return {
+			pixels: nativeResult,
+			tier: resolveNativeCropSource(isFullFrame, nativeResult !== null),
+			missReason,
+			handleAgeMs
+		};
 	}
 	/**
 	* Shape a resolved RGB crop into a `getNativeCrop` result. Raw path (default):
@@ -4757,6 +5084,66 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		}, input);
 	}
 	/**
+	* Stateless single-step execution — no attach, no handle, no device
+	* affinity. Delegates the decision table (catalog lookup, MODEL PIN
+	* servability, crop, dispatch) to the deps-injected pure function in
+	* {@link runStatelessStepImpl}; this method only wires the real deps.
+	*
+	* Note what is NOT wired, deliberately: no `resolveChildSteps` (the step
+	* comes from the catalog, not from an attachment) and no `deviceKey` /
+	* device jump (the jump roster is part of the attach config). The step runs
+	* on the node's default engine, which is exactly the engine
+	* `executionFormat` reports — so the servability check and the dispatch
+	* cannot disagree about which format was verified.
+	*/
+	async runStatelessStep(input) {
+		const convention = await this.cropConvention.refresh(this.ctxIfReady?.api);
+		return runStatelessStep({
+			nodeId: this.nodeId,
+			lookupStep: (stepId) => tryGetStepDefinition(stepId),
+			executionFormat: () => this.resolveNodeExecutionFormat(),
+			resolveCropConvention: () => convention,
+			runPipeline: (steps, imageJpeg, sourceDeviceId) => this.runStatelessPipeline(steps, imageJpeg, sourceDeviceId),
+			logger: this.detailSubtreeLogger()
+		}, input);
+	}
+	/**
+	* The model format this node dispatches on when no `deviceKey` is given —
+	* its selected engine's format. `null` on any failure, which the caller
+	* turns into a refusal rather than a guess: a model pin that cannot be
+	* checked is a substitution waiting to happen.
+	*/
+	async resolveNodeExecutionFormat() {
+		const api = this.ctxIfReady?.api;
+		if (!api) return null;
+		try {
+			return (await api.pipelineExecutor.getSelectedEngine.query()).format;
+		} catch (err) {
+			this.ctxIfReady?.logger.warn("runStatelessStep: could not read this node selected engine — refusing rather than guessing a format", { meta: { error: errMsg(err) } });
+			return null;
+		}
+	}
+	/**
+	* Real `runPipeline` dep for the stateless path: node-local
+	* `pipelineExecutor.runPipeline` on the `'full'` plane with NO `deviceKey`.
+	*
+	* `deviceId` is passed so the executor's own gate/substitution lines are
+	* tagged with the source camera. It is a routing hint on other transports,
+	* but not here: the executor is co-located in the `detection` group, so
+	* `localProviderLink` answers in-process before any router sees it — the
+	* call cannot leave the node this one was pinned to.
+	*/
+	async runStatelessPipeline(steps, imageJpeg, sourceDeviceId) {
+		const api = this.ctxIfReady?.api;
+		if (!api) return null;
+		return api.pipelineExecutor.runPipeline.mutate({
+			steps: [...steps],
+			image: new Uint8Array(imageJpeg),
+			deviceId: sourceDeviceId,
+			plane: "full"
+		});
+	}
+	/**
 	* The cluster-wide detail-crop convention — read from the orchestrator's
 	* global settings, NOT from the attach config. See `crop-convention-source.ts`
 	* for why eleven attach builders make the attach config the wrong carrier.
@@ -4765,6 +5152,34 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		info: (message, extras) => this.ctxIfReady?.logger.info(message, extras),
 		warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras)
 	} });
+	/**
+	* The cluster-wide native-frame LEASE knobs (TTL / RAM ceiling / demand
+	* window) — read from the orchestrator's global settings for the same reason
+	* as the crop convention above, and injected into each decode worker at fork
+	* time. See `native-lease-settings-source.ts`.
+	*/
+	nativeLease = new NativeLeaseSettingsSource({ logger: {
+		info: (message, extras) => this.ctxIfReady?.logger.info(message, extras),
+		warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras)
+	} });
+	/**
+	* Fork a decode worker carrying the operator's lease knobs. Used in place of
+	* a bare `forkDecodeWorker` reference at every session-decode spawn site: the
+	* knobs are read at spawn, so a changed setting reaches NEW sessions and
+	* leaves running ones alone (a live session would have to be re-dialled).
+	*/
+	forkDecodeWorkerWithLease = (source) => forkDecodeWorker(source, this.nativeLease.current());
+	/**
+	* Refresh the lease knobs before a decode worker is spawned. Awaited on the
+	* `acquire` leg of `startGuardedSessionDecode` (which always completes before
+	* `startPump` forks), so the spawn sees a value at most one TTL stale rather
+	* than whatever a background refresh happened to have landed.
+	* `NativeLeaseSettingsSource.refresh` swallows its own failures, so this can
+	* never break a dial.
+	*/
+	async refreshNativeLeaseSettings() {
+		await this.nativeLease.refresh(this.ctxIfReady?.api);
+	}
 	/** A warn sink that survives a not-yet-ready ctx (boot-order dispatches). */
 	detailSubtreeLogger() {
 		return { warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras) };
@@ -4847,18 +5262,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* lease (same path the `getNativeCrop` cap method above uses), encodes the
 	* raw RGB crop to JPEG, and denormalizes `paddedBbox` back to frame-space
 	* pixels for the `frameSpace` the caller maps result bboxes against.
+	*
+	* Returns the MISS REASON rather than a bare `null`. This is the only caller
+	* that can carry it anywhere useful — the cap's return shape has no room for
+	* it, and the detail plane's drop line is where an operator reads why an
+	* enrichment dispatch produced nothing.
 	*/
 	async getNativeCropForDetail(_deviceId, handle, paddedBbox) {
-		const native = await this.getNativeCrop({
+		const resolved = await this.resolveNativeCropPixels({
 			handle,
-			bbox: paddedBbox,
-			encodeJpeg: true
+			bbox: paddedBbox
 		});
-		if (!native?.jpeg) return null;
+		if (resolved.pixels === null || resolved.tier !== "native") return {
+			miss: resolved.missReason ?? "worker-lease-gone",
+			handleAgeMs: resolved.handleAgeMs
+		};
+		const encoded = await this.encodeNativeCropResult(resolved.pixels, "native", true);
+		if (!encoded?.jpeg) return {
+			miss: "jpeg-encode-failed",
+			handleAgeMs: resolved.handleAgeMs
+		};
 		return {
-			jpeg: Buffer.from(native.jpeg, "base64"),
-			width: native.width,
-			height: native.height,
+			jpeg: Buffer.from(encoded.jpeg, "base64"),
+			width: encoded.width,
+			height: encoded.height,
 			frameSpace: denormalizeRect(paddedBbox, handle.width, handle.height)
 		};
 	}
@@ -5083,6 +5510,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* Kept as a method so the two call sites need no change.
 	*/
 	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname, ownerNodeId) {
+		await this.refreshNativeLeaseSettings();
 		return acquireSessionDecodeRestreamFrom(api, this.ctx.logger, {
 			deviceId,
 			streamId,
@@ -5124,8 +5552,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	*/
 	enqueueSharedDetectionFrame(deviceId, frame, handle) {
 		const runner = this.runner;
-		if (!runner) return;
-		runner.enqueueDetectionFrame(deviceId, frame, handle);
+		if (!runner) return false;
+		const admitted = runner.enqueueDetectionFrame(deviceId, frame, handle);
 		const sink = this.sharedMotionSinks.get(deviceId);
 		if (sink) {
 			const now = this.sharedSinkNow();
@@ -5134,6 +5562,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				runner.enqueueMotionFrame(deviceId, rgbFrameToGrayFrame(frame), void 0);
 			}
 		}
+		return admitted;
 	}
 	/**
 	* Epic C P1 detection path for a flagged camera: decode `rgb` in a
@@ -5189,7 +5618,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					codec: source.codec
 				} });
 				return startSessionDecodePump({
-					fork: forkDecodeWorker,
+					fork: this.forkDecodeWorkerWithLease,
 					logger: log,
 					source,
 					opts: {
@@ -5201,7 +5630,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					onDecodedFrame: (frame, nativeCrop) => {
 						const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
 						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
-						this.enqueueSharedDetectionFrame(config.deviceId, frame, handle);
+						if (this.enqueueSharedDetectionFrame(config.deviceId, frame, handle)) nativeCrop?.markInferred();
 					}
 				});
 			}
@@ -5234,7 +5663,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					codec: source.codec
 				} });
 				return startSessionDecodePump({
-					fork: forkDecodeWorker,
+					fork: this.forkDecodeWorkerWithLease,
 					logger: log,
 					source,
 					opts: {
@@ -5706,7 +6135,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			logger: log,
 			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: forkDecodeWorker,
+				fork: this.forkDecodeWorkerWithLease,
 				logger: log,
 				source,
 				opts: {
@@ -5719,7 +6148,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 					if (settled) return;
 					const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
 					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
-					runner.enqueueOccupancyFrame(deviceId, frame, handle);
+					if (runner.enqueueOccupancyFrame(deviceId, frame, handle)) nativeCrop?.markInferred();
 					count++;
 					if (count >= frames) {
 						clearTimeout(safetyTimer);