@camstack/addon-pipeline 1.2.41 → 1.2.43

package/dist/{event-loop-stall-monitor-C5P2bcwP.js → event-loop-stall-monitor-C7_L6vHO.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-BS7wLqoV.js");
+const require_dist = require("./dist-UHbKZiSa.js");
 let node_perf_hooks = require("node:perf_hooks");
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";

package/dist/{event-loop-stall-monitor-a2u9e1qx.mjs → event-loop-stall-monitor-DfKdC7G4.mjs}

@@ -1,4 +1,4 @@
-import { D as hfModelUrl, a as COCO_TO_MACRO, i as COCO_80_LABELS, r as AUDIO_MACRO_LABELS } from "./dist-DvUTPZ8J.mjs";
+import { a as COCO_80_LABELS, j as hfModelUrl, o as COCO_TO_MACRO, r as AUDIO_MACRO_LABELS } from "./dist-B-VVBzrL.mjs";
 import { PerformanceObserver } from "node:perf_hooks";
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";

package/dist/{model-download-service-Cp9f4dk6-fsdDExML.js → model-download-service-D8B-4ktF-7-YxE9Wx.js}

@@ -1,10 +1,10 @@
 const require_chunk = require("./chunk-emK7D4bc.js");
+require("node:crypto");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs, 1);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path, 1);
-require("node:crypto");
-//#region ../system/dist/model-download-service-Cp9f4dk6.mjs
+//#region ../system/dist/model-download-service-D8B-4ktF.mjs
 /**
 * Map a rel path to one candidate absolute path PER root, keeping only roots the
 * path stays within (traversal guard). The handler serves the first candidate

package/dist/{model-download-service-Cp9f4dk6-CwUb5v3Y.mjs → model-download-service-D8B-4ktF-BB7oZL3y.mjs}

@@ -1,9 +1,9 @@
+import "node:crypto";
 import * as fs from "node:fs";
 import { createReadStream, promises } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
-import "node:crypto";
-//#region ../system/dist/model-download-service-Cp9f4dk6.mjs
+//#region ../system/dist/model-download-service-D8B-4ktF.mjs
 /**
 * Map a rel path to one candidate absolute path PER root, keeping only roots the
 * path stays within (traversal guard). The handler serves the first candidate

package/dist/motion-wasm/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-BS7wLqoV.js");
+const require_dist = require("../dist-UHbKZiSa.js");
 const require_lazy_sharp = require("../lazy-sharp-CcYuXtsa.js");
 let node_fs = require("node:fs");
 let node_path = require("node:path");

package/dist/motion-wasm/index.mjs

@@ -1,4 +1,4 @@
-import { A as motionDetectionCapability, E as evaluateZoneRules, K as hydrateSchema, V as BaseAddon, W as DeviceType } from "../dist-DvUTPZ8J.mjs";
+import { A as evaluateZoneRules, F as motionDetectionCapability, Q as hydrateSchema, X as DeviceType, q as BaseAddon } from "../dist-B-VVBzrL.mjs";
 import { t as getSharp } from "../lazy-sharp-B-mb8uWx.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/pipeline-runner/index.js

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-BS7wLqoV.js");
-const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-C5P2bcwP.js");
+const require_dist = require("../dist-UHbKZiSa.js");
+const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-C7_L6vHO.js");
 const require_worker_protocol = require("../worker-protocol-DextwlTX.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_lazy_sharp = require("../lazy-sharp-CcYuXtsa.js");
@@ -1687,27 +1687,108 @@ function startStallSampler(opts = {}) {
 	};
 }
 //#endregion
-//#region src/pipeline-runner/detail-subtree.ts
-/** Relative padding applied to the parent bbox before cutting the crop — more context for the child model. */
-var DETAIL_CROP_PADDING_RATIO = .15;
+//#region src/pipeline-runner/crop-convention-source.ts
+/**
+* Where the runner gets the ONE detail-crop convention.
+*
+* ## Why the runner, and only the runner
+*
+* Every detail crop is now cut inside `runDetailSubtree` — the live plane from
+* a frame handle, the embedding rebuild from a stored key frame it ships in as
+* `frameJpeg`. One cutter means one reader: nothing else needs the value, so
+* nothing else can drift from it.
+*
+* ## Why a settings read and not the attach config
+*
+* `RunnerCameraConfig` is the obvious orchestrator→runner channel, and it is
+* the wrong one here. Eleven separate call sites construct a
+* `RunnerCameraConfig` (session dispatch, standing dispatch, zone refresh,
+* node reconnect, placement correction, …). A cluster-wide constant threaded
+* through eleven builders is a constant that eventually reaches ten of them,
+* and the failure is invisible: the cameras attached by the forgotten builder
+* quietly cut a different crop and write it into the same index. That is the
+* bug this whole change exists to remove, so it must not be reintroduced as
+* the delivery mechanism.
+*
+* Instead the runner reads the OWNER addon's global settings directly, the way
+* both decoder addons read their backend selector
+* (`decoder-backend.ts`) — hub-routed by `AddonCallGateway`, so an agent runner
+* transparently reads the hub-central store with no placement branching.
+*
+* ## Deliberately NOT node-scoped
+*
+* The read passes no `nodeId`. With one, `addon-settings` would project that
+* node's scoped value and two nodes could cut different crops into the same
+* `object-clip` index — the original defect, relocated to the transport.
+*/
 /**
-* Pad `bbox` by {@link DETAIL_CROP_PADDING_RATIO} of its own size, then clamp
-* to `[0, frameWidth] x [0, frameHeight]`. Pure — always returns a new rect.
+* The addon whose GLOBAL settings own the convention. `pipeline-orchestrator`
+* is hub-resident and neutral — it already owns the per-node decoder-backend
+* selector for the same reason (neither consumer should own a value the other
+* depends on).
 */
