@camstack/system 1.2.63 → 1.2.65

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-DqPyKwVB.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.

package/dist/{model-download-service-D8B-4ktF.mjs → model-download-service-CTBHzORJ.mjs}

@@ -4,6 +4,8 @@ import * as fs from "node:fs";
 import { createReadStream, promises } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
+import { promisify } from "node:util";
+import { brotliCompress, constants as constants$1, gzip } from "node:zlib";
 //#region src/http/authenticated-file-server.ts
 /**
 * Authenticated data-plane file-server — a shared host primitive for addons that
@@ -214,6 +216,188 @@ async function handle(opts, cors, req, res) {
 	createReadStream(absPath).pipe(res);
 }
 //#endregion
+//#region src/http/asset-compression.ts
+/**
+* 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.
+*/
+var brotliAsync = promisify(brotliCompress);
+var gzipAsync = promisify(gzip);
+/** LRU bounds. Both are enforced; whichever binds first evicts. */
+var MAX_CACHE_ENTRIES = 64;
+var MAX_CACHE_BYTES = 32 * 1024 * 1024;
+/** Brotli quality — see the file header for the measured trade. */
+var BROTLI_QUALITY = 5;
+/**
+* Content types worth compressing. An ALLOW-list, not a deny-list: an unknown
+* type (`application/octet-stream`) is assumed to be opaque binary. This is what
+* keeps jpeg/png/webp/mp4/m4s/woff2 out — running brotli over them burns CPU to
+* make the body marginally BIGGER.
+*/
+var COMPRESSIBLE_EXACT = new Set([
+	"application/javascript",
+	"application/ecmascript",
+	"application/json",
+	"application/manifest+json",
+	"application/wasm",
+	"application/xml",
+	"application/xhtml+xml",
+	"application/vnd.apple.mpegurl",
+	"image/svg+xml"
+]);
+/** Is a body of this content type worth compressing at all? */
+function isCompressibleContentType(contentType) {
+	const base = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (base.length === 0) return false;
+	if (base.startsWith("text/")) return true;
+	if (base.endsWith("+json") || base.endsWith("+xml")) return true;
+	return COMPRESSIBLE_EXACT.has(base);
+}
+/** Parse `Accept-Encoding` into tokens with their q-values (default 1). */
+function parseAcceptEncoding(header) {
+	if (header === void 0 || header.trim().length === 0) return [];
+	const out = [];
+	for (const part of header.split(",")) {
+		const [rawToken, ...params] = part.split(";");
+		const token = rawToken?.trim().toLowerCase() ?? "";
+		if (token.length === 0) continue;
+		let q = 1;
+		for (const param of params) {
+			const [name, value] = param.split("=");
+			if (name?.trim().toLowerCase() !== "q") continue;
+			const parsed = Number(value?.trim());
+			q = Number.isFinite(parsed) ? parsed : 1;
+		}
+		out.push({
+			token,
+			q
+		});
+	}
+	return out;
+}
+function accepts(prefs, token) {
+	const exact = prefs.find((p) => p.token === token);
+	if (exact) return exact.q > 0;
+	const wildcard = prefs.find((p) => p.token === "*");
+	return wildcard !== void 0 && wildcard.q > 0;
+}
+/**
+* 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.
+*/
+function negotiateContentEncoding(acceptEncoding) {
+	const prefs = parseAcceptEncoding(acceptEncoding);
+	if (prefs.length === 0) return null;
+	if (accepts(prefs, "br")) return "br";
+	if (accepts(prefs, "gzip")) return "gzip";
+	return null;
+}
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+var compressions = 0;
+var hits = 0;
+var cachedBytes = 0;
+function cacheKey(key) {
+	return `${key.encoding}|${String(key.mtimeMs)}|${String(key.size)}|${key.path}`;
+}
+/** Evict least-recently-used entries until both bounds hold. */
+function evictToBounds() {
+	for (const [k, buf] of cache) {
+		if (cache.size <= MAX_CACHE_ENTRIES && cachedBytes <= MAX_CACHE_BYTES) return;
+		cache.delete(k);
+		cachedBytes -= buf.byteLength;
+	}
+}
+async function compressBody(raw, encoding) {
+	if (encoding === "gzip") return await gzipAsync(raw);
+	return await brotliAsync(raw, { params: {
+		[constants$1.BROTLI_PARAM_QUALITY]: BROTLI_QUALITY,
+		[constants$1.BROTLI_PARAM_SIZE_HINT]: raw.byteLength
+	} });
+}
+/**
+* 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.
+*/
+async function getCompressedAsset(key, readSource) {
+	if (key.size > 8388608) return null;
+	const id = cacheKey(key);
+	const cached = cache.get(id);
+	if (cached) {
+		cache.delete(id);
+		cache.set(id, cached);
+		hits += 1;
+		return cached;
+	}
+	const pending = inFlight.get(id) ?? (async () => {
+		let raw;
+		try {
+			raw = await readSource();
+		} catch {
+			return null;
+		}
+		const out = await compressBody(raw, key.encoding);
+		compressions += 1;
+		if (out.byteLength >= raw.byteLength) return null;
+		cache.set(id, out);
+		cachedBytes += out.byteLength;
+		evictToBounds();
+		return out;
+	})();
+	inFlight.set(id, pending);
+	try {
+		return await pending;
+	} catch {
+		return null;
+	} finally {
+		inFlight.delete(id);
+	}
+}
+//#endregion
 //#region src/http/file-data-plane.ts
 /**
 * A ready-made data-plane request handler that serves files from a set of roots
@@ -226,6 +410,11 @@ async function handle(opts, cors, req, res) {
 * the hub already authenticated the caller and the data plane is same-origin
 * through the hub's port. Reuses the shared Range/content-type/traversal helpers
 * so there is one implementation across the standalone file-server and this.
+*
+* It also owns its own CONTENT-CODING. The hub bridge is `{ compress: false }`
+* because the global compressor emits an empty brotli stream over the forked-
+* addon route bridge, so nothing above this layer will ever compress an addon
+* body — see `asset-compression.ts` for the incident and the contract.
 */
 /** Build a `(req, res)` handler that serves `getRoots()` files with Range. */
 function createFileDataPlaneHandler(opts) {
@@ -253,11 +442,13 @@ function createFileDataPlaneHandler(opts) {
 		}
 		let absPath = null;
 		let size = 0;
+		let mtimeMs = 0;
 		for (const candidate of resolved.candidates) try {
 			const st = await promises.stat(candidate);
 			if (st.isFile()) {
 				absPath = candidate;
 				size = st.size;
+				mtimeMs = st.mtimeMs;
 				break;
 			}
 		} catch {}
@@ -265,10 +456,13 @@ function createFileDataPlaneHandler(opts) {
 			res.writeHead(404).end();
 			return;
 		}
+		const contentType = contentTypeFor(absPath, opts.contentTypes);
+		const compressible = isCompressibleContentType(contentType);
 		const baseHeaders = {
-			"content-type": contentTypeFor(absPath, opts.contentTypes),
+			"content-type": contentType,
 			"accept-ranges": "bytes",
-			"cache-control": opts.cacheControl?.(rel) ?? "no-cache"
+			"cache-control": opts.cacheControl?.(rel) ?? "no-cache",
+			...compressible ? { vary: "accept-encoding" } : {}
 		};
 		const range = parseRangeHeader(req.headers.range, size);
 		if (range) {
@@ -287,6 +481,30 @@ function createFileDataPlaneHandler(opts) {
 			}).pipe(res);
 			return;
 		}
+		const encoding = compressible ? negotiateContentEncoding(req.headers["accept-encoding"]) : null;
+		if (encoding !== null && size >= 1024) {
+			const filePath = absPath;
+			const body = await getCompressedAsset({
+				path: filePath,
+				mtimeMs,
+				size,
+				encoding
+			}, () => promises.readFile(filePath));
+			if (body !== null) {
+				res.writeHead(200, {
+					...baseHeaders,
+					"content-encoding": encoding,
+					"accept-ranges": "none",
+					"content-length": String(body.byteLength)
+				});
+				if (req.method === "HEAD") {
+					res.end();
+					return;
+				}
+				res.end(body);
+				return;
+			}
+		}
 		res.writeHead(200, {
 			...baseHeaders,
 			"content-length": String(size)