@typicalday/firegraph 0.2.0 → 0.4.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
 
@@ -337,10 +340,245 @@ Key behaviors:
 - **After `reloadRegistry()`**: Domain writes are validated against the compiled registry. Unknown types are always rejected.
 - **Upsert semantics**: Calling `defineNodeType('tour', ...)` twice overwrites the previous definition. After reloading, the latest schema is used.
 - **Separate collection**: Meta-nodes can be stored in a different collection via `registryMode: { mode: 'dynamic', collection: 'meta' }`.
-- **Mutual exclusivity**: `registry` (static) and `registryMode` (dynamic) cannot be used together.
+- **Merged mode**: Provide both `registry` (static) and `registryMode` (dynamic) to get a merged registry where static entries take priority and dynamic definitions can only add new types — not override existing ones.
 
 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-DR3jF5_b.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-DR3jF5_b.js';
 import '@google-cloud/firestore';

package/dist/editor/server/index.mjs

@@ -30072,6 +30072,9 @@ function matchSegments(path4, pi, pattern, qi) {
 function tripleKey(aType, axbType, bType) {
   return `${aType}:${axbType}:${bType}`;
 }
+function tripleKeyFor(e) {
+  return tripleKey(e.aType, e.axbType, e.bType);
+}
 function createRegistry(input) {
   const map2 = /* @__PURE__ */ new Map();
   let entries;
@@ -30082,14 +30085,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) {
@@ -30117,6 +30141,45 @@ function createRegistry(input) {
     }
   };
 }
+function createMergedRegistry(base, extension) {
+  const baseKeys = new Set(base.entries().map(tripleKeyFor));
+  return {
+    lookup(aType, axbType, bType) {
+      return base.lookup(aType, axbType, bType) ?? extension.lookup(aType, axbType, bType);
+    },
+    lookupByAxbType(axbType) {
+      const baseResults = base.lookupByAxbType(axbType);
+      const extResults = extension.lookupByAxbType(axbType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map(tripleKeyFor));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      if (baseKeys.has(tripleKey(aType, axbType, bType))) {
+        return base.validate(aType, axbType, bType, data, scopePath);
+      }
+      return extension.validate(aType, axbType, bType, data, scopePath);
+    },
+    entries() {
+      const extEntries = extension.entries();
+      if (extEntries.length === 0) return base.entries();
+      const merged = [...base.entries()];
+      for (const entry of extEntries) {
+        if (!baseKeys.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    }
+  };
+}
 function discoveryToEntries(discovery) {
   const entries = [];
   for (const [name, entity] of discovery.nodes) {
@@ -30136,6 +30199,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 +30216,8 @@ function discoveryToEntries(discovery) {
           inverseLabel: topology.inverseLabel,
           titleField: entity.titleField,
           subtitleField: entity.subtitleField,
-          allowedIn: entity.allowedIn
+          allowedIn: entity.allowedIn,
+          targetGraph: resolvedTargetGraph
         });
       }
     }
@@ -30197,7 +30267,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 +30329,8 @@ async function createRegistryFromGraph(reader) {
           inverseLabel: data.inverseLabel,
           titleField: data.titleField,
           subtitleField: data.subtitleField,
-          allowedIn: data.allowedIn
+          allowedIn: data.allowedIn,
+          targetGraph: data.targetGraph
         });
       }
     }
@@ -30274,14 +30346,12 @@ var GraphClientImpl = class _GraphClientImpl {
     this.db = db2;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db2, collectionPath);
