@camstack/types 1.1.42 → 1.1.43

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-ByctZsHo.js");
+const require_sleep = require("./sleep-DmvEGsRg.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 exports.BaseAddon = require_sleep.BaseAddon;
 exports.DATAPLANE_SECRET_HEADER = require_sleep.DATAPLANE_SECRET_HEADER;

package/dist/addon.mjs

@@ -1,3 +1,3 @@
-import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as EventCategory, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep, xt as DisposerChain } from "./sleep-BC9Yqte7.mjs";
+import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as EventCategory, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep, xt as DisposerChain } from "./sleep-Baang_XW.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 export { BaseAddon, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, ReadinessTimeoutError, adminUiCapability, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, normalizeAddonInitResult, parseJsonUnknown, scopeKey, sleep, viewerUiCapability };

package/dist/capabilities/advanced-notifier.cap.d.ts

@@ -28,9 +28,9 @@ declare const NotificationRuleTemplateSchema: z.ZodObject<{
     body: z.ZodString;
     imageMode: z.ZodEnum<{
         none: "none";
+        full: "full";
         crop: "crop";
         annotated: "annotated";
-        full: "full";
     }>;
 }, z.core.$strip>;
 declare const NotificationRuleSchema: z.ZodObject<{
@@ -67,9 +67,9 @@ declare const NotificationRuleSchema: z.ZodObject<{
         body: z.ZodString;
         imageMode: z.ZodEnum<{
             none: "none";
+            full: "full";
             crop: "crop";
             annotated: "annotated";
-            full: "full";
         }>;
     }, z.core.$strip>>;
     priority: z.ZodEnum<{
@@ -145,9 +145,9 @@ export declare const advancedNotifierCapability: {
                     body: z.ZodString;
                     imageMode: z.ZodEnum<{
                         none: "none";
+                        full: "full";
                         crop: "crop";
                         annotated: "annotated";
-                        full: "full";
                     }>;
                 }, z.core.$strip>>;
                 priority: z.ZodEnum<{
@@ -193,9 +193,9 @@ export declare const advancedNotifierCapability: {
                     body: z.ZodString;
                     imageMode: z.ZodEnum<{
                         none: "none";
+                        full: "full";
                         crop: "crop";
                         annotated: "annotated";
-                        full: "full";
                     }>;
                 }, z.core.$strip>>;
                 priority: z.ZodEnum<{

package/dist/capabilities/index.d.ts

@@ -79,7 +79,7 @@ export type { PipelineStepInputOutput, PipelineValidationIssue, PipelineValidati
 export { ModelSubstitutionSchema, PipelineDefaultStepSchema, PipelineEngineChoiceSchema, PipelineRunResultBridge, PipelineStepInputSchema, PipelineValidationIssueSchema, PipelineValidationResultSchema, pipelineExecutorCapability, } from './pipeline-executor.cap.js';
 export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, IngestOwner, } from './pipeline-orchestrator.cap.js';
 export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusSchema, CapabilityBindingsSchema, GlobalMetricsSchema, IngestOwnerSchema, PipelineAssignmentSchema, pipelineOrchestratorCapability, } from './pipeline-orchestrator.cap.js';
-export type { MotionSource, MotionSources, ReportMotionInput, RunnerFrameSource, } from './pipeline-runner.cap.js';
+export type { DetailParent, DetailResult, MotionSource, MotionSources, ReportMotionInput, RunDetailSubtreeInput, RunDetailSubtreeResult, RunnerFrameSource, } from './pipeline-runner.cap.js';
 export { MotionSourceEnum, MotionSourcesSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
 export { AudioChunkInputSchema, AudioClassificationLabelSchema, AudioLevelSchema, BoundingBoxSchema, FrameInputSchema, SpatialDetectionSchema, } from './schemas/detection-shared.js';
 export { CameraMetricsSchema, CameraMetricsWithDeviceIdSchema, OrchestratorMetricsSchema, } from './schemas/orchestrator-metrics.js';

package/dist/capabilities/pipeline-executor.cap.d.ts

@@ -891,6 +891,10 @@ export declare const pipelineExecutorCapability: {
             referenceImage: z.ZodOptional<z.ZodString>;
             deviceId: z.ZodOptional<z.ZodNumber>;
             sessionId: z.ZodOptional<z.ZodString>;
+            plane: z.ZodOptional<z.ZodEnum<{
+                frame: "frame";
+                full: "full";
+            }>>;
         }, z.core.$strip>, z.ZodCustom<FrameResult, FrameResult>, "mutation">;
         /**
          * Batched run — N raw frames packed into one cap call. The provider

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -21,6 +21,39 @@ export declare const NativeCropResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type NativeCropBbox = z.infer<typeof NativeCropBboxSchema>;
 export type NativeCropCapResult = z.infer<typeof NativeCropResultSchema>;
+/** Parent detection context passed to `runDetailSubtree` — the crop's
+ *  originating detection, in FRAME-space coordinates. Reuses
+ *  `NativeCropBboxSchema`'s `{x,y,w,h}` shape (same numeric fields; here
+ *  the coordinates are frame-space rather than getNativeCrop's
+ *  normalized [0,1] convention). */
+declare const DetailParentSchema: z.ZodObject<{
+    bbox: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>;
+    className: z.ZodString;
+}, z.core.$strip>;
+/** One child-step result from `runDetailSubtree` — an embedding, label,
+ *  or refined detection produced by running the crop-subtree on a
+ *  single tracked detection. */
+declare const DetailResultSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    className: z.ZodString;
+    score: z.ZodNumber;
+    bbox: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>>;
+    embedding: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    alignedCropJpeg: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DetailParent = z.infer<typeof DetailParentSchema>;
+export type DetailResult = z.infer<typeof DetailResultSchema>;
 /**
  * Source enum for motion signals fed to the runner. Extensible — add
  * new variants here when new motion-trigger paths are wired in
@@ -436,7 +469,81 @@ export declare const pipelineRunnerCapability: {
             width: z.ZodNumber;
             height: z.ZodNumber;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Two-plane design: run the DETAIL subtree (crop children —
+         * embedding, classifier, refiner steps whose `inputClasses ≠ null`)
+         * for a single tracked detection. The per-frame plane (`runPipeline`
+         * with `plane: 'frame'`) skips crop children entirely; a track-level
+         * caller invokes this per-track, on its own cadence, instead of on
+         * every frame. Takes either a `frameHandle` (shm lease/session —
+         * preferred, zero-copy) or a `cropJpeg` fallback when the lease/
+         * session backing the frame is already gone. `steps` narrows which
+         * configured children to run (default: all configured children for
+         * `parent.className`). Returns `null` when neither frame source is
+         * resolvable (handle evicted and no cropJpeg fallback supplied).
+         */
+        readonly runDetailSubtree: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            frameHandle: z.ZodOptional<z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>>;
+            cropJpeg: z.ZodOptional<z.ZodString>;
+            parent: z.ZodObject<{
+                bbox: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>;
+                className: z.ZodString;
+            }, z.core.$strip>;
+            steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            details: z.ZodArray<z.ZodObject<{
+                stepId: z.ZodString;
+                className: z.ZodString;
+                score: z.ZodNumber;
+                bbox: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>>;
+                embedding: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                alignedCropJpeg: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>, "mutation">;
     };
 };
 export type IPipelineRunnerProvider = InferProvider<typeof pipelineRunnerCapability>;
+/**
+ * Named input/output types for `runDetailSubtree`, derived from the cap
+ * definition above (`InferProvider`) rather than a standalone exported zod
+ * schema — the method's input stays an INLINE `z.object({...})` literal so
+ * `scripts/lib/parse-cap.ts`'s `deviceBound` regex (which only scans a
+ * method's own inline call body for `deviceId: z.number(`) keeps detecting
+ * it as device-bound and `generate-device-proxy.ts` keeps mounting it on
+ * `DeviceProxy.pipelineRunner`. Extracting the input into a separate named
+ * schema constant (as `RunnerCameraConfigSchema` does for `attachCamera`)
+ * would silently drop it from the device proxy — verified via `npm run
+ * codegen` while implementing this cap.
+ */
+export type RunDetailSubtreeInput = Parameters<IPipelineRunnerProvider['runDetailSubtree']>[0];
+export type RunDetailSubtreeResult = NonNullable<Awaited<ReturnType<IPipelineRunnerProvider['runDetailSubtree']>>>;
 export { RunnerCameraConfigSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema };

package/dist/generated/addon-api.d.ts

@@ -5987,6 +5987,13 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 recognizedIdentityId?: string | undefined;
                 identityName?: string | undefined;
                 base64?: string | undefined;
+                faceBbox?: {
+                    x: number;
+                    y: number;
+                    w: number;
+                    h: number;
+                } | undefined;
+                keyFrameMediaKey?: string | undefined;
             }[];
             meta: object;
         }>;
@@ -6005,6 +6012,13 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 recognizedIdentityId?: string | undefined;
                 identityName?: string | undefined;
                 base64?: string | undefined;
+                faceBbox?: {
+                    x: number;
+                    y: number;
+                    w: number;
+                    h: number;
+                } | undefined;
+                keyFrameMediaKey?: string | undefined;
             } | null;
             meta: object;
         }>;
