@camstack/system 1.1.19 → 1.1.20

package/dist/addon-runner.js

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_manifest_python_deps = require("./manifest-python-deps-Dt5XNSyd.js");
+const require_manifest_python_deps = require("./manifest-python-deps-PbdHKDpj.js");
 const require_custom_action_registry = require("./custom-action-registry-vLYEFTtv.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);

package/dist/addon-runner.mjs

@@ -1,4 +1,4 @@
-import { $ as getWorkerNativeCapProvider, N as createUdsLoggerWithControl, P as LocalChildClient, _t as resolveAddonClass, et as getWorkerNativeCapSnapshot, gt as installManifestNativeDeps, i as createUdsAddonContext, it as validateProviderRegistrations, nt as setWorkerNativeCapsChangeListener, t as installManifestPythonDeps } from "./manifest-python-deps-C1Dd9MSr.mjs";
+import { $ as getWorkerNativeCapProvider, N as createUdsLoggerWithControl, P as LocalChildClient, _t as resolveAddonClass, et as getWorkerNativeCapSnapshot, gt as installManifestNativeDeps, i as createUdsAddonContext, it as validateProviderRegistrations, nt as setWorkerNativeCapsChangeListener, t as installManifestPythonDeps } from "./manifest-python-deps-X00KVYHa.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-BEXwC-oo.mjs";
 import { register } from "node:module";
 import * as fs from "node:fs";

package/dist/index.js

@@ -20,7 +20,7 @@ const require_builtins_local_auth_local_auth_addon = require("./builtins/local-a
 require("./builtins/local-auth/index.js");
 const require_builtins_device_manager_device_manager_addon = require("./builtins/device-manager/device-manager.addon.js");
 require("./builtins/device-manager/index.js");
-const require_manifest_python_deps = require("./manifest-python-deps-Dt5XNSyd.js");
+const require_manifest_python_deps = require("./manifest-python-deps-PbdHKDpj.js");
 const require_custom_action_registry = require("./custom-action-registry-vLYEFTtv.js");
 let _camstack_types_node = require("@camstack/types/node");
 let node_http = require("node:http");
@@ -92358,6 +92358,16 @@ function readAddonHeapProfile(spec) {
 	heapProfileCache.set(cacheKey, profile);
 	return profile;
 }
+/**
+* Drop the cached heap profile for each addon so the NEXT `readAddonHeapProfile`
+* re-reads the manifest from disk. Called on operator-driven spawns / restarts
+* (a deploy may have changed the addon's `execution.heapProfile`); the
+* crash-respawn fast path deliberately does NOT invalidate — a crashing runner
+* has the same on-disk manifest, so re-reading it is pure overhead.
+*/
+function invalidateHeapProfiles(addons) {
+	for (const spec of addons) heapProfileCache.delete(`${spec.addonDir}::${spec.addonId}`);
+}
 function manifestHasAddon(parsed, addonId) {
 	return readManifestAddons(parsed).some((a) => a.id === addonId);
 }
@@ -92478,12 +92488,13 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 			CAMSTACK_RUNNER_ADDONS: JSON.stringify(addons),
 			CAMSTACK_PARENT_NODE_ID: parentNodeId,
 			CAMSTACK_DATA_DIR: dataDir,
-			CAMSTACK_LOG_LEVEL: "debug",
+			CAMSTACK_LOG_LEVEL: process.env["CAMSTACK_LOG_LEVEL"] ?? "info",
 			...parentTcpPort !== void 0 ? { CAMSTACK_PARENT_TCP_PORT: String(parentTcpPort) } : {},
 			...parentUdsPath !== void 0 ? { CAMSTACK_PARENT_UDS_PATH: parentUdsPath } : {},
 			...env
 		};
 		const heapFlags = runnerHeapFlags(addons);
+		capturedBroker?.logger.info(`[${runnerId}] heap profile: ${isHeavyRunner(addons) ? "heavy" : "light"} flags=[${heapFlags.join(" ")}]`);
 		const child = spawnFn(process.execPath, [...heapFlags, runnerPath], {
 			env: childEnv,
 			stdio: [
@@ -92558,6 +92569,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 				const { runnerId, addons, env } = ctx.params;
 				if (processes.has(runnerId)) throw new Error(`Runner "${runnerId}" already running`);
 				if (!Array.isArray(addons) || addons.length === 0) throw new Error(`spawnRunner requires non-empty addons array`);
+				invalidateHeapProfiles(addons);
 				const entry = spawnRunner(runnerId, addons, env);
 				return {
 					pid: entry.pid,
@@ -92632,6 +92644,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 					processes.delete(name);
 					crashSupervisor.reset(name);
 					forceMoleculerDisconnect(ctx.broker, deadNodeId);
+					invalidateHeapProfiles(runnerAddons);
 					const restarted = spawnRunner(name, runnerAddons);
 					restarted.restartCount = prevRestartCount + 1;
 					return {
@@ -92689,6 +92702,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 						}
 						processes.delete(name);
 						crashSupervisor.reset(name);
+						invalidateHeapProfiles(runnerAddons);
 						const respawned = spawnRunner(name, runnerAddons);
 						respawned.restartCount = prevRestartCount + 1;
 					});

package/dist/index.mjs

@@ -18,7 +18,7 @@ import { LocalAuthAddon, a as require_ms, c as __esmMin, d as __toCommonJS, f as
 import "./builtins/local-auth/index.mjs";
 import { DeviceManagerAddon } from "./builtins/device-manager/device-manager.addon.mjs";
 import "./builtins/device-manager/index.mjs";
-import { A as createUdsEventBus, B as CapRouteError, C as ipcParentLink, D as createHubCapForwardService, E as HUB_CAP_FWD_SERVICE, F as LocalChildRegistry, G as UdsLocalTransportServer, H as callWithServiceDiscovery, I as UDS_NO_ROUTE_PREFIX, J as FrameDecoder, K as SocketChannel, L as AGENT_CAP_FWD_ACTION, M as createUdsLogger, N as createUdsLoggerWithControl, O as createParentUnownedCallHandler, P as LocalChildClient, Q as createBrokerDeviceManagerApi, R as AGENT_CAP_FWD_SERVICE, S as ipcChildLink, T as HUB_CAP_FWD_ACTION, U as createLocalTransport, V as classifyCapRoute, W as UdsLocalTransportClient, X as buildNativeCapProxy, Y as encodeFrame, Z as buildUdsNativeCapProxy, _ as __resetCapUsageRegistryForTests, _t as resolveAddonClass, a as getWorkerDeviceRegistry, at as NATIVE_PROVIDER_SERVICE_INFIX, b as brokerTransportLink, c as setHubConnected, ct as capBareAction, d as registerEventBusService, dt as deserializeTypedArrays, f as AddonDepsManager, ft as serializeTypedArrays, g as CapUsageRegistry, gt as installManifestNativeDeps, h as createHwAccelService, ht as CapabilityUnavailableError, i as createUdsAddonContext, it as validateProviderRegistrations, j as udsChildLogToWorkerEntry, k as createUdsEventBridge, l as EVENT_TOPIC_PREFIX, lt as capServiceName, m as resolveHwAccel, mt as CapabilityHandle, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as capActionName, p as createKernelHwAccel, pt as DeviceRegistry, q as localEndpointPath, r as createAddonContext, rt as createAddonService, s as getOrInitReadinessRegistryForClient, st as capActionSuffix, t as installManifestPythonDeps, tt as mountNativeCapService, u as getBrokerEventBus, ut as parseCapAction, v as getCapUsageRegistry, w as localProviderLink, x as buildLinkChain, y as brokerCallForCap, z as CapRouteResolver } from "./manifest-python-deps-C1Dd9MSr.mjs";
+import { A as createUdsEventBus, B as CapRouteError, C as ipcParentLink, D as createHubCapForwardService, E as HUB_CAP_FWD_SERVICE, F as LocalChildRegistry, G as UdsLocalTransportServer, H as callWithServiceDiscovery, I as UDS_NO_ROUTE_PREFIX, J as FrameDecoder, K as SocketChannel, L as AGENT_CAP_FWD_ACTION, M as createUdsLogger, N as createUdsLoggerWithControl, O as createParentUnownedCallHandler, P as LocalChildClient, Q as createBrokerDeviceManagerApi, R as AGENT_CAP_FWD_SERVICE, S as ipcChildLink, T as HUB_CAP_FWD_ACTION, U as createLocalTransport, V as classifyCapRoute, W as UdsLocalTransportClient, X as buildNativeCapProxy, Y as encodeFrame, Z as buildUdsNativeCapProxy, _ as __resetCapUsageRegistryForTests, _t as resolveAddonClass, a as getWorkerDeviceRegistry, at as NATIVE_PROVIDER_SERVICE_INFIX, b as brokerTransportLink, c as setHubConnected, ct as capBareAction, d as registerEventBusService, dt as deserializeTypedArrays, f as AddonDepsManager, ft as serializeTypedArrays, g as CapUsageRegistry, gt as installManifestNativeDeps, h as createHwAccelService, ht as CapabilityUnavailableError, i as createUdsAddonContext, it as validateProviderRegistrations, j as udsChildLogToWorkerEntry, k as createUdsEventBridge, l as EVENT_TOPIC_PREFIX, lt as capServiceName, m as resolveHwAccel, mt as CapabilityHandle, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as capActionName, p as createKernelHwAccel, pt as DeviceRegistry, q as localEndpointPath, r as createAddonContext, rt as createAddonService, s as getOrInitReadinessRegistryForClient, st as capActionSuffix, t as installManifestPythonDeps, tt as mountNativeCapService, u as getBrokerEventBus, ut as parseCapAction, v as getCapUsageRegistry, w as localProviderLink, x as buildLinkChain, y as brokerCallForCap, z as CapRouteResolver } from "./manifest-python-deps-X00KVYHa.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-BEXwC-oo.mjs";
 import { PYTHON_VERSION, buildBinaryPath, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
 import { request } from "node:http";
@@ -92350,6 +92350,16 @@ function readAddonHeapProfile(spec) {
 	heapProfileCache.set(cacheKey, profile);
 	return profile;
 }
+/**
+* Drop the cached heap profile for each addon so the NEXT `readAddonHeapProfile`
+* re-reads the manifest from disk. Called on operator-driven spawns / restarts
+* (a deploy may have changed the addon's `execution.heapProfile`); the
+* crash-respawn fast path deliberately does NOT invalidate — a crashing runner
+* has the same on-disk manifest, so re-reading it is pure overhead.
+*/
+function invalidateHeapProfiles(addons) {
+	for (const spec of addons) heapProfileCache.delete(`${spec.addonDir}::${spec.addonId}`);
+}
 function manifestHasAddon(parsed, addonId) {
 	return readManifestAddons(parsed).some((a) => a.id === addonId);
 }
@@ -92470,12 +92480,13 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 			CAMSTACK_RUNNER_ADDONS: JSON.stringify(addons),
 			CAMSTACK_PARENT_NODE_ID: parentNodeId,
 			CAMSTACK_DATA_DIR: dataDir,
-			CAMSTACK_LOG_LEVEL: "debug",
+			CAMSTACK_LOG_LEVEL: process.env["CAMSTACK_LOG_LEVEL"] ?? "info",
 			...parentTcpPort !== void 0 ? { CAMSTACK_PARENT_TCP_PORT: String(parentTcpPort) } : {},
 			...parentUdsPath !== void 0 ? { CAMSTACK_PARENT_UDS_PATH: parentUdsPath } : {},
 			...env
 		};
 		const heapFlags = runnerHeapFlags(addons);
+		capturedBroker?.logger.info(`[${runnerId}] heap profile: ${isHeavyRunner(addons) ? "heavy" : "light"} flags=[${heapFlags.join(" ")}]`);
 		const child = spawnFn(process.execPath, [...heapFlags, runnerPath], {
 			env: childEnv,
 			stdio: [
@@ -92550,6 +92561,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 				const { runnerId, addons, env } = ctx.params;
 				if (processes.has(runnerId)) throw new Error(`Runner "${runnerId}" already running`);
 				if (!Array.isArray(addons) || addons.length === 0) throw new Error(`spawnRunner requires non-empty addons array`);
+				invalidateHeapProfiles(addons);
 				const entry = spawnRunner(runnerId, addons, env);
 				return {
 					pid: entry.pid,
@@ -92624,6 +92636,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 					processes.delete(name);
 					crashSupervisor.reset(name);
 					forceMoleculerDisconnect(ctx.broker, deadNodeId);
+					invalidateHeapProfiles(runnerAddons);
 					const restarted = spawnRunner(name, runnerAddons);
 					restarted.restartCount = prevRestartCount + 1;
 					return {
@@ -92681,6 +92694,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 						}
 						processes.delete(name);
 						crashSupervisor.reset(name);
+						invalidateHeapProfiles(runnerAddons);
 						const respawned = spawnRunner(name, runnerAddons);
 						respawned.restartCount = prevRestartCount + 1;
 					});

package/dist/kernel/moleculer/event-bus-core.d.ts

@@ -1,4 +1,4 @@
-import { SystemEvent, EventFilter } from '@camstack/types';
+import { EventFilter, SystemEvent } from '@camstack/types';
 export interface SubscriberEntry {
     /** Original filter — kept whole so non-category dimensions are honoured per-event. */
     readonly filter: EventFilter | string | undefined;
@@ -18,11 +18,34 @@ export interface SharedBusState {
      * high-frequency categories so the buffer only accumulates audit-grade
      * lifecycle events.
      *
+     * ONLY populated when `retainRecent` is true (the hub main process). On every
+     * other bus this array stays empty for the process's whole lifetime.
+     *
      * Cleared on server restart (intentional — events are volatile by design).
      */
     readonly recent: SystemEvent[];
+    /**
+     * Whether this bus retains events in `recent[]` to back the
+     * `getRecent`/audit capability.
+     *
+     * Events are one-shot (fire-and-forget): ONLY the hub main process — the
+     * single process that serves `getRecent` — needs the registry, so ONLY its
+     * broker bus sets this true. Child addon runners and remote agents leave it
+     * false: they fan every event out to their local subscribers but retain
+     * nothing, so their heap can never accumulate an unbounded recent[] backlog.
+     *
+     * Mutable so the authoritative opt-in (the hub-main `getBrokerEventBus`
+     * caller) can upgrade a bus that a non-retaining caller happened to create
+     * first — see `getSharedBusState`. Never downgraded from true → false.
+     */
+    retainRecent: boolean;
 }
-export declare function createSharedBusState(): SharedBusState;
+/**
+ * @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.
+ */
+export declare function createSharedBusState(retainRecent?: boolean): SharedBusState;
 export declare function matchesPattern(pattern: string, category: string): boolean;
 export declare function extractCategoryPattern(filter: EventFilter | string): string;
 /**
@@ -45,9 +68,23 @@ export declare function matchesEventFilter(event: SystemEvent, filter: EventFilt
  * being displaced by per-frame noise.
  */
 export declare const RING_BUFFER_DENY_PATTERNS: readonly string[];
+/**
+ * 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.
+ */
+export declare const MAX_RECENT_EVENTS = 1000;
 export declare function isHighFrequencyCategory(category: string): boolean;
 /**
- * Deliver `event` to all matching local subscribers and — unless it is
- * high-frequency — append it to the `recent[]` ring.
+ * 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 `[]`.
  */
 export declare function deliverShared(state: SharedBusState, event: SystemEvent): void;

package/dist/kernel/moleculer/event-bus.d.ts

@@ -1,5 +1,5 @@
-import { ServiceBroker } from 'moleculer';
 import { IEventBus } from '@camstack/types';
+import { ServiceBroker } from 'moleculer';
 /**
  * Narrow interface for the Moleculer ServiceBroker surface used in this file.
  * moleculer's index.d.ts chains through eventemitter2 whose package.json has
@@ -49,5 +49,14 @@ export declare function clusterEventTopic(category: string): string;
  *  - forkable process / group runner, before `broker.start()`
  */
 export declare function registerEventBusService(broker: ServiceBroker): void;
-export declare function getBrokerEventBus(broker: ServiceBroker): IEventBus;
+/**
+ * @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.
+ */
+export declare function getBrokerEventBus(broker: ServiceBroker, options?: {
+    retainRecent?: boolean;
+}): IEventBus;
 export declare function createBrokerEventBus(broker: ServiceBroker, addonId: string): IEventBus;

package/dist/kernel/moleculer/process-service.d.ts

@@ -68,5 +68,5 @@ interface ProcessServiceDeps {
     readonly spawnFn?: SpawnFn;
 }
 declare function createProcessService(parentNodeId: string, dataDir: string, deps?: ProcessServiceDeps, parentTcpPort?: number, parentUdsPath?: string): ServiceSchema;
-export { createProcessService };
 export type { ProcessInfo, SpawnedProcess };
+export { createProcessService };

package/dist/kernel/transport/child-cap-protocol.d.ts

@@ -1,4 +1,4 @@
-import { SystemEvent, IReadinessRegistryRecord, LogLevel, LogTags } from '@camstack/types';
+import { IReadinessRegistryRecord, LogLevel, LogTags, SystemEvent } from '@camstack/types';
 /**
  * Routing descriptor a child sends so the parent can route cap calls to it.
  * The provider implementation never crosses the wire — only these keys do.
@@ -15,6 +15,27 @@ export interface RegisterMessage {
     readonly kind: 'register';
     readonly childId: string;
     readonly caps: readonly ChildCapDescriptor[];
+    /**
+     * Snapshot of the child's live category-pattern subscriptions (the keys of
+     * its local `SharedBusState.handlers` map). Carried IN the register frame so
+     * the parent learns the child's subscriptions race-free at boot — no separate
+     * post-connect sync can be missed. OPTIONAL: a legacy child bundling an older
+     * `@camstack/system` omits it; the parent treats an absent field as
+     * "undeclared" and fails OPEN (broadcast every event to that child). See
+     * `EventSubUpdateMessage` for post-boot updates.
+     */
+    readonly eventPatterns?: readonly string[];
+}
+/**
+ * Child → parent, fire-and-forget: the child's category-pattern subscription
+ * set changed after registration. FULL-SET REPLACE semantics — `patterns` is
+ * the complete current set, not a delta. Idempotent and order-safe on the
+ * in-order UDS socket (last write wins is correct). Sent via `channel.emit`
+ * like {@link ChildEventMessage}; carries no response.
+ */
+export interface EventSubUpdateMessage {
+    readonly kind: 'event-sub';
+    readonly patterns: readonly string[];
 }
 /** Child → parent outbound cap invocation — the child asks the parent to route a cap call it does not own. */
 export interface CapCallOutMessage {
@@ -56,10 +77,10 @@ export interface ReadinessSnapshotRequest {
  * Child → parent message bodies.
  * `RegisterMessage`, `CapCallOutMessage`, and `ReadinessSnapshotRequest` travel
  * as correlated request frames (`channel.request`) and carry a response.
- * `ChildEventMessage` and `ChildLogMessage` are sent fire-and-forget via
- * `channel.emit()` and do NOT carry a response.
+ * `ChildEventMessage`, `ChildLogMessage`, and `EventSubUpdateMessage` are sent
+ * fire-and-forget via `channel.emit()` and do NOT carry a response.
  */
-export type ChildToParentRequest = RegisterMessage | CapCallOutMessage | ChildEventMessage | ChildLogMessage | ReadinessSnapshotRequest;
+export type ChildToParentRequest = RegisterMessage | CapCallOutMessage | ChildEventMessage | ChildLogMessage | EventSubUpdateMessage | ReadinessSnapshotRequest;
 /** Parent → child cap invocation. */
 export interface CapCallMessage {
     readonly kind: 'cap-call';

package/dist/kernel/transport/local-child-client.d.ts

@@ -1,5 +1,5 @@
-import { ChildCapDescriptor, CapCallInput, ChildLogMessage, AddonCallInput } from './child-cap-protocol.js';
-import { SystemEvent, IReadinessRegistryRecord } from '@camstack/types';
+import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
+import { AddonCallInput, CapCallInput, ChildCapDescriptor, ChildLogMessage } from './child-cap-protocol.js';
 export interface LocalChildClientOptions {
     /** Parent node id — selects the UDS endpoint this child connects to. */
     readonly nodeId: string;
@@ -38,6 +38,24 @@ export declare class LocalChildClient {
      * the latest set) instead of being lost or throwing.
      */
     private 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).
+     */
+    private readonly patternsByOwner;
+    private 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.
+     */
+    private hasDeclaredEventPatterns;
     /** Events and logs queued while the channel is not yet open. */
     private readonly pendingEmits;
     /** Handler for parent→child events. Registered via `onEvent`. */
@@ -60,6 +78,20 @@ export declare class LocalChildClient {
     /** Callbacks registered via `onConnected`. Fired on every (re)connect. */
     private readonly connectedHandlers;
     constructor(options: LocalChildClientOptions);
+    /**
+     * 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: string, patterns: readonly string[]): void;
+    /** Sorted, de-duplicated union across all owners' pattern sets. */
+    private computePatternUnion;
+    /** Order-insensitive equality — both inputs are already sorted unions here. */
+    private patternsEqual;
     /**
      * Register a callback that fires each time the client successfully connects
      * (or reconnects) to its parent. Multiple handlers may be registered; all

package/dist/kernel/transport/local-child-registry.d.ts

@@ -1,6 +1,22 @@
+import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
+import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
 import { LocalTransportServer } from './local-transport.js';
-import { ChildLogMessage, CapCallInput, AddonCallInput, RegisteredChild } from './child-cap-protocol.js';
-import { SystemEvent, IReadinessRegistryRecord } from '@camstack/types';
+/**
+ * Fan-out mode for parent→child event delivery, from the
+ * `CAMSTACK_UDS_EVENT_FANOUT` env (read once at registry construction):
+ *   - `filter`    (default) — apply the subscription gate; a child receives a
+ *     category only if one of its declared patterns matches.
+ *   - `shadow`    — compute the gate decision + count would-suppresses, but
+ *     STILL send every event (burn-in: prove zero would-be-starved deliveries).
+ *   - `broadcast` — ignore the gate entirely (today's behaviour); the operator's
+ *     one-env rollback without redeploying runners.
+ */
+export type UdsEventFanoutMode = 'filter' | 'shadow' | 'broadcast';
+/** Per-child event fan-out counters (sent = delivered, suppressed = gated/would-gate). */
+export interface ChildEventStats {
+    sent: number;
+    suppressed: number;
+}
 /**
  * Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
  * local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
@@ -69,6 +85,12 @@ export declare class LocalChildRegistry {
     private readonly resolveChildIdForAddon?;
     /** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
     private readonly egressRoutedCaps;
+    /** Active event fan-out mode, read once from `CAMSTACK_UDS_EVENT_FANOUT`. */
+    private readonly fanoutMode;
+    /** Per-child event fan-out counters (sent / suppressed). */
+    private readonly childEventStats;
+    /** Last pattern-set string logged per child, to dedup the INFO line. */
+    private readonly loggedPatternSet;
     /**
      * Accepts either a plain positional `server` argument (backward-compatible)
      * or a full `LocalChildRegistryOptions` object.
@@ -82,6 +104,28 @@ export declare class LocalChildRegistry {
      */
     constructor(serverOrOptions: LocalTransportServer | LocalChildRegistryOptions, onUnownedCallArg?: (input: CapCallInput) => Promise<unknown>);
     start(): Promise<void>;
+    /**
+     * 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: string): ChildEventStats | null;
+    /**
+     * 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.
+     */
+    private childWantsEvent;
+    private statsFor;
+    /** Deduped INFO line whenever a child's declared pattern set changes. */
+    private logPatternSet;
     /**
      * Child id that can service a call to `capName` (optionally addressing
      * `deviceId`), or null.

package/dist/kernel/transport/uds-event-bridge.d.ts

@@ -2,6 +2,16 @@ import { IEventBus, SystemEvent } from '@camstack/types';
 /**
  * Minimal surface the bridge requires from `LocalChildRegistry`.
  * Structurally typed so tests can provide a fake without any casts.
+ *
+ * CONTRACT: `broadcastEventToChildren` is SUBSCRIPTION-FILTERED. The registry
+ * fans an event only to children whose declared category-pattern set matches
+ * `event.category` (mirror of each child's local `SharedBusState.handlers`
+ * keys). A child that never declared a set (legacy/undeclared) fails OPEN and
+ * receives everything. The `CAMSTACK_UDS_EVENT_FANOUT` env (`filter` default /
+ * `shadow` / `broadcast`) is the registry-side kill-switch. The bridge itself
+ * needs no per-event logic change — both fan-out call sites here go through the
+ * filtered `broadcastEventToChildren`. `sendEventToChild` (targeted push) is
+ * NOT filtered — an explicit single-child send expresses intent.
  */
 export interface ChildEventBroadcaster {
     /**

package/dist/kernel/transport/uds-event-bus.d.ts

@@ -6,10 +6,16 @@ import { IEventBus, SystemEvent } from '@camstack/types';
  * - `emitEvent` — fire-and-forget: send a system event to the parent.
  * - `onEvent`   — register the single handler for parent→child events.
  *   (Only one handler is registered; calling again replaces the previous one.)
+ * - `updateEventPatterns` — declare this owner's live category-pattern set to
+ *   the parent so it can subscription-filter the event fan-out. Called after
+ *   every subscribe/unsubscribe with the CURRENT key set (full-set replace).
+ *   Keyed by `ownerId` (the addonId) so multiple buses sharing one client
+ *   union correctly.
  */
 export interface UdsEventChannel {
     emitEvent(event: SystemEvent): void;
     onEvent(handler: (event: SystemEvent) => void): void;
+    updateEventPatterns(ownerId: string, patterns: readonly string[]): void;
 }
 /**
  * Create a UDS-backed `IEventBus` for use inside a forked child process.