@camstack/system 1.1.19 → 1.1.20

package/dist/{manifest-python-deps-C1Dd9MSr.mjs → manifest-python-deps-X00KVYHa.mjs}

@@ -3358,6 +3358,133 @@ function createLocalTransport() {
 	};
 }
 //#endregion
+//#region src/kernel/moleculer/event-bus-core.ts
+/**
+* @param retainRecent - `true` ONLY for the hub main broker bus (it serves
+*   `getRecent`). Defaults to `false` — the safe one-shot default for child
+*   runners + agents, which retain nothing.
+*/
+function createSharedBusState(retainRecent = false) {
+	return {
+		handlers: /* @__PURE__ */ new Map(),
+		recent: [],
+		retainRecent
+	};
+}
+function matchesPattern(pattern, category) {
+	if (pattern === "*" || pattern === "**") return true;
+	if (pattern.endsWith(".**")) return category.startsWith(pattern.slice(0, -3));
+	if (pattern.endsWith(".*")) return category.startsWith(pattern.slice(0, -2));
+	return pattern === category;
+}
+function extractCategoryPattern(filter) {
+	if (typeof filter === "string") return filter;
+	if (filter && typeof filter === "object" && "category" in filter) {
+		const cat = filter.category;
+		if (typeof cat === "string") return cat;
+		if (Array.isArray(cat) && cat.length > 0) return String(cat[0]);
+	}
+	return "*";
+}
+/**
+* Match an event against the full `EventFilter`. The Map-keyed subscribe path
+* only handles the category pattern (deciding which handler set to fan out to);
+* this function applies the remaining scope dimensions (`agentId`, `addonId`,
+* `deviceId`, `source`, `since`) so per-device / per-addon subscribers don't
+* receive sibling events.
+*/
+function matchesEventFilter(event, filter) {
+	if (!filter || typeof filter === "string") return true;
+	if (filter.source) {
+		if (event.source.type !== filter.source.type || event.source.id !== filter.source.id) return false;
+	}
+	if (filter.agentId) {
+		const eventNodeId = event.source.nodeId;
+		if (!eventNodeId || eventNodeId !== filter.agentId && !eventNodeId.startsWith(`${filter.agentId}/`)) return false;
+	}
+	if (filter.addonId) {
+		if ((event.source.addonId ?? (event.source.type === "addon" ? String(event.source.id) : void 0)) !== filter.addonId) return false;
+	}
+	if (filter.deviceId !== void 0) {
+		if ((event.source.deviceId ?? (event.source.type === "device" ? Number(event.source.id) : void 0)) !== filter.deviceId) return false;
+	}
+	if (filter.since && event.timestamp < filter.since) return false;
+	return true;
+}
+/**
+* Categories filtered out of the `recent[]` ring buffer.
+*
+* High-frequency, low-value-for-the-operator categories — periodic metrics
+* snapshots, per-frame inference traces, raw motion-mask dumps, model-download
+* progress, etc. They still fan out to live subscribers (UI charts that
+* explicitly listen for them), but do NOT enter the recent-events ring so
+* meaningful events (motion / phase transitions / device lifecycle / addon
+* lifecycle / recording / detection.event) survive in the last-N window without
+* being displaced by per-frame noise.
+*/
+var RING_BUFFER_DENY_PATTERNS = [
+	"pipeline.camera-metrics-snapshot",
+	"pipeline.runner-load-snapshot",
+	"pipeline.engine-metrics-snapshot",
+	"pipeline.inference-result",
+	"pipeline.trace",
+	"pipeline.progress",
+	"stream-broker.metrics-snapshot",
+	"metrics.node-resources-snapshot",
+	"metrics.node-processes-snapshot",
+	"cluster.topology-snapshot",
+	"detection.motion-analysis",
+	"detection.motion-zones-raw",
+	"detection.result",
+	"pipeline.audio-inference-result",
+	"platform-probe.phase",
+	"benchmark.progress",
+	"model.download.progress",
+	"pipeline-analytics.frame-tracked",
+	"pipeline-analytics.detection-event",
+	"pipeline-analytics.track-started",
+	"pipeline-analytics.track-ended",
+	"motion.on-motion-changed",
+	"capability.binding-changed"
+];
+/**
+* Hard cap on the `recent[]` buffer size. Even audit-grade categories that
+* are NOT on the deny-list (e.g. `device.state-changed`) must not accumulate
+* without bound — this is the last-N window, not a durable log. Without this
+* cap the buffer grew forever (~26 MB/h/process across every broker, agent,
+* and UDS-child bus), filling the hub to 16 GB.
+*/
+var MAX_RECENT_EVENTS = 1e3;
+function isHighFrequencyCategory(category) {
+	for (const pattern of RING_BUFFER_DENY_PATTERNS) if (matchesPattern(pattern, category)) return true;
+	return false;
+}
+/**
+* Deliver `event` to all matching local subscribers and — ONLY on a bus that
+* opted into retention (`state.retainRecent`, i.e. the hub main process) and
+* unless the event is high-frequency — append it to the bounded `recent[]`
+* ring.
+*
+* On a non-retaining bus (child runners, agents) the retention block is skipped
+* entirely: events are one-shot / fire-and-forget, still fanned out to local
+* subscribers but never accumulated. `getRecent` on such a bus returns `[]`.
+*/
+function deliverShared(state, event) {
+	if (state.retainRecent && !isHighFrequencyCategory(event.category)) {
+		state.recent.push(event);
+		if (state.recent.length > 1e3) state.recent.splice(0, state.recent.length - MAX_RECENT_EVENTS);
+	}
+	for (const [pattern, set] of state.handlers) {
+		if (!matchesPattern(pattern, event.category)) continue;
+		for (const entry of set) {
+			if (!matchesEventFilter(event, entry.filter)) continue;
+			try {
+				entry.handler(event);
+			} catch (err) {}
+		}
+	}
+}
+//#endregion
 //#region src/kernel/moleculer/resilient-cap-call.ts
 /** Moleculer error `type` values meaning "the service is not (yet) routable". */
 var DISCOVERY_ERROR_TYPES = new Set(["SERVICE_NOT_FOUND", "SERVICE_NOT_AVAILABLE"]);
