@camstack/types 1.1.41 → 1.1.43

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 { 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,18 @@ export interface DetectionResultPayload {
     readonly capturedAt?: number;
     [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 +157,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;
 }
 /**

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-b4Jf2n33.mjs → sleep-Baang_XW.mjs}

@@ -3408,6 +3408,7 @@ function createDeviceProxy(api, binding, opts) {
 			getMotionEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getMotionEvents", "query", input),
 			getObjectEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getObjectEvents", "query", input),
 			getAudioEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getAudioEvents", "query", input),
+			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),
 			getEventMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMedia", "query", input),
@@ -3625,7 +3626,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-Dqd2OlRi.js → sleep-DmvEGsRg.js}

@@ -3408,6 +3408,7 @@ function createDeviceProxy(api, binding, opts) {
 			getMotionEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getMotionEvents", "query", input),
 			getObjectEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getObjectEvents", "query", input),
 			getAudioEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getAudioEvents", "query", input),
+			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),
 			getEventMedia: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMedia", "query", input),
@@ -3625,7 +3626,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/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.41",
+  "version": "1.1.43",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",