@owlmeans/agent-common 0.1.18-rc.47 → 0.1.18-rc.49

package/build/types.d.ts

@@ -1,5 +1,5 @@
 import type { ResourceRecord } from '@owlmeans/resource';
-import { type AgentRunStatus, RESULTS_EVERY_STEP, CumulativeResultSource, PipelineRunStatus } from './consts.js';
+import { type AgentRunStatus, PipelineRunStatus } from './consts.js';
 import type { Inquiry } from '@owlmeans/llm-common';
 /**
  * What a conversation is, as an address.
@@ -216,140 +216,4 @@ export interface PipelineProgress {
     skipped?: boolean;
     note?: string;
 }
-/**
- * ONE authoritative fact about what a step produced, small enough to be one line of a prompt.
- *
- * Every field is optional past `kind` and `name`, because facts differ in what matters about them:
- * a type has a shape and an import specifier, an endpoint an alias, a method, a path and a guard, a
- * resource a table and an accessor, a file only its path. Put scalars that have no field of their
- * own into `attrs`.
- */
-export interface CumulativeResultFact {
-    /** What the fact is about — see {@link CumulativeFactKind}. */
-    kind: string;
-    /** The name to use VERBATIM. */
-    name: string;
-    /** The file it lives in, relative to the project root. */
-    path?: string;
-    /** The module specifier it is imported from. */
-    specifier?: string;
-    /** Its shape or signature, on one line. */
-    signature?: string;
-    /** Fields, parameters or columns, when there is no signature to say it. */
-    members?: string[];
-    /** Another fact's name this one points at — a returned type, a mapped table. */
-    ref?: string;
-    /** Scalars without a field of their own — `method`, `path`, `guard`, `table`. */
-    attrs?: Record<string, string>;
-}
-/**
- * One step's contribution to a ledger.
- *
- * Keyed by `(ledger, runId, step)`. `order` places it in the ledger: the topological index of the
- * step in its own pipeline, preceded by the index path of every step it was composed under, so a
- * run composed as a step of another sorts inside that step, ahead of the composing step's own
- * entry. A single number cannot say that: two pipelines' indexes are not comparable.
- *
- * `full` and `compact` are rendered once, when the entry is written, and never contain a timestamp,
- * a run id or anything else a model would copy without meaning to.
- */
-export interface CumulativeResultEntry extends ResourceRecord {
-    /** What entries can see each other — by default the root run of the composition. */
-    ledger: string;
-    pipeline: string;
-    runId: string;
-    step: string;
-    /** How the entry is headed in a prompt: the step, behind the path of the steps it runs under. */
-    label: string;
-    order: number[];
-    /** Bumped every time the entry is re-extracted after a later step rewrote one of its files. */
-    revision: number;
-    source: CumulativeResultSource;
-    /** An `optional` step that failed: whatever it left behind, and a heading that says so. */
-    partial?: boolean;
-    facts: CumulativeResultFact[];
-    /** The files the facts were read from — what a later rewrite is matched against. */
-    files: string[];
-    /** A model's summary, rendered and capped. NOT verified, and always labelled so. */
-    summary?: string;
-    full: string;
-    compact: string;
-    /** Consumers that always get the full entry, by step name, or every later step. */
-    fullFor?: string[] | typeof RESULTS_EVERY_STEP;
-    /** Consumers that never see the entry in their prompt. */
-    omitFor?: string[];
-    /** How many edges back the entry is still rendered in full by default. */
-    window?: number;
-    updatedAt: string;
-}
-/**
- * The optional model-written summary of a step. OFF unless a step declares one.
- *
- * Facts are the product; a summary is for what code cannot extract — an intent, a decision taken.
- * It is bounded by `maxChars` in code after the model answers, rendered deterministically from the
- * schema-shaped answer, and always labelled as unverified wherever it is shown.
- */
-export interface ResultSummarySpec {
-    /** Which model — interpreted by the caller's summarize callback (a model role, typically). */
-    role?: string;
-    instructions: string;
-    /** JSON schema of the answer. Absent means `{ summary: string }`. */
-    schema?: Record<string, unknown>;
-    /** Defaults to `DEFAULT_RESULT_SUMMARY_CHARS`. */
-    maxChars?: number;
-}
-/**
- * What one step contributes, and to whom. JSON-safe, so a declaration can live in data.
- *
- * Extractors are named, never inlined: a declaration names what runs, and the runtime holds the
- * code. A consumer not named in `full` or `omit` gets the full entry within `window` edges and the
- * names only beyond it.
- */
-export interface StepResultsSpec {
-    /** Named deterministic extractors, run in this order. */
-    extractors?: string[];
-    /** Later steps that get the FULL entry wherever they sit, or `'*'` for all of them. */
-    full?: string[] | typeof RESULTS_EVERY_STEP;
-    /** Later steps that are never shown the entry. */
-    omit?: string[];
-    /** Overrides {@link CumulativeResultsSpec.window} for this entry. */
-    window?: number;
-    /** Cap on the full rendering; facts are dropped whole, never cut. */
-    maxChars?: number;
-    /** Cap on the names-only rendering. */
-    maxCompactChars?: number;
-    /** Re-extract this entry when a later step rewrites one of its files. Defaults to the spec's. */
-    refresh?: boolean;
-    summary?: ResultSummarySpec;
-}
-/** The pipeline-level declaration — merged from a pipeline's own and any overlay with {@link mergeResultsSpecs}. */
-export interface CumulativeResultsSpec {
-    /** Per step, by step name. A step with no entry contributes only what it records itself. */
-    steps?: Record<string, StepResultsSpec>;
-    /** Default {@link DEFAULT_RESULTS_WINDOW}. */
-    window?: number;
-    /** Total characters of one view. Default `DEFAULT_RESULTS_MAX_CHARS`. */
-    maxChars?: number;
-    /** Default cap of one full entry. Default {@link DEFAULT_RESULT_ENTRY_CHARS}. */
-    maxEntryChars?: number;
-    /** Default cap of one names-only entry. Default {@link DEFAULT_RESULT_COMPACT_CHARS}. */
-    maxCompactChars?: number;
-    /** Default for {@link StepResultsSpec.refresh}. Defaults to `true`. */
-    refresh?: boolean;
-}
-/** What a facts query may narrow by. Every field is an exact match. */
-export interface ResultFactQuery {
-    kind?: string;
-    name?: string;
-    /** A producing step, by its name or by its label. */
-    step?: string;
-}
-/** What {@link renderResultEntry} needs of an entry. */
-export type RenderableResultEntry = Pick<CumulativeResultEntry, 'label' | 'source' | 'partial' | 'facts' | 'summary'>;
-export interface ResultRenderCaps {
-    /** Cap on the full rendering. Default {@link DEFAULT_RESULT_ENTRY_CHARS}. */
-    maxChars?: number;
-    /** Cap on the names-only rendering. Default {@link DEFAULT_RESULT_COMPACT_CHARS}. */
-    maxCompactChars?: number;
-}
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/agent-common",
-  "version": "0.1.18-rc.47",
+  "version": "0.1.18-rc.49",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -29,10 +29,10 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/error": "^0.1.18-rc.37",
-    "@owlmeans/flow": "^0.1.18-rc.44",
-    "@owlmeans/llm-common": "^0.1.18-rc.38",
-    "@owlmeans/resource": "^0.1.18-rc.39"
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/flow": "^0.1.18-rc.45",
+    "@owlmeans/llm-common": "^0.1.18-rc.39",
+    "@owlmeans/resource": "^0.1.18-rc.40"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.ts

