@camstack/system 1.2.146 → 1.2.147

package/dist/builtins/native-metrics/native-metrics.addon.mjs

@@ -1,4 +1,5 @@
-import { Et as BaseAddon, Qt as EventCategory, at as metricsProviderCapability, zt as createEvent } from "../../dist-CG7kwIZp.mjs";
+import { Ht as createEvent, Ot as errMsg, ft as reducePoints, kt as BaseAddon, ot as metricsProviderCapability, pt as resolveBucketMs, q as foldSnapshotByFunction, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
+import { readFile, readdir } from "node:fs/promises";
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import * as os from "node:os";
@@ -458,9 +459,933 @@ function execAsync(cmd, args, timeoutMs = 5e3) {
 		});
 	});
 }
+/**
+* One node's fixed-capacity circular buffer of samples.
+*
+* Mirrors {@link LogRingBuffer}: write at `head`, wrap, and once full every
+* accepted sample evicts the oldest. `rows` is carried alongside so the fleet
+* budget never has to walk the samples to know what a partition costs.
+*/
+var LoadPartition = class {
+	capacity;
+	slots;
+	head = 0;
+	count = 0;
+	rows = 0;
+	/** Newest retained sample's timestamp — the monotonic gate for `push`. */
+	newestAtMs = null;
+	constructor(capacity) {
+		this.capacity = capacity;
+		this.slots = Array.from({ length: capacity });
+	}
+	/**
+	* Accept a sample.
+	*
+	* A sample at or before the newest one already held is REFUSED. The bus drops
+	* a node's own broadcast echo, but a cross-node redelivery or a replayed
+	* subscription must not be able to double a point — and idempotence here is
+	* what lets every reader above treat the series as a set.
+	*
+	* `accepted` is reported separately from `rowDelta` on purpose: a full ring
+	* that evicts a sample of the same size has a delta of zero and is not a
+	* refusal, and conflating the two would silently stop advancing the write
+	* ordinal on a steady-state cluster.
+	*/
+	push(sample) {
+		if (this.newestAtMs !== null && sample.atMs <= this.newestAtMs) return {
+			accepted: false,
+			rowDelta: 0
+		};
+		const evicted = this.count === this.capacity ? this.slots[this.head]?.processes.length ?? 0 : 0;
+		this.slots[this.head] = sample;
+		this.head = (this.head + 1) % this.capacity;
+		if (this.count < this.capacity) this.count++;
+		this.newestAtMs = sample.atMs;
+		const rowDelta = sample.processes.length - evicted;
+		this.rows += rowDelta;
+		return {
+			accepted: true,
+			rowDelta
+		};
+	}
+	/** Drop the oldest sample. Returns the rows reclaimed (0 when empty). */
+	dropOldest() {
+		if (this.count === 0) return 0;
+		const index = (this.head - this.count + this.capacity) % this.capacity;
+		const victim = this.slots[index];
+		this.slots[index] = void 0;
+		this.count--;
+		const reclaimed = victim?.processes.length ?? 0;
+		this.rows -= reclaimed;
+		if (this.count === 0) this.newestAtMs = null;
+		return reclaimed;
+	}
+	/** Oldest-first, optionally only what is strictly newer than `sinceMs`. */
+	list(sinceMs) {
+		const out = [];
+		for (let i = 0; i < this.count; i++) {
+			const index = (this.head - this.count + i + this.capacity) % this.capacity;
+			const sample = this.slots[index];
+			if (sample === void 0) continue;
+			if (sinceMs !== void 0 && sample.atMs <= sinceMs) continue;
+			out.push(sample);
+		}
+		return out;
+	}
+	size() {
+		return this.count;
+	}
+	rowCount() {
+		return this.rows;
+	}
+	oldestAtMs() {
+		if (this.count === 0) return null;
+		const index = (this.head - this.count + this.capacity) % this.capacity;
+		return this.slots[index]?.atMs ?? null;
+	}
+	lastWriteAtMs() {
+		return this.newestAtMs;
+	}
+};
+/**
+* The partitioned ring: one {@link LoadPartition} per node id.
+*
+* Three bounds, doing three different jobs — the same division as the log
+* buffer, for the same reason:
+*
+* - **`samplesPerNode`** is HARD and per partition. It is what the operator
+*   asked for (an hour) and it can never be exceeded.
+* - **`maxTotalProcessRows`** is the FLEET budget, and it is denominated in the
+*   thing memory is proportional to. When it bites, the oldest sample of the
+*   HEAVIEST partition is dropped — the node creating the pressure is the node
+*   that pays, and a quiet node keeps its full hour. The node just written to is
+*   NOT protected here: if it is the heaviest, it is the culprit.
+* - **`maxNodes`** is the backstop against an unbounded key space, and it drops
+*   whole partitions least-recently-written first, never the one being written.
+*
+* Plus {@link DEFAULT_NODE_IDLE_EVICTION_MS}, which is what stops a node that
+* simply stopped emitting from living in memory forever.
+*/
+var NodeLoadRing = class {
+	partitions = /* @__PURE__ */ new Map();
+	/**
+	* Node id → write ordinal of its last accepted sample. A monotonic counter,
+	* not a clock: partition eviction must follow the order writes actually
+	* happened, and node clocks disagree.
+	*/
+	lastWriteSeq = /* @__PURE__ */ new Map();
+	writeSeq = 0;
+	totalRows = 0;
+	samplesPerNode;
+	maxTotalProcessRows;
+	maxNodes;
+	idleEvictionMs;
+	now;
+	constructor(options = {}) {
+		this.samplesPerNode = options.samplesPerNode ?? 180;
+		this.maxTotalProcessRows = options.maxTotalProcessRows ?? 32e3;
+		this.maxNodes = options.maxNodes ?? 16;
+		this.idleEvictionMs = options.idleEvictionMs ?? 36e5;
+		this.now = options.now ?? Date.now;
+	}
+	/**
+	* Retain one snapshot. `processes` is stored by reference — the payload is
+	* already an immutable arrival off the bus, and copying it would double the
+	* measured cost for nothing.
+	*
+	* Returns whether the sample was ACCEPTED — that is, whether it was new
+	* rather than a replay of a timestamp this node has already delivered.
+	*
+	* The return value is not diagnostics. It is the idempotence gate the
+	* DURABLE tier rides on (`load-series-store.ts`): only an accepted sample is
+	* appended to the table, which is what lets that table carry an `INTEGER`
+	* rowid key instead of a composite unique index over two million rows. The
+	* gate is one monotonic comparison in memory; the index it replaces was
+	* measured at ~40 bytes per row.
+	*/
+	record(nodeId, atMs, processes) {
+		if (nodeId.length === 0) return false;
+		this.sweepIdle();
+		let partition = this.partitions.get(nodeId);
+		if (partition === void 0) {
+			partition = new LoadPartition(this.samplesPerNode);
+			this.partitions.set(nodeId, partition);
+		}
+		const outcome = partition.push({
+			atMs,
+			processes
+		});
+		if (!outcome.accepted) {
+			if (partition.size() === 0) this.partitions.delete(nodeId);
+			return false;
+		}
+		this.totalRows += outcome.rowDelta;
+		this.lastWriteSeq.set(nodeId, ++this.writeSeq);
+		if (this.partitions.size > this.maxNodes) this.evictPartitions(this.partitions.size - this.maxNodes, nodeId);
+		this.enforceRowBudget();
+		return true;
+	}
+	/**
+	* Read one node's retained series, oldest-first.
+	*
+	* `sinceMs` is EXCLUSIVE: a caller passes the newest timestamp it already
+	* holds and gets back only what it is missing. That is the whole contract
+	* that lets the admin UI seed from here and then continue live without
+	* doubling a point it already drew.
+	*
+	* A node nobody has recorded answers with an empty series, not an error —
+	* unknown is the truth about a node that has not reported.
+	*/
+	read(nodeId, sinceMs) {
+		this.sweepIdle();
+		const partition = this.partitions.get(nodeId);
+		if (partition === void 0) return {
+			nodeId,
+			samples: [],
+			retainedSamples: 0,
+			oldestAtMs: null,
+			capacity: this.samplesPerNode
+		};
+		return {
+			nodeId,
+			samples: partition.list(sinceMs),
+			retainedSamples: partition.size(),
+			oldestAtMs: partition.oldestAtMs(),
+			capacity: this.samplesPerNode
+		};
+	}
+	/** Node ids with a live partition. Observability for the fleet bound. */
+	nodeIds() {
+		return [...this.partitions.keys()];
+	}
+	/** Process rows retained across every partition — the number that IS memory. */
+	rowCount() {
+		return this.totalRows;
+	}
+	/** Samples retained across every partition. */
+	sampleCount() {
+		let total = 0;
+		for (const partition of this.partitions.values()) total += partition.size();
+		return total;
+	}
+	/**
+	* Drop partitions whose newest sample is older than the retention window.
+	*
+	* Lazy, on write and on read — never a timer. A timer would be a new
+	* periodic cost in a subsystem whose entire premise is that it adds none,
+	* and a ring that nobody writes to and nobody reads is not growing either.
+	*/
+	sweepIdle() {
+		const cutoff = this.now() - this.idleEvictionMs;
+		for (const [nodeId, partition] of [...this.partitions.entries()]) {
+			const lastWrite = partition.lastWriteAtMs();
+			if (lastWrite !== null && lastWrite > cutoff) continue;
+			this.dropPartition(nodeId);
+		}
+	}
+	/**
+	* Bring the fleet back under the row budget by dropping the OLDEST sample of
+	* the HEAVIEST partition, repeatedly.
+	*
+	* Terminates: every iteration removes one sample from a non-empty partition,
+	* and the population of samples is finite and strictly decreasing.
+	*/
+	enforceRowBudget() {
+		while (this.totalRows > this.maxTotalProcessRows) {
+			const victim = this.heaviestPartition();
+			if (victim === null) return;
+			const [nodeId, partition] = victim;
+			this.totalRows -= partition.dropOldest();
+			if (partition.size() === 0) this.dropPartition(nodeId);
+		}
+	}
+	heaviestPartition() {
+		let best = null;
+		for (const entry of this.partitions.entries()) {
+			if (entry[1].size() === 0) continue;
+			if (best === null || entry[1].rowCount() > best[1].rowCount()) best = entry;
+		}
+		return best;
+	}
+	/** Drop `count` whole partitions, least-recently-written first. */
+	evictPartitions(count, protectedNodeId) {
+		const order = [...this.partitions.keys()].filter((nodeId) => nodeId !== protectedNodeId).toSorted((a, b) => (this.lastWriteSeq.get(a) ?? 0) - (this.lastWriteSeq.get(b) ?? 0));
+		let remaining = count;
+		for (const nodeId of order) {
+			if (remaining <= 0) return;
+			this.dropPartition(nodeId);
+			remaining -= 1;
+		}
+	}
+	/** Remove a partition and everything that indexes it. */
+	dropPartition(nodeId) {
+		const partition = this.partitions.get(nodeId);
+		if (partition === void 0) return;
+		this.totalRows -= partition.rowCount();
+		this.partitions.delete(nodeId);
+		this.lastWriteSeq.delete(nodeId);
+	}
+};
 //#endregion