@@ -9033,6 +9047,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 frameWidth?: number | undefined;
                 frameHeight?: number | undefined;
                 mediaKey?: string | undefined;
+                keyFrameMediaKey?: string | undefined;
                 mediaUrl?: string | undefined;
                 importance?: number | undefined;
             }[];
@@ -9118,11 +9133,11 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             input: {
                 [x: string]: unknown;
                 eventId: string;
-                kind?: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | undefined;
+                kind?: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame" | undefined;
             };
             output: readonly {
                 key: string;
-                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop";
+                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame";
                 base64: string;
                 sizeBytes: number;
                 timestamp: number;
@@ -9136,7 +9151,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             };
             output: readonly {
                 key: string;
-                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop";
+                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame";
                 base64: string;
                 sizeBytes: number;
                 timestamp: number;
@@ -9177,6 +9192,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 frameWidth?: number | undefined;
                 frameHeight?: number | undefined;
                 mediaKey?: string | undefined;
+                keyFrameMediaKey?: string | undefined;
                 mediaUrl?: string | undefined;
                 importance?: number | undefined;
             }[];
@@ -9545,6 +9561,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 referenceImage?: string | undefined;
                 deviceId?: number | undefined;
                 sessionId?: string | undefined;
+                plane?: "full" | "frame" | undefined;
             };
             output: import("@camstack/types").FrameResult;
             meta: object;
