@loomwork/ui-hydration 0.0.0-stage → 0.1.1

package/src/loomEffectProvider.ts

@@ -0,0 +1,136 @@
+import { toolInputJsonSchema } from "@loomwork/agent";
+import { TypedFailure, jsonSchemaHash } from "@loomwork/core";
+import type { EffectRuntime } from "@loomwork/effect-runtime";
+import { MCP_INVOKE_TOOL_ID } from "@loomwork/plugin-mcp";
+import { SANDBOX_TOOL_ID } from "@loomwork/plugin-sandbox";
+import type { DataProvider } from "./dataProvider";
+
+/** The kind id of a step whose target is a registered loom effect. */
+export const LOOM_EFFECT_KIND = "loom-effect";
+
+/**
+ * The failure channel for a target the host did not declare. Served to a client as the fixed
+ * `tool-targetUnregistered` code — never the target id or any text of the effect's own.
+ */
+export const TARGET_UNREGISTERED = "targetUnregistered";
+
+/**
+ * The failure channel for an effect that itself raised `schemaDrift` (e.g. a target wrapping
+ * `mcp.invoke`). Only the provider's OWN pin check may emit `schemaDrift`: a target's drift
+ * would otherwise be read as this kind's pin drift, and a repair would re-pin to the inner
+ * hash and flip forever. Served as the `tool-targetFailed` code (`tool-failed` to a client).
+ */
+export const TARGET_FAILED = "targetFailed";
+
+/** The schema of an effect's input, as `tool$({ inputSchema })` takes it. */
+export type EffectInputSchema = Parameters<typeof toolInputJsonSchema>[0];
+
+/**
+ * The pin of an effect's input contract: `jsonSchemaHash` (the one canonical hash MCP pins use)
+ * of the schema's JSON-Schema form. Use it BOTH when the host builds a planner `CapabilityRef`
+ * (`toolSchemaHash`) and when it lists the effect for {@link loomEffectProvider} (via
+ * `{ inputSchema }`) so the two come from one source: editing the effect's zod schema moves
+ * the pin, and every stored step drifts.
+ */
+export function effectPin(schema: EffectInputSchema): string {
+  return jsonSchemaHash(toolInputJsonSchema(schema));
+}
+
+/** The effect kinds a data read can never reach: a person's answer, a model call. */
+const REFUSED_KINDS: ReadonlySet<string> = new Set(["human", "llm"]);
+
+/**
+ * Effects hydration already reaches through a dedicated plane (the MCP kind, the sandbox
+ * reshaper). Exposing them as a data TARGET would let a stored step bypass the pin and the
+ * reshaping boundary, so a host cannot list them.
+ */
+const RESERVED_TARGETS: ReadonlySet<string> = new Set([MCP_INVOKE_TOOL_ID, SANDBOX_TOOL_ID]);
+
+/** How a listed effect's pin is obtained: computed from its schema, or asserted by the host. */
+export type EffectEntry =
+  | { readonly inputSchema: NonNullable<EffectInputSchema> }
+  | { readonly pin: string };
+
+export interface LoomEffectProviderOptions {
+  /**
+   * The runtime the effects are registered with. Read at CONSTRUCTION only (`has` / `modeOf` /
+   * `kindOf`): hydration is a read path that runs per viewer load, unmemoised and retried, so
+   * every listed effect must be registered, explicitly `mode: "ambient"` (ADR 0073 — loom
+   * refuses only an explicit `journaled` one on the transient path, so an UNDECLARED mode is
+   * not a read declaration and is refused here), and not a `human` / `llm` kind.
+   */
+  readonly runtime: Pick<EffectRuntime, "has" | "modeOf" | "kindOf">;
+  /**
+   * The effects a stored step may name. `{ inputSchema }` computes the pin with
+   * {@link effectPin} (a schema change drifts every stored step); `{ pin }` is HOST-ASSERTED —
+   * nothing checks it against the effect, so the host owns changing it when callers must
+   * re-author. A step naming an effect not listed is refused (`tool-targetUnregistered`) and
+   * nothing runs. Pins must be non-empty.
+   */
+  readonly effects: Readonly<Record<string, EffectEntry>>;
+}
+
+/**
+ * The `loom-effect` kind: a step whose `toolName` is the id of an effect registered with the
+ * loom effect runtime (a `tool$`, a read-model query effect, an A2A call…), invoked through the
+ * SAME transient invoker and therefore the same authoriser, budget and principal as the MCP
+ * kind. Construction refuses an effect that is unregistered, not explicitly `ambient`, or a
+ * `human` / `llm` kind.
+ *
+ * An effect's call is not memoised across a pass (the in-pass memo coalesces `mcp.invoke` only:
+ * an arbitrary effect is not known to be a pure read), so two steps naming one effect with equal
+ * arguments call it twice. (Memoising `ambient` effects is a possible follow-up.)
+ *
+ * A persisted experience crosses a version boundary only through the log: an older in-memory
+ * `executeProvider` / `seal` that predates kinds would run a kinded step as an MCP call.
+ */
+export function loomEffectProvider(options: LoomEffectProviderOptions): DataProvider {
+  const { runtime } = options;
+  const pins = new Map<string, string>();
+  for (const [id, entry] of Object.entries(options.effects)) {
+    if (id === "") throw new TypeError("loomEffectProvider: an effect id is empty");
+    if (RESERVED_TARGETS.has(id))
+      throw new TypeError(
+        `loomEffectProvider: "${id}" is reached through its own plane (the MCP kind / the sandbox) and cannot be a data target`
+      );
+    if (!runtime.has(id))
+      throw new TypeError(`loomEffectProvider: effect "${id}" is not registered with the runtime`);
+    if (runtime.modeOf(id) !== "ambient")
+      throw new TypeError(
+        `loomEffectProvider: effect "${id}" is not declared mode "ambient" (ADR 0073); a data read may not run an undeclared or journaled effect`
+      );
+    const kind = runtime.kindOf(id);
+    if (kind !== undefined && REFUSED_KINDS.has(kind))
+      throw new TypeError(
+        `loomEffectProvider: effect "${id}" is a ${kind} effect, not a data read`
+      );
+    const pin =
+      entry !== null && typeof entry === "object" && "inputSchema" in entry
+        ? effectPin(entry.inputSchema)
+        : (entry as { pin?: unknown } | null)?.pin;
+    if (typeof pin !== "string" || pin === "")
+      throw new TypeError(`loomEffectProvider: effect "${id}" needs a non-empty pin`);
+    pins.set(id, pin);
+  }
+  return Object.freeze<DataProvider>({
+    kind: LOOM_EFFECT_KIND,
+    async invoke(call, invoker, opts) {
+      const current = pins.get(call.target);
+      if (current === undefined)
+        throw new TypedFailure(TARGET_UNREGISTERED, { target: call.target });
+      if (current !== call.expectedPin)
+        throw new TypedFailure("schemaDrift", {
+          toolName: call.target,
+          expectedSchemaHash: call.expectedPin,
+          observedHash: current,
+        });
+      try {
+        return await invoker.invokeTransient(call.target, call.args, opts);
+      } catch (e) {
+        if (e instanceof TypedFailure && e.channel === "schemaDrift")
+          throw new TypedFailure(TARGET_FAILED, { target: call.target });
+        throw e;
+      }
+    },
+  });
+}