@@ -3752,6 +3879,11 @@ var CapRouteResolver = class {
 };
 //#endregion
 //#region src/kernel/transport/local-child-registry.ts
+function readFanoutMode() {
+	const raw = process.env.CAMSTACK_UDS_EVENT_FANOUT;
+	if (raw === "shadow" || raw === "broadcast") return raw;
+	return "filter";
+}
 /**
 * Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
 * local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
@@ -3779,6 +3911,12 @@ var LocalChildRegistry = class {
 	resolveChildIdForAddon;
 	/** 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`. */
+	fanoutMode = readFanoutMode();
+	/** Per-child event fan-out counters (sent / suppressed). */
+	childEventStats = /* @__PURE__ */ new Map();
+	/** Last pattern-set string logged per child, to dedup the INFO line. */
+	loggedPatternSet = /* @__PURE__ */ new Map();
 	/**
 	* Accepts either a plain positional `server` argument (backward-compatible)
 	* or a full `LocalChildRegistryOptions` object.
@@ -3804,10 +3942,61 @@ var LocalChildRegistry = class {
 		}
 	}
 	async start() {
+		this.logger?.info("UDS event fan-out mode", { mode: this.fanoutMode });
 		this.server.onConnection((channel) => this.onConnection(channel));
 		await this.server.listen();
 	}
 	/**
+	* Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
+	* child has no recorded events yet. Exposed for the starvation-verification
+	* surface (shadow burn-in + operator debug).
+	*/
+	getChildEventStats(childId) {
+		const s = this.childEventStats.get(childId);
+		return s === void 0 ? null : {
+			sent: s.sent,
+			suppressed: s.suppressed
+		};
+	}
+	/**
+	* Does `entry` want to receive an event in `category`? Honours the fan-out
+	* mode: `broadcast` → always; undeclared patterns (`null`) → always
+	* (fail-open); else the child's declared set must match via `matchesPattern`
+	* — the SAME function the child's own `deliverShared` map-key gate uses,
+	* giving provable delivery parity. `shadow` is handled by the caller (it
+	* counts the would-suppress but still sends).
+	*
+	* NOTE: this gate must NOT consult `RING_BUFFER_DENY_PATTERNS` /
+	* `isHighFrequencyCategory` — those are ring-buffer STORAGE policy; a child
+	* that explicitly subscribes to a ring-denied category must still RECEIVE it.
+	*/
+	childWantsEvent(entry, category) {
+		if (this.fanoutMode === "broadcast") return true;
+		if (entry.eventPatterns === null) return true;
+		return entry.eventPatterns.some((p) => matchesPattern(p, category));
+	}
+	statsFor(childId) {
+		let s = this.childEventStats.get(childId);
+		if (s === void 0) {
+			s = {
+				sent: 0,
+				suppressed: 0
+			};
+			this.childEventStats.set(childId, s);
+		}
+		return s;
+	}
+	/** Deduped INFO line whenever a child's declared pattern set changes. */
+	logPatternSet(childId, patterns) {
+		const key = patterns === null ? "<undeclared>" : JSON.stringify([...patterns].toSorted());
+		if (this.loggedPatternSet.get(childId) === key) return;
+		this.loggedPatternSet.set(childId, key);
+		this.logger?.info("child event patterns", {
+			childId,
+			patterns: patterns ?? null
+		});
+	}
+	/**
 	* Child id that can service a call to `capName` (optionally addressing
 	* `deviceId`), or null.
 	*
@@ -3986,14 +4175,20 @@ var LocalChildRegistry = class {
 	* one (the originating child, to avoid echo). Fire-and-forget.
 	*/
 	broadcastEventToChildren(event, sourceNodeId, exceptChildId) {
+		const msg = {
+			kind: "event",
+			event,
+			sourceNodeId
+		};
 		for (const entry of this.children.values()) {
 			if (entry.childId === exceptChildId) continue;
-			const msg = {
-				kind: "event",
-				event,
-				sourceNodeId
-			};
-			entry.channel.emit(msg);
+			const wants = this.childWantsEvent(entry, event.category);
+			const stats = this.statsFor(entry.childId);
+			if (!wants) stats.suppressed++;
+			if (wants || this.fanoutMode === "shadow") {
+				stats.sent++;
+				entry.channel.emit(msg);
+			}
 		}
 	}
 	/**
@@ -4029,17 +4224,31 @@ var LocalChildRegistry = class {
 				if (childId !== null) this.logHandler?.(childId, msg);
 				return;
 			}
+			if (msg.kind === "event-sub") {
+				if (childId === null) return;
+				const entry = this.children.get(childId);
+				if (entry === void 0) return;
+				this.children.set(childId, {
+					...entry,
+					eventPatterns: msg.patterns
+				});
+				this.logPatternSet(childId, msg.patterns);
+				return;
+			}
 		});
 		channel.onRequest(async (body) => {
 			const msg = body;
 			if (msg.kind === "register") {
 				if (childId !== null && childId !== msg.childId) throw new Error(`child attempted to change identity from "${childId}" to "${msg.childId}"`);
 				childId = msg.childId;
+				const eventPatterns = msg.eventPatterns ?? null;
 				this.children.set(msg.childId, {
 					childId: msg.childId,
 					channel,
-					caps: msg.caps
+					caps: msg.caps,
+					eventPatterns
 				});
+				this.logPatternSet(msg.childId, eventPatterns);
 				this.registeredHandler({
 					childId: msg.childId,
 					caps: msg.caps
@@ -4072,7 +4281,11 @@ var LocalChildRegistry = class {
 			throw new Error(`unknown child request kind: ${msg.kind}`);
 		});
 		channel.onClose(() => {
-			if (childId !== null && this.children.delete(childId)) this.goneHandler(childId);
+			if (childId !== null && this.children.delete(childId)) {
+				this.childEventStats.delete(childId);
+				this.loggedPatternSet.delete(childId);
+				this.goneHandler(childId);
+			}
 		});
 	}
 };
@@ -4104,6 +4317,24 @@ var LocalChildClient = class {
 	* the latest set) instead of being lost or throwing.
 	*/
 	latestCaps;
