ugly-app 0.1.821 → 0.1.823

package/src/server/sqlite/SqliteFilter.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { translateFilter, translateSort, collectJsonFields } from './SqliteFilter.js';
+
+describe('SqliteFilter.translateFilter', () => {
+  it('empty filter → empty where', () => {
+    expect(translateFilter({})).toEqual({ where: '', values: [] });
+  });
+
+  it('bare string equality uses json_extract with ? placeholder', () => {
+    const r = translateFilter({ name: 'hi' });
+    expect(r.where).toBe("json_extract(data,'$.name') = ?");
+    expect(r.values).toEqual(['hi']);
+  });
+
+  it('_id equality uses the primary-key column', () => {
+    expect(translateFilter({ _id: 'abc' })).toEqual({
+      where: '_id = ?',
+      values: ['abc'],
+    });
+  });
+
+  it('number equality compares typed json_extract', () => {
+    const r = translateFilter({ age: 5 });
+    expect(r.where).toBe("json_extract(data,'$.age') = ?");
+    expect(r.values).toEqual([5]);
+  });
+
+  it('boolean equality normalizes operand to 1/0', () => {
+    expect(translateFilter({ ok: true }).values).toEqual([1]);
+    expect(translateFilter({ ok: false }).values).toEqual([0]);
+  });
+
+  it('{f: null} mirrors PG absent-or-string-null quirk', () => {
+    const r = translateFilter({ f: null });
+    expect(r.where).toBe(
+      "(json_type(data,'$.f') IS NULL OR json_extract(data,'$.f') = 'null')",
+    );
+    expect(r.values).toEqual([]);
+  });
+
+  it('$exists:true → key present via json_type', () => {
+    expect(translateFilter({ f: { $exists: true } }).where).toBe(
+      "json_type(data,'$.f') IS NOT NULL",
+    );
+  });
+
+  it('$exists:false → json_type IS NULL', () => {
+    expect(translateFilter({ f: { $exists: false } }).where).toBe(
+      "json_type(data,'$.f') IS NULL",
+    );
+  });
+
+  it('$ne non-null also matches missing/null', () => {
+    const r = translateFilter({ v: { $ne: 'x' } });
+    expect(r.where).toBe(
+      "(json_extract(data,'$.v') IS NULL OR json_extract(data,'$.v') != ?)",
+    );
+    expect(r.values).toEqual(['x']);
+  });
+
+  it('$gt compares typed json_extract', () => {
+    const r = translateFilter({ n: { $gt: 3 } });
+    expect(r.where).toBe("json_extract(data,'$.n') > ?");
+    expect(r.values).toEqual([3]);
+  });
+
+  it('$in matches scalar or array-valued field, binding operand twice', () => {
+    const r = translateFilter({ tag: { $in: ['a', 'b'] } });
+    expect(r.where).toBe(
+      "(json_extract(data,'$.tag') IN (?,?) OR EXISTS(SELECT 1 FROM json_each(data,'$.tag') WHERE json_each.value IN (?,?)))",
+    );
+    expect(r.values).toEqual(['a', 'b', 'a', 'b']);
+  });
+
+  it('combines multiple fields with AND', () => {
+    const r = translateFilter({ a: 1, b: 'x' });
+    expect(r.where).toBe(
+      "json_extract(data,'$.a') = ? AND json_extract(data,'$.b') = ?",
+    );
+    expect(r.values).toEqual([1, 'x']);
+  });
+});
+
+describe('SqliteFilter.translateSort', () => {
+  it('emits nulls-last for ASC (matches PG default)', () => {
+    expect(translateSort({ name: 1 })).toBe(
+      "(CAST(json_extract(data,'$.name') AS TEXT) IS NULL) ASC, CAST(json_extract(data,'$.name') AS TEXT) ASC",
+    );
+  });
+
+  it('emits nulls-first for DESC (matches PG default)', () => {
+    expect(translateSort({ name: -1 })).toBe(
+      "(CAST(json_extract(data,'$.name') AS TEXT) IS NULL) DESC, CAST(json_extract(data,'$.name') AS TEXT) DESC",
+    );
+  });
+
+  it('top-level column sorts without json_extract', () => {
+    expect(translateSort({ created: -1 })).toBe(
+      '("created" IS NULL) DESC, "created" DESC',
+    );
+  });
+});
+
+describe('SqliteFilter.collectJsonFields', () => {
+  it('returns discriminating json fields, skipping top-level and $exists-only', () => {
+    expect(
+      collectJsonFields({ a: 1, _id: 'x', b: { $exists: true }, c: { $gt: 2 } }),
+    ).toEqual(['a', 'c']);
+  });
+});

