@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/native-metrics/load-series-reader.d.ts

@@ -1,37 +1,63 @@
-import { LoadPoint } from '@camstack/types';
-import { RetainedSample } from './load-series-store.js';
+/**
+* The ONE reader over both retention tiers.
+*
+* The hot window is the in-memory ring; the cold one is
+* `metrics:node-load-samples`. A caller never learns which tier a point came
+* from, and that is a hard requirement rather than a nicety: a second reader
+* is how two charts start disagreeing about the same node, and it is how "the
+* ring says X, the table says Y" becomes a question nobody can answer.
+*
+* Three things happen here, in this order, and each one is load-bearing:
+*
+* 1. **Merge and dedupe on `atMs`.** The two tiers OVERLAP by construction —
+*    the ring holds the last 180 snapshots and the table holds every snapshot
+*    the ring accepted, including those same 180. A snapshot present in both
+*    must contribute exactly once. Identity is `atMs`, because one node emits
+*    one snapshot per tick and a timestamp already held IS that snapshot. The
+*    HOT copy wins on a tie: it is the payload as it arrived, while the cold
+*    one has been through the storage encode.
+* 2. **Fold per function.** The chart draws one series per addon, so the fold
+*    happens here rather than in the browser.
+* 3. **Reduce, preserving the extremes.** See `load-series-fold.ts` for why
+*    the representative of a bucket is its MAX and never its mean.
+*
+* A GAP stays a gap through all three. Emission is fixed-cadence, so a missing
+* interval means one thing — nobody reported — and nothing here fills it in.
+*/
+import { type LoadPoint } from "@camstack/types";
+import type { RetainedSample } from "./load-series-store.js";
 /** One function's assembled series, before it is shaped for the wire. */
 export interface FoldedSeries {
-    readonly key: string;
-    readonly kind: 'addon' | 'root' | 'unattributed';
-    readonly points: readonly LoadPoint[];
+	readonly key: string;
+	readonly kind: "addon" | "root" | "unattributed";
+	readonly points: readonly LoadPoint[];
 }
 export interface MergeLoadSeriesInput {
-    /** Cold samples, oldest-first. May overlap `hot` — that is expected. */
-    readonly cold: readonly RetainedSample[];
-    /** Hot samples, oldest-first. Wins over a cold sample at the same `atMs`. */
-    readonly hot: readonly RetainedSample[];
-    readonly cadenceMs: number;
-    /** Absent ⇒ no reduction. */
-    readonly maxPoints?: number;
+	/** Cold samples, oldest-first. May overlap `hot` — that is expected. */
+	readonly cold: readonly RetainedSample[];
+	/** Hot samples, oldest-first. Wins over a cold sample at the same `atMs`. */
+	readonly hot: readonly RetainedSample[];
+	readonly cadenceMs: number;
+	/** Absent ⇒ no reduction. */
+	readonly maxPoints?: number;
 }
 export interface MergedLoadSeries {
-    readonly series: readonly FoldedSeries[];
-    readonly bucketMs: number;
-    readonly retainedSamples: number;
-    readonly oldestAtMs: number | null;
+	readonly series: readonly FoldedSeries[];
+	readonly bucketMs: number;
+	readonly retainedSamples: number;
+	readonly oldestAtMs: number | null;
 }
 /**
- * Merge the two tiers into one deduped, oldest-first list of samples.
- *
- * Exported because the dedup is the property worth testing on its own: a
- * doubled point is invisible in a total and obvious only as a chart that reads
- * twice as loud as the machine.
- */
+* Merge the two tiers into one deduped, oldest-first list of samples.
+*
+* Exported because the dedup is the property worth testing on its own: a
+* doubled point is invisible in a total and obvious only as a chart that reads
+* twice as loud as the machine.
+*/
 export declare function mergeSamples(cold: readonly RetainedSample[], hot: readonly RetainedSample[]): readonly RetainedSample[];
 /**
- * Merge, fold and reduce. The whole read path in one pure function, so every
- * property that matters — dedup, peak survival, an empty bucket staying empty
- * — is testable without a database or a ring.
- */
+* Merge, fold and reduce. The whole read path in one pure function, so every
+* property that matters — dedup, peak survival, an empty bucket staying empty
+* — is testable without a database or a ring.
+*/
 export declare function mergeLoadSeries(input: MergeLoadSeriesInput): MergedLoadSeries;

