@camstack/addon-pipeline 1.1.52 → 1.1.54

package/dist/audio-analyzer/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-B-pQhc30.js");
+const require_dist = require("../dist-BbaoC680.js");
 const require_node_topology_platform = require("../node-topology-platform-CFZ7F4xW.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let node_fs = require("node:fs");

package/dist/audio-analyzer/index.mjs

@@ -1,5 +1,5 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { C as mapAudioLabelToMacro, I as errMsg, L as BaseAddon, U as hydrateSchema, h as audioAnalyzerCapability, l as HF_BASE_URL, m as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, o as DEFAULT_AUDIO_ANALYZER_CONFIG } from "../dist-DM6-eQRs.mjs";
+import { C as mapAudioLabelToMacro, I as errMsg, L as BaseAddon, U as hydrateSchema, h as audioAnalyzerCapability, l as HF_BASE_URL, m as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, o as DEFAULT_AUDIO_ANALYZER_CONFIG } from "../dist-CEcTeu1h.mjs";
 import { t as pickNodePlatformArch } from "../node-topology-platform-BkR_k6WT.mjs";
 import { r as downloadFile } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import * as fs from "node:fs";

package/dist/detection-pipeline/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-B-pQhc30.js");
+const require_dist = require("../dist-BbaoC680.js");
 const require_node_topology_platform = require("../node-topology-platform-CFZ7F4xW.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
@@ -1543,11 +1543,16 @@ var STEP_CLIP_EMBEDDING = new PipelineStepBase({
 	slot: "classifier",
 	postprocessor: "clip",
 	extractMode: "crop-roi",
-	inputClasses: null,
+	inputClasses: [
+		"person",
+		"vehicle",
+		"animal"
+	],
 	outputClasses: ["embedding"],
 	models: [...CLIP_EMBEDDING_MODELS],
 	defaultModelId: "mobileclip-s1",
 	enabledByDefault: true,
+	backfillIntoExistingOverrides: true,
 	defaultConfidence: 0,
 	defaultMinParentScore: .4,
 	group: "CLIP"
@@ -3718,6 +3723,93 @@ function bboxShortSide(bbox) {
 	return Math.min(bbox[2] - bbox[0], bbox[3] - bbox[1]);
 }
 /**
+* Padded region (clamped to the frame) around a face bbox — the area a native
+* crop must cover so the warp has room around a tilted / edge face. Mirrors the
+* padding {@link alignFaceCrop} applies internally (`padRatio` default 0.4), so
+* the native and fallback paths sample the same neighbourhood.
+*/
+function paddedFaceRegion(faceBbox, imageWidth, imageHeight, padRatio = .4) {
+	const bw = faceBbox[2] - faceBbox[0];
+	const bh = faceBbox[3] - faceBbox[1];
+	const padX = bw * padRatio;
+	const padY = bh * padRatio;
+	return {
+		left: Math.max(0, Math.floor(faceBbox[0] - padX)),
+		top: Math.max(0, Math.floor(faceBbox[1] - padY)),
+		right: Math.min(imageWidth, Math.ceil(faceBbox[2] + padX)),
+		bottom: Math.min(imageHeight, Math.ceil(faceBbox[3] + padY))
+	};
+}
+/**
+* Warp a raw RGB crop of `region` (native-resolution pixels of exactly that
+* detection-space region) so `landmarksImageSpace` land on the ArcFace
+* template. Landmarks are mapped from image space into the crop's local pixel
+* space by the per-axis region→crop scale (handles `maxWidth` downscale of the
+* native crop). Channels default to RGB (3) — the format the decode worker's
+* native surface produces.
+*/
+async function alignFaceCropFromRgb(rgb, region, landmarksImageSpace, opts = {}) {
+	const outSize = opts.outSize ?? 112;
+	const quality = opts.quality ?? 95;
+	const channels = opts.channels ?? 3;
+	const regionW = region.right - region.left;
+	const regionH = region.bottom - region.top;
+	if (regionW < 1 || regionH < 1) throw new Error(`alignFaceCropFromRgb: degenerate region ${regionW}x${regionH}`);
+	if (rgb.width < 2 || rgb.height < 2) throw new Error(`alignFaceCropFromRgb: degenerate crop ${rgb.width}x${rgb.height}`);
+	const scaleX = rgb.width / regionW;
+	const scaleY = rgb.height / regionH;
+	const localLandmarks = landmarksImageSpace.map((l) => ({
+		x: (l.x - region.left) * scaleX,
+		y: (l.y - region.top) * scaleY
+	}));
+	const aligned = warpToTemplate({
+		data: rgb.bytes,
+		width: rgb.width,
+		height: rgb.height,
+		channels
+	}, localLandmarks, opts.template ?? ARCFACE_TEMPLATE_112, outSize);
+	return {
+		jpeg: await (0, sharp.default)(Buffer.from(aligned.data), { raw: {
+			width: aligned.width,
+			height: aligned.height,
+			channels: aligned.channels
+		} }).jpeg({ quality }).toBuffer(),
+		width: aligned.width,
+		height: aligned.height
+	};
+}
+/**
+* Produce a landmark-aligned face crop, preferring a NATIVE-resolution crop
+* (design B — the quality win) and FALLING BACK to today's downscaled
+* full-frame alignment on any native miss/error (never worse than before).
+*
+* The native path requests the padded face region from `nativeCropProvider`
+* (a best-effort local cap round-trip bound to this frame), warps the native
+* pixels; the fallback path re-uses {@link alignFaceCrop} on the downscaled
+* JPEG. ArcFace input is a fixed `outSize`×`outSize` either way — only the crop
+* SOURCE changes, so model cost is unchanged.
+*/
+async function buildAlignedFaceCrop(args) {
+	if (args.nativeCropProvider) try {
+		const region = paddedFaceRegion(args.faceBbox, args.imageWidth, args.imageHeight);
+		const roi = {
+			x: region.left / args.imageWidth,
+			y: region.top / args.imageHeight,
+			w: (region.right - region.left) / args.imageWidth,
+			h: (region.bottom - region.top) / args.imageHeight
+		};
+		const native = await args.nativeCropProvider(roi, args.nativeMaxWidth);
+		if (native && native.width >= 2 && native.height >= 2 && native.bytes.length >= native.width * native.height * 3) return {
+			...await alignFaceCropFromRgb(native, region, args.landmarksImageSpace, { outSize: args.outSize }),
+			source: "native"
+		};
+	} catch {}
+	return {
+		...await alignFaceCrop(args.fullFrameJpeg, args.faceBbox, args.landmarksImageSpace, args.imageWidth, args.imageHeight, { outSize: args.outSize }),
+		source: "fallback"
+	};
+}
+/**
 * Produce an aligned 112x112 JPEG of a face from the full-frame JPEG and the
 * face's 5 landmarks (in absolute image-space coordinates). Decodes a padded
 * region around the face bbox to raw RGB, warps to the ArcFace template, and
@@ -4132,15 +4224,42 @@ function formatTopResult(output) {
 /**
 * Default minimum short-side (px, source-frame resolution) of a face bbox for
 * which a recognition embedding is attempted. Faces smaller than this upscale
-* into garbage embeddings; we skip them rather than pollute clustering. Override
+* into weaker embeddings; we skip them rather than pollute clustering. Override
 * per-step via `settings.minFaceSize`.
+*
+* Lowered 40 → 28 (2026-07-14): detection runs on a downscaled frame (e.g.
+* 640×360), so an indoor person's face is often 28-38px there and was being
+* skipped entirely — no faces collected. 28px still warps acceptably onto the
+* 112×112 ArcFace input; the honest below-threshold count is surfaced by the
+* throttled "too small to embed" diagnostic (with the actual `faceShortSidePx`).
+* The quality-preserving alternative is to run face-detection at a higher input
+* resolution — a deeper change tracked separately.
 */
-var DEFAULT_MIN_FACE_SIZE_PX = 40;
+var DEFAULT_MIN_FACE_SIZE_PX = 28;
+/**
+* Cap (px) on the width of the NATIVE face crop fetched for embedding (design
+* B). The arcface input is a fixed 112² warp, so a wider native crop buys no
+* embedding quality past a modest margin but does inflate the per-face transport
+* of the best-effort native-crop round-trip. 320px keeps a distant face well
+* above the downscaled detection resolution while bounding the crop payload.
+*/
+var NATIVE_FACE_CROP_MAX_WIDTH = 320;
 var PipelineExecutor = class {
 	opts;
 	constructor(opts) {
 		this.opts = opts;
 	}
+	/** Per-key last-warn timestamps, so a persistently-failing/skipping child
+	*  step surfaces a diagnostic without spamming the log every frame. */
+	warnThrottleAt = /* @__PURE__ */ new Map();
+	throttledWarn(key, everyMs, message, meta) {
+		const logger = this.opts.logger;
+		if (!logger) return;
+		const now = Date.now();
+		if (now - (this.warnThrottleAt.get(key) ?? 0) < everyMs) return;
+		this.warnThrottleAt.set(key, now);
+		logger.warn(message, { meta });
+	}
 	/**
 	* Execute the full pipeline tree against a frame.
 	*
@@ -4154,7 +4273,7 @@ var PipelineExecutor = class {
 	*
 	* @returns FrameResult + optional trace
 	*/
-	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts) {
+	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeFaceCropProvider) {
 		const startMs = Date.now();
 		const verbosity = runOpts?.traceVerbosity ?? "off";
 		const traceBuilder = new ExecutionTraceBuilder(verbosity, deviceId, imageWidth, imageHeight, this.opts.engineRuntime);
@@ -4192,7 +4311,7 @@ var PipelineExecutor = class {
 					continue;
 				}
 				try {
-					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 				} catch (err) {
 					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 						tags: { deviceId },
@@ -4294,7 +4413,7 @@ var PipelineExecutor = class {
 		});
 		return output;
 	}
-	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg) {
+	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider) {
 		for (const child of children) {
 			if (!this.matchesInputClasses(parentDetection.macroClass, child.inputClasses)) continue;
 			const minParentScore = child.settings?.minParentScore ?? child.definition?.defaultMinParentScore;
@@ -4309,10 +4428,30 @@ var PipelineExecutor = class {
 				let cropH;
 				if (modelEntry?.faceAlignment) {
 					const minFaceSize = typeof child.settings?.["minFaceSize"] === "number" ? child.settings["minFaceSize"] : DEFAULT_MIN_FACE_SIZE_PX;
-					if (bboxShortSide(parentDetection.bbox) < minFaceSize) continue;
+					const faceShortSide = bboxShortSide(parentDetection.bbox);
+					if (faceShortSide < minFaceSize) {
+						this.throttledWarn(`face-small:${child.stepId}`, 3e4, "face detected but too small to embed — skipping", {
+							step: child.stepId,
+							model: child.modelId,
+							faceShortSidePx: Math.round(faceShortSide),
+							minFaceSizePx: minFaceSize
+						});
+						continue;
+					}
 					const lms = parentDetection.landmarks;
 					if (lms && lms.length >= 5) {
-						const aligned = await alignFaceCrop(fullFrameJpeg, parentDetection.bbox, lms, imageWidth, imageHeight, { outSize: modelEntry.inputSize.width });
+						const aligned = await buildAlignedFaceCrop({
+							fullFrameJpeg,
+							faceBbox: parentDetection.bbox,
+							landmarksImageSpace: lms,
+							imageWidth,
+							imageHeight,
+							outSize: modelEntry.inputSize.width,
+							...nativeFaceCropProvider ? {
+								nativeCropProvider: nativeFaceCropProvider,
+								nativeMaxWidth: NATIVE_FACE_CROP_MAX_WIDTH
+							} : {}
+						});
 						cropJpegBuf = aligned.jpeg;
 						cropW = aligned.width;
 						cropH = aligned.height;
@@ -4346,10 +4485,16 @@ var PipelineExecutor = class {
 								y: l.y + py1
 							}));
 						}
-						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 					}
 				}
-			} catch {}
+			} catch (err) {
+				this.throttledWarn(`child-fail:${child.stepId}`, 15e3, "pipeline child step failed", {
+					step: child.stepId,
+					model: child.modelId,
+					error: require_dist.errMsg(err)
+				});
+			}
 		}
 	}
 	matchesInputClasses(className, inputClasses) {
@@ -5832,6 +5977,38 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			debug: { totalInferenceMs: 0 }
 		};
 	}
