@camstack/types 1.2.317 → 1.2.318

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

@@ -1,25 +1,3 @@
-/**
- * Detection demand per inference device, for the Best settings recommender
- * (D745). Pure.
- *
- * Demand is inferences per second a device must sustain:
- *
- *  - a camera PINNED to a device charges its full rate to that device;
- *  - an ALWAYS-ON camera charges its rate to its standing node, split over
- *    that node's eligible devices by balancer weight (the device tier rotates
- *    ties, so the weight share is the long-run split);
- *  - ON-MOTION cameras are placed per session anywhere in the cluster, so
- *    they are charged by how many sessions a device has really carried at
- *    once: the observed 24 h peak of attached sessions on that device, minus
- *    the always-on cameras it already counts, filled with the highest
- *    on-motion rates. A device observed for less than 24 h (the hub
- *    restarted) falls back to a fixed estimate — a quarter of the on-motion
- *    cameras, at least two, spread evenly over the nodes and by weight over a
- *    node's devices — and the plan says so.
- *
- * Every device must also fit the single fastest camera that can land on it:
- * one session cannot be split across devices.
- */
 import type { DeviceDemand } from './plan-schemas.js';
 /** How a camera's detection runs. `disabled` cameras charge nothing. */
 export type BestSettingsDetectionMode = 'always-on' | 'on-motion' | 'disabled';
@@ -33,12 +11,29 @@ export interface BestSettingsCameraLoad {
     readonly runsPipelineRoot: boolean;
     /** The node an always-on camera stands on; null when not placed (on-motion). */
     readonly standingNodeId: string | null;
-    /** An operator pin of this camera to one `(node, device)`. */
+    /** The operator's node pin (`pipelineNodeId`), or null. */
+    readonly nodePinId: string | null;
+    /**
+     * An operator pin of this camera to one device. `nodeId` null = the pin
+     * names only a deviceKey (no node pin, no standing node): it resolves to the
+     * one node that has that key, or is ignored when several or none do.
+     */
     readonly devicePin: {
-        readonly nodeId: string;
+        readonly nodeId: string | null;
         readonly deviceKey: string;
     } | null;
 }
+/** The cluster-wide peak of parallel sessions (sum over every device at one census). */
+export interface ObservedClusterPeak {
+    readonly peakSessions: number;
+    readonly observedForMs: number;
+}
+/** Share placement input: node shares and the cluster-wide peak. */
+export interface DemandShares {
+    /** nodeId → share (any scale). Device shares are the eligible devices' weights. */
+    readonly nodes: Readonly<Record<string, number>>;
+    readonly clusterPeak: ObservedClusterPeak | null;
+}
 /** A device the balancer may place a session on. */
 export interface BestSettingsEligibleDevice {
     readonly nodeId: string;
@@ -75,4 +70,6 @@ export declare function estimateDeviceDemand(input: {
     readonly eligible: readonly BestSettingsEligibleDevice[];
     readonly peaks: readonly ObservedDevicePeak[];
     readonly options?: DemandOptions;
+    /** Present ⇒ share placement (D748); absent ⇒ least-loaded. */
+    readonly shares?: DemandShares;
 }): readonly DeviceDemand[];

package/dist/pipeline/best-settings/plan-schemas.d.ts

@@ -86,6 +86,10 @@ export declare const DeviceDemandSchema: z.ZodObject<{
         estimate: "estimate";
     }>;
     observedForMs: z.ZodNullable<z.ZodNumber>;
+    placement: z.ZodEnum<{
+        "least-loaded": "least-loaded";
+        share: "share";
+    }>;
 }, z.core.$strip>;
 export declare const DeviceModelChoiceSchema: z.ZodObject<{
     modelId: z.ZodString;
@@ -120,6 +124,10 @@ export declare const DeviceRecommendationSchema: z.ZodObject<{
             estimate: "estimate";
         }>;
         observedForMs: z.ZodNullable<z.ZodNumber>;
+        placement: z.ZodEnum<{
+            "least-loaded": "least-loaded";
+            share: "share";
+        }>;
     }, z.core.$strip>>;
     chosen: z.ZodNullable<z.ZodObject<{
         modelId: z.ZodString;
@@ -221,6 +229,10 @@ export declare const NodeRecommendationSchema: z.ZodObject<{
                 estimate: "estimate";
             }>;
             observedForMs: z.ZodNullable<z.ZodNumber>;
+            placement: z.ZodEnum<{
+                "least-loaded": "least-loaded";
+                share: "share";
+            }>;
         }, z.core.$strip>>;
         chosen: z.ZodNullable<z.ZodObject<{
             modelId: z.ZodString;
@@ -386,11 +398,16 @@ export declare const BestSettingsWarningSchema: z.ZodDiscriminatedUnion<[z.ZodOb
 }, z.core.$strip>], "kind">;
 export declare const BestSettingsOptionsSchema: z.ZodObject<{
     headroom: z.ZodDefault<z.ZodNumber>;
+    shares: z.ZodOptional<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>>;
 }, z.core.$strip>;
 export declare const BestSettingsPlanSchema: z.ZodObject<{
     planHash: z.ZodString;
     family: z.ZodLiteral<"yolov9">;
     headroom: z.ZodNumber;
+    whatIf: z.ZodBoolean;
     generatedAt: z.ZodNumber;
     nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         nodeId: z.ZodString;
@@ -430,6 +447,10 @@ export declare const BestSettingsPlanSchema: z.ZodObject<{
                     estimate: "estimate";
                 }>;
                 observedForMs: z.ZodNullable<z.ZodNumber>;
+                placement: z.ZodEnum<{
+                    "least-loaded": "least-loaded";
+                    share: "share";
+                }>;
             }, z.core.$strip>>;
             chosen: z.ZodNullable<z.ZodObject<{
                 modelId: z.ZodString;
@@ -637,6 +658,7 @@ export declare const BestSettingsApplyResultSchema: z.ZodDiscriminatedUnion<[z.Z
         planHash: z.ZodString;
         family: z.ZodLiteral<"yolov9">;
         headroom: z.ZodNumber;
+        whatIf: z.ZodBoolean;
         generatedAt: z.ZodNumber;
         nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
             nodeId: z.ZodString;
@@ -676,6 +698,10 @@ export declare const BestSettingsApplyResultSchema: z.ZodDiscriminatedUnion<[z.Z
                         estimate: "estimate";
                     }>;
                     observedForMs: z.ZodNullable<z.ZodNumber>;
+                    placement: z.ZodEnum<{
+                        "least-loaded": "least-loaded";
+                        share: "share";
+                    }>;
                 }, z.core.$strip>>;
                 chosen: z.ZodNullable<z.ZodObject<{
                     modelId: z.ZodString;

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/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/package.json

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