@camstack/addon-pipeline 1.2.69 → 1.2.71

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

@@ -1,4 +1,5 @@
-import { i as formatNativeLeaseKnobs, n as isWorkerRequest, o as resolveNativeLeaseKnobs, r as logLevelForLine } from "../worker-protocol-DuftUFEI.mjs";
+import { i as formatNativeLeaseKnobs, n as isWorkerRequest, o as resolveNativeLeaseKnobs, r as logLevelForLine } from "../worker-protocol-Dm6LQ9Ls.mjs";
+import { t as getSharp } from "../lazy-sharp-B-mb8uWx.mjs";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
@@ -535,20 +536,31 @@ 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.
+* A count- and byte-bounded, release-driven map from worker frameId → held RAM
+* frame. Insertion-ordered (`Map`), so every eviction is FIFO by age.
 */
 var NativeLeaseStore = class {
 	entries = /* @__PURE__ */ new Map();
 	budgetBytes;
-	ttlMs;
+	maxFrames;
 	now;
 	bytes = 0;
+	/**
+	* Frames dropped because the hold bound or the byte ceiling was reached
+	* before their release arrived. Non-zero means the runner is not keeping up —
+	* a different sentence from "the crop was late", and the reason this is a
+	* counter and not a silent eviction.
+	*/
+	overflowed = 0;
 	constructor(options) {
 		this.budgetBytes = options.budgetBytes;
-		this.ttlMs = options.ttlMs;
+		this.maxFrames = Math.max(1, options.maxFrames);
 		this.now = options.now ?? Date.now;
 	}
+	/** Frames dropped by a bound rather than released (tests / metrics). */
+	get overflowCount() {
+		return this.overflowed;
+	}
 	/** `false` when the store is disabled (`budgetBytes <= 0`). */
 	get enabled() {
 		return this.budgetBytes > 0;
@@ -574,43 +586,42 @@ var NativeLeaseStore = class {
 			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) {
+		while ((this.entries.size > this.maxFrames || this.bytes > this.budgetBytes) && this.entries.size > 0) {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0) break;
+			if (oldest === frameId) break;
+			this.overflowed += 1;
 			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).
+	* The held frame for `frameId`, or `null` if never held or already
+	* released/evicted. No age check: a frame is held until an EVENT ends the
+	* hold, and a store that also expired on a clock would reintroduce the
+	* unreachable window this design removed.
 	*/
 	get(frameId) {
+		return this.entries.get(frameId)?.frame ?? null;
+	}
+	/** How long `frameId` has been held, or `null` when it is not held. */
+	ageMs(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;
+		return entry ? this.now() - entry.insertedAt : null;
 	}
-	/** Free + drop the lease for `frameId` (the prompt release path). Idempotent. */
+	/**
+	* Free + drop the hold for `frameId` — the runner has this frame's result and
+	* has taken what it wanted. Idempotent, and the ORDINARY exit.
+	*/
 	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). */
+	/** Free + drop every held frame. Idempotent (re-dial + teardown call it). */
 	clear() {
 		for (const entry of this.entries.values()) entry.frame.free();
 		this.entries.clear();
@@ -626,6 +637,244 @@ var NativeLeaseStore = class {
 	}
 };
 //#endregion
+//#region src/session-decode/native-tile-geometry.ts
+/**
+* Pure geometry for the **native subject tile** — the compressed, subject-sized
+* container that replaces retaining a whole native frame.
+*
+* > **NOT WIRED YET.** This module is Phase 1 of
+* > `docs/design/2026-08-13-native-lease-two-tier-redesign.md` and nothing
+* > imports it. It landed with the design because it is the piece whose failure
+* > is SILENT. If you find it still unimported after the next structural train,
+* > delete it — a helper nobody calls reads as verification of a design that
+* > was never built.
+*
+* ## What a tile is, and what it is emphatically not
+*
+* A tile is a **container**: the detection's box, padded generously, clamped
+* inside the frame and even-aligned, cut from the native surface at the one
+* instant the frame is still alive and kept as compressed bytes long after it
+* is gone.
+*
+* It is NOT a model input and it is NOT a crop convention. The rectangle a
+* model is fed is still derived in exactly one place — `deriveDetailCropRect`,
+* reached only through `pipeline-runner/detail-subtree.ts`'s `cutFromFullFrame`
+* ([D52](../../../../docs/decisions/adr-0052.md)) — and is then cut FROM the
+* tile raster instead of from a frame that no longer exists. Two paddings are
+* therefore never composed: the tile's padding decides only how much scene is
+* kept available, and the convention's padding decides the rectangle, exactly
+* as it does today against a full frame.
+*
+* ## The one rule this file exists to enforce
+*
+* **A tile serves a request only when it strictly CONTAINS the requested
+* rectangle.** Not clamps it, not stretches it, not re-pads it — contains it.
+* A rectangle clamped to fit inside a tile would enrich a *different* part of
+* the scene, land in the same vector index as correctly-cut neighbours, and
+* error nowhere: the exact shape of the defect D52 was written for. A
+* non-contained rectangle is a MISS, and the caller falls to the next rung
+* (re-decode from the recorded GOP).
+*
+* Geometry only: no pixels, no node-av, no process state.
+*/
+/**
+* How much scene is kept around the detection box, as a fraction of the box's
+* own width/height, applied on every side.
+*
+* Sized to sit comfortably above the detail-crop convention's own padding
+* (0.15 today, `DEFAULT_DETAIL_CROP_CONVENTION`) so the derived model rectangle
+* lands INSIDE the tile even after a track's box has drifted for a second or
+* two — which is precisely the interval a tile has to survive. Raising it costs
+* bytes quadratically; lowering it converts hits into misses. It is a default,
+* not a convention: nothing about a vector's meaning depends on it, because
+* nothing is ever encoded from the tile's own rectangle.
+*/
+var NATIVE_TILE_PADDING_RATIO = .35;
+/**
+* Resolve the tile container for one detection box.
+*
+* The box arrives NORMALISED against the analysis frame; the tile is expressed
+* in NATIVE frame pixels, because that is the raster the worker cuts from. Both
+* are the same scene at different scales, so the normalised box maps directly.
+*
+* Degenerate and out-of-frame inputs are handled by clamping to the frame — a
+* detection touching the edge yields a smaller tile, never a read past the
+* plane. A zero-area box widens to the 2px chroma minimum.
+*/
+function resolveNativeTileRegion(frameWidth, frameHeight, bbox, paddingRatio = NATIVE_TILE_PADDING_RATIO) {
+	const pad = Number.isFinite(paddingRatio) && paddingRatio > 0 ? paddingRatio : 0;
+	const boxLeft = bbox.x * frameWidth;
+	const boxTop = bbox.y * frameHeight;
+	const boxWidth = bbox.w * frameWidth;
+	const boxHeight = bbox.h * frameHeight;
+	const padX = boxWidth * pad;
+	const padY = boxHeight * pad;
+	const rawLeft = Math.max(0, boxLeft - padX);
+	const rawTop = Math.max(0, boxTop - padY);
+	const rawRight = Math.min(frameWidth, boxLeft + boxWidth + padX);
+	const rawBottom = Math.min(frameHeight, boxTop + boxHeight + padY);
+	const left = clampEven(Math.floor(rawLeft), 0, Math.max(0, frameWidth - 2));
+	const top = clampEven(Math.floor(rawTop), 0, Math.max(0, frameHeight - 2));
+	return {
+		region: {
+			left,
+			top,
+			width: clampEven(Math.ceil(rawRight) - left, 2, frameWidth - left),
+			height: clampEven(Math.ceil(rawBottom) - top, 2, frameHeight - top)
+		},
+		paddingRatio: pad
+	};
+}
+/**
+* Whether `rect` lies wholly inside `tile` — the serve gate.
+*
+* Deliberately strict and deliberately boolean: there is no "close enough"
+* verdict, because the caller's only two honest options are to cut the exact
+* rectangle or to report a miss. Touching the tile's edge counts as inside; a
+* single pixel past it does not.
+*/
+function tileContains(tile, rect) {
+	if (rect.width <= 0 || rect.height <= 0) return false;
+	return rect.left >= tile.left && rect.top >= tile.top && rect.left + rect.width <= tile.left + tile.width && rect.top + rect.height <= tile.top + tile.height;
+}
+/**
+* Translate a FRAME-space rectangle into TILE-space, or `null` when the tile
+* does not contain it.
+*
+* `null` is the miss the caller reports; it must never be turned into a clamp.
+* The returned rectangle is a pure translation — no scaling, no re-alignment —
+* so a caller that cut `rect` from the full frame and a caller that cuts the
+* translated rectangle from the tile obtain the same pixels.
+*/
+function rectWithinTile(tile, rect) {
+	if (!tileContains(tile, rect)) return null;
+	return {
+		left: rect.left - tile.left,
+		top: rect.top - tile.top,
+		width: rect.width,
+		height: rect.height
+	};
+}
+/**
+* Pick the tile that can serve `rect`, or `null` when none contains it.
+*
+* Smallest containing tile wins: a tighter container means less scene around
+* the subject and therefore a smaller decode, and among tiles that all satisfy
+* the containment rule the choice cannot affect the pixels — every one of them
+* would yield the same rectangle of the same frame.
+*
+* `null` is a MISS the caller reports and falls through on. It must never
+* become "use the closest tile and clamp": see this module's header.
+*/
+function selectTileForRect(tiles, rect) {
+	let best = null;
+	let bestArea = Number.POSITIVE_INFINITY;
+	for (const tile of tiles) {
+		const local = rectWithinTile(tile.region, rect);
+		if (local === null) continue;
+		const area = tile.region.width * tile.region.height;
+		if (area >= bestArea) continue;
+		bestArea = area;
+		best = {
+			tile,
+			local
+		};
+	}
+	return best;
+}
+//#endregion
+//#region src/session-decode/native-tile-store.ts
+/**
+* A byte-bounded, TTL'd map from worker frameId → the subject tiles cut from
+* that frame. Insertion-ordered (`Map`), so budget eviction is FIFO by age.
+*/
+var NativeTileStore = 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 tiles are disabled (`budgetBytes <= 0`). */
+	get enabled() {
+		return this.budgetBytes > 0;
+	}
+	/** Number of frames with retained tiles (tests / metrics). */
+	get frameCount() {
+		return this.entries.size;
+	}
+	/** Total retained tiles across every frame (tests / metrics). */
+	get tileCount() {
+		let total = 0;
+		for (const entry of this.entries.values()) total += entry.tiles.length;
+		return total;
+	}
+	/** Total resident bytes (tests / metrics). */
+	get totalBytes() {
+		return this.bytes;
+	}
+	/**
+	* Retain `tiles` for `frameId`. Returns `false` when the store is disabled —
+	* the caller then simply has nothing to fall back on, exactly as before this
+	* store existed. Sweeps expired entries first, then evicts oldest-first while
+	* over budget; the entry just admitted is never the one evicted.
+	*/
+	put(frameId, tiles) {
+		if (!this.enabled || tiles.length === 0) return false;
+		this.drop(frameId);
+		this.sweepExpired();
+		let size = 0;
+		for (const tile of tiles) size += tile.bytes.byteLength;
+		this.entries.set(frameId, {
+			tiles,
+			bytes: size,
+			insertedAt: this.now()
+		});
+		this.bytes += size;
+		while (this.bytes > this.budgetBytes && this.entries.size > 1) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0 || oldest === frameId) break;
+			this.drop(oldest);
+		}
+		return true;
+	}
+	/**
+	* The tiles retained for `frameId`, or an empty array when there are none or
+	* they have aged out. An expired entry is dropped here so a caller reading
+	* just after expiry cannot resurrect it.
+	*/
+	get(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return [];
+		if (this.now() - entry.insertedAt > this.ttlMs) {
+			this.drop(frameId);
+			return [];
+		}
+		return entry.tiles;
+	}
+	/** Drop every entry 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);
+	}
+	/** Drop everything. Idempotent (re-dial + teardown call it). */
+	clear() {
+		this.entries.clear();
+		this.bytes = 0;
+	}
+	/** Remove one frame's tiles, keeping the byte tally exact. */
+	drop(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return;
+		this.entries.delete(frameId);
+		this.bytes -= entry.bytes;
+	}
+};
+//#endregion
 //#region src/session-decode/pinned-rgb-crop.ts
 /**
 * Pure decision/plumbing helpers for the `pinnedRgbCrop` native-crop color fix
@@ -845,30 +1094,48 @@ var NATIVE_RING_CAP = (() => {
 */
 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 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.
