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

package/README.md

@@ -1,23 +1,160 @@
 # @owlmeans/agent-common
 
 Serializable contracts for OwlMeans agents and LLM pipelines: conversation identity, the run
-lifecycle flow, and the record shapes an application persists.
+lifecycle flow, the pipeline declaration and run row, the cumulative-results records with their
+deterministic renderers, and the record shapes an application persists. Runtime-free by design — no
+LangChain, no LangGraph, no storage driver — so a backend, a reconciler, an operator console or a
+browser bundle imports it to read what an agent wrote and to say where a pipeline run stands. It does
+not run anything: executing agents and pipelines, binding stores and cutting result views is the
+runtime, [`@owlmeans/agent`](../agent). The package's skill is `agent-common`.
 
-Runtime-free by design — no LangChain, no LangGraph, no storage driver. A backend or a browser
-bundle can import these shapes to read what an agent wrote without pulling the runtime. The
-runtime is [`@owlmeans/agent`](../agent).
+## Installation
 
-## What is here
+```bash
+bun add @owlmeans/agent-common@^0.1.18-rc.49
+```
+
+## Concepts
+
+- **Conversation** — `ConversationRef` (`{ conversationId, scope }`): the thread a run belongs to and
+  the wider subject its memory is filed under. `conversationFor` derives both from an `LlmPurpose`
+  dedication (`<kind>:<id>`).
+- **Run lifecycle** — `agentRunFlow`, an `@owlmeans/flow` declaration with steps `Received` →
+  `Prepared` → `Working` → `Finalizing` → `Finished`, plus a terminal `Failed`. The steps say how far
+  a run got; nothing resumes one.
+- **Pipeline** — `PipelineSpec`, a declaration of named steps joined by `after` edges. It is the
+  resumable unit; `makePipelineSpecModel(spec)` validates and orders it.
+- **Pipeline run** — `PipelineRun`, the one authority on where a run stands: status, `completed` /
+  `pending` steps, `state` as JSON **text** with `stateChars`, and `heartbeatAt`.
+- **Cumulative results** — `CumulativeResultFact`s a step produced, collected into a
+  `CumulativeResultEntry` per step, rendered full or names-only so later steps reuse the
+  authoritative names.
+- **Port** — a store name (`AGENT_CONVERSATION_STORE`, …) a consumer binds its own storage under. An
+  unbound port is not an error; the plugin that needs it degrades to a no-op.
+
+## Usage
+
+### Derive a conversation and cap text
+
+```typescript
+import { DEFAULT_SUMMARY_CHARS, conversationFor, truncateAt } from '@owlmeans/agent-common'
+
+const ref = conversationFor({ type: 'coder', dedication: `project:${projectId}` })
+// { conversationId: 'project:<id>', scope: '<id>' } — an empty dedication becomes 'anonymous'
+
+const summary = truncateAt(modelAnswer, DEFAULT_SUMMARY_CHARS) // cuts on a paragraph/line/sentence/word, marks with '…'
+```
+
+### Drive the run lifecycle
+
+```typescript
+import { makeFlowModel } from '@owlmeans/flow'
+import { AgentRunStep, AgentRunTransition, agentRunFlow } from '@owlmeans/agent-common'
+
+const model = await makeFlowModel(agentRunFlow)
+model.transit(model.next().transition, true) // Received → Prepared: one automatic edge per step
+model.transit(AgentRunTransition.Work, true)
+
+model.step().step === AgentRunStep.Working
+```
+
+### Declare and validate a pipeline
+
+```typescript
+import { makePipelineSpecModel, PipelineSpecError } from '@owlmeans/agent-common'
+import type { PipelineSpec } from '@owlmeans/agent-common'
+
+export const scaffoldPipeline: PipelineSpec = {
+  alias: 'scaffold',
+  version: 2, // bump on every added, removed or renamed step
+  steps: [
+    { step: 'plan', title: 'Plan the change' },
+    { step: 'types', after: ['plan'] },
+    { step: 'api', after: ['types'] },
+    { step: 'web', after: ['types'] },
+    { step: 'wipe-preview', after: ['api', 'web'], nonIdempotent: true },
+  ],
+}
+
+const spec = makePipelineSpecModel(scaffoldPipeline)
+spec.validate()              // throws PipelineSpecError naming every fault at once
+spec.orderSteps()            // ['plan', 'types', 'api', 'web', 'wipe-preview']
+spec.descendants('types')    // what a resume from 'types' re-runs, 'types' included
+spec.ancestry('wipe-preview') // [{ step: 'plan', depth: 3 }, { step: 'types', depth: 2 }, …]
+```
+
+### Render a step's results
+
+```typescript
+import { CumulativeFactKind, CumulativeResultSource, cumulativeResultsHelper } from '@owlmeans/agent-common'
+
+const { full, compact } = cumulativeResultsHelper.renderResultEntry({
+  label: 'types',
+  source: CumulativeResultSource.Extracted,
+  facts: [
+    { kind: CumulativeFactKind.Type, name: 'User', signature: '{ id: string; email: string }', specifier: '@app/common' },
+    { kind: CumulativeFactKind.Endpoint, name: 'user.create', ref: 'User', attrs: { method: 'POST', path: '/api/users' } },
+  ],
+})
+
+const spec = cumulativeResultsHelper.mergeResultsSpecs(pipelineResults, deploymentOverlay)
+```
+
+## API
+
+### Functions and helpers
 
 | Export | Purpose |
 |---|---|
 | `conversationFor(purpose, override?)` | Derives a `ConversationRef` from an `LlmPurpose` dedication — the thread identity an agent run belongs to |
 | `truncateAt(text, max)` | Boundary-aware truncation; every character cap in the family lands here |
