@camstack/system 1.2.389 → 1.2.391

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

@@ -1,14 +1,14 @@
-import { ServiceBroker } from 'moleculer';
+import type { ServiceBroker } from "moleculer";
 /**
- * Per-broker provider registries. In production there is one broker per
- * process, so these behave like module-scoped singletons. In tests that
- * spin up multiple brokers in the same process, each broker gets its
- * own isolated set of maps so providers don't leak across nodes.
- */
+* Per-broker provider registries. In production there is one broker per
+* process, so these behave like module-scoped singletons. In tests that
+* spin up multiple brokers in the same process, each broker gets its
+* own isolated set of maps so providers don't leak across nodes.
+*/
 interface BrokerRegistries {
-    readonly providers: Map<string, unknown[]>;
-    readonly preferred: Map<string, string>;
-    readonly byAddonId: Map<string, Map<string, unknown>>;
+	readonly providers: Map<string, unknown[]>;
+	readonly preferred: Map<string, string>;
+	readonly byAddonId: Map<string, Map<string, unknown>>;
 }
 declare function getRegistries(brokerNodeId: string): BrokerRegistries;
 export { getRegistries };

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

@@ -1,67 +1,67 @@
-import { IEventBus, IScopedLogger } from '@camstack/types';
-import { ReadinessRegistry } from '@camstack/types/addon';
-import { ServiceBroker } from 'moleculer';
+import type { IEventBus, IScopedLogger } from "@camstack/types";
+import { ReadinessRegistry } from "@camstack/types/addon";
+import type { ServiceBroker } from "moleculer";
 /**
- * Minimal interface for the `LocalChildClient` surface used in UDS-mode
- * readiness hydration. Declared here (rather than importing the concrete
- * class) so this module stays free of a direct transport dependency and
- * remains independently testable with a plain fake object.
- */
+* Minimal interface for the `LocalChildClient` surface used in UDS-mode
+* readiness hydration. Declared here (rather than importing the concrete
+* class) so this module stays free of a direct transport dependency and
+* remains independently testable with a plain fake object.
+*/
 interface UdsReadinessClient {
-    /** True once `start()` has connected and registered with the parent. */
-    readonly isConnected: boolean;
-    /** Request the current readiness snapshot from the parent over UDS. */
-    requestReadinessSnapshot(): Promise<readonly import('@camstack/types').IReadinessRegistryRecord[]>;
-    /** Register a callback fired each time the client connects (including reconnects). */
-    onConnected(cb: () => void): void;
+	/** True once `start()` has connected and registered with the parent. */
+	readonly isConnected: boolean;
+	/** Request the current readiness snapshot from the parent over UDS. */
+	requestReadinessSnapshot(): Promise<readonly import("@camstack/types").IReadinessRegistryRecord[]>;
+	/** Register a callback fired each time the client connects (including reconnects). */
+	onConnected(cb: () => void): void;
 }
 /**
- * Return the shared ReadinessRegistry for this broker — one per
- * process is enough. Every addon context on the same broker gets the
- * same instance via `ctx.kernel.readinessRegistry`.
- *
- * For non-hub brokers (forked workers + remote agents) the registry
- * is hydrated from the hub's `$readiness.getSnapshot` Moleculer action
- * on every `$node.connected` — this closes the boot-time race where
- * `broker.broadcast` consumers on the hub fire before the worker is
- * in the cluster, and makes hub reconnects refresh consumer state
- * without forcing every producer to re-emit. Live deltas continue
- * through the normal `system.ready-state` event bridge; hydrate skips
- * entries already observed locally.
- */
+* Return the shared ReadinessRegistry for this broker — one per
+* process is enough. Every addon context on the same broker gets the
+* same instance via `ctx.kernel.readinessRegistry`.
+*
+* For non-hub brokers (forked workers + remote agents) the registry
+* is hydrated from the hub's `$readiness.getSnapshot` Moleculer action
+* on every `$node.connected` — this closes the boot-time race where
+* `broker.broadcast` consumers on the hub fire before the worker is
+* in the cluster, and makes hub reconnects refresh consumer state
+* without forcing every producer to re-emit. Live deltas continue
+* through the normal `system.ready-state` event bridge; hydrate skips
+* entries already observed locally.
+*/
 declare function getOrInitReadinessRegistry(broker: ServiceBroker, eventBus: IEventBus, logger: IScopedLogger): ReadinessRegistry;
 /**
- * Return (or create) the shared `ReadinessRegistry` for a UDS-only child
- * process — one per child node id. The registry is hydrated from the parent
- * over UDS instead of via `$readiness.getSnapshot` Moleculer action.
- *
- * **Hydration strategy:**
- *   - Initial snapshot: `client.requestReadinessSnapshot()` is called once
- *     `client.isConnected` becomes true (the `onConnected` callback).
- *   - Reconnect: each time `onConnected` fires again (the client re-connected
- *     after a parent-side restart), a fresh snapshot is pulled so pending
- *     `awaitReady` callers can unblock.
- *   - Live deltas: `system.ready-state` events arrive via the UDS event bus
- *     (Phase C) — the registry ingests them through its own event-bus
- *     subscription, exactly as in broker mode.
- *
- * **Periodic reconcile (D8):**
- *   The original design assumed the parent reliably forwards every
- *   `system.ready-state` delta over UDS, so no reconcile signal beyond
- *   the (re)connect hydrate was added. The 2026-07-17 incident disproved
- *   the assumption end-to-end: a delta can be lost across the full
- *   producer→parent→child path (restart churn, subscription races), and
- *   a child that saw `starting` then never got `ready` wedged forever.
- *   The registry therefore ALSO re-pulls the parent snapshot every
- *   `READINESS_RECONCILE_INTERVAL_MS` while connected — combined with
- *   `hydrate`'s advance semantics, a lost delta costs one reconcile
- *   round, never forever. No new parent-to-child protocol message is
- *   needed (the existing snapshot request is reused).
- *
- * **`awaitReady`/`acquireCapability`/`onReadyState` semantics unchanged.**
- *
- * Keep `$readiness.getSnapshot` (broker path) intact — Phase F removes it.
- */
+* Return (or create) the shared `ReadinessRegistry` for a UDS-only child
+* process — one per child node id. The registry is hydrated from the parent
+* over UDS instead of via `$readiness.getSnapshot` Moleculer action.
+*
+* **Hydration strategy:**
+*   - Initial snapshot: `client.requestReadinessSnapshot()` is called once
+*     `client.isConnected` becomes true (the `onConnected` callback).
+*   - Reconnect: each time `onConnected` fires again (the client re-connected
+*     after a parent-side restart), a fresh snapshot is pulled so pending
+*     `awaitReady` callers can unblock.
+*   - Live deltas: `system.ready-state` events arrive via the UDS event bus
+*     (Phase C) — the registry ingests them through its own event-bus
+*     subscription, exactly as in broker mode.
+*
+* **Periodic reconcile (D8):**
+*   The original design assumed the parent reliably forwards every
+*   `system.ready-state` delta over UDS, so no reconcile signal beyond
+*   the (re)connect hydrate was added. The 2026-07-17 incident disproved
+*   the assumption end-to-end: a delta can be lost across the full
+*   producer→parent→child path (restart churn, subscription races), and
+*   a child that saw `starting` then never got `ready` wedged forever.
+*   The registry therefore ALSO re-pulls the parent snapshot every
+*   `READINESS_RECONCILE_INTERVAL_MS` while connected — combined with
+*   `hydrate`'s advance semantics, a lost delta costs one reconcile
+*   round, never forever. No new parent-to-child protocol message is
+*   needed (the existing snapshot request is reused).
+*
+* **`awaitReady`/`acquireCapability`/`onReadyState` semantics unchanged.**
+*
+* Keep `$readiness.getSnapshot` (broker path) intact — Phase F removes it.
+*/
 declare function getOrInitReadinessRegistryForClient(client: UdsReadinessClient, eventBus: IEventBus, logger: IScopedLogger, nodeId: string): ReadinessRegistry;
 export type { UdsReadinessClient };
 export { getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient };

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

