@camstack/addon-pipeline 1.1.54 → 1.1.55

package/dist/recorder/index.js

@@ -1,5 +1,5 @@
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-BbaoC680.js");
+const require_dist = require("../dist-DI57FC8K.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let node_child_process = require("node:child_process");

package/dist/recorder/index.mjs

@@ -1,4 +1,4 @@
-import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-CEcTeu1h.mjs";
+import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-RWGGPwVx.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { spawn } from "node:child_process";

package/dist/{remote-source-plane-vN45KFSm.js → remote-source-plane-CHgvzzA6.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-BbaoC680.js");
+const require_dist = require("./dist-DI57FC8K.js");
 let node_crypto = require("node:crypto");
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**

package/dist/{remote-source-plane-CNCqC_XG.mjs → remote-source-plane-DU0aRSPv.mjs}

@@ -1,4 +1,4 @@
-import { D as nodePin, I as errMsg, d as RingBuffer } from "./dist-CEcTeu1h.mjs";
+import { D as nodePin, I as errMsg, d as RingBuffer } from "./dist-RWGGPwVx.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**

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

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_worker_protocol = require("../worker-protocol-DkL6GDxe.js");
+const require_worker_protocol = require("../worker-protocol-PP4jKHHJ.js");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
@@ -237,6 +237,99 @@ var NativeFrameRing = class {
 	}
 };
 //#endregion
+//#region src/session-decode/native-lease-store.ts
+/**
+* A hard-capped-by-bytes, TTL-and-release map from worker frameId → retained
+* RAM frame. Insertion-ordered (`Map`), so budget eviction is FIFO by age.
+*/
+var NativeLeaseStore = class {
+	entries = /* @__PURE__ */ new Map();
+	budgetBytes;
+	ttlMs;
+	now;
+	bytes = 0;
+	constructor(options) {
+		this.budgetBytes = options.budgetBytes;
+		this.ttlMs = options.ttlMs;
+		this.now = options.now ?? Date.now;
+	}
+	/** `false` when the store is disabled (`budgetBytes <= 0`). */
+	get enabled() {
+		return this.budgetBytes > 0;
+	}
+	/** Number of retained leases (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** Total resident bytes across all retained leases (tests / metrics). */
+	get totalBytes() {
+		return this.bytes;
+	}
+	/**
+	* Take ownership of `frame` under `frameId`. Returns `true` when the store
+	* took ownership (caller MUST NOT free), `false` when the store is disabled
+	* (`budgetBytes <= 0`) and the frame was freed here — the caller then keeps
+	* today's GPU-surface-ring path. Sweeps expired leases first, then evicts the
+	* oldest while the total exceeds the budget.
+	*/
+	put(frameId, frame) {
+		if (!this.enabled) {
+			frame.free();
+			return false;
+		}
+		this.drop(frameId);
+		this.sweepExpired();
+		this.entries.set(frameId, {
+			frame,
+			insertedAt: this.now()
+		});
+		this.bytes += frame.byteLength;
+		while (this.bytes > this.budgetBytes && this.entries.size > 0) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.drop(oldest);
+		}
+		return true;
+	}
+	/**
+	* The retained frame for `frameId`, or `null` if never leased, already
+	* released/evicted, OR aged past its TTL (an expired lease is freed + dropped
+	* here so a caller that reads it just after expiry does not resurrect it).
+	*/
+	get(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return null;
+		if (this.now() - entry.insertedAt > this.ttlMs) {
+			this.drop(frameId);
+			return null;
+		}
+		return entry.frame;
+	}
+	/** Free + drop the lease for `frameId` (the prompt release path). Idempotent. */
+	release(frameId) {
+		this.drop(frameId);
+	}
+	/** Free + drop every lease older than the TTL. */
+	sweepExpired() {
+		const cutoff = this.now() - this.ttlMs;
+		for (const [frameId, entry] of this.entries) if (entry.insertedAt < cutoff) this.drop(frameId);
+	}
+	/** Free + drop every retained lease. Idempotent (re-dial + teardown call it). */
+	clear() {
+		for (const entry of this.entries.values()) entry.frame.free();
+		this.entries.clear();
+		this.bytes = 0;
+	}
+	/** Free + remove one entry, keeping the byte tally exact. */
+	drop(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return;
+		this.entries.delete(frameId);
+		this.bytes -= entry.frame.byteLength;
+		entry.frame.free();
+	}
+};
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -262,6 +355,14 @@ var NativeFrameRing = class {
 * NOT `$process`)". Raw `process.on('message')` / `process.send` are the
 * correct, sanctioned mechanism for this specific file only.
 */