package/src/server/sqlite/SqliteFilter.ts

@@ -0,0 +1,161 @@
+/**
+ * MongoDB-style filter → SQLite WHERE clause translation.
+ *
+ * Mirrors PostgresFilter.ts's EXACT current semantics so a collection can move
+ * between the Postgres and SQLite backends with identical query results.
+ * Placeholders are `?` (accepted by both better-sqlite3 and Cloudflare D1).
+ * Pure string manipulation — MUST NOT import any DB driver (native or otherwise).
+ */
+
+export interface TranslatedFilter {
+  where: string;
+  values: unknown[];
+}
+
+const TOP_LEVEL_COLUMNS = new Set(['_id', 'created', 'updated', 'version']);
+
+/** `json_extract(data,'$.a.b')` (typed) or, in text context, cast to TEXT. */
+function jsonPath(field: string, asText = false): string {
+  if (TOP_LEVEL_COLUMNS.has(field)) return `"${field}"`;
+  const path = '$.' + field; // dot-notation maps directly to a JSON path
+  const extract = `json_extract(data,'${path}')`;
+  return asText ? `CAST(${extract} AS TEXT)` : extract;
+}
+
+/** `json_type(data,'$.f')` — NULL only when the path is ABSENT (present-null → 'null'). */
+function jsonTypePath(field: string): string {
+  return `json_type(data,'$.${field}')`;
+}
+
+function isOperatorObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value))
+    return false;
+  return Object.keys(value).some((k) => k.startsWith('$'));
+}
+
+/** SQLite has no boolean type; JSON booleans extract to 1/0. Normalize operands. */
+function normalize(value: unknown): unknown {
+  return typeof value === 'boolean' ? (value ? 1 : 0) : value;
+}
+
+function placeholders(n: number): string {
+  return Array.from({ length: n }, () => '?').join(',');
+}
+
+export function translateFilter(
+  filter: Record<string, unknown>,
+): TranslatedFilter {
+  const clauses: string[] = [];
+  const values: unknown[] = [];
+
+  for (const [field, value] of Object.entries(filter)) {
+    const acc = jsonPath(field);
+    if (isOperatorObject(value)) {
+      for (const [op, operand] of Object.entries(value)) {
+        switch (op) {
+          case '$in': {
+            const arr = (operand as unknown[]).map(normalize);
+            if (TOP_LEVEL_COLUMNS.has(field)) {
+              clauses.push(`${acc} IN (${placeholders(arr.length)})`);
+              values.push(...arr);
+            } else {
+              clauses.push(
+                `(${acc} IN (${placeholders(arr.length)}) OR EXISTS(SELECT 1 FROM json_each(data,'$.${field}') WHERE json_each.value IN (${placeholders(arr.length)})))`,
+              );
+              values.push(...arr, ...arr);
+            }
+            break;
+          }
+          case '$nin': {
+            const arr = (operand as unknown[]).map(normalize);
+            if (TOP_LEVEL_COLUMNS.has(field)) {
+              clauses.push(
+                `(${acc} IS NULL OR ${acc} NOT IN (${placeholders(arr.length)}))`,
+              );
+              values.push(...arr);
+            } else {
+              clauses.push(
+                `(${acc} IS NULL OR (${acc} NOT IN (${placeholders(arr.length)}) AND NOT EXISTS(SELECT 1 FROM json_each(data,'$.${field}') WHERE json_each.value IN (${placeholders(arr.length)}))))`,
+              );
+              values.push(...arr, ...arr);
+            }
+            break;
+          }
+          case '$gt':
+          case '$gte':
+          case '$lt':
+          case '$lte': {
+            const sqlOp = { $gt: '>', $gte: '>=', $lt: '<', $lte: '<=' }[op]!;
+            clauses.push(`${acc} ${sqlOp} ?`);
+            values.push(normalize(operand));
+            break;
+          }
+          case '$ne':
+            if (operand === null) {
+              clauses.push(
+                `(${jsonTypePath(field)} IS NOT NULL AND ${acc} != 'null')`,
+              );
+            } else {
+              clauses.push(`(${acc} IS NULL OR ${acc} != ?)`);
+              values.push(normalize(operand));
+            }
+            break;
+          case '$eq':
+            if (operand === null) {
+              clauses.push(`(${jsonTypePath(field)} IS NULL OR ${acc} = 'null')`);
+            } else {
+              const eqAcc = field === '_id' ? '_id' : acc;
+              clauses.push(`${eqAcc} = ?`);
+              values.push(normalize(operand));
+            }
+            break;
+          case '$exists':
+            clauses.push(
+              operand
+                ? `${jsonTypePath(field)} IS NOT NULL`
+                : `${jsonTypePath(field)} IS NULL`,
+            );
+            break;
+          default:
+            throw new Error(`[SqliteFilter] Unsupported filter operator: ${op}`);
+        }
+      }
+    } else if (value === null) {
+      clauses.push(`(${jsonTypePath(field)} IS NULL OR ${acc} = 'null')`);
+    } else {
+      const eqAcc = field === '_id' ? '_id' : acc;
+      clauses.push(`${eqAcc} = ?`);
+      values.push(normalize(value));
+    }
+  }
+
+  return { where: clauses.join(' AND '), values };
+}
+
+/**
+ * Field names a filter actually discriminates on (excludes top-level columns
+ * and `$exists`-only checks). Sibling of PostgresFilter.collectJsonbFields —
+ * used later by index-coverage enforcement.
+ */
+export function collectJsonFields(filter: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  for (const [field, value] of Object.entries(filter)) {
+    if (TOP_LEVEL_COLUMNS.has(field)) continue;
+    if (isOperatorObject(value)) {
+      const keys = Object.keys(value);
+      if (keys.every((k) => k === '$exists')) continue;
+    }
+    out.push(field);
+  }
+  return out;
+}
+
+export function translateSort(sort: Record<string, 1 | -1>): string {
+  return Object.entries(sort)
+    .map(([field, dir]) => {
+      const d = dir === 1 ? 'ASC' : 'DESC';
+      const expr = jsonPath(field, true); // text context — lexical, matches PG ->>'
+      return `(${expr} IS NULL) ${d}, ${expr} ${d}`;
+    })
+    .join(', ');
+}

