@camstack/types 1.2.327 → 1.2.329

package/dist/pipeline/auto-tune/plan-schemas.d.ts

@@ -78,12 +78,39 @@ export declare const RecommendationReasonSchema: z.ZodDiscriminatedUnion<[z.ZodO
         pt: "pt";
         gguf: "gguf";
     }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"kept-custom-pin">;
+    modelId: z.ZodString;
+    deviceKey: z.ZodString;
+}, z.core.$strip>], "kind">;
+/** Why a device is left exactly as it is, whatever the plan would pick (D786). */
+export declare const KeptReasonSchema: z.ZodEnum<{
+    "custom-pin": "custom-pin";
+}>;
+/**
+ * Where a choice's latency came from (D791): this node's own benchmark
+ * result, or the hardware-class table. Measured on the node beats the table.
+ */
+export declare const LatencySourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"table">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"node-benchmark">;
+    resultId: z.ZodString;
+    measuredAtMs: z.ZodNumber;
 }, z.core.$strip>], "kind">;
+export type LatencySource = z.infer<typeof LatencySourceSchema>;
 export declare const DeviceModelChoiceSchema: z.ZodObject<{
     modelId: z.ZodString;
     p50Ms: z.ZodNumber;
     fps: z.ZodNumber;
     measured: z.ZodBoolean;
+    source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"table">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"node-benchmark">;
+        resultId: z.ZodString;
+        measuredAtMs: z.ZodNumber;
+    }, z.core.$strip>], "kind">>;
     capacitySessions: z.ZodNumber;
     personRecall: z.ZodNumber;
 }, z.core.$strip>;
@@ -104,9 +131,19 @@ export declare const DeviceRecommendationSchema: z.ZodObject<{
         p50Ms: z.ZodNumber;
         fps: z.ZodNumber;
         measured: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"table">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"node-benchmark">;
+            resultId: z.ZodString;
+            measuredAtMs: z.ZodNumber;
+        }, z.core.$strip>], "kind">>;
         capacitySessions: z.ZodNumber;
         personRecall: z.ZodNumber;
     }, z.core.$strip>>;
+    kept: z.ZodOptional<z.ZodEnum<{
+        "custom-pin": "custom-pin";
+    }>>;
     reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"capacity">;
         sessions: z.ZodNumber;
@@ -158,6 +195,10 @@ export declare const DeviceRecommendationSchema: z.ZodObject<{
             pt: "pt";
             gguf: "gguf";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"kept-custom-pin">;
+        modelId: z.ZodString;
+        deviceKey: z.ZodString;
     }, z.core.$strip>], "kind">>>;
 }, z.core.$strip>;
 export declare const NodeRecommendationSchema: z.ZodObject<{
@@ -190,9 +231,19 @@ export declare const NodeRecommendationSchema: z.ZodObject<{
             p50Ms: z.ZodNumber;
             fps: z.ZodNumber;
             measured: z.ZodBoolean;
+            source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"table">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"node-benchmark">;
+                resultId: z.ZodString;
+                measuredAtMs: z.ZodNumber;
+            }, z.core.$strip>], "kind">>;
             capacitySessions: z.ZodNumber;
             personRecall: z.ZodNumber;
         }, z.core.$strip>>;
+        kept: z.ZodOptional<z.ZodEnum<{
+            "custom-pin": "custom-pin";
+        }>>;
         reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"capacity">;
             sessions: z.ZodNumber;
