@camstack/addon-post-analysis 1.2.265 → 1.2.267

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-ZhDqWNZF.js");
+const require_dist = require("../dist-Cgy2NW9x.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -37075,6 +37075,7 @@ function growthAdjacentMatch(track, det, ctx) {
 	const trackArea = track.w * track.h;
 	const detArea = det.w * det.h;
 	if (trackArea <= 0 || detArea <= 0) return false;
+	if (ctx.frameArea > 0 && trackArea / ctx.frameArea > .01) return false;
 	const larger = Math.max(trackArea, detArea);
 	const smaller = Math.min(trackArea, detArea);
 	if (larger / smaller < 1.5) return false;
@@ -37228,6 +37229,17 @@ var SortTracker = class SortTracker {
 	* and a busy one span the same seconds (D438).
 	*/
 	frameSeq = 0;
+	/**
+	* The area of the frame this pass is running over, or `0` when the caller
+	* gave no frame context. Read by the growth clause's FRAGMENT test, which
+	* three call sites reach and only one of them could have been handed it.
+	*/
+	frameArea = 0;
+	/** The frame DIMS of the pass, for the same reason `frameArea` is held: the
+	*  salvage-bind record carries both boxes, and a box without the frame it was
+	*  measured in cannot be put back on a picture. `0` = no frame context. */
+	frameWidthPx = 0;
+	frameHeightPx = 0;
 	/** Sink for track deaths — see {@link setTrackLossObserver}. */
 	trackLossObserver = null;
 	trackLossSampler = new TrackLossSampler();
@@ -37345,7 +37357,7 @@ var SortTracker = class SortTracker {
 			if (!this.config.reacquireTimeScaled) return "plausible-birth-veto";
 			return this.isUnambiguousReach(track, det, detections) ? "already-claimed" : "crowd-guard";
 		}
-		if (growthAdjacentMatch(track.bbox, det.bbox, SortTracker.growthContext(track, timestamp))) return "already-claimed";
+		if (growthAdjacentMatch(track.bbox, det.bbox, this.growthContext(track, timestamp))) return "already-claimed";
 		return "geometry";
 	}
 	/** Emit one dropped-detection record, subject to the refusal sampler. */
@@ -37465,6 +37477,20 @@ var SortTracker = class SortTracker {
 			centroidDistPx: Math.hypot(tc.x - dc.x, tc.y - dc.y),
 			trackDiagPx: Math.hypot(track.bbox.w, track.bbox.h),
 			areaRatio: smaller > 0 ? Math.max(trackArea, detArea) / smaller : 0,
+			trackBbox: {
+				x: track.bbox.x,
+				y: track.bbox.y,
+				w: track.bbox.w,
+				h: track.bbox.h
+			},
+			detBbox: {
+				x: det.bbox.x,
+				y: det.bbox.y,
+				w: det.bbox.w,
+				h: det.bbox.h
+			},
+			frameWidth: this.frameWidthPx,
+			frameHeight: this.frameHeightPx,
 			dtMs: timestamp - track.lastSeen,
 			trackAgeMs: timestamp - track.firstSeen,
 			bindCount,
@@ -37472,10 +37498,11 @@ var SortTracker = class SortTracker {
 		});
 	}
 	/** When the pair is being judged, relative to `track`. */
