@camstack/addon-pipeline-orchestrator 1.2.50 → 1.2.51

package/dist/index.js

@@ -25147,13 +25147,24 @@ method(object({
 /** Playback-speed multiplier for the render (1 = realtime). */
 var ExportSpeedSchema = number().min(.25).max(32);
 /**
-* One dense interval, in SECONDS FROM THE EXPORT'S OWN `fromMs`.
+* One dense interval, in WALL-CLOCK SECONDS FROM THE EXPORT'S OWN `fromMs`.
 *
-* Relative and not absolute epoch on purpose: the renderer's frame-select
-* expression sees ffmpeg's `t`, which starts at 0 for the export's source
-* playlist. Handing it absolute epochs would make every call site responsible
-* for the same subtraction, and the one that forgot would emit a filter that
-* selects nothing — silently, as a uniform timelapse.
+* **Wall clock, not ffmpeg's `t`** — and the recorder translates. A caller
+* derives these bounds from things that happened at a TIME (a track's
+* `firstSeen`), while `t` runs over the source playlist: the concatenation of
+* every segment present for the range, with each recording GAP removed. The
+* two agree only on a window that recorded without one interruption, and only
+* the render side knows the segments, so the translation lives there
+* (`export-dense-map.ts`, addon-pipeline).
+*
+* It was not always so. These seconds were fed to `between(t,…)` verbatim, and
+* on a 10 h window holding 29,393 s of footage every range landed late by the
+* gap accumulated before it — up to 6,607 s, well past EOF. Nothing matched,
+* the video was a uniform timelapse, and the log line reported the five ranges
+* that had been ASKED for (2026-08-13, export `57d14363`, camera 615).
+*
+* Relative and not absolute epoch, because an absolute epoch would make every
+* call site responsible for the same subtraction.
 */
 var ExportDenseRangeSchema = object({
 	fromSec: number().nonnegative(),
@@ -32395,8 +32406,8 @@ var DETAIL_CROP_PADDING_FIELD = {
 	default: DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio
 };
 /**
-* THE native-frame **lease** knobs — TTL, RAM budget and demand window for the
-* decode worker's native-resolution frame retention.
+* THE native-frame **lease** knobs — hold depth, RAM budget, demand window and
+* subject-tile budget for the decode worker's native-resolution retention.
 *
 * ## Why they live here and not in the addon that reads them
 *
@@ -32412,20 +32423,25 @@ var DETAIL_CROP_PADDING_FIELD = {
 * 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
+* hardware: a per-node window 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
+* A HELD 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.
+* resident RAM for ONE busy camera is now `frameBytes × holdFrames`, clamped by
+* the budget ceiling — bounded by a COUNT because a held frame is waiting for
+* one specific event (its own detection result), not for a clock.
+*
+* A TILE is one subject at native resolution, JPEG-encoded: ~60-120 KB on 4K,
+* and nothing at all on a frame that detected nothing. That is the asymmetry
+* this whole shape exists for — see
+* `docs/design/2026-08-13-native-lease-two-tier-redesign.md`.
 */
 /**
 * Store identity of the lease knobs in `pipeline-orchestrator`'s GLOBAL
@@ -32433,10 +32449,11 @@ var DETAIL_CROP_PADDING_FIELD = {
 * the reader can walk every section instead of trusting the section id.
 */
 var NATIVE_LEASE_SECTION_ID = "native-lease";
-var NATIVE_LEASE_TTL_KEY = "nativeLeaseTtlMs";
+var NATIVE_LEASE_HOLD_KEY = "nativeLeaseHoldFrames";
 var NATIVE_LEASE_BUDGET_KEY = "nativeLeaseBudgetMb";
 var NATIVE_LEASE_ACTIVITY_KEY = "nativeLeaseActivityMs";
 var NATIVE_LEASE_ADMISSION_KEY = "nativeLeaseAdmission";
+var NATIVE_LEASE_TILE_BUDGET_KEY = "nativeTileBudgetMb";
 /**
 * WHICH delivered frames the decode worker retains a native copy of.
 *
@@ -32458,25 +32475,32 @@ var NATIVE_LEASE_ADMISSION_KEY = "nativeLeaseAdmission";
 var NativeLeaseAdmissionSchema = _enum(["all", "inferred"]);
 object({
 	/**
-	* How long a retained native frame is served before it counts as a miss.
+	* How many delivered frames the worker HOLDS at once, waiting for each one's
+	* detection result.
+	*
+	* This replaced a TTL on 2026-08-13, and the replacement is the whole point:
+	* a time window was never related to the event the pixels were waiting for.
+	* A held frame now lives from delivery until the runner has its `FrameResult`
+	* — at which moment the runner cuts the subject tiles it actually wanted and
+	* releases the frame. The bound exists only so a runner that stops answering
+	* cannot pin RAM: above it the OLDEST held frame is dropped and counted.
 	*
-	* Must cover the FULL late-crop horizon: detection inference + the
-	* cross-process inference-result hop to hub post-analysis + tracking + the
-	* tRPC crop round-trip back. Below ~500 ms the busiest cameras' subject crops
-	* outrun it and fall back to the ≤640 detection frame; above ~3 s the resident
-	* RAM per busy camera grows linearly with no measured hit-rate gain.
+	* Sizing: the steady state is `inferenceLatency × deliveredFps`, measured at
+	* 40-160 ms × ≤25 fps = 1-4 frames. The default leaves headroom for a hiccup
+	* without ever approaching the old resident set (43 frames × 24.9 MB at 4K).
+	* Raising it does not buy hit rate — it buys tolerance for a slow runner, and
+	* `holdOverflow` on the metrics line is what says you need it.
 	*/
-	ttlMs: number().int().min(250).max(1e4),
+	holdFrames: number().int().min(1).max(64),
 	/**
 	* Hard per-decode-worker RAM ceiling for retained native frames, in MB.
 	*
-	* Intended as a SAFETY ceiling with the TTL as the effective cap — but check
-	* which one is actually binding before reasoning from that. At the shipped
-	* 1024 MB and a 2 800 ms TTL, a 4K camera hits the CEILING first (~43 frames
-	* at ~24 MB each) and the TTL never gets to expire anything; `leaseMb` /
-	* `leaseFrames` on the metrics line say which. When the ceiling binds, a
-	* change that admits fewer frames buys retention WINDOW at constant RAM
-	* rather than giving RAM back — lower this knob if RAM is what you wanted.
+	* Since 2026-08-13 this is a SAFETY ceiling and nothing else: `holdFrames`
+	* is what decides how much is held, and the ceiling is the number above which
+	* something is wrong. Before that it was the effective cap — at 1024 MB with
+	* a 2 800 ms TTL a 4K camera sat pinned at `leaseMb:1020, leaseFrames:43`
+	* with the TTL expiring nothing, which is exactly the confusion the hold
+	* removes. `leaseMb` / `leaseFrames` still say what is resident.
 	* `0` DISABLES the lease entirely and falls the worker back to the tiny
 	* leak-prone GPU surface ring (~85% crop miss; that is what the lease exists
 	* to replace).
@@ -32502,25 +32526,47 @@ object({
 	* there is the signal that some caller names frames outside the inference set
 	* and that this must go back to `all`.
 	*/
-	admission: NativeLeaseAdmissionSchema
+	admission: NativeLeaseAdmissionSchema,
+	/**
+	* RAM ceiling per decode worker, in MB, for the SUBJECT TILES — the
+	* compressed native crops the worker cuts at the moment a frame's detection
+	* result arrives, and keeps long after the frame itself is freed.
+	*
+	* This is the knob that replaced the old retention window, and it buys about
+	* three orders of magnitude more of it: a tile is one subject at native
+	* resolution, JPEG-encoded (~60-120 KB on a 4K person), against ~24.9 MB for
+	* the frame it was cut from. A frame on which nothing was detected costs
+	* nothing at all, which is the real change — the old lease paid per FRAME and
+	* was interrogated per SUBJECT.
+	*
+	* `0` DISABLES tiles, leaving only the hold window and the ≤640 RAM
+	* fallback — i.e. the pre-2026-08-13 miss profile. Set it there only to
+	* reproduce that.
+	*/
+	tileBudgetMb: number().int().min(0).max(1024)
 });
 /**
-* 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.
+* The values in force when the operator has set nothing.
+*
+* `budgetMb` stays at 1024 on the day the hold landed, deliberately: it stopped
+* being the retention window and became the OOM ceiling, and lowering a ceiling
+* in the same change that redefines it would make a regression and a retune
+* indistinguishable. Cut it once `tileHits` / `holdOverflow` have been read on
+* live traffic.
 */
 var DEFAULT_NATIVE_LEASE_SETTINGS = {
-	ttlMs: 1200,
+	holdFrames: 8,
 	budgetMb: 1024,
 	activityMs: 15e3,
+	tileBudgetMb: 64,
 	admission: "inferred"
 };
 /** Slider bounds for the operator-facing knobs (orchestrator settings UI). */
-var NATIVE_LEASE_TTL_FIELD = {
-	min: 250,
-	max: 1e4,
-	step: 50,
-	default: DEFAULT_NATIVE_LEASE_SETTINGS.ttlMs
+var NATIVE_LEASE_HOLD_FIELD = {
+	min: 1,
+	max: 64,
+	step: 1,
+	default: DEFAULT_NATIVE_LEASE_SETTINGS.holdFrames
 };
 var NATIVE_LEASE_BUDGET_FIELD = {
 	min: 0,
@@ -32534,6 +32580,12 @@ var NATIVE_LEASE_ACTIVITY_FIELD = {
 	step: 1e3,
 	default: DEFAULT_NATIVE_LEASE_SETTINGS.activityMs
 };
+var NATIVE_LEASE_TILE_BUDGET_FIELD = {
+	min: 0,
+	max: 1024,
+	step: 16,
+	default: DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb
+};
 /** Select options for the admission knob (orchestrator settings UI). */
 var NATIVE_LEASE_ADMISSION_FIELD = {
 	options: [{
@@ -32907,7 +32959,7 @@ var TRANSIENT_SLOT_READ = Symbol("transient-slot-read");
 * shape so video and audio plumbing self-heal identically.
 */
 /** Poll period — audio chunks arrive ~every 500ms; 200ms keeps latency low. */
-var POLL_INTERVAL_MS = 200;
+var POLL_INTERVAL_MS$1 = 200;
 /** How many chunks to drain per poll — a small burst absorbs jitter. */
 var PULL_MAX_COUNT = 8;
 /**
@@ -33090,7 +33142,7 @@ function startPolling(options, lifecycle) {
 			} });
 			if (!lifecycle.stopped && consecutiveFailures >= RESUBSCRIBE_AFTER_FAILURES && (consecutiveFailures - RESUBSCRIBE_AFTER_FAILURES) % RESUBSCRIBE_THROTTLE_TICKS === 0) await resubscribe();
 		}
-		if (!lifecycle.stopped) lifecycle.pollTimer = setTimeout(() => void tick(), POLL_INTERVAL_MS);
+		if (!lifecycle.stopped) lifecycle.pollTimer = setTimeout(() => void tick(), POLL_INTERVAL_MS$1);
 	};
 	tick();
 }
@@ -41631,6 +41683,79 @@ async function migrateStepGating(deps) {
 	} });
 }
 //#endregion
+//#region src/zone-mirror-hydration.ts
+/** How long to wait for a camera list: the hub wires `ctx.api` AFTER the addon
+*  init chain resolves, and `device-manager` answers a moment later still, so a
+*  task kicked off from `onInitialize` loses both races. Same shape as the
+*  bindings migration's poll — one budget covering "no api yet" and "api, but
+*  device-manager not answering yet", because to this sweep they are the same
+*  thing: no fleet to hydrate. */
+var CAMERA_LIST_WAIT_MS = 6e3;
+var POLL_INTERVAL_MS = 200;
+/**
+* Hydrate the `zones` mirror for every camera once, at boot. Never throws: a
+* hydration sweep that cannot run must not take the orchestrator's boot with
+* it — but it is never silent either, because a skipped sweep is exactly the
+* failure this exists to end.
+*/
+async function hydrateZoneMirrorsAtBoot(deps) {
+	const cameraIds = await readCameraIds(deps);
+	if (cameraIds === null) return;
+	for (const hydrator of deps.hydrators) {
+		let written = 0;
+		let unchanged = 0;
+		let failed = 0;
+		for (const deviceId of cameraIds) try {
+			const outcome = await hydrator.hydrate(deviceId);
+			if (outcome === "written") written++;
+			else if (outcome === "unchanged") unchanged++;
+			else failed++;
+		} catch (err) {
+			failed++;
+			deps.logger.warn("zone mirror boot hydration failed for this camera", {
+				tags: { deviceId },
+				meta: {
+					mirror: hydrator.mirror,
+					error: errMsg(err)
+				}
+			});
+		}
+		deps.logger.info("zone mirror boot hydration complete", { meta: {
+			mirror: hydrator.mirror,
+			cameras: cameraIds.length,
+			written,
+			unchanged,
+			failed
+		} });
+	}
+}
+/**
+* The camera fleet, or `null` when it never became readable inside the budget
+* — in which case this has already said so. Retried inside one budget rather
+* than once, because at orchestrator boot "no api yet" and "device-manager not
+* answering yet" are both transient and indistinguishable from here.
+*/
+async function readCameraIds(deps) {
+	const deadline = Date.now() + (deps.apiWaitMs ?? CAMERA_LIST_WAIT_MS);
+	let lastError = null;
+	for (;;) {
+		const api = deps.api();
+		if (api) try {
+			return (await api.deviceManager.listAll.query({
+				isCamera: true,
+				projection: "slim"
+			})).map((camera) => camera.id);
+		} catch (err) {
+			lastError = err;
+		}
+		if (Date.now() >= deadline) {
+			deps.logger.warn("zones mirror boot hydration SKIPPED — camera list never became readable; mirror-only consumers keep whatever the last write left", { meta: { error: lastError === null ? "ctx.api unavailable" : errMsg(lastError) } });
+			return null;
+		}
+		await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+	}
+}
+//#endregion
 //#region src/zone-rules-provider.ts
 /**
 * `zone-rules-provider.ts` — implements `zoneRulesCapability` for the
@@ -41647,6 +41772,20 @@ async function migrateStepGating(deps) {
 * before persisting — partial / corrupt writes are rejected outright
 * since rules drive runtime filtering and a bad payload would silently
 * widen the operator's intended scope.
+*
+* ── THE MIRROR IS HYDRATED AT BOOT, NOT ONLY ON MUTATION ──────────
+*
+* Same root cause as the `zones` slice (see `zones-provider.ts`): the
+* mirror used to be written only by `persist`, so a camera nobody had
+* mutated since its runtime-state row was last written had NO
+* `zone-rules` slice, and every mirror-only consumer — motion-wasm's
+* zone gate, the detection-pipeline zone gate, the admin rules editor
+* — read "no rules" until an operator happened to save one. Zones and
+* rules gate together, so hydrating one without the other still leaves
+* both runner-side gates inert. {@link ZoneRulesProvider.hydrateMirror}
+* is what the boot sweep (`zone-mirror-hydration.ts`) calls; it is an
+* RPC read, never an event replay (D8), and a stage that could not be
+* read leaves the mirror untouched (D49).
 */
 /**
 * Every zone-rule stage, in the declared enum order. The unified device-state
@@ -41690,6 +41829,11 @@ var ZoneRulesProvider = class {
 	* write on one stage can never drop the other. Built lazily + memoised.
 	*/
 	stateByDevice = /* @__PURE__ */ new Map();
+	/** Per-device fingerprint of the slice this process last successfully wrote.
+	*  Absent ⇒ never mirrored here, so the next hydration writes. */
+	mirroredFingerprint = /* @__PURE__ */ new Map();
+	/** Devices already reported as unmirrorable — one warn per episode. */
+	reportedMirrorFailure = /* @__PURE__ */ new Set();
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
@@ -41732,10 +41876,52 @@ var ZoneRulesProvider = class {
 		if (!parsed.success) throw new Error(`zone-rules.setRules: invalid rule payload — ${parsed.error.issues.map((i) => i.message).join("; ")}`);
 		await this.persist(deviceId, stage, parsed.data);
 	}
+	/**
+	* Reconcile ONE device's `zone-rules` mirror against the durable block.
+	* Called by the boot sweep for every camera. Never throws.
+	*
+	* A stage whose read FAILED aborts the whole hydration: the mirror is a
+	* single slice carrying every stage, so writing a partially-read block would
+	* publish "this stage has no rules" off a store blip — and an empty
+	* `motion`/`detection` array is what makes a gate stop gating.
+	*/
+	async hydrateMirror(deviceId) {
+		const perDevice = this.stageCache(deviceId);
+		for (const stage of ALL_STAGES) {
+			const read = await this.readRules(deviceId, stage);
+			if (!read.ok) return "unreadable";
+			perDevice.set(stage, read.rules);
+		}
+		const slice = await this.buildSliceValue(deviceId, perDevice);
+		const fingerprint = JSON.stringify(slice);
+		if (this.mirroredFingerprint.get(deviceId) === fingerprint) return "unchanged";
+		try {
+			await (await this.ctx.fetchDevice(deviceId)).deviceState.setCapSlice({
+				capName: ZONE_RULES_CAP_NAME,
+				slice
+			});
+		} catch (err) {
+			if (!this.reportedMirrorFailure.has(deviceId)) {
+				this.reportedMirrorFailure.add(deviceId);
+				this.ctx.logger.warn("zone-rules mirror write failed — mirror-only zone gates see NO rules for this camera until it lands", {
+					tags: { deviceId },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			}
+			return "write-failed";
+		}
+		const first = !this.mirroredFingerprint.has(deviceId);
+		this.mirroredFingerprint.set(deviceId, fingerprint);
+		this.reportedMirrorFailure.delete(deviceId);
+		if (first) this.ctx.logger.info("zone-rules mirror hydrated from the durable block", { tags: { deviceId } });
+		return "written";
+	}
 	/** Drop a device's cache entries. Called when the device is removed. */
 	forgetDevice(deviceId) {
 		this.cache.delete(deviceId);
 		this.stateByDevice.delete(deviceId);
+		this.mirroredFingerprint.delete(deviceId);
+		this.reportedMirrorFailure.delete(deviceId);
 	}
 	/** Cap-surface read: a failure folds to the empty list, as it always has. */
 	async loadRules(deviceId, stage) {
@@ -41750,11 +41936,7 @@ var ZoneRulesProvider = class {
 	* momentary store blip into a permanent one.
 	*/
 	async readRules(deviceId, stage) {
-		let perDevice = this.cache.get(deviceId);
-		if (!perDevice) {
-			perDevice = /* @__PURE__ */ new Map();
-			this.cache.set(deviceId, perDevice);
-		}
+		const perDevice = this.stageCache(deviceId);
 		const cached = perDevice.get(stage);
 		if (cached) return {
 			ok: true,
@@ -41795,11 +41977,7 @@ var ZoneRulesProvider = class {
 		};
 	}
 	async persist(deviceId, stage, rules) {
-		let perDevice = this.cache.get(deviceId);
-		if (!perDevice) {
-			perDevice = /* @__PURE__ */ new Map();
-			this.cache.set(deviceId, perDevice);
-		}
+		const perDevice = this.stageCache(deviceId);
 		perDevice.set(stage, rules);
 		await this.rulesState(deviceId).update((prev) => ({
 			...prev,
@@ -41811,6 +41989,8 @@ var ZoneRulesProvider = class {
 				capName: ZONE_RULES_CAP_NAME,
 				slice: sliceValue
 			});
+			this.mirroredFingerprint.set(deviceId, JSON.stringify(sliceValue));
+			this.reportedMirrorFailure.delete(deviceId);
 		} catch (err) {
 			this.ctx.logger.debug("zone-rules slice mirror failed", {
 				tags: { deviceId },
@@ -41829,6 +42009,15 @@ var ZoneRulesProvider = class {
 	* also warms the cache). Iterates {@link ALL_STAGES} so it stays exhaustive
 	* over the cap's stage discriminator without a per-stage branch.
 	*/
+	/** The per-stage cache map for a device, created on first use. */
+	stageCache(deviceId) {
+		let perDevice = this.cache.get(deviceId);
+		if (!perDevice) {
+			perDevice = /* @__PURE__ */ new Map();
+			this.cache.set(deviceId, perDevice);
+		}
+		return perDevice;
+	}
 	async buildSliceValue(deviceId, perDevice) {
 		const slice = {
 			motion: [],
@@ -41846,11 +42035,38 @@ var ZoneRulesProvider = class {
 *
 * Per-camera CRUD over polygon detection zones. Persists to the
 * orchestrator's per-device settings store under the `zones` key and
-* mirrors every change into the device-state `zones` slice via
+* mirrors the catalogue into the device-state `zones` slice via
 * `api.deviceState.setCapSlice`. Downstream consumers (motion-wasm,
 * pipeline-executor, analytics, admin UI) read the live state with
 * the canonical `dev.state.zones.onChanged` channel.
 *
+* ── THIS PROVIDER OWNS THE MIRROR FOR ITS WHOLE LIFETIME ──────────
+*
+* The mirror used to be written in exactly ONE place: `persist`, i.e.
+* only when an operator mutates a zone. Nothing seeded it at startup,
+* so a camera whose runtime-state row had never been written (or had
+* been reset) had no `zones` slice at all, and every mirror-only
+* consumer concluded "this camera has no zones" — forever, because no
+* mutation was coming. Live cost (camera 617 'Parcheggio',
+* 2026-08-12): `zones.listZones {617}` returned 'Parcheggio papà'
+* while `deviceState.getCapSlice {617,'zones'}` returned `null`;
+* occupancy dropped all three parked cars into `unzoned`, its zone
+* rule could never fire, and the admin Zones tab — which reads the
+* same mirror — showed "No zones yet".
+*
+* So the mirror is reconciled against the durable catalogue on the
+* READ path too ({@link ZonesProvider.hydrateMirror}), and the boot
+* sweep in `zone-mirror-hydration.ts` walks every camera once at
+* startup. That is deliberately an RPC read, never an event replay:
+* events are lossy telemetry and a slice change that was dropped is
+* never re-sent (D8).
+*
+* Two rules the hydration path must keep (D49):
+*   - a durable read that FAILED changes nothing — it must never be
+*     mirrored, and must not be cached as "this camera has no zones";
+*   - hydration is a reconcile, not a mutation: `onZonesChanged` is
+*     NOT fired, so nothing downstream re-dispatches on a boot read.
+*
 * Onboard / firmware-reported zones are out of scope for now — every
 * zone is operator-drawn. The provider keeps the surface symmetric:
 * `addZone` rejects id collisions, `updateZone` requires an existing
@@ -41859,6 +42075,11 @@ var ZoneRulesProvider = class {
 var ZONES_STORE_KEY = "zones";
 var ZONES_CAP_NAME = "zones";
 var ZonesArraySchema = array(ZoneSchema);
+/** Identity of a mirrored catalogue — cheap enough to compare on every read,
+*  and it changes whenever anything an operator can see changes. */
+function fingerprintZones(zones) {
+	return JSON.stringify(zones);
+}
 var ZonesProvider = class {
 	ctx;
 	/** Per-device cache. Hydrated lazily on first read for a device. */
@@ -41869,6 +42090,16 @@ var ZonesProvider = class {
 	* be dropped on persist. Built lazily + memoised per device.
 	*/
 	stateByDevice = /* @__PURE__ */ new Map();
+	/**
+	* Per-device fingerprint of the catalogue this process last successfully
+	* wrote to the mirror. Absent ⇒ this process has never mirrored the device,
+	* so the next read hydrates; a write that FAILED leaves it absent, which is
+	* what makes the retry happen on the next read rather than never.
+	*/
+	mirroredFingerprint = /* @__PURE__ */ new Map();
+	/** Devices already reported as unmirrorable — keeps the warn to one per
+	*  episode instead of one per read. */
+	reportedMirrorFailure = /* @__PURE__ */ new Set();
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
@@ -41894,55 +42125,141 @@ var ZonesProvider = class {
 		}
 		return handle;
 	}
+	/**
+	* The device's catalogue — and, on the way past, the one place a mirror-only
+	* consumer's boot blindness is cured: every authoritative read reconciles the
+	* device-state slice against what it just read.
+	*/
 	async listZones({ deviceId }) {
-		return this.loadZones(deviceId);
+		const read = await this.readCatalogue(deviceId);
+		if (read.ok) await this.ensureMirror(deviceId, read.zones);
+		return read.zones;
 	}
 	async addZone({ deviceId, zone }) {
-		const existing = await this.loadZones(deviceId);
+		const existing = await this.readForMutation(deviceId);
 		if (existing.some((entry) => entry.id === zone.id)) throw new Error(`zones.addZone: id ${zone.id} already exists`);
 		await this.persist(deviceId, [...existing, zone]);
 	}
 	async updateZone({ deviceId, zone }) {
-		const existing = await this.loadZones(deviceId);
+		const existing = await this.readForMutation(deviceId);
 		if (!existing.some((entry) => entry.id === zone.id)) throw new Error(`zones.updateZone: id ${zone.id} not found`);
 		const next = existing.map((entry) => entry.id === zone.id ? zone : entry);
 		await this.persist(deviceId, next);
 	}
 	async removeZone({ deviceId, zoneId }) {
-		const existing = await this.loadZones(deviceId);
+		const existing = await this.readForMutation(deviceId);
 		if (!existing.some((entry) => entry.id === zoneId)) return;
 		await this.persist(deviceId, existing.filter((entry) => entry.id !== zoneId));
 	}
 	/**
+	* Reconcile ONE device's mirror against the durable catalogue. The boot
+	* sweep (`zone-mirror-hydration.ts`) calls this for every camera so a
+	* mirror-only consumer never starts blind; `listZones` calls it too, so a
+	* camera adopted after boot is covered by its first read.
+	*
+	* Never throws — a hydration that cannot happen is reported, and reported
+	* once (see {@link ZoneMirrorHydration}).
+	*/
+	async hydrateMirror(deviceId) {
+		const read = await this.readCatalogue(deviceId);
+		if (!read.ok) return "unreadable";
+		return this.ensureMirror(deviceId, read.zones);
+	}
+	/**
 	* Drop a device's cache entry. Called when the device is removed so
 	* the next attach starts from a fresh disk read.
 	*/
 	forgetDevice(deviceId) {
 		this.cache.delete(deviceId);
 		this.stateByDevice.delete(deviceId);
+		this.mirroredFingerprint.delete(deviceId);
+		this.reportedMirrorFailure.delete(deviceId);
 	}
-	async loadZones(deviceId) {
+	/**
+	* The catalogue for a mutation. A mutation is read-modify-write over the
+	* WHOLE array, so proceeding from a failed read would persist the operator's
+	* zones away — refuse instead.
+	*/
+	async readForMutation(deviceId) {
+		const read = await this.readCatalogue(deviceId);
+		if (!read.ok) throw new Error(`zones: catalogue unreadable for device ${deviceId} — refusing to write`);
+		return read.zones;
+	}
+	/**
+	* Read the durable catalogue, cached per device. A FAILED read is neither
+	* cached nor reported as `[]` — the caller decides what an unknown answer
+	* means for it.
+	*/
+	async readCatalogue(deviceId) {
 		const cached = this.cache.get(deviceId);
-		if (cached) return cached;
-		let zones = [];
+		if (cached) return {
+			ok: true,
+			zones: cached
+		};
+		let zones;
 		try {
 			zones = await this.zonesState(deviceId).get();
 		} catch (err) {
-			this.ctx.logger.warn("zones store read failed — using empty list", {
+			this.ctx.logger.warn("zones store read failed — catalogue UNKNOWN for this device", {
 				tags: { deviceId },
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
+			return {
+				ok: false,
+				zones: []
+			};
 		}
 		this.cache.set(deviceId, zones);
-		return zones;
+		return {
+			ok: true,
+			zones
+		};
 	}
-	async persist(deviceId, zones) {
-		this.cache.set(deviceId, zones);
-		await this.zonesState(deviceId).set(zones);
+	/**
+	* Make the device-state mirror agree with `zones`. Idempotent per process
+	* via the fingerprint; the hub itself also no-ops an identical
+	* `setCapSlice`, so this is belt-and-braces against needless RPCs, not
+	* against needless writes.
+	*/
+	async ensureMirror(deviceId, zones) {
+		const fingerprint = fingerprintZones(zones);
+		if (this.mirroredFingerprint.get(deviceId) === fingerprint) return "unchanged";
+		try {
+			await this.writeMirror(deviceId, zones);
+		} catch (err) {
+			if (!this.reportedMirrorFailure.has(deviceId)) {
+				this.reportedMirrorFailure.add(deviceId);
+				this.ctx.logger.warn("zones mirror write failed — mirror-only consumers see NO zones for this camera until it lands", {
+					tags: { deviceId },
+					meta: {
+						zones: zones.length,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+			return "write-failed";
+		}
+		const first = !this.mirroredFingerprint.has(deviceId);
+		this.mirroredFingerprint.set(deviceId, fingerprint);
+		this.reportedMirrorFailure.delete(deviceId);
+		if (first) this.ctx.logger.info("zones mirror hydrated from the durable catalogue", {
+			tags: { deviceId },
+			meta: { zones: zones.length }
+		});
+		return "written";
+	}
+	async writeMirror(deviceId, zones) {
 		await (await this.ctx.fetchDevice(deviceId)).deviceState.setCapSlice({
 			capName: ZONES_CAP_NAME,
 			slice: { zones }
 		});
+	}
+	async persist(deviceId, zones) {
+		this.cache.set(deviceId, zones);
+		await this.zonesState(deviceId).set(zones);
+		await this.writeMirror(deviceId, zones);
+		this.mirroredFingerprint.set(deviceId, fingerprintZones(zones));
+		this.reportedMirrorFailure.delete(deviceId);
 		this.ctx.onZonesChanged?.(deviceId, zones);
 	}
 };
@@ -42355,6 +42672,19 @@ async function buildOrchestratorControllers(deps) {
 			});
 		}
 	});
+	hydrateZoneMirrorsAtBoot({
+		api: () => deps.ctx().api ?? null,
+		hydrators: [{
+			mirror: "zones",
+			hydrate: (deviceId) => zonesProvider.hydrateMirror(deviceId)
+		}, {
+			mirror: "zone-rules",
+			hydrate: (deviceId) => zoneRulesProvider.hydrateMirror(deviceId)
+		}],
+		logger: deps.ctx().logger.child("zones")
+	}).catch((err) => {
+		deps.ctxIfReady()?.logger.warn("zones mirror boot hydration failed", { meta: { error: errMsg(err) } });
+	});
 	const unsubOrchestratorSubscriptions = wireOrchestratorSubscriptions({
 		eventBus: deps.ctx().eventBus,
 		logger: deps.ctx().logger,
@@ -42658,25 +42988,37 @@ function buildGlobalSettingsSections(options) {
 			id: NATIVE_LEASE_SECTION_ID,
 			title: "Native frame lease",
 			tab: "pipeline",
-			description: "How long each decode worker keeps a full-resolution copy of a delivered frame in RAM so a LATE native crop (post-analysis snapshot, face/plate detail) can still be cut from real pixels instead of the ≤640 detection frame. Cost is real: a retained 4K frame is ~24.9 MB on the default pinned-RGB24 path (~12.4 MB as YUV420P), a 1080p frame ~6.2 MB / ~3.1 MB. Worst case for ONE busy camera ≈ frameBytes × delivered fps × TTL seconds, capped by the budget below. Takes effect on the NEXT decode session for a camera, not on sessions already running.",
+			description: "How a decode worker keeps native pixels available for a LATE crop (post-analysis snapshot, face/plate detail) instead of falling back to the ≤640 detection frame. Two things are kept and they cost very differently: a HELD FRAME is a full native raster (~24.9 MB at 4K on the default pinned-RGB24 path, ~6.2 MB at 1080p) and lives only until its own detection result arrives; a TILE is one subject cut from that frame at native resolution and JPEG-encoded (~60-120 KB at 4K), and lives for tens of seconds. A frame on which nothing was detected produces no tiles and costs nothing. Takes effect on the NEXT decode session for a camera, not on sessions already running.",
 			fields: [
 				{
-					key: NATIVE_LEASE_TTL_KEY,
+					key: NATIVE_LEASE_HOLD_KEY,
 					type: "slider",
-					label: "Lease TTL",
-					description: "How long a retained native frame stays claimable before it counts as a miss. It must cover the whole late-crop horizon — detection inference, the cross-process hop to hub post-analysis, tracking, and the tRPC crop round-trip back. Below ~500 ms the busiest cameras outrun it and their crops silently fall back to the downscaled detection frame; every extra second multiplies resident RAM by roughly (frame bytes × delivered fps). 1200 ms is the shipped value.",
-					min: NATIVE_LEASE_TTL_FIELD.min,
-					max: NATIVE_LEASE_TTL_FIELD.max,
-					step: NATIVE_LEASE_TTL_FIELD.step,
-					default: NATIVE_LEASE_TTL_FIELD.default,
+					label: "Frames held at once",
+					description: "How many delivered frames a worker keeps alive while waiting for their detection results. A frame is freed as soon as its own result comes back and its subject tiles have been cut, so the steady state is inference latency × delivered fps — 1 to 4 frames in practice. This number is only the bound above which the OLDEST held frame is dropped, which is what stops a runner that has stopped answering from pinning RAM. Raising it does not improve crop hit rate; it buys tolerance for a slow runner, and holdOverflow on the metrics line is what tells you that you need it.",
+					min: NATIVE_LEASE_HOLD_FIELD.min,
+					max: NATIVE_LEASE_HOLD_FIELD.max,
+					step: NATIVE_LEASE_HOLD_FIELD.step,
+					default: NATIVE_LEASE_HOLD_FIELD.default,
 					showValue: true,
-					unit: "ms"
+					unit: "frames"
+				},
+				{
+					key: NATIVE_LEASE_TILE_BUDGET_KEY,
+					type: "slider",
+					label: "Subject tile RAM",
+					description: "RAM per decode worker for the compressed SUBJECT TILES — the native-resolution crops taken at the moment a frame's detections are known, and kept long after the frame itself is gone. This is what serves a crop that arrives seconds late, which measurement says is the ordinary case (2 to 10 seconds on this cluster). At ~60-120 KB a tile, 64 MB is many hundreds of subjects. 0 turns tiles OFF and restores the old behaviour, where a late crop had nothing to fall back to but the ≤640 detection frame.",
+					min: NATIVE_LEASE_TILE_BUDGET_FIELD.min,
+					max: NATIVE_LEASE_TILE_BUDGET_FIELD.max,
+					step: NATIVE_LEASE_TILE_BUDGET_FIELD.step,
+					default: NATIVE_LEASE_TILE_BUDGET_FIELD.default,
+					showValue: true,
+					unit: "MB"
 				},
 				{
 					key: NATIVE_LEASE_BUDGET_KEY,
 					type: "slider",
 					label: "Lease RAM ceiling",
-					description: "Hard RAM ceiling for retained frames, PER decode worker (one worker per camera per plane). This is a safety ceiling, not the working size — the TTL above is what normally reclaims frames, and at 1024 MB the ceiling is never the binding constraint on a single camera. Lower it on a small host to bound the worst case. 0 DISABLES the lease entirely and falls the worker back to the tiny GPU surface ring, which misses roughly 85% of late crops — that is the behaviour the lease exists to replace, so 0 is a diagnostic setting, not a tuning one.",
+					description: "Hard RAM ceiling for held frames, PER decode worker (one worker per camera per plane). This is a safety ceiling, not the working size — the hold count above is what reclaims frames now, and the ceiling is the number above which something is wrong. Lower it on a small host to bound the worst case. 0 DISABLES the lease entirely and falls the worker back to the tiny GPU surface ring, which misses roughly 85% of late crops — that is the behaviour the lease exists to replace, so 0 is a diagnostic setting, not a tuning one.",
 					min: NATIVE_LEASE_BUDGET_FIELD.min,
 					max: NATIVE_LEASE_BUDGET_FIELD.max,
 					step: NATIVE_LEASE_BUDGET_FIELD.step,