+	/**
+	* Per-owner (addonId) category-pattern subscription sets, and their union.
+	* The union is declared to the parent (in `RegisterMessage.eventPatterns`
+	* pre/at-connect, or via an `event-sub` emit post-connect) so the parent can
+	* subscription-filter its event fan-out. Per-owner keying keeps the union
+	* correct if multiple event buses ever share one client (group-runner case).
+	*/
+	patternsByOwner = /* @__PURE__ */ new Map();
+	latestEventPatterns = [];
+	/**
+	* Whether `updateEventPatterns` has ever been called. A client that never
+	* declared a subscription set (no event bus wired — e.g. a pure cap-call
+	* runner) omits `eventPatterns` from its register frame entirely, so the
+	* parent treats it as UNDECLARED and fails OPEN (broadcast-all). Once any
+	* owner declares (in production every addon context's framework
+	* subscriptions do), the register carries the real union — even if empty.
+	*/
+	hasDeclaredEventPatterns = false;
 	/** Events and logs queued while the channel is not yet open. */
 	pendingEmits = [];
 	/** Handler for parent→child events. Registered via `onEvent`. */
@@ -4130,6 +4361,42 @@ var LocalChildClient = class {
 		this.latestCaps = options.caps;
 	}
 	/**
+	* Declare an owner's live category-pattern subscription set. Stores it
+	* per-owner (keyed by `ownerId` = addonId), recomputes the union, and — only
+	* if the union changed — declares it to the parent:
+	*   - pre-connect: buffered only; `start()`'s register frame carries the set.
+	*   - post-connect: emitted as a fire-and-forget `event-sub` (full-set
+	*     replace).
+	* Idempotent on an unchanged union (no redundant `event-sub` frames).
+	*/
+	updateEventPatterns(ownerId, patterns) {
+		this.hasDeclaredEventPatterns = true;
+		this.patternsByOwner.set(ownerId, patterns);
+		const union = this.computePatternUnion();
+		if (!this.patternsEqual(union, this.latestEventPatterns)) {
+			this.latestEventPatterns = union;
+			if (this.channel !== null) {
+				const msg = {
+					kind: "event-sub",
+					patterns: union
+				};
+				this.channel.emit(msg);
+			}
+		}
+	}
+	/** Sorted, de-duplicated union across all owners' pattern sets. */
+	computePatternUnion() {
+		const all = /* @__PURE__ */ new Set();
+		for (const patterns of this.patternsByOwner.values()) for (const p of patterns) all.add(p);
+		return [...all].toSorted();
+	}
+	/** Order-insensitive equality — both inputs are already sorted unions here. */
+	patternsEqual(a, b) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+		return true;
+	}
+	/**
 	* Register a callback that fires each time the client successfully connects
 	* (or reconnects) to its parent. Multiple handlers may be registered; all
 	* are called in registration order. Used by readiness-context in UDS mode
@@ -4208,7 +4475,8 @@ var LocalChildClient = class {
 		const register = {
 			kind: "register",
 			childId: this.options.childId,
-			caps: this.latestCaps
+			caps: this.latestCaps,
+			...this.hasDeclaredEventPatterns ? { eventPatterns: this.latestEventPatterns } : {}
 		};
 		try {
 			await channel.request(register);
@@ -4241,7 +4509,8 @@ var LocalChildClient = class {
 		const register = {
 			kind: "register",
 			childId: this.options.childId,
-			caps
+			caps,
+			...this.hasDeclaredEventPatterns ? { eventPatterns: this.latestEventPatterns } : {}
 		};
 		await this.channel.request(register);
 	}
@@ -4402,105 +4671,6 @@ function udsChildLogToWorkerEntry(childId, entry) {
 	};
 }
 //#endregion
-//#region src/kernel/moleculer/event-bus-core.ts
-function createSharedBusState() {
-	return {
-		handlers: /* @__PURE__ */ new Map(),
-		recent: []
-	};
-}
-function matchesPattern(pattern, category) {
-	if (pattern === "*" || pattern === "**") return true;
-	if (pattern.endsWith(".**")) return category.startsWith(pattern.slice(0, -3));
-	if (pattern.endsWith(".*")) return category.startsWith(pattern.slice(0, -2));
-	return pattern === category;
-}
-function extractCategoryPattern(filter) {
-	if (typeof filter === "string") return filter;
-	if (filter && typeof filter === "object" && "category" in filter) {
-		const cat = filter.category;
-		if (typeof cat === "string") return cat;
-		if (Array.isArray(cat) && cat.length > 0) return String(cat[0]);
-	}
-	return "*";
-}
-/**
-* Match an event against the full `EventFilter`. The Map-keyed subscribe path
-* only handles the category pattern (deciding which handler set to fan out to);
-* this function applies the remaining scope dimensions (`agentId`, `addonId`,
-* `deviceId`, `source`, `since`) so per-device / per-addon subscribers don't
-* receive sibling events.
-*/
-function matchesEventFilter(event, filter) {
-	if (!filter || typeof filter === "string") return true;
-	if (filter.source) {
-		if (event.source.type !== filter.source.type || event.source.id !== filter.source.id) return false;
-	}
-	if (filter.agentId) {
-		const eventNodeId = event.source.nodeId;
-		if (!eventNodeId || eventNodeId !== filter.agentId && !eventNodeId.startsWith(`${filter.agentId}/`)) return false;
-	}
-	if (filter.addonId) {
-		if ((event.source.addonId ?? (event.source.type === "addon" ? String(event.source.id) : void 0)) !== filter.addonId) return false;
-	}
-	if (filter.deviceId !== void 0) {
-		if ((event.source.deviceId ?? (event.source.type === "device" ? Number(event.source.id) : void 0)) !== filter.deviceId) return false;
-	}
-	if (filter.since && event.timestamp < filter.since) return false;
-	return true;
-}
-/**
-* Categories filtered out of the `recent[]` ring buffer.
-*
-* High-frequency, low-value-for-the-operator categories — periodic metrics
-* snapshots, per-frame inference traces, raw motion-mask dumps, model-download
-* progress, etc. They still fan out to live subscribers (UI charts that
-* explicitly listen for them), but do NOT enter the recent-events ring so
-* meaningful events (motion / phase transitions / device lifecycle / addon
-* lifecycle / recording / detection.event) survive in the last-N window without
-* being displaced by per-frame noise.
-*/
-var RING_BUFFER_DENY_PATTERNS = [
-	"pipeline.camera-metrics-snapshot",
-	"pipeline.runner-load-snapshot",
-	"pipeline.engine-metrics-snapshot",
-	"pipeline.inference-result",
-	"pipeline.trace",
-	"pipeline.progress",
-	"stream-broker.metrics-snapshot",
-	"metrics.node-resources-snapshot",
-	"metrics.node-processes-snapshot",
-	"cluster.topology-snapshot",
-	"detection.motion-analysis",
-	"detection.motion-zones-raw",
-	"detection.result",
-	"pipeline.audio-inference-result",
-	"platform-probe.phase",
-	"benchmark.progress",
-	"model.download.progress",
-	"capability.binding-changed"
-];
-function isHighFrequencyCategory(category) {
-	for (const pattern of RING_BUFFER_DENY_PATTERNS) if (matchesPattern(pattern, category)) return true;
-	return false;
-}
-/**
-* Deliver `event` to all matching local subscribers and — unless it is
-* high-frequency — append it to the `recent[]` ring.
-*/
-function deliverShared(state, event) {
-	if (!isHighFrequencyCategory(event.category)) state.recent.push(event);
-	for (const [pattern, set] of state.handlers) {
-		if (!matchesPattern(pattern, event.category)) continue;
-		for (const entry of set) {
-			if (!matchesEventFilter(event, entry.filter)) continue;
-			try {
-				entry.handler(event);
-			} catch (err) {}
-		}
-	}
-}
-//#endregion
 //#region src/kernel/transport/uds-event-bus.ts
 /**
 * Create a UDS-backed `IEventBus` for use inside a forked child process.
@@ -4515,6 +4685,9 @@ function createUdsEventBus(client, addonId) {
 	client.onEvent((event) => {
 		deliverShared(state, event);
 	});
+	const reportPatterns = () => {
+		client.updateEventPatterns(addonId, [...state.handlers.keys()]);
+	};
 	return {
 		emit(event) {
 			const enriched = {
@@ -4534,8 +4707,13 @@ function createUdsEventBus(client, addonId) {
 			const set = state.handlers.get(pattern) ?? /* @__PURE__ */ new Set();
 			set.add(entry);
 			state.handlers.set(pattern, set);