@@ -1,3 +1,5 @@
+import type { ShallowFlow } from '@owlmeans/flow'
+
 /**
  * The agent service alias.
  *
@@ -172,3 +174,114 @@ export enum CumulativeFactKind {
   Resource = 'resource',
   File = 'file',
 }
+
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so a plugin reading `onFinish` can say where a run ended.
+ * `Fail` is reachable from every working step and is TERMINAL — see the note on that step.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export const agentRunFlow: ShallowFlow = {
+  flow: AGENT_RUN_FLOW,
+  initialStep: AgentRunStep.Received,
+
+  steps: {
+    [AgentRunStep.Received]: {
+      index: 0,
+      step: AgentRunStep.Received,
+      service: AGENT_RUN_FLOW,
+      initial: true,
+      transitions: {
+        [AgentRunTransition.Prepare]: {
+          transition: AgentRunTransition.Prepare,
+          step: AgentRunStep.Prepared,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Prepared]: {
+      index: 1,
+      step: AgentRunStep.Prepared,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Work]: {
+          transition: AgentRunTransition.Work,
+          step: AgentRunStep.Working,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Working]: {
+      index: 2,
+      step: AgentRunStep.Working,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finalize]: {
+          transition: AgentRunTransition.Finalize,
+          step: AgentRunStep.Finalizing,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finalizing]: {
+      index: 3,
+      step: AgentRunStep.Finalizing,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finish]: {
+          transition: AgentRunTransition.Finish,
+          step: AgentRunStep.Finished,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finished]: {
+      index: 4,
+      step: AgentRunStep.Finished,
+      service: AGENT_RUN_FLOW,
+      transitions: {},
+    },
+
+    [AgentRunStep.Failed]: {
+      index: 5,
+      step: AgentRunStep.Failed,
+      service: AGENT_RUN_FLOW,
+      // Terminal. Nothing resumes a ReAct run — its tool results are side effects already applied
+      // to the world, so re-entering it re-applies them. Resumable work is a pipeline.
+      transitions: {},
+    },
+  },
+}
+
+/** Every flow this package declares, for a provider to serve. */
+export const agentFlows: ShallowFlow[] = [agentRunFlow]