-    if (options?.registry && options?.registryMode) {
-      throw new DynamicRegistryError(
-        'Cannot provide both "registry" and "registryMode". Use "registry" for static mode or "registryMode" for dynamic mode.'
-      );
-    }
     if (options?.registryMode) {
       this.dynamicConfig = options.registryMode;
       this.bootstrapRegistry = createBootstrapRegistry();
+      if (options.registry) {
+        this.staticRegistry = options.registry;
+      }
       const metaCollectionPath = options.registryMode.collection;
       if (metaCollectionPath && metaCollectionPath !== collectionPath) {
         this.metaAdapter = createFirestoreAdapter(db2, metaCollectionPath);
@@ -30333,18 +30403,20 @@ var GraphClientImpl = class _GraphClientImpl {
   /**
    * Get the appropriate registry for validating a write to the given type.
    *
-   * - Static mode: returns staticRegistry (or undefined if none set)
-   * - Dynamic mode:
+   * - Static-only mode: returns staticRegistry (or undefined if none set)
+   * - Dynamic mode (pure or merged):
    *   - Meta-types (nodeType, edgeType): validated against bootstrapRegistry
    *   - Domain types: validated against dynamicRegistry (falls back to
    *     bootstrapRegistry which rejects unknown types)
+   *   - Merged mode: dynamicRegistry is a merged wrapper (static + dynamic
+   *     extension), so static entries take priority automatically.
    */
   getRegistryForType(aType) {
     if (!this.dynamicConfig) return this.staticRegistry;
     if (aType === META_NODE_TYPE || aType === META_EDGE_TYPE) {
       return this.bootstrapRegistry;
     }
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   /**
    * Get the Firestore adapter for writing the given type.
@@ -30358,13 +30430,13 @@ var GraphClientImpl = class _GraphClientImpl {
   }
   /**
    * Get the combined registry for transaction/batch context.
-   * In static mode, returns staticRegistry.
+   * In static-only mode, returns staticRegistry.
    * In dynamic mode, returns dynamicRegistry (which includes bootstrap entries)
-   * or bootstrapRegistry if not yet reloaded.
+   * or falls back to staticRegistry (merged mode) or bootstrapRegistry.
    */
   getCombinedRegistry() {
     if (!this.dynamicConfig) return this.staticRegistry;
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   // ---------------------------------------------------------------------------
   // Query dispatch
@@ -30512,6 +30584,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) {
@@ -30534,6 +30633,11 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry?.lookup(name, NODE_RELATION, name)) {
+      throw new DynamicRegistryError(
+        `Cannot define node type "${name}": already defined in the static registry.`
+      );
+    }
     const uid = generateDeterministicUid(META_NODE_TYPE, name);
     const data = { name, jsonSchema };
     if (description !== void 0) data.description = description;
@@ -30555,6 +30659,19 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry) {
+      const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+      const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+      for (const aType of fromTypes) {
+        for (const bType of toTypes) {
+          if (this.staticRegistry.lookup(aType, name, bType)) {
+            throw new DynamicRegistryError(
+              `Cannot define edge type "${name}" for (${aType}) -> (${bType}): already defined in the static registry.`
+            );
+          }
+        }
+      }
+    }
     const uid = generateDeterministicUid(META_EDGE_TYPE, name);
     const data = {
       name,
@@ -30563,6 +30680,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;
@@ -30578,7 +30696,12 @@ var GraphClientImpl = class _GraphClientImpl {
       );
     }
     const reader = this.createMetaReader();
-    this.dynamicRegistry = await createRegistryFromGraph(reader);
+    const dynamicOnly = await createRegistryFromGraph(reader);
+    if (this.staticRegistry) {
+      this.dynamicRegistry = createMergedRegistry(this.staticRegistry, dynamicOnly);
+    } else {
+      this.dynamicRegistry = dynamicOnly;
+    }
   }
   /**
    * Create a GraphReader for the meta-collection.
@@ -30788,7 +30911,8 @@ function loadEdgeEntity(dir, name) {
     viewDefaults: meta3?.viewDefaults,
     viewsPath,
     sampleData,
-    allowedIn: meta3?.allowedIn
+    allowedIn: meta3?.allowedIn,
+    targetGraph: topology.targetGraph ?? meta3?.targetGraph
   };
 }
 function getSubdirectories(dir) {