@camstack/system 1.2.28 → 1.2.29

package/dist/index.js

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-BxtIzexq.js");
+const require_dist = require("./dist-CPmFYLqq.js");
 const require_model_download_service = require("./model-download-service-hf0ookyy.js");
-const require_manifest_python_deps = require("./manifest-python-deps-KZ00cbfP.js");
+const require_manifest_python_deps = require("./manifest-python-deps-BqE5j0-O.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
 const require_builtins_sqlite_storage_filesystem_storage_addon = require("./builtins/sqlite-storage/filesystem-storage.addon.js");
 const require_builtins_sqlite_storage_sqlite_settings_addon = require("./builtins/sqlite-storage/sqlite-settings.addon.js");
@@ -24,6 +24,8 @@ 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_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
+let node_v8 = require("node:v8");
+node_v8 = require_chunk.__toESM(node_v8);
 let _camstack_types_node = require("@camstack/types/node");
 let zod = require("zod");
 let node_http = require("node:http");
@@ -52,6 +54,100 @@ fs = require_chunk.__toESM(fs, 1);
 let path = require("path");
 path = require_chunk.__toESM(path, 1);
 let module$1 = require("module");
+//#region src/kernel/heap-watch.ts
+/**
+* heap-watch — hub-main's own memory, on the record.
+*
+* ## Why this exists
+*
+* hub-main is launched with `--max-old-space-size=1536` (docker-entrypoint) and
+* has logged NOTHING about its own heap. When it died on 2026-08-01/02 the only
+* trace was V8's own stderr line:
+*
+*     FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+*
+* which carries no process name, no heap number and no history — the whole
+* server restarts and the evidence is gone. Four of those in ~15h, and the one
+* at 06:57:57 landed nine seconds after a viewer opened a WebRTC session, which
+* is why the app sat in a permanent "loading": the hub was dying as it
+* connected.
+*
+* `[mem]` reports already exist for forked addon runners (SIGUSR2 in
+* `addon-runner.ts`) — hub-main, the one process that actually OOMs, was the
+* one process with no telemetry at all.
+*
+* ## What it gives
+*
+* A heartbeat carrying the numbers that separate the two possible stories, and
+* a WARN as the heap approaches the ceiling — the line that will exist BEFORE
+* the next fatal instead of after it:
+*
+*  - `heapUsedMb` climbing steadily between restarts → a leak;
+*  - `heapUsedMb` flat with a sharp jump under load → a burst allocation, and
+*    the timestamp says what was being served.
+*
+* `external`/`arrayBuffers` ride along because they are NOT bounded by
+* `--max-old-space-size` and are most of the gap between a 1.5GB cap and the
+* ~2.05GB RSS observed live: a diagnosis that only looks at the JS heap
+* misreads that process by 500MB.
+*/
+/** Heartbeat period. Slow enough to be free, fast enough that the sample before
+*  a fatal is recent. */
+var HEAP_WATCH_INTERVAL_MS = 6e4;
+/** Warn above this share of the heap ceiling. Chosen so the warning precedes
+*  the fatal by more than one interval under realistic growth. */
+var HEAP_WATCH_WARN_RATIO = .8;
+var MB = (bytes) => Math.round(bytes / 1048576);
+/**
+* Build a sample from raw readings. Pure so the thresholds are testable without
+* allocating a gigabyte to reach them.
+*/
+function buildHeapSample(mem, heapLimitBytes, warnRatio = HEAP_WATCH_WARN_RATIO) {
+	const usedRatio = heapLimitBytes > 0 ? mem.heapUsed / heapLimitBytes : 0;
+	return {
+		rssMb: MB(mem.rss),
+		heapUsedMb: MB(mem.heapUsed),
+		heapTotalMb: MB(mem.heapTotal),
+		heapLimitMb: MB(heapLimitBytes),
+		externalMb: MB(mem.external),
+		arrayBuffersMb: MB(mem.arrayBuffers),
+		usedRatio: Math.round(usedRatio * 100) / 100,
+		nearLimit: usedRatio >= warnRatio
+	};
+}
+var consoleSink = {
+	info: (line) => console.log(line),
+	warn: (line) => console.warn(line)
+};
+function format$1(label, s) {
+	return `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
+}
+/**
+* Start the heartbeat. Returns a stop function.
+*
+* `unref`ed so it can never hold the process open, and every read is wrapped:
+* a diagnostic that can crash the process it watches is worse than none.
+*/
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS) {
+	const tick = () => {
+		try {
+			const sample = buildHeapSample(process.memoryUsage(), node_v8.getHeapStatistics().heap_size_limit);
+			const line = format$1(label, sample);
+			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
+			else sink.info(line);
+		} catch {}
+	};
+	const timer = setInterval(tick, intervalMs);
+	timer.unref?.();
+	tick();
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+	};
+}
+//#endregion
 //#region src/events/event-bus.ts
 var EventBus = class {
 	listeners = /* @__PURE__ */ new Map();
@@ -5948,6 +6044,10 @@ var INFRA_CAPABILITIES = [
 		name: "storage-provider",
 		required: true
 	},
+	{
+		name: "data-store-provider",
+		required: true
+	},
 	{
 		name: "storage",
 		required: true
@@ -94119,6 +94219,8 @@ exports.FsStorageBackend = FsStorageBackend;
 exports.HEALTH_MONITOR_GRACE_PERIOD_MS = HEALTH_MONITOR_GRACE_PERIOD_MS;
 exports.HEALTH_MONITOR_RETRY_INTERVALS_MS = HEALTH_MONITOR_RETRY_INTERVALS_MS;
 exports.HEALTH_MONITOR_TICK_MS = HEALTH_MONITOR_TICK_MS;
+exports.HEAP_WATCH_INTERVAL_MS = HEAP_WATCH_INTERVAL_MS;
+exports.HEAP_WATCH_WARN_RATIO = HEAP_WATCH_WARN_RATIO;
 exports.HUB_CAP_FWD_ACTION = require_manifest_python_deps.HUB_CAP_FWD_ACTION;
 exports.HUB_CAP_FWD_SERVICE = require_manifest_python_deps.HUB_CAP_FWD_SERVICE;
 exports.HubForwarderAddon = require_builtins_hub_forwarder_index.HubForwarderAddon$1;
@@ -94193,6 +94295,7 @@ Object.defineProperty(exports, "buildBinaryPath", {
 	}
 });
 exports.buildCapRouters = buildCapRouters;
+exports.buildHeapSample = buildHeapSample;
 exports.buildLinkChain = require_manifest_python_deps.buildLinkChain;
 exports.buildNativeCapProxy = require_manifest_python_deps.buildNativeCapProxy;
 exports.buildNodeManifest = buildNodeManifest;
@@ -94358,6 +94461,7 @@ exports.scopesAllowDeviceCap = scopesAllowDeviceCap;
 exports.serializeTypedArrays = require_manifest_python_deps.serializeTypedArrays;
 exports.setHubConnected = require_manifest_python_deps.setHubConnected;
 exports.setNodeEventInterest = require_manifest_python_deps.setNodeEventInterest;
+exports.startHeapWatch = startHeapWatch;
 exports.stripCamstackDeps = stripCamstackDeps;
 exports.subscribePassthrough = require_manifest_python_deps.subscribePassthrough;
 exports.udsChildLogToWorkerEntry = require_manifest_python_deps.udsChildLogToWorkerEntry;

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM$1, r as __exportAll, t as __commonJSMin$1 } from "./chunk-CNf5ZN-e.mjs";
-import { B as logLevelAtMost, Dt as readinessKey, Et as parseJsonUnknown$1, F as isVoidInput, I as kebabToCamel, L as lifecycleJobSchema, M as isArrayOutputSchema, N as isCollectionArrayMethod, Ot as resolveCapMount, P as isObjectInput, Tt as parseJsonObject, V as looseSchema, W as objectInputDeclaresAddonId, _t as asString$1, c as RUNTIME_DEFAULTS, ct as DEVICE_STATUS_METHOD, ft as ReadinessRegistry, gt as asNumber, ht as asJsonObject$1, it as errMsg$1, jt as EventCategory$1, k as extractNestedAddonId, kt as scopeKey, m as addonSettingsCapability, ot as DATAPLANE_SECRET_HEADER$1, pt as ReadinessTimeoutError, q as procedureAuthKey, s as METHOD_ACCESS_MAP, st as DEVICE_SETTINGS_CONTRIBUTION_METHODS, t as ALL_CAPABILITY_DEFINITIONS, vt as createEvent, xt as expandCapMethods, yt as emitDownForOwnedCaps } from "./dist-BXmFvn3h.mjs";
+import { A as extractNestedAddonId, At as scopeKey, Dt as parseJsonUnknown$1, Et as parseJsonObject, F as isObjectInput, G as objectInputDeclaresAddonId, H as looseSchema, I as isVoidInput, J as procedureAuthKey, L as kebabToCamel, Mt as EventCategory$1, N as isArrayOutputSchema, Ot as readinessKey, P as isCollectionArrayMethod, R as lifecycleJobSchema, St as expandCapMethods, V as logLevelAtMost, _t as asNumber, at as errMsg$1, bt as emitDownForOwnedCaps, c as RUNTIME_DEFAULTS, ct as DEVICE_SETTINGS_CONTRIBUTION_METHODS, gt as asJsonObject$1, kt as resolveCapMount, lt as DEVICE_STATUS_METHOD, m as addonSettingsCapability, mt as ReadinessTimeoutError, pt as ReadinessRegistry, s as METHOD_ACCESS_MAP, st as DATAPLANE_SECRET_HEADER$1, t as ALL_CAPABILITY_DEFINITIONS, vt as asString$1, yt as createEvent } from "./dist-B7hOpr5i.mjs";
 import { a as downloadModel, c as getModelFilePath, d as contentTypeFor, f as createAuthenticatedFileServer, h as resolveFilePath, i as downloadFile, l as isModelDownloaded, m as parseTokenizedUrl, n as collectModelFiles, o as ensureModel, p as parseRangeHeader, r as deleteModelFromDisk, s as fetchJson, t as ModelDownloadService, u as createFileDataPlaneHandler } from "./model-download-service-Cp9f4dk6.mjs";
-import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as resolveAddonClass, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as runNpm, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-BNOApgK0.mjs";
+import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as resolveAddonClass, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as runNpm, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-Ck4-9K9m.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BkP504Vq.mjs";
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./builtins/sqlite-storage/filesystem-storage.addon.mjs";
 import { SqliteSettingsAddon, t as SqliteSettingsBackend } from "./builtins/sqlite-storage/sqlite-settings.addon.mjs";
@@ -23,6 +23,7 @@ import "./builtins/local-auth/index.mjs";
 import { DeviceManagerAddon } from "./builtins/device-manager/device-manager.addon.mjs";
 import "./builtins/device-manager/index.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
+import * as v8 from "node:v8";
 import { PYTHON_VERSION, buildBinaryPath, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
 import { z } from "zod";
 import { request } from "node:http";
@@ -45,6 +46,100 @@ import { StringDecoder } from "node:string_decoder";
 import { lstatSync, readdir as readdir$1, readdirSync, readlinkSync, realpathSync } from "fs";
 import "path";
 import { createRequire } from "module";
+//#region src/kernel/heap-watch.ts
+/**
+* heap-watch — hub-main's own memory, on the record.
+*
+* ## Why this exists
+*
+* hub-main is launched with `--max-old-space-size=1536` (docker-entrypoint) and
+* has logged NOTHING about its own heap. When it died on 2026-08-01/02 the only
+* trace was V8's own stderr line:
+*
+*     FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+*
+* which carries no process name, no heap number and no history — the whole
+* server restarts and the evidence is gone. Four of those in ~15h, and the one
+* at 06:57:57 landed nine seconds after a viewer opened a WebRTC session, which
+* is why the app sat in a permanent "loading": the hub was dying as it
+* connected.
+*
+* `[mem]` reports already exist for forked addon runners (SIGUSR2 in
+* `addon-runner.ts`) — hub-main, the one process that actually OOMs, was the
+* one process with no telemetry at all.
+*
+* ## What it gives
+*
+* A heartbeat carrying the numbers that separate the two possible stories, and
+* a WARN as the heap approaches the ceiling — the line that will exist BEFORE
+* the next fatal instead of after it:
+*
+*  - `heapUsedMb` climbing steadily between restarts → a leak;
+*  - `heapUsedMb` flat with a sharp jump under load → a burst allocation, and
+*    the timestamp says what was being served.
+*
+* `external`/`arrayBuffers` ride along because they are NOT bounded by
+* `--max-old-space-size` and are most of the gap between a 1.5GB cap and the
+* ~2.05GB RSS observed live: a diagnosis that only looks at the JS heap
+* misreads that process by 500MB.
+*/
+/** Heartbeat period. Slow enough to be free, fast enough that the sample before
+*  a fatal is recent. */
+var HEAP_WATCH_INTERVAL_MS = 6e4;
+/** Warn above this share of the heap ceiling. Chosen so the warning precedes
+*  the fatal by more than one interval under realistic growth. */
+var HEAP_WATCH_WARN_RATIO = .8;
+var MB = (bytes) => Math.round(bytes / 1048576);
+/**
+* Build a sample from raw readings. Pure so the thresholds are testable without
+* allocating a gigabyte to reach them.
+*/
+function buildHeapSample(mem, heapLimitBytes, warnRatio = HEAP_WATCH_WARN_RATIO) {
+	const usedRatio = heapLimitBytes > 0 ? mem.heapUsed / heapLimitBytes : 0;
+	return {
+		rssMb: MB(mem.rss),
+		heapUsedMb: MB(mem.heapUsed),
+		heapTotalMb: MB(mem.heapTotal),
+		heapLimitMb: MB(heapLimitBytes),
+		externalMb: MB(mem.external),
+		arrayBuffersMb: MB(mem.arrayBuffers),
+		usedRatio: Math.round(usedRatio * 100) / 100,
+		nearLimit: usedRatio >= warnRatio
+	};
+}
+var consoleSink = {
+	info: (line) => console.log(line),
+	warn: (line) => console.warn(line)
+};
+function format$1(label, s) {
+	return `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
+}
+/**
+* Start the heartbeat. Returns a stop function.
+*
+* `unref`ed so it can never hold the process open, and every read is wrapped:
+* a diagnostic that can crash the process it watches is worse than none.
+*/
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS) {
+	const tick = () => {
+		try {
+			const sample = buildHeapSample(process.memoryUsage(), v8.getHeapStatistics().heap_size_limit);
+			const line = format$1(label, sample);
+			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
+			else sink.info(line);
+		} catch {}
+	};
+	const timer = setInterval(tick, intervalMs);
+	timer.unref?.();
+	tick();
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+	};
+}
+//#endregion
 //#region src/events/event-bus.ts
 var EventBus = class {
 	listeners = /* @__PURE__ */ new Map();
@@ -5941,6 +6036,10 @@ var INFRA_CAPABILITIES = [
 		name: "storage-provider",
 		required: true
 	},
+	{
+		name: "data-store-provider",
+		required: true
+	},
 	{
 		name: "storage",
 		required: true
@@ -94065,4 +94164,4 @@ var LifecycleJobEngine = class {
 	}
 };
 //#endregion
-export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };
+export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, startHeapWatch, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };

