@camstack/system 1.2.154 → 1.2.156

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/addon-runner.js +1 -1
  2. package/dist/addon-runner.mjs +1 -1
  3. package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.js +1 -1
  4. package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.mjs +1 -1
  5. package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.js +1 -1
  6. package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs +1 -1
  7. package/dist/builtins/alerts/alerts.addon.js +1 -1
  8. package/dist/builtins/alerts/alerts.addon.mjs +1 -1
  9. package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.js +1 -1
  10. package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.mjs +1 -1
  11. package/dist/builtins/console-logging/index.js +1 -1
  12. package/dist/builtins/console-logging/index.mjs +1 -1
  13. package/dist/builtins/core-blocks/core-blocks.addon.js +1 -1
  14. package/dist/builtins/core-blocks/core-blocks.addon.mjs +1 -1
  15. package/dist/builtins/device-manager/device-manager.addon.js +2 -2
  16. package/dist/builtins/device-manager/device-manager.addon.mjs +2 -2
  17. package/dist/builtins/doorbell/virtual-doorbell.addon.js +1 -1
  18. package/dist/builtins/doorbell/virtual-doorbell.addon.mjs +1 -1
  19. package/dist/builtins/hub-forwarder/index.js +1 -1
  20. package/dist/builtins/hub-forwarder/index.mjs +1 -1
  21. package/dist/builtins/liveness-monitor/liveness-monitor.addon.js +1 -1
  22. package/dist/builtins/liveness-monitor/liveness-monitor.addon.mjs +1 -1
  23. package/dist/builtins/local-auth/local-auth.addon.js +1 -1
  24. package/dist/builtins/local-auth/local-auth.addon.mjs +1 -1
  25. package/dist/builtins/local-network/local-network.addon.js +1 -1
  26. package/dist/builtins/local-network/local-network.addon.mjs +1 -1
  27. package/dist/builtins/loki-logging/index.js +1 -1
  28. package/dist/builtins/loki-logging/index.mjs +1 -1
  29. package/dist/builtins/native-metrics/native-metrics.addon.js +1 -1
  30. package/dist/builtins/native-metrics/native-metrics.addon.mjs +1 -1
  31. package/dist/builtins/platform-probe/index.js +1 -1
  32. package/dist/builtins/platform-probe/index.mjs +1 -1
  33. package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js +1 -1
  34. package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs +1 -1
  35. package/dist/builtins/snapshot/index.js +1 -1
  36. package/dist/builtins/snapshot/index.mjs +1 -1
  37. package/dist/builtins/sqlite-storage/filesystem-storage.addon.js +1 -1
  38. package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs +1 -1
  39. package/dist/builtins/sqlite-storage/sqlite-settings.addon.js +0 -0
  40. package/dist/builtins/sqlite-storage/sqlite-settings.addon.mjs +0 -0
  41. package/dist/builtins/storage-orchestrator/storage-migration-coordinator.d.ts +101 -1
  42. package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.d.ts +24 -0
  43. package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js +348 -39
  44. package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs +348 -39
  45. package/dist/builtins/storage-orchestrator/storage-orchestrator.service.d.ts +37 -1
  46. package/dist/builtins/system-config/system-config.addon.js +1 -1
  47. package/dist/builtins/system-config/system-config.addon.mjs +1 -1
  48. package/dist/builtins/winston-logging/index.js +1 -1
  49. package/dist/builtins/winston-logging/index.mjs +1 -1
  50. package/dist/{dist-BPlfW-CG.js → dist-CDgIzo82.js} +169 -12
  51. package/dist/{dist-D_NyUV6Y.mjs → dist-LvKus-mT.mjs} +169 -12
  52. package/dist/index.d.ts +2 -0
  53. package/dist/index.js +14 -2
  54. package/dist/index.mjs +3 -3
  55. package/dist/kernel/heap-watch.d.ts +8 -0
  56. package/dist/kernel/socket-plane-report.d.ts +99 -0
  57. package/dist/kernel/transport/frame-codec.d.ts +25 -0
  58. package/dist/kernel/transport/index.d.ts +2 -0
  59. package/dist/kernel/transport/local-child-registry.d.ts +13 -0
  60. package/dist/kernel/transport/local-transport.d.ts +11 -0
  61. package/dist/kernel/transport/socket-channel.d.ts +23 -0
  62. package/dist/kernel/transport/socket-traffic.d.ts +118 -0
  63. package/dist/{manifest-python-deps-BILJm2mI.mjs → manifest-python-deps-CD14Pv0-.mjs} +360 -7
  64. package/dist/{manifest-python-deps-COeSr7el.js → manifest-python-deps-DVODn-qc.js} +431 -6
  65. package/dist/{retired-settings-keys-DBY6ebwV.js → retired-settings-keys-BfAzWvPC.js} +1 -1
  66. package/dist/{retired-settings-keys-Bq1Tb84I.mjs → retired-settings-keys-CV4QVdXj.mjs} +1 -1
  67. package/package.json +1 -1
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  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";
2
- import { $ as isVoidInput, $t as scopeKey, At as DATAPLANE_SECRET_HEADER$1, Bt as asNumber, C as addonSettingsCapability, G as extractNestedAddonId, Gt as expandCapMethods, Ht as createEvent, It as ReadinessRegistry, J as isArrayOutputSchema, Lt as ReadinessTimeoutError, Mt as DEVICE_STATUS_METHOD, Ot as errMsg$1, Qt as resolveCapMount, Ut as emitDownForOwnedCaps, Vt as asString$1, X as isObjectInput, Xt as parseJsonUnknown$1, Y as isCollectionArrayMethod, Yt as parseJsonObject, Zt as readinessKey, _t as scopesAllowDeviceCap, at as looseSchema, ct as objectInputDeclaresAddonId, dt as procedureAuthKey, et as kebabToCamel, f as LOG_LEVEL_RANK, gt as scopesAllowAddon, it as logLevelAtMost, jt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, m as RUNTIME_DEFAULTS, mt as resolveMethodAuth, p as METHOD_ACCESS_MAP, t as ALL_CAPABILITY_DEFINITIONS, tn as EventCategory$1, tt as lifecycleJobSchema, zt as asJsonObject$1 } from "./dist-D_NyUV6Y.mjs";
2
+ import { $ as isVoidInput, $t as scopeKey, At as DATAPLANE_SECRET_HEADER$1, Bt as asNumber, C as addonSettingsCapability, G as extractNestedAddonId, Gt as expandCapMethods, Ht as createEvent, It as ReadinessRegistry, J as isArrayOutputSchema, Lt as ReadinessTimeoutError, Mt as DEVICE_STATUS_METHOD, Ot as errMsg$1, Qt as resolveCapMount, Ut as emitDownForOwnedCaps, Vt as asString$1, X as isObjectInput, Xt as parseJsonUnknown$1, Y as isCollectionArrayMethod, Yt as parseJsonObject, Zt as readinessKey, _t as scopesAllowDeviceCap, at as looseSchema, ct as objectInputDeclaresAddonId, dt as procedureAuthKey, et as kebabToCamel, f as LOG_LEVEL_RANK, gt as scopesAllowAddon, it as logLevelAtMost, jt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, m as RUNTIME_DEFAULTS, mt as resolveMethodAuth, p as METHOD_ACCESS_MAP, t as ALL_CAPABILITY_DEFINITIONS, tn as EventCategory$1, tt as lifecycleJobSchema, zt as asJsonObject$1 } from "./dist-LvKus-mT.mjs";
3
3
  import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