@@ -10783,6 +10800,52 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             } | null;
             meta: object;
         }>;
+        runDetailSubtree: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+                deviceId: number;
+                parent: {
+                    bbox: {
+                        x: number;
+                        y: number;
+                        w: number;
+                        h: number;
+                    };
+                    className: string;
+                };
+                frameHandle?: {
+                    shmId: string;
+                    slot: number;
+                    seq: number;
+                    width: number;
+                    height: number;
+                    format: "rgb" | "jpeg" | "bgr" | "yuv420" | "gray";
+                    pts: number;
+                    byteLength: number;
+                    nodeId: string;
+                    slotCount: number;
+                } | undefined;
+                cropJpeg?: string | undefined;
+                steps?: string[] | undefined;
+            };
+            output: {
+                details: {
+                    stepId: string;
+                    className: string;
+                    score: number;
+                    bbox?: {
+                        x: number;
+                        y: number;
+                        w: number;
+                        h: number;
+                    } | undefined;
+                    embedding?: string | undefined;
+                    label?: string | undefined;
+                    alignedCropJpeg?: string | undefined;
+                }[];
+            } | null;
+            meta: object;
+        }>;
     }>>;
     plateGallery: import("@trpc/server").TRPCBuiltRouter<{
         ctx: TrpcContext;
@@ -20967,6 +21030,13 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 recognizedIdentityId?: string | undefined;
                 identityName?: string | undefined;
                 base64?: string | undefined;
+                faceBbox?: {
+                    x: number;
+                    y: number;
+                    w: number;
+                    h: number;
+                } | undefined;
+                keyFrameMediaKey?: string | undefined;
             }[];
             meta: object;
         }>;
@@ -20985,6 +21055,13 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 recognizedIdentityId?: string | undefined;
                 identityName?: string | undefined;
                 base64?: string | undefined;
+                faceBbox?: {
+                    x: number;
+                    y: number;
+                    w: number;
+                    h: number;
+                } | undefined;
+                keyFrameMediaKey?: string | undefined;
             } | null;
             meta: object;
         }>;
@@ -24013,6 +24090,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 frameWidth?: number | undefined;
                 frameHeight?: number | undefined;
                 mediaKey?: string | undefined;
