@camstack/addon-pipeline 1.2.43 → 1.2.44

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

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_worker_protocol = require("../worker-protocol-DextwlTX.js");
+const require_worker_protocol = require("../worker-protocol-VURr0nUh.js");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
@@ -375,6 +375,94 @@ var LeaseActivityGate = class {
 		return this.now() < this.armedUntil;
 	}
 };
+/**
+* The marked-frame window plus the offered/admitted/unmarked-crop counters for
+* ONE decode worker. Pure and node-av-free so the filter is unit-testable.
+*/
+var LeaseAdmissionLedger = class {
+	mode;
+	capacity;
+	/** Insertion-ordered so the oldest mark is `keys().next()` — a FIFO window. */
+	marked = /* @__PURE__ */ new Set();
+	markedTotal = 0;
+	offeredCount = 0;
+	admittedCount = 0;
+	unmarkedCropCount = 0;
+	constructor(options) {
+		this.mode = options.mode;
+		this.capacity = Math.max(1, options.capacity ?? 1024);
+	}
+	/**
+	* Marks RECEIVED since the worker started.
+	*
+	* Not a curiosity: in `all` mode every other counter looks identical whether
+	* the mark signal is working or has silently stopped arriving, and
+	* {@link unmarkedCrops} reads 0 in BOTH cases — an empty marked window
+	* answers "was this frame inferred?" with "I cannot say", which is correctly
+	* not counted as evidence. So a premise measured while `marks` is 0 measures
+	* nothing. This is the counter that tells the two apart.
+	*/
+	get marks() {
+		return this.markedTotal;
+	}
+	/** Frames offered to the retention hook since the worker started. */
+	get offered() {
+		return this.offeredCount;
+	}
+	/** Frames the ledger let through to the lease store. */
+	get admitted() {
+		return this.admittedCount;
+	}
+	/**
+	* Crop requests naming a frame inside the tracked window that was never
+	* marked. **This is the premise counter**: any value above 0 means something
+	* can ask for a frame the runner never sent to inference, and `inferred` is
+	* dropping frames that someone wants.
+	*/
+	get unmarkedCrops() {
+		return this.unmarkedCropCount;
+	}
+	/** Marks currently remembered (tests / bound checks). */
+	get markedSize() {
+		return this.marked.size;
+	}
+	/** The runner admitted `frameId` to its detection queue. */
+	mark(frameId) {
+		this.markedTotal++;
+		this.marked.delete(frameId);
+		this.marked.add(frameId);
+		while (this.marked.size > this.capacity) {
+			const oldest = this.marked.values().next().value;
+			if (oldest === void 0) break;
+			this.marked.delete(oldest);
+		}
+	}
+	/**
+	* Should this delivered frame get a native lease? `true` in `all` mode
+	* always; in `inferred` mode only when the runner marked it. Counts both
+	* either way, so the saving is visible on the metrics line in both modes.
+	*/
+	admit(frameId) {
+		this.offeredCount++;
+		const keep = this.mode === "all" || this.marked.has(frameId);
+		if (keep) this.admittedCount++;
+		return keep;
+	}
+	/**
+	* Record a native-crop request for `frameId`. Returns `true` when that frame
+	* was never marked AND is recent enough for the window to be sure of it —
+	* a frame older than the oldest remembered mark is UNKNOWABLE, not evidence,
+	* and is deliberately not counted (over-reporting here would read as a broken
+	* premise and send the next session chasing nothing).
+	*/
+	noteCropRequest(frameId) {
+		if (this.marked.has(frameId)) return false;
+		const oldest = this.marked.values().next().value;
+		if (oldest === void 0 || frameId < oldest) return false;
+		this.unmarkedCropCount++;
+		return true;
+	}
+};
 //#endregion
 //#region src/session-decode/native-frame-ring.ts
 /**
@@ -702,6 +790,17 @@ var METRICS_INTERVAL_MS = 1e4;
 * leak site), so the cap MUST stay small; a miss is free (caller falls back to
 * today's detection-frame crop). Override with `CAMSTACK_SESSION_NATIVE_CROP_RING`
 * (0 disables retention entirely); clamped to [0,4], default 2.
+*
+* **Deliberately NOT an operator setting** (unlike the three lease knobs, which
+* became cluster-wide `pipeline-orchestrator` settings on 2026-08-07). Every
+* slot here pins a GPU/VAAPI surface out of the decoder's own pool, and this is
+* the historic leak site — a value large enough to look useful in a settings UI
+* is a value large enough to starve the decoder, and the failure shows up as a
+* camera at 0 fps rather than as memory pressure anyone would trace back to a
+* slider. The ring is also only reachable at all when the lease is DISABLED
+* (budget 0), so exposing it would offer a knob that does nothing in every
+* default configuration. It stays an env-var escape hatch for the person
+* debugging the lease itself.
 */
 var NATIVE_RING_CAP = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_CROP_RING"]);
