@dxos/app-graph 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/node-matcher.ts

@@ -69,7 +69,7 @@ export const whenId =
  * ```ts
  * GraphBuilder.createExtension({
  *   id: 'space-settings-extension',
- *   match: NodeMatcher.whenNodeType('dxos.org/plugin/space/settings'),
+ *   match: NodeMatcher.whenNodeType('org.dxos.plugin.space.settings'),
  *   connector: (node) => Effect.succeed([...]),
  * });
  * ```
@@ -106,10 +106,13 @@ export const whenNodeType =
  * });
  * ```
  *
- * @see {@link whenEchoTypeMatches} - Use instead when composing with whenAll/whenAny.
+ * Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+ * preserving the typed entity data in the result.
+ *
+ * @see {@link whenEchoTypeMatches} - Returns the node instead of data for legacy composition.
  */
 export const whenEchoType =
-  <T extends Type.Entity.Any>(type: T): NodeMatcher<Entity.Entity<Schema.Schema.Type<T>>> =>
+  <T extends Type.AnyEntity>(type: T): NodeMatcher<Entity.Entity<Schema.Schema.Type<T>>> =>
   (node: Node.Node): Option.Option<Entity.Entity<Schema.Schema.Type<T>>> =>
     Obj.instanceOf(type, node.data) ? Option.some(node.data) : Option.none();
 
@@ -129,12 +132,15 @@ export const whenEchoType =
  *   connector: (object) => {
  *     // `object` is typed as Obj.Unknown
  *     const id = Obj.getDXN(object).toString();
- *     return Effect.succeed([{ id: `${id}/settings`, ... }]);
+ *     return Effect.succeed([{ id: `${id}.settings`, ... }]);
  *   },
  * });
  * ```
  *
- * @see {@link whenEchoObjectMatches} - Use instead when composing with whenAll/whenAny.
+ * Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+ * preserving the `Obj.Unknown` data type in the result.
+ *
+ * @see {@link whenEchoObjectMatches} - Returns the node instead of data for legacy composition.
  */
 export const whenEchoObject = (node: Node.Node): Option.Option<Obj.Unknown> =>
   Obj.isObject(node.data) ? Option.some(node.data) : Option.none();
@@ -145,38 +151,53 @@ export const whenEchoObject = (node: Node.Node): Option.Option<Obj.Unknown> =>
 
 /**
  * Composes multiple matchers with AND logic - all matchers must match for success.
- * Returns the **node** (not the matched data) to enable further composition.
+ * The result data type is the intersection of all matchers' data types.
+ * Filter matchers like {@link whenNot} return `unknown`, making them transparent
+ * in the intersection (since `T & unknown = T`).
  *
  * @param matchers - The matchers to combine. All must return Option.some for success.
- * @returns A matcher that returns Option.some(node) if all match, Option.none() otherwise.
+ * @returns A matcher whose data type is the intersection of all input matchers' data types.
+ *   Returns the first matcher's value when all match, Option.none() otherwise.
  *
  * @example
  * ```ts
- * // Match ECHO objects that are NOT Channels
+ * // Match ECHO objects that are NOT Channels — result is NodeMatcher<Obj.Unknown>.
  * const whenCommentable = NodeMatcher.whenAll(
- *   NodeMatcher.whenEchoObjectMatches,
+ *   NodeMatcher.whenEchoObject,
  *   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
  * );
  * ```
  */
-export const whenAll =
-  (...matchers: NodeMatcher[]): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> => {
-    for (const matcher of matchers) {
-      const result = matcher(node);
+export const whenAll: {
+  <A>(a: NodeMatcher<A>, b: NodeMatcher<unknown>): NodeMatcher<A>;
+  <A>(a: NodeMatcher<unknown>, b: NodeMatcher<A>): NodeMatcher<A>;
+  <A, B>(a: NodeMatcher<A>, b: NodeMatcher<B>): NodeMatcher<A & B>;
+  <A, B, C>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>): NodeMatcher<A & B & C>;
+  <A, B, C, D>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>, d: NodeMatcher<D>): NodeMatcher<A & B & C & D>;
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
+} =
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
+  (node: Node.Node) => {
+    let first: Option.Option<any> = Option.none();
+    for (const candidate of matchers) {
+      const result = candidate(node);
       if (Option.isNone(result)) {
         return Option.none();
       }
+      if (Option.isNone(first)) {
+        first = result;
+      }
     }
-    return Option.some(node);
+    return first;
   };
 
 /**
  * Composes multiple matchers with OR logic - at least one matcher must match.
- * Returns the **node** (not the matched data) to enable further composition.
+ * The result data type is the union of all matchers' data types.
  *
  * @param matchers - The matchers to combine. At least one must return Option.some.
- * @returns A matcher that returns Option.some(node) if any match, Option.none() otherwise.
+ * @returns A matcher whose data type is the union of all input matchers' data types.
+ *   Returns the first matching matcher's value, or Option.none() if none match.
  *
  * @example
  * ```ts
@@ -187,13 +208,18 @@ export const whenAll =
  * );
  * ```
  */
