@typicalday/firegraph 0.14.1 → 0.16.0

package/dist/sqlite/index.cjs

@@ -2048,7 +2048,7 @@ var GraphClientImpl = class _GraphClientImpl {
   async findNearest(params) {
     if (!this.backend.findNearest) {
       throw new FiregraphError(
-        "findNearest() is not supported by the current storage backend. Vector search requires a backend that declares `search.vector` (currently Firestore Standard and Enterprise). There is no client-side fallback because emulating ANN on top of the generic backend surface does not scale beyond toy datasets.",
+        "findNearest() is not supported by the current storage backend. Vector search requires a backend that declares `search.vector` (currently Firestore Standard, Firestore Enterprise, and the local better-sqlite3 backend). There is no client-side fallback because emulating ANN on top of the generic backend surface does not scale beyond toy datasets.",
         "UNSUPPORTED_OPERATION"
       );
     }
@@ -2064,13 +2064,15 @@ var GraphClientImpl = class _GraphClientImpl {
    * Native full-text search (capability `search.fullText`).
    *
    * Returns the top-N records by relevance, ordered by the search
-   * index's score. Only Firestore Enterprise declares this capability
-   * today — the underlying Pipelines `search({ query: documentMatches(...) })`
-   * stage requires Enterprise's FTS index. Standard does not declare
-   * the cap (FTS is an Enterprise-only product feature, not a
-   * typed-API gap), and the SQLite-shaped backends have no native
-   * FTS index. Backends without `search.fullText` throw
-   * `UNSUPPORTED_OPERATION` from this wrapper.
+   * index's score. Firestore Enterprise declares this capability (via
+   * the Pipelines `search({ query: documentMatches(...) })` stage over
+   * Enterprise's FTS index), as does the local better-sqlite3 backend
+   * (`firegraph/sqlite-local`, via a trigger-synced FTS5 index ranked
+   * by `bm25()`). Standard does not declare the cap (FTS is an
+   * Enterprise-only product feature, not a typed-API gap); D1 and the
+   * Cloudflare DO edition have no FTS trigger infrastructure. Backends
+   * without `search.fullText` throw `UNSUPPORTED_OPERATION` from this
+   * wrapper.
    *
    * Scan-protection mirrors `findNearest`: a search with no
    * identifying filters (`aType` / `axbType` / `bType`) walks every
@@ -2086,7 +2088,7 @@ var GraphClientImpl = class _GraphClientImpl {
   async fullTextSearch(params) {
     if (!this.backend.fullTextSearch) {
       throw new FiregraphError(
-        "fullTextSearch() is not supported by the current storage backend. Full-text search requires a backend that declares `search.fullText` (currently Firestore Enterprise only \u2014 FTS is an Enterprise product feature). There is no client-side fallback because emulating FTS over the generic backend surface would not scale beyond toy datasets.",
+        "fullTextSearch() is not supported by the current storage backend. Full-text search requires a backend that declares `search.fullText` (currently Firestore Enterprise and the local better-sqlite3 backend). There is no client-side fallback because emulating FTS over the generic backend surface would not scale beyond toy datasets.",
         "UNSUPPORTED_OPERATION"
       );
     }
@@ -2308,6 +2310,186 @@ function createCapabilities(caps) {
   };
 }
 
+// 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/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",
@@ -2321,7 +2503,7 @@ function isFirestoreSpecialType(value) {
   if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
   return null;
 }
-var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 function validateJsonPathKey(key, backendLabel) {
   if (key.length === 0) {
     throw new FiregraphError(
@@ -2329,7 +2511,7 @@ function validateJsonPathKey(key, backendLabel) {
       "INVALID_QUERY"
     );
   }
-  if (!JSON_PATH_KEY_RE.test(key)) {
+  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"
@@ -2457,79 +2639,18 @@ function formatTagValue(value) {
   return typeof value;
 }
 
-// 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-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 quoteIdent(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/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/sqlite/sql.ts
-var SQLITE_BACKEND_LABEL = "shared-table SQLite";
-var SQLITE_BACKEND_ERR_LABEL = "SQLite backend";
+// 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: quoteIdent(column) };
+    return { expr: quoteIdent2(column) };
   }
   if (field.startsWith("data.")) {
     const suffix = field.slice(5);
     for (const part of suffix.split(".")) {
-      validateJsonPathKey(part, SQLITE_BACKEND_ERR_LABEL);
+      validateJsonPathKey(part, BACKEND_ERR_LABEL);
     }
     return { expr: `json_extract("data", '$.${suffix}')` };
   }
@@ -2624,95 +2745,81 @@ function compileLimit(options, params) {
   params.push(options.limit);
   return ` LIMIT ?`;
 }
-function compileSelect(table, scope, filters, options) {
+function compileSelect(table, filters, options) {
   const params = [];
-  const conditions = ['"scope" = ?'];
-  params.push(scope);
+  const conditions = [];
   for (const f of filters) {
     conditions.push(compileFilter(f, params));
   }
-  let sql = `SELECT * FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
-  const orderClause = compileOrderBy(options, params);
-  sql += orderClause;
+  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 compileAggregate(table, scope, spec, filters) {
-  const aliases = Object.keys(spec);
-  if (aliases.length === 0) {
+function compileExpand(table, params) {
+  if (params.sources.length === 0) {
     throw new FiregraphError(
-      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "compileExpand requires a non-empty sources list \u2014 empty IN () is invalid SQL.",
       "INVALID_QUERY"
     );
   }
-  const projections = [];
-  for (const alias of aliases) {
-    const { op, field } = spec[alias];
-    validateJsonPathKey(alias, SQLITE_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 ${quoteIdent(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 ${quoteIdent(alias)}`);
-    else if (op === "avg") projections.push(`AVG(${numeric}) AS ${quoteIdent(alias)}`);
-    else if (op === "min") projections.push(`MIN(${numeric}) AS ${quoteIdent(alias)}`);
-    else if (op === "max") projections.push(`MAX(${numeric}) AS ${quoteIdent(alias)}`);
-    else
-      throw new FiregraphError(
-        `SQLite backend does not support aggregate op: ${String(op)}`,
-        "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);
   }
-  const params = [scope];
-  const conditions = ['"scope" = ?'];
-  for (const f of filters) {
-    conditions.push(compileFilter(f, params));
+  if (params.bType !== void 0) {
+    conditions.push(`${bTypeCol} = ?`);
+    sqlParams.push(params.bType);
   }
-  const sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
-  return { stmt: { sql, params }, aliases };
+  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 compileSelectGlobal(table, filters, options, scopeNameFilter) {
-  if (filters.length === 0) {
+function compileExpandHydrate(table, targetUids) {
+  if (targetUids.length === 0) {
     throw new FiregraphError(
-      "compileSelectGlobal requires at least one filter \u2014 refusing to issue an unbounded SELECT.",
+      "compileExpandHydrate requires a non-empty target list \u2014 empty IN () is invalid SQL.",
       "INVALID_QUERY"
     );
   }
-  const params = [];
-  const conditions = [];
-  if (scopeNameFilter) {
-    if (scopeNameFilter.isRoot) {
-      conditions.push(`"scope" = ?`);
-      params.push("");
-    } else {
-      conditions.push(`"scope" LIKE ? ESCAPE '\\'`);
-      params.push(`%/${escapeLike(scopeNameFilter.name)}`);
-    }
-  }
-  for (const f of filters) {
-    conditions.push(compileFilter(f, params));
-  }
-  const sql = `SELECT * FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}` + compileOrderBy(options, params) + compileLimit(options, params);
-  return { sql, params };
+  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, scope, docId) {
+function compileSelectByDocId(table, docId) {
   return {
-    sql: `SELECT * FROM ${quoteIdent(table)} WHERE "scope" = ? AND "doc_id" = ? LIMIT 1`,
-    params: [scope, docId]
+    sql: `SELECT * FROM ${quoteIdent2(table)} WHERE "doc_id" = ? LIMIT 1`,
+    params: [docId]
   };
 }
 function normalizeProjectionField(field) {
@@ -2720,7 +2827,7 @@ function normalizeProjectionField(field) {
   if (field === "data" || field.startsWith("data.")) return field;
   return `data.${field}`;
 }
-function compileFindEdgesProjected(table, scope, select, filters, options) {
+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`.",
@@ -2759,12 +2866,13 @@ function compileFindEdgesProjected(table, scope, select, filters, options) {
     }
     columns.push({ field, kind, typeAlias: typeAliasName });
   }
-  const params = [scope];
-  const conditions = ['"scope" = ?'];
+  const params = [];
+  const conditions = [];
   for (const f of filters) {
     conditions.push(compileFilter(f, params));
   }
-  let sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  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 };
@@ -2789,7 +2897,7 @@ function decodeProjectedRow(row, columns) {
         }
         break;
       case "builtin-timestamp": {
-        const ms = toMillis(raw);
+        const ms = rowTimestampToMillis(raw);
         out[c.field] = GraphTimestampImpl.fromMillis(ms);
         break;
       }
@@ -2817,74 +2925,63 @@ function decodeProjectedRow(row, columns) {
   }
   return out;
 }
-function compileExpand(table, scope, params) {
-  if (params.sources.length === 0) {
+function compileAggregate(table, spec, filters) {
+  const aliases = Object.keys(spec);
+  if (aliases.length === 0) {
     throw new FiregraphError(
-      "compileExpand requires a non-empty sources list \u2014 empty IN () is invalid SQL. Callers should short-circuit empty input before reaching the compiler.",
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
       "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 = [scope, params.axbType];
-  const conditions = ['"scope" = ?', `${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 ${quoteIdent(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);
+  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"
+      );
   }
-  return { sql, params: sqlParams };
-}
-function compileExpandHydrate(table, scope, targetUids) {
-  if (targetUids.length === 0) {
-    throw new FiregraphError(
-      "compileExpandHydrate requires a non-empty target list \u2014 empty IN () is invalid SQL.",
-      "INVALID_QUERY"
-    );
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
   }
-  const placeholders = targetUids.map(() => "?").join(", ");
-  const sqlParams = [scope, 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 ${quoteIdent(table)} WHERE "scope" = ? AND ${axbTypeCol} = ? AND ${aUidCol} = ${bUidCol} AND ${bUidCol} IN (${placeholders})`,
-    params: sqlParams
-  };
+  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, scope, docId, record, nowMillis, mode) {
-  assertJsonSafePayload(record.data, SQLITE_BACKEND_LABEL);
+function compileSet(table, docId, record, nowMillis, mode) {
+  assertJsonSafePayload(record.data, BACKEND_LABEL);
   if (mode === "replace") {
-    const sql2 = `INSERT OR REPLACE INTO ${quoteIdent(table)} (
-      doc_id, scope, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+    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,
-      scope,
       record.aType,
       record.aUid,
       record.axbType,
@@ -2899,7 +2996,6 @@ function compileSet(table, scope, docId, record, nowMillis, mode) {
   }
   const insertParams = [
     docId,
-    scope,
     record.aType,
     record.aUid,
     record.axbType,
@@ -2912,11 +3008,11 @@ function compileSet(table, scope, docId, record, nowMillis, mode) {
   ];
   const ops = flattenPatch(record.data ?? {});
   const updateParams = [];
-  const dataExpr = compileDataOpsExpr(ops, `COALESCE("data", '{}')`, updateParams, SQLITE_BACKEND_ERR_LABEL) ?? `COALESCE("data", '{}')`;
-  const sql = `INSERT INTO ${quoteIdent(table)} (
-      doc_id, scope, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(scope, doc_id) DO UPDATE SET
+  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",
@@ -2928,23 +3024,23 @@ function compileSet(table, scope, docId, record, nowMillis, mode) {
       "updated_at" = excluded."updated_at"`;
   return { sql, params: [...insertParams, ...updateParams] };
 }
-function compileUpdate(table, scope, docId, update, nowMillis) {
+function compileUpdate(table, docId, update, nowMillis) {
   assertUpdatePayloadExclusive(update);
   const setClauses = [];
   const params = [];
   if (update.replaceData) {
-    assertJsonSafePayload(update.replaceData, SQLITE_BACKEND_LABEL);
+    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, SQLITE_BACKEND_LABEL);
+      if (!op.delete) assertJsonSafePayload(op.value, BACKEND_LABEL);
     }
     const expr = compileDataOpsExpr(
       update.dataOps,
       `COALESCE("data", '{}')`,
       params,
-      SQLITE_BACKEND_ERR_LABEL
+      BACKEND_ERR_LABEL
     );
     if (expr !== null) {
       setClauses.push(`"data" = ${expr}`);
@@ -2956,30 +3052,31 @@ function compileUpdate(table, scope, docId, update, nowMillis) {
   }
   setClauses.push(`"updated_at" = ?`);
   params.push(nowMillis);
-  params.push(scope, docId);
+  params.push(docId);
   return {
-    sql: `UPDATE ${quoteIdent(table)} SET ${setClauses.join(", ")} WHERE "scope" = ? AND "doc_id" = ?`,
+    sql: `UPDATE ${quoteIdent2(table)} SET ${setClauses.join(", ")} WHERE "doc_id" = ?`,
     params
   };
 }
-function compileDelete(table, scope, docId) {
+function compileDelete(table, docId) {
   return {
-    sql: `DELETE FROM ${quoteIdent(table)} WHERE "scope" = ? AND "doc_id" = ?`,
-    params: [scope, docId]
+    sql: `DELETE FROM ${quoteIdent2(table)} WHERE "doc_id" = ?`,
+    params: [docId]
   };
 }
-function compileBulkDelete(table, scope, filters) {
-  const params = [scope];
-  const conditions = ['"scope" = ?'];
+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 ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`,
+    sql: `DELETE FROM ${quoteIdent2(table)}${where}`,
     params
   };
 }
-function compileBulkUpdate(table, scope, filters, patchData, nowMillis) {
+function compileBulkUpdate(table, filters, patchData, nowMillis) {
   const dataOps = flattenPatch(patchData);
   if (dataOps.length === 0) {
     throw new FiregraphError(
@@ -2988,15 +3085,10 @@ function compileBulkUpdate(table, scope, filters, patchData, nowMillis) {
     );
   }
   for (const op of dataOps) {
-    if (!op.delete) assertJsonSafePayload(op.value, SQLITE_BACKEND_LABEL);
+    if (!op.delete) assertJsonSafePayload(op.value, BACKEND_LABEL);
   }
   const setParams = [];
-  const expr = compileDataOpsExpr(
-    dataOps,
-    `COALESCE("data", '{}')`,
-    setParams,
-    SQLITE_BACKEND_ERR_LABEL
-  );
+  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.",
@@ -3005,38 +3097,22 @@ function compileBulkUpdate(table, scope, filters, patchData, nowMillis) {
   }
   const setClauses = [`"data" = ${expr}`, `"updated_at" = ?`];
   setParams.push(nowMillis);
-  const whereParams = [scope];
-  const conditions = ['"scope" = ?'];
+  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 ${quoteIdent(table)} SET ${setClauses.join(", ")} WHERE ${conditions.join(" AND ")}`,
+    sql: `UPDATE ${quoteIdent2(table)} SET ${setClauses.join(", ")}${where}`,
     params: [...setParams, ...whereParams]
   };
 }
-function compileDeleteScopePrefix(table, scopePrefix) {
-  const escaped = escapeLike(scopePrefix);
-  return {
-    sql: `DELETE FROM ${quoteIdent(table)} WHERE "scope" LIKE ? ESCAPE '\\'`,
-    params: [`${escaped}/%`]
-  };
-}
-function compileCountScopePrefix(table, scopePrefix) {
-  const escaped = escapeLike(scopePrefix);
-  return {
-    sql: `SELECT COUNT(*) AS n FROM ${quoteIdent(table)} WHERE "scope" LIKE ? ESCAPE '\\'`,
-    params: [`${escaped}/%`]
-  };
-}
-function escapeLike(value) {
-  return value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
-}
 function rowToRecord(row) {
   const dataString = row.data;
   const data = dataString ? JSON.parse(dataString) : {};
-  const createdMs = toMillis(row.created_at);
-  const updatedMs = toMillis(row.updated_at);
+  const createdMs = rowTimestampToMillis(row.created_at);
+  const updatedMs = rowTimestampToMillis(row.updated_at);
   const record = {
     aType: row.a_type,
     aUid: row.a_uid,
@@ -3052,11 +3128,71 @@ function rowToRecord(row) {
   }
   return record;
 }
-function toMillis(value) {
+function rowTimestampToMillis(value) {
   if (typeof value === "number") return value;
   if (typeof value === "bigint") return Number(value);
-  if (typeof value === "string") return Number(value);
-  return 0;
+  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/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
@@ -3096,63 +3232,59 @@ function chunkStatements(statements, maxStatements, maxParams) {
   return chunks;
 }
 var SqliteTransactionBackendImpl = class {
-  constructor(tx, tableName, storageScope) {
+  constructor(tx, tableName) {
     this.tx = tx;
     this.tableName = tableName;
-    this.storageScope = storageScope;
   }
   async getDoc(docId) {
-    const stmt = compileSelectByDocId(this.tableName, this.storageScope, 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, this.storageScope, 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, this.storageScope, docId, record, Date.now(), 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, this.storageScope, docId, update, Date.now());
+    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} (scope=${this.storageScope})`,
+        `updateDoc: no document found for doc_id=${docId} (table=${this.tableName})`,
         "NOT_FOUND"
       );
     }
   }
   async deleteDoc(docId) {
-    const stmt = compileDelete(this.tableName, this.storageScope, docId);
+    const stmt = compileDelete(this.tableName, docId);
     await this.tx.run(stmt.sql, stmt.params);
   }
 };
 var SqliteBatchBackendImpl = class {
-  constructor(executor, tableName, storageScope) {
+  constructor(executor, tableName, ensureSchema) {
     this.executor = executor;
     this.tableName = tableName;
-    this.storageScope = storageScope;
+    this.ensureSchema = ensureSchema;
   }
   statements = [];
   setDoc(docId, record, mode) {
-    this.statements.push(
-      compileSet(this.tableName, this.storageScope, docId, record, Date.now(), mode)
-    );
+    this.statements.push(compileSet(this.tableName, docId, record, Date.now(), mode));
   }
   updateDoc(docId, update) {
-    this.statements.push(
-      compileUpdate(this.tableName, this.storageScope, docId, update, Date.now())
-    );
+    this.statements.push(compileUpdate(this.tableName, docId, update, Date.now()));
   }
   deleteDoc(docId) {
-    this.statements.push(compileDelete(this.tableName, this.storageScope, 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;
   }
@@ -3169,11 +3301,16 @@ var SQLITE_CORE_CAPS = [
   "raw.sql"
 ];
 var SqliteBackendImpl = class _SqliteBackendImpl {
-  constructor(executor, tableName, storageScope, scopePath) {
+  constructor(executor, rootTable, storageScope, scopePath, registry, coreIndexes, extraTableDDL) {
     this.executor = executor;
-    this.collectionPath = tableName;
+    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");
@@ -3181,48 +3318,130 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     this.capabilities = createCapabilities(caps);
   }
   capabilities;
-  /** Logical table name (returned through `collectionPath` for parity with Firestore). */
+  /** Physical table holding this graph's triples. */
   collectionPath;
   scopePath;
-  /** Materialized storage scope (interleaved parent UIDs + subgraph names). */
+  /** 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) {
-    const stmt = compileSelectByDocId(this.collectionPath, this.storageScope, docId);
-    const rows = await this.executor.all(stmt.sql, stmt.params);
-    return rows.length === 0 ? null : rowToRecord(rows[0]);
+    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) {
-    const stmt = compileSelect(this.collectionPath, this.storageScope, filters, options);
-    const rows = await this.executor.all(stmt.sql, stmt.params);
-    return rows.map(rowToRecord);
+    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) {
-    const stmt = compileSet(
-      this.collectionPath,
-      this.storageScope,
-      docId,
-      record,
-      Date.now(),
-      mode
-    );
-    await this.executor.run(stmt.sql, stmt.params);
+    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) {
-    const stmt = compileUpdate(this.collectionPath, this.storageScope, 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} (scope=${this.storageScope})`,
-        "NOT_FOUND"
-      );
-    }
+    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) {
-    const stmt = compileDelete(this.collectionPath, this.storageScope, docId);
-    await this.executor.run(stmt.sql, stmt.params);
+    return this.withSchema(async () => {
+      const stmt = compileDelete(this.collectionPath, docId);
+      await this.executor.run(stmt.sql, stmt.params);
+    });
   }
   // --- Transactions / Batches ---
   async runTransaction(fn) {
@@ -3232,17 +3451,18 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
         "UNSUPPORTED_OPERATION"
       );
     }
+    await this.ensureSchema();
     return this.executor.transaction(async (tx) => {
-      const txBackend = new SqliteTransactionBackendImpl(
-        tx,
-        this.collectionPath,
-        this.storageScope
-      );
+      const txBackend = new SqliteTransactionBackendImpl(tx, this.collectionPath);
       return fn(txBackend);
     });
   }
   createBatch() {
-    return new SqliteBatchBackendImpl(this.executor, this.collectionPath, this.storageScope);
+    return new SqliteBatchBackendImpl(
+      this.executor,
+      this.collectionPath,
+      () => this.ensureSchema()
+    );
   }
   // --- Subgraphs ---
   subgraph(parentNodeUid, name) {
@@ -3260,10 +3480,19 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     }
     const newStorageScope = this.storageScope ? `${this.storageScope}/${parentNodeUid}/${name}` : `${parentNodeUid}/${name}`;
     const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
-    return new _SqliteBackendImpl(this.executor, this.collectionPath, newStorageScope, newScope);
+    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 })
@@ -3280,22 +3509,33 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     }
     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 countStmt = compileCountScopePrefix(this.collectionPath, prefix);
-      const countRows = await this.executor.all(countStmt.sql, countStmt.params);
-      const first = countRows[0];
-      const n = first?.n;
-      subgraphRowCount = typeof n === "bigint" ? Number(n) : Number(n ?? 0);
+      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, this.storageScope, id)
+      (id) => compileDelete(this.collectionPath, id)
     );
-    writeStatements.push(compileDelete(this.collectionPath, this.storageScope, nodeDocId));
-    if (shouldDeleteSubgraphs) {
-      const prefix = this.storageScope ? `${this.storageScope}/${uid}` : uid;
-      writeStatements.push(compileDeleteScopePrefix(this.collectionPath, prefix));
+    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,
@@ -3305,20 +3545,19 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     const allOk = errors.length === 0;
     const edgesDeleted = allOk ? edgeDocIds.length : 0;
     const nodeDeleted = allOk;
-    const prefixStatementContribution = shouldDeleteSubgraphs && allOk ? 1 : 0;
-    const deleted = stmtDeleted - prefixStatementContribution + (allOk ? subgraphRowCount : 0);
+    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, this.storageScope, id)
-    );
+    const statements = docIds.map((id) => compileDelete(this.collectionPath, id));
     return this.executeChunkedBatches(statements, options);
   }
   /**
@@ -3334,9 +3573,9 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
    * `result.errors.length` after the call.
    *
    * Returns `BulkResult`-shaped fields. `deleted` reflects only the
-   * statement count of *successfully committed* batches — a prefix-delete
-   * statement contributes 1 to that total even though it may match many
-   * rows; `removeNodeCascade` patches that up with a pre-counted row total.
+   * 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.
@@ -3398,29 +3637,12 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     }
     return { deleted, batches, errors };
   }
-  // --- Cross-scope (collection group) ---
-  async findEdgesGlobal(params, collectionName) {
-    const plan = buildEdgeQueryPlan(params);
-    if (plan.strategy === "get") {
-      throw new FiregraphError(
-        "findEdgesGlobal() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
-        "INVALID_QUERY"
-      );
-    }
-    const name = collectionName ?? this.collectionPath;
-    const scopeNameFilter = {
-      name,
-      isRoot: name === this.collectionPath
-    };
-    const stmt = compileSelectGlobal(
-      this.collectionPath,
-      plan.filters,
-      plan.options,
-      scopeNameFilter
-    );
-    const rows = await this.executor.all(stmt.sql, stmt.params);
-    return rows.map(rowToRecord);
-  }
+  // `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
@@ -3432,13 +3654,8 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
    * convention and the Firestore Standard helper.
    */
   async aggregate(spec, filters) {
-    const { stmt, aliases } = compileAggregate(
-      this.collectionPath,
-      this.storageScope,
-      spec,
-      filters
-    );
-    const rows = await this.executor.all(stmt.sql, stmt.params);
+    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) {
@@ -3472,12 +3689,12 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
    * congestion); a permanent failure is surfaced via the `errors` array
    * with `batchIndex: 0` so callers see the same shape as `bulkRemoveEdges`.
    *
-   * Subgraph scoping is enforced inside `compileBulkDelete` (the leading
-   * `"scope" = ?` predicate) so this method, like every other backend
-   * surface, naturally honours subgraph isolation.
+   * Subgraph isolation is physical — the statement only ever touches this
+   * graph's table, so no scoping predicate is needed.
    */
   async bulkDelete(filters, options) {
-    const stmt = compileBulkDelete(this.collectionPath, this.storageScope, filters);
+    await this.ensureSchema();
+    const stmt = compileBulkDelete(this.collectionPath, filters);
     return this.executeDmlWithReturning(stmt, options);
   }
   /**
@@ -3491,13 +3708,8 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
    * transient driver errors.
    */
   async bulkUpdate(filters, patch, options) {
-    const stmt = compileBulkUpdate(
-      this.collectionPath,
-      this.storageScope,
-      filters,
-      patch.data,
-      Date.now()
-    );
+    await this.ensureSchema();
+    const stmt = compileBulkUpdate(this.collectionPath, filters, patch.data, Date.now());
     return this.executeDmlWithReturning(stmt, options);
   }
   /**
@@ -3522,8 +3734,8 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     if (params.sources.length === 0) {
       return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
     }
-    const stmt = compileExpand(this.collectionPath, this.storageScope, params);
-    const rows = await this.executor.all(stmt.sql, stmt.params);
+    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 };
@@ -3534,7 +3746,7 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
     if (uniqueTargets.length === 0) {
       return { edges, targets: [] };
     }
-    const hydrateStmt = compileExpandHydrate(this.collectionPath, this.storageScope, uniqueTargets);
+    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) {
@@ -3563,12 +3775,11 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
   async findEdgesProjected(select, filters, options) {
     const { stmt, columns } = compileFindEdgesProjected(
       this.collectionPath,
-      this.storageScope,
       select,
       filters,
       options
     );
-    const rows = await this.executor.all(stmt.sql, stmt.params);
+    const rows = await this.withSchema(() => this.executor.all(stmt.sql, stmt.params));
     return rows.map((row) => decodeProjectedRow(row, columns));
   }
   /**
@@ -3616,7 +3827,15 @@ var SqliteBackendImpl = class _SqliteBackendImpl {
 function createSqliteBackend(executor, tableName, options = {}) {
   const storageScope = options.storageScope ?? "";
   const scopePath = options.scopePath ?? "";
-  return new SqliteBackendImpl(executor, tableName, storageScope, scopePath);
+  return new SqliteBackendImpl(
+    executor,
+    tableName,
+    storageScope,
+    scopePath,
+    options.registry,
+    options.coreIndexes,
+    options.extraTableDDL
+  );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {