@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/moleculer/node-registry.d.ts

@@ -1,147 +1,147 @@
 /**
- * HubNodeRegistry — the single authority for which capabilities each
- * cluster node provides. Holds the union of node manifests delivered by
- * the D3 `$hub.registerNode` handshake; a node is dropped on
- * `$node.disconnected`. Pure data — no Moleculer, no timers, no scan.
- */
+* HubNodeRegistry — the single authority for which capabilities each
+* cluster node provides. Holds the union of node manifests delivered by
+* the D3 `$hub.registerNode` handshake; a node is dropped on
+* `$node.disconnected`. Pure data — no Moleculer, no timers, no scan.
+*/
 /**
- * A capability call function — routes a method call to a remote cap provider
- * via Moleculer. Moved here from `capability-bridge.ts` when that file was
- * deleted as part of the D3 clean-up (Task 11).
- */
+* A capability call function — routes a method call to a remote cap provider
+* via Moleculer. Moved here from `capability-bridge.ts` when that file was
+* deleted as part of the D3 clean-up (Task 11).
+*/
 type CallFn = (method: string, params: unknown, targetNodeId?: string) => Promise<unknown>;
 /** One addon's contribution within a node's registration manifest. */
 interface RegisteredAddonManifest {
-    readonly addonId: string;
-    readonly capabilities: readonly string[];
+	readonly addonId: string;
+	readonly capabilities: readonly string[];
 }
 /**
- * One device-scoped native cap a node hosts, with the device ids that
- * registered it and the addonId of the registering addon. Device-scoped
- * native caps (`ctx.registerNativeCap` from a `BaseDevice` subclass) are
- * registered per device AFTER the node's system caps, once background device
- * restore completes — so the node re-handshakes carrying these once they are
- * known (D3 idempotent replace).
- *
- * `addonId` is required for the hub to build the correct Moleculer proxy
- * target (`<addonId>.native-provider.<capName>.<method>`). It replaces the
- * pull-based `syncWorkerNativeCaps` discovery sweep (Task 13).
- */
+* One device-scoped native cap a node hosts, with the device ids that
+* registered it and the addonId of the registering addon. Device-scoped
+* native caps (`ctx.registerNativeCap` from a `BaseDevice` subclass) are
+* registered per device AFTER the node's system caps, once background device
+* restore completes — so the node re-handshakes carrying these once they are
+* known (D3 idempotent replace).
+*
+* `addonId` is required for the hub to build the correct Moleculer proxy
+* target (`<addonId>.native-provider.<capName>.<method>`). It replaces the
+* pull-based `syncWorkerNativeCaps` discovery sweep (Task 13).
+*/
 interface RegisteredNativeCap {
-    readonly capName: string;
-    readonly addonId: string;
-    readonly deviceIds: readonly number[];
+	readonly capName: string;
+	readonly addonId: string;
+	readonly deviceIds: readonly number[];
 }
 /**
- * A node's runtime-updatable ROOT package identity (`@camstack/server` — the
- * single root package for every node role) — carried in the `registerNode`
- * manifest so the hub knows every node's exact software version (design:
- * runtime-updatable node packages, "visibility"). Version skew is SEEN in
- * the UI instead of discovered via a black-hole.
- */
+* A node's runtime-updatable ROOT package identity (`@camstack/server` — the
+* single root package for every node role) — carried in the `registerNode`
+* manifest so the hub knows every node's exact software version (design:
+* runtime-updatable node packages, "visibility"). Version skew is SEEN in
+* the UI instead of discovered via a black-hole.
+*/
 interface NodeRootPackageInfo {
-    readonly name: string;
-    readonly version: string;
+	readonly name: string;
+	readonly version: string;
 }
 /** Payload of the `$hub.registerNode` RPC — a node's COMPLETE manifest. */
 interface RegisterNodeParams {
-    readonly nodeId: string;
-    readonly addons: readonly RegisteredAddonManifest[];
-    /**
-     * Device-scoped native caps the node hosts. Optional — absent (or empty)
-     * on the FIRST handshake, populated by the re-handshake the node fires
-     * after `runWorkerDeviceRestoreWithRetry` completes. Each entry includes
-     * the registering `addonId` so the hub can build the correct Moleculer
-     * proxy target without the pull-based discovery sweep (Task 13).
-     */
-    readonly nativeCaps?: readonly RegisteredNativeCap[];
-    /**
-     * SHA-256 hash of the node's cluster secret. Optional — absent
-     * when the node has no secret configured. Verified by the `registerNode`
-     * receiver; never carries the raw secret. (Cluster-secret registration gate.)
-     */
-    readonly clusterSecretHash?: string;
-    /**
-     * The node's root-package identity. Optional — absent from UDS child
-     * manifests and pre-phase-2 agents; present on agents running the
-     * runtime-updatable root model.
-     */
-    readonly rootPackage?: NodeRootPackageInfo;
+	readonly nodeId: string;
+	readonly addons: readonly RegisteredAddonManifest[];
+	/**
+	* Device-scoped native caps the node hosts. Optional — absent (or empty)
+	* on the FIRST handshake, populated by the re-handshake the node fires
+	* after `runWorkerDeviceRestoreWithRetry` completes. Each entry includes
+	* the registering `addonId` so the hub can build the correct Moleculer
+	* proxy target without the pull-based discovery sweep (Task 13).
+	*/
+	readonly nativeCaps?: readonly RegisteredNativeCap[];
+	/**
+	* SHA-256 hash of the node's cluster secret. Optional — absent
+	* when the node has no secret configured. Verified by the `registerNode`
+	* receiver; never carries the raw secret. (Cluster-secret registration gate.)
+	*/
+	readonly clusterSecretHash?: string;
+	/**
+	* The node's root-package identity. Optional — absent from UDS child
+	* manifests and pre-phase-2 agents; present on agents running the
+	* runtime-updatable root model.
+	*/
+	readonly rootPackage?: NodeRootPackageInfo;
 }
 /** Ack returned by `$hub.registerNode` — presence of `ok` is the signal. */
 interface RegisterNodeResult {
-    readonly ok: true;
+	readonly ok: true;
 }
 /** Flattened registry view: one row per (node, addon, capability). */
 interface NodeCapEntry {
-    readonly nodeId: string;
-    readonly addonId: string;
-    readonly capName: string;
+	readonly nodeId: string;
+	readonly addonId: string;
+	readonly capName: string;
 }
 /** Flattened native-cap view: one row per (node, native cap, device). */
 interface NodeNativeCapEntry {
-    readonly nodeId: string;
-    readonly addonId: string;
-    readonly capName: string;
-    readonly deviceId: number;
+	readonly nodeId: string;
+	readonly addonId: string;
+	readonly capName: string;
+	readonly deviceId: number;
 }
 declare class HubNodeRegistry {
-    /** nodeId → its complete addon manifest (last `registerNode` wins). */
-    private readonly nodes;
-    /** nodeId → its device-scoped native caps (last `registerNode` wins). */
-    private readonly nativeCaps;
-    /** nodeId → its root-package identity (last `registerNode` wins). */
-    private readonly rootPackages;
-    /**
-     * deviceId → flat native-cap entries for THAT device, across all nodes.
-     * Maintained incrementally on every `registerNode`/`removeNode` so a
-     * per-device lookup is O(caps-for-device) instead of flattening the whole
-     * cluster (`listNativeCapEntries()`) and filtering — the latter makes the
-     * per-device `getBindings`, run for every device in `getAllBindings`, an
-     * O(D²·C) boot-time hot spot. Insertion order mirrors `listNativeCapEntries`
-     * (node-registration order) so consumers that take the first match are
-     * unaffected.
-     */
-    private readonly nativeCapsByDevice;
-    /**
-     * Drop every `nativeCapsByDevice` entry contributed by `nodeId`, reading the
-     * node's CURRENT (about-to-be-replaced) native caps to know which device
-     * rows it touched. Must run BEFORE `nativeCaps` is overwritten/deleted.
-     */
-    private dropNodeFromDeviceIndex;
-    /**
-     * Replace the node's ENTIRE manifest atomically — addons AND native
-     * caps. Idempotent: a reconnect, hot-update, or post-device-restore
-     * re-handshake simply overwrites. Partial state is impossible because
-     * the node sends its complete picture every time.
-     */
-    registerNode(params: RegisterNodeParams): void;
-    /** Drop a node entirely — caps AND native caps — on `$node.disconnected`. */
-    removeNode(nodeId: string): void;
-    /** The node's root-package identity, or null when it never reported one. */
-    getNodeRootPackage(nodeId: string): NodeRootPackageInfo | null;
-    /** The node's manifest, or undefined when the node never registered. */
-    getNodeManifest(nodeId: string): readonly RegisteredAddonManifest[] | undefined;
-    /**
-     * The node's device-scoped native caps. `[]` when the node registered
-     * without any (or has not yet re-handshaked post-device-restore);
-     * `undefined` when the node never registered at all.
-     */
-    getNodeNativeCaps(nodeId: string): readonly RegisteredNativeCap[] | undefined;
-    /** Flat (nodeId, addonId, capName) view of the whole cluster. */
-    listEntries(): readonly NodeCapEntry[];
-    /** Flat (nodeId, addonId, capName, deviceId) native-cap view of the whole cluster. */
-    listNativeCapEntries(): readonly NodeNativeCapEntry[];
-    /**
-     * Native-cap entries for ONE device, across all nodes — O(caps-for-device).
-     * Equivalent to `listNativeCapEntries().filter(e => e.deviceId === deviceId)`
-     * but served from the incrementally-maintained `nativeCapsByDevice` index, so
-     * per-device resolution (and `getAllBindings`, which runs it per device)
-     * doesn't flatten the whole cluster each call.
-     */
-    listNativeCapEntriesForDevice(deviceId: number): readonly NodeNativeCapEntry[];
-    /** Every node id currently registered. */
-    listNodeIds(): readonly string[];
+	/** nodeId → its complete addon manifest (last `registerNode` wins). */
+	private readonly nodes;
+	/** nodeId → its device-scoped native caps (last `registerNode` wins). */
+	private readonly nativeCaps;
+	/** nodeId → its root-package identity (last `registerNode` wins). */
+	private readonly rootPackages;
+	/**
+	* deviceId → flat native-cap entries for THAT device, across all nodes.
+	* Maintained incrementally on every `registerNode`/`removeNode` so a
+	* per-device lookup is O(caps-for-device) instead of flattening the whole
+	* cluster (`listNativeCapEntries()`) and filtering — the latter makes the
+	* per-device `getBindings`, run for every device in `getAllBindings`, an
+	* O(D²·C) boot-time hot spot. Insertion order mirrors `listNativeCapEntries`
+	* (node-registration order) so consumers that take the first match are
+	* unaffected.
+	*/
+	private readonly nativeCapsByDevice;
+	/**
+	* Drop every `nativeCapsByDevice` entry contributed by `nodeId`, reading the
+	* node's CURRENT (about-to-be-replaced) native caps to know which device
+	* rows it touched. Must run BEFORE `nativeCaps` is overwritten/deleted.
+	*/
+	private dropNodeFromDeviceIndex;
+	/**
+	* Replace the node's ENTIRE manifest atomically — addons AND native
+	* caps. Idempotent: a reconnect, hot-update, or post-device-restore
+	* re-handshake simply overwrites. Partial state is impossible because
+	* the node sends its complete picture every time.
+	*/
+	registerNode(params: RegisterNodeParams): void;
+	/** Drop a node entirely — caps AND native caps — on `$node.disconnected`. */
+	removeNode(nodeId: string): void;
+	/** The node's root-package identity, or null when it never reported one. */
+	getNodeRootPackage(nodeId: string): NodeRootPackageInfo | null;
+	/** The node's manifest, or undefined when the node never registered. */
+	getNodeManifest(nodeId: string): readonly RegisteredAddonManifest[] | undefined;
+	/**
+	* The node's device-scoped native caps. `[]` when the node registered
+	* without any (or has not yet re-handshaked post-device-restore);
+	* `undefined` when the node never registered at all.
+	*/
+	getNodeNativeCaps(nodeId: string): readonly RegisteredNativeCap[] | undefined;
+	/** Flat (nodeId, addonId, capName) view of the whole cluster. */
+	listEntries(): readonly NodeCapEntry[];
+	/** Flat (nodeId, addonId, capName, deviceId) native-cap view of the whole cluster. */
+	listNativeCapEntries(): readonly NodeNativeCapEntry[];
+	/**
+	* Native-cap entries for ONE device, across all nodes — O(caps-for-device).
+	* Equivalent to `listNativeCapEntries().filter(e => e.deviceId === deviceId)`
+	* but served from the incrementally-maintained `nativeCapsByDevice` index, so
+	* per-device resolution (and `getAllBindings`, which runs it per device)
+	* doesn't flatten the whole cluster each call.
+	*/
+	listNativeCapEntriesForDevice(deviceId: number): readonly NodeNativeCapEntry[];
+	/** Every node id currently registered. */
+	listNodeIds(): readonly string[];
 }
 export { HubNodeRegistry };
