@camstack/types 1.2.317 → 1.2.319

package/dist/pipeline/{best-settings → auto-tune}/demand.d.ts

@@ -1,46 +1,41 @@
-/**
- * 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';
+export type AutoTuneDetectionMode = 'always-on' | 'on-motion' | 'disabled';
 /** One camera's detection load. */
-export interface BestSettingsCameraLoad {
+export interface AutoTuneCameraLoad {
     readonly deviceId: number;
-    readonly mode: BestSettingsDetectionMode;
+    readonly mode: AutoTuneDetectionMode;
     /** Detection frames per second while a session runs. */
     readonly fps: number;
     /** False when only the camera's own (onboard) detector runs — no pipeline root. */
     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 {
+export interface AutoTuneEligibleDevice {
     readonly nodeId: string;
     readonly deviceKey: string;
     readonly weight: number;
@@ -71,8 +66,10 @@ export declare function estimatedConcurrentSessions(cameraCount: number, options
  * Demand on every eligible device of the cluster.
  */
 export declare function estimateDeviceDemand(input: {
-    readonly cameras: readonly BestSettingsCameraLoad[];
-    readonly eligible: readonly BestSettingsEligibleDevice[];
+    readonly cameras: readonly AutoTuneCameraLoad[];
+    readonly eligible: readonly AutoTuneEligibleDevice[];
     readonly peaks: readonly ObservedDevicePeak[];
     readonly options?: DemandOptions;
+    /** Present ⇒ share placement (D748); absent ⇒ least-loaded. */
+    readonly shares?: DemandShares;
 }): readonly DeviceDemand[];

package/dist/pipeline/{best-settings → auto-tune}/hardware-class.d.ts

@@ -1,5 +1,5 @@
 /**
- * Static hardware classification for the Best settings recommender (D745).
+ * Static hardware classification for the Auto tune recommender (D745).
  *
  * A node is classified from the facts its platform probe already reports —
  * `cpuModel`, `arch`, `gpu`, `npu` — never from a benchmark. The class picks a

package/dist/pipeline/{best-settings → auto-tune}/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Best settings (D745): the static-hardware × measured-latency × demand
+ * Auto tune (D745): the static-hardware × measured-latency × demand
  * recommender of ONE detector family for the whole cluster, and the shapes of
  * its plan. See `recommend.ts`.
  */

package/dist/pipeline/{best-settings → auto-tune}/plan-schemas.d.ts

@@ -1,5 +1,5 @@
 /**
- * The wire shapes of the Best settings plan and apply (D745), used by the
+ * The wire shapes of the Auto tune plan and apply (D745), used by the
  * `pipeline-orchestrator` cap. The recommender's own types
  * (`recommend.ts`, `demand.ts`) are the TS face of the same data; these
  * schemas are what crosses the cap boundary.
@@ -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;
@@ -373,7 +385,7 @@ export declare const DetectorStoreClearSchema: z.ZodObject<{
     deviceId: z.ZodNumber;
     keys: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
-export declare const BestSettingsWarningSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const AutoTuneWarningSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"detector-store-cluster-wide">;
     skippedNodes: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>, z.ZodObject<{
@@ -384,13 +396,18 @@ export declare const BestSettingsWarningSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     nodeId: z.ZodString;
     deviceKey: z.ZodString;
 }, z.core.$strip>], "kind">;
-export declare const BestSettingsOptionsSchema: z.ZodObject<{
+export declare const AutoTuneOptionsSchema: 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<{
+export declare const AutoTunePlanSchema: 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;
@@ -589,11 +610,11 @@ export declare const BestSettingsPlanSchema: z.ZodObject<{
         deviceKey: z.ZodString;
     }, z.core.$strip>], "kind">>>;
 }, z.core.$strip>;
-export declare const BestSettingsApplyInputSchema: z.ZodObject<{
+export declare const AutoTuneApplyInputSchema: z.ZodObject<{
     planHash: z.ZodString;
     headroom: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
-export declare const BestSettingsPhaseResultSchema: z.ZodObject<{
+export declare const AutoTunePhaseResultSchema: z.ZodObject<{
     phase: z.ZodEnum<{
         download: "download";
         "camera-overrides": "camera-overrides";
@@ -604,7 +625,7 @@ export declare const BestSettingsPhaseResultSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     detail: z.ZodString;
 }, z.core.$strip>;
-export declare const BestSettingsApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"applied">;
     planHash: z.ZodString;
     phases: z.ZodReadonly<z.ZodArray<z.ZodObject<{
@@ -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;
@@ -841,15 +867,15 @@ export declare const BestSettingsApplyResultSchema: z.ZodDiscriminatedUnion<[z.Z
         "apply-in-progress": "apply-in-progress";
     }>;
 }, z.core.$strip>], "kind">;
-export type BestSettingsPlan = z.infer<typeof BestSettingsPlanSchema>;
-export type BestSettingsOptions = z.infer<typeof BestSettingsOptionsSchema>;
-export type BestSettingsApplyInput = z.infer<typeof BestSettingsApplyInputSchema>;
-export type BestSettingsApplyResult = z.infer<typeof BestSettingsApplyResultSchema>;
-export type BestSettingsPhaseResult = z.infer<typeof BestSettingsPhaseResultSchema>;
-export type BestSettingsWarning = z.infer<typeof BestSettingsWarningSchema>;
+export type AutoTunePlan = z.infer<typeof AutoTunePlanSchema>;
+export type AutoTuneOptions = z.infer<typeof AutoTuneOptionsSchema>;
+export type AutoTuneApplyInput = z.infer<typeof AutoTuneApplyInputSchema>;
+export type AutoTuneApplyResult = z.infer<typeof AutoTuneApplyResultSchema>;
+export type AutoTunePhaseResult = z.infer<typeof AutoTunePhaseResultSchema>;
+export type AutoTuneWarning = z.infer<typeof AutoTuneWarningSchema>;
 export type DetectorStoreClear = z.infer<typeof DetectorStoreClearSchema>;
-export type BestSettingsCameraOverrideClear = z.infer<typeof CameraOverrideClearSchema>;
-export type BestSettingsNodeDeviceChange = z.infer<typeof NodeDeviceChangeSchema>;
+export type AutoTuneCameraOverrideClear = z.infer<typeof CameraOverrideClearSchema>;
+export type AutoTuneNodeDeviceChange = z.infer<typeof NodeDeviceChangeSchema>;
 export type HardwareClassId = z.infer<typeof HardwareClassIdSchema>;
 export type AcceleratorKind = z.infer<typeof AcceleratorKindSchema>;
 export type RecommendationReason = z.infer<typeof RecommendationReasonSchema>;

package/dist/pipeline/{best-settings → auto-tune}/recommend.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Best settings recommender (D745): one detector per node, from ONE family
+ * The Auto tune 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.
  *
@@ -24,30 +24,30 @@ 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";
+export declare const AUTO_TUNE_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 {
+export interface AutoTuneDeviceInput {
     readonly key: string;
     readonly format: ModelFormat;
     readonly enabled: boolean;
     readonly available: boolean;
 }
 /** One node, as the recommender reads it. */
-export interface BestSettingsNodeInput {
+export interface AutoTuneNodeInput {
     readonly nodeId: string;
     readonly reachable: boolean;
     readonly hardware: HardwareInfo | null;
-    readonly devices: readonly BestSettingsDeviceInput[];
+    readonly devices: readonly AutoTuneDeviceInput[];
     /** 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 node: AutoTuneNodeInput;
     readonly demand: readonly DeviceDemand[];
     readonly headroom?: number;
     readonly perf?: DetectorPerfTable;

package/dist/pipeline/load-balancing/effective-shares.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The shares a session election actually reads, and the view the Load
+ * balancing tab shows (D750). Pure.
+ *
+ * The SOURCE decides the configured weights: the automatic capacity shares,
+ * or the operator's stored sliders. Eligibility decides the effective ones: a
+ * node or device that cannot take a session now (offline, switched off, no
+ * detect capability, unable to run the root) contributes nothing, and the
+ * others split its share in proportion to their own. That redistribution is
+ * exactly what `electByShare` does over its candidate set, so the view and
+ * the election cannot disagree; the stored values are never rewritten for it.
+ */
+import type { EffectiveShares, SessionPlacementPolicy, ShareSource, ShareWeights } from './schemas.js';
+export interface EffectiveSharesInput {
+    readonly source: ShareSource;
+    /** Every node the view covers, eligible or not. */
+    readonly nodeIds: readonly string[];
+    readonly stored: ShareWeights;
+    /** The last automatic computation; null = none yet. */
+    readonly auto: ShareWeights | null;
+    readonly eligibleNodes: readonly string[];
+    /** nodeId → device keys that can take sessions; a node absent here lists none. */
+    readonly eligibleDevices: Readonly<Record<string, readonly string[]>>;
+    readonly policy?: SessionPlacementPolicy;
+    readonly computedAt?: number | null;
+    readonly trigger?: string | null;
+}
+export declare function resolveEffectiveShares(input: EffectiveSharesInput): EffectiveShares;

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

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

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

@@ -0,0 +1,232 @@
+/**
+ * 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>;
+/**
+ * `share` since D750: the percentages are held by default. `least-loaded` stays
+ * selectable.
+ */
+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. */
+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>;
+/**
+ * Where the node and device shares come from (D750).
+ *  - `auto` — computed by the system from the cluster's measured capacity at
+ *    the Auto tune models, and recomputed whenever a node or device joins,
+ *    leaves, is switched on or off, or changes model.
+ *  - `manual` — the operator's stored sliders. A node or device that cannot
+ *    take sessions gives its share to the others in proportion; the stored
+ *    values are never rewritten for that.
+ */
+export declare const ShareSourceSchema: z.ZodEnum<{
+    manual: "manual";
+    auto: "auto";
+}>;
+export type ShareSource = z.infer<typeof ShareSourceSchema>;
+export declare const DEFAULT_SHARE_SOURCE: ShareSource;
+/** Headroom the automatic shares are computed at (Auto tune's default). */
+export declare const AUTO_SHARE_HEADROOM = 0.4;
+/** The global-settings key the share source is stored under (orchestrator `load` section). */
+export declare const SHARE_SOURCE_SETTING_KEY = "shareSource";
+/** Parse a stored value; anything unknown is the default. */
+export declare function parseShareSource(value: unknown): ShareSource;
+export declare const SetShareSourceInputSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        manual: "manual";
+        auto: "auto";
+    }>;
+}, z.core.$strip>;
+export type SetShareSourceInput = z.infer<typeof SetShareSourceInputSchema>;
+/** Raw relative weights (any scale) per node and per node's device. */
+export declare const ShareWeightsSchema: z.ZodObject<{
+    nodes: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    devices: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ShareWeights = z.infer<typeof ShareWeightsSchema>;
+export declare const EffectiveDeviceShareSchema: z.ZodObject<{
+    deviceKey: z.ZodString;
+    eligible: z.ZodBoolean;
+    configuredPct: z.ZodNumber;
+    effectivePct: z.ZodNumber;
+}, z.core.$strip>;
+export type EffectiveDeviceShare = z.infer<typeof EffectiveDeviceShareSchema>;
+export declare const EffectiveNodeShareSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    eligible: z.ZodBoolean;
+    configuredPct: z.ZodNumber;
+    effectivePct: z.ZodNumber;
+    devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceKey: z.ZodString;
+        eligible: z.ZodBoolean;
+        configuredPct: z.ZodNumber;
+        effectivePct: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type EffectiveNodeShare = z.infer<typeof EffectiveNodeShareSchema>;
+export declare const EffectiveSharesSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        manual: "manual";
+        auto: "auto";
+    }>;
+    policy: z.ZodEnum<{
+        "least-loaded": "least-loaded";
+        share: "share";
+    }>;
+    autoPending: z.ZodBoolean;
+    computedAt: z.ZodNullable<z.ZodNumber>;
+    trigger: z.ZodNullable<z.ZodString>;
+    nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        eligible: z.ZodBoolean;
+        configuredPct: z.ZodNumber;
+        effectivePct: z.ZodNumber;
+        devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            deviceKey: z.ZodString;
+            eligible: z.ZodBoolean;
+            configuredPct: z.ZodNumber;
+            effectivePct: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    nodeWeights: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    deviceWeights: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type EffectiveShares = z.infer<typeof EffectiveSharesSchema>;

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

@@ -84,6 +84,6 @@ export declare function clearModelBoundOverrides(settings: ModelBoundSettingsBag
 /**
  * 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).
+ * and the orchestrator's Auto tune (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/package.json

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