@camstack/types 1.1.42 → 1.1.44

package/dist/interfaces/advanced-notifier.d.ts

@@ -27,6 +27,8 @@ export interface NotificationRule {
             readonly text: string;
             readonly minSimilarity: number;
         };
+        /** Recognized-entity label match (face identity / plate vehicle name). */
+        readonly labels?: readonly string[];
     };
     readonly outputs: readonly string[];
     readonly template?: {

package/dist/interfaces/event-bus.d.ts

@@ -1,5 +1,5 @@
-import type { FrameResult, AudioResult } from '../types/detection.js';
-import type { PipelineExecutionTrace } from '../types/pipeline-step.js';
+import type { FrameResult, AudioResult, ObjectDetection } from '../types/detection.js';
+import type { PipelineExecutionTrace, StepCadence } from '../types/pipeline-step.js';
 import type { MotionRegion } from '../capabilities/motion-detection.cap.js';
 import type { CameraPipelineConfig } from '../types/camera-pipeline.js';
 import type { CameraMetrics } from './api-shared.js';
@@ -120,6 +120,109 @@ export interface DetectionResultPayload {
     readonly capturedAt?: number;
     [key: string]: unknown;
 }
+/**
+ * Enriched frame emitted on `pipeline-analytics.frame-tracked` after
+ * post-analysis detail synthesis. Carries overlay-ready detections:
+ * first-level roots pass through from the inference frame; `kind:'detail'`
+ * entries (face/plate) are SYNTHESIZED per frame from per-track detail
+ * state (two-plane re-injection).
+ */
+export interface PipelineAnalyticsFrameTrackedPayload {
+    readonly deviceId: number;
+    readonly timestamp: number;
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+    readonly detections: readonly ObjectDetection[];
+    [key: string]: unknown;
+}
+/** Lifecycle phase of a tracked object: it appears (`start`), its best
+ *  observation materially improves (`update`), then it ends (`end`). */
+export type TrackLifecyclePhase = 'start' | 'update' | 'end';
+/**
+ * Emitted on `pipeline-analytics.track-lifecycle` at three moments of a
+ * tracked object's life — `phase:'start'` when it first appears,
+ * `phase:'update'` when its best observation MATERIALLY improves (a
+ * clearer/larger frame, a newly-recognized identity or plate), and
+ * `phase:'end'` exactly once when it expires (TTL-gated). One typed
+ * payload shape across phases so a consumer subscribes once and branches
+ * on `phase`. Supersedes the thin `TrackStarted` / `TrackEnded` pair.
+ *
+ * Fields carry the BEST-so-far observation (final at `end`). `media`
+ * addresses the current representative image over HTTP. Telemetry
+ * semantics (D8): a lost event only misses a moment, never a correctness
+ * issue — the durable summary lives in the track store + events.
+ */
+export interface PipelineAnalyticsTrackLifecyclePayload {
+    readonly deviceId: number;
+    readonly trackId: string;
+    readonly phase: TrackLifecyclePhase;
+    /** Per-track observed-class set (deduplicated accumulator). */
+    readonly classes: readonly string[];
+    readonly bestClassName: string;
+    readonly bestConfidence: number;
+    /** Identity name / plate text, when resolved. */
+    readonly label?: string;
+    readonly identityId?: string;
+    readonly plateText?: string;
+    readonly firstSeen: number;
+    readonly lastSeen: number;
+    /** `lastSeen - firstSeen`; ~0 at start, grows over the track's life. */
+    readonly durationMs: number;
+    readonly zonesVisited?: readonly string[];
+    readonly totalDistance?: number;
+    readonly positionsCount?: number;
+    readonly importance?: number;
+    readonly importanceReason?: string;
+    /** The current best image, addressable over HTTP. */
+    readonly media?: {
+        readonly keyFrameMediaKey?: string;
+        readonly bestCropMediaKey?: string;
+        readonly bestEventId?: string;
+    };
+    readonly embeddingId?: string;
+    readonly embeddingModelId?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Emitted on `pipeline-analytics.face-gallery-changed` whenever a gallery
+ * face row changes. `kind:'buffered'` — a new face row was persisted
+ * (`FaceRecognizer.onTrackEnd`); `'assigned'` / `'unassigned'` — the face's
+ * identity link changed (`FaceGalleryProvider.assignFace`/`unassignFace`);
+ * `'deleted'` — the row was removed (`FaceGalleryProvider.deleteFace`).
+ * Telemetry semantics (D8): a lost event only delays a UI refresh, never a
+ * correctness issue. Consumer: `useFaceGalleryLiveRefresh` (admin-ui).
+ */
+export interface PipelineAnalyticsFaceGalleryChangedPayload {
+    readonly deviceId: number;
+    readonly faceId: string;
+    readonly kind: 'buffered' | 'assigned' | 'unassigned' | 'deleted';
+    readonly [key: string]: unknown;
+}
+/**
+ * Emitted when a plate-gallery row changes: `'buffered'` — a new read was
+ * persisted (`PlateRecognizer.onTrackEnd`); `'assigned'`/`'unassigned'` — the
+ * vehicle link changed (`PlateGalleryProvider`); `'deleted'` — the row was
+ * removed. Telemetry (D8): a lost event only delays a UI refresh. Consumer:
+ * `usePlateGalleryLiveRefresh` (admin-ui).
+ */
+export interface PipelineAnalyticsPlateGalleryChangedPayload {
+    readonly deviceId: number;
+    readonly plateId: string;
+    readonly kind: 'buffered' | 'assigned' | 'unassigned' | 'deleted';
+    readonly [key: string]: unknown;
+}
+/**
+ * Child steps enabled for a camera + their scheduling policy, as read
+ * from the pipeline catalog. Announced on `PipelineInferenceResultPayload`
+ * so a track-level consumer knows which detail-subtree steps it can
+ * dispatch via `pipelineRunner.runDetailSubtree` and on what cadence,
+ * without a separate round-trip to the executor's schema/config caps.
+ */
+export interface DetailStepAnnounce {
+    readonly stepId: string;
+    readonly inputClasses: readonly string[];
+    readonly cadence: StepCadence;
+}
 /**
  * Raw inference output emitted by `addon-pipeline-runner` per detection
  * frame. Carries the FrameResult produced by the runner — the hub-side
@@ -145,6 +248,8 @@ export interface PipelineInferenceResultPayload {
      * → delivery latency. Undefined when the frame carried no capture stamp.
      */
     readonly capturedAt?: number;
+    /** Child steps enabled for this camera + their scheduling policy (from the catalog). */
+    readonly detailSteps?: readonly DetailStepAnnounce[];
     readonly [key: string]: unknown;
 }
 /**
@@ -588,6 +693,10 @@ export interface EventCatalog {
     'detection.motion-analysis': MotionAnalysisPayload;
     'detection.motion-zones-raw': MotionZonesRawPayload;
     'motion.on-motion-changed': MotionOnMotionChangedPayload;
+    'pipeline-analytics.frame-tracked': PipelineAnalyticsFrameTrackedPayload;
+    'pipeline-analytics.track-lifecycle': PipelineAnalyticsTrackLifecyclePayload;
+    'pipeline-analytics.face-gallery-changed': PipelineAnalyticsFaceGalleryChangedPayload;
+    'pipeline-analytics.plate-gallery-changed': PipelineAnalyticsPlateGalleryChangedPayload;
     /**
      * On-board detection coming straight from the camera firmware (Reolink
      * AI alarms, ONVIF analytics, etc.) — as opposed to `detection.result`

package/dist/interfaces/pipeline-executor-capability.d.ts

@@ -1,4 +1,5 @@
 import type { PipelineEngineChoice, PipelineConfig } from '../types/pipeline.js';
+import type { PipelineExecutionPlane } from '../types/pipeline-step.js';
 import type { PipelineSchema, PipelineDefaultStep, PipelineTemplateStep, PipelineTemplate } from '../types/pipeline-schema.js';
 import type { ModelFormat } from '../types/models.js';
 import type { FrameInput } from '../types/io.js';
@@ -65,6 +66,14 @@ export interface PipelineRunInput {
      * that omit this field get a generated id.
      */
     readonly sessionId?: string;
+    /**
+     * Execution plane. 'full' (default) runs the whole tree — benchmark,
+     * reference-image, and detail-subtree calls. 'frame' is the live
+     * per-frame dispatch: ONLY root-plane steps run; crop children
+     * (inputClasses ≠ null) are skipped and served per-track via
+     * pipelineRunner.runDetailSubtree (two-plane design).
+     */
+    readonly plane?: PipelineExecutionPlane;
 }
 /**
  * Singleton capability provided by the pipeline-executor addon.

package/dist/interfaces/pipeline-runner-capability.d.ts

@@ -166,4 +166,12 @@ export interface IPipelineRunnerProvider {
     } & CameraMetrics>;
     /** List the deviceIds currently attached to this runner. */
     getLocalCameras(): readonly number[];
