@camstack/types 1.2.307 → 1.2.309

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

@@ -344,14 +344,20 @@ export interface DetailStepAnnounce {
     readonly inputClasses: readonly string[];
     readonly cadence: StepCadence;
     /**
-     * The root model that already fills this step for this camera (D715): the
-     * model declares the fill and the step's `labelLink` policy lets it be
-     * skipped. A consumer does not dispatch the step for a track whose detection
-     * carries the linked label (`detector-link:<stepId>`); a track without one
-     * (a class the detector cannot name) still gets the step. Absent ⇒ the step
-     * runs as before.
+     * The root model that SUPPLIES this step for this camera (D730): the root
+     * declares it and the step's `useRootModel` flag is on — `resolveRootSupply`
+     * says effective. Absent ⇒ the step runs as before.
      */
     readonly filledBy?: string;
+    /**
+     * How the root supplies it, present with `filledBy`.
+     * - `label`: the root's linked label IS the answer — never dispatched.
+     * - `crop`: the root drew the step's box; the dispatcher sends the box to
+     *   the step's served children (`rootSupplyServes`) and never infers the
+     *   step itself. A step none of whose children are served is not dispatched.
+     * A consumer that predates the field reads `filledBy` alone.
+     */
+    readonly filledAs?: 'label' | 'crop';
 }
 /**
  * Raw inference output emitted by `addon-pipeline-runner` per detection

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

@@ -9,7 +9,7 @@ import type { FrameResult } from '../types/detection.js';
 import type { ConfigUISchema } from './config-ui.js';
 import type { InferenceCapabilities } from './inference-capabilities.js';
 import type { IAddonResolver } from './pipeline-runner.js';
-import { PipelineStepInputSchema, type EngineProvisioning, type NativeCropRef, type PipelineValidationResult } from '../capabilities/pipeline-executor.cap.js';
+import { PipelineStepInputSchema, type EngineProvisioning, type NativeCropRef, type PipelineValidationResult, type SuppliedRootOutput } from '../capabilities/pipeline-executor.cap.js';
 import type { z } from 'zod';
 /**
  * Step configuration for pipeline execution — no runtime/backend (comes
@@ -87,6 +87,11 @@ export interface PipelineRunInput {
      * mutually-exclusive image inputs. Absent ⇒ tile-crop children.
      */
     readonly nativeCropRef?: NativeCropRef;
+    /**
+     * Root-supplied output for the tree's ROOT step (D730) — that step is not
+     * inferred; see `pipelineExecutor.runPipeline.suppliedRoot`.
+     */
+    readonly suppliedRoot?: SuppliedRootOutput;
     /**
      * Offline REPLAY of stored media for `deviceId` (D56, D646). The call runs
      * the camera's structure — its detection-stage zone gate and per-device

package/dist/node.js

@@ -1385,7 +1385,7 @@ var FfmpegProcess = class {
 * Node-only (`node:child_process`), so it lives under `@camstack/types/node`.
 */
 /** The detail a site refusing for want of a binary puts in its refusal. */
-var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node (D540)";
+var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node";
 /**
 * {@link pinnedFfmpegSpawner}, asked at the point of use through the node's
 * resolver (`memoizePinnedFfmpeg`). A site that keeps the RESOLVER rather than

package/dist/node.mjs

@@ -1362,7 +1362,7 @@ var FfmpegProcess = class {
 * Node-only (`node:child_process`), so it lives under `@camstack/types/node`.
 */
 /** The detail a site refusing for want of a binary puts in its refusal. */
