@camstack/system 1.2.145 → 1.2.147

package/dist/{manifest-python-deps-BRyNCnnG.mjs → manifest-python-deps-DhT0oFOZ.mjs}

@@ -1,4 +1,4 @@
-import "./dist-CG7kwIZp.mjs";
+import "./dist-DrBc-7Y3.mjs";
 import * as crypto$1 from "node:crypto";
 import { randomBytes, randomUUID } from "node:crypto";
 import { ensureBinary, ensureFfmpeg, ensurePython, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
@@ -262,6 +262,22 @@ var consoleSink = {
 * 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.
 */
 function strandedMb(s) {
 	return s.rssMb - s.heapUsedMb - s.externalMb;
@@ -270,6 +286,67 @@ function strandedMb(s) {
 function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
 	return strandedMb(s) > triggerMb;
 }
+/** Share of RSS, as a whole percent. Never divides by zero. */
+function share(partMb, rssMb) {
+	return rssMb > 0 ? Math.round(partMb / rssMb * 100) : 0;
+}
+/**
+* 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.
+*/
+function describeRss(s, budgetMb) {
+	const nativeResidueMb = Math.max(0, strandedMb(s));
+	const shape = s.heapUsedMb >= s.externalMb && s.heapUsedMb >= nativeResidueMb ? "v8-heap" : s.externalMb >= nativeResidueMb ? "external" : "native-residue";
+	return {
+		rssMb: s.rssMb,
+		budgetMb,
+		overMb: Math.max(0, s.rssMb - budgetMb),
+		heapUsedMb: s.heapUsedMb,
+		externalMb: s.externalMb,
+		nativeResidueMb,
+		arrayBuffersMb: s.arrayBuffersMb,
+		shape
+	};
+}
+/** What the operator can actually DO about each shape. */
+var SHAPE_ADVICE = {
+	"v8-heap": "live JS retainers — bounded by --max-old-space-size; the fix is the retained set",
+	external: "Buffers / native external — NO V8 flag bounds this, and the old-space ceiling never will",
+	"native-residue": "freed native memory the allocator has not returned — MALLOC_ARENA_MAX/VIPS_CONCURRENCY are already applied, so this lever is spent"
+};
+/**
+* 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.
+*/
+var RSS_BUDGET_RELEASE_RATIO = .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.
+*/
+var RSS_BUDGET_REANNOUNCE_MIN_MS = 9e5;
+/**
+* The alarm state machine, pure so the thresholds are testable without
+* allocating five gigabytes to reach them.
+*/
+function nextRssBudgetState(current, rssMb, budgetMb, releaseRatio = RSS_BUDGET_RELEASE_RATIO) {
+	if (current === "over") return rssMb < budgetMb * releaseRatio ? "within" : "over";
+	return rssMb > budgetMb ? "over" : "within";
+}
 function isGcFunction(value) {
 	return typeof value === "function";
 }
@@ -297,8 +374,19 @@ function createV8Reclaimer() {
 		return;
 	}
 }
-function format(label, s, loop) {
-	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
+/**
+* The line that says HOW the process grew, not merely that it did.
+*
+* `heapUsed`, `external` and the native residue each carry their share of RSS,
+* because the shares are what separate the three fixes — and on the process this
+* module failed to catch, the shares were 9% / 74% / 16%, which names the answer
+* on sight.
+*/
+function formatOverBudget(label, b, source) {
+	return `[mem] ${label} OVER RSS BUDGET rss=${b.rssMb}MB budget=${b.budgetMb}MB over=+${b.overMb}MB shape=${b.shape} heapUsed=${b.heapUsedMb}MB(${share(b.heapUsedMb, b.rssMb)}%) external=${b.externalMb}MB(${share(b.externalMb, b.rssMb)}%) nativeResidue=${b.nativeResidueMb}MB(${share(b.nativeResidueMb, b.rssMb)}%) arrayBuffers=${b.arrayBuffersMb}MB budgetFrom="${source}" — ${SHAPE_ADVICE[b.shape]}`;
+}
+function format(label, s, loop, budgetMb) {
+	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB` + (budgetMb === void 0 ? "" : ` rssBudget=${budgetMb}MB`);
 	if (loop === void 0) return line;
 	return `${line} loopP50=${loop.p50Ms}ms loopP99=${loop.p99Ms}ms loopMax=${loop.maxMs}ms`;
 }
@@ -308,7 +396,7 @@ function format(label, s, loop) {
 * `unref`ed so it can never hold the process open, and every read is wrapped:
 * a diagnostic that can crash the process it watches is worse than none.
 */
-function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true, rssBudget) {
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1024;
@@ -352,6 +440,39 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	};
 	let mode = "steady";
 	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	const budgetMb = rssBudget?.budgetMb !== void 0 && rssBudget.budgetMb > 0 ? rssBudget.budgetMb : void 0;
+	const budgetSource = rssBudget?.source ?? "unspecified";
+	const releaseRatio = rssBudget?.releaseRatio ?? .9;
+	const reannounceMinMs = rssBudget?.reannounceMinMs ?? 9e5;
+	let budgetState = "within";
+	let lastBudgetWarnAt = Number.NEGATIVE_INFINITY;
+	/** Only pair a "back within" with an over-budget line that was actually said. */
+	let overBudgetAnnounced = false;
+	/**
+	* One line per STATE CHANGE, never one per sample.
+	*
+	* The probe runs every {@link HEAP_WATCH_FAST_INTERVAL_MS}; warning on every
+	* sample above the budget would put 30 lines a minute in the hub's shared log
+	* for a process that is legitimately, steadily large. That is precisely the
+	* failure mode that buried two real alarms under 83,198 heartbeat lines on
+	* 2026-08-27, so the crossing is the event and the level is not.
+	*/
+	const checkRssBudget = (sample, at) => {
+		if (budgetMb === void 0) return;
+		const previous = budgetState;
+		budgetState = nextRssBudgetState(previous, sample.rssMb, budgetMb, releaseRatio);
+		if (budgetState === previous) return;
+		if (budgetState === "over") {
+			if (at - lastBudgetWarnAt < reannounceMinMs) return;
+			lastBudgetWarnAt = at;
+			overBudgetAnnounced = true;
+			sink.warn(formatOverBudget(label, describeRss(sample, budgetMb), budgetSource));
+			return;
+		}
+		if (!overBudgetAnnounced) return;
+		overBudgetAnnounced = false;
+		sink.info(`[mem] ${label} back within its RSS budget — rss=${sample.rssMb}MB budget=${budgetMb}MB`);
+	};
 	/**
 	* PROBING and LOGGING are separate cadences, and that separation is the whole
 	* point.
@@ -377,18 +498,20 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 			const due = at - lastLoggedAt >= intervalMs;
 			if (mode === "escalated" || due) {
 				lastLoggedAt = at;
-				const line = format(label, sample, loopDelay?.read());
+				const line = format(label, sample, loopDelay?.read(), budgetMb);
 				if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 				else if (mode === "escalated") sink.warn(`${line} — heap elevated, sampling every ${probeIntervalMs}ms`);
 				else sink.info(line);
 			}
 			if (previous === "escalated" && mode === "steady") sink.info(`[mem] ${label} heap back to routine — logging every ${intervalMs}ms`);
+			checkRssBudget(sample, at);
 			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
+	if (rssBudget !== void 0 && budgetMb === void 0) sink.info(`[mem] ${label} is NOT WATCHED against an RSS budget — no budget declared (${budgetSource}). rss growth outside the V8 heap raises nothing here: --max-old-space-size bounds old space only, and stranded subtracts external by construction. Declare execution.rssBudgetMb once this process has a measured working set.`);
 	if (announceCeilingOrigin && heapCeilingOrigin(execArgv) === "v8-default") sink.info(`[mem] ${label} heap ceiling is V8's DEFAULT (${read().heapLimitMb}MB) — no --max-old-space-size on argv. Nothing here CHOSE that number; it is derived from host RAM and moves with it.`);
 	let stopped = false;
 	return () => {
@@ -414,6 +537,71 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 */
 var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 /**
+* 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.
+*/
+function parseRssBudgetMb(raw) {
+	if (raw === void 0) return void 0;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+	return Math.floor(parsed);
+}
+/** Env var carrying a runner's declared RSS budget from parent to child. */
+var RUNNER_RSS_BUDGET_ENV = "CAMSTACK_RUNNER_RSS_BUDGET_MB";
+/** Operator override for hub-main's budget, applied without a release. */
+var 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.
+*/
+var HUB_MAIN_RSS_BUDGET_MB = 4096;
+/** hub-main's budget: the declared number, or the operator's override. */
+function hubMainRssBudget(env = process.env) {
+	const override = env[HUB_RSS_BUDGET_ENV];
+	if (override !== void 0) return {
+		budgetMb: parseRssBudgetMb(override),
+		source: HUB_RSS_BUDGET_ENV
+	};
+	return {
+		budgetMb: HUB_MAIN_RSS_BUDGET_MB,
+		source: "HUB_MAIN_RSS_BUDGET_MB (kernel/heap-watch)"
+	};
+}
+/**
 * 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.
 *
@@ -447,13 +635,17 @@ var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 function startRunnerHeapWatch(options) {
 	if (options.heapProfile !== "heavy") return void 0;
 	const intervalMs = options.intervalMs ?? 3e5;
-	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false);
+	const rssBudget = {
+		budgetMb: parseRssBudgetMb(options.rssBudgetMb),
+		source: `manifest execution.rssBudgetMb (via ${RUNNER_RSS_BUDGET_ENV})`
+	};
+	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false, rssBudget);
 	let reclaimOptions = options.reclaimOptions;
 	if (reclaimOptions === void 0) {
 		const reclaimer = createV8Reclaimer();
 		reclaimOptions = reclaimer === void 0 ? void 0 : { reclaim: reclaimer };
 	}
-	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true);
+	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true, rssBudget);
 }
 //#endregion
 //#region src/kernel/moleculer/addon-data-plane-facility.ts
@@ -8390,4 +8582,4 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 	await deps.installPythonRequirements(reqAbs);
 }
 //#endregion
-export { buildUdsNativeCapProxy as $, createParentUnownedCallHandler as A, createV8Reclaimer as At, AGENT_CAP_FWD_SERVICE as B, brokerTransportLink as C, createAddonDataPlaneFacility as Ct, HUB_CAP_FWD_ACTION as D, HEAP_WATCH_WARN_RATIO as Dt, localProviderLink as E, HEAP_WATCH_INTERVAL_MS as Et, createUdsLoggerWithControl as F, createLocalTransport as G, CapRouteError as H, LocalChildClient as I, SocketChannel as J, UdsLocalTransportClient as K, LocalChildRegistry as L, createUdsEventBus as M, startHeapWatch as Mt, udsChildLogToWorkerEntry as N, startRunnerHeapWatch as Nt, HUB_CAP_FWD_SERVICE as O, RUNNER_HEAP_WATCH_INTERVAL_MS as Ot, createUdsLogger as P, strandedMb as Pt, buildNativeCapProxy as Q, UDS_NO_ROUTE_PREFIX as R, brokerCallForCap as S, runNpm as St, ipcParentLink as T, HEAP_RECLAIM_TRIGGER_MB as Tt, classifyCapRoute as U, CapRouteResolver as V, callWithServiceDiscovery as W, FrameDecoder as X, localEndpointPath as Y, encodeFrame as Z, createKernelHwAccel as _, CapabilityUnavailableError as _t, getWorkerDeviceRegistry as a, createAddonService as at, __resetCapUsageRegistryForTests as b, resolveAddonClass as bt, setHubConnected as c, capActionName as ct, getBrokerEventBus as d, capServiceName as dt, createBrokerDeviceManagerApi as et, getMoleculerEventStats as f, parseCapAction as ft, AddonDepsManager as g, CapabilityHandle as gt, subscribePassthrough as h, DeviceRegistry as ht, createUdsAddonContext as i, setWorkerNativeCapsChangeListener as it, createUdsEventBridge as j, shouldReclaim as jt, createHubCapForwardService as k, buildHeapSample as kt, EVENT_TOPIC_PREFIX as l, capActionSuffix as lt, setNodeEventInterest as m, serializeTypedArrays as mt, adaptBrokerToCluster as n, getWorkerNativeCapSnapshot as nt, getOrInitReadinessRegistry as o, validateProviderRegistrations as ot, registerEventBusService as p, deserializeTypedArrays as pt, UdsLocalTransportServer as q, createAddonContext as r, mountNativeCapService as rt, getOrInitReadinessRegistryForClient as s, NATIVE_PROVIDER_SERVICE_INFIX as st, installManifestPythonDeps as t, getWorkerNativeCapProvider as tt, clusterEventTopic as u, capBareAction as ut, resolveHwAccel as v, copyBundledNativeModules as vt, buildLinkChain as w, HEAP_RECLAIM_MIN_INTERVAL_MS as wt, getCapUsageRegistry as x, resolveNpmInvocation as xt, CapUsageRegistry as y, installManifestNativeDeps as yt, AGENT_CAP_FWD_ACTION as z };
+export { buildUdsNativeCapProxy as $, createParentUnownedCallHandler as A, RSS_BUDGET_REANNOUNCE_MIN_MS as At, AGENT_CAP_FWD_SERVICE as B, shouldReclaim as Bt, brokerTransportLink as C, createAddonDataPlaneFacility as Ct, HUB_CAP_FWD_ACTION as D, HEAP_WATCH_WARN_RATIO as Dt, localProviderLink as E, HEAP_WATCH_INTERVAL_MS as Et, createUdsLoggerWithControl as F, createV8Reclaimer as Ft, createLocalTransport as G, CapRouteError as H, startRunnerHeapWatch as Ht, LocalChildClient as I, describeRss as It, SocketChannel as J, UdsLocalTransportClient as K, LocalChildRegistry as L, hubMainRssBudget as Lt, createUdsEventBus as M, RUNNER_HEAP_WATCH_INTERVAL_MS as Mt, udsChildLogToWorkerEntry as N, RUNNER_RSS_BUDGET_ENV as Nt, HUB_CAP_FWD_SERVICE as O, HUB_MAIN_RSS_BUDGET_MB as Ot, createUdsLogger as P, buildHeapSample as Pt, buildNativeCapProxy as Q, UDS_NO_ROUTE_PREFIX as R, nextRssBudgetState as Rt, brokerCallForCap as S, runNpm as St, ipcParentLink as T, HEAP_RECLAIM_TRIGGER_MB as Tt, classifyCapRoute as U, strandedMb as Ut, CapRouteResolver as V, startHeapWatch as Vt, callWithServiceDiscovery as W, FrameDecoder as X, localEndpointPath as Y, encodeFrame as Z, createKernelHwAccel as _, CapabilityUnavailableError as _t, getWorkerDeviceRegistry as a, createAddonService as at, __resetCapUsageRegistryForTests as b, resolveAddonClass as bt, setHubConnected as c, capActionName as ct, getBrokerEventBus as d, capServiceName as dt, createBrokerDeviceManagerApi as et, getMoleculerEventStats as f, parseCapAction as ft, AddonDepsManager as g, CapabilityHandle as gt, subscribePassthrough as h, DeviceRegistry as ht, createUdsAddonContext as i, setWorkerNativeCapsChangeListener as it, createUdsEventBridge as j, RSS_BUDGET_RELEASE_RATIO as jt, createHubCapForwardService as k, HUB_RSS_BUDGET_ENV as kt, EVENT_TOPIC_PREFIX as l, capActionSuffix as lt, setNodeEventInterest as m, serializeTypedArrays as mt, adaptBrokerToCluster as n, getWorkerNativeCapSnapshot as nt, getOrInitReadinessRegistry as o, validateProviderRegistrations as ot, registerEventBusService as p, deserializeTypedArrays as pt, UdsLocalTransportServer as q, createAddonContext as r, mountNativeCapService as rt, getOrInitReadinessRegistryForClient as s, NATIVE_PROVIDER_SERVICE_INFIX as st, installManifestPythonDeps as t, getWorkerNativeCapProvider as tt, clusterEventTopic as u, capBareAction as ut, resolveHwAccel as v, copyBundledNativeModules as vt, buildLinkChain as w, HEAP_RECLAIM_MIN_INTERVAL_MS as wt, getCapUsageRegistry as x, resolveNpmInvocation as xt, CapUsageRegistry as y, installManifestNativeDeps as yt, AGENT_CAP_FWD_ACTION as z, parseRssBudgetMb as zt };

package/dist/{manifest-python-deps-GjlyPjm0.js → manifest-python-deps-FYZBHc3v.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-require("./dist-BVU5JADq.js");
+require("./dist-Dl6MFXPr.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto);
 let _camstack_types_node = require("@camstack/types/node");
@@ -266,6 +266,22 @@ var consoleSink = {
 * 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.
 */
 function strandedMb(s) {
 	return s.rssMb - s.heapUsedMb - s.externalMb;
@@ -274,6 +290,67 @@ function strandedMb(s) {
 function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
 	return strandedMb(s) > triggerMb;
 }
+/** Share of RSS, as a whole percent. Never divides by zero. */
+function share(partMb, rssMb) {
+	return rssMb > 0 ? Math.round(partMb / rssMb * 100) : 0;
+}
+/**
+* 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.
+*/
+function describeRss(s, budgetMb) {
+	const nativeResidueMb = Math.max(0, strandedMb(s));
+	const shape = s.heapUsedMb >= s.externalMb && s.heapUsedMb >= nativeResidueMb ? "v8-heap" : s.externalMb >= nativeResidueMb ? "external" : "native-residue";
+	return {
+		rssMb: s.rssMb,
+		budgetMb,
+		overMb: Math.max(0, s.rssMb - budgetMb),
+		heapUsedMb: s.heapUsedMb,
+		externalMb: s.externalMb,
+		nativeResidueMb,
+		arrayBuffersMb: s.arrayBuffersMb,
+		shape
+	};
+}
+/** What the operator can actually DO about each shape. */
+var SHAPE_ADVICE = {
+	"v8-heap": "live JS retainers — bounded by --max-old-space-size; the fix is the retained set",
+	external: "Buffers / native external — NO V8 flag bounds this, and the old-space ceiling never will",
+	"native-residue": "freed native memory the allocator has not returned — MALLOC_ARENA_MAX/VIPS_CONCURRENCY are already applied, so this lever is spent"
+};
+/**
+* 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.
+*/
+var RSS_BUDGET_RELEASE_RATIO = .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.
+*/
+var RSS_BUDGET_REANNOUNCE_MIN_MS = 9e5;
+/**
+* The alarm state machine, pure so the thresholds are testable without
+* allocating five gigabytes to reach them.
+*/
+function nextRssBudgetState(current, rssMb, budgetMb, releaseRatio = RSS_BUDGET_RELEASE_RATIO) {
+	if (current === "over") return rssMb < budgetMb * releaseRatio ? "within" : "over";
+	return rssMb > budgetMb ? "over" : "within";
+}
 function isGcFunction(value) {
 	return typeof value === "function";
 }
@@ -301,8 +378,19 @@ function createV8Reclaimer() {
 		return;
 	}
 }
-function format(label, s, loop) {
-	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
+/**
+* The line that says HOW the process grew, not merely that it did.
+*
+* `heapUsed`, `external` and the native residue each carry their share of RSS,
+* because the shares are what separate the three fixes — and on the process this
+* module failed to catch, the shares were 9% / 74% / 16%, which names the answer
+* on sight.
+*/
+function formatOverBudget(label, b, source) {
+	return `[mem] ${label} OVER RSS BUDGET rss=${b.rssMb}MB budget=${b.budgetMb}MB over=+${b.overMb}MB shape=${b.shape} heapUsed=${b.heapUsedMb}MB(${share(b.heapUsedMb, b.rssMb)}%) external=${b.externalMb}MB(${share(b.externalMb, b.rssMb)}%) nativeResidue=${b.nativeResidueMb}MB(${share(b.nativeResidueMb, b.rssMb)}%) arrayBuffers=${b.arrayBuffersMb}MB budgetFrom="${source}" — ${SHAPE_ADVICE[b.shape]}`;
+}
+function format(label, s, loop, budgetMb) {
+	const line = `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB` + (budgetMb === void 0 ? "" : ` rssBudget=${budgetMb}MB`);
 	if (loop === void 0) return line;
 	return `${line} loopP50=${loop.p50Ms}ms loopP99=${loop.p99Ms}ms loopMax=${loop.maxMs}ms`;
 }
@@ -312,7 +400,7 @@ function format(label, s, loop) {
 * `unref`ed so it can never hold the process open, and every read is wrapped:
 * a diagnostic that can crash the process it watches is worse than none.
 */
-function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions, loopDelay = createLoopDelayMeter(), execArgv = process.execArgv, announceCeilingOrigin = true, rssBudget) {
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1024;
@@ -356,6 +444,39 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	};
 	let mode = "steady";
 	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	const budgetMb = rssBudget?.budgetMb !== void 0 && rssBudget.budgetMb > 0 ? rssBudget.budgetMb : void 0;
+	const budgetSource = rssBudget?.source ?? "unspecified";
+	const releaseRatio = rssBudget?.releaseRatio ?? .9;
+	const reannounceMinMs = rssBudget?.reannounceMinMs ?? 9e5;
+	let budgetState = "within";
+	let lastBudgetWarnAt = Number.NEGATIVE_INFINITY;
+	/** Only pair a "back within" with an over-budget line that was actually said. */
+	let overBudgetAnnounced = false;
+	/**
+	* One line per STATE CHANGE, never one per sample.
+	*
+	* The probe runs every {@link HEAP_WATCH_FAST_INTERVAL_MS}; warning on every
+	* sample above the budget would put 30 lines a minute in the hub's shared log
+	* for a process that is legitimately, steadily large. That is precisely the
+	* failure mode that buried two real alarms under 83,198 heartbeat lines on
+	* 2026-08-27, so the crossing is the event and the level is not.
+	*/
+	const checkRssBudget = (sample, at) => {
+		if (budgetMb === void 0) return;
+		const previous = budgetState;
+		budgetState = nextRssBudgetState(previous, sample.rssMb, budgetMb, releaseRatio);
+		if (budgetState === previous) return;
+		if (budgetState === "over") {
+			if (at - lastBudgetWarnAt < reannounceMinMs) return;
+			lastBudgetWarnAt = at;
+			overBudgetAnnounced = true;
+			sink.warn(formatOverBudget(label, describeRss(sample, budgetMb), budgetSource));
+			return;
+		}
+		if (!overBudgetAnnounced) return;
+		overBudgetAnnounced = false;
+		sink.info(`[mem] ${label} back within its RSS budget — rss=${sample.rssMb}MB budget=${budgetMb}MB`);
+	};
 	/**
 	* PROBING and LOGGING are separate cadences, and that separation is the whole
 	* point.
@@ -381,18 +502,20 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 			const due = at - lastLoggedAt >= intervalMs;
 			if (mode === "escalated" || due) {
 				lastLoggedAt = at;
-				const line = format(label, sample, loopDelay?.read());
+				const line = format(label, sample, loopDelay?.read(), budgetMb);
 				if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 				else if (mode === "escalated") sink.warn(`${line} — heap elevated, sampling every ${probeIntervalMs}ms`);
 				else sink.info(line);
 			}
 			if (previous === "escalated" && mode === "steady") sink.info(`[mem] ${label} heap back to routine — logging every ${intervalMs}ms`);
+			checkRssBudget(sample, at);
 			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
+	if (rssBudget !== void 0 && budgetMb === void 0) sink.info(`[mem] ${label} is NOT WATCHED against an RSS budget — no budget declared (${budgetSource}). rss growth outside the V8 heap raises nothing here: --max-old-space-size bounds old space only, and stranded subtracts external by construction. Declare execution.rssBudgetMb once this process has a measured working set.`);
 	if (announceCeilingOrigin && heapCeilingOrigin(execArgv) === "v8-default") sink.info(`[mem] ${label} heap ceiling is V8's DEFAULT (${read().heapLimitMb}MB) — no --max-old-space-size on argv. Nothing here CHOSE that number; it is derived from host RAM and moves with it.`);
 	let stopped = false;
 	return () => {
@@ -418,6 +541,71 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 */
 var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 /**
+* 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.
+*/
+function parseRssBudgetMb(raw) {
+	if (raw === void 0) return void 0;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+	return Math.floor(parsed);
+}
+/** Env var carrying a runner's declared RSS budget from parent to child. */
+var RUNNER_RSS_BUDGET_ENV = "CAMSTACK_RUNNER_RSS_BUDGET_MB";
+/** Operator override for hub-main's budget, applied without a release. */
+var 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.
+*/
+var HUB_MAIN_RSS_BUDGET_MB = 4096;
+/** hub-main's budget: the declared number, or the operator's override. */
+function hubMainRssBudget(env = process.env) {
+	const override = env[HUB_RSS_BUDGET_ENV];
+	if (override !== void 0) return {
+		budgetMb: parseRssBudgetMb(override),
+		source: HUB_RSS_BUDGET_ENV
+	};
+	return {
+		budgetMb: HUB_MAIN_RSS_BUDGET_MB,
+		source: "HUB_MAIN_RSS_BUDGET_MB (kernel/heap-watch)"
+	};
+}
+/**
 * 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.
 *
@@ -451,13 +639,17 @@ var RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 function startRunnerHeapWatch(options) {
 	if (options.heapProfile !== "heavy") return void 0;
 	const intervalMs = options.intervalMs ?? 3e5;
-	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false);
+	const rssBudget = {
+		budgetMb: parseRssBudgetMb(options.rssBudgetMb),
+		source: `manifest execution.rssBudgetMb (via ${RUNNER_RSS_BUDGET_ENV})`
+	};
+	if (options.reclaimSwitch === "off") return startHeapWatch(options.label, options.sink, intervalMs, void 0, void 0, void 0, false, rssBudget);
 	let reclaimOptions = options.reclaimOptions;
 	if (reclaimOptions === void 0) {
 		const reclaimer = createV8Reclaimer();
 		reclaimOptions = reclaimer === void 0 ? void 0 : { reclaim: reclaimer };
 	}
-	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true);
+	return startHeapWatch(options.label, options.sink, intervalMs, reclaimOptions, void 0, void 0, true, rssBudget);
 }
 //#endregion
 //#region src/kernel/moleculer/addon-data-plane-facility.ts
@@ -8496,6 +8688,18 @@ Object.defineProperty(exports, "HUB_CAP_FWD_SERVICE", {
 		return HUB_CAP_FWD_SERVICE;
 	}
 });
+Object.defineProperty(exports, "HUB_MAIN_RSS_BUDGET_MB", {
+	enumerable: true,
+	get: function() {
+		return HUB_MAIN_RSS_BUDGET_MB;
+	}
+});
+Object.defineProperty(exports, "HUB_RSS_BUDGET_ENV", {
+	enumerable: true,
+	get: function() {
+		return HUB_RSS_BUDGET_ENV;
+	}
+});
 Object.defineProperty(exports, "LocalChildClient", {
 	enumerable: true,
 	get: function() {
@@ -8514,12 +8718,30 @@ Object.defineProperty(exports, "NATIVE_PROVIDER_SERVICE_INFIX", {
 		return NATIVE_PROVIDER_SERVICE_INFIX;
 	}
 });
+Object.defineProperty(exports, "RSS_BUDGET_REANNOUNCE_MIN_MS", {
+	enumerable: true,
+	get: function() {
+		return RSS_BUDGET_REANNOUNCE_MIN_MS;
+	}
+});
+Object.defineProperty(exports, "RSS_BUDGET_RELEASE_RATIO", {
+	enumerable: true,
+	get: function() {
+		return RSS_BUDGET_RELEASE_RATIO;
+	}
+});
 Object.defineProperty(exports, "RUNNER_HEAP_WATCH_INTERVAL_MS", {
 	enumerable: true,
 	get: function() {
 		return RUNNER_HEAP_WATCH_INTERVAL_MS;
 	}
 });
+Object.defineProperty(exports, "RUNNER_RSS_BUDGET_ENV", {
+	enumerable: true,
+	get: function() {
+		return RUNNER_RSS_BUDGET_ENV;
+	}
+});
 Object.defineProperty(exports, "SocketChannel", {
 	enumerable: true,
 	get: function() {
@@ -8724,6 +8946,12 @@ Object.defineProperty(exports, "createV8Reclaimer", {
 		return createV8Reclaimer;
 	}
 });
+Object.defineProperty(exports, "describeRss", {
+	enumerable: true,
+	get: function() {
+		return describeRss;
+	}
+});
 Object.defineProperty(exports, "deserializeTypedArrays", {
 	enumerable: true,
 	get: function() {
@@ -8784,6 +9012,12 @@ Object.defineProperty(exports, "getWorkerNativeCapSnapshot", {
 		return getWorkerNativeCapSnapshot;
 	}
 });
+Object.defineProperty(exports, "hubMainRssBudget", {
+	enumerable: true,
+	get: function() {
+		return hubMainRssBudget;
+	}
+});
 Object.defineProperty(exports, "installManifestNativeDeps", {
 	enumerable: true,
 	get: function() {
@@ -8820,12 +9054,24 @@ Object.defineProperty(exports, "mountNativeCapService", {
 		return mountNativeCapService;
 	}
 });
+Object.defineProperty(exports, "nextRssBudgetState", {
+	enumerable: true,
+	get: function() {
+		return nextRssBudgetState;
+	}
+});
 Object.defineProperty(exports, "parseCapAction", {
 	enumerable: true,
 	get: function() {
 		return parseCapAction;
 	}
 });
+Object.defineProperty(exports, "parseRssBudgetMb", {
+	enumerable: true,
+	get: function() {
+		return parseRssBudgetMb;
+	}
+});
 Object.defineProperty(exports, "registerEventBusService", {
 	enumerable: true,
 	get: function() {