-	static growthContext(track, timestamp) {
+	growthContext(track, timestamp) {
 		return {
 			trackAgeMs: timestamp - track.firstSeen,
-			gapMs: timestamp - track.lastSeen
+			gapMs: timestamp - track.lastSeen,
+			frameArea: this.frameArea
 		};
 	}
 	/** Whether two macro-classes may be collapsed as the SAME subject. Same class
@@ -37604,7 +37631,7 @@ var SortTracker = class SortTracker {
 				});
 				return true;
 			}
-			if (t.class === det.class && growthAdjacentMatch(t.bbox, det.bbox, SortTracker.growthContext(t, timestamp))) {
+			if (t.class === det.class && growthAdjacentMatch(t.bbox, det.bbox, this.growthContext(t, timestamp))) {
 				this.reportBind("spawn-dedup", "growth", t, det, timestamp);
 				return true;
 			}
@@ -37779,7 +37806,7 @@ var SortTracker = class SortTracker {
 		const tc = bboxCentroid(track.bbox);
 		const dc = bboxCentroid(det.bbox);
 		if (Math.hypot(tc.x - dc.x, tc.y - dc.y) <= this.reacquireReach(track, timestamp, timeScaled)) return "centroid";
-		if (growthAdjacentMatch(track.bbox, det.bbox, SortTracker.growthContext(track, timestamp))) return "growth";
+		if (growthAdjacentMatch(track.bbox, det.bbox, this.growthContext(track, timestamp))) return "growth";
 		return null;
 	}
 	/**
@@ -38007,6 +38034,9 @@ var SortTracker = class SortTracker {
 	update(detections, timestamp, frameContext) {
 		this.frameSeq++;
 		const frameArea = frameContext ? frameContext.frameWidth * frameContext.frameHeight : 0;
+		this.frameArea = frameArea;
+		this.frameWidthPx = frameContext?.frameWidth ?? 0;
+		this.frameHeightPx = frameContext?.frameHeight ?? 0;
 		const continuationOnly = frameContext?.continuationOnly ?? EMPTY_INDEX_SET;
 		const resurrectedScene = /* @__PURE__ */ new Map();
 		if (this.config.maxTrackLifetimeMs > 0) {
@@ -41251,6 +41281,17 @@ var TrackResidentState = class {
 	objectEmbeddingBestSelector = new TrackBestSelector(BEST_OBJECT_EMBED_POLICY);
 	/** keyFrame keys of CLOSED tracks still readable until the recognizer-end
 	*  deferred drop settles (see module docstring). */
+	/**
+	* How many LIVE tracks carry the operator's `debug` flag, across every camera
+	* this runner holds.
+	*
+	* A counter rather than a scan because the frame path asks it every frame:
+	* it is what lets the host skip maintaining a per-frame handle mirror
+	* entirely while nothing is marked, which is the state of the fleet
+	* essentially always. Kept in step in the three places a resident's flag can
+	* change: {@link setDebugMarked}, {@link close} and {@link clearAll}.
+	*/
+	debugMarkedCount = 0;
 	deferredKeyFrameKeys = /* @__PURE__ */ new Map();
 	constructor(hooks = {}) {
 		this.hooks = hooks;
@@ -41272,7 +41313,8 @@ var TrackResidentState = class {
 			thumbnailLanded: false,
 			keyFrameLanded: false,
 			keyFrameRetries: 0,
-			confirmed: false
+			confirmed: false,
+			debugMarked: false
 		};
 		this.residents.set(trackId, created);
 		return created;
@@ -41286,6 +41328,7 @@ var TrackResidentState = class {
 	*/
 	close(trackId, mode) {
 		const resident = this.residents.get(trackId);
+		if (resident?.debugMarked === true) this.debugMarkedCount -= 1;
 		this.residents.delete(trackId);
 		this.bestFrameTracker.delete(trackId);
 		this.objectEmbeddingBestSelector.delete(trackId);
@@ -41305,6 +41348,7 @@ var TrackResidentState = class {
 	}
 	/** Drop everything (addon dispose). */
 	clearAll() {
+		this.debugMarkedCount = 0;
 		this.residents.clear();
 		this.bestFrameTracker.clear();
 		this.objectEmbeddingBestSelector.clear();
@@ -41496,6 +41540,42 @@ var TrackResidentState = class {
 	markConfirmed(deviceId, trackId) {
 		this.ensure(deviceId, trackId).confirmed = true;
 	}
+	/**
+	* Is this track the one the operator is asking about?
+	*
+	* THE gate for every debug crop, and it must stay this cheap: one map lookup,
+	* no store read, no allocation. An unknown track is not marked — a lookup
+	* that finds nothing is the common case on every camera in the fleet.
+	*/
+	isDebugMarked(trackId) {
+		return this.residents.get(trackId)?.debugMarked ?? false;
+	}
+	/**
+	* Record the operator's `debug` flag for a LIVE track.
+	*
+	* Called from the `setTrackFlags` cap mutation, which is the only thing that
+	* can turn the flag on — so this runs once per press, not per frame.
+	* `ensure` rather than a lookup: the button can be pressed on a track whose
+	* first frame is still in flight, and a mark that silently missed would be
+	* the operator clicking and getting nothing, which is the whole complaint.
+	*/
+	setDebugMarked(deviceId, trackId, marked) {
+		const resident = this.ensure(deviceId, trackId);
+		if (resident.debugMarked === marked) return;
+		resident.debugMarked = marked;
+		this.debugMarkedCount += marked ? 1 : -1;
+	}
+	/**
+	* Does ANY live track on this runner carry the flag?
+	*
+	* The frame path's own gate, one level above {@link isDebugMarked}: it lets
+	* the host skip the per-frame bookkeeping a debug crop needs (the frame
+	* handle mirror the salvage-bind observer reads) while nothing is marked —
+	* which is the fleet's normal state. A counter read, no scan, no allocation.
+	*/
+	anyDebugMarked() {
+		return this.debugMarkedCount > 0;
+	}
 	/** Retain the FIRST detection-raster crop per track (zero-media fallback);
 	*  a later frame never overwrites an existing one. */
 	retainRasterFallback(deviceId, trackId, fallback) {
@@ -48756,6 +48836,298 @@ async function extractCropRaw(frameData, frameWidth, frameHeight, bbox) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/bbox-pad.ts
+/**
+* Pad a normalized bounding box by a fractional amount relative to its own
+* dimensions. All coordinates remain in the [0, 1] unit-square.
+*
+* Formula (before clamping):
+*   newX = x - padding * w
+*   newW = w + 2 * padding * w  (i.e. w * (1 + 2 * padding))
+*   newY = y - padding * h
+*   newH = h + 2 * padding * h
+*
+* padding === 0 is the identity operation. Pure, immutable — always returns a
+* new object.
+*
+* NOTE: clamping SHIFTS, it does not truncate — a window that overflows a
+* bound slides inward and keeps the extent that was asked for, on either side.
+* It shrinks only when the padded window is larger than the frame itself
+* would (e.g. a left-hugging box gains a bit more right-side context). This is
+* acceptable for detection crops (more context, never out of [0,1]); the
+* downstream `extractCrop` clamps to pixel bounds again regardless.
+*/
+function padBbox(bbox, padding) {
+	const rawX = bbox.x - padding * bbox.w;
+	const rawY = bbox.y - padding * bbox.h;
+	const rawW = bbox.w * (1 + 2 * padding);
+	const rawH = bbox.h * (1 + 2 * padding);
+	const w = Math.min(rawW, 1);
+	const h = Math.min(rawH, 1);
+	return {
+		x: Math.min(Math.max(0, rawX), 1 - w),
+		y: Math.min(Math.max(0, rawY), 1 - h),
+		w,
+		h
+	};
+}
+/**
+* Legibility floor: the window's SHORT side is grown until it is at least this
+* fraction of the frame's short side.
+*
+* The 2026-09-18 traces included a 24x18 px subject. At the context ratio alone
+* that is a 72x54 window — and 72x54 source pixels are 72x54 delivered pixels,
+* because nothing in this repo may upscale. Growing the RECTANGLE is the only
+* honest way to make the picture bigger: more real pixels arrive, the subject
+* occupies less of the frame, and its drawn box says which part of it is the
+* subject. 0.18 of 1080 = 194 px, which renders a 24 px subject recognisably in
+* its surroundings.
+*/
+var DEBUG_CROP_MIN_SIDE_FRAC = .18;
+function unionBox(a, b) {
+	const x = Math.min(a.x, b.x);
+	const y = Math.min(a.y, b.y);
+	const right = Math.max(a.x + a.w, b.x + b.w);
+	const bottom = Math.max(a.y + a.h, b.y + b.h);
+	return {
+		x,
+		y,
+		w: right - x,
+		h: bottom - y
+	};
+}
+/**
+* Which borders a box touches, on `edge-clear.ts`'s tolerance band — the SAME
+* band `isEdgeClear` uses, so "clipped" here and "not edge-clear" there can
+* never disagree about one frame.
+*/
+function debugCropClipSides(bbox, frameWidth, frameHeight) {
+	if (frameWidth <= 0 || frameHeight <= 0) return [];
+	const tolX = DEFAULT_EDGE_TOLERANCE * frameWidth;
+	const tolY = DEFAULT_EDGE_TOLERANCE * frameHeight;
+	const sides = [];
+	if (bbox.x <= tolX) sides.push("left");
+	if (bbox.y <= tolY) sides.push("top");
+	if (bbox.x + bbox.w >= frameWidth - tolX) sides.push("right");
+	if (bbox.y + bbox.h >= frameHeight - tolY) sides.push("bottom");
+	return sides;
+}
+/**
+* The ratio that makes `base` reach the legibility floor, or
+* {@link DEBUG_CROP_CONTEXT_RATIO} when it already does.
+*
+* Expressed as a PADDING RATIO rather than as a second rectangle so the window
+* still comes out of one {@link padBbox} call: there is exactly one place in
+* this file where a rectangle is grown, and it is not here.
+*/
+function contextRatioFor(base, frameWidth, frameHeight) {
+	const minSide = DEBUG_CROP_MIN_SIDE_FRAC * Math.min(frameWidth, frameHeight);
+	const ratioFor = (extent) => extent <= 0 ? 1 : (minSide / extent - 1) / 2;
+	const needed = Math.max(ratioFor(base.w), ratioFor(base.h));
+	return Math.max(1, needed);
+}
+/**
+* The one debug-crop rectangle. Pure.
+*
+* A refusal is a VALUE, not a `null`: the caller logs the reason, because a
+* branch that stores nothing and says nothing reads as "never happened".
+*/
+function planDebugCrop(input) {
+	const { frameWidth, frameHeight, subject } = input;
+	if (frameWidth <= 0 || frameHeight <= 0) return {
+		kind: "refused",
+		reason: "degenerate-frame"
+	};
+	if (subject.w <= 0 || subject.h <= 0) return {
+		kind: "refused",
+		reason: "degenerate-subject"
+	};
+	const base = input.rival === void 0 ? subject : unionBox(subject, input.rival);
+	const contextRatio = contextRatioFor(base, frameWidth, frameHeight);
+	const norm = padBbox({
+		x: base.x / frameWidth,
+		y: base.y / frameHeight,
+		w: base.w / frameWidth,
+		h: base.h / frameHeight
+	}, contextRatio);
+	const rect = {
+		x: norm.x * frameWidth,
+		y: norm.y * frameHeight,
+		w: norm.w * frameWidth,
+		h: norm.h * frameHeight
+	};
+	const relative = (role, box) => ({
+		role,
+		x: box.x - rect.x,
+		y: box.y - rect.y,
+		w: box.w,
+		h: box.h
+	});
+	const boxes = input.rival === void 0 ? [relative("subject", subject)] : [relative("subject", subject), relative("rival", input.rival)];
+	return {
+		kind: "plan",
+		decision: input.decision,
+		rect,
+		norm,
+		boxes,
+		contextRatio,
+		floorApplied: contextRatio > 1,
+		clippedSides: debugCropClipSides(subject, frameWidth, frameHeight),
+		subjectCenterNorm: {
+			x: (subject.x + subject.w / 2) / frameWidth,
+			y: (subject.y + subject.h / 2) / frameHeight
+		}
+	};
+}
+function formatRect(rect) {
+	return `${Math.round(rect.x)},${Math.round(rect.y)} ${Math.round(rect.w)}x${Math.round(rect.h)}`;
+}
+/**
+* The attribution bag: the deciding site's evidence FIRST, then the structural
+* facts — so no evidence key can rename the decision, the track or the
+* rectangle the crop belongs to. That ordering is the whole point: a crop whose
+* own label can be overwritten by a caller is back to being unattributable.
+*/
+function debugCropMeta(plan, attribution) {
+	return {
+		...attribution.evidence,
+		decision: attribution.decision,
+		trackId: attribution.trackId,
+		...attribution.rivalTrackId === void 0 ? {} : { rivalTrackId: attribution.rivalTrackId },
+		timestamp: attribution.timestamp,
+		cropRect: formatRect(plan.rect),
+		contextRatio: plan.contextRatio,
+		floorApplied: plan.floorApplied,
+		clippedSides: plan.clippedSides.join("|"),
+		subjectCenter: `${plan.subjectCenterNorm.x.toFixed(3)},${plan.subjectCenterNorm.y.toFixed(3)}`
+	};
+}
+/**
+* The caption burnt into the crop's own pixels.
+*
+* Burnt in, not stored beside it, because a debug crop travels: it is exported,
+* pasted into a note, and looked at months later next to five others. A blob
+* that cannot say what it is, on its own, is the thing that made the last
+* investigation slow — and this store has no column to say it in.
+*/
+function debugCropLabel(plan, attribution) {
+	return `${`${attribution.decision} ${attribution.trackId}`}${attribution.rivalTrackId === void 0 ? "" : ` vs ${attribution.rivalTrackId}`}${plan.clippedSides.length === 0 ? "" : ` clipped:${plan.clippedSides.join("+")}`} ${Object.entries(attribution.evidence).map(([k, v]) => `${k}=${typeof v === "number" ? Math.round(v * 1e3) / 1e3 : String(v)}`).join(" ")}`.trim().slice(0, 160);
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/debug-crop-capture.ts
+/** Stroke colour of the box the decision was ABOUT. */
+var SUBJECT_COLOR = "#00e5ff";
+/** Stroke colour of the box it was weighed AGAINST — a different colour,
+*  because "which one is which" is the first question a two-box crop raises. */
+var RIVAL_COLOR = "#ff9500";
+/** Encode quality: a debug crop is read by a person looking for a defect, so it
+*  is encoded above the timeline-tile default (80) — a JPEG artefact that reads
+*  as a mirror edge would waste the very investigation this exists for. */
+var DEBUG_CROP_QUALITY = 92;
+/** Bound the per-track counters so a long-lived process never leaks them. */
+var MAX_TRACKED_TRACKS = 2e3;
+function createDebugCropCapture(deps) {
+	const storedPerTrack = /* @__PURE__ */ new Map();
+	const cappedAnnounced = /* @__PURE__ */ new Set();
+	const skip = (input, reason, extra) => {
+		deps.logger.info("debug crop not stored", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				reason,
+				decision: input.decision,
+				trackId: input.trackId,
+				timestamp: input.timestamp,
+				...extra
+			}
+		});
+		return null;
+	};
+	return async (input) => {
+		if (!deps.isDebugMarked(input.trackId)) return null;
+		const already = storedPerTrack.get(input.trackId) ?? 0;
+		if (already >= 6) {
+			if (cappedAnnounced.has(input.trackId)) return null;
+			if (cappedAnnounced.size >= MAX_TRACKED_TRACKS) cappedAnnounced.clear();
+			cappedAnnounced.add(input.trackId);
+			return skip(input, "per-track-cap", {
+				stored: already,
+				cap: 6
+			});
+		}
+		const plan = planDebugCrop({
+			decision: input.decision,
+			subject: input.subject,
+			...input.rival === void 0 ? {} : { rival: input.rival },
+			frameWidth: input.frameWidth,
+			frameHeight: input.frameHeight
+		});
+		if (plan.kind === "refused") return skip(input, plan.reason, {});
+		const attribution = {
+			decision: input.decision,
+			trackId: input.trackId,
+			...input.rivalTrackId === void 0 ? {} : { rivalTrackId: input.rivalTrackId },
+			timestamp: input.timestamp,
+			evidence: input.evidence
+		};
+		const meta = debugCropMeta(plan, attribution);
+		const frame = await deps.fetchFrameRgb(input.frameHandle, input.deviceId, input.trackId);
+		if (frame === null || frame.width <= 0 || frame.height <= 0) return skip(input, "frame-unavailable", { nodeId: input.frameHandle.nodeId });
+		let jpeg;
+		try {
+			const cut = await deps.extractCropRaw(frame.bytes, frame.width, frame.height, plan.norm);
+			const scale = plan.rect.w > 0 ? cut.width / plan.rect.w : 1;
+			const boxes = plan.boxes.map((b) => {
+				const geometry = {
+					x: b.x * scale,
+					y: b.y * scale,
+					w: b.w * scale,
+					h: b.h * scale
+				};
+				return b.role === "subject" ? {
+					...geometry,
+					color: SUBJECT_COLOR,
+					label: debugCropLabel(plan, attribution)
+				} : {
+					...geometry,
+					color: RIVAL_COLOR,
+					label: "rival"
+				};
+			});
+			jpeg = await deps.drawBoxedFrame(cut.data, cut.width, cut.height, boxes, { quality: DEBUG_CROP_QUALITY });
+		} catch (err) {
+			return skip(input, "render-failed", { error: err instanceof Error ? err.message : String(err) });
+		}
+		try {
+			const mediaId = await deps.putDebugCrop({
+				deviceId: input.deviceId,
+				trackId: input.trackId,
+				timestamp: input.timestamp,
+				data: jpeg
+			});
+			if (storedPerTrack.size >= MAX_TRACKED_TRACKS) storedPerTrack.clear();
+			storedPerTrack.set(input.trackId, already + 1);
+			deps.logger.info("debug crop stored", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					...meta,
+					mediaId,
+					deviceId: input.deviceId
+				}
+			});
+			return mediaId;
+		} catch (err) {
+			deps.logger.warn("debug crop store failed", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					...meta,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			return null;
+		}
+	};
+}
+//#endregion
 //#region src/shared/frame/encode-crop.ts
 /**
 * JPEG-encode an already-cropped raw RGB (24-bit) buffer. Used for the
@@ -53547,42 +53919,6 @@ var AnalyticsFailureReport = class {
 	}
 };
 //#endregion
-//#region src/pipeline-analytics/pipeline/bbox-pad.ts
-/**
-* Pad a normalized bounding box by a fractional amount relative to its own
-* dimensions. All coordinates remain in the [0, 1] unit-square.
-*
-* Formula (before clamping):
-*   newX = x - padding * w
-*   newW = w + 2 * padding * w  (i.e. w * (1 + 2 * padding))
-*   newY = y - padding * h
-*   newH = h + 2 * padding * h
-*
-* padding === 0 is the identity operation. Pure, immutable — always returns a
-* new object.
-*
-* NOTE: clamping SHIFTS, it does not truncate — a window that overflows a
-* bound slides inward and keeps the extent that was asked for, on either side.
-* It shrinks only when the padded window is larger than the frame itself
-* would (e.g. a left-hugging box gains a bit more right-side context). This is
-* acceptable for detection crops (more context, never out of [0,1]); the
-* downstream `extractCrop` clamps to pixel bounds again regardless.
-*/
-function padBbox(bbox, padding) {
-	const rawX = bbox.x - padding * bbox.w;
-	const rawY = bbox.y - padding * bbox.h;
-	const rawW = bbox.w * (1 + 2 * padding);
-	const rawH = bbox.h * (1 + 2 * padding);
-	const w = Math.min(rawW, 1);
-	const h = Math.min(rawH, 1);
-	return {
-		x: Math.min(Math.max(0, rawX), 1 - w),
-		y: Math.min(Math.max(0, rawY), 1 - h),
-		w,
-		h
-	};
-}
-//#endregion
 //#region src/pipeline-analytics/pipeline/capture-crop.ts
 /**
 * The normalised window a capture asks the runner for: the box padded by
@@ -75975,6 +76311,19 @@ var customActions = {
 	...faceRescoreActions
 };
 /**
+* Width cap on the ONE full frame a debug crop is cut from.
+*
+* A debug crop is a picture for a person, and the plan has already widened the
+* window to a neighbourhood — past this width the extra pixels buy nothing and
+* a 4K native surface would cross the transport for every marked track.
+*/
+var DEBUG_CROP_FETCH_MAX_WIDTH = 1280;
+/** How long a queued debug-crop frame fetch is still worth executing. Past
+*  this the handle's frame has aged out of the runner's retention and the next
+*  decision will ask again with a young one, so the queued entry is dead
+*  weight in a lane real media is waiting in. */
+var DEBUG_CROP_FETCH_STALE_MS = 2e3;
+/**
 * Assist threshold when the caller does not pin one. Packages have their own
 * (0.35, on the zone crop only — `retrain/retrain-assist.ts`); everything else
 * starts here and the operator drops the ones they do not want.
@@ -77008,7 +77357,51 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	* `docs/decisions/` — the gate is a model input, so this is a deliberate
 	* exception to "model-input crops keep captureCrop".
 	*/
+	/**
+	* The operator-debug crop capture (`pipeline/debug-crop-capture.ts`).
+	*
+	* Null until the transport and the media store exist. Reached from three
+	* decision sites and gated INSIDE the capture on the track's `debug` flag, so
+	* a camera with no marked track pays one map lookup per decision — see the
+	* capture's module doc for why the gate lives there and not at each site.
+	*/
+	captureDebugCropFn = null;
 	captureDisplayCropFn = null;
+	/**
+	* Offer one decision's pixels to the operator-debug crop capture.
+	*
+	* Fire-and-forget and NEVER throws: this is the addon's own bookkeeping, and
+	* a frame path that can be slowed or broken by a diagnostic is worse than no
+	* diagnostic. The gate, the per-track cap and all six refusal reasons live in
+	* the capture (`pipeline/debug-crop-capture.ts`); this is only the seam.
+	*/
+	/**
+	* The CURRENT frame's handle and dims, per camera — the one thing the
+	* salvage-bind observer lacks.
+	*
+	* The tracker knows no `deviceId`, holds no handle and writes no media (that
+	* is the point of `pipeline/tracker/**`), so a growth bind reports its two
+	* boxes and stops. This mirror is what lets the host put those boxes back on
+	* a picture. Written ONLY while some track on this runner is marked
+	* (`residents.anyDebugMarked()`), so an ordinary fleet does not allocate one
+	* object per frame per camera for a diagnostic nobody asked for.
+	*/
+	debugFrameContext = /* @__PURE__ */ new Map();
+	offerDebugCrop(input) {
+		const capture = this.captureDebugCropFn;
+		if (capture === null) return;
+		capture(input).catch((err) => {
+			this.ctx.logger.debug("debug crop offer threw", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					deviceId: input.deviceId,
+					trackId: input.trackId,
+					decision: input.decision,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		});
+	}
 	captureCrop = null;
 	/** Full NATIVE frame by handle (downscaled worker-side to `maxWidth`), routed
 	*  to the owning runner, PLUS the source `tier`. Captured in the async init
@@ -77373,6 +77766,36 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			isNodeOffline: (nodeId) => this.nodeLiveness.isKnownOffline(nodeId, Date.now())
 		});
 		this.captureCrop = transport.captureCrop;
+		const fetchDebugFullFrame = transport.getNativeFullFrameRgb;
+		this.captureDebugCropFn = createDebugCropCapture({
+			isDebugMarked: (trackId) => this.residents.isDebugMarked(trackId),
+			fetchFrameRgb: async (handle, deviceId, trackId) => {
+				const frame = await this.captureScheduler.request({
+					deviceId,
+					trackId,
+					kind: "other",
+					coalesceKey: captureCoalesceKey(deviceId, "other", trackId),
+					staleAfterMs: DEBUG_CROP_FETCH_STALE_MS,
+					exec: () => fetchDebugFullFrame(handle, DEBUG_CROP_FETCH_MAX_WIDTH)
+				});
+				return frame === null || frame === void 0 ? null : {
+					bytes: frame.data,
+					width: frame.width,
+					height: frame.height
+				};
+			},
+			extractCropRaw: (data, w, h, box) => extractCropRaw(data, w, h, box),
+			drawBoxedFrame: (data, w, h, boxes, options) => drawBoxedFrame(data, w, h, boxes, options ?? {}),
+			putDebugCrop: (put) => stores.mediaStore.put({
+				deviceId: put.deviceId,
+				ownerKind: "track",
+				ownerId: put.trackId,
+				kind: "debugCrop",
+				timestamp: put.timestamp,
+				data: put.data
+			}),
+			logger: logger.child("DebugCrop")
+		});
 		this.eventMediaDispatcher = new EventMediaDispatcher({
 			getRemoteFrame: transport.getRemoteFrame,
 			getNativeCropJpeg: transport.getNativeCropJpeg,
@@ -80373,6 +80796,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			frameHeight: result.frameHeight
 		}, exhaustedIds);
 		const outcome = run.outcome;
+		if (frameHandle !== void 0 && this.residents.anyDebugMarked()) this.debugFrameContext.set(deviceId, {
+			handle: frameHandle,
+			width: result.frameWidth,
+			height: result.frameHeight,
+			timestamp: result.timestamp
+		});
 		const gateNowMs = Date.now();
 		for (const { id, t } of bornCandidates) {
 			if (outcome.undecided.has(id)) {
@@ -80431,6 +80860,32 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 							error: String(err)
 						} });
 					});
+					if (frameHandle !== void 0) {
+						const decision = run.decisions.get(id);
+						this.offerDebugCrop({
+							deviceId,
+							trackId: id,
+							decision: "birth-confirmation",
+							subject: {
+								x: t.bbox.x,
+								y: t.bbox.y,
+								w: t.bbox.w,
+								h: t.bbox.h
+							},
+							frameHandle,
+							frameWidth: result.frameWidth,
+							frameHeight: result.frameHeight,
+							timestamp: gateNowMs,
+							evidence: {
+								className: t.className,
+								source,
+								verdict: "suppression-held",
+								...decision?.cropSource !== void 0 ? { cropSource: decision.cropSource } : {},
+								...decision?.bestScore !== void 0 ? { bestScore: decision.bestScore } : {},
+								judgedCropKept: judged !== void 0
+							}
+						});
+					}
 					log.info("birth suppression held — the gate is not this root detector", {
 						tags: { deviceId },
 						meta: {
@@ -82459,6 +82914,32 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					meta: { ...bestShotPromotionMeta(promotionAttempt) }
 				});
 			}
+			if (frameHandle !== void 0) {
+				const heldBbox = this.residents.bestSeenBbox(t.trackId);
+				const rival = heldBbox !== void 0 && heldBbox.frameWidth === frameWidth && heldBbox.frameHeight === frameHeight ? {
+					x: heldBbox.x,
+					y: heldBbox.y,
+					w: heldBbox.w,
+					h: heldBbox.h
+				} : void 0;
+				this.offerDebugCrop({
+					deviceId,
+					trackId: t.trackId,
+					decision: "best-shot",
+					subject: {
+						x: t.bbox.x,
+						y: t.bbox.y,
+						w: t.bbox.w,
+						h: t.bbox.h
+					},
+					...rival !== void 0 ? { rival } : {},
+					frameHandle,
+					frameWidth,
+					frameHeight,
+					timestamp,
+					evidence: { ...bestShotPromotionMeta(promotionAttempt) }
+				});
+			}
 			if (!plan.appendSnapshot && !rollingLastFrame && !bestThumbnail && keyFrame === "skip") continue;
 			targets.push({
 				trackId: t.trackId,
@@ -83812,6 +84293,33 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 						...record
 					}
 				});
+				if (record.gate !== "growth") return;
+				const frame = this.debugFrameContext.get(deviceId);
+				if (frame === void 0 || frame.width !== record.frameWidth) return;
+				this.offerDebugCrop({
+					deviceId,
+					trackId: record.trackId,
+					decision: "growth-rescue",
+					subject: record.trackBbox,
+					rival: record.detBbox,
+					frameHandle: frame.handle,
+					frameWidth: record.frameWidth,
+					frameHeight: record.frameHeight,
+					timestamp: frame.timestamp,
+					evidence: {
+						stage: record.stage,
+						trackClass: record.trackClass,
+						detClass: record.detClass,
+						detScore: record.detScore,
+						iou: record.iou,
+						centroidDistPx: record.centroidDistPx,
+						trackDiagPx: record.trackDiagPx,
+						areaRatio: record.areaRatio,
+						dtMs: record.dtMs,
+						trackAgeMs: record.trackAgeMs,
+						source
+					}
+				});
 			});
 			p.setSpawnRefusalObserver((record) => {
 				this.ctx.logger.info("tracker: detection dropped — nothing downstream received it", {
@@ -85958,6 +86466,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			logger: this.ctx.logger,
 			...this.debugNoteArchive !== null ? { noteArchive: this.debugNoteArchive } : {}
 		}, input);
+		this.residents.setDebugMarked(input.deviceId, input.trackId, out.debug);
 		this.ctx.logger.info("track operator flags set", {
 			tags: { deviceId: input.deviceId },
 			meta: {