@camstack/system 1.2.389 → 1.2.391

package/dist/kernel/gc-census.d.ts

@@ -1,144 +1,144 @@
 /**
- * gc-census — HOW OFTEN V8 collects, on the ordinary heartbeat.
- *
- * ## The question this exists to answer, and why four records could not
- *
- * A garbage collector's cost is a product of two independent things: the LIVE
- * SET (how much there is to mark) and the RATE at which a cycle is triggered.
- * The `[mem]` line has carried the live set since 2026-08-29 — `heapUsed`,
- * `oldSpace`, `largeObjectSpace`, `external`, `arrayBuffers` — and has never
- * carried the rate. So D443, D444, D446 and D456 each read a level, saw it flat
- * or falling, and could not say whether the GC share they were looking at came
- * from the size of the heap or from the frequency of the collection. D444 cut
- * hub-main's live set from 2 491 MB to 714 MB — a factor of 3.5 — and the GC
- * share did not move. That result was unreadable until the rate was measured.
- *
- * Measured on hub-main 2026-09-11 with the observer below, the answer was on
- * sight: **1.39 major mark-compacts per second against a 602 MB live set whose
- * old space grew 22 MB/s.** A major GC every 0.7 s cannot be explained by 22
- * MB/s of heap growth under a 3 264 MB ceiling — V8 was being driven by
- * EXTERNAL memory pressure (537 MB/s of ArrayBuffer allocation, D458), and each
- * of those cycles then had to mark the 602 MB live set on four platform
- * workers. That is 70 % of the process.
- *
- * ## Why counts and not a rate of bytes
- *
- * An allocation rate sampled from `process.memoryUsage()` on this heartbeat
- * would be a lie with a number on it. The probe runs every 2 s; external memory
- * on hub-main cycles many times inside 2 s, so a sum of positive deltas
- * under-reports it by more than an order of magnitude (a 100 ms sampler already
- * reported 234 MB/s where a 5 ms one would have said 537). The GC COUNT is
- * exact at any cadence — V8 reports every cycle — and it is the half of the
- * product the line was missing. Read against the `oldSpace=` field already on
- * the line, the two together say which economy is paying:
- *
- *  - many majors, little old-space growth between them ⇒ EXTERNAL pressure.
- *    The fix is an allocation site, and shrinking the live set buys nothing.
- *  - majors that track old-space growth ⇒ the heap is genuinely filling.
- *    The fix is retention.
- *
- * ## Cost
- *
- * One prologue/epilogue callback per GC, into a counter. On hub-main at its
- * worst that is ~4 entries/s. The observer was run against the live hub three
- * times for 90 s while this was written, with no measurable effect on the
- * process; `Profiler.start`, by comparison, stalls it 867 ms (D456).
- *
- * Absence is never zero (D393): a runtime that will not give an observer
- * reports NOTHING on the line, not a census of zero collections.
- */
+* gc-census — HOW OFTEN V8 collects, on the ordinary heartbeat.
+*
+* ## The question this exists to answer, and why four records could not
+*
+* A garbage collector's cost is a product of two independent things: the LIVE
+* SET (how much there is to mark) and the RATE at which a cycle is triggered.
+* The `[mem]` line has carried the live set since 2026-08-29 — `heapUsed`,
+* `oldSpace`, `largeObjectSpace`, `external`, `arrayBuffers` — and has never
+* carried the rate. So D443, D444, D446 and D456 each read a level, saw it flat
+* or falling, and could not say whether the GC share they were looking at came
+* from the size of the heap or from the frequency of the collection. D444 cut
+* hub-main's live set from 2 491 MB to 714 MB — a factor of 3.5 — and the GC
+* share did not move. That result was unreadable until the rate was measured.
+*
+* Measured on hub-main 2026-09-11 with the observer below, the answer was on
+* sight: **1.39 major mark-compacts per second against a 602 MB live set whose
+* old space grew 22 MB/s.** A major GC every 0.7 s cannot be explained by 22
+* MB/s of heap growth under a 3 264 MB ceiling — V8 was being driven by
+* EXTERNAL memory pressure (537 MB/s of ArrayBuffer allocation, D458), and each
+* of those cycles then had to mark the 602 MB live set on four platform
+* workers. That is 70 % of the process.
+*
+* ## Why counts and not a rate of bytes
+*
+* An allocation rate sampled from `process.memoryUsage()` on this heartbeat
+* would be a lie with a number on it. The probe runs every 2 s; external memory
+* on hub-main cycles many times inside 2 s, so a sum of positive deltas
+* under-reports it by more than an order of magnitude (a 100 ms sampler already
+* reported 234 MB/s where a 5 ms one would have said 537). The GC COUNT is
+* exact at any cadence — V8 reports every cycle — and it is the half of the
+* product the line was missing. Read against the `oldSpace=` field already on
+* the line, the two together say which economy is paying:
+*
+*  - many majors, little old-space growth between them ⇒ EXTERNAL pressure.
+*    The fix is an allocation site, and shrinking the live set buys nothing.
+*  - majors that track old-space growth ⇒ the heap is genuinely filling.
+*    The fix is retention.
+*
+* ## Cost
+*
+* One prologue/epilogue callback per GC, into a counter. On hub-main at its
+* worst that is ~4 entries/s. The observer was run against the live hub three
+* times for 90 s while this was written, with no measurable effect on the
+* process; `Profiler.start`, by comparison, stalls it 867 ms (D456).
+*
+* Absence is never zero (D393): a runtime that will not give an observer
+* reports NOTHING on the line, not a census of zero collections.
+*/
 /** One window of collections, as V8 counted them. */
 export interface GcCensusWindow {
-    /** Full mark-compacts. The expensive kind: every one marks the live set. */
-    readonly majors: number;
-    /** Scavenges of the young generation. */
-    readonly minors: number;
-    /** Incremental marking steps on the main thread. */
-    readonly incrementals: number;
-    /** Total MAIN-THREAD pause across the window. Never the concurrent work. */
-    readonly pauseMs: number;
-    /** How long the window was, so a rate can be computed from the line. */
-    readonly windowMs: number;
+	/** Full mark-compacts. The expensive kind: every one marks the live set. */
+	readonly majors: number;
+	/** Scavenges of the young generation. */
+	readonly minors: number;
+	/** Incremental marking steps on the main thread. */
+	readonly incrementals: number;
+	/** Total MAIN-THREAD pause across the window. Never the concurrent work. */
+	readonly pauseMs: number;
+	/** How long the window was, so a rate can be computed from the line. */
+	readonly windowMs: number;
 }
 /**
- * A census that accumulates until it is read, then starts a new window.
- *
- * Window semantics, not cumulative, for the reason D456 gives: a line printing
- * a lifetime total says nothing about the minute it describes, and the reader
- * has to diff two lines by hand to learn anything.
- */
+* A census that accumulates until it is read, then starts a new window.
+*
+* Window semantics, not cumulative, for the reason D456 gives: a line printing
+* a lifetime total says nothing about the minute it describes, and the reader
+* has to diff two lines by hand to learn anything.
+*/
 export interface GcCensus {
-    /** The window since the previous read. `null` until the first full window. */
-    readonly read: (at: number) => GcCensusWindow | null;
-    readonly stop: () => void;
+	/** The window since the previous read. `null` until the first full window. */
+	readonly read: (at: number) => GcCensusWindow | null;
+	readonly stop: () => void;
 }
 /** What the census counts. Node's `PerformanceEntry.detail.kind` values. */
 export interface GcObservation {
-    readonly kind: number;
-    readonly durationMs: number;
+	readonly kind: number;
+	readonly durationMs: number;
 }
 /**
- * How the census is fed. Injectable so a spec can pose a sequence of
- * collections without provoking real ones, which is not something a test can
- * do deterministically.
- */
+* How the census is fed. Injectable so a spec can pose a sequence of
+* collections without provoking real ones, which is not something a test can
+* do deterministically.
+*/
 export type GcObserverInstall = (observe: (entry: GcObservation) => void) => (() => void) | undefined;
 /**
- * V8's kinds, as Node reports them on `detail.kind`.
- *
- * Read from `perf_hooks.constants` rather than written as literals: the values
- * are a Node ABI, and a literal `4` in this file would keep compiling and stop
- * meaning "major" the release it changed.
- */
+* V8's kinds, as Node reports them on `detail.kind`.
+*
+* Read from `perf_hooks.constants` rather than written as literals: the values
+* are a Node ABI, and a literal `4` in this file would keep compiling and stop
+* meaning "major" the release it changed.
+*/
 export interface GcKinds {
-    readonly major: number;
-    readonly minor: number;
-    readonly incremental: number;
+	readonly major: number;
+	readonly minor: number;
+	readonly incremental: number;
 }
 /**
- * The shortest window a rate may be quoted over.
- *
- * One second, and the number comes from the line this field lives on: the boot
- * line is printed microseconds after the watch starts, and `maj0@0s` there
- * would be a rate computed over no time at all — indistinguishable on sight
- * from a process that is genuinely not collecting. Below the floor the census
- * says NOTHING, which is the same discipline as an unobservable runtime
- * (D393): a window too short to answer is not an answer of zero.
- */
-export declare const GC_CENSUS_MIN_WINDOW_MS = 1000;
+* The shortest window a rate may be quoted over.
+*
+* One second, and the number comes from the line this field lives on: the boot
+* line is printed microseconds after the watch starts, and `maj0@0s` there
+* would be a rate computed over no time at all — indistinguishable on sight
+* from a process that is genuinely not collecting. Below the floor the census
+* says NOTHING, which is the same discipline as an unobservable runtime
+* (D393): a window too short to answer is not an answer of zero.
+*/
+export declare const GC_CENSUS_MIN_WINDOW_MS = 1e3;
 /**
- * Build a census over an injected observer.
- *
- * Returns `undefined` when the observer cannot be installed — the caller then
- * prints nothing, which is the honest reading. It must never degrade into a
- * census that reports zero collections: a process whose GC is not being
- * observed and a process that is not collecting look identical on the line, and
- * they are the two answers furthest apart.
- */
+* Build a census over an injected observer.
+*
+* Returns `undefined` when the observer cannot be installed — the caller then
+* prints nothing, which is the honest reading. It must never degrade into a
+* census that reports zero collections: a process whose GC is not being
+* observed and a process that is not collecting look identical on the line, and
+* they are the two answers furthest apart.
+*/
 export declare function createGcCensus(install: GcObserverInstall, kinds: GcKinds, startedAt: number): GcCensus | undefined;
 /** The real Node observer and the real kind constants, wrapped so they can be replaced in a spec. */
 export interface NodeGcObserver {
-    readonly install: GcObserverInstall;
-    readonly kinds: GcKinds;
+	readonly install: GcObserverInstall;
+	readonly kinds: GcKinds;
 }
 /**
- * The observer this process actually gets.
- *
- * Everything that can fail is inside the try: a runtime without
- * `perf_hooks`, without the `gc` entry type, or without the kind constants
- * yields `undefined` from `install`, and {@link createGcCensus} then declines
- * to exist rather than reporting zeros.
- */
+* The observer this process actually gets.
+*
+* Everything that can fail is inside the try: a runtime without
+* `perf_hooks`, without the `gc` entry type, or without the kind constants
+* yields `undefined` from `install`, and {@link createGcCensus} then declines
+* to exist rather than reporting zeros.
+*/
 export declare function nodeGcObserver(): NodeGcObserver;
 /**
- * The two fields, APPENDED LAST on the `[mem]` line.
- *
- * D446's rule: no existing field moves, so every Loki prefix written since
- * 2026-08-29 still matches. `gc=` prints even when nothing was collected — a
- * window with no collections is a reading, and it is the reading that says a
- * process is idle rather than unobserved. `gcPauseMs=` is the MAIN-THREAD
- * pause only; the concurrent marking that cost hub-main 70 % of its CPU is on
- * the platform workers and no in-process counter sees it, which is why the
- * field is named for the thread it describes (D456, part 4).
- */
+* The two fields, APPENDED LAST on the `[mem]` line.
+*
+* D446's rule: no existing field moves, so every Loki prefix written since
+* 2026-08-29 still matches. `gc=` prints even when nothing was collected — a
+* window with no collections is a reading, and it is the reading that says a
+* process is idle rather than unobserved. `gcPauseMs=` is the MAIN-THREAD
+* pause only; the concurrent marking that cost hub-main 70 % of its CPU is on
+* the platform workers and no in-process counter sees it, which is why the
+* field is named for the thread it describes (D456, part 4).
+*/
 export declare function formatGcCensus(window: GcCensusWindow | null | undefined): string;

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