-var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node (D540)";
+var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node";
 /**
 * {@link pinnedFfmpegSpawner}, asked at the point of use through the node's
 * resolver (`memoizePinnedFfmpeg`). A site that keeps the RESOLVER rather than

package/dist/pipeline/removed-model-ids.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Model ids DELETED from a step's catalog (D703, D710, D719), per step — and
+ * the one question asked of them: is a stored pin to this id a pin to a model
+ * that no longer exists? (D725)
+ *
+ * This is NOT a resolver input. `resolveModelForFormat` still returns an
+ * unknown id unchanged (a custom model), and a bulk pass pinned to one still
+ * refuses rather than substitutes (D54). The ONE reader is the orchestrator's
+ * stored-pin reset (`removed-model-pin-reset.ts`), which clears such a pin from
+ * the store so the step follows its default again — unless a registered custom
+ * model carries the same id.
+ *
+ * `removed-model-ids.spec.ts` (addon-pipeline) pins that every id here is
+ * really absent from its step's catalog. A model deleted from a catalog is
+ * added here in the same change, or its stored pins stay behind as custom ids.
+ */
+/** `stepId → ids deleted from that step's catalog`. */
+export declare const REMOVED_MODEL_IDS: Readonly<Record<string, readonly string[]>>;
+/** True when `modelId` was deleted from `stepId`'s catalog. */
+export declare function isRemovedModelId(stepId: string, modelId: string): boolean;