package/src/server/sqlite/SqlitePipeline.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { translatePipeline } from './SqlitePipeline.js';
+
+describe('SqlitePipeline.translatePipeline', () => {
+  it('$match compiles a filter into WHERE with ? params', () => {
+    const { sql, values } = translatePipeline('c', [{ $match: { kind: 'a' } }]);
+    expect(sql).toContain('FROM "c"');
+    expect(sql).toContain("WHERE json_extract(data,'$.kind') = ?");
+    expect(values).toEqual(['a']);
+  });
+
+  it('$group by field with $sum builds GROUP BY + SUM(CAST REAL)', () => {
+    const { sql } = translatePipeline('c', [
+      { $group: { _id: '$kind', total: { $sum: '$amount' } } },
+    ]);
+    expect(sql).toContain(`json_extract(data,'$.kind') AS "_id"`);
+    expect(sql).toContain(`SUM(CAST((json_extract(data,'$.amount')) AS REAL)) AS "total"`);
+    expect(sql).toContain(`GROUP BY json_extract(data,'$.kind')`);
+  });
+
+  it('$group _id:null yields NULL AS "_id" and no GROUP BY', () => {
+    const { sql } = translatePipeline('c', [
+      { $group: { _id: null, total: { $sum: '$amount' } } },
+    ]);
+    expect(sql).toContain('NULL AS "_id"');
+    expect(sql).not.toContain('GROUP BY');
+  });
+
+  it('$count wraps the query in a COUNT(*) subquery', () => {
+    const { sql } = translatePipeline('c', [
+      { $match: { kind: 'a' } },
+      { $count: 'n' },
+    ]);
+    expect(sql).toContain('COUNT(*) AS "n"');
+    expect(sql).toContain('AS _counted');
+  });
+
+  it('$sort emits nulls-last ASC (lexical text cast)', () => {
+    const { sql } = translatePipeline('c', [{ $sort: { name: 1 } }]);
+    expect(sql).toContain(
+      `ORDER BY (CAST(json_extract(data,'$.name') AS TEXT) IS NULL) ASC, CAST(json_extract(data,'$.name') AS TEXT) ASC`,
+    );
+  });
+
+  it('$limit and $skip inline as LIMIT/OFFSET', () => {
+    const { sql } = translatePipeline('c', [{ $limit: 5 }, { $skip: 2 }]);
+    expect(sql).toContain('LIMIT 5');
+    expect(sql).toContain('OFFSET 2');
+  });
+
+  it('rejects an unsupported stage', () => {
+    expect(() => translatePipeline('c', [{ $unwind: '$x' }])).toThrow(/Unsupported/);
+  });
+});