-//#region src/builtins/native-metrics/native-metrics.addon.ts
-var execFileAsync = promisify(execFile);
+//#region src/builtins/native-metrics/load-series-store.ts
+/**
+* @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."
+*/
+var LOAD_SERIES_COLLECTION = "metrics:node-load-samples";
+/**
+* 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).
+*/
+var DEFAULT_MAX_ROWS = 5e5;
+var LOAD_SERIES_COLUMNS = [
+	(
+	/** `INTEGER PRIMARY KEY` = SQLite rowid alias: the key IS the row's address,
+	*  so it costs no separate index and no stored string. */
+	{
+		name: "id",
+		type: "INTEGER",
+		primaryKey: true,
+		notNull: true
+	}),
+	{
+		name: "nodeId",
+		type: "TEXT",
+		notNull: true
+	},
+	(
+	/** The EMITTING node's timestamp for the sample this row belongs to. Every
+	*  row of one sample shares it — that is what makes a sample reassemblable. */
+	{
+		name: "atMs",
+		type: "INTEGER",
+		notNull: true
+	}),
+	{
+		name: "pid",
+		type: "INTEGER",
+		notNull: true
+	},
+	(
+	/** `NULL` for a process no addon owns — `root` and `system` both. */
+	{
+		name: "addonId",
+		type: "TEXT"
+	}),
+	{
+		name: "classification",
+		type: "TEXT",
+		notNull: true
+	},
+	(
+	/** `ps pcpu` x 10. A LIFETIME average, not a rate — see `NodeProcess`. */
+	{
+		name: "cpuDeci",
+		type: "INTEGER",
+		notNull: true
+	}),
+	{
+		name: "rssMib",
+		type: "INTEGER",
+		notNull: true
+	},
+	(
+	/** Instantaneous main-thread CPU% x 10. `NULL` = UNKNOWN, never zero. */
+	{
+		name: "cpuMainDeci",
+		type: "INTEGER"
+	}),
+	(
+	/** Instantaneous V8-helper-pool CPU% x 10. `NULL` = UNKNOWN, never zero. */
+	{
+		name: "cpuGcDeci",
+		type: "INTEGER"
+	})
+];
+var LOAD_SERIES_INDEXES = [(
+/**
+* The ONE index, and it serves both jobs.
+*
+* Reads are always "this node, newer than T" — `nodeId` leads so the
+* equality is a range scan and `atMs` supplies the order without a sort.
+* Prunes are always "this node, oldest first" — the same index, walked from
+* the other end. A second index on `atMs` alone was measured and rejected:
+* it cost 23 B/row (196.0 → 172.8 with the two column drops) to serve a
+* cross-node prune that a per-node loop over three nodes already serves.
+*/
+{
+	name: "idx_load_samples_node_at",
+	columns: ["nodeId", "atMs"]
+})];
+var BYTES_PER_MIB = 1048576;
+/** Tenths → percent. `null` stays `null`: unknown is not zero. */
+function fromDeci(value) {
+	return value === null ? null : Math.round(value) / 10;
+}
+/** Percent → tenths, lossless because both producers already round to tenths. */
+function toDeci(value) {
+	return value === null ? null : Math.round(value * 10);
+}
+/** Storage row → the shape a reader gets. The ONE decode. */
+function rowToProcess(row) {
+	return {
+		pid: row.pid,
+		addonId: row.addonId,
+		classification: row.classification,
+		cpuPercent: fromDeci(row.cpuDeci) ?? 0,
+		memoryRssBytes: row.rssMib * BYTES_PER_MIB,
+		cpuMainPercent: fromDeci(row.cpuMainDeci),
+		cpuGcPercent: fromDeci(row.cpuGcDeci)
+	};
+}
+/** The shape a reader gets → the storage row. The ONE encode. */
+function processToRow(nodeId, atMs, process) {
+	return {
+		nodeId,
+		atMs,
+		pid: process.pid,
+		addonId: process.addonId,
+		classification: process.classification,
+		cpuDeci: toDeci(process.cpuPercent) ?? 0,
+		rssMib: Math.round(process.memoryRssBytes / BYTES_PER_MIB),
+		cpuMainDeci: toDeci(process.cpuMainPercent),
+		cpuGcDeci: toDeci(process.cpuGcPercent)
+	};
+}
+/** Group flat rows into samples, oldest-first. A sample is one `atMs`. */
+function rowsToSamples(rows) {
+	const byAt = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const held = byAt.get(row.atMs);
+		if (held === void 0) byAt.set(row.atMs, [rowToProcess(row)]);
+		else held.push(rowToProcess(row));
+	}
+	return [...byAt.entries()].toSorted((a, b) => a[0] - b[0]).map(([atMs, processes]) => ({
+		atMs,
+		processes
+	}));
+}
+/**
+* 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.
+*/
+var LoadSeriesStore = class {
+	declared = false;
+	lastPruneAtMs = 0;
+	store;
+	logger;
+	nowFn;
+	prunePageRows;
+	pruneIntervalMs;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+		this.nowFn = deps.now ?? (() => Date.now());
+		this.prunePageRows = deps.prunePageRows ?? 2e4;
+		this.pruneIntervalMs = deps.pruneIntervalMs ?? 6e4;
+	}
+	/** Idempotently declare the collection. `false` when the store refused. */
+	async declare() {
+		if (this.declared) return true;
+		try {
+			await this.store.declareCollection.mutate({
+				collection: LOAD_SERIES_COLLECTION,
+				columns: [...LOAD_SERIES_COLUMNS],
+				indexes: LOAD_SERIES_INDEXES.map((i) => ({
+					name: i.name,
+					columns: [...i.columns]
+				}))
+			});
+			this.declared = true;
+			return true;
+		} catch (err) {
+			this.logger.warn("load series declareCollection failed — nothing will be retained on disk", { meta: {
+				collection: LOAD_SERIES_COLLECTION,
+				error: errMsg(err)
+			} });
+			return false;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async append(nodeId, atMs, processes) {
+		if (processes.length === 0) return 0;
+		if (!await this.declare()) return 0;
+		const records = processes.map((p) => ({ data: { ...processToRow(nodeId, atMs, p) } }));
+		try {
+			const { inserted } = await this.store.insertMany.mutate({
+				collection: LOAD_SERIES_COLLECTION,
+				records
+			});
+			return inserted;
+		} catch (err) {
+			this.logger.warn("load series sample not retained — this interval will be missing", { meta: {
+				nodeId,
+				atMs,
+				rows: processes.length,
+				error: errMsg(err)
+			} });
+			return 0;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async read(nodeId, sinceMs, limitRows) {
+		if (!await this.declare()) return [];
+		try {
+			const records = await this.store.query.query({
+				collection: LOAD_SERIES_COLLECTION,
+				filter: {
+					where: { nodeId },
+					whereBetween: { atMs: [sinceMs + 1, Number.MAX_SAFE_INTEGER] },
+					orderBy: {
+						field: "atMs",
+						direction: "asc"
+					},
+					limit: limitRows
+				}
+			});
+			const rows = [];
+			for (const record of records) {
+				const row = recordToRow(record.data);
+				if (row !== null) rows.push(row);
+			}
+			return rowsToSamples(rows);
+		} catch (err) {
+			this.logger.warn("load series cold read failed — answering from the hot window only", { meta: {
+				nodeId,
+				sinceMs,
+				error: errMsg(err)
+			} });
+			return [];
+		}
+	}
+	/**
+	* 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.
+	*/
+	async prune(nodeIds, retention, force = false) {
+		const now = this.nowFn();
+		if (!force && now - this.lastPruneAtMs < this.pruneIntervalMs) return null;
+		this.lastPruneAtMs = now;
+		if (!await this.declare()) return null;
+		let deletedByAge = 0;
+		let deletedByCap = 0;
+		let rowsExamined = 0;
+		const ageCutoff = now - retention.retentionHours * 36e5;
+		for (const nodeId of nodeIds) {
+			const outcome = await this.pruneNodeToCutoff(nodeId, ageCutoff);
+			deletedByAge += outcome.deleted;
+			rowsExamined += outcome.examined;
+		}
+		const total = await this.count();
+		const excess = total === null ? 0 : total - retention.maxRows;
+		if (excess > 0) {
+			const outcome = await this.pruneOldestRows(nodeIds, excess);
+			deletedByCap = outcome.deleted;
+			rowsExamined += outcome.examined;
+			this.logger.warn("load series ROW CAP bit — evicting the oldest samples", { meta: {
+				collection: LOAD_SERIES_COLLECTION,
+				rows: total,
+				cap: retention.maxRows,
+				over: excess,
+				deleted: outcome.deleted,
+				retentionHours: retention.retentionHours,
+				hint: "lower the retention or the sampling cadence — the cap is the guarantee, not the intention"
+			} });
+		}
+		return {
+			deletedByAge,
+			deletedByCap,
+			rowsExamined,
+			capBit: excess > 0
+		};
+	}
+	/** Total rows, or `null` when the store could not answer. */
+	async count() {
+		if (!await this.declare()) return null;
+		try {
+			return await this.store.count.query({ collection: LOAD_SERIES_COLLECTION });
+		} catch (err) {
+			this.logger.warn("load series count failed — the row cap is not enforced this pass", { meta: { error: errMsg(err) } });
+			return 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.
+	*/
+	async pruneNodeToCutoff(nodeId, cutoff) {
+		try {
+			const page = await this.store.query.query({
+				collection: LOAD_SERIES_COLLECTION,
+				filter: {
+					where: { nodeId },
+					whereBetween: { atMs: [0, cutoff] },
+					orderBy: {
+						field: "atMs",
+						direction: "asc"
+					},
+					limit: this.prunePageRows
+				},
+				columns: ["atMs"]
+			});
+			if (page.length === 0) return {
+				deleted: 0,
+				examined: 0
+			};
+			const effectiveCutoff = Number(page.at(-1)?.data["atMs"]);
+			if (!Number.isFinite(effectiveCutoff)) return {
+				deleted: 0,
+				examined: page.length
+			};
+			const { deleted } = await this.store.deleteWhere.mutate({
+				collection: LOAD_SERIES_COLLECTION,
+				filter: {
+					where: { nodeId },
+					whereBetween: { atMs: [0, effectiveCutoff] }
+				}
+			});
+			return {
+				deleted,
+				examined: page.length
+			};
+		} catch (err) {
+			this.logger.warn("load series age prune failed — the table keeps growing this pass", { meta: {
+				nodeId,
+				cutoff,
+				error: errMsg(err)
+			} });
+			return {
+				deleted: 0,
+				examined: 0
+			};
+		}
+	}
+	/**
+	* 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.
+	*/
+	async pruneOldestRows(nodeIds, excess) {
+		let remaining = Math.min(excess, this.prunePageRows);
+		let deleted = 0;
+		let examined = 0;
+		for (const nodeId of nodeIds) {
+			if (remaining <= 0) break;
+			try {
+				const page = await this.store.query.query({
+					collection: LOAD_SERIES_COLLECTION,
+					filter: {
+						where: { nodeId },
+						orderBy: {
+							field: "atMs",
+							direction: "asc"
+						},
+						limit: remaining
+					},
+					columns: ["atMs"]
+				});
+				examined += page.length;
+				if (page.length === 0) continue;
+				const cutoff = Number(page.at(-1)?.data["atMs"]);
+				if (!Number.isFinite(cutoff)) continue;
+				const result = await this.store.deleteWhere.mutate({
+					collection: LOAD_SERIES_COLLECTION,
+					filter: {
+						where: { nodeId },
+						whereBetween: { atMs: [0, cutoff] }
+					}
+				});
+				deleted += result.deleted;
+				remaining -= result.deleted;
+			} catch (err) {
+				this.logger.warn("load series cap prune failed — the cap is not enforced this pass", { meta: {
+					nodeId,
+					error: errMsg(err)
+				} });
+			}
+		}
+		return {
+			deleted,
+			examined
+		};
+	}
+};
+/** Structural validation on read. A malformed row is skipped, never charted. */
+function recordToRow(data) {
+	const nodeId = data["nodeId"];
+	const classification = data["classification"];
+	if (typeof nodeId !== "string" || typeof classification !== "string") return null;
+	const atMs = Number(data["atMs"]);
+	const pid = Number(data["pid"]);
+	const cpuDeci = Number(data["cpuDeci"]);
+	const rssMib = Number(data["rssMib"]);
+	if (![
+		atMs,
+		pid,
+		cpuDeci,
+		rssMib
+	].every((n) => Number.isFinite(n))) return null;
+	const rawAddon = data["addonId"];
+	const optional = (raw) => {
+		if (raw === null || raw === void 0) return null;
+		const n = Number(raw);
+		return Number.isFinite(n) ? n : null;
+	};
+	return {
+		nodeId,
+		atMs,
+		pid,
+		addonId: typeof rawAddon === "string" ? rawAddon : null,
+		classification,
+		cpuDeci,
+		rssMib,
+		cpuMainDeci: optional(data["cpuMainDeci"]),
+		cpuGcDeci: optional(data["cpuGcDeci"])
+	};
+}
+//#endregion
+//#region src/builtins/native-metrics/load-series-config.ts
+/**
+* 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.
+*/
+/** Why a value was refused — the message an operator is shown verbatim. */
+var LoadSeriesConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LoadSeriesConfigError";
+	}
+};
+function requireInteger(value, field) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n)) throw new LoadSeriesConfigError(`${field} must be a number, received ${String(value)}`);
+	return Math.round(n);
+}
+/**
+* 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.
+*/
+function resolveLoadSeriesConfig(raw) {
+	let cadenceSec = 10;
+	if (raw.loadSeriesCadenceSec !== void 0 && raw.loadSeriesCadenceSec !== null) {
+		cadenceSec = requireInteger(raw.loadSeriesCadenceSec, "loadSeriesCadenceSec");
+		if (cadenceSec < 5 || cadenceSec > 60) throw new LoadSeriesConfigError(`load series cadence must be between 5 and 60 seconds — refused ${cadenceSec}`);
+	}
+	let retentionHours = 6;
+	if (raw.loadSeriesRetentionHours !== void 0 && raw.loadSeriesRetentionHours !== null) {
+		retentionHours = requireInteger(raw.loadSeriesRetentionHours, "loadSeriesRetentionHours");
+		if (retentionHours < 1 || retentionHours > 72) throw new LoadSeriesConfigError(`load series retention must be between 1 and 72 hours — refused ${retentionHours}`);
+	}
+	return {
+		cadenceSec,
+		retentionHours,
+		maxRows: DEFAULT_MAX_ROWS
+	};
+}
+/**
+* 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`.
+*/
+function projectLoadSeriesCost(input) {
+	const samplesPerNodeWindow = input.config.retentionHours * 3600 / input.config.cadenceSec;
+	const intendedRows = Math.round(samplesPerNodeWindow * Math.max(input.observedProcessRows, 0));
+	const boundedRows = Math.min(intendedRows, input.config.maxRows);
+	return {
+		intendedRows,
+		boundedRows,
+		estimatedBytes: boundedRows * 87,
+		capBites: intendedRows > input.config.maxRows
+	};
+}
+/** Human-readable one-liner for the settings form. */
+function describeLoadSeriesCost(projection) {
+	const mib = (projection.estimatedBytes / 1048576).toFixed(1);
+	const rows = projection.intendedRows.toLocaleString("en-US");
+	const capped = projection.boundedRows.toLocaleString("en-US");
+	if (!projection.capBites) return `This configuration retains ~${rows} rows ≈ ${mib} MiB on the hub database (NVMe cache), measured at 87 bytes per row.`;
+	return `This configuration WANTS ~${rows} rows, above the ${projection.boundedRows.toLocaleString("en-US")}-row hard cap. The table will hold ~${capped} rows ≈ ${mib} MiB and the OLDEST samples will be evicted, so the effective window is shorter than the retention you asked for.`;
+}
+//#endregion
+//#region src/builtins/native-metrics/load-series-reader.ts
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+function mergeSamples(cold, hot) {
+	const byAt = /* @__PURE__ */ new Map();
+	for (const sample of cold) byAt.set(sample.atMs, sample);
+	for (const sample of hot) byAt.set(sample.atMs, sample);
+	return [...byAt.values()].toSorted((a, b) => a.atMs - b.atMs);
+}
+/** `RetainedProcess` is already the fold's row shape — named, not re-derived. */
+function toFoldRows(processes) {
+	return processes;
+}
+/**
+* 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.
+*/
+function mergeLoadSeries(input) {
+	const samples = mergeSamples(input.cold, input.hot);
+	if (samples.length === 0) return {
+		series: [],
+		bucketMs: input.cadenceMs,
+		retainedSamples: 0,
+		oldestAtMs: null
+	};
+	const byKey = /* @__PURE__ */ new Map();
+	for (const sample of samples) for (const bucket of foldSnapshotByFunction(toFoldRows(sample.processes), sample.atMs)) {
+		const held = byKey.get(bucket.key);
+		if (held === void 0) byKey.set(bucket.key, {
+			kind: bucket.kind,
+			points: [bucket.point]
+		});
+		else held.points.push(bucket.point);
+	}
+	const oldestAtMs = samples[0]?.atMs ?? null;
+	const newestAtMs = samples.at(-1)?.atMs ?? oldestAtMs;
+	const spanMs = oldestAtMs === null || newestAtMs === null ? 0 : newestAtMs - oldestAtMs + input.cadenceMs;
+	const bucketMs = input.maxPoints === void 0 ? input.cadenceMs : resolveBucketMs(spanMs, input.cadenceMs, input.maxPoints);
+	const origin = oldestAtMs ?? 0;
+	const series = [...byKey.entries()].map(([key, held]) => ({
+		key,
+		kind: held.kind,
+		points: bucketMs > input.cadenceMs ? reducePoints(held.points, bucketMs, origin) : held.points
+	}));
+	const weight = (s) => {
+		const last = s.points.at(-1);
+		if (last === void 0) return -1;
+		if (last.cpuMainPercent !== null && last.cpuGcPercent !== null) return last.cpuMainPercent + last.cpuGcPercent;
+		return last.cpuLifetimePercent;
+	};
+	return {
+		series: series.toSorted((a, b) => {
+			const d = weight(b) - weight(a);
+			return d !== 0 ? d : a.key.localeCompare(b.key);
+		}),
+		bucketMs,
+		retainedSamples: samples.length,
+		oldestAtMs
+	};
+}
+//#endregion
+//#region src/builtins/native-metrics/process-classification.ts
 /**
 * Regex matching camstack-related command lines. We surface anything with
 * an obvious camstack fingerprint so operators can spot stray inference
@@ -472,23 +1397,243 @@ var execFileAsync = promisify(execFile);
 */
 var CAMSTACK_CMD_RE = /(camstack|tsx\s+watch\s.*launcher\.ts|packages\/agent\/dist\/cli\.js|inference_pool\.py|bench-(inference-pool|nodeav)|node .*\/packages\/)/;
 /**
-* Boundary patterns: ancestry walks that pass through a process whose
-* command line matches one of these are considered to be inside an
-* "intentional camstack tree". Anything reachable by walking up the
-* pid tree from such a boundary is `system` — not a ghost.
-*
-* The boundaries are:
-*  - `tsx watch .../launcher.ts` — hub launcher (npm run dev:server)
-*  - `node .../packages/agent/dist/cli.js` — agent CLI (dev-cluster, npm run dev:agent)
-*  - `concurrently` — dev-cluster orchestrator that runs hub + admin-ui + agents
-*  - `npm exec ` / `npm-cli.js` — npm wrappers driving the above
-*  - `vite` — admin-ui dev server (sibling of hub under concurrently)
-*
-* The classification logic (`classifyByAncestry`) walks each candidate
-* pid up to ppid=1; if any ancestor matches this regex, the candidate
-* is `system`. Reaching ppid=1 without crossing a boundary = `ghost`.
+* Classify one pid.
+*
+* Identity-driven, not ancestry-driven: a process is `root` because it IS
+* this node, `managed` because the kernel named it, and `system` otherwise.
+* There is no third source of truth to consult and no walk to get wrong.
+*/
+function classifyProcess(pid, selfPid, managed) {
+	if (pid === selfPid) return "root";
+	if (managed.has(pid)) return "managed";
+	return "system";
+}
+/** Turn a `ps` snapshot into the node's process table. */
+function buildNodeProcesses(input) {
+	const out = [];
+	for (const p of input.psRows) {
+		if (!CAMSTACK_CMD_RE.test(p.command)) continue;
+		const managed = input.managed.get(p.pid);
+		const split = input.cpuSplits.get(p.pid);
+		const classification = classifyProcess(p.pid, input.selfPid, input.managed);
+		out.push({
+			pid: p.pid,
+			ppid: p.ppid,
+			pgid: p.pgid,
+			classification,
+			addonId: managed?.addonId ?? null,
+			nodeId: managed?.nodeId ?? (p.pid === input.selfPid ? input.selfNodeId : null),
+			command: p.command,
+			cpuPercent: p.cpuPercent,
+			memoryRssBytes: p.memoryRssBytes,
+			cpuMainPercent: split?.mainPercent ?? null,
+			cpuGcPercent: split?.gcPercent ?? null,
+			threadCount: split?.threadCount ?? null,
+			uptimeSec: p.uptimeSec
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/builtins/native-metrics/thread-cpu-sampler.ts
+/**
+* Per-process CPU split: the process's OWN threads vs V8's helper-thread pool.
+*
+* ## Why this exists
+*
+* `ps pcpu` — the number every CPU column in this app renders today — is the
+* process's CPU averaged over its **entire lifetime**. On a runner that has
+* been up for three days it barely moves, which makes it useless as a series:
+* a chart drawn from it is a flat line that cannot show a spike.
+*
+* Worse, a single total hides the finding that rewrote the 2026-08-27
+* diagnosis. Separating the V8 helper threads from the rest showed that ~2
+* whole cores of the container **were not computing** — hub-main was at 73%
+* and `stream-broker` at 61% of their CPU in that pool
+* (`docs/architecture/load-ledger.md`). A CPU chart that does not split the
+* two renders "busy" where the truth is "allocating too much".
+*
+* This module produces both at once, from the source the ledger prescribes:
+* a delta over `/proc/<pid>/task/<tid>/stat`, classified by thread name.
+*
+* ## What `gcPercent` actually contains — read this before quoting it
+*
+* It is the CPU of the threads V8 names `V8Worker`: its platform worker pool.
+* Concurrent marking and sweeping run there, and so does background
+* compilation. So `gcPercent` is **"the V8 helper pool"**, of which GC is the
+* dominant but not the only tenant. It is exactly the quantity the load ledger
+* measured — the 73% / 61% figures are this number — and it is reported under
+* that name for continuity, not because every jiffy in it is a collection.
+* The UI labels it `GC / V8 helpers` for the same reason.
+*
+* ## Cost
+*
+* One `readdir` plus one small `read` per thread, for the camstack-shaped pids
+* ONLY — on a busy node that is ~10 processes × ~10-40 threads. It rides the
+* existing 20 s process-snapshot tick and never adds a timer of its own, so it
+* is strictly cheaper than the full-process-table `ps -eo` scan that tick
+* already pays. There is no high-frequency sampler here; that is the defect
+* the load ledger documents.
+*
+* ## Linux only
+*
+* `/proc/<pid>/task` does not exist on macOS or Windows. Every read returns
+* `null` there, and `null` must reach the UI as "unknown" — never as zero.
+*/
+/**
+* Kernel jiffies per second (`USER_HZ`). `sysconf(_SC_CLK_TCK)` is not exposed
+* to Node, and this has been 100 on every Linux/x86-64 and arm64 kernel
+* configuration we ship to. It scales both numerator and denominator of the
+* ratio identically, so a wrong value would scale all CPU numbers by a
+* constant — visible immediately, not a silent skew.
+*/
+var CLOCK_TICKS_PER_SEC = 100;
+/**
+* Thread names V8 gives its platform worker pool. `comm` is capped at 15
+* characters by the kernel, which is why this matches a PREFIX.
+*/
+var V8_HELPER_THREAD_RE = /^V8Worker/;
+function parseThreadStat(line) {
+	const close = line.lastIndexOf(")");
+	const open = line.indexOf("(");
+	if (close < 0 || open < 0 || close < open) return null;
+	const comm = line.slice(open + 1, close);
+	const rest = line.slice(close + 1).trim().split(/\s+/);
+	const utime = Number(rest[11]);
+	const stime = Number(rest[12]);
+	const startTicks = Number(rest[19]);
+	if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+	if (!Number.isFinite(startTicks)) return null;
+	return {
+		comm,
+		ticks: utime + stime,
+		startTicks
+	};
+}
+var nodeProcFsReader = {
+	listTaskIds: (pid) => readdir(`/proc/${pid}/task`),
+	readTaskStat: (pid, tid) => readFile(`/proc/${pid}/task/${tid}/stat`, "utf8")
+};
+/**
+* Read one instant's tick counts for `pid`, or `null` when the process has no
+* readable `/proc/<pid>/task` — it exited, we lack permission, or this is not
+* Linux. `null` is "unknown"; it must never be turned into a zero downstream.
+*/
+async function readThreadTicks(pid, reader = nodeProcFsReader) {
+	let tids;
+	try {
+		tids = await reader.listTaskIds(pid);
+	} catch {
+		return null;
+	}
+	let mainTicks = 0;
+	let gcTicks = 0;
+	let threadCount = 0;
+	let startTicks = null;
+	const mainThreadTid = String(pid);
+	for (const tid of tids) {
+		let line;
+		try {
+			line = await reader.readTaskStat(pid, tid);
+		} catch {
+			continue;
+		}
+		const parsed = parseThreadStat(line);
+		if (parsed === null) continue;
+		threadCount += 1;
+		if (tid === mainThreadTid) startTicks = parsed.startTicks;
+		if (V8_HELPER_THREAD_RE.test(parsed.comm)) gcTicks += parsed.ticks;
+		else mainTicks += parsed.ticks;
+	}
+	if (threadCount === 0) return null;
+	return {
+		mainTicks,
+		gcTicks,
+		threadCount,
+		atMs: Date.now(),
+		startTicks
+	};
+}
+/**
+* The CPU split between two samples of the SAME process.
+*
+* Returns `null` — never a zero — when the window cannot produce a rate:
+*  - the two samples are not separated in time (no window to divide by);
+*  - the pid's `starttime` changed, or is unknown on either side. A changed
+*    starttime means the pid was RECYCLED: this is a different process that
+*    happens to wear the same number. See below for why the tick check alone
+*    does not catch it;
+*  - either tick count went BACKWARDS, which is the same fault seen from the
+*    other side. A negative delta divided by a window would render as a
+*    plausible small number for the wrong process, and a plausible wrong
+*    number is the failure this whole surface exists to avoid.
+*
+* ## Why `starttime` and not just the backwards-tick check
+*
+* The backwards check only fires when the NEW process has burned FEWER ticks
+* than the dead one had. A recycled pid landing on a busier process — an
+* ffmpeg that has been transcoding for a minute inheriting the pid of an
+* ffmpeg that idled — produces a large POSITIVE delta, which divides cleanly
+* and renders as a spike. That is not a hypothetical rounding concern now that
+* the process snapshot attributes each pid to a camera: it would charge one
+* camera for another camera's whole lifetime of CPU, in a chart built
+* specifically to answer "why is 617 worse than 615". `starttime` is the pid's
+* incarnation number and it catches both directions.
+*/
+function cpuSplitBetween(prev, next) {
+	const windowMs = next.atMs - prev.atMs;
+	if (windowMs <= 0) return null;
+	if (prev.startTicks === null || next.startTicks === null) return null;
+	if (prev.startTicks !== next.startTicks) return null;
+	const mainDelta = next.mainTicks - prev.mainTicks;
+	const gcDelta = next.gcTicks - prev.gcTicks;
+	if (mainDelta < 0 || gcDelta < 0) return null;
+	const windowTicks = windowMs / 1e3 * CLOCK_TICKS_PER_SEC;
+	const pct = (delta) => Math.round(delta / windowTicks * 1e3) / 10;
+	return {
+		mainPercent: pct(mainDelta),
+		gcPercent: pct(gcDelta),
+		threadCount: next.threadCount
+	};
+}
+/**
+* Keeps the previous tick sample per pid so the next process-snapshot tick can
+* turn it into a rate.
+*
+* Bounded by construction: {@link sample} replaces the whole map with only the
+* pids it was just asked about, so a pid that stops appearing in the scan is
+* dropped on the following tick rather than accumulating forever.
 */
-var SUPERVISOR_BOUNDARY_RE = /(tsx\s+watch\s.*launcher\.ts|packages\/agent\/dist\/cli\.js|\.bin\/concurrently|\/concurrently\/dist|\bnpm-cli\.js\b|npm exec |\.bin\/vite|\/vite\/bin\/vite\.js|node_modules\/\.bin\/(vite|concurrently|tsup|rollup|esbuild|tsx)(\s|$))/;
+var ThreadCpuTracker = class {
+	reader;
+	previous = /* @__PURE__ */ new Map();
+	constructor(reader = nodeProcFsReader) {
+		this.reader = reader;
+	}
+	/**
+	* Sample `pids` and return the split for each one that HAS a usable previous
+	* sample. A pid absent from the result has no answer yet — the caller must
+	* report `null`, not `0`.
+	*/
+	async sample(pids) {
+		const out = /* @__PURE__ */ new Map();
+		const nextPrevious = /* @__PURE__ */ new Map();
+		for (const pid of pids) {
+			const next = await readThreadTicks(pid, this.reader);
+			if (next === null) continue;
+			nextPrevious.set(pid, next);
+			const prev = this.previous.get(pid);
+			if (prev === void 0) continue;
+			const split = cpuSplitBetween(prev, next);
+			if (split !== null) out.set(pid, split);
+		}
+		this.previous = nextPrevious;
+		return out;
+	}
+};
+//#endregion
+//#region src/builtins/native-metrics/native-metrics.addon.ts
+var execFileAsync = promisify(execFile);
 /**
 * Cadence for the per-node metric snapshot bus events. ~5 s matches
 * the existing UI polling cadence (ProcessesTab, ProcessResources)
@@ -497,18 +1642,20 @@ var SUPERVISOR_BOUNDARY_RE = /(tsx\s+watch\s.*launcher\.ts|packages\/agent\/dist
 */
 var METRICS_SNAPSHOT_INTERVAL_MS = 5e3;
 /**
-* Cadence for the per-node PROCESS-TREE snapshot bus events. Kept
-* deliberately coarser than the resources cadence because each tick
-* runs a full OS `ps -eo` scan (`runPs`) plus a `$process.list` broker
-* call — heavy work that was previously paid every 5s regardless of
-* whether any UI consumer was subscribed to
-* `MetricsNodeProcessesSnapshot`. The event bus exposes no per-category
-* subscriber count, so instead of demand-gating we split the cadence:
-* 20s cuts the `ps` frequency 4x while the ProcessesTab still gets a
-* fresh-on-open payload from the on-demand `listNodeProcesses` cap call.
-* The dedup + 60s heartbeat below still apply on top of this.
+* The process-tree snapshot is FIXED-CADENCE, and its cadence is the
+* operator's `loadSeriesCadenceSec` (5-60 s, 10 by default).
+*
+* It used to emit only ON A CHANGE, with a 60 s fallback heartbeat, and the
+* dedup is gone rather than tuned. A conditional emit makes a hole in the
+* series mean two different things — "nothing changed" and "nobody reported"
+* — and telling those apart is the entire reason an operator opens this chart
+* after a spike. Now a gap means exactly one thing.
+*
+* It is not free: the emit rate is deterministic, so the durable table's row
+* count is too (nodes x processes / cadence, no discount for a quiet fleet).
+* The measured cost of that is in `docs/architecture/load-ledger.md`, and it
+* is why the retention default is six hours rather than three days.
 */
-var PROCESS_SNAPSHOT_INTERVAL_MS = 2e4;
 /**
 * Force a metrics-snapshot emit at least every 60s even when the
 * coarsened payload looks unchanged. Without this an idle node
@@ -538,25 +1685,6 @@ function coarsenResourcesSnapshot(snapshot) {
 	};
 	return JSON.stringify(round(snapshot));
 }
-/**
-* Coarsen a process list before deduping — pid, addonId, state +
-* bucketed cpu%. Drops cmdline / cwd / start time / uptime which
-* change every tick on a process that's just running. The result
-* is "process X has the same role and roughly the same load" =
-* skip emit.
-*/
-function coarsenProcessList(processes) {
-	const summary = processes.filter((p) => !!p && typeof p === "object").map((p) => {
-		return [
-			p["pid"],
-			p["addonId"],
-			p["state"],
-			typeof p["cpuPercent"] === "number" ? Math.round(p["cpuPercent"] / 5) * 5 : null,
-			typeof p["memoryRss"] === "number" ? Math.round(p["memoryRss"] / (50 * 1024 * 1024)) : null
-		];
-	});
-	return JSON.stringify(summary);
-}
 function narrowWorkerState(state) {
 	switch (state) {
 		case "starting":
@@ -571,7 +1699,7 @@ function narrowWorkerState(state) {
 * Native metrics — CPU, memory, disk usage sampling.
 * Settings appear under Cluster → NodeDetail → Settings.
 */
-var NativeMetricsAddon = class extends BaseAddon {
+var NativeMetricsAddon = class NativeMetricsAddon extends BaseAddon {
 	provider = null;
 	startedAtMs = Date.now();
 	snapshotTimer = null;
@@ -583,9 +1711,77 @@ var NativeMetricsAddon = class extends BaseAddon {
 	* elapsed) is skipped.
 	*/
 	lastResourcesEmit = null;
-	lastProcessesEmit = null;
+	/**
+	* Holds the previous `/proc/<pid>/task/*` tick counts so each process scan
+	* can turn them into an instantaneous CPU rate split between the process's
+	* own threads and V8's helper pool. Self-bounding — see `ThreadCpuTracker`.
+	*/
+	threadCpu = new ThreadCpuTracker();
+	/**
+	* Retention for the snapshots this addon emits. Fed by SUBSCRIBING to
+	* `metrics.node-processes-snapshot`, never by a second sampler — on the hub
+	* that bus carries every node, so the hub's ring is the cluster's. Bounds and
+	* measured cost live in `node-load-ring.ts`.
+	*/
+	loadRing = new NodeLoadRing();
+	/**
+	* The COLD tier, and it exists only on the HUB.
+	*
+	* The table is hub-resident and the hub already hears every node's snapshot
+	* on its bus, so the hub's writer is the cluster's. An agent writing through
+	* the `settings-store` singleton would ship its rows over Moleculer, once
+	* per sample, to reach that very same table.
+	*/
+	loadStore = null;
+	/** The resolved knobs. Re-resolved on every settings write. */
+	loadConfig = {
+		cadenceSec: 10,
+		retentionHours: 6,
+		maxRows: DEFAULT_MAX_ROWS
+	};
+	/**
+	* Process rows seen in each node's most recent snapshot — the OBSERVED
+	* numbers the settings form projects its cost from. A constant here would be
+	* a projection that stops being true the first time the fleet changes.
+	*/
+	observedRowsByNode = /* @__PURE__ */ new Map();
 	constructor() {
-		super({ samplingIntervalMs: 5e3 });
+		super({
+			samplingIntervalMs: 5e3,
+			loadSeriesCadenceSec: 10,
+			loadSeriesRetentionHours: 6
+		});
+	}
+	/** Is this the hub? The same test every other addon uses (`addon-ai`). */
+	get isHub() {
+		return (this.ctx.kernel.cluster?.broker?.nodeID ?? "hub") === "hub";
+	}
+	/** Process rows observed across the whole fleet, for the cost projection. */
+	observedFleetRows() {
+		let total = 0;
+		for (const rows of this.observedRowsByNode.values()) total += rows;
+		return total;
+	}
+	/**
+	* Project a `NodeProcess` onto the series' own row.
+	*
+	* `command`, `ppid`, `pgid`, `nodeId`, `threadCount` and `uptimeSec` are
+	* dropped here, at the single point both tiers pass through, so the hot ring
+	* and the cold table carry the SAME shape and the merged read cannot tell
+	* them apart. `command` in particular is the fattest field in a snapshot and
+	* the same identical string on every runner — the runner id travels in the
+	* environment, not in argv — and nothing that draws this series reads it.
+	*/
+	static toRetained(process) {
+		return {
+			pid: process.pid,
+			addonId: process.addonId,
+			classification: process.classification,
+			cpuPercent: process.cpuPercent,
+			memoryRssBytes: process.memoryRssBytes,
+			cpuMainPercent: process.cpuMainPercent,
+			cpuGcPercent: process.cpuGcPercent
+		};
 	}
 	async onInitialize() {
 		const provider = new NativeMetricsProvider();
@@ -605,16 +1801,127 @@ var NativeMetricsAddon = class extends BaseAddon {
 			listAddonInstances: () => this.listAddonInstances(),
 			getAddonStats: (params) => this.getAddonStats(params.addonId),
 			listNodeProcesses: () => this.listNodeProcesses(),
-			killProcess: (params) => this.killProcess(params),
+			getLoadSeries: (params) => this.readLoadSeries(params),
 			dumpHeapSnapshot: (params) => this.dumpHeapSnapshot(params)
 		};
+		this.applyLoadSeriesConfig();
+		if (this.isHub) this.loadStore = new LoadSeriesStore({
+			store: this.ctx.api.settingsStore,
+			logger: this.ctx.logger.child("LoadSeries")
+		});
 		this.snapshotTimer = setInterval(() => this.emitResourcesSnapshot(), METRICS_SNAPSHOT_INTERVAL_MS);
-		this.processSnapshotTimer = setInterval(() => this.emitProcessesSnapshot(), PROCESS_SNAPSHOT_INTERVAL_MS);
+		this.startProcessSnapshotTimer();
+		this.ctx.addDisposer(this.ctx.eventBus.subscribe({ category: EventCategory.MetricsNodeProcessesSnapshot }, (event) => this.retainSnapshot(event.data.nodeId, event.data.timestamp, event.data.processes)));
 		return [{
 			capability: metricsProviderCapability,
 			provider: composed
 		}];
 	}
+	/**
+	* Retain one arriving snapshot in BOTH tiers.
+	*
+	* The ring is written FIRST and it is the gate: `record` refuses a timestamp
+	* this node has already delivered, and only an accepted sample reaches the
+	* table. That is what makes the append idempotent without a unique index
+	* over two million rows — the composite key it replaces was measured at ~40
+	* bytes per row (`load-series-store.ts`).
+	*
+	* The durable append is fire-and-forget: a storage stall must cost a gap in
+	* the cold window, never a blocked event-bus handler. Every failure logs.
+	*/
+	retainSnapshot(nodeId, atMs, processes) {
+		const retained = processes.map((p) => NativeMetricsAddon.toRetained(p));
+		if (!this.loadRing.record(nodeId, atMs, retained)) return;
+		this.observedRowsByNode.set(nodeId, retained.length);
+		const store = this.loadStore;
+		if (store === null) return;
+		store.append(nodeId, atMs, retained).then(() => store.prune([...this.observedRowsByNode.keys()], this.loadConfig)).catch((err) => {
+			this.ctx.logger.warn("durable load series write failed", { meta: {
+				nodeId,
+				atMs,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+	/**
+	* The ONE reader, over both tiers.
+	*
+	* Cold first, hot second, merged and deduped on `atMs` — see
+	* `load-series-reader.ts`. The cold read is bounded in ROWS, because rows
+	* are what a query costs, and the fold + reduction happen HERE rather than
+	* in the browser: six hours at the 10 s cadence is 2 160 snapshots, and
+	* shipping them to a page that will discard most of them is precisely the
+	* cost this subsystem exists to avoid.
+	*/
+	async readLoadSeries(params) {
+		const cadenceMs = this.loadConfig.cadenceSec * 1e3;
+		const sinceMs = params.sinceMs ?? 0;
+		const hotSamples = this.loadRing.read(params.forNodeId, params.sinceMs).samples.map((sample) => ({
+			atMs: sample.atMs,
+			processes: sample.processes
+		}));
+		const store = this.loadStore;
+		const merged = mergeLoadSeries({
+			cold: store === null ? [] : await store.read(params.forNodeId, sinceMs, this.loadConfig.maxRows),
+			hot: hotSamples,
+			cadenceMs,
+			...params.maxPoints !== void 0 ? { maxPoints: params.maxPoints } : {}
+		});
+		return {
+			nodeId: params.forNodeId,
+			series: merged.series,
+			bucketMs: merged.bucketMs,
+			retainedSamples: merged.retainedSamples,
+			oldestAtMs: merged.oldestAtMs,
+			cadenceMs,
+			durable: store !== null
+		};
+	}
+	/**
+	* Re-resolve the knobs and restate the fixed cadence.
+	*
+	* A REFUSED value (out of 5-60 s, or out of 1-72 h) leaves the previous
+	* configuration in force and says so. Refused, never clamped: storing 10
+	* when the operator typed 2 and reading 10 back is a knob and a readback
+	* agreeing on a value nobody chose.
+	*/
+	applyLoadSeriesConfig() {
+		try {
+			const next = resolveLoadSeriesConfig({
+				loadSeriesCadenceSec: this.config.loadSeriesCadenceSec,
+				loadSeriesRetentionHours: this.config.loadSeriesRetentionHours
+			});
+			const changed = next.cadenceSec !== this.loadConfig.cadenceSec || next.retentionHours !== this.loadConfig.retentionHours;
+			this.loadConfig = next;
+			if (changed) {
+				const projection = projectLoadSeriesCost({
+					config: next,
+					observedProcessRows: this.observedFleetRows()
+				});
+				this.ctx.logger.info("load series configuration applied", { meta: {
+					nodeId: this.ctx.kernel.localNodeId ?? this.ctx.id,
+					cadenceSec: next.cadenceSec,
+					retentionHours: next.retentionHours,
+					maxRows: next.maxRows,
+					projectedRows: projection.intendedRows,
+					projectedMib: Math.round(projection.estimatedBytes / 1048576 * 10) / 10,
+					capBites: projection.capBites
+				} });
+			}
+		} catch (err) {
+			this.ctx.logger.warn("load series configuration REFUSED — keeping the previous values", { meta: {
+				nodeId: this.ctx.kernel.localNodeId ?? this.ctx.id,
+				cadenceSec: this.loadConfig.cadenceSec,
+				retentionHours: this.loadConfig.retentionHours,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	/** (Re)arm the fixed-cadence process-tree timer at the configured interval. */
+	startProcessSnapshotTimer() {
+		if (this.processSnapshotTimer) clearInterval(this.processSnapshotTimer);
+		this.processSnapshotTimer = setInterval(() => this.emitProcessesSnapshot(), this.loadConfig.cadenceSec * 1e3);
+	}
 	async onShutdown() {
 		if (this.snapshotTimer) {
 			clearInterval(this.snapshotTimer);
@@ -670,10 +1977,14 @@ var NativeMetricsAddon = class extends BaseAddon {
 		} catch {}
 	}
 	/**
-	* Emit one `metrics.node-processes-snapshot` for this node. Heavy —
-	* runs a full OS `ps -eo` scan (`runPs`) plus a `$process.list` broker
-	* call. Fires on the coarser PROCESS_SNAPSHOT_INTERVAL_MS so an idle
-	* node isn't paying a process-table walk every 5s. Skip on failure.
+	* Emit one `metrics.node-processes-snapshot` for this node.
+	*
+	* Heavy — a full OS `ps -eo` scan plus a `$process.list` broker call — and
+	* UNCONDITIONAL. The change-detection that used to guard it is gone: with a
+	* fixed cadence a missing interval means exactly one thing, and that is the
+	* property an operator investigating a spike is actually looking for.
+	*
+	* A failed scan emits nothing, which is the same signal: nobody reported.
 	*/
 	async emitProcessesSnapshot() {
 		const eventBus = this.ctx.eventBus;
@@ -682,29 +1993,27 @@ var NativeMetricsAddon = class extends BaseAddon {
 		const timestamp = Date.now();
 		try {
 			const processes = await this.listNodeProcesses();
-			const coarse = coarsenProcessList(processes);
-			const prev = this.lastProcessesEmit;
-			const heartbeatDue = !prev || timestamp - prev.emittedAt >= METRICS_SNAPSHOT_HEARTBEAT_MS;
-			if (!prev || prev.coarse !== coarse || heartbeatDue) {
-				this.lastProcessesEmit = {
-					coarse,
-					emittedAt: timestamp
-				};
-				eventBus.emit(createEvent(EventCategory.MetricsNodeProcessesSnapshot, {
-					type: "node",
-					id: nodeId,
-					nodeId
-				}, {
-					nodeId,
-					processes,
-					timestamp
-				}));
-			}
-		} catch {}
+			eventBus.emit(createEvent(EventCategory.MetricsNodeProcessesSnapshot, {
+				type: "node",
+				id: nodeId,
+				nodeId
+			}, {
+				nodeId,
+				processes,
+				timestamp
+			}));
+		} catch (err) {
+			this.ctx.logger.warn("process snapshot skipped — this interval will be missing", { meta: {
+				nodeId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
 	}
 	async onConfigChanged() {
 		this.provider?.stopSampling();
 		this.provider?.startSampling(this.config.samplingIntervalMs);
+		this.applyLoadSeriesConfig();
+		this.startProcessSnapshotTimer();
 	}
 	async listWorkerInstances() {
 		const broker = this.ctx.kernel.cluster?.broker;
@@ -748,137 +2057,29 @@ var NativeMetricsAddon = class extends BaseAddon {
 	/**
 	* Walk the OS process table and classify each camstack-shaped process.
 	*
-	* Classification (ancestry-driven, NOT pattern-driven):
-	*  - root    — the current node's own pid (`process.pid`).
-	*  - managed — pid is registered in the kernel's `$process.list`
-	*              (forked addon worker spawned by this hub).
-	*  - system  — ancestry walk crosses a SUPERVISOR_BOUNDARY_RE match
-	*              (tsx-watch launcher, agent CLI, concurrently, vite,
-	*              npm exec wrapper). The process belongs to the dev
-	*              tree even if not in `$process.list`. NEVER killable.
-	*  - ghost   — ancestry walk reaches `ppid=1` without crossing any
-	*              supervisor boundary AND the parent isn't visible in
-	*              `ps`. A truly orphaned camstack-shaped process. The
-	*              ONLY classification that's eligible for kill.
-	*
-	* Old pattern-only ghost detection produced false positives: every
-	* monorepo-path process matched CAMSTACK_CMD_RE, ancestry walk
-	* stopping at ppid=hub returned false-positive ghosts whenever a
-	* concurrently sibling sat above hub. Ancestry-driven classification
-	* fixes that.
+	* Classification is IDENTITY-driven: `root` is this pid, `managed` is a pid
+	* the kernel's `$process.list` names, and every other camstack-shaped
+	* process is `system`. The rules — and why there is no longer an ancestry
+	* walk behind them — live in `process-classification.ts`.
 	*/
 	async listNodeProcesses() {
 		const ps = await this.runPs();
 		if (ps.length === 0) return [];
-		const managedPids = /* @__PURE__ */ new Map();
+		const managed = /* @__PURE__ */ new Map();
 		const workers = await this.listWorkerInstances();
-		for (const w of workers) managedPids.set(w.pid, {
+		for (const w of workers) managed.set(w.pid, {
 			addonId: w.addonId,
 			nodeId: w.nodeId
 		});
-		const hubNodeId = this.ctx.kernel.cluster?.broker?.nodeID ?? "hub";
-		const selfPid = process.pid;
-		const psIndex = /* @__PURE__ */ new Map();
-		for (const p of ps) psIndex.set(p.pid, {
-			ppid: p.ppid,
-			command: p.command
+		const camstackPids = ps.filter((p) => CAMSTACK_CMD_RE.test(p.command)).map((p) => p.pid);
+		const cpuSplits = await this.threadCpu.sample(camstackPids);
+		return buildNodeProcesses({
+			psRows: ps,
+			selfPid: process.pid,
+			selfNodeId: this.ctx.kernel.cluster?.broker?.nodeID ?? "hub",
+			managed,
+			cpuSplits
 		});
-		/**
-		* Walk ancestry from `pid` up to ppid=1 (or until we leave the ps
-		* snapshot). Returns:
-		*   - 'system' — crossed a SUPERVISOR_BOUNDARY_RE ancestor
-		*   - 'ghost'  — reached ppid=1 OR the parent isn't visible in ps
-		*                without crossing a boundary
-		*
-		* `selfPid` itself is treated as a boundary (this node's own root).
-		*/
-		const classifyByAncestry = (startPid) => {
-			let cur = startPid;
-			for (let depth = 0; depth < 32; depth++) {
-				const node = psIndex.get(cur);
-				if (!node) return "ghost";
-				if (cur === selfPid) return "system";
-				if (SUPERVISOR_BOUNDARY_RE.test(node.command)) return "system";
-				if (node.ppid === 1) return "ghost";
-				if (node.ppid === selfPid) return "system";
-				cur = node.ppid;
-			}
-			return "system";
-		};
-		const out = [];
-		for (const p of ps) {
-			if (!CAMSTACK_CMD_RE.test(p.command)) continue;
-			const managed = managedPids.get(p.pid);
-			let classification;
-			if (p.pid === selfPid) classification = "root";
-			else if (managed) classification = "managed";
-			else classification = classifyByAncestry(p.pid);
-			const orphaned = classification === "ghost";
-			out.push({
-				pid: p.pid,
-				ppid: p.ppid,
-				pgid: p.pgid,
-				classification,
-				addonId: managed?.addonId ?? null,
-				nodeId: managed?.nodeId ?? (p.pid === selfPid ? hubNodeId : null),
-				command: p.command,
-				cpuPercent: p.cpuPercent,
-				memoryRssBytes: p.memoryRssBytes,
-				uptimeSec: p.uptimeSec,
-				orphaned
-			});
-		}
-		return out;
-	}
-	/**
-	* Send SIGTERM / SIGKILL to a pid. Refuses pids that don't appear in
-	* `listNodeProcesses()` to prevent arbitrary system kills — a dedicated
-	* admin-path for resurrected zombies, not a generic shell replacement.
-	*
-	* `root`-classified pids (the running launcher / agent CLI / hub itself)
-	* are also refused: killing them tears down the whole node and the
-	* operator's intent is almost always to nuke a leaked child, not the
-	* supervisor that keeps the rest alive. Process restart goes through
-	* the dedicated `$process.restart` action, not this kill API.
-	*/
-	async killProcess(input) {
-		const match = (await this.listNodeProcesses()).find((p) => p.pid === input.pid);
-		if (!match) return {
-			success: false,
-			reason: "pid not in node process table"
-		};
-		if (match.classification === "root" || match.classification === "system") {
-			this.ctx.logger.warn("Refused to kill protected process", { meta: {
-				pid: input.pid,
-				classification: match.classification,
-				addonId: match.addonId,
-				command: match.command
-			} });
-			return {
-				success: false,
-				reason: match.classification === "root" ? "cannot kill root (current node supervisor)" : "cannot kill system (intentional dev-tree ancestor — vite, concurrently, npm, etc.)"
-			};
-		}
-		const signal = input.force ? "SIGKILL" : "SIGTERM";
-		try {
-			process.kill(input.pid, signal);
-			this.ctx.logger.info("Killed node process", { meta: {
-				pid: input.pid,
-				signal,
-				classification: match.classification,
-				addonId: match.addonId
-			} });
-			return {
-				success: true,
-				signal
-			};
-		} catch (err) {
-			return {
-				success: false,
-				reason: err instanceof Error ? err.message : String(err),
-				signal
-			};
-		}
 	}
 	/**
 	* Ask the addon's forked runner to write a V8 heap snapshot (SIGUSR2 → the
@@ -955,7 +2156,29 @@ var NativeMetricsAddon = class extends BaseAddon {
 			return [];
 		}
 	}
+	/**
+	* The knobs live HERE, on the document this addon already owns.
+	*
+	* Fields on an existing document, never a method per knob —
+	* `system.getLoggingSettings` / `setLoggingSettings` set that precedent.
+	* They are deliberately NOT in the logging document: that one is about
+	* levels and diagnostic windows, and two documents both claiming a knob is
+	* how this repo has already shipped a switch nobody read.
+	*
+	* Cluster-wide, not per-node: every node must emit 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.
+	*
+	* The cost line is computed from OBSERVED numbers — the nodes and process
+	* counts the cluster is actually reporting — so an operator raising the
+	* retention sees what it costs BEFORE applying it, not afterwards.
+	*/
 	globalSettingsSchema() {
+		const projection = projectLoadSeriesCost({
+			config: this.loadConfig,
+			observedProcessRows: this.observedFleetRows()
+		});
 		return this.schema({ sections: [{
 			id: "native-metrics-settings",
 			title: "System Metrics",
@@ -970,6 +2193,47 @@ var NativeMetricsAddon = class extends BaseAddon {
 				default: 5e3,
 				unit: "ms"
 			})]
+		}, {
+			id: "native-metrics-load-series",
+			title: "Load history",
+			fields: [
+				this.field({
+					type: "number",
+					key: "loadSeriesCadenceSec",
+					label: "Sampling cadence",
+					description: "How often every node reports its process tree. FIXED — a sample is emitted on every interval whether or not anything changed, so a gap in the chart means one thing only: nobody reported. Outside 5-60 s the value is refused.",
+					min: 5,
+					max: 60,
+					step: 1,
+					default: 10,
+					unit: "s"
+				}),
+				this.field({
+					type: "number",
+					key: "loadSeriesRetentionHours",
+					label: "Retention",
+					description: "How long the load history is kept on disk (the hub database, on the NVMe cache — never the recordings disk). This is the INTENTION; the row cap below is the guarantee.",
+					min: 1,
+					max: 72,
+					step: 1,
+					default: 6,
+					unit: "h"
+				}),
+				{
+					type: "info",
+					key: "load-series-cost",
+					label: "What this configuration costs",
+					content: describeLoadSeriesCost(projection),
+					variant: projection.capBites ? "warning" : "info"
+				},
+				{
+					type: "info",
+					key: "load-series-cap",
+					label: "Hard row cap",
+					content: `The table never exceeds ${this.loadConfig.maxRows.toLocaleString("en-US")} rows. When it would, the OLDEST samples are evicted and a warning is logged — so raising the retention can never turn into an incident, only into a shorter effective window.`,
+					variant: "info"
+				}
+			]
 		}] });
 	}
 };