package/dist/builtins/native-metrics/load-series-store.d.ts

@@ -1,31 +1,92 @@
-import { IScopedLogger, SettingsStoreClient } from '@camstack/types';
 /**
- * @durable class=audit owner=metrics-native
- *   write="one row per process per sample, appended in ONE transaction per
- *     sample (`settingsStore.insertMany`) by the HUB's `native-metrics`, off its
- *     subscription to `metrics.node-processes-snapshot`. Emission is
- *     fixed-cadence, so the write rate is deterministic: nodes x processes /
- *     cadence, 7.6 rows/s on the live fleet at the 10 s default. Only a sample
- *     the in-memory ring ACCEPTED is written, which is what makes the append
- *     idempotent without a unique key."
- *   retention="TWO bounds, swept together at most once a minute. By AGE, the
- *     operator's `loadSeriesRetentionHours` (default 6, the intention); by ROWS,
- *     DEFAULT_MAX_ROWS (the guarantee, which bites regardless of the age knob).
- *     Both prune oldest-first through a bounded page — never a full scan — and
- *     the row cap logs when it bites. Losing the table loses the cold window
- *     only: the ring keeps serving the last hour and the charts keep drawing."
- */
+* Durable retention for the per-node load series — the COLD window behind the
+* in-memory ring's hot one.
+*
+* ## One table, and what that decides
+*
+* One row per process per sample, in `metrics:node-load-samples`, declared the
+* way every other typed collection in this repo is declared: explicit columns,
+* explicit indexes, read by `where`/`whereBetween`/`orderBy`/`limit`. There is
+* no dimension table, no per-addon pre-aggregate and no bucket tier. The
+* consequence is that the row count is DETERMINISTIC and large, and the honest
+* thing to do with a large number is to publish it rather than to design it
+* away — see `docs/architecture/load-ledger.md` § "2026-08-27 (night) — the load
+* series reaches disk, and what it costs".
+*
+* ## Measured cost, not estimated
+*
+* `scripts/measure-load-series-cost.mts` writes the real payload shape through
+* the real `SqliteSettingsBackend` and the real `declareCollection` DDL, then
+* reads `page_count × page_size` off the resulting file. The answer is
+* **{@link MEASURED_BYTES_PER_ROW} bytes per row**, flat from 164 k rows to
+* 3.9 M rows — table plus its one index, after a truncating WAL checkpoint.
+*
+* That number is why the columns look the way they do. Four decisions, each
+* paid for in bytes measured on the same harness:
+*
+* | shape | B/row |
+* | --- | --- |
+* | naive: `TEXT` id, 2 indexes, every `NodeProcess` field | 196.0 |
+* | one index, drop `threadCount` + `uptimeSec` | 172.8 |
+* | + base36 in the composite id | 159.6 |
+* | + CPU as integer tenths, RSS as integer MiB | 140.3 |
+* | + `INTEGER` rowid-alias key (this file) | **86.9** |
+*
+* - **`command` is not stored.** It is the fattest field in a `NodeProcess` and
+*   it is the same ~100-character string on every runner — the runner id
+*   travels in the environment, not in argv, so `ps` reports one identical
+*   command line for all of them. `addonId` is the short identifier that
+*   already exists, and nothing that reads this series reads `command`.
+* - **CPU is stored as integer tenths.** Losslessly: `ps pcpu` is rounded to
+*   one decimal by `runPs`, and the thread sampler rounds to one decimal too
+*   (`Math.round(x * 1000) / 10`). A SQLite `REAL` is 8 bytes always; the same
+*   value as an integer varint is 1-2.
+* - **RSS is stored in whole MiB.** A byte-exact residency on a value in the
+*   hundreds of megabytes is precision no chart can draw, and it costs 3 bytes
+*   a row.
+* - **The key is an `INTEGER` rowid alias.** A composite `TEXT` key cost ~40
+*   B/row — the string in the row plus its own B-tree — for an idempotence
+*   this table gets for free somewhere better: {@link NodeLoadRing.record}
+*   already refuses a sample at or before the newest it holds, and only an
+*   ACCEPTED sample is written here. The gate is one monotonic comparison in
+*   memory instead of a unique index on two million rows.
+*
+* ## Retention is an intention; the row cap is the guarantee
+*
+* {@link LoadSeriesRetention.retentionHours} is what the operator asked to
+* keep. {@link DEFAULT_MAX_ROWS} is what the table is allowed to become. They
+* are different promises on purpose: an operator who raises retention to three
+* days must not be able to take this table to two million rows with nothing
+* stopping it. When the cap bites, the OLDEST rows go and a line says so.
+*/
+import type { IScopedLogger, SettingsStoreClient } from "@camstack/types";
+/**
+* @durable class=audit owner=metrics-native
+*   write="one row per process per sample, appended in ONE transaction per
+*     sample (`settingsStore.insertMany`) by the HUB's `native-metrics`, off its
+*     subscription to `metrics.node-processes-snapshot`. Emission is
+*     fixed-cadence, so the write rate is deterministic: nodes x processes /
+*     cadence, 7.6 rows/s on the live fleet at the 10 s default. Only a sample
+*     the in-memory ring ACCEPTED is written, which is what makes the append
+*     idempotent without a unique key."
+*   retention="TWO bounds, swept together at most once a minute. By AGE, the
+*     operator's `loadSeriesRetentionHours` (default 6, the intention); by ROWS,
+*     DEFAULT_MAX_ROWS (the guarantee, which bites regardless of the age knob).
+*     Both prune oldest-first through a bounded page — never a full scan — and
+*     the row cap logs when it bites. Losing the table loses the cold window
+*     only: the ring keeps serving the last hour and the charts keep drawing."
+*/
 export declare const LOAD_SERIES_COLLECTION = "metrics:node-load-samples";
 /**
- * Bytes one stored row costs on disk, MEASURED — table plus index, after a
- * truncating checkpoint. Used to project the cost of a configuration for the
- * operator BEFORE they apply it, so the knob is honest.
- */
+* Bytes one stored row costs on disk, MEASURED — table plus index, after a
+* truncating checkpoint. Used to project the cost of a configuration for the
+* operator BEFORE they apply it, so the knob is honest.
+*/
 export declare const MEASURED_BYTES_PER_ROW = 87;
 /**
- * Sampling cadence bounds, in seconds. Outside this range a cadence is
- * REFUSED — see {@link resolveLoadSeriesConfig}.
- */
+* Sampling cadence bounds, in seconds. Outside this range a cadence is
+* REFUSED — see {@link resolveLoadSeriesConfig}.
+*/
 export declare const MIN_CADENCE_SEC = 5;
 export declare const MAX_CADENCE_SEC = 60;
 export declare const DEFAULT_CADENCE_SEC = 10;
