@camstack/addon-pipeline 1.2.75 → 1.2.77

package/dist/pipeline-runner/index.mjs

@@ -1,6 +1,6 @@
-import { At as string, Ct as boolean, Dt as number, Et as literal, K as pipelineRunnerCapability, M as deriveDetailCropRect, Mt as EventCategory, Ot as object, St as array, Tt as lazy, U as pickDetailCropConvention, W as pickNativeLeaseOverride, dt as createEvent, gt as nodePin, j as defineCustomActions, k as customAction, s as DEFAULT_DETAIL_CROP_CONVENTION, st as BaseAddon, tt as errMsg, u as DEVICE_BACKEND_TO_FORMAT, xt as _enum } from "../dist-T_8jMw7d.mjs";
-import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-XeGmL4xr.mjs";
-import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-SqED7Y9i.mjs";
+import { At as string, Ct as boolean, Dt as number, Et as literal, K as pipelineRunnerCapability, M as deriveDetailCropRect, Mt as EventCategory, Ot as object, St as array, Tt as lazy, U as pickDetailCropConvention, W as pickNativeLeaseOverride, dt as createEvent, gt as nodePin, j as defineCustomActions, k as customAction, s as DEFAULT_DETAIL_CROP_CONVENTION, st as BaseAddon, tt as errMsg, u as DEVICE_BACKEND_TO_FORMAT, xt as _enum } from "../dist-HhcoV-Ky.mjs";
+import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-CqBEWGSZ.mjs";
+import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-BNlLGLBV.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-6oymT_yf.mjs";
 import { i as withDetectionIntent, n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-Ci7RXNGb.mjs";
@@ -2359,13 +2359,36 @@ function summarizeRunnerHardware(hardware, cpuCores = os.cpus().length) {
 * just picked one up — which coincide with motion in the package zone
 * SETTLING (transitioning from moving to still). This governor fires:
 *
-*   - on a **settle edge**: motion was observed, then has been absent for
-*     `settleMs` (kills flicker between motion frames and the "bag briefly
-*     set down then snatched back" case), and
+*   - on a **settle edge**: motion NEAR THE PACKAGE ZONE was observed, then has
+*     been absent for `settleMs` (kills flicker between motion frames and the
+*     "bag briefly set down then snatched back" case). The settle edge opens a
+*     **BURST**, and
 *   - on a **low-cadence safety poll** (`pollIntervalMs`, ~30–60s): a
 *     backstop so a delivery whose motion was never observed (a session-gap
 *     camera that only decodes intermittently) is still eventually caught.
 *
+* ## The burst, and why the poll alone was not enough
+*
+* A parcel appears at the END of a motion episode — the courier walks up, puts
+* it down, walks away. That is a settle edge, and it is the moment we know
+* something MIGHT have been left behind. So the settle edge does not fire one
+* inference, it opens a burst: `burstCount` runs `burstIntervalMs` apart.
+*
+* The poll alone made the downstream promotion criterion unreachable in
+* PRACTICE and the notification useless in LATENCY. One observation per 45s
+* (and on a session-dispatch camera the measured gap was ~2 minutes) meant a
+* parcel needed minutes to accumulate enough evidence to be called parked, if
+* it ever did. The burst supplies the whole evidence chain inside ~20s, so a
+* delivery is reported while the courier is still in the street.
+*
+* The poll stays, unchanged in role: it is the SAFETY NET for the parcel whose
+* motion was never observed at all — a camera that just came up, an occlusion,
+* a missed analyzer frame. It is not the primary path any more.
+*
+* The two feed the SAME downstream round counter (`PackageStillnessTracker`),
+* which is what lets one promotion criterion serve both cadences. That is the
+* relation `scripts/check-package-promotion-satisfiable.ts` enforces.
+*
 * Pure logic with an injected clock (every method takes `now`), mirroring
 * `FrameGovernor` / `recomputeGovernor(now)` — no timers, no `Date.now()`
 * inside, fully unit-testable. Per-device state lives in a Map; the caller
@@ -2384,14 +2407,37 @@ function summarizeRunnerHardware(hardware, cpuCores = os.cpus().length) {
 */
 /** The step id (`PipelineStepInput.addonId`) the governor gates. */
 var PACKAGE_DETECTION_STEP_ID = "package-detection";
+/**
+* Burst: 5 runs, 5s apart — 0s, 5s, 10s, 15s, 20s after the settle edge.
+*
+* Sized against the two downstream numbers it has to satisfy, both pinned by
+* `scripts/check-package-promotion-satisfiable.ts`:
+*
+*  - `PACKAGE_STILLNESS_ROUND_GAP_MS` (5 000) — the spacing must be ≥ this or
+*    the runs collapse into one round;
+*  - `packageDropDwellSec` (15s default) — the burst SPAN
+*    (`(burstCount - 1) × burstIntervalMs` = 20s) must clear the dwell, or the
+*    burst ends before the parcel has been still long enough to count and the
+*    delivery falls back to the poll. 20s over 15s is one whole run of margin,
+*    which is what absorbs a dropped analyzer frame.
+*
+* Cost: 5 extra inferences per motion episode, on cameras with an active
+* package zone only (the caller consults this governor only while the
+* `package-detection` step is in the camera's tree, and the resolver appends
+* that step only for an enabled `package`-stage zone rule).
+*/
 var DEFAULT_MOTION_SETTLE_CONFIG = {
 	settleMs: 3e3,
-	pollIntervalMs: 45e3
+	pollIntervalMs: 45e3,
+	burstCount: 5,
+	burstIntervalMs: 5e3
 };
 var INITIAL_STATE = {
 	lastMotionAt: null,
 	armed: false,
-	lastRunAt: Number.NEGATIVE_INFINITY
+	lastRunAt: Number.NEGATIVE_INFINITY,
+	burstRemaining: 0,
+	burstNextAt: 0
 };
 var NO_RUN = {
 	run: false,
@@ -2417,18 +2463,35 @@ var MotionSettleGovernor = class {
 			this.state.set(sample.deviceId, {
 				lastMotionAt,
 				armed: false,
-				lastRunAt: sample.now
+				lastRunAt: sample.now,
+				burstRemaining: Math.max(0, this.config.burstCount - 1),
+				burstNextAt: sample.now + this.config.burstIntervalMs
 			});
 			return {
 				run: true,
 				reason: "settle"
 			};
 		}
+		if (prev.burstRemaining > 0 && sample.now >= prev.burstNextAt) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed,
+				lastRunAt: sample.now,
+				burstRemaining: prev.burstRemaining - 1,
+				burstNextAt: sample.now + this.config.burstIntervalMs
+			});
+			return {
+				run: true,
+				reason: "burst"
+			};
+		}
 		if (pollReady) {
 			this.state.set(sample.deviceId, {
 				lastMotionAt,
 				armed,
-				lastRunAt: sample.now
+				lastRunAt: sample.now,
+				burstRemaining: prev.burstRemaining,
+				burstNextAt: prev.burstNextAt
 			});
 			return {
 				run: true,
@@ -2438,7 +2501,9 @@ var MotionSettleGovernor = class {
 		this.state.set(sample.deviceId, {
 			lastMotionAt,
 			armed,
-			lastRunAt: prev.lastRunAt
+			lastRunAt: prev.lastRunAt,
+			burstRemaining: prev.burstRemaining,
+			burstNextAt: prev.burstNextAt
 		});
 		return NO_RUN;
 	}
@@ -2452,6 +2517,90 @@ var MotionSettleGovernor = class {
 	}
 };
 //#endregion
+//#region src/pipeline-runner/package-zone-proximity.ts
+/**
+* How much the zone-union box grows on EVERY side, as a fraction of its own
+* width / height.
+*
+* 0.5 means a doormat 271px wide on a 640px frame is approached through a
+* ~135px apron on each side — about one adult's width at that distance, which
+* is the thing being detected: a person standing next to the mat, not on it.
+* Larger and a passer-by on the pavement opens a burst; smaller and the
+* courier who never steps on the mat does not.
+*/
+var PACKAGE_ZONE_DILATION = .5;
+/** Grow a box by {@link PACKAGE_ZONE_DILATION}, clamped to the frame. */
+function dilateZoneBox(box, dilation = PACKAGE_ZONE_DILATION) {
+	const dx = box.w * dilation;
+	const dy = box.h * dilation;
+	const x = Math.max(0, box.x - dx);
+	const y = Math.max(0, box.y - dy);
+	return {
+		x,
+		y,
+		w: Math.min(1, box.x + box.w + dx) - x,
+		h: Math.min(1, box.y + box.h + dy) - y
+	};
+}
+function intersects(a, b) {
+	return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+/**
+* Does any motion region reach the dilated package zone?
+*
+* **Fail-open on unknown geometry.** `zoneUnion === undefined` means the caller
+* has not (or could not) resolve the zones — a cold cache, a failed cap read.
+* It answers "yes, if there is any motion at all", which degrades to exactly
+* the whole-frame behaviour this replaced. The alternative — answering "no" —
+* would let one failed read silence package detection on a camera for as long
+* as the read kept failing, and be indistinguishable from a quiet doorstep.
+* That is the shape of D49, and it has cost this repo real deliveries.
+*/
+function motionNearPackageZone(input) {
+	if (input.regions.length === 0) return false;
+	if (input.zoneUnion === void 0) return true;
+	if (input.frameWidth <= 0 || input.frameHeight <= 0) return true;
+	const target = dilateZoneBox(input.zoneUnion);
+	for (const region of input.regions) if (intersects({
+		x: region.bbox.x / input.frameWidth,
+		y: region.bbox.y / input.frameHeight,
+		w: region.bbox.w / input.frameWidth,
+		h: region.bbox.h / input.frameHeight
+	}, target)) return true;
+	return false;
+}
+/**
+* The bounding box of a set of normalised polygons — the package zone union.
+* Returns `undefined` when there is no usable geometry, which the caller must
+* pass through as "unknown" rather than as an empty zone.
+*/
+function packageZoneUnion(polygons) {
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	let sawPoint = false;
+	for (const polygon of polygons) for (const point of polygon) {
+		sawPoint = true;
+		if (point.x < minX) minX = point.x;
+		if (point.y < minY) minY = point.y;
+		if (point.x > maxX) maxX = point.x;
+		if (point.y > maxY) maxY = point.y;
+	}
+	if (!sawPoint) return void 0;
+	const x = Math.max(0, Math.min(1, minX));
+	const y = Math.max(0, Math.min(1, minY));
+	const w = Math.max(0, Math.min(1, maxX)) - x;
+	const h = Math.max(0, Math.min(1, maxY)) - y;
+	if (w <= 0 || h <= 0) return void 0;
+	return {
+		x,
+		y,
+		w,
+		h
+	};
+}
+//#endregion
 //#region src/pipeline-runner/native-crop-tier.ts
 /**
 * Pure tier decision for `getNativeCrop`. A native HIT always resolves to the
@@ -3829,6 +3978,13 @@ function isUsable(bbox) {
 //#endregion
 //#region src/pipeline-runner/index.ts
 /**
+* How often a device's package zone-union geometry is re-read. An operator
+* redrawing a package zone takes effect within one interval; the read is a
+* cross-addon cap call reached from the per-frame package gate, so it must be
+* throttled to something far slower than the frame rate.
+*/
+var PACKAGE_ZONE_UNION_TTL_MS = 6e4;
+/**
 * Bound on the frames whose cutter is bound but whose result has not come back.
 * A few per camera in flight; the ceiling only catches results that never
 * arrive (shed, inference timeout, detach mid-flight).
@@ -4199,6 +4355,36 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	*/
 	packageGovernor = new MotionSettleGovernor();
 	/**
+	* Frames on which the governor DROPPED `package-detection` since that
+	* device last ran it. The drop is the single most consequential silent
+	* branch in the package chain — it decides the cadence that the whole
+	* downstream promotion criterion has to be satisfiable at — and it logged
+	* nothing at all, so "the parcel was never detected" and "the step never
+	* ran" were indistinguishable in the logs. Counted here and reported on the
+	* transition (first skip) and on every run, never per frame.
+	*/
+	packageGateSkips = /* @__PURE__ */ new Map();
+	/**
+	* Per-device package zone-union box (normalised), the target the motion
+	* proximity test measures against.
+	*
+	* A device MISSING from this map is "unknown", not "no zones" — and unknown
+	* FAILS OPEN in `motionNearPackageZone`, degrading to the whole-frame motion
+	* signal. Resolved off the frame path (on attach, and refreshed on the
+	* package-step gate's own cadence), never inside `runMotionAnalysis`.
+	*/
+	packageZoneUnionByDevice = /* @__PURE__ */ new Map();
+	/** In-flight/last zone-union resolution time per device, so the refresh does
+	*  not stampede the zone caps from the motion path. */
+	packageZoneUnionAt = /* @__PURE__ */ new Map();
+	/**
+	* Whether the last analyzer frame saw motion NEAR the device's package
+	* zones — the boolean the settle-burst governor consumes. Distinct from
+	* `lastAnalyzerDetected` (whole-frame), which is what the phase machine
+	* uses and which must not change meaning.
+	*/
+	lastMotionNearPackageZone = /* @__PURE__ */ new Map();
+	/**
 	* Last positive motion timestamp per device — preserved across the
 	* OFF transition so the motion runtime-state slice keeps a stable
 	* `lastDetectedAt` after the cooldown closes the phase. Cleared on
@@ -4399,6 +4585,10 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		}
 		this.lastAnalyzerDetected.clear();
 		this.packageGovernor.reset();
+		this.packageGateSkips.clear();
+		this.packageZoneUnionByDevice.clear();
+		this.packageZoneUnionAt.clear();
+		this.lastMotionNearPackageZone.clear();
 		for (const deviceId of [...this.onboardAnalyzerTeardownTimers.keys(), ...this.onboardAnalyzerSubs.keys()]) this.clearOnboardAnalyzer(deviceId);
 		if (this.runner) {
 			this.runner.stop();
@@ -5661,6 +5851,10 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.lastMotionFrameAt.delete(deviceId);
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.packageGovernor.forget(deviceId);
+		this.packageGateSkips.delete(deviceId);
+		this.packageZoneUnionByDevice.delete(deviceId);
+		this.packageZoneUnionAt.delete(deviceId);
+		this.lastMotionNearPackageZone.delete(deviceId);
 		const warnPrefix = `${deviceId}:`;
 		for (const key of this.warnedNoJumpDevice) if (key.startsWith(warnPrefix)) this.warnedNoJumpDevice.delete(key);
 		this.attached.delete(deviceId);
@@ -6237,13 +6431,31 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		if (steps.length === 0) return null;
 		let dispatchSteps = steps;
 		if (steps.some((s) => s.addonId === "package-detection" && s.enabled !== false)) {
-			if (!this.packageGovernor.evaluate({
+			this.refreshPackageZoneUnion(deviceId);
+			const motionInZone = this.lastMotionNearPackageZone.get(deviceId) ?? this.lastAnalyzerDetected.get(deviceId) ?? false;
+			const decision = this.packageGovernor.evaluate({
 				deviceId,
-				motionInZone: this.lastAnalyzerDetected.get(deviceId) ?? false,
+				motionInZone,
 				now: Date.now()
-			}).run) {
+			});
+			const skipped = this.packageGateSkips.get(deviceId) ?? 0;
+			if (!decision.run) {
 				dispatchSteps = steps.filter((s) => s.addonId !== PACKAGE_DETECTION_STEP_ID);
+				if (skipped === 0) log.info("package-detection gated off by the motion-settle governor", {
+					tags: { deviceId },
+					meta: { motionInZone: this.lastAnalyzerDetected.get(deviceId) ?? false }
+				});
+				this.packageGateSkips.set(deviceId, skipped + 1);
 				if (dispatchSteps.length === 0) return null;
+			} else {
+				this.packageGateSkips.set(deviceId, 0);
+				log.info("package-detection dispatched by the motion-settle governor", {
+					tags: { deviceId },
+					meta: {
+						reason: decision.reason,
+						framesSkippedSinceLastRun: skipped
+					}
+				});
 			}
 		}
 		let image;
@@ -6292,6 +6504,51 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		}
 		return false;
 	}
+	/**
+	* Refresh a device's package zone-union box, off the caller's path.
+	*
+	* Cross-addon reads go through `ctx.api` (the only cross-addon layer), and
+	* they are RATE-LIMITED per device: this is reached from the per-frame
+	* package gate, and two cap calls per frame would be a self-inflicted load
+	* problem on the exact cameras the feature exists for.
+	*
+	* A FAILED read leaves the mirror untouched (D49): the last-known-good
+	* geometry keeps being used, and a device that has never been read stays
+	* absent from the map, which `motionNearPackageZone` treats as unknown and
+	* fails OPEN on. Nothing here can make package detection quieter.
+	*/
+	refreshPackageZoneUnion(deviceId) {
+		const now = Date.now();
+		if (now - (this.packageZoneUnionAt.get(deviceId) ?? 0) < PACKAGE_ZONE_UNION_TTL_MS) return;
+		this.packageZoneUnionAt.set(deviceId, now);
+		const api = this.ctx.api;
+		if (!api) return;
+		(async () => {
+			try {
+				const [zones, rules] = await Promise.all([api.zones.listZones.query({ deviceId }), api.zoneRules.listRules.query({
+					deviceId,
+					stage: "package"
+				})]);
+				const zoneIds = new Set(rules.filter((r) => r.enabled !== false).flatMap((r) => r.zoneIds));
+				const polygons = zones.filter((z) => zoneIds.has(z.id)).map((z) => z.polygon);
+				const union = packageZoneUnion(polygons);
+				const previous = this.packageZoneUnionByDevice.get(deviceId);
+				this.packageZoneUnionByDevice.set(deviceId, union);
+				if (previous === void 0 && union !== void 0) this.ctx.logger.info("package zone geometry resolved — motion proximity armed", {
+					tags: { deviceId },
+					meta: {
+						zoneUnion: union,
+						zones: polygons.length
+					}
+				});
+			} catch (err) {
+				this.ctx.logger.warn("package zone geometry read failed — motion proximity fails open", {
+					tags: { deviceId },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			}
+		})();
+	}
 	async runMotionAnalysis(deviceId, frame, handle) {
 		const ctx = this.ctx;
 		const runner = this.runner;
@@ -6312,6 +6569,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			});
 			if (!result) return;
 			const detected = result.regions.length > 0;
+			this.lastMotionNearPackageZone.set(deviceId, motionNearPackageZone({
+				regions: result.regions,
+				frameWidth: result.frameWidth,
+				frameHeight: result.frameHeight,
+				zoneUnion: this.packageZoneUnionByDevice.get(deviceId)
+			}));
 			if (detected !== (this.lastAnalyzerDetected.get(deviceId) ?? false)) {
 				this.lastAnalyzerDetected.set(deviceId, detected);
 				if (this.ctx.eventBus) this.ctx.eventBus.emit(createEvent(EventCategory.MotionOnMotionChanged, {