-| `agentRunFlow` / `AgentRunStep` / `AgentRunTransition` | The `@owlmeans/flow` lifecycle a run is driven through |
-| `ConversationEvent` | One finished run, compacted: `summary` (what happened) + `advice` (what to do next) |
-| `AgentRunState` | The data plane of a run — serialized flow plus the execution snapshot |
-| `MemoryNode` / `MemoryEvent` | Agent-authored memory: a subsystem graph node, and an entry in a bounded sequence |
+| `makePipelineSpecModel(spec)` | `PipelineSpecModel`: `validate`, `orderSteps`, `descendants`, `ancestry`, `ancestors`, `stepOf`, `record` |
+| `validatePipelineSpec`, `orderPipelineSteps`, `pipelineDescendants`, `pipelineStep` | Deprecated wrappers over `makePipelineSpecModel` |
+| `cumulativeResultsHelper` (`createCumulativeResultsHelper()`) | `factKey`, `sortFacts`, `renderResultFact`, `renderResultEntry`, `renderResultSummary`, `compareResultOrder`, `rootRunOf`, `resultLabel`, `mergeResultsSpecs` |
+
+### Records and types
+
+| Export | Purpose |
+|---|---|
+| `agentRunFlow` / `agentFlows` / `AgentRunStep` / `AgentRunTransition` | The `@owlmeans/flow` lifecycle a run is driven through |
+| `ConversationEvent` (+ `ConversationEventInput`) | One finished run, compacted: `summary` (what happened) + `advice` (what to do next) |
+| `MemoryNode` / `MemoryEvent` (+ `MemoryEventInput`) | Agent-authored memory: a subsystem graph node, and an entry in a bounded sequence |
 | `AgentRunMessage` | What a transport carries; execution state travels by reference |
