@camstack/system 1.2.28 → 1.2.30

package/dist/builtins/sqlite-storage/filter-compiler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One filter compiler for both the read and the bulk-mutation paths.
+ *
+ * It exists because those two paths must NOT behave the same way, and until
+ * now the only compiler lived inline in `query` — where being forgiving is
+ * correct. Reusing it verbatim for `deleteWhere` would have shipped two
+ * data-loss shapes:
+ *
+ *  - **A dropped predicate.** A field that is not a column of a structured
+ *    table is skipped, so `{ deviceId: 615, kind: 'motion' }` can compile to
+ *    `WHERE "deviceId" = ?` — on a SELECT that returns extra rows, on a DELETE
+ *    it removes rows the caller meant to keep.
+ *  - **No predicate at all.** An empty filter compiles to an empty WHERE,
+ *    which on a DELETE is the entire collection.
+ *
+ * `select` mode keeps the historical behaviour, because every existing caller
+ * was written against it. `mutate` mode refuses both, before any SQL exists.
+ * Emptying a collection is a legitimate thing to want, and it should be a
+ * differently-named operation rather than a filter that happens to be empty.
+ */
+/** The part of a declared collection this compiler needs. */
+export interface CollectionShape {
+    readonly primaryKey: string;
+    readonly columns: ReadonlySet<string>;
+    /**
+     * The single JSON blob column for a KV-shaped collection (fields inside it
+     * are reachable via `json_extract`), or `null` for a structured table whose
+     * fields are real columns.
+     */
+    readonly kvBlobColumn: string | null;
+}
+export type FilterMode = 'select' | 'mutate';
+/** Marshals a JS value to what the driver should bind. */
+export type SerializeValue = (value: unknown) => unknown;
+export interface QueryFilterInput {
+    readonly where?: Readonly<Record<string, unknown>>;
+    readonly whereIn?: Readonly<Record<string, readonly unknown[]>>;
+    readonly whereBetween?: Readonly<Record<string, readonly [unknown, unknown]>>;
+}
+/**
+ * The predicate-only filter a bulk mutation accepts — no ordering, no limit.
+ * Structurally the mutation half of {@link QueryFilterInput}.
+ */
+export type MutationFilterInput = QueryFilterInput;
+export interface CompiledFilter {
+    /** Either `''` or a leading-space ` WHERE …` clause, ready to concatenate. */
+    readonly whereSql: string;
+    readonly params: readonly unknown[];
+}
+/** Thrown by `mutate` mode. Distinct type so a caller can map it to a 400. */
+export declare class UnsafeFilterError extends Error {
+    constructor(message: string);
+}
+/**
+ * SQL expression for `field` on this collection, or `null` when it cannot be
+ * expressed: a real column → `"field"`; a KV blob field → `json_extract`;
+ * anything else on a structured table → unresolvable. Exported because
+ * `histogram` needs the same resolution for its bucketed column.
+ */
+export declare function fieldExprFor(field: string, shape: CollectionShape): string | null;
+export declare function compileFilter(filter: QueryFilterInput | undefined, shape: CollectionShape, mode: FilterMode, serialize: SerializeValue): CompiledFilter;

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

@@ -1,5 +1,25 @@
 import { default as Database } from 'better-sqlite3';
-import { ISettingsBackend, SettingsRecord, TableSchema, TableQueryOptions, SettingsGetInput, SettingsSetInput, SettingsQueryInput, SettingsInsertInput, SettingsUpdateInput, SettingsDeleteInput, SettingsCountInput, SettingsIsEmptyInput, SettingsHistogramInput, HistogramBucket, CollectionColumn, CollectionIndex } from '@camstack/types';
+import { DataStoreEngineInfo, ISettingsBackend, SettingsRecord, TableSchema, TableQueryOptions, SettingsGetInput, SettingsSetInput, SettingsQueryInput, SettingsInsertInput, SettingsUpdateInput, SettingsDeleteInput, SettingsCountInput, SettingsIsEmptyInput, SettingsHistogramInput, HistogramBucket, CollectionColumn, CollectionIndex } from '@camstack/types';
+import { MutationFilterInput } from './filter-compiler.js';
+/** Input for {@link SqliteSettingsBackend.deleteWhere}. */
+interface SettingsDeleteWhereInput {
+    readonly namespace?: string;
+    readonly collection: string;
+    readonly filter: MutationFilterInput;
+}
+interface SettingsDeleteWhereResult {
+    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>>;
+}
+interface SettingsUpdateWhereResult {
+    readonly updated: number;
+}
 /**
  * SQLite implementation of ISettingsBackend.
  *
@@ -39,12 +59,35 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
      */
     private decodeColumnValue;
     shutdown(): Promise<void>;