@@ -1,22 +1,37 @@
-import { ServiceSchema } from 'moleculer';
-import { IReadinessRegistry, IReadinessRegistryRecord } from '@camstack/types';
 /**
- * Service name AGENTS register their own readiness snapshot under.
- *
- * Deliberately NOT `$readiness`: agents call `$readiness.getSnapshot`
- * UNQUALIFIED to reach the hub's authoritative registry, and Moleculer
- * prefers a local service for an unqualified call — an agent registering
- * `$readiness` would shadow the hub and hydrate from itself. The hub
- * pulls `$agent-readiness.getSnapshot` with an explicit `{ nodeID }` on
- * every agent (re)connect + periodically, closing the reverse leg of the
- * D8 snapshot-reconcile (the hub otherwise learns agent readiness only
- * from lossy cross-node event broadcasts).
- */
+* Hub-side `$readiness` Moleculer service. Exposes a single
+* `getSnapshot` action that returns the hub's current `ReadinessRegistry`
+* state as a plain array of `ReadinessRecord` objects.
+*
+* Every worker / remote agent hydrates its local registry from this
+* snapshot on first `$node.connected` — this eliminates the boot-time
+* race where `broker.broadcast` fires before the remote joined the
+* cluster. Live deltas continue to flow through the normal
+* `system.ready-state` event bridge.
+*
+* The service name is prefixed with `$` so it doesn't appear in the
+* addon / capability graph. Callers invoke it via
+* `broker.call('$readiness.getSnapshot')`.
+*/
+import type { ServiceSchema } from "moleculer";
+import type { IReadinessRegistry, IReadinessRegistryRecord } from "@camstack/types";
+/**
+* Service name AGENTS register their own readiness snapshot under.
+*
+* Deliberately NOT `$readiness`: agents call `$readiness.getSnapshot`
+* UNQUALIFIED to reach the hub's authoritative registry, and Moleculer
+* prefers a local service for an unqualified call — an agent registering
+* `$readiness` would shadow the hub and hydrate from itself. The hub
+* pulls `$agent-readiness.getSnapshot` with an explicit `{ nodeID }` on
+* every agent (re)connect + periodically, closing the reverse leg of the
+* D8 snapshot-reconcile (the hub otherwise learns agent readiness only
+* from lossy cross-node event broadcasts).
+*/
 export declare const AGENT_READINESS_SERVICE_NAME = "$agent-readiness";
 export interface ReadinessServiceDeps {
-    readonly getSnapshot: () => readonly IReadinessRegistryRecord[];
-    /** Service name override — default `$readiness` (the hub-authoritative instance). */
-    readonly name?: string;
+	readonly getSnapshot: () => readonly IReadinessRegistryRecord[];
+	/** Service name override — default `$readiness` (the hub-authoritative instance). */
+	readonly name?: string;
 }
 export declare function createReadinessService(deps: ReadinessServiceDeps): ServiceSchema;
 export declare function createReadinessServiceForRegistry(registry: IReadinessRegistry, name?: string): ServiceSchema;

