@camstack/system 1.1.19 → 1.1.21

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

@@ -3358,6 +3358,156 @@ 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;
+}
+function readMoleculerFanoutMode() {
+	const raw = process.env.CAMSTACK_MOLECULER_EVENT_FANOUT;
+	if (raw === "shadow" || raw === "broadcast") return raw;
+	return "filter";
+}
+/**
+* Does this node want to accept an inbound cross-node event in `category`?
+* The receiving-side mirror of `LocalChildRegistry.childWantsEvent`:
+*   - `broadcast` mode → always (gate disabled).
+*   - a retaining bus (hub main) → always (it serves `getRecent` + admin-ui;
+*     its interest is genuinely everything).
+*   - undeclared interest (`null`) → always (fail-open).
+*   - else the declared union must match via `matchesPattern` — the SAME
+*     function the local subscriber map-key gate uses, giving delivery parity.
+* `shadow` is handled by the caller (it counts the would-suppress but still
+* delivers), exactly like the UDS fan-out.
+*/
+function crossNodeAcceptsCategory(mode, snapshot, category) {
+	if (mode === "broadcast") return true;
+	if (snapshot.retainRecent) return true;
+	if (snapshot.interest === null) return true;
+	return snapshot.interest.some((p) => matchesPattern(p, category));
+}
+/**
+* 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 +3902,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 +3934,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 +3965,92 @@ 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));
+	}
+	/**
+	* D2: this node's aggregate cross-node event interest — the UNION of every
+	* connected child's declared category patterns. Consumed by the parent's
+	* `$event-bus` inbound gate (via `setNodeEventInterest`) so the node only
+	* accepts cross-node (Moleculer) categories at least one local child wants.
+	*
+	* Returns `null` (fail-open — accept everything) when:
+	*   - NO child is currently connected (boot window before the first forked
+	*     child completes its UDS handshake, or every child has disconnected): a
+	*     node MUST NOT drop 100% of inbound cross-node events during that window,
+	*     and a child may connect imminently. This is distinct from the
+	*     declared-empty case below.
+	*   - ANY connected child is UNDECLARED (`eventPatterns === null`, a legacy
+	*     runner): a node cannot safely narrow its inbound set while a child's
+	*     real interest is unknown. Mirrors the per-child fail-open in
+	*     {@link childWantsEvent}, aggregated conservatively.
+	*
+	* Returns an EMPTY array only when ≥1 child is connected and EVERY connected
+	* child declared an explicit empty set — a genuine "wants nothing". Reads the
+	* live `children` map, so a child registering / disconnecting / sending
+	* `event-sub` is reflected on the next call with no extra bookkeeping.
+	*/
+	aggregateEventInterest() {
+		if (this.children.size === 0) return null;
+		const union = /* @__PURE__ */ new Set();
+		for (const entry of this.children.values()) {
+			if (entry.eventPatterns === null) return null;
+			for (const p of entry.eventPatterns) union.add(p);
+		}
+		return [...union];
+	}
+	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 +4229,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 +4278,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 +4335,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 +4371,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 +4415,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 +4529,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 +4563,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 +4725,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 +4739,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 +4761,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) {
@@ -4569,7 +4801,7 @@ var MAX_RECENT = 512;
 *          and clears the child-event handler. Call it on process shutdown.
 */
 function createUdsEventBridge(deps) {
-	const { registry, parentBus, parentNodeId } = deps;
+	const { registry, parentBus, parentNodeId, subscribePassthrough } = deps;
 	/**
 	* In-memory set of event ids for events that originated from one of this
 	* bridge's UDS children and have already been fanned to siblings + the
@@ -4588,10 +4820,11 @@ function createUdsEventBridge(deps) {
 		}
 		parentBus.emit(event);
 	});
-	const unsubscribe = parentBus.subscribe({}, (event) => {
+	const relayHandler = (event) => {
 		if (recentlyFannedIds.has(event.id)) return;
 		registry.broadcastEventToChildren(event, parentNodeId, void 0);
-	});
+	};
+	const unsubscribe = subscribePassthrough !== void 0 ? subscribePassthrough(relayHandler) : parentBus.subscribe({}, relayHandler);
 	return () => {
 		unsubscribe();
 		registry.onChildEvent(null);
@@ -5663,18 +5896,183 @@ 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. */
 var eventBusServiceInstalled = /* @__PURE__ */ new WeakSet();
 var brokerBusWarnTimestamps = /* @__PURE__ */ new WeakMap();
 /**
+* Per-broker node-interest oracle. Returns the FORKED-CHILD interest (the union
+* of this node's UDS children's declared category patterns), or `null` when it
+* is undeclared/unknown (a legacy child, or no forked child has connected yet)
+* → fail-open. Absent (no entry) is also fail-open: pre-D2 behaviour is
+* preserved until a node wires its interest via {@link setNodeEventInterest}.
+*
+* IMPORTANT: this oracle covers ONLY forked/UDS children. In-process
+* ('broker'-mode) subscribers on this same broker (e.g. each addon context's
+* `device.bindings-changed` cache-invalidation sub) are tracked SEPARATELY in
+* {@link brokerLocalInterest}. The gate unions BOTH so it can never starve a
+* live local subscriber of either kind.
+*/
+var brokerNodeInterest = /* @__PURE__ */ new WeakMap();
+/**
+* Per-broker IN-PROCESS subscriber interest: category pattern → live refcount.
+* Populated by `getBrokerEventBus(...).subscribe` (every in-process /
+* 'broker'-mode subscription) and decremented by its unsubscribe. Does NOT
+* include the UDS event bridge's pass-through relay subscription — that is a
+* conduit to forked children (whose real interest the oracle already reports),
+* not a genuine local consumer, so it registers via {@link subscribePassthrough}
+* which bypasses this surface. Keeping the bridge out is what lets the gate
+* actually filter (otherwise the bridge's `*` would make every category wanted).
+*/
+var brokerLocalInterest = /* @__PURE__ */ new WeakMap();
+function bumpLocalInterest(broker, pattern) {
+	let m = brokerLocalInterest.get(broker);
+	if (m === void 0) {
+		m = /* @__PURE__ */ new Map();
+		brokerLocalInterest.set(broker, m);
+	}
+	m.set(pattern, (m.get(pattern) ?? 0) + 1);
+}
+function dropLocalInterest(broker, pattern) {
+	const m = brokerLocalInterest.get(broker);
+	if (m === void 0) return;
+	const next = (m.get(pattern) ?? 0) - 1;
+	if (next <= 0) m.delete(pattern);
+	else m.set(pattern, next);
+}
+/** Snapshot of the in-process subscriber category patterns for `broker`. */
+function localSubscriberPatterns(broker) {
+	const m = brokerLocalInterest.get(broker);
+	return m === void 0 ? [] : [...m.keys()];
+}
+/**
+* Subscribe a PASS-THROUGH relay handler to the broker's shared bus WITHOUT
+* registering it in the local-interest surface. Used exclusively by the UDS
+* event bridge for its cluster/parent-local → children fan-out subscription:
+* the bridge must receive every event the gate lets through so it can relay to
+* forked children, but it is not itself a terminal consumer, so it must not
+* count toward this node's interest (a counted `*` would defeat the filter).
+* Returns an unsubscribe function.
+*/
+function subscribePassthrough(broker, handler) {
+	const state = getSharedBusState(broker);
+	const entry = {
+		filter: {},
+		categoryPattern: "*",
+		handler
+	};
+	const set = state.handlers.get("*") ?? /* @__PURE__ */ new Set();
+	set.add(entry);
+	state.handlers.set("*", set);
+	return () => {
+		state.handlers.get("*")?.delete(entry);
+	};
+}
+/** Per-broker cross-node inbound counters (delivered / would-suppress). */
+var brokerCrossNodeStats = /* @__PURE__ */ new WeakMap();
+/**
+* Install (or clear, with `null`) the per-node interest oracle consulted by the
+* `$event-bus` inbound handler to decide whether an inbound cross-node event is
+* wanted by any local subscriber on this node. The oracle is read PER-EVENT so a
+* child (un)subscribing takes effect immediately with no re-registration.
+*
+* Only non-retaining nodes (agents) meaningfully filter — a retaining bus (hub
+* main) always accepts every category (it serves `getRecent` + the admin-ui live
+* stream). Installing the oracle on the hub too is therefore harmless and keeps
+* the wiring uniform.
+*/
+function setNodeEventInterest(broker, oracle) {
+	if (oracle === null) brokerNodeInterest.delete(broker);
+	else brokerNodeInterest.set(broker, oracle);
+}
+/**
+* Cross-node inbound counters for `broker`, or `null` if no cross-node event has
+* been processed yet. Exposed for the D2 shadow burn-in + operator debug —
+* mirror of `LocalChildRegistry.getChildEventStats`.
+*/
+function getMoleculerEventStats(broker) {
+	const s = brokerCrossNodeStats.get(broker);
+	return s === void 0 ? null : {
+		delivered: s.delivered,
+		suppressed: s.suppressed
+	};
+}
+function crossNodeStatsFor(broker) {
+	let s = brokerCrossNodeStats.get(broker);
+	if (s === void 0) {
+		s = {
+			delivered: 0,
+			suppressed: 0
+		};
+		brokerCrossNodeStats.set(broker, s);
+	}
+	return s;
+}
+/**
+* Compute this node's COMBINED cross-node interest snapshot for the gate:
+*   - `retainRecent` — from the shared bus (hub main → accept everything).
+*   - `interest` — union of (a) forked-child interest (the oracle) and (b) live
+*     in-process subscriber patterns. `null` (fail-open) when the oracle reports
+*     `null` (undeclared / no forked child yet / oracle threw) — we cannot
+*     safely narrow while a forked child's real interest is unknown, and a boot
+*     window with no children yet must not drop everything.
+*
+* The oracle invocation is wrapped in try/catch and fails OPEN on throw — it
+* sits in front of the per-handler try/catch, in the subsystem that previously
+* caused an OOM, so a throwing oracle must never break inbound delivery.
+*/
+function nodeInterestSnapshot(broker) {
+	const state = getSharedBusState(broker);
+	let childInterest;
+	try {
+		const oracle = brokerNodeInterest.get(broker);
+		childInterest = oracle ? oracle() : null;
+	} catch {
+		childInterest = null;
+	}
+	if (childInterest === null) return {
+		retainRecent: state.retainRecent,
+		interest: null
+	};
+	const local = localSubscriberPatterns(broker);
+	const interest = [...new Set([...local, ...childInterest])];
+	return {
+		retainRecent: state.retainRecent,
+		interest
+	};
+}
+/**
+* Decide + account for an inbound cross-node event on `broker`. Returns whether
+* the event should be delivered to the local bus. Honours the
+* `CAMSTACK_MOLECULER_EVENT_FANOUT` mode (`mode`): in `shadow` it still delivers
+* but records the would-suppress; in `filter` it drops unwanted categories.
+* The interest is the UNION of forked-child AND in-process subscribers — the
+* gate never starves a live local subscriber of either kind.
+*/
+function acceptInboundCrossNode(broker, mode, category) {
+	const wants = crossNodeAcceptsCategory(mode, nodeInterestSnapshot(broker), category);
+	const stats = crossNodeStatsFor(broker);
+	if (!wants) stats.suppressed++;
+	const deliver = wants || mode === "shadow";
+	if (deliver) stats.delivered++;
+	return deliver;
+}
+/**
 * Register the `$event-bus` service on a broker. MUST be called BEFORE
 * `broker.start()` — Moleculer announces a service's event
 * subscriptions to remote nodes only during the discovery handshake;
@@ -5698,6 +6096,7 @@ function registerEventBusService(broker) {
 	if (eventBusServiceInstalled.has(broker)) return;
 	eventBusServiceInstalled.add(broker);
 	const bkr = broker;
+	const fanoutMode = readMoleculerFanoutMode();
 	try {
 		bkr.createService({
 			name: "$event-bus",
@@ -5705,6 +6104,7 @@ function registerEventBusService(broker) {
 				const event = ctx.params;
 				if (!event) return;
 				if (event.sourceNodeId === bkr.nodeID) return;
+				if (!acceptInboundCrossNode(broker, fanoutMode, event.category)) return;
 				deliverShared(getSharedBusState(broker), event);
 			} }
 		});
@@ -5715,9 +6115,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);
@@ -5758,8 +6165,9 @@ function getBrokerEventBus(broker) {
 			const set = state.handlers.get(pattern) ?? /* @__PURE__ */ new Set();
 			set.add(entry);
 			state.handlers.set(pattern, set);
+			bumpLocalInterest(broker, pattern);
 			return () => {
-				state.handlers.get(pattern)?.delete(entry);
+				if (state.handlers.get(pattern)?.delete(entry) === true) dropLocalInterest(broker, pattern);
 			};
 		},
 		getRecent(filter, limit) {
@@ -6659,4 +7067,4 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 	await deps.installPythonRequirements(reqAbs);
 }
 //#endregion
-export { getWorkerNativeCapProvider as $, createUdsEventBus as A, CapRouteError as B, ipcParentLink as C, createHubCapForwardService as D, HUB_CAP_FWD_SERVICE as E, LocalChildRegistry as F, UdsLocalTransportServer as G, callWithServiceDiscovery as H, UDS_NO_ROUTE_PREFIX as I, FrameDecoder as J, SocketChannel as K, AGENT_CAP_FWD_ACTION as L, createUdsLogger as M, createUdsLoggerWithControl as N, createParentUnownedCallHandler as O, LocalChildClient as P, createBrokerDeviceManagerApi as Q, AGENT_CAP_FWD_SERVICE as R, ipcChildLink as S, HUB_CAP_FWD_ACTION as T, createLocalTransport as U, classifyCapRoute as V, UdsLocalTransportClient as W, buildNativeCapProxy as X, encodeFrame as Y, buildUdsNativeCapProxy as Z, __resetCapUsageRegistryForTests as _, resolveAddonClass as _t, getWorkerDeviceRegistry as a, NATIVE_PROVIDER_SERVICE_INFIX as at, brokerTransportLink as b, setHubConnected as c, capBareAction as ct, registerEventBusService as d, deserializeTypedArrays as dt, getWorkerNativeCapSnapshot as et, AddonDepsManager as f, serializeTypedArrays as ft, CapUsageRegistry as g, installManifestNativeDeps as gt, createHwAccelService as h, CapabilityUnavailableError as ht, createUdsAddonContext as i, validateProviderRegistrations as it, udsChildLogToWorkerEntry as j, createUdsEventBridge as k, EVENT_TOPIC_PREFIX as l, capServiceName as lt, resolveHwAccel as m, CapabilityHandle as mt, adaptBrokerToCluster as n, setWorkerNativeCapsChangeListener as nt, getOrInitReadinessRegistry as o, capActionName as ot, createKernelHwAccel as p, DeviceRegistry as pt, localEndpointPath as q, createAddonContext as r, createAddonService as rt, getOrInitReadinessRegistryForClient as s, capActionSuffix as st, installManifestPythonDeps as t, mountNativeCapService as tt, getBrokerEventBus as u, parseCapAction as ut, getCapUsageRegistry as v, localProviderLink as w, buildLinkChain as x, brokerCallForCap as y, CapRouteResolver as z };
+export { buildNativeCapProxy as $, createHubCapForwardService as A, AGENT_CAP_FWD_ACTION as B, brokerTransportLink as C, localProviderLink as D, ipcParentLink as E, createUdsLogger as F, callWithServiceDiscovery as G, CapRouteResolver as H, createUdsLoggerWithControl as I, UdsLocalTransportServer as J, createLocalTransport as K, LocalChildClient as L, createUdsEventBridge as M, createUdsEventBus as N, HUB_CAP_FWD_ACTION as O, udsChildLogToWorkerEntry as P, encodeFrame as Q, LocalChildRegistry as R, brokerCallForCap as S, ipcChildLink as T, CapRouteError as U, AGENT_CAP_FWD_SERVICE as V, classifyCapRoute as W, localEndpointPath as X, SocketChannel as Y, FrameDecoder as Z, resolveHwAccel as _, CapabilityHandle as _t, getWorkerDeviceRegistry as a, setWorkerNativeCapsChangeListener as at, __resetCapUsageRegistryForTests as b, resolveAddonClass as bt, setHubConnected as c, NATIVE_PROVIDER_SERVICE_INFIX as ct, getMoleculerEventStats as d, capBareAction as dt, buildUdsNativeCapProxy as et, registerEventBusService as f, capServiceName as ft, createKernelHwAccel as g, DeviceRegistry as gt, AddonDepsManager as h, serializeTypedArrays as ht, createUdsAddonContext as i, mountNativeCapService as it, createParentUnownedCallHandler as j, HUB_CAP_FWD_SERVICE as k, EVENT_TOPIC_PREFIX as l, capActionName as lt, subscribePassthrough as m, deserializeTypedArrays as mt, adaptBrokerToCluster as n, getWorkerNativeCapProvider as nt, getOrInitReadinessRegistry as o, createAddonService as ot, setNodeEventInterest as p, parseCapAction as pt, UdsLocalTransportClient as q, createAddonContext as r, getWorkerNativeCapSnapshot as rt, getOrInitReadinessRegistryForClient as s, validateProviderRegistrations as st, installManifestPythonDeps as t, createBrokerDeviceManagerApi as tt, getBrokerEventBus as u, capActionSuffix as ut, createHwAccelService as v, CapabilityUnavailableError as vt, buildLinkChain as w, getCapUsageRegistry as x, CapUsageRegistry as y, installManifestNativeDeps as yt, UDS_NO_ROUTE_PREFIX as z };