@camstack/system 1.2.145 → 1.2.147

package/dist/builtins/native-metrics/node-load-ring.d.ts

@@ -0,0 +1,214 @@
+/**
+ * In-memory retention for the per-node load snapshots — the shared analogue of
+ * the log ring (`packages/system/src/logging/partitioned-log-buffer.ts`), and
+ * built to the same shape for the same reason: a fixed-capacity circular
+ * partition per key, plus **declared hard ceilings** on the total.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * `native-metrics` emits `metrics.node-processes-snapshot` every 20 s on every
+ * node whether or not anyone is watching (D250). Until now nobody kept it: the
+ * Load charts accumulated 180 points inside the browser tab, so closing the
+ * page threw the hour away and two operators looking at the same node saw two
+ * different windows.
+ *
+ * This ring RETAINS what already arrives. It adds no timer, no sampler, no
+ * probe and no new event — subscribing to a fan-out that exists is the whole
+ * mechanism. It is **not** durable retention: nothing here reaches disk, and a
+ * stored series remains its own decision with its own resolution, retention and
+ * owner (D250 § Consequences).
+ *
+ * ## It does not know what a load snapshot looks like
+ *
+ * `TProcess` is a type parameter and the payload is stored **verbatim**. The
+ * ring reads exactly two things off the envelope — which node, and when — and
+ * never a field of a process row. A field added to the snapshot (a `deviceId`
+ * next to the pid, say) flows through untouched, because there is nothing here
+ * for it to flow through.
+ *
+ * ## Measured cost — see `docs/architecture/load-ledger.md`
+ *
+ * Measured, not estimated, against the real process payloads of the live
+ * cluster (`metricsProvider.listNodeProcesses` on all three nodes: 42 + 20 + 14
+ * rows) replayed 180 deep and weighed as V8 retained heap after a forced GC:
+ *
+ *   **464 B per process row**, so the live cluster's full hour —
+ *   3 nodes x 180 samples x 76 rows = 13 680 rows — is **6.06 MiB**.
+ *
+ * Linear in rows (checked at 360 samples: 463.9 B/row). Every ceiling below is
+ * expressed in ROWS for that reason: rows are what the memory is proportional
+ * to, and samples are not.
+ */
+/** One retained snapshot: when it arrived, and the payload exactly as it came. */
+export interface LoadSample<TProcess> {
+    readonly atMs: number;
+    readonly processes: readonly TProcess[];
+}
+/** What a reader gets back for one node. */
+export interface NodeLoadSeries<TProcess> {
+    readonly nodeId: string;
+    /** Oldest-first, and filtered by the caller's `sinceMs` when given. */
+    readonly samples: readonly LoadSample<TProcess>[];
+    /** Samples retained for this node right now — independent of `sinceMs`. */
+    readonly retainedSamples: number;
+    /** Oldest retained sample's timestamp, or `null` when nothing is retained. */
+    readonly oldestAtMs: number | null;
+    /** The per-node ceiling in force, so a caller can say what it is looking at. */
+    readonly capacity: number;
+}
+/**
+ * Per-node ceiling, in SAMPLES.
+ *
+ * 180 at the 20 s process-snapshot cadence is **one hour** — the window the
+ * operator asked to keep, and the same 180 the browser buffer used before this
+ * existed (`LOAD_SERIES_MAX_POINTS`). The cap is on points, not on age, so a
+ * node whose emits are deduped away covers a longer wall-clock window at the
+ * same cost.
+ */
+export declare const DEFAULT_SAMPLES_PER_NODE = 180;
+/**
+ * Fleet ceiling, in PROCESS ROWS across every node.
+ *
+ * This is the bound the per-node ceiling cannot provide. 180 samples is a fixed
+ * number of samples, not a fixed amount of memory: a node whose process count
+ * explodes — a leaked tsx tree, an inference pool respawning, the ghost storms
+ * the Processes tab exists to surface — multiplies its own partition without
+ * ever touching the per-node cap. That is precisely the defect the RTP pre-roll
+ * rings have in `docs/architecture/load-ledger.md` (#5): a maximum per instance
+ * and no budget for the fleet, which reached 898 MB across 47 rings.
+ *
+ * 32 000 rows x the measured 464 B = **14.2 MiB**, which is deliberately the
+ * same envelope hub-main already accepted for the log ring
+ * (`DEFAULT_MAX_TOTAL_LOG_ENTRIES` 50 000 x ~306 B ~ 15 MB). It is 2.3x the
+ * live cluster's full hour (13 680 rows), so no real deployment evicts on it —
+ * it exists so a runaway node costs 14 MiB instead of everything.
+ */
+export declare const DEFAULT_MAX_TOTAL_PROCESS_ROWS = 32000;
+/**
+ * Ceiling on the number of PARTITIONS.
+ *
+ * The backstop for an unbounded key space, exactly as `DEFAULT_MAX_LOG_BUCKETS`
+ * is: a partition is created on first write, and a node id that appears once —
+ * a renamed agent, a node that joined for an afternoon — must not hold a ring
+ * for the life of the process. 16 is >5x the live fleet of 3.
+ */
+export declare const DEFAULT_MAX_NODES = 16;
+/**
+ * A partition whose newest sample is older than this is dropped whole.
+ *
+ * **Why age, and why this age.** The alternative — evict when the node leaves
+ * the cluster registry — was rejected twice over: it couples this ring to a
+ * registry it has no other reason to know, and a node that is merely offline is
+ * never "removed", so the case that actually happens (an agent that stops
+ * answering) would keep its partition forever. That is the failure mode being
+ * bounded.
+ *
+ * The number is not chosen, it is derived: `DEFAULT_SAMPLES_PER_NODE` x the 20 s
+ * snapshot cadence = **one hour** = the entire window this ring can represent.
+ * A node silent for that long holds nothing that overlaps the hour an operator
+ * is asking about; every point in it has aged out of the question. Below that
+ * threshold the partition is still answering a live question and is kept, even
+ * though the node is quiet — a node emits at least once a minute
+ * (`METRICS_SNAPSHOT_HEARTBEAT_MS`), so an hour of silence is not a slow node,
+ * it is a gone one.
+ */
+export declare const DEFAULT_NODE_IDLE_EVICTION_MS = 3600000;
+export interface NodeLoadRingOptions {
+    readonly samplesPerNode?: number;
+    readonly maxTotalProcessRows?: number;
+    readonly maxNodes?: number;
+    readonly idleEvictionMs?: number;
+    /** Injectable clock. Tests drive eviction without sleeping for an hour. */
+    readonly now?: () => number;
+}
+/**
+ * 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.
+ */
+export declare class NodeLoadRing<TProcess> {
+    private readonly partitions;
+    /**
+     * 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.
+     */
+    private readonly lastWriteSeq;
+    private writeSeq;
+    private totalRows;
+    private readonly samplesPerNode;
+    private readonly maxTotalProcessRows;
+    private readonly maxNodes;
+    private readonly idleEvictionMs;
+    private readonly now;
+    constructor(options?: NodeLoadRingOptions);
+    /**
+     * 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: string, atMs: number, processes: readonly TProcess[]): boolean;
+    /**
+     * 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: string, sinceMs?: number): NodeLoadSeries<TProcess>;
+    /** Node ids with a live partition. Observability for the fleet bound. */
+    nodeIds(): readonly string[];
+    /** Process rows retained across every partition — the number that IS memory. */
+    rowCount(): number;
+    /** Samples retained across every partition. */
+    sampleCount(): number;
+    /**
+     * 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.
+     */
+    private sweepIdle;
+    /**
+     * 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.
+     */
+    private enforceRowBudget;
+    private heaviestPartition;
+    /** Drop `count` whole partitions, least-recently-written first. */
+    private evictPartitions;
+    /** Remove a partition and everything that indexes it. */
+    private dropPartition;
+}