package/src/errors.ts

@@ -21,7 +21,7 @@ export class AgentRunStateError extends AgentCommonError {
 /**
  * A pipeline declaration is not runnable.
  *
- * Thrown by {@link import('./pipeline.js').validatePipelineSpec} and by the runner's own build
+ * Thrown by {@link import('./models/pipeline-spec/types.js').PipelineSpecModel.validate} and by the runner's own build
  * step, and it always names EVERY fault it found rather than the first: a spec is authored once and
  * fixed once, and reporting faults one per build turns a five-minute edit into five builds.
  */

package/src/helpers/conversation.ts

@@ -28,35 +28,3 @@ export const conversationFor = (
     scope: override?.scope ?? (target !== '' ? target : 'anonymous'),
   }
 }
-
-/**
- * Cut `text` to `max` characters on a boundary a reader will not trip over.
- *
- * Every cap in this package lands here, because a model asked for "at most N characters" answers
- * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
- * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
- * sentence, then word break inside the last quarter of the budget, and always marks itself.
- */
-export const truncateAt = (text: string, max: number): string => {
-  const trimmed = text.trim()
-  if (trimmed.length <= max) {
-    return trimmed
-  }
-  if (max <= 1) {
-    return trimmed.slice(0, Math.max(0, max))
-  }
-
-  const ellipsis = '…'
-  const budget = max - ellipsis.length
-  const head = trimmed.slice(0, budget)
-  const floor = Math.floor(budget * 0.75)
-
-  for (const boundary of ['\n\n', '\n', '. ', ' ']) {
-    const at = head.lastIndexOf(boundary)
-    if (at >= floor) {
-      return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis
-    }
-  }
-
-  return head.trimEnd() + ellipsis
-}

package/src/helpers/truncate.ts

@@ -0,0 +1,31 @@
+/**
+ * Cut `text` to `max` characters on a boundary a reader will not trip over.
+ *
+ * Every cap in this package lands here, because a model asked for "at most N characters" answers
+ * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
+ * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
+ * sentence, then word break inside the last quarter of the budget, and always marks itself.
+ */
+export const truncateAt = (text: string, max: number): string => {
+  const trimmed = text.trim()
+  if (trimmed.length <= max) {
+    return trimmed
+  }
+  if (max <= 1) {
+    return trimmed.slice(0, Math.max(0, max))
+  }
+
+  const ellipsis = '…'
+  const budget = max - ellipsis.length
+  const head = trimmed.slice(0, budget)
+  const floor = Math.floor(budget * 0.75)
+
+  for (const boundary of ['\n\n', '\n', '. ', ' ']) {
+    const at = head.lastIndexOf(boundary)
+    if (at >= floor) {
+      return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis
+    }
+  }
+
+  return head.trimEnd() + ellipsis
+}

package/src/index.ts

@@ -1,7 +1,10 @@
 export * from './consts.js'
 export * from './errors.js'
 export type * from './types.js'
+export type * from './results/types.js'
+export type * from './models/pipeline-spec/types.js'
+export * from './models/pipeline-spec.js'
 export * from './pipeline.js'
 export * from './results.js'
-export * from './flows.js'
 export * from './helpers/conversation.js'
+export * from './helpers/truncate.js'

package/src/models/pipeline-spec/types.ts

