@camstack/system 1.2.159 → 1.2.161

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-Ck2jkBZk.js");
+const require_dist = require("./dist-Keu5TDO7.js");
 const require_builtins_alerts_alerts_addon = require("./builtins/alerts/alerts.addon.js");
 require("./builtins/alerts/index.js");
 const require_formatter = require("./formatter-DqAKDlvN.js");
@@ -26,7 +26,7 @@ require("./builtins/system-config/index.js");
 const require_builtins_winston_logging_index = require("./builtins/winston-logging/index.js");
 const require_file_data_plane = require("./file-data-plane-DO8KbxCe.js");
 const require_tls$1 = require("./tls-BxQlomxd.js");
-const require_manifest_system_deps = require("./manifest-system-deps-8boi90D9.js");
+const require_manifest_system_deps = require("./manifest-system-deps-DYv4ZPo2.js");
 const require_resource_monitor = require("./resource-monitor-CdnzxBLP.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let zod = require("zod");
@@ -95162,6 +95162,19 @@ var LifecycleJobEngine = class {
 	* per-task abort timeout. On success the resolved `stagedPath` is returned; on
 	* failure the task is marked `failed` and `null` is returned (so the apply
 	* phase skips it). Other tasks are unaffected.
+	*
+	* **`toVersion` is REWRITTEN here, to the version that was actually
+	* fetched.** A task's `toVersion` starts as the REQUEST, and the request is
+	* routinely a dist-tag: `addons.updatePackage` with no version resolves to
+	* the literal `'latest'`. The staging area already resolves it — it reads
+	* the version out of the unpacked tarball and returns `resolvedVersion` —
+	* and dropping that answer sent the string `'latest'` onward as if it were a
+	* version. It became the manifest's recorded version, the version the Addons
+	* page displayed, and the `toVersion` on the `addon.updated` event, which an
+	* operator read on his phone as "@camstack/addon-terminal 0.0.0 → latest"
+	* (2026-08-30). Everything downstream of the apply reads a version; none of
+	* it can resolve a tag, and none of it could tell that it had been handed
+	* one.
 	*/
 	async fetchAddonTask(job, task) {
 		try {
@@ -95171,20 +95184,28 @@ var LifecycleJobEngine = class {
 			});
 			const ac = new AbortController();
 			const timer = setTimeout(() => ac.abort(), this.deps.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS);
-			let stagedPath;
+			let staged;
 			try {
-				stagedPath = (await this.deps.staging.fetchAndStage({
+				staged = await this.deps.staging.fetchAndStage({
 					jobId: job.jobId,
 					name: task.packageName,
 					version: task.toVersion,
 					signal: ac.signal
-				})).stagedPath;
+				});
 			} finally {
 				clearTimeout(timer);
 			}
-			this.advance(job.jobId, task, "staged", { stagedPath });
+			const stagedPath = staged.stagedPath;
+			const resolved = {
+				...task,
+				toVersion: staged.resolvedVersion
+			};
+			this.advance(job.jobId, task, "staged", {
+				stagedPath,
+				toVersion: resolved.toVersion
+			});
 			return {
-				task,
+				task: resolved,
 				stagedPath
 			};
 		} catch (err) {
@@ -95437,6 +95458,7 @@ exports.NativeMetricsAddon = require_builtins_native_metrics_native_metrics_addo
 exports.NativeMetricsProvider = require_builtins_native_metrics_native_metrics_addon.NativeMetricsProvider;
 exports.NetworkQualityTracker = NetworkQualityTracker;
 exports.NotificationService = NotificationService;
+exports.PARENT_ROUTED_PROVIDER_ADDON_ID = require_manifest_system_deps.PARENT_ROUTED_PROVIDER_ADDON_ID;
 Object.defineProperty(exports, "PYTHON_VERSION", {
 	enumerable: true,
 	get: function() {

package/dist/index.mjs

@@ -1,5 +1,5 @@
 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 { $ as isObjectInput, $t as parseJsonUnknown$1, Bt as ReadinessTimeoutError, Ft as DEVICE_STATUS_METHOD, Gt as createEvent, Ht as asJsonObject$1, J as extractNestedAddonId, Jt as expandCapMethods, Kt as emitDownForOwnedCaps, Nt as DATAPLANE_SECRET_HEADER$1, Pt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Q as isCollectionArrayMethod, Qt as parseJsonObject, T as addonSettingsCapability, Ut as asNumber, Wt as asString$1, Z as isArrayOutputSchema, _t as resolveMethodAuth, bt as scopesAllowDeviceCap, ct as looseSchema, dt as objectInputDeclaresAddonId, en as readinessKey, f as LOG_LEVEL_RANK, h as RUNTIME_DEFAULTS, in as EventCategory$1, it as lifecycleJobSchema, jt as errMsg$1, mt as procedureAuthKey, nn as scopeKey, nt as isVoidInput, p as METHOD_ACCESS_MAP, rt as kebabToCamel, st as logLevelAtMost, t as ALL_CAPABILITY_DEFINITIONS, tn as resolveCapMount, yt as scopesAllowAddon, zt as ReadinessRegistry } from "./dist-DLh4_rn3.mjs";
+import { $ as isObjectInput, $t as parseJsonUnknown$1, Bt as ReadinessTimeoutError, Ft as DEVICE_STATUS_METHOD, Gt as createEvent, Ht as asJsonObject$1, J as extractNestedAddonId, Jt as expandCapMethods, Kt as emitDownForOwnedCaps, Nt as DATAPLANE_SECRET_HEADER$1, Pt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Q as isCollectionArrayMethod, Qt as parseJsonObject, T as addonSettingsCapability, Ut as asNumber, Wt as asString$1, Z as isArrayOutputSchema, _t as resolveMethodAuth, bt as scopesAllowDeviceCap, ct as looseSchema, dt as objectInputDeclaresAddonId, en as readinessKey, f as LOG_LEVEL_RANK, h as RUNTIME_DEFAULTS, in as EventCategory$1, it as lifecycleJobSchema, jt as errMsg$1, mt as procedureAuthKey, nn as scopeKey, nt as isVoidInput, p as METHOD_ACCESS_MAP, rt as kebabToCamel, st as logLevelAtMost, t as ALL_CAPABILITY_DEFINITIONS, tn as resolveCapMount, yt as scopesAllowAddon, zt as ReadinessRegistry } from "./dist-D4xNBlJM.mjs";
 import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
 import "./builtins/alerts/index.mjs";
 import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -25,7 +25,7 @@ import "./builtins/system-config/index.mjs";
 import { WinstonDestination, WinstonLoggingAddon } from "./builtins/winston-logging/index.mjs";
 import { a as parseTokenizedUrl, c as collectModelFiles, d as downloadModel, f as ensureModel, h as isModelDownloaded, i as parseRangeHeader, l as deleteModelFromDisk, m as getModelFilePath, n as contentTypeFor, o as resolveFilePath, p as fetchJson, r as createAuthenticatedFileServer, s as ModelDownloadService, t as createFileDataPlaneHandler, u as downloadFile } from "./file-data-plane-BhKdxJgf.mjs";
 import { C as registerLanHttpHandler, S as readLanHttpState, _ as DEFAULT_LAN_HTTP_PORT, a as writeTlsMode, b as bindPendingLanHttp, c as loadTlsCert, d as collectCertIdentity, f as CA_VALIDITY_DAYS, g as evaluateExistingCert, h as SERVER_AUTH_OID, i as writeExtraSans, l as reissueTlsLeaf, m as MAX_LEAF_VALIDITY_DAYS, n as readTlsAccessStatus, o as validateUploadedTls, p as LEAF_RENEWAL_WINDOW_DAYS, r as readTlsMode, s as ensureTlsCert, t as readExtraSans, u as CA_COMMON_NAME, v as allFamiliesListenHost, x as closeLanHttp, y as applyLanHttp } from "./tls-DOTmtLCW.mjs";
-import { $ as encodeFrame, $t as HEAP_SPACE_REPORT_MIN_MB, A as createHubCapForwardService, At as HEAP_WATCH_WARN_RATIO, B as AGENT_CAP_FWD_ACTION, Bt as createDeferredHeapWatchSink, C as brokerCallForCap, Cn as formatEventPlane, Ct as resolveNpmInvocation, D as localProviderLink, Dt as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, E as ipcParentLink, Et as HEAP_RECLAIM_MIN_INTERVAL_MS, F as createUdsLogger, Ft as RSS_BUDGET_RELEASE_RATIO, G as callWithServiceDiscovery, Gt as nextRssBudgetState, H as CapRouteResolver, Ht as createV8Reclaimer, I as createUdsLoggerWithControl, It as RUNNER_HEAP_WATCH_INTERVAL_MS, J as UdsLocalTransportClient, Jt as shouldReclaim, K as readMoleculerFanoutMode, Kt as parseRssBudgetMb, L as LocalChildClient, Lt as RUNNER_RSS_BUDGET_ENV, M as createUdsEventBridge, Mt as HUB_MAIN_RSS_BUDGET_MB, N as createUdsEventBus, Nt as HUB_RSS_BUDGET_ENV, O as HUB_CAP_FWD_ACTION, Ot as HEAP_RECLAIM_TRIGGER_MB, P as udsChildLogToWorkerEntry, Pt as RSS_BUDGET_REANNOUNCE_MIN_MS, Q as FrameDecoder, Qt as DECISIVE_HEAP_SPACES, R as LocalChildRegistry, Rt as ZERO_LOOP_DELAY, S as getCapUsageRegistry, Sn as diffEventPlane, St as resolveAddonClass, T as buildLinkChain, Tt as createAddonDataPlaneFacility, U as CapRouteError, Ut as describeRss, V as AGENT_CAP_FWD_SERVICE, Vt as createLoopDelayMeter, W as classifyCapRoute, Wt as hubMainRssBudget, X as SocketChannel, Xt as startRunnerHeapWatch, Y as UdsLocalTransportServer, Yt as startHeapWatch, Z as localEndpointPath, Zt as strandedMb, _ as AddonDepsManager, _n as socketDirectionBytes, _t as DeviceRegistry, a as createUdsAddonContext, an as readHeapSpaces, at as mountNativeCapService, b as CapUsageRegistry, bn as createEventPlaneMeter, bt as copyBundledNativeModules, c as getOrInitReadinessRegistryForClient, cn as SOCKET_PLANE_TOP_N, ct as validateProviderRegistrations, d as clusterEventTopic, dn as diffSocketPlane, dt as capActionSuffix, en as RUNNER_HEAP_SNAPSHOT_ENV, et as buildNativeCapProxy, f as getBrokerEventBus, fn as formatSocketPlane, ft as capBareAction, g as subscribePassthrough, gn as sampleSocketDirection, gt as serializeTypedArrays, h as setNodeEventInterest, hn as recordSocketFrame, ht as deserializeTypedArrays, i as createAddonContext, in as heapSpaceField, j as createParentUnownedCallHandler, jt as HUB_MAIN_HEAP_WATCH_LABEL, k as HUB_CAP_FWD_SERVICE, kt as HEAP_WATCH_INTERVAL_MS, l as setHubConnected, ln as createSocketPlaneMeter, lt as NATIVE_PROVIDER_SERVICE_INFIX, m as registerEventBusService, mn as createSocketDirectionCounters, mt as parseCapAction, n as installManifestPythonDeps, nn as formatHeapSpaces, nt as createBrokerDeviceManagerApi, o as getWorkerDeviceRegistry, on as selectReportedSpaces, p as getMoleculerEventStats, pn as EMPTY_SOCKET_DIRECTION, pt as capServiceName, q as createLocalTransport, qt as reclaimIntervalMs, r as adaptBrokerToCluster, rn as heapSnapshotAuthorised, s as getOrInitReadinessRegistry, sn as EMPTY_SOCKET_PLANE_BASELINE, st as createAddonService, t as installManifestSystemDeps, tn as emitHeapDiagnosticReport, tt as buildUdsNativeCapProxy, u as EVENT_TOPIC_PREFIX, un as createSocketPlaneReader, ut as capActionName, v as createKernelHwAccel, vn as socketDirectionMessages, vt as CapabilityHandle, w as brokerTransportLink, wt as runNpm, x as __resetCapUsageRegistryForTests, xn as createEventPlaneReader, xt as installManifestNativeDeps, y as resolveHwAccel, yn as EVENT_PLANE_TOP_N, yt as CapabilityUnavailableError, z as UDS_NO_ROUTE_PREFIX, zt as buildHeapSample } from "./manifest-system-deps-tZZYG3RR.mjs";
+import { $ as FrameDecoder, $t as DECISIVE_HEAP_SPACES, A as createUdsEventBus, At as HEAP_WATCH_INTERVAL_MS, B as CapRouteError, Bt as buildHeapSample, C as ipcParentLink, Cn as diffEventPlane, Ct as resolveAddonClass, D as createHubCapForwardService, Dt as HEAP_RECLAIM_MIN_INTERVAL_MS, E as HUB_CAP_FWD_SERVICE, Et as createAddonDataPlaneFacility, F as LocalChildRegistry, Ft as RSS_BUDGET_REANNOUNCE_MIN_MS, G as PARENT_ROUTED_PROVIDER_ADDON_ID, Gt as hubMainRssBudget, H as callWithServiceDiscovery, Ht as createLoopDelayMeter, I as UDS_NO_ROUTE_PREFIX, It as RSS_BUDGET_RELEASE_RATIO, J as createLocalTransport, Jt as reclaimIntervalMs, K as __resetCapUsageRegistryForTests, Kt as nextRssBudgetState, L as AGENT_CAP_FWD_ACTION, Lt as RUNNER_HEAP_WATCH_INTERVAL_MS, M as createUdsLogger, Mt as HUB_MAIN_HEAP_WATCH_LABEL, N as createUdsLoggerWithControl, Nt as HUB_MAIN_RSS_BUDGET_MB, O as createParentUnownedCallHandler, Ot as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, P as LocalChildClient, Pt as HUB_RSS_BUDGET_ENV, Q as localEndpointPath, Qt as strandedMb, R as AGENT_CAP_FWD_SERVICE, Rt as RUNNER_RSS_BUDGET_ENV, S as buildLinkChain, Sn as createEventPlaneReader, St as installManifestNativeDeps, T as HUB_CAP_FWD_ACTION, Tt as runNpm, U as readMoleculerFanoutMode, Ut as createV8Reclaimer, V as classifyCapRoute, Vt as createDeferredHeapWatchSink, W as CapUsageRegistry, Wt as describeRss, X as UdsLocalTransportServer, Xt as startHeapWatch, Y as UdsLocalTransportClient, Yt as shouldReclaim, Z as SocketChannel, Zt as startRunnerHeapWatch, _ as AddonDepsManager, _n as sampleSocketDirection, _t as serializeTypedArrays, a as createUdsAddonContext, an as heapSpaceField, b as brokerCallForCap, bn as EVENT_PLANE_TOP_N, bt as CapabilityUnavailableError, c as getOrInitReadinessRegistryForClient, cn as EMPTY_SOCKET_PLANE_BASELINE, ct as createAddonService, d as clusterEventTopic, dn as createSocketPlaneReader, dt as capActionName, en as HEAP_SPACE_REPORT_MIN_MB, et as encodeFrame, f as getBrokerEventBus, fn as diffSocketPlane, ft as capActionSuffix, g as subscribePassthrough, gn as recordSocketFrame, gt as deserializeTypedArrays, h as setNodeEventInterest, hn as createSocketDirectionCounters, ht as parseCapAction, i as createAddonContext, in as heapSnapshotAuthorised, j as udsChildLogToWorkerEntry, jt as HEAP_WATCH_WARN_RATIO, k as createUdsEventBridge, kt as HEAP_RECLAIM_TRIGGER_MB, l as setHubConnected, ln as SOCKET_PLANE_TOP_N, lt as validateProviderRegistrations, m as registerEventBusService, mn as EMPTY_SOCKET_DIRECTION, mt as capServiceName, n as installManifestPythonDeps, nn as emitHeapDiagnosticReport, nt as buildUdsNativeCapProxy, o as getWorkerDeviceRegistry, on as readHeapSpaces, ot as mountNativeCapService, p as getMoleculerEventStats, pn as formatSocketPlane, pt as capBareAction, q as getCapUsageRegistry, qt as parseRssBudgetMb, r as adaptBrokerToCluster, rn as formatHeapSpaces, rt as createBrokerDeviceManagerApi, s as getOrInitReadinessRegistry, sn as selectReportedSpaces, t as installManifestSystemDeps, tn as RUNNER_HEAP_SNAPSHOT_ENV, tt as buildNativeCapProxy, u as EVENT_TOPIC_PREFIX, un as createSocketPlaneMeter, ut as NATIVE_PROVIDER_SERVICE_INFIX, v as createKernelHwAccel, vn as socketDirectionBytes, vt as DeviceRegistry, w as localProviderLink, wn as formatEventPlane, wt as resolveNpmInvocation, x as brokerTransportLink, xn as createEventPlaneMeter, xt as copyBundledNativeModules, y as resolveHwAccel, yn as socketDirectionMessages, yt as CapabilityHandle, z as CapRouteResolver, zt as ZERO_LOOP_DELAY } from "./manifest-system-deps-CiCuev2R.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BWmQ5i-o.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { z } from "zod";
@@ -95155,6 +95155,19 @@ var LifecycleJobEngine = class {
 	* per-task abort timeout. On success the resolved `stagedPath` is returned; on
 	* failure the task is marked `failed` and `null` is returned (so the apply
 	* phase skips it). Other tasks are unaffected.
+	*
+	* **`toVersion` is REWRITTEN here, to the version that was actually
+	* fetched.** A task's `toVersion` starts as the REQUEST, and the request is
+	* routinely a dist-tag: `addons.updatePackage` with no version resolves to
+	* the literal `'latest'`. The staging area already resolves it — it reads
+	* the version out of the unpacked tarball and returns `resolvedVersion` —
+	* and dropping that answer sent the string `'latest'` onward as if it were a
+	* version. It became the manifest's recorded version, the version the Addons
+	* page displayed, and the `toVersion` on the `addon.updated` event, which an
+	* operator read on his phone as "@camstack/addon-terminal 0.0.0 → latest"
+	* (2026-08-30). Everything downstream of the apply reads a version; none of
+	* it can resolve a tag, and none of it could tell that it had been handed
+	* one.
 	*/
 	async fetchAddonTask(job, task) {
 		try {
@@ -95164,20 +95177,28 @@ var LifecycleJobEngine = class {
 			});
 			const ac = new AbortController();
 			const timer = setTimeout(() => ac.abort(), this.deps.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS);
-			let stagedPath;
+			let staged;
 			try {
-				stagedPath = (await this.deps.staging.fetchAndStage({
+				staged = await this.deps.staging.fetchAndStage({
 					jobId: job.jobId,
 					name: task.packageName,
 					version: task.toVersion,
 					signal: ac.signal
-				})).stagedPath;
+				});
 			} finally {
 				clearTimeout(timer);
 			}
-			this.advance(job.jobId, task, "staged", { stagedPath });
+			const stagedPath = staged.stagedPath;
+			const resolved = {
+				...task,
+				toVersion: staged.resolvedVersion
+			};
+			this.advance(job.jobId, task, "staged", {
+				stagedPath,
+				toVersion: resolved.toVersion
+			});
 			return {
-				task,
+				task: resolved,
 				stagedPath
 			};
 		} catch (err) {
@@ -95335,4 +95356,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, CA_COMMON_NAME, CA_VALIDITY_DAYS, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DECISIVE_HEAP_SPACES, DEFAULT_DATA_PATH, DEFAULT_LAN_HTTP_PORT, DEFAULT_LOG_LEVEL, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EMPTY_SOCKET_DIRECTION, EMPTY_SOCKET_PLANE_BASELINE, EVENT_PLANE_TOP_N, 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_RECLAIM_MIN_INTERVAL_MS, HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, HEAP_RECLAIM_TRIGGER_MB, HEAP_SPACE_REPORT_MIN_MB, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HUB_MAIN_HEAP_WATCH_LABEL, HUB_MAIN_RSS_BUDGET_MB, HUB_RSS_BUDGET_ENV, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LEAF_RENEWAL_WINDOW_DAYS, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LoggingGate, LokiDestination, LokiLoggingAddon, MAX_LEAF_VALIDITY_DAYS, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, QUARANTINE_DIRNAME, RESTART_MARKER_FILE, RSS_BUDGET_REANNOUNCE_MIN_MS, RSS_BUDGET_RELEASE_RATIO, RUNNER_HEAP_SNAPSHOT_ENV, RUNNER_HEAP_WATCH_INTERVAL_MS, RUNNER_RSS_BUDGET_ENV, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, SERVER_AUTH_OID, SOCKET_PLANE_TOP_N, 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, ZERO_LOOP_DELAY, __resetCapUsageRegistryForTests, __resetLoggingGateForTests, adaptBrokerToCluster, addonSettingsCapability, allFamiliesListenHost, applyLanHttp, bindPendingLanHttp, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, canServeDataPlane, capActionName, capActionSuffix, capBareAction, capServiceName, classifyAddonDir, classifyCapRoute, clearPendingRestart, closeLanHttp, clusterEventTopic, clusterSecretMatches, collectCertIdentity, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createDeferredHeapWatchSink, createDoorSettingsView, createEventPlaneMeter, createEventPlaneReader, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createLoopDelayMeter, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createSocketDirectionCounters, createSocketPlaneMeter, createSocketPlaneReader, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, describeRss, detectWorkspacePackagesDir, diffEventPlane, diffSocketPlane, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, emitHeapDiagnosticReport, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, evaluateExistingCert, expandCapMethods, fetchJson, findInPath, formatEventPlane, formatHeapSpaces, formatLogLine, formatSocketPlane, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getLoggingGate, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, heapSnapshotAuthorised, heapSpaceField, hubMainRssBudget, installManifestNativeDeps, installManifestPythonDeps, installManifestSystemDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, isolatedBuiltinPhase, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, nextRssBudgetState, parseCapAction, parseRangeHeader, parseRssBudgetMb, parseTokenizedUrl, partitionIsolatedBuiltinIds, proxyToUpstream, quarantineAddonResidue, readExtraSans, readHeapSpaces, readLanHttpState, readMoleculerFanoutMode, readPendingRestart, readTlsAccessStatus, readTlsMode, readinessKey, reclaimIntervalMs, recordSocketFrame, registerEventBusService, registerLanHttpHandler, reissueTlsLeaf, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runHubAddonBoot, runNpm, sampleSocketDirection, scheduleSelfRestart, scopeKey, scopesAllowAddon, scopesAllowDeviceCap, selectAddonResidue, selectReportedSpaces, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, socketDirectionBytes, socketDirectionMessages, startHeapWatch, startRunnerHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, validateUploadedTls, waitUntilReady, writeExtraSans, writePendingRestart, writeTlsMode };
+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, CA_COMMON_NAME, CA_VALIDITY_DAYS, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DECISIVE_HEAP_SPACES, DEFAULT_DATA_PATH, DEFAULT_LAN_HTTP_PORT, DEFAULT_LOG_LEVEL, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EMPTY_SOCKET_DIRECTION, EMPTY_SOCKET_PLANE_BASELINE, EVENT_PLANE_TOP_N, 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_RECLAIM_MIN_INTERVAL_MS, HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, HEAP_RECLAIM_TRIGGER_MB, HEAP_SPACE_REPORT_MIN_MB, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HUB_MAIN_HEAP_WATCH_LABEL, HUB_MAIN_RSS_BUDGET_MB, HUB_RSS_BUDGET_ENV, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LEAF_RENEWAL_WINDOW_DAYS, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LoggingGate, LokiDestination, LokiLoggingAddon, MAX_LEAF_VALIDITY_DAYS, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PARENT_ROUTED_PROVIDER_ADDON_ID, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, QUARANTINE_DIRNAME, RESTART_MARKER_FILE, RSS_BUDGET_REANNOUNCE_MIN_MS, RSS_BUDGET_RELEASE_RATIO, RUNNER_HEAP_SNAPSHOT_ENV, RUNNER_HEAP_WATCH_INTERVAL_MS, RUNNER_RSS_BUDGET_ENV, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, SERVER_AUTH_OID, SOCKET_PLANE_TOP_N, 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, ZERO_LOOP_DELAY, __resetCapUsageRegistryForTests, __resetLoggingGateForTests, adaptBrokerToCluster, addonSettingsCapability, allFamiliesListenHost, applyLanHttp, bindPendingLanHttp, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, canServeDataPlane, capActionName, capActionSuffix, capBareAction, capServiceName, classifyAddonDir, classifyCapRoute, clearPendingRestart, closeLanHttp, clusterEventTopic, clusterSecretMatches, collectCertIdentity, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createDeferredHeapWatchSink, createDoorSettingsView, createEventPlaneMeter, createEventPlaneReader, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createLoopDelayMeter, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createSocketDirectionCounters, createSocketPlaneMeter, createSocketPlaneReader, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, describeRss, detectWorkspacePackagesDir, diffEventPlane, diffSocketPlane, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, emitHeapDiagnosticReport, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, evaluateExistingCert, expandCapMethods, fetchJson, findInPath, formatEventPlane, formatHeapSpaces, formatLogLine, formatSocketPlane, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getLoggingGate, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, heapSnapshotAuthorised, heapSpaceField, hubMainRssBudget, installManifestNativeDeps, installManifestPythonDeps, installManifestSystemDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, isolatedBuiltinPhase, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, nextRssBudgetState, parseCapAction, parseRangeHeader, parseRssBudgetMb, parseTokenizedUrl, partitionIsolatedBuiltinIds, proxyToUpstream, quarantineAddonResidue, readExtraSans, readHeapSpaces, readLanHttpState, readMoleculerFanoutMode, readPendingRestart, readTlsAccessStatus, readTlsMode, readinessKey, reclaimIntervalMs, recordSocketFrame, registerEventBusService, registerLanHttpHandler, reissueTlsLeaf, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runHubAddonBoot, runNpm, sampleSocketDirection, scheduleSelfRestart, scopeKey, scopesAllowAddon, scopesAllowDeviceCap, selectAddonResidue, selectReportedSpaces, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, socketDirectionBytes, socketDirectionMessages, startHeapWatch, startRunnerHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, validateUploadedTls, waitUntilReady, writeExtraSans, writePendingRestart, writeTlsMode };

package/dist/kernel/index.d.ts

@@ -73,8 +73,8 @@ export { localProviderLink, brokerTransportLink, ipcParentLink, buildLinkChain,
 export type { LocalProviderResolver, BrokerCapCallOpts } from './moleculer/trpc-links.js';
 export { createProcessService } from './moleculer/process-service.js';
 export type { ProcessInfo } from './moleculer/process-service.js';
-export { CapUsageRegistry, getCapUsageRegistry, __resetCapUsageRegistryForTests, } from './moleculer/cap-usage-registry.js';
-export type { CapUsageCallRecord, CapUsageEdge, CapUsageRegistryOptions, } from './moleculer/cap-usage-registry.js';
+export { CapUsageRegistry, getCapUsageRegistry, PARENT_ROUTED_PROVIDER_ADDON_ID, __resetCapUsageRegistryForTests, } from './moleculer/cap-usage-registry.js';
+export type { CapUsageCallRecord, CapUsageEdge, CapUsageRegistryOptions, CapUsageStats, } from './moleculer/cap-usage-registry.js';
 export { createScopedProcessManager } from './moleculer/process-context.js';
 export type { IAddonProcessManager } from '@camstack/types';
 export { callWithServiceDiscovery } from './moleculer/resilient-cap-call.js';

package/dist/kernel/lifecycle/lifecycle-job-engine.d.ts

@@ -31,6 +31,19 @@ export declare class LifecycleJobEngine {
      * per-task abort timeout. On success the resolved `stagedPath` is returned; on
      * failure the task is marked `failed` and `null` is returned (so the apply
      * phase skips it). Other tasks are unaffected.
+     *
+     * **`toVersion` is REWRITTEN here, to the version that was actually
+     * fetched.** A task's `toVersion` starts as the REQUEST, and the request is
+     * routinely a dist-tag: `addons.updatePackage` with no version resolves to
+     * the literal `'latest'`. The staging area already resolves it — it reads
+     * the version out of the unpacked tarball and returns `resolvedVersion` —
+     * and dropping that answer sent the string `'latest'` onward as if it were a
+     * version. It became the manifest's recorded version, the version the Addons
+     * page displayed, and the `toVersion` on the `addon.updated` event, which an
+     * operator read on his phone as "@camstack/addon-terminal 0.0.0 → latest"
+     * (2026-08-30). Everything downstream of the apply reads a version; none of
+     * it can resolve a tag, and none of it could tell that it had been handed
+     * one.
      */
     private fetchAddonTask;
     /**

package/dist/kernel/moleculer/cap-usage-registry.d.ts

@@ -1,15 +1,62 @@
 /**
- * In-memory observation of tRPC cap calls between addons.
+ * In-memory observation of tRPC cap calls between addons — the store behind
+ * `nodes.getCapUsageGraph`.
  *
  * Storage: `Map<callerAddonId, Map<providerAddonId, Map<capName, RollingWindow>>>`.
  * `RollingWindow` is a fixed-size ring of 1-second buckets — default 300
- * buckets = 5 minutes retention. Queries narrower than the retention
- * window filter buckets at read time.
+ * buckets = 5 minutes retention. Queries narrower than the retention window
+ * filter buckets at read time.
  *
- * Memory bound: 30 callers × 30 providers × 50 caps × 300 buckets × 16 B ≈ 22 MB
- * worst case. Realistic load (~10 active caller→provider→cap triples)
- * keeps it under 200 KB.
+ * ── The ring ages, and that is not free decoration ─────────────────────────
+ * Buckets are indexed `second % retention`, so a bucket written at second S is
+ * hit again at S + retention·k forever. Until 2026-08-30 nothing ever zeroed
+ * them: the `lastCallAtMs` guard hid it while a triple was fully idle, but ONE
+ * fresh call re-armed the entire stale ring. A triple that made 1000 calls and
+ * then one call five minutes later reported **1001 calls/min instead of 1**.
+ * An over-counted edge is worse than the empty graph this instrument shipped
+ * with — silence invites doubt, a confident wrong number sends the next
+ * investigation at the wrong addon.
+ *
+ * The fix is clear-forward: on each record, zero the buckets the ring has
+ * ADVANCED over since the previous write, and never read past the last written
+ * second. Amortised O(1) — a busy triple clears 0–1 buckets per call, and an
+ * idle one clears at most `retention` once, when it wakes.
+ *
+ * ── Cardinality is bounded, because this map lives on hub-main ─────────────
+ * The previous docblock claimed "~22 MB worst case … under 200 KB at ~10 active
+ * triples". Both numbers were written for a smaller machine and the second was
+ * an assumption, not a bound: the key space is caller × provider × cap, and on
+ * the live hub that is 64 addons × 64 runners × ~150 caps. Nothing capped it.
+ *
+ * Today a ring is one `Uint32Array(retention)` — 1.2 KB of ArrayBuffer at the
+ * default — plus the three Map entries that reach it. MEASURED (`heapUsed` +
+ * `arrayBuffers`, node 24, `--expose-gc`): **1.7 KB per triple**, so ≈1.0 MB at
+ * the realistic hub figure (64 callers × a handful of caps each, ≈600 triples)
+ * and **6.3 MB at the {@link DEFAULT_MAX_TRIPLES} ceiling**. `recordCall` costs
+ * ≈46 ns (1e6 calls in 46 ms) — at the 39 717 calls/min that started this
+ * investigation, ≈30 µs of hub-main per second.
+ *
+ * Reclamation is what keeps it at the low end: a triple whose ring has entirely
+ * aged out is dead data and is dropped on the next admission sweep. The hard
+ * cap only exists so that a pathological key space (a caller id derived from
+ * something unbounded) cannot take hub-main's heap with it — and when it bites,
+ * {@link CapUsageRegistry.getStats} says how often, because an instrument that
+ * truncates silently is the defect this whole file exists to fix (D237).
+ */
+/**
+ * Provider placeholder for a call the PARENT routed rather than short-
+ * circuiting to a sibling runner: hub-in-process (`settings-store`,
+ * `device-manager`, the `$core-caps` bridge), or a remote node. At the layer
+ * that records — the parent's `cap-call-out` handler — the sibling id IS the
+ * provider and everything else has not been resolved yet.
+ *
+ * It is a NAMED unknown, not a dropped observation, for the reason D237 was
+ * written: the caller is always known, and "who is hammering `settings-store`"
+ * is the question this graph exists to answer. Sibling to
+ * `UNRESOLVED_PROVIDER_ADDON_ID` in `trpc-links.ts`, which names the same kind
+ * of unknown one layer up.
  */
+export declare const PARENT_ROUTED_PROVIDER_ADDON_ID = "(unresolved: parent-routed)";
 export interface CapUsageCallRecord {
     readonly callerAddonId: string;
     readonly providerAddonId: string;
@@ -17,6 +64,17 @@ export interface CapUsageCallRecord {
     readonly methodName: string;
     readonly atMs: number;
 }
+/**
+ * One observed caller → provider → cap edge.
+ *
+ * There is deliberately no `methodName`: the ring is keyed by CAPABILITY, so
+ * `deviceManager.getAllBindings` (the whole fleet) and
+ * `deviceManager.getBindings` (one camera) collapse into the same edge. The
+ * method IS recorded on the way in ({@link CapUsageCallRecord.methodName}) and
+ * discarded here. Splitting the key by method would multiply cardinality by the
+ * per-cap method count — worth doing, but it is a schema change to
+ * `nodes.getCapUsageGraph`, not a quiet widening of a map on hub-main.
+ */
 export interface CapUsageEdge {
     readonly callerAddonId: string;
     readonly providerAddonId: string;
@@ -27,20 +85,87 @@ export interface CapUsageEdge {
 export interface CapUsageRegistryOptions {
     /** Max retention in seconds (ring length). Default 300. */
     readonly retentionSeconds?: number;
+    /**
+     * Ceiling on live `(caller, provider, cap)` triples. Default
+     * {@link DEFAULT_MAX_TRIPLES}. Reaching it drops NEW triples (counted in
+     * {@link CapUsageStats.droppedTriples}); triples already being watched keep
+     * counting exactly.
+     */
+    readonly maxTriples?: number;
+}
+/** What the registry knows about its own coverage. Never a guess. */
+export interface CapUsageStats {
+    /** Live `(caller, provider, cap)` triples held right now. */
+    readonly triples: number;
+    /** Ceiling in force. */
+    readonly maxTriples: number;
+    /**
+     * New triples refused since process start because the ceiling was full.
+     * Non-zero means the graph is INCOMPLETE — some caller→cap edge exists and
+     * is not shown. Nothing else in this file can be incomplete without saying so.
+     */
+    readonly droppedTriples: number;
 }
 export declare class CapUsageRegistry {
     private readonly retentionSeconds;
+    private readonly maxTriples;
     private readonly map;
+    private triples;
+    private droppedTriples;
     constructor(opts?: CapUsageRegistryOptions);
+    /**
+     * Record one observed cap call.
+     *
+     * On the hot path: this runs once per cross-process cap call on hub-main's
+     * event loop, which is the cluster's only queue (D181). Three Map lookups, an
+     * integer increment, and — only when the wall clock has moved on — a bounded
+     * clear. No allocation once a triple exists, and it NEVER throws into the
+     * call it observes.
+     */
     recordCall(rec: CapUsageCallRecord): void;
     getGraph(opts: {
         windowSeconds: number;
         nowMs: number;
     }): readonly CapUsageEdge[];
+    /** See {@link CapUsageStats}. Cheap — three counters, no scan. */
+    getStats(): CapUsageStats;
     /** Test / diagnostic helper — drops all recorded calls. */
     clear(): void;
+    /**
+     * Sum the buckets covering `(nowSec - windowSeconds, nowSec]`.
+     *
+     * The scan starts at `lastSec`, never at `nowSec`. `recordCall` clears the
+     * buckets the ring has advanced OVER, which by definition stops at the last
+     * write: the buckets for the seconds since then still hold whatever the
+     * previous pass left in them, and reading `nowSec` down would count it. A
+     * triple that went quiet for a couple of minutes and then made one call would
+     * report the burst it made five minutes earlier.
+     *
+     * No lower bound is needed beyond the window itself: every bucket at or below
+     * `lastSec - retention` was cleared by the advance that reached `lastSec`, so
+     * it reads zero anyway. The loop is bounded by `windowSeconds ≤ retention`.
+     */
+    private sumWindow;
+    /**
+     * The ring for this triple, creating it if the ceiling allows. `null` means
+     * the observation is dropped — counted, never silent (see
+     * {@link CapUsageStats.droppedTriples}).
+     */
+    private windowFor;
+    /**
+     * Drop every triple whose whole ring has aged out — its last call is older
+     * than the retention window, so it can contribute to no query. O(triples),
+     * and only reachable when the ceiling is full, so it is amortised away by the
+     * admissions it enables.
+     */
+    private reclaimExpired;
 }
-/** Hub-side singleton. The first caller seeds it; subsequent calls return the same. */
+/**
+ * The registry for THIS process. Deliberately per-process: the reader
+ * (`nodes.getCapUsageGraph` → `cap-providers.ts`) runs on hub-main, so only
+ * writes made on hub-main are ever visible. See the blind-spot list on
+ * `LocalChildRegistryOptions.capUsageObserver` for what that excludes.
+ */
 export declare function getCapUsageRegistry(): CapUsageRegistry;
 /** Test helper — clears the singleton (kept module-private elsewhere). */
 export declare function __resetCapUsageRegistryForTests(): void;

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

@@ -1,4 +1,5 @@
 import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
+import { CapUsageCallRecord } from '../moleculer/cap-usage-registry.js';
 import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
 import { LocalTransportServer } from './local-transport.js';
 import { SocketTrafficSample } from './socket-traffic.js';
@@ -129,6 +130,49 @@ export interface LocalChildRegistryOptions {
      * channel default for every cap call.
      */
     readonly capTimeoutMs?: (capName: string, method: string) => number | undefined;
+    /**
+     * Sink for observed cap calls — the ONE place a forked addon's outbound
+     * `ctx.api` traffic can be recorded in the process that also holds the reader.
+     *
+     * ── Why here, and not in the caller ───────────────────────────────────────
+     * `getCapUsageRegistry()` is a per-process module singleton and the reader
+     * (`nodes.getCapUsageGraph`) runs on hub-main. The only writer used to be
+     * `addon-context-factory.ts`'s `localProviderLink` observer, which runs in
+     * the FORKED RUNNER — so every observation it made was written to an object
+     * hub-main can never read, and it fired only for co-located providers anyway
+     * (`ipcParentLink`, which carries every cross-process call, takes no
+     * observer). `nodes.getCapUsageGraph` therefore returned `[]` in 0.21 s
+     * against a hub running 64 addons and 1019 devices.
+     *
+     * ── Why here, and not in `onUnownedCall` ──────────────────────────────────
+     * Because most inter-addon traffic never gets there. `resolveChildId`
+     * short-circuits a cap owned by a sibling runner straight to `callCap`, and
+     * on the hub every addon IS a sibling runner. Recording in `onUnownedCall`
+     * would have seen `ctx.settings.*` (hub-in-process `settings-store`) and
+     * missed every addon→addon call — a graph with a whole plane silently
+     * missing, which is the defect it was meant to end.
+     *
+     * This handler is strictly upstream of BOTH branches, and it is where
+     * `callerAddonId` is already stamped off the UDS connection the frame
+     * arrived on — a caller identity the child cannot spoof.
+     *
+     * ── What it still cannot see (say it, do not hide it) ─────────────────────
+     *  1. **hub-main → hub-main.** An in-process builtin's `ctx.api` is
+     *     `AddonRegistryService.getBrokerApi()` — ONE lazily-built tRPC client
+     *     shared by every addon, so there is no per-caller identity to record.
+     *     Giving it an observer needs a per-addon client first.
+     *  2. **A runner's co-located calls.** `localProviderLink` answers inside the
+     *     runner and the frame never reaches this socket. Only the `detection` /
+     *     `ml` execution groups have co-located providers at all (D9, D29).
+     *  3. **An agent's own runners.** Their parent is the agent process, whose
+     *     `LocalChildRegistry` writes to the agent's singleton. Aggregating that
+     *     needs a transport hop; `$hub-cap-fwd`'s envelope carries no
+     *     `callerAddonId` today, so an agent-originated call reaching the hub is
+     *     recorded with no caller at all — i.e. not recorded.
+     *
+     * MUST NOT throw; the call site catches anyway (see the record site).
+     */
+    readonly capUsageObserver?: (obs: CapUsageCallRecord) => void;
 }
 /**
  * Parent-side authority for local addon-runners reachable over a
@@ -157,6 +201,8 @@ export declare class LocalChildRegistry {
     private readonly isAddonPinnedCall?;
     /** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
     private readonly capTimeoutMs?;
+    /** See {@link LocalChildRegistryOptions.capUsageObserver}. */
+    private readonly capUsageObserver?;
     /** 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`. */
@@ -274,6 +320,17 @@ export declare class LocalChildRegistry {
      * compete for the same capName.
      */
     resolveChildId(capName: string, deviceId?: number): string | null;
+    /**
+     * Publish one cap-usage observation, if a sink is wired.
+     *
+     * Cost discipline — this is on the hot path (D181: hub-main's event loop is
+     * the cluster's only queue): no sink means one undefined check; with a sink
+     * it is one object literal and one `Date.now()`, and the sink itself is O(1).
+     * Wrapped so a broken observer can never fail the call it observes — the
+     * registry swallows too, and BOTH matter: this catch also covers a sink that
+     * is not the registry.
+     */
+    private recordCapUsage;
     /** First child whose cap manifest contains a descriptor matching `predicate`. */
     private findChildId;
     /** Every child whose cap manifest contains a descriptor matching `predicate`. */