+	/**
+	* Build the design-B native-face-crop provider for a runtime frame. Present
+	* ONLY when the frame arrived as a retention `frameHandle` (the key the owning
+	* pipeline-runner registered the frame's native surface under) and the sibling
+	* `pipeline-runner` cap is reachable via `ctx.api`. Each call is a best-effort
+	* round-trip pinned to the frame's OWNING node (`nodePin(handle.nodeId)` — the
+	* node that decoded it, i.e. THIS node for a local frame, never a cross-node
+	* hop) that returns the native ROI or `null` on a miss; the executor then
+	* falls back to the downscaled crop, so behaviour is never worse than before.
+	*/
+	buildNativeFaceCropProvider(handle) {
+		if (!handle) return void 0;
+		const api = this.addonCtx?.api;
+		if (!api) return void 0;
+		return async (roi, maxWidth) => {
+			try {
+				const native = await api.pipelineRunner.getNativeCrop.query({
+					handle,
+					bbox: roi,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, require_dist.nodePin(handle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return {
+					bytes: native.bytes,
+					width: native.width,
+					height: native.height
+				};
+			} catch {
+				return null;
+			}
+		};
+	}
 	async runPipeline(input, onProgress) {
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
@@ -6088,7 +6265,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const effectiveDeviceId = input.deviceId ?? 0;
 			const deviceOverrides = effectiveDeviceId > 0 ? await this.readDeviceStore(effectiveDeviceId) : {};
 			const effectiveTree = Object.keys(deviceOverrides).length > 0 ? applyDeviceOverridesToTree(tree, "object-detection", deviceOverrides) : tree;
-			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" });
+			const nativeFaceCropProvider = this.buildNativeFaceCropProvider(input.frameHandle);
+			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" }, nativeFaceCropProvider);
 			if (isRuntime) {
 				if (trace && this.eventBus) this.eventBus.emit(require_dist.createEvent(require_dist.EventCategory.PipelineTrace, {
 					type: "device",
@@ -7173,6 +7351,7 @@ function buildSchemaSlots(format, modelsDir, customByStep) {
 			defaultModelId: step.defaultModelId,
 			...step.defaultModelIdByFormat ? { defaultModelIdByFormat: { ...step.defaultModelIdByFormat } } : {},
 			...step.enabledByDefault !== void 0 ? { enabledByDefault: step.enabledByDefault } : {},
+			...step.backfillIntoExistingOverrides !== void 0 ? { backfillIntoExistingOverrides: step.backfillIntoExistingOverrides } : {},
 			defaultConfidence: step.defaultConfidence,
 			...step.group ? { group: step.group } : {},
 			...configSchema.length > 0 ? { configSchema: [...configSchema] } : {}

package/dist/detection-pipeline/index.mjs

@@ -1,5 +1,5 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { H as createEvent, I as errMsg, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, X as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, q as parseJsonUnknown, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-DM6-eQRs.mjs";
+import { D as nodePin, H as createEvent, I as errMsg, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, X as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, q as parseJsonUnknown, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-CEcTeu1h.mjs";
 import { t as pickNodePlatformArch } from "../node-topology-platform-BkR_k6WT.mjs";
 import { a as isModelDownloaded, i as ensureModel, n as deleteModelFromDisk } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
@@ -1535,11 +1535,16 @@ var STEP_CLIP_EMBEDDING = new PipelineStepBase({
 	slot: "classifier",
 	postprocessor: "clip",
 	extractMode: "crop-roi",
-	inputClasses: null,
+	inputClasses: [
+		"person",
+		"vehicle",
+		"animal"
+	],
 	outputClasses: ["embedding"],
 	models: [...CLIP_EMBEDDING_MODELS],
 	defaultModelId: "mobileclip-s1",
 	enabledByDefault: true,
+	backfillIntoExistingOverrides: true,
 	defaultConfidence: 0,
 	defaultMinParentScore: .4,
 	group: "CLIP"
@@ -3710,6 +3715,93 @@ function bboxShortSide(bbox) {
 	return Math.min(bbox[2] - bbox[0], bbox[3] - bbox[1]);
 }
 /**
+* Padded region (clamped to the frame) around a face bbox — the area a native
+* crop must cover so the warp has room around a tilted / edge face. Mirrors the
+* padding {@link alignFaceCrop} applies internally (`padRatio` default 0.4), so
+* the native and fallback paths sample the same neighbourhood.
+*/
+function paddedFaceRegion(faceBbox, imageWidth, imageHeight, padRatio = .4) {
+	const bw = faceBbox[2] - faceBbox[0];
+	const bh = faceBbox[3] - faceBbox[1];
+	const padX = bw * padRatio;
+	const padY = bh * padRatio;
+	return {
+		left: Math.max(0, Math.floor(faceBbox[0] - padX)),
+		top: Math.max(0, Math.floor(faceBbox[1] - padY)),
+		right: Math.min(imageWidth, Math.ceil(faceBbox[2] + padX)),
+		bottom: Math.min(imageHeight, Math.ceil(faceBbox[3] + padY))
+	};
+}
+/**
+* Warp a raw RGB crop of `region` (native-resolution pixels of exactly that
+* detection-space region) so `landmarksImageSpace` land on the ArcFace
+* template. Landmarks are mapped from image space into the crop's local pixel
+* space by the per-axis region→crop scale (handles `maxWidth` downscale of the
+* native crop). Channels default to RGB (3) — the format the decode worker's
+* native surface produces.
+*/
+async function alignFaceCropFromRgb(rgb, region, landmarksImageSpace, opts = {}) {
+	const outSize = opts.outSize ?? 112;
+	const quality = opts.quality ?? 95;
+	const channels = opts.channels ?? 3;
+	const regionW = region.right - region.left;
+	const regionH = region.bottom - region.top;
+	if (regionW < 1 || regionH < 1) throw new Error(`alignFaceCropFromRgb: degenerate region ${regionW}x${regionH}`);
+	if (rgb.width < 2 || rgb.height < 2) throw new Error(`alignFaceCropFromRgb: degenerate crop ${rgb.width}x${rgb.height}`);
+	const scaleX = rgb.width / regionW;
+	const scaleY = rgb.height / regionH;
+	const localLandmarks = landmarksImageSpace.map((l) => ({
+		x: (l.x - region.left) * scaleX,
+		y: (l.y - region.top) * scaleY
+	}));
+	const aligned = warpToTemplate({
+		data: rgb.bytes,
+		width: rgb.width,
+		height: rgb.height,
+		channels
+	}, localLandmarks, opts.template ?? ARCFACE_TEMPLATE_112, outSize);
+	return {
+		jpeg: await sharp(Buffer.from(aligned.data), { raw: {
+			width: aligned.width,
+			height: aligned.height,
+			channels: aligned.channels
+		} }).jpeg({ quality }).toBuffer(),
+		width: aligned.width,
+		height: aligned.height
+	};
+}
+/**
+* Produce a landmark-aligned face crop, preferring a NATIVE-resolution crop
+* (design B — the quality win) and FALLING BACK to today's downscaled
+* full-frame alignment on any native miss/error (never worse than before).
+*
+* The native path requests the padded face region from `nativeCropProvider`
+* (a best-effort local cap round-trip bound to this frame), warps the native
+* pixels; the fallback path re-uses {@link alignFaceCrop} on the downscaled
+* JPEG. ArcFace input is a fixed `outSize`×`outSize` either way — only the crop
+* SOURCE changes, so model cost is unchanged.
+*/
+async function buildAlignedFaceCrop(args) {
+	if (args.nativeCropProvider) try {
+		const region = paddedFaceRegion(args.faceBbox, args.imageWidth, args.imageHeight);
+		const roi = {
+			x: region.left / args.imageWidth,
+			y: region.top / args.imageHeight,
+			w: (region.right - region.left) / args.imageWidth,
+			h: (region.bottom - region.top) / args.imageHeight
+		};
+		const native = await args.nativeCropProvider(roi, args.nativeMaxWidth);
+		if (native && native.width >= 2 && native.height >= 2 && native.bytes.length >= native.width * native.height * 3) return {
+			...await alignFaceCropFromRgb(native, region, args.landmarksImageSpace, { outSize: args.outSize }),
+			source: "native"
+		};
+	} catch {}
+	return {
+		...await alignFaceCrop(args.fullFrameJpeg, args.faceBbox, args.landmarksImageSpace, args.imageWidth, args.imageHeight, { outSize: args.outSize }),
+		source: "fallback"
+	};
+}
+/**
 * Produce an aligned 112x112 JPEG of a face from the full-frame JPEG and the
 * face's 5 landmarks (in absolute image-space coordinates). Decodes a padded
 * region around the face bbox to raw RGB, warps to the ArcFace template, and
@@ -4124,15 +4216,42 @@ function formatTopResult(output) {
 /**
 * Default minimum short-side (px, source-frame resolution) of a face bbox for
 * which a recognition embedding is attempted. Faces smaller than this upscale
-* into garbage embeddings; we skip them rather than pollute clustering. Override
+* into weaker embeddings; we skip them rather than pollute clustering. Override
 * per-step via `settings.minFaceSize`.
+*
+* Lowered 40 → 28 (2026-07-14): detection runs on a downscaled frame (e.g.
+* 640×360), so an indoor person's face is often 28-38px there and was being
+* skipped entirely — no faces collected. 28px still warps acceptably onto the
+* 112×112 ArcFace input; the honest below-threshold count is surfaced by the
+* throttled "too small to embed" diagnostic (with the actual `faceShortSidePx`).
+* The quality-preserving alternative is to run face-detection at a higher input
+* resolution — a deeper change tracked separately.
 */
-var DEFAULT_MIN_FACE_SIZE_PX = 40;
+var DEFAULT_MIN_FACE_SIZE_PX = 28;
+/**
+* Cap (px) on the width of the NATIVE face crop fetched for embedding (design
+* B). The arcface input is a fixed 112² warp, so a wider native crop buys no
+* embedding quality past a modest margin but does inflate the per-face transport
+* of the best-effort native-crop round-trip. 320px keeps a distant face well
+* above the downscaled detection resolution while bounding the crop payload.
+*/
+var NATIVE_FACE_CROP_MAX_WIDTH = 320;
 var PipelineExecutor = class {
 	opts;
 	constructor(opts) {
 		this.opts = opts;
 	}
+	/** Per-key last-warn timestamps, so a persistently-failing/skipping child
+	*  step surfaces a diagnostic without spamming the log every frame. */
+	warnThrottleAt = /* @__PURE__ */ new Map();
+	throttledWarn(key, everyMs, message, meta) {
+		const logger = this.opts.logger;
+		if (!logger) return;
+		const now = Date.now();
+		if (now - (this.warnThrottleAt.get(key) ?? 0) < everyMs) return;
+		this.warnThrottleAt.set(key, now);
+		logger.warn(message, { meta });
+	}
 	/**
 	* Execute the full pipeline tree against a frame.
 	*
@@ -4146,7 +4265,7 @@ var PipelineExecutor = class {
 	*
 	* @returns FrameResult + optional trace
 	*/
-	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts) {
+	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeFaceCropProvider) {
 		const startMs = Date.now();
 		const verbosity = runOpts?.traceVerbosity ?? "off";
 		const traceBuilder = new ExecutionTraceBuilder(verbosity, deviceId, imageWidth, imageHeight, this.opts.engineRuntime);
@@ -4184,7 +4303,7 @@ var PipelineExecutor = class {
 					continue;
 				}
 				try {
-					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 				} catch (err) {
 					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 						tags: { deviceId },
@@ -4286,7 +4405,7 @@ var PipelineExecutor = class {
 		});
 		return output;
 	}
-	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg) {
+	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider) {
 		for (const child of children) {
 			if (!this.matchesInputClasses(parentDetection.macroClass, child.inputClasses)) continue;
 			const minParentScore = child.settings?.minParentScore ?? child.definition?.defaultMinParentScore;
@@ -4301,10 +4420,30 @@ var PipelineExecutor = class {
 				let cropH;
 				if (modelEntry?.faceAlignment) {
 					const minFaceSize = typeof child.settings?.["minFaceSize"] === "number" ? child.settings["minFaceSize"] : DEFAULT_MIN_FACE_SIZE_PX;
-					if (bboxShortSide(parentDetection.bbox) < minFaceSize) continue;
+					const faceShortSide = bboxShortSide(parentDetection.bbox);
+					if (faceShortSide < minFaceSize) {
+						this.throttledWarn(`face-small:${child.stepId}`, 3e4, "face detected but too small to embed — skipping", {
+							step: child.stepId,
+							model: child.modelId,
+							faceShortSidePx: Math.round(faceShortSide),
+							minFaceSizePx: minFaceSize
+						});
+						continue;
+					}
 					const lms = parentDetection.landmarks;
 					if (lms && lms.length >= 5) {
-						const aligned = await alignFaceCrop(fullFrameJpeg, parentDetection.bbox, lms, imageWidth, imageHeight, { outSize: modelEntry.inputSize.width });
+						const aligned = await buildAlignedFaceCrop({
+							fullFrameJpeg,
+							faceBbox: parentDetection.bbox,
+							landmarksImageSpace: lms,
+							imageWidth,
+							imageHeight,
+							outSize: modelEntry.inputSize.width,
+							...nativeFaceCropProvider ? {
+								nativeCropProvider: nativeFaceCropProvider,
+								nativeMaxWidth: NATIVE_FACE_CROP_MAX_WIDTH
+							} : {}
+						});
 						cropJpegBuf = aligned.jpeg;
 						cropW = aligned.width;
 						cropH = aligned.height;
@@ -4338,10 +4477,16 @@ var PipelineExecutor = class {
 								y: l.y + py1
 							}));
 						}
-						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 					}
 				}
-			} catch {}
+			} catch (err) {
+				this.throttledWarn(`child-fail:${child.stepId}`, 15e3, "pipeline child step failed", {
+					step: child.stepId,
+					model: child.modelId,
+					error: errMsg(err)
+				});
+			}
 		}
 	}
 	matchesInputClasses(className, inputClasses) {
@@ -5824,6 +5969,38 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			debug: { totalInferenceMs: 0 }
 		};
 	}
+	/**
+	* Build the design-B native-face-crop provider for a runtime frame. Present
+	* ONLY when the frame arrived as a retention `frameHandle` (the key the owning
+	* pipeline-runner registered the frame's native surface under) and the sibling
+	* `pipeline-runner` cap is reachable via `ctx.api`. Each call is a best-effort
+	* round-trip pinned to the frame's OWNING node (`nodePin(handle.nodeId)` — the
+	* node that decoded it, i.e. THIS node for a local frame, never a cross-node
+	* hop) that returns the native ROI or `null` on a miss; the executor then
+	* falls back to the downscaled crop, so behaviour is never worse than before.
+	*/
+	buildNativeFaceCropProvider(handle) {
+		if (!handle) return void 0;
+		const api = this.addonCtx?.api;
+		if (!api) return void 0;
+		return async (roi, maxWidth) => {
+			try {
+				const native = await api.pipelineRunner.getNativeCrop.query({
+					handle,
+					bbox: roi,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, nodePin(handle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return {
+					bytes: native.bytes,
+					width: native.width,
+					height: native.height
+				};
+			} catch {
+				return null;
+			}
+		};
+	}
 	async runPipeline(input, onProgress) {
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
@@ -6080,7 +6257,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const effectiveDeviceId = input.deviceId ?? 0;
 			const deviceOverrides = effectiveDeviceId > 0 ? await this.readDeviceStore(effectiveDeviceId) : {};
 			const effectiveTree = Object.keys(deviceOverrides).length > 0 ? applyDeviceOverridesToTree(tree, "object-detection", deviceOverrides) : tree;
-			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" });
+			const nativeFaceCropProvider = this.buildNativeFaceCropProvider(input.frameHandle);
+			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" }, nativeFaceCropProvider);
 			if (isRuntime) {
 				if (trace && this.eventBus) this.eventBus.emit(createEvent(EventCategory.PipelineTrace, {
 					type: "device",
@@ -7165,6 +7343,7 @@ function buildSchemaSlots(format, modelsDir, customByStep) {
 			defaultModelId: step.defaultModelId,
 			...step.defaultModelIdByFormat ? { defaultModelIdByFormat: { ...step.defaultModelIdByFormat } } : {},
 			...step.enabledByDefault !== void 0 ? { enabledByDefault: step.enabledByDefault } : {},
+			...step.backfillIntoExistingOverrides !== void 0 ? { backfillIntoExistingOverrides: step.backfillIntoExistingOverrides } : {},
 			defaultConfidence: step.defaultConfidence,
 			...step.group ? { group: step.group } : {},
 			...configSchema.length > 0 ? { configSchema: [...configSchema] } : {}