@@ -244,6 +295,10 @@ export declare const NodeRecommendationSchema: z.ZodObject<{
                 pt: "pt";
                 gguf: "gguf";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"kept-custom-pin">;
+            modelId: z.ZodString;
+            deviceKey: z.ZodString;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>>;
     reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -297,6 +352,10 @@ export declare const NodeRecommendationSchema: z.ZodObject<{
             pt: "pt";
             gguf: "gguf";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"kept-custom-pin">;
+        modelId: z.ZodString;
+        deviceKey: z.ZodString;
     }, z.core.$strip>], "kind">>>;
 }, z.core.$strip>;
 export declare const ModelPinChangeSchema: z.ZodObject<{
@@ -344,6 +403,15 @@ export declare const AutoTuneWarningSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     kind: z.ZodLiteral<"coral-enabled">;
     nodeId: z.ZodString;
     deviceKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom-pin-kept">;
+    nodeId: z.ZodString;
+    deviceKey: z.ZodNullable<z.ZodString>;
+    deviceId: z.ZodNullable<z.ZodNumber>;
+    modelId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom-registry-unreadable">;
+    error: z.ZodString;
 }, z.core.$strip>], "kind">;
 export declare const AutoTuneOptionsSchema: z.ZodObject<{
     headroom: z.ZodDefault<z.ZodNumber>;
@@ -386,9 +454,19 @@ export declare const AutoTunePlanSchema: z.ZodObject<{
                 p50Ms: z.ZodNumber;
                 fps: z.ZodNumber;
                 measured: z.ZodBoolean;
+                source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"table">;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"node-benchmark">;
+                    resultId: z.ZodString;
+                    measuredAtMs: z.ZodNumber;
+                }, z.core.$strip>], "kind">>;
                 capacitySessions: z.ZodNumber;
                 personRecall: z.ZodNumber;
             }, z.core.$strip>>;
+            kept: z.ZodOptional<z.ZodEnum<{
+                "custom-pin": "custom-pin";
+            }>>;
             reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"capacity">;
                 sessions: z.ZodNumber;
@@ -440,6 +518,10 @@ export declare const AutoTunePlanSchema: z.ZodObject<{
                     pt: "pt";
                     gguf: "gguf";
                 }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"kept-custom-pin">;
+                modelId: z.ZodString;
+                deviceKey: z.ZodString;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>>;
         reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -493,6 +575,10 @@ export declare const AutoTunePlanSchema: z.ZodObject<{
                 pt: "pt";
                 gguf: "gguf";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"kept-custom-pin">;
+            modelId: z.ZodString;
+            deviceKey: z.ZodString;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>>;
     nodeChanges: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -535,6 +621,15 @@ export declare const AutoTunePlanSchema: z.ZodObject<{
         kind: z.ZodLiteral<"coral-enabled">;
         nodeId: z.ZodString;
         deviceKey: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"custom-pin-kept">;
+        nodeId: z.ZodString;
+        deviceKey: z.ZodNullable<z.ZodString>;
+        deviceId: z.ZodNullable<z.ZodNumber>;
+        modelId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"custom-registry-unreadable">;
+        error: z.ZodString;
     }, z.core.$strip>], "kind">>>;
 }, z.core.$strip>;
 export declare const AutoTuneApplyInputSchema: z.ZodObject<{
@@ -619,9 +714,19 @@ export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodOb
                     p50Ms: z.ZodNumber;
                     fps: z.ZodNumber;
                     measured: z.ZodBoolean;
+                    source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"table">;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"node-benchmark">;
+                        resultId: z.ZodString;
+                        measuredAtMs: z.ZodNumber;
+                    }, z.core.$strip>], "kind">>;
                     capacitySessions: z.ZodNumber;
                     personRecall: z.ZodNumber;
                 }, z.core.$strip>>;
+                kept: z.ZodOptional<z.ZodEnum<{
+                    "custom-pin": "custom-pin";
+                }>>;
                 reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"capacity">;
                     sessions: z.ZodNumber;
@@ -673,6 +778,10 @@ export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodOb
                         pt: "pt";
                         gguf: "gguf";
                     }>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"kept-custom-pin">;
+                    modelId: z.ZodString;
+                    deviceKey: z.ZodString;
                 }, z.core.$strip>], "kind">>>;
             }, z.core.$strip>>>;
             reasons: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -726,6 +835,10 @@ export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodOb
                     pt: "pt";
                     gguf: "gguf";
                 }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"kept-custom-pin">;