+                keyFrameMediaKey?: string | undefined;
                 mediaUrl?: string | undefined;
                 importance?: number | undefined;
             }[];
@@ -24098,11 +24176,11 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             input: {
                 [x: string]: unknown;
                 eventId: string;
-                kind?: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | undefined;
+                kind?: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame" | undefined;
             };
             output: readonly {
                 key: string;
-                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop";
+                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame";
                 base64: string;
                 sizeBytes: number;
                 timestamp: number;
@@ -24116,7 +24194,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             };
             output: readonly {
                 key: string;
-                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop";
+                kind: "snapshot" | "crop" | "thumbnail" | "firstFrame" | "lastFrame" | "fullFrame" | "fullFrameBoxed" | "faceCrop" | "plateCrop" | "keyFrame";
                 base64: string;
                 sizeBytes: number;
                 timestamp: number;
@@ -24157,6 +24235,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 frameWidth?: number | undefined;
                 frameHeight?: number | undefined;
                 mediaKey?: string | undefined;
+                keyFrameMediaKey?: string | undefined;
                 mediaUrl?: string | undefined;
                 importance?: number | undefined;
             }[];
@@ -24525,6 +24604,7 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
                 referenceImage?: string | undefined;
                 deviceId?: number | undefined;
                 sessionId?: string | undefined;
+                plane?: "full" | "frame" | undefined;
             };
             output: import("@camstack/types").FrameResult;
             meta: object;
@@ -25763,6 +25843,52 @@ export type AppRouter = import("@trpc/server/unstable-core-do-not-import").Route
             } | null;
             meta: object;
         }>;
+        runDetailSubtree: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+                deviceId: number;
+                parent: {
+                    bbox: {
+                        x: number;
+                        y: number;
+                        w: number;
+                        h: number;
+                    };
+                    className: string;
+                };
+                frameHandle?: {
+                    shmId: string;
+                    slot: number;
+                    seq: number;
+                    width: number;
+                    height: number;
+                    format: "rgb" | "jpeg" | "bgr" | "yuv420" | "gray";
+                    pts: number;
+                    byteLength: number;
+                    nodeId: string;
+                    slotCount: number;
+                } | undefined;
+                cropJpeg?: string | undefined;
+                steps?: string[] | undefined;
+            };
+            output: {
+                details: {
+                    stepId: string;
+                    className: string;
+                    score: number;
+                    bbox?: {
+                        x: number;
+                        y: number;
+                        w: number;
+                        h: number;
+                    } | undefined;
+                    embedding?: string | undefined;
+                    label?: string | undefined;
+                    alignedCropJpeg?: string | undefined;
+                }[];
+            } | null;
+            meta: object;
+        }>;
     }>>;
     plateGallery: import("@trpc/server").TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/device-proxy.d.ts