-export type { CallFn, NodeRootPackageInfo, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams, RegisterNodeResult, NodeCapEntry, NodeNativeCapEntry, };
+export type { CallFn, NodeRootPackageInfo, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams, RegisterNodeResult, NodeCapEntry, NodeNativeCapEntry };

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

@@ -1,4 +1,4 @@
-import { ServiceBroker } from 'moleculer';
-import { IAddonProcessManager } from '@camstack/types';
+import type { ServiceBroker } from "moleculer";
+import type { IAddonProcessManager } from "@camstack/types";
 declare function createScopedProcessManager(broker: ServiceBroker, addonId: string): IAddonProcessManager;
 export { createScopedProcessManager };

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

@@ -1,185 +1,185 @@
-import { ChildProcess, SpawnOptions } from 'node:child_process';
-import { ServiceSchema } from 'moleculer';
-import { ProcessGroupOps } from './runner-process-group.js';
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { ServiceSchema } from "moleculer";
+import { type ProcessGroupOps } from "./runner-process-group.js";
 /** One addon hosted inside a runner subprocess. */
 interface RunnerAddonSpec {
-    readonly addonId: string;
-    readonly addonDir: string;
+	readonly addonId: string;
+	readonly addonDir: string;
 }
 /**
- * Default old-space ceiling for a HEAVY runner, in MB.
- *
- * ## Why a heavy runner needs a ceiling at all
- *
- * `heapProfile: 'heavy'` used to mean "V8 defaults", i.e. no `--max-old-space-size` — which on this
- * host is V8's own memory-derived default (multiple GB). Nothing then bounds a burst, and V8 does
- * not hand committed pages back (the long argument for that is in `kernel/heap-watch.ts`), so a
- * one-off burst becomes the runner's permanent RSS.
- *
- * Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
- * there. The same addon on two agent nodes carrying the same code and a smaller archive sits at
- * **58 MB**.
- *
- * ⚠ This paragraph used to attribute that ~2 GB to "walk garbage" from the deferred archive walk,
- * and to argue from a ~21 MB `RecordingIndex`. Both were wrong, and the error cost a session on
- * 2026-08-27. The deferred walk had NO CALLER and never ran (it has since been deleted). And the
- * index is not 21 MB: a 2026-08-27 profile of the live recorder read `heapUsed = 1606 MB` against
- * `external = 8 MB`, with an `smaps` census putting 1510 MB in V8's 256 KB page ranges against
- * 54 MB of native heap — LIVE JavaScript retainers, not high-water garbage. The retained set is
- * ~7.1 M `SegmentRow`s plus their path strings and Map entries (13 cameras x 2 profiles x 8 640
- * segments/day x ~30 days), reseeded at boot by `SegmentHourLedger.hydrateIndex`.
- *
- * The lesson for anyone sizing this flag: a heap number needs a RETAINER, and "garbage the GC has
- * no reason to collect" is the explanation to reach for last, not first.
- *
- * ## Why 1024
- *
- * From the same live topology snapshot, every heavy runner's FULL RSS — which is a strict
- * over-estimate of its old space, since it also contains native allocations, `external` and
- * `arrayBuffers`, none of which `--max-old-space-size` bounds:
- *
- *   detection 471 MB · provider-reolink 507 MB · pipeline-orchestrator 238 MB · ml 218 MB ·
- *   snapshot 185 MB · decoder-nodeav 174 MB · audio-analyzer 170 MB
- *
- * 1024 MB clears the largest of those by ~2x while cutting the recorder's observed ratchet by
- * more than half. It is a CEILING, not a target: a runner that fits today keeps behaving exactly
- * as it does now, because V8 only collects harder as it approaches the limit.
- *
- * A runner whose working set genuinely does not fit declares its own number in its manifest
- * (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
- * `recorder` (3072 MB; peak 2341 MB heapTotal) is the one shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
- * `arrayBuffers` (47 RTP rings), which this flag does not bound and never will — its actual old
- * space peaks at 224 MB. Size the declaration from `heapTotal` in the `[mem]` heartbeat, never
- * from RSS.
- *
- * ## What this flag CANNOT do
- *
- * It bounds old space and nothing else — not `external`, not `arrayBuffers`, not what a native
- * addon mallocs. `hub/pipeline-analytics` reached 7334 MB RSS with this flag set to 1024 the
- * whole time, because 96% of it was native. That half is bounded in `runner-native-allocator.ts`.
- * Reaching for a bigger number here when RSS is the complaint is the standard wrong move.
- */
+* Default old-space ceiling for a HEAVY runner, in MB.
+*
+* ## Why a heavy runner needs a ceiling at all
+*
+* `heapProfile: 'heavy'` used to mean "V8 defaults", i.e. no `--max-old-space-size` — which on this
+* host is V8's own memory-derived default (multiple GB). Nothing then bounds a burst, and V8 does
+* not hand committed pages back (the long argument for that is in `kernel/heap-watch.ts`), so a
+* one-off burst becomes the runner's permanent RSS.
+*
+* Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
+* there. The same addon on two agent nodes carrying the same code and a smaller archive sits at
+* **58 MB**.
+*
+* ⚠ This paragraph used to attribute that ~2 GB to "walk garbage" from the deferred archive walk,
+* and to argue from a ~21 MB `RecordingIndex`. Both were wrong, and the error cost a session on
+* 2026-08-27. The deferred walk had NO CALLER and never ran (it has since been deleted). And the
+* index is not 21 MB: a 2026-08-27 profile of the live recorder read `heapUsed = 1606 MB` against
+* `external = 8 MB`, with an `smaps` census putting 1510 MB in V8's 256 KB page ranges against
+* 54 MB of native heap — LIVE JavaScript retainers, not high-water garbage. The retained set is
+* ~7.1 M `SegmentRow`s plus their path strings and Map entries (13 cameras x 2 profiles x 8 640
+* segments/day x ~30 days), reseeded at boot by `SegmentHourLedger.hydrateIndex`.
+*
+* The lesson for anyone sizing this flag: a heap number needs a RETAINER, and "garbage the GC has
+* no reason to collect" is the explanation to reach for last, not first.
+*
+* ## Why 1024
+*
+* From the same live topology snapshot, every heavy runner's FULL RSS — which is a strict
+* over-estimate of its old space, since it also contains native allocations, `external` and
+* `arrayBuffers`, none of which `--max-old-space-size` bounds:
+*
+*   detection 471 MB · provider-reolink 507 MB · pipeline-orchestrator 238 MB · ml 218 MB ·
+*   snapshot 185 MB · decoder-nodeav 174 MB · audio-analyzer 170 MB
+*
+* 1024 MB clears the largest of those by ~2x while cutting the recorder's observed ratchet by
+* more than half. It is a CEILING, not a target: a runner that fits today keeps behaving exactly
+* as it does now, because V8 only collects harder as it approaches the limit.
+*
+* A runner whose working set genuinely does not fit declares its own number in its manifest
+* (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
+* `recorder` (3072 MB; peak 2341 MB heapTotal) is the one shipped addon that does. `stream-broker` does NOT, despite 1585 MB peak RSS: ~1 GB of that is
+* `arrayBuffers` (47 RTP rings), which this flag does not bound and never will — its actual old
+* space peaks at 224 MB. Size the declaration from `heapTotal` in the `[mem]` heartbeat, never
+* from RSS.
+*
+* ## What this flag CANNOT do
+*
+* It bounds old space and nothing else — not `external`, not `arrayBuffers`, not what a native
+* addon mallocs. `hub/pipeline-analytics` reached 7334 MB RSS with this flag set to 1024 the
+* whole time, because 96% of it was native. That half is bounded in `runner-native-allocator.ts`.
+* 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 the flag is only ever passed with a value of at least 1 — the same trap as
- * `MALLOC_ARENA_MAX=0` in `runner-native-allocator.ts`.
- *
- * ## 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.
- */
+* 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 the flag is only ever passed with a value of at least 1 — the same trap as
+* `MALLOC_ARENA_MAX=0` in `runner-native-allocator.ts`.
+*
+* ## 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.
+*/
 export declare const LIGHT_V8_POOL_SIZE_DEFAULT = 2;
 interface SpawnedProcess {
-    readonly pid: number;
-    readonly nodeId: string;
-    readonly name: string;
-    /**
-     * Synthetic supervisor label `runner:${runnerId}` — the real list of
-     * hosted addons lives on `runnerAddons`. The normal case is a size-1
-     * `runnerAddons` array (one addon, one process); the media-pipeline
-     * group is the sole multi-addon exception.
-     */
-    readonly addonId: string;
-    readonly addonDir: string;
-    /** Every addon hosted by this runner subprocess (size 1 in the normal case). */
-    readonly runnerAddons: readonly RunnerAddonSpec[];
-    readonly startedAt: number;
-    restartCount: number;
-    /**
-     * Runner lifecycle state. `failed` is terminal — the D6 crash
-     * circuit-breaker tripped (too many crashes inside `CRASH_WINDOW_MS`)
-     * and the runner will NOT be respawned. `crashed` is transient — the
-     * window between an exit and the next backoff respawn.
-     */
-    state: 'starting' | 'running' | 'stopping' | 'stopped' | 'crashed' | 'failed';
-    child: ChildProcess;
-    /** The runner leads its own process group (POSIX, D668); its pgid is its `pid`. */
-    readonly ownsGroup: boolean;
-    /** The reap of this runner's group, once started. Memoized: every exit path shares it. */
-    groupReap: Promise<void> | null;
+	readonly pid: number;
+	readonly nodeId: string;
+	readonly name: string;
+	/**
+	* Synthetic supervisor label `runner:${runnerId}` — the real list of
+	* hosted addons lives on `runnerAddons`. The normal case is a size-1
+	* `runnerAddons` array (one addon, one process); the media-pipeline
+	* group is the sole multi-addon exception.
+	*/
+	readonly addonId: string;
+	readonly addonDir: string;
+	/** Every addon hosted by this runner subprocess (size 1 in the normal case). */
+	readonly runnerAddons: readonly RunnerAddonSpec[];
+	readonly startedAt: number;
+	restartCount: number;
+	/**
+	* Runner lifecycle state. `failed` is terminal — the D6 crash
+	* circuit-breaker tripped (too many crashes inside `CRASH_WINDOW_MS`)
+	* and the runner will NOT be respawned. `crashed` is transient — the
+	* window between an exit and the next backoff respawn.
+	*/
+	state: "starting" | "running" | "stopping" | "stopped" | "crashed" | "failed";
+	child: ChildProcess;
+	/** The runner leads its own process group (POSIX, D668); its pgid is its `pid`. */
+	readonly ownsGroup: boolean;
+	/** The reap of this runner's group, once started. Memoized: every exit path shares it. */
+	groupReap: Promise<void> | null;
 }
 interface ProcessInfo {
-    readonly pid: number;
-    readonly nodeId: string;
-    readonly name: string;
-    readonly addonId: string;
-    /**
-     * The full list of addon ids inside this runner subprocess. Size 1 in
-     * the normal one-addon-one-process case; longer only for the media
-     * group. Cluster page UI expands this to render every addon under the
-     * same process card so operators see what's running where.
-     */
-    readonly addonIds: readonly string[];
-    /** Runner label — the `runnerId` this subprocess was spawned with. */
-    readonly groupId: string;
-    readonly isolated: boolean;
-    readonly spawnedBy: string | null;
-    readonly startedAt: number;
-    readonly restartCount: number;
-    readonly state: string;
-    readonly cpuPercent: number;
-    readonly memoryRss: number;
-    readonly uptimeSeconds: number;
+	readonly pid: number;
+	readonly nodeId: string;
+	readonly name: string;
+	readonly addonId: string;
+	/**
+	* The full list of addon ids inside this runner subprocess. Size 1 in
+	* the normal one-addon-one-process case; longer only for the media
+	* group. Cluster page UI expands this to render every addon under the
+	* same process card so operators see what's running where.
+	*/
+	readonly addonIds: readonly string[];
+	/** Runner label — the `runnerId` this subprocess was spawned with. */
+	readonly groupId: string;
+	readonly isolated: boolean;
+	readonly spawnedBy: string | null;
+	readonly startedAt: number;
+	readonly restartCount: number;
+	readonly state: string;
+	readonly cpuPercent: number;
+	readonly memoryRss: number;
+	readonly uptimeSeconds: number;
 }
 /**
- * Subprocess spawner injected into `createProcessService`. Production
- * code passes `child_process.spawn`; tests pass a fake that records
- * the call shape and returns a stub `ChildProcess`. Centralising the
- * dependency here is the only ESM-safe way to intercept spawn — the
- * `node:child_process` module export is non-configurable so `vi.spyOn`
- * fails. The injection point is private to this module: callers don't
- * see it, so the public `createProcessService(parentNodeId, dataDir)`
- * shape stays unchanged.
- */
+* Subprocess spawner injected into `createProcessService`. Production
+* code passes `child_process.spawn`; tests pass a fake that records
+* the call shape and returns a stub `ChildProcess`. Centralising the
+* dependency here is the only ESM-safe way to intercept spawn — the
+* `node:child_process` module export is non-configurable so `vi.spyOn`
+* fails. The injection point is private to this module: callers don't
+* see it, so the public `createProcessService(parentNodeId, dataDir)`
+* shape stays unchanged.
+*/
 type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) => ChildProcess;
 interface ProcessServiceDeps {
-    readonly spawnFn?: SpawnFn;
-    /** Group signalling + member listing. Tests inject a fake: a fake pid must never be signalled. */
-    readonly processGroups?: ProcessGroupOps;
-    /** Platform deciding whether a runner leads a process group. Defaults to `process.platform`. */
-    readonly platform?: NodeJS.Platform;
+	readonly spawnFn?: SpawnFn;
+	/** Group signalling + member listing. Tests inject a fake: a fake pid must never be signalled. */
+	readonly processGroups?: ProcessGroupOps;
+	/** Platform deciding whether a runner leads a process group. Defaults to `process.platform`. */
+	readonly platform?: NodeJS.Platform;
 }
 declare function createProcessService(parentNodeId: string, dataDir: string, deps?: ProcessServiceDeps, parentTcpPort?: number, parentUdsPath?: string): ServiceSchema;
 export type { ProcessInfo, SpawnedProcess };