+                modelId: z.ZodString;
+                deviceKey: z.ZodString;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>>;
         nodeChanges: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -768,6 +881,15 @@ export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             kind: z.ZodLiteral<"coral-enabled">;
             nodeId: z.ZodString;
             deviceKey: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"custom-pin-kept">;
+            nodeId: z.ZodString;
+            deviceKey: z.ZodNullable<z.ZodString>;
+            deviceId: z.ZodNullable<z.ZodNumber>;
+            modelId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"custom-registry-unreadable">;
+            error: z.ZodString;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -791,3 +913,4 @@ export type RecommendationReason = z.infer<typeof RecommendationReasonSchema>;
 export type DeviceModelChoice = z.infer<typeof DeviceModelChoiceSchema>;
 export type DeviceRecommendation = z.infer<typeof DeviceRecommendationSchema>;
 export type NodeRecommendation = z.infer<typeof NodeRecommendationSchema>;
+export type KeptReason = z.infer<typeof KeptReasonSchema>;

package/dist/pipeline/auto-tune/recommend.d.ts

@@ -6,7 +6,12 @@
  *
  * Per node:
  *  1. Classify the hardware (`classifyInferenceHardware`). An unknown class,
- *     an offline node or a node with nothing to recommend is left untouched.
+ *     an offline node or a node with nothing to recommend is left untouched —
+ *     unless the node has its own measurements (below).
+ *  1b. MEASURED ON THE NODE BEATS THE TABLE (D791): a fresh node benchmark
+ *     result for (device, model) replaces the table's cell, and the choice
+ *     names it as its source. A node of unknown hardware with measurements is
+ *     recommended from them alone.
  *  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
@@ -21,6 +26,10 @@
  *     the candidate with the most capacity is used and the plan says so.
  *  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.
+ *  6. A device whose root detector is pinned to a CUSTOM-registry model (a
+ *     fine-tune, a canary) is KEPT (D786): no model is chosen for it, so Apply
+ *     writes nothing there. One kept accelerator keeps the whole accelerator
+ *     group, because the group shares one model.
  */
 import type { HardwareInfo } from '../../interfaces/platform.js';
 import type { ModelFormat } from '../../types/models.js';
@@ -36,12 +45,26 @@ export declare const DEFAULT_HEADROOM = 0.4;
 export declare const DEFAULT_CAMERA_FPS = 10;
 /** Parallel sessions one device sustains at `fps` with `headroom` kept free. */
 export declare function capacitySessionsOf(fps: number, headroom: number, cameraFps: number): number;