package/dist/kernel/moleculer/register-framework-resolver.d.ts

@@ -1,8 +1,8 @@
 /**
- * Register the ESM resolver hook so this runner's addon imports of the
- * host-provided packages (@camstack/system, @camstack/types, …) resolve from
- * `frameworkDir/node_modules` instead of failing to walk up from the addon's
- * isolated `/data/addons/<addon>` folder. No-op in dev (frameworkDir unset),
- * where workspace symlinks already resolve the framework.
- */
+* Register the ESM resolver hook so this runner's addon imports of the
+* host-provided packages (@camstack/system, @camstack/types, …) resolve from
+* `frameworkDir/node_modules` instead of failing to walk up from the addon's
+* isolated `/data/addons/<addon>` folder. No-op in dev (frameworkDir unset),
+* where workspace symlinks already resolve the framework.
+*/
 export declare function registerFrameworkResolver(frameworkDir: string | undefined): void;

package/dist/kernel/moleculer/register-node-client.d.ts

@@ -1,38 +1,45 @@
-import { NodeRootPackageInfo, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams } from './node-registry.js';
+/**
+* Registration-handshake client (D3). A node, once it has finished
+* mounting every service, calls this to push its COMPLETE capability
+* manifest to its parent (`$hub.registerNode` for hub children + agents,
+* `$agent.registerNode` for an agent's own children). Retries the CALL
+* until the parent acks — reliability is the ack, never a timer.
+*/
+import type { NodeRootPackageInfo, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams } from "./node-registry.js";
 /** Minimal broker surface this client needs. */
 interface RegisterNodeBroker {
-    call(action: string, params: unknown, opts?: {
-        nodeID?: string;
-    }): Promise<unknown>;
+	call(action: string, params: unknown, opts?: {
+		nodeID?: string;
+	}): Promise<unknown>;
 }
 interface CallRegisterNodeOptions {
-    /** `'hub'` → `$hub.registerNode`; `'agent'` → `$agent.registerNode`. */
-    readonly target: 'hub' | 'agent';
-    /** Required when target is `'agent'` — the agent's nodeID to route to. */
-    readonly targetNodeId?: string;
-    /** First retry delay; doubles each attempt, capped at 5000ms. Default 250. */
-    readonly baseDelayMs?: number;
-    /** Abort the retry loop (e.g. on node shutdown). */
-    readonly signal?: AbortSignal;
-    /** Optional logger for retry diagnostics. */
-    readonly log?: (msg: string) => void;
+	/** `'hub'` → `$hub.registerNode`; `'agent'` → `$agent.registerNode`. */
+	readonly target: "hub" | "agent";
+	/** Required when target is `'agent'` — the agent's nodeID to route to. */
+	readonly targetNodeId?: string;
+	/** First retry delay; doubles each attempt, capped at 5000ms. Default 250. */
+	readonly baseDelayMs?: number;
+	/** Abort the retry loop (e.g. on node shutdown). */
+	readonly signal?: AbortSignal;
+	/** Optional logger for retry diagnostics. */
+	readonly log?: (msg: string) => void;
 }
 /**
- * Build a `RegisterNodeParams` from a node id, its per-addon manifests,
- * optionally its device-scoped native caps, optionally the SHA-256 hash
- * of the cluster secret, and optionally the node's root-package identity
- * (runtime-updatable node packages: version visibility). `nativeCaps` is
- * omitted entirely on the first handshake; `clusterSecretHash` is omitted
- * when no secret is configured; `rootPackage` is omitted by nodes that do
- * not run the root-package model (UDS children).
- */
+* Build a `RegisterNodeParams` from a node id, its per-addon manifests,
+* optionally its device-scoped native caps, optionally the SHA-256 hash
+* of the cluster secret, and optionally the node's root-package identity
+* (runtime-updatable node packages: version visibility). `nativeCaps` is
+* omitted entirely on the first handshake; `clusterSecretHash` is omitted
+* when no secret is configured; `rootPackage` is omitted by nodes that do
+* not run the root-package model (UDS children).
+*/
 declare function buildNodeManifest(nodeId: string, addons: readonly RegisteredAddonManifest[], nativeCaps?: readonly RegisteredNativeCap[], clusterSecretHash?: string, rootPackage?: NodeRootPackageInfo): RegisterNodeParams;
 /**
- * Call `<target>.registerNode` and retry until the parent acks. The loop
- * terminates ONLY on a successful ack or an abort — there is no fixed
- * attempt cap, because the real terminating condition is "the hub
- * received it", not "we tried N times".
- */
+* Call `<target>.registerNode` and retry until the parent acks. The loop
+* terminates ONLY on a successful ack or an abort — there is no fixed
+* attempt cap, because the real terminating condition is "the hub
+* received it", not "we tried N times".
+*/
 declare function callRegisterNodeWithRetry(broker: RegisterNodeBroker, params: RegisterNodeParams, opts: CallRegisterNodeOptions): Promise<void>;
 export { callRegisterNodeWithRetry, buildNodeManifest };
 export type { RegisterNodeBroker, CallRegisterNodeOptions };

