@camstack/system 1.2.145 → 1.2.147

package/dist/addon-runner.js

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_manifest_python_deps = require("./manifest-python-deps-GjlyPjm0.js");
+const require_manifest_python_deps = require("./manifest-python-deps-FYZBHc3v.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
@@ -692,6 +692,7 @@ async function main() {
 	const stopHeapWatch = require_manifest_python_deps.startRunnerHeapWatch({
 		heapProfile: process.env["CAMSTACK_RUNNER_HEAP_PROFILE"],
 		reclaimSwitch: process.env["CAMSTACK_RUNNER_HEAP_RECLAIM"],
+		rssBudgetMb: process.env[require_manifest_python_deps.RUNNER_RSS_BUDGET_ENV],
 		label: nodeId,
 		sink: {
 			info: (line) => {

package/dist/addon-runner.mjs

@@ -1,4 +1,4 @@
-import { F as createUdsLoggerWithControl, I as LocalChildClient, Nt as startRunnerHeapWatch, bt as resolveAddonClass, i as createUdsAddonContext, it as setWorkerNativeCapsChangeListener, nt as getWorkerNativeCapSnapshot, ot as validateProviderRegistrations, t as installManifestPythonDeps, tt as getWorkerNativeCapProvider, yt as installManifestNativeDeps } from "./manifest-python-deps-BRyNCnnG.mjs";
+import { F as createUdsLoggerWithControl, Ht as startRunnerHeapWatch, I as LocalChildClient, Nt as RUNNER_RSS_BUDGET_ENV, bt as resolveAddonClass, i as createUdsAddonContext, it as setWorkerNativeCapsChangeListener, nt as getWorkerNativeCapSnapshot, ot as validateProviderRegistrations, t as installManifestPythonDeps, tt as getWorkerNativeCapProvider, yt as installManifestNativeDeps } from "./manifest-python-deps-DhT0oFOZ.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { register } from "node:module";
 import * as path$1 from "node:path";
@@ -688,6 +688,7 @@ async function main() {
 	const stopHeapWatch = startRunnerHeapWatch({
 		heapProfile: process.env["CAMSTACK_RUNNER_HEAP_PROFILE"],
 		reclaimSwitch: process.env["CAMSTACK_RUNNER_HEAP_RECLAIM"],
+		rssBudgetMb: process.env[RUNNER_RSS_BUDGET_ENV],
 		label: nodeId,
 		sink: {
 			info: (line) => {

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory, S as addonPagesCapability, Tt as errMsg } from "../../dist-CG7kwIZp.mjs";
+import { Ot as errMsg, S as addonPagesCapability, kt as BaseAddon, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory, Tt as errMsg, w as addonWidgetsCapability } from "../../dist-CG7kwIZp.mjs";
+import { Ot as errMsg, kt as BaseAddon, tn as EventCategory, w as addonWidgetsCapability } from "../../dist-DrBc-7Y3.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/alerts/alerts.addon.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-Dl6MFXPr.js");
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/alerts/alerts.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory, T as alertsCapability, Tt as errMsg, n as AlertSchema, zt as createEvent } from "../../dist-CG7kwIZp.mjs";
+import { Ht as createEvent, Ot as errMsg, T as alertsCapability, kt as BaseAddon, n as AlertSchema, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
 let node_crypto = require("node:crypto");
 let buffer = require("buffer");
 let node_fs_promises = require("node:fs/promises");

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { D as backupCapability, Et as BaseAddon, Qt as EventCategory } from "../../dist-CG7kwIZp.mjs";
+import { D as backupCapability, kt as BaseAddon, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "buffer";
 import * as fsp from "node:fs/promises";

package/dist/builtins/console-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-Dl6MFXPr.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/console-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-DrBc-7Y3.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/core-blocks/core-blocks.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-Dl6MFXPr.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);

package/dist/builtins/core-blocks/core-blocks.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, M as coreBlockIdFromAddonId, N as coreBlocksCapability, Tt as errMsg, c as CoreBlockSchema, j as coreBlockAddonId, o as CORE_BLOCKS_ADDON_ID, s as CORE_BLOCK_ADDON_PREFIX, u as DeclaredDevices } from "../../dist-CG7kwIZp.mjs";
+import { M as coreBlockIdFromAddonId, N as coreBlocksCapability, Ot as errMsg, c as CoreBlockSchema, j as coreBlockAddonId, kt as BaseAddon, o as CORE_BLOCKS_ADDON_ID, s as CORE_BLOCK_ADDON_PREFIX, u as DeclaredDevices } from "../../dist-DrBc-7Y3.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/device-manager/device-manager.addon.js

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
-const require_retired_settings_keys = require("../../retired-settings-keys-_PLI9w0k.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
+const require_retired_settings_keys = require("../../retired-settings-keys-6w_JOqBg.js");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
 //#region src/builtins/device-manager/adoption-job-engine.ts

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -1,5 +1,5 @@
-import { A as buildStreamParamsConfigSchema, At as DeviceFeature, Et as BaseAddon, Ft as WELL_KNOWN_TAB_MAP, H as enumerateItemArrayFields, L as deviceManagerCapability, Mt as DeviceType, Qt as EventCategory, R as deviceStateCapability, Tt as errMsg, U as enumerateSchemaFields, Wt as isDeviceConfigCap, Zt as sleep, _ as STREAM_PROFILE_META, a as CAP_NAMES_WITH_STATUS, ct as parseStreamParamsFormPatch, d as DeviceStatusSchema, ft as runtimeStatePolicyFor, jt as DeviceRole, ot as normalizeUnit, t as ALL_CAPABILITY_DEFINITIONS, z as deviceStatusCapability } from "../../dist-CG7kwIZp.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-Dm1z4mO4.mjs";
+import { A as buildStreamParamsConfigSchema, Ft as DeviceType, H as enumerateItemArrayFields, L as deviceManagerCapability, Nt as DeviceFeature, Ot as errMsg, Pt as DeviceRole, R as deviceStateCapability, Rt as WELL_KNOWN_TAB_MAP, U as enumerateSchemaFields, _ as STREAM_PROFILE_META, a as CAP_NAMES_WITH_STATUS, d as DeviceStatusSchema, en as sleep, ht as runtimeStatePolicyFor, kt as BaseAddon, lt as parseStreamParamsFormPatch, qt as isDeviceConfigCap, st as normalizeUnit, t as ALL_CAPABILITY_DEFINITIONS, tn as EventCategory, z as deviceStatusCapability } from "../../dist-DrBc-7Y3.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-CF5r4YKq.mjs";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
 //#region src/builtins/device-manager/adoption-job-engine.ts

package/dist/builtins/doorbell/virtual-doorbell.addon.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-Dl6MFXPr.js");
 //#region src/builtins/doorbell/trigger-engine.ts
 /**
 * Pure trigger logic for the virtual-doorbell builtin — edge detection over

package/dist/builtins/doorbell/virtual-doorbell.addon.mjs

@@ -1,4 +1,4 @@
-import { B as doorbellCapability, Et as BaseAddon, Mt as DeviceType, O as bareAddonId, Qt as EventCategory, Tt as errMsg, W as evaluateSensorEdge, X as isSameAddonId, Z as isSourceCap, g as SOURCE_DEVICE_TYPES, h as SOURCE_CAPS, zt as createEvent } from "../../dist-CG7kwIZp.mjs";
+import { B as doorbellCapability, Ft as DeviceType, Ht as createEvent, O as bareAddonId, Ot as errMsg, Q as isSourceCap, W as evaluateSensorEdge, Z as isSameAddonId, g as SOURCE_DEVICE_TYPES, h as SOURCE_CAPS, kt as BaseAddon, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 //#region src/builtins/doorbell/trigger-engine.ts
 /**
 * Pure trigger logic for the virtual-doorbell builtin — edge detection over

package/dist/builtins/hub-forwarder/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-Dl6MFXPr.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 //#region src/builtins/hub-forwarder/hub-forwarder-destination.ts
 var DEFAULT_OUTBOUND_BUFFER_SIZE = 500;

package/dist/builtins/hub-forwarder/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-DrBc-7Y3.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 //#region src/builtins/hub-forwarder/hub-forwarder-destination.ts
 var DEFAULT_OUTBOUND_BUFFER_SIZE = 500;

package/dist/builtins/liveness-monitor/liveness-monitor.addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
 //#region src/builtins/liveness-monitor/liveness-checks.ts
 var NO_DEVICES = "liveness:no-devices";
 var ALL_OFFLINE = "liveness:all-devices-offline";

package/dist/builtins/liveness-monitor/liveness-monitor.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory, Tt as errMsg, zt as createEvent } from "../../dist-CG7kwIZp.mjs";
+import { Ht as createEvent, Ot as errMsg, kt as BaseAddon, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 //#region src/builtins/liveness-monitor/liveness-checks.ts
 var NO_DEVICES = "liveness:no-devices";
 var ALL_OFFLINE = "liveness:all-devices-offline";

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

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BVU5JADq.js");
+const require_dist = require("../../dist-Dl6MFXPr.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto);
 let crypto$1 = require("crypto");

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-DrBc-7Y3.mjs";
 import * as crypto$2 from "node:crypto";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import nodeCrypto from "crypto";

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-Dl6MFXPr.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-DrBc-7Y3.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-Dl6MFXPr.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-DrBc-7Y3.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;