package/dist/builtins/native-metrics/process-classification.d.ts

@@ -0,0 +1,51 @@
+import { NodeProcess } from '@camstack/types';
+import { ThreadCpuSplit } from './thread-cpu-sampler.js';
+/** The classes a node process can carry. Mirrors `NodeProcessSchema`. */
+export type ProcessClassification = NodeProcess['classification'];
+/** One parsed `ps -eo pid,ppid,pgid,pcpu,rss,etime,command` row. */
+export interface PsProcessRow {
+    readonly pid: number;
+    readonly ppid: number;
+    readonly pgid: number;
+    readonly cpuPercent: number;
+    readonly memoryRssBytes: number;
+    readonly uptimeSec: number;
+    readonly command: string;
+}
+/** A pid the kernel's `$process.list` attributes to an addon runner. */
+export interface ManagedProcessEntry {
+    readonly addonId: string;
+    readonly nodeId: string;
+}
+export interface BuildNodeProcessesInput {
+    /** Every visible `ps` row on this node, camstack-shaped or not. */
+    readonly psRows: readonly PsProcessRow[];
+    /** This node's own pid. */
+    readonly selfPid: number;
+    /** Node id reported for the `root` row. */
+    readonly selfNodeId: string;
+    /** pid → addon attribution from `$process.list`. */
+    readonly managed: ReadonlyMap<number, ManagedProcessEntry>;
+    /** pid → thread CPU split, when the sampler had an answer this tick. */
+    readonly cpuSplits: ReadonlyMap<number, ThreadCpuSplit>;
+}
+/**
+ * Regex matching camstack-related command lines. We surface anything with
+ * an obvious camstack fingerprint so operators can spot stray inference
+ * pools, leaked tsx watchers, and zombie node workers in the Cluster →
+ * Agent → Processes tab.
+ *
+ * Patterns mirror `scripts/hunt-zombies.sh` — keep them in sync when
+ * adding a new long-lived subprocess.
+ */
+export declare const CAMSTACK_CMD_RE: RegExp;
+/**
+ * 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.
+ */
+export declare function classifyProcess(pid: number, selfPid: number, managed: ReadonlyMap<number, ManagedProcessEntry>): ProcessClassification;
+/** Turn a `ps` snapshot into the node's process table. */
+export declare function buildNodeProcesses(input: BuildNodeProcessesInput): readonly NodeProcess[];

