@camstack/system 1.2.389 → 1.2.391

package/dist/kernel/heap-watch.d.ts

@@ -1,803 +1,803 @@
-import { EventPlaneReader } from './event-plane-report.js';
-import { SocketPlaneCounters, SocketPlaneReader } from './socket-plane-report.js';
-import { MeshPeerQueue, MeshQueueReader } from './moleculer/mesh-queue-report.js';
-import { OutboundQueueGateOptions, OutboundQueueReading } from './outbound-queue-watch.js';
-import { HeapSpaceReader } from './heap-spaces.js';
-import { NodeGcObserver } from './gc-census.js';
-import { TaskTicks } from './process-cpu-census.js';
-import { ArrayBufferCensus, ArrayBufferCensusGateOptions } from './array-buffer-census.js';
+import { type EventPlaneReader } from "./event-plane-report.js";
+import { type SocketPlaneCounters, type SocketPlaneReader } from "./socket-plane-report.js";
+import { type MeshPeerQueue, type MeshQueueReader } from "./moleculer/mesh-queue-report.js";
+import { type OutboundQueueGateOptions, type OutboundQueueReading } from "./outbound-queue-watch.js";
+import { type HeapSpaceReader } from "./heap-spaces.js";
+import { type NodeGcObserver } from "./gc-census.js";
+import { type TaskTicks } from "./process-cpu-census.js";
+import { type ArrayBufferCensus, type ArrayBufferCensusGateOptions } from "./array-buffer-census.js";
 /**
- * What hub-main calls itself in a `[mem]` line.
- *
- * ## Why not `hub/main`
- *
- * A runner's label is its nodeId, and a nodeId is built in exactly one place as
- * `` `${parentNodeId}/${runnerId}` `` (`kernel/moleculer/addon-runner.ts:222`) —
- * so every runner label contains a `/` and every hub-local one is `hub/<runner>`.
- * A label with NO slash therefore cannot be produced by that rule, which makes
- * `hub-main` unambiguous by construction rather than by convention: no future
- * addon, group or agent can ever claim it.
- *
- * It also sorts where it belongs. `-` (0x2D) precedes `/` (0x2F), so a sorted
- * `[mem]` census puts `hub-main` immediately before `hub/decoder`,
- * `hub/recorder`, `hub/stream-broker` — the composition root first, then the
- * runners it forked. `hub/main` would sort into the middle of its own children
- * and would be one addon id away from a collision.
- *
- * And it is the name the rest of this repository already uses — the docblocks,
- * {@link HUB_MAIN_RSS_BUDGET_MB}, {@link HUB_RSS_BUDGET_ENV}, every ADR. A log
- * label that disagreed with the prose would be a second vocabulary for one
- * process, which is the exact failure this telemetry exists to remove.
- */
+* What hub-main calls itself in a `[mem]` line.
+*
+* ## Why not `hub/main`
+*
+* A runner's label is its nodeId, and a nodeId is built in exactly one place as
+* `` `${parentNodeId}/${runnerId}` `` (`kernel/moleculer/addon-runner.ts:222`) —
+* so every runner label contains a `/` and every hub-local one is `hub/<runner>`.
+* A label with NO slash therefore cannot be produced by that rule, which makes
+* `hub-main` unambiguous by construction rather than by convention: no future
+* addon, group or agent can ever claim it.
+*
+* It also sorts where it belongs. `-` (0x2D) precedes `/` (0x2F), so a sorted
+* `[mem]` census puts `hub-main` immediately before `hub/decoder`,
+* `hub/recorder`, `hub/stream-broker` — the composition root first, then the
+* runners it forked. `hub/main` would sort into the middle of its own children
+* and would be one addon id away from a collision.
+*
+* And it is the name the rest of this repository already uses — the docblocks,
+* {@link HUB_MAIN_RSS_BUDGET_MB}, {@link HUB_RSS_BUDGET_ENV}, every ADR. A log
+* label that disagreed with the prose would be a second vocabulary for one
+* process, which is the exact failure this telemetry exists to remove.
+*/
 export declare const HUB_MAIN_HEAP_WATCH_LABEL = "hub-main";
 /** Heartbeat period. Slow enough to be free, fast enough that the sample before
- *  a fatal is recent. */
-export declare const HEAP_WATCH_INTERVAL_MS = 60000;
+*  a fatal is recent. */
+export declare const HEAP_WATCH_INTERVAL_MS = 6e4;
 /** Warn above this share of the heap ceiling. Chosen so the warning precedes
- *  the fatal by more than one interval under realistic growth. */
-export declare const HEAP_WATCH_WARN_RATIO = 0.8;
+*  the fatal by more than one interval under realistic growth. */
+export declare const HEAP_WATCH_WARN_RATIO = .8;
 /**
- * ## The heartbeat could not see the thing it was built to see
- *
- * 2026-08-08 18:28:32Z, hub-main (pid 8) died on `Reached heap limit`. The last
- * `[mem]` line was 18:27:30.433 reading `heapUsed=1086MB` — 25%, unremarkable —
- * and V8's own trace 62 seconds later read 4083MB with a Mark-Compact that
- * reclaimed 4MB of 4090MB. Between those two facts there is not one sample.
- *
- * At `HEAP_WATCH_INTERVAL_MS` the whole event fits inside a single gap, so
- * `HEAP_WATCH_WARN_RATIO` never had a reading to fire on. The docblock above
- * promises "the line that will exist BEFORE the next fatal instead of after
- * it"; on the only occasion that mattered, it did not exist.
- *
- * Measured the same day over 397 consecutive live samples: p50 1266MB, p95
- * 1995MB, **max 2847MB** — 0.66 of the 4288MB ceiling. So the routine sawtooth
- * never approaches 0.8, and the only path to 0.8 is a burst that outruns the
- * sampler. A threshold reachable only through a blind spot is decoration.
- *
- * The fix is not a faster heartbeat — 30 lines a minute forever, to describe a
- * process that is fine, is how a log stops being read. It is to sample fast
- * only while the heap is somewhere the routine sawtooth does not go.
- */
+* ## The heartbeat could not see the thing it was built to see
+*
+* 2026-08-08 18:28:32Z, hub-main (pid 8) died on `Reached heap limit`. The last
+* `[mem]` line was 18:27:30.433 reading `heapUsed=1086MB` — 25%, unremarkable —
+* and V8's own trace 62 seconds later read 4083MB with a Mark-Compact that
+* reclaimed 4MB of 4090MB. Between those two facts there is not one sample.
+*
+* At `HEAP_WATCH_INTERVAL_MS` the whole event fits inside a single gap, so
+* `HEAP_WATCH_WARN_RATIO` never had a reading to fire on. The docblock above
+* promises "the line that will exist BEFORE the next fatal instead of after
+* it"; on the only occasion that mattered, it did not exist.
+*
+* Measured the same day over 397 consecutive live samples: p50 1266MB, p95
+* 1995MB, **max 2847MB** — 0.66 of the 4288MB ceiling. So the routine sawtooth
+* never approaches 0.8, and the only path to 0.8 is a burst that outruns the
+* sampler. A threshold reachable only through a blind spot is decoration.
+*
+* The fix is not a faster heartbeat — 30 lines a minute forever, to describe a
+* process that is fine, is how a log stops being read. It is to sample fast
+* only while the heap is somewhere the routine sawtooth does not go.
+*/
 /** Sampling period once escalated. Bounded below by log volume, above by the
- *  62s window the 2026-08-08 fatal hid in: ~30 readings across that window is
- *  a trajectory, and a trajectory separates a burst from a climb. */
-export declare const HEAP_WATCH_FAST_INTERVAL_MS = 2000;
+*  62s window the 2026-08-08 fatal hid in: ~30 readings across that window is
+*  a trajectory, and a trajectory separates a burst from a climb. */
+export declare const HEAP_WATCH_FAST_INTERVAL_MS = 2e3;
 /**
- * Escalate above this share of the ceiling.
- *
- * 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
- * never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
- * is already running by the time the warn is reachable.
- */
-export declare const HEAP_WATCH_ESCALATE_RATIO = 0.7;
+* Escalate above this share of the ceiling.
+*
+* 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
+* never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
+* is already running by the time the warn is reachable.
+*/
+export declare const HEAP_WATCH_ESCALATE_RATIO = .7;
 /**
- * Release escalation below this share.
- *
- * Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
- * so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
- * retreat rather than the trough of one collection.
- */
-export declare const HEAP_WATCH_DEESCALATE_RATIO = 0.6;
+* Release escalation below this share.
+*
+* Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
+* so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
+* retreat rather than the trough of one collection.
+*/
+export declare const HEAP_WATCH_DEESCALATE_RATIO = .6;
 /** Sampling cadence. `escalated` costs log lines and buys resolution. */