@@ -268,7 +268,7 @@ export interface DeviceProxy {
     readonly networkQuality: Pick<InferDeviceProxyCap<typeof networkQualityCapability>, 'getDeviceStats' | 'reportClientStats'>;
     readonly pipelineExecutor: Pick<InferDeviceProxyCap<typeof pipelineExecutorCapability>, 'runPipeline' | 'runPipelineBatch'>;
     readonly pipelineOrchestrator: Pick<InferDeviceProxyCap<typeof pipelineOrchestratorCapability>, 'assignPipeline' | 'unassignPipeline' | 'getPipelineAssignment' | 'getCameraMetrics' | 'assignAudio' | 'unassignAudio' | 'getAudioAssignment' | 'getAudioAssignments' | 'getCameraSettings' | 'setCameraStepToggle' | 'getCameraStepOverrides' | 'setCameraStepOverride' | 'setCameraPipelineForAgent' | 'resolvePipeline' | 'getCameraStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
-    readonly pipelineRunner: Pick<InferDeviceProxyCap<typeof pipelineRunnerCapability>, 'detachCamera' | 'getCameraMetrics'>;
+    readonly pipelineRunner: Pick<InferDeviceProxyCap<typeof pipelineRunnerCapability>, 'detachCamera' | 'getCameraMetrics' | 'runDetailSubtree'>;
     readonly plateGallery: Pick<InferDeviceProxyCap<typeof plateGalleryCapability>, 'listPlates' | 'getPlateByTrack'>;
     readonly recording: Pick<InferDeviceProxyCap<typeof recordingCapability>, 'getAvailability' | 'getDaysWithRecordings' | 'getPlaybackManifest' | 'getDeviceConfig' | 'locateSegment' | 'readSegmentBytes' | 'setDeviceConfig' | 'rescanStorage' | 'pruneFootage' | 'getStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
     readonly streamBroker: Pick<InferDeviceProxyCap<typeof streamBrokerCapability>, 'publishCameraStream' | 'retractCameraStream' | 'assignProfile' | 'unassignProfile' | 'restartProfile' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 737 method paths across 112 capabilities.
+ * Coverage: 738 method paths across 112 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-ByctZsHo.js");
+const require_sleep = require("./sleep-DmvEGsRg.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");
 //#region src/health/wiring-health.ts
@@ -7880,7 +7880,15 @@ var pipelineExecutorCapability = {
 			image: zod.z.instanceof(Uint8Array).optional(),
 			referenceImage: zod.z.string().optional(),
 			deviceId: zod.z.number().optional(),
-			sessionId: zod.z.string().optional()
+			sessionId: zod.z.string().optional(),
+			/**
+			* 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).
+			*/
+			plane: zod.z.enum(["full", "frame"]).optional()
 		}), PipelineRunResultBridge, { kind: "mutation" }),
 		/**
 		* Batched run — N raw frames packed into one cap call. The provider
@@ -8114,6 +8122,28 @@ var NativeCropResultSchema = zod.z.object({
 	width: zod.z.number().int().positive(),
 	height: zod.z.number().int().positive()
 });
+/** Parent detection context passed to `runDetailSubtree` — the crop's
+*  originating detection, in FRAME-space coordinates. Reuses
+*  `NativeCropBboxSchema`'s `{x,y,w,h}` shape (same numeric fields; here
+*  the coordinates are frame-space rather than getNativeCrop's
+*  normalized [0,1] convention). */
+var DetailParentSchema = zod.z.object({
+	bbox: NativeCropBboxSchema,
+	className: zod.z.string()
+});
+/** One child-step result from `runDetailSubtree` — an embedding, label,
+*  or refined detection produced by running the crop-subtree on a
+*  single tracked detection. */
+var DetailResultSchema = zod.z.object({
+	stepId: zod.z.string(),
+	className: zod.z.string(),
+	score: zod.z.number(),
+	/** FRAME-space bbox (already mapped back from crop space). */
+	bbox: NativeCropBboxSchema.optional(),
+	embedding: zod.z.string().optional(),
+	label: zod.z.string().optional(),
+	alignedCropJpeg: zod.z.string().optional()
+});
 /**
 * Per-camera tunable ranges + defaults. Single source of truth used
 * by both the Zod data schema (validation + default fallback) and
@@ -8557,7 +8587,27 @@ var pipelineRunnerCapability = {
 			handle: require_sleep.FrameHandleSchema,
 			bbox: NativeCropBboxSchema,
 			maxWidth: zod.z.number().int().positive().optional()
-		}), NativeCropResultSchema.nullable())
+		}), NativeCropResultSchema.nullable()),
+		/**
+		* Two-plane design: run the DETAIL subtree (crop children —
+		* embedding, classifier, refiner steps whose `inputClasses ≠ null`)
+		* for a single tracked detection. The per-frame plane (`runPipeline`
+		* with `plane: 'frame'`) skips crop children entirely; a track-level
+		* caller invokes this per-track, on its own cadence, instead of on
+		* every frame. Takes either a `frameHandle` (shm lease/session —
+		* preferred, zero-copy) or a `cropJpeg` fallback when the lease/
+		* session backing the frame is already gone. `steps` narrows which
+		* configured children to run (default: all configured children for
+		* `parent.className`). Returns `null` when neither frame source is
+		* resolvable (handle evicted and no cropJpeg fallback supplied).
+		*/
+		runDetailSubtree: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number(),
+			frameHandle: require_sleep.FrameHandleSchema.optional(),
+			cropJpeg: zod.z.string().optional(),
+			parent: DetailParentSchema,
+			steps: zod.z.array(zod.z.string()).optional()
+		}), zod.z.object({ details: zod.z.array(DetailResultSchema) }).nullable(), { kind: "mutation" })
 	}
 };
 //#endregion
