@typicalday/firegraph 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 > **Warning:** This library is experimental. APIs may change without notice between releases.
 
-A typed graph data layer for Firebase Cloud Firestore. Store nodes and edges in a single collection with smart query planning, sharded document IDs, optional schema validation, and multi-hop traversal.
+A typed graph data layer for Firebase Cloud Firestore. Store nodes and edges as triples in a Firestore collection with smart query planning, sharded document IDs, optional schema validation, multi-hop traversal, and nested subgraphs.
 
 ## Install
 
@@ -57,7 +57,7 @@ const departures = await g.findEdges({ aUid: tourId, axbType: 'hasDeparture' });
 
 ### Graph Model
 
-Firegraph stores everything as **triples** in a single Firestore collection:
+Firegraph stores everything as **triples** in a Firestore collection (with optional nested subcollections for [subgraphs](#subgraphs)):
 
 ```
 (aType, aUid) -[axbType]-> (bType, bUid)
@@ -193,7 +193,7 @@ await batch.commit();
 
 ### Graph Traversal
 
-Multi-hop traversal with budget enforcement, concurrency control, and in-memory filtering:
+Multi-hop traversal with budget enforcement, concurrency control, in-memory filtering, and cross-graph hops:
 
 ```typescript
 import { createTraversal } from 'firegraph';
@@ -213,6 +213,8 @@ result.totalReads; // number — Firestore reads consumed
 result.truncated;  // boolean — true if budget was hit
 ```
 
+`createTraversal` accepts a `GraphClient` or `GraphReader`. When passed a `GraphClient`, cross-graph hops via `targetGraph` are supported (see [Cross-Graph Edges](#cross-graph-edges)).
+
 #### Reverse Traversal
 
 Walk edges backwards to find parents:
@@ -249,6 +251,7 @@ await g.runTransaction(async (tx) => {
 | `limit` | `number` | `10` | Max edges per source node |
 | `orderBy` | `{ field, direction? }` | — | Firestore-level ordering |
 | `filter` | `(edge) => boolean` | — | In-memory post-filter |
+| `targetGraph` | `string` | — | Subgraph to cross into (forward only). See [Cross-Graph Edges](#cross-graph-edges) |
 
 #### Run Options
 
@@ -341,6 +344,241 @@ Key behaviors:
 
 Dynamic registry returns a `DynamicGraphClient` which extends `GraphClient` with `defineNodeType()`, `defineEdgeType()`, and `reloadRegistry()`. Transactions and batches also validate against the compiled dynamic registry.
 
+### Subgraphs
+
+Create isolated graph namespaces inside a parent node's Firestore document as subcollections. Each subgraph is a full `GraphClient` scoped to its own collection path.
+
+```typescript
+const agentId = generateId();
+await g.putNode('agent', agentId, { name: 'ResearchBot' });
+
+// Create a subgraph under the agent's document
+const memories = g.subgraph(agentId, 'memories');
+
+// CRUD works exactly like the parent client
+const memId = generateId();
+await memories.putNode('memory', memId, { text: 'The sky is blue' });
+const mem = await memories.getNode(memId);
+
+// Subgraph data is isolated — parent can't see it
+const parentNodes = await g.findNodes({ aType: 'memory', allowCollectionScan: true });
+// → [] (empty — memories live in the subcollection)
+```
+
+#### Nested Subgraphs
+
+Subgraphs can be nested to any depth:
+
+```typescript
+const workspace = g.subgraph(agentId, 'workspace');
+const taskId = generateId();
+await workspace.putNode('task', taskId, { name: 'Analyze data' });
+
+// Nest further
+const subtasks = workspace.subgraph(taskId, 'subtasks');
+await subtasks.putNode('subtask', generateId(), { name: 'Parse CSV' });
+```
+
+#### Scope Constraints (`allowedIn`)
+
+Registry entries support `allowedIn` patterns that restrict where a type can be used:
+
+```typescript
+const registry = createRegistry([
+  { aType: 'agent', axbType: 'is', bType: 'agent', allowedIn: ['root'] },
+  { aType: 'memory', axbType: 'is', bType: 'memory', allowedIn: ['**/memories'] },
+  { aType: 'task', axbType: 'is', bType: 'task', allowedIn: ['workspace', '**/workspace'] },
+]);
+
+const g = createGraphClient(db, 'graph', { registry });
+
+// Agent only at root
+await g.putNode('agent', agentId, {}); // OK
+await memories.putNode('agent', generateId(), {}); // throws RegistryScopeError
+
+// Memory only in 'memories' subgraphs
+await memories.putNode('memory', generateId(), {}); // OK
+await g.putNode('memory', generateId(), {}); // throws RegistryScopeError
+```
+
+**Pattern syntax:**
+
+| Pattern | Matches |
+|---------|---------|
+| `root` | Top-level collection only |
+| `memories` | Exact subgraph name |
+| `workspace/tasks` | Exact path |
+| `*/memories` | `*` matches one segment |
+| `**/memories` | `**` matches zero or more segments |
+| `**` | Everything including root |
+
+Omitting `allowedIn` (or passing an empty array) means the type is allowed everywhere.
+
+#### Transactions & Batches in Subgraphs
+
+```typescript
+const sub = g.subgraph(agentId, 'memories');
+
+// Transaction
+await sub.runTransaction(async (tx) => {
+  const node = await tx.getNode(memId);
+  await tx.putNode('memory', memId, { text: 'updated' });
+});
+
+// Batch
+const batch = sub.batch();
+await batch.putNode('memory', generateId(), { text: 'first' });
+await batch.putNode('memory', generateId(), { text: 'second' });
+await batch.commit();
+```
+
+#### Cascade Delete
+
+`removeNodeCascade` recursively deletes subcollections by default:
+
+```typescript
+// Deletes the agent node, all its edges, and all subgraph data
+await g.removeNodeCascade(agentId);
+
+// To preserve subgraph data:
+await g.removeNodeCascade(agentId, { deleteSubcollections: false });
+```
+
+#### Firestore Path Layout
+
+```
+graph/                          ← root collection
+  {agentId}                     ← agent node document
+  {agentId}/memories/           ← subgraph subcollection
+    {memId}                     ← memory node document
+    {shard:aUid:rel:bUid}       ← edge document
+  {agentId}/workspace/          ← another subgraph
+    {taskId}                    ← task node document
+    {taskId}/subtasks/          ← nested subgraph
+      {subtaskId}               ← subtask node document
+```
+
+### Cross-Graph Edges
+
+Edges that connect nodes across different subgraphs. The key rule: **edges live with the target node**. A cross-graph edge is stored in the same collection as its target (bUid), while the source (aUid) may be a parent node in an ancestor graph.
+
+```typescript
+import { createGraphClient, createRegistry, createTraversal, generateId } from 'firegraph';
+
+// Registry declares that 'assignedTo' edges live in the 'workflow' subgraph
+const registry = createRegistry([
+  { aType: 'task', axbType: 'is', bType: 'task', jsonSchema: taskSchema },
+  { aType: 'agent', axbType: 'is', bType: 'agent', jsonSchema: agentSchema },
+  { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' },
+]);
+
+const g = createGraphClient(db, 'graph', { registry });
+
+// Create a task in the root graph
+const taskId = generateId();
+await g.putNode('task', taskId, { title: 'Build API' });
+
+// Create agents in a workflow subgraph under the task
+const workflow = g.subgraph(taskId, 'workflow');
+const agentId = generateId();
+await workflow.putNode('agent', agentId, { name: 'Backend Dev' });
+
+// Create the cross-graph edge in the workflow subgraph
+// The edge lives alongside the target (agent), source (task) is an ancestor
+await workflow.putEdge('task', taskId, 'assignedTo', 'agent', agentId, { role: 'lead' });
+
+// Forward traversal: task → agents (automatically crosses into workflow subgraph)
+const result = await createTraversal(g, taskId, registry)
+  .follow('assignedTo')
+  .run();
+// result.nodes contains the agent edges from the workflow subgraph
+```
+
+#### How It Works
+
+1. **Writing**: You explicitly call `putEdge` on the subgraph client where the target node lives. The caller decides where the edge goes.
+
+2. **Reverse traversal is free**: Since the edge lives with the target, querying from the agent's perspective (`findEdges({ bUid: agentId })` on the workflow client) finds it locally.
+
+3. **Forward traversal uses `targetGraph`**: When traversing from the task, the engine sees `targetGraph: 'workflow'` on the registry entry and queries `g.subgraph(taskId, 'workflow')` automatically.
+
+4. **Path-scanning resolution**: To determine if an edge's `aUid` is an ancestor node, firegraph parses the Firestore collection path. The path `graph/taskId/workflow` reveals that `taskId` is a document in the `graph` collection.
+
+#### Registry `targetGraph`
+
+The `targetGraph` field on a `RegistryEntry` tells forward traversal which subgraph to query under each source node:
+
+```typescript
+createRegistry([
+  // When traversing forward from a task along 'assignedTo',
+  // look in the 'workflow' subgraph under each task
+  { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' },
+]);
+```
+
+`targetGraph` must be a single segment (no `/`). It can also be set in entity discovery via `edge.json`:
+
+```json
+{ "from": "task", "to": "agent", "targetGraph": "workflow" }
+```
+
+#### Explicit Hop Override
+
+You can override the registry's `targetGraph` on a per-hop basis:
+
+```typescript
+// Use 'team' subgraph instead of registry's default
+const result = await createTraversal(g, taskId)
+  .follow('assignedTo', { targetGraph: 'team' })
+  .run();
+```
+
+Resolution priority: explicit hop `targetGraph` > registry `targetGraph` > no cross-graph.
+
+#### `findEdgesGlobal` — Collection Group Queries
+
+For cross-cutting reads across all subgraphs, use `findEdgesGlobal`:
+
+```typescript
+// Find all 'assignedTo' edges across all 'workflow' subgraphs in the database
+const allAssignments = await g.findEdgesGlobal(
+  { axbType: 'assignedTo', allowCollectionScan: true },
+  'workflow',  // collection name to query across
+);
+```
+
+This uses Firestore collection group queries and requires collection group indexes. The collection name defaults to the last segment of the client's collection path if omitted.
+
+#### Multi-Hop Limitation
+
+Each hop resolves its reader from the root client. If hop 1 crosses into a subgraph, hop 2 does **not** stay in that subgraph — it reverts to the root. To chain hops within a subgraph, create a separate traversal from the subgraph client:
+
+```typescript
+// This traversal finds agents in the workflow subgraph
+const agents = await createTraversal(g, taskId, registry)
+  .follow('assignedTo')
+  .run();
+
+// To continue traversing within the workflow subgraph,
+// create a new traversal from the subgraph client
+const workflow = g.subgraph(taskId, 'workflow');
+for (const agent of agents.nodes) {
+  const mentees = await createTraversal(workflow, agent.bUid)
+    .follow('mentors')
+    .run();
+}
+```
+
+#### Firestore Path Layout
+
+```
+graph/                              <- root collection
+  {taskId}                          <- task node
+  {taskId}/workflow/                <- workflow subgraph
+    {agentId}                       <- agent node
+    {shard:taskId:assignedTo:agentId} <- cross-graph edge
+```
+
 ### ID Generation
 
 ```typescript
@@ -360,8 +598,10 @@ All errors extend `FiregraphError` with a `code` property:
 | `EdgeNotFoundError` | `EDGE_NOT_FOUND` | Edge lookup fails |
 | `ValidationError` | `VALIDATION_ERROR` | Schema validation fails (registry + Zod) |
 | `RegistryViolationError` | `REGISTRY_VIOLATION` | Triple not registered |
+| `RegistryScopeError` | `REGISTRY_SCOPE` | Type not allowed at this subgraph scope |
 | `DynamicRegistryError` | `DYNAMIC_REGISTRY_ERROR` | Dynamic registry misconfiguration or misuse |
 | `InvalidQueryError` | `INVALID_QUERY` | `findEdges` called with no filters |
+| `QuerySafetyError` | `QUERY_SAFETY` | Query would cause a full collection scan |
 | `TraversalError` | `TRAVERSAL_ERROR` | `run()` called with zero hops |
 
 ```typescript
@@ -403,8 +643,9 @@ import type {
   GraphClientOptions,
 
   // Registry
-  RegistryEntry,
-  GraphRegistry,
+  RegistryEntry,       // includes targetGraph, allowedIn
+  GraphRegistry,       // includes lookupByAxbType
+  EdgeTopology,        // includes targetGraph
 
   // Dynamic Registry
   DynamicGraphClient,
@@ -413,11 +654,15 @@ import type {
   EdgeTypeData,
 
   // Traversal
-  HopDefinition,
+  HopDefinition,       // includes targetGraph
   TraversalOptions,
   HopResult,
   TraversalResult,
   TraversalBuilder,
+
+  // Entity Discovery
+  DiscoveredEntity,
+  DiscoveryResult,
 } from 'firegraph';
 ```
 
@@ -449,6 +694,8 @@ When you call `findEdges`, the query planner decides the strategy:
 
 1. Start with `sourceUids = [startUid]`
 2. For each hop in sequence:
+   - Resolve `targetGraph`: check hop override, then registry, then none
+   - If cross-graph (forward + `targetGraph` + `GraphClient` reader): create a subgraph reader via `reader.subgraph(sourceUid, targetGraph)` for each source
    - Fan out: query edges for each source UID (parallel, bounded by semaphore)
    - Each `findEdges` call counts as 1 read against the budget
    - Apply in-memory `filter` if specified, then apply `limit`

package/dist/codegen/index.d.cts

@@ -1,2 +1,2 @@
-export { l as CodegenOptions, J as generateTypes } from '../index-wSlVH5Nv.cjs';
+export { l as CodegenOptions, J as generateTypes } from '../index-CQkofEC_.cjs';
 import '@google-cloud/firestore';

package/dist/codegen/index.d.ts

@@ -1,2 +1,2 @@
-export { l as CodegenOptions, J as generateTypes } from '../index-wSlVH5Nv.js';
+export { l as CodegenOptions, J as generateTypes } from '../index-CQkofEC_.js';
 import '@google-cloud/firestore';

package/dist/editor/server/index.mjs

@@ -30082,14 +30082,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;
     map2.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 map2.get(tripleKey(aType, axbType, bType))?.entry;
     },
+    lookupByAxbType(axbType) {
+      return axbIndex.get(axbType) ?? [];
+    },
     validate(aType, axbType, bType, data, scopePath) {
       const rec = map2.get(tripleKey(aType, axbType, bType));
       if (!rec) {
@@ -30136,6 +30157,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({
@@ -30147,7 +30174,8 @@ function discoveryToEntries(discovery) {
           inverseLabel: topology.inverseLabel,
           titleField: entity.titleField,
           subtitleField: entity.subtitleField,
-          allowedIn: entity.allowedIn
+          allowedIn: entity.allowedIn,
+          targetGraph: resolvedTargetGraph
         });
       }
     }
@@ -30197,7 +30225,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
 };
@@ -30258,7 +30287,8 @@ async function createRegistryFromGraph(reader) {
           inverseLabel: data.inverseLabel,
           titleField: data.titleField,
           subtitleField: data.subtitleField,
-          allowedIn: data.allowedIn
+          allowedIn: data.allowedIn,
+          targetGraph: data.targetGraph
         });
       }
     }