package/dist/kernel/heap-watch.d.ts

@@ -0,0 +1,36 @@
+/** Heartbeat period. Slow enough to be free, fast enough that the sample before
+ *  a fatal is recent. */
+export declare const HEAP_WATCH_INTERVAL_MS = 60000;
+/** Warn above this share of the heap ceiling. Chosen so the warning precedes
+ *  the fatal by more than one interval under realistic growth. */
+export declare const HEAP_WATCH_WARN_RATIO = 0.8;
+export interface HeapSample {
+    readonly rssMb: number;
+    readonly heapUsedMb: number;
+    readonly heapTotalMb: number;
+    readonly heapLimitMb: number;
+    readonly externalMb: number;
+    readonly arrayBuffersMb: number;
+    /** heapUsed / heapLimit, 0-1. */
+    readonly usedRatio: number;
+    /** True once the heap is close enough to the ceiling to be worth shouting. */
+    readonly nearLimit: boolean;
+}
+/**
+ * Build a sample from raw readings. Pure so the thresholds are testable without
+ * allocating a gigabyte to reach them.
+ */
+export declare function buildHeapSample(mem: NodeJS.MemoryUsage, heapLimitBytes: number, warnRatio?: number): HeapSample;
+/** Minimal sink so this module stays usable before any logger exists — the
+ *  starter runs before the kernel's logging is wired. */
+export interface HeapWatchSink {
+    readonly info: (line: string) => void;
+    readonly warn: (line: string) => void;
+}
+/**
+ * Start the heartbeat. Returns a stop function.
+ *
+ * `unref`ed so it can never hold the process open, and every read is wrapped:
+ * a diagnostic that can crash the process it watches is worse than none.
+ */
+export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number): () => void;

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