+			reportPatterns();
 			return () => {
-				state.handlers.get(pattern)?.delete(entry);
+				const current = state.handlers.get(pattern);
+				if (current === void 0) return;
+				current.delete(entry);
+				if (current.size === 0) state.handlers.delete(pattern);
+				reportPatterns();
 			};
 		},
 		getRecent(filter, limit) {
@@ -5663,12 +5841,20 @@ function clusterEventTopic(category) {
 * brokers GC naturally.
 */
 var brokerBusState = /* @__PURE__ */ new WeakMap();
-function getSharedBusState(broker) {
+/**
+* @param retainRecent - `true` from the hub-main opt-in call site
+*   (`event-bus.service.ts`). If the bus was already created by a non-retaining
+*   caller (e.g. `process-service`, the `$event-bus` handler, or the per-addon
+*   wrapper) we UPGRADE it in place so the opt-in wins regardless of call
+*   order. Only the hub main process ever passes `true`; agents + child runners
+*   never do, so their bus stays one-shot.
+*/
+function getSharedBusState(broker, retainRecent = false) {
 	let state = brokerBusState.get(broker);
 	if (!state) {
-		state = createSharedBusState();
+		state = createSharedBusState(retainRecent);
 		brokerBusState.set(broker, state);
-	}
+	} else if (retainRecent && !state.retainRecent) state.retainRecent = true;
 	return state;
 }
 /** Brokers that already have the `$event-bus` service installed. */
@@ -5715,9 +5901,16 @@ function registerEventBusService(broker) {
 		} catch {}
 	}
 }
-function getBrokerEventBus(broker) {
+/**
+* @param options.retainRecent - Pass `true` ONLY from the hub main process
+*   (`EventBusService.attachBroker`), the single process that serves the
+*   `getRecent`/audit capability. Every other caller (agents, child runners,
+*   the per-addon wrapper, the `$event-bus` handler) omits it → the bus retains
+*   nothing and `getRecent` returns `[]`. Events are one-shot everywhere else.
+*/
+function getBrokerEventBus(broker, options) {
 	const bkr = broker;
-	const state = getSharedBusState(broker);
+	const state = getSharedBusState(broker, options?.retainRecent ?? false);
 	registerEventBusService(broker);
 	const warnTimestamps = (() => {
 		let m = brokerBusWarnTimestamps.get(broker);

package/package.json

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