@camstack/system 1.2.151 → 1.2.153

package/dist/kernel/event-plane-report.d.ts

@@ -0,0 +1,202 @@
+/**
+ * event-plane-report — the fan-out counters this cluster has always kept and
+ * never read, on the line it already emits.
+ *
+ * ## Why this exists
+ *
+ * hub-main's memory is a RATE, not a set. Measured 2026-08-29 over the first 25
+ * minutes of telemetry this process has ever produced: every forced compaction
+ * drops `arrayBuffers` to **12–29 MB** — ten passes out of ten — so a reading of
+ * 726 MB is 707 MB of dead Buffers not yet swept, not a retained set. The real
+ * quantity is the slope: **181–330 MB/min steady, with one burst of ≥1.3 GB in
+ * ≤11 s**.
+ *
+ * And it is sockets, not media. `/proc/<pid>/io` over the same windows: ~21 800
+ * reads/s and ~22 500 writes/s at a **0.33 KB mean**, with regular-file reads at
+ * 0.73 MB/min. A 64 KB proxy chunk or a 200 KB JPEG cannot hide inside a 0.33 KB
+ * mean, so the cost is per MESSAGE on a fan-out plane nobody has ever counted —
+ * an IDLE addon still reads 82 messages/s of it, across ~38 runners.
+ *
+ * The strongest single number available is that **78–82% of hub-main's outbound
+ * bytes correlate with `hub/pipeline-analytics`, in both windows** — but `rchar`
+ * on that runner also counts page-cache reads and it owns a vector store, so the
+ * correlation is not an attribution. `fanoutTop` turns it into one.
+ *
+ * ## And the burn-in that has been running forever
+ *
+ * `event-bus-core.ts:310` states the procedure in its own words: *"Recommended
+ * first fleet-wide enable: `shadow` on both, watch the suppressed counters
+ * (`getMoleculerEventStats` / `getChildEventStats`), then flip to `filter` once
+ * burn-in shows zero would-be-starved deliveries."*
+ *
+ * The hub runs with `CAMSTACK_MOLECULER_EVENT_FANOUT=shadow` — which computes
+ * the drop decision, counts the would-suppresses and **still delivers every
+ * event** — and **neither counter has ever had a production caller**: both
+ * functions are reachable only from barrel re-exports and unit tests. So the
+ * burn-in has no end condition, and the promotion to `filter` never happened
+ * because the evidence that would authorise it was never surfaced. This module
+ * surfaces it. It changes no default and flips no env: the promotion stays a
+ * one-env decision for the operator, and it now has a number behind it.
+ *
+ * Read the modes with the counts, always. A suppressed count of 0 means
+ * "nothing would have been dropped" under `shadow` and "nothing WAS dropped"
+ * under `filter`, and those are different claims. A count printed without its
+ * regime is unreadable, and the regime is read ONCE at construction — invisible
+ * at runtime until now.
+ *
+ * ## The fail-open nobody can see
+ *
+ * A child that never declares its pattern set (`eventPatterns === null`,
+ * `local-child-registry.ts:170`) makes the per-child gate fail OPEN, and per
+ * `setNodeEventInterest` ANY undeclared child makes the whole node's inbound
+ * cross-node gate fail open too. **One legacy runner silently disables the
+ * filtering on both planes**, and nothing reported it. `childrenUndeclared` is
+ * printed even at zero for the same reason `largeObjectSpace=0MB` is: absence
+ * must never be ambiguous.
+ *
+ * ## Deltas, never totals
+ *
+ * Both registries count cumulatively for the life of the process. A cumulative
+ * number on a heartbeat answers "how much since boot", which nobody asked; the
+ * question is "which peer receives the 22 500 writes/s", and that is a rate. So
+ * the meter is read ONCE PER LINE and reports the window since the previous read
+ * — the same discipline the loop-delay histogram already follows, for the same
+ * reason.
+ *
+ * ## What this is NOT evidence of
+ *
+ * `shadow` is the CROSS-NODE plane. The local UDS plane defaults to `filter` and
+ * its env is unset, so it is filtering. hub-main's ~44 000 socket syscalls/s are
+ * mostly to LOCAL runners, so the shadow mode is a real defect and is **not**
+ * established as the source of that load. Do not read these two facts as one.
+ */
+/** Fan-out regime for one plane. Same three values on both. */
+export type EventFanoutMode = 'filter' | 'shadow' | 'broadcast';
+/** One child's fan-out counters, as the registry keeps them (cumulative). */
+export interface ChildFanoutSample {
+    readonly childId: string;
+    readonly sent: number;
+    readonly suppressed: number;
+}
+/** One child's fan-out over the window since the previous read. */
+export interface ChildFanoutDelta {
+    readonly childId: string;
+    readonly sent: number;
+    readonly suppressed: number;
+}
+/** What `LocalChildRegistry` exposes, structurally — the kernel's heartbeat
+ *  must not depend on the transport layer's class. */
+export interface ChildFanoutRegistryChild {
+    readonly childId: string;
+}
+export interface ChildFanoutRegistryStats {
+    readonly sent: number;
+    readonly suppressed: number;
+}
+export interface ChildFanoutRegistry {
+    readonly listChildren: () => readonly ChildFanoutRegistryChild[];
+    readonly getChildEventStats: (childId: string) => ChildFanoutRegistryStats | null;
+    readonly undeclaredChildCount: () => number;
+    readonly eventFanoutMode: EventFanoutMode;
+}
+/** What `getMoleculerEventStats` returns, structurally. */
+export interface CrossNodeEventStats {
+    readonly delivered: number;
+    readonly suppressed: number;
+}
+/** One cumulative reading of both planes. */
+export interface EventPlaneCounters {
+    readonly udsMode: EventFanoutMode;
+    readonly crossNodeMode: EventFanoutMode;
+    readonly children: readonly ChildFanoutSample[];
+    readonly childrenConnected: number;
+    readonly childrenUndeclared: number;
+    readonly crossNodeDelivered: number;
+    readonly crossNodeSuppressed: number;
+}
+/** `undefined` = this process has no event plane to report (every forked
+ *  runner, and hub-main before the registry exists). */
+export type EventPlaneReader = () => EventPlaneCounters | undefined;
+/** Where a reader gets each part. Every one is late-bound, because the
+ *  heartbeat starts before any of them exist. */
+export interface EventPlaneSources {
+    readonly registry: () => ChildFanoutRegistry | null;
+    readonly crossNodeStats: () => CrossNodeEventStats | null;
+    readonly crossNodeMode: () => EventFanoutMode;
+}
+/**
+ * Build a reader over the two registries.
+ *
+ * Returns `undefined` until the child registry exists — the heartbeat starts as
+ * the FIRST statement of `bootstrap()` (a process that dies early still leaves
+ * samples) and `LocalChildRegistry` is built hundreds of lines later inside
+ * `MoleculerService.onModuleInit`. Printing zeros in that window would report a
+ * silent plane where there is no plane at all.
+ *
+ * Wrapped: a registry mid-teardown may throw, and a diagnostic that can crash
+ * the process it watches is worse than none.
+ */
+export declare function createEventPlaneReader(sources: EventPlaneSources): EventPlaneReader;
+/**
+ * How many children get named on the line.
+ *
+ * Five, because the question is which peer DOMINATES and the measured
+ * distribution is not flat: one peer accounted for 78–82% of outbound bytes and
+ * the runner-up for ~6%. Five names the dominant peer, its challenger and enough
+ * of the tail to see the shape change; naming all ~38 would put a kilobyte-long
+ * line in the hub's shared log every minute, which is how a log stops being read.
+ */
+export declare const EVENT_PLANE_TOP_N = 5;
+/** Both planes over one heartbeat window. */
+export interface EventPlaneWindow {
+    readonly udsMode: EventFanoutMode;
+    readonly crossNodeMode: EventFanoutMode;
+    readonly childrenConnected: number;
+    readonly childrenUndeclared: number;
+    readonly fanoutSent: number;
+    readonly fanoutSuppressed: number;
+    readonly crossNodeDelivered: number;
+    readonly crossNodeSuppressed: number;
+    /** Largest `sent` first, at most {@link EVENT_PLANE_TOP_N} entries. */
+    readonly top: readonly ChildFanoutDelta[];
+}
+/** Previous cumulative reading, kept between lines. */
+export interface EventPlaneBaseline {
+    readonly children: ReadonlyMap<string, ChildFanoutSample>;
+    readonly crossNodeDelivered: number;
+    readonly crossNodeSuppressed: number;
+}
+/** A process that has never read a plane. */
+export declare const EMPTY_EVENT_PLANE_BASELINE: EventPlaneBaseline;
+/**
+ * Subtract the previous cumulative reading from the current one.
+ *
+ * A child that RESTARTED has counters that went backwards — the registry keys by
+ * childId and a respawned runner reconnects under the same id with a fresh
+ * entry. Clamping at 0 reports the restart as a quiet window rather than as a
+ * negative rate: the window's traffic is genuinely unknown, and a negative
+ * number on a rate reads as a broken meter.
+ */
+export declare function diffEventPlane(baseline: EventPlaneBaseline, current: EventPlaneCounters, topN?: number): EventPlaneWindow;
+/** Reads the delta since the PREVIOUS read. Same contract as the loop meter. */
+export interface EventPlaneMeter {
+    readonly read: () => EventPlaneWindow | undefined;
+}
+export declare function createEventPlaneMeter(reader: EventPlaneReader, topN?: number): EventPlaneMeter;
+/**
+ * The suffix appended to a `[mem]` line — leading space included, empty when
+ * this process has no event plane.
+ *
+ * Only two processes in the cluster have one (hub-main, and an agent's main), so
+ * these fields never appear on the ~38 runner lines that share the same log
+ * stream. On the two that do, every field is printed on every line INCLUDING at
+ * zero: the modes because a suppressed count without its regime is unreadable,
+ * `childrenUndeclared` because one undeclared child silently disables both
+ * gates, and the deltas because "the plane went quiet for a minute" is a
+ * reading, not a blank.
+ *
+ * `fanoutTop` is the one conditional field — a ranked list of nothing is noise —
+ * and it is a single comma-separated value so the field COUNT does not change
+ * from line to line: `childId:sent/suppressed`, largest first.
+ */
+export declare function formatEventPlane(window: EventPlaneWindow | undefined): string;

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