package/src/server/sqlite/SqlitePipeline.ts

@@ -0,0 +1,172 @@
+/**
+ * MongoDB aggregation pipeline → SQLite SQL. Mirrors PostgresPipeline.ts's MVP
+ * subset ($match/$sort/$limit/$skip/$count/$group with $sum/$avg/$min/$max).
+ * `?` placeholders (positional, consumed in order — no $n renumbering). Pure —
+ * no DB, no native import.
+ */
+import { translateFilter } from './SqliteFilter.js';
+
+const TOP_LEVEL_COLUMNS = new Set(['_id', 'created', 'updated', 'version']);
+
+function jsonPath(field: string, asText = false): string {
+  if (TOP_LEVEL_COLUMNS.has(field)) return `"${field}"`;
+  const extract = `json_extract(data,'$.${field}')`;
+  return asText ? `CAST(${extract} AS TEXT)` : extract;
+}
+
+interface QueryParts {
+  select: string;
+  from: string;
+  where: string[];
+  groupBy: string[];
+  orderBy: string[];
+  limit: number | null;
+  offset: number | null;
+  values: unknown[];
+  grouped: boolean;
+}
+
+function buildSql(p: QueryParts): string {
+  let sql = `SELECT ${p.select} FROM ${p.from}`;
+  if (p.where.length > 0) sql += ` WHERE ${p.where.join(' AND ')}`;
+  if (p.groupBy.length > 0) sql += ` GROUP BY ${p.groupBy.join(', ')}`;
+  if (p.orderBy.length > 0) sql += ` ORDER BY ${p.orderBy.join(', ')}`;
+  if (p.limit !== null) sql += ` LIMIT ${p.limit}`;
+  if (p.offset !== null) sql += ` OFFSET ${p.offset}`;
+  return sql;
+}
+
+function wrapAsSubquery(p: QueryParts): QueryParts {
+  const inner = buildSql(p);
+  return {
+    select: '*',
+    from: `(${inner}) AS _sub`,
+    where: [],
+    groupBy: [],
+    orderBy: [],
+    limit: null,
+    offset: null,
+    values: [...p.values],
+    grouped: false,
+  };
+}
+
+function resolveAccumulator(acc: Record<string, unknown>): string {
+  const [op, field] = Object.entries(acc)[0]!;
+  const col =
+    typeof field === 'string' && field.startsWith('$')
+      ? jsonPath(field.slice(1))
+      : String(field);
+  switch (op) {
+    case '$sum':
+      if (typeof field === 'number') return String(field); // mirror PG quirk
+      return `SUM(CAST((${col}) AS REAL))`;
+    case '$avg':
+      return `AVG(CAST((${col}) AS REAL))`;
+    case '$min':
+      return `MIN(CAST((${col}) AS REAL))`;
+    case '$max':
+      return `MAX(CAST((${col}) AS REAL))`;
+    default:
+      throw new Error(`[SqlitePipeline] Unsupported accumulator: ${op}`);
+  }
+}
+
+function orderByExpr(field: string, dir: number, fromSub: boolean): string {
+  const d = dir === 1 ? 'ASC' : 'DESC';
+  const expr = fromSub ? `"${field}"` : jsonPath(field, true);
+  return `(${expr} IS NULL) ${d}, ${expr} ${d}`;
+}
+
+export function translatePipeline(
+  collection: string,
+  pipeline: Record<string, unknown>[],
+  options?: { skip?: number; limit?: number },
+): { sql: string; values: unknown[] } {
+  const parts: QueryParts = {
+    select: '_id, data, created, updated, version',
+    from: `"${collection}"`,
+    where: [],
+    groupBy: [],
+    orderBy: [],
+    limit: null,
+    offset: null,
+    values: [],
+    grouped: false,
+  };
+
+  for (const stage of pipeline) {
+    const [key, value] = Object.entries(stage)[0]!;
+    switch (key) {
+      case '$match': {
+        if (parts.grouped) Object.assign(parts, wrapAsSubquery(parts));
+        const f = translateFilter(value as Record<string, unknown>);
+        if (f.where) {
+          parts.where.push(f.where);
+          parts.values.push(...f.values);
+        }
+        break;
+      }
+      case '$sort': {
+        if (parts.grouped) Object.assign(parts, wrapAsSubquery(parts));
+        const fromSub = parts.from.includes('_sub');
+        parts.orderBy = Object.entries(value as Record<string, number>).map(
+          ([field, dir]) => orderByExpr(field, dir, fromSub),
+        );
+        break;
+      }
+      case '$limit':
+        parts.limit = value as number;
+        break;
+      case '$skip':
+        parts.offset = value as number;
+        break;
+      case '$count': {
+        const inner = buildSql(parts);
+        parts.select = `COUNT(*) AS "${value as string}"`;
+        parts.from = `(${inner}) AS _counted`;
+        parts.where = [];
+        parts.groupBy = [];
+        parts.orderBy = [];
+        parts.limit = null;
+        parts.offset = null;
+        parts.grouped = false;
+        break;
+      }
+      case '$group': {
+        const group = value as Record<string, unknown>;
+        const groupId = group._id;
+        const selectParts: string[] = [];
+        const groupByParts: string[] = [];
+        if (groupId === null) {
+          selectParts.push(`NULL AS "_id"`);
+        } else if (typeof groupId === 'string' && groupId.startsWith('$')) {
+          const accessor = jsonPath(groupId.slice(1));
+          selectParts.push(`${accessor} AS "_id"`);
+          groupByParts.push(accessor);
+        } else {
+          throw new Error(
+            `[SqlitePipeline] Unsupported $group _id: ${JSON.stringify(groupId)}`,
+          );
+        }
+        for (const [alias, expr] of Object.entries(group)) {
+          if (alias === '_id') continue;
+          selectParts.push(
+            `${resolveAccumulator(expr as Record<string, unknown>)} AS "${alias}"`,
+          );
+        }
+        parts.select = selectParts.join(', ');
+        parts.groupBy = groupByParts;
+        parts.grouped = true;
+        break;
+      }
+      default:
+        throw new Error(`[SqlitePipeline] Unsupported pipeline stage: ${key}`);
+    }
+  }
+
+  if (options?.skip !== undefined) parts.offset = options.skip;
+  if (options?.limit !== undefined) parts.limit = options.limit;
+
+  return { sql: buildSql(parts), values: parts.values };
+}