4
4
  import "./builtins/alerts/index.mjs";
5
5
  import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -25,7 +25,7 @@ import "./builtins/system-config/index.mjs";
25
25
  import { WinstonDestination, WinstonLoggingAddon } from "./builtins/winston-logging/index.mjs";
26
26
  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";
27
27
  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";
28
- import { $ as buildNativeCapProxy, $t as RUNNER_HEAP_SNAPSHOT_ENV, A as createParentUnownedCallHandler, At as HUB_MAIN_HEAP_WATCH_LABEL, B as AGENT_CAP_FWD_SERVICE, Bt as createLoopDelayMeter, C as brokerTransportLink, Ct as runNpm, D as HUB_CAP_FWD_ACTION, Dt as HEAP_RECLAIM_TRIGGER_MB, E as localProviderLink, Et as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, F as createUdsLoggerWithControl, Ft as RUNNER_HEAP_WATCH_INTERVAL_MS, G as readMoleculerFanoutMode, Gt as parseRssBudgetMb, H as CapRouteError, Ht as describeRss, I as LocalChildClient, It as RUNNER_RSS_BUDGET_ENV, J as UdsLocalTransportServer, Jt as startHeapWatch, K as createLocalTransport, Kt as reclaimIntervalMs, L as LocalChildRegistry, Lt as ZERO_LOOP_DELAY, M as createUdsEventBus, Mt as HUB_RSS_BUDGET_ENV, N as udsChildLogToWorkerEntry, Nt as RSS_BUDGET_REANNOUNCE_MIN_MS, O as HUB_CAP_FWD_SERVICE, Ot as HEAP_WATCH_INTERVAL_MS, P as createUdsLogger, Pt as RSS_BUDGET_RELEASE_RATIO, Q as encodeFrame, Qt as HEAP_SPACE_REPORT_MIN_MB, R as UDS_NO_ROUTE_PREFIX, Rt as buildHeapSample, S as brokerCallForCap, St as resolveNpmInvocation, T as ipcParentLink, Tt as HEAP_RECLAIM_MIN_INTERVAL_MS, U as classifyCapRoute, Ut as hubMainRssBudget, V as CapRouteResolver, Vt as createV8Reclaimer, W as callWithServiceDiscovery, Wt as nextRssBudgetState, X as localEndpointPath, Xt as strandedMb, Y as SocketChannel, Yt as startRunnerHeapWatch, Z as FrameDecoder, Zt as DECISIVE_HEAP_SPACES, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, an as selectReportedSpaces, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, cn as createEventPlaneReader, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, en as emitHeapDiagnosticReport, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, in as readHeapSpaces, it as mountNativeCapService, j as createUdsEventBridge, jt as HUB_MAIN_RSS_BUDGET_MB, k as createHubCapForwardService, kt as HEAP_WATCH_WARN_RATIO, l as EVENT_TOPIC_PREFIX, ln as diffEventPlane, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, nn as heapSnapshotAuthorised, o as getOrInitReadinessRegistry, on as EVENT_PLANE_TOP_N, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, qt as shouldReclaim, r as createAddonContext, rn as heapSpaceField, s as getOrInitReadinessRegistryForClient, sn as createEventPlaneMeter, st as validateProviderRegistrations, t as installManifestPythonDeps, tn as formatHeapSpaces, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, un as formatEventPlane, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveAddonClass, y as CapUsageRegistry, yt as copyBundledNativeModules, z as AGENT_CAP_FWD_ACTION, zt as createDeferredHeapWatchSink } from "./manifest-python-deps-BILJm2mI.mjs";
28
+ import { $ as buildNativeCapProxy, $t as RUNNER_HEAP_SNAPSHOT_ENV, A as createParentUnownedCallHandler, At as HUB_MAIN_HEAP_WATCH_LABEL, B as AGENT_CAP_FWD_SERVICE, Bt as createLoopDelayMeter, C as brokerTransportLink, Ct as runNpm, D as HUB_CAP_FWD_ACTION, Dt as HEAP_RECLAIM_TRIGGER_MB, E as localProviderLink, Et as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, F as createUdsLoggerWithControl, Ft as RUNNER_HEAP_WATCH_INTERVAL_MS, G as readMoleculerFanoutMode, Gt as parseRssBudgetMb, H as CapRouteError, Ht as describeRss, I as LocalChildClient, It as RUNNER_RSS_BUDGET_ENV, J as UdsLocalTransportServer, Jt as startHeapWatch, K as createLocalTransport, Kt as reclaimIntervalMs, L as LocalChildRegistry, Lt as ZERO_LOOP_DELAY, M as createUdsEventBus, Mt as HUB_RSS_BUDGET_ENV, N as udsChildLogToWorkerEntry, Nt as RSS_BUDGET_REANNOUNCE_MIN_MS, O as HUB_CAP_FWD_SERVICE, Ot as HEAP_WATCH_INTERVAL_MS, P as createUdsLogger, Pt as RSS_BUDGET_RELEASE_RATIO, Q as encodeFrame, Qt as HEAP_SPACE_REPORT_MIN_MB, R as UDS_NO_ROUTE_PREFIX, Rt as buildHeapSample, S as brokerCallForCap, Sn as formatEventPlane, St as resolveNpmInvocation, T as ipcParentLink, Tt as HEAP_RECLAIM_MIN_INTERVAL_MS, U as classifyCapRoute, Ut as hubMainRssBudget, V as CapRouteResolver, Vt as createV8Reclaimer, W as callWithServiceDiscovery, Wt as nextRssBudgetState, X as localEndpointPath, Xt as strandedMb, Y as SocketChannel, Yt as startRunnerHeapWatch, Z as FrameDecoder, Zt as DECISIVE_HEAP_SPACES, _ as createKernelHwAccel, _n as socketDirectionMessages, _t as CapabilityHandle, a as getWorkerDeviceRegistry, an as selectReportedSpaces, b as __resetCapUsageRegistryForTests, bn as createEventPlaneReader, bt as installManifestNativeDeps, c as setHubConnected, cn as createSocketPlaneMeter, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dn as formatSocketPlane, dt as capBareAction, en as emitHeapDiagnosticReport, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, fn as EMPTY_SOCKET_DIRECTION, ft as capServiceName, g as AddonDepsManager, gn as socketDirectionBytes, gt as DeviceRegistry, h as subscribePassthrough, hn as sampleSocketDirection, ht as serializeTypedArrays, i as createUdsAddonContext, in as readHeapSpaces, it as mountNativeCapService, j as createUdsEventBridge, jt as HUB_MAIN_RSS_BUDGET_MB, k as createHubCapForwardService, kt as HEAP_WATCH_WARN_RATIO, l as EVENT_TOPIC_PREFIX, ln as createSocketPlaneReader, lt as capActionName, m as setNodeEventInterest, mn as recordSocketFrame, mt as deserializeTypedArrays, n as adaptBrokerToCluster, nn as heapSnapshotAuthorised, o as getOrInitReadinessRegistry, on as EMPTY_SOCKET_PLANE_BASELINE, ot as createAddonService, p as registerEventBusService, pn as createSocketDirectionCounters, pt as parseCapAction, q as UdsLocalTransportClient, qt as shouldReclaim, r as createAddonContext, rn as heapSpaceField, s as getOrInitReadinessRegistryForClient, sn as SOCKET_PLANE_TOP_N, st as validateProviderRegistrations, t as installManifestPythonDeps, tn as formatHeapSpaces, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, un as diffSocketPlane, ut as capActionSuffix, v as resolveHwAccel, vn as EVENT_PLANE_TOP_N, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xn as diffEventPlane, xt as resolveAddonClass, y as CapUsageRegistry, yn as createEventPlaneMeter, yt as copyBundledNativeModules, z as AGENT_CAP_FWD_ACTION, zt as createDeferredHeapWatchSink } from "./manifest-python-deps-CD14Pv0-.mjs";
29
29
  import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BWmQ5i-o.mjs";
