@camstack/system 1.2.146 → 1.2.148

package/dist/builtins/local-auth/local-auth.addon.mjs

@@ -1,5 +1,5 @@
 import { i as __require, o as __toESM, t as __commonJSMin } from "../../chunk-CNf5ZN-e.mjs";
-import { E as authProviderCapability, Et as BaseAddon, St as userManagementCapability, r as ApiKeyRecordSchema, v as ScopedTokenSchema, x as UserRecordSchema } from "../../dist-CG7kwIZp.mjs";
+import { E as authProviderCapability, Tt as userManagementCapability, kt as BaseAddon, r as ApiKeyRecordSchema, v as ScopedTokenSchema, x as UserRecordSchema } from "../../dist-BwD83D2f.mjs";
 import * as crypto$2 from "node:crypto";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import nodeCrypto from "crypto";
@@ -6000,7 +6000,7 @@ var require_sign = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	};
 }));
 //#endregion
-//#region src/auth/auth-manager.ts
+//#region src/auth/token-expiry.ts
 var import_jsonwebtoken = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = {
 		decode: require_decode(),
@@ -6011,6 +6011,156 @@ var import_jsonwebtoken = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin
 		TokenExpiredError: require_TokenExpiredError()
 	};
 })))());
+/**
+* Validation for the operator-configured session-JWT lifetime
+* (`auth.tokenExpiry`, System → Settings → Authentication → Token Expiry).
+*
+* WHY THIS EXISTS. The field is a free-text box that reaches `jwt.sign`'s
+* `expiresIn`. Two things go wrong without a gate in front of it:
+*
+*   1. `jsonwebtoken` THROWS on a value it cannot parse. The only caller is
+*      the login/refresh path, so one typo in a settings form turns every
+*      login into a 500 — a self-inflicted outage from a text field.
+*   2. `jsonwebtoken` hands a bare numeric STRING to `ms()`, which reads it
+*      as MILLISECONDS. An operator who types `3600` meaning "an hour" gets
+*      a token that dies in 3.6 seconds. A bare number is therefore rejected
+*      rather than interpreted — the field's own description, placeholder and
+*      default are all duration strings (`24h`, `7d`, `30d`).
+*
+* A rejection never becomes an unbounded lifetime — it resolves to
+* {@link DEFAULT_TOKEN_EXPIRY}, the single documented default — and it is
+* never silent: `parseTokenExpiry` reports the refusal in its result and
+* `logTokenExpiryRejection` renders it. The two are separate so the caller
+* owns how often it speaks; the signer re-reads on every mint.
+*/
+/**
+* The `ms`-compatible duration grammar `jsonwebtoken` accepts, MINUS the bare
+* number (see the docblock above). A unit is mandatory.
+*/
+var DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|milliseconds?|msecs?|s|secs?|seconds?|m|mins?|minutes?|h|hrs?|hours?|d|days?|w|weeks?|y|yrs?|years?)$/i;
+/** Multiplier from each accepted unit to milliseconds. */
+var UNIT_MS = {
+	ms: 1,
+	msec: 1,
+	msecs: 1,
+	millisecond: 1,
+	milliseconds: 1,
+	s: 1e3,
+	sec: 1e3,
+	secs: 1e3,
+	second: 1e3,
+	seconds: 1e3,
+	m: 6e4,
+	min: 6e4,
+	mins: 6e4,
+	minute: 6e4,
+	minutes: 6e4,
+	h: 36e5,
+	hr: 36e5,
+	hrs: 36e5,
+	hour: 36e5,
+	hours: 36e5,
+	d: 864e5,
+	day: 864e5,
+	days: 864e5,
+	w: 6048e5,
+	week: 6048e5,
+	weeks: 6048e5,
+	y: 315576e5,
+	yr: 315576e5,
+	yrs: 315576e5,
+	year: 315576e5,
+	years: 315576e5
+};
+/**
+* Shortest accepted lifetime. Below a minute the token expires inside the
+* round trip that issued it and the operator sees "logged out immediately",
+* which reads as a broken server rather than as a bad setting.
+*/
+var MIN_EXPIRY_MS = 6e4;
+/**
+* Longest accepted lifetime. A year is already far past "a device left
+* unopened for weeks"; anything longer is an infinite-lifetime token wearing
+* a duration string.
+*/
+var MAX_EXPIRY_MS = 365 * 864e5;
+/** Milliseconds for a duration string, or `null` when it is not one. */
+function durationMs(candidate) {
+	const match = DURATION_PATTERN.exec(candidate);
+	if (match === null) return null;
+	const amount = Number(match[1]);
+	const unitMs = UNIT_MS[match[2].toLowerCase()];
+	if (!Number.isFinite(amount) || unitMs === void 0) return null;
+	return amount * unitMs;
+}
+/**
+* The default, pre-parsed. Computed from {@link DEFAULT_TOKEN_EXPIRY} rather
+* than written out again — a second spelling of the same default is the defect
+* this module exists to close.
+*/
+var DEFAULT_SECONDS = (() => {
+	const ms = durationMs("30d");
+	/* c8 ignore next -- unreachable unless DEFAULT_TOKEN_EXPIRY stops being a duration */
+	if (ms === null) throw new Error(`DEFAULT_TOKEN_EXPIRY is not a duration: 30d`);
+	return ms / 1e3;
+})();
+function refuse(reason) {
+	return {
+		ok: false,
+		reason,
+		seconds: DEFAULT_SECONDS,
+		value: "30d"
+	};
+}
+/**
+* Parse a configured `auth.tokenExpiry`. An absent/blank value is not a
+* rejection — it is "operator never set it" and resolves to the default
+* without a log line.
+*/
+function parseTokenExpiry(configured) {
+	if (configured === void 0 || configured === null) return {
+		ok: true,
+		seconds: DEFAULT_SECONDS,
+		value: "30d"
+	};
+	if (typeof configured !== "string") return refuse("not-a-string");
+	const trimmed = configured.trim();
+	if (trimmed === "") return {
+		ok: true,
+		seconds: DEFAULT_SECONDS,
+		value: "30d"
+	};
+	const totalMs = durationMs(trimmed);
+	if (totalMs === null) return refuse("malformed");
+	if (totalMs < MIN_EXPIRY_MS) return refuse("too-short");
+	if (totalMs > MAX_EXPIRY_MS) return refuse("too-long");
+	return {
+		ok: true,
+		seconds: totalMs / 1e3,
+		value: trimmed
+	};
+}
+/** Human-readable tail for the rejection log line. */
+var REJECTION_DETAIL = {
+	"not-a-string": "value is not a string",
+	malformed: "not a duration string (expected e.g. 24h, 7d, 30d — a bare number is NOT seconds)",
+	"too-short": `shorter than the ${MIN_EXPIRY_MS / 1e3}s minimum`,
+	"too-long": `longer than the ${MAX_EXPIRY_MS / 864e5}d maximum`
+};
+/**
+* Report a refused `auth.tokenExpiry`. Separate from {@link parseTokenExpiry}
+* so the caller owns HOW OFTEN it speaks — the signer re-reads the setting on
+* every mint and must not turn one bad save into a line per login.
+*/
+function logTokenExpiryRejection(configured, rejection, logger) {
+	logger.warn(`auth.tokenExpiry REJECTED — ${REJECTION_DETAIL[rejection.reason]}; signing with the default 30d instead`, { meta: {
+		configured,
+		reason: rejection.reason,
+		applied: rejection.value
+	} });
+}
+//#endregion
+//#region src/auth/auth-manager.ts
 /** Minimal no-op logger for default parameter */
 var noopLogger = {
 	debug() {},
@@ -6028,6 +6178,16 @@ var AuthManager = class {
 	config;
 	jwtSecret;
 	logger;
+	/**
+	* Offending `auth.tokenExpiry` values already reported by this instance.
+	*
+	* `signToken` re-reads the setting on EVERY mint so an operator's change
+	* takes effect without a restart — which also means a bad value would log
+	* once per login and once per silent refresh from every viewer. The refusal
+	* must be visible, not repeated: the first mint after a bad save logs, the
+	* rest resolve silently to the same default until the value changes.
+	*/
+	reportedInvalidExpiries = /* @__PURE__ */ new Set();
 	constructor(config, logger = noopLogger) {
 		this.config = config;
 		this.logger = logger;
@@ -6042,8 +6202,15 @@ var AuthManager = class {
 	}
 	signToken(payload) {
 		const configured = this.config.get("auth.tokenExpiry");
-		const expiresIn = typeof configured === "string" && configured.trim() !== "" ? configured.trim() : "30d";
-		return import_jsonwebtoken.sign({ ...payload }, this.jwtSecret, { expiresIn });
+		const parsed = parseTokenExpiry(configured);
+		if (!parsed.ok) {
+			const seen = typeof configured === "string" ? configured : JSON.stringify(configured);
+			if (!this.reportedInvalidExpiries.has(seen)) {
+				this.reportedInvalidExpiries.add(seen);
+				logTokenExpiryRejection(configured, parsed, this.logger);
+			}
+		}
+		return import_jsonwebtoken.sign({ ...payload }, this.jwtSecret, { expiresIn: parsed.seconds });
 	}
 	verifyToken(token) {
 		return import_jsonwebtoken.verify(token, this.jwtSecret);
@@ -8814,6 +8981,38 @@ var TotpManager = class {
 	}
 };
 //#endregion
+//#region src/builtins/local-auth/auth-config-reader.ts
+/**
+* Every config path this reader can answer. Anything else resolves to
+* `undefined` by construction — see the module docblock.
+*/
+function createAuthConfigReader(resolved, writeAuthSection) {
+	return {
+		get(path) {
+			switch (path) {
+				case "auth.jwtSecret": return narrow(resolved.jwtSecret);
+				case "auth.adminUsername": return narrow(resolved.adminUsername);
+				case "auth.adminPassword": return narrow(resolved.adminPassword);
+				case "auth.tokenExpiry": return narrow(resolved.tokenExpiry);
+				default: return;
+			}
+		},
+		update(_section, data) {
+			if (typeof data["jwtSecret"] === "string") writeAuthSection({ jwtSecret: data["jwtSecret"] });
+		}
+	};
+}
+/**
+* The one documented type boundary in this module. `AuthConfigReader.get` is
+* the legacy `get<T>(path)` shape shared with `ConfigManager.get`, which is
+* likewise unchecked at runtime — every value returned here is a `string |
+* undefined` the caller immediately re-validates (`parseTokenExpiry`, the
+* truthiness gate on `jwtSecret`).
+*/
+function narrow(value) {
+	return value;
+}
+//#endregion
 //#region src/builtins/local-auth/auth-schema.ts
 /**
 * @durable class=config owner=local-auth
@@ -9462,19 +9661,14 @@ var LocalAuthAddon = class extends BaseAddon {
 	}
 	async onInitialize() {
 		const authSection = await this.ctx.settings?.getSection("auth") ?? {};
-		const resolvedJwtSecret = typeof authSection["jwtSecret"] === "string" ? authSection["jwtSecret"] : this.config.jwtSecret ?? "";
-		const resolvedAdminUser = typeof authSection["adminUsername"] === "string" && authSection["adminUsername"] ? authSection["adminUsername"] : this.config.adminUsername ?? "";
-		const resolvedAdminPass = typeof authSection["adminPassword"] === "string" && authSection["adminPassword"] ? authSection["adminPassword"] : this.config.adminPassword ?? "";
-		const reader = {
-			get(path) {
-				if (path === "auth.jwtSecret") return resolvedJwtSecret;
-				if (path === "auth.adminUsername") return resolvedAdminUser;
-				if (path === "auth.adminPassword") return resolvedAdminPass;
-			},
-			update: (_section, data) => {
-				if (typeof data["jwtSecret"] === "string") this.ctx.settings?.setSection("auth", { jwtSecret: data["jwtSecret"] });
-			}
-		};
+		const reader = createAuthConfigReader({
+			jwtSecret: typeof authSection["jwtSecret"] === "string" ? authSection["jwtSecret"] : this.config.jwtSecret ?? "",
+			adminUsername: typeof authSection["adminUsername"] === "string" && authSection["adminUsername"] ? authSection["adminUsername"] : this.config.adminUsername ?? "",
+			adminPassword: typeof authSection["adminPassword"] === "string" && authSection["adminPassword"] ? authSection["adminPassword"] : this.config.adminPassword ?? "",
+			tokenExpiry: typeof authSection["tokenExpiry"] === "string" && authSection["tokenExpiry"] ? authSection["tokenExpiry"] : void 0
+		}, (patch) => {
+			this.ctx.settings?.setSection("auth", patch);
+		});
 		this.authManager = new AuthManager(reader, this.ctx.logger);
 		const store = this.ctx.api?.settingsStore;
 		if (store) {

package/dist/builtins/local-network/local-network.addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-B-mBrEz9.js");
 const require_tls = require("../../tls-u8QCJCFE.js");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/builtins/local-network/local-network.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory, tt as localNetworkCapability } from "../../dist-CG7kwIZp.mjs";
+import { kt as BaseAddon, nt as localNetworkCapability, tn as EventCategory } from "../../dist-BwD83D2f.mjs";
 import { S as readLanHttpState, _ as DEFAULT_LAN_HTTP_PORT, a as writeTlsMode, i as writeExtraSans, l as reissueTlsLeaf, n as readTlsAccessStatus, o as validateUploadedTls, r as readTlsMode, s as ensureTlsCert, t as readExtraSans, y as applyLanHttp } from "../../tls-CQhPGSJm.mjs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";

package/dist/builtins/loki-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-B-mBrEz9.js");
 //#region src/builtins/loki-logging/loki-payload.ts
 /**
 * Loki rejects a label name that is not a valid Prometheus label

package/dist/builtins/loki-logging/index.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, nt as logDestinationCapability } from "../../dist-CG7kwIZp.mjs";
+import { kt as BaseAddon, rt as logDestinationCapability } from "../../dist-BwD83D2f.mjs";
 //#region src/builtins/loki-logging/loki-payload.ts
 /**
 * Loki rejects a label name that is not a valid Prometheus label

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

@@ -0,0 +1,74 @@
+/**
+ * The two knobs of the durable load series, and the arithmetic that makes them
+ * honest.
+ *
+ * ## Where they live, and why there
+ *
+ * In `native-metrics`'s OWN global settings document — the one that already
+ * exists and already carries `samplingIntervalMs`. Fields on a document, never
+ * a method per knob: `system.getLoggingSettings` / `setLoggingSettings` set
+ * that precedent and it holds here.
+ *
+ * They are NOT in the logging document, and that is a decision rather than an
+ * omission. That document is about levels and diagnostic windows; a metrics
+ * cadence and a table's retention are neither. Two documents that both claim a
+ * knob is how this repo has already shipped a switch nobody read.
+ *
+ * They are cluster-wide, not per-node. Every node emits on the same cadence or
+ * the fleet's series cannot be laid over each other, and the table is single
+ * and hub-resident, so a per-node retention would be a promise nothing could
+ * keep.
+ *
+ * ## Refused, not clamped
+ *
+ * A cadence outside 5-60 s is REFUSED. Clamping would silently store 10 when
+ * the operator typed 2 and then report 10 back as though it had been accepted
+ * — the failure mode where a knob and its readback agree on a value nobody
+ * chose. The schema advertises the bounds; this refuses anything else.
+ */
+/** The resolved, in-force configuration. */
+export interface LoadSeriesConfig {
+    readonly cadenceSec: number;
+    readonly retentionHours: number;
+    readonly maxRows: number;
+}
+/** Why a value was refused — the message an operator is shown verbatim. */
+export declare class LoadSeriesConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the configuration, REFUSING anything out of range.
+ *
+ * An ABSENT field takes its default — that is not a refusal, it is a document
+ * that has never been written. A PRESENT field outside its bounds throws.
+ */
+export declare function resolveLoadSeriesConfig(raw: {
+    readonly loadSeriesCadenceSec?: unknown;
+    readonly loadSeriesRetentionHours?: unknown;
+}): LoadSeriesConfig;
+/** What a configuration is projected to cost, from OBSERVED counts. */
+export interface LoadSeriesProjection {
+    /** Rows the retention window alone would hold. */
+    readonly intendedRows: number;
+    /** Rows actually allowed — `min(intendedRows, maxRows)`. */
+    readonly boundedRows: number;
+    readonly estimatedBytes: number;
+    /** Does the row cap bite before the retention window is full? */
+    readonly capBites: boolean;
+}
+/**
+ * Project the cost of a configuration from the numbers the cluster is actually
+ * reporting — nodes and processes OBSERVED, never a constant.
+ *
+ * This is what makes the knob honest: an operator raising retention to three
+ * days sees the row count and the megabytes BEFORE applying it, rather than
+ * discovering them afterwards. `MEASURED_BYTES_PER_ROW` is measured, not
+ * guessed — see `load-series-store.ts`.
+ */
+export declare function projectLoadSeriesCost(input: {
+    readonly config: LoadSeriesConfig;
+    /** Process rows observed across the fleet in the most recent snapshots. */
+    readonly observedProcessRows: number;
+}): LoadSeriesProjection;
+/** Human-readable one-liner for the settings form. */
+export declare function describeLoadSeriesCost(projection: LoadSeriesProjection): string;

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

@@ -0,0 +1,37 @@
+import { LoadPoint } from '@camstack/types';
+import { 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[];
+}
+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;
+}
+export interface MergedLoadSeries {
+    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.
+ */
+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.
+ */
+export declare function mergeLoadSeries(input: MergeLoadSeriesInput): MergedLoadSeries;

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

@@ -0,0 +1,232 @@
+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."
+ */
+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.
+ */
+export declare const MEASURED_BYTES_PER_ROW = 87;
+/**
+ * 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;
+/** Retention the operator asked for, in hours. Six is the shipped default. */
+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;
+/**
+ * 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;
+/** How often a prune pass may run. A bound, not a deadline. */
+export declare const PRUNE_INTERVAL_MS = 60000;
+export declare const LOAD_SERIES_COLUMNS: readonly [{
+    readonly name: "id";
+    readonly type: "INTEGER";
+    readonly primaryKey: true;
+    readonly notNull: true;
+}, {
+    readonly name: "nodeId";
+    readonly type: "TEXT";
+    readonly notNull: true;
+}, {
+    readonly name: "atMs";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "pid";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "addonId";
+    readonly type: "TEXT";
+}, {
+    readonly name: "classification";
+    readonly type: "TEXT";
+    readonly notNull: true;
+}, {
+    readonly name: "cpuDeci";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "rssMib";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "cpuMainDeci";
+    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"];
+}];
+/** 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;
+}
+/** 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;
+}
+/** One retained sample: when it was taken, and the processes in it. */
+export interface RetainedSample {
+    readonly atMs: number;
+    readonly processes: readonly RetainedProcess[];
+}
+/** Storage row → the shape a reader gets. The ONE decode. */
+export declare function rowToProcess(row: LoadSeriesRow): RetainedProcess;
+/** The shape a reader gets → the storage row. The ONE encode. */
+export declare function processToRow(nodeId: string, atMs: number, process: RetainedProcess): LoadSeriesRow;
+/** Group flat rows into samples, oldest-first. A sample is one `atMs`. */
+export declare function rowsToSamples(rows: readonly LoadSeriesRow[]): readonly RetainedSample[];
+/** The two bounds in force. */
+export interface LoadSeriesRetention {
+    readonly retentionHours: number;
+    readonly maxRows: number;
+}
+export interface LoadSeriesStoreDeps {
+    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;
+}
+/**
+ * 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;
+}
+/** Structural validation on read. A malformed row is skipped, never charted. */
+export declare function recordToRow(data: Record<string, unknown>): LoadSeriesRow | null;