package/src/server/sqlite/SqliteSchema.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { fieldIndexStatements, ensureSqliteIndexes } from './SqliteSchema.js';
+import { makeBetterSqliteExec, type SqliteExec } from './SqliteExec.js';
+import { ensureSqliteTable, sqliteInsertRaw } from './SqliteDoc.js';
+
+describe('fieldIndexStatements', () => {
+  it('emits a single-field expression index', () => {
+    expect(fieldIndexStatements('post', [{ fields: { status: 1 } }])).toEqual([
+      `CREATE INDEX IF NOT EXISTS "idx_post_status" ON "post" ((json_extract(data,'$.status')))`,
+    ]);
+  });
+
+  it('emits a composite index with DESC and preserves field order', () => {
+    expect(
+      fieldIndexStatements('post', [{ fields: { a: 1, b: -1 } }]),
+    ).toEqual([
+      `CREATE INDEX IF NOT EXISTS "idx_post_a_b" ON "post" ((json_extract(data,'$.a')), (json_extract(data,'$.b')) DESC)`,
+    ]);
+  });
+
+  it('marks unique indexes and names them _unique', () => {
+    expect(
+      fieldIndexStatements('post', [{ fields: { email: 1 }, unique: true }]),
+    ).toEqual([
+      `CREATE UNIQUE INDEX IF NOT EXISTS "idx_post_email_unique" ON "post" ((json_extract(data,'$.email')))`,
+    ]);
+  });
+
+  it('rejects an index whose field name is unsafe (dotted/injection)', () => {
+    expect(fieldIndexStatements('post', [{ fields: { 'a.b': 1 } }])).toEqual([]);
+  });
+});
+
+describe('ensureSqliteIndexes (planner uses the index)', () => {
+  let exec: SqliteExec;
+  beforeAll(async () => {
+    exec = await makeBetterSqliteExec();
+    await ensureSqliteTable(exec, 'idxt');
+    for (let i = 0; i < 300; i++) {
+      await sqliteInsertRaw(exec, 'idxt', {
+        _id: `id${i}`,
+        status: i % 3 === 0 ? 'open' : 'closed',
+        n: i,
+      });
+    }
+    await ensureSqliteIndexes(exec, 'idxt', [{ fields: { status: 1 } }]);
+  });
+
+  it('uses the expression index for a filter on the indexed field', async () => {
+    const plan = await exec.all<{ detail: string }>(
+      `EXPLAIN QUERY PLAN SELECT _id FROM "idxt" WHERE json_extract(data,'$.status') = ?`,
+      ['open'],
+    );
+    expect(plan.map((r) => r.detail).join(' ')).toMatch(/USING INDEX idx_idxt_status/);
+  });
+
+  it('scans for a filter on an unindexed field', async () => {
+    const plan = await exec.all<{ detail: string }>(
+      `EXPLAIN QUERY PLAN SELECT _id FROM "idxt" WHERE json_extract(data,'$.n') = ?`,
+      [5],
+    );
+    expect(plan.map((r) => r.detail).join(' ')).toMatch(/SCAN/);
+  });
+});

