@camstack/types 1.2.42 → 1.2.44

package/dist/node.mjs

@@ -1,6 +1,6 @@
-import { t as canonicalHash } from "./canonical-hash-7nfBbEqR.mjs";
+import { n as canonicalHash, o as buildFfmpegArgs, t as Fmp4BoxSplitter, u as isSoftwareDecode } from "./fmp4-box-splitter-B53u9-Nu.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
@@ -899,4 +899,508 @@ var FfmpegProcess = class {
 	}
 };
 //#endregion
-export { FfmpegProcess, FilesystemStorageProvider, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint };
+//#region src/ffmpeg/fmp4-fragment-plane.ts
+/**
+* Fmp4FragmentPlane — a SUBSCRIBABLE fragmented-MP4 plane, fed by one
+* {@link import('./fmp4-box-splitter.js').Fmp4BoxSplitter}.
+*
+* ## Why a plane and not a callback
+*
+* The operator's requirement for HKSV was explicit: the live fMP4 source built
+* for it must be **dual-use**, so a HomeKit-triggered recording also lands in
+* CamStack as an additional videoclip source alongside the recorder and the NC
+* clip ring — *one fragmenter, two consumers; do not build an HKSV-only pipe*
+* (`docs/roadmap.md` item 4b). A single-callback pipe makes the second consumer
+* a second ffmpeg child of the same camera. So this is the same shape the
+* broker's other multi-consumer surfaces already have
+* (`AudioChunkPlane`, the push packet plane): N independent subscriptions over
+* one producer.
+*
+* **Nothing consumes it yet.** Phase 4 brings the HKSV delegate and phase 4b the
+* clip source; both are named here so the seam is not re-invented, and neither
+* is built.
+*
+* ## The init segment is RETAINED
+*
+* A subscriber that attaches mid-stream — the clip consumer joining an already
+* running HKSV session, which is the whole dual-use case — receives the
+* retained `ftyp`+`moov` as its first packet and then live fragments. Without
+* retention its fragments are undecodable and the failure looks like a codec
+* problem.
+*
+* ## A slow subscriber is CLOSED, never silently gapped
+*
+* `AudioChunkPlane` drops its oldest chunk on overflow, which for audio costs a
+* click. An fMP4 stream with a hole is not a shorter clip, it is a corrupt one:
+* `moof` sequence numbers jump, the consumer's demuxer desynchronises, and HKSV
+* shows a clip that fails to play with nothing anywhere saying why. So a
+* subscription whose queue overflows is ENDED with a reason, loudly, and the
+* other subscriptions are untouched.
+*
+* ## The PREBUFFER (phase 3)
+*
+* HKSV asks for context BEFORE the trigger — `CameraRecordingOptions.prebufferLength`
+* is a HAP-mandated minimum of 4000 ms — and a subscriber that attaches at the
+* motion edge has none. So the plane optionally retains the last few fragments
+* and replays them to a subscriber that asks for them.
+*
+* Three things this ring gets right, each of which is a measured fact rather
+* than a preference (see [D84](../../../../docs/decisions/adr-0084.md)):
+*
+*  - **It is bounded by TIME *and* BYTES.** On the live fleet a 720p copy
+*    fragment is ~255 KB and a 4K one is ~6.35 MB — a 25× spread over the same
+*    window. A time-only bound is a per-camera RAM figure nobody can predict.
+*  - **The window is measured on ARRIVAL, not parsed from `tfdt`.** The
+*    splitter deliberately never computes a fragment's duration (a second
+*    opinion about a fact the muxer owns), and a prebuffer cares about how long
+*    ago the bytes turned up, which is exactly what arrival time answers.
+*  - **A replay is not backlog.** A subscriber taking N retained fragments gets
+*    its queue capacity raised by N for them, because closing a subscriber as a
+*    slow consumer for the prebuffer it explicitly asked for would be the
+*    stupidest possible failure — and, with `DEFAULT_QUEUE_CAPACITY` of 4 and a
+*    ring of 4, the guaranteed one.
+*
+* ## `isLast`
+*
+* hap-nodejs requires the delegate to mark exactly one `RecordingPacket` with
+* `isLast` — a generator that finishes without it produces the twelve-second
+* timeout loop [D50](../../../../../docs/decisions/adr-0050.md) deleted. The
+* plane therefore computes it at DELIVERY time: a packet is last when the plane
+* has ended and nothing remains queued behind it. A subscription that ends
+* having delivered NOTHING says so through {@link Fmp4Subscription.delivered};
+* the future delegate must not open an HDS stream it cannot feed.
+*/
+var DEFAULT_QUEUE_CAPACITY = 4;
+var Fmp4FragmentPlane = class {
+	logger;
+	prebuffer;
+	now;
+	subscriptions = /* @__PURE__ */ new Map();
+	/** The last init unit seen, handed to every later subscriber. */
+	retainedInit = null;
+	ended = false;
+	/** Oldest first. Empty unless {@link Fmp4PrebufferOptions} was supplied. */
+	ring = [];
+	ringBytes = 0;
+	constructor(logger, prebuffer, now = Date.now) {
+		this.logger = logger;
+		this.prebuffer = prebuffer;
+		this.now = now;
+	}
+	get subscriberCount() {
+		return this.subscriptions.size;
+	}
+	/** True once {@link end} has been called — no further units are accepted. */
+	get isEnded() {
+		return this.ended;
+	}
+	/** What the prebuffer ring holds right now. All zeroes when disabled. */
+	prebufferStats() {
+		const oldest = this.ring[0];
+		return {
+			fragments: this.ring.length,
+			bytes: this.ringBytes,
+			spanMs: oldest === void 0 ? 0 : this.now() - oldest.arrivedAt
+		};
+	}
+	subscribe(input) {
+		const replay = input.withPrebuffer === true ? this.trimmedRing() : [];
+		const requested = Math.max(1, input.queueCapacity ?? DEFAULT_QUEUE_CAPACITY);
+		const sub = {
+			id: `fmp4-${randomUUID()}`,
+			tag: input.tag,
+			subscribedAt: this.now(),
+			capacity: requested + replay.length,
+			queue: [],
+			delivered: 0,
+			closedReason: null,
+			wake: null,
+			iterating: false
+		};
+		this.subscriptions.set(sub.id, sub);
+		if (this.retainedInit !== null) this.enqueue(sub, this.retainedInit);
+		for (const retained of replay) this.enqueue(sub, retained.unit);
+		if (this.ended) this.closeSubscription(sub, "ended");
+		this.logger?.info("fmp4 plane: subscribed", { meta: {
+			subscriptionId: sub.id,
+			tag: sub.tag,
+			hasRetainedInit: this.retainedInit !== null,
+			prebufferFragments: replay.length,
+			prebufferBytes: replay.reduce((n, r) => n + r.unit.data.length, 0)
+		} });
+		return this.facade(sub);
+	}
+	/**
+	* Fan one splitter unit out. An `init` REPLACES the retained one — ffmpeg
+	* emits exactly one per child, and a second means the child was respawned, in
+	* which case the old one describes a stream that no longer exists.
+	*/
+	publish(unit) {
+		if (this.ended) return;
+		if (unit.kind === "init") {
+			this.retainedInit = unit;
+			this.ring.length = 0;
+			this.ringBytes = 0;
+		} else this.retain(unit);
+		for (const sub of this.subscriptions.values()) {
+			if (sub.closedReason !== null) continue;
+			this.enqueue(sub, unit);
+		}
+	}
+	/**
+	* The producer stopped. Every subscriber drains what it holds; its final
+	* packet carries `isLast`, and its generator then completes.
+	*/
+	end(reason = "producer ended") {
+		if (this.ended) return;
+		this.ended = true;
+		this.logger?.info("fmp4 plane: ended", { meta: {
+			reason,
+			subscribers: this.subscriptions.size
+		} });
+		for (const sub of this.subscriptions.values()) if (sub.closedReason === null) this.closeSubscription(sub, "ended");
+	}
+	listSubscribers() {
+		return [...this.subscriptions.values()].map((s) => ({
+			tag: s.tag,
+			subscribedAt: s.subscribedAt,
+			delivered: s.delivered,
+			closedReason: s.closedReason
+		}));
+	}
+	/** End and forget everything. Idempotent. */
+	dispose() {
+		this.end("disposed");
+		this.subscriptions.clear();
+		this.retainedInit = null;
+		this.ring.length = 0;
+		this.ringBytes = 0;
+	}
+	/**
+	* Add one fragment to the ring and evict from the front until BOTH bounds
+	* hold. Eviction is oldest-first, which is the one place in this file where
+	* dropping is correct: the ring is context, not stream — nobody is mid-decode
+	* on it, and a subscriber only ever receives a contiguous tail of it.
+	*/
+	retain(unit) {
+		const prebuffer = this.prebuffer;
+		if (prebuffer === void 0) return;
+		const arrivedAt = this.now();
+		this.ring.push({
+			unit,
+			arrivedAt
+		});
+		this.ringBytes += unit.data.length;
+		const cutoff = arrivedAt - prebuffer.windowMs;
+		while (this.ring.length > 0) {
+			const oldest = this.ring[0];
+			if (oldest === void 0) break;
+			const tooOld = oldest.arrivedAt < cutoff;
+			const tooBig = this.ringBytes > prebuffer.maxBytes;
+			if (!tooOld && !tooBig || this.ring.length === 1) break;
+			this.ring.shift();
+			this.ringBytes -= oldest.unit.data.length;
+		}
+	}
+	/**
+	* The ring as a subscriber should receive it — window applied AT SUBSCRIBE
+	* time, not only at publish time. A camera that went quiet keeps its last
+	* fragment in the ring indefinitely (see the never-evict-the-newest rule),
+	* and replaying a 40-second-old fragment as "prebuffer" would put stale video
+	* at the head of a clip iOS presents as the moment of the event.
+	*/
+	trimmedRing() {
+		const prebuffer = this.prebuffer;
+		if (prebuffer === void 0) return [];
+		const cutoff = this.now() - prebuffer.windowMs;
+		return this.ring.filter((r) => r.arrivedAt >= cutoff);
+	}
+	enqueue(sub, unit) {
+		if (sub.queue.length >= sub.capacity) {
+			this.logger?.warn("fmp4 plane: subscriber fell behind — CLOSING it rather than gapping it", { meta: {
+				subscriptionId: sub.id,
+				tag: sub.tag,
+				capacity: sub.capacity,
+				delivered: sub.delivered
+			} });
+			this.closeSubscription(sub, "slow-consumer");
+			return;
+		}
+		sub.queue.push({
+			kind: unit.kind,
+			data: unit.data,
+			sequence: unit.sequence,
+			isLast: false
+		});
+		this.wake(sub);
+	}
+	closeSubscription(sub, reason) {
+		if (sub.closedReason !== null) return;
+		sub.closedReason = reason;
+		if (reason === "slow-consumer") sub.queue.length = 0;
+		this.wake(sub);
+	}
+	wake(sub) {
+		const resume = sub.wake;
+		sub.wake = null;
+		resume?.();
+	}
+	facade(sub) {
+		const plane = this;
+		return {
+			id: sub.id,
+			tag: sub.tag,
+			get delivered() {
+				return sub.delivered;
+			},
+			get closedReason() {
+				return sub.closedReason;
+			},
+			packets: () => plane.iterate(sub),
+			release: () => {
+				plane.closeSubscription(sub, "released");
+				plane.subscriptions.delete(sub.id);
+			}
+		};
+	}
+	async *iterate(sub) {
+		if (sub.iterating) throw new Error(`fmp4 plane: subscription ${sub.tag} is already being consumed — take a second subscription`);
+		sub.iterating = true;
+		for (;;) {
+			const next = sub.queue.shift();
+			if (next === void 0) {
+				if (sub.closedReason !== null) return;
+				await new Promise((resolve) => {
+					sub.wake = resolve;
+				});
+				continue;
+			}
+			const isLast = sub.closedReason === "ended" && sub.queue.length === 0;
+			sub.delivered += 1;
+			yield {
+				...next,
+				isLast
+			};
+			if (isLast) return;
+		}
+	}
+};
+//#endregion
+//#region src/ffmpeg/fmp4-fragment-child.ts
+var DEFAULT_FIRST_UNIT_TIMEOUT_MS = 12e3;
+/** Heartbeat cadence — ~2 minutes of 4 s fragments. */
+var FRAGMENT_LOG_EVERY = 30;
+var Fmp4FragmentChild = class {
+	deps;
+	args;
+	child = null;
+	splitter = new Fmp4BoxSplitter();
+	stopped = false;
+	unitsOut = 0;
+	activeHwAccel = null;
+	constructor(deps, args) {
+		this.deps = deps;
+		this.args = args;
+	}
+	/** Spawn, and resolve once the INIT segment has been cut out of stdout. */
+	async start() {
+		const requested = this.args.invocation.decodeHwAccel;
+		this.activeHwAccel = requested;
+		try {
+			await this.spawnAttempt(requested);
+			return;
+		} catch (err) {
+			if (this.stopped) throw err;
+			if (requested === null || isSoftwareDecode(requested)) throw err;
+			this.deps.logger.warn("fmp4 fragment child: hardware decode produced NO fragment — retrying in SOFTWARE", {
+				tags: { deviceId: this.args.deviceId },
+				meta: {
+					sourceId: this.args.sourceId,
+					decodeHwAccel: requested,
+					error: errMsg(err)
+				}
+			});
+			this.killChild();
+			this.splitter = new Fmp4BoxSplitter();
+			this.activeHwAccel = null;
+			await this.spawnAttempt(null);
+		}
+	}
+	/** The backend the child ACTUALLY ran with — `null` for software. */
+	activeDecodeHwAccel() {
+		const value = this.activeHwAccel;
+		return value === null || value === "none" || value === "copy" ? null : value;
+	}
+	/** Kill ffmpeg and end the plane. Idempotent. */
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.killChild();
+		this.args.plane.end("the fragment child stopped");
+	}
+	spawnAttempt(decodeHwAccel) {
+		const args = buildFfmpegArgs({
+			...this.args.invocation,
+			decodeHwAccel,
+			sink: {
+				kind: "stdout",
+				container: "mp4",
+				fragmentMs: this.args.fragmentMs
+			}
+		});
+		this.deps.logger.info("fmp4 fragment child: spawning ffmpeg", {
+			tags: { deviceId: this.args.deviceId },
+			meta: {
+				sourceId: this.args.sourceId,
+				fragmentMs: this.args.fragmentMs,
+				decodeHwAccel: decodeHwAccel ?? "software",
+				argv: args.join(" ")
+			}
+		});
+		return new Promise((resolve, reject) => {
+			const child = this.deps.spawnFn(this.deps.ffmpegBinaryPath, args, { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+			this.child = child;
+			let settled = false;
+			/**
+			* This attempt FAILED. Set before the kill, because SIGTERM makes the
+			* child exit and that exit must not be reported as a death: the retry —
+			* or the caller's rejection — already owns what happens next. Without it
+			* the timeout path ends the plane the software retry is about to fill,
+			* and the consumer sees a stream that stopped for no reason. A "which
+			* spawn is current" counter does NOT cover this: the retry has not been
+			* spawned when the kill's exit arrives.
+			*/
+			let failed = false;
+			/**
+			* This attempt is still the live producer: it has not failed (a failure
+			* hands ownership to the retry, or to the caller's rejection) and nothing
+			* has stopped the child. Those two cover every way an attempt stops being
+			* current — `start` only respawns after a rejection.
+			*/
+			const isCurrent = () => !this.stopped && !failed;
+			const timeoutMs = this.deps.firstUnitTimeoutMs ?? DEFAULT_FIRST_UNIT_TIMEOUT_MS;
+			const settle = (fail) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				if (fail) {
+					failed = true;
+					reject(fail);
+				} else resolve();
+			};
+			const timer = setTimeout(() => {
+				settle(/* @__PURE__ */ new Error(`fmp4 fragment child: no fragment within ${timeoutMs}ms`));
+				this.killChild();
+			}, timeoutMs);
+			timer.unref?.();
+			child.stdout?.on("data", (chunk) => {
+				for (const unit of this.splitter.push(chunk)) {
+					this.unitsOut += 1;
+					this.args.plane.publish(unit);
+					if (unit.kind === "init") {
+						this.deps.logger.info("fmp4 fragment child: INIT segment cut", {
+							tags: { deviceId: this.args.deviceId },
+							meta: {
+								sourceId: this.args.sourceId,
+								bytes: unit.data.length
+							}
+						});
+						settle();
+					} else if (this.unitsOut % FRAGMENT_LOG_EVERY === 0) this.deps.logger.info("fmp4 fragment child: fragments still flowing", {
+						tags: { deviceId: this.args.deviceId },
+						meta: {
+							sourceId: this.args.sourceId,
+							unitsOut: this.unitsOut,
+							bytes: unit.data.length,
+							subscribers: this.args.plane.subscriberCount
+						}
+					});
+				}
+				const fault = this.splitter.fault;
+				if (fault !== null) this.onFault(fault, settled, isCurrent(), settle);
+			});
+			child.stderr?.setEncoding("utf8");
+			child.stderr?.on("data", (line) => {
+				this.deps.logger.debug("fmp4 fragment child ffmpeg", {
+					tags: { deviceId: this.args.deviceId },
+					meta: {
+						sourceId: this.args.sourceId,
+						line: line.trim()
+					}
+				});
+			});
+			child.once("error", (err) => {
+				if (!settled) {
+					settle(err);
+					return;
+				}
+				if (!isCurrent()) return;
+				this.args.plane.end("the fragment child errored");
+				this.deps.onChildExit?.(err);
+			});
+			child.once("exit", (code, signal) => {
+				if (!settled) {
+					settle(/* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited before any fragment (code=${code} signal=${signal})`));
+					return;
+				}
+				if (!isCurrent()) return;
+				const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited while live (code=${code} signal=${signal})`);
+				this.deps.logger.warn("fmp4 fragment child: ffmpeg exited while live", {
+					tags: { deviceId: this.args.deviceId },
+					meta: {
+						sourceId: this.args.sourceId,
+						code,
+						signal,
+						unitsOut: this.unitsOut
+					}
+				});
+				this.args.plane.end("the fragment child exited");
+				this.deps.onChildExit?.(error);
+			});
+		});
+	}
+	/**
+	* The byte stream stopped being splittable. Not recoverable — the splitter
+	* cannot resynchronise mid-box — so the child is a corpse and every consumer
+	* has to be told, loudly, with the reason.
+	*/
+	onFault(reason, wasLive, current, settle) {
+		const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ${reason}`);
+		this.deps.logger.error("fmp4 fragment child: the ffmpeg output stopped parsing as fMP4", {
+			tags: { deviceId: this.args.deviceId },
+			meta: {
+				sourceId: this.args.sourceId,
+				unitsOut: this.unitsOut,
+				interstitial: this.splitter.discardedInterstitialTypes,
+				reason
+			}
+		});
+		this.killChild();
+		settle(error);
+		if (wasLive && current) {
+			this.args.plane.end("the fragment child produced unsplittable output");
+			this.deps.onChildExit?.(error);
+		}
+	}
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		if (child && !child.killed) try {
+			child.kill("SIGTERM");
+		} catch (err) {
+			this.deps.logger.warn("fmp4 fragment child: kill error", {
+				tags: { deviceId: this.args.deviceId },
+				meta: {
+					sourceId: this.args.sourceId,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+};
+//#endregion
+export { FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint };

package/dist/notification/schedule.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Schedule-window evaluation for the notification-rule vocabulary.
+ *
+ * Hoisted out of the notification-centre's rule engine when a SECOND
+ * consumer appeared (the OSD manager gates an overlay on the same
+ * `NcSchedule`). Addons never import each other, so the alternative was a
+ * copy — and this repo has already recorded what a second copy of a
+ * vocabulary costs (`condition-taxonomy.ts`): two implementations, free to
+ * drift, with nothing that fails when they do.
+ *
+ * Pure: no clock of its own, `atMs` is always supplied by the caller.
+ */
+import type { NcSchedule } from '../capabilities/notification-rules.cap.js';
+/**
+ * Is the schedule active at `atMs`? No schedule = always active. Windows
+ * are OR'd; a window with `startMinute > endMinute` crosses midnight (it
+ * starts on a listed day and spills into the next). `invert` flips the
+ * result (active OUTSIDE the windows).
+ */
+export declare function isScheduleActive(schedule: NcSchedule | undefined, atMs: number): boolean;

package/dist/pipeline/native-lease.d.ts

@@ -0,0 +1,150 @@
+/**
+ * THE native-frame **lease** knobs — TTL, RAM budget and demand window for the
+ * decode worker's native-resolution frame retention.
+ *
+ * ## Why they live here and not in the addon that reads them
+ *
+ * The WRITER is `pipeline-orchestrator` (the cluster-wide settings authority);
+ * the READER is a private child process of `addon-pipeline`'s pipeline-runner.
+ * Addons never import each other, so a key owned by either side would have to
+ * be hand-copied by the other — and a hand-copied key is how a setting silently
+ * stops arriving while both sides still look correct. Same reasoning, same
+ * placement as `detail-crop.ts` (D52's "one cluster-wide orchestrator setting").
+ *
+ * ## Why cluster-wide and not per-node
+ *
+ * The lease is a per-decode-worker RAM window. Its purpose — the late
+ * cross-process native crop landing on a full-resolution frame rather than the
+ * ≤640 detection fallback — is a property of the PIPELINE, not of a node's
+ * hardware: a per-node TTL would mean the same camera produces different crop
+ * quality depending on which node the balancer placed it on, and nobody could
+ * tell that from the stored media. Node-level RAM pressure is already handled
+ * by the per-session budget ceiling, which is itself one of these knobs.
+ *
+ * ## What each knob costs
+ *
+ * A retained frame is a full NATIVE-resolution copy in system RAM. With the
+ * default pinned-RGB24 lease path (`CAMSTACK_SESSION_PINNED_RGB_CROP`, on):
+ * 4K ≈ 24.9 MB/frame, 1080p ≈ 6.2 MB/frame. On the YUV420P path (flag off, and
+ * for software-decoded sessions): 4K ≈ 12.4 MB, 1080p ≈ 3.1 MB. Worst-case
+ * resident RAM for ONE busy camera ≈ frameBytes × deliveredFps × ttlSeconds,
+ * clamped by the budget ceiling. See `docs/design/decode-path.md` → "Lease
+ * admission" for what actually gets admitted.
+ */
+import { z } from 'zod';
+import type { HydratedSettingsView } from './detail-crop.js';
+/**
+ * Store identity of the lease knobs in `pipeline-orchestrator`'s GLOBAL
+ * (cluster-wide) settings. Keys are unique across that addon's whole schema, so
+ * the reader can walk every section instead of trusting the section id.
+ */
+export declare const NATIVE_LEASE_SECTION_ID = "native-lease";
+export declare const NATIVE_LEASE_TTL_KEY = "nativeLeaseTtlMs";
+export declare const NATIVE_LEASE_BUDGET_KEY = "nativeLeaseBudgetMb";
+export declare const NATIVE_LEASE_ACTIVITY_KEY = "nativeLeaseActivityMs";
+export declare const NATIVE_LEASE_ADMISSION_KEY = "nativeLeaseAdmission";
+/**
+ * WHICH delivered frames the decode worker retains a native copy of.
+ *
+ * - `all` — every frame the worker delivered to the runner. The shipped
+ *   behaviour, and the only correct one if something can ask for a crop of a
+ *   frame the runner never sent to inference.
+ * - `inferred` — only the frames the runner ADMITTED to its detection queue.
+ *   A native-crop request always names a `frameId` that rode an inference
+ *   result, so that is the only set a request can name. How much it drops is
+ *   the two-plane governor's admit ratio and nothing else: measured at ~50% on
+ *   this cluster, not the ~80% the design sketch assumed, because the governor
+ *   was not throttling as hard as the sketch supposed. Read
+ *   `leaseAdmitted`/`leaseOffered` off the metrics line for the camera in front
+ *   of you rather than quoting a number from here. The newest delivered frame is
+ *   croppable regardless — it is still the worker's reserved slot, not a lease —
+ *   which covers the one-frame race between a mark and the supersede that
+ *   consumes it.
+ */
+export declare const NativeLeaseAdmissionSchema: z.ZodEnum<{
+    all: "all";
+    inferred: "inferred";
+}>;
+export type NativeLeaseAdmission = z.infer<typeof NativeLeaseAdmissionSchema>;
+/**
+ * Operator-tunable native-lease settings. Bounds are enforced HERE (not only in
+ * the slider) because the value also travels to a forked child process, where a
+ * junk number would silently become a 0-length or unbounded retention window.
+ */
+export declare const NativeLeaseSettingsSchema: z.ZodObject<{
+    ttlMs: z.ZodNumber;
+    budgetMb: z.ZodNumber;
+    activityMs: z.ZodNumber;
+    admission: z.ZodEnum<{
+        all: "all";
+        inferred: "inferred";
+    }>;
+}, z.core.$strip>;
+export type NativeLeaseSettings = z.infer<typeof NativeLeaseSettingsSchema>;
+/**
+ * The values in force when the operator has set nothing — byte-for-byte the
+ * constants the decode worker shipped with as env-var defaults, so making these
+ * settings changed no behaviour on the day it landed.
+ */
+export declare const DEFAULT_NATIVE_LEASE_SETTINGS: NativeLeaseSettings;
+/**
+ * Only the knobs the operator has ACTUALLY set. Distinguishing "set" from
+ * "absent" is what makes the documented precedence (setting > env > default)
+ * expressible: an absent knob leaves the env-var escape hatch working.
+ */
+export type NativeLeaseSettingsOverride = Partial<NativeLeaseSettings>;
+/** Slider bounds for the operator-facing knobs (orchestrator settings UI). */
+export declare const NATIVE_LEASE_TTL_FIELD: {
+    readonly min: 250;
+    readonly max: 10000;
+    readonly step: 50;
+    readonly default: number;
+};
+export declare const NATIVE_LEASE_BUDGET_FIELD: {
+    readonly min: 0;
+    readonly max: 4096;
+    readonly step: 64;
+    readonly default: number;
+};
+export declare const NATIVE_LEASE_ACTIVITY_FIELD: {
+    readonly min: 0;
+    readonly max: 120000;
+    readonly step: 1000;
+    readonly default: number;
+};
+/** Select options for the admission knob (orchestrator settings UI). */
+export declare const NATIVE_LEASE_ADMISSION_FIELD: {
+    readonly options: readonly [{
+        readonly value: "all";
+        readonly label: "Every delivered frame";
+    }, {
+        readonly value: "inferred";
+        readonly label: "Only frames sent to inference";
+    }];
+    readonly default: "all" | "inferred";
+};
+/** The four knobs, as a key union. */
+export type NativeLeaseKnob = keyof NativeLeaseSettings;
+/** The three knobs whose value is a bounded integer (everything but `admission`). */
+export type NativeLeaseNumberKnob = 'ttlMs' | 'budgetMb' | 'activityMs';
+/**
+ * Narrow a FLAT settings record to the knobs the operator set.
+ *
+ * Per-FIELD parse, deliberately: a junk TTL must not also discard a valid
+ * budget. An absent, out-of-bounds or default-valued knob is OMITTED (not
+ * clamped, not defaulted) so the caller can still fall through to the env
+ * override — clamping here would turn a typo into a value nobody chose. See
+ * {@link readKnob} for why the default counts as unset.
+ */
+export declare function readNativeLeaseOverride(config: Readonly<Record<string, unknown>>): NativeLeaseSettingsOverride;
+/**
+ * Extract the operator's lease overrides from an
+ * `addon-settings.getGlobalSettings` payload.
+ *
+ * Walks EVERY section rather than looking inside {@link NATIVE_LEASE_SECTION_ID}
+ * alone: the keys are unique across the addon's schema, and a section rename
+ * must not silently revert the whole cluster to the defaults. A `null` payload
+ * (addon mid-boot) means "operator set nothing" — the env/default fallback then
+ * applies, which is the correct read of "I could not ask".
+ */
+export declare function pickNativeLeaseOverride(view: HydratedSettingsView | null): NativeLeaseSettingsOverride;