@dxos/app-graph 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/graph-builder.ts

@@ -11,17 +11,26 @@ import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
 import * as Record from 'effect/Record';
 import type * as Schema from 'effect/Schema';
-import { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';
 
 import { type CleanupFn, type Trigger } from '@dxos/async';
 import { type Entity, type Type } from '@dxos/echo';
 import { log } from '@dxos/log';
 import { type MaybePromise, type Position, byPosition, getDebugName, isNonNullable } from '@dxos/util';
 
+import { scheduleTask, yieldOrContinue } from '#scheduler';
+
 import * as Graph from './graph';
 import * as Node from './node';
 import * as NodeMatcher from './node-matcher';
-import { Separators, nodeArgsUnchanged, normalizeRelation } from './util';
+import {
+  getParentId,
+  nodeArgsUnchanged,
+  normalizeRelation,
+  primaryKey,
+  primaryParts,
+  qualifyId,
+  validateSegmentId,
+} from './util';
 
 //
 // Extension Types
@@ -55,7 +64,7 @@ export type ActionGroupsExtension = (
 
 export type BuilderExtension = Readonly<{
   id: string;
-  position: Position;
+  position?: Position;
   relation?: Node.RelationInput;
   resolver?: ResolverExtension;
   connector?: (node: Atom.Atom<Option.Option<Node.Node>>) => Atom.Atom<Node.NodeArg<any>[]>;
@@ -71,7 +80,7 @@ export type GraphBuilderTraverseOptions = {
   visitor: (node: Node.Node, path: string[]) => MaybePromise<boolean | void>;
   registry?: Registry.Registry;
   source?: string;
-  relation: Node.RelationInput;
+  relation: Node.RelationInput | Node.RelationInput[];
 };
 
 /**
@@ -105,7 +114,9 @@ class GraphBuilderImpl implements GraphBuilder {
   }
 
   // TODO(wittjosiah): Use Context.
+  /** Active subscriptions keyed by composite ID, cleaned up on node removal. */
   readonly _subscriptions = new Map<string, CleanupFn>();
+  /** Connector updates pending flush, keyed by connector key. */
   readonly _dirtyConnectors = new Map<
     string,
     {
@@ -113,16 +124,26 @@ class GraphBuilderImpl implements GraphBuilder {
       previous: string[];
     }
   >();
+  /** Last-flushed node IDs per connector key, used for edge removal on update. */
   readonly _connectorPrevious = new Map<string, string[]>();
+  /** All inline-descendant IDs per connector key, used to remove stale inline nodes on update. */
+  readonly _connectorPreviousInlineIds = new Map<string, string[]>();
+  /** Last-flushed node args per connector key, used for change detection. */
   readonly _connectorPreviousArgs = new Map<string, Node.NodeArg<any>[]>();
+  /** Whether a dirty-flush task is already scheduled. */
   _flushScheduled = false;
+  /** Resolves when the current flush completes. */
   _flushPromise: Promise<void> = Promise.resolve();
+  /** Registered builder extensions keyed by extension ID. */
   readonly _extensions = Atom.make(Record.empty<string, BuilderExtension>()).pipe(
     Atom.keepAlive,
     Atom.withLabel('graph-builder:extensions'),
   );
+  /** Triggers signalling that a node's resolver has fired at least once. */
   readonly _initialized: Record<string, Trigger> = {};
+  /** Shared atom registry for reactive subscriptions. */
   readonly _registry: Registry.Registry;
+  /** Backing graph with internal accessors for node atoms and construction. */
   readonly _graph: Graph.Graph & {
     _node: (id: string) => Atom.Writable<Option.Option<Node.Node>>;
     _constructNode: (node: Node.NodeArg<any>) => Option.Option<Node.Node>;
@@ -160,6 +181,12 @@ class GraphBuilderImpl implements GraphBuilder {
     this._connectorPrevious.set(key, ids);
     this._connectorPreviousArgs.set(key, nodes);
 
+    const currentInlineIds = collectAllInlineIds(nodes);
+    const previousInlineIds = this._connectorPreviousInlineIds.get(key) ?? [];
+    const staleInlineIds = previousInlineIds.filter((pid) => !currentInlineIds.includes(pid));
+    this._connectorPreviousInlineIds.set(key, currentInlineIds);
+
+    Graph.removeNodes(this._graph, staleInlineIds, true);
     Graph.removeEdges(
       this._graph,
       removed.map((target) => ({ source: id, target, relation })),
@@ -263,7 +290,8 @@ class GraphBuilderImpl implements GraphBuilder {
 
     const cancel = this._registry.subscribe(
       connectors,
-      (nodes) => {
+      (rawNodes) => {
+        const nodes = qualifyNodeArgs(id)(rawNodes);
         const previous = this._connectorPrevious.get(key) ?? [];
         const ids = nodes.map((n) => n.id);
 
@@ -284,7 +312,6 @@ class GraphBuilderImpl implements GraphBuilder {
     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?
   private async _onInitialize(id: string) {
     log('onInitialize', { id });
     const resolver = this._resolvers(id);
@@ -293,14 +320,24 @@ class GraphBuilderImpl implements GraphBuilder {
       resolver,
       (node) => {
         const trigger = this._initialized[id];
+        const connectorOwned = [...this._connectorPrevious.values()].some((ids) => ids.includes(id));
         Option.match(node, {
           onSome: (node) => {
-            Graph.addNodes(this._graph, [node]);
+            if (!connectorOwned) {
+              Graph.addNodes(this._graph, [node]);
+              // Connect resolved node to its parent via a child edge.
+              const parentId = getParentId(id);
+              if (parentId) {
+                Graph.addEdges(this._graph, [{ source: parentId, target: id, relation: 'child' }]);
+              }
+            }
             trigger?.wake();
           },
           onNone: () => {
             trigger?.wake();
-            Graph.removeNodes(this._graph, [id]);
+            if (!connectorOwned) {
+              Graph.removeNodes(this._graph, [id]);
+            }
           },
         });
       },
@@ -311,9 +348,8 @@ class GraphBuilderImpl implements GraphBuilder {
   }
 
   private _onRemoveNode(id: string): void {
-    const prefix = `${id}${Separators.primary}`;
     for (const [key, cleanup] of this._subscriptions) {
-      if (key.startsWith(prefix)) {
+      if (primaryParts(key)[0] === id) {
         cleanup();
         this._subscriptions.delete(key);
       }
@@ -425,11 +461,14 @@ const exploreImpl = async (
     return;
   }
 
-  const nodes = Object.values(internal._registry.get(internal._extensions))
-    .filter((extension) => Graph.relationKey(extension.relation ?? 'child') === Graph.relationKey(relation))
-    .map((extension) => extension.connector)
-    .filter(isNonNullable)
-    .flatMap((connector) => registry.get(connector(internal._graph.node(source))));
+  const nodes = Function.pipe(
+    internal._registry.get(internal._extensions),
+    Record.values,
+    Array.map((extension) => extension.connector),
+    Array.filter(isNonNullable),
+    Array.flatMap((connector) => registry.get(connector(internal._graph.node(source)))),
+    qualifyNodeArgs(source),
+  );
 
   await Promise.all(
     nodes.map((nodeArg) => {
@@ -533,7 +572,7 @@ export type CreateExtensionRawOptions = {
 export const createExtensionRaw = (extension: CreateExtensionRawOptions): BuilderExtension[] => {
   const {
     id,
-    position = 'static',
+    position,
     relation = 'child',
     resolver: _resolver,
     connector: _connector,
@@ -793,19 +832,43 @@ export const createTypeExtension = <T extends Type.AnyEntity, R = never>(
 // Extension Utilities
 //
 
-const connectorKey = (id: string, relation: Node.RelationInput): string =>
-  `${id}${Separators.primary}${Graph.relationKey(relation)}`;
+/**
+ * Qualify node IDs by prefixing with the parent path.
+ * Validates that segment IDs do not contain the path separator.
+ * Recursively qualifies inline child nodes.
+ */
+const qualifyNodeArgs =
+  (parentId: string) =>
+  (nodes: Node.NodeArg<any>[]): Node.NodeArg<any>[] =>
+    nodes.map((node) => {
+      validateSegmentId(node.id);
+      const qualified = qualifyId(parentId, node.id);
+      return {
+        ...node,
+        id: qualified,
+        nodes: node.nodes ? qualifyNodeArgs(qualified)(node.nodes) : undefined,
+      };
+    });
+
+/**
+ * Recursively collect all inline-descendant IDs (the `nodes` arrays at every level)
+ * from a list of top-level NodeArgs. Top-level IDs are excluded because they are
+ * already tracked via `_connectorPrevious`.
+ */
+const collectAllInlineIds = (nodes: Node.NodeArg<any>[]): string[] =>
+  nodes.flatMap((node) =>
+    node.nodes ? [...node.nodes.map((child) => child.id), ...collectAllInlineIds(node.nodes)] : [],
+  );
+
+const connectorKey = (id: string, relation: Node.RelationInput): string => primaryKey(id, Graph.relationKey(relation));
 
 const relationFromConnectorKey = (key: string): { id: string; relation: Node.Relation } => {
-  const separatorIndex = key.indexOf(Separators.primary);
-  const id = key.slice(0, separatorIndex);
-  return { id, relation: Graph.relationFromKey(key.slice(separatorIndex + 1)) };
+  const [id, encodedRelation] = primaryParts(key);
+  return { id, relation: Graph.relationFromKey(encodedRelation) };
 };
 
 const subscriptionKey = (id: string, kind: string, detail?: string): string =>
-  detail != null
-    ? `${id}${Separators.primary}${kind}${Separators.primary}${detail}`
-    : `${id}${Separators.primary}${kind}`;
+  detail != null ? primaryKey(id, kind, detail) : primaryKey(id, kind);
 
 export const flattenExtensions = (extension: BuilderExtensions, acc: BuilderExtension[] = []): BuilderExtension[] => {
   if (Array.isArray(extension)) {

package/src/graph.test.ts

@@ -12,7 +12,7 @@ import * as Node from './node';
 
 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';
 const CHILD_RELATION_KEY = Graph.relationKey('child');
 const CHILD_INBOUND_RELATION_KEY = Graph.relationKey(Node.childRelation('inbound'));
 const ACTIONS_RELATION_KEY = Graph.relationKey('action');
@@ -602,6 +602,26 @@ describe('Graph', () => {
       expect(nodes).to.deep.equal(['root', 'test1']);
     });
 
+    test('traversal with multiple relations follows all edge types', () => {
+      const graph = Graph.make();
+      Graph.addNode(graph, {
+        id: Node.RootId,
+        type: Node.RootType,
+        nodes: [{ id: 'child1', type: 'test' }],
+      });
+      Graph.addNode(graph, { id: 'action1', type: Node.ActionType });
+      Graph.addEdge(graph, { source: Node.RootId, target: 'action1', relation: 'action' });
+
+      const nodes: string[] = [];
+      Graph.traverse(graph, {
+        relation: ['child', 'action'],
+        visitor: (node) => {
+          nodes.push(node.id);
+        },
+      });
+      expect(nodes).to.deep.equal(['root', 'child1', 'action1']);
+    });
+
     test('traverse curried', () => {
       const graph = Graph.make();
       Graph.addNode(graph, {

package/src/graph.ts

@@ -15,7 +15,7 @@ import { log } from '@dxos/log';
 import { type MakeOptional, isNonNullable } from '@dxos/util';
 
 import * as Node from './node';
-import { Separators, normalizeRelation, shallowEqual } from './util';
+import { normalizeRelation, primaryKey, primaryParts, secondaryKey, secondaryParts, shallowEqual } from './util';
 
 const graphSymbol = Symbol('graph');
 
@@ -49,8 +49,8 @@ export type GraphTraversalOptions = {
    */
   source?: string;
 
-  /** The relation to traverse graph edges. */
-  relation: Node.RelationInput;
+  /** The relation(s) to traverse graph edges. */
+  relation: Node.RelationInput | Node.RelationInput[];
 };
 
 export type GraphProps = {
@@ -183,6 +183,12 @@ class GraphImpl implements WritableGraph {
   // TODO(wittjosiah): Atom feature request, support for something akin to `ComplexMap` to allow for complex arguments.
   readonly _connections = Atom.family<string, Atom.Atom<Node.Node[]>>((key) => {
     return Atom.make((get) => {
+      const parts = key ? primaryParts(key) : [];
+      // Empty id (e.g. from `useConnections(graph, undefined, ...)`) yields a key like `\u0001child\u0002outbound`,
+      // which has 2 parts but an empty id — treat as no connections rather than throwing.
+      if (parts.length < 2 || !parts[0]) {
+        return [];
+      }
       const { id, relation } = relationFromConnectionKey(key);
       const edges = get(this._edges(id));
       return (edges[relationKey(relation)] ?? [])
@@ -194,6 +200,9 @@ class GraphImpl implements WritableGraph {
 
   readonly _actions = Atom.family<string, Atom.Atom<(Node.Action | Node.ActionGroup)[]>>((id) => {
     return Atom.make((get) => {
+      if (!id) {
+        return [];
+      }
       return get(this._connections(connectionKey(id, Node.actionRelation()))) as (Node.Action | Node.ActionGroup)[];
     }).pipe(Atom.withLabel(`graph:actions:${id}`));
   });
@@ -515,9 +524,16 @@ const traverseImpl = (graph: BaseGraph, options: GraphTraversalOptions, path: st
     return;
   }
 
-  Object.values(getConnections(graph, source, relation)).forEach((child) =>
-    traverseImpl(graph, { source: child.id, relation, visitor }, [...path, source]),
-  );
+  const relations = Array.isArray(relation) ? relation : [relation];
+  const seen = new Set<string>();
+  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, visitor }, [...path, source]);
+      }
+    }
+  }
 };
 
 /**
@@ -693,7 +709,7 @@ const expandImpl = <T extends ExpandableGraph | WritableGraph>(
 ): T => {
   const internal = getInternal(graph);
   const normalizedRelation = normalizeRelation(relation);
-  const key = `${id}${Separators.primary}${relationKey(normalizedRelation)}`;
+  const key = primaryKey(id, relationKey(normalizedRelation));
   const nodeOpt = internal._registry.get(internal._node(id));
   if (Option.isNone(nodeOpt)) {
     // Node not yet in graph: record expand to run when the node is added.
@@ -887,11 +903,10 @@ const addNodeImpl = <T extends WritableGraph>(graph: T, nodeArg: Node.NodeArg<an
       graph.onNodeChanged.emit({ id, node: newNode });
 
       // Apply any expands that were deferred because this node did not exist yet.
-      const prefix = `${id}${Separators.primary}`;
-      const toApply = [...internal._pendingExpands].filter((k) => k.startsWith(prefix));
+      const toApply = [...internal._pendingExpands].filter((k) => primaryParts(k)[0] === id);
       for (const pendingKey of toApply) {
         internal._pendingExpands.delete(pendingKey);
-        const relation = relationFromKey(pendingKey.slice(prefix.length));
+        const relation = relationFromKey(primaryParts(pendingKey)[1]);
         Record.set(internal._expanded, pendingKey, true);
         internal._onExpand?.(id, relation);
       }
@@ -1213,26 +1228,22 @@ export const make = (params?: GraphProps): Graph => {
 
 export const relationKey = (relation: Node.RelationInput): string => {
   const normalized = normalizeRelation(relation);
-  return `${normalized.kind}${Separators.secondary}${normalized.direction}`;
+  return secondaryKey(normalized.kind, normalized.direction);
 };
 
 export const relationFromKey = (encoded: string): Node.Relation => {
-  const separatorIndex = encoded.lastIndexOf(Separators.secondary);
-  invariant(separatorIndex > 0 && separatorIndex < encoded.length - 1, `Invalid relation key: ${encoded}`);
-  const kind = encoded.slice(0, separatorIndex);
-  const directionRaw = encoded.slice(separatorIndex + 1);
+  const parts = secondaryParts(encoded);
+  invariant(parts.length === 2 && parts[0].length > 0 && parts[1].length > 0, `Invalid relation key: ${encoded}`);
+  const [kind, directionRaw] = parts;
   invariant(directionRaw === 'outbound' || directionRaw === 'inbound', `Invalid relation direction: ${directionRaw}`);
   return Node.relation(kind, directionRaw);
 };
 
-const connectionKey = (id: string, relation: Node.RelationInput): string =>
-  `${id}${Separators.primary}${relationKey(relation)}`;
+const connectionKey = (id: string, relation: Node.RelationInput): string => primaryKey(id, relationKey(relation));
 
 const relationFromConnectionKey = (key: string): { id: string; relation: Node.Relation } => {
-  const separatorIndex = key.indexOf(Separators.primary);
-  invariant(separatorIndex > 0 && separatorIndex < key.length - 1, `Invalid connection key: ${key}`);
-  const id = key.slice(0, separatorIndex);
-  const encodedRelation = key.slice(separatorIndex + 1);
+  const [id, encodedRelation] = primaryParts(key);
+  invariant(id && encodedRelation, `Invalid connection key: ${key}`);
   return { id, relation: relationFromKey(encodedRelation) };
 };
 

package/src/index.ts

@@ -8,6 +8,7 @@ export * as Graph from './graph';
 export * as GraphBuilder from './graph-builder';
 export * as Node from './node';
 export * as NodeMatcher from './node-matcher';
+export { qualifyId, getParentId, getSegmentId } from './util';
 
 // TODO(wittjosiah): Direct re-export needed for portable type references.
 export type { BuilderExtensions } from './graph-builder';

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,7 +106,10 @@ 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.AnyEntity>(type: T): NodeMatcher<Entity.Entity<Schema.Schema.Type<T>>> =>
@@ -124,17 +127,20 @@ export const whenEchoType =
  * @example
  * ```ts
  * GraphBuilder.createExtension({
- *   id: 'object-settings',
+ *   id: 'object-properties',
  *   match: NodeMatcher.whenEchoObject,
  *   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,53 +151,75 @@ 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> => {
+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) {
-      if (Option.isNone(candidate(node))) {
+      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
- * // Match nodes that are either Sequences or Prompts
+ * // Match nodes that are either Sequences or Routines
  * const whenInvocable = NodeMatcher.whenAny(
  *   NodeMatcher.whenEchoTypeMatches(Sequence),
- *   NodeMatcher.whenEchoTypeMatches(Prompt.Prompt),
+ *   NodeMatcher.whenEchoTypeMatches(Routine.Routine),
  * );
  * ```
  */
-export const whenAny =
-  (...matchers: NodeMatcher[]): NodeMatcher =>
-  (node: Node.Node): Option.Option<Node.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) {
-      if (Option.isSome(candidate(node))) {
-        return Option.some(node);
+      const result = candidate(node);
+      if (Option.isSome(result)) {
+        return result;
       }
     }
     return Option.none();
@@ -260,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)),
  * );
  *
@@ -277,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.
@@ -107,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;
 };
 
@@ -147,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/scheduler.browser.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';

package/src/scheduler.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// CF Workers / Node fallback: there is no main thread to yield to.
+// scheduleTask runs the callback on the next microtask; yieldOrContinue is a microtask hop.
+
+type ScheduleOptions = { strategy?: 'smooth' | 'interactive' | 'idle'; signal?: AbortSignal };
+
+export const scheduleTask = async <T>(callback: () => T | Promise<T>, _options?: ScheduleOptions): Promise<T> => {
+  await Promise.resolve();
+  return callback();
+};
+
+export const yieldOrContinue = async (_priority: 'smooth' | 'interactive' | 'idle'): Promise<void> => {
+  await Promise.resolve();
+};