+    /**
+     * `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, }: SettingsQueryInput): Promise<readonly SettingsRecord<T>[]>;
     insert<T extends object = Record<string, unknown>>({ namespace, collection, record, }: SettingsInsertInput<T>): Promise<void>;
     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>;
     count({ namespace, collection, filter }: SettingsCountInput): Promise<number>;
     histogram({ namespace, collection, field, bucketSize, origin, filter, }: SettingsHistogramInput): Promise<readonly HistogramBucket[]>;
     isEmpty({ namespace, collection }: SettingsIsEmptyInput): Promise<boolean>;
@@ -82,6 +125,12 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
     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;
     declareCollection(input: {
         namespace?: string;
         collection: string;

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

@@ -1,8 +1,14 @@
 import { ProviderRegistration, BaseAddon } from '@camstack/types';
 import { SqliteSettingsBackend } from './sqlite-settings-backend.js';
 /**
- * SQLite Settings addon — provides persistent settings storage.
- * Capability: 'settings-store' (singleton)
+ * SQLite Settings addon — the relational ENGINE behind the data door.
+ *
+ * Capability: `data-store-provider` (collection, internal). It does not
+ * serve `settings-store`: that is the public door, owned by
+ * storage-orchestrator, which dispatches here
+ * ([D44](../../../../../docs/decisions/adr-0044.md)). Callers reach this
+ * engine only through the door — which is the point, because it is what
+ * makes the engine replaceable.
  */
 export declare class SqliteSettingsAddon extends BaseAddon {
     private backend;

package/dist/builtins/sqlite-storage/sqlite-settings.addon.js

@@ -3,10 +3,66 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BxtIzexq.js");
+const require_dist = require("../../dist-VIwdvws5.js");
 let node_crypto = require("node:crypto");
 let better_sqlite3 = require("better-sqlite3");
 better_sqlite3 = require_chunk.__toESM(better_sqlite3);
+//#region src/builtins/sqlite-storage/filter-compiler.ts
+/** Thrown by `mutate` mode. Distinct type so a caller can map it to a 400. */
+var UnsafeFilterError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UnsafeFilterError";
+	}
+};
+/**
+* SQL expression for `field` on this collection, or `null` when it cannot be
+* expressed: a real column → `"field"`; a KV blob field → `json_extract`;
+* anything else on a structured table → unresolvable. Exported because
+* `histogram` needs the same resolution for its bucketed column.
+*/
+function fieldExprFor(field, shape) {
+	if (field === shape.primaryKey || shape.columns.has(field)) return `"${field}"`;
+	if (shape.kvBlobColumn !== null) return `json_extract("${shape.kvBlobColumn}", '$.${field}')`;
+	return null;
+}
+function compileFilter(filter, shape, mode, serialize) {
+	const clauses = [];
+	const params = [];
+	const resolve = (field) => {
+		const expr = fieldExprFor(field, shape);
+		if (expr === null && mode === "mutate") throw new UnsafeFilterError(`filter refers to "${field}", which this collection cannot express — refusing to run a bulk mutation with a dropped predicate`);
+		return expr;
+	};
+	for (const [field, value] of Object.entries(filter?.where ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		clauses.push(`${expr} = ?`);
+		params.push(serialize(value));
+	}
+	for (const [field, values] of Object.entries(filter?.whereIn ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		if (values.length === 0) {
+			if (mode === "mutate") throw new UnsafeFilterError(`filter has an empty whereIn list for "${field}" — it matches nothing, which is more likely a caller bug than an intent`);
+			continue;
+		}
+		clauses.push(`${expr} IN (${values.map(() => "?").join(", ")})`);
+		for (const v of values) params.push(serialize(v));
+	}
+	for (const [field, [low, high]] of Object.entries(filter?.whereBetween ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		clauses.push(`${expr} BETWEEN ? AND ?`);
+		params.push(serialize(low), serialize(high));
+	}
+	if (clauses.length === 0 && mode === "mutate") throw new UnsafeFilterError("filter compiled to no predicate — that would affect every row in the collection; use the explicit clear operation if that is the intent");
+	return {
+		whereSql: clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "",
+		params
+	};
+}
+//#endregion
 //#region src/builtins/sqlite-storage/sqlite-settings-backend.ts
 function parseRowData(raw) {
 	return require_dist.asJsonObject(require_dist.parseJsonUnknown(raw)) ?? {};
@@ -119,6 +175,18 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		this.db?.close();
 		this.db = null;
 	}
+	/**
+	* `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.
+	*/
+	async getEngineInfo() {
+		return {
+			engineId: "sqlite",
+			kind: "relational",
+			displayName: "SQLite (WAL)"
+		};
+	}
 	async get({ namespace, collection, key }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
@@ -177,6 +245,41 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const decl = this.requireDeclared(scoped);
 		await this.tableDelete(scoped, { [decl.primaryKey]: key });
 	}
+	/**
+	* 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.
+	*/
+	async deleteWhere({ namespace, collection, filter }) {
+		const scoped = this.scopedName(namespace, collection);
+		const decl = this.requireDeclared(scoped);
+		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		return { deleted: this.getDb().prepare(`DELETE FROM "${scoped}"${whereSql}`).run(...params).changes };
+	}
+	/**
+	* 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.
+	*/
+	async updateWhere({ namespace, collection, filter, data }) {
+		const scoped = this.scopedName(namespace, collection);
+		const decl = this.requireDeclared(scoped);
+		const setClauses = [];
+		const setValues = [];
+		for (const [key, value] of Object.entries(data)) {
+			if (key !== decl.primaryKey && !decl.columns.has(key)) throw new UnsafeFilterError(`updateWhere cannot set "${key}" on "${scoped}" — it is not a column of this collection`);
+			setClauses.push(`"${key}" = ?`);
+			setValues.push(this.serializeColumnValue(value));
+		}
+		if (setClauses.length === 0) throw new UnsafeFilterError("updateWhere was given no fields to set");
+		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		return { updated: this.getDb().prepare(`UPDATE "${scoped}" SET ${setClauses.join(", ")}${whereSql}`).run(...setValues, ...params).changes };
+	}
 	async count({ namespace, collection, filter }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
@@ -204,30 +307,10 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	async histogram({ namespace, collection, field, bucketSize, origin, filter }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
-		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
-		const isColumn = (f) => f === decl.primaryKey || decl.columns.has(f);
-		const fieldExpr = (f) => {
-			if (isColumn(f)) return `"${f}"`;
-			if (isKvShape) return `json_extract("data", '$.${f}')`;
-			return "";
-		};
-		const col = fieldExpr(field);
-		if (!col) return [];
-		const params = [];
-		const clauses = [];
-		if (filter?.where) for (const [f, value] of Object.entries(filter.where)) {
-			const expr = fieldExpr(f);
-			if (!expr) continue;
-			clauses.push(`${expr} = ?`);
-			params.push(this.serializeColumnValue(value));
-		}
-		if (filter?.whereBetween) for (const [f, [lo, hi]] of Object.entries(filter.whereBetween)) {
-			const expr = fieldExpr(f);
-			if (!expr) continue;
-			clauses.push(`${expr} BETWEEN ? AND ?`);
-			params.push(this.serializeColumnValue(lo), this.serializeColumnValue(hi));
-		}
-		const where = clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+		const shape = this.shapeOf(decl);
+		const col = fieldExprFor(field, shape);
+		if (col === null) return [];
+		const { whereSql: where, params } = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
 		const sql = `SELECT ${`CAST((${col} - ?) / ? AS INTEGER)`} AS bucket, COUNT(*) AS count FROM "${scoped}"${where} GROUP BY bucket ORDER BY bucket`;
 		return this.getDb().prepare(sql).all(origin, bucketSize, ...params).map((r) => ({
 			bucket: r.bucket,
@@ -243,43 +326,13 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
 		let sql = `SELECT ${[`"${decl.primaryKey}"`, ...[...decl.columns].map((c) => `"${c}"`)].join(", ")} FROM "${table}"`;
 		const params = [];
-		const whereClauses = [];
-		const isColumn = (f) => f === decl.primaryKey || decl.columns.has(f);
-		/**
-		* SQL expression for `field` on this table.
-		*  - real column → `"field"`
-		*  - KV blob field (e.g. `username` inside `data`) → `json_extract`
-		*  - structured table + non-column → empty string (filter dropped,
-		*    matches legacy structured-table behaviour)
-		*/
-		const fieldExpr = (f) => {
-			if (isColumn(f)) return `"${f}"`;
-			if (isKvShape) return `json_extract("data", '$.${f}')`;
-			return "";
-		};
-		if (filter?.where) for (const [field, value] of Object.entries(filter.where)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			whereClauses.push(`${expr} = ?`);
-			params.push(this.serializeColumnValue(value));
-		}
-		if (filter?.whereIn) for (const [field, values] of Object.entries(filter.whereIn)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			const placeholders = values.map(() => "?").join(", ");
-			whereClauses.push(`${expr} IN (${placeholders})`);
-			for (const v of values) params.push(this.serializeColumnValue(v));
-		}
-		if (filter?.whereBetween) for (const [field, [low, high]] of Object.entries(filter.whereBetween)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			whereClauses.push(`${expr} BETWEEN ? AND ?`);
-			params.push(this.serializeColumnValue(low), this.serializeColumnValue(high));
-		}
-		if (whereClauses.length > 0) sql += ` WHERE ${whereClauses.join(" AND ")}`;
+		const shape = this.shapeOf(decl);
+		const compiled = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
+		sql += compiled.whereSql;
+		params.push(...compiled.params);
 		if (filter?.orderBy) {
-			const expr = fieldExpr(filter.orderBy.field);
-			if (expr) {
+			const expr = fieldExprFor(filter.orderBy.field, shape);
+			if (expr !== null) {
 				const dir = filter.orderBy.direction === "desc" ? "DESC" : "ASC";
 				sql += ` ORDER BY ${expr} ${dir}`;
 			}
@@ -455,6 +508,19 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	scopedName(namespace, collection) {
 		return namespace ? `${namespace}:${collection}` : collection;
 	}
+	/**
+	* 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`.
+	*/
+	shapeOf(decl) {
+		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
+		return {
+			primaryKey: decl.primaryKey,
+			columns: decl.columns,
+			kvBlobColumn: isKvShape ? "data" : null
+		};
+	}
 	async declareCollection(input) {
 		const table = this.scopedName(input.namespace, input.collection);
 		if (this.declaredCollections.has(table)) return;
@@ -605,8 +671,14 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 //#endregion
 //#region src/builtins/sqlite-storage/sqlite-settings.addon.ts
 /**
-* SQLite Settings addon — provides persistent settings storage.
-* Capability: 'settings-store' (singleton)
+* SQLite Settings addon — the relational ENGINE behind the data door.
+*
+* Capability: `data-store-provider` (collection, internal). It does not
+* serve `settings-store`: that is the public door, owned by
+* storage-orchestrator, which dispatches here
+* ([D44](../../../../../docs/decisions/adr-0044.md)). Callers reach this
+* engine only through the door — which is the point, because it is what
+* makes the engine replaceable.
 */
 var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 	backend = null;
@@ -635,7 +707,7 @@ var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 		await this.backend.initialize();
 		this.ctx.logger.info("Initialized successfully");
 		return [{
-			capability: require_dist.settingsStoreCapability,
+			capability: require_dist.dataStoreProviderCapability,
 			provider: this.backend
 		}];
 	}

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

@@ -1,6 +1,62 @@
-import { Et as parseJsonUnknown, X as settingsStoreCapability, at as BaseAddon, c as RUNTIME_DEFAULTS, ht as asJsonObject, it as errMsg } from "../../dist-BXmFvn3h.mjs";
+import { Dt as parseJsonUnknown, at as errMsg, c as RUNTIME_DEFAULTS, gt as asJsonObject, ot as BaseAddon, x as dataStoreProviderCapability } from "../../dist-Dr_P0DOB.mjs";
 import { randomUUID } from "node:crypto";
 import Database from "better-sqlite3";
+//#region src/builtins/sqlite-storage/filter-compiler.ts
+/** Thrown by `mutate` mode. Distinct type so a caller can map it to a 400. */
+var UnsafeFilterError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UnsafeFilterError";
+	}
+};
+/**
+* SQL expression for `field` on this collection, or `null` when it cannot be
+* expressed: a real column → `"field"`; a KV blob field → `json_extract`;
+* anything else on a structured table → unresolvable. Exported because
+* `histogram` needs the same resolution for its bucketed column.
+*/
+function fieldExprFor(field, shape) {
+	if (field === shape.primaryKey || shape.columns.has(field)) return `"${field}"`;
+	if (shape.kvBlobColumn !== null) return `json_extract("${shape.kvBlobColumn}", '$.${field}')`;
+	return null;
+}
+function compileFilter(filter, shape, mode, serialize) {
+	const clauses = [];
+	const params = [];
+	const resolve = (field) => {
+		const expr = fieldExprFor(field, shape);
+		if (expr === null && mode === "mutate") throw new UnsafeFilterError(`filter refers to "${field}", which this collection cannot express — refusing to run a bulk mutation with a dropped predicate`);
+		return expr;
+	};
+	for (const [field, value] of Object.entries(filter?.where ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		clauses.push(`${expr} = ?`);
+		params.push(serialize(value));
+	}
+	for (const [field, values] of Object.entries(filter?.whereIn ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		if (values.length === 0) {
+			if (mode === "mutate") throw new UnsafeFilterError(`filter has an empty whereIn list for "${field}" — it matches nothing, which is more likely a caller bug than an intent`);
+			continue;
+		}
+		clauses.push(`${expr} IN (${values.map(() => "?").join(", ")})`);
+		for (const v of values) params.push(serialize(v));
+	}
+	for (const [field, [low, high]] of Object.entries(filter?.whereBetween ?? {})) {
+		const expr = resolve(field);
+		if (expr === null) continue;
+		clauses.push(`${expr} BETWEEN ? AND ?`);
+		params.push(serialize(low), serialize(high));
+	}
+	if (clauses.length === 0 && mode === "mutate") throw new UnsafeFilterError("filter compiled to no predicate — that would affect every row in the collection; use the explicit clear operation if that is the intent");
+	return {
+		whereSql: clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "",
+		params
+	};
+}
+//#endregion
 //#region src/builtins/sqlite-storage/sqlite-settings-backend.ts
 function parseRowData(raw) {
 	return asJsonObject(parseJsonUnknown(raw)) ?? {};
@@ -113,6 +169,18 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		this.db?.close();
 		this.db = null;
 	}
+	/**
+	* `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.
+	*/
+	async getEngineInfo() {
+		return {
+			engineId: "sqlite",
+			kind: "relational",
+			displayName: "SQLite (WAL)"
+		};
+	}
 	async get({ namespace, collection, key }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
@@ -171,6 +239,41 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const decl = this.requireDeclared(scoped);
 		await this.tableDelete(scoped, { [decl.primaryKey]: key });
 	}
+	/**
+	* 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.
+	*/
+	async deleteWhere({ namespace, collection, filter }) {
+		const scoped = this.scopedName(namespace, collection);
+		const decl = this.requireDeclared(scoped);
+		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		return { deleted: this.getDb().prepare(`DELETE FROM "${scoped}"${whereSql}`).run(...params).changes };
+	}
+	/**
+	* 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.
+	*/
+	async updateWhere({ namespace, collection, filter, data }) {
+		const scoped = this.scopedName(namespace, collection);
+		const decl = this.requireDeclared(scoped);
+		const setClauses = [];
+		const setValues = [];
+		for (const [key, value] of Object.entries(data)) {
+			if (key !== decl.primaryKey && !decl.columns.has(key)) throw new UnsafeFilterError(`updateWhere cannot set "${key}" on "${scoped}" — it is not a column of this collection`);
+			setClauses.push(`"${key}" = ?`);
+			setValues.push(this.serializeColumnValue(value));
+		}
+		if (setClauses.length === 0) throw new UnsafeFilterError("updateWhere was given no fields to set");
+		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		return { updated: this.getDb().prepare(`UPDATE "${scoped}" SET ${setClauses.join(", ")}${whereSql}`).run(...setValues, ...params).changes };
+	}
 	async count({ namespace, collection, filter }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
@@ -198,30 +301,10 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	async histogram({ namespace, collection, field, bucketSize, origin, filter }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
-		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
-		const isColumn = (f) => f === decl.primaryKey || decl.columns.has(f);
-		const fieldExpr = (f) => {
-			if (isColumn(f)) return `"${f}"`;
-			if (isKvShape) return `json_extract("data", '$.${f}')`;
-			return "";
-		};
-		const col = fieldExpr(field);
-		if (!col) return [];
-		const params = [];
-		const clauses = [];
-		if (filter?.where) for (const [f, value] of Object.entries(filter.where)) {
-			const expr = fieldExpr(f);
-			if (!expr) continue;
-			clauses.push(`${expr} = ?`);
-			params.push(this.serializeColumnValue(value));
-		}
-		if (filter?.whereBetween) for (const [f, [lo, hi]] of Object.entries(filter.whereBetween)) {
-			const expr = fieldExpr(f);
-			if (!expr) continue;
-			clauses.push(`${expr} BETWEEN ? AND ?`);
-			params.push(this.serializeColumnValue(lo), this.serializeColumnValue(hi));
-		}
-		const where = clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+		const shape = this.shapeOf(decl);
+		const col = fieldExprFor(field, shape);
+		if (col === null) return [];
+		const { whereSql: where, params } = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
 		const sql = `SELECT ${`CAST((${col} - ?) / ? AS INTEGER)`} AS bucket, COUNT(*) AS count FROM "${scoped}"${where} GROUP BY bucket ORDER BY bucket`;
 		return this.getDb().prepare(sql).all(origin, bucketSize, ...params).map((r) => ({
 			bucket: r.bucket,
@@ -237,43 +320,13 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
 		let sql = `SELECT ${[`"${decl.primaryKey}"`, ...[...decl.columns].map((c) => `"${c}"`)].join(", ")} FROM "${table}"`;
 		const params = [];
-		const whereClauses = [];
-		const isColumn = (f) => f === decl.primaryKey || decl.columns.has(f);
-		/**
-		* SQL expression for `field` on this table.
-		*  - real column → `"field"`
-		*  - KV blob field (e.g. `username` inside `data`) → `json_extract`
-		*  - structured table + non-column → empty string (filter dropped,
-		*    matches legacy structured-table behaviour)
-		*/
-		const fieldExpr = (f) => {
-			if (isColumn(f)) return `"${f}"`;
-			if (isKvShape) return `json_extract("data", '$.${f}')`;
-			return "";
-		};
-		if (filter?.where) for (const [field, value] of Object.entries(filter.where)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			whereClauses.push(`${expr} = ?`);
-			params.push(this.serializeColumnValue(value));
-		}
-		if (filter?.whereIn) for (const [field, values] of Object.entries(filter.whereIn)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			const placeholders = values.map(() => "?").join(", ");
-			whereClauses.push(`${expr} IN (${placeholders})`);
-			for (const v of values) params.push(this.serializeColumnValue(v));
-		}
-		if (filter?.whereBetween) for (const [field, [low, high]] of Object.entries(filter.whereBetween)) {
-			const expr = fieldExpr(field);
-			if (!expr) continue;
-			whereClauses.push(`${expr} BETWEEN ? AND ?`);
-			params.push(this.serializeColumnValue(low), this.serializeColumnValue(high));
-		}
-		if (whereClauses.length > 0) sql += ` WHERE ${whereClauses.join(" AND ")}`;
+		const shape = this.shapeOf(decl);
+		const compiled = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
+		sql += compiled.whereSql;
+		params.push(...compiled.params);
 		if (filter?.orderBy) {
-			const expr = fieldExpr(filter.orderBy.field);
-			if (expr) {
+			const expr = fieldExprFor(filter.orderBy.field, shape);
+			if (expr !== null) {
 				const dir = filter.orderBy.direction === "desc" ? "DESC" : "ASC";
 				sql += ` ORDER BY ${expr} ${dir}`;
 			}
@@ -449,6 +502,19 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	scopedName(namespace, collection) {
 		return namespace ? `${namespace}:${collection}` : collection;
 	}
+	/**
+	* 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`.
+	*/
+	shapeOf(decl) {
+		const isKvShape = decl.columns.size === 1 && decl.columns.has("data");
+		return {
+			primaryKey: decl.primaryKey,
+			columns: decl.columns,
+			kvBlobColumn: isKvShape ? "data" : null
+		};
+	}
 	async declareCollection(input) {
 		const table = this.scopedName(input.namespace, input.collection);
 		if (this.declaredCollections.has(table)) return;
@@ -599,8 +665,14 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 //#endregion
 //#region src/builtins/sqlite-storage/sqlite-settings.addon.ts
 /**
-* SQLite Settings addon — provides persistent settings storage.
-* Capability: 'settings-store' (singleton)
+* SQLite Settings addon — the relational ENGINE behind the data door.
+*
+* Capability: `data-store-provider` (collection, internal). It does not
+* serve `settings-store`: that is the public door, owned by
+* storage-orchestrator, which dispatches here
+* ([D44](../../../../../docs/decisions/adr-0044.md)). Callers reach this
+* engine only through the door — which is the point, because it is what
+* makes the engine replaceable.
 */
 var SqliteSettingsAddon = class extends BaseAddon {
 	backend = null;
@@ -629,7 +701,7 @@ var SqliteSettingsAddon = class extends BaseAddon {
 		await this.backend.initialize();
 		this.ctx.logger.info("Initialized successfully");
 		return [{
-			capability: settingsStoreCapability,
+			capability: dataStoreProviderCapability,
 			provider: this.backend
 		}];
 	}