@camstack/system 1.1.19 → 1.1.21

package/dist/{manifest-python-deps-Dt5XNSyd.js → manifest-python-deps-Di_9ayDE.js}

@@ -3360,6 +3360,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"]);
@@ -3754,6 +3904,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
@@ -3781,6 +3936,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.
@@ -3806,10 +3967,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.
 	*
@@ -3988,14 +4231,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);
+			}
 		}
 	}
 	/**
@@ -4031,17 +4280,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
@@ -4074,7 +4337,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);
+			}
 		});
 	}
 };
@@ -4106,6 +4373,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`. */
@@ -4132,6 +4417,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
@@ -4210,7 +4531,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);
@@ -4243,7 +4565,8 @@ var LocalChildClient = class {
 		const register = {
 			kind: "register",
 			childId: this.options.childId,
-			caps
+			caps,
+			...this.hasDeclaredEventPatterns ? { eventPatterns: this.latestEventPatterns } : {}
 		};
 		await this.channel.request(register);
 	}
@@ -4404,105 +4727,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.
@@ -4517,6 +4741,9 @@ function createUdsEventBus(client, addonId) {
 	client.onEvent((event) => {
 		deliverShared(state, event);
 	});
+	const reportPatterns = () => {
+		client.updateEventPatterns(addonId, [...state.handlers.keys()]);
+	};
 	return {
 		emit(event) {
 			const enriched = {
@@ -4536,8 +4763,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) {
@@ -4571,7 +4803,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
@@ -4590,10 +4822,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);
@@ -5665,18 +5898,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;
@@ -5700,6 +6098,7 @@ function registerEventBusService(broker) {
 	if (eventBusServiceInstalled.has(broker)) return;
 	eventBusServiceInstalled.add(broker);
 	const bkr = broker;
+	const fanoutMode = readMoleculerFanoutMode();
 	try {
 		bkr.createService({
 			name: "$event-bus",
@@ -5707,6 +6106,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);
 			} }
 		});
@@ -5717,9 +6117,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);
@@ -5760,8 +6167,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) {
@@ -6961,6 +7369,12 @@ Object.defineProperty(exports, "getCapUsageRegistry", {
 		return getCapUsageRegistry;
 	}
 });
+Object.defineProperty(exports, "getMoleculerEventStats", {
+	enumerable: true,
+	get: function() {
+		return getMoleculerEventStats;
+	}
+});
 Object.defineProperty(exports, "getOrInitReadinessRegistry", {
 	enumerable: true,
 	get: function() {
@@ -7069,12 +7483,24 @@ Object.defineProperty(exports, "setHubConnected", {
 		return setHubConnected;
 	}
 });
+Object.defineProperty(exports, "setNodeEventInterest", {
+	enumerable: true,
+	get: function() {
+		return setNodeEventInterest;
+	}
+});
 Object.defineProperty(exports, "setWorkerNativeCapsChangeListener", {
 	enumerable: true,
 	get: function() {
 		return setWorkerNativeCapsChangeListener;
 	}
 });
+Object.defineProperty(exports, "subscribePassthrough", {
+	enumerable: true,
+	get: function() {
+		return subscribePassthrough;
+	}
+});
 Object.defineProperty(exports, "udsChildLogToWorkerEntry", {
 	enumerable: true,
 	get: function() {