+| `PipelineSpec`, `PipelineStepSpec`, `PipelineState` | The declaration and the scalar state passed between steps |
+| `PipelineRun`, `PipelineRunInquiry`, `PipelineProgress` | The persisted run row, the question a `Waiting` run stopped on, runner progress |
+| `PipelineSpecModel`, `PipelineStepDepth` | The spec model and an ancestor with its edge distance |
+| `CumulativeResultFact`, `CumulativeResultEntry`, `RenderableResultEntry`, `RenderedResultEntry`, `ResultRenderCaps` | Cumulative-results records and rendering |
+| `CumulativeResultsSpec`, `StepResultsSpec`, `ResultSummarySpec`, `ResultFactQuery`, `CumulativeResultsHelper` | The JSON-safe declaration, a facts query, the helper interface |
+
+### Constants and enums
+
+| Export | Value / members |
+|---|---|
+| `AGENTS_SERVICE` | `'agents'` — plural, so it never collides with an app's own `agent` service |
+| `AGENT_CONVERSATION_STORE`, `AGENT_MEMORY_GRAPH_STORE`, `AGENT_MEMORY_EVENTS_STORE`, `AGENT_PIPELINE_RUN_STORE`, `AGENT_CHECKPOINT_STORE`, `AGENT_CUMULATIVE_RESULT_STORE` | Port names |
+| `AGENT_RUN_FLOW`, `SCOPE_SEP`, `INQUIRY_ANSWERS_KEY`, `RESULTS_EVERY_STEP` | `'agent-run'`, `':'`, `'answers'`, `'*'` |
+| `DEFAULT_SUMMARY_CHARS` 1200 · `DEFAULT_ADVICE_CHARS` 400 · `DEFAULT_EVENT_WINDOW` 3 · `DEFAULT_MEMORY_NODE_CHARS` 2000 · `DEFAULT_MEMORY_EVENTS_LIMIT` 50 | Run and memory caps |
+| `DEFAULT_MAX_STATE_CHARS` 256 000 · `DEFAULT_STEP_ATTEMPTS` 1 · `DEFAULT_STEP_TIMEOUT` 1 800 000 ms | Pipeline defaults |
+| `DEFAULT_RESULTS_MAX_CHARS` 12 000 · `DEFAULT_RESULT_ENTRY_CHARS` 4 000 · `DEFAULT_RESULT_COMPACT_CHARS` 400 · `DEFAULT_RESULTS_WINDOW` 2 · `DEFAULT_RESULT_SUMMARY_CHARS` 600 | Cumulative-results caps |
+| `AgentRunStatus` | `Ok`, `Failed` |
+| `PipelineRunStatus` | `Running`, `Done`, `Failed`, `Aborted`, `Waiting` |
+| `CumulativeResultSource` | `Extracted`, `Rebuilt`, `Seeded`, `Summarized` |
+| `CumulativeFactKind` | `Type`, `Symbol`, `Endpoint`, `Resource`, `File` |
+| `ResultViewMode` | `Full`, `Compact`, `Omitted` |
+
+### Errors
+
+All extend `AgentCommonError` (a `ResilientError`) and are registered for marshalling.
+
+| Error | Thrown when |
+|---|---|
+| `AgentRunStateError` | a run is asked to advance along a transition its step does not offer |
+| `PipelineSpecError` | a declaration is not runnable — every fault in one message |
+| `PipelineVersionError` | a resume targets a run started under another spec `version` |
+| `PipelineUnknownStepError` | a step name the spec does not declare |
+| `PipelineNotIdempotentError` | a resume would re-enter a completed `nonIdempotent` step without `force` |
+| `PipelineStateTooLargeError` | a step's state exceeds the run row's cap |
+| `PipelineNotResumableError` | a step asks a question with no one to answer and no run store to park in |
 
 ## Conventions worth knowing
 
@@ -27,8 +164,8 @@ at its own adapter boundary.
 
 **Flow steps are lifecycle stages, not conversational turns.** `FlowPayload` holds flat scalars
 only and a ReAct loop's turn count is unbounded, so the loop lives inside the `Working` step and
-only its counter travels in the payload. What the steps buy is the ability to say where an
-interrupted run resumes.
+only its counter travels in the payload. What the steps buy is the ability to say how far a run got
+when it ended. Resumable work is a pipeline.
 
 **Each working step has exactly one non-explicit outgoing transition**, so `FlowModel.next()` always
 has an unambiguous answer and a driver can advance a run without knowing the vocabulary. `Fail` is
@@ -36,7 +173,31 @@ marked explicit precisely so it never becomes that automatic answer.
 
 **Port names are exported, ports are not bound here.** `AGENT_CONVERSATION_STORE` and friends are
 the keys a consumer registers its own storage under. An unbound port is not an error — the plugin