package/dist/builtins/native-metrics/thread-cpu-sampler.d.ts

@@ -0,0 +1,116 @@
+/** Raw tick counts for one process at one instant, already classified. */
+export interface ThreadTickSample {
+    /** Sum of utime+stime over threads that are NOT in the V8 helper pool. */
+    readonly mainTicks: number;
+    /** Sum of utime+stime over the V8 helper-pool threads. */
+    readonly gcTicks: number;
+    /** Number of threads seen, both classes together. */
+    readonly threadCount: number;
+    /** `Date.now()` at the moment the sample was taken. */
+    readonly atMs: number;
+    /**
+     * The process's `starttime` (field 22 of `/proc/<pid>/stat`) — jiffies since
+     * boot at which THIS incarnation of the pid began. Read from the main
+     * thread, whose tid equals the pid.
+     *
+     * It is the process's identity, and it is the only thing that distinguishes
+     * "the same process, later" from "a different process that got the same pid".
+     * `null` when the main thread's stat could not be read, which is also
+     * treated as "identity unknown" — see {@link cpuSplitBetween}.
+     */
+    readonly startTicks: number | null;
+}
+/** The CPU split over the window between two {@link ThreadTickSample}s. */
+export interface ThreadCpuSplit {
+    /** CPU% of the process's own threads. 100 = one core saturated. */
+    readonly mainPercent: number;
+    /** CPU% of the V8 helper pool — see the module docblock on what this holds. */
+    readonly gcPercent: number;
+    /** Threads seen in the newer sample. */
+    readonly threadCount: number;
+}
+/**
+ * Parse one `/proc/<pid>/task/<tid>/stat` line.
+ *
+ * The `comm` field is field 2 and is wrapped in parentheses — and it can
+ * itself contain spaces and parentheses (`(V8Worker)`, but also
+ * `(some (weird) name)`). Splitting the line on whitespace therefore corrupts
+ * every field after it. The only correct parse is to cut at the LAST `)`, take
+ * `comm` from inside the parens, and index the remaining fields from there:
+ * after the cut, field 3 (`state`) is index 0, so `utime` (field 14) is index
+ * 11 and `stime` (field 15) is index 12.
+ *
+ * `starttime` is field 22, so index 19 by the same arithmetic. It is the
+ * thread's own start, which for the main thread (tid == pid) is the PROCESS's
+ * start — the identity {@link cpuSplitBetween} checks before it believes a
+ * window belongs to the process it belonged to last time.
+ *
+ * Returns `null` for a line that does not parse — a thread that exited between
+ * the readdir and the read leaves a truncated or empty file, and that is
+ * normal, not an error.
+ */
+export interface ParsedThreadStat {
+    readonly comm: string;
+    readonly ticks: number;
+    /** Field 22 (`starttime`), in jiffies since boot. */
+    readonly startTicks: number;
+}
+export declare function parseThreadStat(line: string): ParsedThreadStat | null;
+/** Injectable procfs surface — the whole reason this module is testable. */
+export interface ProcFsReader {
+    readonly listTaskIds: (pid: number) => Promise<readonly string[]>;
+    readonly readTaskStat: (pid: number, tid: string) => Promise<string>;
+}
+export declare const nodeProcFsReader: ProcFsReader;
+/**
+ * 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.
+ */
+export declare function readThreadTicks(pid: number, reader?: ProcFsReader): Promise<ThreadTickSample | null>;
+/**
+ * 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.
+ */
+export declare function cpuSplitBetween(prev: ThreadTickSample, next: ThreadTickSample): ThreadCpuSplit | null;
+/**
+ * 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.
+ */
+export declare class ThreadCpuTracker {
+    private readonly reader;
+    private previous;
+    constructor(reader?: ProcFsReader);
+    /**
+     * 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`.
+     */
+    sample(pids: readonly number[]): Promise<ReadonlyMap<number, ThreadCpuSplit>>;
+}

