@camstack/system 1.2.144 → 1.2.146

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-D3lqzV40.js");
+const require_dist = require("./dist-BVU5JADq.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-u8QCJCFE.js");
-const require_manifest_python_deps = require("./manifest-python-deps-B_mCU6gz.js");
+const require_manifest_python_deps = require("./manifest-python-deps-CktMcXzS.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");
@@ -94270,7 +94270,8 @@ async function getPidStats$1(pids) {
 }
 var EMPTY_HEAP_DECLARATION = {
 	profile: void 0,
-	maxOldSpaceMb: void 0
+	maxOldSpaceMb: void 0,
+	rssBudgetMb: void 0
 };
 /**
 * Resolve the declared heap profile + old-space ceiling for one addon by reading its package.json
@@ -94291,10 +94292,12 @@ function readAddonHeapDeclaration(spec) {
 		const parsed = JSON.parse(raw);
 		const profile = extractHeapProfile(parsed, spec.addonId);
 		const maxOldSpaceMb = extractMaxOldSpaceMb(parsed, spec.addonId);
-		if (profile !== void 0 || maxOldSpaceMb !== void 0) {
+		const rssBudgetMb = extractRssBudgetMb(parsed, spec.addonId);
+		if (profile !== void 0 || maxOldSpaceMb !== void 0 || rssBudgetMb !== void 0) {
 			declaration = {
 				profile,
-				maxOldSpaceMb
+				maxOldSpaceMb,
+				rssBudgetMb
 			};
 			break;
 		}
@@ -94324,6 +94327,15 @@ function extractMaxOldSpaceMb(parsed, addonId) {
 	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.maxOldSpaceMb;
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : void 0;
 }
+/**
+* `execution.rssBudgetMb` for one addon. Only a POSITIVE finite number is a budget: unlike
+* `maxOldSpaceMb`, `0` here is not an escape hatch that lifts a cap, it is an absent budget —
+* and an absent budget is reported as "unwatched", never rounded into a default.
+*/
+function extractRssBudgetMb(parsed, addonId) {
+	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.rssBudgetMb;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : void 0;
+}
 function readManifestAddons(parsed) {
 	if (typeof parsed !== "object" || parsed === null) return [];
 	const camstack = parsed.camstack;
@@ -94349,10 +94361,20 @@ function isHeavyRunner(addons) {
 * one-off burst becomes the runner's permanent RSS.
 *
 * Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
-* there after the deferred archive walk (99,809 segments in 84s), while the `RecordingIndex` it
-* actually retains is arithmetically ~21 MB (a `SegmentRow` is 5 numbers + 3 strings ≈ 207 B). The
-* same addon on two agent nodes carrying the same code and a smaller archive sits at **58 MB**.
-* The ~2 GB is walk garbage held as high-water in a heap that had no reason to collect it.
+* there. The same addon on two agent nodes carrying the same code and a smaller archive sits at
+* **58 MB**.
+*
+* ⚠ This paragraph used to attribute that ~2 GB to "walk garbage" from the deferred archive walk,
+* and to argue from a ~21 MB `RecordingIndex`. Both were wrong, and the error cost a session on
+* 2026-08-27. The deferred walk had NO CALLER and never ran (it has since been deleted). And the
+* index is not 21 MB: a 2026-08-27 profile of the live recorder read `heapUsed = 1606 MB` against
+* `external = 8 MB`, with an `smaps` census putting 1510 MB in V8's 256 KB page ranges against
+* 54 MB of native heap — LIVE JavaScript retainers, not high-water garbage. The retained set is
+* ~7.1 M `SegmentRow`s plus their path strings and Map entries (13 cameras x 2 profiles x 8 640
+* segments/day x ~30 days), reseeded at boot by `SegmentHourLedger.hydrateIndex`.
+*
+* The lesson for anyone sizing this flag: a heap number needs a RETAINER, and "garbage the GC has
+* no reason to collect" is the explanation to reach for last, not first.
 *
 * ## Why 1024
 *
@@ -94369,8 +94391,7 @@ function isHeavyRunner(addons) {
 *
 * A runner whose working set genuinely does not fit declares its own number in its manifest
 * (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
-* `recorder` (3072 MB; peak 2341 MB heapTotal during the deferred archive walk) is the one
-* shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
+* `recorder` (3072 MB; peak 2341 MB heapTotal) is the one shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
 * `arrayBuffers` (47 RTP rings), which this flag does not bound and never will — its actual old
 * space peaks at 224 MB. Size the declaration from `heapTotal` in the `[mem]` heartbeat, never
 * from RSS.
@@ -94399,6 +94420,22 @@ function runnerMaxOldSpaceMb(addons, heavy) {
 	return Math.max(...declared);
 }
 /**
+* The runner's declared RSS budget in MB, or `undefined` when NOBODY declared one.
+*
+* Same rule as the old-space ceiling, for the same reason (D2/D29): the runner takes the MAXIMUM
+* any co-located addon declares, because a runner is respawned as a whole and co-location must
+* never silence the hungriest member. It would be strictly worse here than for a heap ceiling —
+* an under-sized budget does not kill anything, it just cries wolf, and a watchdog that cries
+* wolf is a watchdog that gets muted.
+*
+* `undefined` propagates as an ABSENT env var, and the child then announces itself unwatched.
+* There is deliberately no class default: see `AddonExecution.rssBudgetMb`.
+*/
+function runnerRssBudgetMb(addons) {
+	const declared = addons.map((a) => readAddonHeapDeclaration(a).rssBudgetMb).filter((mb) => mb !== void 0);
+	return declared.length === 0 ? void 0 : Math.max(...declared);
+}
+/**
 * Per-placement V8 heap flags (Block D). LIGHT runners cap their young generation
 * (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — and
 * keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
@@ -94496,6 +94533,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 		const nodeId = buildNodeId(runnerId);
 		const runnerPath = node_path.resolve(__dirname, "addon-runner.js");
 		const heavy = isHeavyRunner(addons);
+		const rssBudgetMb = runnerRssBudgetMb(addons);
 		const childEnv = {
 			...process.env,
 			CAMSTACK_RUNNER_ID: runnerId,
@@ -94509,6 +94547,8 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 			...applyRunnerNativeAllocator(process.env),
 			...env
 		};
+		if (rssBudgetMb === void 0) delete childEnv[require_manifest_python_deps.RUNNER_RSS_BUDGET_ENV];
+		else childEnv[require_manifest_python_deps.RUNNER_RSS_BUDGET_ENV] = String(rssBudgetMb);
 		const heapFlags = runnerHeapFlags(addons);
 		capturedBroker?.logger.info(`[${runnerId}] heap profile: ${heavy ? "heavy" : "light"} flags=[${heapFlags.join(" ")}] arenas=${childEnv["MALLOC_ARENA_MAX"] ?? "glibc-default"} vips=${childEnv["VIPS_CONCURRENCY"] ?? "sharp-default"}`);
 		const child = spawnFn(process.execPath, [...heapFlags, runnerPath], {
@@ -95308,6 +95348,8 @@ exports.HEAP_WATCH_INTERVAL_MS = require_manifest_python_deps.HEAP_WATCH_INTERVA
 exports.HEAP_WATCH_WARN_RATIO = require_manifest_python_deps.HEAP_WATCH_WARN_RATIO;
 exports.HUB_CAP_FWD_ACTION = require_manifest_python_deps.HUB_CAP_FWD_ACTION;
 exports.HUB_CAP_FWD_SERVICE = require_manifest_python_deps.HUB_CAP_FWD_SERVICE;
+exports.HUB_MAIN_RSS_BUDGET_MB = require_manifest_python_deps.HUB_MAIN_RSS_BUDGET_MB;
+exports.HUB_RSS_BUDGET_ENV = require_manifest_python_deps.HUB_RSS_BUDGET_ENV;
 exports.HubForwarderAddon = require_builtins_hub_forwarder_index.HubForwarderAddon$1;
 exports.HubForwarderDestination = require_builtins_hub_forwarder_index.HubForwarderDestination$1;
 exports.HubLogForwarder = HubLogForwarder;
@@ -95347,7 +95389,10 @@ exports.PipelineValidator = PipelineValidator;
 exports.PythonEnvManager = PythonEnvManager;
 exports.QUARANTINE_DIRNAME = QUARANTINE_DIRNAME;
 exports.RESTART_MARKER_FILE = RESTART_MARKER_FILE;
+exports.RSS_BUDGET_REANNOUNCE_MIN_MS = require_manifest_python_deps.RSS_BUDGET_REANNOUNCE_MIN_MS;
+exports.RSS_BUDGET_RELEASE_RATIO = require_manifest_python_deps.RSS_BUDGET_RELEASE_RATIO;
 exports.RUNNER_HEAP_WATCH_INTERVAL_MS = require_manifest_python_deps.RUNNER_HEAP_WATCH_INTERVAL_MS;
+exports.RUNNER_RSS_BUDGET_ENV = require_manifest_python_deps.RUNNER_RSS_BUDGET_ENV;
 exports.RUNTIME_DEFAULTS = require_dist.RUNTIME_DEFAULTS;
 exports.ReadinessRegistry = require_dist.ReadinessRegistry;
 exports.ReadinessTimeoutError = require_dist.ReadinessTimeoutError;
@@ -95444,6 +95489,7 @@ exports.createV8Reclaimer = require_manifest_python_deps.createV8Reclaimer;
 exports.deleteModelFromDisk = require_file_data_plane.deleteModelFromDisk;
 exports.deriveAgentListenPort = deriveAgentListenPort;
 exports.describeProviderKindDrift = describeProviderKindDrift;
+exports.describeRss = require_manifest_python_deps.describeRss;
 exports.detectWorkspacePackagesDir = detectWorkspacePackagesDir;
 Object.defineProperty(exports, "downloadBinary", {
 	enumerable: true,
@@ -95520,6 +95566,7 @@ exports.getSinglePidStats = require_resource_monitor.getSinglePidStats;
 exports.getWorkerDeviceRegistry = require_manifest_python_deps.getWorkerDeviceRegistry;
 exports.hasDotNode = hasDotNode;
 exports.hashClusterSecret = hashClusterSecret;
+exports.hubMainRssBudget = require_manifest_python_deps.hubMainRssBudget;
 exports.installManifestNativeDeps = require_manifest_python_deps.installManifestNativeDeps;
 exports.installManifestPythonDeps = require_manifest_python_deps.installManifestPythonDeps;
 exports.installPackageFromNpm = installPackageFromNpm;
@@ -95548,8 +95595,10 @@ exports.loadTlsCert = require_tls$1.loadTlsCert;
 exports.localEndpointPath = require_manifest_python_deps.localEndpointPath;
 exports.localProviderLink = require_manifest_python_deps.localProviderLink;
 exports.mountNativeCapService = require_manifest_python_deps.mountNativeCapService;
+exports.nextRssBudgetState = require_manifest_python_deps.nextRssBudgetState;
 exports.parseCapAction = require_manifest_python_deps.parseCapAction;
 exports.parseRangeHeader = require_file_data_plane.parseRangeHeader;
+exports.parseRssBudgetMb = require_manifest_python_deps.parseRssBudgetMb;
 exports.parseTokenizedUrl = require_file_data_plane.parseTokenizedUrl;
 exports.partitionIsolatedBuiltinIds = partitionIsolatedBuiltinIds;
 exports.proxyToUpstream = proxyToUpstream;

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 kebabToCamel, Bt as emitDownForOwnedCaps, C as addonSettingsCapability, Dt as DATAPLANE_SECRET_HEADER$1, G as extractNestedAddonId, Ht as expandCapMethods, It as asJsonObject$1, J as isCollectionArrayMethod, Jt as readinessKey, Kt as parseJsonObject, Lt as asNumber, Nt as ReadinessRegistry, Ot as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Pt as ReadinessTimeoutError, Q as isVoidInput, Qt as EventCategory$1, Rt as asString$1, Tt as errMsg$1, Xt as scopeKey, Y as isObjectInput, Yt as resolveCapMount, dt as resolveMethodAuth, et as lifecycleJobSchema, f as LOG_LEVEL_RANK, it as looseSchema, kt as DEVICE_STATUS_METHOD, m as RUNTIME_DEFAULTS, mt as scopesAllowDeviceCap, p as METHOD_ACCESS_MAP, pt as scopesAllowAddon, q as isArrayOutputSchema, qt as parseJsonUnknown$1, rt as logLevelAtMost, st as objectInputDeclaresAddonId, t as ALL_CAPABILITY_DEFINITIONS, ut as procedureAuthKey, zt as createEvent } from "./dist-6rM7chzb.mjs";
+import { $ as kebabToCamel, Bt as emitDownForOwnedCaps, C as addonSettingsCapability, Dt as DATAPLANE_SECRET_HEADER$1, G as extractNestedAddonId, Ht as expandCapMethods, It as asJsonObject$1, J as isCollectionArrayMethod, Jt as readinessKey, Kt as parseJsonObject, Lt as asNumber, Nt as ReadinessRegistry, Ot as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Pt as ReadinessTimeoutError, Q as isVoidInput, Qt as EventCategory$1, Rt as asString$1, Tt as errMsg$1, Xt as scopeKey, Y as isObjectInput, Yt as resolveCapMount, dt as resolveMethodAuth, et as lifecycleJobSchema, f as LOG_LEVEL_RANK, it as looseSchema, kt as DEVICE_STATUS_METHOD, m as RUNTIME_DEFAULTS, mt as scopesAllowDeviceCap, p as METHOD_ACCESS_MAP, pt as scopesAllowAddon, q as isArrayOutputSchema, qt as parseJsonUnknown$1, rt as logLevelAtMost, st as objectInputDeclaresAddonId, t as ALL_CAPABILITY_DEFINITIONS, ut as procedureAuthKey, zt as createEvent } from "./dist-CG7kwIZp.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-CQhPGSJm.mjs";
-import { $ as buildUdsNativeCapProxy, A as createParentUnownedCallHandler, At as createV8Reclaimer, B as AGENT_CAP_FWD_SERVICE, C as brokerTransportLink, Ct as createAddonDataPlaneFacility, D as HUB_CAP_FWD_ACTION, Dt as HEAP_WATCH_WARN_RATIO, E as localProviderLink, Et as HEAP_WATCH_INTERVAL_MS, F as createUdsLoggerWithControl, G as createLocalTransport, H as CapRouteError, I as LocalChildClient, J as SocketChannel, K as UdsLocalTransportClient, L as LocalChildRegistry, M as createUdsEventBus, Mt as startHeapWatch, N as udsChildLogToWorkerEntry, Nt as startRunnerHeapWatch, O as HUB_CAP_FWD_SERVICE, Ot as RUNNER_HEAP_WATCH_INTERVAL_MS, P as createUdsLogger, Pt as strandedMb, Q as buildNativeCapProxy, R as UDS_NO_ROUTE_PREFIX, S as brokerCallForCap, St as runNpm, T as ipcParentLink, Tt as HEAP_RECLAIM_TRIGGER_MB, U as classifyCapRoute, V as CapRouteResolver, W as callWithServiceDiscovery, X as FrameDecoder, Y as localEndpointPath, Z as encodeFrame, _ as createKernelHwAccel, _t as CapabilityUnavailableError, a as getWorkerDeviceRegistry, at as createAddonService, b as __resetCapUsageRegistryForTests, bt as resolveAddonClass, c as setHubConnected, ct as capActionName, d as getBrokerEventBus, dt as capServiceName, et as createBrokerDeviceManagerApi, f as getMoleculerEventStats, ft as parseCapAction, g as AddonDepsManager, gt as CapabilityHandle, h as subscribePassthrough, ht as DeviceRegistry, i as createUdsAddonContext, j as createUdsEventBridge, jt as shouldReclaim, k as createHubCapForwardService, kt as buildHeapSample, l as EVENT_TOPIC_PREFIX, lt as capActionSuffix, m as setNodeEventInterest, mt as serializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as validateProviderRegistrations, p as registerEventBusService, pt as deserializeTypedArrays, q as UdsLocalTransportServer, r as createAddonContext, rt as mountNativeCapService, s as getOrInitReadinessRegistryForClient, st as NATIVE_PROVIDER_SERVICE_INFIX, t as installManifestPythonDeps, u as clusterEventTopic, ut as capBareAction, v as resolveHwAccel, vt as copyBundledNativeModules, w as buildLinkChain, wt as HEAP_RECLAIM_MIN_INTERVAL_MS, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as installManifestNativeDeps, z as AGENT_CAP_FWD_ACTION } from "./manifest-python-deps-BuhBXCg0.mjs";
+import { $ as buildUdsNativeCapProxy, A as createParentUnownedCallHandler, At as RSS_BUDGET_REANNOUNCE_MIN_MS, B as AGENT_CAP_FWD_SERVICE, Bt as shouldReclaim, C as brokerTransportLink, Ct as createAddonDataPlaneFacility, D as HUB_CAP_FWD_ACTION, Dt as HEAP_WATCH_WARN_RATIO, E as localProviderLink, Et as HEAP_WATCH_INTERVAL_MS, F as createUdsLoggerWithControl, Ft as createV8Reclaimer, G as createLocalTransport, H as CapRouteError, Ht as startRunnerHeapWatch, I as LocalChildClient, It as describeRss, J as SocketChannel, K as UdsLocalTransportClient, L as LocalChildRegistry, Lt as hubMainRssBudget, M as createUdsEventBus, Mt as RUNNER_HEAP_WATCH_INTERVAL_MS, N as udsChildLogToWorkerEntry, Nt as RUNNER_RSS_BUDGET_ENV, O as HUB_CAP_FWD_SERVICE, Ot as HUB_MAIN_RSS_BUDGET_MB, P as createUdsLogger, Pt as buildHeapSample, Q as buildNativeCapProxy, R as UDS_NO_ROUTE_PREFIX, Rt as nextRssBudgetState, S as brokerCallForCap, St as runNpm, T as ipcParentLink, Tt as HEAP_RECLAIM_TRIGGER_MB, U as classifyCapRoute, Ut as strandedMb, V as CapRouteResolver, Vt as startHeapWatch, W as callWithServiceDiscovery, X as FrameDecoder, Y as localEndpointPath, Z as encodeFrame, _ as createKernelHwAccel, _t as CapabilityUnavailableError, a as getWorkerDeviceRegistry, at as createAddonService, b as __resetCapUsageRegistryForTests, bt as resolveAddonClass, c as setHubConnected, ct as capActionName, d as getBrokerEventBus, dt as capServiceName, et as createBrokerDeviceManagerApi, f as getMoleculerEventStats, ft as parseCapAction, g as AddonDepsManager, gt as CapabilityHandle, h as subscribePassthrough, ht as DeviceRegistry, i as createUdsAddonContext, j as createUdsEventBridge, jt as RSS_BUDGET_RELEASE_RATIO, k as createHubCapForwardService, kt as HUB_RSS_BUDGET_ENV, l as EVENT_TOPIC_PREFIX, lt as capActionSuffix, m as setNodeEventInterest, mt as serializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as validateProviderRegistrations, p as registerEventBusService, pt as deserializeTypedArrays, q as UdsLocalTransportServer, r as createAddonContext, rt as mountNativeCapService, s as getOrInitReadinessRegistryForClient, st as NATIVE_PROVIDER_SERVICE_INFIX, t as installManifestPythonDeps, u as clusterEventTopic, ut as capBareAction, v as resolveHwAccel, vt as copyBundledNativeModules, w as buildLinkChain, wt as HEAP_RECLAIM_MIN_INTERVAL_MS, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as installManifestNativeDeps, z as AGENT_CAP_FWD_ACTION, zt as parseRssBudgetMb } from "./manifest-python-deps-CVeckyXx.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";
@@ -94263,7 +94263,8 @@ async function getPidStats$1(pids) {
 }
 var EMPTY_HEAP_DECLARATION = {
 	profile: void 0,
-	maxOldSpaceMb: void 0
+	maxOldSpaceMb: void 0,
+	rssBudgetMb: void 0
 };
 /**
 * Resolve the declared heap profile + old-space ceiling for one addon by reading its package.json
@@ -94284,10 +94285,12 @@ function readAddonHeapDeclaration(spec) {
 		const parsed = JSON.parse(raw);
 		const profile = extractHeapProfile(parsed, spec.addonId);
 		const maxOldSpaceMb = extractMaxOldSpaceMb(parsed, spec.addonId);
-		if (profile !== void 0 || maxOldSpaceMb !== void 0) {
+		const rssBudgetMb = extractRssBudgetMb(parsed, spec.addonId);
+		if (profile !== void 0 || maxOldSpaceMb !== void 0 || rssBudgetMb !== void 0) {
 			declaration = {
 				profile,
-				maxOldSpaceMb
+				maxOldSpaceMb,
+				rssBudgetMb
 			};
 			break;
 		}
@@ -94317,6 +94320,15 @@ function extractMaxOldSpaceMb(parsed, addonId) {
 	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.maxOldSpaceMb;
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : void 0;
 }
+/**
+* `execution.rssBudgetMb` for one addon. Only a POSITIVE finite number is a budget: unlike
+* `maxOldSpaceMb`, `0` here is not an escape hatch that lifts a cap, it is an absent budget —
+* and an absent budget is reported as "unwatched", never rounded into a default.
+*/
+function extractRssBudgetMb(parsed, addonId) {
+	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.rssBudgetMb;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : void 0;
+}
 function readManifestAddons(parsed) {
 	if (typeof parsed !== "object" || parsed === null) return [];
 	const camstack = parsed.camstack;
@@ -94342,10 +94354,20 @@ function isHeavyRunner(addons) {
 * one-off burst becomes the runner's permanent RSS.
 *
 * Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
-* there after the deferred archive walk (99,809 segments in 84s), while the `RecordingIndex` it
-* actually retains is arithmetically ~21 MB (a `SegmentRow` is 5 numbers + 3 strings ≈ 207 B). The
-* same addon on two agent nodes carrying the same code and a smaller archive sits at **58 MB**.
-* The ~2 GB is walk garbage held as high-water in a heap that had no reason to collect it.
+* there. The same addon on two agent nodes carrying the same code and a smaller archive sits at
+* **58 MB**.
+*
+* ⚠ This paragraph used to attribute that ~2 GB to "walk garbage" from the deferred archive walk,
+* and to argue from a ~21 MB `RecordingIndex`. Both were wrong, and the error cost a session on
+* 2026-08-27. The deferred walk had NO CALLER and never ran (it has since been deleted). And the
+* index is not 21 MB: a 2026-08-27 profile of the live recorder read `heapUsed = 1606 MB` against
+* `external = 8 MB`, with an `smaps` census putting 1510 MB in V8's 256 KB page ranges against
+* 54 MB of native heap — LIVE JavaScript retainers, not high-water garbage. The retained set is
+* ~7.1 M `SegmentRow`s plus their path strings and Map entries (13 cameras x 2 profiles x 8 640
+* segments/day x ~30 days), reseeded at boot by `SegmentHourLedger.hydrateIndex`.
+*
+* The lesson for anyone sizing this flag: a heap number needs a RETAINER, and "garbage the GC has
+* no reason to collect" is the explanation to reach for last, not first.
 *
 * ## Why 1024
 *
@@ -94362,8 +94384,7 @@ function isHeavyRunner(addons) {
 *
 * A runner whose working set genuinely does not fit declares its own number in its manifest
 * (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
-* `recorder` (3072 MB; peak 2341 MB heapTotal during the deferred archive walk) is the one
-* shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
+* `recorder` (3072 MB; peak 2341 MB heapTotal) is the one shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
 * `arrayBuffers` (47 RTP rings), which this flag does not bound and never will — its actual old
 * space peaks at 224 MB. Size the declaration from `heapTotal` in the `[mem]` heartbeat, never
 * from RSS.
@@ -94392,6 +94413,22 @@ function runnerMaxOldSpaceMb(addons, heavy) {
 	return Math.max(...declared);
 }
 /**
+* The runner's declared RSS budget in MB, or `undefined` when NOBODY declared one.
+*
+* Same rule as the old-space ceiling, for the same reason (D2/D29): the runner takes the MAXIMUM
+* any co-located addon declares, because a runner is respawned as a whole and co-location must
+* never silence the hungriest member. It would be strictly worse here than for a heap ceiling —
+* an under-sized budget does not kill anything, it just cries wolf, and a watchdog that cries
+* wolf is a watchdog that gets muted.
+*
+* `undefined` propagates as an ABSENT env var, and the child then announces itself unwatched.
+* There is deliberately no class default: see `AddonExecution.rssBudgetMb`.
+*/
+function runnerRssBudgetMb(addons) {
+	const declared = addons.map((a) => readAddonHeapDeclaration(a).rssBudgetMb).filter((mb) => mb !== void 0);
+	return declared.length === 0 ? void 0 : Math.max(...declared);
+}
+/**
 * Per-placement V8 heap flags (Block D). LIGHT runners cap their young generation
 * (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — and
 * keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
@@ -94489,6 +94526,7 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 		const nodeId = buildNodeId(runnerId);
 		const runnerPath = path$39.resolve(__dirname, "addon-runner.js");
 		const heavy = isHeavyRunner(addons);
+		const rssBudgetMb = runnerRssBudgetMb(addons);
 		const childEnv = {
 			...process.env,
 			CAMSTACK_RUNNER_ID: runnerId,
@@ -94502,6 +94540,8 @@ function createProcessService(parentNodeId, dataDir, deps, parentTcpPort, parent
 			...applyRunnerNativeAllocator(process.env),
 			...env
 		};
+		if (rssBudgetMb === void 0) delete childEnv[RUNNER_RSS_BUDGET_ENV];
+		else childEnv[RUNNER_RSS_BUDGET_ENV] = String(rssBudgetMb);
 		const heapFlags = runnerHeapFlags(addons);
 		capturedBroker?.logger.info(`[${runnerId}] heap profile: ${heavy ? "heavy" : "light"} flags=[${heapFlags.join(" ")}] arenas=${childEnv["MALLOC_ARENA_MAX"] ?? "glibc-default"} vips=${childEnv["VIPS_CONCURRENCY"] ?? "sharp-default"}`);
 		const child = spawnFn(process.execPath, [...heapFlags, runnerPath], {
@@ -95243,4 +95283,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, DEFAULT_DATA_PATH, DEFAULT_LAN_HTTP_PORT, DEFAULT_LOG_LEVEL, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_RECLAIM_MIN_INTERVAL_MS, HEAP_RECLAIM_TRIGGER_MB, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, 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, RUNNER_HEAP_WATCH_INTERVAL_MS, 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, __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, createDoorSettingsView, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, evaluateExistingCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getLoggingGate, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, isolatedBuiltinPhase, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, partitionIsolatedBuiltinIds, proxyToUpstream, quarantineAddonResidue, readExtraSans, readLanHttpState, readPendingRestart, readTlsAccessStatus, readTlsMode, readinessKey, registerEventBusService, registerLanHttpHandler, reissueTlsLeaf, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runHubAddonBoot, runNpm, scheduleSelfRestart, scopeKey, scopesAllowAddon, scopesAllowDeviceCap, selectAddonResidue, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, 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, DEFAULT_DATA_PATH, DEFAULT_LAN_HTTP_PORT, DEFAULT_LOG_LEVEL, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_RECLAIM_MIN_INTERVAL_MS, HEAP_RECLAIM_TRIGGER_MB, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, 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_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, __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, createDoorSettingsView, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, describeRss, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, evaluateExistingCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getLoggingGate, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, 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, readLanHttpState, readPendingRestart, readTlsAccessStatus, readTlsMode, readinessKey, registerEventBusService, registerLanHttpHandler, reissueTlsLeaf, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runHubAddonBoot, runNpm, scheduleSelfRestart, scopeKey, scopesAllowAddon, scopesAllowDeviceCap, selectAddonResidue, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, startHeapWatch, startRunnerHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, validateUploadedTls, waitUntilReady, writeExtraSans, writePendingRestart, writeTlsMode };

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

@@ -207,10 +207,103 @@ export interface HeapWatchSink {
  * The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
  * committed at a sawtooth peak and no longer needs are counted inside heapTotal,
  * and they are precisely what this number exists to see.
+ *
+ * ## What this number can and CANNOT be asked
+ *
+ * It answers exactly one question: *are there pages a `last-resort` GC could
+ * hand back?* For that it is correct, and {@link shouldReclaim} is the only
+ * gate that should ever be built on it.
+ *
+ * It can never answer *is this process too big?*, because `external` is
+ * subtracted by construction. A process whose growth is entirely `external` —
+ * Buffers, `arrayBuffers`, what a native addon mallocs — moves `rss` and the
+ * subtrahend by the same amount, so this number is **algebraically constant
+ * while the process triples**. That is not a threshold set too high; the
+ * quantity cannot represent the event.
+ *
+ * It cost 11.4GB and a ~154 second stall of the whole container to establish
+ * that. See {@link RssBudgetOptions} for the number that does answer it.
  */
 export declare function strandedMb(s: HeapSample): number;
 /** Whether it is worth paying a stop-the-world to get those pages back. */
 export declare function shouldReclaim(s: HeapSample, triggerMb?: number): boolean;
+/**
+ * Which of the three MEASURED growth shapes dominates a process's footprint.
+ *
+ * These are not categories invented for a log line. They are what `smaps` found
+ * on the three live processes on 2026-08-27, and each one has a different lever:
+ *
+ * | process | evidence | shape |
+ * | --- | --- | --- |
+ * | `hub/recorder` | 1509.8MB in V8's 256KB page ranges, 53.9MB `brk`, `external` 8MB | `v8-heap` |
+ * | `hub/stream-broker` | 242.6MB V8 pages but **1159.1MB `brk`**, `arrayBuffers` 829MB | `external` |
+ * | `hub-main` | 1295.1MB V8 pages, 566.7MB `brk`, **2.7GB across 13 anonymous mappings >=64MB** | `native-residue` |
+ *
+ *  - `v8-heap` — live JS retainers. `--max-old-space-size` is the bound, and the
+ *    fix is the retained set (the recorder's ~7.1M `SegmentRow`s).
+ *  - `external` — Buffers and native `external`. **No V8 flag bounds any of
+ *    it**; `hub/pipeline-analytics` reached 5735MB with `--max-old-space-size=1024`
+ *    in force the whole time.
+ *  - `native-residue` — memory already freed that the allocator has not returned
+ *    to the kernel. This is what the reclaim pass exists for, and the only shape
+ *    where `MALLOC_ARENA_MAX` / `VIPS_CONCURRENCY` are the lever — both of which
+ *    are ALREADY applied here, so a `native-residue` line means that lever is
+ *    spent and the answer is upstream.
+ *
+ * Reporting only "it is big" leaves the operator to guess between three
+ * different fixes, two of which cannot work.
+ */
+export type RssGrowthShape = 'v8-heap' | 'external' | 'native-residue';
+/** Where a process's footprint stands against the budget its role declared. */
+export type RssBudgetState = 'within' | 'over';
+/** The footprint, split into the three parts that imply different fixes. */
+export interface RssBreakdown {
+    readonly rssMb: number;
+    readonly budgetMb: number;
+    /** How far past the budget. 0 when within — "how far over" has no meaning below it. */
+    readonly overMb: number;
+    readonly heapUsedMb: number;
+    readonly externalMb: number;
+    /** `rss − heapUsed − external`: native the other two numbers do not name. */
+    readonly nativeResidueMb: number;
+    readonly arrayBuffersMb: number;
+    readonly shape: RssGrowthShape;
+}
+/**
+ * Split a sample into the three shapes and name the dominant one.
+ *
+ * `nativeResidue` is clamped at 0: `process.memoryUsage()` reads its fields at
+ * slightly different instants, so `heapUsed + external` can transiently exceed
+ * `rss` and a negative residue would misclassify the sample.
+ */
+export declare function describeRss(s: HeapSample, budgetMb: number): RssBreakdown;
+/**
+ * Release the alarm below this share of the budget.
+ *
+ * Hysteresis, not a second budget: every process here sawtooths (the reclaim
+ * pass alone moves hub-main by ~1.6GB), so a single threshold would print a
+ * pair of lines on every cycle. 0.9 of the budget is a real retreat.
+ */
+export declare const RSS_BUDGET_RELEASE_RATIO = 0.9;
+/**
+ * Floor on how often a crossing may be ANNOUNCED again.
+ *
+ * Hysteresis alone bounds flapping around the edge; it does not bound a process
+ * that genuinely swings across the budget every reclaim cycle
+ * ({@link HEAP_RECLAIM_MIN_INTERVAL_MS} is 2 minutes, so that is up to 30 pairs
+ * of lines an hour, forever). A process that oscillates across its budget is ONE
+ * story, and the operator needs it told once per quarter-hour, not thirty times.
+ *
+ * This is the discipline the rest of this module already follows and the one the
+ * log needed: on 2026-08-27 two real alarms were buried under 83,198 Hikvision
+ * heartbeat lines in 12h. A watchdog that shouts is a watchdog that gets muted.
+ */
+export declare const RSS_BUDGET_REANNOUNCE_MIN_MS = 900000;
+/**
+ * The alarm state machine, pure so the thresholds are testable without
+ * allocating five gigabytes to reach them.
+ */
+export declare function nextRssBudgetState(current: RssBudgetState, rssMb: number, budgetMb: number, releaseRatio?: number): RssBudgetState;
 /** A full collection that also asks V8 to hand the pages back to the OS. */
 export type HeapReclaimer = () => void;
 /**
@@ -240,13 +333,71 @@ export interface HeapReclaimOptions {
     /** Ratio at which it releases. See {@link HEAP_WATCH_DEESCALATE_RATIO}. */
     readonly deescalateRatio?: number;
 }
+/**
+ * The RSS budget for ONE process, and where the number came from.
+ *
+ * ## Why a DECLARED budget, and not a derived one
+ *
+ * Every bound this system had was derived, and each one is blind to most of a
+ * process: `--max-old-space-size` bounds old space only, and `strandedMb`
+ * subtracts `external` by construction. `hub/pipeline-analytics` was killed at
+ * 11.4GB with a 1024MB old-space ceiling in force and a stranded number that
+ * never moved. RSS is the quantity the host's OOM killer actually reads, so RSS
+ * is the quantity that needs a ceiling — and RSS cannot be derived from any flag,
+ * because most of it is not V8's.
+ *
+ * ## Why there is no single constant
+ *
+ * The legitimate footprint differs by an order of magnitude BY ROLE, measured
+ * on the same host on the same day:
+ *
+ *  - `hub/recorder` legitimately holds ~1.5GB of live V8 index (~7.1M
+ *    `SegmentRow`s, ~30 days x 13 cameras x 2 profiles) and declares a 3072MB
+ *    old space to hold it;
+ *  - `hub/stream-broker` legitimately holds ~900MB of `arrayBuffers` (47 RTP
+ *    pre-roll rings) in the glibc heap, with an old space of only 224MB;
+ *  - `hub/pipeline-analytics` has no legitimate multi-GB working set at all —
+ *    it died at 11.4GB holding a 536MB heap.
+ *
+ * One constant would either wave through analytics' 11GB or scream at the
+ * recorder's entirely correct 2GB. So the number lives **next to the role that
+ * knows it**: an addon declares `execution.rssBudgetMb` in its own manifest,
+ * exactly as it already declares `execution.maxOldSpaceMb`, and the runner takes
+ * the MAXIMUM any co-located addon declares (D2/D29 — a runner is respawned as a
+ * whole, so co-location must never silence the hungriest member).
+ *
+ * hub-main has no manifest, and its entrypoint is the LEAST deployable surface
+ * in this system (the Dockerfile's own comment: a backend change is train-bound
+ * by construction, and an image build does not ship it). Its budget therefore
+ * lives in `@camstack/server`, which `applyServerUpdate` replaces the same day —
+ * see {@link HUB_MAIN_RSS_BUDGET_MB}.
+ *
+ * ## And a process with no declaration is UNWATCHED, out loud
+ *
+ * `budgetMb: undefined` does not select a default. Defaulting would be the same
+ * mistake in a new place: a number nobody measured, applied to a process nobody
+ * profiled, producing either silence or noise with equal authority. The process
+ * says once, at boot, that nothing is watching it. Most runners are in this
+ * state today and that is the honest report — measurements exist for four
+ * processes, so four processes carry a budget.
+ */
+export interface RssBudgetOptions {
+    /** MB. `undefined` → this process is declared UNWATCHED and says so at boot. */
+    readonly budgetMb: number | undefined;
+    /** Named in every line, so a budget that is wrong is traceable to its author. */
+    readonly source: string;
+    /** See {@link RSS_BUDGET_RELEASE_RATIO}. */
+    readonly releaseRatio?: number;
+    /** See {@link RSS_BUDGET_REANNOUNCE_MIN_MS}. */
+    readonly reannounceMinMs?: number;
+}
 /**
  * Start the heartbeat. Returns a stop function.
  *
  * `unref`ed so it can never hold the process open, and every read is wrapped:
  * a diagnostic that can crash the process it watches is worse than none.
  */
-export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number, reclaimOptions?: HeapReclaimOptions, loopDelay?: LoopDelayMeter | undefined, execArgv?: readonly string[], announceCeilingOrigin?: boolean): () => void;
+export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number, reclaimOptions?: HeapReclaimOptions, loopDelay?: LoopDelayMeter | undefined, execArgv?: readonly string[], announceCeilingOrigin?: boolean, rssBudget?: RssBudgetOptions): () => void;
 /**
  * Steady heartbeat period for a HEAVY addon runner.
  *
@@ -284,7 +435,64 @@ export interface RunnerHeapWatchOptions {
     readonly intervalMs?: number;
     /** Test injection. Production omits it and gets {@link createV8Reclaimer}. */
     readonly reclaimOptions?: HeapReclaimOptions;
+    /**
+     * `CAMSTACK_RUNNER_RSS_BUDGET_MB` as the parent passed it — the MAXIMUM
+     * `execution.rssBudgetMb` any co-located addon declares, resolved from the
+     * manifests in `process-service.ts`. Absent means no co-located addon declared
+     * one, and the runner reports itself UNWATCHED. See {@link RssBudgetOptions}.
+     */
+    readonly rssBudgetMb?: string;
 }
+/**
+ * Parse a budget carried across a process boundary as an env string.
+ *
+ * Anything that is not a positive finite integer is `undefined` — i.e. the
+ * process is UNWATCHED and says so. A malformed budget must never round to a
+ * silent default: that is the failure this whole mechanism exists to remove.
+ */
+export declare function parseRssBudgetMb(raw: string | undefined): number | undefined;
+/** Env var carrying a runner's declared RSS budget from parent to child. */
+export declare const RUNNER_RSS_BUDGET_ENV = "CAMSTACK_RUNNER_RSS_BUDGET_MB";
+/** Operator override for hub-main's budget, applied without a release. */
+export declare const HUB_RSS_BUDGET_ENV = "CAMSTACK_HUB_RSS_BUDGET_MB";
+/**
+ * hub-main's declared RSS budget, in MB.
+ *
+ * ## Why the number lives HERE and not in the image
+ *
+ * hub-main has no manifest to declare it in, and the obvious alternative — the
+ * entrypoint that already knew about `CAMSTACK_HUB_HEAP_MB` — is the least
+ * deployable surface in this system. The Dockerfile says so itself: the image
+ * never contains this repo's backend, so a value written there reaches a running
+ * hub only on an image rebuild. `main.ts` is what `applyServerUpdate` replaces,
+ * which is exactly why the heartbeat was started from there in the first place.
+ * A budget that cannot ship is not a budget.
+ *
+ * ## Why 4096
+ *
+ * hub-main's entitlement is its old-space ceiling plus its measured native
+ * floor. The floor is 438MB, established live across five consecutive
+ * `gc(last-resort)` passes that landed within 4MB of each other
+ * (4559/4561/4560/4562/4563MB) — sqlite pages, libvips, sharp, thread stacks and
+ * node's own text. Against the 3072MB ceiling in force on 2026-08-27 that is
+ * ~3.5GB of legitimate footprint, and 4096 leaves it ~600MB of slack.
+ *
+ * **This WILL fire on the hub as measured on 2026-08-27, and that is the point.**
+ * That process sat at 4.87GiB with `external` at 360MB: ~2.8GB of it was native
+ * memory already freed and never returned, spread across 13 anonymous mappings
+ * >=64MB, with only 1295MB in V8 pages. `MALLOC_ARENA_MAX=2` and
+ * `VIPS_CONCURRENCY=1` were already applied — verified from `/proc/<pid>/environ`
+ * — so that lever is spent and the residue stands. The alarm reporting a
+ * genuinely over-budget process is the mechanism working; a number picked to sit
+ * just above today's RSS would be a rubber stamp.
+ *
+ * An operator who decides that residue is the cost of doing business moves it in
+ * one place with {@link HUB_RSS_BUDGET_ENV}, and the decision is on the record
+ * instead of being absorbed by a threshold nobody set.
+ */
+export declare const HUB_MAIN_RSS_BUDGET_MB = 4096;
+/** hub-main's budget: the declared number, or the operator's override. */
+export declare function hubMainRssBudget(env?: NodeJS.ProcessEnv): RssBudgetOptions;
 /**
  * Start the heap watch + stranded-page reclaimer for ONE addon runner, iff it
  * is a heavy one. Returns the stop function, or undefined when nothing started.

package/dist/kernel/moleculer/children-batch-loader.d.ts

@@ -0,0 +1,46 @@
+import { IScopedLogger } from '@camstack/types';
+/**
+ * The child fields the accessory reconcile reads. Deliberately narrower than
+ * `DeviceInfo`: the loader is a transport, and a transport that pins the whole
+ * projection would have to change every time an unrelated field does.
+ */
+export interface ReconcileChildRow {
+    readonly id: number;
+    readonly stableId: string;
+    readonly name: string;
+    readonly linkDeviceId?: number | null;
+}
+/**
+ * Narrow an untyped cap answer to the fields the reconcile reads.
+ *
+ * `callDeviceManager` is an untyped boundary, and the answer may come from a
+ * hub of a different vintage. A row that does not carry an id, a stableId and
+ * a name is not a child this code can prune ON, so it is dropped rather than
+ * cast into shape — the prune step DELETES, and a half-parsed row is the input
+ * that would make it delete the wrong thing.
+ */
+export declare function parseChildRows(value: unknown): readonly ReconcileChildRow[] | null;
+/**
+ * Narrow a `getChildrenBatch` answer: a record keyed by parent id as a string.
+ *
+ * An EMPTY record is a valid answer — "none of these parents has children" —
+ * and so is what a hub that answers the call but knows none of the parents
+ * would send. Both mean "nothing to prune", which is the safe direction. Only
+ * a shape that is not a record at all is `null`, and the loader treats that as
+ * a failed batch and re-asks per parent.
+ */
+export declare function parseChildrenByParent(value: unknown): ReadonlyMap<number, readonly ReconcileChildRow[]> | null;
+export interface ChildrenBatchLoaderOptions {
+    /** One `device-manager.getChildrenBatch` call. Rejects like any RPC. */
+    readonly fetchBatch: (parentDeviceIds: readonly number[]) => Promise<ReadonlyMap<number, readonly ReconcileChildRow[]>>;
+    /** One `device-manager.getChildren` call — the fallback, and the old path. */
+    readonly fetchOne: (parentDeviceId: number) => Promise<readonly ReconcileChildRow[]>;
+    readonly logger: IScopedLogger;
+    /** Test seam. Production takes {@link DEVICE_CHILDREN_BATCH_MAX}. */
+    readonly maxBatch?: number;
+}
+export interface ChildrenBatchLoader {
+    /** The direct children of one parent, coalesced with every other in-flight ask. */
+    load(parentDeviceId: number): Promise<readonly ReconcileChildRow[]>;
+}
+export declare function createChildrenBatchLoader(opts: ChildrenBatchLoaderOptions): ChildrenBatchLoader;