30
30
  import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
31
31
  import { z } from "zod";
@@ -95283,4 +95283,4 @@ var LifecycleJobEngine = class {
95283
95283
  }
95284
95284
  };
95285
95285
  //#endregion
95286
- 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, 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, 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, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, describeRss, detectWorkspacePackagesDir, diffEventPlane, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, emitHeapDiagnosticReport, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, evaluateExistingCert, expandCapMethods, fetchJson, findInPath, formatEventPlane, formatHeapSpaces, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getLoggingGate, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, heapSnapshotAuthorised, heapSpaceField, hubMainRssBudget, installManifestNativeDeps, installManifestPythonDeps, 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, registerEventBusService, registerLanHttpHandler, reissueTlsLeaf, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runHubAddonBoot, runNpm, scheduleSelfRestart, scopeKey, scopesAllowAddon, scopesAllowDeviceCap, selectAddonResidue, selectReportedSpaces, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, startHeapWatch, startRunnerHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, validateUploadedTls, waitUntilReady, writeExtraSans, writePendingRestart, writeTlsMode };
95286
+ 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, 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 };
@@ -1,4 +1,5 @@
1
1
  import { EventPlaneReader } from './event-plane-report.js';
2
+ import { SocketPlaneReader } from './socket-plane-report.js';
2
3
  import { HeapSpaceReader } from './heap-spaces.js';