+    /**
+     * Two-plane design: run the DETAIL subtree (crop children — embedding,
+     * classifier, refiner steps whose `inputClasses !== null`) for a single
+     * tracked detection. See `pipelineRunnerCapability.runDetailSubtree`
+     * (`capabilities/pipeline-runner.cap.ts`) for full semantics. Returns
+     * `null` when neither `frameHandle` nor `cropJpeg` resolves to a crop.
+     */
+    runDetailSubtree(input: import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeInput): Promise<import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeResult | null>;
 }

package/dist/{sleep-BC9Yqte7.mjs → sleep-DkhOVOjW.mjs}

@@ -474,10 +474,43 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["EnrichmentEmbeddingStored"] = "enrichment.embedding.stored";
 	EventCategory["EnrichmentSceneStateChanged"] = "enrichment.scene.state-changed";
 	EventCategory["EnrichmentActivitySummary"] = "enrichment.activity.summary";
+	/**
+	* Unified track-lifecycle event: ONE category carrying `phase:
+	* 'start' | 'update' | 'end'` with a rich, typed
+	* `PipelineAnalyticsTrackLifecyclePayload`. Supersedes the thin
+	* `PipelineAnalyticsTrackStarted` / `PipelineAnalyticsTrackEnded`
+	* pair — a consumer subscribes once and branches on `phase`.
+	*/
+	EventCategory["PipelineAnalyticsTrackLifecycle"] = "pipeline-analytics.track-lifecycle";
+	/**
+	* @deprecated Superseded by {@link PipelineAnalyticsTrackLifecycle}
+	* (`phase:'start'`). Kept as a soft alias — no known subscribers.
+	*/
 	EventCategory["PipelineAnalyticsTrackStarted"] = "pipeline-analytics.track-started";
