@camstack/addon-pipeline 1.2.328 → 1.2.330

package/dist/detection-pipeline/index.js

@@ -3,11 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-wJO7mXeO.js");
-const require_node = require("../node-BCrqaejt.js");
-const require_default_detection_model = require("../default-detection-model-1SadEKsW.js");
+const require_dist = require("../dist-CMeICL07.js");
+const require_node = require("../node-X_0Tka7-.js");
+const require_default_detection_model = require("../default-detection-model-B6gKGnfx.js");
 const require_lazy_sharp = require("../lazy-sharp-BuwKlQLR.js");
-const require_process_memory = require("../process-memory-iUJuTpXs.js");
+const require_process_memory = require("../process-memory-o4LFWbBN.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_fs = require("node:fs");
@@ -759,7 +759,7 @@ var POOL_MODEL_LOAD_BOUNDS = {
 		hardMs: 6e5,
 		why: "A cold iGPU compile of the WHOLE model set measured ~25 s on the N100; one model is 1-3 s (YuNet 1.4 s on a fresh worker, 2026-09-26). 120 s is ~5x the worst measured set. No evidence of a legitimate compile past it; the hard bound gives one 5x more before the worker is recycled.",
 		gilMayBeHeldDuringCompile: false,
-		gilWhy: "The OpenVINO Python binding is believed to release the GIL around compile_model (gil_scoped_release). Not measured on the hub; the passive recipe in D653 checks it."
+		gilWhy: "The OpenVINO Python binding is believed to release the GIL around compile_model (gil_scoped_release). Not yet measured on this node."
 	},
 	coreml: {
 		softMs: 3e5,
@@ -2816,6 +2816,8 @@ var PipelineModelManager = class {
 			stepId,
 			modelId,
 			poolIndex: index,
+			path: config.path,
+			...settings !== void 0 ? { settings } : {},
 			lruTick: ++this.lruClock,
 			decode
 		};
@@ -2823,6 +2825,56 @@ var PipelineModelManager = class {
 		return entry;
 	}
 	/**
+	* Reload every resident slot whose model FILE is no longer the one
+	* `buildConfig` names — a Coral pool that switched co-compiled set (D724).
+	* The new slot is loaded BEFORE the old one is unloaded and the entry is
+	* replaced in between, so a lookup always finds a loaded index. Returns the
+	* `(step, model)` pairs reloaded. A failed reload keeps the old slot (it
+	* still serves, from the file it was loaded from) and is logged.
+	*/
+	async reloadChangedPaths() {
+		const reloaded = [];
+		for (const [stepId, perStep] of this.loaded) for (const entry of perStep.values()) {
+			const config = this.source.buildConfig(stepId, entry.modelId, entry.settings);
+			if (config.path === entry.path) continue;
+			const index = this.pool.allocateIndex();
+			try {
+				await this.pool.loadModel(index, config);
+			} catch (err) {
+				this.pool.releaseIndex(index);
+				this.log.error("Step variant reload from another model file failed — the old file keeps serving", { meta: {
+					step: stepId,
+					modelId: entry.modelId,
+					deviceKey: this.deviceKey,
+					from: entry.path,
+					to: config.path,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				continue;
+			}
+			perStep.set(entry.modelId, {
+				...entry,
+				poolIndex: index,
+				path: config.path,
+				decode: poolDecodeSettingsOf(config)
+			});
+			await this.pool.unloadModel(entry.poolIndex);
+			this.log.info("Step variant reloaded from another model file", { meta: {
+				step: stepId,
+				modelId: entry.modelId,
+				deviceKey: this.deviceKey,
+				from: entry.path,
+				to: config.path,
+				poolIndex: index
+			} });
+			reloaded.push({
+				stepId,
+				modelId: entry.modelId
+			});
+		}
+		return reloaded;
+	}
+	/**
 	* Push a retuned decode setting into ONE already-loaded slot.
 	*
 	* Scope is the point: `reconfigure` names a single pool index, so a slider
@@ -2981,6 +3033,251 @@ function deviceKeyOf(engine) {
 	return engine.device ? `${engine.backend}:${engine.device}` : engine.backend;
 }
 //#endregion
+//#region src/detection-pipeline/engine/coral-cocompiled-set.ts
+var ROOT_DETECTOR_STEP_ID = "object-detection";
+/** The models a dispatch places on the pool that runs it: every enabled video step. */
+function placedModelsOf(steps) {
+	return flattenEnabledVideoSteps(steps).map((s) => ({
+		stepId: s.addonId,
+		modelId: s.modelId
+	}));
+}
+var sameModel = (a, b) => a.stepId === b.stepId && a.modelId === b.modelId;
+/**
+* The set for `placed`, or why there is none.
+*
+* 1. A set that reserves the cache for the root detector is eligible only when
+*    the root is placed here, and a rootless set only when it is not: a root
+*    set on a pool without the root wastes the cache the root would have had,
+*    and a rootless set beside a root makes the root swap.
+* 2. A set must stand for at least two placed models — one model alone is
+*    better off with the whole cache (its separately compiled file).
+* 3. Most placed models covered wins; then the set with fewest members nobody
+*    placed (they hold cache for nothing); then declaration order.
+*/
+function selectCoCompiledSet(placed, sets) {
+	if (placed.length === 0) return {
+		kind: "separate",
+		reason: "nothing-placed"
+	};
+	if (placed.length === 1) return {
+		kind: "separate",
+		reason: "single-model"
+	};
+	const hostsRoot = placed.some((p) => p.stepId === ROOT_DETECTOR_STEP_ID);
+	let best = null;
+	for (const set of sets) {
+		if (set.hostsRoot !== hostsRoot) continue;
+		const covered = placed.filter((p) => set.members.some((m) => sameModel(m, p)));
+		if (covered.length < 2) continue;
+		const idle = set.members.length - covered.length;
+		if (best === null || covered.length > best.covered.length || covered.length === best.covered.length && idle < best.idle) best = {
+			set,
+			covered,
+			idle
+		};
+	}
+	if (best === null) return {
+		kind: "separate",
+		reason: "no-set-covers-two"
+	};
+	const { set, covered } = best;
+	return {
+		kind: "set",
+		set,
+		covered,
+		uncovered: placed.filter((p) => !covered.some((c) => sameModel(c, p)))
+	};
+}
+/** The member a selection loads `(stepId, modelId)` from, or `null` (its own `formats.tflite`). */
+function setMemberFor(selection, stepId, modelId) {
+	if (selection.kind !== "set") return null;
+	return selection.set.members.find((m) => m.stepId === stepId && m.modelId === modelId) ?? null;
+}
+/**
+* `entry` with its `tflite` build pointed at the set's file. Everything else —
+* labels, postprocessor, input contract, licence — is the entry's own: a
+* member is the same model, compiled together with others.
+*/
+function withSetBuild(entry, member) {
+	return {
+		...entry,
+		formats: {
+			...entry.formats,
+			tflite: {
+				url: member.url,
+				sizeMB: member.sizeMB,
+				runtimes: ["python"]
+			}
+		}
+	};
+}
+/** Identity of a selection for change detection: the set AND what it leaves out. */
+var selectionKey = (s) => s.kind === "set" ? `${s.set.id}|${s.uncovered.map((u) => `${u.stepId}/${u.modelId}`).toSorted().join(",")}` : `separate:${s.reason}`;
+/**
+* The placement of ONE Coral pool and the set it loads. Lives exactly as long
+* as the pool (the factory owns it).
+*/
+var CoralSetPlanner = class {
+	sets;
+	placed = [];
+	current = {
+		kind: "separate",
+		reason: "nothing-placed"
+	};
+	constructor(sets) {
+		this.sets = sets;
+	}
+	/** Add the models a dispatch places on this pool; say whether the set changed. */
+	note(models) {
+		let grew = false;
+		for (const m of models) {
+			if (this.placed.some((p) => sameModel(p, m))) continue;
+			this.placed.push({
+				stepId: m.stepId,
+				modelId: m.modelId
+			});
+			grew = true;
+		}
+		if (!grew) return { kind: "unchanged" };
+		const next = selectCoCompiledSet(this.placed, this.sets);
+		if (selectionKey(next) === selectionKey(this.current)) {
+			this.current = next;
+			return { kind: "unchanged" };
+		}
+		const from = this.current;
+		this.current = next;
+		return {
+			kind: "changed",
+			from,
+			to: next,
+			placed: [...this.placed]
+		};
+	}
+	selection() {
+		return this.current;
+	}
+	/** `entry` as this pool must load it: from the set when the set stands for it. */
+	entryFor(stepId, entry) {
+		const member = setMemberFor(this.current, stepId, entry.id);
+		return member === null ? entry : withSetBuild(entry, member);
+	}
+};
+//#endregion
+//#region src/detection-pipeline/registry/edgetpu-cocompiled-sets.ts
+/**
+* Co-compiled Edge TPU sets — pool-level artifacts, not models (D724).
+*
+* A Coral holds ~6.9 MiB of parameter cache. Two separately compiled models
+* carry two different cache tokens, so every alternation between them on one
+* Coral flushes the cache and re-streams the incoming model's parameters over
+* USB (D710). `edgetpu_compiler` given several models at once allocates the
+* cache between them, in command-line order, under ONE token: loaded from the
+* same set, they never evict each other — whatever does not fit is streamed on
+* every invoke of THAT model instead.
+*
+* Each member is the SAME model as its catalog entry's `formats.tflite` (same
+* `modelId`, same int8 graph, same labels and licence record), compiled
+* together with the other members (D710: a Coral build is a format of the
+* survivor; the set is where it is placed, not a new model). A Coral pool picks
+* at most one set from the models placed on it (`coral-cocompiled-set.ts`) and
+* falls back to the separately compiled `formats.tflite` for everything else.
+*
+* Built by `scripts/build-edgetpu-sets.py` (compile order = `members` order =
+* cache priority) and hosted under `edgetpuSets/<id>/`. Only sets whose
+* measured cost is acceptable are listed here: a set that would make the root
+* detector stream parameters on every frame (root + YuNet at 640: the root
+* keeps 3.34 of its 6.39 MiB, YuNet's activations take the rest) is
+* deliberately absent.
+*/
+var HF_REPO = "camstack/camstack-models";
+var setFile = (setId, file) => require_dist.hfModelUrl(HF_REPO, `edgetpuSets/${setId}/${setId}__${file}`);
+var SSD = "ssd-mobilenet-v2-coco-edgetpu";
+var YUNET = "yunet-2023mar";
+var YOLOX = "yolox-tiny-plate";
+var BIRD = "bird-classifier";
+var EDGETPU_COCOMPILED_SETS = [
+	{
+		id: "root-plate-bird",
+		hostsRoot: true,
+		members: [
+			{
+				stepId: "object-detection",
+				modelId: SSD,
+				url: setFile("root-plate-bird", "ssd_mobilenet_v2_coco_quant_postprocess_edgetpu.tflite"),
+				sizeMB: 6.9,
+				onChipMiB: 6.39,
+				streamedMiB: 0
+			},
+			{
+				stepId: "plate-detection",
+				modelId: YOLOX,
+				url: setFile("root-plate-bird", "camstack-yolox-tiny-plate_int8_edgetpu.tflite"),
+				sizeMB: 6.9,
+				onChipMiB: .08,
+				streamedMiB: 5.41
+			},
+			{
+				stepId: "bird-classifier",
+				modelId: BIRD,
+				url: setFile("root-plate-bird", "mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite"),
+				sizeMB: 4.9,
+				onChipMiB: 0,
+				streamedMiB: 4.54
+			}
+		]
+	},
+	{
+		id: "face-plate-bird",
+		hostsRoot: false,
+		members: [
+			{
+				stepId: "face-detection",
+				modelId: YUNET,
+				url: setFile("face-plate-bird", "camstack-yunet-2023mar_int8_edgetpu.tflite"),
+				sizeMB: .7,
+				onChipMiB: .11,
+				streamedMiB: 0
+			},
+			{
+				stepId: "plate-detection",
+				modelId: YOLOX,
+				url: setFile("face-plate-bird", "camstack-yolox-tiny-plate_int8_edgetpu.tflite"),
+				sizeMB: 6.9,
+				onChipMiB: 3.23,
+				streamedMiB: 2.27
+			},
+			{
+				stepId: "bird-classifier",
+				modelId: BIRD,
+				url: setFile("face-plate-bird", "mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite"),
+				sizeMB: 4.9,
+				onChipMiB: 0,
+				streamedMiB: 4.54
+			}
+		]
+	},
+	{
+		id: "plate-bird",
+		hostsRoot: false,
+		members: [{
+			stepId: "plate-detection",
+			modelId: YOLOX,
+			url: setFile("plate-bird", "camstack-yolox-tiny-plate_int8_edgetpu.tflite"),
+			sizeMB: 6.9,
+			onChipMiB: 5.55,
+			streamedMiB: 0
+		}, {
+			stepId: "bird-classifier",
+			modelId: BIRD,
+			url: setFile("plate-bird", "mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite"),
+			sizeMB: 4.1,
+			onChipMiB: .92,
+			streamedMiB: 2.8
+		}]
+	}
+];
+//#endregion
 //#region src/detection-pipeline/engine/engine-factory.ts
 var BACKEND_TO_POOL_RUNTIME = {
 	coreml: "coreml",
@@ -3074,11 +3371,45 @@ var EngineFactory = class {
 	* trying to be.
 	*/
 	resolvedProvisioning;
+	/**
+	* A Coral pool's placement and the co-compiled set it loads (D724); `null`
+	* on every other runtime. Lives exactly as long as this factory — a new
+	* pool starts from nothing placed.
+	*/
+	coralSets;
 	constructor(opts) {
 		this.opts = opts;
 		this.log = opts.logger;
 		this.deviceKey = deviceKeyOf(opts.engine);
 		this.resolvedProvisioning = resolvePoolProvisioning(opts.engine, opts.provisioning);
+		this.coralSets = BACKEND_TO_POOL_RUNTIME[opts.engine.backend] === "edgetpu" ? new CoralSetPlanner(opts.coCompiledSets ?? EDGETPU_COCOMPILED_SETS) : null;
+	}
+	/**
+	* Record the models a dispatch places on this pool. On a Coral pool the
+	* answer says whether the co-compiled set it loads from changed; on any
+	* other pool nothing is placed and nothing changes.
+	*/
+	notePlacement(models) {
+		return this.coralSets?.note(models) ?? { kind: "unchanged" };
+	}
+	/** The co-compiled set this pool loads from, or why none (`null`: not a Coral pool). */
+	coralSetSelection() {
+		return this.coralSets?.selection() ?? null;
+	}
+	/**
+	* The catalog entry as THIS pool must download and load it: on a Coral pool
+	* whose set stands for the model, the `tflite` build is the set's file.
+	* Every other entry is returned unchanged.
+	*/
+	entryForPool(stepId, entry) {
+		return this.coralSets?.entryFor(stepId, entry) ?? entry;
+	}
+	/**
+	* Reload every resident model whose file this pool no longer names — after
+	* the Coral set changed. The caller has already downloaded the new files.
+	*/
+	async reloadChangedModelFiles() {
+		return this.poolManager?.reloadChangedPaths() ?? [];
 	}
 	/**
 	* The provisioning this factory's pool runs with — resolved from the pool's
@@ -3340,6 +3671,7 @@ var EngineFactory = class {
 			stepSettings,
 			device: this.opts.engine.device,
 			resolveCustomModel: this.opts.resolveCustomModel,
+			entryForPool: (sid, entry) => this.entryForPool(sid, entry),
 			onClassMapDrop: ({ stepId: sid, modelId: mid, unmappedLabels }) => {
 				const key = `${sid}::${mid}`;
 				if (this.classMapDropLogged.has(key)) return;
@@ -3365,8 +3697,9 @@ var EngineFactory = class {
 function buildPoolModelConfigForStep(inputs) {
 	const { stepId, modelId, poolRuntime, modelsDir } = inputs;
 	const def = require_default_detection_model.getStepDefinition(stepId);
-	const modelEntry = def.models.find((m) => m.id === modelId) ?? inputs.resolveCustomModel?.(stepId, modelId);
-	if (!modelEntry) throw new Error(`Model "${modelId}" not found in step "${stepId}" catalog (static or custom registry)`);
+	const resolvedEntry = def.models.find((m) => m.id === modelId) ?? inputs.resolveCustomModel?.(stepId, modelId);
+	if (!resolvedEntry) throw new Error(`Model "${modelId}" not found in step "${stepId}" catalog (static or custom registry)`);
+	const modelEntry = inputs.entryForPool?.(stepId, resolvedEntry) ?? resolvedEntry;
 	const format = RUNTIME_TO_FORMAT[poolRuntime];
 	if (!format) throw new Error(`No format mapping for pool runtime "${poolRuntime}"`);
 	const dropWarning = collectClassMapDropWarning(def, modelEntry);
@@ -5450,6 +5783,26 @@ var PLATE_OCR_CROP_POLICIES = {
 	}
 };
 /**
+* The margin around a plate box drawn by the ROOT model (D730) — a Frigate+
+* `license_plate` read in place of `plate-detection`'s own box.
+*
+* The margin is a property of the box's detector (see above), and this
+* detector's boxes have never been measured against the plate readers: 0.15 is
+* the value that served a TIGHT detector box (the deleted `yolov8n-plate`,
+* 7/7 Kia reads at 0.13–0.16), on the assumption that Frigate+ boxes are
+* tight as well. It is uncalibrated and needs measuring on a ground-truth set
+* of root-supplied plates before it is trusted; until then it applies to every
+* reader alike, replacing the reader's own detector-specific margin.
+*/
+var ROOT_SUPPLIED_PLATE_MARGIN_FRACTION = .15;
+/**
+* The margin a reader cuts around its plate box: the reader's own, unless the
+* box was drawn by the root model.
+*/
+function plateOcrMarginFraction(policy, boxFromRoot) {
+	return boxFromRoot ? ROOT_SUPPLIED_PLATE_MARGIN_FRACTION : policy.marginFraction;
+}
+/**
 * The crop policy for a step child, or `null` when the child is not a plate
 * reader at all (a face embedder, a classifier — nothing here applies to them).
 */
@@ -5479,6 +5832,79 @@ function expandBbox(bbox, marginFraction, imageWidth, imageHeight) {
 	];
 }
 //#endregion
+//#region src/detection-pipeline/pipeline/root-child-boxes.ts
+/**
+* Root child boxes (D730) — a root model's `license_plate` / `face` box made
+* into a DETAIL of the vehicle / person that contains it.
+*
+* The labels are deliberately absent from the root's classMap, so they never
+* make a first-level detection and therefore never a track (D683). When the
+* root declares a CROP supply for them, the executor keeps the boxes aside
+* instead of discarding them, and once the frame's first-level detections are
+* final this attaches each to its containing parent (`containingParentIndex`).
+* Whether the camera USES them is the runner's decision
+* (`pipeline-runner/root-supply.ts`); a box nothing contains is discarded.
+*
+* Pure.
+*/
+/** The crop supply a raw root class belongs to, if the root declares one. */
+function cropSupplyForLabel(supplies, rawClass) {
+	for (const supply of supplies ?? []) if (supply.kind === "crop" && supply.rootLabels.includes(rawClass)) return supply;
+}
+function toBox(b) {
+	return {
+		x: b[0],
+		y: b[1],
+		w: b[2] - b[0],
+		h: b[3] - b[1]
+	};
+}
+/**
+* Attach each candidate to the smallest first-level parent of its supply's
+* macro that contains it. Never mutates the parents.
+*/
+function attachRootChildBoxes(candidates, parents, modelId, idGen) {
+	const details = [];
+	const uncontained = [];
+	for (const candidate of candidates) {
+		const eligible = parents.filter((p) => p.kind === "first-level" && p.macroClass === candidate.supply.parentMacro);
+		const index = require_dist.containingParentIndex(toBox(candidate.bbox), eligible.map((p) => toBox(p.bbox)));
+		const parent = index >= 0 ? eligible[index] : void 0;
+		if (parent === void 0) {
+			uncontained.push(candidate);
+			continue;
+		}
+		const stepId = candidate.supply.stepId;
+		details.push({
+			id: idGen.next(),
+			kind: "detail",
+			macroClass: candidate.supply.childClass,
+			originalClass: candidate.rawClass,
+			score: candidate.score,
+			bbox: [
+				candidate.bbox[0],
+				candidate.bbox[1],
+				candidate.bbox[2],
+				candidate.bbox[3]
+			],
+			parentId: parent.id,
+			rootSupplied: {
+				stepId,
+				modelId
+			},
+			ownLabels: [],
+			alternateLabels: {},
+			stepLatencyMs: {},
+			modelIds: { [stepId]: modelId },
+			extractMode: "full-frame"
+		});
+	}
+	return {
+		details,
+		uncontained
+	};
+}
+//#endregion
 //#region src/detection-pipeline/pipeline/plate-warp.ts
 /**
 * Plate-crop WARP — perspective rectification of a licence-plate ROI to a
@@ -6035,6 +6461,7 @@ function buildFrameResult(input) {
 			} : {},
 			labels,
 			...m.parentId !== void 0 ? { parentId: m.parentId } : {},
+			...m.rootSupplied !== void 0 ? { rootSupplied: m.rootSupplied } : {},
 			...embedding !== void 0 ? {
 				embedding,
 				...embeddingModelId !== void 0 ? { embeddingModelId } : {}
@@ -6136,33 +6563,35 @@ function toMutableRootDetection(det, rootStep, idGen, rootStepLatencyMs) {
 //#endregion
 //#region src/detection-pipeline/pipeline/linked-label.ts
 /**
-* The detector's linked label (D715): when the model that RAN declares it
-* fills a step, a detection whose raw class names that step's effect carries
-* the effect as a `ScoredLabel` attributed to `detector-link:<stepId>` — in
-* the step's own vocabulary and tier, so tier 1 means one thing whichever
+* The detector's linked label (D715, D730): when the model that RAN declares a
+* LABEL supply for a step, a detection whose raw class names that step's effect
+* carries the effect as a `ScoredLabel` attributed to `detector-link:<stepId>`
+* — in the step's own vocabulary and tier, so tier 1 means one thing whichever
 * writer produced it.
 *
 * Written at score 0 here, always: the executor cannot see the camera's whole
 * step tree (a detail step placed on another pool is pruned from the dispatch),
-* so it cannot know who the writer is. The runner, which holds the attach
-* config, raises the score to the detection's own when the detector is
-* authoritative (`pipeline-runner/label-link.ts`). Score 0 is the fallback any
-* scored answer of the step outranks.
+* so it cannot know whether the camera USES the supply. The runner, which holds
+* the attach config, decides with `resolveRootSupply` (`pipeline-runner/root-supply.ts`):
+* effective ⇒ the label is raised to the detection's score, or dropped when the
+* step's class list switched it off; otherwise it stays the score-0 fallback
+* any scored answer of the step outranks.
 */
 /** The linked labels one mapped root detection carries. Pure. */
-function linkedLabelsFor(fills, rawClass, macroClass, modelId) {
-	if (fills === void 0 || fills.length === 0) return [];
+function linkedLabelsFor(supplies, rawClass, macroClass, modelId) {
+	if (supplies === void 0 || supplies.length === 0) return [];
 	const out = [];
-	for (const fill of fills) {
-		if (require_dist.FILLABLE_STEP_MACRO[fill.stepId] !== macroClass) continue;
-		const effect = fill.labelToEffect[rawClass];
+	for (const supply of supplies) {
+		if (supply.kind !== "label") continue;
+		if (require_dist.LABEL_SUPPLY_MACRO[supply.stepId] !== macroClass) continue;
+		const effect = supply.labelToEffect[rawClass];
 		if (effect === void 0 || effect === macroClass) continue;
-		const tier = require_default_detection_model.getStepDefinition(fill.stepId).labelTier;
+		const tier = require_default_detection_model.getStepDefinition(supply.stepId).labelTier;
 		out.push({
 			label: effect,
 			score: 0,
 			...tier !== void 0 ? { tier } : {},
-			stepId: require_dist.linkedLabelStepId(fill.stepId),
+			stepId: require_dist.linkedLabelStepId(supply.stepId),
 			modelId
 		});
 	}
@@ -6391,10 +6820,19 @@ var PipelineExecutor = class {
 			const rootView = rootInputViewProvider ? await rootInputViewProvider(rootStep, rootCrop) : null;
 			const cropPrep = !rootView && rootCrop !== void 0 ? await this.prepareCropZoneInput(rootCrop, fullFrameJpegProvider, imageWidth, imageHeight, deviceId) : null;
 			const rootStart = Date.now();
-			const rawRootOutput = await this.executeStep(rootStep, rootView?.input ?? cropPrep?.input ?? withInferenceDeviceId(rootInput, deviceId), rootView?.width ?? cropPrep?.width ?? imageWidth, rootView?.height ?? cropPrep?.height ?? imageHeight, "full-frame", void 0, void 0, traceBuilder, stepTimings, poolAgg, rootShed);
+			const supplied = runOpts?.suppliedRoot?.stepId === rootStep.stepId ? runOpts.suppliedRoot : void 0;
+			const rawRootOutput = supplied ? {
+				kind: "detections",
+				detections: supplied.detections.map((d) => ({
+					class: rootStep.definition.outputClasses[0] ?? rootStep.stepId,
+					score: d.score,
+					bbox: d.bbox,
+					...d.landmarks !== void 0 ? { landmarks: d.landmarks } : {}
+				}))
+			} : await this.executeStep(rootStep, rootView?.input ?? cropPrep?.input ?? withInferenceDeviceId(rootInput, deviceId), rootView?.width ?? cropPrep?.width ?? imageWidth, rootView?.height ?? cropPrep?.height ?? imageHeight, "full-frame", void 0, void 0, traceBuilder, stepTimings, poolAgg, rootShed);
 			const rootMs = Date.now() - rootStart;
 			if (rawRootOutput === null) continue;
-			const rootOutput = rootView && rawRootOutput.kind === "detections" ? reprojectViewDetections(rawRootOutput, rootView.geometry) : cropPrep && rawRootOutput.kind === "detections" ? reprojectCropZoneDetections(rawRootOutput, cropPrep.origin) : rawRootOutput;
+			const rootOutput = supplied ? rawRootOutput : rootView && rawRootOutput.kind === "detections" ? reprojectViewDetections(rawRootOutput, rootView.geometry) : cropPrep && rawRootOutput.kind === "detections" ? reprojectCropZoneDetections(rawRootOutput, cropPrep.origin) : rawRootOutput;
 			if (rootOutput.kind !== "detections") {
 				if (isEnrichmentOutput(rootOutput)) {
 					const mutable = this.synthesizeRootDetection(rootOutput, rootStep, idGen, rootMs, imageWidth, imageHeight);
@@ -6416,8 +6854,33 @@ var PipelineExecutor = class {
 				}
 				continue;
 			}
+			const rootChildCandidates = [];
+			const firstLevelStart = firstLevel.length;
 			for (const det of rootOutput.detections) {
-				const mutable = toMutableRootDetection(det, rootStep, idGen, rootMs);
+				const cropSupply = cropSupplyForLabel(rootStep.rootSupplies, det.class);
+				if (cropSupply !== void 0) {
+					rootChildCandidates.push({
+						rawClass: det.class,
+						score: det.score,
+						bbox: [
+							det.bbox[0],
+							det.bbox[1],
+							det.bbox[2],
+							det.bbox[3]
+						],
+						supply: cropSupply
+					});
+					continue;
+				}
+				const seeded = toMutableRootDetection(det, rootStep, idGen, rootMs);
+				const mutable = supplied ? {
+					...seeded,
+					rootSupplied: {
+						stepId: rootStep.stepId,
+						modelId: supplied.modelId
+					},
+					modelIds: { [rootStep.stepId]: supplied.modelId }
+				} : seeded;
 				if (rootStep.effectiveClassMap) {
 					const mapped = rootStep.effectiveClassMap.mapping[det.class];
 					if (mapped) {
@@ -6438,7 +6901,7 @@ var PipelineExecutor = class {
 						continue;
 					}
 				}
-				for (const linked of linkedLabelsFor(rootStep.fillsClassifierEffects, det.class, mutable.macroClass, rootStep.modelId)) mutable.ownLabels.push(linked);
+				for (const linked of linkedLabelsFor(rootStep.rootSupplies, det.class, mutable.macroClass, rootStep.modelId)) mutable.ownLabels.push(linked);
 				const filterVerdict = this.macroFilterVerdict(mutable.macroClass, mutable.score, rootStep.settings);
 				if (filterVerdict !== "pass") {
 					(discarded ??= []).push({
@@ -6520,6 +6983,21 @@ var PipelineExecutor = class {
 				}
 				firstLevel.push(mutable);
 			}
+			if (rootChildCandidates.length > 0) {
+				const attached = attachRootChildBoxes(rootChildCandidates, firstLevel.slice(firstLevelStart), rootStep.modelId, idGen);
+				details.push(...attached.details);
+				for (const c of attached.uncontained) (discarded ??= []).push({
+					bbox: [
+						c.bbox[0],
+						c.bbox[1],
+						c.bbox[2],
+						c.bbox[3]
+					],
+					macroClass: c.supply.childClass,
+					score: c.score,
+					reason: "class-filter"
+				});
+			}
 		}
 		const totalMs = Date.now() - startMs;
 		return {
@@ -6787,7 +7265,8 @@ var PipelineExecutor = class {
 					}
 				} else {
 					const cropPolicy = resolvePlateOcrCropPolicy(resolveEffectivePostprocessor(child.definition, child.modelId));
-					const cropBbox = cropPolicy ? expandBbox(parentDetection.bbox, cropPolicy.marginFraction, imageWidth, imageHeight) : parentDetection.bbox;
+					const marginFraction = cropPolicy ? plateOcrMarginFraction(cropPolicy, parentDetection.rootSupplied !== void 0) : 0;
+					const cropBbox = cropPolicy ? expandBbox(parentDetection.bbox, marginFraction, imageWidth, imageHeight) : parentDetection.bbox;
 					const nativeChild = nativeCropProvider && child.children.length === 0 ? await nativeChildCrop(nativeCropProvider, cropBbox, imageWidth, imageHeight, NATIVE_CHILD_CROP_MAX_WIDTH) : null;
 					if (nativeChild) {
 						cropJpegBuf = nativeChild.jpeg;
@@ -6810,7 +7289,8 @@ var PipelineExecutor = class {
 									plateLongSidePx: Math.round(plateLongSidePx),
 									plateShortSidePx: Math.round(Math.min(cropW, cropH)),
 									minPlateLongSidePx: cropPolicy.minLongSidePx,
-									marginFraction: cropPolicy.marginFraction,
+									marginFraction,
+									boxFrom: parentDetection.rootSupplied !== void 0 ? "root-model" : "step",
 									source: nativeChild ? "native" : "detection-tile"
 								}
 							});
@@ -7008,9 +7488,18 @@ function buildNode(step, getEngine, resolveModel, onMissingVariant, resolved) {
 		children,
 		...Object.keys(mergedSettings).length > 0 ? { settings: mergedSettings } : {},
 		...effectiveClassMap !== void 0 ? { effectiveClassMap } : {},
-		...modelEntry?.fillsClassifierEffects !== void 0 ? { fillsClassifierEffects: modelEntry.fillsClassifierEffects } : {}
+		...rootSuppliesField(definition, modelEntry)
 	};
 }
+/** A root step's supplies, omitted when it declares none (and for every child step). */
+function rootSuppliesField(definition, modelEntry) {
+	if (definition.inputClasses !== null) return {};
+	const supplies = require_dist.rootSuppliesOf(modelEntry, {
+		labels: definition.labels ?? [],
+		...definition.classMap !== void 0 ? { classMap: definition.classMap } : {}
+	});
+	return supplies.length > 0 ? { rootSupplies: supplies } : {};
+}
 /**
 * Walk the step's declared `getConfigSchema()` and collect every field
 * with a primitive `default` value into a plain record. Group fields
@@ -9156,7 +9645,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			execution = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, {
 				traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full",
 				plane: input.plane,
-				occasion: input.replay === true ? "replay" : "live"
+				occasion: input.replay === true ? "replay" : "live",
+				...input.suppliedRoot !== void 0 ? { suppliedRoot: input.suppliedRoot } : {}
 			}, nativeCropProvider, cropZoneBbox, rootInputViewProvider);
 			executionSucceeded = true;
 		} finally {
@@ -9432,6 +9922,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	*/
 	async loadDispatchModels(steps, factory, format, context, policy) {
 		const failures = [];
+		if (factory !== null) await this.noteCoralPlacement(steps, factory, format, context);
 		const walk = async (nodes, root) => {
 			for (const step of nodes) {
 				if (!step.enabled || step.slot === "audio-classifier") continue;
@@ -9456,6 +9947,69 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		await walk(steps, true);
 		return failures;
 	}
+	/**
+	* Tell a Coral pool which models this dispatch places on it, and act on a
+	* change of the co-compiled set it loads from (D724): download the set's
+	* files for the models already resident and reload them — queued behind the
+	* pool's other loads, so nothing loads from the old file meanwhile. Logged
+	* once per change, tagged with the camera whose dispatch moved it.
+	*/
+	async noteCoralPlacement(steps, factory, format, context) {
+		const change = factory.notePlacement(placedModelsOf(steps));
+		if (change.kind === "unchanged") return;
+		const deviceKey = context.deviceKey ?? deviceKeyOf(this.currentEngine);
+		const tags = context.deviceId !== void 0 ? { tags: { deviceId: context.deviceId } } : {};
+		const placed = change.placed.map((p) => `${p.stepId}/${p.modelId}`);
+		if (change.to.kind === "set") this.log.info("Coral pool loads a co-compiled set — the models placed on it share the parameter cache", {
+			...tags,
+			meta: {
+				deviceKey,
+				set: change.to.set.id,
+				placed,
+				fromSet: change.to.covered.map((p) => `${p.stepId}/${p.modelId}`),
+				separatelyCompiled: change.to.uncovered.map((p) => `${p.stepId}/${p.modelId}`),
+				previous: change.from.kind === "set" ? change.from.set.id : null
+			}
+		});
+		else if (change.to.reason === "no-set-covers-two") this.log.warn("Coral pool has no co-compiled set for the models placed on it — each is compiled alone, so they evict each other from the parameter cache on every alternation", {
+			...tags,
+			meta: {
+				deviceKey,
+				placed,
+				previous: change.from.kind === "set" ? change.from.set.id : null,
+				hint: "keep the extra step off this Coral with its jumpDeviceKey, or place a combination a published set covers"
+			}
+		});
+		const pool = factory;
+		const previous = this.modelLoadTail.get(pool) ?? Promise.resolve();
+		const tail = (async () => {
+			await previous;
+			for (const loaded of factory.listLoaded()) {
+				const resolved = await this.resolveModelEntry(loaded.stepId, loaded.modelId);
+				if (resolved === void 0) continue;
+				const entry = factory.entryForPool(loaded.stepId, resolved);
+				if (!(0, _camstack_system_addon_utils.isModelDownloaded)(this.modelsDir, entry, format)) await this.downloadWithRetry(entry, format, 3);
+			}
+			const reloaded = await factory.reloadChangedModelFiles();
+			if (reloaded.length > 0) this.log.info("Coral pool reloaded its resident models from the new set", {
+				...tags,
+				meta: {
+					deviceKey,
+					reloaded: reloaded.map((r) => `${r.stepId}/${r.modelId}`)
+				}
+			});
+		})().catch((err) => {
+			this.log.error("Coral pool could not move its resident models to the new set — they keep serving from the old files", {
+				...tags,
+				meta: {
+					deviceKey,
+					error: require_dist.errMsg(err)
+				}
+			});
+		});
+		this.modelLoadTail.set(pool, tail);
+		await tail;
+	}
 	/** Ensure all models needed by steps are downloaded and loaded in the engine pool.
 	* `factory`/`format` default to the node's engine; a per-device dispatch passes
 	* that device's factory + format (Phase 2 multi-device). `context` names the
@@ -9553,7 +10107,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const refusal = this.loadRefusal(pool, deviceKey, models);
 			if (refusal !== null) throw refusal;
 			try {
-				await this.downloadNeededModels(needed, format);
+				await this.downloadNeededModels(needed, format, factory);
 				this.log.info("Loading additional models for benchmark", { meta: {
 					count: needed.length,
 					models,
@@ -9617,16 +10171,21 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		});
 	}
 	/** Download any model of `needed` missing in `format` (the device's). */
-	async downloadNeededModels(needed, format) {
+	async downloadNeededModels(needed, format, factory = null) {
 		for (const step of needed) try {
-			await this.ensureStepModelArtifact(step, format);
+			await this.ensureStepModelArtifact(step, format, factory);
 		} catch (err) {
 			throw new StepModelArtifactError(step.addonId, step.modelId, err);
 		}
 	}
-	/** Make one step's model artifact present on disk for `format`, or say why it cannot be. */
-	async ensureStepModelArtifact(step, format) {
-		const modelEntry = await this.resolveModelEntry(step.addonId, step.modelId);
+	/**
+	* Make one step's model artifact present on disk for `format`, or say why it
+	* cannot be. The entry is the one `factory`'s pool will LOAD — on a Coral
+	* pool, a co-compiled set's file when the set stands for the model (D724).
+	*/
+	async ensureStepModelArtifact(step, format, factory = null) {
+		const resolved = await this.resolveModelEntry(step.addonId, step.modelId);
+		const modelEntry = resolved && factory !== null ? factory.entryForPool(step.addonId, resolved) : resolved;
 		if (modelEntry && !(0, _camstack_system_addon_utils.isModelDownloaded)(this.modelsDir, modelEntry, format)) {
 			if (modelEntry.formats[format] === void 0) throw new Error(`Model "${modelEntry.id}" has no ${format} format build (available: ${Object.keys(modelEntry.formats).join(", ") || "none"}) — not retrying a permanent format mismatch`);
 			if (modelEntry.formats[format]?.url.startsWith("camstack-local://") === true) throw new Error(`Custom model "${modelEntry.id}" (${format}) is not present in this node's models directory — distribute it to this node from Model Studio before selecting it here`);
@@ -10648,7 +11207,7 @@ function buildSchemaSlots(formats, modelsDir, customByStep) {
 				...m.legacy !== void 0 ? { legacy: m.legacy } : {},
 				provider: m.provider ?? "camstack",
 				defaultConfidence: require_default_detection_model.resolveModelDefaultConfidence(step, m),
-				...m.fillsClassifierEffects !== void 0 ? { fillsClassifierEffects: m.fillsClassifierEffects } : {}
+				...modelSuppliesField(step, m)
 			})),
 			defaultModelId: step.defaultModelId,
 			...step.defaultModelIdByFormat ? { defaultModelIdByFormat: { ...step.defaultModelIdByFormat } } : {},
@@ -10784,6 +11343,15 @@ function isDetailPlaneStep(addonId) {
 		return false;
 	}
 }
+/** A root model's supplies for the schema, omitted when it supplies nothing. */
+function modelSuppliesField(step, model) {
+	if (step.inputClasses !== null) return {};
+	const supplies = require_dist.rootSuppliesOf(model, {
+		labels: step.labels ?? [],
+		...step.classMap !== void 0 ? { classMap: step.classMap } : {}
+	});
+	return supplies.length > 0 ? { suppliesSteps: supplies } : {};
+}
 /**
 * What a dispatch runs after its per-step loads (D657).
 *
@@ -11032,7 +11600,7 @@ var DetectionPipelineAddon = class extends require_dist.BaseAddon {
 					type: "select",
 					key: "batchMode",
 					label: "Batch dispatch mode",
-					description: "How the Python pool GROUPS predict requests — it never changes a model's compiled batch SHAPE, which is derived from (engine, device) at load and is not configurable (D202). `none` = one call per frame. `window` = per-model accumulator coalesces concurrent calls within Window (ms). Auto uses the matrix-sweep default for the current backend. Applies to THIS node only.",
+					description: "How the Python pool GROUPS predict requests — it never changes a model's compiled batch SHAPE, which is derived from (engine, device) at load and is not configurable. `none` = one call per frame. `window` = per-model accumulator coalesces concurrent calls within Window (ms). Auto uses the matrix-sweep default for the current backend. Applies to THIS node only.",
 					options: [
 						{
 							value: "",
@@ -11076,7 +11644,7 @@ var DetectionPipelineAddon = class extends require_dist.BaseAddon {
 					type: "slider",
 					key: "maxBatchSize",
 					label: "Max batch size",
-					description: "Cap on how many requests are GROUPED into one batched predict call. Not the model's compiled batch shape — that is derived from (engine, device) at load and is not configurable (D202); a stacked tensor is only ever built for an export that declares a flexible batch axis itself. Auto = backend default. Applies to THIS node only.",
+					description: "Cap on how many requests are GROUPED into one batched predict call. Not the model's compiled batch shape — that is derived from (engine, device) at load and is not configurable; a stacked tensor is only ever built for an export that declares a flexible batch axis itself. Auto = backend default. Applies to THIS node only.",
 					min: 1,
 					max: 16,
 					step: 1,