@typicalday/firegraph 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-wSlVH5Nv.cjs';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-wSlVH5Nv.cjs';
+import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.cjs';
+export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.cjs';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.cjs';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.cjs';
 
@@ -71,7 +71,18 @@ declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, b
 declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
 declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
 
-declare function createTraversal(reader: GraphReader, startUid: string): TraversalBuilder;
+/**
+ * Create a traversal builder for multi-hop graph traversal.
+ *
+ * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
+ * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
+ * is supported — the traversal can follow edges into subgraphs.
+ *
+ * @param reader - A `GraphClient` or `GraphReader` to execute queries against
+ * @param startUid - UID of the starting node
+ * @param registry - Optional registry for automatic `targetGraph` resolution
+ */
+declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
 declare class FiregraphError extends Error {
     readonly code: string;
@@ -187,6 +198,52 @@ declare function matchScope(scopePath: string, pattern: string): boolean;
  */
 declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
 
+/**
+ * Cross-graph edge resolution utilities.
+ *
+ * Provides path-scanning resolution for determining whether an edge's source
+ * (aUid) is an ancestor node by checking if the UID appears in the Firestore
+ * collection path.
+ *
+ * Firestore paths have a rigid alternating structure:
+ *   collection / docId / collection / docId / collection
+ *
+ * Given a path like `graph/A/workspace/B/context`, segments at even indices
+ * are collection names and odd indices are document IDs. When we find a UID
+ * at an odd index, the collection containing that document is the path up to
+ * (and including) the preceding even-index segment.
+ */
+/**
+ * Parse a Firestore collection path and determine the collection path
+ * where a given UID's document lives, if that UID is an ancestor in the path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to search for in the path
+ * @returns The collection path containing the UID, or `null` if not found in the path
+ *
+ * @example
+ * ```ts
+ * // Path: graph/A/workspace/B/context
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
+ * // → 'graph'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
+ * // → 'graph/A/workspace'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
+ * // → null
+ * ```
+ */
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+/**
+ * Check whether a UID belongs to an ancestor node by scanning the collection path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to check
+ * @returns `true` if the UID appears as a document segment in the path
+ */
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -226,7 +283,7 @@ interface FirestoreIndexField {
 }
 interface FirestoreIndex {
     collectionGroup: string;
-    queryScope: 'COLLECTION';
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
     fields: FirestoreIndexField[];
 }
 interface FirestoreIndexConfig {
@@ -241,10 +298,17 @@ interface FirestoreIndexConfig {
  * patterns on node data fields:
  *   (aType, axbType, data.{field})
  *
+ * When registry entries with `targetGraph` are provided, also generates
+ * collection group indexes for `findEdgesGlobal()` queries. The collection
+ * group name defaults to `'graph'` (the standard subgraph name) but can be
+ * overridden per `targetGraph` value.
+ *
  * @param collection - Firestore collection name (e.g. 'graph')
  * @param entities - Optional discovery result for per-entity data field indexes
+ * @param registryEntries - Optional registry entries; when any have `targetGraph`,
+ *   collection group indexes are generated for the distinct subgraph names
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
 
 /**
  * Result of analyzing a query for collection scan risk.
@@ -272,4 +336,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, jsonSchemaToFieldMeta, matchScope, matchScopeAny };
+export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-wSlVH5Nv.js';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-wSlVH5Nv.js';
+import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.js';
+export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.js';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.js';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.js';
 
@@ -71,7 +71,18 @@ declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, b
 declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
 declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
 
-declare function createTraversal(reader: GraphReader, startUid: string): TraversalBuilder;
+/**
+ * Create a traversal builder for multi-hop graph traversal.
+ *
+ * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
+ * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
+ * is supported — the traversal can follow edges into subgraphs.
+ *
+ * @param reader - A `GraphClient` or `GraphReader` to execute queries against
+ * @param startUid - UID of the starting node
+ * @param registry - Optional registry for automatic `targetGraph` resolution
+ */
+declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
 declare class FiregraphError extends Error {
     readonly code: string;
@@ -187,6 +198,52 @@ declare function matchScope(scopePath: string, pattern: string): boolean;
  */
 declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
 
+/**
+ * Cross-graph edge resolution utilities.
+ *
+ * Provides path-scanning resolution for determining whether an edge's source
+ * (aUid) is an ancestor node by checking if the UID appears in the Firestore
+ * collection path.
+ *
+ * Firestore paths have a rigid alternating structure:
+ *   collection / docId / collection / docId / collection
+ *
+ * Given a path like `graph/A/workspace/B/context`, segments at even indices
+ * are collection names and odd indices are document IDs. When we find a UID
+ * at an odd index, the collection containing that document is the path up to
+ * (and including) the preceding even-index segment.
+ */
+/**
+ * Parse a Firestore collection path and determine the collection path
+ * where a given UID's document lives, if that UID is an ancestor in the path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to search for in the path
+ * @returns The collection path containing the UID, or `null` if not found in the path
+ *
+ * @example
+ * ```ts
+ * // Path: graph/A/workspace/B/context
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
+ * // → 'graph'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
+ * // → 'graph/A/workspace'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
+ * // → null
+ * ```
+ */
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+/**
+ * Check whether a UID belongs to an ancestor node by scanning the collection path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to check
+ * @returns `true` if the UID appears as a document segment in the path
+ */
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -226,7 +283,7 @@ interface FirestoreIndexField {
 }
 interface FirestoreIndex {
     collectionGroup: string;
-    queryScope: 'COLLECTION';
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
     fields: FirestoreIndexField[];
 }
 interface FirestoreIndexConfig {
@@ -241,10 +298,17 @@ interface FirestoreIndexConfig {
  * patterns on node data fields:
  *   (aType, axbType, data.{field})
  *
+ * When registry entries with `targetGraph` are provided, also generates
+ * collection group indexes for `findEdgesGlobal()` queries. The collection
+ * group name defaults to `'graph'` (the standard subgraph name) but can be
+ * overridden per `targetGraph` value.
+ *
  * @param collection - Firestore collection name (e.g. 'graph')
  * @param entities - Optional discovery result for per-entity data field indexes
+ * @param registryEntries - Optional registry entries; when any have `targetGraph`,
+ *   collection group indexes are generated for the distinct subgraph names
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
 
 /**
  * Result of analyzing a query for collection scan risk.
@@ -272,4 +336,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, jsonSchemaToFieldMeta, matchScope, matchScopeAny };
+export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };

package/dist/index.js

@@ -783,14 +783,35 @@ function createRegistry(input) {
   }
   const entryList = Object.freeze([...entries]);
   for (const entry of entries) {
+    if (entry.targetGraph && entry.targetGraph.includes("/")) {
+      throw new ValidationError(
+        `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType}) has invalid targetGraph "${entry.targetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
     const key = tripleKey(entry.aType, entry.axbType, entry.bType);
     const validator = entry.jsonSchema ? compileSchema(entry.jsonSchema, `(${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`) : void 0;
     map.set(key, { entry, validate: validator });
   }
+  const axbIndex = /* @__PURE__ */ new Map();
+  const axbBuild = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = axbBuild.get(entry.axbType);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      axbBuild.set(entry.axbType, [entry]);
+    }
+  }
+  for (const [key, arr] of axbBuild) {
+    axbIndex.set(key, Object.freeze(arr));
+  }
   return {
     lookup(aType, axbType, bType) {
       return map.get(tripleKey(aType, axbType, bType))?.entry;
     },
+    lookupByAxbType(axbType) {
+      return axbIndex.get(axbType) ?? [];
+    },
     validate(aType, axbType, bType, data, scopePath) {
       const rec = map.get(tripleKey(aType, axbType, bType));
       if (!rec) {
@@ -837,6 +858,12 @@ function discoveryToEntries(discovery) {
     if (!topology) continue;
     const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
     const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+    const resolvedTargetGraph = entity.targetGraph ?? topology.targetGraph;
+    if (resolvedTargetGraph && resolvedTargetGraph.includes("/")) {
+      throw new ValidationError(
+        `Edge "${axbType}" has invalid targetGraph "${resolvedTargetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
     for (const aType of fromTypes) {
       for (const bType of toTypes) {
         entries.push({
@@ -848,7 +875,8 @@ function discoveryToEntries(discovery) {
           inverseLabel: topology.inverseLabel,
           titleField: entity.titleField,
           subtitleField: entity.subtitleField,
-          allowedIn: entity.allowedIn
+          allowedIn: entity.allowedIn,
+          targetGraph: resolvedTargetGraph
         });
       }
     }
@@ -898,7 +926,8 @@ var EDGE_TYPE_SCHEMA = {
     subtitleField: { type: "string" },
     viewTemplate: { type: "string" },
     viewCss: { type: "string" },
-    allowedIn: { type: "array", items: { type: "string", minLength: 1 } }
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
+    targetGraph: { type: "string", minLength: 1, pattern: "^[^/]+$" }
   },
   additionalProperties: false
 };
@@ -959,7 +988,8 @@ async function createRegistryFromGraph(reader) {
           inverseLabel: data.inverseLabel,
           titleField: data.titleField,
           subtitleField: data.subtitleField,
-          allowedIn: data.allowedIn
+          allowedIn: data.allowedIn,
+          targetGraph: data.targetGraph
         });
       }
     }
@@ -1213,6 +1243,33 @@ var GraphClientImpl = class _GraphClientImpl {
     );
   }
   // ---------------------------------------------------------------------------
+  // Collection group query
+  // ---------------------------------------------------------------------------
+  async findEdgesGlobal(params, collectionName) {
+    const name = collectionName ?? this.adapter.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"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    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());
+  }
+  // ---------------------------------------------------------------------------
   // Bulk operations
   // ---------------------------------------------------------------------------
   async removeNodeCascade(uid, options) {
@@ -1264,6 +1321,7 @@ var GraphClientImpl = class _GraphClientImpl {
     };
     if (jsonSchema !== void 0) data.jsonSchema = jsonSchema;
     if (topology.inverseLabel !== void 0) data.inverseLabel = topology.inverseLabel;
+    if (topology.targetGraph !== void 0) data.targetGraph = topology.targetGraph;
     if (description !== void 0) data.description = description;
     if (options?.titleField !== void 0) data.titleField = options.titleField;
     if (options?.subtitleField !== void 0) data.subtitleField = options.subtitleField;
@@ -1338,6 +1396,10 @@ function generateId() {
 var DEFAULT_LIMIT = 10;
 var DEFAULT_MAX_READS = 100;
 var DEFAULT_CONCURRENCY = 5;
+var _crossGraphWarned = false;
+function isGraphClient(reader) {
+  return "subgraph" in reader && typeof reader.subgraph === "function";
+}
 var Semaphore = class {
   constructor(slots) {
     this.slots = slots;
@@ -1363,9 +1425,10 @@ var Semaphore = class {
   }
 };
 var TraversalBuilderImpl = class {
-  constructor(reader, startUid) {
+  constructor(reader, startUid, registry) {
     this.reader = reader;
     this.startUid = startUid;
+    this.registry = registry;
   }
   hops = [];
   follow(axbType, options) {
@@ -1382,11 +1445,13 @@ var TraversalBuilderImpl = class {
     const semaphore = new Semaphore(concurrency);
     let totalReads = 0;
     let truncated = false;
-    let sourceUids = [this.startUid];
+    let sources = [
+      { uid: this.startUid, reader: this.reader }
+    ];
     const hopResults = [];
     for (let depth = 0; depth < this.hops.length; depth++) {
       const hop = this.hops[depth];
-      if (sourceUids.length === 0) {
+      if (sources.length === 0) {
         hopResults.push({
           axbType: hop.axbType,
           depth,
@@ -1397,9 +1462,12 @@ var TraversalBuilderImpl = class {
         continue;
       }
       const hopEdges = [];
-      const sourceCount = sourceUids.length;
+      const sourceCount = sources.length;
       let hopTruncated = false;
-      const tasks = sourceUids.map((uid) => async () => {
+      const resolvedTargetGraph = this.resolveTargetGraph(hop);
+      const direction = hop.direction ?? "forward";
+      const isCrossGraph = direction === "forward" && !!resolvedTargetGraph;
+      const tasks = sources.map(({ uid, reader: sourceReader }) => async () => {
         if (totalReads >= maxReads) {
           hopTruncated = true;
           return;
@@ -1411,19 +1479,18 @@ var TraversalBuilderImpl = class {
             return;
           }
           totalReads++;
-          const direction2 = hop.direction ?? "forward";
           const params = { axbType: hop.axbType };
-          if (direction2 === "forward") {
+          if (direction === "forward") {
             params.aUid = uid;
             if (hop.bType) params.bType = hop.bType;
           } else {
             params.bUid = uid;
             if (hop.aType) params.aType = hop.aType;
           }
-          if (direction2 === "forward" && hop.aType) {
+          if (direction === "forward" && hop.aType) {
             params.aType = hop.aType;
           }
-          if (direction2 === "reverse" && hop.bType) {
+          if (direction === "reverse" && hop.bType) {
             params.bType = hop.bType;
           }
           if (hop.orderBy) params.orderBy = hop.orderBy;
@@ -1433,31 +1500,58 @@ var TraversalBuilderImpl = class {
           } else {
             params.limit = limit;
           }
-          let edges = await this.reader.findEdges(params);
+          let hopReader;
+          let nextReader;
+          if (isCrossGraph) {
+            if (isGraphClient(this.reader)) {
+              hopReader = this.reader.subgraph(uid, resolvedTargetGraph);
+              nextReader = hopReader;
+            } else {
+              hopReader = sourceReader;
+              nextReader = sourceReader;
+              if (!_crossGraphWarned) {
+                _crossGraphWarned = true;
+                console.warn(
+                  `[firegraph] Traversal hop "${hop.axbType}" has targetGraph "${resolvedTargetGraph}" but the reader does not support subgraph(). Cross-graph hop will query the current collection instead. Pass a GraphClient to createTraversal() to enable cross-graph traversal.`
+                );
+              }
+            }
+          } else {
+            hopReader = sourceReader;
+            nextReader = sourceReader;
+          }
+          let edges2 = await hopReader.findEdges(params);
           if (hop.filter) {
-            edges = edges.filter(hop.filter);
-            edges = edges.slice(0, limit);
+            edges2 = edges2.filter(hop.filter);
+            edges2 = edges2.slice(0, limit);
+          }
+          for (const edge of edges2) {
+            hopEdges.push({ edge, reader: nextReader });
           }
-          hopEdges.push(...edges);
         } finally {
           semaphore.release();
         }
       });
       await Promise.all(tasks.map((task) => task()));
+      const edges = hopEdges.map((h) => h.edge);
       hopResults.push({
         axbType: hop.axbType,
         depth,
-        edges: returnIntermediates ? [...hopEdges] : hopEdges,
+        edges: returnIntermediates ? [...edges] : edges,
         sourceCount,
         truncated: hopTruncated
       });
       if (hopTruncated) {
         truncated = true;
       }
-      const direction = hop.direction ?? "forward";
-      sourceUids = [...new Set(
-        hopEdges.map((e) => direction === "forward" ? e.bUid : e.aUid)
-      )];
+      const seen = /* @__PURE__ */ new Map();
+      for (const { edge, reader: edgeReader } of hopEdges) {
+        const nextUid = direction === "forward" ? edge.bUid : edge.aUid;
+        if (!seen.has(nextUid)) {
+          seen.set(nextUid, edgeReader);
+        }
+      }
+      sources = [...seen.entries()].map(([uid, reader]) => ({ uid, reader }));
     }
     const lastHop = hopResults[hopResults.length - 1];
     return {
@@ -1467,9 +1561,25 @@ var TraversalBuilderImpl = class {
       truncated
     };
   }
+  /**
+   * Resolve the targetGraph for a hop. Priority:
+   * 1. Explicit `hop.targetGraph` (user override)
+   * 2. Registry `targetGraph` for the axbType (if registry available)
+   * 3. undefined (no cross-graph)
+   */
+  resolveTargetGraph(hop) {
+    if (hop.targetGraph) return hop.targetGraph;
+    if (this.registry) {
+      const entries = this.registry.lookupByAxbType(hop.axbType);
+      for (const entry of entries) {
+        if (entry.targetGraph) return entry.targetGraph;
+      }
+    }
+    return void 0;
+  }
 };
-function createTraversal(reader, startUid) {
-  return new TraversalBuilderImpl(reader, startUid);
+function createTraversal(reader, startUid, registry) {
+  return new TraversalBuilderImpl(reader, startUid, registry);
 }
 
 // src/views.ts
@@ -1717,7 +1827,8 @@ function loadEdgeEntity(dir, name) {
     viewDefaults: meta?.viewDefaults,
     viewsPath,
     sampleData,
-    allowedIn: meta?.allowedIn
+    allowedIn: meta?.allowedIn,
+    targetGraph: topology.targetGraph ?? meta?.targetGraph
   };
 }
 function getSubdirectories(dir) {
@@ -1760,6 +1871,20 @@ function discoverEntities(entitiesDir) {
   };
 }
 
+// src/cross-graph.ts
+function resolveAncestorCollection(collectionPath, uid) {
+  const segments = collectionPath.split("/");
+  for (let i = 1; i < segments.length; i += 2) {
+    if (segments[i] === uid) {
+      return segments.slice(0, i).join("/");
+    }
+  }
+  return null;
+}
+function isAncestorUid(collectionPath, uid) {
+  return resolveAncestorCollection(collectionPath, uid) !== null;
+}
+
 // src/indexes.ts
 function baseIndexes(collection) {
   return [
@@ -1802,7 +1927,43 @@ function extractSchemaFields(schema) {
   if (s.type !== "object" || !s.properties) return [];
   return Object.keys(s.properties);
 }
-function generateIndexConfig(collection, entities) {
+function collectionGroupIndexes(collectionName) {
+  return [
+    {
+      collectionGroup: collectionName,
+      queryScope: "COLLECTION_GROUP",
+      fields: [
+        { fieldPath: "aUid", order: "ASCENDING" },
+        { fieldPath: "axbType", order: "ASCENDING" }
+      ]
+    },
+    {
+      collectionGroup: collectionName,
+      queryScope: "COLLECTION_GROUP",
+      fields: [
+        { fieldPath: "axbType", order: "ASCENDING" },
+        { fieldPath: "bUid", order: "ASCENDING" }
+      ]
+    },
+    {
+      collectionGroup: collectionName,
+      queryScope: "COLLECTION_GROUP",
+      fields: [
+        { fieldPath: "aType", order: "ASCENDING" },
+        { fieldPath: "axbType", order: "ASCENDING" }
+      ]
+    },
+    {
+      collectionGroup: collectionName,
+      queryScope: "COLLECTION_GROUP",
+      fields: [
+        { fieldPath: "axbType", order: "ASCENDING" },
+        { fieldPath: "bType", order: "ASCENDING" }
+      ]
+    }
+  ];
+}
+function generateIndexConfig(collection, entities, registryEntries) {
   const indexes = baseIndexes(collection);
   if (entities) {
     for (const [, entity] of entities.nodes) {
@@ -1834,6 +1995,17 @@ function generateIndexConfig(collection, entities) {
       }
     }
   }
+  if (registryEntries) {
+    const targetGraphNames = /* @__PURE__ */ new Set();
+    for (const entry of registryEntries) {
+      if (entry.targetGraph) {
+        targetGraphNames.add(entry.targetGraph);
+      }
+    }
+    for (const name of targetGraphNames) {
+      indexes.push(...collectionGroupIndexes(name));
+    }
+  }
   return { indexes, fieldOverrides: [] };
 }
 export {
@@ -1876,9 +2048,11 @@ export {
   generateId,
   generateIndexConfig,
   generateTypes,
+  isAncestorUid,
   jsonSchemaToFieldMeta,
   matchScope,
   matchScopeAny,
+  resolveAncestorCollection,
   resolveView
 };
 //# sourceMappingURL=index.js.map