+	/**
+	* @deprecated Superseded by {@link PipelineAnalyticsTrackLifecycle}
+	* (`phase:'end'`). Kept as a soft alias — no known subscribers.
+	*/
 	EventCategory["PipelineAnalyticsTrackEnded"] = "pipeline-analytics.track-ended";
 	EventCategory["PipelineAnalyticsDetectionEvent"] = "pipeline-analytics.detection-event";
 	EventCategory["PipelineAnalyticsFrameTracked"] = "pipeline-analytics.frame-tracked";
+	/**
+	* Fired by `addon-post-analysis` whenever a gallery face row changes:
+	* `kind:'buffered'` a new detected face was persisted, `'assigned'` /
+	* `'unassigned'` its identity link changed, `'deleted'` the row was
+	* removed. Telemetry semantics (D8): a lost event only delays a refresh,
+	* never a correctness issue. Payload `PipelineAnalyticsFaceGalleryChangedPayload`.
+	*/
+	EventCategory["PipelineAnalyticsFaceGalleryChanged"] = "pipeline-analytics.face-gallery-changed";
+	/**
+	* Fired by `addon-post-analysis` whenever a gallery plate row changes:
+	* `kind:'buffered'` a new read was persisted (`PlateRecognizer.onTrackEnd`),
+	* `'assigned'` / `'unassigned'` its vehicle link changed
+	* (`PlateGalleryProvider`), `'deleted'` the row was removed. Telemetry
+	* semantics (D8): a lost event only delays a refresh, never a correctness
+	* issue. Payload `PipelineAnalyticsPlateGalleryChangedPayload`.
+	*/
+	EventCategory["PipelineAnalyticsPlateGalleryChanged"] = "pipeline-analytics.plate-gallery-changed";
 	EventCategory["FrigateLiveEvent"] = "frigate.live-event";
 	EventCategory["CameraStreamsProfileSlotsChanged"] = "camera-streams.onProfileSlotsChanged";
 	/**
@@ -3159,6 +3192,7 @@ function createDeviceProxy(api, binding, opts) {
 			pressureSensor: createSliceHandle(stateSource, binding.deviceId, "pressure-sensor"),
 			privacyMask: createSliceHandle(stateSource, binding.deviceId, "privacy-mask"),
 			ptzAutotrack: createSliceHandle(stateSource, binding.deviceId, "ptz-autotrack"),
+			sceneMonitor: createSliceHandle(stateSource, binding.deviceId, "scene-monitor"),
 			scriptRunner: createSliceHandle(stateSource, binding.deviceId, "script-runner"),
 			smoke: createSliceHandle(stateSource, binding.deviceId, "smoke"),
 			streamParams: createSliceHandle(stateSource, binding.deviceId, "stream-params"),
@@ -3411,6 +3445,9 @@ function createDeviceProxy(api, binding, opts) {
 			getKeyEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getKeyEvents", "query", input),
 			getEventDensity: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventDensity", "query", input),
 			pruneEventsBefore: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneEventsBefore", "mutation", input),
+			pruneTracksBefore: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneTracksBefore", "mutation", input),
+			wipeAllAnalytics: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "wipeAllAnalytics", "mutation", input),
+			deleteTracks: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "deleteTracks", "mutation", input),
 			getEventMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMedia", "query", input),
 			getTrackMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getTrackMedia", "query", input),
 			searchObjectEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "searchObjectEvents", "query", input),
@@ -3447,6 +3484,16 @@ function createDeviceProxy(api, binding, opts) {
 			setSettings: (input) => dispatch("ptz-autotrack", "ptzAutotrack", "setSettings", "mutation", input)
 		},
 		reboot: { reboot: (input) => dispatch("reboot", "reboot", "reboot", "mutation", input) },
+		sceneMonitor: {
+			listScenes: (input) => dispatch("scene-monitor", "sceneMonitor", "listScenes", "query", input),
+			createScene: (input) => dispatch("scene-monitor", "sceneMonitor", "createScene", "mutation", input),
+			updateScene: (input) => dispatch("scene-monitor", "sceneMonitor", "updateScene", "mutation", input),
+			deleteScene: (input) => dispatch("scene-monitor", "sceneMonitor", "deleteScene", "mutation", input),
+			captureReference: (input) => dispatch("scene-monitor", "sceneMonitor", "captureReference", "mutation", input),
+			deleteReference: (input) => dispatch("scene-monitor", "sceneMonitor", "deleteReference", "mutation", input),
+			recheckNow: (input) => dispatch("scene-monitor", "sceneMonitor", "recheckNow", "mutation", input),
+			getStatus: (input) => dispatch("scene-monitor", "sceneMonitor", "getStatus", "query", input)
+		},
 		scriptRunner: {
 			run: (input) => dispatch("script-runner", "scriptRunner", "run", "mutation", input),
 			stop: (input) => dispatch("script-runner", "scriptRunner", "stop", "mutation", input),
@@ -3626,7 +3673,8 @@ function createDeviceProxy(api, binding, opts) {
 		},
 		pipelineRunner: {
 			detachCamera: (input) => dispatchSystem("pipelineRunner", "detachCamera", "mutation", input),
-			getCameraMetrics: (input) => dispatchSystem("pipelineRunner", "getCameraMetrics", "query", input)
+			getCameraMetrics: (input) => dispatchSystem("pipelineRunner", "getCameraMetrics", "query", input),
+			runDetailSubtree: (input) => dispatchSystem("pipelineRunner", "runDetailSubtree", "mutation", input)
 		},
 		plateGallery: {
 			listPlates: (input) => dispatchSystem("plateGallery", "listPlates", "query", input),

package/dist/{sleep-ByctZsHo.js → sleep-k6I1e98_.js}

@@ -474,10 +474,43 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["EnrichmentEmbeddingStored"] = "enrichment.embedding.stored";
 	EventCategory["EnrichmentSceneStateChanged"] = "enrichment.scene.state-changed";
 	EventCategory["EnrichmentActivitySummary"] = "enrichment.activity.summary";
+	/**
+	* Unified track-lifecycle event: ONE category carrying `phase:
+	* 'start' | 'update' | 'end'` with a rich, typed
+	* `PipelineAnalyticsTrackLifecyclePayload`. Supersedes the thin
+	* `PipelineAnalyticsTrackStarted` / `PipelineAnalyticsTrackEnded`
+	* pair — a consumer subscribes once and branches on `phase`.
+	*/
+	EventCategory["PipelineAnalyticsTrackLifecycle"] = "pipeline-analytics.track-lifecycle";
+	/**
+	* @deprecated Superseded by {@link PipelineAnalyticsTrackLifecycle}
+	* (`phase:'start'`). Kept as a soft alias — no known subscribers.
+	*/
 	EventCategory["PipelineAnalyticsTrackStarted"] = "pipeline-analytics.track-started";