package/dist/kernel/moleculer/remote-logger.d.ts

@@ -1,43 +1,43 @@
-import { ServiceBroker } from 'moleculer';
-import { IScopedLogger, LogTags } from '@camstack/types';
-import { BrokerLike } from './event-bus.js';
+import type { ServiceBroker } from "moleculer";
+import type { IScopedLogger, LogTags } from "@camstack/types";
+import type { BrokerLike } from "./event-bus.js";
 /**
- * Call after `broker.waitForServices('$hub')` to enable log forwarding.
- *
- * Marks the broker connected and flushes any log lines buffered during
- * the pre-discovery window. With no argument (test harnesses), every
- * known broker state is connected and flushed — the buffered entries
- * carry their own dispatch closures so no broker reference is needed.
- */
+* Call after `broker.waitForServices('$hub')` to enable log forwarding.
+*
+* Marks the broker connected and flushes any log lines buffered during
+* the pre-discovery window. With no argument (test harnesses), every
+* known broker state is connected and flushed — the buffered entries
+* carry their own dispatch closures so no broker reference is needed.
+*/
 declare function setHubConnected(broker?: ServiceBroker): void;
 /**
- * Test-only: clear all per-broker hub-connection state + buffers and the
- * process-wide baseline so specs that create brokers in sequence start
- * from a clean slate. Production never calls this.
- */
+* Test-only: clear all per-broker hub-connection state + buffers and the
+* process-wide baseline so specs that create brokers in sequence start
+* from a clean slate. Production never calls this.
+*/
 declare function __resetHubConnectedForTests(): void;
 export { __resetHubConnectedForTests };
 declare function createRemoteLogger(broker: ServiceBroker, addonId: string, scope?: string, tags?: LogTags): IScopedLogger;
 export { createRemoteLogger };
 /**
- * Build a hub-forwarding logger for a forked-process runner (process-runner
- * / group-runner). The runner has no `AddonContext` of its own — its own
- * diagnostics ("started", "handshake failed", …) would otherwise be raw
- * `console.*` that never reaches the hub `LogManager`. This routes them
- * through the same `$hub.log` transport every addon logger uses, with the
- * Part A pre-connect buffer so boot-time lines survive.
- *
- * `scope` lets the runner tag its own lines (e.g. `process-runner`) so the
- * hub renderer distinguishes runner plumbing from the hosted addon's output.
- */
+* Build a hub-forwarding logger for a forked-process runner (process-runner
+* / group-runner). The runner has no `AddonContext` of its own — its own
+* diagnostics ("started", "handshake failed", …) would otherwise be raw
+* `console.*` that never reaches the hub `LogManager`. This routes them
+* through the same `$hub.log` transport every addon logger uses, with the
+* Part A pre-connect buffer so boot-time lines survive.
+*
+* `scope` lets the runner tag its own lines (e.g. `process-runner`) so the
+* hub renderer distinguishes runner plumbing from the hosted addon's output.
+*/
 declare function createRunnerLogger(broker: ServiceBroker, addonId: string, scope: string): IScopedLogger;
 export { createRunnerLogger };
 /**
- * Test-only: build a remote logger against a structural broker spy.
- * `createRemoteLogger` only touches `broker.nodeID` + `broker.call`, so a
- * minimal stand-in is enough — this avoids spinning a real `ServiceBroker`
- * just to assert the pre-connect buffer behaviour.
- */
+* Test-only: build a remote logger against a structural broker spy.
+* `createRemoteLogger` only touches `broker.nodeID` + `broker.call`, so a
+* minimal stand-in is enough — this avoids spinning a real `ServiceBroker`
+* just to assert the pre-connect buffer behaviour.
+*/
 declare function __createRemoteLoggerForTests(broker: BrokerLike, addonId: string): IScopedLogger;
 export { __createRemoteLoggerForTests };
 export { setHubConnected };

