@nhtio/adk/batteries/orchestration/plan

The IR's runtime helpers: pure, graph-shaped predicates and guards.

Remarks

This module is the shared vocabulary that WP 04's freeze validation and WP 07's executor both call. It performs NO validation policy itself and throws nothing — it answers questions about a graph. Every export is a pure function over {nodes, edges} (a RawPlanView or any structural subset carrying those two arrays), so the same code path serves a full folded view and a hand-built slice.

The functions here are deliberately small and single-purpose. Policy — "exactly one entry", "the graph is acyclic", "every join is a diamond" — lives in the freeze validator, which composes these primitives; the executor composes them to decide what fires next. Neither reimplements a graph walk.

Interfaces

Interface	Description
PlanGraphView	The minimal structural surface these helpers read. A RawPlanView satisfies it; so does any {nodes, edges} subset. Accepting the subset keeps the helpers usable on slices and test fixtures without forcing a full view.

Functions

Function	Description
entryNodes	Every node of kind 'entry'.
findCycle	Find a cycle in the graph, over EVERY edge handle.
handleAppliesTo	Whether an edge handle may be used on an edge leaving a node of a given kind.
immediateDominator	The immediate dominator of a node, relative to an entry.
incoming	The edges entering a node.
isPlanEdge	True when v is a well-shaped PlanEdge.
isPlanNode	True when v is a well-shaped PlanNode.
isValidEdgeId	Whether a string is a valid edge id.
isValidNodeId	Whether a string is a valid node id.
nodeById	Look up a node by id.
outgoing	The edges leaving a node.
reachableFrom	The forward closure from a start node over ALL edge handles.
readPath	Read a dot-path from a value, with a per-segment prototype-pollution guard.
routesBetween	All distinct simple paths from one node to another.