@camstack/system 1.1.18 → 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-lZd5B4FS.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-DOAh19rY.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.d.ts

@@ -72,6 +72,7 @@ export type { UserRecord, UserStorageAccess, UserConfigReader } from './auth/use
 export { ScopedTokenManager } from './auth/scoped-token-manager.js';
 export { scopesAllowDeviceCap } from './auth/scope-matcher.js';
 export { NotificationService } from './notification/notification-service.js';
+export type { NotificationTargetRef } from './notification/notification-service.js';
 export { ToastService } from './notification/toast-service.js';
 export type { Unsubscribe } from './notification/toast-service.js';
 export { AddonRouteRegistry } from './addon-routes/addon-route-registry.js';

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-lZd5B4FS.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");
@@ -1493,16 +1493,17 @@ function scopesAllowDeviceCap(scopes, access) {
 //#endregion
 //#region src/notification/notification-service.ts
 /**
-* Central notification service that routes notifications to configured outputs.
-* Framework-agnostic — dependencies injected via constructor.
+* Central notification service that routes canonical notifications to
+* configured `(addonId, targetId)` targets. Framework-agnostic —
+* dependencies injected via constructor.
 *
-* Outputs are resolved from the ICapabilityRegistry's 'notification-output'
-* collection on each call (proxy pattern). Falls back to a local map
-* when no registry is provided (backward compat).
+* Providers are resolved from the ICapabilityRegistry by `addonId` on each
+* call (proxy pattern). Falls back to a local map when no registry is
+* provided (tests / backward compat).
 */
 var NotificationService = class {
 	logger;
-	localOutputs = /* @__PURE__ */ new Map();
+	localProviders = /* @__PURE__ */ new Map();
 	routing = /* @__PURE__ */ new Map();
 	rateLimits = /* @__PURE__ */ new Map();
 	lastSent = /* @__PURE__ */ new Map();
@@ -1510,35 +1511,28 @@ var NotificationService = class {
 	constructor(logger) {
 		this.logger = logger;
 	}
-	/** Set the registry for live output lookup. Called once during boot. */
+	/** Set the registry for live provider lookup. Called once during boot. */
 	setRegistry(registry) {
 		this.registry = registry;
 	}
-	/** Resolve all outputs — prefers registry, falls back to local map */
-	get outputs() {
-		if (this.registry) {
-			const collection = this.registry.getCollection("notification-output");
-			const map = /* @__PURE__ */ new Map();
-			for (const output of collection) map.set(output.id, output);
-			return map;
-		}
-		return this.localOutputs;
-	}
-	/** Register an output in the local fallback map (used when no registry is set). */
-	registerLocalOutput(output) {
-		this.localOutputs.set(output.id, output);
-		this.logger.info("Notification output added", { meta: {
-			name: output.name,
-			outputId: output.id
-		} });
+	/** Resolve the collection provider for an addon — registry first, then local map. */
+	resolveProvider(addonId) {
+		if (this.registry) return this.registry.getProviderByAddon("notification-output", addonId) ?? void 0;
+		return this.localProviders.get(addonId);
+	}
+	/** Register a provider in the local fallback map (used when no registry is set). */
+	registerLocalProvider(addonId, provider) {
+		this.localProviders.set(addonId, provider);
+		this.logger.info("Notification provider added", { meta: { addonId } });
 	}
-	/** Remove an output from the local fallback map. */
-	unregisterLocalOutput(id) {
-		this.localOutputs.delete(id);
-		this.logger.info("Notification output removed", { meta: { outputId: id } });
+	/** Remove a provider from the local fallback map. */
+	unregisterLocalProvider(addonId) {
+		this.localProviders.delete(addonId);
+		this.logger.info("Notification provider removed", { meta: { addonId } });
 	}
-	setRouting(category, outputIds) {
-		this.routing.set(category, [...outputIds]);
+	/** Route a category to a set of `(addonId, targetId)` targets. */
+	setRouting(category, targets) {
+		this.routing.set(category, [...targets]);
 	}
 	setRateLimit(category, minIntervalMs) {
 		this.rateLimits.set(category, minIntervalMs);
@@ -1554,38 +1548,36 @@ var NotificationService = class {
 				return;
 			}
 		}
-		const targetIds = this.routing.get(category) ?? this.routing.get("*") ?? [];
-		if (targetIds.length === 0) {
+		const targets = this.routing.get(category) ?? this.routing.get("*") ?? [];
+		if (targets.length === 0) {
 			this.logger.debug("No routing configured for category", { meta: { category } });
 			return;
 		}
-		const currentOutputs = this.outputs;
 		this.lastSent.set(rateLimitKey, notification.timestamp);
-		await Promise.allSettled(targetIds.map((id) => currentOutputs.get(id)).filter((output) => output !== void 0).map(async (output) => {
+		const { category: _category, timestamp: _timestamp, ...canonical } = notification;
+		await Promise.allSettled(targets.map(async (ref) => {
+			const provider = this.resolveProvider(ref.addonId);
+			if (!provider) {
+				this.logger.debug("No provider for target", { meta: { addonId: ref.addonId } });
+				return;
+			}
 			try {
-				await output.send(notification);
+				await provider.send({
+					targetId: ref.targetId,
+					notification: canonical
+				});
 			} catch (err) {
-				const msg = (0, _camstack_types.errMsg)(err);
-				this.logger.error("Notification output failed", { meta: {
-					outputId: output.id,
-					error: msg
+				this.logger.error("Notification target failed", { meta: {
+					addonId: ref.addonId,
+					targetId: ref.targetId,
+					error: (0, _camstack_types.errMsg)(err)
 				} });
 			}
 		}));
 	}
-	getOutputs() {
-		return Array.from(this.outputs.values()).map(({ id, name, icon }) => ({
-			id,
-			name,
-			icon
-		}));
-	}
 	getRouting() {
 		return this.routing;
 	}
-	getOutput(id) {
-		return this.outputs.get(id);
-	}
 };
 //#endregion
 //#region src/notification/toast-service.ts
@@ -92366,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);
 }
@@ -92486,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: [
@@ -92566,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,
@@ -92640,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 {
@@ -92697,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-DOAh19rY.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";
@@ -1485,16 +1485,17 @@ function scopesAllowDeviceCap(scopes, access) {
 //#endregion
 //#region src/notification/notification-service.ts
 /**
-* Central notification service that routes notifications to configured outputs.
-* Framework-agnostic — dependencies injected via constructor.
+* Central notification service that routes canonical notifications to
+* configured `(addonId, targetId)` targets. Framework-agnostic —
+* dependencies injected via constructor.
 *
-* Outputs are resolved from the ICapabilityRegistry's 'notification-output'
-* collection on each call (proxy pattern). Falls back to a local map
-* when no registry is provided (backward compat).
+* Providers are resolved from the ICapabilityRegistry by `addonId` on each
+* call (proxy pattern). Falls back to a local map when no registry is
+* provided (tests / backward compat).
 */
 var NotificationService = class {
 	logger;
-	localOutputs = /* @__PURE__ */ new Map();
+	localProviders = /* @__PURE__ */ new Map();
 	routing = /* @__PURE__ */ new Map();
 	rateLimits = /* @__PURE__ */ new Map();
 	lastSent = /* @__PURE__ */ new Map();
@@ -1502,35 +1503,28 @@ var NotificationService = class {
 	constructor(logger) {
 		this.logger = logger;
 	}
-	/** Set the registry for live output lookup. Called once during boot. */
+	/** Set the registry for live provider lookup. Called once during boot. */
 	setRegistry(registry) {
 		this.registry = registry;
 	}
-	/** Resolve all outputs — prefers registry, falls back to local map */
-	get outputs() {
-		if (this.registry) {
-			const collection = this.registry.getCollection("notification-output");
-			const map = /* @__PURE__ */ new Map();
-			for (const output of collection) map.set(output.id, output);
-			return map;
-		}
-		return this.localOutputs;
-	}
-	/** Register an output in the local fallback map (used when no registry is set). */
-	registerLocalOutput(output) {
-		this.localOutputs.set(output.id, output);
-		this.logger.info("Notification output added", { meta: {
-			name: output.name,
-			outputId: output.id
-		} });
+	/** Resolve the collection provider for an addon — registry first, then local map. */
+	resolveProvider(addonId) {
+		if (this.registry) return this.registry.getProviderByAddon("notification-output", addonId) ?? void 0;
+		return this.localProviders.get(addonId);
+	}
+	/** Register a provider in the local fallback map (used when no registry is set). */
+	registerLocalProvider(addonId, provider) {
+		this.localProviders.set(addonId, provider);
+		this.logger.info("Notification provider added", { meta: { addonId } });
 	}
-	/** Remove an output from the local fallback map. */
-	unregisterLocalOutput(id) {
-		this.localOutputs.delete(id);
-		this.logger.info("Notification output removed", { meta: { outputId: id } });
+	/** Remove a provider from the local fallback map. */
+	unregisterLocalProvider(addonId) {
+		this.localProviders.delete(addonId);
+		this.logger.info("Notification provider removed", { meta: { addonId } });
 	}
-	setRouting(category, outputIds) {
-		this.routing.set(category, [...outputIds]);
+	/** Route a category to a set of `(addonId, targetId)` targets. */
+	setRouting(category, targets) {
+		this.routing.set(category, [...targets]);
 	}
 	setRateLimit(category, minIntervalMs) {
 		this.rateLimits.set(category, minIntervalMs);
@@ -1546,38 +1540,36 @@ var NotificationService = class {
 				return;
 			}
 		}
-		const targetIds = this.routing.get(category) ?? this.routing.get("*") ?? [];
-		if (targetIds.length === 0) {
+		const targets = this.routing.get(category) ?? this.routing.get("*") ?? [];
+		if (targets.length === 0) {
 			this.logger.debug("No routing configured for category", { meta: { category } });
 			return;
 		}
-		const currentOutputs = this.outputs;
 		this.lastSent.set(rateLimitKey, notification.timestamp);
-		await Promise.allSettled(targetIds.map((id) => currentOutputs.get(id)).filter((output) => output !== void 0).map(async (output) => {
+		const { category: _category, timestamp: _timestamp, ...canonical } = notification;
+		await Promise.allSettled(targets.map(async (ref) => {
+			const provider = this.resolveProvider(ref.addonId);
+			if (!provider) {
+				this.logger.debug("No provider for target", { meta: { addonId: ref.addonId } });
+				return;
+			}
 			try {
-				await output.send(notification);
+				await provider.send({
+					targetId: ref.targetId,
+					notification: canonical
+				});
 			} catch (err) {
-				const msg = errMsg(err);
-				this.logger.error("Notification output failed", { meta: {
-					outputId: output.id,
-					error: msg
+				this.logger.error("Notification target failed", { meta: {
+					addonId: ref.addonId,
+					targetId: ref.targetId,
+					error: errMsg(err)
 				} });
 			}
 		}));
 	}
-	getOutputs() {
-		return Array.from(this.outputs.values()).map(({ id, name, icon }) => ({
-			id,
-			name,
-			icon
-		}));
-	}
 	getRouting() {
 		return this.routing;
 	}
-	getOutput(id) {
-		return this.outputs.get(id);
-	}
 };
 //#endregion
 //#region src/notification/toast-service.ts
@@ -92358,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);
 }
@@ -92478,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: [
@@ -92558,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,
@@ -92632,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 {
@@ -92689,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