@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/index.js

@@ -1,18 +1,32 @@
+import {
+  QueryClient,
+  QueryClientError
+} from "./chunk-EEKWRX5E.js";
 import {
   appendStorageScope,
   isAncestorScopeUid,
   parseStorageScope,
   resolveAncestorScope
 } from "./chunk-TYYPRVIE.js";
+import {
+  DEFAULT_CORE_INDEXES
+} from "./chunk-2DHMNTV6.js";
+import {
+  generateTypes
+} from "./chunk-GJVVRTQT.js";
+import {
+  compileEngineTraversal
+} from "./chunk-D4J7Z4FE.js";
+import {
+  deserializeFirestoreTypes,
+  serializeFirestoreTypes
+} from "./chunk-C2QMD7RY.js";
 import {
   BOOTSTRAP_ENTRIES,
-  DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT,
   EDGE_TYPE_SCHEMA,
-  GraphClientImpl,
   META_EDGE_TYPE,
   META_NODE_TYPE,
-  NODE_RELATION,
   NODE_TYPE_SCHEMA,
   analyzeQuerySafety,
   applyMigrationChain,
@@ -24,6 +38,7 @@ import {
   computeEdgeDocId,
   computeNodeDocId,
   createBootstrapRegistry,
+  createGraphClient,
   createGraphClientFromBackend,
   createMergedRegistry,
   createRegistry,
@@ -39,8 +54,9 @@ import {
   migrateRecords,
   precompileSource,
   validateMigrationChain
-} from "./chunk-HONQY4HF.js";
+} from "./chunk-WRTFC5NG.js";
 import {
+  CapabilityNotSupportedError,
   CrossBackendTransactionError,
   DynamicRegistryError,
   EdgeNotFoundError,
@@ -53,21 +69,8 @@ import {
   RegistryViolationError,
   TraversalError,
   ValidationError,
-  assertSafePath,
-  assertUpdatePayloadExclusive,
   deleteField
-} from "./chunk-AWW4MUJ5.js";
-import {
-  generateTypes
-} from "./chunk-GJVVRTQT.js";
-import {
-  QueryClient,
-  QueryClientError
-} from "./chunk-EEKWRX5E.js";
-import {
-  deserializeFirestoreTypes,
-  serializeFirestoreTypes
-} from "./chunk-C2QMD7RY.js";
+} from "./chunk-TK64DNVK.js";
 import {
   SERIALIZATION_TAG,
   isTaggedValue
@@ -308,512 +311,6 @@ function discoverEntities(entitiesDir) {
   };
 }
 
-// src/internal/firestore-backend.ts
-import { FieldValue } from "@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-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: 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 ? FieldValue.delete() : op.value;
-    }
-  }
-  if (update.v !== void 0) {
-    out.v = update.v;
-  }
-  return out;
-}
-function stampWritableRecord(record) {
-  const now = 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/indexes.ts
 function normalizeField(f) {
   return typeof f === "string" ? { path: f, desc: false } : { path: f.path, desc: !!f.desc };
@@ -888,35 +385,6 @@ function generateIndexConfig(collection, options = {}) {
   return { indexes, fieldOverrides: [] };
 }
 
-// src/record.ts
-import { FieldValue as FieldValue2 } from "@google-cloud/firestore";
-function buildNodeRecord(aType, uid, data) {
-  const now = FieldValue2.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 = FieldValue2.serverTimestamp();
-  return {
-    aType,
-    aUid,
-    axbType,
-    bType,
-    bUid,
-    data,
-    createdAt: now,
-    updatedAt: now
-  };
-}
-
 // src/traverse.ts
 var DEFAULT_LIMIT = 10;
 var DEFAULT_MAX_READS = 100;
@@ -925,6 +393,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;
@@ -967,7 +445,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 = [
@@ -992,6 +478,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;
@@ -1086,6 +628,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)
@@ -1207,6 +831,7 @@ function defineViews(input) {
 }
 export {
   BOOTSTRAP_ENTRIES,
+  CapabilityNotSupportedError,
   CrossBackendTransactionError,
   DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT,
@@ -1233,9 +858,7 @@ export {
   appendStorageScope,
   applyMigrationChain,
   buildEdgeQueryPlan,
-  buildEdgeRecord,
   buildNodeQueryPlan,
-  buildNodeRecord,
   compileMigrationFn,
   compileMigrations,
   compileSchema,