@typicalday/firegraph 0.15.0 → 0.16.1

package/dist/sqlite/index.d.cts

@@ -1,5 +1,5 @@
-export { c as createGraphClient } from '../client-BGHwxwPg.cjs';
-export { M as META_EDGE_TYPE, a as META_NODE_TYPE, c as createMergedRegistry, b as createRegistry, g as generateId } from '../registry-BGh7Jqpb.cjs';
-export { S as SqliteBackendOptions, a as SqliteCapability, c as createSqliteBackend } from '../backend-CvImIwTY.cjs';
-import '../backend-BpYLdwCW.cjs';
+export { c as createGraphClient } from '../client-CaXH5D5C.cjs';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, c as createMergedRegistry, b as createRegistry, g as generateId } from '../registry-CNToyEra.cjs';
+export { S as SqliteBackendOptions, a as SqliteCapability, c as createSqliteBackend } from '../backend-EjFfw9yO.cjs';
+import '../backend-DNzv8KSR.cjs';
 import '@google-cloud/firestore';

package/dist/sqlite/index.d.ts

@@ -1,5 +1,5 @@
-export { c as createGraphClient } from '../client-B5o39X79.js';
-export { M as META_EDGE_TYPE, a as META_NODE_TYPE, c as createMergedRegistry, b as createRegistry, g as generateId } from '../registry-tKTb5Kx1.js';
-export { S as SqliteBackendOptions, a as SqliteCapability, c as createSqliteBackend } from '../backend-YH5HtawN.js';
-import '../backend-BpYLdwCW.js';
+export { c as createGraphClient } from '../client-CNAwJayO.js';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, c as createMergedRegistry, b as createRegistry, g as generateId } from '../registry-By1i-zge.js';
+export { S as SqliteBackendOptions, a as SqliteCapability, c as createSqliteBackend } from '../backend-CE3pM9-T.js';
+import '../backend-DNzv8KSR.js';
 import '@google-cloud/firestore';

package/dist/sqlite/index.js

@@ -1,9 +1,9 @@
 import {
   createSqliteBackend
-} from "../chunk-FODIMIWY.js";
-import "../chunk-ULRDQ6HZ.js";
+} from "../chunk-5JBNLH5W.js";
+import "../chunk-NZVSLWNY.js";
 import "../chunk-2DHMNTV6.js";
-import "../chunk-N5HFDWQX.js";
+import "../chunk-PWIO46RT.js";
 import {
   META_EDGE_TYPE,
   META_NODE_TYPE,
@@ -11,7 +11,7 @@ import {
   createMergedRegistry,
   createRegistry,
   generateId
-} from "../chunk-5HIRYV2S.js";
+} from "../chunk-6IO74NKD.js";
 import "../chunk-NGAJCALM.js";
 import "../chunk-SIHE4UY4.js";
 import "../chunk-EQJUUVFG.js";

package/dist/sqlite/local.cjs

@@ -44,24 +44,6 @@ var FiregraphError = class extends Error {
   }
 };
 
-// src/docid.ts
-var import_node_crypto = require("crypto");
-
-// src/internal/constants.ts
-var NODE_RELATION = "is";
-var SHARD_SEPARATOR = ":";
-
-// src/docid.ts
-function computeNodeDocId(uid) {
-  return uid;
-}
-function computeEdgeDocId(aUid, axbType, bUid) {
-  const composite = `${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
-  const hash = (0, import_node_crypto.createHash)("sha256").update(composite).digest("hex");
-  const shard = hash[0];
-  return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
-}
-
 // src/internal/backend.ts
 function createCapabilities(caps) {
   return {
@@ -225,31 +207,6 @@ function quoteColumnAlias(label) {
   return `"${label.replace(/"/g, '""')}"`;
 }
 
-// src/timestamp.ts
-var GraphTimestampImpl = class _GraphTimestampImpl {
-  constructor(seconds, nanoseconds) {
-    this.seconds = seconds;
-    this.nanoseconds = nanoseconds;
-  }
-  toDate() {
-    return new Date(this.toMillis());
-  }
-  toMillis() {
-    return this.seconds * 1e3 + Math.floor(this.nanoseconds / 1e6);
-  }
-  toJSON() {
-    return { seconds: this.seconds, nanoseconds: this.nanoseconds };
-  }
-  static fromMillis(ms) {
-    const seconds = Math.floor(ms / 1e3);
-    const nanoseconds = (ms - seconds * 1e3) * 1e6;
-    return new _GraphTimestampImpl(seconds, nanoseconds);
-  }
-  static now() {
-    return _GraphTimestampImpl.fromMillis(Date.now());
-  }
-};
-
 // src/internal/sqlite-data-ops.ts
 var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
   "Timestamp",
@@ -318,6 +275,35 @@ function compileDataOpsExpr(ops, base, params, backendLabel) {
   return expr;
 }
 
+// src/timestamp.ts
+var GraphTimestampImpl = class _GraphTimestampImpl {
+  constructor(seconds, nanoseconds) {
+    this.seconds = seconds;
+    this.nanoseconds = nanoseconds;
+  }
+  toDate() {
+    return new Date(this.toMillis());
+  }
+  toMillis() {
+    return this.seconds * 1e3 + Math.floor(this.nanoseconds / 1e6);
+  }
+  toJSON() {
+    return { seconds: this.seconds, nanoseconds: this.nanoseconds };
+  }
+  static fromMillis(ms) {
+    const seconds = Math.floor(ms / 1e3);
+    const nanoseconds = (ms - seconds * 1e3) * 1e6;
+    return new _GraphTimestampImpl(seconds, nanoseconds);
+  }
+  static now() {
+    return _GraphTimestampImpl.fromMillis(Date.now());
+  }
+};
+
+// src/internal/constants.ts
+var NODE_RELATION = "is";
+var SHARD_SEPARATOR = ":";
+
 // src/internal/serialization-tag.ts
 var SERIALIZATION_TAG = "__firegraph_ser__";
 var KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
