@camstack/system 1.2.366 → 1.2.368

package/dist/{dist-BUfYKaXx.mjs → dist-CuTBQnSA.mjs}

@@ -26294,7 +26294,7 @@ var pipelineExecutorCapability = {
 			auth: "admin"
 		}),
 		/**
-		* Best settings (D745): the MODEL-BOUND thresholds (`bindsToModel` keys of
+		* Auto tune (D745): the MODEL-BOUND thresholds (`bindsToModel` keys of
 		* the object-detection root, and their binding keys) stored in THIS node's
 		* per-camera detector settings — and, unless `dryRun`, remove them so the
 		* running model's own defaults apply. Every other key of a camera's store
@@ -26666,7 +26666,143 @@ var pipelineExecutorCapability = {
 	}
 };
 /**
-* The wire shapes of the Best settings plan and apply (D745), used by the
+* 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.
+*/
+/**
+* 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).
+*/
+var SessionPlacementPolicySchema = z.enum(["least-loaded", "share"]);
+var LoadBalancingSharesInputSchema = z.object({
+	/** nodeId → share (> 0). A node left out keeps its weight. */
+	nodes: z.record(z.string(), z.number().positive()).default({}),
+	/** nodeId → deviceKey → share (> 0). A device left out keeps its weight. */
+	devices: z.record(z.string(), z.record(z.string(), z.number().positive())).default({})
+});
+var PlacementStatsInputSchema = z.object({ 
+/** Window the observed shares are averaged over (default 1 h, max 24 h). */
+windowMs: z.number().int().min(6e4).max(1440 * 60 * 1e3).default(3600 * 1e3) });
+var PlacementDeviceStatsSchema = z.object({
+	deviceKey: z.string(),
+	/** Sessions running on this device now. */
+	sessionsNow: z.number(),
+	/** Sessions started on this device inside the window. */
+	sessionsStarted: z.number(),
+	/** Time-weighted share of the node's parallel sessions over the window (0–1); null = no session ran. */
+	observedShare: z.number().nullable()
+});
+var PlacementNodeStatsSchema = z.object({
+	nodeId: z.string(),
+	sessionsNow: z.number(),
+	sessionsStarted: z.number(),
+	/** Time-weighted share of the cluster's parallel sessions over the window (0–1); null = none ran. */
+	observedShare: z.number().nullable(),
+	/** Most sessions this node ran at once inside the window. */
+	peakSessions: z.number(),
+	/** Sessions a share election handed elsewhere because this node was full or drowning. */
+	yieldsAway: z.number(),
+	devices: z.array(PlacementDeviceStatsSchema).readonly()
+});
+/** A camera's device pin that the session path cannot honour. */
+var StaleDevicePinSchema = z.object({
+	deviceId: z.number(),
+	deviceKey: z.string(),
+	/** `disabled` — the key exists on some node but is not enabled anywhere; `absent` — no node has it. */
+	reason: z.enum(["disabled", "absent"])
+});
+var PlacementStatsSchema = z.object({
+	policy: SessionPlacementPolicySchema,
+	windowMs: z.number(),
+	/** How much of the window was actually observed (the hub keeps it in memory). */
+	observedForMs: z.number(),
+	sessionsNow: z.number(),
+	/** Most parallel sessions across the cluster inside the window. */
+	clusterPeakSessions: z.number(),
+	nodes: z.array(PlacementNodeStatsSchema).readonly(),
+	stalePins: z.array(StaleDevicePinSchema).readonly()
+});
+var SuggestSharesInputSchema = z.object({ headroom: z.number().min(.3).max(.5).default(.4) });
+var SuggestedDeviceShareSchema = z.object({
+	deviceKey: z.string(),
+	/** Share of the node (0–100, rounded). */
+	share: z.number(),
+	modelId: z.string().nullable(),
+	/** Inferences per second at that model, from the measured table. */
+	fps: z.number().nullable(),
+	measured: z.boolean(),
+	/** Advisory session cap: ⌊fps × (1 − headroom) / camera fps⌋. Never enforced. */
+	suggestedMaxSessions: z.number().nullable()
+});
+var SuggestedNodeShareSchema = z.object({
+	nodeId: z.string(),
+	/** Share of the cluster (0–100, rounded); null = node skipped (offline, unknown hardware). */
+	share: z.number().nullable(),
+	/** Parallel sessions the node sustains at the suggested models with the headroom kept free. */
+	capacitySessions: z.number(),
+	devices: z.array(SuggestedDeviceShareSchema).readonly(),
+	skippedReason: z.string().nullable()
+});
+var SuggestSharesResultSchema = z.object({
+	headroom: z.number(),
+	/** Camera detection rate the capacity is counted in (the fastest camera's fps). */
+	cameraFps: z.number(),
+	/** How many share → model → capacity rounds ran before the shares stopped moving (≤ 3). */
+	iterations: z.number(),
+	nodes: z.array(SuggestedNodeShareSchema).readonly()
+});
+/**
+* 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.
+*/
+var ShareSourceSchema = z.enum(["auto", "manual"]);
+var SetShareSourceInputSchema = z.object({ source: ShareSourceSchema });
+z.object({
+	nodes: z.record(z.string(), z.number()),
+	devices: z.record(z.string(), z.record(z.string(), z.number()))
+});
+var EffectiveDeviceShareSchema = z.object({
+	deviceKey: z.string(),
+	/** Can take sessions now (enabled, available, can run the root). */
+	eligible: z.boolean(),
+	/** The share the source assigns, as a percentage of the node's devices. */
+	configuredPct: z.number(),
+	/** The share actually used, after an ineligible device's share went to the others. */
+	effectivePct: z.number()
+});
+var EffectiveNodeShareSchema = z.object({
+	nodeId: z.string(),
+	eligible: z.boolean(),
+	configuredPct: z.number(),
+	effectivePct: z.number(),
+	devices: z.array(EffectiveDeviceShareSchema).readonly()
+});
+var EffectiveSharesSchema = z.object({
+	source: ShareSourceSchema,
+	policy: SessionPlacementPolicySchema,
+	/** `auto` with no computed answer yet: the stored sliders are used meanwhile. */
+	autoPending: z.boolean(),
+	/** When the automatic shares were last computed (ms epoch); null = never. */
+	computedAt: z.number().nullable(),
+	/** What made the system recompute them last. */
+	trigger: z.string().nullable(),
+	nodes: z.array(EffectiveNodeShareSchema).readonly(),
+	/** The relative weights the election reads (before eligibility). */
+	nodeWeights: z.record(z.string(), z.number()),
+	deviceWeights: z.record(z.string(), z.record(z.string(), z.number()))
+});
+/**
+* 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.
@@ -26742,7 +26878,9 @@ var DeviceDemandSchema = z.object({
 		"estimate",
 		"none"
 	]),
-	observedForMs: z.number().nullable()
+	observedForMs: z.number().nullable(),
+	/** How on-motion sessions were charged: per-device observation, or split by share (D748). */
+	placement: SessionPlacementPolicySchema
 });
 var DeviceModelChoiceSchema = z.object({
 	modelId: z.string(),
@@ -26799,7 +26937,7 @@ var DetectorStoreClearSchema = z.object({
 	deviceId: z.number(),
 	keys: z.array(z.string()).readonly()
 });
-var BestSettingsWarningSchema = z.discriminatedUnion("kind", [
+var AutoTuneWarningSchema = z.discriminatedUnion("kind", [
 	z.object({
 		kind: z.literal("detector-store-cluster-wide"),
 		skippedNodes: z.array(z.string()).readonly()
@@ -26814,26 +26952,36 @@ var BestSettingsWarningSchema = z.discriminatedUnion("kind", [
 		deviceKey: z.string()
 	})
 ]);
-var BestSettingsOptionsSchema = z.object({ 
-/** Share of each accelerator's throughput kept free (0.3–0.5). */
-headroom: z.number().min(.3).max(.5).default(.4) });
-var BestSettingsPlanSchema = z.object({
+var AutoTuneOptionsSchema = z.object({
+	/** Share of each accelerator's throughput kept free (0.3–0.5). */
+	headroom: z.number().min(.3).max(.5).default(.4),
+	/**
+	* What-if shares (D748): plan as if these node/device shares were stored
+	* and the policy were `share`. Absent = the stored shares under the stored
+	* policy. A what-if plan is for display; apply always re-plans from what
+	* is stored.
+	*/
+	shares: LoadBalancingSharesInputSchema.optional()
+});
+var AutoTunePlanSchema = z.object({
 	/** Hash of everything the apply will write — the apply refuses a different one. */
 	planHash: z.string(),
 	family: z.literal("yolov9"),
 	headroom: z.number(),
+	/** Planned under what-if shares (D748): for display — apply refuses it as stale. */
+	whatIf: z.boolean(),
 	generatedAt: z.number(),
 	nodes: z.array(NodeRecommendationSchema).readonly(),
 	nodeChanges: z.array(NodeDeviceChangeSchema).readonly(),
 	cameraClears: z.array(CameraOverrideClearSchema).readonly(),
 	detectorStoreClears: z.array(DetectorStoreClearSchema).readonly(),
-	warnings: z.array(BestSettingsWarningSchema).readonly()
+	warnings: z.array(AutoTuneWarningSchema).readonly()
 });
-var BestSettingsApplyInputSchema = z.object({
+var AutoTuneApplyInputSchema = z.object({
 	planHash: z.string(),
 	headroom: z.number().min(.3).max(.5).default(.4)
 });
-var BestSettingsPhaseResultSchema = z.object({
+var AutoTunePhaseResultSchema = z.object({
 	phase: z.enum([
 		"download",
 		"camera-overrides",
@@ -26844,19 +26992,19 @@ var BestSettingsPhaseResultSchema = z.object({
 	ok: z.boolean(),
 	detail: z.string()
 });
-var BestSettingsApplyResultSchema = z.discriminatedUnion("kind", [
+var AutoTuneApplyResultSchema = z.discriminatedUnion("kind", [
 	z.object({
 		kind: z.literal("applied"),
 		planHash: z.string(),
-		phases: z.array(BestSettingsPhaseResultSchema).readonly()
+		phases: z.array(AutoTunePhaseResultSchema).readonly()
 	}),
 	z.object({
 		kind: z.literal("aborted"),
-		phases: z.array(BestSettingsPhaseResultSchema).readonly()
+		phases: z.array(AutoTunePhaseResultSchema).readonly()
 	}),
 	z.object({
 		kind: z.literal("stale"),
-		plan: BestSettingsPlanSchema
+		plan: AutoTunePlanSchema
 	}),
 	z.object({
 		kind: z.literal("refused"),
@@ -28275,7 +28423,6 @@ var CameraStepOverridePatchSchema = z.object({
 	settings: z.record(z.string(), z.unknown()).readonly().optional()
 });
 var CameraPipelineSettingsSchema = z.object({
-	pinnedAgentNodeId: z.string().optional(),
 	stepToggles: z.record(z.string(), z.boolean()).optional(),
 	stepOverridesByDevice: z.record(z.string(), z.record(z.string(), z.record(z.string(), CameraStepOverridePatchSchema))).optional(),
 	pipelineByAgent: z.record(z.string(), CameraPipelineForAgentSchema).optional()
@@ -28953,18 +29100,6 @@ var pipelineOrchestratorCapability = {
 			auth: "admin"
 		}),
 		/**
-		* Set a node's detection WEIGHT (relative share for the quota balancer).
-		* `null` clears it (back to the implicit weight 1). Unpinned cameras
-		* distribute proportionally to weight; `maxCameras` still clamps on top.
-		*/
-		setAgentDetectWeight: method(z.object({
-			agentNodeId: z.string(),
-			detectWeight: z.number().positive().nullable()
-		}), z.object({ success: z.literal(true) }), {
-			kind: "mutation",
-			auth: "admin"
-		}),
-		/**
 		* Set one node's placement CAPABILITIES — the per-node record that
 		* replaced the four flat orchestrator lists (`enabledNodes`,
 		* `enabledDecoderNodes`, `enabledAudioNodes`, `remoteSourcingNodes`).
@@ -29084,7 +29219,7 @@ var pipelineOrchestratorCapability = {
 			auth: "admin"
 		}),
 		/**
-		* Best settings (D745) — DRY RUN. Recommends ONE detector family (YOLOv9)
+		* Auto tune (D745) — DRY RUN. Recommends ONE detector family (YOLOv9)
 		* for the whole cluster from each node's static hardware class, the
 		* measured latency table and the detection demand, and lists every write
 		* the apply would make: the node model pins set, the enrichment pins and
@@ -29093,14 +29228,57 @@ var pipelineOrchestratorCapability = {
 		* enablement, device enablement, pins, recording, notifications, zones and
 		* rules are never part of it. `planHash` names exactly this diff.
 		*/
-		planBestSettings: method(BestSettingsOptionsSchema, BestSettingsPlanSchema, { auth: "admin" }),
+		planAutoTune: method(AutoTuneOptionsSchema, AutoTunePlanSchema, { auth: "admin" }),
 		/**
-		* Best settings (D745) — APPLY the plan the operator confirmed. Recomputes
+		* Auto tune (D745) — APPLY the plan the operator confirmed. Recomputes
 		* the plan and refuses (`stale`, with the fresh plan) when its hash is not
 		* `planHash`, so what is written is exactly the confirmed diff. Offline
 		* nodes are skipped; there is no undo.
 		*/
-		applyBestSettings: method(BestSettingsApplyInputSchema, BestSettingsApplyResultSchema, {
+		applyAutoTune: method(AutoTuneApplyInputSchema, AutoTuneApplyResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Load balancing (D748) — write node shares (`detectWeight`) and per-node
+		* device shares (inference-device `weight`) in ONE atomic read-modify-write
+		* of the agent settings — the only writer of node shares (the per-node
+		* `setAgentDetectWeight` it replaced raced its siblings, one RMW each).
+		* A node or device left out keeps its weight. Never changes the
+		* `sessionPlacement` policy.
+		*/
+		setLoadBalancingShares: method(LoadBalancingSharesInputSchema, z.object({ success: z.literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Load balancing (D748) — what placement actually did: per node and
+		* device, sessions now, sessions started and the time-weighted share of
+		* PARALLEL sessions over `windowMs`; the cluster's parallel peak; yields
+		* a share election made; and every device pin the session path cannot
+		* honour. In memory on the hub — a restart starts a new window.
+		*/
+		getPlacementStats: method(PlacementStatsInputSchema, PlacementStatsSchema, { auth: "admin" }),
+		/**
+		* Load balancing (D748) — shares proportional to each node's measured
+		* capacity at the models Auto tune would pick, iterated (≤ 3 rounds)
+		* until the shares stop moving; per device, an ADVISORY session cap.
+		* Writes nothing.
+		*/
+		suggestShares: method(SuggestSharesInputSchema, SuggestSharesResultSchema, { auth: "admin" }),
+		/**
+		* Load balancing (D750) — the shares placement reads now: the source
+		* (automatic capacity shares or the operator's sliders), each node's and
+		* device's configured share, and the effective share after a node or
+		* device that cannot take sessions gave its share to the others.
+		*/
+		getEffectiveShares: method(z.void(), EffectiveSharesSchema, { auth: "admin" }),
+		/**
+		* Load balancing (D750) — switch between automatic and manual shares.
+		* Going manual seeds the sliders with the current automatic shares (one
+		* atomic write), so nothing jumps; going automatic recomputes at once.
+		*/
+		setShareSource: method(SetShareSourceInputSchema, z.object({ success: z.literal(true) }), {
 			kind: "mutation",
 			auth: "admin"
 		}),
@@ -52286,7 +52464,7 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
-	"pipelineOrchestrator.applyBestSettings": {
+	"pipelineOrchestrator.applyAutoTune": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
@@ -52406,6 +52584,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getEffectiveShares": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getGlobalMetrics": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -52442,6 +52626,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getPlacementStats": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getReconcileFromDiskStatus": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -52466,7 +52656,7 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.planBestSettings": {
+	"pipelineOrchestrator.planAutoTune": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
@@ -52532,12 +52722,6 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setAgentDetectWeight": {
-		capName: "pipeline-orchestrator",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
 	"pipelineOrchestrator.setAgentInferenceDevices": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -52592,12 +52776,30 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setLoadBalancingShares": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setPipelineDevicePin": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setShareSource": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineOrchestrator.suggestShares": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.unassignAudio": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",