@@ -5,7 +5,9 @@ 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.)
+ *   (Only one handler is registered; calling again replaces the previous one.
+ *   Because the slot is single, this module registers it exactly ONCE per
+ *   channel — the shared-state factory below — never once per addon bus.)
  * - `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).
@@ -19,6 +21,7 @@ export interface UdsEventChannel {
 }
 /**
  * Create a UDS-backed `IEventBus` for use inside a forked child process.
+ * Returns a per-addon facade over the channel's ONE shared state (module doc).
  *
  * @param client  - The UDS channel toward the parent (hub or agent).
  * @param addonId - This child's stable addon id — stamped as `sourceAddonId`

package/dist/{manifest-python-deps-KZ00cbfP.js → manifest-python-deps-BqE5j0-O.js}

@@ -5164,7 +5164,31 @@ function udsChildLogToWorkerEntry(childId, entry) {
 //#endregion
 //#region src/kernel/transport/uds-event-bus.ts
 /**
+* ONE `SharedBusState` per `UdsEventChannel` (see the module doc's
+* group-runner contract). Keyed weakly so a channel torn down with its
+* process does not pin its state.
+*/
+var sharedStateByChannel = /* @__PURE__ */ new WeakMap();
+/**
+* Resolve (or lazily create) the channel's shared bus state, registering the
+* single-slot `client.onEvent` handler exactly once — on first creation. The
+* handler delivers into the SHARED state, so every co-located addon's
+* subscribers see parent→child events regardless of bus construction order.
+* It does NOT call `client.emitEvent` (no echo back to the parent).
+*/
+function sharedStateFor(client) {
+	const existing = sharedStateByChannel.get(client);
+	if (existing !== void 0) return existing;
+	const created = createSharedBusState();
+	sharedStateByChannel.set(client, created);
+	client.onEvent((event) => {
+		deliverShared(created, event);
+	});
+	return created;
+}
+/**
 * Create a UDS-backed `IEventBus` for use inside a forked child process.
+* Returns a per-addon facade over the channel's ONE shared state (module doc).
 *
 * @param client  - The UDS channel toward the parent (hub or agent).
 * @param addonId - This child's stable addon id — stamped as `sourceAddonId`
@@ -5172,10 +5196,7 @@ function udsChildLogToWorkerEntry(childId, entry) {
 *                  events to their source addon.
 */
 function createUdsEventBus(client, addonId) {
-	const state = createSharedBusState();
-	client.onEvent((event) => {
-		deliverShared(state, event);
-	});
+	const state = sharedStateFor(client);
 	const reportPatterns = () => {
 		client.updateEventPatterns(addonId, [...state.handlers.keys()]);
 	};

package/dist/{manifest-python-deps-BNOApgK0.mjs → manifest-python-deps-Ck4-9K9m.mjs}

@@ -5162,7 +5162,31 @@ function udsChildLogToWorkerEntry(childId, entry) {
 //#endregion
 //#region src/kernel/transport/uds-event-bus.ts
 /**
+* ONE `SharedBusState` per `UdsEventChannel` (see the module doc's
+* group-runner contract). Keyed weakly so a channel torn down with its
+* process does not pin its state.
+*/
+var sharedStateByChannel = /* @__PURE__ */ new WeakMap();
+/**
+* Resolve (or lazily create) the channel's shared bus state, registering the
+* single-slot `client.onEvent` handler exactly once — on first creation. The
+* handler delivers into the SHARED state, so every co-located addon's
+* subscribers see parent→child events regardless of bus construction order.
+* It does NOT call `client.emitEvent` (no echo back to the parent).
+*/
+function sharedStateFor(client) {
+	const existing = sharedStateByChannel.get(client);
+	if (existing !== void 0) return existing;
+	const created = createSharedBusState();
+	sharedStateByChannel.set(client, created);
+	client.onEvent((event) => {
+		deliverShared(created, event);
+	});
+	return created;
+}
+/**
 * Create a UDS-backed `IEventBus` for use inside a forked child process.
+* Returns a per-addon facade over the channel's ONE shared state (module doc).
 *
 * @param client  - The UDS channel toward the parent (hub or agent).
 * @param addonId - This child's stable addon id — stamped as `sourceAddonId`
@@ -5170,10 +5194,7 @@ function udsChildLogToWorkerEntry(childId, entry) {
 *                  events to their source addon.
 */
 function createUdsEventBus(client, addonId) {
-	const state = createSharedBusState();
-	client.onEvent((event) => {
-		deliverShared(state, event);
-	});
+	const state = sharedStateFor(client);
 	const reportPatterns = () => {
 		client.updateEventPatterns(addonId, [...state.handlers.keys()]);
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.28",
+  "version": "1.2.29",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",
@@ -53,9 +53,10 @@
         "category": "system",
         "name": "SQLite Settings",
         "entry": "./dist/builtins/sqlite-storage/sqlite-settings.addon.js",
+        "description": "The relational ENGINE behind the data door (SQLite WAL). Registers `data-store-provider`, an internal collection cap; the public `settings-store` door is owned by `storage-orchestrator`, which dispatches here. Callers never reach this addon directly — that is what makes the engine replaceable.",
         "capabilities": [
           {
-            "name": "settings-store"
+            "name": "data-store-provider"
           }
         ]
       },
@@ -134,12 +135,15 @@
         "id": "storage-orchestrator",
         "category": "system",
         "name": "Storage Orchestrator",
-        "description": "Hub-only singleton that owns the consumer-facing `storage` cap. Holds the `locationId → StorageLocation` map, resolves `StorageLocationRef` to concrete locations, and dispatches every call to the matching `storage-provider` collection registrant (`filesystem-storage` today; future SFTP / S3 / WebDAV addons plug in alongside).",
+        "description": "The single data door. Owns the consumer-facing `storage` cap for bytes — the `locationId → StorageLocation` map, `StorageLocationRef` resolution, dispatch to the matching `storage-provider` registrant (`filesystem-storage` today; SFTP / S3 / WebDAV plug in alongside) — AND the `settings-store` cap for rows, dispatching to the `data-store-provider` engine (`sqlite-settings` today; a vector engine plugs in alongside). Nothing reaches an engine except through this addon.",
         "entry": "./dist/builtins/storage-orchestrator/index.js",
         "protected": true,
         "capabilities": [
           {
             "name": "storage"
+          },
+          {
+            "name": "settings-store"
           }
         ]
       },