@@ -709,21 +808,33 @@ var NATIVE_RING_CAP = (() => {
 	return Math.min(4, Math.max(0, Math.floor(raw)));
 })();
 /**
+* The three native-lease knobs in force for THIS worker, resolved once at
+* module load (the lease store and the demand gate are constructed with the
+* worker instance, before the first `start` message).
+*
+* These are **operator settings**, not env vars: they live on
+* `pipeline-orchestrator`'s cluster-wide globals, the pipeline-runner reads them
+* over the hub-routed `addon-settings` cap, and it injects the ones the operator
+* SET into this child's environment at fork time. Precedence is
+* `setting > env > default` — the `CAMSTACK_SESSION_NATIVE_LEASE_*` vars survive
+* as an emergency/dev override for knobs the operator has not touched. The
+* resolved values AND their source are logged once per worker in
+* {@link DecodeWorkerChild.handleStart}. Full contract:
+* `native-lease-config.ts` and `packages/types/src/pipeline/native-lease.ts`.
+*/
+var NATIVE_LEASE_KNOBS = require_worker_protocol.resolveNativeLeaseKnobs(process.env);
+/**
 * Hard RAM budget (bytes) for the native-frame LEASE store — the primary
 * native-crop survival window. Unlike {@link NATIVE_RING_CAP} (GPU surfaces,
 * leak-prone → tiny), a lease is a downloaded RAM copy, so the window is sized
 * by memory, not a 2-frame count, and the late cross-process crop reliably
 * hits. The primary eviction is the {@link NATIVE_LEASE_TTL_MS} TTL — a 64MB
 * budget held only ~5 native 4K frames (~0.2s), which the late crop still
-* outran; the budget is now a HIGH safety ceiling (default 1024MB) so the TTL
-* is the effective cap and the ~40-200ms crop reliably lands within it.
-* `CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB` (default 1024); `0` DISABLES the
-* lease and falls back to the {@link NATIVE_RING_CAP} GPU ring (today's path).
+* outran; the budget is a HIGH safety ceiling (default 1024MB) so the TTL is
+* the effective cap and the ~40-200ms crop reliably lands within it. `0`
+* DISABLES the lease and falls back to the {@link NATIVE_RING_CAP} GPU ring.
 */
-var NATIVE_LEASE_BUDGET_BYTES = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB"]);
-	return (Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 1024) * 1024 * 1024;
-})();
+var NATIVE_LEASE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.budgetMb * 1024 * 1024;
 /**
 * TTL (ms) after which a native-frame lease is treated as a miss and reclaimed.
 * The backstop that bounds in-flight RAM even if the explicit `releaseNativeLease`
@@ -731,25 +842,19 @@ var NATIVE_LEASE_BUDGET_BYTES = (() => {
 * inference + the cross-process inference-result hop to hub post-analysis +
 * tracking + the tRPC crop round-trip back — on a busy camera with many
 * concurrent tracks that is well past the old 500 ms (which the busiest cameras'
-* subject crops outran, missing to the ≤640 fallback). Raised to 1200 ms; still
+* subject crops outran, missing to the ≤640 fallback). Default 1200 ms; still
 * bounded by the per-session {@link NATIVE_LEASE_BUDGET_BYTES} ceiling and the
 * {@link NATIVE_LEASE_ACTIVITY_WINDOW_MS} demand gate, so idle cameras retain
-* nothing. `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 1200).
+* nothing.
 */
-var NATIVE_LEASE_TTL_MS = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS"]);
-	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1200;
-})();
+var NATIVE_LEASE_TTL_MS = NATIVE_LEASE_KNOBS.values.ttlMs;
 /**
 * Demand window (ms) for the lease-capture {@link LeaseActivityGate}: eager
 * per-frame native downloads run only within this window of the last
-* native-crop request (or dial start). `0` disables gating (legacy always-on
-* eager capture). `CAMSTACK_SESSION_NATIVE_LEASE_ACTIVITY_MS` (default 15000).
+* native-crop request (or dial start). `0` disables the GATE (legacy always-on
+* eager capture) — it does not disable retention. Default 15000.
 */