3
4
  /**
4
5
  * What hub-main calls itself in a `[mem]` line.
@@ -598,6 +599,13 @@ export interface HeapWatchProbes {
598
599
  * printing nothing. Only hub-main and an agent's main pass one.
599
600
  */
600
601
  readonly eventPlane?: EventPlaneReader;
602
+ /**
603
+ * Per-peer UDS socket traffic, split by frame kind. No default, for the same
604
+ * reason as {@link eventPlane}: a forked runner has no child registry, and the
605
+ * plane it does have (its single channel to its parent) is already reported
606
+ * from the parent's side. Only hub-main and an agent's main pass one.
607
+ */
608
+ readonly socketPlane?: SocketPlaneReader;
601
609
  }
602
610
  /**
603
611
  * Start the heartbeat. Returns a stop function.
@@ -0,0 +1,99 @@
1
+ import { SocketDirectionSample, SocketTrafficSample } from './transport/socket-traffic.js';
2
+ /** One peer's cumulative traffic, as the channel keeps it. */
3
+ export interface SocketPeerSample {
4
+ readonly peerId: string;
5
+ readonly tx: SocketDirectionSample;
6
+ readonly rx: SocketDirectionSample;
7
+ }
8
+ /** What `LocalChildRegistry` exposes, structurally — the kernel's heartbeat
9
+ * must not depend on the transport layer's class. */
10
+ export interface SocketPlaneRegistryChild {
11
+ readonly childId: string;
12
+ }
13
+ export interface SocketPlaneRegistry {
14
+ readonly listChildren: () => readonly SocketPlaneRegistryChild[];
15
+ readonly getChildSocketTraffic: (childId: string) => SocketTrafficSample | null;
16
+ }
17
+ /** One cumulative reading of every measured peer. */
18
+ export interface SocketPlaneCounters {
19
+ readonly peers: readonly SocketPeerSample[];
20
+ /** Connected children, INCLUDING any whose channel keeps no counters. */
21
+ readonly peersConnected: number;
22
+ }
23
+ /** `undefined` = this process has no local socket plane to report (every forked
24
+ * runner, and hub-main before the registry exists). */
25
+ export type SocketPlaneReader = () => SocketPlaneCounters | undefined;
26
+ /** Where a reader gets its registry. Late-bound, because the heartbeat starts
27
+ * before the registry exists. */
28
+ export interface SocketPlaneSources {
29
+ readonly registry: () => SocketPlaneRegistry | null;
30
+ }
31
+ /**
32
+ * Build a reader over the child registry.
33
+ *
34
+ * Returns `undefined` until the registry exists — the heartbeat starts as the
35
+ * FIRST statement of `bootstrap()` and `LocalChildRegistry` is built hundreds
36
+ * of lines later. Printing zeros in that window would report a silent plane
37
+ * where there is no plane at all.
38
+ *
39
+ * Wrapped: a registry mid-teardown may throw, and a diagnostic that can crash
40
+ * the process it watches is worse than none.
41
+ */
42
+ export declare function createSocketPlaneReader(sources: SocketPlaneSources): SocketPlaneReader;
43
+ /**
44
+ * How many peers get named on the line.
45
+ *
46
+ * Five, matching `EVENT_PLANE_TOP_N` for the same reason: the measured
47
+ * distribution is not flat — one peer accounted for 78–82 % of outbound bytes
48
+ * and the runner-up for ~6 % — so five names the dominant peer, its challenger
49
+ * and enough of the tail to see the shape change. Naming all ~38 would put a
50
+ * kilobyte-long line in the hub's shared log every minute, which is how a log
51
+ * stops being read.
52
+ */
53
+ export declare const SOCKET_PLANE_TOP_N = 5;
54
+ /** One peer's traffic over the window since the previous read. */
55
+ export interface SocketPeerDelta {
56
+ readonly peerId: string;
57
+ readonly tx: SocketDirectionSample;
58
+ readonly rx: SocketDirectionSample;
59
+ }
60
+ /** The whole plane over one heartbeat window. */
61
+ export interface SocketPlaneWindow {
62
+ readonly peersConnected: number;
63
+ /** Peers that reported counters. Below `peersConnected` ⇒ unmeasured channels. */
64
+ readonly peersMeasured: number;
65
+ /** Summed over every measured peer. */
66
+ readonly tx: SocketDirectionSample;
67
+ readonly rx: SocketDirectionSample;
68
+ /** Busiest first (tx+rx messages), at most {@link SOCKET_PLANE_TOP_N}. */
69
+ readonly top: readonly SocketPeerDelta[];
70
+ }
71
+ /** Previous cumulative reading, kept between lines. */
72
+ export interface SocketPlaneBaseline {
73
+ readonly peers: ReadonlyMap<string, SocketPeerSample>;
74
+ }
75
+ /** A process that has never read the plane. */
76
+ export declare const EMPTY_SOCKET_PLANE_BASELINE: SocketPlaneBaseline;
77
+ /** Subtract the previous cumulative reading from the current one. */
78
+ export declare function diffSocketPlane(baseline: SocketPlaneBaseline, current: SocketPlaneCounters, topN?: number): SocketPlaneWindow;
79
+ /** Reads the delta since the PREVIOUS read. Same contract as the loop meter. */
80
+ export interface SocketPlaneMeter {
81
+ readonly read: () => SocketPlaneWindow | undefined;
82
+ }
83
+ export declare function createSocketPlaneMeter(reader: SocketPlaneReader, topN?: number): SocketPlaneMeter;
84
+ /**
85
+ * The suffix appended to a `[mem]` line — leading space included, empty when
86
+ * this process has no local socket plane.
87
+ *
88
+ * Only the processes that OWN a child registry have one (hub-main, and an
89
+ * agent's main), so these fields never appear on the ~38 runner lines that
90
+ * share the same log stream. On the ones that do, every field is printed on
91
+ * every line including at zero — `socketPeers` because measured-below-connected
92
+ * is the only way to see an unmeasured channel, and the per-kind splits because
93
+ * "the plane went quiet for a minute" is a reading.
94
+ *
95
+ * `socketTop` is the one conditional field — a ranked list of nothing is noise —
96
+ * and it is a single comma-separated value so the field COUNT does not change
97
+ * from line to line.
98
+ */
99
+ export declare function formatSocketPlane(window: SocketPlaneWindow | undefined): string;
@@ -29,6 +29,31 @@ export declare class FrameDecoder {
29
29
  private chunks;
30
30
  /** Sum of `chunks[i].byteLength` — tracked so length checks cost nothing. */
31
31
  private buffered;
32
+ /** Backing store for {@link lastFrameBytes}; see that getter. */
33
+ private readonly sizes;
34
+ /**
35
+ * On-the-wire byte length (4-byte prefix included) of each frame returned by
36
+ * the most recent {@link push}, index-aligned with the returned array.
37
+ *
38
+ * It exists because the frames come back DECODED, and a decoded value has no
39
+ * memory of how many bytes it cost — so a caller counting received bytes per
40
+ * message kind (`SocketChannel`, feeding the `[mem]` line's per-peer socket
41
+ * attribution) could otherwise only charge a whole `data` chunk, which may
42
+ * hold several frames of different kinds, or half of one.
43
+ *
44
+ * **Only the first `frames.length` entries are meaningful**, and the array is
45
+ * never truncated. That is deliberate and it was measured on Node 24.17:
46
+ * `sizes.length = 0` + `push` costs **35.1–35.9 ns** per call — V8 shrinks the
47
+ * backing store and the next call re-grows it — which is 3 % of
48
+ * `FrameDecoder.push` itself and 15× the counter it feeds. Writing in place
49
+ * costs **0.06–0.13 ns**. On a path that runs ~22 000 times a second, an
50
+ * instrument may not be the most expensive thing on the line it measures.
51
+ *
52
+ * Read it immediately after the `push` that produced it — it is a window onto
53
+ * the decoder, not a value. Safe because `push` is only ever driven by a
54
+ * socket `data` event, which Node never delivers re-entrantly.
55
+ */
56
+ get lastFrameBytes(): readonly number[];
32
57
  push(chunk: Buffer): unknown[];
33
58
  /**
34
59
  * Read the frame length without consuming it. The prefix itself can land
@@ -1,5 +1,7 @@
1
1
  export type { Frame, RequestHandler, EventHandler, LocalChannel, LocalTransportServer, LocalTransportClient, LocalTransportFactory, } from './local-transport.js';
2
2
  export { encodeFrame, FrameDecoder } from './frame-codec.js';
3
+ export type { SocketDirectionCounters, SocketDirectionSample, SocketMessageKind, SocketTrafficSample, } from './socket-traffic.js';
4
+ export { createSocketDirectionCounters, EMPTY_SOCKET_DIRECTION, recordSocketFrame, sampleSocketDirection, socketDirectionBytes, socketDirectionMessages, } from './socket-traffic.js';
3
5
  export { localEndpointPath } from './local-endpoint-path.js';
4
6
  export { SocketChannel } from './socket-channel.js';
5
7
  export { UdsLocalTransportServer, UdsLocalTransportClient } from './uds-local-transport.js';
@@ -1,6 +1,7 @@
1
1
  import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
2
2
  import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
3
3
  import { LocalTransportServer } from './local-transport.js';
4
+ import { SocketTrafficSample } from './socket-traffic.js';
4
5
  /**
5
6
  * Fan-out mode for parent→child event delivery, from the
6
7
  * `CAMSTACK_UDS_EVENT_FANOUT` env (read once at registry construction):
@@ -183,6 +184,18 @@ export declare class LocalChildRegistry {
183
184
  * surface (shadow burn-in + operator debug).
184
185
  */
185
186
  getChildEventStats(childId: string): ChildEventStats | null;
187
+ /**
188
+ * This child's socket traffic — bytes and messages, both directions, split by
189
+ * frame kind — or `null` when the child is gone or its channel keeps no
190
+ * counters (an in-process or test transport).
191
+ *
192
+ * The event counters above cover ONE kind of frame and, once surfaced on
193
+ * 2026-08-29, accounted for 4% of hub-main's ~44 000 socket syscalls/s. This
194
+ * is the same question asked of every frame the channel moves, and it is the
195
+ * only per-peer attribution that exists: `/proc` reports one `rchar`/`wchar`
196
+ * pair for the whole process and has no per-socket breakdown.
197
+ */
198
+ getChildSocketTraffic(childId: string): SocketTrafficSample | null;
186
199
  /**
187
200
  * The regime the counters above were produced under, read once from
188
201
  * `CAMSTACK_UDS_EVENT_FANOUT` at construction.
@@ -1,3 +1,4 @@
1
+ import { SocketTrafficSample } from './socket-traffic.js';
1
2
  /** Wire frame exchanged over a local channel. */
2
3
  export type Frame = {
3
4
  readonly k: 'req';
@@ -37,6 +38,16 @@ export interface LocalChannel {
37
38
  onEvent(handler: EventHandler): void;
38
39
  onClose(handler: () => void): void;
39
40
  close(): void;
41
+ /**
42
+ * Cumulative byte and message counters for this channel, split by frame
43
+ * kind, or absent when the implementation keeps none.
44
+ *
45
+ * OPTIONAL because the counters are a property of a real socket, not of the
46
+ * channel contract: the in-process and test transports move no bytes, and a
47
+ * required member would make every double invent numbers. A reader that
48
+ * finds it absent reports the peer as unmeasured rather than as silent.
49
+ */
50
+ readTraffic?(): SocketTrafficSample;
40
51
  }
41
52
  /** Parent side: listens and hands a channel per accepted child connection. */
42
53
  export interface LocalTransportServer {
@@ -1,5 +1,6 @@
1
1
  import { Socket } from 'node:net';
2
2
  import { LocalChannel, RequestHandler, EventHandler } from './local-transport.js';
3
+ import { SocketTrafficSample } from './socket-traffic.js';
3
4
  /**
4
5
  * Default bound on one UDS request, when the caller names none.
5
6
  *
@@ -26,6 +27,11 @@ export declare class SocketChannel implements LocalChannel {
26
27
  private closeHandler;
27
28
  private closed;
28
29
  private closeFired;
30
+ /** Frames written to the peer, cumulative, split by kind. See
31
+ * {@link readTraffic} and `transport/socket-traffic.ts`. */
32
+ private readonly txCounters;
33
+ /** Frames read from the peer, cumulative, split by kind. */
34
+ private readonly rxCounters;
29
35
  constructor(socket: Socket);
30
36
  /**
31
37
  * Send a request and wait for the peer's response.
@@ -47,8 +53,25 @@ export declare class SocketChannel implements LocalChannel {
47
53
  /** Replace the close handler. Only one handler is active at a time. */
48
54
  onClose(handler: () => void): void;
49
55
  close(): void;
56
+ /**
57
+ * This channel's cumulative traffic, both directions, split by frame kind.
58
+ *
59
+ * Cumulative for the life of the channel: the reporting layer subtracts the
60
+ * previous reading, because the question is a RATE ("which peer receives the
61
+ * 22 500 writes/s") and not a total since boot.
62
+ */
63
+ readTraffic(): SocketTrafficSample;
50
64
  private send;
51
65
  private onData;
66
+ /**
67
+ * `wireBytes` is the frame's on-the-wire length, counted HERE rather than in
68
+ * `onData` on purpose: a peer that sends a frame this decoder can parse but
69
+ * whose shape is not a `Frame` throws on `frame.k`, and inside this async
70
+ * method that stays the rejected promise it has always been. Reading `.k`
71
+ * one frame earlier, synchronously in the socket's `data` handler, would
72
+ * turn the same malformed frame into an uncaught exception on the transport
73
+ * — a diagnostic that can crash the process it watches.
74
+ */
52
75
  private handleFrame;
53
76
  private handleClose;
54
77
  }
@@ -0,0 +1,118 @@
1
+ /**
2
+ * socket-traffic — per-channel byte and message counters, split by frame kind.
3
+ *
4
+ * ## The question this exists to answer
5
+ *
6
+ * hub-main runs ~22 000 socket reads/s and ~22 500 writes/s at a **0.33 KB
7
+ * mean** (measured 2026-08-29 from `/proc/<pid>/io` with every regular-file
8
+ * descriptor's offset subtracted, so the bytes are socket bytes and not file
9
+ * bytes). That is ~44 000 syscalls/s on the process that mediates every
10
+ * cross-runner call, and **nothing could attribute a single one of them**. The
11
+ * event fan-out plane WAS measurable — `LocalChildRegistry` has counted
12
+ * `sent`/`suppressed` per child since the gate was built — and once surfaced it
13
+ * accounted for **4 %**. The other 96 % had no instrument at all.
14
+ *
15
+ * `/proc` cannot close this: it reports one `rchar`/`wchar` pair for the whole
16
+ * process, and per-socket counters do not exist there. The correlation that was
17
+ * available — 78–82 % of hub-main's outbound bytes moving with
18
+ * `hub/pipeline-analytics` — is derived from that runner's own `rchar`, which
19
+ * also counts page-cache file reads on a runner that owns a vector store. It is
20
+ * a correlation and it has never been an attribution.
21
+ *
22
+ * So the counters have to sit where the frames are: in the channel, on both
23
+ * sides, split by kind.
24
+ *
25
+ * ## Why split by KIND, and why these three
26
+ *
27
+ * A total answers nothing that was not already known. The three wire kinds are
28
+ * three different mechanisms with three different fixes:
29
+ *
30
+ * - `req` — a cap call this process is making or serving. Scales with work.
31
+ * - `res` — its answer. Where a payload can be large (a msgpack `Uint8Array`
32
+ * of GOP bytes is a `res`), so this is the field the "message-RATE, not
33
+ * media" conclusion is falsified against: if `res` bytes dominate at a large
34
+ * mean, the traffic is media and D9/D18 must be re-opened.
35
+ * - `evt` — one-way fan-out. Scales with the number of runners rather than
36
+ * with anything an operator asked for; an IDLE addon still reads 82
37
+ * messages/s of it.
38
+ *
39
+ * Bytes AND messages, per kind, because the mean is the whole argument: 0.33 KB
40
+ * across 22 000 reads/s is a rate problem, and the same bytes in 300 messages
41
+ * would be a media problem.
42
+ *
43
+ * ## Why these objects are MUTATED
44
+ *
45
+ * A deliberate, measured exception to the immutability default. The write
46
+ * happens on a path that runs ~44 000 times a second; allocating a replacement
47
+ * object per frame would make the instrument the largest allocator it is trying
48
+ * to measure. The counters are therefore plain mutable numbers, written only by
49
+ * {@link recordSocketFrame} and read only through {@link sampleSocketDirection},
50
+ * which copies. Same discipline `LocalChildRegistry` already applies to
51
+ * `childEventStats`.
52
+ *
53
+ * Cumulative for the life of the channel. A cumulative number on a heartbeat
54
+ * answers "how much since boot", which nobody asked; the reporting layer
55
+ * (`kernel/socket-plane-report.ts`) subtracts the previous reading and reports
56
+ * the window, exactly as the fan-out counters and the loop-delay histogram do.
57
+ */
58
+ /** The three wire kinds of {@link import('./local-transport.js').Frame}. */
59
+ export type SocketMessageKind = 'req' | 'res' | 'evt';
60
+ /**
61
+ * One direction of one channel, cumulative. Mutable by design — see the module
62
+ * docblock; nothing outside {@link recordSocketFrame} may write these.
63
+ *
64
+ * `bytes` is the ON-THE-WIRE size: the 4-byte length prefix plus the MsgPack
65
+ * body, i.e. exactly what `socket.write` was handed and exactly what the peer's
66
+ * `rchar` will have counted. Anything else would not reconcile against `/proc`,
67
+ * and reconciling against `/proc` is the only reason to trust either number.
68
+ */
69
+ export interface SocketDirectionCounters {
70
+ reqMessages: number;
71
+ reqBytes: number;
72
+ resMessages: number;
73
+ resBytes: number;
74
+ evtMessages: number;
75
+ evtBytes: number;
76
+ }
77
+ /** An immutable reading of {@link SocketDirectionCounters}. */
78
+ export interface SocketDirectionSample {
79
+ readonly reqMessages: number;
80
+ readonly reqBytes: number;
81
+ readonly resMessages: number;
82
+ readonly resBytes: number;
83
+ readonly evtMessages: number;
84
+ readonly evtBytes: number;
85
+ }
86
+ /** Both directions of one channel. */
87
+ export interface SocketTrafficSample {
88
+ /** Frames this process WROTE to the peer. */
89
+ readonly tx: SocketDirectionSample;
90
+ /** Frames this process READ from the peer. */
91
+ readonly rx: SocketDirectionSample;
92
+ }
93
+ export declare function createSocketDirectionCounters(): SocketDirectionCounters;
94
+ /**
95
+ * The hot-path write. Two additions and at most two string comparisons against
96
+ * interned literals — no allocation, no branch on anything the caller has to
97
+ * compute, and nothing that can throw.
98
+ *
99
+ * Measured on Node 24.17, 20 M iterations, three runs: **2.37–2.41 ns/call**
100
+ * against an empty loop. Its neighbours on the same path, measured in the same
101
+ * run: `encodeFrame` on a 0.33 KB body 1948–1975 ns, `FrameDecoder.push`
102
+ * 1156–1166 ns, `process.memoryUsage()` 920–945 ns. The counter is **0.12 % of
103
+ * `encodeFrame`** — and `encodeFrame` is followed by a syscall.
104
+ *
105
+ * Together with the decoder's per-frame size write (0.06–0.13 ns, see
106
+ * `frame-codec.ts`) the whole instrument adds **~2.5 ns per frame**: at 44 000
107
+ * frames/s that is 107–111 µs/s, i.e. **0.011 % of one core**. An instrument
108
+ * that changes what it measures is not an instrument, and this one cannot.
109
+ */
110
+ export declare function recordSocketFrame(counters: SocketDirectionCounters, kind: SocketMessageKind, bytes: number): void;
111
+ /** Copy out. Called once per heartbeat line, never on the frame path. */
112
+ export declare function sampleSocketDirection(counters: SocketDirectionCounters): SocketDirectionSample;
113
+ /** A direction that has seen nothing. */
114
+ export declare const EMPTY_SOCKET_DIRECTION: SocketDirectionSample;
115
+ /** Total messages across the three kinds. */
116
+ export declare function socketDirectionMessages(sample: SocketDirectionSample): number;
117
+ /** Total on-the-wire bytes across the three kinds. */
118
+ export declare function socketDirectionBytes(sample: SocketDirectionSample): number;