@camstack/addon-pipeline 1.2.0 → 1.2.2

package/dist/pipeline-runner/index.js

@@ -3,11 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-DWy-H6bo.js");
+const require_dist = require("../dist-CVjqvU8G.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_sheet_geometry = require("../sheet-geometry-BR-ip0CP.js");
-const require_worker_protocol = require("../worker-protocol-PP4jKHHJ.js");
-const require_step_definitions = require("../step-definitions-BQG_6dmZ.js");
+const require_worker_protocol = require("../worker-protocol-DextwlTX.js");
+const require_step_definitions = require("../step-definitions-D76MMwbo.js");
 let node_child_process = require("node:child_process");
 let node_url = require("node:url");
 let sharp = require("sharp");
@@ -1152,6 +1152,17 @@ function summarizeDeviceLoad(attachedDeviceKeys) {
 	})).toSorted((a, b) => a.deviceKey.localeCompare(b.deviceKey));
 }
 //#endregion
+//#region src/pipeline-runner/native-crop-tier.ts
+/**
+* Pure tier decision for `getNativeCrop`. A native HIT always resolves to the
+* native surface. On a native MISS, only a full-frame request falls back to the
+* ≤640 RAM store; an ROI miss is reported as `miss` (no quality masquerade).
+*/
+function resolveNativeCropSource(isFullFrame, nativeHit) {
+	if (nativeHit) return "native";
+	return isFullFrame ? "ram-fullframe" : "miss";
+}
+//#endregion
 //#region src/session-decode/fork-decode-worker.ts
 /**
 * Real `fork` implementation for the session-decode coordinator — Epic C P1,
@@ -1669,11 +1680,18 @@ var SessionDecodeSession = class {
 				});
 				return;
 			case "nativeCropMiss":
+				if (raw.reason !== void 0) this.logger.debug("session-decode: native crop miss", { meta: {
+					requestId: raw.requestId,
+					reason: raw.reason
+				} });
 				this.settleNativeCrop(raw.requestId, null);
 				return;
 			case "error":
 				this.settleError(raw.message, raw.frameId);
 				return;
+			case "log":
+				this.logger[raw.level](raw.message);
+				return;
 		}
 	}
 	handleExit(info) {
@@ -2242,13 +2260,93 @@ async function runDetailSubtree(deps, input) {
 	if (!crop) return null;
 	const details = [];
 	for (const step of steps) {
-		const result = await deps.runPipeline([step], crop.jpeg, input.deviceId);
+		const deviceKey = deps.resolveStepDevice?.(input.deviceId, step);
+		const result = await deps.runPipeline([step], crop.jpeg, input.deviceId, deviceKey);
 		if (!result) continue;
 		for (const detection of result.detections) details.push(toDetailResult(detection, step.addonId, crop));
 	}
 	return { details };
 }
 //#endregion
+//#region src/pipeline-runner/device-jump.ts
+/**
+* Step-tree device jump (same-node, phase 1) — the PURE resolution core.
+*
+* Given the camera's elected ("effective") inference device and the node's
+* enabled-device roster, decide which device ONE enrichment step should run on:
+*
+*   1. A manual `jumpDeviceKey` override wins when it names a candidate that can
+*      run the step (bypasses the auto choice; operator intent).
+*   2. Otherwise, if the effective device's format can run the step's model →
+*      NO jump (the step inherits the effective device — the common case).
+*   3. Otherwise AUTO-jump: among the node's OTHER enabled devices whose format
+*      can run the step (and that are under their `maxSessions` cap), pick the
+*      weighted-least-loaded one — mirroring the balancer's per-device core.
+*   4. If nothing on the node can run it → `no-candidate` (the caller emits the
+*      loud once-per-(camera,step) warn that replaces today's silent degrade).
+*
+* Framework-free + side-effect-free so the whole decision table is unit-testable
+* without a live runner/catalog. The `canRun(format)` predicate is injected by
+* the runner (which owns the model catalog); this module never imports it.
+*/
+/** The `ModelFormat` of a `<backend>:<device>` key, or `undefined` for an unknown backend. */
+function formatOf(deviceKey) {
+	const colon = deviceKey.indexOf(":");
+	return require_dist.DEVICE_BACKEND_TO_FORMAT[colon >= 0 ? deviceKey.slice(0, colon) : deviceKey];
+}
+/** True when the step's model has a build for `deviceKey`'s format. */
+function canRunOn(deviceKey, canRun) {
+	const format = formatOf(deviceKey);
+	return format !== void 0 && canRun(format);
+}
+/** Effective weighted load of a device (session count ÷ weight); lower = preferred. */
+function weightedLoad(d) {
+	return d.attachedCameras / (d.weight > 0 ? d.weight : 1);
+}
+/**
+* Weighted-least-loaded pick with a deterministic `deviceKey` tie-break —
+* mirrors the node/device balancer's decision core (least `load/weight`, ties
+* broken stably). `devices` is assumed non-empty.
+*/
+function pickWeightedLeastLoaded(devices) {
+	return devices.reduce((best, d) => {
+		const dScore = weightedLoad(d);
+		const bScore = weightedLoad(best);
+		if (dScore < bScore) return d;
+		if (dScore > bScore) return best;
+		return d.deviceKey < best.deviceKey ? d : best;
+	});
+}
+/**
+* Resolve the device one enrichment step runs on. See the module header for the
+* decision table. Pure — never throws, no I/O.
+*/
+function resolveStepDevice(input) {
+	const { effectiveDeviceKey, manualJumpDeviceKey, canRun } = input;
+	if (manualJumpDeviceKey !== void 0 && manualJumpDeviceKey !== effectiveDeviceKey) {
+		const target = input.devices.find((d) => d.deviceKey === manualJumpDeviceKey);
+		if (target && canRunOn(target.deviceKey, canRun)) return {
+			kind: "jumped",
+			deviceKey: target.deviceKey,
+			reason: "manual"
+		};
+	}
+	if (canRunOn(effectiveDeviceKey, canRun)) return {
+		kind: "no-jump",
+		deviceKey: effectiveDeviceKey
+	};
+	const runnable = input.devices.filter((d) => d.deviceKey !== effectiveDeviceKey && (d.maxSessions === null || d.attachedCameras < d.maxSessions) && canRunOn(d.deviceKey, canRun));
+	if (runnable.length === 0) return {
+		kind: "no-candidate",
+		deviceKey: effectiveDeviceKey
+	};
+	return {
+		kind: "jumped",
+		deviceKey: pickWeightedLeastLoaded(runnable).deviceKey,
+		reason: "auto"
+	};
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
@@ -3184,31 +3282,77 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		return { success: true };
 	}
 	/**
-	* Best-effort native-resolution crop for a retention-ring frame (native-crop
-	* feature). Looks the handle up in {@link nativeCropRegistry}; a miss (never
-	* registered, or the worker's tiny native ring already evicted the frame)
-	* returns `null` so the caller falls back to a detection-frame crop. The
-	* worker downloads ONLY the ROI — a full native frame never travels the wire.
+	* Native-resolution crop for a retention-ring frame (native-crop feature).
+	* Looks the handle up in {@link nativeCropRegistry}; the worker downloads ONLY
+	* the ROI — a full native frame never travels the wire.
+	*
+	* Tier decision ({@link resolveNativeCropSource}): a native-lease HIT always
+	* wins. On a MISS (never registered, or the worker's tiny native ring already
+	* evicted the frame), an ROI (subject-crop) request returns `null` so the
+	* caller reports the miss and RETRIES — it is NEVER handed the ≤640 detection
+	* raster masquerading as a native crop (Task S1). A full-frame request keeps
+	* the ≤640 RAM `RetainedFrameStore` fallback (blank-frame guard / 640-snapshot
+	* resolve legitimately want the lower-RES honest frame).
 	*/
 	async getNativeCrop(input) {
 		const b = input.bbox;
-		if (!(b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999 && input.maxWidth === void 0)) {
+		const isFullFrame = b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999;
+		const isUnboundedFullFrame = isFullFrame && input.maxWidth === void 0;
+		let nativeResult = null;
+		if (!isUnboundedFullFrame) {
 			const requester = this.nativeCropRegistry.get(input.handle);
 			if (requester) {
 				const result = await requester(input.bbox, input.maxWidth);
-				if (result) return {
+				if (result) nativeResult = {
 					bytes: result.bytes,
 					width: result.width,
 					height: result.height
 				};
 			}
 		}
+		const tier = resolveNativeCropSource(isFullFrame, nativeResult !== null);
+		if (tier === "native" && nativeResult) return this.encodeNativeCropResult(nativeResult, tier, input.encodeJpeg);
+		if (tier !== "ram-fullframe") return null;
 		const crop = this.retainedFrames?.crop(input.handle, input.bbox, input.maxWidth);
-		return crop ? {
+		if (!crop) return null;
+		return this.encodeNativeCropResult({
 			bytes: crop.bytes,
 			width: crop.width,
 			height: crop.height
-		} : null;
+		}, tier, input.encodeJpeg);
+	}
+	/**
+	* Shape a resolved RGB crop into a `getNativeCrop` result. Raw path (default):
+	* return the zero-copy `bytes` — same-node callers encode locally. Compressed
+	* path (`encodeJpeg`, the CROSS-NODE case): encode to JPEG in-process, on the
+	* OWNING node, and return `jpeg` (base64) with NO `bytes` — the payload then
+	* fits Moleculer's `maxPacketSize` and no raw pixels cross the process
+	* boundary (CLAUDE.md invariant #21). On an encode failure the crop is a miss
+	* (`null`) — the caller retries — never a silent raw-RGB cross-node fallback.
+	*/
+	async encodeNativeCropResult(crop, tier, encodeJpeg) {
+		if (encodeJpeg !== true) return {
+			bytes: crop.bytes,
+			width: crop.width,
+			height: crop.height,
+			tier
+		};
+		try {
+			const sharp$3 = (await import("sharp")).default;
+			return {
+				jpeg: (await sharp$3(Buffer.from(crop.bytes), { raw: {
+					width: crop.width,
+					height: crop.height,
+					channels: 3
+				} }).jpeg({ quality: 90 }).toBuffer()).toString("base64"),
+				width: crop.width,
+				height: crop.height,
+				tier
+			};
+		} catch (err) {
+			this.ctx.logger.warn("getNativeCrop: cross-node JPEG encode failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return null;
+		}
 	}
 	/**
 	* Two-plane design: run the DETAIL subtree (crop children) for a single
@@ -3223,10 +3367,72 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		return runDetailSubtree({
 			resolveChildSteps: (deviceId, parentClassName, filter) => this.resolveDetailChildSteps(deviceId, parentClassName, filter),
 			getNativeCrop: (deviceId, handle, paddedBbox) => this.getNativeCropForDetail(deviceId, handle, paddedBbox),
-			runPipeline: (steps, imageJpeg, deviceId) => this.runDetailPipeline(steps, imageJpeg, deviceId)
+			runPipeline: (steps, imageJpeg, deviceId, deviceKey) => this.runDetailPipeline(steps, imageJpeg, deviceId, deviceKey),
+			resolveStepDevice: (deviceId, step) => this.resolveDetailStepDevice(deviceId, step)
 		}, input);
 	}
 	/**
+	* 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
+	* `step.jumpDeviceKey` overrides. Returns the resolved `<backend>:<device>`
+	* key, or `undefined` (⇒ the runner's per-camera default pool) when there is
+	* nothing to route: no elected device, or no jump roster on the attach.
+	*
+	* When NO enabled device on the node can run the step, logs a LOUD warn once
+	* per (camera, step) — killing the historical SILENT per-child degrade (an
+	* `edgetpu` root would otherwise drop faces/plates/clip with no signal).
+	*/
+	resolveDetailStepDevice(deviceId, step) {
+		const config = this.attached.get(deviceId)?.config;
+		const effectiveDeviceKey = config?.deviceKey;
+		if (!effectiveDeviceKey) return void 0;
+		const roster = config?.inferenceDevices;
+		if (!roster || roster.length < 2) return effectiveDeviceKey;
+		const attachedByKey = this.perDeviceAttachedCounts();
+		const devices = roster.map((d) => ({
+			deviceKey: d.deviceKey,
+			weight: d.weight,
+			maxSessions: d.maxSessions,
+			attachedCameras: attachedByKey.get(d.deviceKey) ?? 0
+		}));
+		const def = tryGetStepDefinition(step.addonId);
+		const canRun = (format) => def === null || def.models.some((m) => m.formats[format]);
+		const result = resolveStepDevice({
+			effectiveDeviceKey,
+			devices,
+			...step.jumpDeviceKey !== void 0 ? { manualJumpDeviceKey: step.jumpDeviceKey } : {},
+			canRun
+		});
+		if (result.kind === "no-candidate") this.warnStepHasNoRunnableDevice(deviceId, step.addonId, effectiveDeviceKey);
+		return result.deviceKey;
+	}
+	/** Live attached-camera count per inference `deviceKey` on this runner. */
+	perDeviceAttachedCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const cam of this.attached.values()) {
+			const key = cam.config.deviceKey;
+			if (key === void 0) continue;
+			counts.set(key, (counts.get(key) ?? 0) + 1);
+		}
+		return counts;
+	}
+	/** `${deviceId}:${addonId}` pairs already warned about a no-runnable-device step. */
+	warnedNoJumpDevice = /* @__PURE__ */ new Set();
+	warnStepHasNoRunnableDevice(deviceId, addonId, effectiveDeviceKey) {
+		const key = `${deviceId}:${addonId}`;
+		if (this.warnedNoJumpDevice.has(key)) return;
+		this.warnedNoJumpDevice.add(key);
+		this.ctx?.logger.warn("enrichment step has no runnable inference device on this node — producing NO results for it", {
+			tags: { deviceId },
+			meta: {
+				step: addonId,
+				electedDeviceKey: effectiveDeviceKey,
+				hint: "the elected device format has no build of this step, and no enabled same-node device can run it — enable a compatible accelerator or add a jumpDeviceKey"
+			}
+		});
+	}
+	/**
 	* Real `resolveChildSteps` dep: `null` when the camera isn't attached
 	* (matches the cap doc — "camera not attached" is a distinct case from
 	* "attached but no matching child steps", which returns an empty array
@@ -3248,16 +3454,12 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 	async getNativeCropForDetail(_deviceId, handle, paddedBbox) {
 		const native = await this.getNativeCrop({
 			handle,
-			bbox: paddedBbox
+			bbox: paddedBbox,
+			encodeJpeg: true
 		});
-		if (!native) return null;
-		const sharp$3 = (await import("sharp")).default;
+		if (!native?.jpeg) return null;
 		return {
-			jpeg: await sharp$3(Buffer.from(native.bytes), { raw: {
-				width: native.width,
-				height: native.height,
-				channels: 3
-			} }).jpeg({ quality: 90 }).toBuffer(),
+			jpeg: Buffer.from(native.jpeg, "base64"),
 			width: native.width,
 			height: native.height,
 			frameSpace: denormalizeRect(paddedBbox, handle.width, handle.height)
@@ -3317,10 +3519,10 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		})();
 	}
 	/** Real `runPipeline` dep: node-local `pipelineExecutor.runPipeline` on the `'full'` plane. */
-	async runDetailPipeline(steps, imageJpeg, deviceId) {
+	async runDetailPipeline(steps, imageJpeg, deviceId, stepDeviceKey) {
 		const api = this.ctxIfReady?.api;
 		if (!api) return null;
-		const detailDeviceKey = this.attached.get(deviceId)?.config?.deviceKey;
+		const detailDeviceKey = stepDeviceKey ?? this.attached.get(deviceId)?.config?.deviceKey;
 		try {
 			return await api.pipelineExecutor.runPipeline.mutate({
 				steps: [...steps],
@@ -3397,6 +3599,8 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.thumbSampler?.forget(deviceId);
 		this.packageGovernor.forget(deviceId);
+		const warnPrefix = `${deviceId}:`;
+		for (const key of this.warnedNoJumpDevice) if (key.startsWith(warnPrefix)) this.warnedNoJumpDevice.delete(key);
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);