-var NATIVE_LEASE_ACTIVITY_WINDOW_MS = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_ACTIVITY_MS"]);
-	return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 15e3;
-})();
+var NATIVE_LEASE_ACTIVITY_WINDOW_MS = NATIVE_LEASE_KNOBS.values.activityMs;
 /**
 * `pinnedRgbCrop` — pinned-color RGB24 native-crop retention. DEFAULT **ON**
 * (2026-07-20 rollout); set `CAMSTACK_SESSION_PINNED_RGB_CROP=0` to opt out.
@@ -1040,6 +1145,15 @@ var DecodeWorkerChild = class {
 	*/
 	leaseGate = new LeaseActivityGate(NATIVE_LEASE_ACTIVITY_WINDOW_MS);
 	/**
+	* WHICH delivered frames are worth a native lease — the runner marks the ones
+	* it admitted to inference (`markInferred`), and in `inferred` mode only
+	* those are retained. Also the premise counter: it tallies every crop request
+	* naming a frame that was never marked, in BOTH modes, so the assumption the
+	* filter rests on is measured on live traffic rather than argued. See
+	* `lease-admission-ledger.ts`.
+	*/
+	admission = new LeaseAdmissionLedger({ mode: NATIVE_LEASE_KNOBS.values.admission });
+	/**
 	* DEDICATED full-frame GPU→system download filtergraph
 	* (`scale_<be>=iw:ih,hwdownload,format=nv12,format=yuv420p`) used ONLY to
 	* materialize a HW surface into a leasable software frame at NATIVE
@@ -1151,6 +1265,9 @@ var DecodeWorkerChild = class {
 			case "releaseNativeLease":
 				this.leaseStore.release(message.frameId);
 				return;
+			case "markInferred":
+				this.admission.mark(message.frameId);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -1210,7 +1327,7 @@ var DecodeWorkerChild = class {
 		const skipped = this.framesSkipped + this.frames.droppedCount;
 		const rssMb = Math.round(process.memoryUsage().rss / 1048576);
 		const ageS = Math.round((now - this.startedAt) / 1e3);
-		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, leaseOffered:${this.admission.offered}, leaseAdmitted:${this.admission.admitted}, leaseMarks:${this.admission.marks}, leaseUnmarkedCrops:${this.admission.unmarkedCrops}, leaseAdmission:${NATIVE_LEASE_KNOBS.values.admission}, leaseMb:${Math.round(this.leaseStore.totalBytes / 1048576)}, leaseFrames:${this.leaseStore.size}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 		if (!this.warnedLarge && rssMb >= WORKER_RSS_WARN_MB) {
@@ -1225,6 +1342,7 @@ var DecodeWorkerChild = class {
 		}
 		this.started = true;
 		this.deviceId = source.deviceId;
+		this.emitStderr(`decode-worker-child: ${require_worker_protocol.formatNativeLeaseKnobs(NATIVE_LEASE_KNOBS)}\n`, "info");
 		this.sessionFormat = opts.format ?? "rgb";
 		this.minIntervalMs = opts.fps && opts.fps > 0 ? 1e3 / opts.fps : 0;
 		this.lastMetricsAt = Date.now();
@@ -1275,6 +1393,7 @@ var DecodeWorkerChild = class {
 	*/
 	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
 		this.leaseGate.arm();