package/src/server/sqlite/SqliteSchema.ts

@@ -0,0 +1,56 @@
+/**
+ * Expression indexes a collection declares via `meta.indexes`. Mirrors
+ * schemaIndexes.fieldIndexStatements, emitting SQLite expression indexes over
+ * `json_extract(data,'$.field')` — the exact expression SqliteFilter builds, so
+ * the planner uses them (EXPLAIN QUERY PLAN → SEARCH ... USING INDEX). Pure
+ * statement builder + a thin exec runner. No native import.
+ */
+import type { IndexDef } from '../../shared/DB.js';
+import type { SqliteExec } from './SqliteExec.js';
+
+const VALID_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** Raw `CREATE [UNIQUE] INDEX` SQL for each declared (single- or multi-field) index. */
+export function fieldIndexStatements(
+  collection: string,
+  indexes?: IndexDef[],
+): string[] {
+  if (!VALID_NAME.test(collection)) return [];
+  const out: string[] = [];
+  for (const idx of indexes ?? []) {
+    const entries = Object.entries(idx.fields);
+    if (entries.length === 0) continue;
+    if (!entries.every(([field]) => VALID_NAME.test(field))) continue;
+    const unique = idx.unique ? 'UNIQUE ' : '';
+    const base = `idx_${collection}_${entries.map(([field]) => field).join('_')}`;
+    const name = idx.unique ? `${base}_unique` : base;
+    const cols = entries
+      .map(
+        ([field, dir]) =>
+          `(json_extract(data,'$.${field}'))${dir === -1 ? ' DESC' : ''}`,
+      )
+      .join(', ');
+    out.push(
+      `CREATE ${unique}INDEX IF NOT EXISTS "${name}" ON "${collection}" (${cols})`,
+    );
+  }
+  return out;
+}
+
+/** Create each declared index. Isolates a single failing index (e.g. a UNIQUE
+ *  over pre-existing duplicate data) so it never aborts the rest of the sync. */
+export async function ensureSqliteIndexes(
+  exec: SqliteExec,
+  collection: string,
+  indexes?: IndexDef[],
+): Promise<void> {
+  for (const sql of fieldIndexStatements(collection, indexes)) {
+    try {
+      await exec.run(sql);
+    } catch (err) {
+      console.warn(
+        `[SqliteSchema] index skipped for "${collection}": ${(err as Error).message}`,
+      );
+    }
+  }
+}

