@camstack/system 1.2.29 → 1.2.31

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/integration-registry.d.ts

@@ -1,7 +1,7 @@
-import { Integration, PersistedDevice, CreateIntegrationInput, CreateDeviceInput, IIntegrationRegistry, ISettingsBackend } from '@camstack/types';
+import { Integration, PersistedDevice, CreateIntegrationInput, CreateDeviceInput, IIntegrationRegistry, ISettingsStoreProvider } from '@camstack/types';
 export declare class IntegrationRegistry implements IIntegrationRegistry {
-    private readonly backend;
-    constructor(backend: ISettingsBackend);
+    private readonly store;
+    constructor(backend: ISettingsStoreProvider);
     initialize(): Promise<void>;
     createIntegration(input: CreateIntegrationInput): Promise<Integration>;
     getIntegration(id: string): Promise<Integration | null>;

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

@@ -1,5 +1,25 @@
 import { default as Database } from 'better-sqlite3';
-import { DataStoreEngineInfo, ISettingsBackend, SettingsRecord, TableSchema, TableQueryOptions, SettingsGetInput, SettingsSetInput, SettingsQueryInput, SettingsInsertInput, SettingsUpdateInput, SettingsDeleteInput, SettingsCountInput, SettingsIsEmptyInput, SettingsHistogramInput, HistogramBucket, CollectionColumn, CollectionIndex } from '@camstack/types';
+import { DataStoreEngineInfo, ISettingsBackend, SettingsRecord, 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.
  *
@@ -51,6 +71,23 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
     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>;
@@ -88,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;
@@ -96,13 +139,11 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
     }): Promise<void>;
     /** Serialise per-column values for SQL binding: objects → JSON, booleans → 0/1. */
     private serializeColumnValue;
-    ensureTable(table: string, schema: TableSchema): Promise<void>;
-    tableInsert(table: string, row: Record<string, unknown>): Promise<void>;
-    tableUpdate(table: string, filter: Record<string, unknown>, updates: Record<string, unknown>): Promise<number>;
-    tableDelete(table: string, filter: Record<string, unknown>): Promise<number>;
-    tableQuery(table: string, options?: TableQueryOptions): Promise<readonly Record<string, unknown>[]>;
-    tableGet(table: string, filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-    tableCount(table: string, filter?: Record<string, unknown>): Promise<number>;
+    private ensureTable;
+    private tableInsert;
+    private tableUpdate;
+    private tableDelete;
+    private tableCount;
     private buildWhere;
 }
 export default SqliteSettingsBackend;

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-CPmFYLqq.js");
+const require_dist = require("../../dist-CDv5YTHQ.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)) ?? {};
@@ -189,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);
@@ -216,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,
@@ -255,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}`;
 			}
@@ -467,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;
@@ -482,7 +536,8 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 				type: c.type === "JSON" ? "TEXT" : c.type === "BOOLEAN" ? "INTEGER" : c.type,
 				...c.primaryKey !== void 0 ? { primaryKey: c.primaryKey } : {},
 				...c.notNull !== void 0 ? { notNull: c.notNull } : {},
-				...c.unique !== void 0 ? { unique: c.unique } : {}
+				...c.unique !== void 0 ? { unique: c.unique } : {},
+				...c.defaultValue !== void 0 ? { defaultValue: c.defaultValue } : {}
 			})),
 			...input.indexes ? { indexes: input.indexes.map((i) => ({
 				name: i.name,
@@ -567,29 +622,6 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const { whereSql, whereValues } = this.buildWhere(filter);
 		return this.getDb().prepare(`DELETE FROM "${table}"${whereSql}`).run(...whereValues).changes;
 	}
-	async tableQuery(table, options) {
-		let sql = `SELECT * FROM "${table}"`;
-		const values = [];
-		if (options?.where) {
-			const { whereSql, whereValues } = this.buildWhere(options.where);
-			sql += whereSql;
-			values.push(...whereValues);
-		}
-		if (options?.orderBy) sql += ` ORDER BY "${options.orderBy.field}" ${options.orderBy.direction === "desc" ? "DESC" : "ASC"}`;
-		if (options?.limit !== void 0) {
-			sql += ` LIMIT ?`;
-			values.push(options.limit);
-		}
-		if (options?.offset !== void 0) {
-			sql += ` OFFSET ?`;
-			values.push(options.offset);
-		}
-		return this.getDb().prepare(sql).all(...values).flatMap((r) => require_dist.asJsonObject(r) ? [require_dist.asJsonObject(r)] : []);
-	}
-	async tableGet(table, filter) {
-		const { whereSql, whereValues } = this.buildWhere(filter);
-		return require_dist.asJsonObject(this.getDb().prepare(`SELECT * FROM "${table}"${whereSql} LIMIT 1`).get(...whereValues));
-	}
 	async tableCount(table, filter) {
 		let sql = `SELECT COUNT(*) as count FROM "${table}"`;
 		const values = [];

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

@@ -1,6 +1,62 @@
-import { Dt as parseJsonUnknown, at as errMsg, c as RUNTIME_DEFAULTS, gt as asJsonObject, ot as BaseAddon, x as dataStoreProviderCapability } from "../../dist-B7hOpr5i.mjs";
+import { Dt as parseJsonUnknown, at as errMsg, c as RUNTIME_DEFAULTS, gt as asJsonObject, ot as BaseAddon, x as dataStoreProviderCapability } from "../../dist-CNmXITJ-.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)) ?? {};
@@ -183,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);
@@ -210,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,
@@ -249,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}`;
 			}
