@dxos/app-graph 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/dist/lib/node-esm/index.mjs

@@ -42,6 +42,8 @@ __export(graph_exports, {
   getRoot: () => getRoot,
   initialize: () => initialize,
   make: () => make,
+  relationFromKey: () => relationFromKey,
+  relationKey: () => relationKey,
   removeEdge: () => removeEdge,
   removeEdges: () => removeEdges,
   removeNode: () => removeNode,
@@ -58,7 +60,7 @@ import * as Pipeable from "effect/Pipeable";
 import * as Record from "effect/Record";
 import { Event, Trigger } from "@dxos/async";
 import { todo } from "@dxos/debug";
-import { invariant } from "@dxos/invariant";
+import { invariant as invariant2 } from "@dxos/invariant";
 import { log } from "@dxos/log";
 import { isNonNullable } from "@dxos/util";
 
@@ -70,29 +72,79 @@ __export(node_exports, {
   RootId: () => RootId,
   RootType: () => RootType,
   actionGroupSymbol: () => actionGroupSymbol,
+  actionRelation: () => actionRelation,
+  childRelation: () => childRelation,
   isAction: () => isAction,
   isActionGroup: () => isActionGroup,
   isActionLike: () => isActionLike,
-  isGraphNode: () => isGraphNode
+  isGraphNode: () => isGraphNode,
+  relation: () => relation
 });
 var RootId = "root";
-var RootType = "dxos.org/type/GraphRoot";
-var ActionType = "dxos.org/type/GraphAction";
-var ActionGroupType = "dxos.org/type/GraphActionGroup";
+var RootType = "org.dxos.type.graph-root";
+var ActionType = "org.dxos.type.graph-action";
+var ActionGroupType = "org.dxos.type.graph-action-group";
+var relation = (kind, direction = "outbound") => ({
+  kind,
+  direction
+});
+var childRelation = (direction = "outbound") => relation("child", direction);
+var actionRelation = (direction = "outbound") => relation("action", direction);
 var isGraphNode = (data) => data && typeof data === "object" && "id" in data && "properties" in data && data.properties ? typeof data.properties === "object" && "data" in data : false;
 var isAction = (data) => isGraphNode(data) ? typeof data.data === "function" && data.type === ActionType : false;
-var actionGroupSymbol = Symbol("ActionGroup");
+var actionGroupSymbol = /* @__PURE__ */ Symbol("ActionGroup");
 var isActionGroup = (data) => isGraphNode(data) ? data.data === actionGroupSymbol && data.type === ActionGroupType : false;
 var isActionLike = (data) => isAction(data) || isActionGroup(data);
 
+// src/util.ts
+import { invariant } from "@dxos/invariant";
+var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-graph/src/util.ts";
+var Separators = {
+  primary: "
",
+  secondary: "",
+  path: "/"
+};
+var normalizeRelation = (relation2) => relation2 == null ? childRelation() : typeof relation2 === "string" ? relation(relation2) : relation2;
+var shallowEqual = (a, b) => {
+  if (a === b) return true;
+  if (a == null || b == null || typeof a !== "object" || typeof b !== "object") return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  return keysA.every((k) => a[k] === b[k]);
+};
+var nodeArgsUnchanged = (prev, next) => {
+  if (prev.length !== next.length) {
+    return false;
+  }
+  return prev.every((prevNode, idx) => {
+    const nextNode = next[idx];
+    return prevNode.id === nextNode.id && prevNode.type === nextNode.type && shallowEqual(prevNode.data, nextNode.data) && shallowEqual(prevNode.properties, nextNode.properties);
+  });
+};
+var qualifyId = (parentId, segmentId) => `${parentId}${Separators.path}${segmentId}`;
+var validateSegmentId = (id) => {
+  invariant(!id.includes(Separators.path), `Node segment ID must not contain '${Separators.path}': ${id}`, {
+    F: __dxlog_file,
+    L: 70,
+    S: void 0,
+    A: [
+      "!id.includes(Separators.path)",
+      "`Node segment ID must not contain '${Separators.path}': ${id}`"
+    ]
+  });
+};
+
 // src/graph.ts
-var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph.ts";
-var graphSymbol = Symbol("graph");
+var __dxlog_file2 = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph.ts";
+var graphSymbol = /* @__PURE__ */ Symbol("graph");
 var getGraph = (node) => {
   const graph = node[graphSymbol];
-  invariant(graph, "Node is not associated with a graph.", {
-    F: __dxlog_file,
-    L: 32,
+  invariant2(graph, "Node is not associated with a graph.", {
+    F: __dxlog_file2,
+    L: 33,
     S: void 0,
     A: [
       "graph",
@@ -101,8 +153,8 @@ var getGraph = (node) => {
   });
   return graph;
 };
-var GraphTypeId = Symbol.for("@dxos/app-graph/Graph");
-var GraphKind = Symbol.for("@dxos/app-graph/GraphKind");
+var GraphTypeId = /* @__PURE__ */ Symbol.for("@dxos/app-graph/Graph");
+var GraphKind = /* @__PURE__ */ Symbol.for("@dxos/app-graph/GraphKind");
 var GraphImpl = class {
   [GraphTypeId] = GraphTypeId;
   [GraphKind] = "writable";
@@ -115,6 +167,7 @@ var GraphImpl = class {
   _onRemoveNode;
   _registry;
   _expanded = Record.empty();
+  _pendingExpands = /* @__PURE__ */ new Set();
   _initialized = Record.empty();
   _initialEdges = Record.empty();
   _initialNodes = Record.fromEntries([
@@ -136,9 +189,9 @@ var GraphImpl = class {
   _nodeOrThrow = Atom2.family((id) => {
     return Atom2.make((get2) => {
       const node = get2(this._node(id));
-      invariant(Option.isSome(node), `Node not available: ${id}`, {
-        F: __dxlog_file,
-        L: 174,
+      invariant2(Option.isSome(node), `Node not available: ${id}`, {
+        F: __dxlog_file2,
+        L: 172,
         S: this,
         A: [
           "Option.isSome(node)",
@@ -149,30 +202,33 @@ var GraphImpl = class {
     });
   });
   _edges = Atom2.family((id) => {
-    const initial = Record.get(this._initialEdges, id).pipe(Option.getOrElse(() => ({
-      inbound: [],
-      outbound: []
-    })));
+    const initial = Record.get(this._initialEdges, id).pipe(Option.getOrElse(() => ({})));
     return Atom2.make(initial).pipe(Atom2.keepAlive, Atom2.withLabel(`graph:edges:${id}`));
   });
   // NOTE: Currently the argument to the family needs to be referentially stable for the atom to be referentially stable.
   // TODO(wittjosiah): Atom feature request, support for something akin to `ComplexMap` to allow for complex arguments.
   _connections = Atom2.family((key) => {
     return Atom2.make((get2) => {
-      const [id, relation] = key.split("$");
+      if (!key || key.indexOf(Separators.primary) <= 0) {
+        return [];
+      }
+      const { id, relation: relation2 } = relationFromConnectionKey(key);
       const edges = get2(this._edges(id));
-      return edges[relation].map((id2) => get2(this._node(id2))).filter(Option.isSome).map((o) => o.value);
+      return (edges[relationKey(relation2)] ?? []).map((id2) => get2(this._node(id2))).filter(Option.isSome).map((o) => o.value);
     }).pipe(Atom2.withLabel(`graph:connections:${key}`));
   });
   _actions = Atom2.family((id) => {
     return Atom2.make((get2) => {
-      return get2(this._connections(`${id}$outbound`)).filter((node) => node.type === ActionType || node.type === ActionGroupType);
+      if (!id) {
+        return [];
+      }
+      return get2(this._connections(connectionKey(id, actionRelation())));
     }).pipe(Atom2.withLabel(`graph:actions:${id}`));
   });
   _json = Atom2.family((id) => {
     return Atom2.make((get2) => {
       const toJSON2 = (node, seen = []) => {
-        const nodes = get2(this._connections(`${node.id}$outbound`));
+        const nodes = get2(this._connections(connectionKey(node.id, "child")));
         const obj = {
           id: node.id,
           type: node.type
@@ -220,8 +276,8 @@ var GraphImpl = class {
   nodeOrThrow(id) {
     return nodeOrThrowImpl(this, id);
   }
-  connections(id, relation = "outbound") {
-    return connectionsImpl(this, id, relation);
+  connections(id, relation2) {
+    return connectionsImpl(this, id, relation2);
   }
   actions(id) {
     return actionsImpl(this, id);
@@ -258,9 +314,9 @@ var nodeOrThrowImpl = (graph, id) => {
   const internal = getInternal(graph);
   return internal._nodeOrThrow(id);
 };
-var connectionsImpl = (graph, id, relation = "outbound") => {
+var connectionsImpl = (graph, id, relation2) => {
   const internal = getInternal(graph);
-  return internal._connections(`${id}$${relation}`);
+  return internal._connections(connectionKey(id, relation2));
 };
 var actionsImpl = (graph, id) => {
   const internal = getInternal(graph);
@@ -299,19 +355,28 @@ function getNodeOrThrow(graphOrId, id) {
 function getRoot(graph) {
   return getNodeOrThrowImpl(graph, RootId);
 }
-var getConnectionsImpl = (graph, id, relation = "outbound") => {
+var getConnectionsImpl = (graph, id, relation2) => {
   const internal = getInternal(graph);
-  return internal._registry.get(connectionsImpl(graph, id, relation));
+  return internal._registry.get(connectionsImpl(graph, id, relation2));
 };
-function getConnections(graphOrId, idOrRelation, relation) {
+function getConnections(graphOrId, idOrRelation, relation2) {
   if (typeof graphOrId === "string") {
     const id = graphOrId;
-    const rel = (typeof idOrRelation === "string" ? "outbound" : idOrRelation) ?? "outbound";
+    const rel = idOrRelation;
     return (graph) => getConnectionsImpl(graph, id, rel);
   } else {
     const graph = graphOrId;
     const id = idOrRelation;
-    const rel = relation ?? "outbound";
+    invariant2(relation2 !== void 0, "Relation is required.", {
+      F: __dxlog_file2,
+      L: 446,
+      S: this,
+      A: [
+        "relation !== undefined",
+        "'Relation is required.'"
+      ]
+    });
+    const rel = relation2;
     return getConnectionsImpl(graph, id, rel);
   }
 }
@@ -342,7 +407,7 @@ function getEdges(graphOrId, id) {
   }
 }
 var traverseImpl = (graph, options, path = []) => {
-  const { visitor, source = RootId, relation = "outbound" } = options;
+  const { visitor, source = RootId, relation: relation2 } = options;
   if (path.includes(source)) {
     return;
   }
@@ -354,14 +419,25 @@ var traverseImpl = (graph, options, path = []) => {
   if (shouldContinue === false) {
     return;
   }
-  Object.values(getConnections(graph, source, relation)).forEach((child) => traverseImpl(graph, {
-    source: child.id,
-    relation,
-    visitor
-  }, [
-    ...path,
-    source
-  ]));
+  const relations = Array.isArray(relation2) ? relation2 : [
+    relation2
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const rel of relations) {
+    for (const connected of getConnections(graph, source, rel)) {
+      if (!seen.has(connected.id)) {
+        seen.add(connected.id);
+        traverseImpl(graph, {
+          source: connected.id,
+          relation: relation2,
+          visitor
+        }, [
+          ...path,
+          source
+        ]);
+      }
+    }
+  }
 };
 function traverse(graphOrOptions, optionsOrPath, path) {
   if (typeof graphOrOptions === "object" && "visitor" in graphOrOptions) {
@@ -380,6 +456,7 @@ var getPathImpl = (graph, params) => {
     let found = Option.none();
     traverseImpl(graph, {
       source: node.id,
+      relation: "child",
       visitor: (node2, path) => {
         if (Option.isSome(found)) {
           return false;
@@ -436,14 +513,14 @@ var initializeImpl = async (graph, id) => {
     id,
     initialized
   }, {
-    F: __dxlog_file,
-    L: 661,
+    F: __dxlog_file2,
+    L: 668,
     S: void 0,
     C: (f, a) => f(...a)
   });
   if (!initialized) {
-    await internal._onInitialize?.(id);
     Record.set(internal._initialized, id, true);
+    await internal._onInitialize?.(id);
   }
   return graph;
 };
@@ -456,61 +533,93 @@ function initialize(graphOrId, id) {
     return initializeImpl(graph, id);
   }
 }
-var expandImpl = (graph, id, relation = "outbound") => {
+var expandImpl = (graph, id, relation2) => {
   const internal = getInternal(graph);
-  const key = `${id}$${relation}`;
+  const normalizedRelation = normalizeRelation(relation2);
+  const key = `${id}${Separators.primary}${relationKey(normalizedRelation)}`;
+  const nodeOpt = internal._registry.get(internal._node(id));
+  if (Option.isNone(nodeOpt)) {
+    internal._pendingExpands.add(key);
+    log("expand", {
+      key,
+      deferred: true
+    }, {
+      F: __dxlog_file2,
+      L: 714,
+      S: void 0,
+      C: (f, a) => f(...a)
+    });
+    return graph;
+  }
   const expanded = Record.get(internal._expanded, key).pipe(Option.getOrElse(() => false));
   log("expand", {
     key,
     expanded
   }, {
-    F: __dxlog_file,
-    L: 702,
+    F: __dxlog_file2,
+    L: 719,
     S: void 0,
     C: (f, a) => f(...a)
   });
   if (!expanded) {
-    internal._onExpand?.(id, relation);
     Record.set(internal._expanded, key, true);
+    internal._onExpand?.(id, normalizedRelation);
   }
   return graph;
 };
-function expand(graphOrId, idOrRelation, relation) {
+function expand(graphOrId, idOrRelation, relation2) {
   if (typeof graphOrId === "string") {
     const id = graphOrId;
-    const rel = (typeof idOrRelation === "string" ? "outbound" : idOrRelation) ?? "outbound";
+    const rel = idOrRelation;
     return (graph) => expandImpl(graph, id, rel);
   } else {
     const graph = graphOrId;
     const id = idOrRelation;
-    const rel = relation ?? "outbound";
+    invariant2(relation2 !== void 0, "Relation is required.", {
+      F: __dxlog_file2,
+      L: 755,
+      S: this,
+      A: [
+        "relation !== undefined",
+        "'Relation is required.'"
+      ]
+    });
+    const rel = relation2;
     return expandImpl(graph, id, rel);
   }
 }
-var sortEdgesImpl = (graph, id, relation, order) => {
+var sortEdgesImpl = (graph, id, relation2, order) => {
   const internal = getInternal(graph);
   const edgesAtom = internal._edges(id);
   const edges = internal._registry.get(edgesAtom);
-  const unsorted = edges[relation].filter((id2) => !order.includes(id2)) ?? [];
-  const sorted = order.filter((id2) => edges[relation].includes(id2)) ?? [];
-  edges[relation].splice(0, edges[relation].length, ...[
+  const relationId = relationKey(relation2);
+  const current = edges[relationId] ?? [];
+  const unsorted = current.filter((id2) => !order.includes(id2));
+  const sorted = order.filter((id2) => current.includes(id2));
+  const newOrder = [
     ...sorted,
     ...unsorted
-  ]);
-  internal._registry.set(edgesAtom, edges);
+  ];
+  if (newOrder.length === current.length && newOrder.every((id2, i) => id2 === current[i])) {
+    return graph;
+  }
+  internal._registry.set(edgesAtom, {
+    ...edges,
+    [relationId]: newOrder
+  });
   return graph;
 };
 function sortEdges(graphOrId, idOrRelation, relationOrOrder, order) {
   if (typeof graphOrId === "string") {
     const id = graphOrId;
-    const relation = idOrRelation;
+    const relation2 = idOrRelation;
     const order2 = relationOrOrder;
-    return (graph) => sortEdgesImpl(graph, id, relation, order2);
+    return (graph) => sortEdgesImpl(graph, id, relation2, order2);
   } else {
     const graph = graphOrId;
     const id = idOrRelation;
-    const relation = relationOrOrder;
-    return sortEdgesImpl(graph, id, relation, order);
+    const relation2 = relationOrOrder;
+    return sortEdgesImpl(graph, id, relation2, order);
   }
 }
 var addNodesImpl = (graph, nodes) => {
@@ -536,7 +645,7 @@ var addNodeImpl = (graph, nodeArg) => {
   Option.match(existingNode, {
     onSome: (existing) => {
       const typeChanged = existing.type !== type;
-      const dataChanged = existing.data !== data;
+      const dataChanged = !shallowEqual(existing.data, data);
       const propertiesChanged = Object.keys(properties).some((key) => existing.properties[key] !== properties[key]);
       log("existing node", {
         id,
@@ -544,8 +653,8 @@ var addNodeImpl = (graph, nodeArg) => {
         dataChanged,
         propertiesChanged
       }, {
-        F: __dxlog_file,
-        L: 847,
+        F: __dxlog_file2,
+        L: 877,
         S: void 0,
         C: (f, a) => f(...a)
       });
@@ -556,8 +665,8 @@ var addNodeImpl = (graph, nodeArg) => {
           data,
           properties
         }, {
-          F: __dxlog_file,
-          L: 854,
+          F: __dxlog_file2,
+          L: 884,
           S: void 0,
           C: (f, a) => f(...a)
         });
@@ -585,8 +694,8 @@ var addNodeImpl = (graph, nodeArg) => {
         data,
         properties
       }, {
-        F: __dxlog_file,
-        L: 867,
+        F: __dxlog_file2,
+        L: 897,
         S: void 0,
         C: (f, a) => f(...a)
       });
@@ -602,13 +711,24 @@ var addNodeImpl = (graph, nodeArg) => {
         id,
         node: newNode
       });
+      const prefix = `${id}${Separators.primary}`;
+      const toApply = [
+        ...internal._pendingExpands
+      ].filter((k) => k.startsWith(prefix));
+      for (const pendingKey of toApply) {
+        internal._pendingExpands.delete(pendingKey);
+        const relation2 = relationFromKey(pendingKey.slice(prefix.length));
+        Record.set(internal._expanded, pendingKey, true);
+        internal._onExpand?.(id, relation2);
+      }
     }
   });
   if (nodes) {
     addNodesImpl(graph, nodes);
     const _edges = nodes.map((node) => ({
       source: id,
-      target: node.id
+      target: node.id,
+      relation: "child"
     }));
     addEdgesImpl(graph, _edges);
   }
@@ -653,17 +773,27 @@ var removeNodeImpl = (graph, id, edges = false) => {
     node: Option.none()
   });
   if (edges) {
-    const { inbound, outbound } = internal._registry.get(internal._edges(id));
-    const edgesToRemove = [
-      ...inbound.map((source) => ({
-        source,
-        target: id
-      })),
-      ...outbound.map((target) => ({
-        source: id,
-        target
-      }))
-    ];
+    const nodeEdges = internal._registry.get(internal._edges(id));
+    const edgesToRemove = [];
+    for (const [relationKeyValue, relatedIds] of Object.entries(nodeEdges)) {
+      const relation2 = relationFromKey(relationKeyValue);
+      const isInboundRelation = relation2.direction === "inbound";
+      for (const relatedId of relatedIds) {
+        if (isInboundRelation) {
+          edgesToRemove.push({
+            source: relatedId,
+            target: id,
+            relation: inverseRelation(relation2)
+          });
+        } else {
+          edgesToRemove.push({
+            source: id,
+            target: relatedId,
+            relation: relation2
+          });
+        }
+      }
+    }
     removeEdgesImpl(graph, edgesToRemove);
   }
   internal._onRemoveNode?.(id);
@@ -697,45 +827,53 @@ function addEdges(graphOrEdges, edges) {
   }
 }
 var addEdgeImpl = (graph, edgeArg) => {
+  const relation2 = normalizeRelation(edgeArg.relation);
+  const relationId = relationKey(relation2);
+  const inverse = inverseRelation(relation2);
+  const inverseId = relationKey(inverse);
   const internal = getInternal(graph);
   const sourceAtom = internal._edges(edgeArg.source);
   const source = internal._registry.get(sourceAtom);
-  if (!source.outbound.includes(edgeArg.target)) {
-    log("add outbound edge", {
+  const sourceList = source[relationId] ?? [];
+  if (!sourceList.includes(edgeArg.target)) {
+    log("add edge", {
       source: edgeArg.source,
-      target: edgeArg.target
+      target: edgeArg.target,
+      relation: relationId
     }, {
-      F: __dxlog_file,
-      L: 1026,
+      F: __dxlog_file2,
+      L: 1081,
       S: void 0,
       C: (f, a) => f(...a)
     });
     internal._registry.set(sourceAtom, {
-      inbound: source.inbound,
-      outbound: [
-        ...source.outbound,
+      ...source,
+      [relationId]: [
+        ...sourceList,
         edgeArg.target
       ]
     });
   }
   const targetAtom = internal._edges(edgeArg.target);
   const target = internal._registry.get(targetAtom);
-  if (!target.inbound.includes(edgeArg.source)) {
-    log("add inbound edge", {
+  const targetList = target[inverseId] ?? [];
+  if (!targetList.includes(edgeArg.source)) {
+    log("add inverse edge", {
       source: edgeArg.source,
-      target: edgeArg.target
+      target: edgeArg.target,
+      relation: inverseId
     }, {
-      F: __dxlog_file,
-      L: 1039,
+      F: __dxlog_file2,
+      L: 1089,
       S: void 0,
       C: (f, a) => f(...a)
     });
     internal._registry.set(targetAtom, {
-      inbound: [
-        ...target.inbound,
+      ...target,
+      [inverseId]: [
+        ...targetList,
         edgeArg.source
-      ],
-      outbound: target.outbound
+      ]
     });
   }
   return graph;
@@ -768,32 +906,39 @@ function removeEdges(graphOrEdges, edgesOrRemoveOrphans, removeOrphans) {
   }
 }
 var removeEdgeImpl = (graph, edgeArg, removeOrphans = false) => {
+  const relation2 = normalizeRelation(edgeArg.relation);
+  const relationId = relationKey(relation2);
+  const inverse = inverseRelation(relation2);
+  const inverseId = relationKey(inverse);
   const internal = getInternal(graph);
   const sourceAtom = internal._edges(edgeArg.source);
   const source = internal._registry.get(sourceAtom);
-  if (source.outbound.includes(edgeArg.target)) {
+  const sourceList = source[relationId] ?? [];
+  if (sourceList.includes(edgeArg.target)) {
     internal._registry.set(sourceAtom, {
-      inbound: source.inbound,
-      outbound: source.outbound.filter((id) => id !== edgeArg.target)
+      ...source,
+      [relationId]: sourceList.filter((id) => id !== edgeArg.target)
     });
   }
   const targetAtom = internal._edges(edgeArg.target);
   const target = internal._registry.get(targetAtom);
-  if (target.inbound.includes(edgeArg.source)) {
+  const targetList = target[inverseId] ?? [];
+  if (targetList.includes(edgeArg.source)) {
     internal._registry.set(targetAtom, {
-      inbound: target.inbound.filter((id) => id !== edgeArg.source),
-      outbound: target.outbound
+      ...target,
+      [inverseId]: targetList.filter((id) => id !== edgeArg.source)
     });
   }
   if (removeOrphans) {
-    const source2 = internal._registry.get(sourceAtom);
-    const target2 = internal._registry.get(targetAtom);
-    if (source2.outbound.length === 0 && source2.inbound.length === 0 && edgeArg.source !== RootId) {
+    const sourceAfter = internal._registry.get(sourceAtom);
+    const targetAfter = internal._registry.get(targetAtom);
+    const isEmpty = (edges) => Object.values(edges).every((ids) => ids.length === 0);
+    if (isEmpty(sourceAfter) && edgeArg.source !== RootId) {
       removeNodesImpl(graph, [
         edgeArg.source
       ]);
     }
-    if (target2.outbound.length === 0 && target2.inbound.length === 0 && edgeArg.target !== RootId) {
+    if (isEmpty(targetAfter) && edgeArg.target !== RootId) {
       removeNodesImpl(graph, [
         edgeArg.target
       ]);
@@ -816,6 +961,57 @@ function removeEdge(graphOrEdgeArg, edgeArgOrRemoveOrphans, removeOrphans) {
 var make = (params) => {
   return new GraphImpl(params);
 };
+var relationKey = (relation2) => {
+  const normalized = normalizeRelation(relation2);
+  return `${normalized.kind}${Separators.secondary}${normalized.direction}`;
+};
+var relationFromKey = (encoded) => {
+  const separatorIndex = encoded.lastIndexOf(Separators.secondary);
+  invariant2(separatorIndex > 0 && separatorIndex < encoded.length - 1, `Invalid relation key: ${encoded}`, {
+    F: __dxlog_file2,
+    L: 1234,
+    S: void 0,
+    A: [
+      "separatorIndex > 0 && separatorIndex < encoded.length - 1",
+      "`Invalid relation key: ${encoded}`"
+    ]
+  });
+  const kind = encoded.slice(0, separatorIndex);
+  const directionRaw = encoded.slice(separatorIndex + 1);
+  invariant2(directionRaw === "outbound" || directionRaw === "inbound", `Invalid relation direction: ${directionRaw}`, {
+    F: __dxlog_file2,
+    L: 1237,
+    S: void 0,
+    A: [
+      "directionRaw === 'outbound' || directionRaw === 'inbound'",
+      "`Invalid relation direction: ${directionRaw}`"
+    ]
+  });
+  return relation(kind, directionRaw);
+};
+var connectionKey = (id, relation2) => `${id}${Separators.primary}${relationKey(relation2)}`;
+var relationFromConnectionKey = (key) => {
+  const separatorIndex = key.indexOf(Separators.primary);
+  invariant2(separatorIndex > 0 && separatorIndex < key.length - 1, `Invalid connection key: ${key}`, {
+    F: __dxlog_file2,
+    L: 1246,
+    S: void 0,
+    A: [
+      "separatorIndex > 0 && separatorIndex < key.length - 1",
+      "`Invalid connection key: ${key}`"
+    ]
+  });
+  const id = key.slice(0, separatorIndex);
+  const encodedRelation = key.slice(separatorIndex + 1);
+  return {
+    id,
+    relation: relationFromKey(encodedRelation)
+  };
+};
+var inverseRelation = (relation2) => {
+  const normalized = normalizeRelation(relation2);
+  return relation(normalized.kind, normalized.direction === "outbound" ? "inbound" : "outbound");
+};
 
 // src/graph-builder.ts
 var graph_builder_exports = {};
@@ -829,6 +1025,7 @@ __export(graph_builder_exports, {
   destroy: () => destroy,
   explore: () => explore,
   flattenExtensions: () => flattenExtensions,
+  flush: () => flush,
   from: () => from,
   make: () => make2,
   removeExtension: () => removeExtension
@@ -840,8 +1037,9 @@ import * as Function2 from "effect/Function";
 import * as Option3 from "effect/Option";
 import * as Pipeable2 from "effect/Pipeable";
 import * as Record2 from "effect/Record";
+import { scheduleTask, yieldOrContinue } from "main-thread-scheduling";
 import { log as log2 } from "@dxos/log";
-import { byPosition, getDebugName, isNode, isNonNullable as isNonNullable2 } from "@dxos/util";
+import { byPosition, getDebugName, isNonNullable as isNonNullable2 } from "@dxos/util";
 
 // src/node-matcher.ts
 var node_matcher_exports = {};
@@ -865,18 +1063,16 @@ var whenNodeType = (type) => (node) => node.type === type ? Option2.some(node) :
 var whenEchoType = (type) => (node) => Obj.instanceOf(type, node.data) ? Option2.some(node.data) : Option2.none();
 var whenEchoObject = (node) => Obj.isObject(node.data) ? Option2.some(node.data) : Option2.none();
 var whenAll = (...matchers) => (node) => {
-  for (const matcher of matchers) {
-    const result = matcher(node);
-    if (Option2.isNone(result)) {
+  for (const candidate of matchers) {
+    if (Option2.isNone(candidate(node))) {
       return Option2.none();
     }
   }
   return Option2.some(node);
 };
 var whenAny = (...matchers) => (node) => {
-  for (const matcher of matchers) {
-    const result = matcher(node);
-    if (Option2.isSome(result)) {
+  for (const candidate of matchers) {
+    if (Option2.isSome(candidate(node))) {
       return Option2.some(node);
     }
   }
@@ -887,25 +1083,40 @@ var whenEchoObjectMatches = (node) => Obj.isObject(node.data) ? Option2.some(nod
 var whenNot = (matcher) => (node) => Option2.isNone(matcher(node)) ? Option2.some(node) : Option2.none();
 
 // src/graph-builder.ts
-var __dxlog_file2 = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph-builder.ts";
-var GraphBuilderTypeId = Symbol.for("@dxos/app-graph/GraphBuilder");
+var __dxlog_file3 = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph-builder.ts";
+var GraphBuilderTypeId = /* @__PURE__ */ Symbol.for("@dxos/app-graph/GraphBuilder");
 var GraphBuilderImpl = class {
   [GraphBuilderTypeId] = GraphBuilderTypeId;
   pipe() {
     return Pipeable2.pipeArguments(this, arguments);
   }
   // TODO(wittjosiah): Use Context.
+  /** Active subscriptions keyed by composite ID, cleaned up on node removal. */
   _subscriptions = /* @__PURE__ */ new Map();
+  /** Connector updates pending flush, keyed by connector key. */
+  _dirtyConnectors = /* @__PURE__ */ new Map();
+  /** Last-flushed node IDs per connector key, used for edge removal on update. */
+  _connectorPrevious = /* @__PURE__ */ new Map();
+  /** Last-flushed node args per connector key, used for change detection. */
+  _connectorPreviousArgs = /* @__PURE__ */ new Map();
+  /** Whether a dirty-flush task is already scheduled. */
+  _flushScheduled = false;
+  /** Resolves when the current flush completes. */
+  _flushPromise = Promise.resolve();
+  /** Registered builder extensions keyed by extension ID. */
   _extensions = Atom3.make(Record2.empty()).pipe(Atom3.keepAlive, Atom3.withLabel("graph-builder:extensions"));
+  /** Triggers signalling that a node's resolver has fired at least once. */
   _initialized = {};
+  /** Shared atom registry for reactive subscriptions. */
   _registry;
+  /** Backing graph with internal accessors for node atoms and construction. */
   _graph;
   constructor({ registry, ...params } = {}) {
     this._registry = registry ?? Registry2.make();
     const graph = make({
       ...params,
       registry: this._registry,
-      onExpand: (id, relation) => this._onExpand(id, relation),
+      onExpand: (id, relation2) => this._onExpand(id, relation2),
       onInitialize: (id) => this._onInitialize(id),
       onRemoveNode: (id) => this._onRemoveNode(id)
     });
@@ -917,6 +1128,52 @@ var GraphBuilderImpl = class {
   get extensions() {
     return this._extensions;
   }
+  /** Apply a set of node changes for a single connector key. */
+  _applyConnectorUpdate(key, nodes, previous) {
+    const { id, relation: relation2 } = relationFromConnectorKey(key);
+    const ids = nodes.map((node) => node.id);
+    const removed = previous.filter((pid) => !ids.includes(pid));
+    this._connectorPrevious.set(key, ids);
+    this._connectorPreviousArgs.set(key, nodes);
+    removeEdges(this._graph, removed.map((target) => ({
+      source: id,
+      target,
+      relation: relation2
+    })), true);
+    addNodes(this._graph, nodes);
+    addEdges(this._graph, nodes.map((node) => ({
+      source: id,
+      target: node.id,
+      relation: relation2
+    })));
+    if (ids.length > 0) {
+      const sortedIds = [
+        ...nodes
+      ].sort((a, b) => byPosition(a.properties ?? {}, b.properties ?? {})).map((n) => n.id);
+      sortEdges(this._graph, id, relation2, sortedIds);
+    }
+  }
+  _scheduleDirtyFlush() {
+    if (!this._flushScheduled) {
+      this._flushScheduled = true;
+      this._flushPromise = scheduleTask(() => {
+        this._flushScheduled = false;
+        while (this._dirtyConnectors.size > 0) {
+          const entries = [
+            ...this._dirtyConnectors.entries()
+          ];
+          this._dirtyConnectors.clear();
+          Atom3.batch(() => {
+            for (const [key, { nodes, previous }] of entries) {
+              this._applyConnectorUpdate(key, nodes, previous);
+            }
+          });
+        }
+      }, {
+        strategy: "smooth"
+      });
+    }
+  }
   _resolvers = Atom3.family((id) => {
     return Atom3.make((get2) => {
       return Function2.pipe(get2(this._extensions), Record2.values, Array2.sortBy(byPosition), Array2.map(({ resolver }) => resolver), Array2.filter(isNonNullable2), Array2.map((resolver) => get2(resolver(id))), Array2.filter(isNonNullable2), Array2.head);
@@ -924,82 +1181,77 @@ var GraphBuilderImpl = class {
   });
   _connectors = Atom3.family((key) => {
     return Atom3.make((get2) => {
-      const [id, relation] = key.split("+");
+      const { id, relation: relation2 } = relationFromConnectorKey(key);
       const node = this._graph.node(id);
-      return Function2.pipe(
-        get2(this._extensions),
-        Record2.values,
-        // TODO(wittjosiah): Sort on write rather than read.
-        Array2.sortBy(byPosition),
-        Array2.filter(({ relation: _relation = "outbound" }) => _relation === relation),
-        Array2.map(({ connector }) => connector?.(node)),
-        Array2.filter(isNonNullable2),
-        Array2.flatMap((result) => get2(result))
-      );
+      const sourceNode = Option3.getOrElse(get2(node), () => void 0);
+      if (!sourceNode) {
+        return [];
+      }
+      const extensions = Function2.pipe(get2(this._extensions), Record2.values, Array2.sortBy(byPosition), Array2.filter((ext) => relationKey(ext.relation ?? "child") === relationKey(relation2) && ext.connector != null));
+      const nodes = [];
+      for (const ext of extensions) {
+        const result = get2(ext.connector(node));
+        nodes.push(...result);
+      }
+      return nodes;
     }).pipe(Atom3.withLabel(`graph-builder:connectors:${key}`));
   });
-  _onExpand(id, relation) {
+  _onExpand(id, relation2) {
     log2("onExpand", {
       id,
-      relation,
+      relation: relation2,
       registry: getDebugName(this._registry)
     }, {
-      F: __dxlog_file2,
-      L: 176,
+      F: __dxlog_file3,
+      L: 261,
       S: this,
       C: (f, a) => f(...a)
     });
-    const connectors = this._connectors(`${id}+${relation}`);
-    let previous = [];
-    const cancel = this._registry.subscribe(connectors, (nodes) => {
+    this._expandRelation(id, relation2);
+    if (relation2.kind === "child" && relation2.direction === "outbound") {
+      expand(this._graph, id, "action");
+    }
+  }
+  _expandRelation(id, relation2) {
+    const key = connectorKey(id, relation2);
+    const connectors = this._connectors(key);
+    const cancel = this._registry.subscribe(connectors, (rawNodes) => {
+      const nodes = qualifyNodeArgs(id)(rawNodes);
+      const previous = this._connectorPrevious.get(key) ?? [];
       const ids = nodes.map((n) => n.id);
-      const removed = previous.filter((id2) => !ids.includes(id2));
-      previous = ids;
+      if (ids.length === previous.length && ids.every((nodeId, idx) => nodeId === previous[idx])) {
+        const prevArgs = this._connectorPreviousArgs.get(key);
+        if (prevArgs && nodeArgsUnchanged(prevArgs, nodes)) {
+          return;
+        }
+      }
       log2("update", {
         id,
-        relation,
-        ids,
-        removed
+        relation: relation2,
+        ids
       }, {
-        F: __dxlog_file2,
-        L: 187,
+        F: __dxlog_file3,
+        L: 288,
         S: this,
         C: (f, a) => f(...a)
       });
-      const update = () => {
-        Atom3.batch(() => {
-          removeEdges(this._graph, removed.map((target) => ({
-            source: id,
-            target
-          })), true);
-          addNodes(this._graph, nodes);
-          addEdges(this._graph, nodes.map((node) => relation === "outbound" ? {
-            source: id,
-            target: node.id
-          } : {
-            source: node.id,
-            target: id
-          }));
-          sortEdges(this._graph, id, relation, nodes.map(({ id: id2 }) => id2));
-        });
-      };
-      if (typeof requestAnimationFrame === "function") {
-        requestAnimationFrame(update);
-      } else {
-        update();
-      }
+      this._dirtyConnectors.set(key, {
+        nodes,
+        previous
+      });
+      this._scheduleDirtyFlush();
     }, {
       immediate: true
     });
-    this._subscriptions.set(id, cancel);
+    this._subscriptions.set(subscriptionKey(id, "expand", key), cancel);
   }
   // TODO(wittjosiah): If the same node is added by a connector, the resolver should probably cancel itself?
   async _onInitialize(id) {
     log2("onInitialize", {
       id
     }, {
-      F: __dxlog_file2,
-      L: 227,
+      F: __dxlog_file3,
+      L: 300,
       S: this,
       C: (f, a) => f(...a)
     });
@@ -1008,9 +1260,14 @@ var GraphBuilderImpl = class {
       const trigger = this._initialized[id];
       Option3.match(node, {
         onSome: (node2) => {
-          addNodes(this._graph, [
-            node2
-          ]);
+          const connectorOwned = [
+            ...this._connectorPrevious.values()
+          ].some((ids) => ids.includes(id));
+          if (!connectorOwned) {
+            addNodes(this._graph, [
+              node2
+            ]);
+          }
           trigger?.wake();
         },
         onNone: () => {
@@ -1023,11 +1280,16 @@ var GraphBuilderImpl = class {
     }, {
       immediate: true
     });
-    this._subscriptions.set(id, cancel);
+    this._subscriptions.set(subscriptionKey(id, "init"), cancel);
   }
   _onRemoveNode(id) {
-    this._subscriptions.get(id)?.();
-    this._subscriptions.delete(id);
+    const prefix = `${id}${Separators.primary}`;
+    for (const [key, cleanup] of this._subscriptions) {
+      if (key.startsWith(prefix)) {
+        cleanup();
+        this._subscriptions.delete(key);
+      }
+    }
   }
 };
 var make2 = (params) => {
@@ -1080,14 +1342,11 @@ function removeExtension(builderOrId, id) {
 }
 var exploreImpl = async (builder, options, path = []) => {
   const internal = builder;
-  const { registry = Registry2.make(), source = RootId, relation = "outbound", visitor } = options;
+  const { registry = Registry2.make(), source = RootId, relation: relation2, visitor } = options;
   if (path.includes(source)) {
     return;
   }
-  if (!isNode()) {
-    const { yieldOrContinue } = await import("main-thread-scheduling");
-    await yieldOrContinue("idle");
-  }
+  await yieldOrContinue("idle");
   const node = registry.get(internal._graph.nodeOrThrow(source));
   const shouldContinue = await visitor(node, [
     ...path,
@@ -1096,13 +1355,13 @@ var exploreImpl = async (builder, options, path = []) => {
   if (shouldContinue === false) {
     return;
   }
-  const nodes = Object.values(internal._registry.get(internal._extensions)).filter((extension) => relation === (extension.relation ?? "outbound")).map((extension) => extension.connector).filter(isNonNullable2).flatMap((connector) => registry.get(connector(internal._graph.node(source))));
+  const nodes = Function2.pipe(internal._registry.get(internal._extensions), Record2.values, Array2.map((extension) => extension.connector), Array2.filter(isNonNullable2), Array2.flatMap((connector) => registry.get(connector(internal._graph.node(source)))), qualifyNodeArgs(source));
   await Promise.all(nodes.map((nodeArg) => {
     registry.set(internal._graph._node(nodeArg.id), internal._graph._constructNode(nodeArg));
     return exploreImpl(builder, {
       registry,
       source: nodeArg.id,
-      relation,
+      relation: relation2,
       visitor
     }, [
       ...path,
@@ -1138,8 +1397,12 @@ function destroy(builder) {
     return destroyImpl(builder);
   }
 }
+var flush = (builder) => {
+  return builder._flushPromise;
+};
 var createExtensionRaw = (extension) => {
-  const { id, position = "static", relation = "outbound", resolver: _resolver, connector: _connector, actions: _actions, actionGroups: _actionGroups } = extension;
+  const { id, position = "static", relation: relation2 = "child", resolver: _resolver, connector: _connector, actions: _actions, actionGroups: _actionGroups } = extension;
+  const normalizedRelation = normalizeRelation(relation2);
   const getId = (key) => `${id}/${key}`;
   const resolver = _resolver && Atom3.family((id2) => _resolver(id2).pipe(Atom3.withLabel(`graph-builder:_resolver:${id2}`)));
   const connector = _connector && Atom3.family((node) => _connector(node).pipe(Atom3.withLabel(`graph-builder:_connector:${id}`)));
@@ -1154,7 +1417,7 @@ var createExtensionRaw = (extension) => {
     connector ? {
       id: getId("connector"),
       position,
-      relation,
+      relation: normalizedRelation,
       connector: Atom3.family((node) => Atom3.make((get2) => {
         try {
           return get2(connector(node));
@@ -1164,8 +1427,8 @@ var createExtensionRaw = (extension) => {
             node,
             error
           }, {
-            F: __dxlog_file2,
-            L: 509,
+            F: __dxlog_file3,
+            L: 596,
             S: void 0,
             C: (f, a) => f(...a)
           });
@@ -1176,7 +1439,7 @@ var createExtensionRaw = (extension) => {
     actionGroups ? {
       id: getId("actionGroups"),
       position,
-      relation: "outbound",
+      relation: actionRelation(),
       connector: Atom3.family((node) => Atom3.make((get2) => {
         try {
           return get2(actionGroups(node)).map((arg) => ({
@@ -1190,8 +1453,8 @@ var createExtensionRaw = (extension) => {
             node,
             error
           }, {
-            F: __dxlog_file2,
-            L: 530,
+            F: __dxlog_file3,
+            L: 617,
             S: void 0,
             C: (f, a) => f(...a)
           });
@@ -1202,7 +1465,7 @@ var createExtensionRaw = (extension) => {
     actions ? {
       id: getId("actions"),
       position,
-      relation: "outbound",
+      relation: actionRelation(),
       connector: Atom3.family((node) => Atom3.make((get2) => {
         try {
           return get2(actions(node)).map((arg) => ({
@@ -1215,8 +1478,8 @@ var createExtensionRaw = (extension) => {
             node,
             error
           }, {
-            F: __dxlog_file2,
-            L: 547,
+            F: __dxlog_file3,
+            L: 634,
             S: void 0,
             C: (f, a) => f(...a)
           });
@@ -1232,8 +1495,8 @@ var runEffectSyncWithFallback = (effect, context2, extensionId, fallback) => {
       extension: extensionId,
       error
     }, {
-      F: __dxlog_file2,
-      L: 590,
+      F: __dxlog_file3,
+      L: 677,
       S: void 0,
       C: (f, a) => f(...a)
     });
@@ -1241,7 +1504,7 @@ var runEffectSyncWithFallback = (effect, context2, extensionId, fallback) => {
   })));
 };
 var createExtension = (options) => Effect.map(Effect.context(), (context2) => {
-  const { id, match: match3, actions, connector, resolver, relation, position } = options;
+  const { id, match: match3, actions, connector, resolver, relation: relation2, position } = options;
   const connectorExtension = connector ? createConnectorWithRuntime(id, match3, connector, context2) : void 0;
   const actionsExtension = actions ? (node) => Atom3.make((get2) => Function2.pipe(get2(node), Option3.flatMap(match3), Option3.map((matched) => runEffectSyncWithFallback(actions(matched, get2), context2, id, []).map((action) => ({
     ...action,
@@ -1251,7 +1514,7 @@ var createExtension = (options) => Effect.map(Effect.context(), (context2) => {
   const resolverExtension = resolver ? (nodeId) => Atom3.make((get2) => runEffectSyncWithFallback(resolver(nodeId, get2), context2, id, null) ?? null) : void 0;
   return createExtensionRaw({
     id,
-    relation,
+    relation: relation2,
     position,
     connector: connectorExtension,
     actions: actionsExtension,
@@ -1265,16 +1528,35 @@ var createConnectorWithRuntime = (extensionId, matcher, factory, context2) => {
   return (node) => Atom3.make((get2) => Function2.pipe(get2(node), Option3.flatMap(matcher), Option3.map((data) => runEffectSyncWithFallback(factory(data, get2), context2, extensionId, [])), Option3.getOrElse(() => [])));
 };
 var createTypeExtension = (options) => {
-  const { id, type, actions, connector, relation, position } = options;
+  const { id, type, actions, connector, relation: relation2, position } = options;
   return createExtension({
     id,
     match: whenEchoType(type),
     actions,
     connector,
-    relation,
+    relation: relation2,
     position
   });
 };
+var qualifyNodeArgs = (parentId) => (nodes) => nodes.map((node) => {
+  validateSegmentId(node.id);
+  const qualified = qualifyId(parentId, node.id);
+  return {
+    ...node,
+    id: qualified,
+    nodes: node.nodes ? qualifyNodeArgs(qualified)(node.nodes) : void 0
+  };
+});
+var connectorKey = (id, relation2) => `${id}${Separators.primary}${relationKey(relation2)}`;
+var relationFromConnectorKey = (key) => {
+  const separatorIndex = key.indexOf(Separators.primary);
+  const id = key.slice(0, separatorIndex);
+  return {
+    id,
+    relation: relationFromKey(key.slice(separatorIndex + 1))
+  };
+};
+var subscriptionKey = (id, kind, detail) => detail != null ? `${id}${Separators.primary}${kind}${Separators.primary}${detail}` : `${id}${Separators.primary}${kind}`;
 var flattenExtensions = (extension, acc = []) => {
   if (Array2.isArray(extension)) {
     return [