@typicalday/firegraph 0.15.0 → 0.16.1

package/dist/sqlite/local.d.cts

@@ -1,6 +1,6 @@
 import { Database } from 'better-sqlite3';
-import { S as StorageBackend } from '../backend-BpYLdwCW.cjs';
-import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-CvImIwTY.cjs';
+import { S as StorageBackend } from '../backend-DNzv8KSR.cjs';
+import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-EjFfw9yO.cjs';
 import '@google-cloud/firestore';
 
 /**
@@ -17,8 +17,34 @@ import '@google-cloud/firestore';
  * `journal_mode = WAL` and a `busy_timeout` applied; caller-provided
  * databases are used as-is (only `busy_timeout` is set) since the caller
  * owns their pragma configuration.
+ *
+ * ## Search capabilities
+ *
+ * On top of the shared SQLite capability set, the local backend declares
+ * `search.fullText` and `search.vector` (see `src/internal/sqlite-search.ts`
+ * for the mechanics):
+ *
+ *   - **Full-text search** is backed by one FTS5 table per graph table,
+ *     kept in sync by pure-SQL triggers installed with the table's DDL.
+ *     Because the triggers live in the database file, writes from ANY
+ *     process or connection stay indexed. The trade-off is a per-write
+ *     overhead (text extraction via `json_tree` + an FTS index update) on
+ *     every insert/update/delete.
+ *   - **Vector search** is a brute-force scan scored by a deterministic
+ *     scalar UDF registered on this connection. UDFs are connection-local:
+ *     `findNearest` only works through a backend created by this factory
+ *     (other connections to the same file can read/write normally — only
+ *     vector *search* needs the UDF).
  */
 
