@camstack/types 1.2.93 → 1.2.95

package/dist/interfaces/config-ui.d.ts

@@ -81,6 +81,38 @@ export interface ConfigSection {
     readonly fields: readonly ConfigField[];
 }
 export type ConfigField = ConfigTextField | ConfigNumberField | ConfigBooleanField | ConfigSelectField | ConfigMultiSelectField | ConfigTimezoneField | ConfigDateTimeField | ConfigColorField | ConfigPasswordField | ConfigTextAreaField | ConfigSliderField | ConfigTagsField | ConfigGroupField | ConfigSubTabsField | ConfigSeparatorField | ConfigInfoField | ConfigQrCodeField | ConfigObjectArrayField | ConfigEditableArrayField | ConfigModelSelectorField | ConfigStorageLocationField | ConfigProbeField | ConfigButtonField | ConfigPipelineEditorField | ConfigNodeSelectField | ConfigNodeMultiSelectField | ConfigDeviceSelectField | ConfigDeviceMultiSelectField | ConfigWidgetField | ConfigAddonActionSelectField | ConfigAddonActionButtonField | ConfigDeviceActionButtonField;
+/**
+ * Per-MODEL applicability of a pipeline-step setting (D214).
+ *
+ * A step's config schema is static, but whether a knob has any effect depends
+ * on WHICH model the step runs: an NMS IoU threshold means nothing to a model
+ * whose export fuses NMS into the graph (Frigate YOLO-NAS, TFLite SSD), a
+ * per-macro confidence slider is moot for a macro the model's labelmap cannot
+ * produce, and a class allow-list must offer the MODEL's labels, not the
+ * catalog's. Computed server-side (`buildSchemaSlots` → the step's model
+ * union, static + custom registry) and consumed by the step editors, which
+ * disable an inapplicable knob WITH its reason instead of rendering a control
+ * that silently does nothing.
+ *
+ * COMPILE-TIME ONLY on the wire: `ConfigField` crosses the cap boundary via
+ * `z.custom<ConfigField>()` (no stripping), so an addon compiled against this
+ * field runs on hubs whose installed framework predates it — same pattern as
+ * the `yolonas` `PostprocessorType` member (D208).
+ */
+export interface ConfigFieldModelApplicability {
+    /**
+     * modelId → operator-readable reason this knob has NO effect with that
+     * model. The editor disables the control and shows the reason.
+     */
+    readonly inapplicable?: Readonly<Record<string, string>>;
+    /**
+     * modelId → replacement options for select/multiselect fields whose offer
+     * derives from the model's own labelmap (custom models: a class allow-list
+     * must operate on THE MODEL's labels — options from another labelmap build
+     * a filter that can never match).
+     */
+    readonly optionsByModel?: Readonly<Record<string, readonly ConfigOption[]>>;
+}
 export interface ConfigFieldBase {
     readonly key: string;
     readonly label: string;
@@ -92,6 +124,8 @@ export interface ConfigFieldBase {
     readonly default?: unknown;
     readonly span?: 1 | 2 | 3 | 4;
     readonly showWhen?: ConfigCondition;
+    /** Per-model knob applicability — see {@link ConfigFieldModelApplicability}. */
+    readonly modelApplicability?: ConfigFieldModelApplicability;
     /**
      * Save behavior when value changes.
      * - true: save immediately on change (toggles, selects, checkboxes)

package/dist/interfaces/recording-config.d.ts

@@ -111,12 +111,25 @@ export type RecordingBand = z.infer<typeof RecordingBandSchema>;
  * segment is ever finalized and the camera records nothing anyway. At the 10 s
  * default segment length, 30 s leaves room for two full segments. `preBufferSec`
  * is retroactive only — it costs nothing at record time, it merely keeps
- * already-written segments — so it is set to one segment length.
+ * already-written segments.
  *
- * An EXPLICIT `0` is left alone: that is an operator statement, not an omission.
+ * ## Why `preBufferSec` is 15 and not one segment length
+ *
+ * It has to cover the broker's RECORDING pre-roll, which is media handed to the
+ * writer from BEFORE the trigger (D192/D193). If this bound were narrower, the
+ * keep gate would delete the very seconds the ring just supplied — two
+ * authorities disagreeing about the same footage, which is the failure D191 was
+ * written against. It is therefore set to `RECORDING_PRE_ROLL_MAX_MS` (15 s),
+ * the widest window the broker can be configured to serve, so an operator
+ * raising the cluster pre-roll can never walk past the gate silently. The
+ * addon-side guard is
+ * `packages/addon-pipeline/src/recorder/addon/__tests__/band-decision.spec.ts`.
+ *
+ * An EXPLICIT `0` is left alone: that is an operator statement, not an omission,
+ * and it is excluded from that invariant by name.
  */
 export declare const DEFAULT_EVENTS_BAND_BUFFER_SEC: {
-    readonly preBufferSec: 10;
+    readonly preBufferSec: 15;
     readonly postBufferSec: 30;
 };
 export type DefaultEventsBandBufferSec = typeof DEFAULT_EVENTS_BAND_BUFFER_SEC;

package/dist/pipeline/cluster-model-scope.d.ts

@@ -0,0 +1,108 @@
+/**
+ * How a step's model is chosen.
+ *
+ *  - `'node'` — per (node, device). Free to differ across the fleet.
+ *  - `'cluster'` — ONE value for the whole cluster. The step writes into a
+ *    shared vector index, so two values would put two incomparable feature
+ *    spaces in it with nothing in the data to show it.
+ *
+ * Absent on a {@link import('../types/pipeline-step.js').StepDefinition} means
+ * `'node'`, which is the safe reading: a step that never declared a scope has
+ * never had a cluster-wide row to read.
+ */
+export type StepModelScope = 'node' | 'cluster';
+/** One selectable model for a cluster-scoped step. */
+export interface ClusterModelOption {
+    readonly id: string;
+    readonly label: string;
+}
+/** One cluster-scoped step, as every non-pipeline package sees it. */
+export interface ClusterModelScopedStep {
+    readonly stepId: string;
+    /** Operator-facing label for the settings row. */
+    readonly label: string;
+    /**
+     * The model in force when nobody has chosen — the step's catalog
+     * `defaultModelId`, so declaring the scope is behaviour-neutral.
+     */
+    readonly defaultModelId: string;
+    /** The index a change invalidates, named in the operator-facing description. */
+    readonly indexName: string;
+    /**
+     * The choosable models, mirrored from the step's catalog (non-`legacy`
+     * entries) and guarded by `scripts/check-cluster-model-scope.ts`.
+     *
+     * Mirrored rather than derived because the orchestrator renders this dropdown
+     * and may not import an addon. A free-text field would have been less code
+     * and strictly worse: a typo there is not a validation error, it is a model
+     * that every node refuses, cluster-wide, and the symptom is "recognition
+     * stopped" with no bad value in sight.
+     */
+    readonly options: readonly ClusterModelOption[];
+}
+/**
+ * The cluster-scoped steps. Mirrored from the catalog's `modelScope: 'cluster'`
+ * declarations and guarded by `scripts/check-cluster-model-scope.ts`.
+ */
+export declare const CLUSTER_MODEL_SCOPED_STEPS: readonly ClusterModelScopedStep[];
+/**
+ * Store identity of the cluster row inside `pipeline-orchestrator`'s GLOBAL
+ * (cluster-wide) settings — the same owner, and for the same reason, as the
+ * detail-crop convention: hub-resident and neutral between the addons that
+ * read it.
+ */
+export declare const CLUSTER_MODEL_SECTION_ID = "cluster-step-models";
+/**
+ * The settings key holding one step's cluster model choice.
+ *
+ * Step-qualified so the keys stay unique across the addon's whole schema, which
+ * is what lets {@link pickClusterStepModels} walk every section instead of
+ * trusting the section id.
+ */
+export declare function clusterModelSettingKey(stepId: string): string;
+/** True when this step's model is a cluster-wide choice rather than a per-node one. */
+export declare function isClusterScopedStep(stepId: string): boolean;
+/** `stepId → modelId` for every cluster-scoped step. Total: never missing a key. */
+export type ClusterStepModels = Readonly<Record<string, string>>;
+/** The cluster row when nobody has configured one — today's catalog defaults. */
+export declare const DEFAULT_CLUSTER_STEP_MODELS: ClusterStepModels;
+/**
+ * Narrow a FLAT settings record to the cluster row.
+ *
+ * Per-FIELD fallback, deliberately (same rule as `readDetailCropConvention`): a
+ * junk face model must not also discard a valid clip model. An absent, empty or
+ * non-string value resolves to the step's catalog default — the historical
+ * behaviour — never to a blank id, because a blank id downstream becomes
+ * "substitute the format default", which is precisely the substitution this
+ * scope exists to forbid.
+ */
+export declare function readClusterStepModels(config: Readonly<Record<string, unknown>>): ClusterStepModels;
+/** One section of an `addon-settings.getGlobalSettings` payload. */
+export interface HydratedClusterSection {
+    readonly fields: readonly unknown[];
+}
+/**
+ * Minimal structural view of `ConfigUISchemaWithValues` — only what this walk
+ * needs. Structural on purpose: the readers are addons that must not depend on
+ * the writer's schema type.
+ */
+export interface HydratedClusterView {
+    readonly sections: readonly HydratedClusterSection[];
+}
+/**
+ * Extract the cluster row from an `addon-settings.getGlobalSettings` payload.
+ *
+ * Walks EVERY section rather than looking inside {@link CLUSTER_MODEL_SECTION_ID}
+ * alone: the keys are unique across the addon's schema, and a section rename
+ * must not silently revert the whole cluster to the defaults. A `null` payload
+ * (addon mid-boot) is the defaults.
+ */
+export declare function pickClusterStepModels(view: HydratedClusterView | null): ClusterStepModels;
+/**
+ * The cluster model for `stepId`, or `null` when the step is node-scoped.
+ *
+ * `null` is the signal to LEAVE THE CALLER'S RESOLUTION ALONE — it is not "no
+ * model". Returning a default here for a node-scoped step would quietly
+ * override every per-(node,device) selection in the fleet.
+ */
+export declare function resolveClusterStepModelId(stepId: string, models: ClusterStepModels): string | null;

package/dist/pipeline/detail-crop.d.ts

@@ -95,6 +95,25 @@ export interface HydratedSettingsView {
  * (addon mid-boot) is the default convention.
  */
 export declare function pickDetailCropConvention(view: HydratedSettingsView | null): DetailCropConvention;
+/**
+ * The normalised box that means "the image IS the subject".
+ *
+ * Used when the stored pixels are ALREADY the model's input — the 112×112
+ * aligned face template a gallery sample carries. There is no rectangle left to
+ * choose, and the convention must not choose one: re-detecting and re-aligning
+ * over a template applies a SECOND warp, passes every gate, and produces a
+ * plausible useless vector (session 2026-08-20 §3).
+ *
+ * Sending it as the whole frame with this box is exact rather than merely
+ * convenient, and the reason is a property of {@link deriveDetailCropRect}, not
+ * a coincidence: padding a full-frame box can only push OUTSIDE the frame, and
+ * both edge modes bring it straight back — unsquared truncates, squared cannot
+ * exceed the frame's short side and then slides inside. So for a SQUARE image
+ * the derivation is the identity under every convention value, and an operator
+ * changing the crop margin cannot silently re-cut an enrolled template.
+ * `face-reembed-pass.spec.ts` asserts that identity against the real function.
+ */
+export declare const FULL_IMAGE_BBOX: DetailCropRect;
 /** Slider bounds for the operator-facing padding knob (orchestrator settings UI). */
 export declare const DETAIL_CROP_PADDING_FIELD: {
     readonly min: 0;

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

@@ -1,4 +1,5 @@
 import type { ConfigField } from '../interfaces/config-ui.js';
+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';
@@ -12,7 +13,7 @@ export interface IPipelineStep {
     readonly definition: StepDefinition;
     getConfigSchema(): readonly ConfigField[];
 }
-export type PostprocessorType = 'yolo' | 'ssd' | 'rfdetr' | 'yolo-seg' | 'scrfd' | 'arcface' | 'clip' | 'softmax' | 'ctc' | 'saliency' | 'yamnet';
+export type PostprocessorType = 'yolo' | 'ssd' | 'rfdetr' | 'yolonas' | 'yolo-seg' | 'scrfd' | 'arcface' | 'clip' | 'softmax' | 'ctc' | 'plate-slots' | 'saliency' | 'yamnet';
 export interface StepDefinition {
     /** Unique step identifier (e.g., 'object-detection', 'face-detection') */
     readonly id: string;
@@ -75,6 +76,27 @@ export interface StepDefinition {
      * duplicating the step definition per engine.
      */
     readonly defaultModelIdByFormat?: Readonly<Record<string, string>>;
+    /**
+     * WHOSE choice this step's model is — see
+     * [`pipeline/cluster-model-scope.ts`](../pipeline/cluster-model-scope.ts).
+     *
+     *  - `'node'` (the default when absent) — per (node, device). Two nodes may
+     *    answer differently because nothing compares their outputs: a box is a
+     *    box.
+     *  - `'cluster'` — ONE value for the whole cluster, stored in ONE
+     *    `pipeline-orchestrator` global row. Declared by a step that writes into a
+     *    SHARED VECTOR INDEX (`face-embedding` → the enrolled gallery,
+     *    `clip-embedding` → `vec_object_clip`), where a second model does not
+     *    degrade the ranking, it makes it meaningless — and nothing inside a
+     *    vector can reveal which encoder produced it.
+     *
+     * A `'cluster'` declaration changes the RESOLUTION RULE, not just the storage:
+     * a node whose format ships no build of the chosen model REFUSES the step and
+     * logs it, where a node-scoped step would substitute that format's default
+     * ([D54](../../../../docs/decisions/adr-0056.md)). Substituting is what fills
+     * one index from several encoders.
+     */
+    readonly modelScope?: StepModelScope;
     /**
      * Whether a newly-seeded agent has this addon enabled by default.
      * Absent = `true`. Operators can always toggle this after boot; this
@@ -135,6 +157,14 @@ export interface StepDefinition {
      * `DEFAULT_MIN_TEXT_CONFIDENCE` (0, disabled).
      */
     readonly minTextConfidence?: number;
+    /**
+     * Plausibility gate for a FIXED-SLOT plate reader (`plate-slots`): the
+     * minimum probability the WEAKEST emitted character must carry. It replaces
+     * {@link minTextLength}, which carries no information for a reader that emits
+     * a full-length string on every input including a blank wall. Forwarded to
+     * the Python postprocessor; absent ⇒ its `DEFAULT_MIN_CHAR_PROBABILITY`.
+     */
+    readonly minCharProbability?: number;
     /** COCO-to-macro class mapping (e.g., 'car' → 'vehicle') */
     readonly classMap?: ClassMapDefinition;
     /** UI grouping label — steps with the same group are displayed together (e.g., 'Segmentation') */
@@ -234,6 +264,11 @@ export interface PoolModelConfig {
     readonly minTextLength?: number;
     /** Plate-OCR plausibility gate: confidence floor. */
     readonly minTextConfidence?: number;
+    /**
+     * Fixed-slot plate-OCR gate: minimum per-character probability. See
+     * {@link StepDefinition.minCharProbability}.
+     */
+    readonly minCharProbability?: number;
     /** Number of classes (for YOLO: 80 COCO or 1 for plate) */
     readonly numClasses?: number;
     /** Anchor strides for SCRFD (default [8, 16, 32]) */

package/package.json

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