-that needs it degrades to a no-op.
+that needs it degrades to a no-op. A pipeline without `AGENT_PIPELINE_RUN_STORE` still runs but
+cannot be resumed.
+
+**A rendered result entry is deterministic.** Facts sort by kind (file facts last), name and
+location; nothing that varies (timestamp, run id, revision) is rendered, and over its cap an entry
+drops whole facts and says how many.
+
+## Common pitfalls
+
+- A pipeline state is scalars and keys; a document in it fails the step with
+  `PipelineStateTooLargeError` rather than being truncated — store artifacts elsewhere and pass keys.
+- Forgetting to bump `version` after renaming a step lets a resume skip work silently; a bumped
+  version makes the resume refuse instead.
+- `nonIdempotent: true` with `attempts > 1` is a validation fault.
+- `ancestry`/`ancestors` exclude the named step, `descendants` include it.
+- Caps are applied by truncation after the model answers; restating them in a prompt is not a cap.
+- A `Waiting` run's `heartbeatAt` does not move — do not treat it as stale.
+
+## Related packages
+
+- [`@owlmeans/agent`](../agent) — the runtime that executes runs and pipelines and writes these records
+- [`@owlmeans/llm-common`](../llm-common) — `LlmPurpose` and `Inquiry`
+- [`@owlmeans/flow`](../flow) — the flow model the run lifecycle is declared against
+- [`@owlmeans/resource`](../resource) — `ResourceRecord`, the base of every persisted record
+- [`@owlmeans/error`](../error) — `ResilientError`, the base of the error family
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -46,7 +207,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.48
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/agent-common",
-  "version": "0.1.18-rc.47",
-  "generatedAt": "2026-10-05T08:32:19.091Z",
+  "version": "0.1.18-rc.49",
+  "generatedAt": "2026-10-08T21:27:54.286Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/agent-common/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/agent-common
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/agent-common": "^0.1.18-rc.47"` in `dependencies`
+**Install:** `"@owlmeans/agent-common": "^0.1.18-rc.49"` in `dependencies`
 
 Serializable contracts for the agent family. No LangChain, no LangGraph, no storage driver — a
 backend or a browser bundle imports these to read what an agent wrote without pulling the runtime.

package/build/consts.d.ts

@@ -1,3 +1,4 @@
+import type { ShallowFlow } from '@owlmeans/flow';
 /**
  * The agent service alias.
  *
@@ -157,4 +158,23 @@ export declare 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 declare const agentRunFlow: ShallowFlow;
+/** Every flow this package declares, for a provider to serve. */
+export declare const agentFlows: ShallowFlow[];
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,sBAAsB,2BAA2B,CAAA;AAC9D,eAAO,MAAM,6BAA6B,kCAAkC,CAAA;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAC/C,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAC/C,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAC/C,eAAO,MAAM,sBAAsB,IAAI,CAAA;AACvC,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAC9C,eAAO,MAAM,qBAAqB,IAAI,CAAA;AACtC,eAAO,MAAM,oBAAoB,UAAY,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,2FAA2F;AAC3F,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B,2CAA2C;AAC3C,oBAAY,iBAAiB;IAC3B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,4FAA4F;IAC5F,OAAO,YAAY;IACnB;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAED,6CAA6C;AAC7C,oBAAY,sBAAsB;IAChC,2EAA2E;IAC3E,SAAS,cAAc;IACvB;;;OAGG;IACH,OAAO,YAAY;IACnB,8EAA8E;IAC9E,MAAM,WAAW;IACjB,0EAA0E;IAC1E,UAAU,eAAe;CAC1B;AAED,4DAA4D;AAC5D,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,mCAAmC;IACnC,OAAO,YAAY;IACnB,uEAAuE;IACvE,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,IAAI,SAAS;CACd"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,sBAAsB,2BAA2B,CAAA;AAC9D,eAAO,MAAM,6BAA6B,kCAAkC,CAAA;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAC/C,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAC/C,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAC/C,eAAO,MAAM,sBAAsB,IAAI,CAAA;AACvC,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAC9C,eAAO,MAAM,qBAAqB,IAAI,CAAA;AACtC,eAAO,MAAM,oBAAoB,UAAY,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,2FAA2F;AAC3F,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B,2CAA2C;AAC3C,oBAAY,iBAAiB;IAC3B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,4FAA4F;IAC5F,OAAO,YAAY;IACnB;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAED,6CAA6C;AAC7C,oBAAY,sBAAsB;IAChC,2EAA2E;IAC3E,SAAS,cAAc;IACvB;;;OAGG;IACH,OAAO,YAAY;IACnB,8EAA8E;IAC9E,MAAM,WAAW;IACjB,0EAA0E;IAC1E,UAAU,eAAe;CAC1B;AAED,4DAA4D;AAC5D,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,mCAAmC;IACnC,OAAO,YAAY;IACnB,uEAAuE;IACvE,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,IAAI,SAAS;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,WA0F1B,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,UAAU,EAAE,WAAW,EAAmB,CAAA"}