-export type HeapWatchMode = 'steady' | 'escalated';
+export type HeapWatchMode = "steady" | "escalated";
 /**
- * The cadence state machine, pure so the thresholds are testable without
- * allocating three gigabytes to reach them.
- */
+* The cadence state machine, pure so the thresholds are testable without
+* allocating three gigabytes to reach them.
+*/
 export declare function nextMode(current: HeapWatchMode, usedRatio: number, escalateRatio?: number, deescalateRatio?: number): HeapWatchMode;
 /**
- * Reclaim once the process holds this many MB beyond what it is USING.
- *
- * Live calibration, both readings from the same hub minutes apart: 2491MB
- * stranded before the reclaim, 438MB after. 438MB is this process's irreducible
- * native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
- * collecting against it would buy nothing and cost a stall every minute.
- *
- * ## Why this came down from 1536 (2026-08-17)
- *
- * The trigger was originally set to fire only on an unmistakable strand. It
- * does, and the pass on the record works exactly as designed:
- *
- *     [mem] reclaim hub-main stranded=2365MB rss=4016MB→2368MB freed=1648MB took=654ms
- *
- * But the number it was protecting against changed. The host now runs with a
- * 24GiB cgroup ceiling and **no swap**, and is OOM-killing a neighbouring VM.
- * RSS this process is holding and not using is no longer merely untidy — it is
- * the headroom something else needed, and the OOM is triggered by the PEAK, not
- * by the average. A trigger of 1536 means the peak is allowed to stand 1.5GiB
- * above the floor before anything happens.
- *
- * 1024 is 2.3x the measured 438MB floor, so ordinary movement around the floor
- * can never trip it, and every pass that does fire still returns roughly
- * `1024 - 438` ≈ **580MB minimum** — a real return for a 250-650ms stall,
- * not a stall spent collecting noise.
- */
+* Reclaim once the process holds this many MB beyond what it is USING.
+*
+* Live calibration, both readings from the same hub minutes apart: 2491MB
+* stranded before the reclaim, 438MB after. 438MB is this process's irreducible
+* native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
+* collecting against it would buy nothing and cost a stall every minute.
+*
+* ## Why this came down from 1536 (2026-08-17)
+*
+* The trigger was originally set to fire only on an unmistakable strand. It
+* does, and the pass on the record works exactly as designed:
+*
+*     [mem] reclaim hub-main stranded=2365MB rss=4016MB→2368MB freed=1648MB took=654ms
+*
+* But the number it was protecting against changed. The host now runs with a
+* 24GiB cgroup ceiling and **no swap**, and is OOM-killing a neighbouring VM.
+* RSS this process is holding and not using is no longer merely untidy — it is
+* the headroom something else needed, and the OOM is triggered by the PEAK, not
+* by the average. A trigger of 1536 means the peak is allowed to stand 1.5GiB
+* above the floor before anything happens.
+*
+* 1024 is 2.3x the measured 438MB floor, so ordinary movement around the floor
+* can never trip it, and every pass that does fire still returns roughly
+* `1024 - 438` ≈ **580MB minimum** — a real return for a 250-650ms stall,
+* not a stall spent collecting noise.
+*/
 export declare const HEAP_RECLAIM_TRIGGER_MB = 1024;
 /**
- * Floor on how often the stop-the-world may run.
- *
- * Ten minutes was chosen to keep the worst case under 0.1% of the router's
- * time. The worst case is not what governs the cost, though: the reclaim only
- * runs when {@link shouldReclaim} says the process is genuinely stranded, and
- * after a pass it is at the ~438MB floor. Live off-heap growth was measured at
- * roughly 3GB/2h ≈ 25MB/min, so re-stranding the ~580MB needed to qualify again
- * takes on the order of **20 minutes** — well outside any floor considered
- * here. In steady state this constant therefore costs nothing at all.
- *
- * What it does govern is a BURST, which is the only case that matters on a host
- * with no swap: the ten-minute floor let a peak that re-formed in seconds stand
- * for ten minutes. Two minutes bounds that, and even the pathological case of a
- * process that re-strands instantly costs 654ms per 120s — 0.55% of the
- * router's time, against a ~1.5GiB peak it removes each pass.
- */
-export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 120000;
+* Floor on how often the stop-the-world may run.
+*
+* Ten minutes was chosen to keep the worst case under 0.1% of the router's
+* time. The worst case is not what governs the cost, though: the reclaim only
+* runs when {@link shouldReclaim} says the process is genuinely stranded, and
+* after a pass it is at the ~438MB floor. Live off-heap growth was measured at
+* roughly 3GB/2h ≈ 25MB/min, so re-stranding the ~580MB needed to qualify again
+* takes on the order of **20 minutes** — well outside any floor considered
+* here. In steady state this constant therefore costs nothing at all.
+*
+* What it does govern is a BURST, which is the only case that matters on a host
+* with no swap: the ten-minute floor let a peak that re-formed in seconds stand
+* for ten minutes. Two minutes bounds that, and even the pathological case of a
+* process that re-strands instantly costs 654ms per 120s — 0.55% of the
+* router's time, against a ~1.5GiB peak it removes each pass.
+*/
+export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 12e4;
 /**
- * Consecutive floor-to-floor passes after which the reclaim is announced as
- * STEADY STATE rather than a rescue.
- *
- * The floor above is documented as a bound on a BURST, on the measured premise
- * that re-stranding the trigger takes ~20 minutes. Measured on the live hub
- * 2026-08-25 it takes under two: 13 passes in 30 minutes, every one of them
- * firing the instant {@link HEAP_RECLAIM_MIN_INTERVAL_MS} elapsed, `took=`
- * 556-695ms each. Nothing in the record said so, because a pass that fires
- * every floor period and a pass that fires once an hour print the same line.
- *
- * Six is 12 minutes of back-to-back passes: long enough that a genuine burst
- * (which subsides) never reaches it, short enough that a process which has
- * quietly made the stop-the-world part of its steady state is named within the
- * quarter-hour.
- *
- * ## Until 2026-08-29 this counter changed nothing, and that was the bug
- *
- * It used to WARN and leave the cadence alone — "the pass is load-bearing and
- * keeps running". Then hub-main's first 25 minutes of telemetry arrived and
- * showed what that costs. See {@link HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS}:
- * the system already knew the difference between a rescue and a steady state
- * and simply refused to act on it.
- */
+* Consecutive floor-to-floor passes after which the reclaim is announced as
+* STEADY STATE rather than a rescue.
+*
+* The floor above is documented as a bound on a BURST, on the measured premise
+* that re-stranding the trigger takes ~20 minutes. Measured on the live hub
+* 2026-08-25 it takes under two: 13 passes in 30 minutes, every one of them
+* firing the instant {@link HEAP_RECLAIM_MIN_INTERVAL_MS} elapsed, `took=`
+* 556-695ms each. Nothing in the record said so, because a pass that fires
+* every floor period and a pass that fires once an hour print the same line.
+*
+* Six is 12 minutes of back-to-back passes: long enough that a genuine burst
+* (which subsides) never reaches it, short enough that a process which has
+* quietly made the stop-the-world part of its steady state is named within the
+* quarter-hour.
+*
+* ## Until 2026-08-29 this counter changed nothing, and that was the bug
+*
+* It used to WARN and leave the cadence alone — "the pass is load-bearing and
+* keeps running". Then hub-main's first 25 minutes of telemetry arrived and
+* showed what that costs. See {@link HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS}:
+* the system already knew the difference between a rescue and a steady state
+* and simply refused to act on it.
+*/
 export declare const RECLAIM_STEADY_STATE_PASSES = 6;
 /**
- * Floor on the pass once it has PROVEN it is steady state, not a rescue.
- *
- * ## Why `stranded` cannot discriminate on hub-main
- *
- * {@link strandedMb} is `rss − heapUsed − external`: everything the process
- * holds that those two numbers do not name. That lumps together two things with
- * opposite fixes —
- *
- *  - V8 pages committed at a sawtooth peak, which `gc(last-resort)` RETURNS;
- *  - glibc arena memory already freed and never handed back, which **no V8
- *    flavor can reach** (nothing in this repository calls `malloc_trim`).
- *
- * {@link HEAP_RECLAIM_TRIGGER_MB} was calibrated against a hub-main whose strand
- * was mostly the first kind, and a pass then took it back under the trigger. Once
- * the second kind grows past 1024 MB the quantity can never fall back under it,
- * and the gate degenerates. Measured on the live hub 2026-08-29, first 25
- * minutes of hub-main telemetry ever collected:
- *
- *  - `stranded` sat at **1031–2313 MB for the entire boot**, i.e.
- *    {@link shouldReclaim} never once said no. **What is written as a threshold
- *    is, on this process, an unconditional 120-second timer.**
- *  - Nine minutes out of nine that contained a reclaim show `loopMax` ≈ the
- *    reclaim's own duration (555–869 ms). Every minute without one is
- *    107–435 ms. **The largest recurring event-loop stall on the process that
- *    mediates every cross-runner call is the memory patch it applies to itself.**
- *  - Each pass freed less than the last (1193 → 462 MB) while the post-pass RSS
- *    floor ratcheted **1940 → 3510 MB in fourteen minutes**, with `heapUsed`
- *    never moving. It is compacting a heap that is not the problem.
- *
- * ## The fix is not a bigger trigger
- *
- * Raising {@link HEAP_RECLAIM_TRIGGER_MB} would move the number at which the same
- * degeneration happens, and it would silence `hub/recorder` — whose single pass
- * in six hours is the only cheap proof anyone has that the recorder's 1.4 GB is
- * RETAINED (a forced compaction freed 507 MB and V8 still held 1.44 GB live).
- * The discriminator is not the level of the strand; it is **whether the strand
- * ever falls back under the trigger between passes**, which is precisely what
- * {@link RECLAIM_STEADY_STATE_PASSES} already counts and used only to talk about.
- *
- * So the counter becomes load-bearing: once the pass has fired at the floor
- * {@link RECLAIM_STEADY_STATE_PASSES} times running, the trigger has demonstrably
- * stopped discriminating on this process, and the cadence falls back to a period
- * chosen for its COST rather than to a threshold pretending to be a gate.
- *
- * ## Why 600_000, and why that is not a regression
- *
- * It is the value {@link HEAP_RECLAIM_MIN_INTERVAL_MS} held before 2026-08-17,
- * and the reason it came down is recorded there: *"the ten-minute floor let a
- * peak that re-formed in seconds stand for ten minutes"*. That argument is about
- * a BURST — and a burst subsides, which resets the run and restores the 120 s
- * floor. It never applied to a process in proven steady state. So the burst
- * bound is untouched and the steady state gets the period the burst argument was
- * never about.
- *
- * ## What each process does after this change
- *
- *  - **hub-main**: first six passes at 120 s, unchanged. From the seventh
- *    consecutive floor-to-floor pass, every 600 s. Stop-the-world cost on the
- *    router falls from ~0.58% of wall clock to ~0.12%. The ArrayBuffer probe
- *    survives at six passes an hour — the finding it produced needed ten passes
- *    total, not ten in twenty-five minutes.
- *  - **`hub/recorder`**: zero change, by construction. `passesAtFloor` only
- *    increments when a pass fires within `minIntervalMs * 2` of the previous
- *    one; the recorder's strand takes six hours to re-form, so the counter is
- *    reset to 1 on every pass and can never reach six. The 507 MB probe is
- *    intact.
- *  - **Anything that recovers**: the run resets the moment the strand falls back
- *    under the trigger, and the 120 s floor returns with it.
- */
-export declare const HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS = 600000;
+* Floor on the pass once it has PROVEN it is steady state, not a rescue.
+*
+* ## Why `stranded` cannot discriminate on hub-main
+*
+* {@link strandedMb} is `rss − heapUsed − external`: everything the process
+* holds that those two numbers do not name. That lumps together two things with
+* opposite fixes —
+*
+*  - V8 pages committed at a sawtooth peak, which `gc(last-resort)` RETURNS;
+*  - glibc arena memory already freed and never handed back, which **no V8
+*    flavor can reach** (nothing in this repository calls `malloc_trim`).
+*
+* {@link HEAP_RECLAIM_TRIGGER_MB} was calibrated against a hub-main whose strand
+* was mostly the first kind, and a pass then took it back under the trigger. Once
+* the second kind grows past 1024 MB the quantity can never fall back under it,
+* and the gate degenerates. Measured on the live hub 2026-08-29, first 25
+* minutes of hub-main telemetry ever collected:
+*
+*  - `stranded` sat at **1031–2313 MB for the entire boot**, i.e.
+*    {@link shouldReclaim} never once said no. **What is written as a threshold
+*    is, on this process, an unconditional 120-second timer.**
+*  - Nine minutes out of nine that contained a reclaim show `loopMax` ≈ the
+*    reclaim's own duration (555–869 ms). Every minute without one is
+*    107–435 ms. **The largest recurring event-loop stall on the process that
+*    mediates every cross-runner call is the memory patch it applies to itself.**
+*  - Each pass freed less than the last (1193 → 462 MB) while the post-pass RSS
+*    floor ratcheted **1940 → 3510 MB in fourteen minutes**, with `heapUsed`
+*    never moving. It is compacting a heap that is not the problem.
+*
+* ## The fix is not a bigger trigger
+*
+* Raising {@link HEAP_RECLAIM_TRIGGER_MB} would move the number at which the same
+* degeneration happens, and it would silence `hub/recorder` — whose single pass
+* in six hours is the only cheap proof anyone has that the recorder's 1.4 GB is
+* RETAINED (a forced compaction freed 507 MB and V8 still held 1.44 GB live).
+* The discriminator is not the level of the strand; it is **whether the strand
+* ever falls back under the trigger between passes**, which is precisely what
+* {@link RECLAIM_STEADY_STATE_PASSES} already counts and used only to talk about.
+*
+* So the counter becomes load-bearing: once the pass has fired at the floor
+* {@link RECLAIM_STEADY_STATE_PASSES} times running, the trigger has demonstrably
+* stopped discriminating on this process, and the cadence falls back to a period
+* chosen for its COST rather than to a threshold pretending to be a gate.
+*
+* ## Why 600_000, and why that is not a regression
+*
+* It is the value {@link HEAP_RECLAIM_MIN_INTERVAL_MS} held before 2026-08-17,
+* and the reason it came down is recorded there: *"the ten-minute floor let a
+* peak that re-formed in seconds stand for ten minutes"*. That argument is about
+* a BURST — and a burst subsides, which resets the run and restores the 120 s
+* floor. It never applied to a process in proven steady state. So the burst
+* bound is untouched and the steady state gets the period the burst argument was
+* never about.
+*
+* ## What each process does after this change
+*
+*  - **hub-main**: first six passes at 120 s, unchanged. From the seventh
+*    consecutive floor-to-floor pass, every 600 s. Stop-the-world cost on the
+*    router falls from ~0.58% of wall clock to ~0.12%. The ArrayBuffer probe
+*    survives at six passes an hour — the finding it produced needed ten passes
+*    total, not ten in twenty-five minutes.
+*  - **`hub/recorder`**: zero change, by construction. `passesAtFloor` only
+*    increments when a pass fires within `minIntervalMs * 2` of the previous
+*    one; the recorder's strand takes six hours to re-form, so the counter is
+*    reset to 1 on every pass and can never reach six. The 507 MB probe is
+*    intact.
+*  - **Anything that recovers**: the run resets the moment the strand falls back
+*    under the trigger, and the 120 s floor returns with it.
+*/
+export declare const HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS = 6e5;
 /**
- * The floor in force for the NEXT pass, given how many have fired at the floor.
- *
- * Pure, so the cadence change is testable without stranding a gigabyte to reach
- * it — and so the one place that decides it can be read on its own.
- */
+* The floor in force for the NEXT pass, given how many have fired at the floor.
+*
+* Pure, so the cadence change is testable without stranding a gigabyte to reach
+* it — and so the one place that decides it can be read on its own.
+*/
 export declare function reclaimIntervalMs(passesAtFloor: number, minIntervalMs?: number, steadyStateIntervalMs?: number, steadyStatePasses?: number): number;
 /**
- * Event-loop delay over the window since the previous read, in milliseconds.
- *
- * Why the heartbeat carries this at all: hub-main's event loop is the cluster's
- * only queue (D181 — every settings read from every runner and every agent,
- * every UDS handshake and every cross-runner cap call is served on it, and a
- * live CPU profile of a boot put `(idle)` at 0.1%). The reclaim pass is a
- * stop-the-world ON that loop, and `took=` prices the PASS without ever pricing
- * what it delays. 590ms against a p99 of 4ms is a visible stall; the same 590ms
- * against a p99 of 900ms is noise inside a queue that was already saturated.
- * Those are opposite conclusions, and until now the log could not tell them
- * apart.
- */
+* Event-loop delay over the window since the previous read, in milliseconds.
+*
+* Why the heartbeat carries this at all: hub-main's event loop is the cluster's
+* only queue (D181 — every settings read from every runner and every agent,
+* every UDS handshake and every cross-runner cap call is served on it, and a
+* live CPU profile of a boot put `(idle)` at 0.1%). The reclaim pass is a
+* stop-the-world ON that loop, and `took=` prices the PASS without ever pricing
+* what it delays. 590ms against a p99 of 4ms is a visible stall; the same 590ms
+* against a p99 of 900ms is noise inside a queue that was already saturated.
+* Those are opposite conclusions, and until now the log could not tell them
+* apart.
+*/
 export interface LoopDelaySample {
-    readonly p50Ms: number;
-    readonly p99Ms: number;
-    readonly maxMs: number;
+	readonly p50Ms: number;
+	readonly p99Ms: number;
+	readonly maxMs: number;
 }
 /** What a loop with nothing recorded yet reports. */
 export declare const ZERO_LOOP_DELAY: LoopDelaySample;
 export interface LoopDelayMeter {
-    /** Percentiles over the window since the previous read. Reading RESETS it. */
-    readonly read: () => LoopDelaySample;
-    readonly stop: () => void;
+	/** Percentiles over the window since the previous read. Reading RESETS it. */
+	readonly read: () => LoopDelaySample;
+	readonly stop: () => void;
 }
 /**
- * A `perf_hooks` interval histogram, read once per LOGGED line.
- *
- * The histogram samples in libuv at `resolutionMs` and costs nothing to keep
- * enabled; the expensive part would be reading it on every 2s probe, which
- * would also destroy the window the line claims to describe (probe and log
- * cadences are deliberately different — see {@link startHeapWatch}).
- *
- * An EMPTY histogram is the trap: Node answers `min = 9223372036854776000` and
- * `percentile()` throws on some versions, so a first heartbeat that read it
- * naively would print `loopMax=9223372036854ms` and be read as a catastrophe on
- * every boot. `count === 0` short-circuits to {@link ZERO_LOOP_DELAY}.
- *
- * ## `loopP50=20ms` was the SAMPLER, not the loop (fixed 2026-08-29)
- *
- * `monitorEventLoopDelay` records the whole INTERVAL between its own timer
- * firings, not the excess over the interval it asked for. So on a loop with
- * nothing wrong the histogram reads `resolution`, and every `[mem]` line this
- * process has ever emitted said `loopP50=20ms` — which was read, repeatedly in
- * one session, as "hub-main is chronically 20 ms behind". It is not; 20 was the
- * default `resolutionMs` of this very function.
- *
- * The delay is `interval − resolution`, and that is not a fudge factor — it is
- * the only reading the four resolutions agree on. Measured here, one 120 ms
- * block observed by four histograms at once:
- *
- * | resolution | raw p50 | raw max | max − resolution |
- * | --- | --- | --- | --- |
- * | 20 ms | 20.40 ms | 137.63 ms | 117.6 ms |
- * | 10 ms | 10.22 ms | 123.60 ms | 113.6 ms |
- * | 5 ms | 5.11 ms | 123.60 ms | 118.6 ms |
- * | 1 ms | 1.27 ms | 121.04 ms | 120.0 ms |
- *
- * Raw, the four disagree by 16 ms about the same event and none of them reports
- * the block. Corrected, they agree within 7 ms and all four name it. The
- * subtraction costs nothing and needs no faster sampler — a 1 ms resolution
- * would be 1 000 extra timer wakeups per second on the process that already
- * serves ~44 000 socket operations per second, to buy 2 ms of accuracy on a
- * quantity nobody reads below 100 ms.
- *
- * **Readings from before this change are 20 ms high.** `loopP99=21–28ms` in the
- * 2026-08-29 census is really 1–8 ms; `loopMax=2804ms` is really 2784 ms. Do not
- * compare a pre-fix series with a post-fix one without shifting it.
- *
- * Returns undefined if the platform declines, so the caller keeps a heartbeat
- * either way.
- */
+* A `perf_hooks` interval histogram, read once per LOGGED line.
+*
+* The histogram samples in libuv at `resolutionMs` and costs nothing to keep
+* enabled; the expensive part would be reading it on every 2s probe, which
+* would also destroy the window the line claims to describe (probe and log
+* cadences are deliberately different — see {@link startHeapWatch}).
+*
+* An EMPTY histogram is the trap: Node answers `min = 9223372036854776000` and
+* `percentile()` throws on some versions, so a first heartbeat that read it
+* naively would print `loopMax=9223372036854ms` and be read as a catastrophe on
+* every boot. `count === 0` short-circuits to {@link ZERO_LOOP_DELAY}.
+*
+* ## `loopP50=20ms` was the SAMPLER, not the loop (fixed 2026-08-29)
+*
+* `monitorEventLoopDelay` records the whole INTERVAL between its own timer
+* firings, not the excess over the interval it asked for. So on a loop with
+* nothing wrong the histogram reads `resolution`, and every `[mem]` line this
+* process has ever emitted said `loopP50=20ms` — which was read, repeatedly in
+* one session, as "hub-main is chronically 20 ms behind". It is not; 20 was the
+* default `resolutionMs` of this very function.
+*
+* The delay is `interval − resolution`, and that is not a fudge factor — it is
+* the only reading the four resolutions agree on. Measured here, one 120 ms
+* block observed by four histograms at once:
+*
+* | resolution | raw p50 | raw max | max − resolution |
+* | --- | --- | --- | --- |
+* | 20 ms | 20.40 ms | 137.63 ms | 117.6 ms |
+* | 10 ms | 10.22 ms | 123.60 ms | 113.6 ms |
+* | 5 ms | 5.11 ms | 123.60 ms | 118.6 ms |
+* | 1 ms | 1.27 ms | 121.04 ms | 120.0 ms |
+*
+* Raw, the four disagree by 16 ms about the same event and none of them reports
+* the block. Corrected, they agree within 7 ms and all four name it. The
+* subtraction costs nothing and needs no faster sampler — a 1 ms resolution
+* would be 1 000 extra timer wakeups per second on the process that already
+* serves ~44 000 socket operations per second, to buy 2 ms of accuracy on a
+* quantity nobody reads below 100 ms.
+*
+* **Readings from before this change are 20 ms high.** `loopP99=21–28ms` in the
+* 2026-08-29 census is really 1–8 ms; `loopMax=2804ms` is really 2784 ms. Do not
+* compare a pre-fix series with a post-fix one without shifting it.
+*
+* Returns undefined if the platform declines, so the caller keeps a heartbeat
+* either way.
+*/
 export declare function createLoopDelayMeter(resolutionMs?: number): LoopDelayMeter | undefined;
 /** Whether anyone CHOSE this process's old-space ceiling, or V8 derived one. */
