@camstack/system 1.2.272 → 1.2.274

package/dist/{dist-Diz59Dhi.mjs → dist-DchKwh_m.mjs}

@@ -691,7 +691,7 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	return EventCategory;
 }({});
 //#endregion
-//#region ../types/dist/sleep-GU_us3DG.mjs
+//#region ../types/dist/sleep-CiR4z7r9.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -1857,6 +1857,17 @@ var CamProfileSchema = z.enum([
 	"mid",
 	"low"
 ]);
+/**
+* Which rung a per-camera consumer listens on: an explicit profile, or `auto`.
+*
+* `auto` is a REAL value, not an absent one — it means "resolve it by the rule
+* that consumer owns". It lives beside `CamProfile` because a rung is the only
+* operator-facing way to name a stream: a cam-stream id is broker-internal and
+* moves when a slot is reassigned, so a stored id silently stops meaning what
+* the operator picked. Today's one user is the audio analyser, whose rule is
+* "the lowest AVAILABLE native rung" (D537).
+*/
+var AudioStreamPickSchema = z.union([CamProfileSchema, z.literal("auto")]);
 var CamStreamKindSchema = z.enum([
 	"pull-rtsp",
 	"pull-rtmp",
@@ -3404,7 +3415,7 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 //#endregion
-//#region ../types/dist/canonical-hash-CvL03d3i.mjs
+//#region ../types/dist/canonical-hash-CPK2Dy60.mjs
 var AUDIO_ENCODER_BY_CODEC = {
 	opus: "libopus",
 	aac: "aac",
@@ -3505,16 +3516,29 @@ function resolveStreamMaps(selection) {
 	};
 }
 /** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
-function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+function buildVideoFilterArgs(scale, outputArgs, filterGraph, hwUpload) {
 	if (filterGraph) {
 		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
 		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
 		return [];
 	}
-	if (!scale) return [];
 	if (outputArgs.some((a) => a === "-vf")) return [];
-	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
-	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+	if (!scale) return hwUpload.length > 0 ? ["-vf", hwUpload] : [];
+	const suffix = hwUpload.length > 0 ? `,${hwUpload}` : "";
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}${suffix}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2${suffix}`];
+}
+/**
+* The upload filter a hardware encode needs, or `''`.
+*
+* Nothing is uploaded when the DECODE already left the frames on the GPU
+* (`-hwaccel vaapi`): they are surfaces already, and uploading a surface is an
+* error rather than a no-op.
+*/
+function resolveHwUpload(device, decodeHwAccel) {
+	if (device === void 0) return "";
+	if (!isSoftwareDecode(decodeHwAccel)) return "";
+	return "format=nv12,hwupload";
 }
 /** Rate-control args for an encode plan. */
 function buildRateControlArgs(video) {
@@ -3534,7 +3558,7 @@ function buildRateControlArgs(video) {
 	];
 }
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-function buildVideoArgs(video, outputArgs, filterGraph) {
+function buildVideoArgs(video, outputArgs, filterGraph, hwEncode) {
 	if (video.kind === "raw") {
 		if (filterGraph && video.filter !== void 0) throw new Error("FfmpegInvocation: video.filter cannot be combined with a filter graph — fold the filter into the graph");
 		return [
@@ -3554,8 +3578,10 @@ function buildVideoArgs(video, outputArgs, filterGraph) {
 			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
 		];
 	}
+	const hwUpload = hwEncode === void 0 ? "" : resolveHwUpload(hwEncode.device, hwEncode.decodeHwAccel);
+	if (hwEncode !== void 0 && filterGraph) throw new Error("FfmpegInvocation: a hardware encode fed by a filter graph must upload INSIDE the graph — hwEncodeDevice cannot be combined with filterGraph");
 	const args = [
-		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph, hwUpload),
 		"-c:v",
 		video.encoder
 	];
@@ -3725,10 +3751,18 @@ function buildAudioSidecarArgs(sidecar) {
 * (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
 * output, not as whatever the main output happens to carry.
 */
+/** The hardware-encode context for this invocation, or `undefined`. */
+function hwEncodeFor(inv) {
+	return inv.hwEncodeDevice === void 0 ? void 0 : {
+		device: inv.hwEncodeDevice,
+		decodeHwAccel: inv.decodeHwAccel
+	};
+}
 function buildFfmpegArgs(inv) {
 	const graph = inv.filterGraph ?? null;
 	const head = [
 		...logBannerArgs(inv.logLevel),
+		...inv.hwEncodeDevice !== void 0 ? ["-vaapi_device", inv.hwEncodeDevice.renderNode] : [],
 		...buildInputArgs(inv.input, inv.decodeHwAccel),
 		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
 		...graph ? ["-filter_complex", graph.graph] : []
@@ -3742,7 +3776,7 @@ function buildFfmpegArgs(inv) {
 			"-an",
 			"-map",
 			maps.video ?? "0:v:0",
-			...buildVideoArgs(inv.video, inv.outputArgs, graph),
+			...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 			...threadArgs,
 			...inv.outputArgs,
 			...buildRtpOutputArgs(inv.sink.video)
@@ -3765,7 +3799,7 @@ function buildFfmpegArgs(inv) {
 	return [
 		...head,
 		...videoMapArgs,
-		...buildVideoArgs(inv.video, inv.outputArgs, graph),
+		...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 		...threadArgs,
 		...mutedAudio ? [] : audioMapArgs,
 		...audioArgs,
@@ -4205,6 +4239,7 @@ var CameraSwitchIdSchema = z.enum([
 	"device-audio",
 	"broker-audio",
 	"audio-analysis",
+	"event-saving",
 	"recording",
 	"notifications"
 ]);
@@ -4231,6 +4266,7 @@ var CAMERA_SWITCH_ORDER = [
 	"device-audio",
 	"broker-audio",
 	"audio-analysis",
+	"event-saving",
 	"recording",
 	"notifications"
 ];
@@ -4814,11 +4850,31 @@ var RecordingBandTriggersSchema = RecordingTriggersSchema;
 * band engine's `applies` rule). `start`/`end` are `HH:MM`; an `end <= start`
 * span wraps past midnight (handled by the band engine).
 */
+/**
+* Whether a band's footage carries sound.
+*
+* The recorder has always attached with `audio: 'aac'`, so every band of every
+* camera recorded sound whether anyone wanted it or not. The broker already
+* serves the other answer — `audio: 'none'` takes the video-only `/muted`
+* restream — so this was a choice the product could always have offered.
+*
+* It belongs on the BAND rather than the camera because one camera can want
+* both: silent across the shop floor during opening hours, sound overnight.
+* And it applies to BOTH modes — an events band firing on motion has the same
+* question to answer as a continuous one.
+*/
+var RecordingBandAudioSchema = z.enum(["on", "muted"]);
 var RecordingBandSchema = z.object({
 	days: z.array(RecordingWeekdaySchema),
 	start: z.string().regex(HHMM),
 	end: z.string().regex(HHMM),
 	mode: RecordingBandModeSchema,
+	/**
+	* Sound, or silence. OPTIONAL and absent-means-`on`: every recording
+	* written before this existed carried sound, and a band whose key is
+	* missing must keep meaning what it meant. See {@link RecordingBandAudioSchema}.
+	*/
+	audio: RecordingBandAudioSchema.optional(),
 	triggers: RecordingBandTriggersSchema.optional(),
 	/**
 	* RETIRED (D381). A band no longer carries a pre-buffer of its own.
@@ -19996,6 +20052,7 @@ var MediaFileKindEnum = z.enum([
 	"keyFrameSmall",
 	"thumbnailSmall",
 	"confirmationCrop",
+	"debugCrop",
 	"sceneFrame"
 ]);
 /**
@@ -22307,6 +22364,18 @@ var RunnerCameraConfigSchema = z.object({
 	motionStreamId: z.string(),
 	detectionStreamId: z.string(),
 	/**
+	* Which rung this camera's audio analysis listens on — `auto` (the lowest
+	* AVAILABLE native rung) or an explicit one.
+	*
+	* Not consumed by the runner: carried here so it travels with the camera's
+	* config the way `audioMotionWindowMs` does, and so the orchestrator's
+	* watchdog resolves the same stream the audio subscription did. OPTIONAL
+	* with no default — absent means `auto`, which is what every camera written
+	* before this field had, and an absent optional adds nothing to the
+	* generated cap-input defaults (D537).
+	*/
+	audioStreamPick: AudioStreamPickSchema.optional(),
+	/**
 	* Motion sources that can activate the pipeline. At least one must
 	* be present. Multiple sources OR-ed: any one firing arms the
 	* cooldown timer and transitions watching → active. The same
@@ -25941,6 +26010,104 @@ var WebrtcStreamChoiceSchema = z.object({
 	bitrateKbps: z.number().nullable()
 });
 /**
+* The last move the adaptive ladder made on this session, and the numbers it
+* rested on. Mirrors `LadderDecision` in the stream-broker's
+* `adaptive-controller.ts` — the log line's evidence, made readable.
+*
+* Nullability is load-bearing: `lossRatio: null` means the loss tracker had
+* no window to report, which is NOT a link with zero loss.
+*/
+var WebrtcLadderDecisionSchema = z.object({
+	/** `loss` — RTCP / client-reported packet loss; `stall` — the picture
+	*  stopped moving; `healthy` — a promotion. */
+	cause: z.enum([
+		"loss",
+		"stall",
+		"healthy"
+	]),
+	/** The rung the ladder moved TO. Null for a move that changed no rung
+	*  (an MTU reduction, a forced transcode-down at the bottom). */
+	tier: CamProfileSchema.nullable(),
+	/** Whether that move forced the egress transcode-down rung. */
+	forcedTranscodeDown: z.boolean(),
+	/** Loss ratio over the tracker's window at the moment of the decision. */
+	lossRatio: z.number().nullable(),
+	/** The client's reported downlink at that moment, in kbps. */
+	clientKbps: z.number().nullable(),
+	/** How long the stall detector had been seeing nothing arrive. */
+	stalledForMs: z.number().nullable(),
+	/** Whether the broker WAS sending while that was measured — the half that
+	*  separates "the camera stopped" from "the link stopped". */
+	serverSending: z.boolean().nullable(),
+	/** Epoch ms. The overlay prints its age; a decision from 40 minutes ago
+	*  must not read like one from this second. */
+	at: z.number()
+});
+/** Per-tier count of MEASURED downgrades this viewer session has suffered. */
+var WebrtcTierFailureSchema = z.object({
+	tier: CamProfileSchema,
+	failures: z.number().int().nonnegative()
+});
+/**
+* What the SERVER decided for one WebRTC session — the half the client cannot
+* measure. See `getSessionDebug`.
+*/
+var WebrtcSessionDebugSchema = z.object({
+	sessionId: z.string(),
+	/** Whether the session still exists here. Everything below is null when
+	*  it does not — a dead session has no measurements, not zero ones. */
+	alive: z.boolean(),
+	/** Epoch ms this snapshot was taken, so the overlay can show its age. */
+	observedAt: z.number(),
+	/** The broker actually feeding this session (`<deviceId>/<camStreamId>`). */
+	brokerId: z.string().nullable(),
+	camStreamId: z.string().nullable(),
+	/** `derived` = this hub BUILT the rung being served (a transcode/scale of
+	*  another stream); `native` = the camera's own encode. */
+	sourceKind: z.enum([
+		"native",
+		"derived",
+		"unknown"
+	]),
+	/** Whether the ladder is running at all (an `adaptive` target). */
+	adaptive: z.boolean(),
+	/** The rung `auto` ACTUALLY resolved to right now. Null when the broker
+	*  is bound to no profile slot (a manually-activated stream). */
+	servedTier: CamProfileSchema.nullable(),
+	/** Which node ingests the source. Null when unresolved. */
+	ingestNodeId: z.string().nullable(),
+	/** Whether that node is a remote one (the media crosses a node boundary
+	*  before it reaches this session). Null when unresolved. */
+	ingestIsRemote: z.boolean().nullable(),
+	/** Codec off the source, and the one negotiated with this client. */
+	sourceCodec: z.string().nullable(),
+	negotiatedCodec: z.string().nullable(),
+	/** Whether the EGRESS leg re-encodes for this client or forwards the
+	*  source bytes untouched. */
+	egressLeg: z.enum([
+		"copy",
+		"transcode",
+		"unknown"
+	]),
+	/** What the broker itself reports about the rung it is serving. */
+	brokerStatus: z.string().nullable(),
+	brokerCodec: z.string().nullable(),
+	brokerBitrateKbps: z.number().nullable(),
+	brokerInputFps: z.number().nullable(),
+	brokerUptimeMs: z.number().nullable(),
+	/** RTP packets this session has sent — the server's own "am I sending?". */
+	rtpPacketsSent: z.number().nullable(),
+	/** D42: the track may be carrying the recorded feeder, not live. The ladder
+	*  is suspended there, so a frozen picture in `recorded` mode means
+	*  something entirely different. */
+	trackMode: z.enum(["live", "recorded"]).nullable(),
+	lastDecision: WebrtcLadderDecisionSchema.nullable(),
+	tierFailures: z.array(WebrtcTierFailureSchema),
+	/** Successful promotions in this viewer session (drives the progressive
+	*  healthy timer). Null when no ladder is running. */
+	upgradeCount: z.number().nullable()
+});
+/**
 * WebRTC session — device-scoped facade over the system `webrtc` cap.
 *
 * Exposes per-device signaling (`createSession`, `handleAnswer`,
@@ -26180,7 +26347,27 @@ var webrtcSessionCapability = {
 			* the same answer as "it ended": either way nothing is holding it up.
 			*/
 			alive: z.boolean()
-		}))
+		})),
+		/**
+		* The SERVER's half of the stream-debug overlay, for one live session.
+		*
+		* The client can measure its own transport (`getStats()`); it cannot see
+		* which rung `auto` actually resolved to, why the ladder last moved, or
+		* whether the rung it is being served is the camera's own encode or
+		* something this hub built. That asymmetry is why "quality is stuck on
+		* low" reports have historically been unanswerable from the viewer alone.
+		*
+		* EVERY measurement here is nullable and `null` means UNKNOWN, never zero
+		* (D393): a session whose ladder has never moved reports
+		* `lastDecision: null`, which is a different fact from a ladder that moved
+		* for `healthy` with a 0 loss ratio.
+		*
+		* Read-only, ~1 Hz, polled by the overlay only while it is visible.
+		*/
+		getSessionDebug: method(z.object({
+			deviceId: z.number().int().nonnegative(),
+			sessionId: z.string()
+		}), WebrtcSessionDebugSchema, { kind: "query" })
 	},
 	/** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
 	mount: { kind: "server-provided" }
@@ -45782,6 +45969,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"webrtcSession.getSessionDebug": {
+		capName: "webrtc-session",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"webrtcSession.getSessionState": {
 		capName: "webrtc-session",
 		capScope: "device",
@@ -47765,6 +47958,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"webrtcSession.getSessionDebug": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"webrtcSession.getSessionState": [{
 		name: "deviceId",
 		form: "single",

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-_YWIPtUH.js");
+const require_dist = require("./dist-C_4Xt0Ya.js");
 const require_builtins_alerts_alerts_addon = require("./builtins/alerts/alerts.addon.js");
 require("./builtins/alerts/index.js");
 const require_formatter = require("./formatter-DqAKDlvN.js");
@@ -94942,14 +94942,19 @@ function runnerRssBudgetMb(addons) {
 	return declared.length === 0 ? void 0 : Math.max(...declared);
 }
 /**
-* Per-placement V8 heap flags (Block D). LIGHT runners cap their young generation
-* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — and
-* keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
+* Per-placement V8 flags (Block D). LIGHT runners cap their young generation
+* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — bound
+* V8's platform thread pool (`--v8-pool-size`, see {@link LIGHT_V8_POOL_SIZE_DEFAULT}: a measured
+* ~58 threads across the hub's 29 light runners, against a cgroup `pids.max` this host has already
+* hit) and keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
 * runners keep V8's default young generation but ALWAYS carry an old-space ceiling; see
 * {@link HEAVY_MAX_OLD_MB_DEFAULT} for why, and how a runner declares its own.
 *
 * Kill-switch: `CAMSTACK_RUNNER_HEAP_TUNING=off` disables all flags (recover without a rebuild).
-* Overrides: `CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB` (default 2), `CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`
+* Overrides: `CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB` (default 2),
+* `CAMSTACK_RUNNER_LIGHT_V8_POOL_SIZE` (default {@link LIGHT_V8_POOL_SIZE_DEFAULT}; below 1 omits
+* the flag — `0` means "size from the CPU count" to V8, not "off"),
+* `CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`
 * (default unset = no old-space cap), `CAMSTACK_RUNNER_HEAVY_MAX_OLD_MB`
 * (default {@link HEAVY_MAX_OLD_MB_DEFAULT}; `0` restores the old uncapped behaviour).
 */
@@ -94960,6 +94965,8 @@ function runnerHeapFlags(addons) {
 	if (!heavy) {
 		const semiMb = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB", 2);
 		if (semiMb > 0) flags.push(`--max-semi-space-size=${semiMb}`);
+		const v8Pool = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_V8_POOL_SIZE", 2);
+		if (v8Pool > 0) flags.push(`--v8-pool-size=${v8Pool}`);
 	}
 	const oldMb = runnerMaxOldSpaceMb(addons, heavy);
 	if (oldMb > 0) flags.push(`--max-old-space-size=${oldMb}`);

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 { An as readinessKey, Cn as expandCapMethods, F as addonSettingsCapability, Ft as procedureAuthKey, Mn as scopeKey, Mt as objectInputDeclaresAddonId, On as parseJsonObject, Pn as EventCategory$1, S as RUNTIME_DEFAULTS, Tt as looseSchema, Ut as scopesAllowAddon, Vt as resolveMethodAuth, Wt as scopesAllowDeviceCap, _n as asJsonObject$1, _t as isVoidInput, an as errMsg$1, bn as createEvent, bt as lifecycleJobSchema, cn as DATAPLANE_SECRET_HEADER$1, dt as isArrayOutputSchema, ft as isCollectionArrayMethod, g as LOG_LEVEL_RANK, hn as ReadinessTimeoutError, jn as resolveCapMount, kn as parseJsonUnknown, ln as DEVICE_SETTINGS_CONTRIBUTION_METHODS, mn as ReadinessRegistry, mt as isObjectInput, st as extractNestedAddonId, t as ALL_CAPABILITY_DEFINITIONS, un as DEVICE_STATUS_METHOD, vn as asNumber, vt as kebabToCamel, wt as logLevelAtMost, xn as emitDownForOwnedCaps, y as METHOD_ACCESS_MAP, yn as asString$1 } from "./dist-Diz59Dhi.mjs";
+import { An as readinessKey, Cn as expandCapMethods, F as addonSettingsCapability, Ft as procedureAuthKey, Mn as scopeKey, Mt as objectInputDeclaresAddonId, On as parseJsonObject, Pn as EventCategory$1, S as RUNTIME_DEFAULTS, Tt as looseSchema, Ut as scopesAllowAddon, Vt as resolveMethodAuth, Wt as scopesAllowDeviceCap, _n as asJsonObject$1, _t as isVoidInput, an as errMsg$1, bn as createEvent, bt as lifecycleJobSchema, cn as DATAPLANE_SECRET_HEADER$1, dt as isArrayOutputSchema, ft as isCollectionArrayMethod, g as LOG_LEVEL_RANK, hn as ReadinessTimeoutError, jn as resolveCapMount, kn as parseJsonUnknown, ln as DEVICE_SETTINGS_CONTRIBUTION_METHODS, mn as ReadinessRegistry, mt as isObjectInput, st as extractNestedAddonId, t as ALL_CAPABILITY_DEFINITIONS, un as DEVICE_STATUS_METHOD, vn as asNumber, vt as kebabToCamel, wt as logLevelAtMost, xn as emitDownForOwnedCaps, y as METHOD_ACCESS_MAP, yn as asString$1 } from "./dist-DchKwh_m.mjs";
 import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
 import "./builtins/alerts/index.mjs";
 import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -94935,14 +94935,19 @@ function runnerRssBudgetMb(addons) {
 	return declared.length === 0 ? void 0 : Math.max(...declared);
 }
 /**
-* Per-placement V8 heap flags (Block D). LIGHT runners cap their young generation
-* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — and
-* keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
+* Per-placement V8 flags (Block D). LIGHT runners cap their young generation
+* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — bound
+* V8's platform thread pool (`--v8-pool-size`, see {@link LIGHT_V8_POOL_SIZE_DEFAULT}: a measured
+* ~58 threads across the hub's 29 light runners, against a cgroup `pids.max` this host has already
+* hit) and keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
 * runners keep V8's default young generation but ALWAYS carry an old-space ceiling; see
 * {@link HEAVY_MAX_OLD_MB_DEFAULT} for why, and how a runner declares its own.
 *
 * Kill-switch: `CAMSTACK_RUNNER_HEAP_TUNING=off` disables all flags (recover without a rebuild).
-* Overrides: `CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB` (default 2), `CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`
+* Overrides: `CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB` (default 2),
+* `CAMSTACK_RUNNER_LIGHT_V8_POOL_SIZE` (default {@link LIGHT_V8_POOL_SIZE_DEFAULT}; below 1 omits
+* the flag — `0` means "size from the CPU count" to V8, not "off"),
+* `CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`
 * (default unset = no old-space cap), `CAMSTACK_RUNNER_HEAVY_MAX_OLD_MB`
 * (default {@link HEAVY_MAX_OLD_MB_DEFAULT}; `0` restores the old uncapped behaviour).
 */
@@ -94953,6 +94958,8 @@ function runnerHeapFlags(addons) {
 	if (!heavy) {
 		const semiMb = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB", 2);
 		if (semiMb > 0) flags.push(`--max-semi-space-size=${semiMb}`);
+		const v8Pool = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_V8_POOL_SIZE", 2);
+		if (v8Pool > 0) flags.push(`--v8-pool-size=${v8Pool}`);
 	}
 	const oldMb = runnerMaxOldSpaceMb(addons, heavy);
 	if (oldMb > 0) flags.push(`--max-old-space-size=${oldMb}`);

package/dist/kernel/moleculer/process-service.d.ts

@@ -59,6 +59,60 @@ interface RunnerAddonSpec {
  * Reaching for a bigger number here when RSS is the complaint is the standard wrong move.
  */
 export declare const HEAVY_MAX_OLD_MB_DEFAULT = 1024;
+/**
+ * V8 platform worker threads for a LIGHT runner (`--v8-pool-size`).
+ *
+ * ## What this bounds
+ *
+ * Node gives every process a V8 platform thread pool — background compilation,
+ * parallel marking and sweeping — defaulted to 4. It is not the libuv pool
+ * (`UV_THREADPOOL_SIZE`, which serves `fs`/`dns`/`zlib`/`crypto`) and it is
+ * deliberately not touched here; see below.
+ *
+ * ## Why it is worth a flag
+ *
+ * A container cgroup counts THREADS, not processes, and this cluster forks a
+ * runner per addon (D2). Measured on the live hub 2026-09-18 (20 cores,
+ * `pids.max=2048`), after 22 fork refusals in 45 minutes earlier that day:
+ *
+ *   pids.current 991 · 47 node processes holding 469 threads
+ *   of those, 29 LIGHT runners holding 274 (mean 9.4 threads each)
+ *
+ * A light runner is a control-plane addon with a 2 MB young generation. It does
+ * not generate the background GC work four marking threads exist for, and it
+ * pays 4 threads of the cgroup's pid budget for them anyway. Two returns ~58
+ * threads — ~6% of the container's live thread count — for background GC that
+ * is, on these heaps, a few milliseconds a cycle.
+ *
+ * ## Why TWO and never ZERO
+ *
+ * `--v8-pool-size=0` does not disable the pool: it tells V8 to size it from the
+ * detected parallelism. Measured locally 2026-09-18 on a node process holding
+ * the libuv pool open:
+ *
+ *   default            11 threads
+ *   --v8-pool-size=2    9 threads
+ *   --v8-pool-size=0   18 threads
+ *
+ * So a value below 1 omits the flag entirely rather than being passed through —
+ * the same trap as `MALLOC_ARENA_MAX=0` in `runner-native-allocator.ts`. To turn
+ * the tuning off, use `CAMSTACK_RUNNER_HEAP_TUNING=off`.
+ *
+ * ## What is deliberately NOT bounded
+ *
+ * HEAVY runners keep V8's default: they hold real heaps (the recorder declares
+ * 3072 MB) where parallel marking is the difference between a pause and a stall.
+ *
+ * `UV_THREADPOOL_SIZE` is left alone on every runner. Its 4 threads are lazily
+ * spawned, and the measurement above says most light runners have spawned all
+ * four — i.e. they really do run concurrent `fs` work. Halving that would trade
+ * ~58 more threads for serialized filesystem I/O in runners whose I/O profile
+ * has not been measured, on a media system. A thread saving is not worth a
+ * media gap.
+ *
+ * Override: `CAMSTACK_RUNNER_LIGHT_V8_POOL_SIZE`.
+ */
+export declare const LIGHT_V8_POOL_SIZE_DEFAULT = 2;
 interface SpawnedProcess {
     readonly pid: number;
     readonly nodeId: string;

package/dist/{retired-settings-keys-C2ocoH_l.js → retired-settings-keys-6wZNp7lr.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-_YWIPtUH.js");
+const require_dist = require("./dist-C_4Xt0Ya.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-C_Hg5d37.mjs → retired-settings-keys-DPSHUHMu.mjs}

@@ -1,4 +1,4 @@
-import { _n as asJsonObject } from "./dist-Diz59Dhi.mjs";
+import { _n as asJsonObject } from "./dist-DchKwh_m.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/package.json

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