@@ -30512,6 +30542,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) {
@@ -30563,6 +30620,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;
@@ -30788,7 +30846,8 @@ function loadEdgeEntity(dir, name) {
     viewDefaults: meta3?.viewDefaults,
     viewsPath,
     sampleData,
-    allowedIn: meta3?.allowedIn
+    allowedIn: meta3?.allowedIn,
+    targetGraph: topology.targetGraph ?? meta3?.targetGraph
   };
 }
 function getSubdirectories(dir) {

package/dist/{index-wSlVH5Nv.d.cts → index-CQkofEC_.d.cts}

@@ -199,12 +199,38 @@ interface RegistryEntry {
      *   - `'**​/agents'`       — `**` matches zero or more segments
      */
     allowedIn?: string[];
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     *
+     * When set, forward traversal queries the named subgraph under each
+     * source node (e.g., `{collection}/{sourceUid}/{targetGraph}`) instead
+     * of the current collection. The subgraph contains both the edge
+     * documents and the target nodes they reference.
+     *
+     * Reverse traversal is unaffected — if you're already in the subgraph,
+     * the edges are local.
+     *
+     * Only applies to edge entries (not node self-loop entries).
+     * Must be a single segment (no `/`).
+     *
+     * @example
+     * ```ts
+     * { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' }
+     * // Forward traversal from task1: queries {collection}/task1/workflow
+     * ```
+     */
+    targetGraph?: string;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
     from: string | string[];
     to: string | string[];
     inverseLabel?: string;
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     * See `RegistryEntry.targetGraph` for full documentation.
+     */
+    targetGraph?: string;
 }
 /** A discovered entity from the per-entity folder convention. */
 interface DiscoveredEntity {
@@ -227,6 +253,8 @@ interface DiscoveredEntity {
     sampleData?: Record<string, unknown>;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /** Subgraph name where cross-graph edges of this type live. */
+    targetGraph?: string;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -284,6 +312,7 @@ interface EdgeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    targetGraph?: string;
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
@@ -318,6 +347,8 @@ interface GraphClientOptions {
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
     lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    /** Return all entries matching the given axbType (edge relation name). */
+    lookupByAxbType(axbType: string): ReadonlyArray<RegistryEntry>;
     entries(): ReadonlyArray<RegistryEntry>;
 }
 interface GraphReader {
@@ -356,6 +387,19 @@ interface GraphClient extends GraphReader, GraphWriter {
      * @returns A `GraphClient` scoped to `{collectionPath}/{parentNodeUid}/{name}`
      */
     subgraph(parentNodeUid: string, name?: string): GraphClient;
+    /**
+     * Find edges across all subgraphs using a Firestore collection group query.
+     *
+     * Queries all collections with the given name (defaults to `'graph'`) across
+     * the entire database. This is useful for cross-cutting reads that span
+     * multiple subgraphs.
+     *
+     * **Requires** a Firestore collection group index for the query pattern.
+     *
+     * @param params - Edge filter parameters (same as `findEdges`)
+     * @param collectionName - Collection name to query across (defaults to last segment of this client's collection path)
+     */
+    findEdgesGlobal(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -381,6 +425,23 @@ interface HopDefinition {
         direction?: 'asc' | 'desc';
     };
     filter?: (edge: StoredGraphRecord) => boolean;
+    /**
+     * Subgraph name to cross into for this hop (forward traversal only).
+     *
+     * When set, the traversal queries the named subgraph under each source node
+     * instead of the current collection (`{collection}/{sourceUid}/{targetGraph}`).
+     *
+     * If omitted but the registry has a `targetGraph` for this `axbType`,
+     * the registry value is used automatically.
+     *
+     * **Context tracking:** Once a hop crosses into a subgraph, subsequent
+     * hops without `targetGraph` stay in that subgraph automatically. To
+     * cross into a different subgraph, set `targetGraph` explicitly on the
+     * next hop — explicit `targetGraph` always resolves relative to the
+     * root client, not the current subgraph. To return to the root graph,
+     * create a separate traversal from the root client.
+     */
+    targetGraph?: string;
 }
 interface TraversalOptions {
     maxReads?: number;

package/dist/{index-wSlVH5Nv.d.ts → index-CQkofEC_.d.ts}

@@ -199,12 +199,38 @@ interface RegistryEntry {
      *   - `'**​/agents'`       — `**` matches zero or more segments
      */
     allowedIn?: string[];
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     *
+     * When set, forward traversal queries the named subgraph under each
+     * source node (e.g., `{collection}/{sourceUid}/{targetGraph}`) instead
+     * of the current collection. The subgraph contains both the edge
+     * documents and the target nodes they reference.
+     *
+     * Reverse traversal is unaffected — if you're already in the subgraph,
+     * the edges are local.
+     *
+     * Only applies to edge entries (not node self-loop entries).
+     * Must be a single segment (no `/`).
+     *
+     * @example
+     * ```ts
+     * { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' }
+     * // Forward traversal from task1: queries {collection}/task1/workflow
+     * ```
+     */
+    targetGraph?: string;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
     from: string | string[];
     to: string | string[];
     inverseLabel?: string;
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     * See `RegistryEntry.targetGraph` for full documentation.
+     */
+    targetGraph?: string;
 }
 /** A discovered entity from the per-entity folder convention. */
 interface DiscoveredEntity {
@@ -227,6 +253,8 @@ interface DiscoveredEntity {
     sampleData?: Record<string, unknown>;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /** Subgraph name where cross-graph edges of this type live. */
+    targetGraph?: string;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -284,6 +312,7 @@ interface EdgeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    targetGraph?: string;
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
@@ -318,6 +347,8 @@ interface GraphClientOptions {
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
     lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    /** Return all entries matching the given axbType (edge relation name). */
+    lookupByAxbType(axbType: string): ReadonlyArray<RegistryEntry>;
     entries(): ReadonlyArray<RegistryEntry>;
 }
 interface GraphReader {
@@ -356,6 +387,19 @@ interface GraphClient extends GraphReader, GraphWriter {
      * @returns A `GraphClient` scoped to `{collectionPath}/{parentNodeUid}/{name}`
      */
     subgraph(parentNodeUid: string, name?: string): GraphClient;
+    /**
+     * Find edges across all subgraphs using a Firestore collection group query.
+     *
+     * Queries all collections with the given name (defaults to `'graph'`) across
+     * the entire database. This is useful for cross-cutting reads that span
+     * multiple subgraphs.
+     *
+     * **Requires** a Firestore collection group index for the query pattern.
+     *
+     * @param params - Edge filter parameters (same as `findEdges`)
+     * @param collectionName - Collection name to query across (defaults to last segment of this client's collection path)
+     */
+    findEdgesGlobal(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -381,6 +425,23 @@ interface HopDefinition {
         direction?: 'asc' | 'desc';
     };
     filter?: (edge: StoredGraphRecord) => boolean;
+    /**
+     * Subgraph name to cross into for this hop (forward traversal only).
+     *
+     * When set, the traversal queries the named subgraph under each source node
+     * instead of the current collection (`{collection}/{sourceUid}/{targetGraph}`).
+     *
+     * If omitted but the registry has a `targetGraph` for this `axbType`,
+     * the registry value is used automatically.
+     *
+     * **Context tracking:** Once a hop crosses into a subgraph, subsequent
+     * hops without `targetGraph` stay in that subgraph automatically. To
+     * cross into a different subgraph, set `targetGraph` explicitly on the
+     * next hop — explicit `targetGraph` always resolves relative to the
+     * root client, not the current subgraph. To return to the root graph,
+     * create a separate traversal from the root client.
+     */
+    targetGraph?: string;
 }
 interface TraversalOptions {
     maxReads?: number;