@camstack/system 1.2.63 → 1.2.64

package/dist/{dist-BJ2w3uoN.mjs → dist-CMb7aKS0.mjs}

@@ -19525,7 +19525,29 @@ var FaceInfoSchema = z.object({
 	recognizedIdentityId: z.string().optional(),
 	identityName: z.string().optional(),
 	assigned: z.boolean(),
+	/**
+	* The crop, inline, base64.
+	*
+	* **Prefer {@link cropUrl}.** At the 500 rows the Faces view asks for this
+	* field alone is ~2.87 MiB, re-sent in full on every operator assign and
+	* every 30 s poll, base64-inflated over the msgpack socket and held in the
+	* query heap. It stays for callers that have not migrated; `includeCrops:
+	* false` turns it off once they have.
+	*/
 	base64: z.string().optional(),
+	/**
+	* Same crop, as a data-plane URL for `<img src>` — the move the admin
+	* snapshot surfaces made on 2026-08-08.
+	*
+	* Served by the `event-media` plane, which resolves a raw MediaStore key and
+	* is `access: 'authenticated'`: a bare `<img>` carries the `camstack_session`
+	* cookie, so no header plumbing is needed. The bytes then ride the browser's
+	* HTTP cache with an ETag and `immutable`, instead of the WebSocket.
+	*
+	* Absent when the face has no stored crop, or when the addon has no data
+	* plane — callers fall back to {@link base64}.
+	*/
+	cropUrl: z.string().optional(),
 	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
 	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
 	*  legacy rows written before design B. */
@@ -19601,7 +19623,23 @@ var faceGalleryCapability = {
 		}),
 		listRecentFaces: method(z.object({
 			limit: z.number().int().positive().optional(),
-			filter: FaceFilterEnum.optional()
+			filter: FaceFilterEnum.optional(),
+			/**
+			* Inline the base64 crop on every row. Default `true` — the existing
+			* behaviour, kept so no caller breaks.
+			*
+			* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
+			* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
+			* the browser cache the images.
+			*
+			* **This is an INPUT field, so it does not reach the addon until the
+			* next train.** The hub router validates cap inputs against its own
+			* compiled Zod, which strips a key it does not know — verified today
+			* on the OUTPUT side, where an additive field DOES arrive immediately
+			* (`Track.hasFace`). Until the train ships, sending `false` is
+			* harmless and simply keeps the crops inline.
+			*/
+			includeCrops: z.boolean().optional()
 		}).optional(), z.array(FaceInfoSchema).readonly()),
 		getFaceByTrack: method(z.object({
 			deviceId: z.number().int(),

package/dist/{dist-LDrOFrd-.js → dist-DP3nHlNM.js}

@@ -19525,7 +19525,29 @@ var FaceInfoSchema = zod.z.object({
 	recognizedIdentityId: zod.z.string().optional(),
 	identityName: zod.z.string().optional(),
 	assigned: zod.z.boolean(),
+	/**
+	* The crop, inline, base64.
+	*
+	* **Prefer {@link cropUrl}.** At the 500 rows the Faces view asks for this
+	* field alone is ~2.87 MiB, re-sent in full on every operator assign and
+	* every 30 s poll, base64-inflated over the msgpack socket and held in the
+	* query heap. It stays for callers that have not migrated; `includeCrops:
+	* false` turns it off once they have.
+	*/
 	base64: zod.z.string().optional(),
+	/**
+	* Same crop, as a data-plane URL for `<img src>` — the move the admin
+	* snapshot surfaces made on 2026-08-08.
+	*
+	* Served by the `event-media` plane, which resolves a raw MediaStore key and
+	* is `access: 'authenticated'`: a bare `<img>` carries the `camstack_session`
+	* cookie, so no header plumbing is needed. The bytes then ride the browser's
+	* HTTP cache with an ETag and `immutable`, instead of the WebSocket.
+	*
+	* Absent when the face has no stored crop, or when the addon has no data
+	* plane — callers fall back to {@link base64}.
+	*/
+	cropUrl: zod.z.string().optional(),
 	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
 	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
 	*  legacy rows written before design B. */
@@ -19601,7 +19623,23 @@ var faceGalleryCapability = {
 		}),
 		listRecentFaces: method(zod.z.object({
 			limit: zod.z.number().int().positive().optional(),
-			filter: FaceFilterEnum.optional()
+			filter: FaceFilterEnum.optional(),
+			/**
+			* Inline the base64 crop on every row. Default `true` — the existing
+			* behaviour, kept so no caller breaks.
+			*
+			* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
+			* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
+			* the browser cache the images.
+			*
+			* **This is an INPUT field, so it does not reach the addon until the
+			* next train.** The hub router validates cap inputs against its own
+			* compiled Zod, which strips a key it does not know — verified today
+			* on the OUTPUT side, where an additive field DOES arrive immediately
+			* (`Track.hasFace`). Until the train ships, sending `false` is
+			* harmless and simply keeps the crops inline.
+			*/
+			includeCrops: zod.z.boolean().optional()
 		}).optional(), zod.z.array(FaceInfoSchema).readonly()),
 		getFaceByTrack: method(zod.z.object({
 			deviceId: zod.z.number().int(),

package/dist/http/asset-compression.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Content-coding for addon-served static assets: `Accept-Encoding` negotiation,
+ * an eligibility rule, and a BOUNDED cache of the compressed bytes.
+ *
+ * ## Why the ADDON owns the encoding
+ *
+ * The hub's `/addon/:addonId/*` bridge is registered `{ compress: false }`. That
+ * is not an oversight — on 2026-07-16 the global `@fastify/compress` was found
+ * emitting an EMPTY brotli stream (`content-encoding: br`, `content-length: 0`)
+ * for any compressible body over its 1 KiB threshold once the body had crossed
+ * the UDS route bridge of a FORKED addon. It silently broke the notifier SVG
+ * icons; the deploy-bundle pull route had already dodged the same class with
+ * `compress: false`. The resolution then, and the contract now, is that an addon
+ * route owns its content-coding END TO END: it negotiates, it compresses, it
+ * stamps `content-encoding` + `Vary`, and the hub pipes those bytes through
+ * untouched (`proxyToUpstream` replays the upstream headers verbatim).
+ *
+ * So compression belongs HERE, in the shared file data-plane, and nowhere above
+ * it. Anything that re-compresses on top of this reintroduces the empty-brotli
+ * bug rather than doubling the ratio.
+ *
+ * ## Why the bytes are cached, and why the cache is bounded
+ *
+ * Measured on the stream-broker embed bundle (`index-<hash>.js`, 1,443,142 B):
+ * gzip-6 → 360,868 B, brotli-5 → 327,419 B in 27 ms, brotli-11 → 293,677 B in
+ * 2,233 ms. Quality 5 is the request-path choice: 77% off the wire for 27 ms
+ * paid ONCE. Quality 11 buys another 2.3% for eighty times the CPU, on a path
+ * where a real client is waiting.
+ *
+ * The cache is an LRU bounded by BOTH entry count and total bytes, and it
+ * refuses assets over {@link COMPRESSION_MAX_ASSET_BYTES} outright. An unbounded
+ * `Map` keyed by URL is how a long-lived process walks into an OOM, and this
+ * repo has already spent a session on one.
+ *
+ * The key carries `mtimeMs` and `size`, so a rebuild that rewrites an asset in
+ * place under an UNCHANGED name (an SPA shell, a service worker) can never be
+ * served from the previous build's bytes.
+ */
+/** The codings this layer will produce. Identity is the absence of one. */
+export type ContentEncoding = 'br' | 'gzip';
+/**
+ * Below this the framing and the `Vary` cache split cost more than the
+ * compression saves. Same threshold the hub's global compressor is registered
+ * with, deliberately.
+ */
+export declare const COMPRESSION_MIN_BYTES = 1024;
+/**
+ * Above this an asset is streamed identity and never buffered. Compression
+ * requires the whole body in RAM twice; a multi-hundred-MB recording segment
+ * must not be able to do that, whatever its content type says.
+ */
+export declare const COMPRESSION_MAX_ASSET_BYTES: number;
+/** Is a body of this content type worth compressing at all? */
+export declare function isCompressibleContentType(contentType: string): boolean;
+/**
+ * Pick a coding for this request: brotli when offered, else gzip, else identity.
+ *
+ * Returns `null` for identity — including when the header is ABSENT. A client
+ * that offers nothing gets the raw bytes; guessing on its behalf is how a
+ * non-negotiating consumer (a native fetch, a probe, an OTA puller) ends up with
+ * a body it cannot read.
+ */
+export declare function negotiateContentEncoding(acceptEncoding: string | undefined): ContentEncoding | null;
+/** Identity of one compressed body. `mtimeMs`+`size` make a rebuild-in-place a MISS. */
+export interface CompressedAssetKey {
+    readonly path: string;
+    readonly mtimeMs: number;
+    readonly size: number;
+    readonly encoding: ContentEncoding;
+}
+/** Counters for the cache. Exported so a test can prove the compressor ran ONCE. */
+export interface AssetCompressionStats {
+    /** Bodies actually run through zlib. */
+    readonly compressions: number;
+    /** Requests served from already-compressed bytes. */
+    readonly hits: number;
+    readonly entries: number;
+    readonly bytes: number;
+}
+/**
+ * Compressed bytes for one asset, compressing at most once per key.
+ *
+ * `null` means "send the original" — the asset is too large to buffer, the
+ * source could not be read, or compression did not actually shrink it. Every
+ * failure degrades to identity, so this can only ever be an optimisation.
+ *
+ * Concurrent callers for the same key share ONE compression: a cold cache hit by
+ * a dozen parallel asset requests must not run zlib a dozen times.
+ */
+export declare function getCompressedAsset(key: CompressedAssetKey, readSource: () => Promise<Buffer>): Promise<Buffer | null>;
+export declare function getAssetCompressionStats(): AssetCompressionStats;
+/** Test seam — the cache and its counters are process-wide. */
+export declare function resetAssetCompressionCache(): void;

package/dist/index.js

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-LDrOFrd-.js");
-const require_model_download_service = require("./model-download-service-Cpc6SWzV.js");
-const require_manifest_python_deps = require("./manifest-python-deps-DNfmBu20.js");
+const require_dist = require("./dist-DP3nHlNM.js");
+const require_model_download_service = require("./model-download-service-Caj1kaSi.js");
+const require_manifest_python_deps = require("./manifest-python-deps-BE6l8Y4W.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
 const require_builtins_sqlite_storage_filesystem_storage_addon = require("./builtins/sqlite-storage/filesystem-storage.addon.js");
 const require_builtins_sqlite_storage_sqlite_settings_addon = require("./builtins/sqlite-storage/sqlite-settings.addon.js");
@@ -41,10 +41,10 @@ let node_fs$1 = require_chunk.__toESM(node_fs, 1);
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path, 1);
-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 _camstack_types_addon = require("@camstack/types/addon");
+let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_fs_promises = require("node:fs/promises");
@@ -139,6 +139,30 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
 /**
+* Escalate above this share of the ceiling.
+*
+* 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
+* never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
+* is already running by the time the warn is reachable.
+*/
+var HEAP_WATCH_ESCALATE_RATIO = .7;
+/**
+* Release escalation below this share.
+*
+* Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
+* so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
+* retreat rather than the trough of one collection.
+*/
+var HEAP_WATCH_DEESCALATE_RATIO = .6;
+/**
+* The cadence state machine, pure so the thresholds are testable without
+* allocating three gigabytes to reach them.
+*/
+function nextMode(current, usedRatio, escalateRatio = HEAP_WATCH_ESCALATE_RATIO, deescalateRatio = HEAP_WATCH_DEESCALATE_RATIO) {
+	if (current === "escalated") return usedRatio < deescalateRatio ? "steady" : "escalated";
+	return usedRatio >= escalateRatio ? "escalated" : "steady";
+}
+/**
 * Reclaim once the process holds this many MB beyond what it is USING.
 *
 * Live calibration, both readings from the same hub minutes apart: 2491MB
@@ -229,6 +253,9 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
 	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	const fastIntervalMs = reclaimOptions?.fastIntervalMs ?? 2e3;
+	const escalateRatio = reclaimOptions?.escalateRatio ?? .7;
+	const deescalateRatio = reclaimOptions?.deescalateRatio ?? .6;
 	let lastReclaimAt = Number.NEGATIVE_INFINITY;
 	const read = () => {
 		const limit = reclaimOptions?.heapLimitBytes ?? node_v8.getHeapStatistics().heap_size_limit;
@@ -249,16 +276,43 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 		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`);
 	};
+	let mode = "steady";
+	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	/**
+	* PROBING and LOGGING are separate cadences, and that separation is the whole
+	* point.
+	*
+	* The 2026-08-08 fatal escaped a 60s heartbeat because the burst began and
+	* ended between two samples. Deciding "is the heap elevated?" only when a
+	* line is due would reproduce that exactly: the process would still be read
+	* once a minute, and a 62-second climb would still be invisible. So the timer
+	* runs at the FAST period always — `process.memoryUsage()` is tens of
+	* microseconds, i.e. free at this rate — and the slow period governs only how
+	* often a steady process is allowed to say so.
+	*
+	* Never probe slower than the log cadence, or a caller passing a short
+	* `intervalMs` would silently get the long one.
+	*/
+	const probeIntervalMs = Math.min(fastIntervalMs, intervalMs);
 	const tick = () => {
 		try {
 			const sample = read();
-			const line = format$1(label, sample);
-			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
-			else sink.info(line);
+			const previous = mode;
+			mode = nextMode(previous, sample.usedRatio, escalateRatio, deescalateRatio);
+			const at = now();
+			const due = at - lastLoggedAt >= intervalMs;
+			if (mode === "escalated" || due) {
+				lastLoggedAt = at;
+				const line = format$1(label, sample);
+				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`);
 			maybeReclaim(sample);
 		} catch {}
 	};
-	const timer = setInterval(tick, intervalMs);
+	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
 	let stopped = false;

package/dist/index.mjs

@@ -1,7 +1,7 @@
 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 { Ct as asString$1, Dt as expandCapMethods, F as extractNestedAddonId, Ft as scopeKey, H as kebabToCamel, K as logLevelAtMost, L as isArrayOutputSchema, Lt as EventCategory$1, Mt as parseJsonUnknown$1, Nt as readinessKey, Pt as resolveCapMount, R as isCollectionArrayMethod, St as asNumber, Tt as emitDownForOwnedCaps, U as lifecycleJobSchema, V as isVoidInput, Z as objectInputDeclaresAddonId, et as procedureAuthKey, ft as DATAPLANE_SECRET_HEADER$1, g as addonSettingsCapability, jt as parseJsonObject, l as METHOD_ACCESS_MAP, mt as DEVICE_STATUS_METHOD, pt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, u as RUNTIME_DEFAULTS, ut as errMsg$1, vt as ReadinessRegistry, wt as createEvent, xt as asJsonObject$1, yt as ReadinessTimeoutError, z as isObjectInput } from "./dist-BJ2w3uoN.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-CopL1_5C.mjs";
+import { Ct as asString$1, Dt as expandCapMethods, F as extractNestedAddonId, Ft as scopeKey, H as kebabToCamel, K as logLevelAtMost, L as isArrayOutputSchema, Lt as EventCategory$1, Mt as parseJsonUnknown$1, Nt as readinessKey, Pt as resolveCapMount, R as isCollectionArrayMethod, St as asNumber, Tt as emitDownForOwnedCaps, U as lifecycleJobSchema, V as isVoidInput, Z as objectInputDeclaresAddonId, et as procedureAuthKey, ft as DATAPLANE_SECRET_HEADER$1, g as addonSettingsCapability, jt as parseJsonObject, l as METHOD_ACCESS_MAP, mt as DEVICE_STATUS_METHOD, pt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, q as looseSchema, t as ALL_CAPABILITY_DEFINITIONS, u as RUNTIME_DEFAULTS, ut as errMsg$1, vt as ReadinessRegistry, wt as createEvent, xt as asJsonObject$1, yt as ReadinessTimeoutError, z as isObjectInput } from "./dist-CMb7aKS0.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-CTBHzORJ.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-Dz1ryHIN.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BkP504Vq.mjs";
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./builtins/sqlite-storage/filesystem-storage.addon.mjs";
 import { SqliteSettingsAddon, o as SqliteSettingsBackend } from "./builtins/sqlite-storage/sqlite-settings.addon.mjs";
@@ -37,10 +37,10 @@ import * as fs$17 from "node:fs";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
 import * as path$39 from "node:path";
 import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
-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 { asJsonObject, errMsg, parseJsonUnknown } from "@camstack/types/addon";
+import { execFile, spawn } from "node:child_process";
 import * as os$18 from "node:os";
 import { lstat, readdir, readlink, realpath } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -131,6 +131,30 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
 /**
+* Escalate above this share of the ceiling.
+*
+* 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
+* never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
+* is already running by the time the warn is reachable.
+*/
+var HEAP_WATCH_ESCALATE_RATIO = .7;
+/**
+* Release escalation below this share.
+*
+* Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
+* so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
+* retreat rather than the trough of one collection.
+*/
+var HEAP_WATCH_DEESCALATE_RATIO = .6;
+/**
+* The cadence state machine, pure so the thresholds are testable without
+* allocating three gigabytes to reach them.
+*/
+function nextMode(current, usedRatio, escalateRatio = HEAP_WATCH_ESCALATE_RATIO, deescalateRatio = HEAP_WATCH_DEESCALATE_RATIO) {
+	if (current === "escalated") return usedRatio < deescalateRatio ? "steady" : "escalated";
+	return usedRatio >= escalateRatio ? "escalated" : "steady";
+}
+/**
 * Reclaim once the process holds this many MB beyond what it is USING.
 *
 * Live calibration, both readings from the same hub minutes apart: 2491MB
@@ -221,6 +245,9 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
 	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	const fastIntervalMs = reclaimOptions?.fastIntervalMs ?? 2e3;
+	const escalateRatio = reclaimOptions?.escalateRatio ?? .7;
+	const deescalateRatio = reclaimOptions?.deescalateRatio ?? .6;
 	let lastReclaimAt = Number.NEGATIVE_INFINITY;
 	const read = () => {
 		const limit = reclaimOptions?.heapLimitBytes ?? v8.getHeapStatistics().heap_size_limit;
@@ -241,16 +268,43 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 		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`);
 	};
+	let mode = "steady";
+	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	/**
+	* PROBING and LOGGING are separate cadences, and that separation is the whole
+	* point.
+	*
+	* The 2026-08-08 fatal escaped a 60s heartbeat because the burst began and
+	* ended between two samples. Deciding "is the heap elevated?" only when a
+	* line is due would reproduce that exactly: the process would still be read
+	* once a minute, and a 62-second climb would still be invisible. So the timer
+	* runs at the FAST period always — `process.memoryUsage()` is tens of
+	* microseconds, i.e. free at this rate — and the slow period governs only how
+	* often a steady process is allowed to say so.
+	*
+	* Never probe slower than the log cadence, or a caller passing a short
+	* `intervalMs` would silently get the long one.
+	*/
+	const probeIntervalMs = Math.min(fastIntervalMs, intervalMs);
 	const tick = () => {
 		try {
 			const sample = read();
-			const line = format$1(label, sample);
-			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
-			else sink.info(line);
+			const previous = mode;
+			mode = nextMode(previous, sample.usedRatio, escalateRatio, deescalateRatio);
+			const at = now();
+			const due = at - lastLoggedAt >= intervalMs;
+			if (mode === "escalated" || due) {
+				lastLoggedAt = at;
+				const line = format$1(label, sample);
+				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`);
 			maybeReclaim(sample);
 		} catch {}
 	};
-	const timer = setInterval(tick, intervalMs);
+	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
 	let stopped = false;

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

@@ -4,6 +4,55 @@ 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;
+/**
+ * ## The heartbeat could not see the thing it was built to see
+ *
+ * 2026-08-08 18:28:32Z, hub-main (pid 8) died on `Reached heap limit`. The last
+ * `[mem]` line was 18:27:30.433 reading `heapUsed=1086MB` — 25%, unremarkable —
+ * and V8's own trace 62 seconds later read 4083MB with a Mark-Compact that
+ * reclaimed 4MB of 4090MB. Between those two facts there is not one sample.
+ *
+ * At `HEAP_WATCH_INTERVAL_MS` the whole event fits inside a single gap, so
+ * `HEAP_WATCH_WARN_RATIO` never had a reading to fire on. The docblock above
+ * promises "the line that will exist BEFORE the next fatal instead of after
+ * it"; on the only occasion that mattered, it did not exist.
+ *
+ * Measured the same day over 397 consecutive live samples: p50 1266MB, p95
+ * 1995MB, **max 2847MB** — 0.66 of the 4288MB ceiling. So the routine sawtooth
+ * never approaches 0.8, and the only path to 0.8 is a burst that outruns the
+ * sampler. A threshold reachable only through a blind spot is decoration.
+ *
+ * The fix is not a faster heartbeat — 30 lines a minute forever, to describe a
+ * process that is fine, is how a log stops being read. It is to sample fast
+ * only while the heap is somewhere the routine sawtooth does not go.
+ */
+/** Sampling period once escalated. Bounded below by log volume, above by the
+ *  62s window the 2026-08-08 fatal hid in: ~30 readings across that window is
+ *  a trajectory, and a trajectory separates a burst from a climb. */
+export declare const HEAP_WATCH_FAST_INTERVAL_MS = 2000;
+/**
+ * Escalate above this share of the ceiling.
+ *
+ * 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
+ * never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
+ * is already running by the time the warn is reachable.
+ */
+export declare const HEAP_WATCH_ESCALATE_RATIO = 0.7;
+/**
+ * Release escalation below this share.
+ *
+ * Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
+ * so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
+ * retreat rather than the trough of one collection.
+ */
+export declare const HEAP_WATCH_DEESCALATE_RATIO = 0.6;
+/** Sampling cadence. `escalated` costs log lines and buys resolution. */
+export type HeapWatchMode = 'steady' | 'escalated';
+/**
+ * The cadence state machine, pure so the thresholds are testable without
+ * allocating three gigabytes to reach them.
+ */
+export declare function nextMode(current: HeapWatchMode, usedRatio: number, escalateRatio?: number, deescalateRatio?: number): HeapWatchMode;
 /**
  * Reclaim once the process holds this many MB beyond what it is USING.
  *
@@ -73,6 +122,12 @@ export interface HeapReclaimOptions {
     readonly triggerMb?: number;
     readonly minIntervalMs?: number;
     readonly now?: () => number;
+    /** Sampling cadence once escalated. See {@link HEAP_WATCH_FAST_INTERVAL_MS}. */
+    readonly fastIntervalMs?: number;
+    /** Ratio at which the fast cadence begins. See {@link HEAP_WATCH_ESCALATE_RATIO}. */
+    readonly escalateRatio?: number;
+    /** Ratio at which it releases. See {@link HEAP_WATCH_DEESCALATE_RATIO}. */
+    readonly deescalateRatio?: number;
 }
 /**
  * Start the heartbeat. Returns a stop function.