+/** A latency measured on the node itself (a fresh node benchmark result, D791). */
+export interface MeasuredLatencyCell {
+    readonly p50Ms: number;
+    readonly fps: number;
+    readonly resultId: string;
+    readonly measuredAtMs: number;
+}
+/** deviceKey → modelId → measured cell. */
+export type MeasuredLatency = Readonly<Record<string, Readonly<Record<string, MeasuredLatencyCell>>>>;
 /** One device of a node, as the recommender reads it. */
 export interface AutoTuneDeviceInput {
     readonly key: string;
     readonly format: ModelFormat;
     readonly enabled: boolean;
     readonly available: boolean;
+    /**
+     * The custom-registry model the device's root detector is pinned to, when
+     * it is one (the caller decides what is custom). The device is then kept.
+     */
+    readonly customPinModelId?: string;
 }
 /** One node, as the recommender reads it. */
 export interface AutoTuneNodeInput {
@@ -61,4 +84,6 @@ export declare function recommendNode(input: {
     /** The rate a session is counted at (default {@link DEFAULT_CAMERA_FPS}). */
     readonly cameraFps?: number;
     readonly perf?: DetectorPerfTable;
+    /** This node's fresh node-benchmark measurements (D791); they beat the table. */
+    readonly measured?: MeasuredLatency;
 }): NodeRecommendation;

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

@@ -191,13 +191,14 @@ export declare const SuggestSharesResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SuggestSharesResult = z.infer<typeof SuggestSharesResultSchema>;
 /**
- * Where the node and device shares come from (D750, D755).
- *  - `hardware` (default) — computed by the system from each node's static
- *    capacity (its accelerators at their Auto tune models, from the measured
- *    latency table), recomputed whenever a node or device joins, leaves, is
- *    switched on or off, or changes model. No load input.
- *  - `benchmark` — the same, from each node's measured capacity (node
- *    benchmark results); a node without results falls back to `hardware`.
+ * Where the node and device shares come from (D750, D755, D791).
+ *  - `benchmark` (default since D791) — each node's capacity as its own node
+ *    benchmark measured it; a node without fresh results is sized from
+ *    `hardware` and says so. Measured on the node beats the table.
+ *  - `hardware` — computed from each node's static capacity only (its
+ *    accelerators at their Auto tune models, from the latency table).
+ *  Both are recomputed whenever a node or device joins, leaves, is switched
+ *  on or off, changes model, or a benchmark result is written. No load input.
  *  - `manual` — the operator's stored sliders.
  * Either way a node or device that cannot take sessions gives its share to
  * the others in proportion; the stored values are never rewritten for that.

package/dist/pipeline/node-benchmark/benchmark-mode.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Benchmark mode (D791) — the pure rules of "one node under test". Pure.
+ *
+ * While the cluster is in benchmark mode for node N:
+ *  - N is not a detection candidate for any camera that another node can
+ *    serve ({@link eligibleUnderBenchmark});
+ *  - a node pin naming N is ignored for such a camera
+ *    ({@link pinUnderBenchmark}) — the stored pin is never rewritten, so it
+ *    is "restored" the moment the mode ends;
+ *  - a camera whose ONLY frame source is N stays on N (never blind) and the
+ *    run is flagged contaminated.
+ */
+import { type NodeBenchmarkMovingCamera, type NodeBenchmarkPlan, type NodeBenchmarkRefusal, type NodeBenchmarkStayingCamera } from './schemas.js';
+/** The detection candidates of one camera while `benchNodeId` is under test. */
+export declare function eligibleUnderBenchmark(eligible: readonly string[], benchNodeId: string | null): readonly string[];
+/** A camera's node pin while `benchNodeId` is under test (null = no pin). */
+export declare function pinUnderBenchmark(pin: string | null, benchNodeId: string | null, eligible: readonly string[]): string | null;
+/** One camera as the preflight sees it. */
+export interface BenchmarkCameraFacts {
+    readonly deviceId: number;
+    /** The node its detection is placed on now; null = not placed. */
+    readonly placedNodeId: string | null;
+    /** Its stored node pin; null = none. */
+    readonly nodePin: string | null;
+    /** Nodes that can obtain its frames (before the benchmark). */
+    readonly frameSourceNodes: readonly string[];
+}
+/** Which cameras leave the node for the run, and which cannot. */
+export declare function classifyCamerasForBenchmark(nodeId: string, cameras: readonly BenchmarkCameraFacts[]): {
+    readonly moving: readonly NodeBenchmarkMovingCamera[];
+    readonly staying: readonly NodeBenchmarkStayingCamera[];
+};
+/** Ramp steps the runner tries per cell, at most. */
+export declare const DEVICE_RAMP: readonly number[];
+export declare const PIPELINE_RAMP: readonly number[];
+/**
+ * An upper bound on how long the run takes: every ramp step of every cell,
+ * plus the drain, the clip and the restore — capped at the budget, which is
+ * the hard deadline anyway. A ramp usually stops well before its last step.
+ */
+export declare function estimateNodeBenchmarkDurationMs(plan: NodeBenchmarkPlan, timing?: {
+    readonly settleSec?: number;
+    readonly measureSec?: number;
+}): number;
+/** Why a run cannot start, in the order the operator should read them. */
+export declare function nodeBenchmarkRefusals(input: {
+    readonly plan: NodeBenchmarkPlan;
+    /** The node a run is active for, if any. */
+    readonly activeRunNodeId: string | null;
+    readonly online: boolean;
+    /** Inference devices the node reports. */
+    readonly knownDeviceKeys: readonly string[];
+    /** Parallel sessions the cluster runs now. */
+    readonly sessionsNow: number;
+    /** Sessions the OTHER nodes can carry; null = unknown. */
+    readonly otherNodesCapacitySessions: number | null;
+}): readonly NodeBenchmarkRefusal[];

package/dist/pipeline/node-benchmark/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node benchmark (D791): one node at a time, owned by the pipeline
+ * orchestrator, measured by the node's own runner; its results feed Auto
+ * tune and the automatic shares. See `schemas.ts` and `benchmark-mode.ts`.
+ */
+export * from './schemas.js';
+export * from './benchmark-mode.js';
+export * from './results.js';
+export * from './step-tree.js';

package/dist/pipeline/node-benchmark/results.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which node benchmark result still beats the table (D791). Pure.
+ *
+ * A row is FRESH when it is the newest for its cell (node × device × phase
+ * × model [× steps]), younger than the stale bound (30 days), and was
+ * measured on the pool the node runs today (same runtime, same tuning). A
+ * fresh row is what Auto tune and the automatic shares read; anything else
+ * falls back to the latency table and says why.
+ *
+ * A pool the node does not answer for today does not make a row stale: an
+ * unreadable fact is not a changed one.
+ */
+import type { NodeMeasuredCapacity } from '../load-balancing/capacity-shares.js';
+import { type NodeBenchmarkResult, type NodeBenchmarkResultView } from './schemas.js';
+/** The pool a device runs today, as `getEffectiveTuning` answers it. */
+export interface CurrentPool {
+    readonly runtime: string;
+    readonly numWorkers: number;
+    readonly concurrency: number;
+    readonly batchMode: string;
+}
+export interface StandingContext {
+    readonly nowMs: number;
+    /** Default {@link NODE_BENCHMARK_DEFAULTS.staleAfterDays}. */
+    readonly staleAfterMs?: number;
+    /** nodeId → deviceKey → the pool now; a missing entry is "unknown", never "changed". */
+    readonly currentPools: Readonly<Record<string, Readonly<Record<string, CurrentPool>>>>;
+}
+export interface Standing {
+    readonly standing: NodeBenchmarkResultView['standing'];
+    readonly staleWhy: NodeBenchmarkResultView['staleWhy'];
+}
+/** The cell a row measures — two rows with the same key measure the same thing. */
+export declare function resultCellKey(row: NodeBenchmarkResult): string;
+/** The standing of every row, by id. */
+export declare function resultStandings(rows: readonly NodeBenchmarkResult[], ctx: StandingContext): ReadonlyMap<string, Standing>;
+/** Rows that beat the table today. */
+export declare function freshResults(rows: readonly NodeBenchmarkResult[], ctx: StandingContext): readonly NodeBenchmarkResult[];
+/** One measured detector on one device — what Auto tune overlays on the table. */
+export interface MeasuredDetectorCell {
+    readonly p50Ms: number;
+    readonly fps: number;
+    readonly resultId: string;
+    readonly measuredAtMs: number;
+}
+/** deviceKey → modelId → the fresh `device` measurement on `nodeId`. */
+export declare function measuredDetectorCells(rows: readonly NodeBenchmarkResult[], nodeId: string, ctx: StandingContext): Readonly<Record<string, Readonly<Record<string, MeasuredDetectorCell>>>>;
+/**
+ * Per node, each device at its newest fresh `pipeline` measurement — the
+ * `NodeCapacitySource` answer the automatic shares read.
+ */
+export declare function measuredCapacityFromResults(rows: readonly NodeBenchmarkResult[], nodeIds: readonly string[], ctx: StandingContext): ReadonlyMap<string, NodeMeasuredCapacity>;