@camstack/types 1.2.316 → 1.2.318

package/dist/pipeline/best-settings/recommend.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The Best settings recommender (D745): one detector per node, from ONE family
+ * (YOLOv9) for the whole cluster, chosen from static hardware facts × the
+ * measured latency table × the node's detection demand. Pure; no benchmark.
+ *
+ * Per node:
+ *  1. Classify the hardware (`classifyInferenceHardware`). An unknown class,
+ *     an offline node or a node with nothing to recommend is left untouched.
+ *  2. The node's ACCELERATORS (NPU, iGPU, Neural Engine) that are enabled and
+ *     available share ONE model — so a camera's floors never flip with the
+ *     device the balancer rotated it onto. A candidate must have a build for
+ *     every accelerator's format and a latency cell for each.
+ *  3. A candidate FITS a device when its throughput, less the headroom, covers
+ *     the device's demand and the single fastest camera that can land on it.
+ *  4. Among candidates that fit everywhere, the most accurate wins (person
+ *     recall at the shipped floor); within `RECALL_TIE` of the best, the
+ *     fastest wins. That IS the step-down order the data gives: the first
+ *     variant down from m-640 is s-640-int8, not m-320.
+ *  5. An enabled CPU device (the fallback pool) gets its own pick the same
+ *     way; a Coral is never touched (no YOLOv9 build), only reported.
+ */
+import type { HardwareInfo } from '../../interfaces/platform.js';
+import type { ModelFormat } from '../../types/models.js';
+import { type DetectorPerfTable } from './detector-performance.js';
+import type { DeviceDemand, NodeRecommendation } from './plan-schemas.js';
+/** The family the cluster runs. */
+export declare const BEST_SETTINGS_FAMILY = "yolov9";
+/** Recall within this of the best counts as a tie — the faster one wins. */
+export declare const RECALL_TIE = 0.02;
+/** Default share of an accelerator's throughput kept free. */
+export declare const DEFAULT_HEADROOM = 0.4;
+/** One device of a node, as the recommender reads it. */
+export interface BestSettingsDeviceInput {
+    readonly key: string;
+    readonly format: ModelFormat;
+    readonly enabled: boolean;
+    readonly available: boolean;
+}
+/** One node, as the recommender reads it. */
+export interface BestSettingsNodeInput {
+    readonly nodeId: string;
+    readonly reachable: boolean;
+    readonly hardware: HardwareInfo | null;
+    readonly devices: readonly BestSettingsDeviceInput[];
+    /** Object-detection model id → the formats it has a build for, from the node's catalog. */
+    readonly formatsByModel: Readonly<Record<string, readonly ModelFormat[]>>;
+}
+/** Recommend one node. See the module header. */
+export declare function recommendNode(input: {
+    readonly node: BestSettingsNodeInput;
+    readonly demand: readonly DeviceDemand[];
+    readonly headroom?: number;
+    readonly perf?: DetectorPerfTable;
+}): NodeRecommendation;

package/dist/pipeline/load-balancing/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load balancing (D748): the share placement policy for detection sessions
+ * and the shapes of its admin surface. See `share-election.ts`.
+ */
+export * from './share-election.js';
+export * from './schemas.js';