@@ -1,112 +1,112 @@
-import { HeapWatchSink } from './heap-watch.js';
+import type { 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;
+	/** 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.
- */
+* 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.
- */
+* 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.
- */
+* 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.
- */
+* `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.
- */
+* 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.
- */
+* 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;
 /** 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;
+	/** The runner's nodeId, so the line groups with its `[mem]` heartbeat. */
+	readonly label: string;
+	readonly addons: readonly string[];
+	readonly sink: HeapWatchSink;
 }
 /** Everything the report READS. Injected so the split itself is testable. */
 export interface HeapDiagnosticDeps {
-    readonly readMemory: () => NodeJS.MemoryUsage;
-    readonly readSpaces: HeapSpaceReader;
+	readonly readMemory: () => NodeJS.MemoryUsage;
+	readonly readSpaces: HeapSpaceReader;
 }
 /**
- * The SIGUSR2 report — memory + the FULL per-space breakdown; never a heap
- * snapshot (D718) — see the note in the body.
- *
- * 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.
- */
+* The SIGUSR2 report — memory + the FULL per-space breakdown; never a heap
+* snapshot (D718) — see the note in the body.
+*
+* 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.
+*/
 export declare function emitHeapDiagnosticReport(request: HeapDiagnosticRequest, deps?: HeapDiagnosticDeps): void;