-function padAndClampFrameBbox(bbox, frameWidth, frameHeight) {
-	const padX = DETAIL_CROP_PADDING_RATIO * bbox.w;
-	const padY = DETAIL_CROP_PADDING_RATIO * bbox.h;
-	const x1 = Math.max(0, bbox.x - padX);
-	const y1 = Math.max(0, bbox.y - padY);
-	const x2 = Math.min(frameWidth, bbox.x + bbox.w + padX);
-	const y2 = Math.min(frameHeight, bbox.y + bbox.h + padY);
-	return {
-		x: x1,
-		y: y1,
-		w: Math.max(0, x2 - x1),
-		h: Math.max(0, y2 - y1)
-	};
-}
+var CROP_CONVENTION_OWNER_ADDON_ID = "pipeline-orchestrator";
+/**
+* TTL-cached read of the cluster crop convention.
+*
+* {@link current} is synchronous because the crop derivation is, and because a
+* value that is never missing is easier to reason about than one that is
+* sometimes a promise. {@link refresh} is what actually talks to the hub;
+* the runner awaits it at the top of a detail dispatch.
+*/
+var CropConventionSource = class {
+	convention = require_dist.DEFAULT_DETAIL_CROP_CONVENTION;
+	lastReadAtMs = Number.NEGATIVE_INFINITY;
+	inFlight = null;
+	logger;
+	now;
+	ttlMs;
+	constructor(options) {
+		this.logger = options.logger;
+		this.now = options.now ?? (() => Date.now());
+		this.ttlMs = options.ttlMs ?? 6e4;
+	}
+	/** The convention in force right now — the default until a read lands. */
+	current() {
+		return this.convention;
+	}
+	/**
+	* Re-read if the cached value has expired. Concurrent callers share one
+	* in-flight read; a failure keeps the LAST KNOWN value rather than reverting
+	* to the default, because a mid-pass revert would silently change what every
+	* remaining vector of that pass means.
+	*/
+	async refresh(api) {
+		if (api === void 0) return this.convention;
+		if (this.now() - this.lastReadAtMs < this.ttlMs) return this.convention;
+		this.inFlight ??= this.read(api).finally(() => {
+			this.inFlight = null;
+		});
+		await this.inFlight;
+		return this.convention;
+	}
+	async read(api) {
+		try {
+			const next = require_dist.pickDetailCropConvention(await api.addonSettings.getGlobalSettings.query({ addonId: CROP_CONVENTION_OWNER_ADDON_ID }));
+			this.lastReadAtMs = this.now();
+			if (next.paddingRatio !== this.convention.paddingRatio || next.square !== this.convention.square) {
+				this.logger.info("detail crop convention changed — stored vectors need a rebuild", { meta: {
+					from: { ...this.convention },
+					to: { ...next }
+				} });
+				this.convention = next;
+			}
+		} catch (err) {
+			this.logger.warn("detail crop convention read failed — keeping the last known value", { meta: {
+				owner: CROP_CONVENTION_OWNER_ADDON_ID,
+				inUse: { ...this.convention },
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+//#region src/pipeline-runner/detail-subtree.ts
 /** Normalize a frame-space pixel rect to `[0,1]` by the given frame dims. */
 function normalizeRect(rect, frameWidth, frameHeight) {
 	return {
@@ -1793,6 +1874,15 @@ function encodeEmbeddingBase64(embedding) {
 function pickLabel(detection) {
 	return detection.labels.find((l) => !l.label.startsWith("embedding:"))?.label;
 }
+/**
+* Turn one executor detection into the cap's `DetailResult`, reprojecting its
+* crop-space bbox back onto the frame the crop came from.
+*
+* Exported because the STATELESS step path (`stateless-step.ts`) produces the
+* same shape from the same executor output and must not grow its own mapping —
+* a second reprojection is a second set of coordinates, and the two would agree
+* right up until one of them changed.
+*/
 function toDetailResult(detection, stepId, crop) {
 	const label = pickLabel(detection);
 	return {
@@ -1806,15 +1896,62 @@ function toDetailResult(detection, stepId, crop) {
 		...detection.nativeFaceShortSidePx !== void 0 ? { nativeFaceShortSidePx: detection.nativeFaceShortSidePx } : {}
 	};
 }
-async function resolveCrop(deps, input) {
+/**
+* Cut the crop out of a caller-supplied FULL FRAME, applying the one crop
+* convention. This is the branch that made the rebuild comparable with live
+* traffic: before it existed the only way to feed stored pixels in was a
+* pre-cut tile, so the caller decided the rectangle and every caller decided
+* differently.
+*
+* Exported so the STATELESS step path can reach `deriveDetailCropRect` through
+* this function rather than importing it — `scripts/check-clip-crop-single-owner.ts`
+* permits exactly one importer, and that is the enforcement of
+* [D52](../../../../docs/decisions/adr-0052.md). A second caller of the
+* derivation is a second cutter no matter how similar its arithmetic looks
+* today.
+*/
+async function cutFromFullFrame(frameJpegBase64, bbox, convention) {
+	const image = (await require_lazy_sharp.getSharp())(Buffer.from(frameJpegBase64, "base64"));
+	const meta = await image.metadata();
+	const frameWidth = meta.width ?? 0;
+	const frameHeight = meta.height ?? 0;
+	if (frameWidth <= 0 || frameHeight <= 0) return null;
+	const rect = require_dist.deriveDetailCropRect(bbox.kind === "frame-pixels" ? bbox.rect : denormalizeRect(bbox.rect, frameWidth, frameHeight), frameWidth, frameHeight, convention);
+	const left = Math.max(0, Math.min(Math.round(rect.x), frameWidth - 1));
+	const top = Math.max(0, Math.min(Math.round(rect.y), frameHeight - 1));
+	const width = Math.max(1, Math.min(Math.round(rect.w), frameWidth - left));
+	const height = Math.max(1, Math.min(Math.round(rect.h), frameHeight - top));
+	return {
+		jpeg: await image.extract({
+			left,
+			top,
+			width,
+			height
+		}).jpeg({ quality: 90 }).toBuffer(),
+		width,
+		height,
+		frameSpace: {
+			x: left,
+			y: top,
+			w: width,
+			h: height
+		},
+		source: "derived"
+	};
+}
+async function resolveCrop(deps, input, convention) {
 	if (input.frameHandle) {
-		const normalized = normalizeRect(padAndClampFrameBbox(input.parent.bbox, input.frameHandle.width, input.frameHandle.height), input.frameHandle.width, input.frameHandle.height);
+		const normalized = normalizeRect(require_dist.deriveDetailCropRect(input.parent.bbox, input.frameHandle.width, input.frameHandle.height, convention), input.frameHandle.width, input.frameHandle.height);
 		const native = await deps.getNativeCrop(input.deviceId, input.frameHandle, normalized);
 		if (native) return {
 			...native,
 			source: "native"
 		};
 	}
+	if (input.frameJpeg) return cutFromFullFrame(input.frameJpeg, {
+		kind: "frame-pixels",
+		rect: input.parent.bbox
+	}, convention);
 	if (input.cropJpeg) {
 		const jpeg = Buffer.from(input.cropJpeg, "base64");
 		const meta = await (await require_lazy_sharp.getSharp())(jpeg).metadata();
@@ -1849,11 +1986,42 @@ async function resolveCrop(deps, input) {
 */
 async function runDetailSubtree(deps, input) {
 	const matched = deps.resolveChildSteps(input.deviceId, input.parent.className, input.steps);
-	if (!matched || matched.length === 0) return null;
+	if (!matched) {
+		deps.logger.warn("runDetailSubtree: camera is not attached — no detail steps to run", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				parentClass: input.parent.className,
+				...input.steps ? { requestedSteps: [...input.steps] } : {}
+			}
+		});
+		return null;
+	}
+	if (matched.length === 0) {
+		deps.logger.warn("runDetailSubtree: no matching detail step is enabled for this parent class", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				parentClass: input.parent.className,
+				...input.steps ? { requestedSteps: [...input.steps] } : {},
+				hint: "the step is either absent from this camera step tree or disabled on it"
+			}
+		});
+		return null;
+	}
 	const requested = input.steps;
 	const steps = requested === void 0 ? matched : matched.map((step) => pruneChildStepsToRequested(step, requested));
-	const crop = await resolveCrop(deps, input);
-	if (!crop) return null;
+	const crop = await resolveCrop(deps, input, deps.resolveCropConvention(input.deviceId));
+	if (!crop) {
+		deps.logger.warn("runDetailSubtree: no crop source resolved — the dispatch produced nothing", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				parentClass: input.parent.className,
+				hadFrameHandle: input.frameHandle !== void 0,
+				hadFrameJpeg: input.frameJpeg !== void 0,
+				hadCropJpeg: input.cropJpeg !== void 0
+			}
+		});
+		return null;
+	}
 	const nativeCropRef = input.frameHandle !== void 0 && crop.source === "native" ? {
 		handle: input.frameHandle,
 		cropFrameSpace: crop.frameSpace
@@ -3248,6 +3416,83 @@ var PipelineRunner = class {
 	}
 };
 //#endregion
+//#region src/pipeline-runner/stateless-step.ts
+function modelServability(step, modelId, format) {
+	const entry = step.models.find((m) => m.id === modelId);
+	if (entry === void 0) return { kind: "custom-model" };
+	if (entry.formats[format] !== void 0) return { kind: "catalog-build" };
+	return {
+		kind: "no-build",
+		availableFormats: Object.keys(entry.formats)
+	};
+}
+/** Build the refusal answer, log it, and return it — never one without the other. */
+function refuse(deps, input, reason, detail) {
+	deps.logger.warn("runStatelessStep refused", {
+		tags: { deviceId: input.sourceDeviceId },
+		meta: {
+			nodeId: deps.nodeId,
+			stepId: input.stepId,
+			modelId: input.modelId,
+			reason,
+			detail
+		}
+	});
+	return {
+		kind: "refused",
+		nodeId: deps.nodeId,
+		reason,
+		detail
+	};
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Run one step over one subject. See the module header for the two invariants.
+*
+* Never throws: every failure mode is a named, logged refusal, because the
+* caller is a bulk pass whose counters are the only signal an operator gets and
+* a thrown error there reads as "the whole pass broke".
+*/
+async function runStatelessStep(deps, input) {
+	const definition = deps.lookupStep(input.stepId);
+	if (definition === null) return refuse(deps, input, "unknown-step", `this node's step catalog has no "${input.stepId}" — version skew, or a custom step that is not installed here`);
+	if (input.bbox.w <= 0 || input.bbox.h <= 0) return refuse(deps, input, "unreadable-frame", `degenerate normalized bbox ${JSON.stringify(input.bbox)} — nothing to crop`);
+	const format = await deps.executionFormat();
+	if (format === null) return refuse(deps, input, "model-not-servable", "this node could not report the engine format it would dispatch on, so the model pin cannot be verified — running anyway would risk a silent format substitution");
+	const servability = modelServability(definition, input.modelId, format);
+	if (servability.kind === "no-build") return refuse(deps, input, "model-not-servable", `model "${input.modelId}" has no ${format} build (catalog ships: ${servability.availableFormats.join(", ") || "none"}) — this node would have substituted the ${format} default`);
+	let decodeError = null;
+	const crop = await cutFromFullFrame(input.frameJpeg, {
+		kind: "normalized",
+		rect: input.bbox
+	}, deps.resolveCropConvention()).catch((err) => {
+		decodeError = errorMessage(err);
+		return null;
+	});
+	if (crop === null) return refuse(deps, input, "unreadable-frame", decodeError ?? "the supplied frame decoded to no readable dimensions");
+	const steps = [{
+		addonId: input.stepId,
+		modelId: input.modelId,
+		enabled: true
+	}];
+	let result;
+	try {
+		result = await deps.runPipeline(steps, crop.jpeg, input.sourceDeviceId);
+	} catch (err) {
+		return refuse(deps, input, "execution-failed", errorMessage(err));
+	}
+	if (result === null) return refuse(deps, input, "execution-failed", "the executor returned no frame result for the crop");
+	const details = result.detections.map((detection) => toDetailResult(detection, input.stepId, crop));
+	return {
+		kind: "ran",
+		nodeId: deps.nodeId,
+		modelId: input.modelId,
+		details
+	};
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
@@ -4605,14 +4850,90 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	* the frame's owning process), and the node-local `pipelineExecutor`.
 	*/
 	async runDetailSubtree(input) {
+		const convention = await this.cropConvention.refresh(this.ctxIfReady?.api);
 		return runDetailSubtree({
 			resolveChildSteps: (deviceId, parentClassName, filter) => this.resolveDetailChildSteps(deviceId, parentClassName, filter),
 			getNativeCrop: (deviceId, handle, paddedBbox) => this.getNativeCropForDetail(deviceId, handle, paddedBbox),
 			runPipeline: (steps, imageJpeg, deviceId, deviceKey, nativeCropRef) => this.runDetailPipeline(steps, imageJpeg, deviceId, deviceKey, nativeCropRef),
-			resolveStepDevice: (deviceId, step) => this.resolveDetailStepDevice(deviceId, step)
+			resolveStepDevice: (deviceId, step) => this.resolveDetailStepDevice(deviceId, step),
+			resolveCropConvention: () => convention,
+			logger: this.detailSubtreeLogger()
+		}, input);
+	}
+	/**
+	* Stateless single-step execution — no attach, no handle, no device
+	* affinity. Delegates the decision table (catalog lookup, MODEL PIN
+	* servability, crop, dispatch) to the deps-injected pure function in
+	* {@link runStatelessStepImpl}; this method only wires the real deps.
+	*
+	* Note what is NOT wired, deliberately: no `resolveChildSteps` (the step
+	* comes from the catalog, not from an attachment) and no `deviceKey` /
+	* device jump (the jump roster is part of the attach config). The step runs
+	* on the node's default engine, which is exactly the engine
+	* `executionFormat` reports — so the servability check and the dispatch
+	* cannot disagree about which format was verified.
+	*/
+	async runStatelessStep(input) {
+		const convention = await this.cropConvention.refresh(this.ctxIfReady?.api);
+		return runStatelessStep({
+			nodeId: this.nodeId,
+			lookupStep: (stepId) => tryGetStepDefinition(stepId),
+			executionFormat: () => this.resolveNodeExecutionFormat(),
+			resolveCropConvention: () => convention,
+			runPipeline: (steps, imageJpeg, sourceDeviceId) => this.runStatelessPipeline(steps, imageJpeg, sourceDeviceId),
+			logger: this.detailSubtreeLogger()
 		}, input);
 	}
 	/**
+	* The model format this node dispatches on when no `deviceKey` is given —
+	* its selected engine's format. `null` on any failure, which the caller
+	* turns into a refusal rather than a guess: a model pin that cannot be
+	* checked is a substitution waiting to happen.
+	*/
+	async resolveNodeExecutionFormat() {
+		const api = this.ctxIfReady?.api;
+		if (!api) return null;
+		try {
+			return (await api.pipelineExecutor.getSelectedEngine.query()).format;
+		} catch (err) {
+			this.ctxIfReady?.logger.warn("runStatelessStep: could not read this node selected engine — refusing rather than guessing a format", { meta: { error: require_dist.errMsg(err) } });
+			return null;
+		}
+	}
+	/**
+	* Real `runPipeline` dep for the stateless path: node-local
+	* `pipelineExecutor.runPipeline` on the `'full'` plane with NO `deviceKey`.
+	*
+	* `deviceId` is passed so the executor's own gate/substitution lines are
+	* tagged with the source camera. It is a routing hint on other transports,
+	* but not here: the executor is co-located in the `detection` group, so
+	* `localProviderLink` answers in-process before any router sees it — the
+	* call cannot leave the node this one was pinned to.
+	*/
+	async runStatelessPipeline(steps, imageJpeg, sourceDeviceId) {
+		const api = this.ctxIfReady?.api;
+		if (!api) return null;
+		return api.pipelineExecutor.runPipeline.mutate({
+			steps: [...steps],
+			image: new Uint8Array(imageJpeg),
+			deviceId: sourceDeviceId,
+			plane: "full"
+		});
+	}
+	/**
+	* The cluster-wide detail-crop convention — read from the orchestrator's
+	* global settings, NOT from the attach config. See `crop-convention-source.ts`
+	* for why eleven attach builders make the attach config the wrong carrier.
+	*/
+	cropConvention = new CropConventionSource({ logger: {
+		info: (message, extras) => this.ctxIfReady?.logger.info(message, extras),
+		warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras)
+	} });
+	/** A warn sink that survives a not-yet-ready ctx (boot-order dispatches). */
+	detailSubtreeLogger() {
+		return { warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras) };
+	}
+	/**
 	* Step-tree device jump (phase 1) — pick which same-node inference device an
 	* enrichment `step` runs on. AUTO-jumps only when the camera's elected device
 	* cannot run the step's model (its format has no build); an operator