@typicalday/firegraph 0.14.0 → 0.15.0

package/dist/chunk-FODIMIWY.js

@@ -0,0 +1,721 @@
+import {
+  buildSchemaStatements,
+  compileAggregate,
+  compileBulkDelete,
+  compileBulkUpdate,
+  compileDelete,
+  compileExpand,
+  compileExpandHydrate,
+  compileFindEdgesProjected,
+  compileSelect,
+  compileSelectByDocId,
+  compileSet,
+  compileUpdate,
+  decodeProjectedRow,
+  quoteIdent,
+  rowToRecord,
+  validateTableName
+} from "./chunk-ULRDQ6HZ.js";
+import {
+  createCapabilities
+} from "./chunk-N5HFDWQX.js";
+import {
+  NODE_RELATION,
+  computeEdgeDocId,
+  computeNodeDocId
+} from "./chunk-NGAJCALM.js";
+import {
+  FiregraphError
+} from "./chunk-SIHE4UY4.js";
+
+// 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 = quoteIdent(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 = quoteIdent(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 = quoteIdent(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 = quoteIdent(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) {
+    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;
+    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;
+  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;
+  }
+  async doEnsureSchema() {
+    const ddl = [
+      ...buildSchemaStatements(this.collectionPath, {
+        coreIndexes: this.coreIndexes,
+        registry: this.registry
+      }),
+      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
+    );
+  }
+  // --- 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 ${quoteIdent(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 ${quoteIdent(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
+  );
+}
+
+export {
+  createSqliteBackend
+};
+//# sourceMappingURL=chunk-FODIMIWY.js.map