-export type HeapCeilingOrigin = 'explicit' | 'v8-default';
+export type HeapCeilingOrigin = "explicit" | "v8-default";
 /**
- * Read the origin of the old-space ceiling off node's own options.
- *
- * hub-main is the only process in the cluster whose ceiling nobody chose. Every
- * forked runner is given V8 heap flags by `process-service.ts`; hub-main gets
- * `--max-old-space-size` from `docker-entrypoint.sh` ONLY when the operator sets
- * `CAMSTACK_HUB_HEAP_MB`, and on the live container it is unset — verified
- * 2026-08-25 by reading pid 7's argv, a bare `node .../starter.js`. So the
- * ceiling in force is whatever V8 derives from the host (4288MB there), and the
- * only record of that was a comment inside an image nobody rebuilds to read.
- *
- * A fact about the running process belongs in the running process's log, and
- * `execArgv` answers it for free at boot.
- */
+* Read the origin of the old-space ceiling off node's own options.
+*
+* hub-main is the only process in the cluster whose ceiling nobody chose. Every
+* forked runner is given V8 heap flags by `process-service.ts`; hub-main gets
+* `--max-old-space-size` from `docker-entrypoint.sh` ONLY when the operator sets
+* `CAMSTACK_HUB_HEAP_MB`, and on the live container it is unset — verified
+* 2026-08-25 by reading pid 7's argv, a bare `node .../starter.js`. So the
+* ceiling in force is whatever V8 derives from the host (4288MB there), and the
+* only record of that was a comment inside an image nobody rebuilds to read.
+*
+* A fact about the running process belongs in the running process's log, and
+* `execArgv` answers it for free at boot.
+*/
 export declare function heapCeilingOrigin(execArgv?: readonly string[]): HeapCeilingOrigin;
 export interface HeapSample {
-    readonly rssMb: number;
-    readonly heapUsedMb: number;
-    readonly heapTotalMb: number;
-    readonly heapLimitMb: number;
-    readonly externalMb: number;
-    readonly arrayBuffersMb: number;
-    /** heapUsed / heapLimit, 0-1. */
-    readonly usedRatio: number;
-    /** True once the heap is close enough to the ceiling to be worth shouting. */
-    readonly nearLimit: boolean;
+	readonly rssMb: number;
+	readonly heapUsedMb: number;
+	readonly heapTotalMb: number;
+	readonly heapLimitMb: number;
+	readonly externalMb: number;
+	readonly arrayBuffersMb: number;
+	/** heapUsed / heapLimit, 0-1. */
+	readonly usedRatio: number;
+	/** True once the heap is close enough to the ceiling to be worth shouting. */
+	readonly nearLimit: boolean;
 }
 /**
- * Build a sample from raw readings. Pure so the thresholds are testable without
- * allocating a gigabyte to reach them.
- */
+* Build a sample from raw readings. Pure so the thresholds are testable without
+* allocating a gigabyte to reach them.
+*/
 export declare function buildHeapSample(mem: NodeJS.MemoryUsage, heapLimitBytes: number, warnRatio?: number): HeapSample;
 /** Minimal sink so this module stays usable before any logger exists — the
- *  starter runs before the kernel's logging is wired. */
+*  starter runs before the kernel's logging is wired. */
 export interface HeapWatchSink {
-    readonly info: (line: string) => void;
-    readonly warn: (line: string) => void;
+	readonly info: (line: string) => void;
+	readonly warn: (line: string) => void;
 }
 /**
- * A sink that starts on stdout and is repointed at the real logger the moment
- * one exists.
- *
- * ## The gap this closes
- *
- * hub-main has had this heartbeat since 2026-08-02, started from
- * `server/backend/src/main.ts` as the very first statement of `bootstrap()`.
- * It was never wired to the LOG MANAGER, only to {@link consoleSink} — i.e. to
- * `console.log`, which is not a destination. Every forked runner passes a sink
- * backed by its `IScopedLogger` (`kernel/moleculer/addon-runner.ts:729`), so a
- * runner's `[mem]` line fans out to the buffer, the console destination, the
- * rotated file AND the Loki destination; hub-main's went to a file descriptor
- * and nowhere else. Result: 42 hours of Loki with a `[mem]` line for every
- * runner in the cluster and not one for the largest process in it, whose growth
- * to ~4.8 GB was consequently never trended, only inferred.
- *
- * ## Why late binding rather than moving the call
- *
- * The heartbeat cannot simply be started later. Its whole point is that a
- * process which dies early still leaves samples — the fatal that motivated it
- * landed nine seconds after a viewer connected — and `LoggingService` does not
- * exist until the Fastify app has been booted, hundreds of lines into
- * `bootstrap()`. So the sink is handed over instead of the start being delayed:
- * boot lines keep going to stdout exactly as they do today, and every line from
- * the handover on enters the log manager.
- *
- * Nothing before the handover is lost from Loki by accident, only by design:
- * `LogManager.addDestination` replays its ring buffer into a destination that
- * registers late, so the heartbeat lines emitted between the handover and the
- * Loki addon's own registration still ship.
- */
+* A sink that starts on stdout and is repointed at the real logger the moment
+* one exists.
+*
+* ## The gap this closes
+*
+* hub-main has had this heartbeat since 2026-08-02, started from
+* `server/backend/src/main.ts` as the very first statement of `bootstrap()`.
+* It was never wired to the LOG MANAGER, only to {@link consoleSink} — i.e. to
+* `console.log`, which is not a destination. Every forked runner passes a sink
+* backed by its `IScopedLogger` (`kernel/moleculer/addon-runner.ts:729`), so a
+* runner's `[mem]` line fans out to the buffer, the console destination, the
+* rotated file AND the Loki destination; hub-main's went to a file descriptor
+* and nowhere else. Result: 42 hours of Loki with a `[mem]` line for every
+* runner in the cluster and not one for the largest process in it, whose growth
+* to ~4.8 GB was consequently never trended, only inferred.
+*
+* ## Why late binding rather than moving the call
+*
+* The heartbeat cannot simply be started later. Its whole point is that a
+* process which dies early still leaves samples — the fatal that motivated it
+* landed nine seconds after a viewer connected — and `LoggingService` does not
+* exist until the Fastify app has been booted, hundreds of lines into
+* `bootstrap()`. So the sink is handed over instead of the start being delayed:
+* boot lines keep going to stdout exactly as they do today, and every line from
+* the handover on enters the log manager.
+*
+* Nothing before the handover is lost from Loki by accident, only by design:
+* `LogManager.addDestination` replays its ring buffer into a destination that
+* registers late, so the heartbeat lines emitted between the handover and the
+* Loki addon's own registration still ship.
+*/
 export interface DeferredHeapWatchSink {
-    /** Hand this to {@link startHeapWatch}. */
-    readonly sink: HeapWatchSink;
-    /** Point every SUBSEQUENT line at `target`. Last call wins. */
-    readonly attach: (target: HeapWatchSink) => void;
+	/** Hand this to {@link startHeapWatch}. */
+	readonly sink: HeapWatchSink;
+	/** Point every SUBSEQUENT line at `target`. Last call wins. */
+	readonly attach: (target: HeapWatchSink) => void;
 }
 /**
- * Build a {@link DeferredHeapWatchSink}.
- *
- * The handover announces itself, once, through the NEW target: that line is the
- * only in-band evidence that hub-main's telemetry actually reached the log
- * manager on a given boot. Its absence from Loki means the wiring is broken —
- * which is precisely the state this module was in, undetected, for 42 hours.
- */
+* Build a {@link DeferredHeapWatchSink}.
+*
+* The handover announces itself, once, through the NEW target: that line is the
+* only in-band evidence that hub-main's telemetry actually reached the log
+* manager on a given boot. Its absence from Loki means the wiring is broken —
+* which is precisely the state this module was in, undetected, for 42 hours.
+*/
 export declare function createDeferredHeapWatchSink(label?: string, fallback?: HeapWatchSink): DeferredHeapWatchSink;
 /**
- * RSS the process is holding but not using.
- *
- * The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
- * committed at a sawtooth peak and no longer needs are counted inside heapTotal,
- * and they are precisely what this number exists to see.
- *
- * ## What this number can and CANNOT be asked
- *
- * It answers exactly one question: *are there pages a `last-resort` GC could
- * hand back?* For that it is correct, and {@link shouldReclaim} is the only
- * gate that should ever be built on it.
- *
- * It can never answer *is this process too big?*, because `external` is
- * subtracted by construction. A process whose growth is entirely `external` —
- * Buffers, `arrayBuffers`, what a native addon mallocs — moves `rss` and the
- * subtrahend by the same amount, so this number is **algebraically constant
- * while the process triples**. That is not a threshold set too high; the
- * quantity cannot represent the event.
- *
- * It cost 11.4GB and a ~154 second stall of the whole container to establish
- * that. See {@link RssBudgetOptions} for the number that does answer it.
- */
+* RSS the process is holding but not using.
+*
+* The subtrahend is heapUSED, not heapTotal, deliberately: the pages V8
+* committed at a sawtooth peak and no longer needs are counted inside heapTotal,
+* and they are precisely what this number exists to see.
+*
+* ## What this number can and CANNOT be asked
+*
+* It answers exactly one question: *are there pages a `last-resort` GC could
+* hand back?* For that it is correct, and {@link shouldReclaim} is the only
+* gate that should ever be built on it.
+*
+* It can never answer *is this process too big?*, because `external` is
+* subtracted by construction. A process whose growth is entirely `external` —
+* Buffers, `arrayBuffers`, what a native addon mallocs — moves `rss` and the
+* subtrahend by the same amount, so this number is **algebraically constant
+* while the process triples**. That is not a threshold set too high; the
+* quantity cannot represent the event.
+*
+* It cost 11.4GB and a ~154 second stall of the whole container to establish
+* that. See {@link RssBudgetOptions} for the number that does answer it.
+*/
 export declare function strandedMb(s: HeapSample): number;
 /** Whether it is worth paying a stop-the-world to get those pages back. */
 export declare function shouldReclaim(s: HeapSample, triggerMb?: number): boolean;
 /**
- * Which of the three MEASURED growth shapes dominates a process's footprint.
- *
- * These are not categories invented for a log line. They are what `smaps` found
- * on the three live processes on 2026-08-27, and each one has a different lever:
- *
- * | process | evidence | shape |
- * | --- | --- | --- |
- * | `hub/recorder` | 1509.8MB in V8's 256KB page ranges, 53.9MB `brk`, `external` 8MB | `v8-heap` |
- * | `hub/stream-broker` | 242.6MB V8 pages but **1159.1MB `brk`**, `arrayBuffers` 829MB | `external` |
- * | `hub-main` | 1295.1MB V8 pages, 566.7MB `brk`, **2.7GB across 13 anonymous mappings >=64MB** | `native-residue` |
- *
- *  - `v8-heap` — live JS retainers. `--max-old-space-size` is the bound, and the
- *    fix is the retained set (the recorder's ~7.1M `SegmentRow`s).
- *  - `external` — Buffers and native `external`. **No V8 flag bounds any of
- *    it**; `hub/pipeline-analytics` reached 5735MB with `--max-old-space-size=1024`
- *    in force the whole time.
- *  - `native-residue` — memory already freed that the allocator has not returned
- *    to the kernel. This is what the reclaim pass exists for, and the only shape
- *    where `MALLOC_ARENA_MAX` / `VIPS_CONCURRENCY` are the lever — both of which
- *    are ALREADY applied here, so a `native-residue` line means that lever is
- *    spent and the answer is upstream.
- *
- * Reporting only "it is big" leaves the operator to guess between three
- * different fixes, two of which cannot work.
- */
-export type RssGrowthShape = 'v8-heap' | 'external' | 'native-residue';
+* Which of the three MEASURED growth shapes dominates a process's footprint.
+*
+* These are not categories invented for a log line. They are what `smaps` found
+* on the three live processes on 2026-08-27, and each one has a different lever:
+*
+* | process | evidence | shape |
+* | --- | --- | --- |
+* | `hub/recorder` | 1509.8MB in V8's 256KB page ranges, 53.9MB `brk`, `external` 8MB | `v8-heap` |
+* | `hub/stream-broker` | 242.6MB V8 pages but **1159.1MB `brk`**, `arrayBuffers` 829MB | `external` |
+* | `hub-main` | 1295.1MB V8 pages, 566.7MB `brk`, **2.7GB across 13 anonymous mappings >=64MB** | `native-residue` |
+*
+*  - `v8-heap` — live JS retainers. `--max-old-space-size` is the bound, and the
+*    fix is the retained set (the recorder's ~7.1M `SegmentRow`s).
+*  - `external` — Buffers and native `external`. **No V8 flag bounds any of
+*    it**; `hub/pipeline-analytics` reached 5735MB with `--max-old-space-size=1024`
+*    in force the whole time.
+*  - `native-residue` — memory already freed that the allocator has not returned
+*    to the kernel. This is what the reclaim pass exists for, and the only shape
+*    where `MALLOC_ARENA_MAX` / `VIPS_CONCURRENCY` are the lever — both of which
+*    are ALREADY applied here, so a `native-residue` line means that lever is
+*    spent and the answer is upstream.
+*
+* Reporting only "it is big" leaves the operator to guess between three
+* different fixes, two of which cannot work.
+*/
+export type RssGrowthShape = "v8-heap" | "external" | "native-residue";
 /** Where a process's footprint stands against the budget its role declared. */
-export type RssBudgetState = 'within' | 'over';
+export type RssBudgetState = "within" | "over";
 /** The footprint, split into the three parts that imply different fixes. */
 export interface RssBreakdown {
-    readonly rssMb: number;
-    readonly budgetMb: number;
-    /** How far past the budget. 0 when within — "how far over" has no meaning below it. */
-    readonly overMb: number;
-    readonly heapUsedMb: number;
-    readonly externalMb: number;
-    /** `rss − heapUsed − external`: native the other two numbers do not name. */
-    readonly nativeResidueMb: number;
-    readonly arrayBuffersMb: number;
-    readonly shape: RssGrowthShape;
+	readonly rssMb: number;
+	readonly budgetMb: number;
+	/** How far past the budget. 0 when within — "how far over" has no meaning below it. */
+	readonly overMb: number;
+	readonly heapUsedMb: number;
+	readonly externalMb: number;
+	/** `rss − heapUsed − external`: native the other two numbers do not name. */
+	readonly nativeResidueMb: number;
+	readonly arrayBuffersMb: number;
+	readonly shape: RssGrowthShape;
 }
 /**
- * Split a sample into the three shapes and name the dominant one.
- *
- * `nativeResidue` is clamped at 0: `process.memoryUsage()` reads its fields at
- * slightly different instants, so `heapUsed + external` can transiently exceed
- * `rss` and a negative residue would misclassify the sample.
- */
+* Split a sample into the three shapes and name the dominant one.
+*
+* `nativeResidue` is clamped at 0: `process.memoryUsage()` reads its fields at
+* slightly different instants, so `heapUsed + external` can transiently exceed
+* `rss` and a negative residue would misclassify the sample.
+*/
 export declare function describeRss(s: HeapSample, budgetMb: number): RssBreakdown;
 /**
- * Release the alarm below this share of the budget.
- *
- * Hysteresis, not a second budget: every process here sawtooths (the reclaim
- * pass alone moves hub-main by ~1.6GB), so a single threshold would print a
- * pair of lines on every cycle. 0.9 of the budget is a real retreat.
- */
-export declare const RSS_BUDGET_RELEASE_RATIO = 0.9;
+* Release the alarm below this share of the budget.
+*
+* Hysteresis, not a second budget: every process here sawtooths (the reclaim
+* pass alone moves hub-main by ~1.6GB), so a single threshold would print a
+* pair of lines on every cycle. 0.9 of the budget is a real retreat.
+*/
+export declare const RSS_BUDGET_RELEASE_RATIO = .9;
 /**
- * Floor on how often a crossing may be ANNOUNCED again.
- *
- * Hysteresis alone bounds flapping around the edge; it does not bound a process
- * that genuinely swings across the budget every reclaim cycle
- * ({@link HEAP_RECLAIM_MIN_INTERVAL_MS} is 2 minutes, so that is up to 30 pairs
- * of lines an hour, forever). A process that oscillates across its budget is ONE
- * story, and the operator needs it told once per quarter-hour, not thirty times.
- *
- * This is the discipline the rest of this module already follows and the one the
- * log needed: on 2026-08-27 two real alarms were buried under 83,198 Hikvision
- * heartbeat lines in 12h. A watchdog that shouts is a watchdog that gets muted.
- */
-export declare const RSS_BUDGET_REANNOUNCE_MIN_MS = 900000;
+* Floor on how often a crossing may be ANNOUNCED again.
+*
+* Hysteresis alone bounds flapping around the edge; it does not bound a process
+* that genuinely swings across the budget every reclaim cycle
+* ({@link HEAP_RECLAIM_MIN_INTERVAL_MS} is 2 minutes, so that is up to 30 pairs
+* of lines an hour, forever). A process that oscillates across its budget is ONE
+* story, and the operator needs it told once per quarter-hour, not thirty times.
+*
+* This is the discipline the rest of this module already follows and the one the
+* log needed: on 2026-08-27 two real alarms were buried under 83,198 Hikvision
+* heartbeat lines in 12h. A watchdog that shouts is a watchdog that gets muted.
+*/
+export declare const RSS_BUDGET_REANNOUNCE_MIN_MS = 9e5;
 /**
- * The alarm state machine, pure so the thresholds are testable without
- * allocating five gigabytes to reach them.
- */
+* The alarm state machine, pure so the thresholds are testable without
+* allocating five gigabytes to reach them.
+*/
 export declare function nextRssBudgetState(current: RssBudgetState, rssMb: number, budgetMb: number, releaseRatio?: number): RssBudgetState;
 /** A full collection that also asks V8 to hand the pages back to the OS. */
 export type HeapReclaimer = () => void;
 /**
- * Build the reclaimer without requiring `--expose-gc` on argv.
- *
- * The flag is turned on, the function captured, and the flag turned straight
- * back off — a global `gc` left reachable by application code is a footgun, and
- * requiring an argv change would mean this cannot ship without a new image.
- * Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
- *
- * Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
- */
+* Build the reclaimer without requiring `--expose-gc` on argv.
+*
+* The flag is turned on, the function captured, and the flag turned straight
+* back off — a global `gc` left reachable by application code is a footgun, and
+* requiring an argv change would mean this cannot ship without a new image.
+* Verified against the live hub before being written: 266ms, RSS 1453 -> 1237.
+*
+* Returns undefined if V8 declines, so the caller keeps a heartbeat either way.
+*/
 export declare function createV8Reclaimer(): HeapReclaimer | undefined;
 /** Wiring for the reclaim pass. `readMemory`/`heapLimitBytes` exist so a test
- *  can reach a gigabyte-scale state without allocating one. */
+*  can reach a gigabyte-scale state without allocating one. */
 export interface HeapReclaimOptions {
-    readonly reclaim: HeapReclaimer;
-    readonly readMemory?: () => NodeJS.MemoryUsage;
-    readonly heapLimitBytes?: number;
-    readonly triggerMb?: number;
-    readonly minIntervalMs?: number;
-    /** Floor once the pass is proven steady state. See
-     *  {@link HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS}. */
-    readonly steadyStateIntervalMs?: number;
-    readonly now?: () => number;
-    /** Sampling cadence once escalated. See {@link HEAP_WATCH_FAST_INTERVAL_MS}. */
-    readonly fastIntervalMs?: number;
-    /** Ratio at which the fast cadence begins. See {@link HEAP_WATCH_ESCALATE_RATIO}. */
-    readonly escalateRatio?: number;
-    /** Ratio at which it releases. See {@link HEAP_WATCH_DEESCALATE_RATIO}. */
-    readonly deescalateRatio?: number;
+	readonly reclaim: HeapReclaimer;
+	readonly readMemory?: () => NodeJS.MemoryUsage;
+	readonly heapLimitBytes?: number;
+	readonly triggerMb?: number;
+	readonly minIntervalMs?: number;
+	/** Floor once the pass is proven steady state. See
+	*  {@link HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS}. */
+	readonly steadyStateIntervalMs?: number;
+	readonly now?: () => number;
+	/** Sampling cadence once escalated. See {@link HEAP_WATCH_FAST_INTERVAL_MS}. */
+	readonly fastIntervalMs?: number;
+	/** Ratio at which the fast cadence begins. See {@link HEAP_WATCH_ESCALATE_RATIO}. */
+	readonly escalateRatio?: number;
+	/** Ratio at which it releases. See {@link HEAP_WATCH_DEESCALATE_RATIO}. */
+	readonly deescalateRatio?: number;
 }
 /**
- * The RSS budget for ONE process, and where the number came from.
- *
- * ## Why a DECLARED budget, and not a derived one
- *
- * Every bound this system had was derived, and each one is blind to most of a
- * process: `--max-old-space-size` bounds old space only, and `strandedMb`
- * subtracts `external` by construction. `hub/pipeline-analytics` was killed at
- * 11.4GB with a 1024MB old-space ceiling in force and a stranded number that
- * never moved. RSS is the quantity the host's OOM killer actually reads, so RSS
- * is the quantity that needs a ceiling — and RSS cannot be derived from any flag,
- * because most of it is not V8's.
- *
- * ## Why there is no single constant
- *
- * The legitimate footprint differs by an order of magnitude BY ROLE, measured
- * on the same host on the same day:
- *
- *  - `hub/recorder` legitimately holds ~1.5GB of live V8 index (~7.1M
- *    `SegmentRow`s, ~30 days x 13 cameras x 2 profiles) and declares a 3072MB
- *    old space to hold it;
- *  - `hub/stream-broker` legitimately holds ~900MB of `arrayBuffers` (47 RTP
- *    pre-roll rings) in the glibc heap, with an old space of only 224MB;
- *  - `hub/pipeline-analytics` has no legitimate multi-GB working set at all —
- *    it died at 11.4GB holding a 536MB heap.
- *
- * One constant would either wave through analytics' 11GB or scream at the
- * recorder's entirely correct 2GB. So the number lives **next to the role that
- * knows it**: an addon declares `execution.rssBudgetMb` in its own manifest,
- * exactly as it already declares `execution.maxOldSpaceMb`, and the runner takes
- * the MAXIMUM any co-located addon declares (D2/D29 — a runner is respawned as a
- * whole, so co-location must never silence the hungriest member).
- *
- * hub-main has no manifest, and its entrypoint is the LEAST deployable surface
- * in this system (the Dockerfile's own comment: a backend change is train-bound
- * by construction, and an image build does not ship it). Its budget therefore
- * lives in `@camstack/server`, which `applyServerUpdate` replaces the same day —
- * see {@link HUB_MAIN_RSS_BUDGET_MB}.
- *
- * ## And a process with no declaration is UNWATCHED, out loud
- *
- * `budgetMb: undefined` does not select a default. Defaulting would be the same
- * mistake in a new place: a number nobody measured, applied to a process nobody
- * profiled, producing either silence or noise with equal authority. The process
- * says once, at boot, that nothing is watching it. Most runners are in this
- * state today and that is the honest report — measurements exist for four
- * processes, so four processes carry a budget.
- */
+* The RSS budget for ONE process, and where the number came from.
+*
+* ## Why a DECLARED budget, and not a derived one
+*
+* Every bound this system had was derived, and each one is blind to most of a
+* process: `--max-old-space-size` bounds old space only, and `strandedMb`
+* subtracts `external` by construction. `hub/pipeline-analytics` was killed at
+* 11.4GB with a 1024MB old-space ceiling in force and a stranded number that
+* never moved. RSS is the quantity the host's OOM killer actually reads, so RSS
+* is the quantity that needs a ceiling — and RSS cannot be derived from any flag,
+* because most of it is not V8's.
+*
+* ## Why there is no single constant
+*
+* The legitimate footprint differs by an order of magnitude BY ROLE, measured
+* on the same host on the same day:
+*
+*  - `hub/recorder` legitimately holds ~1.5GB of live V8 index (~7.1M
+*    `SegmentRow`s, ~30 days x 13 cameras x 2 profiles) and declares a 3072MB
+*    old space to hold it;
+*  - `hub/stream-broker` legitimately holds ~900MB of `arrayBuffers` (47 RTP
+*    pre-roll rings) in the glibc heap, with an old space of only 224MB;
+*  - `hub/pipeline-analytics` has no legitimate multi-GB working set at all —
+*    it died at 11.4GB holding a 536MB heap.
+*
+* One constant would either wave through analytics' 11GB or scream at the
+* recorder's entirely correct 2GB. So the number lives **next to the role that
+* knows it**: an addon declares `execution.rssBudgetMb` in its own manifest,
+* exactly as it already declares `execution.maxOldSpaceMb`, and the runner takes
+* the MAXIMUM any co-located addon declares (D2/D29 — a runner is respawned as a
+* whole, so co-location must never silence the hungriest member).
+*
+* hub-main has no manifest, and its entrypoint is the LEAST deployable surface
+* in this system (the Dockerfile's own comment: a backend change is train-bound
+* by construction, and an image build does not ship it). Its budget therefore
+* lives in `@camstack/server`, which `applyServerUpdate` replaces the same day —
+* see {@link HUB_MAIN_RSS_BUDGET_MB}.
+*
+* ## And a process with no declaration is UNWATCHED, out loud
+*
+* `budgetMb: undefined` does not select a default. Defaulting would be the same
+* mistake in a new place: a number nobody measured, applied to a process nobody
+* profiled, producing either silence or noise with equal authority. The process
+* says once, at boot, that nothing is watching it. Most runners are in this
+* state today and that is the honest report — measurements exist for four
+* processes, so four processes carry a budget.
+*/
 export interface RssBudgetOptions {
-    /** MB. `undefined` → this process is declared UNWATCHED and says so at boot. */
-    readonly budgetMb: number | undefined;
-    /** Named in every line, so a budget that is wrong is traceable to its author. */
-    readonly source: string;
-    /** See {@link RSS_BUDGET_RELEASE_RATIO}. */
-    readonly releaseRatio?: number;
-    /** See {@link RSS_BUDGET_REANNOUNCE_MIN_MS}. */
-    readonly reannounceMinMs?: number;
+	/** MB. `undefined` → this process is declared UNWATCHED and says so at boot. */
+	readonly budgetMb: number | undefined;
+	/** Named in every line, so a budget that is wrong is traceable to its author. */
+	readonly source: string;
+	/** See {@link RSS_BUDGET_RELEASE_RATIO}. */
+	readonly releaseRatio?: number;
+	/** See {@link RSS_BUDGET_REANNOUNCE_MIN_MS}. */
+	readonly reannounceMinMs?: number;
 }
 /**
- * The optional per-line probes.
- *
- * An OBJECT rather than two more positional parameters: `startHeapWatch` already
- * takes eight, and a ninth and tenth `undefined` at a call site is how a caller
- * ends up passing the loop meter into the space reader. Every field is optional,
- * so a caller that wants neither passes nothing.
- */
+* The optional per-line probes.
+*
+* An OBJECT rather than two more positional parameters: `startHeapWatch` already
+* takes eight, and a ninth and tenth `undefined` at a call site is how a caller
+* ends up passing the loop meter into the space reader. Every field is optional,
+* so a caller that wants neither passes nothing.
+*/
 export interface HeapWatchProbes {
-    /** Per-V8-space breakdown. Defaults to the real reader. */
-    readonly readSpaces?: HeapSpaceReader;
-    /**
-     * UDS + cross-node event fan-out. No default: a forked runner has no child
-     * registry, and printing zeros for a plane that does not exist is worse than
-     * printing nothing. Only hub-main and an agent's main pass one.
-     */
-    readonly eventPlane?: EventPlaneReader;
-    /**
-     * Per-peer UDS socket traffic, split by frame kind. No default, for the same
-     * reason as {@link eventPlane}: a forked runner has no child registry, and the
-     * plane it does have (its single channel to its parent) is already reported
-     * from the parent's side. Only hub-main and an agent's main pass one.
-     */
-    readonly socketPlane?: SocketPlaneReader;
-    /**
-     * The write queue of every Moleculer TCP socket to a peer node. No default:
-     * only a process with a broker on a real transporter has one. Those sockets
-     * are UNREF'D by Moleculer, so a sum over `_getActiveHandles()` never listed
-     * them — the hole in the 2026-09-10 exclusion of "every socket queue"
-     * (D446). Read on every probe, judged with the UDS queues below.
-     */
-    readonly meshQueue?: MeshQueueReader;
-    /**
-     * Thresholds for the outbound-queue gate. The gate itself is created
-     * whenever {@link socketPlane} or {@link meshQueue} is given; this only
-     * tunes it (tests, or a process with a different notion of "held").
-     */
-    readonly outboundQueue?: OutboundQueueGateOptions;
-    /**
-     * The ArrayBuffer census that ARMS ITSELF. No default: it costs a forced
-     * full GC when it fires, and only hub-main has an episode on record (two
-     * silent linear climbs to 1.3 GB and 5 GB on 2026-09-10, each released in
-     * one instant with no line, the second two hours before the OOM). A runner
-     * that legitimately holds gigabytes of ArrayBuffers (`hub/stream-broker`,
-     * ~900 MB of RTP pre-roll rings) would fire it forever. See
-     * `array-buffer-census.ts` for the gate, the cost and what it is NOT.
-     */
-    readonly arrayBufferCensus?: ArrayBufferCensusProbe;
-    /**
-     * How the GC census observes collections. Defaults to the real Node
-     * observer, for EVERY process — the rate is half of what a GC costs and the
-     * line has never carried it (see `gc-census.ts`). A spec passes its own so a
-     * sequence of collections can be posed; nothing in production passes one.
-     */
-    readonly gcObserver?: NodeGcObserver;
-    /**
-     * How this process reads its own CPU. Defaults to the real
-     * `process.cpuUsage()` and the real `/proc/self/task`, for EVERY process —
-     * `docker stats` reports the cgroup, and nothing on any line said what share
-     * of it this process was (see `process-cpu-census.ts`). A spec passes its own
-     * so a cost can be posed; nothing in production passes one.
-     */
-    readonly processCpu?: ProcessCpuProbe;
+	/** Per-V8-space breakdown. Defaults to the real reader. */
+	readonly readSpaces?: HeapSpaceReader;
+	/**
+	* UDS + cross-node event fan-out. No default: a forked runner has no child
+	* registry, and printing zeros for a plane that does not exist is worse than
+	* printing nothing. Only hub-main and an agent's main pass one.
+	*/
+	readonly eventPlane?: EventPlaneReader;
+	/**
+	* Per-peer UDS socket traffic, split by frame kind. No default, for the same
+	* reason as {@link eventPlane}: a forked runner has no child registry, and the
+	* plane it does have (its single channel to its parent) is already reported
+	* from the parent's side. Only hub-main and an agent's main pass one.
+	*/
+	readonly socketPlane?: SocketPlaneReader;
+	/**
+	* The write queue of every Moleculer TCP socket to a peer node. No default:
+	* only a process with a broker on a real transporter has one. Those sockets
+	* are UNREF'D by Moleculer, so a sum over `_getActiveHandles()` never listed
+	* them — the hole in the 2026-09-10 exclusion of "every socket queue"
+	* (D446). Read on every probe, judged with the UDS queues below.
+	*/
+	readonly meshQueue?: MeshQueueReader;
+	/**
+	* Thresholds for the outbound-queue gate. The gate itself is created
+	* whenever {@link socketPlane} or {@link meshQueue} is given; this only
+	* tunes it (tests, or a process with a different notion of "held").
+	*/
+	readonly outboundQueue?: OutboundQueueGateOptions;
+	/**
+	* The ArrayBuffer census that ARMS ITSELF. No default: it costs a forced
+	* full GC when it fires, and only hub-main has an episode on record (two
+	* silent linear climbs to 1.3 GB and 5 GB on 2026-09-10, each released in
+	* one instant with no line, the second two hours before the OOM). A runner
+	* that legitimately holds gigabytes of ArrayBuffers (`hub/stream-broker`,
+	* ~900 MB of RTP pre-roll rings) would fire it forever. See
+	* `array-buffer-census.ts` for the gate, the cost and what it is NOT.
+	*/
+	readonly arrayBufferCensus?: ArrayBufferCensusProbe;
+	/**
+	* How the GC census observes collections. Defaults to the real Node
+	* observer, for EVERY process — the rate is half of what a GC costs and the
+	* line has never carried it (see `gc-census.ts`). A spec passes its own so a
+	* sequence of collections can be posed; nothing in production passes one.
+	*/
+	readonly gcObserver?: NodeGcObserver;
+	/**
+	* How this process reads its own CPU. Defaults to the real
+	* `process.cpuUsage()` and the real `/proc/self/task`, for EVERY process —
+	* `docker stats` reports the cgroup, and nothing on any line said what share
+	* of it this process was (see `process-cpu-census.ts`). A spec passes its own
+	* so a cost can be posed; nothing in production passes one.
+	*/
+	readonly processCpu?: ProcessCpuProbe;
 }
 /** The two readings `process-cpu-census.ts` needs, injectable for a spec. */
 export interface ProcessCpuProbe {
-    readonly cpuUsageUs: () => number;
-    readonly readTasks: () => readonly TaskTicks[] | null;
+	readonly cpuUsageUs: () => number;
+	readonly readTasks: () => readonly TaskTicks[] | null;
 }
 /** How the census is wired: the census itself plus the gate's thresholds. */
 export interface ArrayBufferCensusProbe extends ArrayBufferCensusGateOptions {
-    readonly census: ArrayBufferCensus;
+	readonly census: ArrayBufferCensus;
 }
 /**
- * Every outbound queue the heartbeat can reach, as the gate wants them: the
- * UDS children (only those whose channel keeps a reading — an unmeasured
- * peer is not a zero) and the mesh writer sockets, each prefixed with its
- * plane.
- */
+* Every outbound queue the heartbeat can reach, as the gate wants them: the
+* UDS children (only those whose channel keeps a reading — an unmeasured
+* peer is not a zero) and the mesh writer sockets, each prefixed with its
+* plane.
+*/
 export declare function outboundQueueReadings(uds: SocketPlaneCounters | undefined, mesh: readonly MeshPeerQueue[] | undefined): readonly OutboundQueueReading[];
 /**
- * Start the heartbeat. Returns a stop function.
- *
- * `unref`ed so it can never hold the process open, and every read is wrapped:
- * a diagnostic that can crash the process it watches is worse than none.
- */
+* Start the heartbeat. Returns a stop function.
+*
+* `unref`ed so it can never hold the process open, and every read is wrapped:
+* a diagnostic that can crash the process it watches is worse than none.
+*/
 export declare function startHeapWatch(label?: string, sink?: HeapWatchSink, intervalMs?: number, reclaimOptions?: HeapReclaimOptions, loopDelay?: LoopDelayMeter | undefined, execArgv?: readonly string[], announceCeilingOrigin?: boolean, rssBudget?: RssBudgetOptions, probes?: HeapWatchProbes): () => void;
 /**
- * Steady heartbeat period for a HEAVY addon runner.
- *
- * hub-main logs once a minute because it is ONE process. The heavy runners are
- * ~7 per node sharing the same hub log stream; at 60s each they would put 7
- * routine lines a minute in it forever, which is how a log stops being read.
- * Five minutes keeps the per-runner record (a leak is still a visible climb
- * across samples) at ~1.4 lines/min across the class.
- *
- * This slows LOGGING only. The probe keeps running at
- * {@link HEAP_WATCH_FAST_INTERVAL_MS} (probe and log cadences are separate —
- * see the comment inside {@link startHeapWatch}), so the reclaim gate and the
- * escalated burst-sampling react exactly as fast as hub-main's.
- */
-export declare const RUNNER_HEAP_WATCH_INTERVAL_MS = 300000;
+* Steady heartbeat period for a HEAVY addon runner.
+*
+* hub-main logs once a minute because it is ONE process. The heavy runners are
+* ~7 per node sharing the same hub log stream; at 60s each they would put 7
+* routine lines a minute in it forever, which is how a log stops being read.
+* Five minutes keeps the per-runner record (a leak is still a visible climb
+* across samples) at ~1.4 lines/min across the class.
+*
+* This slows LOGGING only. The probe keeps running at
+* {@link HEAP_WATCH_FAST_INTERVAL_MS} (probe and log cadences are separate —
+* see the comment inside {@link startHeapWatch}), so the reclaim gate and the
+* escalated burst-sampling react exactly as fast as hub-main's.
+*/
+export declare const RUNNER_HEAP_WATCH_INTERVAL_MS = 3e5;
 /** Wiring for {@link startRunnerHeapWatch}. */
 export interface RunnerHeapWatchOptions {
-    /**
-     * `CAMSTACK_RUNNER_HEAP_PROFILE` as the parent passed it. Anything but
-     * `'heavy'` (including unset — the un-annotated default is light) starts
-     * nothing: light runners are small, already carry V8 heap flags, and a
-     * quiet runner must never pay a stop-the-world.
-     */
-    readonly heapProfile: string | undefined;
-    /** Log label — the runner's nodeId, so `[mem]` lines group per runner. */
-    readonly label: string;
-    readonly sink: HeapWatchSink;
-    /**
-     * `CAMSTACK_RUNNER_HEAP_RECLAIM` as the environment carries it. `'off'`
-     * keeps the heartbeat and disables only the reclaim pass — the operator
-     * kill-switch for the media path, usable without a rebuild.
-     */
-    readonly reclaimSwitch?: string;
-    /** Heartbeat period override. Defaults to {@link RUNNER_HEAP_WATCH_INTERVAL_MS}. */
-    readonly intervalMs?: number;
-    /** Test injection. Production omits it and gets {@link createV8Reclaimer}. */
-    readonly reclaimOptions?: HeapReclaimOptions;
-    /**
-     * `CAMSTACK_RUNNER_RSS_BUDGET_MB` as the parent passed it — the MAXIMUM
-     * `execution.rssBudgetMb` any co-located addon declares, resolved from the
-     * manifests in `process-service.ts`. Absent means no co-located addon declared
-     * one, and the runner reports itself UNWATCHED. See {@link RssBudgetOptions}.
-     */
-    readonly rssBudgetMb?: string;
+	/**
+	* `CAMSTACK_RUNNER_HEAP_PROFILE` as the parent passed it. Anything but
+	* `'heavy'` (including unset — the un-annotated default is light) starts
+	* nothing: light runners are small, already carry V8 heap flags, and a
+	* quiet runner must never pay a stop-the-world.
+	*/
+	readonly heapProfile: string | undefined;
+	/** Log label — the runner's nodeId, so `[mem]` lines group per runner. */
+	readonly label: string;
+	readonly sink: HeapWatchSink;
+	/**
+	* `CAMSTACK_RUNNER_HEAP_RECLAIM` as the environment carries it. `'off'`
+	* keeps the heartbeat and disables only the reclaim pass — the operator
+	* kill-switch for the media path, usable without a rebuild.
+	*/
+	readonly reclaimSwitch?: string;
+	/** Heartbeat period override. Defaults to {@link RUNNER_HEAP_WATCH_INTERVAL_MS}. */
+	readonly intervalMs?: number;
+	/** Test injection. Production omits it and gets {@link createV8Reclaimer}. */
+	readonly reclaimOptions?: HeapReclaimOptions;
+	/**
+	* `CAMSTACK_RUNNER_RSS_BUDGET_MB` as the parent passed it — the MAXIMUM
+	* `execution.rssBudgetMb` any co-located addon declares, resolved from the
+	* manifests in `process-service.ts`. Absent means no co-located addon declared
+	* one, and the runner reports itself UNWATCHED. See {@link RssBudgetOptions}.
+	*/
+	readonly rssBudgetMb?: string;
 }
 /**
- * Parse a budget carried across a process boundary as an env string.
- *
- * Anything that is not a positive finite integer is `undefined` — i.e. the
- * process is UNWATCHED and says so. A malformed budget must never round to a
- * silent default: that is the failure this whole mechanism exists to remove.
- */
+* Parse a budget carried across a process boundary as an env string.
+*
+* Anything that is not a positive finite integer is `undefined` — i.e. the
+* process is UNWATCHED and says so. A malformed budget must never round to a
+* silent default: that is the failure this whole mechanism exists to remove.
+*/
 export declare function parseRssBudgetMb(raw: string | undefined): number | undefined;
 /** Env var carrying a runner's declared RSS budget from parent to child. */
 export declare const RUNNER_RSS_BUDGET_ENV = "CAMSTACK_RUNNER_RSS_BUDGET_MB";
 /** Operator override for hub-main's budget, applied without a release. */
 export declare const HUB_RSS_BUDGET_ENV = "CAMSTACK_HUB_RSS_BUDGET_MB";
 /**
- * hub-main's declared RSS budget, in MB.
- *
- * ## Why the number lives HERE and not in the image
- *
- * hub-main has no manifest to declare it in, and the obvious alternative — the
- * entrypoint that already knew about `CAMSTACK_HUB_HEAP_MB` — is the least
- * deployable surface in this system. The Dockerfile says so itself: the image
- * never contains this repo's backend, so a value written there reaches a running
- * hub only on an image rebuild. `main.ts` is what `applyServerUpdate` replaces,
- * which is exactly why the heartbeat was started from there in the first place.
- * A budget that cannot ship is not a budget.
- *
- * ## Why 4096
- *
- * hub-main's entitlement is its old-space ceiling plus its measured native
- * floor. The floor is 438MB, established live across five consecutive
- * `gc(last-resort)` passes that landed within 4MB of each other
- * (4559/4561/4560/4562/4563MB) — sqlite pages, libvips, sharp, thread stacks and
- * node's own text. Against the 3072MB ceiling in force on 2026-08-27 that is
- * ~3.5GB of legitimate footprint, and 4096 leaves it ~600MB of slack.
- *
- * **This WILL fire on the hub as measured on 2026-08-27, and that is the point.**
- * That process sat at 4.87GiB with `external` at 360MB: ~2.8GB of it was native
- * memory already freed and never returned, spread across 13 anonymous mappings
- * >=64MB, with only 1295MB in V8 pages. `MALLOC_ARENA_MAX=2` and
- * `VIPS_CONCURRENCY=1` were already applied — verified from `/proc/<pid>/environ`
- * — so that lever is spent and the residue stands. The alarm reporting a
- * genuinely over-budget process is the mechanism working; a number picked to sit
- * just above today's RSS would be a rubber stamp.
- *
- * An operator who decides that residue is the cost of doing business moves it in
- * one place with {@link HUB_RSS_BUDGET_ENV}, and the decision is on the record
- * instead of being absorbed by a threshold nobody set.
- */
+* hub-main's declared RSS budget, in MB.
+*
+* ## Why the number lives HERE and not in the image
+*
+* hub-main has no manifest to declare it in, and the obvious alternative — the
+* entrypoint that already knew about `CAMSTACK_HUB_HEAP_MB` — is the least
+* deployable surface in this system. The Dockerfile says so itself: the image
+* never contains this repo's backend, so a value written there reaches a running
+* hub only on an image rebuild. `main.ts` is what `applyServerUpdate` replaces,
+* which is exactly why the heartbeat was started from there in the first place.
+* A budget that cannot ship is not a budget.
+*
+* ## Why 4096
+*
+* hub-main's entitlement is its old-space ceiling plus its measured native
+* floor. The floor is 438MB, established live across five consecutive
+* `gc(last-resort)` passes that landed within 4MB of each other
+* (4559/4561/4560/4562/4563MB) — sqlite pages, libvips, sharp, thread stacks and
+* node's own text. Against the 3072MB ceiling in force on 2026-08-27 that is
+* ~3.5GB of legitimate footprint, and 4096 leaves it ~600MB of slack.
+*
+* **This WILL fire on the hub as measured on 2026-08-27, and that is the point.**
+* That process sat at 4.87GiB with `external` at 360MB: ~2.8GB of it was native
+* memory already freed and never returned, spread across 13 anonymous mappings
+* >=64MB, with only 1295MB in V8 pages. `MALLOC_ARENA_MAX=2` and
+* `VIPS_CONCURRENCY=1` were already applied — verified from `/proc/<pid>/environ`
+* — so that lever is spent and the residue stands. The alarm reporting a
+* genuinely over-budget process is the mechanism working; a number picked to sit
+* just above today's RSS would be a rubber stamp.
+*
+* An operator who decides that residue is the cost of doing business moves it in
+* one place with {@link HUB_RSS_BUDGET_ENV}, and the decision is on the record
+* instead of being absorbed by a threshold nobody set.
+*/
 export declare const HUB_MAIN_RSS_BUDGET_MB = 4096;
 /** hub-main's budget: the declared number, or the operator's override. */
 export declare function hubMainRssBudget(env?: NodeJS.ProcessEnv): RssBudgetOptions;
 /**
- * Start the heap watch + stranded-page reclaimer for ONE addon runner, iff it
- * is a heavy one. Returns the stop function, or undefined when nothing started.
- *
- * ## Why heavy runners get hub-main's mechanism
- *
- * Because a heap ceiling cannot reach what actually strands in them. Every
- * media-path runner now carries an old-space ceiling sized from its own
- * measured peak (`addon-pipeline` manifest + its `manifest-heap-ceilings` spec),
- * and that changes nothing here: what a heavy runner strands is NATIVE —
- * `external`, `arrayBuffers`, glibc arena free lists — none of which
- * `--max-old-space-size` bounds. Measured 2026-08-25, `hub/pipeline-analytics`
- * reported `stranded=2552MB` while holding an 81MB V8 heap under a 1024MB
- * ceiling that was in force the whole time. hub-main had exactly this shape and
- * its reclaimer is proven live — 11 passes in 4h, 375–1652MB returned per pass
- * at 550–680ms each. Same mechanism, same `shouldReclaim` stranded-over-trigger
- * gate; never a second implementation.
- *
- * ## The stall, priced for the runners that get it
- *
- * A pass is a sub-second stop-the-world at most once per
- * {@link HEAP_RECLAIM_MIN_INTERVAL_MS}, and only while >1GiB is stranded. For
- * the recorder — finalizing a segment every ~300ms across 34 profile-writers —
- * the pause delays WATCHER work, not video: ffmpeg children keep writing to
- * disk independently, the playlist tail is the durable queue, and the next
- * tick drains what accrued. For stream-broker a pass can hitch live frames
- * once per qualifying window; after a pass the runner sits at its floor and
- * re-stranding the trigger takes tens of minutes, so in practice the class
- * pays a few passes per hour against the multi-GiB peak that was OOM-killing
- * a neighbouring VM on a host with no swap.
- */
+* Start the heap watch + stranded-page reclaimer for ONE addon runner, iff it
+* is a heavy one. Returns the stop function, or undefined when nothing started.
+*
+* ## Why heavy runners get hub-main's mechanism
+*
+* Because a heap ceiling cannot reach what actually strands in them. Every
+* media-path runner now carries an old-space ceiling sized from its own
+* measured peak (`addon-pipeline` manifest + its `manifest-heap-ceilings` spec),
+* and that changes nothing here: what a heavy runner strands is NATIVE —
+* `external`, `arrayBuffers`, glibc arena free lists — none of which
+* `--max-old-space-size` bounds. Measured 2026-08-25, `hub/pipeline-analytics`
+* reported `stranded=2552MB` while holding an 81MB V8 heap under a 1024MB
+* ceiling that was in force the whole time. hub-main had exactly this shape and
+* its reclaimer is proven live — 11 passes in 4h, 375–1652MB returned per pass
+* at 550–680ms each. Same mechanism, same `shouldReclaim` stranded-over-trigger
+* gate; never a second implementation.
+*
+* ## The stall, priced for the runners that get it
+*
+* A pass is a sub-second stop-the-world at most once per
+* {@link HEAP_RECLAIM_MIN_INTERVAL_MS}, and only while >1GiB is stranded. For
+* the recorder — finalizing a segment every ~300ms across 34 profile-writers —
+* the pause delays WATCHER work, not video: ffmpeg children keep writing to
+* disk independently, the playlist tail is the durable queue, and the next
+* tick drains what accrued. For stream-broker a pass can hitch live frames
+* once per qualifying window; after a pass the runner sits at its floor and
+* re-stranding the trigger takes tens of minutes, so in practice the class
+* pays a few passes per hour against the multi-GiB peak that was OOM-killing
+* a neighbouring VM on a host with no swap.
+*/
 export declare function startRunnerHeapWatch(options: RunnerHeapWatchOptions): (() => void) | undefined;