@camstack/types 1.2.17 → 1.2.19

package/dist/{sleep-yfPaamGa.js → sleep-mkNQLVPE.js}

@@ -1,4 +1,4 @@
-const require_event_category = require("./event-category-Cdyife4p.js");
+const require_event_category = require("./event-category-39bpf1r_.js");
 let zod = require("zod");
 //#region src/disposer-chain.ts
 var DisposerChain = class {
@@ -1513,6 +1513,7 @@ var ReadinessRegistry = class {
 	logger;
 	now;
 	generation;
+	verboseDeviceScopeLogs;
 	snapshot = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Set();
 	unsubscribeBus;
@@ -1523,6 +1524,7 @@ var ReadinessRegistry = class {
 		this.logger = options.logger;
 		this.now = options.now ?? (() => Date.now());
 		this.generation = options.generation ?? randomGeneration();
+		this.verboseDeviceScopeLogs = options.verboseDeviceScopeLogs ?? false;
 		this.unsubscribeBus = this.bus.subscribe({ category: "system.ready-state" }, (event) => this.ingest(event.data));
 		this.unsubscribeAgentOffline = this.bus.subscribe({ category: "agent.offline" }, (event) => this.synthesizeDownForNode(event.data.agentId));
 		if (typeof this.bus.getRecent === "function") try {
@@ -1576,9 +1578,16 @@ var ReadinessRegistry = class {
 	* Every applied entry dispatches a one-shot transition to matching
 	* subscriptions so pending `awaitReady` callers unblock without having
 	* to wait for a fresh event.
+	*
+	* Returns the number of records APPLIED (added or advanced). Callers
+	* doing periodic reconciles use this to stay silent when the snapshot
+	* changed nothing — the every-60s "hydrated 1446 record(s)" heartbeat
+	* from every child process was pure noise (≈2 800 lines/hour observed
+	* live on 2026-08-01).
 	*/
 	hydrate(records) {
 		const now = this.now();
+		let applied = 0;
 		for (const record of records) {
 			const key = readinessKey(record.capName, record.scope);
 			const prev = this.snapshot.get(key) ?? null;
@@ -1604,7 +1613,8 @@ var ReadinessRegistry = class {
 				sourceNodeId: record.sourceNodeId
 			};
 			this.snapshot.set(key, hydrated);
-			if (this.logger) this.logger.debug(`readiness: ${record.capName} (${scopeKey(record.scope)}) → ${record.state} (hydrated${prev !== null ? " update" : ""}, gen=${record.generation.slice(0, 6)})`);
+			applied++;
+			this.logPerRecord(record.scope, `readiness: ${record.capName} (${scopeKey(record.scope)}) → ${record.state} (hydrated${prev !== null ? " update" : ""}, gen=${record.generation.slice(0, 6)})`);
 			const transition = {
 				capName: record.capName,
 				scope: record.scope,
@@ -1625,6 +1635,23 @@ var ReadinessRegistry = class {
 				}
 			}
 		}
+		return applied;
+	}
+	/**
+	* Per-record debug line, volume-gated: device-scoped records are logged
+	* only when `verboseDeviceScopeLogs` is set (see the option's doc for
+	* the 21 577-lines-per-boot-minute incident that forced the gate);
+	* node/global records always log. Device lines carry `tags.deviceId`
+	* so they group per-camera (CLAUDE.md logging rule).
+	*/
+	logPerRecord(scope, message) {
+		if (!this.logger) return;
+		if (scope.type === "device") {
+			if (!this.verboseDeviceScopeLogs) return;
+			this.logger.debug(message, { tags: { deviceId: scope.deviceId } });
+			return;
+		}
+		this.logger.debug(message);
 	}
 	/**
 	* True when THIS process is the origin authority for `record` — a
@@ -1799,7 +1826,7 @@ var ReadinessRegistry = class {
 			ts: payload.ts,
 			durationInPrevState
 		};
-		if (this.logger) this.logger.debug(`readiness: ${payload.capName} (${scopeKey(payload.scope)}) → ${payload.state} epoch=${epoch} gen=${payload.generation.slice(0, 6)} (prev ${durationInPrevState}ms)`);
+		this.logPerRecord(payload.scope, `readiness: ${payload.capName} (${scopeKey(payload.scope)}) → ${payload.state} epoch=${epoch} gen=${payload.generation.slice(0, 6)} (prev ${durationInPrevState}ms)`);
 		for (const sub of this.subscriptions) {
 			if (sub.capName !== payload.capName) continue;
 			if (!scopesEqual(sub.scope, payload.scope)) continue;
@@ -1844,7 +1871,7 @@ var ReadinessRegistry = class {
 				ts: now,
 				durationInPrevState
 			};
-			if (this.logger) this.logger.debug(`readiness: ${record.capName} (${scopeKey(record.scope)}) → down (synthesized from agent.offline ${offlineNodeId})`);
+			this.logPerRecord(record.scope, `readiness: ${record.capName} (${scopeKey(record.scope)}) → down (synthesized from agent.offline ${offlineNodeId})`);
 			for (const sub of this.subscriptions) {
 				if (sub.capName !== record.capName) continue;
 				if (!scopesEqual(sub.scope, record.scope)) continue;

package/dist/types/detection.d.ts

@@ -1,4 +1,4 @@
-import type { BoundingBox as EngineBoundingBox, Landmark, FrameInput } from './io.js';
+import type { BoundingBox as EngineBoundingBox, FrameInput, Landmark } from './io.js';
 export interface SpatialDetection {
     readonly class: string;
     readonly originalClass: string;
@@ -248,6 +248,47 @@ export interface AudioDetection extends DetectionBase {
  * avoids an import-level collision.
  */
 export type DetectionEntry = ObjectDetection | AudioDetection;
+/**
+ * Why a POST-NMS box was dropped between the model and the overlay. One code
+ * per drop site — the diagnostic overlay shows the code verbatim, so a new
+ * drop site MUST add its own code here rather than reuse a neighbour's:
+ *  - `class-filter`: class not in the step's `enabledMacroClasses`, or a
+ *    COCO class the `classMap` does not map (both are class-identity drops
+ *    and both count toward the trace's model-saw/kept gap).
+ *  - `below-threshold`: score under the per-macro `minConfidence<Macro>`.
+ *  - `full-frame-guard`: the full-frame phantom guard
+ *    (`pipeline/full-frame-guard.ts`).
+ *  - `zone-gate`: dropped by a detection-stage zone rule AFTER the frame
+ *    result was built (`gateDetectionsByZoneRules`).
+ *
+ * NMS suppression is NOT a reason here: every engine's NMS runs in-process in
+ * the Python pool (`inference_pool.py` postprocessors) and the suppressed set
+ * is destroyed before the boundary — the trace's model-saw count is the only
+ * NMS visibility. A reason that can never fire does not belong in the union.
+ */
+export type DiscardReason = 'class-filter' | 'below-threshold' | 'full-frame-guard' | 'zone-gate';
+/**
+ * A post-NMS box the pipeline dropped before it could reach the overlay /
+ * tracker / events — always carried on `FrameResult.discarded` when a frame
+ * drops at least one box (the discarded set is post-NMS and
+ * post-confidence-floor: a handful of boxes per frame, not the raw
+ * candidate flood, which never leaves the Python pool).
+ *
+ * `bbox` is the executor's `[x1, y1, x2, y2]` tuple in ABSOLUTE
+ * analysis-frame pixels (the same space the executor's drop sites hold) —
+ * consumers normalise against `FrameResult.width`/`height` from the same
+ * frame. Deliberately NOT the survivors' `{x, y, width, height}` object:
+ * the tuple is what every drop site already holds, and the viewer's
+ * `parseDiscardedEvent` accepts it as-is.
+ */
+export interface DiscardedDetection {
+    /** `[x1, y1, x2, y2]` in absolute analysis-frame pixels. */
+    readonly bbox: readonly [number, number, number, number];
+    /** Macro class where the classMap resolves one, else the raw model class. */
+    readonly macroClass: string;
+    readonly score: number;
+    readonly reason: DiscardReason;
+}
 /**
  * Per-frame pipeline result — the canonical container emitted by
  * `pipelineExecutor.runPipeline` (one-shot benchmark + runtime dispatch)
@@ -263,6 +304,13 @@ export interface FrameResult {
     readonly width: number;
     readonly height: number;
     readonly detections: readonly ObjectDetection[];
+    /**
+     * Post-NMS boxes the pipeline dropped on this frame (see
+     * {@link DiscardedDetection}). Always populated when at least one box was
+     * dropped — absent means "nothing dropped", never "empty array". A frame
+     * that drops nothing allocates nothing and puts no field on the wire.
+     */
+    readonly discarded?: readonly DiscardedDetection[];
     readonly debug?: FrameDebug;
 }
 /**

package/dist/types/engine-output.d.ts

@@ -1,23 +1,23 @@
-export interface LetterboxMeta {
-    readonly scale: number;
-    readonly padX: number;
-    readonly padY: number;
-    readonly originalWidth: number;
-    readonly originalHeight: number;
-}
+/**
+ * Output envelope of an inference engine call.
+ *
+ * Every engine is a Python pool (`inference_pool.py`) and postprocessing runs
+ * in-process there — the pool returns a `structured` StepOutput payload. The
+ * former Node.js onnxruntime raw-tensor fields (`tensor` / `tensors` /
+ * `letterbox`) were removed with that path: the platform ships no Node ONNX
+ * runtime.
+ */
 export interface EngineOutput {
-    readonly tensor?: Float32Array;
-    readonly tensors?: Record<string, Float32Array>;
     readonly structured?: Record<string, unknown>;
-    readonly letterbox?: LetterboxMeta;
     readonly inferenceMs: number;
-}
-export interface ModelInputMeta {
-    readonly inputSize: {
-        readonly width: number;
-        readonly height: number;
-    };
-    readonly inputNormalization: 'zero-one' | 'imagenet' | 'none';
-    readonly inputLayout: 'nchw' | 'nhwc';
-    readonly preprocessMode: 'letterbox' | 'resize';
+    /**
+     * Overload shed: the inference pool DELIBERATELY did not run inference for
+     * this frame (the Python pool's per-model in-flight bound, or the TS-side
+     * worker in-flight cap). A shed output carries NO `structured` payload —
+     * consumers skip the frame the way any dropped frame is skipped. It is an
+     * expected flow-control outcome, never an error.
+     */
+    readonly dropped?: true;
+    /** Which bound shed the frame (e.g. `'worker-in-flight-cap'`). */
+    readonly shedReason?: string;
 }

package/dist/types/pipeline-step.d.ts

@@ -1,7 +1,7 @@
-import type { ModelCatalogEntry } from './models.js';
+import type { ConfigField } from '../interfaces/config-ui.js';
 import type { ClassMapDefinition } from './labels.js';
+import type { ModelCatalogEntry } from './models.js';
 import type { PipelineSlot } from './pipeline.js';
-import type { ConfigField } from '../interfaces/config-ui.js';
 /**
  * Each pipeline step implements this interface as a class.
  * `definition` holds the static metadata; `getConfigSchema()` declares

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.17",
+  "version": "1.2.19",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",
@@ -48,7 +48,7 @@
   },
   "camstack": {
     "system": false,
-    "displayName": "CamStack Types",
+    "displayName": "Types",
     "description": "Shared cap definitions, schemas, and runtime contracts. Required at server boot; updating restarts the hub."
   },
   "files": [