@camstack/system 1.2.389 → 1.2.391

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

@@ -1,487 +1,487 @@
-import { BulkRecord, CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsAggregateInput, SettingsAggregateResult, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput, SettingsUpsertInput } from '@camstack/types';
-import { default as Database } from 'better-sqlite3';
-import { MutationFilterInput } from './filter-compiler.js';
-import { SqliteOpProfiler } from './query-profiler.js';
+import type { BulkRecord, CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsAggregateInput, SettingsAggregateResult, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput, SettingsUpsertInput } from "@camstack/types";
+import Database from "better-sqlite3";
+import { type 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[];
+	readonly namespace?: string;
+	readonly collection: string;
+	readonly records: readonly BulkRecord[];
 }
 interface SettingsInsertManyResult {
-    readonly inserted: number;
+	readonly inserted: number;
 }
 /** Input for {@link SqliteSettingsBackend.deleteWhere}. */
 interface SettingsDeleteWhereInput {
-    readonly namespace?: string;
-    readonly collection: string;
-    readonly filter: MutationFilterInput;
+	readonly namespace?: string;
+	readonly collection: string;
+	readonly filter: MutationFilterInput;
 }
 interface SettingsDeleteWhereResult {
-    readonly deleted: number;
+	readonly deleted: number;
 }
 /** Input for {@link SqliteSettingsBackend.updateWhere}. */
 interface SettingsUpdateWhereInput {
-    readonly namespace?: string;
-    readonly collection: string;
-    readonly filter: MutationFilterInput;
-    readonly data: Readonly<Record<string, unknown>>;
+	readonly namespace?: string;
+	readonly collection: string;
+	readonly filter: MutationFilterInput;
+	readonly data: Readonly<Record<string, unknown>>;
 }
 interface SettingsUpdateWhereResult {
-    readonly updated: number;
+	readonly updated: number;
 }
 /** What {@link SqliteSettingsBackend.dropRetiredTable} destroyed. */
 export interface DroppedTable {
-    /** Rows the table held at the moment it was dropped. */
-    readonly rows: number;
+	/** Rows the table held at the moment it was dropped. */
+	readonly rows: number;
 }
 /**
- * The addon that owns a scoped row, lifted out of the filter that names it.
- *
- * `(op, collection)` cannot name a culprit: the 60 s window of 2026-08-25 read
- * `query addon-device-settings` 67 660 times — 1 128 a second on a
- * single-threaded synchronous engine — and the report could say what was
- * running but never who. The caller identity is not reachable from this
- * process (a cap handler receives an input, not a caller), but for the scoped
- * collections it does not need to be: the id IS `<addonId>:<deviceId>.<field>`,
- * so a filter that names an id names its owner.
- *
- * Attributes NOTHING when the id is unscoped or absent. A storm blamed on the
- * wrong addon is worse than one with no name on it — the wrong name gets acted
- * on. Same source and same shape as {@link deviceIdOf}, which already lifts the
- * device out of this very filter.
- */
+* The addon that owns a scoped row, lifted out of the filter that names it.
+*
+* `(op, collection)` cannot name a culprit: the 60 s window of 2026-08-25 read
+* `query addon-device-settings` 67 660 times — 1 128 a second on a
+* single-threaded synchronous engine — and the report could say what was
+* running but never who. The caller identity is not reachable from this
+* process (a cap handler receives an input, not a caller), but for the scoped
+* collections it does not need to be: the id IS `<addonId>:<deviceId>.<field>`,
+* so a filter that names an id names its owner.
+*
+* Attributes NOTHING when the id is unscoped or absent. A storm blamed on the
+* wrong addon is worse than one with no name on it — the wrong name gets acted
+* on. Same source and same shape as {@link deviceIdOf}, which already lifts the
+* device out of this very filter.
+*/
 export declare function scopeOwnerOf(filter: QueryFilter | undefined): {
-    owner?: string;
+	owner?: string;
 };
 /**
- * Stable identity of a declared schema — every property that changes the DDL
- * or the set of columns a filter can name.
- *
- * Deliberately covers `indexes` too: an added index is as invisible to a
- * name-only memo as an added column, and `CREATE INDEX IF NOT EXISTS` is
- * cheap enough that re-running it costs nothing.
- */
+* Stable identity of a declared schema — every property that changes the DDL
+* or the set of columns a filter can name.
+*
+* Deliberately covers `indexes` too: an added index is as invisible to a
+* name-only memo as an added column, and `CREATE INDEX IF NOT EXISTS` is
+* cheap enough that re-running it costs nothing.
+*/
 /**
- * A `query` asked to read a column the collection cannot serve. Distinct type
- * so a caller can map it to a 400 — it is always a programming error in the
- * caller, never a condition of the data.
- */
+* A `query` asked to read a column the collection cannot serve. Distinct type
+* so a caller can map it to a 400 — it is always a programming error in the
+* caller, never a condition of the data.
+*/
 export declare class UnprojectableColumnError extends Error {
-    constructor(message: string);
+	constructor(message: string);
 }
 /**
- * SQLite implementation of ISettingsBackend.
- *
- * Every collection is structured: declared at boot (canonical KV
- * collections) or via `declareCollection` (typed schemas like
- * `pipeline-analytics:tracks`). The legacy auto-create-on-first-access
- * path was removed — see commit history for the migration. Operations
- * on undeclared collections throw at runtime so callers fail fast.
- *
- * WAL mode for concurrent reads.
- */
+* SQLite implementation of ISettingsBackend.
+*
+* Every collection is structured: declared at boot (canonical KV
+* collections) or via `declareCollection` (typed schemas like
+* `pipeline-analytics:tracks`). The legacy auto-create-on-first-access
+* path was removed — see commit history for the migration. Operations
+* on undeclared collections throw at runtime so callers fail fast.
+*
+* WAL mode for concurrent reads.
+*/
 export declare class SqliteSettingsBackend implements ISettingsBackend {
-    private readonly dbPath;
-    private db;
-    /**
-     * Table name → fingerprint of the schema this process last materialised.
-     *
-     * Keyed by FINGERPRINT, not by name, and that is the whole point. An addon
-     * declares its schema at every boot, but the backend lives in hub-main,
-     * which outlives an addon respawn: `camstack deploy` restarts the addon
-     * runner and NOT hub-main. A name-only memo therefore made the second
-     * declaration of a table a no-op FOREVER — a redeployed addon whose schema
-     * had gained a column never got the `ALTER TABLE … ADD COLUMN`, and, because
-     * `compileFilter` silently drops a predicate naming a column the collection
-     * cannot express (select mode), the missing column read as "matches
-     * everything" instead of failing. That is how `pipeline-analytics:tracks`
-     * ran for a whole release with no `retrainStatus`: the retention sweep's
-     * `whereIn: { retrainStatus: ['none','trained'] }` pin evaporated, so every
-     * operator-staged track was eligible for deletion, and `countStaging`
-     * reported the entire history as staged.
-     */
-    private readonly structuredTables;
-    /** Map from scoped collection name → set of column names (non-id) that
-     *  the structured schema owns. Routes set/get/insert/update/query to
-     *  typed columns. Every collection MUST be declared here before use. */
-    private readonly declaredCollections;
-    private readonly runtimeDefaults;
-    /**
-     * Canonical key/value collections — declared with a `(id TEXT PK,
-     * data TEXT NOT NULL)` schema at boot so existing JSON-blob rows
-     * keep working through the structured path. Generates SQL identical
-     * to the previous legacy path; only the routing is unified.
-     */
-    private static readonly CANONICAL_KV_COLLECTIONS;
-    /**
-     * Optional, because the engine is constructed in places that have no addon
-     * context (migrations, one-shot tools, most specs). It is NOT optional in
-     * production: `sqlite-settings.addon.ts` passes one, and without it a row cap
-     * being hit would be silent — which is the failure mode the cap exists to
-     * avoid replacing.
-     */
-    private readonly logger;
-    /**
-     * Per-statement timing. Absent only where the backend is constructed without
-     * a logger (migrations, one-shot tools, most specs) — production always has
-     * one, because a runner that stalls with no record of what it was executing
-     * is the failure this was built for (`query-profiler.ts`).
-     */
-    private readonly profiler;
-    constructor(dbPath: string, runtimeDefaults?: Record<string, unknown>, logger?: IScopedLogger);
-    initialize(): Promise<void>;
-    private requireDeclared;
-    /**
-     * Decode a single column value off a SQLite row into the JS shape the
-     * caller's schema expects. Handles:
-     *   - BOOLEAN columns: `0|1` → `false|true`
-     *   - JSON columns (TEXT starting with `{` / `[`): parse
-     *   - everything else: pass-through with null coalescing
-     */
-    private decodeColumnValue;
-    shutdown(): Promise<void>;
-    /**
-     * The statement profiler, so an addon sharing this handle (the sqlite-vec
-     * index) reports into the SAME window. Two profilers on one thread would
-     * each describe a fraction of the stall and neither would add up to it.
-     */
-    getProfiler(): SqliteOpProfiler | undefined;
-    /**
-     * `data-store-provider` self-description — how the orchestrator names
-     * this engine in a log line, and (once collections declare an engine)
-     * how it picks between registrants.
-     */
-    getEngineInfo(): Promise<DataStoreEngineInfo>;
-    get({ namespace, collection, key }: SettingsGetInput): Promise<unknown>;
-    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<{
-        readonly id: string | number;
-    }>;
-    /**
-     * Make a SLOT hold this row, and answer with the id the row HAS — one
-     * statement, `INSERT … ON CONFLICT(<slot>) DO UPDATE … RETURNING <pk>`.
-     *
-     * See `settings-store.cap.ts`'s `upsert` docblock for why the store needed a
-     * slot that is not the primary key (D482). Three things are load-bearing
-     * here:
-     *
-     *  - **`RETURNING` and not `lastInsertRowid`.** On the UPDATE branch
-     *    `lastInsertRowid` is whatever the connection last inserted — a
-     *    different row, or a different TABLE. It answers confidently and wrongly,
-     *    which is worse than not answering. `RETURNING` names the row this
-     *    statement actually touched, on both branches.
-     *  - **The conflict columns are checked against the declaration** before they
-     *    reach the SQL. An undeclared name would be interpolated into DDL-shaped
-     *    text; it is refused, by the same rule and for the same reason
-     *    {@link resolveProjection} throws on an unprojectable column.
-     *  - **The primary key is never part of the SET list.** An `INTEGER` rowid
-     *    alias is not in `row` at all, and on a TEXT key rewriting the id of the
-     *    row we just matched is the one update that cannot be right.
-     */
-    upsert<T extends object = Record<string, unknown>>({ namespace, collection, conflict, record, }: SettingsUpsertInput<T>): Promise<{
-        readonly id: string | number;
-    }>;
-    /**
-     * 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>;
-    /**
-     * Bulk delete. One statement, whatever the row count — this is what every
-     * retention path in the system was hand-rolling as a select-then-delete
-     * loop. The filter is compiled in `mutate` mode, so an unresolvable
-     * predicate or an empty one throws before any SQL exists.
-     */
-    deleteWhere({ namespace, collection, filter, }: SettingsDeleteWhereInput): Promise<SettingsDeleteWhereResult>;
-    /**
-     * Bulk update. Same filter contract as {@link deleteWhere}.
-     *
-     * Every key of `data` must be a REAL column. A KV-shaped collection keeps
-     * its fields inside a JSON blob, and setting one would need `json_set` with
-     * read-modify-write semantics this method does not have — so it refuses
-     * rather than writing a column that does not exist, which is what the
-     * uncapped `tableUpdate` would have done.
-     */
-    updateWhere({ namespace, collection, filter, data, }: SettingsUpdateWhereInput): Promise<SettingsUpdateWhereResult>;
-    /**
-     * How many rows match — about the SAME rows {@link query} would return.
-     *
-     * That agreement is the entire contract, and until now it did not hold. This
-     * was the FOURTH hand-rolled copy of the filter logic (after `query`, the
-     * bulk mutations and `histogram`) and it compiled only `where`:
-     * `whereBetween`, `whereIn` and `whereNot` were dropped silently, so the
-     * count was not slow, it was WRONG, and always wrong in the same direction —
-     * too big, because every dropped predicate is a predicate that would have
-     * excluded rows.
-     *
-     * Two live callers decided on it. `TrackStore.countStaging({ deviceId,
-     * olderThanMs })` sends the cutoff as `whereBetween: { lastSeen: [0, …] }`
-     * and got the device's whole staging history instead. The notification-centre
-     * artefact gallery pages on `total` from this method while listing through
-     * `query`, and its filter is almost entirely `whereIn`/`whereBetween`
-     * (visibility, kind, device, time window, expiry) — so `total` counted rows
-     * the page could never show, including other users'.
-     *
-     * `measure` mode. `count` compiles the same predicates `query` does — the
-     * two must never disagree about WHICH rows they are talking about — but it
-     * refuses a predicate it cannot express rather than skipping it. `query`
-     * hands back rows and a caller can see the filter did not bite; a count
-     * hands back a number, and the whole collection and the intended subset are
-     * the same shape.
-     */
-    count({ namespace, collection, filter }: SettingsCountInput): Promise<number>;
-    /**
-     * `COUNT(*)` and one SUM/MIN/MAX per requested field, in ONE statement.
-     *
-     * Result slots are aliased POSITIONALLY (`a0`, `a1`, …) and mapped back by
-     * index: `as` is caller text and must never reach SQL as an identifier, and
-     * the column name is validated through {@link fieldExprFor} exactly like a
-     * projection — an unresolvable field THROWS rather than being dropped, because
-     * a missing aggregate comes back as a number that looks real.
-     *
-     * `measure` mode on the filter, so this agrees with `query` and `count`
-     * about which rows it is talking about — and, since 2026-08-30, refuses an
-     * unresolvable PREDICATE for the same reason it already refused an
-     * unresolvable FIELD. Both come back as a number that looks real.
-     */
-    aggregate({ namespace, collection, fields, filter, }: SettingsAggregateInput): Promise<SettingsAggregateResult>;
-    histogram({ namespace, collection, field, bucketSize, origin, filter, }: SettingsHistogramInput): Promise<readonly HistogramBucket[]>;
-    isEmpty({ namespace, collection }: SettingsIsEmptyInput): Promise<boolean>;
-    private queryDeclared;
-    /** Get a system setting by dot-notation key */
-    getSystem(key: string): unknown;
-    /** Set a system setting */
-    setSystem(key: string, value: unknown): void;
-    /** Get all system settings as flat key-value */
-    getAllSystem(): Record<string, unknown>;
-    /**
-     * Get all settings for an addon.
-     *
-     * Selected by the SAME key range {@link setAllAddon} deletes and re-inserts
-     * — `prefixWhere("<addonId>.")` — and for the same reason `getAllScoped`
-     * uses it: `"<addonId>.<key>"` is the PRIMARY KEY, so the range is a
-     * `SEARCH … USING INDEX` while anything else is a full `SCAN`.
-     *
-     * It used to select on `json_extract(data, '$.addonId')`, which is a second
-     * authority for "this addon's rows" and disagreed with the writer in both
-     * directions: a row inside the JSON's idea of the addon but outside the key
-     * range was READ and never DELETED (a config key that could not be cleared),
-     * and `json_extract` was evaluated on EVERY row — so a four-key addon paid
-     * for the whole table and one unparseable neighbour aborted the statement,
-     * taking out every addon's config read at once.
-     *
-     * The cost was not theoretical. On the live hub `addon-settings` is 627 KB
-     * in 24 rows, 625 KB of it device-manager's three fleet blobs; a V8 profile
-     * of a boot (2026-08-19) had hub-main's JS thread 99.9% busy with **64% of
-     * it inside this method**, which is what put a ~45 s queue in front of every
-     * runner's first store read. Measured on that table: 0.947 ms → ~0.02 ms for
-     * a four-key addon, 2.90 ms → 2.13 ms for device-manager's own.
-     */
-    getAllAddon(addonId: string): Record<string, unknown>;
-    /** Bulk-set all settings for an addon */
-    setAllAddon(addonId: string, config: Record<string, unknown>): void;
-    /** Get all settings for a provider */
-    getAllProvider(providerId: string): Record<string, unknown>;
-    /** Set a provider setting */
-    setProvider(providerId: string, key: string, value: unknown): void;
-    /** Get all settings for a device */
-    getAllDevice(deviceId: string): Record<string, unknown>;
-    /** Set a device setting */
-    setDevice(deviceId: string, key: string, value: unknown): void;
-    getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
-    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
-    clearAddonDevice(addonId: string, deviceId: string): void;
-    private static readonly LEGACY_RUNTIME_STATE_ADDON_ID;
-    /**
-     * The device's whole cap-slice map. Canonical row first, legacy prefix as the
-     * fallback. `{}` — never null — when the device has never persisted a slice,
-     * because every caller treats the result as a cap map to iterate.
-     */
-    getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
-    /**
-     * Replace the device's whole cap-slice map. Replace, not merge — the caller
-     * always hands over the full persistable blob, and merging would resurrect a
-     * slice the durability policy has since stopped persisting.
-     */
-    setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
-    /** Forget the device's runtime state in BOTH stores (device removal). */
-    clearDeviceRuntimeState(deviceId: string): void;
-    /** Seed system-settings with runtime defaults (first boot) */
-    private seedDefaults;
-    /**
-     * Expose the raw better-sqlite3 Database instance for components that
-     * need direct SQL access (e.g. DeviceStore, ConfigStore).
-     * Returns null if the backend has not been initialized yet.
-     */
-    getDatabase(): Database.Database | null;
-    /**
-     * `EXPLAIN QUERY PLAN` for a statement, as one string per plan row.
-     *
-     * Answers the question the timing alone cannot: "1.6 s for 501 rows" is a
-     * full scan and is also a cold disk, and only the plan tells them apart. It
-     * runs on the SAME connection as the statement, because that is the only
-     * connection whose `sqlite_stat1` visibility and temp schema match.
-     *
-     * `EXPLAIN QUERY PLAN` prepares and plans; it does not execute the statement,
-     * so it costs no page reads of its own. In production it is called only from
-     * the slow-call path, once per shape per window; it is public so a guard can
-     * assert that a declared index is the one the planner actually picks — "we
-     * added an index" and "the query uses it" are different claims.
-     *
-     * Never throws. A plan that cannot be taken (a statement the engine will no
-     * longer prepare, a closed handle mid-shutdown) is a missing ANSWER, not a
-     * failure worth turning a slow query into a crash — the profiler falls back
-     * to the line it would have printed anyway.
-     */
-    explainQueryPlan(sql: string, params: readonly unknown[]): readonly string[];
-    /**
-     * Run one synchronous statement under the profiler.
-     *
-     * A thin pass-through when no profiler exists, so the specs that construct
-     * this backend without a logger keep exercising the SAME code path as
-     * production. The alternative — two call shapes — is how a fix gets tested
-     * on a branch production never takes.
-     */
-    private measured;
-    /**
-     * Size of the database file, or 0 when it cannot be read.
-     *
-     * 0 is the honest answer for a first boot (no file yet) and for an
-     * unreadable `stat`, and both callers treat it as "unknown" and fall back to
-     * the floor — never to a smaller setting than the one already argued for.
-     */
-    /**
-     * One numeric PRAGMA off the open connection. A pragma that does not answer
-     * with a number yields 0, which `sqliteOccupancy` reads as "unknown" and
-     * reports as an empty file rather than inventing a ratio.
-     */
-    /**
-     * Follow the file as it grows.
-     *
-     * The map is derived from the file at OPEN and never again, which is the same
-     * expiry one level up: a database that grows during uptime keeps the map it
-     * had at boot, and once the file passes it every read outside the window
-     * costs a synchronous page-in — 418 per second, measured 2026-08-25. This
-     * node escaped it only because 130 MB → 858 MB spanned seventeen days of
-     * restarts.
-     *
-     * `unref` so it never holds the process open.
-     */
-    private scheduleMapGrowthCheck;
-    /**
-     * One-shot `ANALYZE`, long after boot, only if the database has none.
-     *
-     * `analyze-stats.ts` has the measurement that justifies it: without
-     * `sqlite_stat1` the planner walked 150 133 media rows to return six, and one
-     * `ANALYZE` took that same query from 727 ms to 3.2 ms. It is scheduled
-     * rather than run inline because it is a 14 s synchronous statement on the
-     * one thread the cluster reads configuration through.
-     */
-    private scheduleIndexAnalysis;
-    /**
-     * Name the biggest tables, once, a minute after the connection opens.
-     *
-     * `dbSizeMb` says how big the file is and `freePct` says how much of it is
-     * live; neither says WHOSE. Per-addon scoped collections are created on first
-     * write and declared nowhere, so this is the only place the real set can be
-     * enumerated. `unref` so it can never hold the process open.
-     */
-    private scheduleStorageReport;
-    private logStorageReport;
-    private readPragmaNumber;
-    private measureDbSizeBytes;
-    private getDb;
-    /**
-     * `WHERE` fragment selecting every key that starts with `prefix`, plus its
-     * bound parameters.
-     *
-     * The range form is what makes the implicit PRIMARY KEY index usable — see
-     * `prefix-range.ts` for the `EXPLAIN QUERY PLAN` output and the measured
-     * 1.8x/19.4x. The `LIKE` fallback is the SQL that shipped before, kept
-     * verbatim for the prefixes a byte range cannot express, so a key shape this
-     * function refuses degrades in speed and never in correctness.
-     */
-    private prefixWhere;
-    private getAllScoped;
-    private setScopedKey;
-    private scopedName;
-    /**
-     * Project a declared collection onto what {@link compileFilter} needs. A
-     * collection whose only column is `data` is KV-shaped: its fields live
-     * inside that blob and are reached with `json_extract`.
-     */
-    private shapeOf;
-    /**
-     * Where a declaration LIVES, so it outlives the process that made it.
-     *
-     * `declaredCollections` used to be only an in-memory Map, and the
-     * declarations are made once, by each addon, at that addon's own boot.
-     * On 2026-09-12 this backend died with SIGBUS (a second connection
-     * truncated the WAL under its mmap) and `CrashSupervisor` respawned it: the
-     * new instance knew only the canonical KV collections, every other addon
-     * stayed up and never re-declared, and the cluster failed every settings
-     * read for six hours — the operator could not log in.
-     *
-     * The tables are durable. What the backend knows ABOUT them has to be too,
-     * because nothing in the system re-declares and nothing listens for this
-     * process restarting.
-     */
-    private static readonly DECLARATIONS_TABLE;
-    /** Create the meta table. Idempotent; called before anything reads it. */
-    private ensureDeclarationsTable;
-    /** Persist one declaration, replacing any earlier shape for the same table. */
-    private persistDeclaration;
-    /**
-     * Reload every persisted declaration. Called at init, BEFORE any addon has
-     * had the chance to re-declare — which on a respawn none of them will.
-     */
-    private restorePersistedDeclarations;
-    declareCollection(input: {
-        namespace?: string;
-        collection: string;
-        columns: readonly CollectionColumn[];
-        indexes?: readonly CollectionIndex[];
-    }): Promise<void>;
-    /** Serialise per-column values for SQL binding: objects → JSON, booleans → 0/1. */
-    private serializeColumnValue;
-    private ensureTable;
-    /**
-     * Drop a table nothing declares any more, reporting what went with it.
-     *
-     * The DDL lives here because the engine owns the handle AND the two memos
-     * that outlive a table: `structuredTables` (schema fingerprint) and
-     * `declaredCollections` (the column set `compileFilter` resolves against).
-     * Dropping behind their backs would leave a ghost — a later declaration of
-     * the same name would be memoised as "already materialised" against a table
-     * that no longer exists.
-     *
-     * WHICH tables are retired, and the logging, are policy: they live in
-     * `retired-collections.ts`. This method knows only how to drop one.
-     *
-     * Answers `null` when the table is not there — the steady state after the
-     * first boot that ran the purge, and the case on a fresh install.
-     */
-    dropRetiredTable(table: string): DroppedTable | null;
-    /** Returns SQLite's `lastInsertRowid` — the only place an auto-assigned key
-     *  is knowable (D473). */
-    private tableInsert;
-    private tableUpdate;
-    private tableDelete;
-    private tableCount;
-    private buildWhere;
+	private readonly dbPath;
+	private db;
+	/**
+	* Table name → fingerprint of the schema this process last materialised.
+	*
+	* Keyed by FINGERPRINT, not by name, and that is the whole point. An addon
+	* declares its schema at every boot, but the backend lives in hub-main,
+	* which outlives an addon respawn: `camstack deploy` restarts the addon
+	* runner and NOT hub-main. A name-only memo therefore made the second
+	* declaration of a table a no-op FOREVER — a redeployed addon whose schema
+	* had gained a column never got the `ALTER TABLE … ADD COLUMN`, and, because
+	* `compileFilter` silently drops a predicate naming a column the collection
+	* cannot express (select mode), the missing column read as "matches
+	* everything" instead of failing. That is how `pipeline-analytics:tracks`
+	* ran for a whole release with no `retrainStatus`: the retention sweep's
+	* `whereIn: { retrainStatus: ['none','trained'] }` pin evaporated, so every
+	* operator-staged track was eligible for deletion, and `countStaging`
+	* reported the entire history as staged.
+	*/
+	private readonly structuredTables;
+	/** Map from scoped collection name → set of column names (non-id) that
+	*  the structured schema owns. Routes set/get/insert/update/query to
+	*  typed columns. Every collection MUST be declared here before use. */
+	private readonly declaredCollections;
+	private readonly runtimeDefaults;
+	/**
+	* Canonical key/value collections — declared with a `(id TEXT PK,
+	* data TEXT NOT NULL)` schema at boot so existing JSON-blob rows
+	* keep working through the structured path. Generates SQL identical
+	* to the previous legacy path; only the routing is unified.
+	*/
+	private static readonly CANONICAL_KV_COLLECTIONS;
+	/**
+	* Optional, because the engine is constructed in places that have no addon
+	* context (migrations, one-shot tools, most specs). It is NOT optional in
+	* production: `sqlite-settings.addon.ts` passes one, and without it a row cap
+	* being hit would be silent — which is the failure mode the cap exists to
+	* avoid replacing.
+	*/
+	private readonly logger;
+	/**
+	* Per-statement timing. Absent only where the backend is constructed without
+	* a logger (migrations, one-shot tools, most specs) — production always has
+	* one, because a runner that stalls with no record of what it was executing
+	* is the failure this was built for (`query-profiler.ts`).
+	*/
+	private readonly profiler;
+	constructor(dbPath: string, runtimeDefaults?: Record<string, unknown>, logger?: IScopedLogger);
+	initialize(): Promise<void>;
+	private requireDeclared;
+	/**
+	* Decode a single column value off a SQLite row into the JS shape the
+	* caller's schema expects. Handles:
+	*   - BOOLEAN columns: `0|1` → `false|true`
+	*   - JSON columns (TEXT starting with `{` / `[`): parse
+	*   - everything else: pass-through with null coalescing
+	*/
+	private decodeColumnValue;
+	shutdown(): Promise<void>;
+	/**
+	* The statement profiler, so an addon sharing this handle (the sqlite-vec
+	* index) reports into the SAME window. Two profilers on one thread would
+	* each describe a fraction of the stall and neither would add up to it.
+	*/
+	getProfiler(): SqliteOpProfiler | undefined;
+	/**
+	* `data-store-provider` self-description — how the orchestrator names
+	* this engine in a log line, and (once collections declare an engine)
+	* how it picks between registrants.
+	*/
+	getEngineInfo(): Promise<DataStoreEngineInfo>;
+	get({ namespace, collection, key }: SettingsGetInput): Promise<unknown>;
+	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<{
+		readonly id: string | number;
+	}>;
+	/**
+	* Make a SLOT hold this row, and answer with the id the row HAS — one
+	* statement, `INSERT … ON CONFLICT(<slot>) DO UPDATE … RETURNING <pk>`.
+	*
+	* See `settings-store.cap.ts`'s `upsert` docblock for why the store needed a
+	* slot that is not the primary key (D482). Three things are load-bearing
+	* here:
+	*
+	*  - **`RETURNING` and not `lastInsertRowid`.** On the UPDATE branch
+	*    `lastInsertRowid` is whatever the connection last inserted — a
+	*    different row, or a different TABLE. It answers confidently and wrongly,
+	*    which is worse than not answering. `RETURNING` names the row this
+	*    statement actually touched, on both branches.
+	*  - **The conflict columns are checked against the declaration** before they
+	*    reach the SQL. An undeclared name would be interpolated into DDL-shaped
+	*    text; it is refused, by the same rule and for the same reason
+	*    {@link resolveProjection} throws on an unprojectable column.
+	*  - **The primary key is never part of the SET list.** An `INTEGER` rowid
+	*    alias is not in `row` at all, and on a TEXT key rewriting the id of the
+	*    row we just matched is the one update that cannot be right.
+	*/
+	upsert<T extends object = Record<string, unknown>>({ namespace, collection, conflict, record }: SettingsUpsertInput<T>): Promise<{
+		readonly id: string | number;
+	}>;
+	/**
+	* 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>;
+	/**
+	* Bulk delete. One statement, whatever the row count — this is what every
+	* retention path in the system was hand-rolling as a select-then-delete
+	* loop. The filter is compiled in `mutate` mode, so an unresolvable
+	* predicate or an empty one throws before any SQL exists.
+	*/
+	deleteWhere({ namespace, collection, filter }: SettingsDeleteWhereInput): Promise<SettingsDeleteWhereResult>;
+	/**
+	* Bulk update. Same filter contract as {@link deleteWhere}.
+	*
+	* Every key of `data` must be a REAL column. A KV-shaped collection keeps
+	* its fields inside a JSON blob, and setting one would need `json_set` with
+	* read-modify-write semantics this method does not have — so it refuses
+	* rather than writing a column that does not exist, which is what the
+	* uncapped `tableUpdate` would have done.
+	*/
+	updateWhere({ namespace, collection, filter, data }: SettingsUpdateWhereInput): Promise<SettingsUpdateWhereResult>;
+	/**
+	* How many rows match — about the SAME rows {@link query} would return.
+	*
+	* That agreement is the entire contract, and until now it did not hold. This
+	* was the FOURTH hand-rolled copy of the filter logic (after `query`, the
+	* bulk mutations and `histogram`) and it compiled only `where`:
+	* `whereBetween`, `whereIn` and `whereNot` were dropped silently, so the
+	* count was not slow, it was WRONG, and always wrong in the same direction —
+	* too big, because every dropped predicate is a predicate that would have
+	* excluded rows.
+	*
+	* Two live callers decided on it. `TrackStore.countStaging({ deviceId,
+	* olderThanMs })` sends the cutoff as `whereBetween: { lastSeen: [0, …] }`
+	* and got the device's whole staging history instead. The notification-centre
+	* artefact gallery pages on `total` from this method while listing through
+	* `query`, and its filter is almost entirely `whereIn`/`whereBetween`
+	* (visibility, kind, device, time window, expiry) — so `total` counted rows
+	* the page could never show, including other users'.
+	*
+	* `measure` mode. `count` compiles the same predicates `query` does — the
+	* two must never disagree about WHICH rows they are talking about — but it
+	* refuses a predicate it cannot express rather than skipping it. `query`
+	* hands back rows and a caller can see the filter did not bite; a count
+	* hands back a number, and the whole collection and the intended subset are
+	* the same shape.
+	*/
+	count({ namespace, collection, filter }: SettingsCountInput): Promise<number>;
+	/**
+	* `COUNT(*)` and one SUM/MIN/MAX per requested field, in ONE statement.
+	*
+	* Result slots are aliased POSITIONALLY (`a0`, `a1`, …) and mapped back by
+	* index: `as` is caller text and must never reach SQL as an identifier, and
+	* the column name is validated through {@link fieldExprFor} exactly like a
+	* projection — an unresolvable field THROWS rather than being dropped, because
+	* a missing aggregate comes back as a number that looks real.
+	*
+	* `measure` mode on the filter, so this agrees with `query` and `count`
+	* about which rows it is talking about — and, since 2026-08-30, refuses an
+	* unresolvable PREDICATE for the same reason it already refused an
+	* unresolvable FIELD. Both come back as a number that looks real.
+	*/
+	aggregate({ namespace, collection, fields, filter }: SettingsAggregateInput): Promise<SettingsAggregateResult>;
+	histogram({ namespace, collection, field, bucketSize, origin, filter }: SettingsHistogramInput): Promise<readonly HistogramBucket[]>;
+	isEmpty({ namespace, collection }: SettingsIsEmptyInput): Promise<boolean>;
+	private queryDeclared;
+	/** Get a system setting by dot-notation key */
+	getSystem(key: string): unknown;
+	/** Set a system setting */
+	setSystem(key: string, value: unknown): void;
+	/** Get all system settings as flat key-value */
+	getAllSystem(): Record<string, unknown>;
+	/**
+	* Get all settings for an addon.
+	*
+	* Selected by the SAME key range {@link setAllAddon} deletes and re-inserts
+	* — `prefixWhere("<addonId>.")` — and for the same reason `getAllScoped`
+	* uses it: `"<addonId>.<key>"` is the PRIMARY KEY, so the range is a
+	* `SEARCH … USING INDEX` while anything else is a full `SCAN`.
+	*
+	* It used to select on `json_extract(data, '$.addonId')`, which is a second
+	* authority for "this addon's rows" and disagreed with the writer in both
+	* directions: a row inside the JSON's idea of the addon but outside the key
+	* range was READ and never DELETED (a config key that could not be cleared),
+	* and `json_extract` was evaluated on EVERY row — so a four-key addon paid
+	* for the whole table and one unparseable neighbour aborted the statement,
+	* taking out every addon's config read at once.
+	*
+	* The cost was not theoretical. On the live hub `addon-settings` is 627 KB
+	* in 24 rows, 625 KB of it device-manager's three fleet blobs; a V8 profile
+	* of a boot (2026-08-19) had hub-main's JS thread 99.9% busy with **64% of
+	* it inside this method**, which is what put a ~45 s queue in front of every
+	* runner's first store read. Measured on that table: 0.947 ms → ~0.02 ms for
+	* a four-key addon, 2.90 ms → 2.13 ms for device-manager's own.
+	*/
+	getAllAddon(addonId: string): Record<string, unknown>;
+	/** Bulk-set all settings for an addon */
+	setAllAddon(addonId: string, config: Record<string, unknown>): void;
+	/** Get all settings for a provider */
+	getAllProvider(providerId: string): Record<string, unknown>;
+	/** Set a provider setting */
+	setProvider(providerId: string, key: string, value: unknown): void;
+	/** Get all settings for a device */
+	getAllDevice(deviceId: string): Record<string, unknown>;
+	/** Set a device setting */
+	setDevice(deviceId: string, key: string, value: unknown): void;
+	getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
+	setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
+	clearAddonDevice(addonId: string, deviceId: string): void;
+	private static readonly LEGACY_RUNTIME_STATE_ADDON_ID;
+	/**
+	* The device's whole cap-slice map. Canonical row first, legacy prefix as the
+	* fallback. `{}` — never null — when the device has never persisted a slice,
+	* because every caller treats the result as a cap map to iterate.
+	*/
+	getDeviceRuntimeState(deviceId: string): Record<string, unknown>;
+	/**
+	* Replace the device's whole cap-slice map. Replace, not merge — the caller
+	* always hands over the full persistable blob, and merging would resurrect a
+	* slice the durability policy has since stopped persisting.
+	*/
+	setDeviceRuntimeState(deviceId: string, blob: Record<string, unknown>): void;
+	/** Forget the device's runtime state in BOTH stores (device removal). */
+	clearDeviceRuntimeState(deviceId: string): void;
+	/** Seed system-settings with runtime defaults (first boot) */
+	private seedDefaults;
+	/**
+	* Expose the raw better-sqlite3 Database instance for components that
+	* need direct SQL access (e.g. DeviceStore, ConfigStore).
+	* Returns null if the backend has not been initialized yet.
+	*/
+	getDatabase(): Database.Database | null;
+	/**
+	* `EXPLAIN QUERY PLAN` for a statement, as one string per plan row.
+	*
+	* Answers the question the timing alone cannot: "1.6 s for 501 rows" is a
+	* full scan and is also a cold disk, and only the plan tells them apart. It
+	* runs on the SAME connection as the statement, because that is the only
+	* connection whose `sqlite_stat1` visibility and temp schema match.
+	*
+	* `EXPLAIN QUERY PLAN` prepares and plans; it does not execute the statement,
+	* so it costs no page reads of its own. In production it is called only from
+	* the slow-call path, once per shape per window; it is public so a guard can
+	* assert that a declared index is the one the planner actually picks — "we
+	* added an index" and "the query uses it" are different claims.
+	*
+	* Never throws. A plan that cannot be taken (a statement the engine will no
+	* longer prepare, a closed handle mid-shutdown) is a missing ANSWER, not a
+	* failure worth turning a slow query into a crash — the profiler falls back
+	* to the line it would have printed anyway.
+	*/
+	explainQueryPlan(sql: string, params: readonly unknown[]): readonly string[];
+	/**
+	* Run one synchronous statement under the profiler.
+	*
+	* A thin pass-through when no profiler exists, so the specs that construct
+	* this backend without a logger keep exercising the SAME code path as
+	* production. The alternative — two call shapes — is how a fix gets tested
+	* on a branch production never takes.
+	*/
+	private measured;
+	/**
+	* Size of the database file, or 0 when it cannot be read.
+	*
+	* 0 is the honest answer for a first boot (no file yet) and for an
+	* unreadable `stat`, and both callers treat it as "unknown" and fall back to
+	* the floor — never to a smaller setting than the one already argued for.
+	*/
+	/**
+	* One numeric PRAGMA off the open connection. A pragma that does not answer
+	* with a number yields 0, which `sqliteOccupancy` reads as "unknown" and
+	* reports as an empty file rather than inventing a ratio.
+	*/
+	/**
+	* Follow the file as it grows.
+	*
+	* The map is derived from the file at OPEN and never again, which is the same
+	* expiry one level up: a database that grows during uptime keeps the map it
+	* had at boot, and once the file passes it every read outside the window
+	* costs a synchronous page-in — 418 per second, measured 2026-08-25. This
+	* node escaped it only because 130 MB → 858 MB spanned seventeen days of
+	* restarts.
+	*
+	* `unref` so it never holds the process open.
+	*/
+	private scheduleMapGrowthCheck;
+	/**
+	* One-shot `ANALYZE`, long after boot, only if the database has none.
+	*
+	* `analyze-stats.ts` has the measurement that justifies it: without
+	* `sqlite_stat1` the planner walked 150 133 media rows to return six, and one
+	* `ANALYZE` took that same query from 727 ms to 3.2 ms. It is scheduled
+	* rather than run inline because it is a 14 s synchronous statement on the
+	* one thread the cluster reads configuration through.
+	*/
+	private scheduleIndexAnalysis;
+	/**
+	* Name the biggest tables, once, a minute after the connection opens.
+	*
+	* `dbSizeMb` says how big the file is and `freePct` says how much of it is
+	* live; neither says WHOSE. Per-addon scoped collections are created on first
+	* write and declared nowhere, so this is the only place the real set can be
+	* enumerated. `unref` so it can never hold the process open.
+	*/
+	private scheduleStorageReport;
+	private logStorageReport;
+	private readPragmaNumber;
+	private measureDbSizeBytes;
+	private getDb;
+	/**
+	* `WHERE` fragment selecting every key that starts with `prefix`, plus its
+	* bound parameters.
+	*
+	* The range form is what makes the implicit PRIMARY KEY index usable — see
+	* `prefix-range.ts` for the `EXPLAIN QUERY PLAN` output and the measured
+	* 1.8x/19.4x. The `LIKE` fallback is the SQL that shipped before, kept
+	* verbatim for the prefixes a byte range cannot express, so a key shape this
+	* function refuses degrades in speed and never in correctness.
+	*/
+	private prefixWhere;
+	private getAllScoped;
+	private setScopedKey;
+	private scopedName;
+	/**
+	* Project a declared collection onto what {@link compileFilter} needs. A
+	* collection whose only column is `data` is KV-shaped: its fields live
+	* inside that blob and are reached with `json_extract`.
+	*/
+	private shapeOf;
+	/**
+	* Where a declaration LIVES, so it outlives the process that made it.
+	*
+	* `declaredCollections` used to be only an in-memory Map, and the
+	* declarations are made once, by each addon, at that addon's own boot.
+	* On 2026-09-12 this backend died with SIGBUS (a second connection
+	* truncated the WAL under its mmap) and `CrashSupervisor` respawned it: the
+	* new instance knew only the canonical KV collections, every other addon
+	* stayed up and never re-declared, and the cluster failed every settings
+	* read for six hours — the operator could not log in.
+	*
+	* The tables are durable. What the backend knows ABOUT them has to be too,
+	* because nothing in the system re-declares and nothing listens for this
+	* process restarting.
+	*/
+	private static readonly DECLARATIONS_TABLE;
+	/** Create the meta table. Idempotent; called before anything reads it. */
+	private ensureDeclarationsTable;
+	/** Persist one declaration, replacing any earlier shape for the same table. */
+	private persistDeclaration;
+	/**
+	* Reload every persisted declaration. Called at init, BEFORE any addon has
+	* had the chance to re-declare — which on a respawn none of them will.
+	*/
+	private restorePersistedDeclarations;
+	declareCollection(input: {
+		namespace?: string;
+		collection: string;
+		columns: readonly CollectionColumn[];
+		indexes?: readonly CollectionIndex[];
+	}): Promise<void>;
+	/** Serialise per-column values for SQL binding: objects → JSON, booleans → 0/1. */
+	private serializeColumnValue;
+	private ensureTable;
+	/**
+	* Drop a table nothing declares any more, reporting what went with it.
+	*
+	* The DDL lives here because the engine owns the handle AND the two memos
+	* that outlive a table: `structuredTables` (schema fingerprint) and
+	* `declaredCollections` (the column set `compileFilter` resolves against).
+	* Dropping behind their backs would leave a ghost — a later declaration of
+	* the same name would be memoised as "already materialised" against a table
+	* that no longer exists.
+	*
+	* WHICH tables are retired, and the logging, are policy: they live in
+	* `retired-collections.ts`. This method knows only how to drop one.
+	*
+	* Answers `null` when the table is not there — the steady state after the
+	* first boot that ran the purge, and the case on a fresh install.
+	*/
+	dropRetiredTable(table: string): DroppedTable | null;
+	/** Returns SQLite's `lastInsertRowid` — the only place an auto-assigned key
+	*  is knowable (D473). */
+	private tableInsert;
+	private tableUpdate;
+	private tableDelete;
+	private tableCount;
+	private buildWhere;
 }
 export default SqliteSettingsBackend;