@dxos/app-graph 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/graph-builder.test.ts

@@ -2,122 +2,379 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Registry, Rx } from '@effect-rx/rx-react';
-import { Option, pipe } from 'effect';
+import { Atom, Registry } from '@effect-atom/atom-react';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
 import { describe, expect, onTestFinished, test } from 'vitest';
 
-import { sleep, Trigger } from '@dxos/async';
+import { Trigger } from '@dxos/async';
+import { Obj } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
 
-import { ROOT_ID } from './graph';
-import { createExtension, GraphBuilder } from './graph-builder';
-import { type Node } from './node';
+import * as Graph from './graph';
+import * as GraphBuilder from './graph-builder';
+import * as Node from './node';
+import * as NodeMatcher from './node-matcher';
+import { qualifyId } from './util';
 
 const exampleId = (id: number) => `dx:test:${id}`;
 const EXAMPLE_ID = exampleId(1);
-const EXAMPLE_TYPE = 'dxos.org/type/example';
+const EXAMPLE_TYPE = 'org.dxos.type.example';
 
 describe('GraphBuilder', () => {
+  describe('resolver', () => {
+    test('works', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const graph = builder.graph;
+
+      {
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node).to.be.null;
+      }
+
+      // Test direct API
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'resolver',
+          resolver: () => Atom.make({ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: 1 }),
+        }),
+      );
+      await Graph.initialize(graph, EXAMPLE_ID);
+
+      {
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node?.id).to.equal(EXAMPLE_ID);
+        expect(node?.type).to.equal(EXAMPLE_TYPE);
+        expect(node?.data).to.equal(1);
+      }
+    });
+
+    test('updates', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const name = Atom.make('default');
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'resolver',
+          resolver: () => Atom.make((get) => ({ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: get(name) })),
+        }),
+      );
+      const graph = builder.graph;
+      await Graph.initialize(graph, EXAMPLE_ID);
+
+      {
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('default');
+      }
+
+      registry.set(name, 'updated');
+
+      {
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('updated');
+      }
+    });
+
+    test('connects resolved node to parent via child edge', async ({ expect }) => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const childId = qualifyId('root', '~child');
+
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'resolver',
+          resolver: (id) =>
+            id === childId ? Atom.make({ id: childId, type: EXAMPLE_TYPE, data: 'resolved' }) : Atom.make(null),
+        }),
+      );
+
+      const graph = builder.graph;
+      await Graph.initialize(graph, childId);
+
+      {
+        const node = Graph.getNode(graph, childId).pipe(Option.getOrNull);
+        expect(node?.id).to.equal(childId);
+        expect(node?.data).to.equal('resolved');
+      }
+
+      // Verify the resolved node is a child of root.
+      {
+        const children = registry.get(graph.connections('root', 'child'));
+        expect(children.some((n) => n.id === childId)).to.be.true;
+      }
+    });
+
+    test('out-of-order: resolver fires before parent exists', async ({ expect }) => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const parentId = qualifyId('root', 'parent');
+      const childId = qualifyId('root', 'parent', '~child');
+
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
+          id: 'resolver',
+          resolver: (id) =>
+            id === childId ? Atom.make({ id: childId, type: EXAMPLE_TYPE, data: 'resolved-child' }) : Atom.make(null),
+        }),
+        GraphBuilder.createExtensionRaw({
+          id: 'connector',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [{ id: 'parent', type: EXAMPLE_TYPE, data: 'parent-data' }]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+      ]);
+
+      const graph = builder.graph;
+
+      // Resolve child BEFORE parent exists in the graph.
+      await Graph.initialize(graph, childId);
+
+      {
+        const node = Graph.getNode(graph, childId).pipe(Option.getOrNull);
+        expect(node?.id).to.equal(childId);
+        expect(node?.data).to.equal('resolved-child');
+      }
+
+      // Now expand root to create parent via connector.
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      {
+        const parent = Graph.getNode(graph, parentId).pipe(Option.getOrNull);
+        expect(parent?.data).to.equal('parent-data');
+      }
+
+      // The resolved child should be connected to the parent.
+      {
+        const children = registry.get(graph.connections(parentId, 'child'));
+        expect(children.some((n) => n.id === childId)).to.be.true;
+      }
+    });
+
+    test('onNone does not remove connector-owned node', async ({ expect }) => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const nodeId = qualifyId('root', 'shared');
+
+      // Connector that produces root/shared. No resolver matches root/shared.
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'connector',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [{ id: 'shared', type: EXAMPLE_TYPE, data: 'from-connector' }]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+      );
+
+      const graph = builder.graph;
+
+      // Connector produces root/shared.
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      {
+        const node = Graph.getNode(graph, nodeId).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('from-connector');
+      }
+
+      // Initialize fires for the same ID. No resolver matches, so onNone fires.
+      // The connector-owned node should NOT be removed.
+      await Graph.initialize(graph, nodeId);
+
+      {
+        const node = Graph.getNode(graph, nodeId).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('from-connector');
+      }
+    });
+
+    test('does not overwrite connector-produced node', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      const resolverData = Atom.make('from-resolver');
+
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
+          id: 'resolver',
+          resolver: (id) =>
+            id === qualifyId('root', 'shared')
+              ? Atom.make((get) => ({ id: qualifyId('root', 'shared'), type: EXAMPLE_TYPE, data: get(resolverData) }))
+              : Atom.make(null),
+        }),
+        GraphBuilder.createExtensionRaw({
+          id: 'connector',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [{ id: 'shared', type: EXAMPLE_TYPE, data: 'from-connector' }]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+      ]);
+
+      const graph = builder.graph;
+
+      // Connector produces root/shared.
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      {
+        const node = Graph.getNode(graph, qualifyId('root', 'shared')).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('from-connector');
+      }
+
+      // Resolver fires for the same ID but should not overwrite.
+      await Graph.initialize(graph, qualifyId('root', 'shared'));
+
+      {
+        const node = Graph.getNode(graph, qualifyId('root', 'shared')).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('from-connector');
+      }
+
+      // Updating the resolver's atom should still not overwrite.
+      registry.set(resolverData, 'updated-resolver');
+
+      {
+        const node = Graph.getNode(graph, qualifyId('root', 'shared')).pipe(Option.getOrNull);
+        expect(node?.data).to.equal('from-connector');
+      }
+    });
+  });
+
   describe('connector', () => {
-    test('works', () => {
+    test('works', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'outbound-connector',
-          connector: () => Rx.make([{ id: 'child', type: EXAMPLE_TYPE, data: 2 }]),
+          connector: () => Atom.make([{ id: 'child', type: EXAMPLE_TYPE, data: 2 }]),
         }),
       );
-      builder.addExtension(
-        createExtension({
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'inbound-connector',
-          relation: 'inbound',
-          connector: () => Rx.make([{ id: 'parent', type: EXAMPLE_TYPE, data: 0 }]),
+          relation: Node.childRelation('inbound'),
+          connector: () => Atom.make([{ id: 'parent', type: EXAMPLE_TYPE, data: 0 }]),
         }),
       );
 
       const graph = builder.graph;
-      graph.expand(ROOT_ID);
-      graph.expand(ROOT_ID, 'inbound');
+      Graph.expand(graph, Node.RootId, 'child');
+      Graph.expand(graph, Node.RootId, Node.childRelation('inbound'));
+      await GraphBuilder.flush(builder);
 
-      const outbound = registry.get(graph.connections(ROOT_ID));
-      const inbound = registry.get(graph.connections(ROOT_ID, 'inbound'));
+      const outbound = registry.get(graph.connections(Node.RootId, 'child'));
+      const inbound = registry.get(graph.connections(Node.RootId, Node.childRelation('inbound')));
 
       expect(outbound).has.length(1);
-      expect(outbound[0].id).to.equal('child');
+      expect(outbound[0].id).to.equal('root/child');
       expect(outbound[0].data).to.equal(2);
       expect(inbound).has.length(1);
-      expect(inbound[0].id).to.equal('parent');
+      expect(inbound[0].id).to.equal('root/parent');
       expect(inbound[0].data).to.equal(0);
     });
 