-export const whenAny =
-  (...matchers: NodeMatcher[]): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> => {
-    for (const matcher of matchers) {
-      const result = matcher(node);
+export const whenAny: {
+  <A, B>(a: NodeMatcher<A>, b: NodeMatcher<B>): NodeMatcher<A | B>;
+  <A, B, C>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>): NodeMatcher<A | B | C>;
+  <A, B, C, D>(a: NodeMatcher<A>, b: NodeMatcher<B>, c: NodeMatcher<C>, d: NodeMatcher<D>): NodeMatcher<A | B | C | D>;
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any>;
+} =
+  (...matchers: NodeMatcher<any>[]): NodeMatcher<any> =>
+  (node: Node.Node) => {
+    for (const candidate of matchers) {
+      const result = candidate(node);
       if (Option.isSome(result)) {
-        return Option.some(node);
+        return result;
       }
     }
     return Option.none();
@@ -229,7 +255,7 @@ export const whenAny =
  * @see {@link whenEchoType} - Use instead when you need the typed entity directly.
  */
 export const whenEchoTypeMatches =
-  <T extends Type.Entity.Any>(type: T): NodeMatcher =>
+  <T extends Type.AnyEntity>(type: T): NodeMatcher =>
   (node: Node.Node): Option.Option<Node.Node> =>
     Obj.instanceOf(type, node.data) ? Option.some(node) : Option.none();
 
@@ -262,15 +288,19 @@ export const whenEchoObjectMatches = (node: Node.Node): Option.Option<Node.Node>
  * Negates a matcher - matches when the given matcher does NOT match.
  * Useful for exclusion patterns like "any object EXCEPT type X".
  *
+ * Returns `NodeMatcher<unknown>` because negation is a filter — it doesn't provide
+ * typed data. This makes it transparent in {@link whenAll} intersections
+ * (since `T & unknown = T`).
+ *
  * @param matcher - The matcher to negate.
  * @returns A matcher that returns Option.some(node) if the input matcher returns none,
  *   and Option.none() if the input matcher returns some.
  *
  * @example
  * ```ts
- * // Match any ECHO object that is NOT a Channel
+ * // Match any ECHO object that is NOT a Channel — result is NodeMatcher<Obj.Unknown>.
  * const whenCommentable = NodeMatcher.whenAll(
- *   NodeMatcher.whenEchoObjectMatches,
+ *   NodeMatcher.whenEchoObject,
  *   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
  * );
  *
@@ -279,6 +309,6 @@ export const whenEchoObjectMatches = (node: Node.Node): Option.Option<Node.Node>
  * ```
  */
 export const whenNot =
-  (matcher: NodeMatcher): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.Node> =>
+  (matcher: NodeMatcher<any>): NodeMatcher<unknown> =>
+  (node: Node.Node): Option.Option<unknown> =>
     Option.isNone(matcher(node)) ? Option.some(node) : Option.none();

package/src/node.ts

@@ -15,17 +15,17 @@ export const RootId = 'root';
 /**
  * Root node type.
  */
-export const RootType = 'dxos.org/type/GraphRoot';
+export const RootType = 'org.dxos.type.graphRoot';
 
 /**
  * Action node type.
  */
-export const ActionType = 'dxos.org/type/GraphAction';
+export const ActionType = 'org.dxos.type.graphAction';
 
 /**
  * Action group node type.
  */
-export const ActionGroupType = 'dxos.org/type/GraphActionGroup';
+export const ActionGroupType = 'org.dxos.type.graphActionGroup';
 
 /**
  * Represents a node in the graph.
@@ -69,7 +69,19 @@ export type NodeFilter<TData = any, TProperties extends Record<string, any> = Re
   connectedNode: Node,
 ) => node is Node<TData, TProperties>;
 
-export type Relation = 'outbound' | 'inbound';
+export type RelationDirection = 'outbound' | 'inbound';
+
+export type Relation = Readonly<{
+  kind: string;
+  direction: RelationDirection;
+}>;
+
+export type RelationInput = Relation | string;
+
+export const relation = (kind: string, direction: RelationDirection = 'outbound'): Relation => ({ kind, direction });
+// TODO(wittjosiah): Consider moving these helpers out of the core API.
+export const childRelation = (direction: RelationDirection = 'outbound'): Relation => relation('child', direction);
+export const actionRelation = (direction: RelationDirection = 'outbound'): Relation => relation('action', direction);
 
 export const isGraphNode = (data: unknown): data is Node =>
   data && typeof data === 'object' && 'id' in data && 'properties' in data && data.properties
@@ -84,7 +96,7 @@ export type NodeArg<TData, TProperties extends Record<string, any> = Record<stri
   nodes?: NodeArg<unknown>[];
 
   /** Will automatically add specified edges. */
-  edges?: [string, Relation][];
+  edges?: [string, RelationInput][];
 };
 
 //
@@ -95,6 +107,9 @@ export type InvokeProps = {
   /** Node the invoked action is connected to. */
   parent?: Node;
 
+  /** Path from root to the node in the current tree context. */
+  path?: string[];
+
   caller?: string;
 };
 
@@ -135,3 +150,29 @@ export const isActionGroup = (data: unknown): data is ActionGroup =>
 export type ActionLike = Action | ActionGroup;
 
 export const isActionLike = (data: unknown): data is Action | ActionGroup => isAction(data) || isActionGroup(data);
+
+//
+// Node Factories
+//
+
+/** Typed factory for constructing a NodeArg. Provides auto-complete and type validation. */
+export const make = <TData = any, TProperties extends Record<string, any> = Record<string, any>>(
+  arg: NodeArg<TData, TProperties>,
+): NodeArg<TData, TProperties> => arg;
+
+/** Create an action node. Automatically sets `type: ActionType`. */
+export const makeAction = <R = never>(
+  arg: Omit<NodeArg<ActionData<R>>, 'type' | 'nodes' | 'edges'>,
+): NodeArg<ActionData<R>> => ({
+  ...arg,
+  type: ActionType,
+});
+
+/** Create an action group node. Automatically sets `type` and `data`. */
+export const makeActionGroup = (
+  arg: Omit<NodeArg<typeof actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>,
+): NodeArg<typeof actionGroupSymbol> => ({
+  ...arg,
+  type: ActionGroupType,
+  data: actionGroupSymbol,
+});

package/src/stories/EchoGraph.stories.tsx

@@ -17,9 +17,9 @@ import { type Client, useClient } from '@dxos/react-client';
 import { withClientProvider } from '@dxos/react-client/testing';
 import { Icon, IconButton, Input, Select } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
-import { Path, Tree } from '@dxos/react-ui-list';
+import { Path, Tree, type TreeModel } from '@dxos/react-ui-list';
 import { getSize, mx } from '@dxos/ui-theme';
-import { byPosition, isNonNullable, safeParseInt } from '@dxos/util';
+import { safeParseInt } from '@dxos/util';
 
 import * as CreateAtom from '../atoms';
 import * as Graph from '../graph';
@@ -64,7 +64,7 @@ const createGraph = (client: Client, registry: Registry.Registry): Graph.Expanda
                 const propertiesSnapshot = get(AtomObj.make(space.properties));
                 return {
                   id: space.id,
-                  type: 'dxos.org/type/Space',
+                  type: 'org.dxos.type.space',
                   properties: {
                     label: propertiesSnapshot.name,
                   },
@@ -88,7 +88,7 @@ const createGraph = (client: Client, registry: Registry.Registry): Graph.Expanda
             const objects = get(AtomQuery.make(space.db, Query.type(TestSchema.Expando, { type: 'test' })));
             return objects.map((object) => ({
               id: object.id,
-              type: 'dxos.org/type/test',
+              type: 'org.dxos.type.test',
               properties: { label: object.name },
               data: object,
             }));
@@ -104,9 +104,9 @@ const createGraph = (client: Client, registry: Registry.Registry): Graph.Expanda
   GraphBuilder.addExtension(builder, objectBuilderExtension);
   const graph = builder.graph;
   graph.onNodeChanged.on(({ id }) => {
-    Graph.expand(graph, id);
+    Graph.expand(graph, id, 'child');
   });
-  Graph.expand(graph, Node.RootId);
+  Graph.expand(graph, Node.RootId, 'child');
   (window as any).graph = graph;
   return graph;
 };
@@ -146,8 +146,8 @@ const runAction = async (client: Client, action: Action) => {
     case Action.RENAME_SPACE: {
       const space = getRandomSpace(client);
       if (space) {
-        Obj.change(space.properties, (p) => {
-          p.name = faker.commerce.productName();
+        Obj.change(space.properties, (obj) => {
+          obj.name = faker.commerce.productName();
         });
       }
       break;
@@ -176,8 +176,8 @@ const runAction = async (client: Client, action: Action) => {
       if (space) {
         const objects = await space.db.query(Filter.type(TestSchema.Expando, { type: 'test' })).run();
         const object = objects[Math.floor(Math.random() * objects.length)];
-        Obj.change(object, (o) => {
-          o.name = faker.commerce.productName();
+        Obj.change(object, (obj) => {
+          obj.name = faker.commerce.productName();
         });
       }
       break;
@@ -216,14 +216,13 @@ const Controls = ({ children }: PropsWithChildren) => {
           <Input.Root>
             <Input.TextInput
               autoComplete='off'
-              size={5}
-              classNames='is-[100px] text-right pie-[22px]'
+              classNames='w-[100px] text-right pe-[22px]'
               placeholder='Interval'
               value={actionInterval}
               onChange={({ target: { value } }) => setActionInterval(value)}
             />
           </Input.Root>
-          <Icon icon='ph--timer--regular' classNames={mx('absolute inline-end-1 block-start-1 mt-[6px]', getSize(3))} />
+          <Icon icon='ph--timer--regular' classNames={mx('absolute right-1 top-1 mt-[6px]', getSize(3))} />
         </div>
         <IconButton icon='ph--plus--regular' label='Add' onClick={() => action && runAction(client, action)} />
         <Select.Root value={action?.toString()} onValueChange={(action) => setAction(action as unknown as Action)}>
@@ -252,9 +251,10 @@ const Controls = ({ children }: PropsWithChildren) => {
 const meta = {
   title: 'sdk/app-graph/EchoGraph',
   decorators: [
-    withTheme,
+    withTheme(),
     withClientProvider({
       createIdentity: true,
+      types: [TestSchema.Expando],
       onCreateIdentity: async ({ client }) => {
         await client.spaces.create();
         await client.spaces.create();
@@ -291,60 +291,97 @@ export const TreeView: Story = {
     const stateRef = useRef(new Map<string, Atom.Writable<{ open: boolean; current: boolean }>>());
 
     const getOrCreateState = useMemo(
-      () => (path: string) => {
-        let atom = stateRef.current.get(path);
+      () => (pathKey: string) => {
+        let atom = stateRef.current.get(pathKey);
         if (!atom) {
           atom = Atom.make({ open: true, current: false }).pipe(Atom.keepAlive);
-          stateRef.current.set(path, atom);
+          stateRef.current.set(pathKey, atom);
         }
         return atom;
       },
       [],
     );
 
-    const useItems = useCallback(
-      (node?: Node.Node, options?: { disposition?: string; sort?: boolean }) => {
-        const connections = useAtomValue(graph.connections(node?.id ?? Node.RootId));
-        return options?.sort ? connections.toSorted((a, b) => byPosition(a.properties, b.properties)) : connections;
-      },
+    const childIdsFamily = useMemo(
+      () =>
+        Atom.family((id: string) =>
+          Atom.make((get) => {
+            const connections = get(graph.connections(id, 'child'));
+            return connections.map((connection) => connection.id);
+          }),
+        ),
       [graph],
     );
 
-    const getProps = useCallback(
-      (node: Node.Node, path: string[]) => {
-        const children = Graph.getConnections(graph, node.id, 'outbound')
-          .map((n) => {
-            // Break cycles.
-            const nextPath = [...path, node.id];
-            return nextPath.includes(n.id) ? undefined : (n as Node.Node);
-          })
-          .filter(isNonNullable) as Node.Node[];
-        const parentOf =
-          children.length > 0 ? children.map(({ id }) => id) : node.properties.role === 'branch' ? [] : undefined;
-        return {
-          id: node.id,
-          label: node.id,
-          icon: node.type === 'dxos.org/type/Space' ? 'ph--planet--regular' : 'ph--placeholder--regular',
-          parentOf,
-        };
-      },
+    const itemFamily = useMemo(
+      () =>
+        Atom.family((id: string) =>
+          Atom.make((get) => {
+            const node = get(graph.node(id));
+            return Option.isSome(node) ? node.value : undefined;
+          }),
+        ),
+      [graph],
+    );
+
+    const itemPropsFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const path = pathKey.split('~');
+          const id = path[path.length - 1];
+          return Atom.make((get) => {
+            const nodeOpt = get(graph.node(id));
+            const node = Option.isSome(nodeOpt) ? nodeOpt.value : undefined;
+            if (!node) {
+              return { id, label: id };
+            }
+            const connections = get(graph.connections(node.id, 'child'));
+            const safeChildren = connections.filter((n) => !path.includes(n.id));
+            const parentOf =
+              safeChildren.length > 0
+                ? safeChildren.map(({ id }) => id)
+                : node.properties.role === 'branch'
+                  ? []
+                  : undefined;
+            return {
+              id: node.id,
+              label: node.id,
+              icon: node.type === 'org.dxos.type.space' ? 'ph--planet--regular' : 'ph--placeholder--regular',
+              parentOf,
+            };
+          });
+        }),
       [graph],
     );
 
-    // Hook that subscribes to item state via Atom.
-    const useItemState = (_path: string[]) => {
-      const path = useMemo(() => Path.create(..._path), [_path.join('~')]);
-      const atom = getOrCreateState(path);
-      return useAtomValue(atom);
-    };
+    const itemOpenFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const stateAtom = getOrCreateState(pathKey);
+          return Atom.make((get) => get(stateAtom).open);
+        }),
+      [getOrCreateState],
+    );
 
-    const useIsOpen = (_path: string[]) => {
-      return useItemState(_path).open;
-    };
+    const itemCurrentFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const stateAtom = getOrCreateState(pathKey);
+          return Atom.make((get) => get(stateAtom).current);
+        }),
+      [getOrCreateState],
+    );
 
-    const useIsCurrent = (_path: string[]) => {
-      return useItemState(_path).current;
-    };
+    const model: TreeModel<Node.Node> = useMemo(
+      () => ({
+        childIds: (parentId?: string) => childIdsFamily(parentId ?? Node.RootId),
+        item: (id: string) => itemFamily(id),
+        itemProps: (path: string[]) => itemPropsFamily(path.join('~')),
+        itemOpen: (path: string[]) => itemOpenFamily(Path.create(...path)),
+        itemCurrent: (path: string[]) => itemCurrentFamily(Path.create(...path)),
+      }),
+      [childIdsFamily, itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily],
+    );
 
     const onOpenChange = useCallback(
       ({ path: _path, open }: { path: string[]; open: boolean }) => {
@@ -373,15 +410,7 @@ export const TreeView: Story = {
     return (
       <>
         <Controls />
-        <Tree
-          id={Node.RootId}
-          useItems={useItems}
-          getProps={getProps}
-          useIsOpen={useIsOpen}
-          useIsCurrent={useIsCurrent}
-          onOpenChange={onOpenChange}
-          onSelect={onSelect}
-        />
+        <Tree model={model} id={Node.RootId} onOpenChange={onOpenChange} onSelect={onSelect} />
       </>
     );
   },

package/src/stories/Tree.tsx

@@ -72,7 +72,7 @@ const Scalar: FC<{ value: any }> = ({ value }) => {
 
 const Box: FC<HTMLAttributes<HTMLDivElement>> = ({ children, className, ...props }) => {
   return (
-    <div className={mx('flex pli-2 border border-l-0 font-mono truncate', className)} {...props}>
+    <div className={mx('flex px-2 border border-l-0 font-mono truncate', className)} {...props}>
       {children}
     </div>
   );

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './setup-graph-builder';

package/src/testing/setup-graph-builder.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import * as Option from 'effect/Option';
+
+import * as Graph from '../graph';
+import * as GraphBuilder from '../graph-builder';
+import * as Node from '../node';
+
+export type SetupGraphBuilderOptions = {
+  registry?: Registry.Registry;
+  extensions?: GraphBuilder.BuilderExtensions;
+};
+
+export const setupGraphBuilder = ({ registry = Registry.make(), extensions }: SetupGraphBuilderOptions = {}) => {
+  const builder = GraphBuilder.make({ registry });
+  const graph = builder.graph;
+
+  if (extensions) {
+    GraphBuilder.addExtension(builder, extensions);
+  }
+
+  return {
+    registry,
+    builder,
+    graph,
+    addExtensions: (nextExtensions: GraphBuilder.BuilderExtensions) => {
+      GraphBuilder.addExtension(builder, nextExtensions);
+    },
+    expand: async (id: string, relation: Node.RelationInput = 'child') => {
+      Graph.expand(graph, id, relation);
+      await GraphBuilder.flush(builder);
+    },
+    flush: () => GraphBuilder.flush(builder),
+    getConnections: (id: string, relation: Node.RelationInput = 'child') =>
+      registry.get(graph.connections(id, relation)),
+    getNode: (id: string) => Graph.getNode(graph, id).pipe(Option.getOrNull),
+  };
+};

package/src/util.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import * as Node from './node';
+
+// PRIMARY separates top-level components (e.g., node ID from relation) in compound string keys used within the app-graph package.
+const PRIMARY = '\u0001';
+
+// SECONDARY separates sub-components within an encoded value (e.g., relation kind from direction) in the same context.
+const SECONDARY = '\u0002';
+
+// PATH separates segments in qualified node IDs (e.g., parent path from local segment).
+const PATH = '/';
+
+/** Join parts with the primary separator. */
+export const primaryKey = (...parts: string[]): string => parts.join(PRIMARY);
+
+/** Split a key on the primary separator. */
+export const primaryParts = (key: string): string[] => key.split(PRIMARY);
+
+/** Join parts with the secondary separator. */
+export const secondaryKey = (...parts: string[]): string => parts.join(SECONDARY);
+
+/** Split a key on the secondary separator. */
+export const secondaryParts = (key: string): string[] => key.split(SECONDARY);
+
+/**
+ * Normalize a relation input to a full Relation object.
+ */
+export const normalizeRelation = (relation?: Node.RelationInput): Node.Relation =>
+  relation == null ? Node.childRelation() : typeof relation === 'string' ? Node.relation(relation) : relation;
+
+/**
+ * Shallow-compare two values: same reference, or same own-keys with === values.
+ */
+export const shallowEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (a == null || b == null || typeof a !== 'object' || typeof b !== 'object') return false;
+  const keysA = Object.keys(a as Record<string, unknown>);
+  const keysB = Object.keys(b as Record<string, unknown>);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  return keysA.every((k) => (a as Record<string, unknown>)[k] === (b as Record<string, unknown>)[k]);
+};
+
+/**
+ * Returns true if two NodeArg arrays are semantically identical (same id, type, data, properties per index).
+ */
+export const nodeArgsUnchanged = (prev: Node.NodeArg<any>[], next: Node.NodeArg<any>[]): boolean => {
+  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)
+    );
+  });
+};
+
+/**
+ * Build a qualified node ID by joining path segments.
+ */
+export const qualifyId = (parentId: string, ...segmentIds: string[]): string => [parentId, ...segmentIds].join(PATH);
+
+/**
+ * Validate that a segment ID does not contain the path separator.
+ */
+export const validateSegmentId = (id: string): void => {
+  invariant(!id.includes(PATH), `Node segment ID must not contain '${PATH}': ${id}`);
+};
+
+/**
+ * Extract the parent qualified ID (everything before the last path separator).
+ * Returns undefined for IDs with no parent (single segment).
+ */
+export const getParentId = (qualifiedId: string): string | undefined => {
+  const lastSlash = qualifiedId.lastIndexOf(PATH);
+  return lastSlash > 0 ? qualifiedId.slice(0, lastSlash) : undefined;
+};
+
+/**
+ * Extract the last segment of a qualified ID.
+ */
+export const getSegmentId = (qualifiedId: string): string => {
+  return qualifiedId.split(PATH).pop() ?? qualifiedId;
+};