@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/index.cjs

@@ -30,6 +30,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/internal/serialization-tag.ts
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+var SERIALIZATION_TAG, KNOWN_TYPES;
+var init_serialization_tag = __esm({
+  "src/internal/serialization-tag.ts"() {
+    "use strict";
+    SERIALIZATION_TAG = "__firegraph_ser__";
+    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+  }
+});
+
 // src/serialization.ts
 var serialization_exports = {};
 __export(serialization_exports, {
@@ -38,11 +53,6 @@ __export(serialization_exports, {
   isTaggedValue: () => isTaggedValue,
   serializeFirestoreTypes: () => serializeFirestoreTypes
 });
-function isTaggedValue(value) {
-  if (value === null || typeof value !== "object") return false;
-  const tag = value[SERIALIZATION_TAG];
-  return typeof tag === "string" && KNOWN_TYPES.has(tag);
-}
 function isTimestamp(value) {
   return value instanceof import_firestore.Timestamp;
 }
@@ -143,13 +153,13 @@ function deserializeValue(value, db) {
   }
   return result;
 }
-var import_firestore, SERIALIZATION_TAG, KNOWN_TYPES, _docRefWarned;
+var import_firestore, _docRefWarned;
 var init_serialization = __esm({
   "src/serialization.ts"() {
     "use strict";
     import_firestore = require("@google-cloud/firestore");
-    SERIALIZATION_TAG = "__firegraph_ser__";
-    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+    init_serialization_tag();
+    init_serialization_tag();
     _docRefWarned = false;
   }
 });
@@ -158,6 +168,7 @@ var init_serialization = __esm({
 var index_exports = {};
 __export(index_exports, {
   BOOTSTRAP_ENTRIES: () => BOOTSTRAP_ENTRIES,
+  CapabilityNotSupportedError: () => CapabilityNotSupportedError,
   CrossBackendTransactionError: () => CrossBackendTransactionError,
   DEFAULT_CORE_INDEXES: () => DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT: () => DEFAULT_QUERY_LIMIT,
@@ -184,9 +195,7 @@ __export(index_exports, {
   appendStorageScope: () => appendStorageScope,
   applyMigrationChain: () => applyMigrationChain,
   buildEdgeQueryPlan: () => buildEdgeQueryPlan,
-  buildEdgeRecord: () => buildEdgeRecord,
   buildNodeQueryPlan: () => buildNodeQueryPlan,
-  buildNodeRecord: () => buildNodeRecord,
   compileMigrationFn: () => compileMigrationFn,
   compileMigrations: () => compileMigrations,
   compileSchema: () => compileSchema,
@@ -202,6 +211,7 @@ __export(index_exports, {
   defaultExecutor: () => defaultExecutor,
   defineConfig: () => defineConfig,
   defineViews: () => defineViews,
+  deleteField: () => deleteField,
   deserializeFirestoreTypes: () => deserializeFirestoreTypes,
   destroySandboxWorker: () => destroySandboxWorker,
   discoverEntities: () => discoverEntities,
@@ -255,6 +265,139 @@ function computeEdgeDocId(aUid, axbType, bUid) {
   return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
 }
 
+// src/internal/write-plan.ts
+init_serialization_tag();
+var DELETE_FIELD = /* @__PURE__ */ Symbol.for("firegraph.deleteField");
+function deleteField() {
+  return DELETE_FIELD;
+}
+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;
+}
+var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function assertNoDeleteSentinels(data, callerLabel) {
+  walkForDeleteSentinels(data, [], { kind: "root" }, ({ path }) => {
+    const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+    throw new Error(
+      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. deleteField() is only valid inside updateNode/updateEdge \u2014 full-data writes (put*, replace*) cannot delete individual fields. Use updateNode with a deleteField() value, or omit the field from the replace payload.`
+    );
+  });
+}
+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 (!SAFE_KEY_RE.test(seg)) {
+      throw new Error(
+        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Keys used inside update payloads must match /^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in SQLite JSON paths.`
+      );
+    }
+  }
+}
+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/batch.ts
 function buildWritableNodeRecord(aType, uid, data) {
   return { aType, aUid: uid, axbType: NODE_RELATION, bType: aType, bUid: uid, data };
@@ -269,6 +412,19 @@ var GraphBatchImpl = class {
     this.scopePath = scopePath;
   }
   async putNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -280,9 +436,10 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -294,11 +451,15 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    this.backend.updateDoc(docId, { dataFields: data });
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -394,6 +555,16 @@ var CrossBackendTransactionError = class extends FiregraphError {
     this.name = "CrossBackendTransactionError";
   }
 };
+var CapabilityNotSupportedError = class extends FiregraphError {
+  constructor(capability, backendDescription) {
+    super(
+      `Capability "${capability}" is not supported by ${backendDescription}.`,
+      "CAPABILITY_NOT_SUPPORTED"
+    );
+    this.capability = capability;
+    this.name = "CapabilityNotSupportedError";
+  }
+};
 
 // src/json-schema.ts
 var import_json_schema = require("@cfworker/json-schema");
@@ -1409,6 +1580,19 @@ var GraphTransactionImpl = class {
     return results.map((r) => r.record);
   }
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -1420,9 +1604,10 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -1434,11 +1619,15 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1476,6 +1665,15 @@ var GraphClientImpl = class _GraphClientImpl {
     this.scanProtection = options?.scanProtection ?? "error";
   }
   scanProtection;
+  /**
+   * Capability set of the underlying backend. Mirrors `backend.capabilities`
+   * verbatim so callers can portability-check (`client.capabilities.has(
+   * 'query.join')`) without reaching for the backend handle. Static for the
+   * lifetime of the client.
+   */
+  get capabilities() {
+    return this.backend.capabilities;
+  }
   // Static mode
   staticRegistry;
   // Dynamic mode
@@ -1637,6 +1835,19 @@ var GraphClientImpl = class _GraphClientImpl {
   // GraphWriter
   // ---------------------------------------------------------------------------
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, NODE_RELATION, aType, data, this.backend.scopePath);
@@ -1650,9 +1861,10 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, axbType, bType, data, this.backend.scopePath);
@@ -1666,11 +1878,15 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1752,6 +1968,33 @@ var GraphClientImpl = class _GraphClientImpl {
     return this.applyMigrations(records);
   }
   // ---------------------------------------------------------------------------
+  // Aggregate query (capability: query.aggregate)
+  // ---------------------------------------------------------------------------
+  async aggregate(params) {
+    if (!this.backend.aggregate) {
+      throw new FiregraphError(
+        "aggregate() is not supported by the current storage backend.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const hasAnyFilter = params.aType || params.aUid || params.axbType || params.bType || params.bUid || params.where && params.where.length > 0;
+    if (!hasAnyFilter) {
+      this.checkQuerySafety([], params.allowCollectionScan);
+      const result2 = await this.backend.aggregate(params.aggregates, []);
+      return result2;
+    }
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "aggregate() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    const result = await this.backend.aggregate(params.aggregates, plan.filters);
+    return result;
+  }
+  // ---------------------------------------------------------------------------
   // Bulk operations
   // ---------------------------------------------------------------------------
   async removeNodeCascade(uid, options) {
@@ -1761,6 +2004,327 @@ var GraphClientImpl = class _GraphClientImpl {
     return this.backend.bulkRemoveEdges(params, this, options);
   }
   // ---------------------------------------------------------------------------
+  // Server-side DML (capability: query.dml)
+  // ---------------------------------------------------------------------------
+  /**
+   * Single-statement bulk DELETE. Translates `params` to a filter list via
+   * `buildEdgeQueryPlan` (the same plan `findEdges` uses) and dispatches to
+   * `backend.bulkDelete`. The fetch-then-delete loop in `bulkRemoveEdges`
+   * is the cap-less fallback; this method is the fast path on backends
+   * declaring `query.dml`.
+   *
+   * Scan-protection rules match `findEdges`: a query with no identifying
+   * fields requires `allowCollectionScan: true` to pass. A bare-empty
+   * filter set (no `aType`, `aUid`, etc., no `where`) is allowed at this
+   * layer — shared SQLite bounds the blast radius via its leading `scope`
+   * predicate — but the DO RPC backend rejects empty filters at the wire
+   * boundary as defense-in-depth. To wipe a routed subgraph DO, use
+   * `removeNodeCascade` on the parent node instead.
+   */
+  async bulkDelete(params, options) {
+    if (!this.backend.bulkDelete) {
+      throw new FiregraphError(
+        "bulkDelete() is not supported by the current storage backend. Fall back to bulkRemoveEdges() for backends without query.dml (e.g. Firestore Standard).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = this.buildDmlFilters(params);
+    return this.backend.bulkDelete(filters, options);
+  }
+  /**
+   * Single-statement bulk UPDATE. Same translation path as `bulkDelete`,
+   * but the patch is deep-merged into each matching row's `data` via the
+   * shared `flattenPatch` pipeline. Identifying columns are immutable
+   * through this path (see `BulkUpdatePatch` JSDoc).
+   *
+   * Empty-patch rejection happens inside the backend (`compileBulkUpdate`)
+   * — a `data: {}` payload would only rewrite `updated_at`, which is
+   * almost certainly a bug.
+   */
+  async bulkUpdate(params, patch, options) {
+    if (!this.backend.bulkUpdate) {
+      throw new FiregraphError(
+        "bulkUpdate() is not supported by the current storage backend.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = this.buildDmlFilters(params);
+    return this.backend.bulkUpdate(filters, patch, options);
+  }
+  // ---------------------------------------------------------------------------
+  // Multi-source fan-out (capability: query.join)
+  // ---------------------------------------------------------------------------
+  /**
+   * Fan out from `params.sources` over a single edge type in one round trip.
+   * On backends without `query.join`, throws `UNSUPPORTED_OPERATION` — the
+   * cap-less fallback is the per-source `findEdges` loop, which lives in
+   * `traverse.ts` (the higher-level traversal walker) rather than here.
+   *
+   * `expand()` is intentionally edge-type-only — the source set is a flat
+   * UID list and the hop matches one `axbType`. Multi-axbType expansions
+   * become multiple `expand()` calls, one per relation.
+   *
+   * `params.sources.length === 0` short-circuits to an empty result. The
+   * backend never sees the call. (`compileExpand` itself rejects empty
+   * because `IN ()` is not valid SQL.)
+   */
+  async expand(params) {
+    if (!this.backend.expand) {
+      throw new FiregraphError(
+        "expand() is not supported by the current storage backend. Backends without `query.join` can use createTraversal() instead \u2014 the per-hop loop is functionally equivalent (just slower).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    return this.backend.expand(params);
+  }
+  // ---------------------------------------------------------------------------
+  // Engine-level multi-hop traversal (capability: traversal.serverSide)
+  // ---------------------------------------------------------------------------
+  /**
+   * Compile a multi-hop traversal spec into one server-side nested
+   * Pipeline and dispatch a single round trip.
+   *
+   * Backends declaring `traversal.serverSide` (Firestore Enterprise
+   * today) install this method; everywhere else, it throws
+   * `UNSUPPORTED_OPERATION`. The capability gate matches the type-level
+   * surface — `GraphClient<C>` only exposes `runEngineTraversal` when
+   * `'traversal.serverSide' extends C`.
+   *
+   * Most callers should not invoke this method directly; the
+   * `createTraversal(...).run()` builder routes through it
+   * automatically when `engineTraversal: 'auto'` (the default) and
+   * the spec is eligible per `firestore-traverse-compiler.ts`. Calling
+   * directly is appropriate for benchmarking or for callers that have
+   * already shaped their hop chain into the strict
+   * `EngineTraversalParams` shape.
+   *
+   * `params.sources.length === 0` short-circuits to empty per-hop
+   * arrays. The backend never sees the call.
+   */
+  async runEngineTraversal(params) {
+    if (!this.backend.runEngineTraversal) {
+      throw new FiregraphError(
+        "runEngineTraversal() is not supported by the current storage backend. Backends without `traversal.serverSide` can use createTraversal() instead \u2014 the per-hop loop is functionally equivalent for in-graph specs (different round-trip profile).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.sources.length === 0) {
+      return {
+        hops: params.hops.map(() => ({ edges: [], sourceCount: 0 })),
+        totalReads: 0
+      };
+    }
+    return this.backend.runEngineTraversal(params);
+  }
+  // ---------------------------------------------------------------------------
+  // Server-side projection (capability: query.select)
+  // ---------------------------------------------------------------------------
+  /**
+   * Server-side projection — fetch only the requested fields from each
+   * matching edge. The backend translates the call into a projecting query
+   * (`SELECT json_extract(...)` on SQLite/DO, `Query.select(...)` on
+   * Firestore Standard, classic projection on Enterprise) so the wire
+   * payload is reduced to just the requested fields.
+   *
+   * Resolution rules for `select` (mirrored across all backends):
+   *
+   *   - Built-in envelope fields (`aType`, `aUid`, `axbType`, `bType`,
+   *     `bUid`, `createdAt`, `updatedAt`, `v`) → resolve to the typed
+   *     column / Firestore field directly.
+   *   - `'data'` literal → returns the whole user payload.
+   *   - `'data.<x>'` → explicit nested path, returned at the same shape.
+   *   - bare name → rewritten to `data.<name>` (the canonical "give me a
+   *     few keys out of the JSON payload" shape).
+   *
+   * Empty `select: []` is rejected with `INVALID_QUERY`. Duplicate entries
+   * are de-duped (first-occurrence order preserved); the result row carries
+   * one slot per unique field.
+   *
+   * Migrations are *not* applied to the result. The caller asked for a
+   * partial shape, and rehydrating it through the migration pipeline would
+   * require synthesising every absent field — see
+   * `StorageBackend.findEdgesProjected` for the rationale.
+   *
+   * Scan protection follows the `findEdges` rules: a query with no
+   * identifying fields requires `allowCollectionScan: true` to pass. The
+   * cap-less fallback would be `findEdges` + JS-side projection, but that
+   * defeats the wire-payload reduction; backends without `query.select`
+   * throw `UNSUPPORTED_OPERATION` rather than silently materialising full
+   * rows.
+   */
+  async findEdgesProjected(params) {
+    if (!this.backend.findEdgesProjected) {
+      throw new FiregraphError(
+        "findEdgesProjected() is not supported by the current storage backend. There is no client-side fallback because the wire-payload reduction is the entire point of the API \u2014 use findEdges() and project in JS if the backend does not declare `query.select`.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.select.length === 0) {
+      throw new FiregraphError(
+        "findEdgesProjected() requires a non-empty `select` list.",
+        "INVALID_QUERY"
+      );
+    }
+    const plan = buildEdgeQueryPlan(params);
+    let filters;
+    let options;
+    if (plan.strategy === "get") {
+      filters = [
+        { field: "aUid", op: "==", value: params.aUid },
+        { field: "axbType", op: "==", value: params.axbType },
+        { field: "bUid", op: "==", value: params.bUid }
+      ];
+      if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+      if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+      options = void 0;
+    } else {
+      filters = plan.filters;
+      options = plan.options;
+    }
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    const rows = await this.backend.findEdgesProjected(params.select, filters, options);
+    return rows;
+  }
+  /**
+   * Native vector / nearest-neighbour search (capability `search.vector`).
+   *
+   * Resolves to the top-K records by similarity, sorted nearest-first
+   * (`EUCLIDEAN` / `COSINE`) or highest-first (`DOT_PRODUCT`). The wrapper
+   * is intentionally thin: capability check, scan-protection, then forward
+   * `params` verbatim to the backend. All field-path normalisation and
+   * SDK-shape validation lives in the shared
+   * `runFirestoreFindNearest` helper that both Firestore editions call —
+   * keeping it there means the validation surface stays in lockstep with
+   * the SDK call site, regardless of which backend is plugged in.
+   *
+   * Migrations are NOT applied. The vector index walked the raw stored
+   * shape; rehydrating each row through the migration pipeline would
+   * change the candidate set the index already chose. If you need
+   * migrated shape, follow up with `getNode` / `findEdges` on the
+   * returned UIDs — those paths apply migrations normally.
+   *
+   * Scan-protection mirrors `findEdges`: if no identifying filters
+   * (`aType` / `axbType` / `bType`) and no `where` clauses are supplied,
+   * the request must opt in via `allowCollectionScan: true`. The ANN
+   * query still walks the candidate set the WHERE clause produces, so
+   * an unfiltered nearest-neighbour search over a million-row collection
+   * is the same scan trap as an unfiltered `findEdges`.
+   *
+   * Backends without `search.vector` throw `UNSUPPORTED_OPERATION` —
+   * there is no client-side fallback because emulating ANN over the
+   * generic backend surface (`findEdges` + JS-side cosine) doesn't scale
+   * past trivial datasets and would give callers the wrong mental model
+   * about cost.
+   */
+  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.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    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 });
+    if (params.where) filters.push(...params.where);
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.findNearest(params);
+  }
+  /**
+   * 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.
+   *
+   * Scan-protection mirrors `findNearest`: a search with no
+   * identifying filters (`aType` / `axbType` / `bType`) walks every
+   * row the index scored, so the request must opt in via
+   * `allowCollectionScan: true`.
+   *
+   * Migrations are NOT applied. The FTS index walked the raw stored
+   * shape; rehydrating each row through the migration pipeline would
+   * change the candidate set the index already scored. If you need
+   * migrated shape, follow up with `getNode` / `findEdges` on the
+   * returned UIDs.
+   */
+  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.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    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 });
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.fullTextSearch(params);
+  }
+  /**
+   * Native geospatial distance search (capability `search.geo`).
+   *
+   * Returns rows whose `geoField` lies within `radiusMeters` of
+   * `point`, ordered nearest-first by default. Only Firestore
+   * Enterprise declares this capability — same Enterprise-only
+   * gating as `fullTextSearch`. Backends without `search.geo` throw
+   * `UNSUPPORTED_OPERATION` from this wrapper.
+   *
+   * Scan-protection mirrors `findNearest` and `fullTextSearch`.
+   *
+   * Migrations are NOT applied — same rationale as the other search
+   * extensions.
+   */
+  async geoSearch(params) {
+    if (!this.backend.geoSearch) {
+      throw new FiregraphError(
+        "geoSearch() is not supported by the current storage backend. Geospatial search requires a backend that declares `search.geo` (currently Firestore Enterprise only \u2014 geo queries are an Enterprise product feature). There is no client-side fallback because emulating geo over the generic backend surface (haversine over `findEdges`) would not scale beyond trivial datasets.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    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 });
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.geoSearch(params);
+  }
+  /**
+   * Translate a `FindEdgesParams` into the `QueryFilter[]` shape the
+   * backend `bulkDelete` / `bulkUpdate` methods expect. Mirrors the
+   * `aggregate()` plan: a bare-empty params object becomes an empty
+   * filter list (after a scan-protection check); a GET-shape (all three
+   * identifiers) is rejected so we never silently turn a single-row
+   * lookup into a server-side DML; otherwise we run `buildEdgeQueryPlan`
+   * and surface its filters.
+   */
+  buildDmlFilters(params) {
+    const hasAnyFilter = params.aType || params.aUid || params.axbType || params.bType || params.bUid || params.where && params.where.length > 0;
+    if (!hasAnyFilter) {
+      this.checkQuerySafety([], params.allowCollectionScan);
+      return [];
+    }
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "bulkDelete() / bulkUpdate() require a query, not a direct document lookup. Use removeEdge() / updateEdge() for single-row operations, or omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    return plan.filters;
+  }
+  // ---------------------------------------------------------------------------
   // Dynamic registry methods
   // ---------------------------------------------------------------------------
   async defineNodeType(name, jsonSchema, description, options) {
@@ -1900,9 +2464,10 @@ var GraphClientImpl = class _GraphClientImpl {
     };
   }
 };
-function createGraphClientFromBackend(backend, options, metaBackend) {
+function createGraphClient(backend, options, metaBackend) {
   return new GraphClientImpl(backend, options, metaBackend);
 }
+var createGraphClientFromBackend = createGraphClient;
 
 // src/codegen/index.ts
 function pascalCase(s) {
@@ -2186,486 +2751,6 @@ function discoverEntities(entitiesDir) {
   };
 }
 
-// src/internal/firestore-backend.ts
-var import_firestore2 = require("@google-cloud/firestore");
-
-// src/bulk.ts
-var MAX_BATCH_SIZE = 500;
-var DEFAULT_MAX_RETRIES = 3;
-var BASE_DELAY_MS = 200;
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-function chunk(arr, size) {
-  const chunks = [];
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size));
-  }
-  return chunks;
-}
-async function bulkDeleteDocIds(db, collectionPath, docIds, options) {
-  if (docIds.length === 0) {
-    return { deleted: 0, batches: 0, errors: [] };
-  }
-  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
-  const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
-  const onProgress = options?.onProgress;
-  const chunks = chunk(docIds, batchSize);
-  const errors = [];
-  let deleted = 0;
-  let completedBatches = 0;
-  for (let i = 0; i < chunks.length; i++) {
-    const ids = chunks[i];
-    let committed = false;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const batch = db.batch();
-        const collectionRef = db.collection(collectionPath);
-        for (const id of ids) {
-          batch.delete(collectionRef.doc(id));
-        }
-        await batch.commit();
-        committed = true;
-        deleted += ids.length;
-        break;
-      } catch (err) {
-        if (attempt < maxRetries) {
-          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
-          await sleep(delay);
-        } else {
-          errors.push({
-            batchIndex: i,
-            error: err instanceof Error ? err : new Error(String(err)),
-            operationCount: ids.length
-          });
-        }
-      }
-    }
-    if (committed) {
-      completedBatches++;
-    }
-    if (onProgress) {
-      onProgress({
-        completedBatches,
-        totalBatches: chunks.length,
-        deletedSoFar: deleted
-      });
-    }
-  }
-  return { deleted, batches: completedBatches, errors };
-}
-async function bulkRemoveEdges(db, collectionPath, reader, params, options) {
-  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));
-  return bulkDeleteDocIds(db, collectionPath, docIds, options);
-}
-async function deleteSubcollectionsRecursive(db, collectionPath, docId, options) {
-  const docRef = db.collection(collectionPath).doc(docId);
-  const subcollections = await docRef.listCollections();
-  if (subcollections.length === 0) return { deleted: 0, errors: [] };
-  let totalDeleted = 0;
-  const allErrors = [];
-  const subOptions = options ? { batchSize: options.batchSize, maxRetries: options.maxRetries } : void 0;
-  for (const subCollRef of subcollections) {
-    const subCollPath = subCollRef.path;
-    const snapshot = await subCollRef.select().get();
-    const subDocIds = snapshot.docs.map((d) => d.id);
-    for (const subDocId of subDocIds) {
-      const subResult = await deleteSubcollectionsRecursive(db, subCollPath, subDocId, subOptions);
-      totalDeleted += subResult.deleted;
-      allErrors.push(...subResult.errors);
-    }
-    if (subDocIds.length > 0) {
-      const result = await bulkDeleteDocIds(db, subCollPath, subDocIds, subOptions);
-      totalDeleted += result.deleted;
-      allErrors.push(...result.errors);
-    }
-  }
-  return { deleted: totalDeleted, errors: allErrors };
-}
-async function removeNodeCascade(db, collectionPath, reader, uid, options) {
-  const [outgoingRaw, incomingRaw] = await Promise.all([
-    reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
-    reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
-  ]);
-  const outgoing = outgoingRaw.filter((e) => e.axbType !== NODE_RELATION);
-  const incoming = incomingRaw.filter((e) => e.axbType !== NODE_RELATION);
-  const edgeDocIdSet = /* @__PURE__ */ new Set();
-  const allEdges = [];
-  for (const edge of [...outgoing, ...incoming]) {
-    const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
-    if (!edgeDocIdSet.has(docId)) {
-      edgeDocIdSet.add(docId);
-      allEdges.push(edge);
-    }
-  }
-  const shouldDeleteSubcollections = options?.deleteSubcollections !== false;
-  const nodeDocId = computeNodeDocId(uid);
-  let subcollectionResult = { deleted: 0, errors: [] };
-  if (shouldDeleteSubcollections) {
-    subcollectionResult = await deleteSubcollectionsRecursive(
-      db,
-      collectionPath,
-      nodeDocId,
-      options
-    );
-  }
-  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
-  const allDocIds = [...edgeDocIds, nodeDocId];
-  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
-  const result = await bulkDeleteDocIds(db, collectionPath, allDocIds, {
-    ...options,
-    batchSize
-  });
-  const totalChunks = Math.ceil(allDocIds.length / batchSize);
-  const nodeChunkIndex = totalChunks - 1;
-  const nodeDeleted = !result.errors.some((e) => e.batchIndex === nodeChunkIndex);
-  const topLevelEdgesDeleted = nodeDeleted ? result.deleted - 1 : result.deleted;
-  return {
-    deleted: result.deleted + subcollectionResult.deleted,
-    batches: result.batches,
-    errors: [...result.errors, ...subcollectionResult.errors],
-    edgesDeleted: topLevelEdgesDeleted,
-    nodeDeleted
-  };
-}
-
-// src/internal/firestore-backend.ts
-init_serialization();
-
-// src/internal/firestore-adapter.ts
-function createFirestoreAdapter(db, collectionPath) {
-  const collectionRef = db.collection(collectionPath);
-  return {
-    collectionPath,
-    async getDoc(docId) {
-      const snap = await collectionRef.doc(docId).get();
-      if (!snap.exists) return null;
-      return snap.data();
-    },
-    async setDoc(docId, data) {
-      await collectionRef.doc(docId).set(data);
-    },
-    async updateDoc(docId, data) {
-      await collectionRef.doc(docId).update(data);
-    },
-    async deleteDoc(docId) {
-      await collectionRef.doc(docId).delete();
-    },
-    async query(filters, options) {
-      let q = collectionRef;
-      for (const f of filters) {
-        q = q.where(f.field, f.op, f.value);
-      }
-      if (options?.orderBy) {
-        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
-      }
-      if (options?.limit !== void 0) {
-        q = q.limit(options.limit);
-      }
-      const snap = await q.get();
-      return snap.docs.map((doc) => doc.data());
-    }
-  };
-}
-function createTransactionAdapter(db, collectionPath, tx) {
-  const collectionRef = db.collection(collectionPath);
-  return {
-    async getDoc(docId) {
-      const snap = await tx.get(collectionRef.doc(docId));
-      if (!snap.exists) return null;
-      return snap.data();
-    },
-    setDoc(docId, data) {
-      tx.set(collectionRef.doc(docId), data);
-    },
-    updateDoc(docId, data) {
-      tx.update(collectionRef.doc(docId), data);
-    },
-    deleteDoc(docId) {
-      tx.delete(collectionRef.doc(docId));
-    },
-    async query(filters, options) {
-      let q = collectionRef;
-      for (const f of filters) {
-        q = q.where(f.field, f.op, f.value);
-      }
-      if (options?.orderBy) {
-        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
-      }
-      if (options?.limit !== void 0) {
-        q = q.limit(options.limit);
-      }
-      const snap = await tx.get(q);
-      return snap.docs.map((doc) => doc.data());
-    }
-  };
-}
-function createBatchAdapter(db, collectionPath) {
-  const collectionRef = db.collection(collectionPath);
-  const batch = db.batch();
-  return {
-    setDoc(docId, data) {
-      batch.set(collectionRef.doc(docId), data);
-    },
-    updateDoc(docId, data) {
-      batch.update(collectionRef.doc(docId), data);
-    },
-    deleteDoc(docId) {
-      batch.delete(collectionRef.doc(docId));
-    },
-    async commit() {
-      await batch.commit();
-    }
-  };
-}
-
-// src/internal/pipeline-adapter.ts
-var _Pipelines = null;
-async function getPipelines() {
-  if (!_Pipelines) {
-    const mod = await import("@google-cloud/firestore");
-    _Pipelines = mod.Pipelines;
-  }
-  return _Pipelines;
-}
-function buildFilterExpression(P, filter) {
-  const { field: fieldName, op, value } = filter;
-  switch (op) {
-    case "==":
-      return P.equal(fieldName, value);
-    case "!=":
-      return P.notEqual(fieldName, value);
-    case "<":
-      return P.lessThan(fieldName, value);
-    case "<=":
-      return P.lessThanOrEqual(fieldName, value);
-    case ">":
-      return P.greaterThan(fieldName, value);
-    case ">=":
-      return P.greaterThanOrEqual(fieldName, value);
-    case "in":
-      return P.equalAny(fieldName, value);
-    case "not-in":
-      return P.notEqualAny(fieldName, value);
-    case "array-contains":
-      return P.arrayContains(fieldName, value);
-    case "array-contains-any":
-      return P.arrayContainsAny(fieldName, value);
-    default:
-      throw new Error(`Unsupported filter op for pipeline mode: ${op}`);
-  }
-}
-function createPipelineQueryAdapter(db, collectionPath) {
-  return {
-    async query(filters, options) {
-      const P = await getPipelines();
-      let pipeline = db.pipeline().collection(collectionPath);
-      if (filters.length === 1) {
-        pipeline = pipeline.where(buildFilterExpression(P, filters[0]));
-      } else if (filters.length > 1) {
-        const [first, second, ...rest] = filters.map((f) => buildFilterExpression(P, f));
-        pipeline = pipeline.where(P.and(first, second, ...rest));
-      }
-      if (options?.orderBy) {
-        const f = P.field(options.orderBy.field);
-        const ordering = options.orderBy.direction === "desc" ? f.descending() : f.ascending();
-        pipeline = pipeline.sort(ordering);
-      }
-      if (options?.limit !== void 0) {
-        pipeline = pipeline.limit(options.limit);
-      }
-      const snap = await pipeline.execute();
-      return snap.results.map((r) => r.data());
-    }
-  };
-}
-
-// src/internal/firestore-backend.ts
-function buildFirestoreUpdate(update, db) {
-  const out = {
-    updatedAt: import_firestore2.FieldValue.serverTimestamp()
-  };
-  if (update.replaceData) {
-    out.data = deserializeFirestoreTypes(update.replaceData, db);
-  }
-  if (update.dataFields) {
-    for (const [k, v] of Object.entries(update.dataFields)) {
-      out[`data.${k}`] = v;
-    }
-  }
-  if (update.v !== void 0) {
-    out.v = update.v;
-  }
-  return out;
-}
-function stampWritableRecord(record) {
-  const now = import_firestore2.FieldValue.serverTimestamp();
-  const out = {
-    aType: record.aType,
-    aUid: record.aUid,
-    axbType: record.axbType,
-    bType: record.bType,
-    bUid: record.bUid,
-    data: record.data,
-    createdAt: now,
-    updatedAt: now
-  };
-  if (record.v !== void 0) out.v = record.v;
-  return out;
-}
-var FirestoreTransactionBackend = class {
-  constructor(adapter, db) {
-    this.adapter = adapter;
-    this.db = db;
-  }
-  getDoc(docId) {
-    return this.adapter.getDoc(docId);
-  }
-  query(filters, options) {
-    return this.adapter.query(filters, options);
-  }
-  async setDoc(docId, record) {
-    this.adapter.setDoc(docId, stampWritableRecord(record));
-  }
-  async updateDoc(docId, update) {
-    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
-  }
-  async deleteDoc(docId) {
-    this.adapter.deleteDoc(docId);
-  }
-};
-var FirestoreBatchBackend = class {
-  constructor(adapter, db) {
-    this.adapter = adapter;
-    this.db = db;
-  }
-  setDoc(docId, record) {
-    this.adapter.setDoc(docId, stampWritableRecord(record));
-  }
-  updateDoc(docId, update) {
-    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
-  }
-  deleteDoc(docId) {
-    this.adapter.deleteDoc(docId);
-  }
-  commit() {
-    return this.adapter.commit();
-  }
-};
-var FirestoreBackendImpl = class _FirestoreBackendImpl {
-  constructor(db, collectionPath, queryMode, scopePath) {
-    this.db = db;
-    this.queryMode = queryMode;
-    this.collectionPath = collectionPath;
-    this.scopePath = scopePath;
-    this.adapter = createFirestoreAdapter(db, collectionPath);
-    if (queryMode === "pipeline") {
-      this.pipelineAdapter = createPipelineQueryAdapter(db, collectionPath);
-    }
-  }
-  collectionPath;
-  scopePath;
-  adapter;
-  pipelineAdapter;
-  // --- Reads ---
-  getDoc(docId) {
-    return this.adapter.getDoc(docId);
-  }
-  query(filters, options) {
-    if (this.pipelineAdapter) {
-      return this.pipelineAdapter.query(filters, options);
-    }
-    return this.adapter.query(filters, options);
-  }
-  // --- Writes ---
-  setDoc(docId, record) {
-    return this.adapter.setDoc(docId, stampWritableRecord(record));
-  }
-  updateDoc(docId, update) {
-    return this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
-  }
-  deleteDoc(docId) {
-    return this.adapter.deleteDoc(docId);
-  }
-  // --- Transactions / Batches ---
-  runTransaction(fn) {
-    return this.db.runTransaction(async (firestoreTx) => {
-      const txAdapter = createTransactionAdapter(this.db, this.collectionPath, firestoreTx);
-      return fn(new FirestoreTransactionBackend(txAdapter, this.db));
-    });
-  }
-  createBatch() {
-    const batchAdapter = createBatchAdapter(this.db, this.collectionPath);
-    return new FirestoreBatchBackend(batchAdapter, this.db);
-  }
-  // --- Subgraphs ---
-  subgraph(parentNodeUid, name) {
-    const subPath = `${this.collectionPath}/${parentNodeUid}/${name}`;
-    const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
-    return new _FirestoreBackendImpl(this.db, subPath, this.queryMode, newScope);
-  }
-  // --- Cascade & bulk ---
-  removeNodeCascade(uid, reader, options) {
-    return removeNodeCascade(this.db, this.collectionPath, reader, uid, options);
-  }
-  bulkRemoveEdges(params, reader, options) {
-    return bulkRemoveEdges(this.db, this.collectionPath, reader, params, options);
-  }
-  // --- Cross-collection ---
-  async findEdgesGlobal(params, collectionName) {
-    const name = collectionName ?? this.collectionPath.split("/").pop();
-    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 collectionGroupRef = this.db.collectionGroup(name);
-    let q = collectionGroupRef;
-    for (const f of plan.filters) {
-      q = q.where(f.field, f.op, f.value);
-    }
-    if (plan.options?.orderBy) {
-      q = q.orderBy(plan.options.orderBy.field, plan.options.orderBy.direction ?? "asc");
-    }
-    if (plan.options?.limit !== void 0) {
-      q = q.limit(plan.options.limit);
-    }
-    const snap = await q.get();
-    return snap.docs.map((doc) => doc.data());
-  }
-};
-function createFirestoreBackend(db, collectionPath, options = {}) {
-  const queryMode = options.queryMode ?? "pipeline";
-  const scopePath = options.scopePath ?? "";
-  return new FirestoreBackendImpl(db, collectionPath, queryMode, scopePath);
-}
-
-// src/firestore.ts
-var _standardModeWarned = false;
-function createGraphClient(db, collectionPath, options) {
-  const requestedMode = options?.queryMode ?? "pipeline";
-  const isEmulator = !!process.env.FIRESTORE_EMULATOR_HOST;
-  const effectiveMode = isEmulator ? "standard" : requestedMode;
-  if (effectiveMode === "standard" && !isEmulator && requestedMode === "standard" && !_standardModeWarned) {
-    _standardModeWarned = true;
-    console.warn(
-      "[firegraph] Standard query mode enabled. This is NOT recommended for production:\n  - Enterprise Firestore: data.* filters cause full collection scans (high billing)\n  - Standard Firestore: data.* filters without composite indexes will fail\n  See: https://github.com/typicalday/firegraph#query-modes"
-    );
-  }
-  const backend = createFirestoreBackend(db, collectionPath, { queryMode: effectiveMode });
-  let metaBackend;
-  if (options?.registryMode?.collection && options.registryMode.collection !== collectionPath) {
-    metaBackend = createFirestoreBackend(db, options.registryMode.collection, {
-      queryMode: effectiveMode
-    });
-  }
-  return new GraphClientImpl(backend, options, metaBackend);
-}
-
 // src/id.ts
 var import_nanoid = require("nanoid");
 function generateId() {
@@ -3024,35 +3109,6 @@ var QueryClient = class {
   }
 };
 
-// src/record.ts
-var import_firestore3 = require("@google-cloud/firestore");
-function buildNodeRecord(aType, uid, data) {
-  const now = import_firestore3.FieldValue.serverTimestamp();
-  return {
-    aType,
-    aUid: uid,
-    axbType: NODE_RELATION,
-    bType: aType,
-    bUid: uid,
-    data,
-    createdAt: now,
-    updatedAt: now
-  };
-}
-function buildEdgeRecord(aType, aUid, axbType, bType, bUid, data) {
-  const now = import_firestore3.FieldValue.serverTimestamp();
-  return {
-    aType,
-    aUid,
-    axbType,
-    bType,
-    bUid,
-    data,
-    createdAt: now,
-    updatedAt: now
-  };
-}
-
 // src/scope-path.ts
 function parseStorageScope(scope) {
   if (scope === "") return [];
@@ -3106,6 +3162,69 @@ function appendStorageScope(parentScope, uid, name) {
 // src/index.ts
 init_serialization();
 
+// src/internal/firestore-traverse-compiler.ts
+var MAX_PIPELINE_DEPTH = 5;
+function compileEngineTraversal(params, opts) {
+  const maxDepth = opts?.maxDepth ?? MAX_PIPELINE_DEPTH;
+  const maxReads = opts?.maxReads ?? params.maxReads;
+  if (!Array.isArray(params.hops) || params.hops.length === 0) {
+    return { eligible: false, reason: "engine traversal requires at least one hop" };
+  }
+  if (params.hops.length > maxDepth) {
+    return {
+      eligible: false,
+      reason: `engine traversal depth ${params.hops.length} exceeds MAX_PIPELINE_DEPTH (${maxDepth})`
+    };
+  }
+  if (!Array.isArray(params.sources)) {
+    return { eligible: false, reason: "engine traversal requires a sources array" };
+  }
+  const normalizedHops = [];
+  for (let i = 0; i < params.hops.length; i++) {
+    const hop = params.hops[i];
+    if (!hop.axbType || hop.axbType.length === 0) {
+      return {
+        eligible: false,
+        reason: `engine traversal hop ${i} is missing axbType`
+      };
+    }
+    if (typeof hop.limitPerSource !== "number" || hop.limitPerSource <= 0 || !Number.isFinite(hop.limitPerSource)) {
+      return {
+        eligible: false,
+        reason: `engine traversal hop ${i} (${hop.axbType}) requires a positive limitPerSource`
+      };
+    }
+    normalizedHops.push({
+      ...hop,
+      axbType: hop.axbType,
+      direction: hop.direction ?? "forward",
+      limitPerSource: hop.limitPerSource
+    });
+  }
+  let estimatedReads = Math.max(1, params.sources.length);
+  for (const hop of normalizedHops) {
+    estimatedReads *= hop.limitPerSource;
+    if (estimatedReads > Number.MAX_SAFE_INTEGER) {
+      estimatedReads = Number.MAX_SAFE_INTEGER;
+      break;
+    }
+  }
+  if (maxReads !== void 0 && estimatedReads > maxReads) {
+    return {
+      eligible: false,
+      reason: `engine traversal worst-case response size ${estimatedReads} exceeds maxReads budget ${maxReads}`
+    };
+  }
+  return {
+    eligible: true,
+    normalized: {
+      sources: params.sources,
+      hops: normalizedHops,
+      estimatedReads
+    }
+  };
+}
+
 // src/traverse.ts
 var DEFAULT_LIMIT = 10;
 var DEFAULT_MAX_READS = 100;
@@ -3114,6 +3233,16 @@ var _crossGraphWarned = false;
 function isGraphClient(reader) {
   return "subgraph" in reader && typeof reader.subgraph === "function";
 }
+function readerSupportsExpand(reader) {
+  if (!isGraphClient(reader)) return false;
+  const client = reader;
+  return "capabilities" in client && typeof client.capabilities?.has === "function" && client.capabilities.has("query.join") && typeof client.expand === "function";
+}
+function readerSupportsEngineTraversal(reader) {
+  if (!isGraphClient(reader)) return false;
+  const client = reader;
+  return "capabilities" in client && typeof client.capabilities?.has === "function" && client.capabilities.has("traversal.serverSide") && typeof client.runEngineTraversal === "function";
+}
 var Semaphore = class {
   constructor(slots) {
     this.slots = slots;
@@ -3156,7 +3285,15 @@ var TraversalBuilderImpl = class {
     const maxReads = options?.maxReads ?? DEFAULT_MAX_READS;
     const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
     const returnIntermediates = options?.returnIntermediates ?? false;
+    const engineMode = options?.engineTraversal ?? "auto";
     const semaphore = new Semaphore(concurrency);
+    if (engineMode !== "off") {
+      const engineResult = await this.tryEngineTraversal({
+        engineMode,
+        returnIntermediates
+      });
+      if (engineResult) return engineResult;
+    }
     let totalReads = 0;
     let truncated = false;
     let sources = [
@@ -3181,6 +3318,62 @@ var TraversalBuilderImpl = class {
       const resolvedTargetGraph = this.resolveTargetGraph(hop);
       const direction = hop.direction ?? "forward";
       const isCrossGraph = direction === "forward" && !!resolvedTargetGraph;
+      const sharedReader = sources.every((s) => s.reader === sources[0].reader) ? sources[0].reader : null;
+      const canFastPath = !isCrossGraph && sharedReader && readerSupportsExpand(sharedReader);
+      if (canFastPath && sharedReader) {
+        if (totalReads >= maxReads) {
+          hopTruncated = true;
+        } else {
+          totalReads++;
+          const limit = hop.limit ?? DEFAULT_LIMIT;
+          const expandParams = {
+            sources: sources.map((s) => s.uid),
+            axbType: hop.axbType,
+            direction
+          };
+          if (hop.aType) expandParams.aType = hop.aType;
+          if (hop.bType) expandParams.bType = hop.bType;
+          if (hop.orderBy) expandParams.orderBy = hop.orderBy;
+          if (!hop.filter) {
+            expandParams.limitPerSource = limit;
+          }
+          const result = await sharedReader.expand(expandParams);
+          let edges2 = result.edges;
+          if (hop.filter) {
+            edges2 = edges2.filter(hop.filter);
+            const counts = /* @__PURE__ */ new Map();
+            const kept = [];
+            for (const e of edges2) {
+              const sourceUid = direction === "forward" ? e.aUid : e.bUid;
+              const c = counts.get(sourceUid) ?? 0;
+              if (c < limit) {
+                counts.set(sourceUid, c + 1);
+                kept.push(e);
+              }
+            }
+            edges2 = kept;
+          }
+          for (const edge of edges2) {
+            hopEdges.push({ edge, reader: sharedReader });
+          }
+        }
+        const fastEdges = hopEdges.map((h) => h.edge);
+        hopResults.push({
+          axbType: hop.axbType,
+          depth,
+          edges: returnIntermediates ? [...fastEdges] : fastEdges,
+          sourceCount,
+          truncated: hopTruncated
+        });
+        if (hopTruncated) truncated = true;
+        const seen2 = /* @__PURE__ */ new Map();
+        for (const { edge, reader: edgeReader } of hopEdges) {
+          const nextUid = direction === "forward" ? edge.bUid : edge.aUid;
+          if (!seen2.has(nextUid)) seen2.set(nextUid, edgeReader);
+        }
+        sources = [...seen2.entries()].map(([uid, reader]) => ({ uid, reader }));
+        continue;
+      }
       const tasks = sources.map(({ uid, reader: sourceReader }) => async () => {
         if (totalReads >= maxReads) {
           hopTruncated = true;
@@ -3275,6 +3468,88 @@ var TraversalBuilderImpl = class {
       truncated
     };
   }
+  /**
+   * Try to dispatch the entire hop chain as one engine-traversal call.
+   * Returns a `TraversalResult` on success, or `undefined` if the spec is
+   * ineligible and the caller should fall through to the per-hop loop.
+   *
+   * `'force'` mode throws on any ineligibility instead of returning
+   * `undefined` — the caller intentionally opted out of fallback.
+   */
+  async tryEngineTraversal(args) {
+    const { engineMode, returnIntermediates } = args;
+    const refuse = (reason) => {
+      if (engineMode === "force") {
+        throw new FiregraphError(`engineTraversal: 'force' but ${reason}`, "UNSUPPORTED_OPERATION");
+      }
+      return void 0;
+    };
+    if (!readerSupportsEngineTraversal(this.reader)) {
+      return refuse("reader does not declare traversal.serverSide capability");
+    }
+    const client = this.reader;
+    const engineHops = [];
+    for (let i = 0; i < this.hops.length; i++) {
+      const hop = this.hops[i];
+      if (hop.filter) {
+        return refuse(`hop ${i} (${hop.axbType}) carries a JS filter callback`);
+      }
+      const targetGraph = this.resolveTargetGraph(hop);
+      const direction = hop.direction ?? "forward";
+      if (targetGraph) {
+        return refuse(`hop ${i} (${hop.axbType}) is cross-graph (targetGraph=${targetGraph})`);
+      }
+      const limit = hop.limit ?? DEFAULT_LIMIT;
+      const engineHop = {
+        axbType: hop.axbType,
+        direction,
+        limitPerSource: limit
+      };
+      if (hop.aType) engineHop.aType = hop.aType;
+      if (hop.bType) engineHop.bType = hop.bType;
+      if (hop.orderBy) engineHop.orderBy = hop.orderBy;
+      engineHops.push(engineHop);
+    }
+    const params = {
+      sources: [this.startUid],
+      hops: engineHops
+    };
+    const compiled = compileEngineTraversal(params);
+    if (!compiled.eligible) {
+      return refuse(compiled.reason);
+    }
+    let engineResult;
+    try {
+      engineResult = await client.runEngineTraversal(params);
+    } catch (err) {
+      if (engineMode === "force") throw err;
+      return void 0;
+    }
+    const hopResults = [];
+    for (let i = 0; i < this.hops.length; i++) {
+      const definedHop = this.hops[i];
+      const engineHopResult = engineResult.hops[i] ?? { edges: [], sourceCount: 0 };
+      const edges = engineHopResult.edges;
+      const hopTruncated = edges.length >= engineHops[i].limitPerSource;
+      hopResults.push({
+        axbType: definedHop.axbType,
+        depth: i,
+        edges: returnIntermediates ? [...edges] : edges,
+        sourceCount: engineHopResult.sourceCount,
+        truncated: hopTruncated
+      });
+    }
+    const lastHop = hopResults[hopResults.length - 1];
+    return {
+      nodes: lastHop.edges,
+      hops: hopResults,
+      // One server-side round trip — same accounting as the `expand()`
+      // fast path. The tree response can carry up to `estimatedReads`
+      // docs total, but the budget is in round trips, not docs.
+      totalReads: 1,
+      truncated: hopResults.some((h) => h.truncated)
+    };
+  }
   /**
    * Resolve the targetGraph for a hop. Priority:
    * 1. Explicit `hop.targetGraph` (user override)
@@ -3397,6 +3672,7 @@ function defineViews(input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BOOTSTRAP_ENTRIES,
+  CapabilityNotSupportedError,
   CrossBackendTransactionError,
   DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT,
@@ -3423,9 +3699,7 @@ function defineViews(input) {
   appendStorageScope,
   applyMigrationChain,
   buildEdgeQueryPlan,
-  buildEdgeRecord,
   buildNodeQueryPlan,
-  buildNodeRecord,
   compileMigrationFn,
   compileMigrations,
   compileSchema,
@@ -3441,6 +3715,7 @@ function defineViews(input) {
   defaultExecutor,
   defineConfig,
   defineViews,
+  deleteField,
   deserializeFirestoreTypes,
   destroySandboxWorker,
   discoverEntities,