package/dist/pipeline/root-face-crop.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The ONE face-scoped crop of a root-supplied face (D731): the rectangle a
+ * root model's `face` box is refined in before it can be recognised.
+ *
+ * A root face box (a Frigate+ `face`) carries no landmarks, and an unaligned
+ * crop must never reach the face embedder (D52: one vector index, one crop
+ * derivation — and the face gallery's derivation is the landmark alignment).
+ * So the box is only a LOCATION: a square around it is cut from the frame's
+ * native surface, the face detector re-finds the face in it — with landmarks —
+ * and the existing alignment takes it from there.
+ *
+ * This is not the detail/CLIP convention (`deriveDetailCropRect`): that one
+ * pads a SUBJECT for an embedder; this one frames a FACE for a detector, at a
+ * scale the detector was measured to find faces at.
+ */
+import type { DetailCropRect } from './detail-crop.js';
+/** Side of the square, as a multiple of the face box's longer side. */
+export declare const ROOT_FACE_REFINE_SCALE = 1.6;
+/**
+ * The input the face detector sees the square at, in pixels. A face that
+ * fills ~60% of a 160 px input is in the detector's measured sweet spot; the
+ * same square fed at 640 puts a ~400 px face in front of a detector whose
+ * largest anchors are far smaller.
+ */
+export declare const ROOT_FACE_REFINE_INPUT_PX = 160;
+/**
+ * The square (frame-space pixels) a root face box is refined in: centred on
+ * the box, side `ROOT_FACE_REFINE_SCALE ×` its longer side, slid inside the
+ * frame, and shrunk only when the frame's shorter side is smaller. Pure.
+ */
+export declare function deriveRootFaceRefineRect(face: DetailCropRect, frameWidth: number, frameHeight: number): DetailCropRect;

package/dist/types/detection.d.ts

@@ -369,6 +369,15 @@ export interface ObjectDetection extends DetectionBase {
      * person box (or a plate back to the vehicle box).
      */
     readonly parentId?: string;
+    /**
+     * A `detail` the ROOT model drew (D730): a Frigate+ `license_plate` / `face`
+     * box contained in its parent, standing in for the named crop step's
+     * inference. Never a track (D683) — only `first-level` entries are.
+     */
+    readonly rootSupplied?: {
+        readonly stepId: string;
+        readonly modelId: string;
+    };
     /**
      * Normalized (L2, ||v||=1) face/biometric embedding produced by an
      * in-pipeline embedding step (arcface, `inputClasses:['face']`). Present on

package/dist/types/models.d.ts

@@ -183,8 +183,19 @@ export declare const ModelLicenseSchema: z.ZodPreprocess<z.ZodObject<{
     nonCommercial: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>>;
 export type ModelLicense = z.infer<typeof ModelLicenseSchema>;
-/** One `fillsClassifierEffects` entry — see `ModelCatalogEntry.fillsClassifierEffects`. */
-export declare const FillsClassifierEffectSchema: z.ZodObject<{
+/**
+ * One step a ROOT detector can supply from its own output (D730) — see
+ * `ModelCatalogEntry.suppliesSteps`.
+ *
+ * - `label`: the root's raw class IS the step's answer. `labelToEffect` maps
+ *   the root's label to the step's vocabulary; `uncovered` is the vocabulary
+ *   the root cannot produce (shown as unavailable, never a blocker).
+ * - `crop`: the root draws the box the step would have found (`license_plate`
+ *   for plate-detection, `face` for face-detection). The box becomes a detail
+ *   child of the `parentMacro` detection that contains it — never a track.
+ */
+export declare const RootStepSupplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"label">;
     stepId: z.ZodEnum<{
         "animal-classifier": "animal-classifier";
         "vehicle-classifier": "vehicle-classifier";
@@ -192,8 +203,24 @@ export declare const FillsClassifierEffectSchema: z.ZodObject<{
     }>;
     labelToEffect: z.ZodRecord<z.ZodString, z.ZodString>;
     uncovered: z.ZodReadonly<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export type FillsClassifierEffect = z.infer<typeof FillsClassifierEffectSchema>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"crop">;
+    stepId: z.ZodEnum<{
+        "plate-detection": "plate-detection";
+        "face-detection": "face-detection";
+    }>;
+    rootLabels: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    parentMacro: z.ZodEnum<{
+        person: "person";
+        vehicle: "vehicle";
+    }>;
+    childClass: z.ZodEnum<{
+        face: "face";
+        plate: "plate";
+    }>;
+    rootInputPx: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export type RootStepSupply = z.infer<typeof RootStepSupplySchema>;
 export declare const ModelCatalogEntrySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -344,7 +371,8 @@ export declare const ModelCatalogEntrySchema: z.ZodObject<{
         }>>;
         preserveOriginal: z.ZodBoolean;
     }, z.core.$strip>>;
-    fillsClassifierEffects: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    suppliesSteps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"label">;
         stepId: z.ZodEnum<{
             "animal-classifier": "animal-classifier";
             "vehicle-classifier": "vehicle-classifier";
@@ -352,7 +380,23 @@ export declare const ModelCatalogEntrySchema: z.ZodObject<{
         }>;
         labelToEffect: z.ZodRecord<z.ZodString, z.ZodString>;
         uncovered: z.ZodReadonly<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"crop">;
+        stepId: z.ZodEnum<{
+            "plate-detection": "plate-detection";
+            "face-detection": "face-detection";
+        }>;
+        rootLabels: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        parentMacro: z.ZodEnum<{
+            person: "person";
+            vehicle: "vehicle";
+        }>;
+        childClass: z.ZodEnum<{
+            face: "face";
+            plate: "plate";
+        }>;
+        rootInputPx: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "kind">>>>;
     clip: z.ZodOptional<z.ZodObject<{
         textModelId: z.ZodString;
         embeddingDim: z.ZodNumber;
@@ -625,7 +669,8 @@ export declare const ConvertResultSchema: z.ZodObject<{
             }>>;
             preserveOriginal: z.ZodBoolean;
         }, z.core.$strip>>;
-        fillsClassifierEffects: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        suppliesSteps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"label">;
             stepId: z.ZodEnum<{
                 "animal-classifier": "animal-classifier";
                 "vehicle-classifier": "vehicle-classifier";
@@ -633,7 +678,23 @@ export declare const ConvertResultSchema: z.ZodObject<{
             }>;
             labelToEffect: z.ZodRecord<z.ZodString, z.ZodString>;
             uncovered: z.ZodReadonly<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"crop">;
+            stepId: z.ZodEnum<{
+                "plate-detection": "plate-detection";
+                "face-detection": "face-detection";
+            }>;
+            rootLabels: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            parentMacro: z.ZodEnum<{
+                person: "person";
+                vehicle: "vehicle";
+            }>;
+            childClass: z.ZodEnum<{
+                face: "face";
+                plate: "plate";
+            }>;
+            rootInputPx: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], "kind">>>>;
         clip: z.ZodOptional<z.ZodObject<{
             textModelId: z.ZodString;
             embeddingDim: z.ZodNumber;

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

@@ -3,6 +3,7 @@ import type { StepModelScope } from '../pipeline/cluster-model-scope.js';
 import type { ClassMapDefinition } from './labels.js';
 import type { ModelCatalogEntry } from './models.js';
 import type { PipelineSlot } from './pipeline.js';
+import type { SuppliedRootOutput } from '../capabilities/pipeline-executor.cap.js';
 /**
  * Each pipeline step implements this interface as a class.
  * `definition` holds the static metadata; `getConfigSchema()` declares
@@ -366,6 +367,11 @@ export interface PipelineRunOptions {
     readonly traceVerbosity?: TraceVerbosity;
     readonly plane?: PipelineExecutionPlane;
     readonly occasion?: PipelineRunOccasion;
+    /**
+     * Root-supplied output for a crop-kind root step (D730,
+     * `pipelineExecutor.runPipeline.suppliedRoot`): that step is not inferred.
+     */
+    readonly suppliedRoot?: SuppliedRootOutput;
 }
 export interface StepTrace {
     readonly stepId: string;

package/package.json

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

package/dist/catalogs/classifier-fill.d.ts

@@ -1,104 +0,0 @@
-/**
- * Detector ↔ step label link — the ONE place that says which pipeline steps a
- * root detector can stand in for, in whose vocabulary, and who writes tier 1.
- *
- * A Frigate+ detector already emits `deer`, `car`, `package`: the effect
- * `animal-classifier`, `vehicle-classifier` and `package-detection` exist to
- * produce. The model DECLARES that (`ModelCatalogEntry.fillsClassifierEffects`,
- * derived here from its labelmap), and the step's own `labelLink` policy says
- * whether the declaration is honoured. Pure — no I/O, no clock.
- */
-import type { FillsClassifierEffect, ModelCatalogEntry } from '../types/models.js';
-/** Steps a root detector may declare it fills. */
-export declare const FILLABLE_STEP_IDS: readonly ["animal-classifier", "vehicle-classifier", "package-detection"];
-export type FillableStepId = (typeof FILLABLE_STEP_IDS)[number];
-/** Narrow a step id to a fillable one — type guard, not a cast. */
-export declare function isFillableStepId(value: string): value is FillableStepId;
-/**
- * The EFFECT vocabulary of each fillable step: exactly the strings the step
- * itself emits, in its own spelling. A linked label is one of these and nothing
- * else, so a tier-1 value means the same thing whichever writer produced it.
- *
- * - `animal-classifier`: the PRIMARY model's `-labels.json` (Open Images V7,
- *   8 classes) — also the species allow-list the step offers.
- * - `vehicle-classifier`: `vehicle-type-v1-labels.json`, capitalised as the
- *   model emits them (the classifier writes `winner.class` verbatim).
- * - `package-detection`: its one output class.
- *
- * `scripts/check-label-link-vocabulary.ts` fails the build if a model entry's
- * `labelToEffect` names anything outside this table.
- */
-export declare const FILLABLE_STEP_VOCABULARIES: Readonly<Record<FillableStepId, readonly string[]>>;
-/** The macro a detection must carry for the step to apply to it. */
-export declare const FILLABLE_STEP_MACRO: Readonly<Record<FillableStepId, string>>;
-/** The policy values of a step's `labelLink` setting. */
-export declare const LABEL_LINK_POLICIES: readonly ["run", "skip-when-filled"];
-export type LabelLinkPolicy = (typeof LABEL_LINK_POLICIES)[number];
-/** Absent setting ⇒ this. It changes nothing unless the root model declares a fill. */
-export declare const DEFAULT_LABEL_LINK_POLICY: LabelLinkPolicy;
-/** The step-settings key the policy is stored under (DeviceStepConfig.settings). */
-export declare const LABEL_LINK_SETTING_KEY = "labelLink";
-/** One fill a root model declares — the catalog schema's own type. */
-export type ClassifierFillDeclaration = FillsClassifierEffect;
-/** `ScoredLabel.stepId` prefix of a label the detector wrote for a step. */
-export declare const LINKED_LABEL_STEP_PREFIX = "detector-link:";
-/** `detector-link:<stepId>` — the attribution of a linked label. */
-export declare function linkedLabelStepId(stepId: FillableStepId): string;
-/** The step a linked label stands in for, or `undefined` for any other attribution. */
-export declare function linkedStepOf(attributionStepId: string | undefined): FillableStepId | undefined;
-/**
- * A labelmap is COCO when it carries at least half of the COCO-80 classes. A
- * COCO detector NEVER fills a step (operator decision, D715): its `dog` / `car`
- * is the generic class the classifier exists to refine, and its six animal
- * classes would otherwise read as "fills animal-classifier 6/8". Frigate+
- * shares about a dozen COCO names; a COCO-80 or COCO-91 labelmap carries ~80.
- */
-export declare function isCocoLabelmap(labels: readonly string[]): boolean;
-/**
- * Which steps a root detector fills, from its labelmap and classMap. A label
- * counts for a step only when the model's classMap sends it to that step's
- * macro AND it names a vocabulary entry. A step none of the labels reach is
- * not declared; a COCO labelmap declares nothing.
- */
-export declare function deriveClassifierFills(labels: readonly string[], classMap: {
-    readonly mapping: Readonly<Record<string, string>>;
-} | undefined): readonly ClassifierFillDeclaration[];
-/** The fill a model declares for one step, if any. */
-export declare function fillFor(entry: Pick<ModelCatalogEntry, 'fillsClassifierEffects'> | undefined, stepId: FillableStepId): ClassifierFillDeclaration | undefined;
-/** Read the `labelLink` policy off a step's settings bag; anything else ⇒ the default. */
-export declare function readLabelLinkPolicy(settings: Readonly<Record<string, unknown>> | undefined): LabelLinkPolicy;
-/** The configured step the decision is about, as the attach tree carries it. */
-export interface LinkedStepState {
-    readonly enabled: boolean;
-    readonly settings?: Readonly<Record<string, unknown>>;
-}
-/** Who writes the step's effect for this camera. */
-export interface LabelLinkDecision {
-    /**
-     * The detector is the ONE writer of this effect: its linked label carries
-     * the detection's score. Otherwise it is written at score 0, a fallback any
-     * scored answer of the step outranks.
-     */
-    readonly authoritative: boolean;
-    /** The step is configured to run and must NOT be dispatched. */
-    readonly skip: boolean;
-    readonly policy: LabelLinkPolicy;
-    /**
-     * Vocabulary entries the detector cannot produce that the step's
-     * `enabledClasses` still asks for (empty allow-list = all). The skip waits
-     * until the operator switches every one of them off.
-     */
-    readonly openGaps: readonly string[];
-}
-/**
- * Decide the writer of one filled effect for one camera.
- *
- * - The step is not running (disabled, or not in the camera's tree): the
- *   detector is the only writer — authoritative, nothing to skip.
- * - The step runs, the policy is `skip-when-filled` and every coverage gap is
- *   switched off in `enabledClasses`: the detector is authoritative and the
- *   step is skipped.
- * - Otherwise the step runs and is the writer; the linked label is a score-0
- *   fallback.
- */
-export declare function resolveLabelLink(fill: ClassifierFillDeclaration, step: LinkedStepState | undefined): LabelLinkDecision;