@@ -0,0 +1,58 @@
+import type { PipelineSpec, PipelineStepSpec } from '../../types.js'
+
+/** One step a step transitively waits on, with the fewest `after` edges between the two. */
+export interface PipelineStepDepth {
+  step: string
+  depth: number
+}
+
+/** The rules of one pipeline declaration: its validity, its order and the graph of its steps. */
+export interface PipelineSpecModel {
+  readonly record: PipelineSpec
+  /**
+   * Every fault in one message, or nothing.
+   *
+   * Total and IO-free, so a spec can be checked by a test in microseconds and by the runner at build
+   * time. It reports EVERY fault it finds rather than the first, because a spec is authored once and
+   * a build that names one fault per run turns a five-minute edit into five builds.
+   *
+   * @throws {PipelineSpecError}
+   */
+  validate: () => void
+  /**
+   * The steps in an order that respects every `after`, with declaration order as the tie-break.
+   *
+   * Deterministic on purpose: the order decides what a progress report calls "step 3 of 16" and what
+   * a resume considers already behind it, and an order that depends on a `Set`'s iteration would make
+   * both drift between processes.
+   *
+   * @throws {PipelineSpecError} on a cycle or an unknown `after`.
+   */
+  orderSteps: () => string[]
+  /**
+   * `step` and everything that transitively waits on it.
+   *
+   * What a resume has to re-run when an operator names a step: re-entering a step without re-entering
+   * what read its output leaves the run describing a state that no longer follows from itself.
+   *
+   * @throws {PipelineUnknownStepError} when the spec does not declare `step`.
+   */
+  descendants: (step: string) => string[]
+  /**
+   * Every step `step` transitively waits on, with its DEPTH — the fewest `after` edges between the
+   * two — in topological order.
+   *
+   * The mirror of {@link PipelineSpecModel.descendants}, with one deliberate asymmetry: the named step
+   * itself is NOT included. A re-run re-enters the step it names, so the descendants include it;
+   * nothing is its own predecessor, so the ancestors do not. The depth is what a consumer uses to
+   * decide how much of a predecessor's output it needs to be told — a direct predecessor is depth 1
+   * however far apart the two sit in the topological order.
+   *
+   * @throws {PipelineUnknownStepError} when the spec does not declare `step`.
+   */
+  ancestry: (step: string) => PipelineStepDepth[]
+  /** The names from {@link PipelineSpecModel.ancestry}: what must finish before `step` may start, in order. */
+  ancestors: (step: string) => string[]
+  /** The declaration of one step, by name. `null` when the spec does not declare it. */
+  stepOf: (step: string) => PipelineStepSpec | null
+}

package/src/models/pipeline-spec.ts

