@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/index.cjs

@@ -168,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,
@@ -194,9 +195,7 @@ __export(index_exports, {
   appendStorageScope: () => appendStorageScope,
   applyMigrationChain: () => applyMigrationChain,
   buildEdgeQueryPlan: () => buildEdgeQueryPlan,
-  buildEdgeRecord: () => buildEdgeRecord,
   buildNodeQueryPlan: () => buildNodeQueryPlan,
-  buildNodeRecord: () => buildNodeRecord,
   compileMigrationFn: () => compileMigrationFn,
   compileMigrations: () => compileMigrations,
   compileSchema: () => compileSchema,
@@ -300,13 +299,6 @@ function isTerminalValue(value) {
   return true;
 }
 var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-function assertUpdatePayloadExclusive(update) {
-  if (update.replaceData !== void 0 && update.dataOps !== void 0) {
-    throw new Error(
-      "firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. Use one or the other \u2014 `replaceData` is the migration-write-back form, `dataOps` is the standard partial-update form."
-    );
-  }
-}
 function assertNoDeleteSentinels(data, callerLabel) {
   walkForDeleteSentinels(data, [], { kind: "root" }, ({ path }) => {
     const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
@@ -563,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");
@@ -1663,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
@@ -1957,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) {
@@ -1966,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) {
@@ -2105,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) {
@@ -2391,515 +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, options) {
-      if (options?.merge) {
-        await collectionRef.doc(docId).set(data, { merge: true });
-      } else {
-        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, options) {
-      if (options?.merge) {
-        tx.set(collectionRef.doc(docId), data, { merge: true });
-      } else {
-        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, options) {
-      if (options?.merge) {
-        batch.set(collectionRef.doc(docId), data, { merge: true });
-      } else {
-        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 dottedDataPath(op) {
-  assertSafePath(op.path);
-  return `data.${op.path.join(".")}`;
-}
-function buildFirestoreUpdate(update, db) {
-  assertUpdatePayloadExclusive(update);
-  const out = {
-    updatedAt: import_firestore2.FieldValue.serverTimestamp()
-  };
-  if (update.replaceData) {
-    out.data = deserializeFirestoreTypes(update.replaceData, db);
-  } else if (update.dataOps) {
-    for (const op of update.dataOps) {
-      const key = dottedDataPath(op);
-      out[key] = op.delete ? import_firestore2.FieldValue.delete() : op.value;
-    }
-  }
-  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, mode) {
-    this.adapter.setDoc(
-      docId,
-      stampWritableRecord(record),
-      mode === "merge" ? { merge: true } : void 0
-    );
-  }
-  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, mode) {
-    this.adapter.setDoc(
-      docId,
-      stampWritableRecord(record),
-      mode === "merge" ? { merge: true } : void 0
-    );
-  }
-  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, mode) {
-    return this.adapter.setDoc(
-      docId,
-      stampWritableRecord(record),
-      mode === "merge" ? { merge: true } : void 0
-    );
-  }
-  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() {
@@ -3258,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 [];
@@ -3340,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;
@@ -3348,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;
@@ -3390,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 = [
@@ -3415,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;
@@ -3509,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)
@@ -3631,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,
@@ -3657,9 +3699,7 @@ function defineViews(input) {
   appendStorageScope,
   applyMigrationChain,
   buildEdgeQueryPlan,
-  buildEdgeRecord,
   buildNodeQueryPlan,
-  buildNodeRecord,
   compileMigrationFn,
   compileMigrations,
   compileSchema,