@@ -0,0 +1,138 @@
+import { HeapWatchSink } from './heap-watch.js';
+/** One V8 space, as V8 names it, with the bytes it is holding. */
+export interface HeapSpaceUsage {
+    /** V8's own `space_name`, e.g. `old_space`. Never renamed here. */
+    readonly name: string;
+    readonly usedBytes: number;
+}
+/** A reading of every space. Injectable so a test can pose a known heap state. */
+export type HeapSpaceReader = () => readonly HeapSpaceUsage[];
+/**
+ * The two spaces that ANSWER the question, printed always — including at zero.
+ *
+ * Node 24 reports thirteen spaces (measured on 24.17: `read_only_space`,
+ * `new_space`, `old_space`, `code_space`, `shared_space`, `trusted_space`,
+ * `shared_trusted_space`, `new_large_object_space`, `large_object_space`,
+ * `code_large_object_space`, `shared_large_object_space`,
+ * `shared_trusted_large_object_space`, `trusted_large_object_space`). Printing
+ * all thirteen once a minute per process would add ~13 fields to a line that
+ * already carries eleven, on every runner, forever — and eleven of the thirteen
+ * cannot be the answer to a 1.4 GB retained-set question.
+ *
+ * These two are printed unconditionally because **absence must never be
+ * ambiguous**. A threshold-only rule would drop `large_object_space` at 20 MB,
+ * and a reader would not be able to tell "small" from "this build does not
+ * report it" — which is the same class of mistake as a heartbeat with no
+ * destination (D285). `largeObjectSpace=0MB` is a load-bearing reading: it says
+ * the retainer is NOT a handful of huge objects.
+ */
+export declare const DECISIVE_HEAP_SPACES: readonly string[];
+/**
+ * A non-decisive space is printed only once it holds at least this many MB.
+ *
+ * 32 MB, and the number comes from the smallest heap this line is ever asked to
+ * explain: the control in the 2026-08-29 pass is an idle `recorder` runner at
+ * **52 MB** of `heapUsed`. A threshold below that means no space that could
+ * dominate even the smallest watched process is ever hidden, while a quiet
+ * process — measured on a bare Node 24.17: `new_space` 0.7 MB, `code_space`
+ * 0.25 MB, `trusted_space` 0.9 MB — prints nothing but the decisive pair.
+ *
+ * What this drops, and why it is right to drop it: `new_space` is the scavenger's
+ * semi-space and is bounded by `--max-semi-space-size`, so it can never be a
+ * retained set; `code_space` and `read_only_space` are JIT output and V8's own
+ * immutable roots, both bounded by the code that exists rather than by the data
+ * it touches; the `shared_*` spaces are empty outside a worker-threads
+ * deployment, which this cluster does not run. None of them has ever been the
+ * answer to "what is this process holding", and each would cost a field on
+ * every `[mem]` line in the fleet.
+ *
+ * They are not censored, though — a space over the threshold prints, whatever it
+ * is. If `code_space` ever reaches 32 MB that is itself the finding.
+ */
+export declare const HEAP_SPACE_REPORT_MIN_MB = 32;
+/**
+ * Read every space from V8.
+ *
+ * Wrapped: a diagnostic that can crash the process it watches is worse than
+ * none, and this is called from a heartbeat whose whole contract is that it
+ * survives whatever it is measuring. An empty reading prints no fields, which
+ * is exactly what a heartbeat that could not read the heap should say.
+ */
+export declare function readHeapSpaces(): readonly HeapSpaceUsage[];
+/**
+ * `old_space` → `oldSpace`. Mechanical and total, so a space V8 adds tomorrow
+ * gets a field name without anyone editing a table.
+ *
+ * camelCase because that is the vocabulary of every other field on this line
+ * (`heapUsed`, `heapTotal`, `arrayBuffers`, `rssBudget`, `loopP99`). A line that
+ * mixed `heapUsed=` with `old_space=` would be two conventions for one record.
+ */
+export declare function heapSpaceField(v8Name: string): string;
+/**
+ * The spaces worth a field on this line: the decisive pair (in that order,
+ * always), then every other space at or above `minMb`, largest first.
+ *
+ * Largest-first for the tail because the tail only ever appears when something
+ * unexpected is holding memory, and the biggest surprise should be the first
+ * thing read. The decisive pair keeps a FIXED position so the two numbers a
+ * reader is comparing are always in the same place on every line.
+ */
+export declare function selectReportedSpaces(spaces: readonly HeapSpaceUsage[], minMb?: number): readonly HeapSpaceUsage[];
+/**
+ * The suffix appended to a `[mem]` line — leading space included, empty when
+ * there is nothing to say.
+ *
+ * APPENDED, never interleaved: every existing field keeps its name AND its
+ * position, so a `hl loki-query` pipeline written against the old line still
+ * matches. Prefix stability is the only change to a log line that cannot break
+ * a query someone already wrote.
+ */
+export declare function formatHeapSpaces(spaces: readonly HeapSpaceUsage[], minMb?: number): string;
+/**
+ * Env var that authorises a heap snapshot on SIGUSR2.
+ *
+ * A snapshot is an admin mutation on a production hub: `writeHeapSnapshot`
+ * streams a file the size of the heap to `/tmp` and stops the world while it
+ * walks it — on the recorder that is a multi-GB file and a stall measured in
+ * seconds. The per-space breakdown is ~1.2 µs and changes nothing. Welding them
+ * to one signal priced the free answer at the cost of the expensive one.
+ */
+export declare const RUNNER_HEAP_SNAPSHOT_ENV = "CAMSTACK_RUNNER_HEAP_SNAPSHOT";
+/**
+ * Whether the operator has authorised the snapshot half of SIGUSR2.
+ *
+ * Explicit `'on'` only. Anything else — unset, empty, `'true'`, `'1'` — is NOT
+ * authorisation: a multi-GB stop-the-world write must never be reachable by a
+ * value someone set for a different purpose.
+ */
+export declare function heapSnapshotAuthorised(env?: NodeJS.ProcessEnv): boolean;
+/** What a diagnostic report is ABOUT. */
+export interface HeapDiagnosticRequest {
+    /** The runner's nodeId, so the line groups with its `[mem]` heartbeat. */
+    readonly label: string;
+    readonly addons: readonly string[];
+    readonly sink: HeapWatchSink;
+    /** Where a snapshot would be written, if one is authorised. */
+    readonly snapshotPath: string;
+}
+/** Everything the report READS. Injected so the split itself is testable. */
+export interface HeapDiagnosticDeps {
+    readonly readMemory: () => NodeJS.MemoryUsage;
+    readonly readSpaces: HeapSpaceReader;
+    readonly writeSnapshot: (path: string) => void;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * The SIGUSR2 report — memory + the FULL per-space breakdown, always; the
+ * snapshot only when {@link heapSnapshotAuthorised}.
+ *
+ * The breakdown here keeps every non-empty space at 0.1 MB, unlike the
+ * heartbeat's filtered whole-MB pair: this is a hand-fired diagnostic read once
+ * by a human who asked for it, so completeness costs nothing. The heartbeat runs
+ * unattended on every runner forever, so it pays for every field it prints.
+ *
+ * A refused snapshot SAYS SO. A branch that drops work silently reads as "it was
+ * never requested", and this one is fired by an operator who is standing there
+ * waiting for a file.
+ */
+export declare function emitHeapDiagnosticReport(request: HeapDiagnosticRequest, deps?: HeapDiagnosticDeps): void;

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

@@ -1,3 +1,5 @@
+import { EventPlaneReader } from './event-plane-report.js';
+import { HeapSpaceReader } from './heap-spaces.js';
 /**
  * What hub-main calls itself in a `[mem]` line.
  *
@@ -137,12 +139,95 @@ export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 120000;
  * 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. The warn changes no behaviour — the pass is load-bearing and
- * keeps running. It exists so the OPERATOR is told that the safety net has
- * become the mechanism, which is the moment to go after the allocation source
- * instead of the symptom.
+ * 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;
+/**
+ * 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.
  *
@@ -181,6 +266,37 @@ export interface LoopDelayMeter {
  * 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.
  */
@@ -396,6 +512,9 @@ export interface HeapReclaimOptions {
     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;
@@ -462,13 +581,31 @@ export interface RssBudgetOptions {
     /** 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.
+ */
+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;
+}
 /**
  * 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): () => void;
+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.
  *

package/dist/kernel/index.d.ts

@@ -40,6 +40,8 @@ export { createCoreCapService, CORE_CAP_SERVICE_NAME } from './moleculer/core-ca
 export type { CoreCapAction, CoreCapCallOrigin, CoreCapServiceOptions, } from './moleculer/core-cap-service.js';
 export { createAddonContext, createUdsAddonContext, setHubConnected, adaptBrokerToCluster, registerEventBusService, setNodeEventInterest, getMoleculerEventStats, subscribePassthrough, getBrokerEventBus, clusterEventTopic, EVENT_TOPIC_PREFIX, } from './moleculer/addon-context-factory.js';
 export type { MoleculerEventStats } from './moleculer/addon-context-factory.js';
+export type { MoleculerEventFanoutMode } from './moleculer/event-bus-core.js';
+export { readMoleculerFanoutMode } from './moleculer/event-bus-core.js';
 export { HubLogForwarder } from './moleculer/hub-log-forwarder.js';
 export type { AddonContextOptions } from './moleculer/addon-context-factory.js';
 export { createHubService } from './moleculer/hub-service.js';

package/dist/kernel/transport/local-child-registry.d.ts

@@ -183,6 +183,28 @@ export declare class LocalChildRegistry {
      * surface (shadow burn-in + operator debug).
      */
     getChildEventStats(childId: string): ChildEventStats | null;
+    /**
+     * The regime the counters above were produced under, read once from
+     * `CAMSTACK_UDS_EVENT_FANOUT` at construction.
+     *
+     * A suppressed count means "nothing WAS dropped" under `filter` and "nothing
+     * WOULD have been dropped" under `shadow`. Those are different claims, and
+     * until this getter existed the mode was invisible at runtime — the counters
+     * were readable and the regime that produced them was not.
+     */
+    get eventFanoutMode(): UdsEventFanoutMode;
+    /**
+     * Connected children that never declared a subscription pattern set.
+     *
+     * Each one is a fail-open on BOTH planes: `childWantsEvent` returns true for
+     * an undeclared child ({@link ChildEntry.eventPatterns} `=== null`), and
+     * `aggregateEventInterest` returns `null` — accept everything — if ANY
+     * connected child is undeclared, which disables the node's inbound cross-node
+     * gate as well. **One legacy runner silently turns off the filtering for the
+     * whole node**, and nothing reported it, so a zero here is as load-bearing as
+     * a non-zero one.
+     */
+    undeclaredChildCount(): number;
     /**
      * Does `entry` want to receive an event in `category`? Honours the fan-out
      * mode: `broadcast` → always; undeclared patterns (`null`) → always