package/dist/kernel/moleculer/resilient-cap-call.d.ts

@@ -1,28 +1,28 @@
 /**
- * D3 — resilient cross-process capability call.
- *
- * The `$hub.registerNode` handshake registers a cap proxy the moment the
- * RPC lands — decoupled from Moleculer's service-discovery INFO packet,
- * which propagates separately. A call through the proxy in that window
- * fails with `ServiceNotFoundError`. This wraps a `broker.call` so that,
- * on a discovery error, it waits for Moleculer to discover the service
- * (the framework-native `waitForServices` primitive) and retries ONCE.
- * Happy path (service already discovered) pays nothing. If the service
- * genuinely never appears, `waitForServices` rejects → fail-fast.
- */
+* D3 — resilient cross-process capability call.
+*
+* The `$hub.registerNode` handshake registers a cap proxy the moment the
+* RPC lands — decoupled from Moleculer's service-discovery INFO packet,
+* which propagates separately. A call through the proxy in that window
+* fails with `ServiceNotFoundError`. This wraps a `broker.call` so that,
+* on a discovery error, it waits for Moleculer to discover the service
+* (the framework-native `waitForServices` primitive) and retries ONCE.
+* Happy path (service already discovered) pays nothing. If the service
+* genuinely never appears, `waitForServices` rejects → fail-fast.
+*/
 /** Minimal broker surface this helper needs. */
 export interface ServiceDiscoveryBroker {
-    call(action: string, params: unknown, opts: {
-        nodeID?: string;
-        timeout?: number;
-    }): Promise<unknown>;
-    waitForServices(services: string[], timeout?: number): Promise<unknown>;
+	call(action: string, params: unknown, opts: {
+		nodeID?: string;
+		timeout?: number;
+	}): Promise<unknown>;
+	waitForServices(services: string[], timeout?: number): Promise<unknown>;
 }
 /**
- * Call a Moleculer action; on a service-discovery error, wait for the
- * named service to be discovered and retry the call exactly once.
- */
+* Call a Moleculer action; on a service-discovery error, wait for the
+* named service to be discovered and retry the call exactly once.
+*/
 export declare function callWithServiceDiscovery(broker: ServiceDiscoveryBroker, serviceName: string, action: string, params: unknown, opts: {
-    nodeID?: string;
-    timeout?: number;
+	nodeID?: string;
+	timeout?: number;
 }, discoveryTimeoutMs?: number): Promise<unknown>;