+/** Wrap a software YUV420P frame as a lease entry (byte size ≈ w×h×1.5). */
+function toLeasedNavFrame(frame) {
+	return {
+		frame,
+		byteLength: Math.ceil(frame.width * frame.height * 1.5),
+		free: () => frame.free()
+	};
+}
 /** Re-dial backoff on a transient dial error/EOF (mirrors the decoder's PULL_REDIAL_MS). */
 var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
@@ -281,6 +382,32 @@ var NATIVE_RING_CAP = (() => {
 	return Math.min(4, Math.max(0, Math.floor(raw)));
 })();
 /**
+* 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).
+*/
+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;
+})();
+/**
+* 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`
+* is dropped — comfortably longer than the detection inference + crop round-trip
+* (~40-200ms). `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 500).
+*/
+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) : 500;
+})();
+/**
 * The libav GPU scale filter for a hwaccel backend, or `null` when none is
 * known here — those backends fall back to the software crop+scale path.
 * Mirrors `addon-decoder-ffmpeg/src/ffmpeg-args.ts` `gpuScaleFilterForBackend`.
@@ -520,6 +647,29 @@ var DecodeWorkerChild = class {
 	* re-dial + teardown (see {@link closeInput}).
 	*/
 	nativeRing = new NativeFrameRing(NATIVE_RING_CAP);
+	/**
+	* PRIMARY native-frame survival window — a bounded RAM copy of each shipped
+	* detection frame, keyed by frameId, held until release / TTL / budget
+	* eviction. Replaces the tiny GPU {@link nativeRing} as the default (the ring
+	* is used only when the lease is disabled via a 0 budget). Because it holds
+	* DOWNLOADED (system-memory) frames, retaining a large window has no VAAPI
+	* surface-pool starvation risk. Cleared on every re-dial + teardown.
+	*/
+	leaseStore = new NativeLeaseStore({
+		budgetBytes: NATIVE_LEASE_BUDGET_BYTES,
+		ttlMs: NATIVE_LEASE_TTL_MS
+	});
+	/**
+	* 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
+	* resolution (no scale). Kept separate from the detection/native-crop filters
+	* (different geometry). Same dispose discipline: closed on every re-dial
+	* ({@link closeInput}) + teardown, since it references the decoder's per-dial
+	* `hw_frames_ctx`.
+	*/
+	nativeLeaseDownloadFilter = null;
+	nativeLeaseDownloadFilterKey = "";
 	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
 	nativeCropHits = 0;
 	nativeCropMisses = 0;
@@ -555,7 +705,7 @@ var DecodeWorkerChild = class {
 	* the reserve-on-pull invariant (`e3c78a9b`) is unit-tested without
 	* node-av. See that file's doc comment for the full semantics.
 	*/
-	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.nativeRing.retain(frameId, frame) });
+	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.captureNativeFrame(frameId, frame) });
 	/**
 	* Mirrors whether `this.frames` currently has a pull waiting, so
 	* `teardown` knows to resolve it with `{kind:'ended'}` — `FrameSlot`
@@ -584,6 +734,9 @@ var DecodeWorkerChild = class {
 			case "nativeCrop":
 				this.handleNativeCrop(message.requestId, message.frameId, message.bbox, message.maxWidth);
 				return;
+			case "releaseNativeLease":
+				this.leaseStore.release(message.frameId);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -685,7 +838,7 @@ var DecodeWorkerChild = class {
 	* session to software on a GPU-filter error).
 	*/
 	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
-		const frame = this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+		const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
 		if (!frame) {
 			this.nativeCropMisses++;
 			this.send({
@@ -714,6 +867,68 @@ var DecodeWorkerChild = class {
 			});
 		}
 	}
