@typicalday/firegraph 0.14.1 → 0.16.0

package/dist/sqlite/local.cjs

@@ -0,0 +1,2262 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sqlite/local.ts
+var local_exports = {};
+__export(local_exports, {
+  createBetterSqliteExecutor: () => createBetterSqliteExecutor,
+  createLocalSqliteBackend: () => createLocalSqliteBackend
+});
+module.exports = __toCommonJS(local_exports);
+
+// src/errors.ts
+var FiregraphError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FiregraphError";
+  }
+};
+
+// src/internal/backend.ts
+function createCapabilities(caps) {
+  return {
+    has: (capability) => caps.has(capability),
+    values: () => caps.values()
+  };
+}
+
+// src/default-indexes.ts
+var DEFAULT_CORE_INDEXES = Object.freeze([
+  { fields: ["aUid"] },
+  { fields: ["bUid"] },
+  { fields: ["aType"] },
+  { fields: ["bType"] },
+  { fields: ["aUid", "axbType"] },
+  { fields: ["axbType", "bUid"] },
+  { fields: ["aType", "axbType"] },
+  { fields: ["axbType", "bType"] }
+]);
+
+// src/internal/sqlite-index-ddl.ts
+var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function quoteIdent(name) {
+  if (!IDENT_RE.test(name)) {
+    throw new FiregraphError(
+      `Invalid SQL identifier in index DDL: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+      "INVALID_INDEX"
+    );
+  }
+  return `"${name}"`;
+}
+function fnv1a32(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function normalizeFields(fields) {
+  return fields.map((f) => {
+    if (typeof f === "string") return { path: f, desc: false };
+    if (!f.path || typeof f.path !== "string") {
+      throw new FiregraphError(
+        `IndexSpec field must be a string or { path: string, desc?: boolean }; got ${JSON.stringify(f)}`,
+        "INVALID_INDEX"
+      );
+    }
+    return { path: f.path, desc: !!f.desc };
+  });
+}
+function specFingerprint(spec) {
+  const normalized = {
+    lead: [],
+    fields: normalizeFields(spec.fields),
+    where: spec.where ?? ""
+  };
+  return fnv1a32(JSON.stringify(normalized));
+}
+function compileFieldExpr(path, fieldToColumn) {
+  const col = fieldToColumn[path];
+  if (col) return quoteIdent(col);
+  if (path === "data") {
+    return `json_extract("data", '$')`;
+  }
+  if (path.startsWith("data.")) {
+    const suffix = path.slice(5);
+    const parts = suffix.split(".");
+    for (const part of parts) {
+      if (!JSON_PATH_KEY_RE.test(part)) {
+        throw new FiregraphError(
+          `IndexSpec data path "${path}" has invalid component "${part}". Each component must match /^[A-Za-z_][A-Za-z0-9_-]*$/.`,
+          "INVALID_INDEX"
+        );
+      }
+    }
+    return `json_extract("data", '$.${suffix}')`;
+  }
+  throw new FiregraphError(
+    `IndexSpec field "${path}" is not a known firegraph field. Use a top-level field (aType, aUid, axbType, bType, bUid, createdAt, updatedAt, v) or a dotted data path like 'data.status'.`,
+    "INVALID_INDEX"
+  );
+}
+function buildIndexDDL(spec, options) {
+  const { table, fieldToColumn } = options;
+  if (!spec.fields || spec.fields.length === 0) {
+    throw new FiregraphError("IndexSpec.fields must be a non-empty array", "INVALID_INDEX");
+  }
+  const normalized = normalizeFields(spec.fields);
+  const hash = specFingerprint(spec);
+  const indexName = `${table}_idx_${hash}`;
+  const cols = [];
+  for (const f of normalized) {
+    const expr = compileFieldExpr(f.path, fieldToColumn);
+    cols.push(f.desc ? `${expr} DESC` : expr);
+  }
+  let ddl = `CREATE INDEX IF NOT EXISTS ${quoteIdent(indexName)} ON ${quoteIdent(table)}(${cols.join(", ")})`;
+  if (spec.where) {
+    ddl += ` WHERE ${spec.where}`;
+  }
+  return ddl;
+}
+function dedupeIndexSpecs(specs) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const spec of specs) {
+    const fp = specFingerprint(spec);
+    if (seen.has(fp)) continue;
+    seen.add(fp);
+    out.push(spec);
+  }
+  return out;
+}
+
+// src/internal/sqlite-schema.ts
+var FIELD_TO_COLUMN = {
+  aType: "a_type",
+  aUid: "a_uid",
+  axbType: "axb_type",
+  bType: "b_type",
+  bUid: "b_uid",
+  v: "v",
+  createdAt: "created_at",
+  updatedAt: "updated_at"
+};
+function buildSchemaStatements(table, options = {}) {
+  const t = quoteIdent2(table);
+  const statements = [
+    `CREATE TABLE IF NOT EXISTS ${t} (
+      doc_id      TEXT NOT NULL PRIMARY KEY,
+      a_type      TEXT NOT NULL,
+      a_uid       TEXT NOT NULL,
+      axb_type    TEXT NOT NULL,
+      b_type      TEXT NOT NULL,
+      b_uid       TEXT NOT NULL,
+      data        TEXT NOT NULL,
+      v           INTEGER,
+      created_at  INTEGER NOT NULL,
+      updated_at  INTEGER NOT NULL
+    )`
+  ];
+  const core = options.coreIndexes ?? [...DEFAULT_CORE_INDEXES];
+  const fromRegistry = options.registry?.entries().flatMap((e) => e.indexes ?? []) ?? [];
+  const deduped = dedupeIndexSpecs([...core, ...fromRegistry]);
+  for (const spec of deduped) {
+    statements.push(buildIndexDDL(spec, { table, fieldToColumn: FIELD_TO_COLUMN }));
+  }
+  return statements;
+}
+function quoteIdent2(name) {
+  validateTableName(name);
+  return `"${name}"`;
+}
+function validateTableName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid SQL identifier: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+  }
+}
+function quoteColumnAlias(label) {
+  return `"${label.replace(/"/g, '""')}"`;
+}
+
+// src/internal/sqlite-data-ops.ts
+var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function isFirestoreSpecialType(value) {
+  const ctorName = value.constructor?.name;
+  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
+  return null;
+}
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function validateJsonPathKey(key, backendLabel) {
+  if (key.length === 0) {
+    throw new FiregraphError(
+      `${backendLabel}: empty JSON path component is not allowed`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!JSON_PATH_KEY_RE2.test(key)) {
+    throw new FiregraphError(
+      `${backendLabel}: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceNode/replaceEdge (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+function buildJsonPath(segments) {
+  return "$" + segments.map((seg) => "." + JSON.stringify(seg)).join("");
+}
+function jsonBind(value, backendLabel) {
+  if (value === void 0) return "null";
+  if (value !== null && typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `${backendLabel} cannot persist a Firestore ${firestoreType} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp).`,
+        "INVALID_ARGUMENT"
+      );
+    }
+  }
+  return JSON.stringify(value);
+}
+function compileDataOpsExpr(ops, base, params, backendLabel) {
+  if (ops.length === 0) return null;
+  const deletes = [];
+  const sets = [];
+  for (const op of ops) (op.delete ? deletes : sets).push(op);
+  let expr = base;
+  if (deletes.length > 0) {
+    const placeholders = deletes.map(() => "?").join(", ");
+    expr = `json_remove(${expr}, ${placeholders})`;
+    for (const op of deletes) {
+      params.push(buildJsonPath(op.path));
+    }
+  }
+  if (sets.length > 0) {
+    const pieces = sets.map(() => "?, json(?)").join(", ");
+    expr = `json_set(${expr}, ${pieces})`;
+    for (const op of sets) {
+      params.push(buildJsonPath(op.path));
+      params.push(jsonBind(op.value, 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"]);
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+
+// src/internal/write-plan.ts
+var DELETE_FIELD = /* @__PURE__ */ Symbol.for("firegraph.deleteField");
+function isDeleteSentinel(value) {
+  return value === DELETE_FIELD;
+}
+var FIRESTORE_TERMINAL_CTOR = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue",
+  "NumericIncrementTransform",
+  "ArrayUnionTransform",
+  "ArrayRemoveTransform",
+  "ServerTimestampTransform",
+  "DeleteTransform"
+]);
+function isTerminalValue(value) {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t !== "object") return true;
+  if (Array.isArray(value)) return true;
+  if (isTaggedValue(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return false;
+  const ctor = value.constructor;
+  if (ctor && typeof ctor.name === "string" && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;
+  return true;
+}
+function assertUpdatePayloadExclusive(update) {
+  if (update.replaceData !== void 0 && update.dataOps !== void 0) {
+    throw new Error(
+      "firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. Use one or the other \u2014 `replaceData` is the migration-write-back form, `dataOps` is the standard partial-update form."
+    );
+  }
+}
+function walkForDeleteSentinels(node, path, parent, visit) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    visit({ path, parent });
+    return;
+  }
+  if (typeof node !== "object") return;
+  if (isTaggedValue(node)) return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: "array", index: i }, visit);
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) return;
+  const obj = node;
+  for (const key of Object.keys(obj)) {
+    walkForDeleteSentinels(obj[key], [...path, key], { kind: "object" }, visit);
+  }
+}
+function assertSafePath(path) {
+  for (const seg of path) {
+    if (seg === "") {
+      throw new Error(
+        `firegraph: empty object key at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Object keys in update payloads must be non-empty.`
+      );
+    }
+  }
+}
+function flattenPatch(data) {
+  const ops = [];
+  walk(data, [], ops);
+  return ops;
+}
+function assertNoDeleteSentinelsInArrayValue(arr, arrayPath) {
+  walkForDeleteSentinels(arr, arrayPath, { kind: "root" }, ({ parent }) => {
+    const arrayPathStr = arrayPath.length === 0 ? "<root>" : arrayPath.map((p) => JSON.stringify(p)).join(" > ");
+    if (parent.kind === "array") {
+      throw new Error(
+        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at path ${arrayPathStr}. Arrays are terminal in update payloads (replaced as a unit), so the sentinel would be silently dropped by JSON serialization. To remove the field entirely, pass deleteField() in place of the whole array.`
+      );
+    }
+    throw new Error(
+      `firegraph: deleteField() sentinel inside an array element at path ${arrayPathStr}. Arrays are terminal in update payloads \u2014 the sentinel would be silently dropped by JSON serialization.`
+    );
+  });
+}
+function walk(node, path, out) {
+  if (node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    if (path.length === 0) {
+      throw new Error("firegraph: deleteField() cannot be the entire update payload.");
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: void 0, delete: true });
+    return;
+  }
+  if (isTerminalValue(node)) {
+    if (path.length === 0) {
+      throw new Error(
+        "firegraph: update payload must be a plain object. Got " + (node === null ? "null" : Array.isArray(node) ? "array" : typeof node) + "."
+      );
+    }
+    if (Array.isArray(node)) {
+      assertNoDeleteSentinelsInArrayValue(node, path);
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: node, delete: false });
+    return;
+  }
+  const obj = node;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    if (path.length > 0) {
+      assertSafePath(path);
+      out.push({ path: [...path], value: {}, delete: false });
+    }
+    return;
+  }
+  for (const key of keys) {
+    if (key === SERIALIZATION_TAG) {
+      const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+      throw new Error(
+        `firegraph: update payload contains a literal \`${SERIALIZATION_TAG}\` key at ${where}. That key is reserved for firegraph's serialization envelope and cannot appear on a plain object in user data. Use a different field name, or pass a recognized tagged value through replaceNode/replaceEdge instead.`
+      );
+    }
+    walk(obj[key], [...path, key], out);
+  }
+}
+
+// src/internal/sqlite-payload-guard.ts
+var FIRESTORE_TYPE_NAMES2 = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function assertJsonSafePayload(data, label) {
+  walk2(data, [], label);
+}
+function walk2(node, path, label) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    throw new FiregraphError(
+      `${label} backend cannot persist a deleteField() sentinel inside a full-data payload (replaceNode/replaceEdge or first-insert). The sentinel is only valid inside an updateNode/updateEdge dataOps patch. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const t = typeof node;
+  if (t === "symbol" || t === "function") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type ${t}. JSON.stringify drops it silently. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t === "bigint") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type bigint. JSON.stringify cannot serialize this type (throws TypeError). Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t !== "object") return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walk2(node[i], [...path, String(i)], label);
+    }
+    return;
+  }
+  const obj = node;
+  if (Object.prototype.hasOwnProperty.call(obj, SERIALIZATION_TAG)) {
+    const tagValue = obj[SERIALIZATION_TAG];
+    throw new FiregraphError(
+      `${label} backend cannot persist an object with a \`${SERIALIZATION_TAG}\` key (value: ${formatTagValue(tagValue)}). Recognised tags are valid only on the Firestore backend (migration-sandbox output); a literal \`${SERIALIZATION_TAG}\` field in user data is reserved and not allowed. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) {
+    const ctor = node.constructor;
+    const ctorName = ctor && typeof ctor.name === "string" ? ctor.name : "<anonymous>";
+    if (FIRESTORE_TYPE_NAMES2.has(ctorName)) {
+      throw new FiregraphError(
+        `${label} backend cannot persist a Firestore ${ctorName} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp, \`{lat,lng}\` for GeoPoint). Path: ${formatPath(path)}.`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    if (node instanceof Date) return;
+    throw new FiregraphError(
+      `${label} backend cannot persist a class instance of type ${ctorName}. Only plain objects, arrays, and primitives round-trip safely through JSON storage. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  for (const key of Object.keys(obj)) {
+    walk2(obj[key], [...path, key], label);
+  }
+}
+function formatPath(path) {
+  return path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+}
+function formatTagValue(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return typeof value;
+}
+
+// src/internal/sqlite-sql.ts
+var BACKEND_LABEL = "SQLite";
+var BACKEND_ERR_LABEL = "SQLite backend";
+function compileFieldRef(field) {
+  const column = FIELD_TO_COLUMN[field];
+  if (column) {
+    return { expr: quoteIdent2(column) };
+  }
+  if (field.startsWith("data.")) {
+    const suffix = field.slice(5);
+    for (const part of suffix.split(".")) {
+      validateJsonPathKey(part, BACKEND_ERR_LABEL);
+    }
+    return { expr: `json_extract("data", '$.${suffix}')` };
+  }
+  if (field === "data") {
+    return { expr: `json_extract("data", '$')` };
+  }
+  throw new FiregraphError(`SQLite backend cannot resolve filter field: ${field}`, "INVALID_QUERY");
+}
+function bindValue(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `SQLite backend cannot bind a Firestore ${firestoreType} value \u2014 JSON serialization would silently drop fields and the resulting bind would never match a stored row. Convert to a primitive (e.g. \`ts.toMillis()\` for Timestamp) before filtering or updating.`,
+        "INVALID_QUERY"
+      );
+    }
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function compileFilter(filter, params) {
+  const { expr } = compileFieldRef(filter.field);
+  switch (filter.op) {
+    case "==":
+      params.push(bindValue(filter.value));
+      return `${expr} = ?`;
+    case "!=":
+      params.push(bindValue(filter.value));
+      return `${expr} != ?`;
+    case "<":
+      params.push(bindValue(filter.value));
+      return `${expr} < ?`;
+    case "<=":
+      params.push(bindValue(filter.value));
+      return `${expr} <= ?`;
+    case ">":
+      params.push(bindValue(filter.value));
+      return `${expr} > ?`;
+    case ">=":
+      params.push(bindValue(filter.value));
+      return `${expr} >= ?`;
+    case "in": {
+      const values = asArray(filter.value, "in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} IN (${placeholders})`;
+    }
+    case "not-in": {
+      const values = asArray(filter.value, "not-in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} NOT IN (${placeholders})`;
+    }
+    case "array-contains": {
+      params.push(bindValue(filter.value));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value = ?)`;
+    }
+    case "array-contains-any": {
+      const values = asArray(filter.value, "array-contains-any");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value IN (${placeholders}))`;
+    }
+    default:
+      throw new FiregraphError(
+        `SQLite backend does not support filter operator: ${String(filter.op)}`,
+        "INVALID_QUERY"
+      );
+  }
+}
+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");
+  }
+  return value;
+}
+function compileOrderBy(options, _params) {
+  if (!options?.orderBy) return "";
+  const { field, direction } = options.orderBy;
+  const { expr } = compileFieldRef(field);
+  const dir = direction === "desc" ? "DESC" : "ASC";
+  return ` ORDER BY ${expr} ${dir}`;
+}
+function compileLimit(options, params) {
+  if (options?.limit === void 0) return "";
+  params.push(options.limit);
+  return ` LIMIT ?`;
+}
+function compileSelect(table, filters, options) {
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  let sql = `SELECT * FROM ${quoteIdent2(table)}${where}`;
+  sql += compileOrderBy(options, params);
+  sql += compileLimit(options, params);
+  return { sql, params };
+}
+function compileExpand(table, params) {
+  if (params.sources.length === 0) {
+    throw new FiregraphError(
+      "compileExpand requires a non-empty sources list \u2014 empty IN () is invalid SQL.",
+      "INVALID_QUERY"
+    );
+  }
+  const direction = params.direction ?? "forward";
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const aTypeCol = compileFieldRef("aType").expr;
+  const bTypeCol = compileFieldRef("bType").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  const sourceColumn = direction === "forward" ? aUidCol : bUidCol;
+  const sqlParams = [params.axbType];
+  const conditions = [`${axbTypeCol} = ?`];
+  const placeholders = params.sources.map(() => "?").join(", ");
+  conditions.push(`${sourceColumn} IN (${placeholders})`);
+  for (const uid of params.sources) sqlParams.push(uid);
+  if (params.aType !== void 0) {
+    conditions.push(`${aTypeCol} = ?`);
+    sqlParams.push(params.aType);
+  }
+  if (params.bType !== void 0) {
+    conditions.push(`${bTypeCol} = ?`);
+    sqlParams.push(params.bType);
+  }
+  if (params.axbType === NODE_RELATION) {
+    conditions.push(`${aUidCol} != ${bUidCol}`);
+  }
+  let sql = `SELECT * FROM ${quoteIdent2(table)} WHERE ${conditions.join(" AND ")}`;
+  if (params.orderBy) {
+    sql += compileOrderBy({ orderBy: params.orderBy }, sqlParams);
+  }
+  if (params.limitPerSource !== void 0) {
+    const totalLimit = params.sources.length * params.limitPerSource;
+    sql += ` LIMIT ?`;
+    sqlParams.push(totalLimit);
+  }
+  return { sql, params: sqlParams };
+}
+function compileExpandHydrate(table, targetUids) {
+  if (targetUids.length === 0) {
+    throw new FiregraphError(
+      "compileExpandHydrate requires a non-empty target list \u2014 empty IN () is invalid SQL.",
+      "INVALID_QUERY"
+    );
+  }
+  const placeholders = targetUids.map(() => "?").join(", ");
+  const sqlParams = [NODE_RELATION];
+  for (const uid of targetUids) sqlParams.push(uid);
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  return {
+    sql: `SELECT * FROM ${quoteIdent2(table)} WHERE ${axbTypeCol} = ? AND ${aUidCol} = ${bUidCol} AND ${bUidCol} IN (${placeholders})`,
+    params: sqlParams
+  };
+}
+function compileSelectByDocId(table, docId) {
+  return {
+    sql: `SELECT * FROM ${quoteIdent2(table)} WHERE "doc_id" = ? LIMIT 1`,
+    params: [docId]
+  };
+}
+function normalizeProjectionField(field) {
+  if (field in FIELD_TO_COLUMN) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function compileFindEdgesProjected(table, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "compileFindEdgesProjected requires a non-empty select list \u2014 an empty projection has no SQL representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueFields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      uniqueFields.push(f);
+    }
+  }
+  const projections = [];
+  const columns = [];
+  for (let idx = 0; idx < uniqueFields.length; idx++) {
+    const field = uniqueFields[idx];
+    const canonical = normalizeProjectionField(field);
+    const { expr } = compileFieldRef(canonical);
+    const alias = quoteColumnAlias(field);
+    projections.push(`${expr} AS ${alias}`);
+    let kind;
+    let typeAliasName;
+    if (canonical === "data") {
+      kind = "data";
+    } else if (canonical.startsWith("data.")) {
+      kind = "json";
+      typeAliasName = `__fg_t_${idx}`;
+      const typeAlias = quoteColumnAlias(typeAliasName);
+      projections.push(`json_type("data", '$.${canonical.slice(5)}') AS ${typeAlias}`);
+    } else {
+      if (canonical === "v") kind = "builtin-int";
+      else if (canonical === "createdAt" || canonical === "updatedAt") kind = "builtin-timestamp";
+      else kind = "builtin-text";
+    }
+    columns.push({ field, kind, typeAlias: typeAliasName });
+  }
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  let sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent2(table)}${where}`;
+  sql += compileOrderBy(options, params);
+  sql += compileLimit(options, params);
+  return { stmt: { sql, params }, columns };
+}
+function decodeProjectedRow(row, columns) {
+  const out = {};
+  for (const c of columns) {
+    const raw = row[c.field];
+    switch (c.kind) {
+      case "builtin-text":
+        out[c.field] = raw === null || raw === void 0 ? null : String(raw);
+        break;
+      case "builtin-int":
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else if (typeof raw === "number") {
+          out[c.field] = raw;
+        } else {
+          out[c.field] = Number(raw);
+        }
+        break;
+      case "builtin-timestamp": {
+        const ms = rowTimestampToMillis(raw);
+        out[c.field] = GraphTimestampImpl.fromMillis(ms);
+        break;
+      }
+      case "data":
+        if (raw === null || raw === void 0 || raw === "") {
+          out[c.field] = {};
+        } else {
+          out[c.field] = JSON.parse(raw);
+        }
+        break;
+      case "json": {
+        const t = row[c.typeAlias];
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (t === "object" || t === "array") {
+          out[c.field] = typeof raw === "string" ? JSON.parse(raw) : raw;
+        } else if (t === "integer" && typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else {
+          out[c.field] = raw;
+        }
+        break;
+      }
+    }
+  }
+  return out;
+}
+function compileAggregate(table, spec, filters) {
+  const aliases = Object.keys(spec);
+  if (aliases.length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const projections = [];
+  for (const alias of aliases) {
+    const { op, field } = spec[alias];
+    validateJsonPathKey(alias, BACKEND_ERR_LABEL);
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      projections.push(`COUNT(*) AS ${quoteIdent2(alias)}`);
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    const { expr } = compileFieldRef(field);
+    const numeric = `CAST(${expr} AS REAL)`;
+    if (op === "sum") projections.push(`SUM(${numeric}) AS ${quoteIdent2(alias)}`);
+    else if (op === "avg") projections.push(`AVG(${numeric}) AS ${quoteIdent2(alias)}`);
+    else if (op === "min") projections.push(`MIN(${numeric}) AS ${quoteIdent2(alias)}`);
+    else if (op === "max") projections.push(`MAX(${numeric}) AS ${quoteIdent2(alias)}`);
+    else
+      throw new FiregraphError(
+        `SQLite backend does not support aggregate op: ${String(op)}`,
+        "INVALID_QUERY"
+      );
+  }
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  const sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent2(table)}${where}`;
+  return { stmt: { sql, params }, aliases };
+}
+function compileSet(table, docId, record, nowMillis, mode) {
+  assertJsonSafePayload(record.data, BACKEND_LABEL);
+  if (mode === "replace") {
+    const sql2 = `INSERT OR REPLACE INTO ${quoteIdent2(table)} (
+      doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+    const params = [
+      docId,
+      record.aType,
+      record.aUid,
+      record.axbType,
+      record.bType,
+      record.bUid,
+      JSON.stringify(record.data ?? {}),
+      record.v ?? null,
+      nowMillis,
+      nowMillis
+    ];
+    return { sql: sql2, params };
+  }
+  const insertParams = [
+    docId,
+    record.aType,
+    record.aUid,
+    record.axbType,
+    record.bType,
+    record.bUid,
+    JSON.stringify(record.data ?? {}),
+    record.v ?? null,
+    nowMillis,
+    nowMillis
+  ];
+  const ops = flattenPatch(record.data ?? {});
+  const updateParams = [];
+  const dataExpr = compileDataOpsExpr(ops, `COALESCE("data", '{}')`, updateParams, BACKEND_ERR_LABEL) ?? `COALESCE("data", '{}')`;
+  const sql = `INSERT INTO ${quoteIdent2(table)} (
+      doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(doc_id) DO UPDATE SET
+      "a_type" = excluded."a_type",
+      "a_uid" = excluded."a_uid",
+      "axb_type" = excluded."axb_type",
+      "b_type" = excluded."b_type",
+      "b_uid" = excluded."b_uid",
+      "data" = ${dataExpr},
+      "v" = COALESCE(excluded."v", "v"),
+      "created_at" = excluded."created_at",
+      "updated_at" = excluded."updated_at"`;
+  return { sql, params: [...insertParams, ...updateParams] };
+}
+function compileUpdate(table, docId, update, nowMillis) {
+  assertUpdatePayloadExclusive(update);
+  const setClauses = [];
+  const params = [];
+  if (update.replaceData) {
+    assertJsonSafePayload(update.replaceData, BACKEND_LABEL);
+    setClauses.push(`"data" = ?`);
+    params.push(JSON.stringify(update.replaceData));
+  } else if (update.dataOps && update.dataOps.length > 0) {
+    for (const op of update.dataOps) {
+      if (!op.delete) assertJsonSafePayload(op.value, BACKEND_LABEL);
+    }
+    const expr = compileDataOpsExpr(
+      update.dataOps,
+      `COALESCE("data", '{}')`,
+      params,
+      BACKEND_ERR_LABEL
+    );
+    if (expr !== null) {
+      setClauses.push(`"data" = ${expr}`);
+    }
+  }
+  if (update.v !== void 0) {
+    setClauses.push(`"v" = ?`);
+    params.push(update.v);
+  }
+  setClauses.push(`"updated_at" = ?`);
+  params.push(nowMillis);
+  params.push(docId);
+  return {
+    sql: `UPDATE ${quoteIdent2(table)} SET ${setClauses.join(", ")} WHERE "doc_id" = ?`,
+    params
+  };
+}
+function compileDelete(table, docId) {
+  return {
+    sql: `DELETE FROM ${quoteIdent2(table)} WHERE "doc_id" = ?`,
+    params: [docId]
+  };
+}
+function compileBulkDelete(table, filters) {
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  return {
+    sql: `DELETE FROM ${quoteIdent2(table)}${where}`,
+    params
+  };
+}
+function compileBulkUpdate(table, filters, patchData, nowMillis) {
+  const dataOps = flattenPatch(patchData);
+  if (dataOps.length === 0) {
+    throw new FiregraphError(
+      "bulkUpdate() patch.data must contain at least one leaf \u2014 an empty patch would only rewrite `updated_at`, which is almost certainly a bug. Use `setDoc` with merge mode if you want to stamp without editing data.",
+      "INVALID_QUERY"
+    );
+  }
+  for (const op of dataOps) {
+    if (!op.delete) assertJsonSafePayload(op.value, BACKEND_LABEL);
+  }
+  const setParams = [];
+  const expr = compileDataOpsExpr(dataOps, `COALESCE("data", '{}')`, setParams, BACKEND_ERR_LABEL);
+  if (expr === null) {
+    throw new FiregraphError(
+      "bulkUpdate() patch produced no SQL operations \u2014 internal invariant violated.",
+      "INVALID_ARGUMENT"
+    );
+  }
+  const setClauses = [`"data" = ${expr}`, `"updated_at" = ?`];
+  setParams.push(nowMillis);
+  const whereParams = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, whereParams));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  return {
+    sql: `UPDATE ${quoteIdent2(table)} SET ${setClauses.join(", ")}${where}`,
+    params: [...setParams, ...whereParams]
+  };
+}
+function rowToRecord(row) {
+  const dataString = row.data;
+  const data = dataString ? JSON.parse(dataString) : {};
+  const createdMs = rowTimestampToMillis(row.created_at);
+  const updatedMs = rowTimestampToMillis(row.updated_at);
+  const record = {
+    aType: row.a_type,
+    aUid: row.a_uid,
+    axbType: row.axb_type,
+    bType: row.b_type,
+    bUid: row.b_uid,
+    data,
+    createdAt: GraphTimestampImpl.fromMillis(createdMs),
+    updatedAt: GraphTimestampImpl.fromMillis(updatedMs)
+  };
+  if (row.v !== null && row.v !== void 0) {
+    record.v = Number(row.v);
+  }
+  return record;
+}
+function rowTimestampToMillis(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  throw new FiregraphError(
+    `SQLite row has non-numeric timestamp column: ${typeof value} (${String(value)})`,
+    "INVALID_QUERY"
+  );
+}
+
+// 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 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);
+  return `${rootTable}_graphs`;
+}
+function mangleStorageScope(scope) {
+  let out = "";
+  for (const ch of scope) {
+    if (/[A-Za-z0-9]/.test(ch)) out += ch;
+    else if (ch === "_") out += "__";
+    else if (ch === "-") out += "_h";
+    else if (ch === "/") out += "_s";
+    else out += `_u${ch.codePointAt(0).toString(16)}_`;
+  }
+  return out;
+}
+function tableForScope(rootTable, storageScope) {
+  validateTableName(rootTable);
+  if (storageScope === "") return rootTable;
+  return `${rootTable}_g_${mangleStorageScope(storageScope)}`;
+}
+function escapeLikePrefix(prefix) {
+  return prefix.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+function buildCatalogDDL(rootTable) {
+  const t = quoteIdent2(catalogTableName(rootTable));
+  return `CREATE TABLE IF NOT EXISTS ${t} (
+      storage_scope TEXT NOT NULL PRIMARY KEY,
+      table_name    TEXT NOT NULL UNIQUE,
+      scope_path    TEXT NOT NULL
+    )`;
+}
+function compileCatalogRegister(rootTable, storageScope, tableName, scopePath) {
+  const t = quoteIdent2(catalogTableName(rootTable));
+  return {
+    sql: `INSERT OR IGNORE INTO ${t} (storage_scope, table_name, scope_path) VALUES (?, ?, ?)`,
+    params: [storageScope, tableName, scopePath]
+  };
+}
+function compileCatalogDescendants(rootTable, scopePrefix) {
+  const t = quoteIdent2(catalogTableName(rootTable));
+  return {
+    sql: `SELECT storage_scope, table_name FROM ${t} WHERE storage_scope LIKE ? ESCAPE '\\' ORDER BY storage_scope`,
+    params: [`${escapeLikePrefix(scopePrefix)}/%`]
+  };
+}
+function compileCatalogDelete(rootTable, storageScope) {
+  const t = quoteIdent2(catalogTableName(rootTable));
+  return {
+    sql: `DELETE FROM ${t} WHERE storage_scope = ?`,
+    params: [storageScope]
+  };
+}
+
+// src/sqlite/backend.ts
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_RETRY_DELAY_MS = 200;
+var MAX_RETRY_DELAY_MS = 5e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function minDefined(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return Math.min(a, b);
+}
+function chunkStatements(statements, maxStatements, maxParams) {
+  const stmtCap = maxStatements && maxStatements > 0 && Number.isFinite(maxStatements) ? Math.floor(maxStatements) : Infinity;
+  const paramCap = maxParams && maxParams > 0 && Number.isFinite(maxParams) ? Math.floor(maxParams) : Infinity;
+  if (stmtCap === Infinity && paramCap === Infinity) {
+    return [statements];
+  }
+  const chunks = [];
+  let current = [];
+  let currentParamCount = 0;
+  for (const stmt of statements) {
+    const stmtParams = stmt.params.length;
+    const wouldExceedStmt = current.length + 1 > stmtCap;
+    const wouldExceedParam = currentParamCount + stmtParams > paramCap;
+    if (current.length > 0 && (wouldExceedStmt || wouldExceedParam)) {
+      chunks.push(current);
+      current = [];
+      currentParamCount = 0;
+    }
+    current.push(stmt);
+    currentParamCount += stmtParams;
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+var SqliteTransactionBackendImpl = class {
+  constructor(tx, tableName) {
+    this.tx = tx;
+    this.tableName = tableName;
+  }
+  async getDoc(docId) {
+    const stmt = compileSelectByDocId(this.tableName, docId);
+    const rows = await this.tx.all(stmt.sql, stmt.params);
+    return rows.length === 0 ? null : rowToRecord(rows[0]);
+  }
+  async query(filters, options) {
+    const stmt = compileSelect(this.tableName, filters, options);
+    const rows = await this.tx.all(stmt.sql, stmt.params);
+    return rows.map(rowToRecord);
+  }
+  async setDoc(docId, record, mode) {
+    const stmt = compileSet(this.tableName, docId, record, Date.now(), mode);
+    await this.tx.run(stmt.sql, stmt.params);
+  }
+  async updateDoc(docId, update) {
+    const stmt = compileUpdate(this.tableName, docId, update, Date.now());
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const rows = await this.tx.all(sqlWithReturning, stmt.params);
+    if (rows.length === 0) {
+      throw new FiregraphError(
+        `updateDoc: no document found for doc_id=${docId} (table=${this.tableName})`,
+        "NOT_FOUND"
+      );
+    }
+  }
+  async deleteDoc(docId) {
+    const stmt = compileDelete(this.tableName, docId);
+    await this.tx.run(stmt.sql, stmt.params);
+  }
+};
+var SqliteBatchBackendImpl = class {
+  constructor(executor, tableName, ensureSchema) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.ensureSchema = ensureSchema;
+  }
+  statements = [];
+  setDoc(docId, record, mode) {
+    this.statements.push(compileSet(this.tableName, docId, record, Date.now(), mode));
+  }
+  updateDoc(docId, update) {
+    this.statements.push(compileUpdate(this.tableName, docId, update, Date.now()));
+  }
+  deleteDoc(docId) {
+    this.statements.push(compileDelete(this.tableName, docId));
+  }
+  async commit() {
+    if (this.statements.length === 0) return;
+    await this.ensureSchema();
+    await this.executor.batch(this.statements);
+    this.statements.length = 0;
+  }
+};
+var SQLITE_CORE_CAPS = [
+  "core.read",
+  "core.write",
+  "core.batch",
+  "core.subgraph",
+  "query.aggregate",
+  "query.dml",
+  "query.join",
+  "query.select",
+  "raw.sql"
+];
+var SqliteBackendImpl = class _SqliteBackendImpl {
+  constructor(executor, rootTable, storageScope, scopePath, registry, coreIndexes, extraTableDDL) {
+    this.executor = executor;
+    validateTableName(rootTable);
+    this.rootTable = rootTable;
+    this.collectionPath = tableForScope(rootTable, storageScope);
+    this.storageScope = storageScope;
+    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");
+    }
+    this.capabilities = createCapabilities(caps);
+  }
+  capabilities;
+  /** Physical table holding this graph's triples. */
+  collectionPath;
+  scopePath;
+  /** Storage scope (interleaved parent UIDs + subgraph names) — `''` at root. */
+  storageScope;
+  /** Root graph's table name — prefix for subgraph tables and the catalog. */
+  rootTable;
+  registry;
+  coreIndexes;
+  extraTableDDL;
+  ensured = null;
+  /**
+   * Lazily create this graph's table + indexes + the catalog, and register
+   * the graph in the catalog. Runs once per backend instance; the DDL is
+   * all `IF NOT EXISTS` / `INSERT OR IGNORE`, so concurrent instances over
+   * the same database converge safely.
+   */
+  ensureSchema() {
+    if (!this.ensured) {
+      this.ensured = this.doEnsureSchema().catch((err) => {
+        this.ensured = null;
+        throw err;
+      });
+    }
+    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: [] }));
+    statements.push(
+      compileCatalogRegister(
+        this.rootTable,
+        this.storageScope,
+        this.collectionPath,
+        this.scopePath
+      )
+    );
+    const chunks = chunkStatements(
+      statements,
+      this.executor.maxBatchSize,
+      this.executor.maxBatchParams
+    );
+    for (const chunk of chunks) {
+      await this.executor.batch(chunk);
+    }
+  }
+  /**
+   * Run `op` with the schema bootstrap applied, self-healing when this
+   * graph's table was dropped out from under the instance — a parent's
+   * cascade delete DROPs descendant tables, but subgraph handles created
+   * before the cascade still point at this (now missing) table with a
+   * resolved bootstrap cache. On a "no such table: <own table>" error the
+   * cache resets, the empty graph is recreated, and the op retries once.
+   * This matches Firestore semantics, where a deleted subcollection reads
+   * as empty and writes recreate it.
+   */
+  async withSchema(op) {
+    await this.ensureSchema();
+    try {
+      return await op();
+    } catch (err) {
+      if (!this.isMissingOwnTable(err)) throw err;
+      this.ensured = null;
+      await this.ensureSchema();
+      return op();
+    }
+  }
+  /** True when `err` is SQLite's missing-table error naming OUR table. */
+  isMissingOwnTable(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes(`no such table: ${this.collectionPath}`);
+  }
+  // --- Reads ---
+  async getDoc(docId) {
+    return this.withSchema(async () => {
+      const stmt = compileSelectByDocId(this.collectionPath, docId);
+      const rows = await this.executor.all(stmt.sql, stmt.params);
+      return rows.length === 0 ? null : rowToRecord(rows[0]);
+    });
+  }
+  async query(filters, options) {
+    return this.withSchema(async () => {
+      const stmt = compileSelect(this.collectionPath, filters, options);
+      const rows = await this.executor.all(stmt.sql, stmt.params);
+      return rows.map(rowToRecord);
+    });
+  }
+  // --- Writes ---
+  async setDoc(docId, record, mode) {
+    return this.withSchema(async () => {
+      const stmt = compileSet(this.collectionPath, docId, record, Date.now(), mode);
+      await this.executor.run(stmt.sql, stmt.params);
+    });
+  }
+  async updateDoc(docId, update) {
+    return this.withSchema(async () => {
+      const stmt = compileUpdate(this.collectionPath, docId, update, Date.now());
+      const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+      const rows = await this.executor.all(sqlWithReturning, stmt.params);
+      if (rows.length === 0) {
+        throw new FiregraphError(
+          `updateDoc: no document found for doc_id=${docId} (table=${this.collectionPath})`,
+          "NOT_FOUND"
+        );
+      }
+    });
+  }
+  async deleteDoc(docId) {
+    return this.withSchema(async () => {
+      const stmt = compileDelete(this.collectionPath, docId);
+      await this.executor.run(stmt.sql, stmt.params);
+    });
+  }
+  // --- Transactions / Batches ---
+  async runTransaction(fn) {
+    if (!this.executor.transaction) {
+      throw new FiregraphError(
+        "Interactive transactions are not supported by this SQLite driver. D1 in particular has no read-then-conditional-write transactions; use a Durable Object SQLite client instead, or rewrite the code path as a batch().",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    await this.ensureSchema();
+    return this.executor.transaction(async (tx) => {
+      const txBackend = new SqliteTransactionBackendImpl(tx, this.collectionPath);
+      return fn(txBackend);
+    });
+  }
+  createBatch() {
+    return new SqliteBatchBackendImpl(
+      this.executor,
+      this.collectionPath,
+      () => this.ensureSchema()
+    );
+  }
+  // --- Subgraphs ---
+  subgraph(parentNodeUid, name) {
+    if (!parentNodeUid || parentNodeUid.includes("/")) {
+      throw new FiregraphError(
+        `Invalid parentNodeUid for subgraph: "${parentNodeUid}". Must be a non-empty string without "/".`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    if (!name || name.includes("/")) {
+      throw new FiregraphError(
+        `Subgraph name must not contain "/" and must be non-empty: got "${name}". Use chained .subgraph() calls for nested subgraphs.`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    const newStorageScope = this.storageScope ? `${this.storageScope}/${parentNodeUid}/${name}` : `${parentNodeUid}/${name}`;
+    const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _SqliteBackendImpl(
+      this.executor,
+      this.rootTable,
+      newStorageScope,
+      newScope,
+      this.registry,
+      this.coreIndexes,
+      this.extraTableDDL
+    );
+  }
+  // --- Cascade & bulk ---
+  async removeNodeCascade(uid, reader, options) {
+    await this.ensureSchema();
+    const [outgoingRaw, incomingRaw] = await Promise.all([
+      reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+      reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
+    ]);
+    const seen = /* @__PURE__ */ new Set();
+    const edgeDocIds = [];
+    for (const edge of [...outgoingRaw, ...incomingRaw]) {
+      if (edge.axbType === NODE_RELATION) continue;
+      const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
+      if (!seen.has(docId)) {
+        seen.add(docId);
+        edgeDocIds.push(docId);
+      }
+    }
+    const nodeDocId = computeNodeDocId(uid);
+    const shouldDeleteSubgraphs = options?.deleteSubcollections !== false;
+    const descendants = [];
+    let subgraphRowCount = 0;
+    if (shouldDeleteSubgraphs) {
+      const prefix = this.storageScope ? `${this.storageScope}/${uid}` : uid;
+      const descStmt = compileCatalogDescendants(this.rootTable, prefix);
+      const rows = await this.executor.all(descStmt.sql, descStmt.params);
+      for (const row of rows) {
+        const tableName = String(row.table_name);
+        validateTableName(tableName);
+        descendants.push({ storageScope: String(row.storage_scope), tableName });
+      }
+      for (const d of descendants) {
+        const countRows = await this.executor.all(
+          `SELECT COUNT(*) AS n FROM ${quoteIdent2(d.tableName)}`,
+          []
+        );
+        const n = countRows[0]?.n;
+        subgraphRowCount += typeof n === "bigint" ? Number(n) : Number(n ?? 0);
+      }
+    }
+    const writeStatements = edgeDocIds.map(
+      (id) => compileDelete(this.collectionPath, id)
+    );
+    writeStatements.push(compileDelete(this.collectionPath, nodeDocId));
+    for (const d of descendants) {
+      writeStatements.push({ sql: `DROP TABLE IF EXISTS ${quoteIdent2(d.tableName)}`, params: [] });
+      writeStatements.push(compileCatalogDelete(this.rootTable, d.storageScope));
+    }
+    const {
+      deleted: stmtDeleted,
+      batches,
+      errors
+    } = await this.executeChunkedBatches(writeStatements, options);
+    const allOk = errors.length === 0;
+    const edgesDeleted = allOk ? edgeDocIds.length : 0;
+    const nodeDeleted = allOk;
+    const bookkeepingContribution = allOk ? descendants.length * 2 : 0;
+    const deleted = stmtDeleted - bookkeepingContribution + (allOk ? subgraphRowCount : 0);
+    return { deleted, batches, errors, edgesDeleted, nodeDeleted };
+  }
+  async bulkRemoveEdges(params, reader, options) {
+    await this.ensureSchema();
+    const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+    const edges = await reader.findEdges(effectiveParams);
+    const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+    if (docIds.length === 0) {
+      return { deleted: 0, batches: 0, errors: [] };
+    }
+    const statements = docIds.map((id) => compileDelete(this.collectionPath, id));
+    return this.executeChunkedBatches(statements, options);
+  }
+  /**
+   * Submit `statements` to the executor as one or more `batch()` calls,
+   * chunking by `executor.maxBatchSize` (e.g. D1's ~100-statement cap).
+   * Drivers that don't advertise a cap submit everything in one batch,
+   * preserving cross-batch atomicity.
+   *
+   * Each chunk is retried with exponential backoff up to `maxRetries`
+   * (default 3) before being recorded in `errors`. The loop continues past
+   * a permanently failed chunk so the caller still gets partial progress
+   * visibility — to halt on first failure, set `maxRetries: 0` and check
+   * `result.errors.length` after the call.
+   *
+   * Returns `BulkResult`-shaped fields. `deleted` reflects only the
+   * statement count of *successfully committed* batches — a DROP TABLE
+   * statement contributes 1 to that total even though it may remove many
+   * rows; `removeNodeCascade` patches that up with pre-counted row totals.
+   *
+   * **Atomicity caveat (D1):** when chunking kicks in, atomicity is lost
+   * across chunk boundaries — one chunk may commit while a later one fails.
+   * `removeNodeCascade` is idempotent (deleting the same docs again is a
+   * no-op) so a caller can simply retry on partial failure. `bulkRemoveEdges`
+   * is also idempotent for the same reason. DO SQLite leaves `maxBatchSize`
+   * unset, so everything funnels through one atomic `transactionSync` and
+   * this caveat does not apply.
+   */
+  async executeChunkedBatches(statements, options) {
+    if (statements.length === 0) {
+      return { deleted: 0, batches: 0, errors: [] };
+    }
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const callerBatchSize = options?.batchSize;
+    const stmtCap = minDefined(callerBatchSize, this.executor.maxBatchSize);
+    const chunks = chunkStatements(statements, stmtCap, this.executor.maxBatchParams);
+    const errors = [];
+    let deleted = 0;
+    let batches = 0;
+    const totalBatches = chunks.length;
+    const driverParamCap = this.executor.maxBatchParams;
+    for (let batchIndex = 0; batchIndex < chunks.length; batchIndex++) {
+      const chunk = chunks[batchIndex];
+      const isUnretriableOversize = chunk.length === 1 && driverParamCap !== void 0 && chunk[0].params.length > driverParamCap;
+      let committed = false;
+      let lastError = null;
+      const effectiveRetries = isUnretriableOversize ? 0 : maxRetries;
+      for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
+        try {
+          await this.executor.batch(chunk);
+          committed = true;
+          break;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+          if (attempt < effectiveRetries) {
+            const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+            await sleep(delay);
+          }
+        }
+      }
+      if (committed) {
+        deleted += chunk.length;
+        batches += 1;
+      } else if (lastError) {
+        errors.push({
+          batchIndex,
+          error: lastError,
+          operationCount: chunk.length
+        });
+      }
+      if (options?.onProgress) {
+        options.onProgress({
+          completedBatches: batches,
+          totalBatches,
+          deletedSoFar: deleted
+        });
+      }
+    }
+    return { deleted, batches, errors };
+  }
+  // `findEdgesGlobal` is deliberately NOT defined on this class. Each graph
+  // is its own table, so a "collection group" query would mean scanning every
+  // table listed in the catalog — an unbounded fan-out the cross-backend
+  // contract treats as unsupported (the Cloudflare DO edition makes the same
+  // call: no cross-DO index, no `findEdgesGlobal`). The client surfaces
+  // `UNSUPPORTED_OPERATION` when the method is absent.
+  // --- Aggregate ---
+  /**
+   * Run an aggregate query in a single SQL statement. Supports the full
+   * count/sum/avg/min/max set — the SQLite engine evaluates each aggregate
+   * function over the filtered row set and the executor returns one row
+   * with one column per alias. SUM/MIN/MAX of an empty set returns 0
+   * (SQLite's `SUM(NULL) = NULL` is mapped to a clean number for the
+   * cross-backend contract); AVG returns NaN, matching the mathematical
+   * convention and the Firestore Standard helper.
+   */
+  async aggregate(spec, filters) {
+    const { stmt, aliases } = compileAggregate(this.collectionPath, spec, filters);
+    const rows = await this.withSchema(() => this.executor.all(stmt.sql, stmt.params));
+    const row = rows[0] ?? {};
+    const out = {};
+    for (const alias of aliases) {
+      const v = row[alias];
+      if (v === null || v === void 0) {
+        const op = spec[alias].op;
+        out[alias] = op === "avg" ? Number.NaN : 0;
+      } else if (typeof v === "bigint") {
+        out[alias] = Number(v);
+      } else if (typeof v === "number") {
+        out[alias] = v;
+      } else {
+        out[alias] = Number(v);
+      }
+    }
+    return out;
+  }
+  // --- Server-side DML ---
+  /**
+   * Delete every row matching `filters` in a single SQL DELETE statement.
+   *
+   * Uses `RETURNING "doc_id"` to count rows touched — the SQLite executor's
+   * `run` returns void, so RETURNING + `all()` is the portable way to learn
+   * how many rows the engine actually deleted. SQLite ≥ 3.35 supports
+   * `DELETE … RETURNING`; better-sqlite3, D1, and DO SQLite all run on a
+   * recent enough engine.
+   *
+   * Single-statement DML doesn't chunk: the engine handles N rows in one
+   * shot, so `BulkOptions.batchSize` is intentionally ignored. The retry
+   * loop here exists only for transient driver errors (e.g. D1 surface
+   * congestion); a permanent failure is surfaced via the `errors` array
+   * with `batchIndex: 0` so callers see the same shape as `bulkRemoveEdges`.
+   *
+   * Subgraph isolation is physical — the statement only ever touches this
+   * graph's table, so no scoping predicate is needed.
+   */
+  async bulkDelete(filters, options) {
+    await this.ensureSchema();
+    const stmt = compileBulkDelete(this.collectionPath, filters);
+    return this.executeDmlWithReturning(stmt, options);
+  }
+  /**
+   * Update every row matching `filters` with `patch.data` in a single SQL
+   * UPDATE statement. The patch is deep-merged into each row's `data`
+   * column via the same `flattenPatch` → `compileDataOpsExpr` pipeline that
+   * `compileUpdate` (single-row) uses.
+   *
+   * Same contract notes as `bulkDelete` apply: single-statement, no
+   * chunking, `RETURNING "doc_id"` for the affected count, retry loop for
+   * transient driver errors.
+   */
+  async bulkUpdate(filters, patch, options) {
+    await this.ensureSchema();
+    const stmt = compileBulkUpdate(this.collectionPath, filters, patch.data, Date.now());
+    return this.executeDmlWithReturning(stmt, options);
+  }
+  /**
+   * Multi-source fan-out — `query.join` capability.
+   *
+   * Issues a single `SELECT … WHERE "aUid" IN (?, ?, …)` statement that
+   * matches every edge from every source UID in one round trip. When
+   * `params.hydrate === true`, follows up with a second statement that
+   * fetches the target node rows; both queries hit the same table so
+   * the executor amortises connection / parsing cost across them.
+   *
+   * Empty `params.sources` short-circuits to an empty result without
+   * touching the executor — `IN ()` is not valid SQL.
+   *
+   * Per-source ordering / strict per-source LIMIT enforcement is NOT
+   * implemented here; see the `ExpandParams.limitPerSource` JSDoc and
+   * `compileExpand` for the cap semantics. Strict per-source caps would
+   * require window functions and were judged out of scope for the
+   * round-trip-collapse goal.
+   */
+  async expand(params) {
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    const stmt = compileExpand(this.collectionPath, params);
+    const rows = await this.withSchema(() => this.executor.all(stmt.sql, stmt.params));
+    const edges = rows.map(rowToRecord);
+    if (!params.hydrate) {
+      return { edges };
+    }
+    const direction = params.direction ?? "forward";
+    const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+    const uniqueTargets = [...new Set(targetUids)];
+    if (uniqueTargets.length === 0) {
+      return { edges, targets: [] };
+    }
+    const hydrateStmt = compileExpandHydrate(this.collectionPath, uniqueTargets);
+    const hydrateRows = await this.executor.all(hydrateStmt.sql, hydrateStmt.params);
+    const byUid = /* @__PURE__ */ new Map();
+    for (const row of hydrateRows) {
+      const node = rowToRecord(row);
+      byUid.set(node.bUid, node);
+    }
+    const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+    return { edges, targets };
+  }
+  /**
+   * Server-side projection — `query.select` capability.
+   *
+   * Issues a single `SELECT json_extract(data, '$.f1'), …` statement that
+   * returns only the requested fields. The compiler emits one column per
+   * unique field plus a paired `json_type` column for `data.*` projections
+   * so the decoder can recover JSON-encoded objects/arrays without a
+   * second round trip. Migrations are NOT applied — the caller asked for
+   * a partial shape, and rehydrating that into the migration pipeline
+   * would require synthesising every absent field.
+   *
+   * The wire-payload reduction is the entire reason this method exists:
+   * a list view that only needs `title` / `date` no longer drags the
+   * full `data` JSON across the network. Callers that need the full
+   * record should use `findEdges` (with migration support).
+   */
+  async findEdgesProjected(select, filters, options) {
+    const { stmt, columns } = compileFindEdgesProjected(
+      this.collectionPath,
+      select,
+      filters,
+      options
+    );
+    const rows = await this.withSchema(() => this.executor.all(stmt.sql, stmt.params));
+    return rows.map((row) => decodeProjectedRow(row, columns));
+  }
+  /**
+   * Run a DML statement with `RETURNING "doc_id"` so we can count the
+   * rows the engine touched, with the same retry/backoff contract as
+   * `executeChunkedBatches`. Single statement, single batch.
+   */
+  async executeDmlWithReturning(stmt, options) {
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const rows = await this.executor.all(sqlWithReturning, stmt.params);
+        const deleted = rows.length;
+        if (options?.onProgress) {
+          options.onProgress({
+            completedBatches: 1,
+            totalBatches: 1,
+            deletedSoFar: deleted
+          });
+        }
+        return { deleted, batches: 1, errors: [] };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxRetries) {
+          const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+          await sleep(delay);
+        }
+      }
+    }
+    return {
+      deleted: 0,
+      batches: 0,
+      errors: [
+        {
+          batchIndex: 0,
+          error: lastError ?? new Error("bulk DML failed for unknown reason"),
+          operationCount: 0
+        }
+      ]
+    };
+  }
+};
+function createSqliteBackend(executor, tableName, options = {}) {
+  const storageScope = options.storageScope ?? "";
+  const scopePath = options.scopePath ?? "";
+  return new SqliteBackendImpl(
+    executor,
+    tableName,
+    storageScope,
+    scopePath,
+    options.registry,
+    options.coreIndexes,
+    options.extraTableDDL
+  );
+}
+
+// src/sqlite/local.ts
+function createBetterSqliteExecutor(db) {
+  return {
+    async all(sql, params) {
+      return db.prepare(sql).all(...params);
+    },
+    async run(sql, params) {
+      db.prepare(sql).run(...params);
+    },
+    async batch(statements) {
+      const tx = db.transaction((stmts) => {
+        for (const s of stmts) {
+          db.prepare(s.sql).run(...s.params);
+        }
+      });
+      tx(statements);
+    },
+    async transaction(fn) {
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const result = await fn({
+          async all(sql, params) {
+            return db.prepare(sql).all(...params);
+          },
+          async run(sql, params) {
+            db.prepare(sql).run(...params);
+          }
+        });
+        db.exec("COMMIT");
+        return result;
+      } catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+      }
+    }
+  };
+}
+function isDatabase(value) {
+  return typeof value === "object" && value !== null && typeof value.prepare === "function" && typeof value.exec === "function";
+}
+var PRAGMA_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PRAGMA_VALUE_PATTERN = /^-?[A-Za-z0-9_]+$/;
+function applyPragmas(db, pragmas) {
+  for (const [key, value] of Object.entries(pragmas)) {
+    if (!PRAGMA_KEY_PATTERN.test(key)) {
+      throw new FiregraphError(`Invalid pragma name: ${JSON.stringify(key)}`, "INVALID_ARGUMENT");
+    }
+    if (!PRAGMA_VALUE_PATTERN.test(String(value)) || typeof value === "number" && !Number.isFinite(value)) {
+      throw new FiregraphError(
+        `Invalid pragma value for ${key}: ${JSON.stringify(value)}`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    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 (message.includes("fts5") || message.includes("unknown special query")) {
+          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",
+    busyTimeoutMs = 5e3,
+    pragmas,
+    fileMustExist,
+    ...backendOptions
+  } = options;
+  let db;
+  let ownsDb;
+  if (typeof pathOrDb === "string") {
+    let Database;
+    try {
+      Database = (await import("better-sqlite3")).default;
+    } catch (err) {
+      throw new FiregraphError(
+        `createLocalSqliteBackend requires the optional peer dependency 'better-sqlite3' \u2014 install it to use the local SQLite backend (${err instanceof Error ? err.message : String(err)})`,
+        "MISSING_DEPENDENCY"
+      );
+    }
+    db = new Database(pathOrDb, fileMustExist ? { fileMustExist: true } : {});
+    ownsDb = true;
+    db.pragma("journal_mode = WAL");
+  } else if (isDatabase(pathOrDb)) {
+    db = pathOrDb;
+    ownsDb = false;
+  } else {
+    throw new FiregraphError(
+      "createLocalSqliteBackend expects a file path or an open better-sqlite3 Database",
+      "INVALID_ARGUMENT"
+    );
+  }
+  db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
+  if (pragmas) {
+    applyPragmas(db, pragmas);
+  }
+  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,
+    db,
+    close() {
+      if (closed || !ownsDb) return;
+      closed = true;
+      db.close();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createBetterSqliteExecutor,
+  createLocalSqliteBackend
+});
+//# sourceMappingURL=local.cjs.map