-    test('updates', () => {
+    test('updates', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const state = Rx.make(0);
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make({ registry });
+      const state = Atom.make(0);
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
-          connector: () => Rx.make((get) => [{ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: get(state) }]),
+          connector: () => Atom.make((get) => [{ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: get(state) }]),
         }),
       );
       const graph = builder.graph;
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
 
       {
-        const [node] = registry.get(graph.connections(ROOT_ID));
+        const [node] = registry.get(graph.connections(Node.RootId, 'child'));
         expect(node.data).to.equal(0);
       }
 
       {
         registry.set(state, 1);
-        const [node] = registry.get(graph.connections(ROOT_ID));
+        await GraphBuilder.flush(builder);
+        const [node] = registry.get(graph.connections(Node.RootId, 'child'));
         expect(node.data).to.equal(1);
       }
     });
 
-    test('subscribes to updates', () => {
+    test('subscribes to updates', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const state = Rx.make(0);
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make({ registry });
+      const state = Atom.make(0);
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
-          connector: () => Rx.make((get) => [{ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: get(state) }]),
+          connector: () => Atom.make((get) => [{ id: EXAMPLE_ID, type: EXAMPLE_TYPE, data: get(state) }]),
         }),
       );
       const graph = builder.graph;
 
       let count = 0;
-      const cancel = registry.subscribe(graph.connections(ROOT_ID), (_) => {
+      const cancel = registry.subscribe(graph.connections(Node.RootId, 'child'), (_) => {
         count++;
       });
       onTestFinished(() => cancel());
 
       expect(count).to.equal(0);
-      expect(registry.get(graph.connections(ROOT_ID))).to.have.length(0);
+      expect(registry.get(graph.connections(Node.RootId, 'child'))).to.have.length(0);
       expect(count).to.equal(1);
 
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(2);
+
       registry.set(state, 1);
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(3);
     });
 
-    test('updates with new extensions', () => {
+    test('updates with new extensions', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
-          connector: () => Rx.make([{ id: EXAMPLE_ID, type: EXAMPLE_TYPE }]),
+          connector: () => Atom.make([{ id: EXAMPLE_ID, type: EXAMPLE_TYPE }]),
         }),
       );
       const graph = builder.graph;
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
 
-      let nodes: Node[] = [];
+      let nodes: Node.Node[] = [];
       let count = 0;
