@procedures/compiler 0.0.0-stage → 0.2.3

package/src/fold.ts

@@ -0,0 +1,136 @@
+/**
+ * The fold pass (optional): a pure core call with a literal input becomes its value.
+ *
+ * The pass folds a call only when all of these conditions are true:
+ *
+ * - The manifest entry is the description of a core procedure of `@procedures/client`. Thus the
+ *   host has the same code.
+ * - Its effects are `reads: []` and `writes: []`.
+ * - It does not take raw input, and it is not data-driven.
+ * - Its value is a primitive.
+ *
+ * The pass starts the procedure here with `invokeProcedure()`, so the validation and the output
+ * schema apply. A call that fails stays a call: the run gives its error.
+ *
+ * A folded call does not start at run time: an interceptor, a trace and the admission do not see
+ * it. A host that needs each call in its trace does not fold.
+ */
+
+import { invokeProcedure, isReadOnly, outputValue, effectsOf } from "@procedures/client/browser";
+import type { ChainStep, IRNode, ItemsSpec, LiteralNode } from "./ir.js";
+import type { ProcedureFacts } from "./facts.js";
+import { mergeExtra } from "./normalize.js";
+
+/** The value of a node when it is fully known before the run. */
+function staticValue(node: IRNode): { known: true; value: unknown } | { known: false } {
+  switch (node.kind) {
+    case "literal":
+      return { known: true, value: node.value };
+    case "object": {
+      const entries: Array<[string, unknown]> = [];
+      for (const entry of node.entries) {
+        const value = staticValue(entry.value);
+        if (!value.known) return value;
+        entries.push([entry.key, value.value]);
+      }
+      return { known: true, value: Object.fromEntries(entries) };
+    }
+    case "array": {
+      const values: unknown[] = [];
+      for (const item of node.items) {
+        const value = staticValue(item);
+        if (!value.known) return value;
+        values.push(value.value);
+      }
+      return { known: true, value: values };
+    }
+    default:
+      return { known: false };
+  }
+}
+
+function isPrimitive(value: unknown): boolean {
+  return value === null || (typeof value !== "object" && typeof value !== "function" && typeof value !== "symbol");
+}
+
+/** The result of the pass: the new tree and the pointers of the folded calls. */
+export interface FoldResult {
+  readonly root: IRNode;
+  readonly folded: readonly string[];
+}
+
+/** This function folds the pure core calls with literal inputs. */
+export async function foldProgram(root: IRNode, facts: ProcedureFacts): Promise<FoldResult> {
+  const folded: string[] = [];
+
+  const items = async (spec: ItemsSpec): Promise<ItemsSpec> =>
+    spec.kind === "list" ? { kind: "list", items: await Promise.all(spec.items.map(fold)) } : { kind: "value", value: await fold(spec.value) };
+
+  const tryFold = async (node: Extract<IRNode, { kind: "call" }>): Promise<IRNode> => {
+    const input = staticValue(node.input);
+    if (!input.known) return node;
+    const entry = facts.entry(node.path);
+    const procedure = facts.core(node.path);
+    if (!entry || !procedure || entry.dataDriven || facts.rawInput(node.path)) return node;
+    const effects = effectsOf(procedure);
+    if (!isReadOnly(effects) || (effects?.reads ?? ["unknown"]).length > 0) return node;
+    try {
+      const value = await outputValue(await invokeProcedure(procedure, mergeExtra(input.value, node.extra)), node.path);
+      if (!isPrimitive(value)) return node;
+      folded.push(node.pointer);
+      const literal: LiteralNode = { kind: "literal", value, origin: "fold", pointer: node.pointer };
+      return literal;
+    } catch {
+      return node;
+    }
+  };
+
+  const fold = async (node: IRNode): Promise<IRNode> => {
+    switch (node.kind) {
+      case "literal":
+      case "reference":
+      case "fail":
+        return node;
+      case "object":
+        return { ...node, entries: await Promise.all(node.entries.map(async (entry) => ({ key: entry.key, value: await fold(entry.value) }))) };
+      case "array":
+        return { ...node, items: await Promise.all(node.items.map(fold)) };
+      case "call":
+        return tryFold({ ...node, input: await fold(node.input) });
+      case "deferred":
+        return { ...node, input: await fold(node.input) };
+      case "dynamic":
+        return node;
+      case "chain": {
+        const steps: ChainStep[] = [];
+        for (const step of node.steps) steps.push({ ...step, node: await fold(step.node) });
+        return { ...node, steps, initialInput: node.initialInput ? await fold(node.initialInput) : undefined };
+      }
+      case "parallel":
+        return { ...node, tasks: await Promise.all(node.tasks.map(fold)) };
+      case "conditional":
+        return {
+          ...node,
+          condition: await fold(node.condition),
+          then: node.then ? await fold(node.then) : undefined,
+          else: node.else ? await fold(node.else) : undefined,
+        };
+      case "try":
+        return { ...node, try: await fold(node.try), catch: await fold(node.catch) };
+      case "and":
+      case "or":
+        return { ...node, values: await Promise.all(node.values.map(fold)) };
+      case "map":
+        return { ...node, items: await items(node.items), fn: node.fn ? await fold(node.fn) : undefined };
+      case "reduce":
+        return {
+          ...node,
+          items: node.items ? await items(node.items) : undefined,
+          initial: await fold(node.initial),
+          fn: node.fn ? await fold(node.fn) : undefined,
+        };
+    }
+  };
+
+  return { root: await fold(root), folded };
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export { checkProgram, compileProgram } from "./program.js";
+export { programCheckInterceptor } from "./interceptor.js";
+export { toMermaid, diagramProgram, mermaidText } from "./mermaid.js";
+export type { MermaidOptions, DiagramResult } from "./mermaid.js";
+export { explainProgram } from "./explain.js";
+export type { CallExplanation, CallKind, ProgramExplanation } from "./explain.js";
+export { toOpenRpc, OPENRPC_VERSION } from "./openrpc.js";
+export type { OpenRpcDocument, OpenRpcMethod, OpenRpcContentDescriptor, OpenRpcOptions } from "./openrpc.js";
+export { toTypeScriptSdk, schemaToType } from "./typescript-sdk.js";
+export type { TypeScriptSdkOptions } from "./typescript-sdk.js";
+export type { ProgramCheckOptions, ObservableRegistry } from "./interceptor.js";
+export type { CheckOptions, CheckResult, CompileOptions, CompileResult, MustEffects } from "./program.js";
+export { manifestFacts, registryFacts, withDefinitions, coreProcedureOf, entryTakesRawInput } from "./facts.js";
+export type { ProcedureFacts, RegistryLike, FactsOptions, Definition } from "./facts.js";
+export { normalize, findDefinitions, MAX_REF_DEPTH } from "./normalize.js";
+export type { NormalizeOptions, NormalizeResult } from "./normalize.js";
+export { resolveScopes } from "./scopes.js";
+export { inferEffects, toEffects, NO_EFFECTS, UNKNOWN_EFFECTS } from "./effects.js";
+export type { EffectSummary, EffectsAnalysis, MayEffects, MustEffects as MustEffectSets, BodyEffects } from "./effects.js";
+export { checkCalls } from "./checks.js";
+export { checkShape, shapeOf } from "./schema.js";
+export type { Shape, SchemaIssue } from "./schema.js";
+export { foldProgram } from "./fold.js";
+export { compileClosure } from "./codegen-closure.js";
+export { emitText } from "./codegen-text.js";
+export type { ProgramText, SourceMapLine, TextOptions } from "./codegen-text.js";
+export { printIR } from "./print.js";
+export { hasErrors, sortDiagnostics } from "./diagnostics.js";
+export type { Diagnostic, DiagnosticCode, Severity } from "./diagnostics.js";
+export { childPointer, childrenOf, isCallLike, isControl, walk } from "./ir.js";
+export type * from "./ir.js";
+export type { CompiledProgram, ProgramContext, RuntimeFrame } from "./runtime.js";

package/src/interceptor.ts

@@ -0,0 +1,149 @@
+/**
+ * The check before the run, as an interceptor of a host (roadmap R22).
+ *
+ * A host calls a data-driven procedure (`client.chain`, `client.map`, a procedure that
+ * `procedure.define` made) with a program in its input. Without the check, the interpreter finds
+ * a problem only when it arrives there: step 1 can write a file before step 3 meets a refusal.
+ * The interceptor checks the whole program before the first step. When the check finds an error,
+ * the host refuses the call, and no step starts.
+ *
+ * The check is conservative. It refuses a call that a branch can make, also a branch that does
+ * not run. A `client.tryCatch` around a refused call does not help: the program does not start.
+ *
+ * A call of `procedure.define` gets the check of its body. The host refuses a body with an
+ * error, and gives the effects of the body to `procedure.define`, which keeps them as
+ * `inferredEffects`. Then the tool of a defined procedure has the right hints.
+ *
+ * @example
+ * ```typescript
+ * const server = new ProcedureServer({
+ *   registry,
+ *   expose,
+ *   interceptors: [programCheckInterceptor({ registry, expose })],
+ * });
+ * ```
+ */
+
+import {
+  INFERRED_EFFECTS_METADATA_KEY,
+  InvocationError,
+  effectsValue,
+  isDataDriven,
+  pathToKey,
+  type AnyProcedure,
+  type CapabilityRefusalReason,
+  type Interceptor,
+  type Invocation,
+  type InvocationErrorCode,
+  type ProcedurePath,
+} from "@procedures/client/browser";
+import { registryFacts, type ProcedureFacts, type RegistryLike } from "./facts.js";
+import { checkProgram, type CheckResult } from "./program.js";
+import type { Diagnostic } from "./diagnostics.js";
+
+/** A registry that tells when its procedures change, so the interceptor can make its facts again. */
+export interface ObservableRegistry extends RegistryLike {
+  on?(event: "register" | "unregister", listener: (procedure: AnyProcedure) => void): void;
+}
+
+/** The options of `programCheckInterceptor()`. */
+export interface ProgramCheckOptions {
+  /** The registry of the host. */
+  readonly registry: ObservableRegistry;
+  /** The expose rule of the host. The default exposes each procedure. */
+  readonly expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /** The diagnostics that refuse a program. The default refuses each error. */
+  readonly refuses?: ((diagnostic: Diagnostic) => boolean) | undefined;
+  /** This function gets each result of the check (for logs and tests). */
+  readonly onCheck?: ((invocation: Invocation, result: CheckResult) => void) | undefined;
+}
+
+/** The error code of the interpreter for the same problem, so a client sees one code. */
+function codeOf(diagnostic: Diagnostic): InvocationErrorCode {
+  switch (diagnostic.code) {
+    case "not-exposed":
+      return "NOT_EXPOSED";
+    case "unknown-procedure":
+      return "NOT_FOUND";
+    case "capability-refused":
+    case "effects-unknown":
+      return "FORBIDDEN";
+    default:
+      return "VALIDATION_ERROR";
+  }
+}
+
+const REASONS: readonly CapabilityRefusalReason[] = ["effects-undeclared", "effects-exceeded", "clearance", "deadline"];
+
+/** The reason of a `FORBIDDEN` refusal: the diagnostic names it in its message. */
+function reasonOf(diagnostic: Diagnostic): CapabilityRefusalReason | undefined {
+  if (diagnostic.code === "effects-unknown") return "effects-undeclared";
+  if (diagnostic.code !== "capability-refused") return undefined;
+  return REASONS.find((reason) => diagnostic.message.includes(`(${reason})`));
+}
+
+/**
+ * The place of a problem for the caller. The check examines `{ $proc, input }`, and the caller
+ * sent only the input, so a pointer into the input loses its `/input` part.
+ */
+function placeOf(pointer: string): string {
+  if (pointer === "" || pointer === "/$proc") return "the call";
+  if (pointer === "/input") return "the input";
+  if (pointer.startsWith("/input/")) return `${pointer.slice("/input".length)} of the input`;
+  return pointer;
+}
+
+/** The text of a refusal: the first problem with its place, and the number of the others. */
+function messageOf(refused: readonly Diagnostic[]): string {
+  const first = refused[0]!;
+  const where = placeOf(first.pointer);
+  const more = refused.length > 1 ? ` The check found ${refused.length - 1} more problem${refused.length > 2 ? "s" : ""}.` : "";
+  return `The check before the run refused the program, and no step started. ${first.code} at ${where}: ${first.message}${more}`;
+}
+
+/**
+ * This function gives an interceptor that checks the program of each call of the host to a
+ * data-driven procedure, before the procedure starts. A nested call is a part of a program that
+ * the check examined already, so the interceptor does not check it again.
+ */
+export function programCheckInterceptor(options: ProgramCheckOptions): Interceptor {
+  const refuses = options.refuses ?? ((diagnostic: Diagnostic) => diagnostic.severity === "error");
+  // The facts of the registry cost a description of each procedure: keep them until it changes
+  let facts: ProcedureFacts | undefined;
+  const reset = (): void => {
+    facts = undefined;
+  };
+  options.registry.on?.("register", reset);
+  options.registry.on?.("unregister", reset);
+
+  return async (invocation, next) => {
+    if (pathToKey(invocation.path) === "procedure.define") {
+      const aggregation = (invocation.input as { aggregation?: unknown } | null | undefined)?.aggregation;
+      if (aggregation === undefined) return next();
+      facts ??= registryFacts(options.registry, { expose: options.expose });
+      const body = checkProgram(aggregation, { facts, expose: options.expose, mode: "body" });
+      options.onCheck?.(invocation, body);
+      // A nested definition is a part of a program that the check examined already
+      const refused = invocation.depth === 0 ? body.diagnostics.filter(refuses) : [];
+      if (refused.length > 0) {
+        const placed = refused.map((diagnostic) => ({ ...diagnostic, pointer: `/input/aggregation${diagnostic.pointer}` }));
+        throw new InvocationError(codeOf(placed[0]!), messageOf(placed), invocation.path, reasonOf(placed[0]!));
+      }
+      const effects = effectsValue(body.effects);
+      return effects ? next({ metadata: { ...invocation.metadata, [INFERRED_EFFECTS_METADATA_KEY]: effects } }) : next();
+    }
+    if (invocation.depth !== 0 || !isDataDriven(invocation.procedure)) return next();
+    facts ??= registryFacts(options.registry, { expose: options.expose });
+    const result = checkProgram(
+      { $proc: invocation.path, input: invocation.input },
+      { facts, expose: options.expose, capability: invocation.capability },
+    );
+    options.onCheck?.(invocation, result);
+    const refused = result.diagnostics.filter(refuses);
+    if (refused.length > 0) {
+      const first = refused[0]!;
+      throw new InvocationError(codeOf(first), messageOf(refused), invocation.path, reasonOf(first));
+    }
+    return next();
+  };
+}

package/src/ir.ts

@@ -0,0 +1,330 @@
+/**
+ * The intermediate representation (IR) of a program.
+ *
+ * The normalize pass makes the IR from the JSON of a program. Each node is one step of the
+ * interpreter: `hydrateInput()` or a control-flow procedure of `@procedures/client`. The code
+ * generation follows the IR in the order of the interpreter. Each node keeps the JSON pointer
+ * (RFC 6901) of its source in the program.
+ */
+
+import type { ProcedurePath } from "@procedures/client/browser";
+
+/** A JSON pointer (RFC 6901) into the program. The empty string is the root. */
+export type Pointer = string;
+
+/** This function gives the pointer of a child: the key is escaped as RFC 6901 tells. */
+export function childPointer(pointer: Pointer, key: string | number): Pointer {
+  return `${pointer}/${String(key).replace(/~/g, "~0").replace(/\//g, "~1")}`;
+}
+
+/** The kinds of a binding: the source of a name in a scope. */
+export type BindingKind = "step" | "initial" | "item" | "index" | "acc" | "error" | "input";
+
+/**
+ * A binding is a value that a scope gives to a name. Examples are the result of a chain step,
+ * the item of `client.map` and the error of `client.tryCatch`. Each binding gets one variable.
+ */
+export interface Binding {
+  /** The number of the binding, unique in the program. */
+  readonly id: number;
+  readonly kind: BindingKind;
+  /** The name in the scope. A step without `$name` has no name: only `$last` reads it. */
+  readonly name: string | undefined;
+  /** The pointer of the source of the binding. */
+  readonly pointer: Pointer;
+}
+
+/** One frame of a static scope, as the interpreter has it at one point of the program. */
+export interface ScopeFrame {
+  /** The names of the frame and their bindings, in the order of `Map.set`. */
+  readonly names: ReadonlyArray<readonly [string, Binding]>;
+  /** The binding that `$last` reads in this frame, or undefined when the frame has none. */
+  readonly last: Binding | undefined;
+}
+
+/** A static scope: the frames from the outermost to the innermost. Undefined: no scope. */
+export type ScopeSnapshot = readonly ScopeFrame[] | undefined;
+
+/** Where a call is: the root call, an operand of control flow, or a call in an input. */
+export type CallPosition = "root" | "operand" | "nested";
+
+interface NodeBase {
+  readonly pointer: Pointer;
+}
+
+/** A value that the program gives as it is. */
+export interface LiteralNode extends NodeBase {
+  readonly kind: "literal";
+  /** The value. The closure code gives this object itself, as the interpreter does. */
+  readonly value: unknown;
+  /**
+   * The source of the value. It is plain data, a `$literal`, a `$never` call or a `$ref` outside
+   * each scope. It can also be a deferred call of a procedure that takes raw input, or a folded call.
+   */
+  readonly origin: "data" | "literal" | "never" | "deferred" | "unscoped-ref" | "fold";
+}
+
+/** A plain object with values that the interpreter computes. The entries keep the order of `Object.entries`. */
+export interface ObjectNode extends NodeBase {
+  readonly kind: "object";
+  readonly entries: ReadonlyArray<{ readonly key: string; readonly value: IRNode }>;
+}
+
+/** An array with items that the interpreter computes, from the first item to the last item. */
+export interface ArrayNode extends NodeBase {
+  readonly kind: "array";
+  readonly items: readonly IRNode[];
+}
+
+/** A `$ref`: it reads a name of the scope and optional fields. */
+export interface ReferenceNode extends NodeBase {
+  readonly kind: "reference";
+  /** The text of the `$ref`: a name and fields, with dots. */
+  readonly text: string;
+  readonly name: string;
+  readonly fields: readonly string[];
+  /** True in the input of a deferred call: there, an unknown name stays data for the runner. */
+  readonly deferred: boolean;
+  /** The `$ref` object of the program. A deferred input gives it for an unknown name. */
+  readonly source: unknown;
+  /** True for a reference that the compiler made (the value that `passThrough` gives). */
+  readonly synthetic: boolean;
+  /** The binding of the name. The scopes pass sets it. Undefined: no scope has the name. */
+  binding: Binding | undefined;
+}
+
+/** A call through the client. Its input is hydrated before the call. */
+export interface CallNode extends NodeBase {
+  readonly kind: "call";
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly position: CallPosition;
+  readonly input: IRNode;
+  /** The parent context (`cwd`, `node`) that control flow adds to the input of an operand call. */
+  readonly extra: Readonly<Record<string, unknown>>;
+  /** The `$name` of the call. Only a chain step binds it. */
+  readonly name: string | undefined;
+}
+
+/** A call that waits for its runner (`$parent` or a context name): it is data, with its input hydrated. */
+export interface DeferredNode extends NodeBase {
+  readonly kind: "deferred";
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly when: string;
+  /** The call object of the program. */
+  readonly source: Readonly<Record<string, unknown>>;
+  readonly input: IRNode;
+}
+
+/** The reasons for a dynamic node. */
+export type DynamicReason =
+  /** The procedure runs the refs of its input (the `runs-refs` tag): `client.eval`, `dag.traverse`, `procedure.define`. */
+  | "runs-refs"
+  /** The procedure takes its input as data (the `raw-input` tag): `client.export`. */
+  | "raw-input"
+  /** The input of a control-flow procedure does not agree with its schema: the call gives the validation error. */
+  | "invalid-control-flow"
+  /** The registry does not have the core control-flow procedure at the path. */
+  | "not-core"
+  /** A control-flow call contains itself. */
+  | "cyclic";
+
+/**
+ * A call whose procedure gets its input raw, and whose operands the compiler does not model.
+ * The compiled code calls the procedure through the client with the raw input and the scope:
+ * the interpreter of the client runs it.
+ */
+export interface DynamicNode extends NodeBase {
+  readonly kind: "dynamic";
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly position: CallPosition;
+  readonly reason: DynamicReason;
+  /** The raw input: a literal, or a value that the compiled code computes (`passThrough`). */
+  readonly input: IRNode;
+  readonly extra: Readonly<Record<string, unknown>>;
+  /** What the procedure runs, when the compiler can see it (`client.eval` of a literal path). Only the checks read it. */
+  readonly model: IRNode | undefined;
+  /** The scope that the call gets (`withScope`). The scopes pass sets it. */
+  scope: ScopeSnapshot;
+}
+
+/** A step of the interpreter that throws: a hydration limit, or a `fn` that is not a call. */
+export interface FailNode extends NodeBase {
+  readonly kind: "fail";
+  readonly message: string;
+}
+
+interface ControlBase extends NodeBase {
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly position: CallPosition;
+}
+
+/** One step of a chain. */
+export interface ChainStep {
+  readonly pointer: Pointer;
+  readonly node: IRNode;
+  /** The result of the step: `$last` and `passThrough` read it, and `$name` names it. */
+  readonly result: Binding;
+}
+
+/** `client.chain`, or an array of calls that runs as one chain (an implicit chain). */
+export interface ChainNode extends ControlBase {
+  readonly kind: "chain";
+  readonly implicit: boolean;
+  readonly steps: readonly ChainStep[];
+  readonly passThrough: boolean;
+  /** The hydrated `initialInput` when `passThrough` is true. */
+  readonly initialInput: IRNode | undefined;
+  readonly initial: Binding | undefined;
+}
+
+/** `client.parallel`. */
+export interface ParallelNode extends ControlBase {
+  readonly kind: "parallel";
+  readonly tasks: readonly IRNode[];
+  readonly concurrency: number | undefined;
+  readonly failFast: boolean;
+}
+
+/** `client.conditional`. An absent branch is undefined: the result is undefined, and nothing runs. */
+export interface ConditionalNode extends ControlBase {
+  readonly kind: "conditional";
+  readonly condition: IRNode;
+  readonly then: IRNode | undefined;
+  readonly else: IRNode | undefined;
+}
+
+/** `client.tryCatch`. */
+export interface TryNode extends ControlBase {
+  readonly kind: "try";
+  readonly try: IRNode;
+  readonly catch: IRNode;
+  readonly error: Binding;
+}
+
+/** `client.and` and `client.or`. */
+export interface LogicNode extends ControlBase {
+  readonly kind: "and" | "or";
+  readonly values: readonly IRNode[];
+}
+
+/** The `items` of `client.map` and `client.reduce`: an array whose items are hydrated one by one, or one value. */
+export type ItemsSpec =
+  | { readonly kind: "list"; readonly items: readonly IRNode[] }
+  | { readonly kind: "value"; readonly value: IRNode };
+
+/** `client.map`. */
+export interface MapNode extends ControlBase {
+  readonly kind: "map";
+  readonly items: ItemsSpec;
+  readonly fn: IRNode | undefined;
+  readonly item: Binding;
+  readonly index: Binding;
+}
+
+/** `client.reduce`. Without `fn`, the result is the hydrated `initial` (or `accumulated`), and the items do not run. */
+export interface ReduceNode extends ControlBase {
+  readonly kind: "reduce";
+  readonly items: ItemsSpec | undefined;
+  readonly initial: IRNode;
+  readonly fn: IRNode | undefined;
+  readonly acc: Binding;
+  readonly item: Binding;
+  readonly index: Binding;
+}
+
+/** The nodes of the control flow. */
+export type ControlNode = ChainNode | ParallelNode | ConditionalNode | TryNode | LogicNode | MapNode | ReduceNode;
+
+/** A node of the IR. */
+export type IRNode =
+  | LiteralNode
+  | ObjectNode
+  | ArrayNode
+  | ReferenceNode
+  | CallNode
+  | DeferredNode
+  | DynamicNode
+  | FailNode
+  | ControlNode;
+
+/** The IR of a program. */
+export interface ProgramIR {
+  /** `exec`: the program runs as `client.exec()` runs it. `body`: as the body of a defined procedure. */
+  readonly mode: "exec" | "body";
+  readonly root: IRNode;
+  /** The binding of `input` in the body mode. */
+  readonly input: Binding | undefined;
+  /** The number of bindings: the ids go from 0 to this number minus one. */
+  readonly bindingCount: number;
+  /** The program, as the source of the IR. */
+  readonly program: unknown;
+}
+
+/** True for the nodes that call a procedure (a control-flow node is a call in the interpreter). */
+export function isCallLike(node: IRNode): node is CallNode | DynamicNode | ControlNode {
+  return node.kind === "call" || node.kind === "dynamic" || isControl(node);
+}
+
+/** True for a control-flow node. */
+export function isControl(node: IRNode): node is ControlNode {
+  switch (node.kind) {
+    case "chain":
+    case "parallel":
+    case "conditional":
+    case "try":
+    case "and":
+    case "or":
+    case "map":
+    case "reduce":
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** The child nodes of a node, in the order of the interpreter. A dynamic node gives its input, not its model. */
+export function childrenOf(node: IRNode): IRNode[] {
+  switch (node.kind) {
+    case "literal":
+    case "reference":
+    case "fail":
+      return [];
+    case "object":
+      return node.entries.map((entry) => entry.value);
+    case "array":
+      return [...node.items];
+    case "call":
+    case "deferred":
+    case "dynamic":
+      return [node.input];
+    case "chain":
+      return [...(node.initialInput ? [node.initialInput] : []), ...node.steps.map((step) => step.node)];
+    case "parallel":
+      return [...node.tasks];
+    case "conditional":
+      return [node.condition, ...(node.then ? [node.then] : []), ...(node.else ? [node.else] : [])];
+    case "try":
+      return [node.try, node.catch];
+    case "and":
+    case "or":
+      return [...node.values];
+    case "map":
+      return [...itemsChildren(node.items), ...(node.fn ? [node.fn] : [])];
+    case "reduce":
+      return [...(node.items ? itemsChildren(node.items) : []), node.initial, ...(node.fn ? [node.fn] : [])];
+  }
+}
+
+function itemsChildren(items: ItemsSpec): IRNode[] {
+  return items.kind === "list" ? [...items.items] : [items.value];
+}
+
+/** This function calls `visit` for each node of the tree, parents before children. */
+export function walk(node: IRNode, visit: (node: IRNode) => void): void {
+  visit(node);
+  for (const child of childrenOf(node)) walk(child, visit);
+}