@camstack/system 1.2.59 → 1.2.61

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { startHeapWatch, buildHeapSample, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, } from './kernel/heap-watch.js';
-export type { HeapSample, HeapWatchSink } from './kernel/heap-watch.js';
+export { startHeapWatch, buildHeapSample, createV8Reclaimer, shouldReclaim, strandedMb, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HEAP_RECLAIM_TRIGGER_MB, HEAP_RECLAIM_MIN_INTERVAL_MS, } from './kernel/heap-watch.js';
+export type { HeapSample, HeapWatchSink, HeapReclaimer, HeapReclaimOptions, } from './kernel/heap-watch.js';
 export { ensureBinary, downloadBinary, findInPath, getPlatformInfo, buildBinaryPath, ensureFfmpeg, getFfmpegDownloadUrl, ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from '@camstack/types/node';
 export type { PlatformInfo } from '@camstack/types/node';
 export { ALL_CAPABILITY_DEFINITIONS, METHOD_ACCESS_MAP, expandCapMethods, isArrayOutputSchema, isCollectionArrayMethod, addonSettingsCapability, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, } from '@camstack/types';

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-CV6XTApk.js");
+const require_dist = require("./dist-BN681PgO.js");
 const require_model_download_service = require("./model-download-service-Cpc6SWzV.js");
 const require_manifest_python_deps = require("./manifest-python-deps-d4acYXVV.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
@@ -30,6 +30,8 @@ require("./builtins/device-manager/index.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let node_v8 = require("node:v8");
 node_v8 = require_chunk.__toESM(node_v8);
+let node_vm = require("node:vm");
+node_vm = require_chunk.__toESM(node_vm);
 let _camstack_types_node = require("@camstack/types/node");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
@@ -43,8 +45,6 @@ let _camstack_types_addon = require("@camstack/types/addon");
 let node_child_process = require("node:child_process");
 let node_util = require("node:util");
 node_util = require_chunk.__toESM(node_util);
-let node_vm = require("node:vm");
-node_vm = require_chunk.__toESM(node_vm);
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_fs_promises = require("node:fs/promises");
@@ -60,13 +60,15 @@ path = require_chunk.__toESM(path, 1);
 let module$1 = require("module");
 //#region src/kernel/heap-watch.ts
 /**
-* heap-watch — hub-main's own memory, on the record.
+* heap-watch — hub-main's own memory, on the record, and returned to the OS.
 *
 * ## Why this exists
 *
-* hub-main is launched with `--max-old-space-size=1536` (docker-entrypoint) and
-* has logged NOTHING about its own heap. When it died on 2026-08-01/02 the only
-* trace was V8's own stderr line:
+* hub-main used to be launched with `--max-old-space-size=1536` (docker-entrypoint;
+* the cap was removed on 2026-08-02, so the live ceiling is now V8's own default —
+* 4288MB in this container — and this module reads it at runtime rather than
+* assuming a number). It logged NOTHING about its own heap. When it died on
+* 2026-08-01/02 the only trace was V8's own stderr line:
 *
 *     FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 *
@@ -94,6 +96,41 @@ let module$1 = require("module");
 * `--max-old-space-size` and are most of the gap between a 1.5GB cap and the
 * ~2.05GB RSS observed live: a diagnosis that only looks at the JS heap
 * misreads that process by 500MB.
+*
+* ## And then the heartbeat explained the "off-heap leak", which was not one
+*
+* 2026-08-08, measured on the live hub over 1019 consecutive samples and seven
+* separate boots: **hub-main's RSS is a HIGH-WATER MARK, not a leak.** In every
+* one of those 1019 samples RSS was >= the running maximum of
+* `heapTotal + external`, never once below it, and
+* `RSS_peak - peak(heapTotal + external)` landed between 874MB and 1639MB on
+* every boot — a roughly constant native floor on top of a number that only
+* ever goes up. RSS tracked the highest point the process ever reached and
+* stayed there: 3.3GB -> 4.5GB -> 5.2GB, and 7.8GB on the worst boot.
+*
+* Two things push that peak, and neither is a retained object:
+*
+*  - the JS heap sawtooths to 2.0-2.8GB because the ceiling is 4288MB and
+*    nothing creates pressure before then;
+*  - `arrayBuffers` accumulates DEAD Buffers — up to 3.65GB — because V8 only
+*    sweeps them on a major GC. Eleven collapses were captured, and every
+*    single one coincides with `heapUsed` dropping to its ~650MB floor. No code
+*    released a reference at 13:23:03; a mark-compact ran.
+*
+* At the peak V8 has committed the pages, and **an ordinary major GC does not
+* give them back.** Proven on the production hub: `smaps` showed 10,819 mapped
+* 256KB pages (V8's `kRegularPageSize`) holding 2704MB while V8 itself reported
+* `total_physical_size` of only 846MB — ~7,800 pages committed, resident, and
+* outside V8's own accounting. One `gc({ flavor: 'last-resort' })` took 417ms
+* and returned RSS 3355MB -> 1237MB, pages 10,819 -> 2,963.
+*
+* So the fix for the "~3GB/2h off-heap growth" is not a retainer hunt. It is to
+* ask V8 for the pages back when the process is visibly holding more than it is
+* using — which is what `shouldReclaim` decides and what the heartbeat now does.
+*
+* The cost is a 250-450ms stop-the-world on the hub's router process, bounded to
+* once per `HEAP_RECLAIM_MIN_INTERVAL_MS`. The alternative, measured, is a
+* ratchet to 7.8GB and the OOM that ends it.
 */
 /** Heartbeat period. Slow enough to be free, fast enough that the sample before
 *  a fatal is recent. */
@@ -101,6 +138,20 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
+/**
+* Reclaim once the process holds this many MB beyond what it is USING.
+*
+* Live calibration, both readings from the same hub minutes apart: 2491MB
+* stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+* native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+* collecting against it would buy nothing and cost a stall every minute. 1536
+* sits clear of that floor and still fires ~1.1GB before the ratchet is worth
+* anything, so it triggers on the real condition and stops as soon as it is fixed.
+*/
+var HEAP_RECLAIM_TRIGGER_MB = 1536;
+/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
+*  minutes keeps the worst case under 0.1% of the router's time. */
+var HEAP_RECLAIM_MIN_INTERVAL_MS = 6e5;
 var MB = (bytes) => Math.round(bytes / 1048576);
 /**
 * Build a sample from raw readings. Pure so the thresholds are testable without
@@ -123,6 +174,47 @@ var consoleSink = {
 	info: (line) => console.log(line),
 	warn: (line) => console.warn(line)
 };
+/**
+* RSS the process is holding but not using.
+*
+* 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.
+*/
+function strandedMb(s) {
+	return s.rssMb - s.heapUsedMb - s.externalMb;
+}
+/** Whether it is worth paying a stop-the-world to get those pages back. */
+function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
+	return strandedMb(s) > triggerMb;
+}
+function isGcFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Build the reclaimer without requiring `--expose-gc` on argv.
+*
+* The flag is turned on, the function captured, and the flag turned straight
+* back off — a global `gc` left reachable by application code is a footgun, and
+* requiring an argv change would mean this cannot ship without a new image.
+* Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+*
+* Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+*/
+function createV8Reclaimer() {
+	try {
+		node_v8.setFlagsFromString("--expose-gc");
+		const gc = node_vm.runInNewContext("gc");
+		node_v8.setFlagsFromString("--no-expose-gc");
+		if (!isGcFunction(gc)) return void 0;
+		return () => gc({
+			execution: "sync",
+			flavor: "last-resort"
+		});
+	} catch {
+		return;
+	}
+}
 function format$1(label, s) {
 	return `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
 }
@@ -132,13 +224,38 @@ function format$1(label, s) {
 * `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) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions) {
+	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
+	const now = reclaimOptions?.now ?? (() => Date.now());
+	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
+	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	let lastReclaimAt = Number.NEGATIVE_INFINITY;
+	const read = () => {
+		const limit = reclaimOptions?.heapLimitBytes ?? node_v8.getHeapStatistics().heap_size_limit;
+		return buildHeapSample(readMemory(), limit);
+	};
+	const maybeReclaim = (sample) => {
+		if (reclaimOptions === void 0) return;
+		if (!shouldReclaim(sample, triggerMb)) return;
+		if (now() - lastReclaimAt < minIntervalMs) return;
+		lastReclaimAt = now();
+		const startedAt = now();
+		try {
+			reclaimOptions.reclaim();
+		} catch (error) {
+			sink.warn(`[mem] reclaim failed — ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+		const after = read();
+		sink.info(`[mem] reclaim ${label} stranded=${strandedMb(sample)}MB rss=${sample.rssMb}MB→${after.rssMb}MB freed=${sample.rssMb - after.rssMb}MB arrayBuffers=${sample.arrayBuffersMb}MB→${after.arrayBuffersMb}MB took=${now() - startedAt}ms`);
+	};
 	const tick = () => {
 		try {
-			const sample = buildHeapSample(process.memoryUsage(), node_v8.getHeapStatistics().heap_size_limit);
+			const sample = read();
 			const line = format$1(label, sample);
 			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 			else sink.info(line);
+			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, intervalMs);
@@ -94566,6 +94683,8 @@ exports.FsStorageBackend = FsStorageBackend;
 exports.HEALTH_MONITOR_GRACE_PERIOD_MS = HEALTH_MONITOR_GRACE_PERIOD_MS;
 exports.HEALTH_MONITOR_RETRY_INTERVALS_MS = HEALTH_MONITOR_RETRY_INTERVALS_MS;
 exports.HEALTH_MONITOR_TICK_MS = HEALTH_MONITOR_TICK_MS;
+exports.HEAP_RECLAIM_MIN_INTERVAL_MS = HEAP_RECLAIM_MIN_INTERVAL_MS;
+exports.HEAP_RECLAIM_TRIGGER_MB = HEAP_RECLAIM_TRIGGER_MB;
 exports.HEAP_WATCH_INTERVAL_MS = HEAP_WATCH_INTERVAL_MS;
 exports.HEAP_WATCH_WARN_RATIO = HEAP_WATCH_WARN_RATIO;
 exports.HUB_CAP_FWD_ACTION = require_manifest_python_deps.HUB_CAP_FWD_ACTION;
@@ -94687,6 +94806,7 @@ exports.createUdsEventBridge = require_manifest_python_deps.createUdsEventBridge
 exports.createUdsEventBus = require_manifest_python_deps.createUdsEventBus;
 exports.createUdsLogger = require_manifest_python_deps.createUdsLogger;
 exports.createUdsLoggerWithControl = require_manifest_python_deps.createUdsLoggerWithControl;
+exports.createV8Reclaimer = createV8Reclaimer;
 exports.deleteModelFromDisk = require_model_download_service.deleteModelFromDisk;
 exports.deriveAgentListenPort = deriveAgentListenPort;
 exports.describeProviderKindDrift = describeProviderKindDrift;
@@ -94809,7 +94929,9 @@ exports.scopesAllowDeviceCap = scopesAllowDeviceCap;
 exports.serializeTypedArrays = require_manifest_python_deps.serializeTypedArrays;
 exports.setHubConnected = require_manifest_python_deps.setHubConnected;
 exports.setNodeEventInterest = require_manifest_python_deps.setNodeEventInterest;
+exports.shouldReclaim = shouldReclaim;
 exports.startHeapWatch = startHeapWatch;
+exports.strandedMb = strandedMb;
 exports.stripCamstackDeps = stripCamstackDeps;
 exports.subscribePassthrough = require_manifest_python_deps.subscribePassthrough;
 exports.udsChildLogToWorkerEntry = require_manifest_python_deps.udsChildLogToWorkerEntry;

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 procedureAuthKey, Ct as asJsonObject$1, Dt as emitDownForOwnedCaps, Et as createEvent, Ft as readinessKey, H as kebabToCamel, It as resolveCapMount, K as logLevelAtMost, L as isArrayOutputSchema, Lt as scopeKey, Nt as parseJsonObject, P as extractNestedAddonId, Pt as parseJsonUnknown$1, R as isCollectionArrayMethod, Tt as asString$1, U as lifecycleJobSchema, V as isVoidInput, X as objectInputDeclaresAddonId, bt as ReadinessRegistry, c as METHOD_ACCESS_MAP, ft as errMsg$1, gt as DEVICE_STATUS_METHOD, h as addonSettingsCapability, ht as DEVICE_SETTINGS_CONTRIBUTION_METHODS, kt as expandCapMethods, l as RUNTIME_DEFAULTS, mt as DATAPLANE_SECRET_HEADER$1, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, wt as asNumber, xt as ReadinessTimeoutError, z as isObjectInput, zt as EventCategory$1 } from "./dist-BqJJWCS8.mjs";
+import { $ as procedureAuthKey, Ct as asJsonObject$1, Dt as emitDownForOwnedCaps, Et as createEvent, Ft as readinessKey, H as kebabToCamel, It as resolveCapMount, K as logLevelAtMost, L as isArrayOutputSchema, Lt as scopeKey, Nt as parseJsonObject, P as extractNestedAddonId, Pt as parseJsonUnknown$1, R as isCollectionArrayMethod, Tt as asString$1, U as lifecycleJobSchema, V as isVoidInput, X as objectInputDeclaresAddonId, bt as ReadinessRegistry, c as METHOD_ACCESS_MAP, ft as errMsg$1, gt as DEVICE_STATUS_METHOD, h as addonSettingsCapability, ht as DEVICE_SETTINGS_CONTRIBUTION_METHODS, kt as expandCapMethods, l as RUNTIME_DEFAULTS, mt as DATAPLANE_SECRET_HEADER$1, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, wt as asNumber, xt as ReadinessTimeoutError, z as isObjectInput, zt as EventCategory$1 } from "./dist-L6QPJWsr.mjs";
 import { a as downloadModel, c as getModelFilePath, d as contentTypeFor, f as createAuthenticatedFileServer, h as resolveFilePath, i as downloadFile, l as isModelDownloaded, m as parseTokenizedUrl, n as collectModelFiles, o as ensureModel, p as parseRangeHeader, r as deleteModelFromDisk, s as fetchJson, t as ModelDownloadService, u as createFileDataPlaneHandler } from "./model-download-service-D8B-4ktF.mjs";
 import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as resolveAddonClass, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as runNpm, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveNpmInvocation, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-CX5tGRqf.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BkP504Vq.mjs";
@@ -28,6 +28,7 @@ import { DeviceManagerAddon } from "./builtins/device-manager/device-manager.add
 import "./builtins/device-manager/index.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import * as v8 from "node:v8";
+import * as vm from "node:vm";
 import { PYTHON_VERSION, buildBinaryPath, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
 import { z } from "zod";
 import { X509Certificate, createHash, randomUUID, timingSafeEqual } from "node:crypto";
@@ -40,7 +41,6 @@ import { asJsonObject, errMsg, parseJsonUnknown } from "@camstack/types/addon";
 import { execFile, spawn } from "node:child_process";
 import * as util$10 from "node:util";
 import { promisify } from "node:util";
-import * as vm from "node:vm";
 import * as os$18 from "node:os";
 import { lstat, readdir, readlink, realpath } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -52,13 +52,15 @@ import "path";
 import { createRequire } from "module";
 //#region src/kernel/heap-watch.ts
 /**
-* heap-watch — hub-main's own memory, on the record.
+* heap-watch — hub-main's own memory, on the record, and returned to the OS.
 *
 * ## Why this exists
 *
-* hub-main is launched with `--max-old-space-size=1536` (docker-entrypoint) and
-* has logged NOTHING about its own heap. When it died on 2026-08-01/02 the only
-* trace was V8's own stderr line:
+* hub-main used to be launched with `--max-old-space-size=1536` (docker-entrypoint;
+* the cap was removed on 2026-08-02, so the live ceiling is now V8's own default —
+* 4288MB in this container — and this module reads it at runtime rather than
+* assuming a number). It logged NOTHING about its own heap. When it died on
+* 2026-08-01/02 the only trace was V8's own stderr line:
 *
 *     FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 *
@@ -86,6 +88,41 @@ import { createRequire } from "module";
 * `--max-old-space-size` and are most of the gap between a 1.5GB cap and the
 * ~2.05GB RSS observed live: a diagnosis that only looks at the JS heap
 * misreads that process by 500MB.
+*
+* ## And then the heartbeat explained the "off-heap leak", which was not one
+*
+* 2026-08-08, measured on the live hub over 1019 consecutive samples and seven
+* separate boots: **hub-main's RSS is a HIGH-WATER MARK, not a leak.** In every
+* one of those 1019 samples RSS was >= the running maximum of
+* `heapTotal + external`, never once below it, and
+* `RSS_peak - peak(heapTotal + external)` landed between 874MB and 1639MB on
+* every boot — a roughly constant native floor on top of a number that only
+* ever goes up. RSS tracked the highest point the process ever reached and
+* stayed there: 3.3GB -> 4.5GB -> 5.2GB, and 7.8GB on the worst boot.
+*
+* Two things push that peak, and neither is a retained object:
+*
+*  - the JS heap sawtooths to 2.0-2.8GB because the ceiling is 4288MB and
+*    nothing creates pressure before then;
+*  - `arrayBuffers` accumulates DEAD Buffers — up to 3.65GB — because V8 only
+*    sweeps them on a major GC. Eleven collapses were captured, and every
+*    single one coincides with `heapUsed` dropping to its ~650MB floor. No code
+*    released a reference at 13:23:03; a mark-compact ran.
+*
+* At the peak V8 has committed the pages, and **an ordinary major GC does not
+* give them back.** Proven on the production hub: `smaps` showed 10,819 mapped
+* 256KB pages (V8's `kRegularPageSize`) holding 2704MB while V8 itself reported
+* `total_physical_size` of only 846MB — ~7,800 pages committed, resident, and
+* outside V8's own accounting. One `gc({ flavor: 'last-resort' })` took 417ms
+* and returned RSS 3355MB -> 1237MB, pages 10,819 -> 2,963.
+*
+* So the fix for the "~3GB/2h off-heap growth" is not a retainer hunt. It is to
+* ask V8 for the pages back when the process is visibly holding more than it is
+* using — which is what `shouldReclaim` decides and what the heartbeat now does.
+*
+* The cost is a 250-450ms stop-the-world on the hub's router process, bounded to
+* once per `HEAP_RECLAIM_MIN_INTERVAL_MS`. The alternative, measured, is a
+* ratchet to 7.8GB and the OOM that ends it.
 */
 /** Heartbeat period. Slow enough to be free, fast enough that the sample before
 *  a fatal is recent. */
@@ -93,6 +130,20 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
+/**
+* Reclaim once the process holds this many MB beyond what it is USING.
+*
+* Live calibration, both readings from the same hub minutes apart: 2491MB
+* stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+* native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+* collecting against it would buy nothing and cost a stall every minute. 1536
+* sits clear of that floor and still fires ~1.1GB before the ratchet is worth
+* anything, so it triggers on the real condition and stops as soon as it is fixed.
+*/
+var HEAP_RECLAIM_TRIGGER_MB = 1536;
+/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
+*  minutes keeps the worst case under 0.1% of the router's time. */
+var HEAP_RECLAIM_MIN_INTERVAL_MS = 6e5;
 var MB = (bytes) => Math.round(bytes / 1048576);
 /**
 * Build a sample from raw readings. Pure so the thresholds are testable without
@@ -115,6 +166,47 @@ var consoleSink = {
 	info: (line) => console.log(line),
 	warn: (line) => console.warn(line)
 };
+/**
+* RSS the process is holding but not using.
+*
+* 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.
+*/
+function strandedMb(s) {
+	return s.rssMb - s.heapUsedMb - s.externalMb;
+}
+/** Whether it is worth paying a stop-the-world to get those pages back. */
+function shouldReclaim(s, triggerMb = HEAP_RECLAIM_TRIGGER_MB) {
+	return strandedMb(s) > triggerMb;
+}
+function isGcFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Build the reclaimer without requiring `--expose-gc` on argv.
+*
+* The flag is turned on, the function captured, and the flag turned straight
+* back off — a global `gc` left reachable by application code is a footgun, and
+* requiring an argv change would mean this cannot ship without a new image.
+* Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+*
+* Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+*/
+function createV8Reclaimer() {
+	try {
+		v8.setFlagsFromString("--expose-gc");
+		const gc = vm.runInNewContext("gc");
+		v8.setFlagsFromString("--no-expose-gc");
+		if (!isGcFunction(gc)) return void 0;
+		return () => gc({
+			execution: "sync",
+			flavor: "last-resort"
+		});
+	} catch {
+		return;
+	}
+}
 function format$1(label, s) {
 	return `[mem] ${label} rss=${s.rssMb}MB heapUsed=${s.heapUsedMb}MB heapTotal=${s.heapTotalMb}MB heapLimit=${s.heapLimitMb}MB used=${Math.round(s.usedRatio * 100)}% external=${s.externalMb}MB arrayBuffers=${s.arrayBuffersMb}MB`;
 }
@@ -124,13 +216,38 @@ function format$1(label, s) {
 * `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) {
+function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions) {
+	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
+	const now = reclaimOptions?.now ?? (() => Date.now());
+	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
+	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	let lastReclaimAt = Number.NEGATIVE_INFINITY;
+	const read = () => {
+		const limit = reclaimOptions?.heapLimitBytes ?? v8.getHeapStatistics().heap_size_limit;
+		return buildHeapSample(readMemory(), limit);
+	};
+	const maybeReclaim = (sample) => {
+		if (reclaimOptions === void 0) return;
+		if (!shouldReclaim(sample, triggerMb)) return;
+		if (now() - lastReclaimAt < minIntervalMs) return;
+		lastReclaimAt = now();
+		const startedAt = now();
+		try {
+			reclaimOptions.reclaim();
+		} catch (error) {
+			sink.warn(`[mem] reclaim failed — ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+		const after = read();
+		sink.info(`[mem] reclaim ${label} stranded=${strandedMb(sample)}MB rss=${sample.rssMb}MB→${after.rssMb}MB freed=${sample.rssMb - after.rssMb}MB arrayBuffers=${sample.arrayBuffersMb}MB→${after.arrayBuffersMb}MB took=${now() - startedAt}ms`);
+	};
 	const tick = () => {
 		try {
-			const sample = buildHeapSample(process.memoryUsage(), v8.getHeapStatistics().heap_size_limit);
+			const sample = read();
 			const line = format$1(label, sample);
 			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
 			else sink.info(line);
+			maybeReclaim(sample);
 		} catch {}
 	};
 	const timer = setInterval(tick, intervalMs);
@@ -94510,4 +94627,4 @@ var LifecycleJobEngine = class {
 	}
 };
 //#endregion
-export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_WATCH_INTERVAL_MS, HEAP_WATCH_WARN_RATIO, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, startHeapWatch, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };
+export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CoreBlocksAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HEAP_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, LifecycleJobEngine, LifecycleStateMachine, LivenessMonitorAddon, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, LokiDestination, LokiLoggingAddon, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildHeapSample, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, createV8Reclaimer, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, shouldReclaim, startHeapWatch, strandedMb, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };

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

@@ -4,6 +4,20 @@ export declare const HEAP_WATCH_INTERVAL_MS = 60000;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
  *  the fatal by more than one interval under realistic growth. */
 export declare const HEAP_WATCH_WARN_RATIO = 0.8;
+/**
+ * Reclaim once the process holds this many MB beyond what it is USING.
+ *
+ * Live calibration, both readings from the same hub minutes apart: 2491MB
+ * stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+ * native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+ * collecting against it would buy nothing and cost a stall every minute. 1536
+ * sits clear of that floor and still fires ~1.1GB before the ratchet is worth
+ * anything, so it triggers on the real condition and stops as soon as it is fixed.
+ */
+export declare const HEAP_RECLAIM_TRIGGER_MB = 1536;
+/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
+ *  minutes keeps the worst case under 0.1% of the router's time. */
+export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 600000;
 export interface HeapSample {
     readonly rssMb: number;
     readonly heapUsedMb: number;
@@ -27,10 +41,43 @@ export interface HeapWatchSink {
     readonly info: (line: string) => void;
     readonly warn: (line: string) => void;
 }
+/**
+ * RSS the process is holding but not using.
+ *
+ * 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.
+ */
+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;
+/** A full collection that also asks V8 to hand the pages back to the OS. */
+export type HeapReclaimer = () => void;
+/**
+ * Build the reclaimer without requiring `--expose-gc` on argv.
+ *
+ * The flag is turned on, the function captured, and the flag turned straight
+ * back off — a global `gc` left reachable by application code is a footgun, and
+ * requiring an argv change would mean this cannot ship without a new image.
+ * Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+ *
+ * Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+ */
+export declare function createV8Reclaimer(): HeapReclaimer | undefined;
+/** Wiring for the reclaim pass. `readMemory`/`heapLimitBytes` exist so a test
+ *  can reach a gigabyte-scale state without allocating one. */
+export interface HeapReclaimOptions {
+    readonly reclaim: HeapReclaimer;
+    readonly readMemory?: () => NodeJS.MemoryUsage;
+    readonly heapLimitBytes?: number;
+    readonly triggerMb?: number;
+    readonly minIntervalMs?: number;
+    readonly now?: () => 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): () => void;
+export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number, reclaimOptions?: HeapReclaimOptions): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.59",
+  "version": "1.2.61",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",