package/dist/builtins/platform-probe/index.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_child_process = require("node:child_process");
 let node_util = require("node:util");
 let node_os = require("node:os");

package/dist/builtins/platform-probe/index.mjs

@@ -1,5 +1,5 @@
 import { o as __toESM } from "../../chunk-CNf5ZN-e.mjs";
-import { Et as BaseAddon, Qt as EventCategory, Tt as errMsg, V as enumerateInferenceDevices, Vt as emitReadiness, ht as scoreRuntimes, lt as platformProbeCapability } from "../../dist-CG7kwIZp.mjs";
+import { Ot as errMsg, V as enumerateInferenceDevices, Wt as emitReadiness, kt as BaseAddon, tn as EventCategory, ut as platformProbeCapability, vt as scoreRuntimes } from "../../dist-DrBc-7Y3.mjs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import * as os from "node:os";

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.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/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Qt as EventCategory } from "../../dist-CG7kwIZp.mjs";
+import { kt as BaseAddon, tn as EventCategory } from "../../dist-DrBc-7Y3.mjs";
 //#region src/builtins/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/snapshot/index.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 zod = require("zod");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { At as DeviceFeature, Et as BaseAddon, Gt as nodePin, I as deriveBatteryPresence, Mt as DeviceType, O as bareAddonId, Qt as EventCategory, Tt as errMsg, _t as snapshotCapability, i as BatteryStatusSchema, k as batteryCapability, xt as streamQualityLabel } from "../../dist-CG7kwIZp.mjs";
+import { Ft as DeviceType, I as deriveBatteryPresence, Jt as nodePin, Nt as DeviceFeature, O as bareAddonId, Ot as errMsg, bt as snapshotCapability, i as BatteryStatusSchema, k as batteryCapability, kt as BaseAddon, tn as EventCategory, wt as streamQualityLabel } from "../../dist-DrBc-7Y3.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { signExpiringUrl, verifyExpiringUrl } from "@camstack/types/node";

package/dist/builtins/sqlite-storage/filesystem-storage.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 node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, K as filesystemBrowseCapability, bt as storageProviderCapability } from "../../dist-CG7kwIZp.mjs";
+import { Ct as storageProviderCapability, K as filesystemBrowseCapability, kt as BaseAddon } from "../../dist-DrBc-7Y3.mjs";
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/sqlite-storage/sqlite-settings-backend.d.ts