package/build/consts.js

@@ -164,4 +164,107 @@ export var CumulativeFactKind;
     CumulativeFactKind["Resource"] = "resource";
     CumulativeFactKind["File"] = "file";
 })(CumulativeFactKind || (CumulativeFactKind = {}));
+/**
+ * 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 = {
+    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 = [agentRunFlow];
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

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

package/build/errors.d.ts

@@ -11,7 +11,7 @@ export declare 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/build/errors.js

@@ -16,7 +16,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/build/helpers/conversation.d.ts

@@ -14,13 +14,4 @@ import type { ConversationRef } from '../types.js';
  * dedication.
  */
 export declare const conversationFor: (purpose: LlmPurpose | undefined, override?: Partial<ConversationRef>) => ConversationRef;
-/**
- * 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 declare const truncateAt: (text: string, max: number) => string;
 //# sourceMappingURL=conversation.d.ts.map

package/build/helpers/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,YACjB,UAAU,GAAG,SAAS,aACpB,OAAO,CAAC,eAAe,CAAC,KAClC,eASF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,OAAO,MAAM,KAAG,MAsBtD,CAAA"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,YACjB,UAAU,GAAG,SAAS,aACpB,OAAO,CAAC,eAAe,CAAC,KAClC,eASF,CAAA"}

package/build/helpers/conversation.js

@@ -21,32 +21,4 @@ export const conversationFor = (purpose, override) => {
         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, max) => {
-    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;
-};
 //# sourceMappingURL=conversation.js.map

package/build/helpers/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAA+B,EAC/B,QAAmC,EAClB,EAAE;IACnB,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAA;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAA;IAE3E,OAAO;QACL,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAC1F,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;KACjE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAA;IACpB,MAAM,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEvC,KAAK,MAAM,QAAQ,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;QACrC,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;AAClC,CAAC,CAAA"}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/helpers/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAA+B,EAC/B,QAAmC,EAClB,EAAE;IACnB,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAA;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAA;IAE3E,OAAO;QACL,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAC1F,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;KACjE,CAAA;AACH,CAAC,CAAA"}

package/build/helpers/truncate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const truncateAt: (text: string, max: number) => string;
+//# sourceMappingURL=truncate.d.ts.map

package/build/helpers/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/helpers/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,OAAO,MAAM,KAAG,MAsBtD,CAAA"}

package/build/helpers/truncate.js

@@ -0,0 +1,29 @@
+/**
+ * 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, max) => {
+    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;
+};
+//# sourceMappingURL=truncate.js.map

package/build/helpers/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/helpers/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAA;IACpB,MAAM,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEvC,KAAK,MAAM,QAAQ,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;QACrC,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAA;AAClC,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,8 +1,11 @@
 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';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,2BAA2B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,oBAAoB,CAAA;AACvC,mBAAmB,iCAAiC,CAAA;AACpD,cAAc,2BAA2B,CAAA;AACzC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,2BAA2B,CAAA;AACzC,cAAc,uBAAuB,CAAA"}

package/build/index.js

@@ -1,7 +1,8 @@
 export * from './consts.js';
 export * from './errors.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';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,2BAA2B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAI3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,2BAA2B,CAAA;AACzC,cAAc,uBAAuB,CAAA"}

package/build/models/pipeline-spec/types.d.ts

@@ -0,0 +1,57 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map