package/src/params.ts

@@ -0,0 +1,314 @@
+import { canonicalJson, fnv1a64 } from "@loomwork/core";
+import type { Finding, MCPToolNode, ProviderSpec } from "@loomwork/ui-core";
+import { resolveArguments } from "./plan";
+
+// ── Per-load params and relative time ─────────────────────────────────────────
+// A step opts arguments INTO being overridden (`MCPToolNode.overridable`). A load's params
+// replace exactly those — never an argument holding a `{{steps.…}}` template (that value is
+// another step's output; a param overwriting it would silently cut the graph), and never with a
+// value that is itself a template (a param is a literal). Relative-time tokens (`$now`,
+// `$now-7d`, `$now+1h`) resolve against ONE injected instant per load, so two steps asking for
+// "the last day" in one pass ask the same question. Arguments are prepared in a fixed order:
+// params → time tokens → templates → the host's argument hook.
+
+export type LoadParams = Readonly<Record<string, unknown>>;
+
+/** A time-range default a host may pass as `ControllerOptions.defaultParams`: the last 24 hours, relative to each pass. */
+export const DEFAULT_TIME_RANGE: LoadParams = Object.freeze({ from: "$now-24h", to: "$now" });
+
+/** Token-shaped: `$now` not followed by a word character. `$nowcast` is an ordinary string. */
+const TOKEN_LIKE = /^\$now(?![A-Za-z0-9_])/;
+const TIME_TOKEN = /^\$now(?:([+-])(\d{1,9})([smhdw]))?$/;
+const UNIT_MS: Readonly<Record<string, number>> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 604_800_000,
+};
+
+const bad = (code: string, message: string): Finding => ({ code, severity: "error", message });
+const note = (code: string, message: string): Finding => ({ code, severity: "warn", message });
+
+/** An async argument hook returns one of these: `prepareArguments` never awaits it. */
+function isThenable(v: unknown): v is PromiseLike<unknown> {
+  return (
+    v !== null && typeof v === "object" && typeof (v as { then?: unknown }).then === "function"
+  );
+}
+
+/** `$now`, `$now-7d`, `$now+1h` (units s m h d w) as an ISO-8601 instant; `undefined` otherwise. */
+export function resolveTimeToken(token: string, now: number): string | undefined {
+  const m = TIME_TOKEN.exec(token);
+  if (!m) return undefined;
+  const offset =
+    m[1] === undefined
+      ? 0
+      : (m[1] === "-" ? -1 : 1) * Number(m[2]) * (UNIT_MS[m[3] as string] as number);
+  const at = new Date(now + offset);
+  // Past ±8.64e15 ms a Date is invalid and `toISOString` would throw: refuse instead.
+  return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+
+/** Every token-shaped string leaf is resolved, or the whole value is refused. Other leaves pass. */
+export function resolveTimeTokens(
+  value: unknown,
+  now: number,
+  where: string
+): { ok: true; value: unknown } | { ok: false; finding: Finding } {
+  let failure: Finding | undefined;
+  const visit = (v: unknown): unknown => {
+    if (failure) return v;
+    if (typeof v === "string") {
+      if (!TOKEN_LIKE.test(v)) return v;
+      const iso = resolveTimeToken(v, now);
+      if (iso !== undefined) return iso;
+      failure = bad(
+        "invalid-time-token",
+        `${where}: "${v.slice(0, 64)}" is not a relative-time token ($now, $now-7d, $now+1h; units s m h d w)`
+      );
+      return v;
+    }
+    if (Array.isArray(v)) return v.map(visit);
+    if (v !== null && typeof v === "object")
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, visit(x)]));
+    return v;
+  };
+  const out = visit(value);
+  return failure ? { ok: false, finding: failure } : { ok: true, value: out };
+}
+
+const STEP_REF = /\{\{\s*steps\./;
+function containsStepTemplate(v: unknown): boolean {
+  if (typeof v === "string") return STEP_REF.test(v);
+  if (Array.isArray(v)) return v.some(containsStepTemplate);
+  if (v !== null && typeof v === "object") return Object.values(v).some(containsStepTemplate);
+  return false;
+}
+
+/** A plain object `canonicalJson` can represent (no NaN/±Infinity, bigint, function, over-deep nest). */
+export function checkParams(params: unknown): Finding | undefined {
+  if (params === null || typeof params !== "object" || Array.isArray(params))
+    return bad("invalid-params", "params must be a plain object");
+  try {
+    canonicalJson(params);
+    return undefined;
+  } catch (e) {
+    return bad(
+      "invalid-params",
+      `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+}
+
+/** Canonical identity of a param set (key order irrelevant); `""` for none. Throws only on what `checkParams` refuses. */
+export function paramsKey(params: LoadParams): string {
+  return Object.keys(params).length === 0 ? "" : fnv1a64(canonicalJson(params));
+}
+
+/** Every argument name any step of the provider declares overridable, sorted. */
+export function providerParams(spec: ProviderSpec): string[] {
+  const names = new Set<string>();
+  for (const step of spec.executionGraph) for (const n of step.overridable ?? []) names.add(n);
+  return [...names].sort();
+}
+
+/**
+ * The named params the set actually holds (own keys only), as a fresh, FROZEN object — this is
+ * the object every step's `prepareArguments` call (and its argument hook) receives as `ctx.params`
+ * for the whole load, so a hook mutating it would leak into every other step's view of the load.
+ * Reads `params[n]` once per name: on params that crossed a trust boundary, snapshot them first
+ * (`snapshotParams`) — a live accessor that answered safely for an earlier, separate check (e.g.
+ * `checkParams` alone) is free to answer differently by the time THIS read runs.
+ */
+export function pickParams(params: LoadParams, names: readonly string[]): LoadParams {
+  return Object.freeze(
+    Object.fromEntries(names.filter((n) => Object.hasOwn(params, n)).map((n) => [n, params[n]]))
+  );
+}
+
+/**
+ * ONE plain, detached copy of untrusted params — a JSON round-trip through `canonicalJson`, so a
+ * value it refuses (a function, bigint, non-finite number, a cycle, past the depth cap) is caught
+ * HERE, and `JSON.parse` builds the result from that already-captured string alone: nothing
+ * downstream (`checkParams`, `pickParams`, `relevantParams`) ever reads a property of the SOURCE
+ * object again. Required wherever params cross a trust boundary (`serveHandle(s)`) — validating a
+ * live accessor and then separately picking named keys off it re-reads it, and a hostile getter is
+ * free to answer only the validating read safely and answer a later, picking read with something
+ * else entirely (observed: a plain value for the first two reads, a function for the third).
+ */
+export function snapshotParams(
+  params: unknown
+): { ok: true; params: LoadParams } | { ok: false; finding: Finding } {
+  if (params === null || typeof params !== "object" || Array.isArray(params))
+    return { ok: false, finding: bad("invalid-params", "params must be a plain object") };
+  try {
+    return { ok: true, params: JSON.parse(canonicalJson(params)) as LoadParams };
+  } catch (e) {
+    return {
+      ok: false,
+      finding: bad(
+        "invalid-params",
+        `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`
+      ),
+    };
+  }
+}
+
+/** The params this provider can use: everything else cannot change its answer. */
+export function relevantParams(spec: ProviderSpec, params: LoadParams): LoadParams {
+  return pickParams(params, providerParams(spec));
+}
+
+export function applyParams(
+  node: MCPToolNode,
+  params: LoadParams
+): { args: Record<string, unknown>; findings: Finding[] } {
+  const { args, findings } = applyParamsDetailed(node, params);
+  return { args, findings };
+}
+
+/** {@link applyParams}, plus which top-level arguments a param actually replaced (U9b needs them). */
+export function applyParamsDetailed(
+  node: MCPToolNode,
+  params: LoadParams
+): { args: Record<string, unknown>; findings: Finding[]; replaced: string[] } {
+  const names = node.overridable ?? [];
+  const findings: Finding[] = [];
+  const replaced: string[] = [];
+  if (names.length === 0) return { args: node.arguments, findings, replaced };
+  // A Map, then `Object.fromEntries`: every write is CreateDataProperty, so an argument named
+  // `__proto__` lands as an own key instead of setting a prototype.
+  const args = new Map(Object.entries(node.arguments));
+  for (const name of names) {
+    if (!Object.hasOwn(params, name)) continue;
+    if (containsStepTemplate(args.get(name))) {
+      findings.push(
+        note(
+          "param-templated",
+          `step "${node.stepId}": argument "${name}" is a {{steps.…}} template — another step's output — so no param replaces it`
+        )
+      );
+      continue;
+    }
+    const value = params[name];
+    if (containsStepTemplate(value)) {
+      findings.push(
+        note(
+          "param-template-refused",
+          `step "${node.stepId}": the param for "${name}" contains a {{steps.…}} template; a param is a literal, so it is not applied`
+        )
+      );
+      continue;
+    }
+    args.set(name, value);
+    replaced.push(name);
+  }
+  return { args: Object.fromEntries(args), findings, replaced };
+}
+
+export interface ArgumentHookContext {
+  readonly handle: string;
+  readonly stepId: string;
+  readonly toolName: string;
+  /**
+   * The step's data-provider kind; absent for an MCP step. A hook that branches on `toolName`
+   * must also read this: an MCP tool `x` and a loom effect `x` are different targets.
+   */
+  readonly kind?: string;
+  /**
+   * The load's params as declared — under `executeProvider`, only those some step of the provider
+   * declares overridable — with time tokens NOT resolved (`now` is the instant they resolve against).
+   */
+  readonly params: LoadParams;
+  /** The instant this load resolved its time tokens against (epoch ms). */
+  readonly now: number;
+}
+
+/** The host's last word on a step's arguments: after params, time tokens and templates; before the call. */
+export type ArgumentHook = (
+  args: Record<string, unknown>,
+  ctx: ArgumentHookContext
+) => Record<string, unknown>;
+
+export interface PrepareContext {
+  readonly handle: string;
+  readonly params: LoadParams;
+  readonly now: number;
+  readonly hook?: ArgumentHook;
+  /**
+   * Runs after params are applied and before time tokens, templates or the hook (U9b's content-reference
+   * guard, `contentRefs.ts`, is the one user); a returned finding refuses the step. `replaced` names the
+   * top-level arguments a param actually replaced.
+   */
+  readonly guard?: (
+    node: MCPToolNode,
+    applied: { readonly args: Record<string, unknown>; readonly replaced: readonly string[] }
+  ) => Finding | undefined;
+  /** Rewrites the arguments after templates resolve and before the hook (U9b strips JSON null at marked paths). */
+  readonly finish?: (args: Record<string, unknown>) => Record<string, unknown>;
+}
+
+export function prepareArguments(
+  node: MCPToolNode,
+  outputs: ReadonlyMap<string, unknown>,
+  ctx: PrepareContext
+):
+  | { ok: true; args: Record<string, unknown>; findings: Finding[] }
+  | { ok: false; finding: Finding } {
+  const applied = applyParamsDetailed(node, ctx.params);
+  const refused = ctx.guard?.(node, applied);
+  if (refused !== undefined) return { ok: false, finding: refused };
+  const timed = resolveTimeTokens(applied.args, ctx.now, `step "${node.stepId}"`);
+  if (!timed.ok) return timed;
+  const templated = resolveArguments(
+    { ...node, arguments: timed.value as Record<string, unknown> },
+    outputs
+  );
+  if (!templated.ok) return templated;
+  const finished = ctx.finish ? ctx.finish(templated.args) : templated.args;
+  if (ctx.hook === undefined) return { ok: true, args: finished, findings: applied.findings };
+  let hooked: unknown;
+  try {
+    hooked = ctx.hook(finished, {
+      handle: ctx.handle,
+      stepId: node.stepId,
+      toolName: node.toolName,
+      ...(node.kind !== undefined && { kind: node.kind }),
+      params: ctx.params,
+      now: ctx.now,
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      finding: bad(
+        "argument-hook-failed",
+        `step "${node.stepId}": the argument hook threw: ${e instanceof Error ? e.message : String(e)}`
+      ),
+    };
+  }
+  if (isThenable(hooked)) {
+    // The step callback never awaits a hook (it is documented as synchronous): swallow whatever
+    // this thenable eventually does, so an async hook never surfaces as an unhandled rejection.
+    hooked.then(
+      () => {},
+      () => {}
+    );
+    return {
+      ok: false,
+      finding: bad(
+        "argument-hook-failed",
+        `step "${node.stepId}": the argument hook returned a thenable — hooks must return the arguments object synchronously, not a Promise`
+      ),
+    };
+  }
+  if (hooked === null || typeof hooked !== "object" || Array.isArray(hooked))
+    return {
+      ok: false,
+      finding: bad(
+        "argument-hook-failed",
+        `step "${node.stepId}": the argument hook returned ${hooked === null ? "null" : Array.isArray(hooked) ? "an array" : typeof hooked}, not an arguments object`
+      ),
+    };
+  return { ok: true, args: hooked as Record<string, unknown>, findings: applied.findings };
+}

package/src/path.ts

@@ -0,0 +1,26 @@
+// ── Binding path ↔ hydration handle, browser-safe ────────────────────────────────
+// A compiled widget binds to `values.<handle>`. `@loomwork/ui-core` owns that spelling for the
+// compile side (`hydrationPath`), but the client entry must not pull core's runtime module graph
+// into a browser bundle, and core cannot import hydration (hydration depends on core). So the
+// client entry carries its own definition of the prefix and the inverse, pinned against core's
+// twice: at compile time (the `satisfies` below, type-only, erased at build) and by
+// `path.test.ts`, which compares the values and round-trips `hydrationPath`.
+
+import type { HYDRATION_VALUES_PREFIX as CoreValuesPrefix } from "@loomwork/ui-core";
+
+/** The hydration projection's top-level key; equal to `@loomwork/ui-core`'s constant of the same name. */
+export const HYDRATION_VALUES_PREFIX = "values" satisfies typeof CoreValuesPrefix;
+
+/**
+ * The hydration handle a binding path names: the exact inverse of core's `hydrationPath`.
+ * `undefined` for a path not of the form `values.<handle>` with a non-empty handle (including the
+ * bare prefix and `values.`). Everything after the first `values.` is the handle, spelled exactly
+ * as `hydrationPath` spelled it. Note: blueprint-runtime resolves a binding path by splitting on
+ * `.`, so a handle that itself contains a dot round-trips here but will not resolve at render time —
+ * keep handles dot-free. A reserved handle (`__proto__` etc.) is returned as-is; the store refuses it.
+ */
+export function handleOfPath(path: string): string | undefined {
+  const head = `${HYDRATION_VALUES_PREFIX}.`;
+  if (!path.startsWith(head) || path.length === head.length) return undefined;
+  return path.slice(head.length);
+}

package/src/plan.ts

@@ -0,0 +1,197 @@
+import type { Finding, MCPToolNode } from "@loomwork/ui-core";
+
+// ── Graph scheduling and argument templating ──────────────────────────────────
+// A ProviderSpec's executionGraph is a DAG of MCP steps. Steps run in topological WAVES (every
+// step in a wave has all its in-graph dependencies in earlier waves). A dependency naming a step
+// outside the graph is treated as satisfied — the planner may reference a step it pruned — and a
+// cycle is reported, never looped over. Arguments may embed `{{steps.<id>.output.<path>}}`,
+// resolved from an earlier step's raw output over OWN properties only: the path is model-written
+// and walked over a tool response, so an unguarded walk is a prototype-pollution read. An index
+// past the end of a present array is not a bad path — the upstream answered with no such row —
+// and is reported apart from every other miss (`walkPath`), so it can publish `empty`.
+
+/**
+ * Kahn's algorithm over step IDS, O(V + E): in-degree counts (distinct in-graph dependencies per
+ * step) and a dependents list built once, then a FIFO of ids whose level never decreases. A step's
+ * wave is 1 + the latest wave among its in-graph dependencies (0 with none); an id is placed at the
+ * earliest wave any step carrying it is ready. Waves are then filled in the input's own order, so a
+ * wave lists its steps exactly as the input does. This is the semantics of the original
+ * re-filtering loop, pinned by an equivalence test: a step whose id another step already placed in
+ * an EARLIER wave never runs (a duplicate id), and `cycle` lists — in input order — every step
+ * whose id is never placed (a cycle, or anything behind one).
+ */
+export function topoWaves(nodes: readonly MCPToolNode[]): {
+  waves: MCPToolNode[][];
+  cycle: string[];
+} {
+  const ids = new Set(nodes.map((n) => n.stepId));
+  const pending = new Array<number>(nodes.length);
+  const readyAt = new Array<number>(nodes.length).fill(-1);
+  const latestDep = new Array<number>(nodes.length).fill(-1);
+  const dependents = new Map<string, number[]>();
+  const placedAt = new Map<string, number>();
+  const queue: string[] = [];
+  const ready = (i: number, level: number): void => {
+    readyAt[i] = level;
+    const id = (nodes[i] as MCPToolNode).stepId;
+    if (placedAt.has(id)) return;
+    placedAt.set(id, level);
+    queue.push(id);
+  };
+  nodes.forEach((n, i) => {
+    const deps = new Set(n.dependsOn.filter((d) => ids.has(d)));
+    pending[i] = deps.size;
+    for (const d of deps) {
+      const list = dependents.get(d);
+      if (list === undefined) dependents.set(d, [i]);
+      else list.push(i);
+    }
+  });
+  nodes.forEach((_, i) => {
+    if (pending[i] === 0) ready(i, 0);
+  });
+  for (let head = 0; head < queue.length; head++) {
+    const id = queue[head] as string;
+    const level = placedAt.get(id) as number;
+    for (const i of dependents.get(id) ?? []) {
+      latestDep[i] = Math.max(latestDep[i] as number, level);
+      pending[i] = (pending[i] as number) - 1;
+      if (pending[i] === 0) ready(i, (latestDep[i] as number) + 1);
+    }
+  }
+  const waves: MCPToolNode[][] = [];
+  const cycle: string[] = [];
+  nodes.forEach((n, i) => {
+    const at = placedAt.get(n.stepId);
+    if (at === undefined) cycle.push(n.stepId);
+    else if (readyAt[i] === at) {
+      while (waves.length <= at) waves.push([]);
+      (waves[at] as MCPToolNode[]).push(n);
+    }
+  });
+  return { waves, cycle };
+}
+
+export function terminalSteps(nodes: readonly MCPToolNode[]): MCPToolNode[] {
+  const depended = new Set(nodes.flatMap((n) => n.dependsOn));
+  return nodes.filter((n) => !depended.has(n.stepId));
+}
+
+const SEGMENT = /^([^[\]]+)((?:\[\d+\])*)$/;
+
+/**
+ * Why a path walk found nothing. `out-of-range`: the walk stopped at an `[i]` applied to a value
+ * that IS an array, with `i >= length` — the path is right, the upstream just has no such row (the
+ * row count is DATA). `absent`: every other miss — a missing own key, `null` or a primitive
+ * mid-path, an index on a non-array, a malformed segment — a BAD PATH.
+ */
+export type PathMiss = "out-of-range" | "absent";
+
+/** Dotted path with optional `[i]` indices, own properties only. A present `null` resolves to `null`. */
+export function walkPath(
+  obj: unknown,
+  dotted: string
+): { ok: true; value: unknown } | { ok: false; cause: PathMiss } {
+  const absent = { ok: false, cause: "absent" } as const;
+  let cur: unknown = obj;
+  for (const part of dotted.split(".")) {
+    const m = SEGMENT.exec(part);
+    if (!m || cur === null || typeof cur !== "object") return absent;
+    const key = m[1] as string;
+    if (!Object.hasOwn(cur, key)) return absent;
+    cur = (cur as Record<string, unknown>)[key];
+    for (const idx of (m[2] ?? "").match(/\d+/g) ?? []) {
+      if (!Array.isArray(cur)) return absent;
+      const i = Number(idx);
+      if (i >= cur.length) return { ok: false, cause: "out-of-range" };
+      cur = cur[i];
+    }
+  }
+  return { ok: true, value: cur };
+}
+
+/** `walkPath`'s value, or `undefined` when anything is missing. */
+export function resolvePath(obj: unknown, dotted: string): unknown {
+  const r = walkPath(obj, dotted);
+  return r.ok ? r.value : undefined;
+}
+
+export const STEP_TEMPLATE = /^\{\{steps\.([A-Za-z0-9_-]+)\.output(?:\.(.+))?\}\}$/;
+
+/**
+ * Every step id `arguments` references through a `{{steps.<id>.output…}}` template, in first-seen
+ * order, deduplicated — the same template grammar `resolveArguments` substitutes, so a planner can
+ * check a graph it builds before it ships. At execution a reference resolves only against a step
+ * in a STRICTLY EARLIER `topoWaves` wave than the referencing step; a step outside the graph, or in
+ * the same or a later wave, has no output yet and is `unresolved-step-reference`.
+ */
+export function stepReferences(args: unknown): string[] {
+  const found = new Set<string>();
+  const visit = (v: unknown): void => {
+    if (typeof v === "string") {
+      const m = STEP_TEMPLATE.exec(v);
+      if (m) found.add(m[1] as string);
+    } else if (Array.isArray(v)) for (const x of v) visit(x);
+    else if (v !== null && typeof v === "object") for (const x of Object.values(v)) visit(x);
+  };
+  visit(args);
+  return [...found];
+}
+
+/**
+ * Substitute every `{{steps.<id>.output.<path>}}` in the step's arguments. EVERY template is
+ * walked: a bad path anywhere (`absent`, or a step with no output) is `unresolved-step-reference`
+ * (an error) and wins; otherwise an index past the end of a present upstream array is
+ * `upstream-empty` (a warn — the upstream answered with no such row; loom ADR 0100's `empty`).
+ */
+export function resolveArguments(
+  node: MCPToolNode,
+  outputs: ReadonlyMap<string, unknown>
+): { ok: true; args: Record<string, unknown> } | { ok: false; finding: Finding } {
+  let bad: Finding | undefined;
+  let empty: Finding | undefined;
+  const visit = (v: unknown): unknown => {
+    if (typeof v === "string") {
+      const m = STEP_TEMPLATE.exec(v);
+      if (!m) return v;
+      const stepId = m[1] as string;
+      if (!outputs.has(stepId)) {
+        bad ??= {
+          code: "unresolved-step-reference",
+          severity: "error",
+          message: `step "${node.stepId}" references "${stepId}", which has no output`,
+        };
+        return v;
+      }
+      const path = m[2];
+      const out: ReturnType<typeof walkPath> =
+        path === undefined
+          ? { ok: true, value: outputs.get(stepId) }
+          : walkPath(outputs.get(stepId), path);
+      // A present `undefined` (never produced by JSON) is treated as nothing, as before.
+      if (out.ok && out.value !== undefined) return out.value;
+      if (!out.ok && out.cause === "out-of-range")
+        empty ??= {
+          code: "upstream-empty",
+          severity: "warn",
+          message: `step "${node.stepId}" references "${stepId}" at path "${path ?? ""}": the upstream has no such row`,
+        };
+      else
+        bad ??= {
+          code: "unresolved-step-reference",
+          severity: "error",
+          message: `step "${node.stepId}" references "${stepId}" at path "${path ?? ""}", which resolves to nothing`,
+        };
+      return v;
+    }
+    if (Array.isArray(v)) return v.map(visit);
+    // `Object.fromEntries` writes with CreateDataProperty: an own `__proto__` argument stays an
+    // own key instead of becoming the args object's prototype (an assignment would set it).
+    if (v !== null && typeof v === "object")
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, visit(x)]));
+    return v;
+  };
+  const args = visit(node.arguments) as Record<string, unknown>;
+  const failure = bad ?? empty;
+  return failure ? { ok: false, finding: failure } : { ok: true, args };
+}