-      const cancel = registry.subscribe(graph.connections(ROOT_ID), (_nodes) => {
+      const cancel = registry.subscribe(graph.connections(Node.RootId, 'child'), (_nodes) => {
         count++;
         nodes = _nodes;
       });
@@ -125,63 +382,68 @@ describe('GraphBuilder', () => {
 
       expect(nodes).has.length(0);
       expect(count).to.equal(0);
-      registry.get(graph.connections(ROOT_ID));
+      registry.get(graph.connections(Node.RootId, 'child'));
       expect(nodes).has.length(1);
       expect(count).to.equal(1);
 
-      builder.addExtension(
-        createExtension({
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector-2',
-          connector: () => Rx.make([{ id: exampleId(2), type: EXAMPLE_TYPE }]),
+          connector: () => Atom.make([{ id: exampleId(2), type: EXAMPLE_TYPE }]),
         }),
       );
+      await GraphBuilder.flush(builder);
       expect(nodes).has.length(2);
       expect(count).to.equal(2);
     });
 
-    test('removes', () => {
+    test('removes', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const nodes = Rx.make([
+      const builder = GraphBuilder.make({ registry });
+      const nodes = Atom.make([
         { id: exampleId(1), type: EXAMPLE_TYPE },
         { id: exampleId(2), type: EXAMPLE_TYPE },
       ]);
-      builder.addExtension(
-        createExtension({
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
-          connector: () => Rx.make((get) => get(nodes)),
+          connector: () => Atom.make((get) => get(nodes)),
         }),
       );
       const graph = builder.graph;
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
 
       {
-        const nodes = registry.get(graph.connections(ROOT_ID));
+        const nodes = registry.get(graph.connections(Node.RootId, 'child'));
         expect(nodes).has.length(2);
-        expect(nodes[0].id).to.equal(exampleId(1));
-        expect(nodes[1].id).to.equal(exampleId(2));
+        expect(nodes[0].id).to.equal(qualifyId('root', exampleId(1)));
+        expect(nodes[1].id).to.equal(qualifyId('root', exampleId(2)));
       }
 
       registry.set(nodes, [{ id: exampleId(3), type: EXAMPLE_TYPE }]);
+      await GraphBuilder.flush(builder);
 
       {
-        const nodes = registry.get(graph.connections(ROOT_ID));
+        const nodes = registry.get(graph.connections(Node.RootId, 'child'));
         expect(nodes).has.length(1);
-        expect(nodes[0].id).to.equal(exampleId(3));
+        expect(nodes[0].id).to.equal(qualifyId('root', exampleId(3)));
       }
     });
 
-    test('nodes are updated when removed', () => {
+    test('nodes are updated when removed', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const name = Rx.make('removed');
+      const builder = GraphBuilder.make({ registry });
+      const name = Atom.make('removed');
 
-      builder.addExtension([
-        createExtension({
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
           id: 'root',
           connector: (node) =>
-            Rx.make((get) =>
-              pipe(
+            Atom.make((get) =>
+              Function.pipe(
                 get(node),
                 Option.flatMap((node) => (node.id === 'root' ? Option.some(get(name)) : Option.none())),
                 Option.filter((name) => name !== 'removed'),
@@ -196,52 +458,184 @@ describe('GraphBuilder', () => {
 
       let count = 0;
       let exists = false;
-      const cancel = registry.subscribe(graph.node(EXAMPLE_ID), (node) => {
+      const cancel = registry.subscribe(graph.node(qualifyId('root', EXAMPLE_ID)), (node) => {
         count++;
         exists = Option.isSome(node);
       });
       onTestFinished(() => cancel());
 
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(0);
       expect(exists).to.be.false;
 
       registry.set(name, 'default');
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(1);
       expect(exists).to.be.true;
 
       registry.set(name, 'removed');
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(2);
       expect(exists).to.be.false;
 
       registry.set(name, 'added');
+      await GraphBuilder.flush(builder);
       expect(count).to.equal(3);
       expect(exists).to.be.true;
     });
 
+    describe('inline nodes', () => {
+      const parent = (child?: Node.NodeArg<any>): Node.NodeArg<any> => ({
+        id: 'parent-node',
+        type: EXAMPLE_TYPE,
+        data: null,
+        nodes: child ? [child] : [],
+      });
+
+      const inlineChild = (overrides?: Partial<Node.NodeArg<any>>): Node.NodeArg<any> => ({
+        id: 'inline-child',
+        type: EXAMPLE_TYPE,
+        data: null,
+        ...overrides,
+      });
+
+      const makeGraph = () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const nodesAtom = Atom.make<Node.NodeArg<any>[]>([]);
+        GraphBuilder.addExtension(
+          builder,
+          GraphBuilder.createExtensionRaw({
+            id: 'inline-connector',
+            connector: () => Atom.make((get) => get(nodesAtom)),
+          }),
+        );
+        const graph = builder.graph;
+        Graph.expand(graph, Node.RootId, 'child');
+        return { registry, builder, graph, nodesAtom };
+      };
+
+      const getInlineChild = (graph: Graph.ExpandableGraph) =>
+        Graph.getNode(graph, 'root/parent-node/inline-child').pipe(Option.getOrNull);
+
+      test('are removed when connector re-runs with data change', async () => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [parent(inlineChild())]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.not.be.null;
+
+        // Remove inline child while also changing parent data to trigger the update.
+        registry.set(nodesAtom, [{ ...parent(), data: 'v2' }]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.be.null;
+      });
+
+      test('are removed when only inline children change', async () => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [parent(inlineChild())]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.not.be.null;
+
+        // Remove inline child without touching parent — tests change detection covers inline children.
+        registry.set(nodesAtom, [parent()]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.be.null;
+      });
+
+      test('are added when connector re-runs', async () => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [parent()]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.be.null;
+
+        registry.set(nodesAtom, [parent(inlineChild())]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)).to.not.be.null;
+      });
+
+      test('reactively update data', async ({ expect }) => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [parent(inlineChild({ data: 'v1' }))]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)?.data).to.equal('v1');
+
+        // Change only the inline child's data — parent is unchanged.
+        registry.set(nodesAtom, [parent(inlineChild({ data: 'v2' }))]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)?.data).to.equal('v2');
+      });
+
+      test('reactively update properties', async ({ expect }) => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+        registry.set(nodesAtom, [parent(inlineChild({ properties: { label: 'before' } }))]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)?.properties.label).to.equal('before');
+
+        registry.set(nodesAtom, [parent(inlineChild({ properties: { label: 'after' } }))]);
+        await GraphBuilder.flush(builder);
+
+        expect(getInlineChild(graph)?.properties.label).to.equal('after');
+      });
+
+      test('deeply nested inline nodes reactively update', async ({ expect }) => {
+        const { registry, builder, graph, nodesAtom } = makeGraph();
+
+        const withGrandchild = (data: string) =>
+          parent({
+            id: 'child',
+            type: EXAMPLE_TYPE,
+            data: null,
+            nodes: [{ id: 'grandchild', type: EXAMPLE_TYPE, data }],
+          });
+
+        registry.set(nodesAtom, [withGrandchild('v1')]);
+        await GraphBuilder.flush(builder);
+
+        expect(Graph.getNode(graph, 'root/parent-node/child/grandchild').pipe(Option.getOrNull)?.data).to.equal('v1');
+
+        // Change only the grandchild's data — all ancestors unchanged.
+        registry.set(nodesAtom, [withGrandchild('v2')]);
+        await GraphBuilder.flush(builder);
+
+        expect(Graph.getNode(graph, 'root/parent-node/child/grandchild').pipe(Option.getOrNull)?.data).to.equal('v2');
+      });
+    });
+
     test('sort edges', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const nodes = Rx.make([
+      const builder = GraphBuilder.make({ registry });
+      const nodes = Atom.make([
         { id: exampleId(1), type: EXAMPLE_TYPE, data: 1 },
         { id: exampleId(2), type: EXAMPLE_TYPE, data: 2 },
         { id: exampleId(3), type: EXAMPLE_TYPE, data: 3 },
       ]);
-      builder.addExtension(
-        createExtension({
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
-          connector: () => Rx.make((get) => get(nodes)),
+          connector: () => Atom.make((get) => get(nodes)),
         }),
       );
       const graph = builder.graph;
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
 
       {
-        const nodes = registry.get(graph.connections(ROOT_ID));
+        const nodes = registry.get(graph.connections(Node.RootId, 'child'));
         expect(nodes).has.length(3);
-        expect(nodes[0].id).to.equal(exampleId(1));
-        expect(nodes[1].id).to.equal(exampleId(2));
-        expect(nodes[2].id).to.equal(exampleId(3));
+        expect(nodes[0].id).to.equal(qualifyId('root', exampleId(1)));
+        expect(nodes[1].id).to.equal(qualifyId('root', exampleId(2)));
+        expect(nodes[2].id).to.equal(qualifyId('root', exampleId(3)));
       }
 
       registry.set(nodes, [
@@ -249,31 +643,29 @@ describe('GraphBuilder', () => {
         { id: exampleId(1), type: EXAMPLE_TYPE, data: 1 },
         { id: exampleId(2), type: EXAMPLE_TYPE, data: 2 },
       ]);
-
-      // TODO(wittjosiah): Why is this needed for the following conditions to pass?
-      await sleep(0);
+      await GraphBuilder.flush(builder);
 
       {
-        const nodes = registry.get(graph.connections(ROOT_ID));
+        const nodes = registry.get(graph.connections(Node.RootId, 'child'));
         expect(nodes).has.length(3);
-        expect(nodes[0].id).to.equal(exampleId(3));
-        expect(nodes[1].id).to.equal(exampleId(1));
-        expect(nodes[2].id).to.equal(exampleId(2));
+        expect(nodes[0].id).to.equal(qualifyId('root', exampleId(3)));
+        expect(nodes[1].id).to.equal(qualifyId('root', exampleId(1)));
+        expect(nodes[2].id).to.equal(qualifyId('root', exampleId(2)));
       }
     });
 
-    test('updates are constrained', () => {
+    test('updates are constrained', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      const name = Rx.make('default');
-      const sub = Rx.make('default');
+      const builder = GraphBuilder.make({ registry });
+      const name = Atom.make('default');
+      const sub = Atom.make('default');
 
-      builder.addExtension([
-        createExtension({
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
           id: 'root',
           connector: (node) =>
-            Rx.make((get) =>
-              pipe(
+            Atom.make((get) =>
+              Function.pipe(
                 get(node),
                 Option.flatMap((node) => (node.id === 'root' ? Option.some(get(name)) : Option.none())),
                 Option.filter((name) => name !== 'removed'),
@@ -282,25 +674,29 @@ describe('GraphBuilder', () => {
               ),
             ),
         }),
-        createExtension({
+        GraphBuilder.createExtensionRaw({
           id: 'connector1',
           connector: (node) =>
-            Rx.make((get) =>
-              pipe(
+            Atom.make((get) =>
+              Function.pipe(
                 get(node),
-                Option.flatMap((node) => (node.id === EXAMPLE_ID ? Option.some(get(sub)) : Option.none())),
+                Option.flatMap((node) =>
+                  node.id === qualifyId('root', EXAMPLE_ID) ? Option.some(get(sub)) : Option.none(),
+                ),
                 Option.map((sub) => [{ id: exampleId(2), type: EXAMPLE_TYPE, data: sub }]),
                 Option.getOrElse(() => []),
               ),
             ),
         }),
-        createExtension({
+        GraphBuilder.createExtensionRaw({
           id: 'connector2',
           connector: (node) =>
-            Rx.make((get) =>
-              pipe(
+            Atom.make((get) =>
+              Function.pipe(
                 get(node),
-                Option.flatMap((node) => (node.id === EXAMPLE_ID ? Option.some(node.data) : Option.none())),
+                Option.flatMap((node) =>
+                  node.id === qualifyId('root', EXAMPLE_ID) ? Option.some(node.data) : Option.none(),
+                ),
                 Option.map((data) => [{ id: exampleId(3), type: EXAMPLE_TYPE, data }]),
                 Option.getOrElse(() => []),
               ),
@@ -311,64 +707,71 @@ describe('GraphBuilder', () => {
       const graph = builder.graph;
 
       let parentCount = 0;
-      const parentCancel = registry.subscribe(graph.node(EXAMPLE_ID), (_) => {
+      const parentCancel = registry.subscribe(graph.node(qualifyId('root', EXAMPLE_ID)), (_) => {
         parentCount++;
       });
       onTestFinished(() => parentCancel());
 
       let independentCount = 0;
-      const independentCancel = registry.subscribe(graph.node(exampleId(2)), (_) => {
+      const independentCancel = registry.subscribe(graph.node(qualifyId('root', EXAMPLE_ID, exampleId(2))), (_) => {
         independentCount++;
       });
       onTestFinished(() => independentCancel());
 
       let dependentCount = 0;
-      const dependentCancel = registry.subscribe(graph.node(exampleId(3)), (_) => {
+      const dependentCancel = registry.subscribe(graph.node(qualifyId('root', EXAMPLE_ID, exampleId(3))), (_) => {
         dependentCount++;
       });
       onTestFinished(() => dependentCancel());
 
       // Counts should not increment until the node is expanded.
-      graph.expand(ROOT_ID);
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(1);
       expect(independentCount).to.equal(0);
       expect(dependentCount).to.equal(0);
 
       // Counts should increment when the node is expanded.
-      graph.expand(EXAMPLE_ID);
+      Graph.expand(graph, qualifyId('root', EXAMPLE_ID), 'child');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(1);
       expect(independentCount).to.equal(1);
       expect(dependentCount).to.equal(1);
 
       // Only dependent count should increment when the parent changes.
       registry.set(name, 'updated');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(2);
       expect(independentCount).to.equal(1);
       expect(dependentCount).to.equal(2);
 
       // Only independent count should increment when its state changes.
       registry.set(sub, 'updated');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(2);
       expect(independentCount).to.equal(2);
       expect(dependentCount).to.equal(2);
 
       // Independent count should update if its state changes even if the parent is removed.
-      Rx.batch(() => {
+      Atom.batch(() => {
         registry.set(name, 'removed');
         registry.set(sub, 'batch');
       });
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(2);
       expect(independentCount).to.equal(3);
       expect(dependentCount).to.equal(2);
 
       // Dependent count should increment when the node is added back.
       registry.set(name, 'added');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(3);
       expect(independentCount).to.equal(3);
       expect(dependentCount).to.equal(3);
 
       // Counts should not increment when the node is expanded again.
-      graph.expand(EXAMPLE_ID);
+      Graph.expand(graph, qualifyId('root', EXAMPLE_ID), 'child');
+      await GraphBuilder.flush(builder);
       expect(parentCount).to.equal(3);
       expect(independentCount).to.equal(3);
       expect(dependentCount).to.equal(3);
@@ -376,13 +779,14 @@ describe('GraphBuilder', () => {
 
     test('eager graph expansion', async () => {
       const registry = Registry.make();
-      const builder = new GraphBuilder({ registry });
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
           connector: (node) => {
-            return Rx.make((get) =>
-              pipe(
+            return Atom.make((get) =>
+              Function.pipe(
                 get(node),
                 Option.map((node) => (node.data ? node.data + 1 : 1)),
                 Option.filter((data) => data <= 5),
@@ -397,14 +801,14 @@ describe('GraphBuilder', () => {
       let count = 0;
       const trigger = new Trigger();
       builder.graph.onNodeChanged.on(({ id }) => {
-        builder.graph.expand(id);
+        Graph.expand(builder.graph, id, 'child');
         count++;
         if (count === 5) {
           trigger.wake();
         }
       });
 
-      builder.graph.expand(ROOT_ID);
+      Graph.expand(builder.graph, Node.RootId, 'child');
       await trigger.wait();
       expect(count).to.equal(5);
     });
@@ -412,13 +816,14 @@ describe('GraphBuilder', () => {
 
   describe('explore', () => {
     test('works', async () => {
-      const builder = new GraphBuilder();
-      builder.addExtension(
-        createExtension({
+      const builder = GraphBuilder.make();
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
           id: 'connector',
           connector: (node) =>
-            Rx.make((get) =>
-              pipe(
+            Atom.make((get) =>
+              Function.pipe(
                 get(node),
                 Option.map((node) => (node.data ? node.data + 1 : 1)),
                 Option.filter((data) => data <= 5),
@@ -430,7 +835,8 @@ describe('GraphBuilder', () => {
       );
 
       let count = 0;
-      await builder.explore({
+      await GraphBuilder.explore(builder, {
+        relation: 'child',
         visitor: () => {
           count++;
         },
@@ -439,4 +845,665 @@ describe('GraphBuilder', () => {
       expect(count).to.equal(6);
     });
   });
+
+  describe('helpers', () => {
+    describe('createConnector', () => {
+      test('creates connector with type inference', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const matcher = (node: Node.Node) => NodeMatcher.whenId('root')(node);
+        const factory = (node: Node.Node) => [{ id: 'child', type: EXAMPLE_TYPE, data: node.id }];
+
+        const connector = GraphBuilder.createConnector(matcher, factory);
+
+        GraphBuilder.addExtension(
+          builder,
+          GraphBuilder.createExtensionRaw({
+            id: 'test-connector',
+            connector,
+          }),
+        );
+
+        Graph.expand(graph, Node.RootId, 'child');
+        await GraphBuilder.flush(builder);
+
+        const connections = registry.get(graph.connections(Node.RootId, 'child'));
+        expect(connections).has.length(1);
+        expect(connections[0].id).to.equal('root/child');
+      });
+    });
+
+    describe('createExtension', () => {
+      test('works with Effect connector', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.succeed([{ id: 'child', type: EXAMPLE_TYPE, data: node.data }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const connections = registry.get(graph.connections('parent', 'child'));
+        expect(connections).has.length(1);
+        expect(connections[0].id).to.equal('parent/child');
+        expect(connections[0].data).to.equal('test');
+      });
+
+      test('works with Effect actions', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            actions: (node, get) =>
+              Effect.succeed([
+                {
+                  id: 'test-action',
+                  data: () => Effect.void,
+                  properties: { label: 'Test' },
+                },
+              ]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const edges = registry.get(graph.edges('parent'));
+        expect(edges[Graph.relationKey('action')] ?? []).to.have.length(1);
+        expect(edges[Graph.relationKey('action')] ?? []).to.include('parent/test-action');
+        expect(edges[Graph.relationKey('child')] ?? []).to.have.length(0);
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(1);
+        expect(actions[0].id).to.equal('parent/test-action');
+      });
+
+      test('actions expand automatically with child relation', async ({ expect }) => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.succeed([{ id: 'child', type: EXAMPLE_TYPE, data: 'c' }]),
+            actions: (node, get) =>
+              Effect.succeed([{ id: 'act1', data: () => Effect.void, properties: { label: 'A' } }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const edges = registry.get(graph.edges('parent'));
+        expect(edges[Graph.relationKey('child')] ?? []).to.include('parent/child');
+        expect(edges[Graph.relationKey('action')] ?? []).to.include('parent/act1');
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(1);
+        expect(actions[0].id).to.equal('parent/act1');
+        const connections = registry.get(graph.connections('parent', 'child'));
+        expect(connections).has.length(1);
+        expect(connections[0].id).to.equal('parent/child');
+      });
+
+      test('actions appear when extension registered after expand', async ({ expect }) => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+        const writableGraph = graph as Graph.WritableGraph;
+
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        expect(registry.get(graph.actions('parent'))).to.have.length(0);
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'late-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            actions: (node, get) =>
+              Effect.succeed([{ id: 'late-act', data: () => Effect.void, properties: { label: 'Late' } }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+        await GraphBuilder.flush(builder);
+
+        const edges = registry.get(graph.edges('parent'));
+        expect(edges[Graph.relationKey('action')] ?? []).to.include('parent/late-act');
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(1);
+        expect(actions[0].id).to.equal('parent/late-act');
+      });
+
+      test('_actionContext captures and provides services to action execution', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        // Define a test service using Context.GenericTag pattern.
+        interface TestServiceInterface {
+          getValue(): number;
+        }
+        const TestService = Context.GenericTag<TestServiceInterface>('TestService');
+
+        // Track whether the action was executed with the correct context.
+        let executionResult: number | null = null;
+
+        // Create extension with service requirement.
+        // Note: The actions callback must USE the service for R to be inferred correctly.
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            actions: (node, get) =>
+              // Use TestService in the callback to include it in R.
+              Effect.gen(function* () {
+                const service = yield* TestService;
+                return [
+                  {
+                    id: 'test-action',
+                    data: () =>
+                      Effect.gen(function* () {
+                        // Action can use the same service from captured context.
+                        const svc = yield* TestService;
+                        executionResult = svc.getValue();
+                      }).pipe(Effect.asVoid),
+                    properties: { label: `Test ${service.getValue()}` },
+                  },
+                ];
+              }),
+          }).pipe(Effect.provideService(TestService, { getValue: () => 42 })),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(1);
+
+        // Verify _actionContext is captured.
+        const action = actions[0] as Node.Action;
+        expect(action._actionContext).to.not.be.undefined;
+
+        // Execute the action with the captured context.
+        const actionEffect = action.data();
+        const effectWithContext = action._actionContext
+          ? actionEffect.pipe(Effect.provide(action._actionContext))
+          : actionEffect;
+
+        Effect.runSync(effectWithContext);
+
+        // Verify the service was accessible during execution.
+        expect(executionResult).to.equal(42);
+      });
+
+      test('works with resolver', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            resolver: (id, get) => Effect.succeed({ id, type: EXAMPLE_TYPE, properties: {}, data: 'resolved' }),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+        await Graph.initialize(graph, EXAMPLE_ID);
+
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node).to.not.be.null;
+        expect(node?.id).to.equal(EXAMPLE_ID);
+        expect(node?.data).to.equal('resolved');
+      });
+
+      test('works with connector and actions together', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.succeed([{ id: 'child', type: EXAMPLE_TYPE, data: node.data }]),
+            actions: (node, get) =>
+              Effect.succeed([
+                {
+                  id: 'test-action',
+                  data: () => Effect.void,
+                  properties: { label: 'Test' },
+                },
+              ]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const connections = registry.get(graph.connections('parent', 'child'));
+        // Should have both the child node and the action node.
+        expect(connections.length).to.be.greaterThanOrEqual(1);
+        const childNode = connections.find((n) => n.id === 'parent/child');
+        expect(childNode).to.not.be.undefined;
+        expect(childNode?.data).to.equal('test');
+
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(1);
+        expect(actions[0].id).to.equal('parent/test-action');
+      });
+
+      test('works with reactive connector using get context', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const state = Atom.make('initial');
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'test-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.succeed([{ id: 'child', type: EXAMPLE_TYPE, data: get(state) }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        {
+          const connections = registry.get(graph.connections('parent', 'child'));
+          expect(connections).has.length(1);
+          expect(connections[0].data).to.equal('initial');
+        }
+
+        registry.set(state, 'updated');
+        await GraphBuilder.flush(builder);
+
+        {
+          const connections = registry.get(graph.connections('parent', 'child'));
+          expect(connections).has.length(1);
+          expect(connections[0].data).to.equal('updated');
+        }
+      });
+    });
+
+    describe('extension error handling', () => {
+      test('connector failure is caught and logged, returns empty array', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'failing-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.fail(new Error('Connector failed intentionally')),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+
+        // Should not throw, error is caught internally.
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        // Should return empty connections since the connector failed.
+        const connections = registry.get(graph.connections('parent', 'child'));
+        expect(connections).has.length(0);
+      });
+
+      test('actions failure is caught and logged, returns empty array', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'failing-actions-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            actions: (node, get) => Effect.fail(new Error('Actions failed intentionally')),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+
+        // Should not throw, error is caught internally.
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        // Should return empty actions since the actions callback failed.
+        const actions = registry.get(graph.actions('parent'));
+        expect(actions).has.length(0);
+      });
+
+      test('resolver failure is caught and logged, returns null', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'failing-resolver-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            resolver: (id, get) => Effect.fail(new Error('Resolver failed intentionally')),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        // Should not throw, error is caught internally.
+        await Graph.initialize(graph, EXAMPLE_ID);
+
+        // Should return null/none since the resolver failed.
+        const node = Graph.getNode(graph, EXAMPLE_ID).pipe(Option.getOrNull);
+        expect(node).to.be.null;
+      });
+
+      test('failing extension does not affect other extensions', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        // Add a failing extension.
+        const failingExtensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'failing-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) => Effect.fail(new Error('This one fails')),
+          }),
+        );
+
+        // Add a working extension.
+        const workingExtensions = Effect.runSync(
+          GraphBuilder.createExtension({
+            id: 'working-extension',
+            match: NodeMatcher.whenNodeType(EXAMPLE_TYPE),
+            connector: (node, get) =>
+              Effect.succeed([{ id: 'child-from-working', type: EXAMPLE_TYPE, data: 'success' }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, failingExtensions);
+        GraphBuilder.addExtension(builder, workingExtensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: 'test' });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        // The working extension should still produce its node.
+        const connections = registry.get(graph.connections('parent', 'child'));
+        expect(connections).has.length(1);
+        expect(connections[0].id).to.equal('parent/child-from-working');
+        expect(connections[0].data).to.equal('success');
+      });
+    });
+
+    describe('createTypeExtension', () => {
+      test('creates extension matching by schema type with inferred object type', async () => {
+        const registry = Registry.make();
+        const builder = GraphBuilder.make({ registry });
+        const graph = builder.graph;
+
+        const extensions = Effect.runSync(
+          GraphBuilder.createTypeExtension({
+            id: 'type-extension',
+            type: TestSchema.Person,
+            connector: (object) => Effect.succeed([{ id: 'child', type: EXAMPLE_TYPE, data: object }]),
+          }),
+        );
+
+        GraphBuilder.addExtension(builder, extensions);
+
+        const writableGraph = graph as Graph.WritableGraph;
+        const testObject = Obj.make(TestSchema.Person, { name: 'Test' });
+        Graph.addNode(writableGraph, { id: 'parent', type: EXAMPLE_TYPE, properties: {}, data: testObject });
+        Graph.expand(graph, 'parent', 'child');
+        await GraphBuilder.flush(builder);
+
+        const connections = registry.get(graph.connections('parent', 'child'));
+        expect(connections).has.length(1);
+        expect(connections[0].id).to.equal('parent/child');
+        expect(connections[0].data).to.equal(testObject);
+      });
+    });
+  });
+  describe('path-based ID qualification', () => {
+    test('rejects segment IDs containing slash', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'bad-connector',
+          connector: () => Atom.make([{ id: 'foo/bar', type: EXAMPLE_TYPE, data: null }]),
+        }),
+      );
+
+      expect(() => Graph.expand(builder.graph, Node.RootId, 'child')).toThrow(/must not contain/);
+    });
+
+    test('multi-level path qualification', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
+          id: 'level1',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [{ id: 'A', type: EXAMPLE_TYPE, data: 'a' }]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+        GraphBuilder.createExtensionRaw({
+          id: 'level2',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root/A'),
+                Option.map(() => [{ id: 'B', type: EXAMPLE_TYPE, data: 'b' }]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+      ]);
+
+      const graph = builder.graph;
+
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      const level1 = registry.get(graph.connections(Node.RootId, 'child'));
+      expect(level1).has.length(1);
+      expect(level1[0].id).to.equal('root/A');
+
+      Graph.expand(graph, 'root/A', 'child');
+      await GraphBuilder.flush(builder);
+
+      const level2 = registry.get(graph.connections('root/A', 'child'));
+      expect(level2).has.length(1);
+      expect(level2[0].id).to.equal('root/A/B');
+    });
+
+    test('inline nodes are recursively qualified', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'inline-connector',
+          connector: () =>
+            Atom.make([
+              {
+                id: 'parent-node',
+                type: EXAMPLE_TYPE,
+                data: null,
+                nodes: [
+                  {
+                    id: 'inline-child',
+                    type: EXAMPLE_TYPE,
+                    data: null,
+                    nodes: [{ id: 'deep-child', type: EXAMPLE_TYPE, data: null }],
+                  },
+                ],
+              },
+            ]),
+        }),
+      );
+
+      const graph = builder.graph;
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      const connections = registry.get(graph.connections(Node.RootId, 'child'));
+      expect(connections).has.length(1);
+      expect(connections[0].id).to.equal('root/parent-node');
+
+      const inlineNode = Graph.getNode(graph, 'root/parent-node/inline-child').pipe(Option.getOrNull);
+      expect(inlineNode).to.not.be.null;
+      expect(inlineNode?.id).to.equal('root/parent-node/inline-child');
+
+      const deepNode = Graph.getNode(graph, 'root/parent-node/inline-child/deep-child').pipe(Option.getOrNull);
+      expect(deepNode).to.not.be.null;
+      expect(deepNode?.id).to.equal('root/parent-node/inline-child/deep-child');
+    });
+
+    test('constant connector produces distinct nodes under different parents', async () => {
+      const registry = Registry.make();
+      const builder = GraphBuilder.make({ registry });
+
+      GraphBuilder.addExtension(builder, [
+        GraphBuilder.createExtensionRaw({
+          id: 'parents',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [
+                  { id: 'A', type: EXAMPLE_TYPE, data: 'a' },
+                  { id: 'B', type: EXAMPLE_TYPE, data: 'b' },
+                ]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+        GraphBuilder.createExtensionRaw({
+          id: 'constant-child',
+          connector: () => Atom.make([{ id: 'shared', type: EXAMPLE_TYPE, data: 'constant' }]),
+        }),
+      ]);
+
+      const graph = builder.graph;
+
+      Graph.expand(graph, Node.RootId, 'child');
+      await GraphBuilder.flush(builder);
+
+      Graph.expand(graph, 'root/A', 'child');
+      Graph.expand(graph, 'root/B', 'child');
+      await GraphBuilder.flush(builder);
+
+      const childrenOfA = registry.get(graph.connections('root/A', 'child'));
+      const childrenOfB = registry.get(graph.connections('root/B', 'child'));
+
+      expect(childrenOfA).has.length(1);
+      expect(childrenOfB).has.length(1);
+      expect(childrenOfA[0].id).to.equal('root/A/shared');
+      expect(childrenOfB[0].id).to.equal('root/B/shared');
+
+      const nodeA = Graph.getNode(graph, 'root/A/shared').pipe(Option.getOrNull);
+      const nodeB = Graph.getNode(graph, 'root/B/shared').pipe(Option.getOrNull);
+      expect(nodeA).to.not.be.null;
+      expect(nodeB).to.not.be.null;
+      expect(nodeA?.id).to.not.equal(nodeB?.id);
+    });
+
+    test('explore qualifies node IDs', async () => {
+      const builder = GraphBuilder.make();
+      GraphBuilder.addExtension(
+        builder,
+        GraphBuilder.createExtensionRaw({
+          id: 'connector',
+          connector: (node) =>
+            Atom.make((get) =>
+              Function.pipe(
+                get(node),
+                Option.filter((n) => n.id === 'root'),
+                Option.map(() => [
+                  { id: 'first', type: EXAMPLE_TYPE, data: 1 },
+                  { id: 'second', type: EXAMPLE_TYPE, data: 2 },
+                ]),
+                Option.getOrElse(() => []),
+              ),
+            ),
+        }),
+      );
+
+      const visited: Array<{ id: string; path: string[] }> = [];
+      await GraphBuilder.explore(builder, {
+        relation: 'child',
+        visitor: (node, path) => {
+          visited.push({ id: node.id, path });
+        },
+      });
+
+      expect(visited).has.length(3);
+      expect(visited[0].id).to.equal('root');
+      expect(visited[1].id).to.equal('root/first');
+      expect(visited[2].id).to.equal('root/second');
+    });
+  });
 });