+	/**
+	* @deprecated Superseded by {@link PipelineAnalyticsTrackLifecycle}
+	* (`phase:'end'`). Kept as a soft alias — no known subscribers.
+	*/
 	EventCategory["PipelineAnalyticsTrackEnded"] = "pipeline-analytics.track-ended";
 	EventCategory["PipelineAnalyticsDetectionEvent"] = "pipeline-analytics.detection-event";
 	EventCategory["PipelineAnalyticsFrameTracked"] = "pipeline-analytics.frame-tracked";
+	/**
+	* Fired by `addon-post-analysis` whenever a gallery face row changes:
+	* `kind:'buffered'` a new detected face was persisted, `'assigned'` /
+	* `'unassigned'` its identity link changed, `'deleted'` the row was
+	* removed. Telemetry semantics (D8): a lost event only delays a refresh,
+	* never a correctness issue. Payload `PipelineAnalyticsFaceGalleryChangedPayload`.
+	*/
+	EventCategory["PipelineAnalyticsFaceGalleryChanged"] = "pipeline-analytics.face-gallery-changed";
+	/**
+	* Fired by `addon-post-analysis` whenever a gallery plate row changes:
+	* `kind:'buffered'` a new read was persisted (`PlateRecognizer.onTrackEnd`),
+	* `'assigned'` / `'unassigned'` its vehicle link changed
+	* (`PlateGalleryProvider`), `'deleted'` the row was removed. Telemetry
+	* semantics (D8): a lost event only delays a refresh, never a correctness
+	* issue. Payload `PipelineAnalyticsPlateGalleryChangedPayload`.
+	*/
+	EventCategory["PipelineAnalyticsPlateGalleryChanged"] = "pipeline-analytics.plate-gallery-changed";
 	EventCategory["FrigateLiveEvent"] = "frigate.live-event";
 	EventCategory["CameraStreamsProfileSlotsChanged"] = "camera-streams.onProfileSlotsChanged";
 	/**
@@ -3159,6 +3192,7 @@ function createDeviceProxy(api, binding, opts) {
 			pressureSensor: createSliceHandle(stateSource, binding.deviceId, "pressure-sensor"),
 			privacyMask: createSliceHandle(stateSource, binding.deviceId, "privacy-mask"),
 			ptzAutotrack: createSliceHandle(stateSource, binding.deviceId, "ptz-autotrack"),
+			sceneMonitor: createSliceHandle(stateSource, binding.deviceId, "scene-monitor"),
 			scriptRunner: createSliceHandle(stateSource, binding.deviceId, "script-runner"),
 			smoke: createSliceHandle(stateSource, binding.deviceId, "smoke"),
 			streamParams: createSliceHandle(stateSource, binding.deviceId, "stream-params"),
@@ -3411,6 +3445,9 @@ function createDeviceProxy(api, binding, opts) {
 			getKeyEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getKeyEvents", "query", input),
 			getEventDensity: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventDensity", "query", input),
 			pruneEventsBefore: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneEventsBefore", "mutation", input),
+			pruneTracksBefore: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneTracksBefore", "mutation", input),
+			wipeAllAnalytics: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "wipeAllAnalytics", "mutation", input),
+			deleteTracks: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "deleteTracks", "mutation", input),
 			getEventMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMedia", "query", input),
 			getTrackMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getTrackMedia", "query", input),
 			searchObjectEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "searchObjectEvents", "query", input),
@@ -3447,6 +3484,16 @@ function createDeviceProxy(api, binding, opts) {
 			setSettings: (input) => dispatch("ptz-autotrack", "ptzAutotrack", "setSettings", "mutation", input)
 		},
 		reboot: { reboot: (input) => dispatch("reboot", "reboot", "reboot", "mutation", input) },
+		sceneMonitor: {
+			listScenes: (input) => dispatch("scene-monitor", "sceneMonitor", "listScenes", "query", input),
+			createScene: (input) => dispatch("scene-monitor", "sceneMonitor", "createScene", "mutation", input),
+			updateScene: (input) => dispatch("scene-monitor", "sceneMonitor", "updateScene", "mutation", input),
+			deleteScene: (input) => dispatch("scene-monitor", "sceneMonitor", "deleteScene", "mutation", input),
+			captureReference: (input) => dispatch("scene-monitor", "sceneMonitor", "captureReference", "mutation", input),
+			deleteReference: (input) => dispatch("scene-monitor", "sceneMonitor", "deleteReference", "mutation", input),
+			recheckNow: (input) => dispatch("scene-monitor", "sceneMonitor", "recheckNow", "mutation", input),
+			getStatus: (input) => dispatch("scene-monitor", "sceneMonitor", "getStatus", "query", input)
+		},
 		scriptRunner: {
 			run: (input) => dispatch("script-runner", "scriptRunner", "run", "mutation", input),
 			stop: (input) => dispatch("script-runner", "scriptRunner", "stop", "mutation", input),
@@ -3626,7 +3673,8 @@ function createDeviceProxy(api, binding, opts) {
 		},
 		pipelineRunner: {
 			detachCamera: (input) => dispatchSystem("pipelineRunner", "detachCamera", "mutation", input),
-			getCameraMetrics: (input) => dispatchSystem("pipelineRunner", "getCameraMetrics", "query", input)
+			getCameraMetrics: (input) => dispatchSystem("pipelineRunner", "getCameraMetrics", "query", input),
+			runDetailSubtree: (input) => dispatchSystem("pipelineRunner", "runDetailSubtree", "mutation", input)
 		},
 		plateGallery: {
 			listPlates: (input) => dispatchSystem("plateGallery", "listPlates", "query", input),

package/dist/types/detection.d.ts

@@ -206,6 +206,18 @@ export interface ObjectDetection extends DetectionBase {
     /** Model id that produced `embedding` (e.g. `arcface-r100`). Present iff
      *  `embedding` is present — lets consumers skip samples from a stale model. */
     readonly embeddingModelId?: string;