+* Hard RAM budget (bytes) for the native-frame HOLD store — the OOM ceiling,
+* and since 2026-08-13 nothing else. {@link NATIVE_LEASE_HOLD_FRAMES} is what
+* decides how much is held; this is the number above which something is wrong.
+* `0` DISABLES the hold and falls back to the {@link NATIVE_RING_CAP} GPU ring.
 */
 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`
-* is dropped. Must comfortably exceed the FULL late-crop horizon: detection
-* 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). 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.
+* How many delivered frames are HELD at once, each waiting for its own
+* detection result. The ordinary exit is `cutTiles` / `releaseNativeLease`; this
+* bound only stops a runner that stopped answering from pinning RAM, and every
+* frame it drops is counted (`holdOverflow`).
 */
-var NATIVE_LEASE_TTL_MS = NATIVE_LEASE_KNOBS.values.ttlMs;
+var NATIVE_LEASE_HOLD_FRAMES = NATIVE_LEASE_KNOBS.values.holdFrames;
+/**
+* Hard RAM budget (bytes) for the SUBJECT TILE store — what survives a frame.
+* `0` turns tiles off and restores the pre-2026-08-13 miss profile.
+*/
+var NATIVE_TILE_BUDGET_BYTES = NATIVE_LEASE_KNOBS.values.tileBudgetMb * 1024 * 1024;
+/**
+* How long a subject tile is served. A TTL is honest HERE and dishonest on the
+* hold: nothing is waiting on a tile, it is speculative retention against a
+* request that may never come. Sized an order of magnitude above the measured
+* ask age (2.2-9.9 s on this cluster) because it can be — a tile is ~60-120 KB.
+* Env-tunable for a bisect; not an operator knob, because the RAM it costs is
+* already the operator's knob.
+*/
+var NATIVE_TILE_TTL_MS = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_TILE_TTL_MS"]);
+	return Number.isFinite(raw) && raw > 0 ? raw : 3e4;
+})();
+/**
+* Most tiles cut from ONE frame, highest-confidence first (the runner orders
+* them). The bound exists because the cut runs on the decode worker between two
+* pulls: a frame that detected twenty subjects must not turn one late crop into
+* twenty encodes. Anything past it is counted, not silently dropped.
+*/
+var NATIVE_TILE_MAX_PER_FRAME = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_TILE_MAX_PER_FRAME"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 4;
+})();
+/** JPEG quality for a retained tile. High: this is a MODEL INPUT, not a preview. */
+var NATIVE_TILE_JPEG_QUALITY = 90;
 /**
 * Demand window (ms) for the lease-capture {@link LeaseActivityGate}: eager
 * per-frame native downloads run only within this window of the last
@@ -1175,8 +1442,31 @@ var DecodeWorkerChild = class {
 	*/
 	leaseStore = new NativeLeaseStore({
 		budgetBytes: NATIVE_LEASE_BUDGET_BYTES,
-		ttlMs: NATIVE_LEASE_TTL_MS
+		maxFrames: NATIVE_LEASE_HOLD_FRAMES
+	});
+	/**
+	* What SURVIVES a held frame: one compressed native tile per subject, cut at
+	* the instant the frame's detection result arrived. Every late native crop
+	* that the hold can no longer serve is served from here — which measurement
+	* says is the ordinary case, not the exception. See `native-tile-store.ts`.
+	*/
+	tileStore = new NativeTileStore({
+		budgetBytes: NATIVE_TILE_BUDGET_BYTES,
+		ttlMs: NATIVE_TILE_TTL_MS
 	});
+	/** Tiles cut / served / refused-for-containment, on the throughput line. */
+	tilesCut = 0;
+	tileHits = 0;
+	tileMisses = 0;
+	tileCutFailures = 0;
+	/**
+	* Native frame dimensions the retained tiles were cut from. A session's
+	* resolution does not change (a re-dial clears the store), so ONE pair is
+	* enough — and it has to be remembered because a tile outlives the frame that
+	* knew it.
+	*/
+	tileFrameWidth = 0;
+	tileFrameHeight = 0;
 	/**
 	* Demand gate for lease capture — armed at dial start + on every native-crop
 	* request; while cold, {@link captureNativeFrame} declines retention so the
@@ -1302,6 +1592,9 @@ var DecodeWorkerChild = class {
 			case "nativeCrop":
 				this.handleNativeCrop(message.requestId, message.frameId, message.bbox, message.maxWidth);
 				return;
+			case "cutTiles":
+				this.handleCutTiles(message.frameId, message.bboxes);
+				return;
 			case "releaseNativeLease":
 				this.leaseStore.release(message.frameId);
 				return;
@@ -1367,7 +1660,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}, 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.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}, holdOverflow:${this.leaseStore.overflowCount}, tilesCut:${this.tilesCut}, tileHits:${this.tileHits}, tileMisses:${this.tileMisses}, tileCutFailures:${this.tileCutFailures}, tileMb:${Math.round(this.tileStore.totalBytes / 1048576)}, tileFrames:${this.tileStore.frameCount}, rssMb:${rssMb}, ageS:${ageS}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 		if (!this.warnedLarge && rssMb >= WORKER_RSS_WARN_MB) {
@@ -1436,12 +1729,7 @@ var DecodeWorkerChild = class {
 		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++;
-			this.send({
-				kind: "nativeCropMiss",
-				requestId,
-				reason: `frame ${frameId} not retained (lease/ring evicted before crop)`
-			});
+			this.serveTileFallback(requestId, frameId, bbox, maxWidth);
 			return;
 		}
 		try {
@@ -1466,11 +1754,151 @@ var DecodeWorkerChild = class {
 			});
 		}
 	}
-	/** The GPU-ring or reserved-slot frame for `frameId` (lease-disabled / newest paths). */
+	/**
+	* Answer a native-crop request from the tile tier, or report the miss.
+	*
+	* Separate from {@link handleNativeCrop} because it is ASYNC (a JPEG decode)
+	* while the hold path is synchronous, and because the reason strings differ:
+	* `no tile contains the requested rectangle` and `no tiles retained` have
+	* different fixes, and a single "not retained" hid both.
+	*/
+	async serveTileFallback(requestId, frameId, bbox, maxWidth) {
+		try {
+			const served = await this.serveFromTile(frameId, bbox, maxWidth);
+			if (served) {
+				this.tileHits += 1;
+				this.nativeCropHits++;
+				this.send({
+					kind: "nativeCropResult",
+					requestId,
+					bytes: served.bytes,
+					width: served.width,
+					height: served.height
+				});
+				return;
+			}
+			this.tileMisses += 1;
+			this.nativeCropMisses++;
+			this.send({
+				kind: "nativeCropMiss",
+				requestId,
+				reason: this.tileStore.enabled ? `frame ${frameId} released and no retained subject tile contains the requested rectangle` : `frame ${frameId} released and subject tiles are DISABLED (tileBudgetMb 0)`
+			});
+		} catch (err) {
+			this.tileMisses += 1;
+			this.nativeCropMisses++;
+			const reason = errMessage(err);
+			this.emitStderr(`decode-worker-child: tile serve failed (frame ${frameId}) — ${reason}\n`);
+			this.send({
+				kind: "nativeCropMiss",
+				requestId,
+				reason: `tile serve failed — ${reason}`
+			});
+		}
+	}
+	/** The GPU-ring or reserved-slot frame for `frameId` (hold-disabled / newest paths). */
 	resolveRetainedFrame(frameId) {
 		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
 	}
 	/**
+	* The runner has this frame's detections. Cut one native TILE per subject and
+	* end the hold.
+	*
+	* This is the hinge of the two-tier design: it runs at the last instant the
+	* frame's native pixels exist, and what it leaves behind is a handful of
+	* subject-sized JPEGs instead of a ~24.9 MB raster. A frame on which nothing
+	* was detected leaves nothing at all, which is the asymmetry the old
+	* per-frame lease could not express.
+	*
+	* Three properties are load-bearing:
+	*  - the hold ENDS regardless of what happens here (`finally`), including on
+	*    an encode failure — a tile is a bonus, a pinned frame is a leak;
+	*  - the tile is a CONTAINER, padded wider than any model-input rectangle the
+	*    cluster convention can produce. The rectangle a model is fed is still
+	*    derived once, by the runner, and cut out of the tile in
+	*    {@link serveFromTile} ([D52](../../../../docs/decisions/adr-0052.md));
+	*  - every drop is counted. A silently-skipped tile is a crop miss with no
+	*    explanation, which is the failure this whole redesign exists to remove.
+	*/
+	async handleCutTiles(frameId, bboxes) {
+		try {
+			if (!this.tileStore.enabled || bboxes.length === 0) return;
+			const frame = this.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(frameId);
+			if (!frame) {
+				this.tileCutFailures += 1;
+				return;
+			}
+			this.tileFrameWidth = frame.width;
+			this.tileFrameHeight = frame.height;
+			const wanted = bboxes.slice(0, NATIVE_TILE_MAX_PER_FRAME);
+			if (bboxes.length > wanted.length) this.emitStderr(`decode-worker-child: tile cut capped at ${NATIVE_TILE_MAX_PER_FRAME} of ${bboxes.length} subjects on frame ${frameId} — the rest fall back to the ≤640 tier\n`);
+			const tiles = [];
+			for (const bbox of wanted) {
+				const { region } = resolveNativeTileRegion(frame.width, frame.height, bbox, NATIVE_TILE_PADDING_RATIO);
+				const resolved = {
+					region,
+					target: {
+						width: region.width,
+						height: region.height
+					}
+				};
+				try {
+					const raw = frame.isHwFrame() ? this.nativeHwCropToBuffer(frame, resolved) : this.nativeScaleCropToBuffer(frame, resolved);
+					const jpeg = await (await getSharp())(raw, { raw: {
+						width: region.width,
+						height: region.height,
+						channels: 3
+					} }).jpeg({ quality: NATIVE_TILE_JPEG_QUALITY }).toBuffer();
+					tiles.push({
+						region,
+						bytes: new Uint8Array(jpeg)
+					});
+				} catch (err) {
+					this.tileCutFailures += 1;
+					this.emitStderr(`decode-worker-child: subject tile cut FAILED on frame ${frameId} — ${errMessage(err)}\n`);
+				}
+			}
+			if (tiles.length > 0) {
+				this.tilesCut += tiles.length;
+				this.tileStore.put(frameId, tiles);
+			}
+		} finally {
+			this.leaseStore.release(frameId);
+		}
+	}
+	/**
+	* Serve a native crop from a retained subject TILE — the rung that covers the
+	* ordinary case, where the request arrives seconds after the frame is gone.
+	*
+	* The rectangle is the SAME one {@link resolveNativeCrop} would have cut from
+	* the full frame; only the raster it is taken from differs. A rectangle no
+	* tile CONTAINS is a miss (`null`) — never a clamp into the nearest tile,
+	* which would enrich a different part of the scene and error nowhere.
+	*/
+	async serveFromTile(frameId, bbox, maxWidth) {
+		const tiles = this.tileStore.get(frameId);
+		if (tiles.length === 0) return null;
+		const width = this.tileFrameWidth;
+		const height = this.tileFrameHeight;
+		if (width <= 0 || height <= 0) return null;
+		const { region, target } = resolveNativeCropGeometry(width, height, bbox, maxWidth);
+		const served = selectTileForRect(tiles, region);
+		if (!served) return null;
+		let pipeline = (await getSharp())(served.tile.bytes).extract({
+			left: served.local.left,
+			top: served.local.top,
+			width: served.local.width,
+			height: served.local.height
+		});
+		if (target.width !== served.local.width || target.height !== served.local.height) pipeline = pipeline.resize(target.width, target.height, { fit: "fill" });
+		const raw = await pipeline.removeAlpha().raw().toBuffer();
+		return {
+			bytes: new Uint8Array(raw),
+			width: target.width,
+			height: target.height
+		};
+	}
+	/**
 	* Resolve a decoded frame's `(colorSpace, colorRange)` tags to the EXPLICIT
 	* `(matrix, range)` every RGB conversion site pins — the RC-5 fix. `colorSpace`
 	* / `colorRange` are node-av branded `number` subtypes, so they pass to the
@@ -2124,6 +2552,9 @@ var DecodeWorkerChild = class {
 	closeInput() {
 		this.nativeRing.clear();
 		this.leaseStore.clear();
+		this.tileStore.clear();
+		this.tileFrameWidth = 0;
+		this.tileFrameHeight = 0;
 		this.nativeLeaseDownloadFilter?.close();
 		this.nativeLeaseDownloadFilter = null;
 		this.nativeLeaseDownloadFilterKey = "";