@@ -27025,6 +27075,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.runDetailSubtree": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"plateGallery.correctPlateText": {
 		capName: "plate-gallery",
 		capScope: "system",

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { $ as StreamSourceSchema, A as parseJsonUnknown, B as CamProfileSchema, C as asBoolean, D as asString, E as asNumber, F as readinessKey, G as DecodedFrameSchema, H as CamStreamResolutionSchema, I as scopeKey, J as FrameHandleSchema, K as EncodedPacketSchema, L as BrokerStatsSchema, M as ReadinessRegistry, N as ReadinessTimeoutError, O as parseJsonArray, P as emitDownForOwnedCaps, Q as StreamSourceEntrySchema, R as BrokerStatusSchema, S as DeviceType, T as asJsonObject, U as CameraStreamSchema, V as CamStreamKindSchema, W as DecodedAudioChunkSchema, X as ProfileSlotSchema, Y as ProfileRtspEntrySchema, Z as ProfileSlotStatusSchema, _ as resolveCapMount, _t as collectHydratedFieldValues, a as viewerUiCapability, at as makeSourceBrokerId, b as DeviceFeature, bt as EventCategory, c as createLazyTrpcSource, ct as BaseAddon, d as DEVICE_SETTINGS_CONTRIBUTION_METHODS, dt as createEvent, et as SubscribeAudioChunksInputSchema, f as DEVICE_STATUS_METHOD, ft as emitReadiness, g as method, gt as collectHydratedFieldEntries, h as isDeviceConfigCap, ht as WELL_KNOWN_TAB_MAP, i as deviceOpsCapability, it as makeProfileBrokerId, j as DATAPLANE_SECRET_HEADER, k as parseJsonObject, l as createMirrorSource, lt as normalizeAddonInitResult, m as expandCapMethods, mt as WELL_KNOWN_TABS, n as sleepCancellable, nt as SubscribeFramesInputSchema, o as adminUiCapability, ot as parseProfileBrokerId, p as event, pt as isEvent, q as FrameHandleFormatSchema, r as RawStateResultSchema, rt as SubscribeFramesResultSchema, s as createDeviceProxy, st as selectAssignedProfileSlots, t as sleep, tt as SubscribeAudioChunksResultSchema, u as createSliceHandle, ut as createDurableState, v as systemMethod, vt as hydrateSchema, w as asJsonArray, x as DeviceRole, xt as DisposerChain, y as ChargingStatus, yt as resolveHydratedFieldValue, z as CAM_PROFILE_ORDER } from "./sleep-BC9Yqte7.mjs";
+import { $ as StreamSourceSchema, A as parseJsonUnknown, B as CamProfileSchema, C as asBoolean, D as asString, E as asNumber, F as readinessKey, G as DecodedFrameSchema, H as CamStreamResolutionSchema, I as scopeKey, J as FrameHandleSchema, K as EncodedPacketSchema, L as BrokerStatsSchema, M as ReadinessRegistry, N as ReadinessTimeoutError, O as parseJsonArray, P as emitDownForOwnedCaps, Q as StreamSourceEntrySchema, R as BrokerStatusSchema, S as DeviceType, T as asJsonObject, U as CameraStreamSchema, V as CamStreamKindSchema, W as DecodedAudioChunkSchema, X as ProfileSlotSchema, Y as ProfileRtspEntrySchema, Z as ProfileSlotStatusSchema, _ as resolveCapMount, _t as collectHydratedFieldValues, a as viewerUiCapability, at as makeSourceBrokerId, b as DeviceFeature, bt as EventCategory, c as createLazyTrpcSource, ct as BaseAddon, d as DEVICE_SETTINGS_CONTRIBUTION_METHODS, dt as createEvent, et as SubscribeAudioChunksInputSchema, f as DEVICE_STATUS_METHOD, ft as emitReadiness, g as method, gt as collectHydratedFieldEntries, h as isDeviceConfigCap, ht as WELL_KNOWN_TAB_MAP, i as deviceOpsCapability, it as makeProfileBrokerId, j as DATAPLANE_SECRET_HEADER, k as parseJsonObject, l as createMirrorSource, lt as normalizeAddonInitResult, m as expandCapMethods, mt as WELL_KNOWN_TABS, n as sleepCancellable, nt as SubscribeFramesInputSchema, o as adminUiCapability, ot as parseProfileBrokerId, p as event, pt as isEvent, q as FrameHandleFormatSchema, r as RawStateResultSchema, rt as SubscribeFramesResultSchema, s as createDeviceProxy, st as selectAssignedProfileSlots, t as sleep, tt as SubscribeAudioChunksResultSchema, u as createSliceHandle, ut as createDurableState, v as systemMethod, vt as hydrateSchema, w as asJsonArray, x as DeviceRole, xt as DisposerChain, y as ChargingStatus, yt as resolveHydratedFieldValue, z as CAM_PROFILE_ORDER } from "./sleep-Baang_XW.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 import { z } from "zod";
 //#region src/health/wiring-health.ts