+    /**
+     * The EXACT landmark-aligned crop (base64-encoded JPEG) that a face-embedding
+     * step fed to the recognizer for THIS `face` detail — i.e. the literal ArcFace
+     * model input the `embedding` above was computed from. Present iff an aligned
+     * crop was produced (a `faceAlignment` model ran with ≥5 landmarks); absent on
+     * the plain-crop fallback and on non-face detections. Lets a gallery display
+     * the true embedded crop (1:1 with the embedding, for match debugging) instead
+     * of a separately captured natural crop. Small (a 112² JPEG), cheap to carry on
+     * the face detail. Only the `face` detail carries it — it is NOT inherited onto
+     * the parent person (the person box is not the ArcFace input).
+     */
+    readonly faceAlignedCrop?: string;
 }
 /** Audio detection — flat, time-localised within the window. */
 export interface AudioDetection extends DetectionBase {

package/dist/types/models.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { ClassMapDefinition, LabelDefinition } from './labels.js';
-export declare const MODEL_FORMATS: readonly ["onnx", "coreml", "openvino", "tflite", "pt"];
+export declare const MODEL_FORMATS: readonly ["onnx", "coreml", "openvino", "tflite", "pt", "gguf"];
 export type ModelFormat = (typeof MODEL_FORMATS)[number];
 export type ModelOutputFormat = 'yolo' | 'ssd' | 'embedding' | 'classification' | 'ocr' | 'segmentation';
 /**
@@ -93,6 +93,16 @@ export declare const ModelFormatsSchema: z.ZodObject<{
             python: "python";
         }>>>>;
     }, z.core.$strip>>;
+    gguf: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        sizeMB: z.ZodNumber;
+        isDirectory: z.ZodOptional<z.ZodBoolean>;
+        files: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        runtimes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            node: "node";
+            python: "python";
+        }>>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * Variant-selector grouping axes. Shared by the full `ModelCatalogEntry` and by
@@ -171,6 +181,16 @@ export declare const ModelCatalogEntrySchema: z.ZodObject<{
                 python: "python";
             }>>>>;
         }, z.core.$strip>>;
+        gguf: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            sizeMB: z.ZodNumber;
+            isDirectory: z.ZodOptional<z.ZodBoolean>;
+            files: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            runtimes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+                node: "node";
+                python: "python";
+            }>>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     inputSize: z.ZodObject<{
         width: z.ZodNumber;
@@ -312,6 +332,7 @@ export declare const ConvertArtifactSchema: z.ZodObject<{
         openvino: "openvino";
         tflite: "tflite";
         pt: "pt";
+        gguf: "gguf";
     }>;
     precision: z.ZodOptional<z.ZodEnum<{
         int8: "int8";
@@ -378,6 +399,16 @@ export declare const ConvertResultSchema: z.ZodObject<{
                     python: "python";
                 }>>>>;
             }, z.core.$strip>>;
+            gguf: z.ZodOptional<z.ZodObject<{
+                url: z.ZodString;
+                sizeMB: z.ZodNumber;
+                isDirectory: z.ZodOptional<z.ZodBoolean>;
+                files: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                runtimes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+                    node: "node";
+                    python: "python";
+                }>>>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>;
         inputSize: z.ZodObject<{
             width: z.ZodNumber;
@@ -436,6 +467,7 @@ export declare const ConvertResultSchema: z.ZodObject<{
             openvino: "openvino";
             tflite: "tflite";
             pt: "pt";
+            gguf: "gguf";
         }>;
         precision: z.ZodOptional<z.ZodEnum<{
             int8: "int8";

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

@@ -82,6 +82,28 @@ export interface StepDefinition {
      * detected with score ≥ 0.7. Configurable per-step via settings.
      */
     readonly defaultMinParentScore?: number;
+    /**
+     * Detail-subtree dispatch cadence — how often a track-level consumer
+     * should invoke `pipelineRunner.runDetailSubtree` for this step. Only
+     * meaningful for child steps (`inputClasses !== null`); root steps
+     * (object-detection, audio-classifier) run on every frame instead and
+     * ignore this field. Absent on a child step falls back to the catalog
+     * builder's default (`{ trigger: 'once', maxPerTrack: 3 }` — see
+     * `PipelineStepBase` in `addon-pipeline`'s step-definitions.ts).
+     */
+    readonly cadence?: StepCadence;
+}
+/**
+ * Scheduling policy for a detail-subtree step, shared by
+ * `StepDefinition.cadence` (the catalog authority) and
+ * `DetailStepAnnounce.cadence` (the per-camera announce derived from it —
+ * see `interfaces/event-bus.ts`).
+ */
+export interface StepCadence {
+    readonly trigger: 'once' | 'improve' | 'periodic';
+    readonly minIntervalMs?: number;
+    readonly maxPerTrack?: number;
+    readonly stickyOnConfidence?: number;
 }
 export interface PoolModelConfig {
     /** Absolute path to the model file (.mlpackage, .xml, .onnx) */
@@ -158,8 +180,17 @@ export interface MaskOutput {
 /** Discriminated union for step output — use switch(output.kind) */
 export type StepOutput = DetectionsOutput | ClassificationsOutput | EmbeddingOutput | TextOutput | MaskOutput;
 export type TraceVerbosity = 'off' | 'summary' | 'full';
+/**
+ * Execution plane for a pipeline run (two-plane design). `'full'` (default)
+ * runs the whole tree — benchmark, reference-image, and detail-subtree
+ * calls. `'frame'` is the live per-frame dispatch: ONLY root-plane steps
+ * (`StepDefinition.inputClasses === null`) run; crop children are skipped
+ * and served per-track via a separate detail-subtree call instead.
+ */
+export type PipelineExecutionPlane = 'full' | 'frame';
 export interface PipelineRunOptions {
     readonly traceVerbosity?: TraceVerbosity;
+    readonly plane?: PipelineExecutionPlane;
 }
 export interface StepTrace {
     readonly stepId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.1.42",
+  "version": "1.1.44",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",