@@ -0,0 +1,202 @@
+import { DEFAULT_STEP_ATTEMPTS } from '../consts.js'
+import { PipelineSpecError, PipelineUnknownStepError } from '../errors.js'
+import type { PipelineSpec, PipelineStepSpec } from '../types.js'
+import type { PipelineSpecModel, PipelineStepDepth } from './pipeline-spec/types.js'
+
+export const makePipelineSpecModel = (spec: PipelineSpec): PipelineSpecModel => {
+  const fault = (faults: string[], message: string): void => {
+    faults.push(message)
+  }
+
+  const validate = (): void => {
+    const faults: string[] = []
+
+    if (spec.alias == null || spec.alias.trim() === '') {
+      fault(faults, 'alias is empty')
+    }
+    if (!Number.isInteger(spec.version) || spec.version < 1) {
+      fault(faults, `version must be a positive integer, got ${String(spec.version)}`)
+    }
+    if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+      fault(faults, 'no steps declared')
+      throw new PipelineSpecError(`${spec.alias ?? '?'}: ${faults.join('; ')}`)
+    }
+
+    const seen = new Set<string>()
+    for (const step of spec.steps) {
+      if (step.step == null || step.step.trim() === '') {
+        fault(faults, 'a step has an empty name')
+        continue
+      }
+      if (seen.has(step.step)) {
+        fault(faults, `duplicate step "${step.step}"`)
+      }
+      seen.add(step.step)
+    }
+
+    for (const step of spec.steps) {
+      for (const dependency of step.after ?? []) {
+        if (dependency === step.step) {
+          fault(faults, `step "${step.step}" declares itself in \`after\``)
+        } else if (!seen.has(dependency)) {
+          fault(faults, `step "${step.step}" waits on unknown step "${dependency}"`)
+        }
+      }
+      const attempts = step.attempts ?? DEFAULT_STEP_ATTEMPTS
+      if (!Number.isInteger(attempts) || attempts < 1) {
+        fault(faults, `step "${step.step}" declares attempts ${String(step.attempts)}`)
+      }
+      if (step.nonIdempotent === true && attempts > 1) {
+        fault(
+          faults,
+          `step "${step.step}" is nonIdempotent and declares attempts ${attempts} — an automatic `
+          + 'retry is exactly what that flag says must not happen',
+        )
+      }
+      if (step.timeout != null && (!Number.isFinite(step.timeout) || step.timeout <= 0)) {
+        fault(faults, `step "${step.step}" declares timeout ${String(step.timeout)}`)
+      }
+    }
+
+    // A cycle is reported here rather than left to the sort, so one message carries every fault.
+    if (faults.every(entry => !entry.includes('unknown step'))) {
+      const cycle = detectCycle()
+      if (cycle != null) {
+        fault(faults, `cycle: ${cycle.join(' → ')}`)
+      }
+    }
+
+    if (faults.length > 0) {
+      throw new PipelineSpecError(`${spec.alias}: ${faults.join('; ')}`)
+    }
+  }
+
+  const detectCycle = (): string[] | null => {
+    const after = new Map(spec.steps.map(step => [step.step, step.after ?? []]))
+    const state = new Map<string, 0 | 1 | 2>()
+    const path: string[] = []
+
+    const walk = (name: string): string[] | null => {
+      const mark = state.get(name)
+      if (mark === 2) return null
+      if (mark === 1) return [...path.slice(path.indexOf(name)), name]
+
+      state.set(name, 1)
+      path.push(name)
+      for (const dependency of after.get(name) ?? []) {
+        const found = walk(dependency)
+        if (found != null) return found
+      }
+      path.pop()
+      state.set(name, 2)
+
+      return null
+    }
+
+    for (const step of spec.steps) {
+      const found = walk(step.step)
+      if (found != null) return found.reverse()
+    }
+
+    return null
+  }
+
+  const orderSteps = (): string[] => {
+    const names = spec.steps.map(step => step.step)
+    const known = new Set(names)
+    const pending = new Map<string, Set<string>>()
+    const dependents = new Map<string, string[]>()
+
+    for (const step of spec.steps) {
+      const dependencies = new Set<string>()
+      for (const dependency of step.after ?? []) {
+        if (!known.has(dependency)) {
+          throw new PipelineSpecError(
+            `${spec.alias}: step "${step.step}" waits on unknown step "${dependency}"`,
+          )
+        }
+        dependencies.add(dependency)
+        dependents.set(dependency, [...(dependents.get(dependency) ?? []), step.step])
+      }
+      pending.set(step.step, dependencies)
+    }
+
+    const ordered: string[] = []
+    const emitted = new Set<string>()
+
+    while (ordered.length < names.length) {
+      // Declaration order among everything currently ready — never a set's own order.
+      const ready = names.filter(name => !emitted.has(name) && (pending.get(name)?.size ?? 0) === 0)
+      if (ready.length === 0) {
+        const cycle = detectCycle()
+        throw new PipelineSpecError(
+          `${spec.alias}: cycle: ${(cycle ?? names.filter(name => !emitted.has(name))).join(' → ')}`,
+        )
+      }
+      for (const name of ready) {
+        ordered.push(name)
+        emitted.add(name)
+        for (const dependent of dependents.get(name) ?? []) {
+          pending.get(dependent)?.delete(name)
+        }
+      }
+    }
+
+    return ordered
+  }
+
+  const descendants = (step: string): string[] => {
+    if (!spec.steps.some(entry => entry.step === step)) {
+      throw new PipelineUnknownStepError(`${spec.alias}:${step}`)
+    }
+
+    const reached = new Set<string>([step])
+    let grew = true
+    while (grew) {
+      grew = false
+      for (const entry of spec.steps) {
+        if (reached.has(entry.step)) continue
+        if ((entry.after ?? []).some(dependency => reached.has(dependency))) {
+          reached.add(entry.step)
+          grew = true
+        }
+      }
+    }
+
+    return orderSteps().filter(name => reached.has(name))
+  }
+
+  const ancestry = (step: string): PipelineStepDepth[] => {
+    if (!spec.steps.some(entry => entry.step === step)) {
+      throw new PipelineUnknownStepError(`${spec.alias}:${step}`)
+    }
+
+    const after = new Map(spec.steps.map(entry => [entry.step, entry.after ?? []]))
+    const depths = new Map<string, number>()
+    let frontier = [step]
+    for (let depth = 1; frontier.length > 0; ++depth) {
+      const next: string[] = []
+      for (const name of frontier) {
+        for (const dependency of after.get(name) ?? []) {
+          if (dependency !== step && !depths.has(dependency)) {
+            depths.set(dependency, depth)
+            next.push(dependency)
+          }
+        }
+      }
+      frontier = next
+    }
+
+    return orderSteps()
+      .filter(name => depths.has(name))
+      .map(name => ({ step: name, depth: depths.get(name)! }))
+  }
+
+  const ancestors = (step: string): string[] =>
+    ancestry(step).map(entry => entry.step)
+
+  const stepOf = (step: string): PipelineStepSpec | null =>
+    spec.steps.find(entry => entry.step === step) ?? null
+
+  return { record: spec, validate, orderSteps, descendants, ancestry, ancestors, stepOf }
+}