@@ -622,6 +608,9 @@ function compileFilter(filter, params) {
       );
   }
 }
+function compileFilterConditions(filters, params) {
+  return filters.map((f) => compileFilter(f, params));
+}
 function asArray(value, op) {
   if (!Array.isArray(value) || value.length === 0) {
     throw new FiregraphError(`Operator "${op}" requires a non-empty array value`, "INVALID_QUERY");
@@ -1036,6 +1025,321 @@ function rowTimestampToMillis(value) {
   );
 }
 
+// src/internal/sqlite-search.ts
+var VECTOR_DISTANCE_UDF = "firegraph_vector_distance";
+var DISTANCE_ALIAS = "__fg_distance";
+var BACKEND_ERR_LABEL2 = "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 = quoteIdent2(table);
+  const fts = quoteIdent2(ftsTableName(table));
+  const map = quoteIdent2(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 ${quoteIdent2(`${table}_fts_ai`)} AFTER INSERT ON ${t} BEGIN
+${reindexBody}END`,
+    `CREATE TRIGGER IF NOT EXISTS ${quoteIdent2(`${table}_fts_au`)} AFTER UPDATE ON ${t} BEGIN
+${reindexBody}END`,
+    `CREATE TRIGGER IF NOT EXISTS ${quoteIdent2(`${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 = quoteIdent2(table);
+  const fts = quoteIdent2(ftsTableName(table));
+  const map = quoteIdent2(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 = quoteIdent2(table);
+  const fts = quoteIdent2(ftsTableName(table));
+  const map = quoteIdent2(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_LABEL2);
+    }
+    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_LABEL2);
+    }
+  }
+  const sqlParams = [JSON.stringify(vec), params.distanceMeasure];
+  const conditions = compileFilterConditions(buildSearchFilters(params), sqlParams);
+  const innerWhere = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  const dist = quoteIdent2(DISTANCE_ALIAS);
+  const descending = params.distanceMeasure === "DOT_PRODUCT";
+  let sql = `SELECT * FROM (SELECT *, ${VECTOR_DISTANCE_UDF}(${vectorExpr}, ?, ?) AS ${dist} FROM ${quoteIdent2(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/docid.ts
+var import_node_crypto = require("crypto");
+function computeNodeDocId(uid) {
+  return uid;
+}
+function computeEdgeDocId(aUid, axbType, bUid) {
+  const composite = `${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+  const hash = (0, import_node_crypto.createHash)("sha256").update(composite).digest("hex");
+  const shard = hash[0];
+  return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+}
+
 // src/sqlite/catalog.ts
 function catalogTableName(rootTable) {
   validateTableName(rootTable);
@@ -1196,7 +1500,7 @@ var SQLITE_CORE_CAPS = [
   "raw.sql"
 ];
 var SqliteBackendImpl = class _SqliteBackendImpl {
-  constructor(executor, rootTable, storageScope, scopePath, registry, coreIndexes) {
+  constructor(executor, rootTable, storageScope, scopePath, registry, coreIndexes, extraTableDDL) {
     this.executor = executor;
     validateTableName(rootTable);
     this.rootTable = rootTable;
@@ -1205,6 +1509,7 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     this.scopePath = scopePath;
     this.registry = registry;
     this.coreIndexes = coreIndexes;
+    this.extraTableDDL = extraTableDDL;
     const caps = new Set(SQLITE_CORE_CAPS);
     if (typeof executor.transaction === "function") {
       caps.add("core.transactions");
@@ -1221,6 +1526,7 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
   rootTable;
   registry;
   coreIndexes;
+  extraTableDDL;
   ensured = null;
   /**
    * Lazily create this graph's table + indexes + the catalog, and register
@@ -1237,12 +1543,18 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     }
     return this.ensured;
   }
+  /** @internal See `SqliteStorageBackend.ensureReady`. */
+  async ensureReady(force = false) {
+    if (force) this.ensured = null;
+    await this.ensureSchema();
+  }
   async doEnsureSchema() {
     const ddl = [
       ...buildSchemaStatements(this.collectionPath, {
         coreIndexes: this.coreIndexes,
         registry: this.registry
       }),
+      ...this.extraTableDDL ? this.extraTableDDL(this.collectionPath) : [],
       buildCatalogDDL(this.rootTable)
     ];
     const statements = ddl.map((sql) => ({ sql, params: [] }));
@@ -1373,7 +1685,8 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
       newStorageScope,
       newScope,
       this.registry,
-      this.coreIndexes
+      this.coreIndexes,
+      this.extraTableDDL
     );
   }
   // --- Cascade & bulk ---
@@ -1719,7 +2032,8 @@ function createSqliteBackend(executor, tableName, options = {}) {
     storageScope,
     scopePath,
     options.registry,
-    options.coreIndexes
+    options.coreIndexes,
+    options.extraTableDDL
   );
 }
 
@@ -1779,6 +2093,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 ${quoteIdent2(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 ${quoteIdent2(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",
@@ -1815,7 +2241,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,