@camstack/types 1.2.318 → 1.2.320

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

@@ -17,10 +17,14 @@ export declare const SessionPlacementPolicySchema: z.ZodEnum<{
     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 (nothing changes on deploy). */
+/** 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>>;
@@ -96,8 +100,30 @@ export declare const PlacementStatsSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type PlacementStats = z.infer<typeof PlacementStatsSchema>;
+/**
+ * Where an automatic share's capacity comes from (D755).
+ *  - `hardware` — the static capacity of each device at its Auto tune model:
+ *    the measured latency table for the node's hardware class.
+ *  - `benchmark` — the node's own measured capacity (node benchmark results).
+ *    A node with no results falls back to `hardware`, and says so.
+ */
+export declare const CapacitySourceSchema: z.ZodEnum<{
+    hardware: "hardware";
+    benchmark: "benchmark";
+}>;
+export type CapacitySource = z.infer<typeof CapacitySourceSchema>;
+/** Why a node under the `benchmark` source was sized from hardware instead. */
+export declare const CapacityFallbackSchema: z.ZodEnum<{
+    "no-benchmark-results": "no-benchmark-results";
+    "partial-benchmark-results": "partial-benchmark-results";
+}>;
+export type CapacityFallback = z.infer<typeof CapacityFallbackSchema>;
 export declare const SuggestSharesInputSchema: z.ZodObject<{
     headroom: z.ZodDefault<z.ZodNumber>;
+    source: z.ZodDefault<z.ZodEnum<{
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>>;
 }, z.core.$strip>;
 export type SuggestSharesInput = z.infer<typeof SuggestSharesInputSchema>;
 export declare const SuggestedDeviceShareSchema: z.ZodObject<{
@@ -122,12 +148,24 @@ export declare const SuggestedNodeShareSchema: z.ZodObject<{
         suggestedMaxSessions: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strip>>>;
     skippedReason: z.ZodNullable<z.ZodString>;
+    capacitySource: z.ZodNullable<z.ZodEnum<{
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>>;
+    capacityFallback: z.ZodNullable<z.ZodEnum<{
+        "no-benchmark-results": "no-benchmark-results";
+        "partial-benchmark-results": "partial-benchmark-results";
+    }>>;
 }, z.core.$strip>;
 export type SuggestedNodeShare = z.infer<typeof SuggestedNodeShareSchema>;
 export declare const SuggestSharesResultSchema: z.ZodObject<{
     headroom: z.ZodNumber;
+    source: z.ZodEnum<{
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>;
     cameraFps: z.ZodNumber;
-    iterations: z.ZodNumber;
+    minSessionsPerDevice: z.ZodNumber;
     nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         nodeId: z.ZodString;
         share: z.ZodNullable<z.ZodNumber>;
@@ -141,6 +179,123 @@ export declare const SuggestSharesResultSchema: z.ZodObject<{
             suggestedMaxSessions: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>>>;
         skippedReason: z.ZodNullable<z.ZodString>;
+        capacitySource: z.ZodNullable<z.ZodEnum<{
+            hardware: "hardware";
+            benchmark: "benchmark";
+        }>>;
+        capacityFallback: z.ZodNullable<z.ZodEnum<{
+            "no-benchmark-results": "no-benchmark-results";
+            "partial-benchmark-results": "partial-benchmark-results";
+        }>>;
     }, z.core.$strip>>>;
 }, 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`.
+ *  - `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.
+ */
+export declare const ShareSourceSchema: z.ZodEnum<{
+    manual: "manual";
+    hardware: "hardware";
+    benchmark: "benchmark";
+}>;
+export type ShareSource = z.infer<typeof ShareSourceSchema>;
+export declare const DEFAULT_SHARE_SOURCE: ShareSource;
+/** `hardware` or `benchmark`: the system computes the shares. */
+export declare function isAutomaticShareSource(source: ShareSource): source is Exclude<ShareSource, 'manual'>;
+/** 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. `auto` (D750, before
+ * D755 split it) reads as `hardware` — that is what it computed.
+ */
+export declare function parseShareSource(value: unknown): ShareSource;
+export declare const SetShareSourceInputSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        manual: "manual";
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>;
+}, 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;
+    capacitySource: z.ZodNullable<z.ZodEnum<{
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>>;
+    capacityFallback: z.ZodNullable<z.ZodEnum<{
+        "no-benchmark-results": "no-benchmark-results";
+        "partial-benchmark-results": "partial-benchmark-results";
+    }>>;
+    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";
+        hardware: "hardware";
+        benchmark: "benchmark";
+    }>;
+    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;
+        capacitySource: z.ZodNullable<z.ZodEnum<{
+            hardware: "hardware";
+            benchmark: "benchmark";
+        }>>;
+        capacityFallback: z.ZodNullable<z.ZodEnum<{
+            "no-benchmark-results": "no-benchmark-results";
+            "partial-benchmark-results": "partial-benchmark-results";
+        }>>;
+        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/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/pipeline/step-settings-layers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The layers of a detection step's settings, and the field-level edits on them
+ * (D754).
+ *
+ * A step's settings reach a session through up to three stored layers, merged
+ * key by key — a key in a higher layer wins:
+ *
+ *   node         the node's folded base (`inferenceDevices[node][*].steps`)
+ *   camera       `cameraSettings[cam].stepSettings[step]` — every accelerator
+ *   accelerator  `cameraSettings[cam].stepOverridesByDevice[node][key][step].settings`
+ *
+ * Below them sits the default: the running model's (D738) or the field's own.
+ *
+ * Every layer is SPARSE and FIELD-LEVEL. A key present in a layer is an
+ * override; an absent key inherits. Two consequences that every editor must
+ * respect, and why this module exists:
+ *
+ *   - A model-bound field (D738) occupies TWO keys, its value and
+ *     `<key>ModelId`. They are written, compared and removed as one unit — a
+ *     value without its binding over a lower layer's binding would be judged
+ *     against the wrong model.
+ *   - An editor writes a DIFF against the merged layers below, never a copy of
+ *     them. A copy pins every field at the value it had that day, so later
+ *     edits below never reach it (the full-copy "Override" this replaced).
+ */
+/** One stored settings layer. */
+export type StepSettingsBag = Readonly<Record<string, unknown>>;
+/** The stored layers, from the top. `undefined` = the layer stores nothing for this step. */
+export interface StepSettingsLayers {
+    readonly accelerator?: StepSettingsBag;
+    readonly camera?: StepSettingsBag;
+    readonly node?: StepSettingsBag;
+}
+/** Which stored layer supplies a field, or `default` when none does. */
+export type StepSettingSource = 'accelerator' | 'camera' | 'node' | 'default';
+/**
+ * The keys one field occupies in a bag: its own, plus its binding key when it
+ * binds to a model. `boundKeys` = `collectModelBoundKeys(schema)`.
+ */
+export declare function fieldUnitKeys(key: string, boundKeys: readonly string[]): readonly string[];
+/** Structural equality for stored values (numbers, strings, booleans, arrays, plain objects). */
+export declare function settingValuesEqual(a: unknown, b: unknown): boolean;
+/** Merge bags bottom-up (later wins, per key). Fresh object. */
+export declare function mergeSettingsBags(...bags: readonly (StepSettingsBag | undefined)[]): Record<string, unknown>;
+/** The merged value of the layers BELOW `layer` (what removing a key from `layer` falls back to). */
+export declare function settingsBelow(layers: StepSettingsLayers, layer: Exclude<StepSettingSource, 'default'>): Record<string, unknown>;
+/** The effective bag: every stored layer merged. */
+export declare function effectiveStepSettings(layers: StepSettingsLayers): Record<string, unknown>;
+/** The highest stored layer that holds any key of `key`'s unit, or `default`. */
+export declare function stepSettingSource(layers: StepSettingsLayers, key: string, boundKeys: readonly string[]): StepSettingSource;
+/**
+ * `layer` with `key`'s unit set from `values` (a bag carrying the unit's new
+ * value — e.g. the editor's whole next settings bag). A unit key that `values`
+ * does not carry is removed from the layer. Fresh object.
+ */
+export declare function withFieldFrom(layer: StepSettingsBag | undefined, key: string, values: StepSettingsBag, boundKeys: readonly string[]): Record<string, unknown>;
+/** `layer` without `key`'s unit — "reset to the next level". Fresh object. */
+export declare function withoutField(layer: StepSettingsBag | undefined, key: string, boundKeys: readonly string[]): Record<string, unknown>;
+/**
+ * `layer` reduced to the fields that DIFFER from `below` — what an editor
+ * stores. A unit is kept or dropped whole. `undefined` when nothing is left.
+ */
+export declare function diffStepSettings(layer: StepSettingsBag | undefined, below: StepSettingsBag, boundKeys: readonly string[]): Record<string, unknown> | undefined;
+/**
+ * The fields `layer` stores at exactly the value of the layers below — a
+ * legacy full copy's leftovers. They change nothing today and stop every
+ * later edit below from reaching this layer. Sorted.
+ */
+export declare function fieldsPinnedAtValueBelow(layer: StepSettingsBag | undefined, below: StepSettingsBag, boundKeys: readonly string[]): readonly string[];

package/dist/{sleep-DyF95STh.js → sleep-AalHiRYL.js}

@@ -3757,6 +3757,7 @@ function createDeviceProxy(api, binding, opts) {
 		setCameraStepToggle: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepToggle", "mutation", input),
 		getCameraStepOverrides: (input) => dispatchSystem("pipelineOrchestrator", "getCameraStepOverrides", "query", input),
 		setCameraStepOverride: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepOverride", "mutation", input),
+		setCameraStepSettings: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepSettings", "mutation", input),
 		setCameraPipelineForAgent: (input) => dispatchSystem("pipelineOrchestrator", "setCameraPipelineForAgent", "mutation", input),
 		resolvePipeline: (input) => dispatchSystem("pipelineOrchestrator", "resolvePipeline", "query", input),
 		getCameraSwitches: (input) => dispatchSystem("pipelineOrchestrator", "getCameraSwitches", "query", input),

package/dist/{sleep-C16NCZR2.mjs → sleep-DAJ9Er57.mjs}

@@ -3757,6 +3757,7 @@ function createDeviceProxy(api, binding, opts) {
 		setCameraStepToggle: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepToggle", "mutation", input),
 		getCameraStepOverrides: (input) => dispatchSystem("pipelineOrchestrator", "getCameraStepOverrides", "query", input),
 		setCameraStepOverride: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepOverride", "mutation", input),
+		setCameraStepSettings: (input) => dispatchSystem("pipelineOrchestrator", "setCameraStepSettings", "mutation", input),
 		setCameraPipelineForAgent: (input) => dispatchSystem("pipelineOrchestrator", "setCameraPipelineForAgent", "mutation", input),
 		resolvePipeline: (input) => dispatchSystem("pipelineOrchestrator", "resolvePipeline", "query", input),
 		getCameraSwitches: (input) => dispatchSystem("pipelineOrchestrator", "getCameraSwitches", "query", input),

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

@@ -158,6 +158,17 @@ export interface AgentPipelineSettings {
  */
 export interface CameraPipelineSettings {
     readonly stepToggles?: Readonly<Record<string, boolean>>;
+    /**
+     * Camera-wide step SETTINGS (D754): `[addonId] → { fieldKey → value }`, the
+     * fields this camera overrides on EVERY accelerator it is balanced onto. A
+     * sparse, field-level bag — a key present here is an override, an absent key
+     * inherits the node. Merge order at dispatch, per key:
+     * node (folded base) ⊕ this ⊕ `stepOverridesByDevice[node][deviceKey]`.
+     * A model-bound field (D738) is always written with its binding key.
+     * Settings only: a model is a per-accelerator question (formats differ), so
+     * it stays in `stepOverridesByDevice`.
+     */
+    readonly stepSettings?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
     /**
      * Per-(camera,node,device) model/settings override. Addressed by
      * `[agentNodeId][deviceKey][addonId]` because the camera is balanced onto

package/package.json

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

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

@@ -1,75 +0,0 @@
-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';
-/** One camera's detection load. */
-export interface BestSettingsCameraLoad {
-    readonly deviceId: number;
-    readonly mode: BestSettingsDetectionMode;
-    /** 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;
-    /** 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 | 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;
-    readonly deviceKey: string;
-    readonly weight: number;
-}
-/** The observed peak of concurrent sessions on one device. */
-export interface ObservedDevicePeak {
-    readonly nodeId: string;
-    /** `''` = the node's sessions as a whole (a single-device node reports no per-device rows). */
-    readonly deviceKey: string;
-    /** Most sessions attached at once in the window. */
-    readonly peakSessions: number;
-    /** How long the device has been observed (ms) — the window is complete at 24 h. */
-    readonly observedForMs: number;
-}
-/** The on-motion load model's knobs. */
-export interface DemandOptions {
-    /** Share of on-motion cameras assumed concurrent when there is no full observation. */
-    readonly onMotionConcurrency: number;
-    /** Minimum concurrent on-motion sessions assumed (capped at the camera count). */
-    readonly onMotionMinConcurrent: number;
-}
-export declare const DEFAULT_DEMAND_OPTIONS: DemandOptions;
-/** A full observation window. */
-export declare const OBSERVATION_WINDOW_MS: number;
-/** Concurrent on-motion sessions assumed cluster-wide without an observation. */
-export declare function estimatedConcurrentSessions(cameraCount: number, options: DemandOptions): number;
-/**
- * Demand on every eligible device of the cluster.
- */
-export declare function estimateDeviceDemand(input: {
-    readonly cameras: readonly BestSettingsCameraLoad[];
-    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/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * Best settings (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`.
- */
-export * from './hardware-class.js';
-export * from './detector-performance.js';
-export * from './demand.js';
-export * from './recommend.js';
-export * from './plan-schemas.js';