@camstack/system 1.2.437 → 1.2.439

package/dist/addon-runner.js

@@ -1578,7 +1578,8 @@ function formatOutboundQueueVerdict(label, verdict) {
 }
 //#endregion
 //#region src/kernel/gc-census.ts
-function countsOf(entries, kinds) {
+function countsOf(entries, kinds, flagBits) {
+	const flags = {};
 	let majors = 0;
 	let minors = 0;
 	let incrementals = 0;
@@ -1588,13 +1589,17 @@ function countsOf(entries, kinds) {
 		else if (e.kind === kinds.minor) minors++;
 		else if (e.kind === kinds.incremental) incrementals++;
 		pauseMs += e.durationMs;
+		if (e.flags !== void 0) {
+			for (const f of flagBits) if ((e.flags & f.bit) !== 0) flags[f.name] = (flags[f.name] ?? 0) + 1;
+		}
 	}
 	return {
 		majors,
 		minors,
 		incrementals,
 		pauseMs,
-		windowMs: 0
+		windowMs: 0,
+		...Object.keys(flags).length > 0 ? { flags } : {}
 	};
 }
 /**
@@ -1606,7 +1611,7 @@ function countsOf(entries, kinds) {
 * observed and a process that is not collecting look identical on the line, and
 * they are the two answers furthest apart.
 */
-function createGcCensus(install, kinds, startedAt) {
+function createGcCensus(install, kinds, startedAt, flagBits = []) {
 	let pending = [];
 	const stopObserving = install((entry) => {
 		pending.push(entry);
@@ -1621,7 +1626,7 @@ function createGcCensus(install, kinds, startedAt) {
 			pending = [];
 			windowStart = at;
 			return {
-				...countsOf(taken, kinds),
+				...countsOf(taken, kinds, flagBits),
 				windowMs
 			};
 		},
@@ -1646,14 +1651,18 @@ function nodeGcObserver() {
 			minor: 1,
 			incremental: 8
 		}),
+		flagBits: readFlagBits(),
 		install: (observe) => {
 			try {
 				const observer = new (process.getBuiltinModule("node:perf_hooks")).PerformanceObserver((list) => {
 					for (const entry of list.getEntries()) {
 						const detail = "detail" in entry ? entry.detail : void 0;
+						const kind = typeof detail === "object" && detail !== null && "kind" in detail && typeof detail.kind === "number" ? detail.kind : -1;
+						const flags = typeof detail === "object" && detail !== null && "flags" in detail && typeof detail.flags === "number" ? detail.flags : void 0;
 						observe({
-							kind: typeof detail === "object" && detail !== null && "kind" in detail && typeof detail.kind === "number" ? detail.kind : -1,
-							durationMs: entry.duration
+							kind,
+							durationMs: entry.duration,
+							...flags !== void 0 ? { flags } : {}
 						});
 					}
 				});
@@ -1667,6 +1676,25 @@ function nodeGcObserver() {
 		}
 	};
 }
+var GC_FLAG_PREFIX = "NODE_PERFORMANCE_GC_FLAGS_";
+/**
+* The flag bits, read from `perf_hooks.constants` by their prefix so a flag V8
+* adds tomorrow gets a name without anyone editing a table. `NO` (0) can never
+* match a bit and is dropped.
+*/
+function readFlagBits() {
+	try {
+		const perf = process.getBuiltinModule("node:perf_hooks");
+		const bits = [];
+		for (const [key, value] of Object.entries(perf.constants)) if (key.startsWith(GC_FLAG_PREFIX) && typeof value === "number" && value > 0) bits.push({
+			name: key.slice(26),
+			bit: value
+		});
+		return bits;
+	} catch {
+		return [];
+	}
+}
 function readKinds(fallback) {
 	try {
 		const c = process.getBuiltinModule("node:perf_hooks").constants;
@@ -1693,7 +1721,14 @@ function readKinds(fallback) {
 function formatGcCensus(window) {
 	if (window === null || window === void 0) return "";
 	const perMin = (n) => window.windowMs <= 0 ? "?" : (n / (window.windowMs / 6e4)).toFixed(1);
-	return ` gc=maj${window.majors}/min${window.minors}/inc${window.incrementals}@${Math.round(window.windowMs / 1e3)}s gcMajPerMin=${perMin(window.majors)} gcPauseMs=${Math.round(window.pauseMs)}`;
+	return ` gc=maj${window.majors}/min${window.minors}/inc${window.incrementals}@${Math.round(window.windowMs / 1e3)}s gcMajPerMin=${perMin(window.majors)} gcPauseMs=${Math.round(window.pauseMs)}` + formatGcFlags(window.flags);
+}
+/** ` gcFlags=ALL_EXTERNAL_MEMORY:12,FORCED:1` — most frequent first; empty when none. */
+function formatGcFlags(flags) {
+	if (flags === void 0) return "";
+	const entries = Object.entries(flags).toSorted((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+	if (entries.length === 0) return "";
+	return ` gcFlags=${entries.map(([name, n]) => `${name}:${n}`).join(",")}`;
 }
 /**
 * The census. Always exists — `process.cpuUsage()` is available on every
@@ -2440,7 +2475,7 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const gcObserver = probes?.gcObserver ?? nodeGcObserver();
-	const gcCensus = createGcCensus(gcObserver.install, gcObserver.kinds, now());
+	const gcCensus = createGcCensus(gcObserver.install, gcObserver.kinds, now(), gcObserver.flagBits);
 	const cpuProbe = probes?.processCpu;
 	const processCpu = createProcessCpuCensus({
 		cpuUsageUs: cpuProbe?.cpuUsageUs ?? (() => {
@@ -2494,6 +2529,7 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 	};
 	let mode = "steady";
 	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	let firstLinePending = true;
 	const budgetMb = rssBudget?.budgetMb !== void 0 && rssBudget.budgetMb > 0 ? rssBudget.budgetMb : void 0;
 	const budgetSource = rssBudget?.source ?? "unspecified";
 	const releaseRatio = rssBudget?.releaseRatio ?? .9;
@@ -2552,7 +2588,9 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 			const due = at - lastLoggedAt >= intervalMs;
 			if (mode === "escalated" || due) {
 				lastLoggedAt = at;
-				const line = format(label, sample, loopDelay?.read(), budgetMb, `${formatHeapSpaces(readSpaces())}${formatEventPlane(eventPlane?.read())}` + formatSocketPlane(socketPlane?.read()) + formatMeshQueue(meshQueue?.()) + formatGcCensus(gcCensus?.read(at)) + formatProcessCpu(processCpu.read(at)));
+				const firstLine = firstLinePending;
+				firstLinePending = false;
+				const line = format(label, sample, loopDelay?.read(), budgetMb, `${formatHeapSpaces(readSpaces(), firstLine ? 0 : void 0)}${formatEventPlane(eventPlane?.read())}` + formatSocketPlane(socketPlane?.read()) + formatMeshQueue(meshQueue?.()) + formatGcCensus(gcCensus?.read(at)) + formatProcessCpu(processCpu.read(at)));
 				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);
@@ -2775,9 +2813,14 @@ function capBareAction(capName, method) {
 * node had answered (2026-09-25, device 3836).
 */
 var PeerAnsweredError = class extends Error {
-	constructor(message) {
+	/** The far end's stable error code (D863), carried so the hub can translate it. */
+	i18nCode;
+	i18nParams;
+	constructor(message, i18n) {
 		super(message);
 		this.name = "PeerAnsweredError";
+		this.i18nCode = i18n?.code;
+		this.i18nParams = i18n?.params;
 	}
 };
 /**
@@ -4306,6 +4349,13 @@ var PayloadReply = class {
 		this.payload = payload;
 	}
 };
+//#endregion
+//#region src/kernel/transport/socket-channel.ts
+/** A peer's `i18n` is untrusted wire data: a malformed one is dropped, the message still travels. */
+function parseWireI18n(raw) {
+	const parsed = _camstack_types_addon.ErrorI18nPayloadSchema.safeParse(raw);
+	return parsed.success ? parsed.data : void 0;
+}
 var SocketChannel = class {
 	socket;
 	nextId = 1;
@@ -4517,11 +4567,13 @@ var SocketChannel = class {
 					body: result
 				});
 			} catch (err) {
+				const i18n = (0, _camstack_types_addon.readErrorI18n)(err);
 				resBytes = this.send({
 					k: "res",
 					id: frame.id,
 					ok: false,
-					err: err instanceof Error ? err.message : String(err)
+					err: err instanceof Error ? err.message : String(err),
+					...i18n !== null ? { i18n } : {}
 				});
 			}
 			if (label !== void 0) this.recordAction(label, wireBytes, resBytes);
@@ -4533,7 +4585,7 @@ var SocketChannel = class {
 			this.pending.delete(frame.id);
 			if (p.timer !== null) clearTimeout(p.timer);
 			if (p.action !== null) this.recordAction(p.action.label, p.action.reqBytes, wireBytes);
-			if (!frame.ok) p.reject(new PeerAnsweredError(frame.err));
+			if (!frame.ok) p.reject(new PeerAnsweredError(frame.err, parseWireI18n(frame.i18n)));
 			else if (frame.pl !== void 0) p.resolve(new PayloadReply(frame.body, frame.pl));
 			else p.resolve(frame.body);
 			return;

package/dist/addon-runner.mjs

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import { createReadStream, createWriteStream, existsSync, readFileSync, readdirSync } from "node:fs";
 import * as path from "node:path";
 import { dirname, isAbsolute, join } from "node:path";
-import { BOOT_RECOVERY_BACKOFF_MS, DATAPLANE_SECRET_HEADER, DEVICE_CHILDREN_BATCH_MAX, DeviceType, DisposerChain, EventCategory, PEER_BYTES_CHUNK_BYTES, PEER_BYTES_MAX_OUTSTANDING, PEER_BYTES_STALL_MS, PEER_BYTES_TICKET_TTL_MS, ReadinessRegistry, ReadinessTimeoutError, asJsonObject, asString, collectZodSecretPaths, createDeviceProxy, createEventBusSliceSource, createSecretsAccess, describeCustomActions, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, isCollectionArrayMethodName, isProviderOptionalMethodName, maskUrlCredentials, normalizeAddonInitResult, readNodePin, resolveSecretViewsIn, scopeKey, scrubKnownSecrets, withCapInputDefaults } from "@camstack/types/addon";
+import { BOOT_RECOVERY_BACKOFF_MS, DATAPLANE_SECRET_HEADER, DEVICE_CHILDREN_BATCH_MAX, DeviceType, DisposerChain, ErrorI18nPayloadSchema, EventCategory, PEER_BYTES_CHUNK_BYTES, PEER_BYTES_MAX_OUTSTANDING, PEER_BYTES_STALL_MS, PEER_BYTES_TICKET_TTL_MS, ReadinessRegistry, ReadinessTimeoutError, asJsonObject, asString, collectZodSecretPaths, createDeviceProxy, createEventBusSliceSource, createSecretsAccess, describeCustomActions, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, isCollectionArrayMethodName, isProviderOptionalMethodName, maskUrlCredentials, normalizeAddonInitResult, readErrorI18n, readNodePin, resolveSecretViewsIn, scopeKey, scrubKnownSecrets, withCapInputDefaults } from "@camstack/types/addon";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import * as os from "node:os";
@@ -1554,7 +1554,8 @@ function formatOutboundQueueVerdict(label, verdict) {
 }
 //#endregion
 //#region src/kernel/gc-census.ts
-function countsOf(entries, kinds) {
+function countsOf(entries, kinds, flagBits) {
+	const flags = {};
 	let majors = 0;
 	let minors = 0;
 	let incrementals = 0;
@@ -1564,13 +1565,17 @@ function countsOf(entries, kinds) {
 		else if (e.kind === kinds.minor) minors++;
 		else if (e.kind === kinds.incremental) incrementals++;
 		pauseMs += e.durationMs;
+		if (e.flags !== void 0) {
+			for (const f of flagBits) if ((e.flags & f.bit) !== 0) flags[f.name] = (flags[f.name] ?? 0) + 1;
+		}
 	}
 	return {
 		majors,
 		minors,
 		incrementals,
 		pauseMs,
-		windowMs: 0
+		windowMs: 0,
+		...Object.keys(flags).length > 0 ? { flags } : {}
 	};
 }
 /**
@@ -1582,7 +1587,7 @@ function countsOf(entries, kinds) {
 * observed and a process that is not collecting look identical on the line, and
 * they are the two answers furthest apart.
 */
-function createGcCensus(install, kinds, startedAt) {
+function createGcCensus(install, kinds, startedAt, flagBits = []) {
 	let pending = [];
 	const stopObserving = install((entry) => {
 		pending.push(entry);
@@ -1597,7 +1602,7 @@ function createGcCensus(install, kinds, startedAt) {
 			pending = [];
 			windowStart = at;
 			return {
-				...countsOf(taken, kinds),
+				...countsOf(taken, kinds, flagBits),
 				windowMs
 			};
 		},
@@ -1622,14 +1627,18 @@ function nodeGcObserver() {
 			minor: 1,
 			incremental: 8
 		}),
+		flagBits: readFlagBits(),
 		install: (observe) => {
 			try {
 				const observer = new (process.getBuiltinModule("node:perf_hooks")).PerformanceObserver((list) => {
 					for (const entry of list.getEntries()) {
 						const detail = "detail" in entry ? entry.detail : void 0;
+						const kind = typeof detail === "object" && detail !== null && "kind" in detail && typeof detail.kind === "number" ? detail.kind : -1;
+						const flags = typeof detail === "object" && detail !== null && "flags" in detail && typeof detail.flags === "number" ? detail.flags : void 0;
 						observe({
-							kind: typeof detail === "object" && detail !== null && "kind" in detail && typeof detail.kind === "number" ? detail.kind : -1,
-							durationMs: entry.duration
+							kind,
+							durationMs: entry.duration,
+							...flags !== void 0 ? { flags } : {}
 						});
 					}
 				});
@@ -1643,6 +1652,25 @@ function nodeGcObserver() {
 		}
 	};
 }
+var GC_FLAG_PREFIX = "NODE_PERFORMANCE_GC_FLAGS_";
+/**
+* The flag bits, read from `perf_hooks.constants` by their prefix so a flag V8
+* adds tomorrow gets a name without anyone editing a table. `NO` (0) can never
+* match a bit and is dropped.
+*/
+function readFlagBits() {
+	try {
+		const perf = process.getBuiltinModule("node:perf_hooks");
+		const bits = [];
+		for (const [key, value] of Object.entries(perf.constants)) if (key.startsWith(GC_FLAG_PREFIX) && typeof value === "number" && value > 0) bits.push({
+			name: key.slice(26),
+			bit: value
+		});
+		return bits;
+	} catch {
+		return [];
+	}
+}
 function readKinds(fallback) {
 	try {
 		const c = process.getBuiltinModule("node:perf_hooks").constants;
@@ -1669,7 +1697,14 @@ function readKinds(fallback) {
 function formatGcCensus(window) {
 	if (window === null || window === void 0) return "";
 	const perMin = (n) => window.windowMs <= 0 ? "?" : (n / (window.windowMs / 6e4)).toFixed(1);
-	return ` gc=maj${window.majors}/min${window.minors}/inc${window.incrementals}@${Math.round(window.windowMs / 1e3)}s gcMajPerMin=${perMin(window.majors)} gcPauseMs=${Math.round(window.pauseMs)}`;
+	return ` gc=maj${window.majors}/min${window.minors}/inc${window.incrementals}@${Math.round(window.windowMs / 1e3)}s gcMajPerMin=${perMin(window.majors)} gcPauseMs=${Math.round(window.pauseMs)}` + formatGcFlags(window.flags);
+}
+/** ` gcFlags=ALL_EXTERNAL_MEMORY:12,FORCED:1` — most frequent first; empty when none. */
+function formatGcFlags(flags) {
+	if (flags === void 0) return "";
+	const entries = Object.entries(flags).toSorted((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+	if (entries.length === 0) return "";
+	return ` gcFlags=${entries.map(([name, n]) => `${name}:${n}`).join(",")}`;
 }
 /**
 * The census. Always exists — `process.cpuUsage()` is available on every
@@ -2416,7 +2451,7 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const gcObserver = probes?.gcObserver ?? nodeGcObserver();
-	const gcCensus = createGcCensus(gcObserver.install, gcObserver.kinds, now());
+	const gcCensus = createGcCensus(gcObserver.install, gcObserver.kinds, now(), gcObserver.flagBits);
 	const cpuProbe = probes?.processCpu;
 	const processCpu = createProcessCpuCensus({
 		cpuUsageUs: cpuProbe?.cpuUsageUs ?? (() => {
@@ -2470,6 +2505,7 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 	};
 	let mode = "steady";
 	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	let firstLinePending = true;
 	const budgetMb = rssBudget?.budgetMb !== void 0 && rssBudget.budgetMb > 0 ? rssBudget.budgetMb : void 0;
 	const budgetSource = rssBudget?.source ?? "unspecified";
 	const releaseRatio = rssBudget?.releaseRatio ?? .9;
@@ -2528,7 +2564,9 @@ function startHeapWatch(label = HUB_MAIN_HEAP_WATCH_LABEL, sink = consoleSink, i
 			const due = at - lastLoggedAt >= intervalMs;
 			if (mode === "escalated" || due) {
 				lastLoggedAt = at;
-				const line = format(label, sample, loopDelay?.read(), budgetMb, `${formatHeapSpaces(readSpaces())}${formatEventPlane(eventPlane?.read())}` + formatSocketPlane(socketPlane?.read()) + formatMeshQueue(meshQueue?.()) + formatGcCensus(gcCensus?.read(at)) + formatProcessCpu(processCpu.read(at)));
+				const firstLine = firstLinePending;
+				firstLinePending = false;
+				const line = format(label, sample, loopDelay?.read(), budgetMb, `${formatHeapSpaces(readSpaces(), firstLine ? 0 : void 0)}${formatEventPlane(eventPlane?.read())}` + formatSocketPlane(socketPlane?.read()) + formatMeshQueue(meshQueue?.()) + formatGcCensus(gcCensus?.read(at)) + formatProcessCpu(processCpu.read(at)));
 				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);
@@ -2751,9 +2789,14 @@ function capBareAction(capName, method) {
 * node had answered (2026-09-25, device 3836).
 */
 var PeerAnsweredError = class extends Error {
-	constructor(message) {
+	/** The far end's stable error code (D863), carried so the hub can translate it. */
+	i18nCode;
+	i18nParams;
+	constructor(message, i18n) {
 		super(message);
 		this.name = "PeerAnsweredError";
+		this.i18nCode = i18n?.code;
+		this.i18nParams = i18n?.params;
 	}
 };
 /**
@@ -4282,6 +4325,13 @@ var PayloadReply = class {
 		this.payload = payload;
 	}
 };
+//#endregion
+//#region src/kernel/transport/socket-channel.ts
+/** A peer's `i18n` is untrusted wire data: a malformed one is dropped, the message still travels. */
+function parseWireI18n(raw) {
+	const parsed = ErrorI18nPayloadSchema.safeParse(raw);
+	return parsed.success ? parsed.data : void 0;
+}
 var SocketChannel = class {
 	socket;
 	nextId = 1;
@@ -4493,11 +4543,13 @@ var SocketChannel = class {
 					body: result
 				});
 			} catch (err) {
+				const i18n = readErrorI18n(err);
 				resBytes = this.send({
 					k: "res",
 					id: frame.id,
 					ok: false,
-					err: err instanceof Error ? err.message : String(err)
+					err: err instanceof Error ? err.message : String(err),
+					...i18n !== null ? { i18n } : {}
 				});
 			}
 			if (label !== void 0) this.recordAction(label, wireBytes, resBytes);
@@ -4509,7 +4561,7 @@ var SocketChannel = class {
 			this.pending.delete(frame.id);
 			if (p.timer !== null) clearTimeout(p.timer);
 			if (p.action !== null) this.recordAction(p.action.label, p.action.reqBytes, wireBytes);
-			if (!frame.ok) p.reject(new PeerAnsweredError(frame.err));
+			if (!frame.ok) p.reject(new PeerAnsweredError(frame.err, parseWireI18n(frame.i18n)));
 			else if (frame.pl !== void 0) p.resolve(new PayloadReply(frame.body, frame.pl));
 			else p.resolve(frame.body);
 			return;