package/src/server/sqlite/assertIndexed.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import {
+  assertIndexed,
+  coveredFields,
+  UnindexedQueryError,
+} from './assertIndexed.js';
+import type { IndexDef } from '../../shared/DB.js';
+
+const IDX: IndexDef[] = [{ fields: { status: 1 } }, { fields: { a: 1, b: -1 } }];
+
+describe('coveredFields', () => {
+  it('credits every field of single and composite indexes', () => {
+    expect(coveredFields(IDX)).toEqual(new Set(['status', 'a', 'b']));
+  });
+});
+
+describe('assertIndexed', () => {
+  it('passes a filter on an indexed field', () => {
+    expect(() => assertIndexed('c', IDX, { status: 'open' })).not.toThrow();
+  });
+
+  it('credits the trailing field of a composite index', () => {
+    expect(() => assertIndexed('c', IDX, { b: 1 })).not.toThrow();
+  });
+
+  it('throws UnindexedQueryError on an unindexed filter field', () => {
+    expect(() => assertIndexed('c', IDX, { other: 1 })).toThrow(UnindexedQueryError);
+  });
+
+  it('names the offending field in the message', () => {
+    expect(() => assertIndexed('c', IDX, { other: 1 })).toThrow(/other/);
+  });
+
+  it('checks sort keys too', () => {
+    expect(() => assertIndexed('c', IDX, undefined, { other: 1 })).toThrow(
+      UnindexedQueryError,
+    );
+    expect(() => assertIndexed('c', IDX, undefined, { status: -1 })).not.toThrow();
+  });
+
+  it('always allows _id / created / updated (top-level columns)', () => {
+    expect(() => assertIndexed('c', IDX, { _id: 'x' }, { created: -1 })).not.toThrow();
+  });
+
+  it('ignores $exists-only filter fields', () => {
+    expect(() => assertIndexed('c', IDX, { other: { $exists: true } })).not.toThrow();
+  });
+
+  it('allowScan bypasses the check', () => {
+    expect(() =>
+      assertIndexed('c', IDX, { other: 1 }, undefined, { allowScan: true }),
+    ).not.toThrow();
+  });
+
+  it('no filter/sort → no-op', () => {
+    expect(() => assertIndexed('c', IDX)).not.toThrow();
+  });
+});