@@ -34,109 +95,109 @@ export declare const DEFAULT_RETENTION_HOURS = 6;
 export declare const MIN_RETENTION_HOURS = 1;
 export declare const MAX_RETENTION_HOURS = 72;
 /**
- * Hard ceiling on the table, in ROWS.
- *
- * The guarantee behind the retention knob. Sized against the shipped default
- * and against the worst configuration the knob can express:
- *
- * | cadence | retention | rows (3 nodes, 76 processes) |
- * | --- | --- | --- |
- * | 10 s | 6 h (default) | 164 160 |
- * | 5 s | 6 h | 328 320 |
- * | 5 s | 72 h | 3 939 840 — capped here |
- *
- * 500 000 rows x the measured 87 B = **41.5 MiB**, roughly 3x what the shipped
- * default needs and far below the 2 M rows a three-day retention would reach.
- * It is deliberately NOT a knob: the point of a guarantee is that it is not
- * subject to the same hand that raised the intention. This is the discipline
- * the in-memory ring already adopted (`DEFAULT_MAX_TOTAL_PROCESS_ROWS`) and
- * the one the RTP pre-roll rings still lack — a maximum per instance and no
- * budget at all for the whole, which reached 898 MB across 47 rings
- * (`docs/architecture/load-ledger.md` #5).
- */
-export declare const DEFAULT_MAX_ROWS = 500000;
+* Hard ceiling on the table, in ROWS.
+*
+* The guarantee behind the retention knob. Sized against the shipped default
+* and against the worst configuration the knob can express:
+*
+* | cadence | retention | rows (3 nodes, 76 processes) |
+* | --- | --- | --- |
+* | 10 s | 6 h (default) | 164 160 |
+* | 5 s | 6 h | 328 320 |
+* | 5 s | 72 h | 3 939 840 — capped here |
+*
+* 500 000 rows x the measured 87 B = **41.5 MiB**, roughly 3x what the shipped
+* default needs and far below the 2 M rows a three-day retention would reach.
+* It is deliberately NOT a knob: the point of a guarantee is that it is not
+* subject to the same hand that raised the intention. This is the discipline
+* the in-memory ring already adopted (`DEFAULT_MAX_TOTAL_PROCESS_ROWS`) and
+* the one the RTP pre-roll rings still lack — a maximum per instance and no
+* budget at all for the whole, which reached 898 MB across 47 rings
+* (`docs/architecture/load-ledger.md` #5).
+*/
+export declare const DEFAULT_MAX_ROWS = 5e5;
 /**
- * Rows a single prune pass may remove.
- *
- * The prune is BOUNDED, never a full scan. It reads at most this many keys
- * oldest-first through `idx_load_samples_node_at`, takes the last one's `atMs`
- * as the effective cutoff and issues ONE `deleteWhere` up to it. A backlog
- * larger than a page is worked off across passes rather than in one stall —
- * which is the defect corrected in the recorder the same week, where
- * `accountingForLocations` visited 6.7 M rows twice a minute.
- */
-export declare const PRUNE_PAGE_ROWS = 20000;
+* Rows a single prune pass may remove.
+*
+* The prune is BOUNDED, never a full scan. It reads at most this many keys
+* oldest-first through `idx_load_samples_node_at`, takes the last one's `atMs`
+* as the effective cutoff and issues ONE `deleteWhere` up to it. A backlog
+* larger than a page is worked off across passes rather than in one stall —
+* which is the defect corrected in the recorder the same week, where
+* `accountingForLocations` visited 6.7 M rows twice a minute.
+*/
+export declare const PRUNE_PAGE_ROWS = 2e4;
 /** How often a prune pass may run. A bound, not a deadline. */
-export declare const PRUNE_INTERVAL_MS = 60000;
+export declare const PRUNE_INTERVAL_MS = 6e4;
 export declare const LOAD_SERIES_COLUMNS: readonly [{
-    readonly name: "id";
-    readonly type: "INTEGER";
-    readonly primaryKey: true;
-    readonly notNull: true;
+	readonly name: "id";
+	readonly type: "INTEGER";
+	readonly primaryKey: true;
+	readonly notNull: true;
 }, {
-    readonly name: "nodeId";
-    readonly type: "TEXT";
-    readonly notNull: true;
+	readonly name: "nodeId";
+	readonly type: "TEXT";
+	readonly notNull: true;
 }, {
-    readonly name: "atMs";
-    readonly type: "INTEGER";
-    readonly notNull: true;
+	readonly name: "atMs";
+	readonly type: "INTEGER";
+	readonly notNull: true;
 }, {
-    readonly name: "pid";
-    readonly type: "INTEGER";
-    readonly notNull: true;
+	readonly name: "pid";
+	readonly type: "INTEGER";
+	readonly notNull: true;
 }, {
-    readonly name: "addonId";
-    readonly type: "TEXT";
+	readonly name: "addonId";
+	readonly type: "TEXT";
 }, {
-    readonly name: "classification";
-    readonly type: "TEXT";
-    readonly notNull: true;
+	readonly name: "classification";
+	readonly type: "TEXT";
+	readonly notNull: true;
 }, {
-    readonly name: "cpuDeci";
-    readonly type: "INTEGER";
-    readonly notNull: true;
+	readonly name: "cpuDeci";
+	readonly type: "INTEGER";
+	readonly notNull: true;
 }, {
-    readonly name: "rssMib";
-    readonly type: "INTEGER";
-    readonly notNull: true;
+	readonly name: "rssMib";
+	readonly type: "INTEGER";
+	readonly notNull: true;
 }, {
-    readonly name: "cpuMainDeci";
-    readonly type: "INTEGER";
+	readonly name: "cpuMainDeci";
+	readonly type: "INTEGER";
 }, {
-    readonly name: "cpuGcDeci";
-    readonly type: "INTEGER";
+	readonly name: "cpuGcDeci";
+	readonly type: "INTEGER";
 }];
 export declare const LOAD_SERIES_INDEXES: readonly [{
-    readonly name: "idx_load_samples_node_at";
-    readonly columns: readonly ["nodeId", "atMs"];
+	readonly name: "idx_load_samples_node_at";
+	readonly columns: readonly ["nodeId", "atMs"];
 }];
 /** One stored process row, in the units the table stores them in. */
 export interface LoadSeriesRow {
-    readonly nodeId: string;
-    readonly atMs: number;
-    readonly pid: number;
-    readonly addonId: string | null;
-    readonly classification: string;
-    readonly cpuDeci: number;
-    readonly rssMib: number;
-    readonly cpuMainDeci: number | null;
-    readonly cpuGcDeci: number | null;
+	readonly nodeId: string;
+	readonly atMs: number;
+	readonly pid: number;
+	readonly addonId: string | null;
+	readonly classification: string;
+	readonly cpuDeci: number;
+	readonly rssMib: number;
+	readonly cpuMainDeci: number | null;
+	readonly cpuGcDeci: number | null;
 }
 /** The process shape both tiers hand back — the series' own row, not `ps`'s. */
 export interface RetainedProcess {
-    readonly pid: number;
-    readonly addonId: string | null;
-    readonly classification: string;
-    readonly cpuPercent: number;
-    readonly memoryRssBytes: number;
-    readonly cpuMainPercent: number | null;
-    readonly cpuGcPercent: number | null;
+	readonly pid: number;
+	readonly addonId: string | null;
+	readonly classification: string;
+	readonly cpuPercent: number;
+	readonly memoryRssBytes: number;
+	readonly cpuMainPercent: number | null;
+	readonly cpuGcPercent: number | null;
 }
 /** One retained sample: when it was taken, and the processes in it. */
 export interface RetainedSample {
-    readonly atMs: number;
-    readonly processes: readonly RetainedProcess[];
+	readonly atMs: number;
+	readonly processes: readonly RetainedProcess[];
 }
 /** Storage row → the shape a reader gets. The ONE decode. */
 export declare function rowToProcess(row: LoadSeriesRow): RetainedProcess;
@@ -146,87 +207,87 @@ export declare function processToRow(nodeId: string, atMs: number, process: Reta
 export declare function rowsToSamples(rows: readonly LoadSeriesRow[]): readonly RetainedSample[];
 /** The two bounds in force. */
 export interface LoadSeriesRetention {
-    readonly retentionHours: number;
-    readonly maxRows: number;
+	readonly retentionHours: number;
+	readonly maxRows: number;
 }
 export interface LoadSeriesStoreDeps {
-    readonly store: SettingsStoreClient;
-    readonly logger: IScopedLogger;
-    readonly now?: () => number;
-    readonly prunePageRows?: number;
-    readonly pruneIntervalMs?: number;
+	readonly store: SettingsStoreClient;
+	readonly logger: IScopedLogger;
+	readonly now?: () => number;
+	readonly prunePageRows?: number;
+	readonly pruneIntervalMs?: number;
 }
 /** What one prune pass did. Returned so a test can assert the bound held. */
 export interface PruneOutcome {
-    readonly deletedByAge: number;
-    readonly deletedByCap: number;
-    /** Rows read to find the cutoffs — the number that must stay bounded. */
-    readonly rowsExamined: number;
-    readonly capBit: boolean;
+	readonly deletedByAge: number;
+	readonly deletedByCap: number;
+	/** Rows read to find the cutoffs — the number that must stay bounded. */
+	readonly rowsExamined: number;
+	readonly capBit: boolean;
 }
 /**
- * The cold tier. Append-only, bounded, and never the authority on anything the
- * hot ring can answer.
- *
- * Every method is best-effort and says so in the log rather than throwing at
- * the emitter: a storage hiccup must cost a gap in a chart, never a dropped
- * snapshot on the bus.
- */
+* The cold tier. Append-only, bounded, and never the authority on anything the
+* hot ring can answer.
+*
+* Every method is best-effort and says so in the log rather than throwing at
+* the emitter: a storage hiccup must cost a gap in a chart, never a dropped
+* snapshot on the bus.
+*/
 export declare class LoadSeriesStore {
-    private declared;
-    private lastPruneAtMs;
-    private readonly store;
-    private readonly logger;
-    private readonly nowFn;
-    private readonly prunePageRows;
-    private readonly pruneIntervalMs;
-    constructor(deps: LoadSeriesStoreDeps);
-    /** Idempotently declare the collection. `false` when the store refused. */
-    declare(): Promise<boolean>;
-    /**
-     * Append ONE sample — every process row of it — in ONE transaction.
-     *
-     * Never a write per row. `insertMany` exists for exactly this: at the 10 s
-     * default the fleet produces 7.6 rows/s, and 7.6 separate commits per second
-     * on the connection that also serves every cluster-wide configuration read
-     * is a constant load nobody asked for.
-     */
-    append(nodeId: string, atMs: number, processes: readonly RetainedProcess[]): Promise<number>;
-    /**
-     * Read one node's cold samples, oldest-first.
-     *
-     * `sinceMs` is EXCLUSIVE, matching the ring, so a caller passing the newest
-     * timestamp it holds gets only what it is missing. `limitRows` bounds the
-     * read in ROWS (not samples) because rows are what the query costs.
-     */
-    read(nodeId: string, sinceMs: number, limitRows: number): Promise<readonly RetainedSample[]>;
-    /**
-     * Enforce BOTH bounds, oldest-first, through a bounded page each.
-     *
-     * Rate-limited to {@link pruneIntervalMs}: a bound is not a deadline, and the
-     * append path must not pay a sweep on every sample.
-     */
-    prune(nodeIds: readonly string[], retention: LoadSeriesRetention, force?: boolean): Promise<PruneOutcome | null>;
-    /** Total rows, or `null` when the store could not answer. */
-    count(): Promise<number | null>;
-    /**
-     * Delete this node's rows older than `cutoff`, at most one page's worth.
-     *
-     * The page is the whole point. `deleteWhere({ atMs: [0, cutoff] })` on its
-     * own is one statement but an UNBOUNDED one — a first pass after a retention
-     * change would delete millions of rows inside a single stalling transaction.
-     * So the page is read first (keys only, ordered by the index), its last
-     * `atMs` becomes the EFFECTIVE cutoff, and the delete is bounded by it.
-     */
-    private pruneNodeToCutoff;
-    /**
-     * Drop the oldest rows across the known nodes until `excess` is covered.
-     *
-     * Same bounded-page technique, walked per node so the one index serves it.
-     * The node holding the oldest rows pays first, which is also the node
-     * producing the pressure when a runaway process count is the cause.
-     */
-    private pruneOldestRows;
+	private declared;
+	private lastPruneAtMs;
+	private readonly store;
+	private readonly logger;
+	private readonly nowFn;
+	private readonly prunePageRows;
+	private readonly pruneIntervalMs;
+	constructor(deps: LoadSeriesStoreDeps);
+	/** Idempotently declare the collection. `false` when the store refused. */
+	declare(): Promise<boolean>;
+	/**
+	* Append ONE sample — every process row of it — in ONE transaction.
+	*
+	* Never a write per row. `insertMany` exists for exactly this: at the 10 s
+	* default the fleet produces 7.6 rows/s, and 7.6 separate commits per second
+	* on the connection that also serves every cluster-wide configuration read
+	* is a constant load nobody asked for.
+	*/
+	append(nodeId: string, atMs: number, processes: readonly RetainedProcess[]): Promise<number>;
+	/**
+	* Read one node's cold samples, oldest-first.
+	*
+	* `sinceMs` is EXCLUSIVE, matching the ring, so a caller passing the newest
+	* timestamp it holds gets only what it is missing. `limitRows` bounds the
+	* read in ROWS (not samples) because rows are what the query costs.
+	*/
+	read(nodeId: string, sinceMs: number, limitRows: number): Promise<readonly RetainedSample[]>;
+	/**
+	* Enforce BOTH bounds, oldest-first, through a bounded page each.
+	*
+	* Rate-limited to {@link pruneIntervalMs}: a bound is not a deadline, and the
+	* append path must not pay a sweep on every sample.
+	*/
+	prune(nodeIds: readonly string[], retention: LoadSeriesRetention, force?: boolean): Promise<PruneOutcome | null>;
+	/** Total rows, or `null` when the store could not answer. */
+	count(): Promise<number | null>;
+	/**
+	* Delete this node's rows older than `cutoff`, at most one page's worth.
+	*
+	* The page is the whole point. `deleteWhere({ atMs: [0, cutoff] })` on its
+	* own is one statement but an UNBOUNDED one — a first pass after a retention
+	* change would delete millions of rows inside a single stalling transaction.
+	* So the page is read first (keys only, ordered by the index), its last
+	* `atMs` becomes the EFFECTIVE cutoff, and the delete is bounded by it.
+	*/
+	private pruneNodeToCutoff;
+	/**
+	* Drop the oldest rows across the known nodes until `excess` is covered.
+	*
+	* Same bounded-page technique, walked per node so the one index serves it.
+	* The node holding the oldest rows pays first, which is also the node
+	* producing the pressure when a runaway process count is the cause.
+	*/
+	private pruneOldestRows;
 }
 /** Structural validation on read. A malformed row is skipped, never charted. */
 export declare function recordToRow(data: Record<string, unknown>): LoadSeriesRow | null;

package/dist/builtins/native-metrics/native-metrics-provider.d.ts

@@ -1,48 +1,48 @@
-import { DiskSpaceInfo, MemoryInfo, MetricsGpuInfo, PidResourceStats, SystemResourceSnapshot } from '@camstack/types';
+import type { DiskSpaceInfo, MemoryInfo, MetricsGpuInfo, PidResourceStats, SystemResourceSnapshot } from "@camstack/types";
 interface SamplingDiagnostics {
-    warn(message: string, meta?: Record<string, unknown>): void;
+	warn(message: string, meta?: Record<string, unknown>): void;
 }
 export declare class NativeMetricsProvider {
-    readonly id = "native";
-    private cachedSnapshot;
-    private samplingTimer;
-    private macMemTimer;
-    private prevCpu;
-    private diagnostics;
-    private consecutiveSampleErrors;
-    constructor();
-    /**
-     * Optional diagnostics sink for sampling errors. The first failure and
-     * every Nth failure thereafter are reported so a permanently-broken
-     * collector doesn't spam logs but is still observable.
-     */
-    setDiagnostics(diag: SamplingDiagnostics): void;
-    startSampling(intervalMs: number): void;
-    private reportSampleError;
-    stopSampling(): void;
-    collectSnapshot(): Promise<SystemResourceSnapshot>;
-    getCached(): Promise<SystemResourceSnapshot | null>;
-    getCurrent(): Promise<{
-        cpuPercent: number;
-        memoryPercent: number;
-        memoryUsedMB: number;
-        memoryTotalMB: number;
-        diskPercent?: number;
-        temperature?: number;
-        gpuPercent?: number;
-        gpuMemoryPercent?: number;
-    }>;
-    getDiskSpace(input: {
-        dirPath: string;
-    }): Promise<DiskSpaceInfo>;
-    getGpuInfo(): Promise<MetricsGpuInfo | null>;
-    getCpuTemperature(): Promise<number | null>;
-    getProcessStats(input: {
-        pids: number[];
-    }): Promise<PidResourceStats[]>;
-    private sampleCpu;
-    /** Cached macOS memory (set by sampleMacMemory timer). */
-    _cachedMacMem: MemoryInfo | null;
-    private getMemoryInfo;
+	readonly id = "native";
+	private cachedSnapshot;
+	private samplingTimer;
+	private macMemTimer;
+	private prevCpu;
+	private diagnostics;
+	private consecutiveSampleErrors;
+	constructor();
+	/**
+	* Optional diagnostics sink for sampling errors. The first failure and
+	* every Nth failure thereafter are reported so a permanently-broken
+	* collector doesn't spam logs but is still observable.
+	*/
+	setDiagnostics(diag: SamplingDiagnostics): void;
+	startSampling(intervalMs: number): void;
+	private reportSampleError;
+	stopSampling(): void;
+	collectSnapshot(): Promise<SystemResourceSnapshot>;
+	getCached(): Promise<SystemResourceSnapshot | null>;
+	getCurrent(): Promise<{
+		cpuPercent: number;
+		memoryPercent: number;
+		memoryUsedMB: number;
+		memoryTotalMB: number;
+		diskPercent?: number;
+		temperature?: number;
+		gpuPercent?: number;
+		gpuMemoryPercent?: number;
+	}>;
+	getDiskSpace(input: {
+		dirPath: string;
+	}): Promise<DiskSpaceInfo>;
+	getGpuInfo(): Promise<MetricsGpuInfo | null>;
+	getCpuTemperature(): Promise<number | null>;
+	getProcessStats(input: {
+		pids: number[];
+	}): Promise<PidResourceStats[]>;
+	private sampleCpu;
+	/** Cached macOS memory (set by sampleMacMemory timer). */
+	_cachedMacMem: MemoryInfo | null;
+	private getMemoryInfo;
 }
 export {};