@@ -1,7 +1,16 @@
-import { CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsAggregateInput, SettingsAggregateResult, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput } from '@camstack/types';
+import { BulkRecord, CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsAggregateInput, SettingsAggregateResult, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput } from '@camstack/types';
 import { default as Database } from 'better-sqlite3';
 import { MutationFilterInput } from './filter-compiler.js';
 import { SqliteOpProfiler } from './query-profiler.js';
+/** Input for {@link SqliteSettingsBackend.insertMany}. */
+interface SettingsInsertManyInput {
+    readonly namespace?: string;
+    readonly collection: string;
+    readonly records: readonly BulkRecord[];
+}
+interface SettingsInsertManyResult {
+    readonly inserted: number;
+}
 /** Input for {@link SqliteSettingsBackend.deleteWhere}. */
 interface SettingsDeleteWhereInput {
     readonly namespace?: string;
@@ -148,6 +157,21 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
     set({ namespace, collection, key, value }: SettingsSetInput): Promise<void>;
     query<T extends object = Record<string, unknown>>({ namespace, collection, filter, columns, }: SettingsQueryInput): Promise<readonly SettingsRecord<T>[]>;
     insert<T extends object = Record<string, unknown>>({ namespace, collection, record, }: SettingsInsertInput<T>): Promise<void>;
+    /**
+     * Insert a batch in ONE transaction, on ONE prepared statement.
+     *
+     * The write-side twin of {@link deleteWhere}. Every row in the batch shares
+     * a single column list, which is what makes one `prepare` legal: rows are
+     * normalised to the collection's DECLARED column set, so a row that omits a
+     * column binds `null` for it rather than producing a second statement shape.
+     *
+     * All or nothing — `better-sqlite3`'s `transaction()` rolls the whole batch
+     * back on any throw. A caller writing one process sample gets one COMMIT,
+     * which is the entire point: 76 rows every 10 s is 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.
+     */
+    insertMany({ namespace, collection, records, }: SettingsInsertManyInput): Promise<SettingsInsertManyResult>;
     update({ namespace, collection, id, data }: SettingsUpdateInput): Promise<void>;
     delete({ namespace, collection, key }: SettingsDeleteInput): Promise<void>;
     /**

package/dist/builtins/storage-orchestrator/storage-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 node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);
@@ -663,6 +663,7 @@ function createDataStoreDispatch(getEngines) {
 		set: async (input) => (await engine()).set(input),
 		query: async (input) => (await engine()).query(input),
 		insert: async (input) => (await engine()).insert(input),
+		insertMany: async (input) => (await engine()).insertMany(input),
 		update: async (input) => (await engine()).update(input),
 		delete: async (input) => (await engine()).delete(input),
 		deleteWhere: async (input) => (await engine()).deleteWhere(input),

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

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Kt as parseJsonObject, b as StorageMigrationJobSchema, gt as settingsStoreCapability, vt as storageCapability, y as StorageLocationTypeSchema, yt as storageMigrationCapability } from "../../dist-CG7kwIZp.mjs";
+import { St as storageMigrationCapability, Yt as parseJsonObject, b as StorageMigrationJobSchema, kt as BaseAddon, xt as storageCapability, y as StorageLocationTypeSchema, yt as settingsStoreCapability } from "../../dist-DrBc-7Y3.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
@@ -656,6 +656,7 @@ function createDataStoreDispatch(getEngines) {
 		set: async (input) => (await engine()).set(input),
 		query: async (input) => (await engine()).query(input),
 		insert: async (input) => (await engine()).insert(input),
+		insertMany: async (input) => (await engine()).insertMany(input),
 		update: async (input) => (await engine()).update(input),
 		delete: async (input) => (await engine()).delete(input),
 		deleteWhere: async (input) => (await engine()).deleteWhere(input),

package/dist/builtins/system-config/system-config.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/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as BaseAddon, Tt as errMsg, Ut as hydrateSchema } from "../../dist-CG7kwIZp.mjs";
+import { Kt as hydrateSchema, Ot as errMsg, kt as BaseAddon } from "../../dist-DrBc-7Y3.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.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_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-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";
 import * as path$1 from "node:path";
 import path from "node:path";