package/dist/pipeline/load-balancing/schemas.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Wire shapes of the Load balancing surface (D748): the session placement
+ * policy, the atomic share write, the observed placement statistics, the
+ * hardware share suggestion and the stale device pins.
+ */
+import { z } from 'zod';
+/**
+ * How a new detection session picks its node and device.
+ *  - `least-loaded` — the historical rule: lowest `attached / weight`, a
+ *    constant node order at a tie (D37). An idle node always ties at 0, so a
+ *    weight only bites once a node already holds a session.
+ *  - `share` — the share of PARALLEL sessions is held to the weights, and a
+ *    full or drowning node yields to a free one (D748).
+ */
+export declare const SessionPlacementPolicySchema: z.ZodEnum<{
+    "least-loaded": "least-loaded";
+    share: "share";
+}>;
+export type SessionPlacementPolicy = z.infer<typeof SessionPlacementPolicySchema>;
+export declare const DEFAULT_SESSION_PLACEMENT_POLICY: SessionPlacementPolicy;
+/** The global-settings key the policy is stored under (orchestrator `load` section). */
+export declare const SESSION_PLACEMENT_SETTING_KEY = "sessionPlacement";
+/** Parse a stored value; anything unknown is the default (nothing changes on deploy). */
+export declare function parseSessionPlacementPolicy(value: unknown): SessionPlacementPolicy;
+export declare const LoadBalancingSharesInputSchema: z.ZodObject<{
+    nodes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    devices: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+}, z.core.$strip>;
+export type LoadBalancingSharesInput = z.infer<typeof LoadBalancingSharesInputSchema>;
+export declare const PlacementStatsInputSchema: z.ZodObject<{
+    windowMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type PlacementStatsInput = z.infer<typeof PlacementStatsInputSchema>;
+export declare const PlacementDeviceStatsSchema: z.ZodObject<{
+    deviceKey: z.ZodString;
+    sessionsNow: z.ZodNumber;
+    sessionsStarted: z.ZodNumber;
+    observedShare: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PlacementDeviceStats = z.infer<typeof PlacementDeviceStatsSchema>;
+export declare const PlacementNodeStatsSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    sessionsNow: z.ZodNumber;
+    sessionsStarted: z.ZodNumber;
+    observedShare: z.ZodNullable<z.ZodNumber>;
+    peakSessions: z.ZodNumber;
+    yieldsAway: z.ZodNumber;
+    devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceKey: z.ZodString;
+        sessionsNow: z.ZodNumber;
+        sessionsStarted: z.ZodNumber;
+        observedShare: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PlacementNodeStats = z.infer<typeof PlacementNodeStatsSchema>;
+/** A camera's device pin that the session path cannot honour. */
+export declare const StaleDevicePinSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    deviceKey: z.ZodString;
+    reason: z.ZodEnum<{
+        absent: "absent";
+        disabled: "disabled";
+    }>;
+}, z.core.$strip>;
+export type StaleDevicePin = z.infer<typeof StaleDevicePinSchema>;
+export declare const PlacementStatsSchema: z.ZodObject<{
+    policy: z.ZodEnum<{
+        "least-loaded": "least-loaded";
+        share: "share";
+    }>;
+    windowMs: z.ZodNumber;
+    observedForMs: z.ZodNumber;
+    sessionsNow: z.ZodNumber;
+    clusterPeakSessions: z.ZodNumber;
+    nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        sessionsNow: z.ZodNumber;
+        sessionsStarted: z.ZodNumber;
+        observedShare: z.ZodNullable<z.ZodNumber>;
+        peakSessions: z.ZodNumber;
+        yieldsAway: z.ZodNumber;
+        devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            deviceKey: z.ZodString;
+            sessionsNow: z.ZodNumber;
+            sessionsStarted: z.ZodNumber;
+            observedShare: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    stalePins: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        deviceKey: z.ZodString;
+        reason: z.ZodEnum<{
+            absent: "absent";
+            disabled: "disabled";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PlacementStats = z.infer<typeof PlacementStatsSchema>;
+export declare const SuggestSharesInputSchema: z.ZodObject<{
+    headroom: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SuggestSharesInput = z.infer<typeof SuggestSharesInputSchema>;
+export declare const SuggestedDeviceShareSchema: z.ZodObject<{
+    deviceKey: z.ZodString;
+    share: z.ZodNumber;
+    modelId: z.ZodNullable<z.ZodString>;
+    fps: z.ZodNullable<z.ZodNumber>;
+    measured: z.ZodBoolean;
+    suggestedMaxSessions: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type SuggestedDeviceShare = z.infer<typeof SuggestedDeviceShareSchema>;
+export declare const SuggestedNodeShareSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    share: z.ZodNullable<z.ZodNumber>;
+    capacitySessions: z.ZodNumber;
+    devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceKey: z.ZodString;
+        share: z.ZodNumber;
+        modelId: z.ZodNullable<z.ZodString>;
+        fps: z.ZodNullable<z.ZodNumber>;
+        measured: z.ZodBoolean;
+        suggestedMaxSessions: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    skippedReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SuggestedNodeShare = z.infer<typeof SuggestedNodeShareSchema>;
+export declare const SuggestSharesResultSchema: z.ZodObject<{
+    headroom: z.ZodNumber;
+    cameraFps: z.ZodNumber;
+    iterations: z.ZodNumber;
+    nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        share: z.ZodNullable<z.ZodNumber>;
+        capacitySessions: z.ZodNumber;
+        devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            deviceKey: z.ZodString;
+            share: z.ZodNumber;
+            modelId: z.ZodNullable<z.ZodString>;
+            fps: z.ZodNullable<z.ZodNumber>;
+            measured: z.ZodBoolean;
+            suggestedMaxSessions: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        skippedReason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type SuggestSharesResult = z.infer<typeof SuggestSharesResultSchema>;

package/dist/pipeline/load-balancing/share-election.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Share placement (D748): which node — or which device of a node — a NEW
+ * detection session goes to when the cluster's `sessionPlacement` policy is
+ * `share`. Pure.
+ *
+ * A share is a share of PARALLEL sessions. At each session start the
+ * candidate furthest below its share of the sessions running once this one
+ * starts wins:
+ *
+ *     deficit_i = share_i / Σshare × (Σrunning + 1) − running_i
+ *
+ * so with 70/20/10 and an empty cluster the first session goes to the 70,
+ * and ten concurrent sessions settle at 7/2/1. Sessions a pin placed count
+ * toward their candidate like any other — a pinned node is not owed extra.
+ *
+ * Work-conserving: when the turn holder has no room — at an EXPLICIT cap
+ * (`maxSessions` / `maxCameras`) or drowning (its pool at the shed cap) — the
+ * session goes to the free candidate with the most spare explicit capacity,
+ * then the largest deficit. Never onto a saturated one. A capacity derived
+ * from the measured latency table is advisory only and never enters here: it
+ * would turn a suggestion into a de-facto cap.
+ *
+ * When every uncapped candidate is saturated the turn holder keeps the
+ * session: excluding the whole set would silently disable placement.
+ */
+export interface ShareCandidate {
+    readonly key: string;
+    /** Relative share (any scale; ≤ 0 = wanted last). */
+    readonly share: number;
+    /** Sessions running on this candidate now. */
+    readonly running: number;
+    /** At an explicit cap — never elected. */
+    readonly capped: boolean;
+    /** Drowning (pool queue at its shed cap) — stepped over while another is free. */
+    readonly saturated: boolean;
+    /** Spare sessions under an explicit cap; absent = no explicit cap. */
+    readonly spare?: number;
+}
+export type ShareYieldReason = 'at-cap' | 'saturated';
+export type ShareElection = {
+    readonly kind: 'elected';
+    readonly key: string;
+    readonly reason: 'share';
+} | {
+    readonly kind: 'elected';
+    readonly key: string;
+    readonly reason: 'yield';
+    /** The candidate whose turn it was. */
+    readonly turnKey: string;
+    readonly yieldReason: ShareYieldReason;
+} | {
+    readonly kind: 'none';
+};
+export declare function electByShare(candidates: readonly ShareCandidate[]): ShareElection;

package/dist/pipeline/model-bound-settings.d.ts

@@ -33,6 +33,7 @@
  * runner (`addon-pipeline`) and the editors (`ui-library`, `addon-admin-ui`)
  * apply the same rule.
  */
+import type { ConfigField } from '../interfaces/config-ui.js';
 /** `minConfidencePerson` → `minConfidencePersonModelId`. */
 export declare function modelBindingKey(key: string): string;
 /** A loose step-settings bag, as it is stored and travels. */
@@ -80,3 +81,9 @@ export declare function hasModelBoundOverrides(settings: ModelBoundSettingsBag |
  * that model runs.
  */
 export declare function clearModelBoundOverrides(settings: ModelBoundSettingsBag | undefined, boundKeys: readonly string[], modelId: string | undefined): Record<string, unknown>;
+/**
+ * The keys of every `bindsToModel` field of a step's config schema, groups
+ * flattened (D738). One definition for the runner (which applies the binding)
+ * and the orchestrator's Best settings (which clears those overrides, D745).
+ */
+export declare function collectModelBoundKeys(fields: readonly ConfigField[]): string[];

package/dist/types/agent-pipeline-settings.d.ts

@@ -157,7 +157,6 @@ export interface AgentPipelineSettings {
  * resolved tree.
  */
 export interface CameraPipelineSettings {
-    readonly pinnedAgentNodeId?: string;
     readonly stepToggles?: Readonly<Record<string, boolean>>;
     /**
      * Per-(camera,node,device) model/settings override. Addressed by

package/dist/types/models.d.ts

@@ -27,6 +27,51 @@ export declare const ModelFormatEntrySchema: z.ZodObject<{
     revision: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ModelFormatEntry = z.infer<typeof ModelFormatEntrySchema>;
+/**
+ * What a node holds for one (model, format) (D746). `current` is a complete
+ * copy at its catalog revision — exactly what `downloaded: true` means.
+ * `stale` is bytes on disk that are not (yet) proven current under D743/D744:
+ * no or a different revision record, or a missing sibling. `missing` is no
+ * copy. `downloaded` alone folds `stale` into "not downloaded", which hid
+ * reclaimable bytes and a copy about to be replaced.
+ */
+export declare const ModelOnDiskStateSchema: z.ZodEnum<{
+    missing: "missing";
+    current: "current";
+    stale: "stale";
+}>;
+export type ModelOnDiskState = z.infer<typeof ModelOnDiskStateSchema>;
+/**
+ * The numeric precision of one format's BUILD (D746) — reported only when the
+ * build states it (file-name token, an INT8 variant, an EdgeTPU compile, a
+ * CamStack Core ML export). Absent means "not stated", never "fp32".
+ */
+export declare const ModelFormatPrecisionSchema: z.ZodEnum<{
+    fp32: "fp32";
+    fp16: "fp16";
+    int8: "int8";
+}>;
+export type ModelFormatPrecision = z.infer<typeof ModelFormatPrecisionSchema>;
+/**
+ * One format of one model as a node's `pipelineExecutor.getSchema` reports it.
+ * `onDisk` / `precision` are optional for version skew: a runner that predates
+ * them omits them, and a reader falls back to `downloaded`.
+ */
+export declare const PipelineModelFormatStatusSchema: z.ZodObject<{
+    downloaded: z.ZodBoolean;
+    sizeMB: z.ZodNumber;
+    onDisk: z.ZodOptional<z.ZodEnum<{
+        missing: "missing";
+        current: "current";
+        stale: "stale";
+    }>>;
+    precision: z.ZodOptional<z.ZodEnum<{
+        fp32: "fp32";
+        fp16: "fp16";
+        int8: "int8";
+    }>>;
+}, z.core.$strip>;
+export type PipelineModelFormatStatus = z.infer<typeof PipelineModelFormatStatusSchema>;
 /**
  * Extra file that must be downloaded alongside the model (e.g., labels JSON, dict.txt).
  * The downloader fetches from `url` and saves to `{modelsDir}/{filename}`.

package/package.json

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