+/**
+ * Capability union for the local better-sqlite3 backend: everything the
+ * shared SQLite edition declares, plus native FTS5 full-text search and
+ * brute-force vector search. `search.geo` stays out — there is no geo
+ * index in stock SQLite, and a UDF-scored scan without a haversine
+ * contract pinned by Firestore parity tests would be guesswork.
+ */
+type LocalSqliteCapability = SqliteCapability | 'search.fullText' | 'search.vector';
 interface LocalSqliteBackendOptions extends SqliteBackendOptions {
     /** Root graph table name. Defaults to `'firegraph'`. */
     tableName?: string;
@@ -41,7 +67,7 @@ interface LocalSqliteBackendOptions extends SqliteBackendOptions {
 }
 interface LocalSqliteBackend {
     /** The graph storage backend — pass to `createGraphClient`. */
-    backend: StorageBackend<SqliteCapability>;
+    backend: StorageBackend<LocalSqliteCapability>;
     /** The underlying better-sqlite3 database, for raw access. */
     db: Database;
     /**
@@ -70,7 +96,7 @@ declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
  *
  * const { backend, close } = await createLocalSqliteBackend('./graph.db');
  * const client = createGraphClient(backend);
- * // ... use the client ...
+ * // ... use the client — including fullTextSearch() and findNearest() ...
  * close();
  * ```
  *
@@ -80,4 +106,4 @@ declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
  */
 declare function createLocalSqliteBackend(pathOrDb: string | Database, options?: LocalSqliteBackendOptions): Promise<LocalSqliteBackend>;
 
-export { type LocalSqliteBackend, type LocalSqliteBackendOptions, createBetterSqliteExecutor, createLocalSqliteBackend };
+export { type LocalSqliteBackend, type LocalSqliteBackendOptions, type LocalSqliteCapability, createBetterSqliteExecutor, createLocalSqliteBackend };

package/dist/sqlite/local.d.ts

@@ -1,6 +1,6 @@
 import { Database } from 'better-sqlite3';
-import { S as StorageBackend } from '../backend-BpYLdwCW.js';
-import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-YH5HtawN.js';
+import { S as StorageBackend } from '../backend-DNzv8KSR.js';
+import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-CE3pM9-T.js';
 import '@google-cloud/firestore';
 
 /**
@@ -17,8 +17,34 @@ import '@google-cloud/firestore';
  * `journal_mode = WAL` and a `busy_timeout` applied; caller-provided
  * databases are used as-is (only `busy_timeout` is set) since the caller
  * owns their pragma configuration.
+ *
+ * ## Search capabilities
+ *
+ * On top of the shared SQLite capability set, the local backend declares
+ * `search.fullText` and `search.vector` (see `src/internal/sqlite-search.ts`
+ * for the mechanics):
+ *
+ *   - **Full-text search** is backed by one FTS5 table per graph table,
+ *     kept in sync by pure-SQL triggers installed with the table's DDL.
+ *     Because the triggers live in the database file, writes from ANY
+ *     process or connection stay indexed. The trade-off is a per-write
+ *     overhead (text extraction via `json_tree` + an FTS index update) on
+ *     every insert/update/delete.
+ *   - **Vector search** is a brute-force scan scored by a deterministic
+ *     scalar UDF registered on this connection. UDFs are connection-local:
+ *     `findNearest` only works through a backend created by this factory
+ *     (other connections to the same file can read/write normally — only
+ *     vector *search* needs the UDF).
  */
 
+/**
+ * Capability union for the local better-sqlite3 backend: everything the
+ * shared SQLite edition declares, plus native FTS5 full-text search and
+ * brute-force vector search. `search.geo` stays out — there is no geo
+ * index in stock SQLite, and a UDF-scored scan without a haversine
+ * contract pinned by Firestore parity tests would be guesswork.
+ */
+type LocalSqliteCapability = SqliteCapability | 'search.fullText' | 'search.vector';
 interface LocalSqliteBackendOptions extends SqliteBackendOptions {
     /** Root graph table name. Defaults to `'firegraph'`. */
     tableName?: string;
@@ -41,7 +67,7 @@ interface LocalSqliteBackendOptions extends SqliteBackendOptions {
 }
 interface LocalSqliteBackend {
     /** The graph storage backend — pass to `createGraphClient`. */
-    backend: StorageBackend<SqliteCapability>;
+    backend: StorageBackend<LocalSqliteCapability>;
     /** The underlying better-sqlite3 database, for raw access. */
     db: Database;
     /**
@@ -70,7 +96,7 @@ declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
  *
  * const { backend, close } = await createLocalSqliteBackend('./graph.db');
  * const client = createGraphClient(backend);
- * // ... use the client ...
+ * // ... use the client — including fullTextSearch() and findNearest() ...
  * close();
  * ```
  *
@@ -80,4 +106,4 @@ declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
  */
 declare function createLocalSqliteBackend(pathOrDb: string | Database, options?: LocalSqliteBackendOptions): Promise<LocalSqliteBackend>;
 
-export { type LocalSqliteBackend, type LocalSqliteBackendOptions, createBetterSqliteExecutor, createLocalSqliteBackend };
+export { type LocalSqliteBackend, type LocalSqliteBackendOptions, type LocalSqliteCapability, createBetterSqliteExecutor, createLocalSqliteBackend };

package/dist/sqlite/local.js

@@ -1,15 +1,327 @@
 import {
+  catalogTableName,
   createSqliteBackend
-} from "../chunk-FODIMIWY.js";
-import "../chunk-ULRDQ6HZ.js";
+} from "../chunk-5JBNLH5W.js";
+import {
+  compileFilterConditions,
+  quoteIdent,
+  rowToRecord,
+  validateJsonPathKey,
+  validateTableName
+} from "../chunk-NZVSLWNY.js";
 import "../chunk-2DHMNTV6.js";
-import "../chunk-N5HFDWQX.js";
+import {
+  createCapabilities
+} from "../chunk-PWIO46RT.js";
 import "../chunk-NGAJCALM.js";
 import {
   FiregraphError
 } from "../chunk-SIHE4UY4.js";
 import "../chunk-EQJUUVFG.js";
 
+// src/internal/sqlite-search.ts
+var VECTOR_DISTANCE_UDF = "firegraph_vector_distance";
+var DISTANCE_ALIAS = "__fg_distance";
+var BACKEND_ERR_LABEL = "SQLite backend";
+var ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function ftsTableName(table) {
+  return `${table}_fts`;
+}
+function ftsMapTableName(table) {
+  return `${table}_fts_map`;
+}
+function textExtractionExpr(dataRef) {
+  return `(SELECT coalesce(group_concat("value", ' '), '') FROM json_tree(coalesce(${dataRef}, '{}')) WHERE "type" = 'text')`;
+}
+function buildFtsDDL(table) {
+  const t = quoteIdent(table);
+  const fts = quoteIdent(ftsTableName(table));
+  const map = quoteIdent(ftsMapTableName(table));
+  const mappedId = `(SELECT "id" FROM ${map} WHERE "doc_id" = new."doc_id")`;
+  const reindexBody = `  INSERT INTO ${map} ("doc_id") SELECT new."doc_id" WHERE NOT EXISTS (SELECT 1 FROM ${map} WHERE "doc_id" = new."doc_id");
+  DELETE FROM ${fts} WHERE rowid = ${mappedId};
+  INSERT INTO ${fts} (rowid, "text") VALUES (${mappedId}, ${textExtractionExpr('new."data"')});
+`;
+  return [
+    `CREATE TABLE IF NOT EXISTS ${map} (
+      "id"     INTEGER PRIMARY KEY AUTOINCREMENT,
+      "doc_id" TEXT NOT NULL UNIQUE
+    )`,
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${fts} USING fts5("text")`,
+    `CREATE TRIGGER IF NOT EXISTS ${quoteIdent(`${table}_fts_ai`)} AFTER INSERT ON ${t} BEGIN
+${reindexBody}END`,
+    `CREATE TRIGGER IF NOT EXISTS ${quoteIdent(`${table}_fts_au`)} AFTER UPDATE ON ${t} BEGIN
+${reindexBody}END`,
+    `CREATE TRIGGER IF NOT EXISTS ${quoteIdent(`${table}_fts_ad`)} AFTER DELETE ON ${t} BEGIN
+  DELETE FROM ${fts} WHERE rowid = (SELECT "id" FROM ${map} WHERE "doc_id" = old."doc_id");
+  DELETE FROM ${map} WHERE "doc_id" = old."doc_id";
+END`
+  ];
+}
+function buildFtsSyncStatements(table) {
+  const t = quoteIdent(table);
+  const fts = quoteIdent(ftsTableName(table));
+  const map = quoteIdent(ftsMapTableName(table));
+  return [
+    `DELETE FROM ${fts} WHERE rowid IN (
+      SELECT m."id" FROM ${map} m LEFT JOIN ${t} t ON t."doc_id" = m."doc_id"
+      WHERE t."doc_id" IS NULL
+    )`,
+    `DELETE FROM ${map} WHERE "doc_id" NOT IN (SELECT "doc_id" FROM ${t})`,
+    `INSERT OR IGNORE INTO ${map} ("doc_id") SELECT "doc_id" FROM ${t}`,
+    `INSERT INTO ${fts} (rowid, "text")
+      SELECT m."id", ${textExtractionExpr('t."data"')}
+      FROM ${t} t JOIN ${map} m ON m."doc_id" = t."doc_id"
+      WHERE m."id" NOT IN (SELECT rowid FROM ${fts})`
+  ];
+}
+function buildLocalSearchDDL(table) {
+  return [...buildFtsDDL(table), ...buildFtsSyncStatements(table)];
+}
+function normalizeVectorFieldPath(label, field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `findNearest(): ${label} '${field}' is a built-in envelope field \u2014 vectors must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function normalizeFullTextFieldPath(field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `fullTextSearch(): field '${field}' is a built-in envelope field \u2014 text-indexed fields must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function buildSearchFilters(params) {
+  const filters = [];
+  if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+  if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+  if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+  for (const clause of params.where ?? []) {
+    const field = ENVELOPE_FIELDS.has(clause.field) || clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
+    filters.push({ field, op: clause.op, value: clause.value });
+  }
+  return filters;
+}
+function compileFullTextSearch(table, params) {
+  if (typeof params.query !== "string" || params.query.length === 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): query must be a non-empty string.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0) {
+    throw new FiregraphError(
+      `fullTextSearch(): limit must be a positive integer (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const normalizedFields = params.fields?.map((f) => normalizeFullTextFieldPath(f));
+  if (normalizedFields !== void 0 && normalizedFields.length > 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): the `fields` option is not yet supported \u2014 the local SQLite FTS index stores one combined text column per record. Omit `fields` to search all string values.",
+      "INVALID_QUERY"
+    );
+  }
+  const t = quoteIdent(table);
+  const fts = quoteIdent(ftsTableName(table));
+  const map = quoteIdent(ftsMapTableName(table));
+  const sqlParams = [params.query];
+  const conditions = [`${fts} MATCH ?`];
+  conditions.push(...compileFilterConditions(buildSearchFilters(params), sqlParams));
+  sqlParams.push(params.limit);
+  const sql = `SELECT ${t}.* FROM ${fts} JOIN ${map} ON ${map}."id" = ${fts}.rowid JOIN ${t} ON ${t}."doc_id" = ${map}."doc_id" WHERE ${conditions.join(" AND ")} ORDER BY bm25(${fts}) ASC, ${t}."doc_id" ASC LIMIT ?`;
+  return { sql, params: sqlParams };
+}
+var FTS5_QUERY_ERROR_SIGNATURES = [
+  "fts5: syntax error",
+  "unterminated string",
+  "unknown special query",
+  "no such column"
+];
+function isFts5QueryError(message) {
+  const lower = message.toLowerCase();
+  return FTS5_QUERY_ERROR_SIGNATURES.some((sig) => lower.includes(sig));
+}
+var DISTANCE_MEASURES = /* @__PURE__ */ new Set(["EUCLIDEAN", "COSINE", "DOT_PRODUCT"]);
+function toNumberArray(qv) {
+  if (Array.isArray(qv)) return qv;
+  if (typeof qv.toArray === "function") {
+    return qv.toArray();
+  }
+  throw new FiregraphError(
+    "findNearest(): queryVector must be a number[] or a Firestore VectorValue.",
+    "INVALID_QUERY"
+  );
+}
+function compileFindNearest(table, params) {
+  const vec = toNumberArray(params.queryVector);
+  if (vec.length === 0) {
+    throw new FiregraphError(
+      "findNearest(): queryVector is empty \u2014 at least one dimension is required.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0 || params.limit > 1e3) {
+    throw new FiregraphError(
+      `findNearest(): limit must be a positive integer \u2264 1000 (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!DISTANCE_MEASURES.has(params.distanceMeasure)) {
+    throw new FiregraphError(
+      `findNearest(): unknown distanceMeasure '${String(params.distanceMeasure)}' \u2014 expected EUCLIDEAN, COSINE, or DOT_PRODUCT.`,
+      "INVALID_QUERY"
+    );
+  }
+  const vectorField = normalizeVectorFieldPath("vectorField", params.vectorField);
+  let vectorExpr;
+  if (vectorField === "data") {
+    vectorExpr = '"data"';
+  } else {
+    const suffix = vectorField.slice("data.".length);
+    for (const part of suffix.split(".")) {
+      validateJsonPathKey(part, BACKEND_ERR_LABEL);
+    }
+    vectorExpr = `json_extract("data", '$.${suffix}')`;
+  }
+  let distancePath = null;
+  if (params.distanceResultField !== void 0) {
+    const normalized = normalizeVectorFieldPath("distanceResultField", params.distanceResultField);
+    if (normalized === "data") {
+      throw new FiregraphError(
+        `findNearest(): distanceResultField 'data' would replace the entire data payload \u2014 use a nested path like 'data.distance'.`,
+        "INVALID_QUERY"
+      );
+    }
+    distancePath = normalized.slice("data.".length).split(".");
+    for (const part of distancePath) {
+      validateJsonPathKey(part, BACKEND_ERR_LABEL);
+    }
+  }
+  const sqlParams = [JSON.stringify(vec), params.distanceMeasure];
+  const conditions = compileFilterConditions(buildSearchFilters(params), sqlParams);
+  const innerWhere = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  const dist = quoteIdent(DISTANCE_ALIAS);
+  const descending = params.distanceMeasure === "DOT_PRODUCT";
+  let sql = `SELECT * FROM (SELECT *, ${VECTOR_DISTANCE_UDF}(${vectorExpr}, ?, ?) AS ${dist} FROM ${quoteIdent(table)}${innerWhere}) WHERE ${dist} IS NOT NULL`;
+  if (params.distanceThreshold !== void 0) {
+    sql += ` AND ${dist} ${descending ? ">=" : "<="} ?`;
+    sqlParams.push(params.distanceThreshold);
+  }
+  sql += ` ORDER BY ${dist} ${descending ? "DESC" : "ASC"}, "doc_id" ASC LIMIT ?`;
+  sqlParams.push(params.limit);
+  return { stmt: { sql, params: sqlParams }, distancePath };
+}
+var memoQueryJson = null;
+var memoQueryVec = null;
+function computeVectorDistance(storedJson, queryJson, measure) {
+  if (typeof storedJson !== "string" || typeof queryJson !== "string" || typeof measure !== "string") {
+    return null;
+  }
+  let query;
+  if (memoQueryJson === queryJson && memoQueryVec !== null) {
+    query = memoQueryVec;
+  } else {
+    let parsed;
+    try {
+      parsed = JSON.parse(queryJson);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(parsed)) return null;
+    query = parsed;
+    memoQueryJson = queryJson;
+    memoQueryVec = query;
+  }
+  let stored;
+  try {
+    stored = JSON.parse(storedJson);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(stored) || stored.length !== query.length) return null;
+  let dot = 0;
+  let sumSq = 0;
+  let normStored = 0;
+  let normQuery = 0;
+  for (let i = 0; i < query.length; i++) {
+    const a = stored[i];
+    const b = query[i];
+    if (typeof a !== "number" || !Number.isFinite(a)) return null;
+    if (typeof b !== "number" || !Number.isFinite(b)) return null;
+    dot += a * b;
+    const diff = a - b;
+    sumSq += diff * diff;
+    normStored += a * a;
+    normQuery += b * b;
+  }
+  let result;
+  switch (measure) {
+    case "EUCLIDEAN":
+      result = Math.sqrt(sumSq);
+      break;
+    case "COSINE": {
+      const denom = Math.sqrt(normStored) * Math.sqrt(normQuery);
+      if (denom === 0) return null;
+      result = 1 - dot / denom;
+      break;
+    }
+    case "DOT_PRODUCT":
+      result = dot;
+      break;
+    default:
+      return null;
+  }
+  return Number.isFinite(result) ? result : null;
+}
+function setDataPath(data, path, value) {
+  let cursor = data;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    const next = cursor[key];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      const created = {};
+      cursor[key] = created;
+      cursor = created;
+    } else {
+      cursor = next;
+    }
+  }
+  cursor[path[path.length - 1]] = value;
+}
+function findOrphanedFtsTables(allTables, catalogTables, rootTable) {
+  const names = new Set(allTables);
+  const liveGraphTables = new Set(catalogTables);
+  const subgraphPrefix = `${rootTable}_g_`;
+  const orphans = [];
+  for (const name of names) {
+    let base = null;
+    if (name.endsWith("_fts_map")) base = name.slice(0, -"_fts_map".length);
+    else if (name.endsWith("_fts")) base = name.slice(0, -"_fts".length);
+    if (base === null || !base.startsWith(subgraphPrefix)) continue;
+    if (liveGraphTables.has(name)) continue;
+    if (names.has(base)) continue;
+    orphans.push(name);
+  }
+  return orphans.sort();
+}
+
 // src/sqlite/local.ts
 function createBetterSqliteExecutor(db) {
   return {
@@ -66,6 +378,118 @@ function applyPragmas(db, pragmas) {
     db.pragma(`${key} = ${value}`);
   }
 }
+function registerVectorUdf(db) {
+  try {
+    db.function(
+      VECTOR_DISTANCE_UDF,
+      { deterministic: true },
+      (stored, query, measure) => computeVectorDistance(stored, query, measure)
+    );
+  } catch {
+  }
+}
+async function sweepOrphanedFtsArtifacts(executor, rootTable) {
+  const tableRows = await executor.all(
+    `SELECT "name" FROM sqlite_master WHERE "type" = 'table'`,
+    []
+  );
+  const allTables = tableRows.map((r) => String(r.name));
+  const catalogRows = await executor.all(
+    `SELECT "table_name" FROM ${quoteIdent(catalogTableName(rootTable))}`,
+    []
+  );
+  const catalogTables = catalogRows.map((r) => String(r.table_name));
+  for (const name of findOrphanedFtsTables(allTables, catalogTables, rootTable)) {
+    validateTableName(name);
+    await executor.run(`DROP TABLE IF EXISTS ${quoteIdent(name)}`, []);
+  }
+}
+function wrapLocalSearchBackend(inner, executor, rootTable) {
+  const caps = /* @__PURE__ */ new Set([
+    ...inner.capabilities.values(),
+    "search.fullText",
+    "search.vector"
+  ]);
+  const healableTables = /* @__PURE__ */ new Set([
+    inner.collectionPath,
+    ftsTableName(inner.collectionPath),
+    ftsMapTableName(inner.collectionPath)
+  ]);
+  const runWithSchema = async (op) => {
+    await inner.ensureReady();
+    try {
+      return await op();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const missing = /no such table: (\S+)/.exec(message)?.[1];
+      if (missing === void 0 || !healableTables.has(missing)) throw err;
+      await inner.ensureReady(true);
+      return op();
+    }
+  };
+  const wrapper = {
+    capabilities: createCapabilities(caps),
+    collectionPath: inner.collectionPath,
+    scopePath: inner.scopePath,
+    getDoc: (docId) => inner.getDoc(docId),
+    query: (filters, options) => inner.query(filters, options),
+    setDoc: (docId, record, mode) => inner.setDoc(docId, record, mode),
+    updateDoc: (docId, update) => inner.updateDoc(docId, update),
+    deleteDoc: (docId) => inner.deleteDoc(docId),
+    runTransaction: (fn) => inner.runTransaction(fn),
+    createBatch: () => inner.createBatch(),
+    subgraph: (parentNodeUid, name) => wrapLocalSearchBackend(inner.subgraph(parentNodeUid, name), executor, rootTable),
+    removeNodeCascade: async (uid, reader, options) => {
+      const result = await inner.removeNodeCascade(uid, reader, options);
+      if (result.errors.length === 0) {
+        await sweepOrphanedFtsArtifacts(executor, rootTable);
+      }
+      return result;
+    },
+    bulkRemoveEdges: (params, reader, options) => inner.bulkRemoveEdges(params, reader, options),
+    aggregate: (spec, filters) => inner.aggregate(spec, filters),
+    bulkDelete: (filters, options) => inner.bulkDelete(filters, options),
+    bulkUpdate: (filters, patch, options) => inner.bulkUpdate(filters, patch, options),
+    expand: (params) => inner.expand(params),
+    findEdgesProjected: (select, filters, options) => inner.findEdgesProjected(select, filters, options),
+    // `findEdgesGlobal` stays absent, same as the inner backend — each graph
+    // is its own table; there is no cross-table index.
+    async findNearest(params) {
+      const { stmt, distancePath } = compileFindNearest(inner.collectionPath, params);
+      const rows = await runWithSchema(() => executor.all(stmt.sql, stmt.params));
+      return rows.map((row) => {
+        const record = rowToRecord(row);
+        if (distancePath) {
+          const distance = row[DISTANCE_ALIAS];
+          setDataPath(
+            record.data,
+            distancePath,
+            typeof distance === "number" ? distance : Number(distance)
+          );
+        }
+        return record;
+      });
+    },
+    async fullTextSearch(params) {
+      const stmt = compileFullTextSearch(inner.collectionPath, params);
+      let rows;
+      try {
+        rows = await runWithSchema(() => executor.all(stmt.sql, stmt.params));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isFts5QueryError(message)) {
+          throw new FiregraphError(
+            `fullTextSearch(): invalid FTS5 query syntax \u2014 ${message}`,
+            "INVALID_QUERY"
+          );
+        }
+        throw err;
+      }
+      return rows.map(rowToRecord);
+    }
+  };
+  return wrapper;
+}
 async function createLocalSqliteBackend(pathOrDb, options = {}) {
   const {
     tableName = "firegraph",
@@ -102,7 +526,18 @@ async function createLocalSqliteBackend(pathOrDb, options = {}) {
   if (pragmas) {
     applyPragmas(db, pragmas);
   }
-  const backend = createSqliteBackend(createBetterSqliteExecutor(db), tableName, backendOptions);
+  registerVectorUdf(db);
+  const userExtraDDL = backendOptions.extraTableDDL;
+  const optionsWithSearch = {
+    ...backendOptions,
+    extraTableDDL: (table) => [
+      ...userExtraDDL ? userExtraDDL(table) : [],
+      ...buildLocalSearchDDL(table)
+    ]
+  };
+  const executor = createBetterSqliteExecutor(db);
+  const inner = createSqliteBackend(executor, tableName, optionsWithSearch);
+  const backend = wrapLocalSearchBackend(inner, executor, tableName);
   let closed = false;
   return {
     backend,