+		if (this.admission.noteCropRequest(frameId)) this.emitStderr(`decode-worker-child: native crop named an UNINFERRED frame (frameId ${frameId}) — the 'inferred' lease-admission premise does not hold on this path; total=${this.admission.unmarkedCrops}\n`);
 		const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
 		if (!frame) {
 			this.nativeCropMisses++;
@@ -1344,10 +1463,59 @@ var DecodeWorkerChild = class {
 	*   is leased directly. A download failure still consumes ownership (freed
 	*   here) so the slot never double-frees — the crop simply misses → fallback.
 	* - Lease DISABLED (`budget 0`): fall back to today's tiny GPU {@link nativeRing}.
+	*
+	* ## LEASE ADMISSION — what actually gets stored
+	*
+	* Three conditions decide it, and only the third is per-frame:
+	*   1. the lease is enabled (`budgetMb > 0`);
+	*   2. {@link leaseGate} is inside its demand window (`activityMs` since the
+	*      last native-crop request or the dial);
+	*   3. {@link admission} accepts the frame — everything in `all` mode, only
+	*      frames the runner MARKED as having reached inference in `inferred`
+	*      mode (`nativeLeaseAdmission`).
+	*
+	* What reaches this function at all is the {@link FrameSlot} lifecycle, not a
+	* quality filter. `retainSuperseded` is called only from
+	* `FrameSlot.reserveSlot()` (`frame-slot.ts`), on the frame the PREVIOUS
+	* `pull` delivered to the parent, at the moment the next `pull` supersedes it.
+	* So:
+	*   - frames dropped by the `minIntervalMs` fps throttle never enter the slot
+	*     and are never offered;
+	*   - frames superseded in the slot before any `pull` took them (latest-wins)
+	*     are freed by `publish` and never offered;
+	*   - every DELIVERED frame is offered exactly once, and then rule 3 decides.
+	*
+	* ## Why `inferred` is safe, and how that is checked rather than assumed
+	*
+	* A native crop names a `frameId`, and the only way a `frameId` leaves the
+	* runner is on a `FrameHandle` riding an INFERENCE RESULT — post-analysis
+	* reaches every one of its handles through `processFrame`, whose only
+	* handle-bearing caller is `handleInferenceResult`. A frame the runner never
+	* enqueued is therefore a frame nobody can ask for. The counter that keeps
+	* this honest is `leaseUnmarkedCrops` on the metrics line: it counts crop
+	* requests naming an unmarked frame in BOTH modes, so the premise is a
+	* production number, not a reading of the call graph.
+	*
+	* The NEWEST delivered frame is never at risk either way: it is the slot's
+	* reserved frame and {@link handleNativeCrop} resolves it through
+	* `FrameSlot.toBuffer`, never through the lease.
+	*
+	* ## What it costs / saves
+	*
+	* One 4K frame is ~24.9 MB on the default pinned-RGB24 lease path
+	* ({@link PINNED_RGB_CROP}), ~12.4 MB as YUV420P. At the ~25 delivered fps of
+	* `all` mode that is ~620 MB/s of GPU→RAM download while the gate is open and
+	* a steady-state resident set of roughly `frameBytes × deliveredFps ×
+	* ttlSeconds`. `inferred` cuts both by the governor's admit ratio — ~5 of 25
+	* frames on a two-plane camera, so ~80%. Prompt `releaseNativeLease` reclaims
+	* earlier still, so the observed figure is lower than the ceiling; the
+	* ceiling is what the budget knob has to survive. See
+	* `docs/design/decode-path.md` → "Lease admission".
 	*/
 	captureNativeFrame(frameId, frame) {
 		if (!this.leaseStore.enabled) return this.nativeRing.retain(frameId, frame);
 		if (!this.leaseGate.active) return false;
+		if (!this.admission.admit(frameId)) return false;
 		if (frame.isHwFrame()) {
 			const software = this.downloadToSoftware(frame);
 			frame.free();
@@ -1935,14 +2103,19 @@ var DecodeWorkerChild = class {
 	* output. Public so the module-level process handlers — which only hold the
 	* `worker` instance — emit device-tagged lines too. Callers pass the line
 	* INCLUDING its trailing newline (unchanged from the prior direct writes).
+	*
+	* `level` overrides the derived severity for the few lines whose importance
+	* is not inferable from their words — the lease-knob line states an
+	* operator's configuration taking effect and would otherwise sit at `debug`,
+	* where a setting that failed to arrive is indistinguishable from silence.
 	*/
-	emitStderr(line) {
+	emitStderr(line, level) {
 		const tag = this.deviceId === null ? "[dev:?]" : `[dev:${this.deviceId}]`;
 		process.stderr.write(`${tag} ${line}`);
 		try {
 			this.send({
 				kind: "log",
-				level: require_worker_protocol.logLevelForLine(line),
+				level: level ?? require_worker_protocol.logLevelForLine(line),
 				message: `${tag} ${line.trimEnd()}`
 			});
 		} catch {}

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

@@ -1,4 +1,4 @@
-import { n as isWorkerRequest, r as logLevelForLine } from "../worker-protocol-D7RzZIla.mjs";
+import { i as formatNativeLeaseKnobs, n as isWorkerRequest, o as resolveNativeLeaseKnobs, r as logLevelForLine } from "../worker-protocol-BOXlUhWO.mjs";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
@@ -371,6 +371,94 @@ var LeaseActivityGate = class {
 		return this.now() < this.armedUntil;
 	}
 };
+/**
+* The marked-frame window plus the offered/admitted/unmarked-crop counters for
+* ONE decode worker. Pure and node-av-free so the filter is unit-testable.
+*/
+var LeaseAdmissionLedger = class {
+	mode;
+	capacity;
+	/** Insertion-ordered so the oldest mark is `keys().next()` — a FIFO window. */
+	marked = /* @__PURE__ */ new Set();
+	markedTotal = 0;
+	offeredCount = 0;
+	admittedCount = 0;
+	unmarkedCropCount = 0;
+	constructor(options) {
+		this.mode = options.mode;
+		this.capacity = Math.max(1, options.capacity ?? 1024);
+	}
+	/**
+	* Marks RECEIVED since the worker started.
+	*
+	* Not a curiosity: in `all` mode every other counter looks identical whether
+	* the mark signal is working or has silently stopped arriving, and
+	* {@link unmarkedCrops} reads 0 in BOTH cases — an empty marked window
+	* answers "was this frame inferred?" with "I cannot say", which is correctly
+	* not counted as evidence. So a premise measured while `marks` is 0 measures
+	* nothing. This is the counter that tells the two apart.
+	*/
+	get marks() {
+		return this.markedTotal;
+	}
+	/** Frames offered to the retention hook since the worker started. */
+	get offered() {
+		return this.offeredCount;
+	}
+	/** Frames the ledger let through to the lease store. */
+	get admitted() {
+		return this.admittedCount;
+	}
+	/**
+	* Crop requests naming a frame inside the tracked window that was never
+	* marked. **This is the premise counter**: any value above 0 means something
+	* can ask for a frame the runner never sent to inference, and `inferred` is
+	* dropping frames that someone wants.
+	*/
+	get unmarkedCrops() {
+		return this.unmarkedCropCount;
+	}
+	/** Marks currently remembered (tests / bound checks). */
+	get markedSize() {
+		return this.marked.size;
+	}
+	/** The runner admitted `frameId` to its detection queue. */
+	mark(frameId) {
+		this.markedTotal++;
+		this.marked.delete(frameId);
+		this.marked.add(frameId);
+		while (this.marked.size > this.capacity) {
+			const oldest = this.marked.values().next().value;
+			if (oldest === void 0) break;
+			this.marked.delete(oldest);
+		}
+	}
+	/**
+	* Should this delivered frame get a native lease? `true` in `all` mode
+	* always; in `inferred` mode only when the runner marked it. Counts both
+	* either way, so the saving is visible on the metrics line in both modes.
+	*/
+	admit(frameId) {
+		this.offeredCount++;
+		const keep = this.mode === "all" || this.marked.has(frameId);
+		if (keep) this.admittedCount++;
+		return keep;
+	}
+	/**
+	* Record a native-crop request for `frameId`. Returns `true` when that frame
+	* was never marked AND is recent enough for the window to be sure of it —
+	* a frame older than the oldest remembered mark is UNKNOWABLE, not evidence,
+	* and is deliberately not counted (over-reporting here would read as a broken
+	* premise and send the next session chasing nothing).
+	*/
+	noteCropRequest(frameId) {
+		if (this.marked.has(frameId)) return false;
+		const oldest = this.marked.values().next().value;
+		if (oldest === void 0 || frameId < oldest) return false;
+		this.unmarkedCropCount++;
+		return true;
+	}
+};
 //#endregion
 //#region src/session-decode/native-frame-ring.ts
 /**
@@ -698,6 +786,17 @@ var METRICS_INTERVAL_MS = 1e4;
 * leak site), so the cap MUST stay small; a miss is free (caller falls back to
 * today's detection-frame crop). Override with `CAMSTACK_SESSION_NATIVE_CROP_RING`
 * (0 disables retention entirely); clamped to [0,4], default 2.
+*
+* **Deliberately NOT an operator setting** (unlike the three lease knobs, which
+* became cluster-wide `pipeline-orchestrator` settings on 2026-08-07). Every
+* slot here pins a GPU/VAAPI surface out of the decoder's own pool, and this is
+* the historic leak site — a value large enough to look useful in a settings UI
+* is a value large enough to starve the decoder, and the failure shows up as a
+* camera at 0 fps rather than as memory pressure anyone would trace back to a
+* slider. The ring is also only reachable at all when the lease is DISABLED
+* (budget 0), so exposing it would offer a knob that does nothing in every
+* default configuration. It stays an env-var escape hatch for the person
+* debugging the lease itself.
 */
 var NATIVE_RING_CAP = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_CROP_RING"]);
@@ -705,21 +804,33 @@ var NATIVE_RING_CAP = (() => {
 	return Math.min(4, Math.max(0, Math.floor(raw)));
 })();
 /**
+* The three native-lease knobs in force for THIS worker, resolved once at
+* module load (the lease store and the demand gate are constructed with the
+* worker instance, before the first `start` message).
+*
+* These are **operator settings**, not env vars: they live on
+* `pipeline-orchestrator`'s cluster-wide globals, the pipeline-runner reads them
+* over the hub-routed `addon-settings` cap, and it injects the ones the operator
+* SET into this child's environment at fork time. Precedence is
+* `setting > env > default` — the `CAMSTACK_SESSION_NATIVE_LEASE_*` vars survive
+* as an emergency/dev override for knobs the operator has not touched. The
+* resolved values AND their source are logged once per worker in
+* {@link DecodeWorkerChild.handleStart}. Full contract:
+* `native-lease-config.ts` and `packages/types/src/pipeline/native-lease.ts`.
+*/
+var NATIVE_LEASE_KNOBS = resolveNativeLeaseKnobs(process.env);
+/**
 * Hard RAM budget (bytes) for the native-frame LEASE store — the primary
 * native-crop survival window. Unlike {@link NATIVE_RING_CAP} (GPU surfaces,
 * leak-prone → tiny), a lease is a downloaded RAM copy, so the window is sized
 * by memory, not a 2-frame count, and the late cross-process crop reliably
 * hits. The primary eviction is the {@link NATIVE_LEASE_TTL_MS} TTL — a 64MB
 * budget held only ~5 native 4K frames (~0.2s), which the late crop still
-* outran; the budget is now a HIGH safety ceiling (default 1024MB) so the TTL
-* is the effective cap and the ~40-200ms crop reliably lands within it.
-* `CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB` (default 1024); `0` DISABLES the
-* lease and falls back to the {@link NATIVE_RING_CAP} GPU ring (today's path).
+* outran; the budget is a HIGH safety ceiling (default 1024MB) so the TTL is
+* the effective cap and the ~40-200ms crop reliably lands within it. `0`
+* DISABLES the lease and falls back to the {@link NATIVE_RING_CAP} GPU ring.
 */
-var NATIVE_LEASE_BUDGET_BYTES = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB"]);
-	return (Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 1024) * 1024 * 1024;
-})();
+var NATIVE_LEASE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.budgetMb * 1024 * 1024;
 /**
 * TTL (ms) after which a native-frame lease is treated as a miss and reclaimed.
 * The backstop that bounds in-flight RAM even if the explicit `releaseNativeLease`
@@ -727,25 +838,19 @@ var NATIVE_LEASE_BUDGET_BYTES = (() => {
 * inference + the cross-process inference-result hop to hub post-analysis +
 * tracking + the tRPC crop round-trip back — on a busy camera with many
 * concurrent tracks that is well past the old 500 ms (which the busiest cameras'
-* subject crops outran, missing to the ≤640 fallback). Raised to 1200 ms; still
+* subject crops outran, missing to the ≤640 fallback). Default 1200 ms; still
 * bounded by the per-session {@link NATIVE_LEASE_BUDGET_BYTES} ceiling and the
 * {@link NATIVE_LEASE_ACTIVITY_WINDOW_MS} demand gate, so idle cameras retain
-* nothing. `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 1200).
+* nothing.
 */
-var NATIVE_LEASE_TTL_MS = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS"]);
-	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1200;
-})();
+var NATIVE_LEASE_TTL_MS = NATIVE_LEASE_KNOBS.values.ttlMs;
 /**
 * Demand window (ms) for the lease-capture {@link LeaseActivityGate}: eager
 * per-frame native downloads run only within this window of the last
-* native-crop request (or dial start). `0` disables gating (legacy always-on
-* eager capture). `CAMSTACK_SESSION_NATIVE_LEASE_ACTIVITY_MS` (default 15000).
+* native-crop request (or dial start). `0` disables the GATE (legacy always-on
+* eager capture) — it does not disable retention. Default 15000.
 */
-var NATIVE_LEASE_ACTIVITY_WINDOW_MS = (() => {
-	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_ACTIVITY_MS"]);
-	return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 15e3;
-})();
+var NATIVE_LEASE_ACTIVITY_WINDOW_MS = NATIVE_LEASE_KNOBS.values.activityMs;
 /**
 * `pinnedRgbCrop` — pinned-color RGB24 native-crop retention. DEFAULT **ON**
 * (2026-07-20 rollout); set `CAMSTACK_SESSION_PINNED_RGB_CROP=0` to opt out.
@@ -1036,6 +1141,15 @@ var DecodeWorkerChild = class {
 	*/
 	leaseGate = new LeaseActivityGate(NATIVE_LEASE_ACTIVITY_WINDOW_MS);
 	/**
+	* WHICH delivered frames are worth a native lease — the runner marks the ones
+	* it admitted to inference (`markInferred`), and in `inferred` mode only
+	* those are retained. Also the premise counter: it tallies every crop request
+	* naming a frame that was never marked, in BOTH modes, so the assumption the
+	* filter rests on is measured on live traffic rather than argued. See
+	* `lease-admission-ledger.ts`.
+	*/
+	admission = new LeaseAdmissionLedger({ mode: NATIVE_LEASE_KNOBS.values.admission });
+	/**
 	* DEDICATED full-frame GPU→system download filtergraph
 	* (`scale_<be>=iw:ih,hwdownload,format=nv12,format=yuv420p`) used ONLY to
 	* materialize a HW surface into a leasable software frame at NATIVE
@@ -1147,6 +1261,9 @@ var DecodeWorkerChild = class {
 			case "releaseNativeLease":
 				this.leaseStore.release(message.frameId);
 				return;
+			case "markInferred":
+				this.admission.mark(message.frameId);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -1206,7 +1323,7 @@ var DecodeWorkerChild = class {
 		const skipped = this.framesSkipped + this.frames.droppedCount;
 		const rssMb = Math.round(process.memoryUsage().rss / 1048576);
 		const ageS = Math.round((now - this.startedAt) / 1e3);
-		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}, leaseOffered:${this.admission.offered}, leaseAdmitted:${this.admission.admitted}, leaseMarks:${this.admission.marks}, leaseUnmarkedCrops:${this.admission.unmarkedCrops}, leaseAdmission:${NATIVE_LEASE_KNOBS.values.admission}, leaseMb:${Math.round(this.leaseStore.totalBytes / 1048576)}, leaseFrames:${this.leaseStore.size}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 		if (!this.warnedLarge && rssMb >= WORKER_RSS_WARN_MB) {
@@ -1221,6 +1338,7 @@ var DecodeWorkerChild = class {
 		}
 		this.started = true;
 		this.deviceId = source.deviceId;
+		this.emitStderr(`decode-worker-child: ${formatNativeLeaseKnobs(NATIVE_LEASE_KNOBS)}\n`, "info");
 		this.sessionFormat = opts.format ?? "rgb";
 		this.minIntervalMs = opts.fps && opts.fps > 0 ? 1e3 / opts.fps : 0;
 		this.lastMetricsAt = Date.now();
@@ -1271,6 +1389,7 @@ var DecodeWorkerChild = class {
 	*/
 	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
 		this.leaseGate.arm();
+		if (this.admission.noteCropRequest(frameId)) this.emitStderr(`decode-worker-child: native crop named an UNINFERRED frame (frameId ${frameId}) — the 'inferred' lease-admission premise does not hold on this path; total=${this.admission.unmarkedCrops}\n`);
 		const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
 		if (!frame) {
 			this.nativeCropMisses++;
@@ -1340,10 +1459,59 @@ var DecodeWorkerChild = class {
 	*   is leased directly. A download failure still consumes ownership (freed
 	*   here) so the slot never double-frees — the crop simply misses → fallback.
 	* - Lease DISABLED (`budget 0`): fall back to today's tiny GPU {@link nativeRing}.
+	*
+	* ## LEASE ADMISSION — what actually gets stored
+	*
+	* Three conditions decide it, and only the third is per-frame:
+	*   1. the lease is enabled (`budgetMb > 0`);
+	*   2. {@link leaseGate} is inside its demand window (`activityMs` since the
+	*      last native-crop request or the dial);
+	*   3. {@link admission} accepts the frame — everything in `all` mode, only
+	*      frames the runner MARKED as having reached inference in `inferred`
+	*      mode (`nativeLeaseAdmission`).
+	*
+	* What reaches this function at all is the {@link FrameSlot} lifecycle, not a
+	* quality filter. `retainSuperseded` is called only from
+	* `FrameSlot.reserveSlot()` (`frame-slot.ts`), on the frame the PREVIOUS
+	* `pull` delivered to the parent, at the moment the next `pull` supersedes it.
+	* So:
+	*   - frames dropped by the `minIntervalMs` fps throttle never enter the slot
+	*     and are never offered;
+	*   - frames superseded in the slot before any `pull` took them (latest-wins)
+	*     are freed by `publish` and never offered;
+	*   - every DELIVERED frame is offered exactly once, and then rule 3 decides.
+	*
+	* ## Why `inferred` is safe, and how that is checked rather than assumed
+	*
+	* A native crop names a `frameId`, and the only way a `frameId` leaves the
+	* runner is on a `FrameHandle` riding an INFERENCE RESULT — post-analysis
+	* reaches every one of its handles through `processFrame`, whose only
+	* handle-bearing caller is `handleInferenceResult`. A frame the runner never
+	* enqueued is therefore a frame nobody can ask for. The counter that keeps
+	* this honest is `leaseUnmarkedCrops` on the metrics line: it counts crop
+	* requests naming an unmarked frame in BOTH modes, so the premise is a
+	* production number, not a reading of the call graph.
+	*
+	* The NEWEST delivered frame is never at risk either way: it is the slot's
+	* reserved frame and {@link handleNativeCrop} resolves it through
+	* `FrameSlot.toBuffer`, never through the lease.
+	*
+	* ## What it costs / saves
+	*
+	* One 4K frame is ~24.9 MB on the default pinned-RGB24 lease path
+	* ({@link PINNED_RGB_CROP}), ~12.4 MB as YUV420P. At the ~25 delivered fps of
+	* `all` mode that is ~620 MB/s of GPU→RAM download while the gate is open and
+	* a steady-state resident set of roughly `frameBytes × deliveredFps ×
+	* ttlSeconds`. `inferred` cuts both by the governor's admit ratio — ~5 of 25
+	* frames on a two-plane camera, so ~80%. Prompt `releaseNativeLease` reclaims
+	* earlier still, so the observed figure is lower than the ceiling; the
+	* ceiling is what the budget knob has to survive. See
+	* `docs/design/decode-path.md` → "Lease admission".
 	*/
 	captureNativeFrame(frameId, frame) {
 		if (!this.leaseStore.enabled) return this.nativeRing.retain(frameId, frame);
 		if (!this.leaseGate.active) return false;
+		if (!this.admission.admit(frameId)) return false;
 		if (frame.isHwFrame()) {
 			const software = this.downloadToSoftware(frame);
 			frame.free();
@@ -1931,14 +2099,19 @@ var DecodeWorkerChild = class {
 	* output. Public so the module-level process handlers — which only hold the
 	* `worker` instance — emit device-tagged lines too. Callers pass the line
 	* INCLUDING its trailing newline (unchanged from the prior direct writes).
+	*
+	* `level` overrides the derived severity for the few lines whose importance
+	* is not inferable from their words — the lease-knob line states an
+	* operator's configuration taking effect and would otherwise sit at `debug`,
+	* where a setting that failed to arrive is indistinguishable from silence.
 	*/
-	emitStderr(line) {
+	emitStderr(line, level) {
 		const tag = this.deviceId === null ? "[dev:?]" : `[dev:${this.deviceId}]`;
 		process.stderr.write(`${tag} ${line}`);
 		try {
 			this.send({
 				kind: "log",
-				level: logLevelForLine(line),
+				level: level ?? logLevelForLine(line),
 				message: `${tag} ${line.trimEnd()}`
 			});
 		} catch {}

package/dist/stream-broker/_stub.js

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