+	/** The GPU-ring or reserved-slot frame for `frameId` (lease-disabled / newest paths). */
+	resolveRetainedFrame(frameId) {
+		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+	}
+	/**
+	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
+	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
+	* returns `true`).
+	*
+	* - Lease ENABLED (default): materialize a SOFTWARE RAM copy and put it in the
+	*   {@link leaseStore}. A HW surface is downloaded to system memory ONCE here
+	*   (freeing the GPU surface immediately — no VAAPI-pool pin); a software frame
+	*   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}.
+	*/
+	captureNativeFrame(frameId, frame) {
+		if (!this.leaseStore.enabled) return this.nativeRing.retain(frameId, frame);
+		if (frame.isHwFrame()) {
+			const software = this.downloadToSoftware(frame);
+			frame.free();
+			if (!software) return true;
+			this.leaseStore.put(frameId, toLeasedNavFrame(software));
+			return true;
+		}
+		this.leaseStore.put(frameId, toLeasedNavFrame(frame));
+		return true;
+	}
+	/**
+	* Download a HW surface to a NATIVE-resolution software YUV420P frame via the
+	* dedicated full-frame download filtergraph. Returns the software frame (owned
+	* by the caller) or `null` on any failure (the lease is then simply skipped).
+	* `processAllSync` only refs the input surface, so the caller frees it after.
+	*/
+	downloadToSoftware(frame) {
+		const nav = this.nav;
+		const scaleFilter = this.gpuScaleFilter;
+		if (!nav || !scaleFilter || !this.hwContext) return null;
+		try {
+			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height).processAllSync(frame);
+			const first = outputs[0] ?? null;
+			for (let i = 1; i < outputs.length; i++) outputs[i]?.free();
+			return first;
+		} catch (err) {
+			this.emitStderr(`decode-worker-child: native lease download failed — ${errMessage(err)}\n`);
+			return null;
+		}
+	}
+	/** Build-once / reuse the full-frame GPU→system YUV420P download filtergraph. */
+	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH) {
+		const key = `${srcW}x${srcH}`;
+		const cached = this.nativeLeaseDownloadFilter;
+		if (cached && key === this.nativeLeaseDownloadFilterKey) return cached;
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
+		const description = `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
+		this.nativeLeaseDownloadFilter = filter;
+		this.nativeLeaseDownloadFilterKey = key;
+		return filter;
+	}
 	/** Map a normalized bbox to an even-aligned pixel crop + (optionally capped) target. */
 	resolveNativeCrop(frame, bbox, maxWidth) {
 		return resolveNativeCropGeometry(frame.width, frame.height, bbox, maxWidth);
@@ -1168,6 +1383,10 @@ var DecodeWorkerChild = class {
 	*/
 	closeInput() {
 		this.nativeRing.clear();
+		this.leaseStore.clear();
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
 		this.nativeCropHwFilter?.close();
 		this.nativeCropHwFilter = null;
 		this.nativeCropHwFilterKey = "";

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

@@ -1,4 +1,4 @@
-import { n as isWorkerRequest } from "../worker-protocol-DGIt_waM.mjs";
+import { n as isWorkerRequest } from "../worker-protocol-CyVJTZEO.mjs";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
@@ -233,6 +233,99 @@ var NativeFrameRing = class {
 	}
 };
 //#endregion
+//#region src/session-decode/native-lease-store.ts
+/**
+* A hard-capped-by-bytes, TTL-and-release map from worker frameId → retained
+* RAM frame. Insertion-ordered (`Map`), so budget eviction is FIFO by age.
+*/
+var NativeLeaseStore = class {
+	entries = /* @__PURE__ */ new Map();
+	budgetBytes;
+	ttlMs;
+	now;
+	bytes = 0;
+	constructor(options) {
+		this.budgetBytes = options.budgetBytes;
+		this.ttlMs = options.ttlMs;
+		this.now = options.now ?? Date.now;
+	}
+	/** `false` when the store is disabled (`budgetBytes <= 0`). */
+	get enabled() {
+		return this.budgetBytes > 0;
+	}
+	/** Number of retained leases (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** Total resident bytes across all retained leases (tests / metrics). */
+	get totalBytes() {
+		return this.bytes;
+	}
+	/**
+	* Take ownership of `frame` under `frameId`. Returns `true` when the store
+	* took ownership (caller MUST NOT free), `false` when the store is disabled
+	* (`budgetBytes <= 0`) and the frame was freed here — the caller then keeps
+	* today's GPU-surface-ring path. Sweeps expired leases first, then evicts the
+	* oldest while the total exceeds the budget.
+	*/
+	put(frameId, frame) {
+		if (!this.enabled) {
+			frame.free();
+			return false;
+		}
+		this.drop(frameId);
+		this.sweepExpired();
+		this.entries.set(frameId, {
+			frame,
+			insertedAt: this.now()
+		});
+		this.bytes += frame.byteLength;
+		while (this.bytes > this.budgetBytes && this.entries.size > 0) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.drop(oldest);
+		}
+		return true;
+	}
+	/**
+	* The retained frame for `frameId`, or `null` if never leased, already
+	* released/evicted, OR aged past its TTL (an expired lease is freed + dropped
+	* here so a caller that reads it just after expiry does not resurrect it).
+	*/
+	get(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return null;
+		if (this.now() - entry.insertedAt > this.ttlMs) {
+			this.drop(frameId);
+			return null;
+		}
+		return entry.frame;
+	}
+	/** Free + drop the lease for `frameId` (the prompt release path). Idempotent. */
+	release(frameId) {
+		this.drop(frameId);
+	}
+	/** Free + drop every lease older than the TTL. */
+	sweepExpired() {
+		const cutoff = this.now() - this.ttlMs;
+		for (const [frameId, entry] of this.entries) if (entry.insertedAt < cutoff) this.drop(frameId);
+	}
+	/** Free + drop every retained lease. Idempotent (re-dial + teardown call it). */
+	clear() {
+		for (const entry of this.entries.values()) entry.frame.free();
+		this.entries.clear();
+		this.bytes = 0;
+	}
+	/** Free + remove one entry, keeping the byte tally exact. */
+	drop(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return;
+		this.entries.delete(frameId);
+		this.bytes -= entry.frame.byteLength;
+		entry.frame.free();
+	}
+};
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -258,6 +351,14 @@ var NativeFrameRing = class {
 * NOT `$process`)". Raw `process.on('message')` / `process.send` are the
 * correct, sanctioned mechanism for this specific file only.
 */
+/** Wrap a software YUV420P frame as a lease entry (byte size ≈ w×h×1.5). */
+function toLeasedNavFrame(frame) {
+	return {
+		frame,
+		byteLength: Math.ceil(frame.width * frame.height * 1.5),
+		free: () => frame.free()
+	};
+}
 /** Re-dial backoff on a transient dial error/EOF (mirrors the decoder's PULL_REDIAL_MS). */
 var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
@@ -277,6 +378,32 @@ var NATIVE_RING_CAP = (() => {
 	return Math.min(4, Math.max(0, Math.floor(raw)));
 })();
 /**
+* 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).
+*/
+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;
+})();
+/**
+* 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`
+* is dropped — comfortably longer than the detection inference + crop round-trip
+* (~40-200ms). `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 500).
+*/
+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) : 500;
+})();
+/**
 * The libav GPU scale filter for a hwaccel backend, or `null` when none is
 * known here — those backends fall back to the software crop+scale path.
 * Mirrors `addon-decoder-ffmpeg/src/ffmpeg-args.ts` `gpuScaleFilterForBackend`.
@@ -516,6 +643,29 @@ var DecodeWorkerChild = class {
 	* re-dial + teardown (see {@link closeInput}).
 	*/
 	nativeRing = new NativeFrameRing(NATIVE_RING_CAP);
+	/**
+	* PRIMARY native-frame survival window — a bounded RAM copy of each shipped
+	* detection frame, keyed by frameId, held until release / TTL / budget
+	* eviction. Replaces the tiny GPU {@link nativeRing} as the default (the ring
+	* is used only when the lease is disabled via a 0 budget). Because it holds
+	* DOWNLOADED (system-memory) frames, retaining a large window has no VAAPI
+	* surface-pool starvation risk. Cleared on every re-dial + teardown.
+	*/
+	leaseStore = new NativeLeaseStore({
+		budgetBytes: NATIVE_LEASE_BUDGET_BYTES,
+		ttlMs: NATIVE_LEASE_TTL_MS
+	});
+	/**
+	* 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
+	* resolution (no scale). Kept separate from the detection/native-crop filters
+	* (different geometry). Same dispose discipline: closed on every re-dial
+	* ({@link closeInput}) + teardown, since it references the decoder's per-dial
+	* `hw_frames_ctx`.
+	*/
+	nativeLeaseDownloadFilter = null;
+	nativeLeaseDownloadFilterKey = "";
 	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
 	nativeCropHits = 0;
 	nativeCropMisses = 0;
@@ -551,7 +701,7 @@ var DecodeWorkerChild = class {
 	* the reserve-on-pull invariant (`e3c78a9b`) is unit-tested without
 	* node-av. See that file's doc comment for the full semantics.
 	*/
-	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.nativeRing.retain(frameId, frame) });
+	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.captureNativeFrame(frameId, frame) });
 	/**
 	* Mirrors whether `this.frames` currently has a pull waiting, so
 	* `teardown` knows to resolve it with `{kind:'ended'}` — `FrameSlot`
@@ -580,6 +730,9 @@ var DecodeWorkerChild = class {
 			case "nativeCrop":
 				this.handleNativeCrop(message.requestId, message.frameId, message.bbox, message.maxWidth);
 				return;
+			case "releaseNativeLease":
+				this.leaseStore.release(message.frameId);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -681,7 +834,7 @@ var DecodeWorkerChild = class {
 	* session to software on a GPU-filter error).
 	*/
 	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
-		const frame = this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+		const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
 		if (!frame) {
 			this.nativeCropMisses++;
 			this.send({
@@ -710,6 +863,68 @@ var DecodeWorkerChild = class {
 			});
 		}
 	}
+	/** The GPU-ring or reserved-slot frame for `frameId` (lease-disabled / newest paths). */
+	resolveRetainedFrame(frameId) {
+		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+	}
+	/**
+	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
+	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
+	* returns `true`).
+	*
+	* - Lease ENABLED (default): materialize a SOFTWARE RAM copy and put it in the
+	*   {@link leaseStore}. A HW surface is downloaded to system memory ONCE here
+	*   (freeing the GPU surface immediately — no VAAPI-pool pin); a software frame
+	*   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}.
+	*/
+	captureNativeFrame(frameId, frame) {
+		if (!this.leaseStore.enabled) return this.nativeRing.retain(frameId, frame);
+		if (frame.isHwFrame()) {
+			const software = this.downloadToSoftware(frame);
+			frame.free();
+			if (!software) return true;
+			this.leaseStore.put(frameId, toLeasedNavFrame(software));
+			return true;
+		}
+		this.leaseStore.put(frameId, toLeasedNavFrame(frame));
+		return true;
+	}
+	/**
+	* Download a HW surface to a NATIVE-resolution software YUV420P frame via the
+	* dedicated full-frame download filtergraph. Returns the software frame (owned
+	* by the caller) or `null` on any failure (the lease is then simply skipped).
+	* `processAllSync` only refs the input surface, so the caller frees it after.
+	*/
+	downloadToSoftware(frame) {
+		const nav = this.nav;
+		const scaleFilter = this.gpuScaleFilter;
+		if (!nav || !scaleFilter || !this.hwContext) return null;
+		try {
+			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height).processAllSync(frame);
+			const first = outputs[0] ?? null;
+			for (let i = 1; i < outputs.length; i++) outputs[i]?.free();
+			return first;
+		} catch (err) {
+			this.emitStderr(`decode-worker-child: native lease download failed — ${errMessage(err)}\n`);
+			return null;
+		}
+	}
+	/** Build-once / reuse the full-frame GPU→system YUV420P download filtergraph. */
+	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH) {
+		const key = `${srcW}x${srcH}`;
+		const cached = this.nativeLeaseDownloadFilter;
+		if (cached && key === this.nativeLeaseDownloadFilterKey) return cached;
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
+		const description = `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
+		this.nativeLeaseDownloadFilter = filter;
+		this.nativeLeaseDownloadFilterKey = key;
+		return filter;
+	}
 	/** Map a normalized bbox to an even-aligned pixel crop + (optionally capped) target. */
 	resolveNativeCrop(frame, bbox, maxWidth) {
 		return resolveNativeCropGeometry(frame.width, frame.height, bbox, maxWidth);
@@ -1164,6 +1379,10 @@ var DecodeWorkerChild = class {
 	*/
 	closeInput() {
 		this.nativeRing.clear();
+		this.leaseStore.clear();
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
 		this.nativeCropHwFilter?.close();
 		this.nativeCropHwFilter = null;
 		this.nativeCropHwFilterKey = "";