@camstack/system 1.2.159 → 1.2.160

package/dist/{manifest-system-deps-8boi90D9.js → manifest-system-deps-oJMkWSX-.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-require("./dist-Ck2jkBZk.js");
+require("./dist-CcvXUhHK.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto);
 let _camstack_types_node = require("@camstack/types/node");
@@ -5550,6 +5550,246 @@ function createLocalTransport() {
 	};
 }
 //#endregion
+//#region src/kernel/moleculer/cap-usage-registry.ts
+/**
+* In-memory observation of tRPC cap calls between addons — the store behind
+* `nodes.getCapUsageGraph`.
+*
+* Storage: `Map<callerAddonId, Map<providerAddonId, Map<capName, RollingWindow>>>`.
+* `RollingWindow` is a fixed-size ring of 1-second buckets — default 300
+* buckets = 5 minutes retention. Queries narrower than the retention window
+* filter buckets at read time.
+*
+* ── The ring ages, and that is not free decoration ─────────────────────────
+* Buckets are indexed `second % retention`, so a bucket written at second S is
+* hit again at S + retention·k forever. Until 2026-08-30 nothing ever zeroed
+* them: the `lastCallAtMs` guard hid it while a triple was fully idle, but ONE
+* fresh call re-armed the entire stale ring. A triple that made 1000 calls and
+* then one call five minutes later reported **1001 calls/min instead of 1**.
+* An over-counted edge is worse than the empty graph this instrument shipped
+* with — silence invites doubt, a confident wrong number sends the next
+* investigation at the wrong addon.
+*
+* The fix is clear-forward: on each record, zero the buckets the ring has
+* ADVANCED over since the previous write, and never read past the last written
+* second. Amortised O(1) — a busy triple clears 0–1 buckets per call, and an
+* idle one clears at most `retention` once, when it wakes.
+*
+* ── Cardinality is bounded, because this map lives on hub-main ─────────────
+* The previous docblock claimed "~22 MB worst case … under 200 KB at ~10 active
+* triples". Both numbers were written for a smaller machine and the second was
+* an assumption, not a bound: the key space is caller × provider × cap, and on
+* the live hub that is 64 addons × 64 runners × ~150 caps. Nothing capped it.
+*
+* Today a ring is one `Uint32Array(retention)` — 1.2 KB of ArrayBuffer at the
+* default — plus the three Map entries that reach it. MEASURED (`heapUsed` +
+* `arrayBuffers`, node 24, `--expose-gc`): **1.7 KB per triple**, so ≈1.0 MB at
+* the realistic hub figure (64 callers × a handful of caps each, ≈600 triples)
+* and **6.3 MB at the {@link DEFAULT_MAX_TRIPLES} ceiling**. `recordCall` costs
+* ≈46 ns (1e6 calls in 46 ms) — at the 39 717 calls/min that started this
+* investigation, ≈30 µs of hub-main per second.
+*
+* Reclamation is what keeps it at the low end: a triple whose ring has entirely
+* aged out is dead data and is dropped on the next admission sweep. The hard
+* cap only exists so that a pathological key space (a caller id derived from
+* something unbounded) cannot take hub-main's heap with it — and when it bites,
+* {@link CapUsageRegistry.getStats} says how often, because an instrument that
+* truncates silently is the defect this whole file exists to fix (D237).
+*/
+/** Ring length in seconds when the caller does not pick one. */
+var DEFAULT_RETENTION_SECONDS = 300;
+/**
+* Ceiling on live `(caller, provider, cap)` triples. ≈1.5 KB each → ≈6 MB.
+* Roughly 6× the realistic hub figure, so it is a backstop against an
+* unbounded key space, not a working limit.
+*/
+var DEFAULT_MAX_TRIPLES = 4e3;
+/**
+* Provider placeholder for a call the PARENT routed rather than short-
+* circuiting to a sibling runner: hub-in-process (`settings-store`,
+* `device-manager`, the `$core-caps` bridge), or a remote node. At the layer
+* that records — the parent's `cap-call-out` handler — the sibling id IS the
+* provider and everything else has not been resolved yet.
+*
+* It is a NAMED unknown, not a dropped observation, for the reason D237 was
+* written: the caller is always known, and "who is hammering `settings-store`"
+* is the question this graph exists to answer. Sibling to
+* `UNRESOLVED_PROVIDER_ADDON_ID` in `trpc-links.ts`, which names the same kind
+* of unknown one layer up.
+*/
+var PARENT_ROUTED_PROVIDER_ADDON_ID = "(unresolved: parent-routed)";
+var CapUsageRegistry = class {
+	retentionSeconds;
+	maxTriples;
+	map = /* @__PURE__ */ new Map();
+	triples = 0;
+	droppedTriples = 0;
+	constructor(opts) {
+		this.retentionSeconds = Math.max(1, opts?.retentionSeconds ?? DEFAULT_RETENTION_SECONDS);
+		this.maxTriples = Math.max(1, opts?.maxTriples ?? DEFAULT_MAX_TRIPLES);
+	}
+	/**
+	* Record one observed cap call.
+	*
+	* On the hot path: this runs once per cross-process cap call on hub-main's
+	* event loop, which is the cluster's only queue (D181). Three Map lookups, an
+	* integer increment, and — only when the wall clock has moved on — a bounded
+	* clear. No allocation once a triple exists, and it NEVER throws into the
+	* call it observes.
+	*/
+	recordCall(rec) {
+		try {
+			if (rec.callerAddonId === "" || rec.providerAddonId === "" || rec.capName === "") return;
+			if (!Number.isFinite(rec.atMs) || rec.atMs < 0) return;
+			const window = this.windowFor(rec);
+			if (window === null) return;
+			const sec = Math.floor(rec.atMs / 1e3);
+			if (window.lastCallAtMs !== 0) {
+				const lastSec = Math.floor(window.lastCallAtMs / 1e3);
+				const advanced = Math.min(sec - lastSec, this.retentionSeconds);
+				for (let k = 1; k <= advanced; k++) window.buckets[(lastSec + k) % this.retentionSeconds] = 0;
+			}
+			const idx = sec % this.retentionSeconds;
+			window.buckets[idx] = (window.buckets[idx] ?? 0) + 1;
+			if (rec.atMs > window.lastCallAtMs) window.lastCallAtMs = rec.atMs;
+		} catch {}
+	}
+	getGraph(opts) {
+		const windowSeconds = Math.max(1, Math.min(opts.windowSeconds, this.retentionSeconds));
+		const minMs = opts.nowMs - windowSeconds * 1e3;
+		const nowSec = Math.floor(opts.nowMs / 1e3);
+		const out = [];
+		for (const [caller, byProvider] of this.map) for (const [provider, byCap] of byProvider) for (const [capName, window] of byCap) {
+			if (window.lastCallAtMs < minMs) continue;
+			const count = this.sumWindow(window, nowSec, windowSeconds);
+			if (count === 0) continue;
+			const callsPerMin = count / windowSeconds * 60;
+			out.push({
+				callerAddonId: caller,
+				providerAddonId: provider,
+				capName,
+				callsPerMin,
+				lastCallAtMs: window.lastCallAtMs
+			});
+		}
+		return out;
+	}
+	/** See {@link CapUsageStats}. Cheap — three counters, no scan. */
+	getStats() {
+		return {
+			triples: this.triples,
+			maxTriples: this.maxTriples,
+			droppedTriples: this.droppedTriples
+		};
+	}
+	/** Test / diagnostic helper — drops all recorded calls. */
+	clear() {
+		this.map.clear();
+		this.triples = 0;
+		this.droppedTriples = 0;
+	}
+	/**
+	* Sum the buckets covering `(nowSec - windowSeconds, nowSec]`.
+	*
+	* The scan starts at `lastSec`, never at `nowSec`. `recordCall` clears the
+	* buckets the ring has advanced OVER, which by definition stops at the last
+	* write: the buckets for the seconds since then still hold whatever the
+	* previous pass left in them, and reading `nowSec` down would count it. A
+	* triple that went quiet for a couple of minutes and then made one call would
+	* report the burst it made five minutes earlier.
+	*
+	* No lower bound is needed beyond the window itself: every bucket at or below
+	* `lastSec - retention` was cleared by the advance that reached `lastSec`, so
+	* it reads zero anyway. The loop is bounded by `windowSeconds ≤ retention`.
+	*/
+	sumWindow(window, nowSec, windowSeconds) {
+		const lastSec = Math.floor(window.lastCallAtMs / 1e3);
+		const from = Math.min(nowSec, lastSec);
+		const floorSec = nowSec - windowSeconds;
+		let count = 0;
+		for (let s = from; s > floorSec; s--) count += window.buckets[s % this.retentionSeconds] ?? 0;
+		return count;
+	}
+	/**
+	* The ring for this triple, creating it if the ceiling allows. `null` means
+	* the observation is dropped — counted, never silent (see
+	* {@link CapUsageStats.droppedTriples}).
+	*/
+	windowFor(rec) {
+		let byProvider = this.map.get(rec.callerAddonId);
+		if (!byProvider) {
+			byProvider = /* @__PURE__ */ new Map();
+			this.map.set(rec.callerAddonId, byProvider);
+		}
+		let byCap = byProvider.get(rec.providerAddonId);
+		if (!byCap) {
+			byCap = /* @__PURE__ */ new Map();
+			byProvider.set(rec.providerAddonId, byCap);
+		}
+		const existing = byCap.get(rec.capName);
+		if (existing) return existing;
+		if (this.triples >= this.maxTriples) {
+			this.reclaimExpired(rec.atMs);
+			if (this.triples >= this.maxTriples) {
+				this.droppedTriples++;
+				return null;
+			}
+			byProvider = this.map.get(rec.callerAddonId);
+			if (!byProvider) {
+				byProvider = /* @__PURE__ */ new Map();
+				this.map.set(rec.callerAddonId, byProvider);
+			}
+			byCap = byProvider.get(rec.providerAddonId);
+			if (!byCap) {
+				byCap = /* @__PURE__ */ new Map();
+				byProvider.set(rec.providerAddonId, byCap);
+			}
+		}
+		const created = {
+			buckets: new Uint32Array(this.retentionSeconds),
+			lastCallAtMs: 0
+		};
+		byCap.set(rec.capName, created);
+		this.triples++;
+		return created;
+	}
+	/**
+	* Drop every triple whose whole ring has aged out — its last call is older
+	* than the retention window, so it can contribute to no query. O(triples),
+	* and only reachable when the ceiling is full, so it is amortised away by the
+	* admissions it enables.
+	*/
+	reclaimExpired(nowMs) {
+		const cutoff = nowMs - this.retentionSeconds * 1e3;
+		for (const [caller, byProvider] of this.map) {
+			for (const [provider, byCap] of byProvider) {
+				for (const [capName, window] of byCap) {
+					if (window.lastCallAtMs >= cutoff) continue;
+					byCap.delete(capName);
+					this.triples--;
+				}
+				if (byCap.size === 0) byProvider.delete(provider);
+			}
+			if (byProvider.size === 0) this.map.delete(caller);
+		}
+	}
+};
+var singleton = null;
+/**
+* The registry for THIS process. Deliberately per-process: the reader
+* (`nodes.getCapUsageGraph` → `cap-providers.ts`) runs on hub-main, so only
+* writes made on hub-main are ever visible. See the blind-spot list on
+* `LocalChildRegistryOptions.capUsageObserver` for what that excludes.
+*/
+function getCapUsageRegistry() {
+	if (!singleton) singleton = new CapUsageRegistry();
+	return singleton;
+}
+/** Test helper — clears the singleton (kept module-private elsewhere). */
+function __resetCapUsageRegistryForTests() {
+	singleton = null;
+}
+//#endregion
 //#region src/kernel/moleculer/event-bus-core.ts
 /**
 * @param retainRecent - `true` ONLY for the hub main broker bus (it serves
@@ -6241,6 +6481,8 @@ var LocalChildRegistry = class {
 	isAddonPinnedCall;
 	/** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
 	capTimeoutMs;
+	/** See {@link LocalChildRegistryOptions.capUsageObserver}. */
+	capUsageObserver;
 	/** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
 	egressRoutedCaps = /* @__PURE__ */ new Set();
 	/** Active event fan-out mode, read once from `CAMSTACK_UDS_EVENT_FANOUT`. */
@@ -6272,6 +6514,7 @@ var LocalChildRegistry = class {
 			this.isAggregatedCollectionMethod = opts.isAggregatedCollectionMethod;
 			this.isAddonPinnedCall = opts.isAddonPinnedCall;
 			this.capTimeoutMs = opts.capTimeoutMs;
+			this.capUsageObserver = opts.capUsageObserver;
 		} else {
 			this.server = serverOrOptions;
 			this.onUnownedCall = onUnownedCallArg;
@@ -6438,6 +6681,29 @@ var LocalChildRegistry = class {
 		}
 		return candidates[0];
 	}
+	/**
+	* Publish one cap-usage observation, if a sink is wired.
+	*
+	* Cost discipline — this is on the hot path (D181: hub-main's event loop is
+	* the cluster's only queue): no sink means one undefined check; with a sink
+	* it is one object literal and one `Date.now()`, and the sink itself is O(1).
+	* Wrapped so a broken observer can never fail the call it observes — the
+	* registry swallows too, and BOTH matter: this catch also covers a sink that
+	* is not the registry.
+	*/
+	recordCapUsage(callerChildId, providerChildId, capName, methodName) {
+		const sink = this.capUsageObserver;
+		if (sink === void 0 || callerChildId === null) return;
+		try {
+			sink({
+				callerAddonId: callerChildId,
+				providerAddonId: providerChildId ?? "(unresolved: parent-routed)",
+				capName,
+				methodName,
+				atMs: Date.now()
+			});
+		} catch {}
+	}
 	/** First child whose cap manifest contains a descriptor matching `predicate`. */
 	findChildId(predicate) {
 		for (const entry of this.children.values()) if (entry.caps.some(predicate)) return entry.childId;
@@ -6707,7 +6973,9 @@ var LocalChildRegistry = class {
 				const pinTargetsThisNode = pinnedNodeId !== void 0 && this.ownNodeId !== void 0 && pinnedNodeId === this.ownNodeId;
 				const aggregated = pinnedNodeId === void 0 && this.isAggregatedCollectionMethod?.(out.capName, out.method) === true;
 				const addonPinned = pinnedNodeId === void 0 && this.isAddonPinnedCall?.(out.capName, out.method, out.args) === true;
-				if ((!(out.native === true) && !aggregated && !addonPinned && (pinnedNodeId === void 0 || pinTargetsThisNode) ? this.resolveChildId(out.capName, out.deviceId) : null) !== null) {
+				const target = !(out.native === true) && !aggregated && !addonPinned && (pinnedNodeId === void 0 || pinTargetsThisNode) ? this.resolveChildId(out.capName, out.deviceId) : null;
+				this.recordCapUsage(childId, target, out.capName, out.method);
+				if (target !== null) {
 					if (!this.egressRoutedCaps.has(out.capName)) {
 						this.egressRoutedCaps.add(out.capName);
 						this.logger?.info("routed child egress over UDS", { capName: out.capName });
@@ -7859,80 +8127,6 @@ function buildLinkChain(target, localResolver, hookup) {
 	return links;
 }
 //#endregion
-//#region src/kernel/moleculer/cap-usage-registry.ts
-var CapUsageRegistry = class {
-	retentionSeconds;
-	map = /* @__PURE__ */ new Map();
-	constructor(opts) {
-		this.retentionSeconds = Math.max(1, opts?.retentionSeconds ?? 300);
-	}
-	recordCall(rec) {
-		try {
-			if (rec.callerAddonId === "" || rec.providerAddonId === "" || rec.capName === "") return;
-			if (!Number.isFinite(rec.atMs) || rec.atMs < 0) return;
-			let byProvider = this.map.get(rec.callerAddonId);
-			if (!byProvider) {
-				byProvider = /* @__PURE__ */ new Map();
-				this.map.set(rec.callerAddonId, byProvider);
-			}
-			let byCap = byProvider.get(rec.providerAddonId);
-			if (!byCap) {
-				byCap = /* @__PURE__ */ new Map();
-				byProvider.set(rec.providerAddonId, byCap);
-			}
-			let window = byCap.get(rec.capName);
-			if (!window) {
-				window = {
-					buckets: Array.from({ length: this.retentionSeconds }, () => 0),
-					lastCallAtMs: 0
-				};
-				byCap.set(rec.capName, window);
-			}
-			const bucketIdx = Math.floor(rec.atMs / 1e3) % this.retentionSeconds;
-			window.buckets[bucketIdx] = (window.buckets[bucketIdx] ?? 0) + 1;
-			if (rec.atMs > window.lastCallAtMs) window.lastCallAtMs = rec.atMs;
-		} catch {}
-	}
-	getGraph(opts) {
-		const windowSeconds = Math.max(1, Math.min(opts.windowSeconds, this.retentionSeconds));
-		const minMs = opts.nowMs - windowSeconds * 1e3;
-		const out = [];
-		for (const [caller, byProvider] of this.map) for (const [provider, byCap] of byProvider) for (const [capName, window] of byCap) {
-			if (window.lastCallAtMs < minMs) continue;
-			const nowBucket = Math.floor(opts.nowMs / 1e3);
-			let count = 0;
-			for (let i = 0; i < windowSeconds; i++) {
-				const b = (nowBucket - i + this.retentionSeconds * 1e6) % this.retentionSeconds;
-				count += window.buckets[b] ?? 0;
-			}
-			if (count === 0) continue;
-			const callsPerMin = count / windowSeconds * 60;
-			out.push({
-				callerAddonId: caller,
-				providerAddonId: provider,
-				capName,
-				callsPerMin,
-				lastCallAtMs: window.lastCallAtMs
-			});
-		}
-		return out;
-	}
-	/** Test / diagnostic helper — drops all recorded calls. */
-	clear() {
-		this.map.clear();
-	}
-};
-var singleton = null;
-/** Hub-side singleton. The first caller seeds it; subsequent calls return the same. */
-function getCapUsageRegistry() {
-	if (!singleton) singleton = new CapUsageRegistry();
-	return singleton;
-}
-/** Test helper — clears the singleton (kept module-private elsewhere). */
-function __resetCapUsageRegistryForTests() {
-	singleton = null;
-}
-//#endregion
 //#region src/kernel/hwaccel/hwaccel-resolver.ts
 /**
 * Platform-probe for hardware video decode acceleration.
@@ -9867,6 +10061,12 @@ Object.defineProperty(exports, "NATIVE_PROVIDER_SERVICE_INFIX", {
 		return NATIVE_PROVIDER_SERVICE_INFIX;
 	}
 });
+Object.defineProperty(exports, "PARENT_ROUTED_PROVIDER_ADDON_ID", {
+	enumerable: true,
+	get: function() {
+		return PARENT_ROUTED_PROVIDER_ADDON_ID;
+	}
+});
 Object.defineProperty(exports, "RSS_BUDGET_REANNOUNCE_MIN_MS", {
 	enumerable: true,
 	get: function() {

package/dist/{retired-settings-keys-Bi0ZKBjb.mjs → retired-settings-keys-C3eONTvV.mjs}

@@ -1,4 +1,4 @@
-import { Ht as asJsonObject } from "./dist-DLh4_rn3.mjs";
+import { Ht as asJsonObject } from "./dist-DKs---Vx.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-Dp_CyuCW.js → retired-settings-keys-DXZ2xe7C.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-Ck2jkBZk.js");
+const require_dist = require("./dist-CcvXUhHK.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.159",
+  "version": "1.2.160",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",