@@ -461,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;
@@ -476,7 +530,8 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 				type: c.type === "JSON" ? "TEXT" : c.type === "BOOLEAN" ? "INTEGER" : c.type,
 				...c.primaryKey !== void 0 ? { primaryKey: c.primaryKey } : {},
 				...c.notNull !== void 0 ? { notNull: c.notNull } : {},
-				...c.unique !== void 0 ? { unique: c.unique } : {}
+				...c.unique !== void 0 ? { unique: c.unique } : {},
+				...c.defaultValue !== void 0 ? { defaultValue: c.defaultValue } : {}
 			})),
 			...input.indexes ? { indexes: input.indexes.map((i) => ({
 				name: i.name,
@@ -561,29 +616,6 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const { whereSql, whereValues } = this.buildWhere(filter);
 		return this.getDb().prepare(`DELETE FROM "${table}"${whereSql}`).run(...whereValues).changes;
 	}
-	async tableQuery(table, options) {
-		let sql = `SELECT * FROM "${table}"`;
-		const values = [];
-		if (options?.where) {
-			const { whereSql, whereValues } = this.buildWhere(options.where);
-			sql += whereSql;
-			values.push(...whereValues);
-		}
-		if (options?.orderBy) sql += ` ORDER BY "${options.orderBy.field}" ${options.orderBy.direction === "desc" ? "DESC" : "ASC"}`;
-		if (options?.limit !== void 0) {
-			sql += ` LIMIT ?`;
-			values.push(options.limit);
-		}
-		if (options?.offset !== void 0) {
-			sql += ` OFFSET ?`;
-			values.push(options.offset);
-		}
-		return this.getDb().prepare(sql).all(...values).flatMap((r) => asJsonObject(r) ? [asJsonObject(r)] : []);
-	}
-	async tableGet(table, filter) {
-		const { whereSql, whereValues } = this.buildWhere(filter);
-		return asJsonObject(this.getDb().prepare(`SELECT * FROM "${table}"${whereSql} LIMIT 1`).get(...whereValues));
-	}
 	async tableCount(table, filter) {
 		let sql = `SELECT COUNT(*) as count FROM "${table}"`;
 		const values = [];