package/dist/kernel/moleculer/runner-native-allocator.d.ts

@@ -1,107 +1,107 @@
 /**
- * Native-allocator environment for a forked addon runner.
- *
- * ## The half of a runner's memory that no V8 flag reaches
- *
- * `--max-old-space-size` bounds V8's old space and nothing else. It does not
- * bound `external`, it does not bound `arrayBuffers`, and it does not bound what
- * a native addon (`sharp`/`libvips`, decoders, codecs) allocates through `malloc`.
- *
- * Measured on the live hub, 2026-08-25, over a ~6h window of `[mem]` heartbeats:
- *
- *   hub/pipeline-analytics  rss 309-7334MB   heapTotal max 343MB   external max 5479MB
- *
- * It already carried `--max-old-space-size=1024`, so the flag was in force the
- * whole time and the process still reached 7.3GB — because 96% of it was never
- * V8's to bound. Its reclaim line names the shape exactly:
- *
- *   reclaim hub/pipeline-analytics stranded=2552MB rss=2765MB→2647MB
- *           freed=118MB arrayBuffers=81MB→29MB took=58ms
- *
- * The `arrayBuffers` FLOOR returns to ~1MB every cycle, so this is not a leak.
- * It is glibc holding freed pages: with `MALLOC_ARENA_MAX` unset, glibc opens up
- * to `8 × ncpu` arenas — 160 on this 20-core host — and each keeps its own free
- * list, which is returned to the OS only when the top of that arena is free.
- *
- * ## Why this matters more than the cgroup number suggests
- *
- * The container is capped at 24GiB and `memory.current` rides at 21-24GB. Near
- * the limit the kernel performs direct reclaim IN THE CONTEXT OF THE TASK THAT
- * ALLOCATES, so every process in the container stalls together — measured as
- * four idle, mutually unrelated runners sharing one ~39s stall in the same
- * sample. Returning stranded pages is therefore not a tidiness win; it is what
- * keeps unrelated runners off the direct-reclaim path.
- *
- * ## Why `VIPS_CONCURRENCY` is welded to it
- *
- * `sharp` reads `MALLOC_ARENA_MAX` in its NATIVE binding (not in JS — grepping
- * the bundle finds nothing). Unset on glibc, sharp pins libvips concurrency to 1
- * as its own fragmentation defence; the moment the variable appears it restores
- * concurrency to `availableParallelism()`. Verified in the live container:
- *
- *   MALLOC_ARENA_MAX unset                  → sharp.concurrency() === 1
- *   MALLOC_ARENA_MAX=2                      → sharp.concurrency() === 20
- *   MALLOC_ARENA_MAX=2 VIPS_CONCURRENCY=1   → sharp.concurrency() === 1
- *
- * Shipping the arena bound alone would therefore have quietly shipped a 1→20
- * libvips threading change to the busiest addon on a host already at ~75% CPU,
- * under the banner of a memory fix. This module ships the allocator change and
- * ONLY the allocator change; raising libvips concurrency is a separate decision.
- *
- * ## What it costs, measured
- *
- * Same container, same 12-image corpus, same pipeline as analytics (decode →
- * extract → resize → encode → raw), 3 interleaved pairs so host load cancels,
- * concurrency pinned to 1 on both arms:
- *
- *   arenas default : mean 51.9ms  p50 60.0ms  p90 67.3ms  p99 70.7ms  rss 505MB
- *   arenas=2       : mean 51.5ms  p50 57.6ms  p90 67.2ms  p99 72.9ms  rss 354MB
- *
- * Latency is unchanged inside noise (-0.8% mean, +3.1% p99); the same work is
- * done in 30% less RSS.
- */
+* Native-allocator environment for a forked addon runner.
+*
+* ## The half of a runner's memory that no V8 flag reaches
+*
+* `--max-old-space-size` bounds V8's old space and nothing else. It does not
+* bound `external`, it does not bound `arrayBuffers`, and it does not bound what
+* a native addon (`sharp`/`libvips`, decoders, codecs) allocates through `malloc`.
+*
+* Measured on the live hub, 2026-08-25, over a ~6h window of `[mem]` heartbeats:
+*
+*   hub/pipeline-analytics  rss 309-7334MB   heapTotal max 343MB   external max 5479MB
+*
+* It already carried `--max-old-space-size=1024`, so the flag was in force the
+* whole time and the process still reached 7.3GB — because 96% of it was never
+* V8's to bound. Its reclaim line names the shape exactly:
+*
+*   reclaim hub/pipeline-analytics stranded=2552MB rss=2765MB→2647MB
+*           freed=118MB arrayBuffers=81MB→29MB took=58ms
+*
+* The `arrayBuffers` FLOOR returns to ~1MB every cycle, so this is not a leak.
+* It is glibc holding freed pages: with `MALLOC_ARENA_MAX` unset, glibc opens up
+* to `8 × ncpu` arenas — 160 on this 20-core host — and each keeps its own free
+* list, which is returned to the OS only when the top of that arena is free.
+*
+* ## Why this matters more than the cgroup number suggests
+*
+* The container is capped at 24GiB and `memory.current` rides at 21-24GB. Near
+* the limit the kernel performs direct reclaim IN THE CONTEXT OF THE TASK THAT
+* ALLOCATES, so every process in the container stalls together — measured as
+* four idle, mutually unrelated runners sharing one ~39s stall in the same
+* sample. Returning stranded pages is therefore not a tidiness win; it is what
+* keeps unrelated runners off the direct-reclaim path.
+*
+* ## Why `VIPS_CONCURRENCY` is welded to it
+*
+* `sharp` reads `MALLOC_ARENA_MAX` in its NATIVE binding (not in JS — grepping
+* the bundle finds nothing). Unset on glibc, sharp pins libvips concurrency to 1
+* as its own fragmentation defence; the moment the variable appears it restores
+* concurrency to `availableParallelism()`. Verified in the live container:
+*
+*   MALLOC_ARENA_MAX unset                  → sharp.concurrency() === 1
+*   MALLOC_ARENA_MAX=2                      → sharp.concurrency() === 20
+*   MALLOC_ARENA_MAX=2 VIPS_CONCURRENCY=1   → sharp.concurrency() === 1
+*
+* Shipping the arena bound alone would therefore have quietly shipped a 1→20
+* libvips threading change to the busiest addon on a host already at ~75% CPU,
+* under the banner of a memory fix. This module ships the allocator change and
+* ONLY the allocator change; raising libvips concurrency is a separate decision.
+*
+* ## What it costs, measured
+*
+* Same container, same 12-image corpus, same pipeline as analytics (decode →
+* extract → resize → encode → raw), 3 interleaved pairs so host load cancels,
+* concurrency pinned to 1 on both arms:
+*
+*   arenas default : mean 51.9ms  p50 60.0ms  p90 67.3ms  p99 70.7ms  rss 505MB
+*   arenas=2       : mean 51.5ms  p50 57.6ms  p90 67.2ms  p99 72.9ms  rss 354MB
+*
+* Latency is unchanged inside noise (-0.8% mean, +3.1% p99); the same work is
+* done in 30% less RSS.
+*/
 /** Bounded glibc arenas per forked runner. */
 export declare const RUNNER_MALLOC_ARENA_MAX_DEFAULT = 2;
 /**
- * libvips worker threads per forked runner. `1` is not a tuning choice — it is
- * sharp's OWN default on glibc, pinned here so that bounding the arenas does not
- * change it as a side effect. See the module header.
- */
+* libvips worker threads per forked runner. `1` is not a tuning choice — it is
+* sharp's OWN default on glibc, pinned here so that bounding the arenas does not
+* change it as a side effect. See the module header.
+*/
 export declare const RUNNER_VIPS_CONCURRENCY_DEFAULT = 1;
 /**
- * The native-allocator variables to add to a runner's environment. Both keys are
- * present or both are absent — see the `VIPS_CONCURRENCY` note in the module
- * header for why one without the other is the dangerous configuration.
- */
+* The native-allocator variables to add to a runner's environment. Both keys are
+* present or both are absent — see the `VIPS_CONCURRENCY` note in the module
+* header for why one without the other is the dangerous configuration.
+*/
 export interface RunnerNativeAllocatorEnv {
-    readonly MALLOC_ARENA_MAX?: string;
-    readonly VIPS_CONCURRENCY?: string;
+	readonly MALLOC_ARENA_MAX?: string;
+	readonly VIPS_CONCURRENCY?: string;
 }
 /**
- * Resolve the native-allocator env for a child runner from the parent's env.
- *
- * Precedence, highest first:
- *   1. `CAMSTACK_RUNNER_NATIVE_ALLOCATOR=off` — kill switch, returns nothing and
- *      restores the glibc/sharp defaults. Recoverable without a rebuild.
- *   2. A value the operator already put in the environment (`MALLOC_ARENA_MAX`,
- *      `VIPS_CONCURRENCY`) — inherited verbatim, never overwritten.
- *   3. The defaults above.
- */
+* Resolve the native-allocator env for a child runner from the parent's env.
+*
+* Precedence, highest first:
+*   1. `CAMSTACK_RUNNER_NATIVE_ALLOCATOR=off` — kill switch, returns nothing and
+*      restores the glibc/sharp defaults. Recoverable without a rebuild.
+*   2. A value the operator already put in the environment (`MALLOC_ARENA_MAX`,
+*      `VIPS_CONCURRENCY`) — inherited verbatim, never overwritten.
+*   3. The defaults above.
+*/
 export declare function runnerNativeAllocatorEnv(parentEnv: NodeJS.ProcessEnv, platform?: NodeJS.Platform): RunnerNativeAllocatorEnv;
 /**
- * The child's environment, with the allocator pair applied or REMOVED.
- *
- * `runnerNativeAllocatorEnv` returns what to add. That was sufficient while the
- * parent had nothing to inherit: omitting a key meant the child never saw it.
- * Once the image entrypoint welds the pair into the container environment — the
- * change that lets an operator drop them from the Unraid template — the child
- * INHERITS them, and a kill switch that only omits is a kill switch that does
- * nothing.
- *
- * So `CAMSTACK_RUNNER_NATIVE_ALLOCATOR=off` DELETES. And only that: the
- * non-linux path returns nothing to add for its own reasons (the pin is a pure
- * throughput cut there — measured `sharp.concurrency()` 6 on the darwin agent
- * against 1 on the linux hub) and must not be read as "remove what the operator
- * chose". Deletion is the switch's job, not absence's.
- */
+* The child's environment, with the allocator pair applied or REMOVED.
+*
+* `runnerNativeAllocatorEnv` returns what to add. That was sufficient while the
+* parent had nothing to inherit: omitting a key meant the child never saw it.
+* Once the image entrypoint welds the pair into the container environment — the
+* change that lets an operator drop them from the Unraid template — the child
+* INHERITS them, and a kill switch that only omits is a kill switch that does
+* nothing.
+*
+* So `CAMSTACK_RUNNER_NATIVE_ALLOCATOR=off` DELETES. And only that: the
+* non-linux path returns nothing to add for its own reasons (the pin is a pure
+* throughput cut there — measured `sharp.concurrency()` 6 on the darwin agent
+* against 1 on the linux hub) and must not be read as "remove what the operator
+* chose". Deletion is the switch's job, not absence's.
+*/
 export declare function applyRunnerNativeAllocator(parentEnv: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;