@@ -7879,7 +7879,15 @@ var pipelineExecutorCapability = {
 			image: z.instanceof(Uint8Array).optional(),
 			referenceImage: z.string().optional(),
 			deviceId: z.number().optional(),
-			sessionId: z.string().optional()
+			sessionId: z.string().optional(),
+			/**
+			* 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).
+			*/
+			plane: z.enum(["full", "frame"]).optional()
 		}), PipelineRunResultBridge, { kind: "mutation" }),
 		/**
 		* Batched run — N raw frames packed into one cap call. The provider
@@ -8113,6 +8121,28 @@ var NativeCropResultSchema = z.object({
 	width: z.number().int().positive(),
 	height: z.number().int().positive()
 });
+/** Parent detection context passed to `runDetailSubtree` — the crop's
+*  originating detection, in FRAME-space coordinates. Reuses
+*  `NativeCropBboxSchema`'s `{x,y,w,h}` shape (same numeric fields; here
+*  the coordinates are frame-space rather than getNativeCrop's
+*  normalized [0,1] convention). */
+var DetailParentSchema = z.object({
+	bbox: NativeCropBboxSchema,
+	className: z.string()
+});
+/** One child-step result from `runDetailSubtree` — an embedding, label,
+*  or refined detection produced by running the crop-subtree on a
+*  single tracked detection. */
+var DetailResultSchema = z.object({
+	stepId: z.string(),
+	className: z.string(),
+	score: z.number(),
+	/** FRAME-space bbox (already mapped back from crop space). */
+	bbox: NativeCropBboxSchema.optional(),
+	embedding: z.string().optional(),
+	label: z.string().optional(),
+	alignedCropJpeg: z.string().optional()
+});
 /**
 * Per-camera tunable ranges + defaults. Single source of truth used
 * by both the Zod data schema (validation + default fallback) and
@@ -8556,7 +8586,27 @@ var pipelineRunnerCapability = {
 			handle: FrameHandleSchema,
 			bbox: NativeCropBboxSchema,
 			maxWidth: z.number().int().positive().optional()
-		}), NativeCropResultSchema.nullable())
+		}), NativeCropResultSchema.nullable()),
+		/**
+		* Two-plane design: run the DETAIL subtree (crop children —
+		* embedding, classifier, refiner steps whose `inputClasses ≠ null`)
+		* for a single tracked detection. The per-frame plane (`runPipeline`
+		* with `plane: 'frame'`) skips crop children entirely; a track-level
+		* caller invokes this per-track, on its own cadence, instead of on
+		* every frame. Takes either a `frameHandle` (shm lease/session —
+		* preferred, zero-copy) or a `cropJpeg` fallback when the lease/
+		* session backing the frame is already gone. `steps` narrows which
+		* configured children to run (default: all configured children for
+		* `parent.className`). Returns `null` when neither frame source is
+		* resolvable (handle evicted and no cropJpeg fallback supplied).
+		*/
+		runDetailSubtree: method(z.object({
+			deviceId: z.number(),
+			frameHandle: FrameHandleSchema.optional(),
+			cropJpeg: z.string().optional(),
+			parent: DetailParentSchema,
+			steps: z.array(z.string()).optional()
+		}), z.object({ details: z.array(DetailResultSchema) }).nullable(), { kind: "mutation" })
 	}
 };
 //#endregion
@@ -27024,6 +27074,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineRunner.runDetailSubtree": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"plateGallery.correctPlateText": {
 		capName: "plate-gallery",
 		capScope: "system",

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

@@ -3626,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-ByctZsHo.js → sleep-DmvEGsRg.js}

@@ -3626,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.42",
+  "version": "1.1.43",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",