vigiles 5.1.0 → 6.0.0

package/dist/core/spec.d.ts

@@ -50,6 +50,42 @@ export type StrictLinterRule = [keyof KnownLinterRules] extends [never] ? Linter
  */
 export type StrictFile = [keyof KnownProjectFiles] extends [never] ? string : KnownProjectFiles[keyof KnownProjectFiles] & string;
 export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm run ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | `npm ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | (string & {});
+/**
+ * A harness's tool vocabulary, split by the purity floor that admits it. The
+ * read-only/side-effecting split is harness-specific (it comes from the
+ * dialect's `builtinAgentTools` − `sideEffectingTools`), so the concrete unions
+ * are supplied by the adapter; core only describes the SHAPE.
+ *
+ * - `readOnly`: tools a `pure` unit may declare (observation only).
+ * - `bounded`: tools a `bounded` unit may declare — the read-only set PLUS the
+ *   decidable side-effecting tools (Write/Edit/NotebookEdit) AND `Bash` (its
+ *   command is decided at RUNTIME by the gate; the floor admits the tool). Bars
+ *   MCP / unknown / wildcard.
+ *
+ * The default (`string` at both) imposes no constraint — any tool is accepted at
+ * every level, the historical behaviour of an untyped `agent()`/`skill()`.
+ */
+export interface ToolVocabulary {
+    /** Union of tool names allowed under `purity: "pure"`. */
+    readonly readOnly: string;
+    /** Union of tool names allowed under `purity: "bounded"`. */
+    readonly bounded: string;
+}
+/** The fully-open default vocabulary — no constraint at any purity level. */
+export interface OpenToolVocabulary extends ToolVocabulary {
+    readonly readOnly: string;
+    readonly bounded: string;
+}
+/**
+ * The tool names ALLOWED at a declared `purity`, given a vocabulary `V`:
+ * - `"pure"`  → only `V["readOnly"]`.
+ * - `"bounded"` → `V["bounded"]` (read-only ∪ decidable side-effecting ∪ `Bash`).
+ * - `"dangerously-unrestricted"` (or no purity) → `string` (anything).
+ *
+ * With the open default vocabulary every branch widens to `string`, so an
+ * untyped surface accepts any tools.
+ */
+export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;
 export type ClaudeTool = "Read" | "Write" | "Edit" | "Bash" | "Grep" | "Glob" | "Agent" | "TodoWrite" | "WebSearch" | "WebFetch" | "NotebookEdit";
 export type HookEvent = "PreToolUse" | "PostToolUse" | "PreSession" | "PostSession" | "Notification";
 /** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
@@ -120,6 +156,12 @@ export type VerifiedCmd = string & {
 export type VerifiedRef = string & {
     readonly [__brand]: "VerifiedRef";
 };
+export type VerifiedDir = string & {
+    readonly [__brand]: "VerifiedDir";
+};
+export type VerifiedGlob = string & {
+    readonly [__brand]: "VerifiedGlob";
+};
 /** A typed file reference — verified at compile time. */
 export interface FileRef {
     readonly _ref: "file";
@@ -141,7 +183,17 @@ export interface SymbolRef {
     readonly file: VerifiedPath;
     readonly symbol: string;
 }
-export type Ref = FileRef | CmdRef | SkillRef | SymbolRef;
+/** A typed directory reference — verified to exist AND be a directory. */
+export interface DirRef {
+    readonly _ref: "dir";
+    readonly path: VerifiedDir;
+}
+/** A typed glob reference — verified to match at least one path. */
+export interface GlobRef {
+    readonly _ref: "glob";
+    readonly pattern: VerifiedGlob;
+}
+export type Ref = FileRef | CmdRef | SkillRef | SymbolRef | DirRef | GlobRef;
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -164,7 +216,33 @@ export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolR
  * Compiles to a markdown link: [skill name](path)
  */
 export declare function ref(path: string): SkillRef;
-export type InstructionFragment = string | Ref;
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+export declare function dir(path: string): DirRef;
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+export declare function glob(pattern: string): GlobRef;
+/**
+ * A marked side-effect BOUNDARY inside a skill/agent body — "side effects are
+ * allowed ONLY inside this block." Compiles to `<!-- vigiles:effect -->` …
+ * `<!-- /vigiles:effect -->` markers the runtime PreToolUse gate keys on: outside
+ * the region the unit is treated as read-only (the `"pure"` effective floor),
+ * inside it the declared purity floor applies. The position-aware companion to
+ * the per-call `purity` floor. See `research/effect-boundary-design.md`.
+ */
+export interface EffectRegion {
+    readonly _ref: "effect";
+    readonly body: InstructionFragment[];
+}
+export type InstructionFragment = string | Ref | EffectRegion;
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -175,6 +253,39 @@ export type InstructionFragment = string | Ref;
  *   `
  */
 export declare function instructions(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
+/**
+ * The purity an author DECLARES for a skill/agent — the floor `compile`
+ * enforces against the tool contract (see `purityViolations` in
+ * `core/effects.ts`). Mirrors the analysis `PurityLevel` for the two meaningful
+ * rungs, so what you DECLARE and what `scan` REPORTS share one vocabulary:
+ * - `"pure"`:    only read-only tools — no side effects at all.
+ * - `"bounded"`: decidable side-effecting tools (Write, Edit, …) are allowed,
+ *   but not `Bash` / unknown-effect / inherits-all (the unbounded cells).
+ * - `"dangerously-unrestricted"`: the explicit escape hatch — no enforcement.
+ *   Deliberately loud (cf. React's `dangerouslySetInnerHTML`) so opting OUT of
+ *   the guardrail stands out in review. Omitting `purity` is the same
+ *   (unenforced) default WITHOUT typing the loud word — you write it only when
+ *   you mean to override a stricter level.
+ */
+export type AuthoredPurity = "pure" | "bounded" | "dangerously-unrestricted";
 /** Known markdown instruction file targets. */
 export type InstructionTarget = "CLAUDE.md" | "AGENTS.md" | (string & {});
 export interface ClaudeSpec {
@@ -190,7 +301,12 @@ export interface ClaudeSpec {
     readonly keyFiles?: Record<string, string>;
     /** Named prose sections — plain strings or tagged templates with file()/cmd()/ref(). */
     readonly sections?: Record<string, string | InstructionFragment[]>;
-    /** Maximum lines per prose section (per-spec override). */
+    /**
+     * Maximum lines for a single named prose section. Overrides the generous
+     * compile-time default (200 lines) that guards every section + agent section
+     * against an egregious content dump — set a tighter number to enforce your own
+     * house limit, or a larger one for an intentionally long section.
+     */
     readonly maxSectionLines?: number;
     /**
      * Maximum estimated tokens for the compiled output (~4 chars per token).
@@ -293,6 +409,31 @@ export interface SkillSpec {
     readonly inputs?: readonly SkillInput[];
     /** Whether to disable model invocation (frontmatter flag). */
     readonly disableModelInvocation?: boolean;
+    /**
+     * Execution context. `"fork"` runs the skill's body as the task inside a
+     * forked SUBAGENT (its own context window) instead of inline in the main
+     * conversation (Anthropic's `context: fork` frontmatter). This is the ONLY
+     * setting under which a skill gains a real call→return boundary — so it's the
+     * prerequisite for declaring an `output` Result contract (see `output`). Omit
+     * for the default inline execution.
+     */
+    readonly context?: "fork";
+    /**
+     * The allowed-tools contract for this skill. Each entry must be a known
+     * built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
+     * tools. When `purity` is `"pure"`/`"bounded"`, the declared tools are checked
+     * against that floor — compile rejects a tool looser than the declared level.
+     */
+    readonly tools?: readonly string[];
+    /**
+     * Declare this skill's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. NOTE: `"pure"`/`"bounded"` require an explicit read-only
+     * `tools` list — an absent list inherits ALL tools and is a violation.
+     */
+    readonly purity?: AuthoredPurity;
     /**
      * Gated pipeline steps. When set, the skill compiles to a `## Steps`
      * checklist with a deterministic gate per step. Use this OR `body`.
@@ -303,6 +444,18 @@ export interface SkillSpec {
      * Compiles to a `## Result` section + a `vigiles:result` marker.
      */
     readonly result?: Gate;
+    /**
+     * The skill's typed railway outcome — the SAME `Result<ok, err>` contract a
+     * subagent declares with `result(okShape, errShape)`. Valid ONLY with
+     * `context: "fork"`: a forked skill runs as a subagent, so it has the
+     * call→return boundary a typed outcome needs (compile errors if `output` is set
+     * without `context: "fork"`). When valid, compiles to a `## Output contract`
+     * with a `vigiles:ok` / `vigiles:err` block — parseable (`parseAgentResult`) and
+     * testable (`assertAgentOk`) via the existing subagent rail. An INLINE skill has
+     * no return, so a typed outcome there is a category error — hence the gate. See
+     * `research/spec-syntax-and-railway-scope.md`.
+     */
+    readonly output?: OutputContract;
     /** Freeform instruction body (linear/unstructured skills). Use this OR `steps`. */
     readonly body?: string | InstructionFragment[];
     /**
@@ -313,13 +466,27 @@ export interface SkillSpec {
      */
     readonly maxInlineCodeLines?: number;
 }
+/**
+ * The input to `skill()` — `SkillSpec` minus `_specType`, with `tools`
+ * constrained by the declared `purity` and vocabulary `V` (same mechanism as
+ * `AgentSpecInput`). The open default vocabulary leaves it unconstrained.
+ */
+export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = Omit<SkillSpec, "_specType" | "tools" | "purity"> & {
+    readonly purity?: P;
+    readonly tools?: readonly AllowedAt<P, V>[];
+};
 /**
  * Define a SKILL.md specification.
  *
  *   // skills/my-skill/SKILL.md.spec.ts
  *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *
+ * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
+ * constraint), exactly like `agent()`: a vocabulary-bound `skill` (e.g.
+ * `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a `tsc`
+ * error; the bare core `skill()` accepts any tools, as before.
  */
-export declare function skill(spec: Omit<SkillSpec, "_specType">): SkillSpec;
+export declare function skill<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary>(spec: SkillSpecInput<P, V>): SkillSpec;
 /**
  * A subagent definition (compiles to `agents/<name>.md`). Unlike a skill —
  * reference material the model reads on activation — a subagent is a *delegated
@@ -338,6 +505,8 @@ export interface AgentSpec {
     readonly description: string;
     /** Model alias (e.g. "sonnet", "opus", "haiku", "inherit"). Optional. */
     readonly model?: string;
+    /** Subagent UI colour (Claude Code frontmatter, e.g. "pink", "blue"). Optional. */
+    readonly color?: string;
     /**
      * The allowed-tools contract — the rails the worker runs on. Each entry must be
      * a known built-in tool (Read/Write/Edit/Bash/Grep/Glob/WebSearch/WebFetch/
@@ -345,6 +514,17 @@ export interface AgentSpec {
      * Omit to inherit all tools. Verified at compile time.
      */
     readonly tools?: readonly string[];
+    /**
+     * The DENY-side contract — tools the worker may NOT use. Use this INSTEAD OF
+     * `tools`, not with it: `tools` is an allowlist (only these), so a tool not
+     * listed is already unavailable and a `disallowedTools` entry would be
+     * redundant. `disallowedTools` earns its place only when there's NO allowlist
+     * (the agent inherits ALL tools) and you want to subtract a few — e.g.
+     * `disallowedTools: ["Bash"]` on an otherwise-unrestricted worker. Rendered to
+     * the `disallowedTools:` frontmatter; close-typos are flagged (a typo'd entry
+     * blocks nothing). For a read-only floor prefer a tight `tools` list + `purity`.
+     */
+    readonly disallowedTools?: readonly string[];
     /**
      * The lead/intro prose of the system prompt (the "You are…" opener), before any
      * sections. Carries verified `file()`/`cmd()`/`symbol()`/`ref()` marks. No
@@ -367,7 +547,56 @@ export interface AgentSpec {
      * and testable (see `result()`, `parseAgentResult`, `assertAgentOk`).
      */
     readonly output?: OutputContract;
+    /**
+     * Declare this agent's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. `"pure"`/`"bounded"` require an explicit `tools` list — a
+     * wildcard or absent-tools (inherits-all) is always a violation.
+     */
+    readonly purity?: AuthoredPurity;
 }
+/**
+ * The input to `agent()` — `AgentSpec` minus the internal `_specType`, with the
+ * `tools` list constrained by the declared `purity` and the tool vocabulary `V`.
+ * `P` is inferred from the literal `purity` field (`const` inference), and
+ * `tools` is then typed `AllowedAt<P, V>[]`:
+ * - `purity: "pure"`   → `tools` may list only `V["readOnly"]` tools.
+ * - `purity: "bounded"`→ `tools` may list `V["bounded"]` tools (admits `Bash`).
+ * - no `purity` / `"dangerously-unrestricted"` → `tools` is `string[]` (open).
+ *
+ * With the open default vocabulary (core `agent()`) every level widens to
+ * `string`, so any tools compile — backwards-compatible.
+ */
+export type AgentSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape> = Omit<AgentSpec, "_specType" | "tools" | "purity" | "output"> & {
+    readonly purity?: P;
+    readonly tools?: readonly AllowedAt<P, V>[];
+    /** The typed result contract — `result(ok, err)`. Its literal field shapes are
+     *  captured into the returned `TypedAgentSpec` so a typed `pipe` can check them. */
+    readonly output?: OutputContract<Ok, Err>;
+};
+declare const __outcome: unique symbol;
+/** Phantom carrier of an agent's success/error result shapes (type-level only). */
+export interface TypedOutcome<Ok extends Shape, Err extends Shape> {
+    readonly [__outcome]: {
+        readonly ok: Ok;
+        readonly err: Err;
+    };
+}
+/** An `AgentSpec` that REMEMBERS its `result()` ok/err shapes at the type level
+ *  (via a phantom field). Still an `AgentSpec`, so it flows everywhere one does.
+ *  The input to a typed `pipe` / `then`. */
+export type TypedAgentSpec<Ok extends Shape, Err extends Shape> = AgentSpec & TypedOutcome<Ok, Err>;
+/**
+ * Extract a typed agent's success (`result().ok`) SHAPE at the type level. The
+ * phantom `__outcome` symbol is module-private, so this is the exported reader
+ * the whole-harness registry uses: `OkOf<typeof registry["planner"]>` is the
+ * literal `ok` shape `planner` produces, the producer side of a cross-file
+ * `Handoff<>` check. A plain `AgentSpec` (no `result()` contract) carries no
+ * phantom, so `OkOf` widens to the erased `Shape` — a no-op handoff, additive.
+ */
+export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
 /**
  * Define a subagent specification (compiles to `agents/<name>.md`).
  *
@@ -382,21 +611,41 @@ export interface AgentSpec {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
  *   });
+ *
+ * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
+ * constraint). A harness adapter re-exports a vocabulary-bound `agent` (e.g.
+ * `vigiles/claude-code`) so `purity: "pure"` + a side-effecting tool is a `tsc`
+ * error at edit time; the bare core `agent()` accepts any tools, as before.
+ *
+ * Also generic over the result's `Ok`/`Err` shapes, inferred from `output:
+ * result(...)`. The returned value is a `TypedAgentSpec<Ok, Err>` — an
+ * `AgentSpec` that carries those shapes at the type level, so a typed `pipe`
+ * can cross-reference the handoff. With no `output` the shapes default to the
+ * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
  */
-export declare function agent(spec: Omit<AgentSpec, "_specType">): AgentSpec;
+export declare function agent<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
 /** The field types a result contract can declare (kept tiny + dependency-free). */
 export type OutputFieldType = "string" | "number" | "boolean" | "string[]";
+/** A field SHAPE — a record of field-name → field-type, kept in the TYPE so a
+ *  typed pipeline can cross-reference one agent's `ok` against the next agent's
+ *  `needs`. The erased runtime form is `Record<string, OutputFieldType>`. */
+export type Shape = Readonly<Record<string, OutputFieldType>>;
 /**
  * A subagent's typed result contract: the shape it must return on success
  * (`ok`) and on failure (`err`). Rich on both tracks — an error is structured
  * detail, not a bare pass/fail bit. Compiles into the worker's system prompt
  * (the `vigiles:ok` / `vigiles:err` block it must emit) and is the schema the
  * `parseAgentResult` parser + the `assertAgentOk/Err` test helpers validate.
+ *
+ * Generic over its `ok`/`err` field shapes so a typed value REMEMBERS them at
+ * the type level (the basis of typed composition — see `pipe`). The default
+ * type parameters widen to the historical erased `Shape`, so an `OutputContract`
+ * named with no arguments behaves exactly as before — backwards-compatible.
  */
-export interface OutputContract {
+export interface OutputContract<Ok extends Shape = Shape, Err extends Shape = Shape> {
     readonly _ref: "output";
-    readonly ok: Readonly<Record<string, OutputFieldType>>;
-    readonly err: Readonly<Record<string, OutputFieldType>>;
+    readonly ok: Ok;
+    readonly err: Err;
 }
 /**
  * Declare a subagent's success/error result contract.
@@ -408,8 +657,14 @@ export interface OutputContract {
  *
  * (Distinct from a skill's `result:` postcondition gate — this types a
  * subagent's *return value*, the success/error tracks of the railway.)
+ *
+ * The literal field shapes are PRESERVED in the return type (`const` inference),
+ * not erased to `Record<string, OutputFieldType>` — this is what lets `pipe`
+ * cross-reference one agent's `ok` against the next agent's needs at `tsc` time.
+ * The return is still an `OutputContract`, so every existing consumer (the
+ * `output:` field, `renderOutputContract`, `parseAgentResult`) is unchanged.
  */
-export declare function result(ok: Record<string, OutputFieldType>, err: Record<string, OutputFieldType>): OutputContract;
+export declare function result<const Ok extends Shape, const Err extends Shape>(ok: Ok, err: Err): OutputContract<Ok, Err>;
 /** One step on a railway: dispatch a flat subagent (the "activity"). */
 export interface RailwayStep {
     readonly _step: "delegate";
@@ -417,9 +672,31 @@ export interface RailwayStep {
     readonly agent: string;
     /** Optional task hint passed to the worker. */
     readonly task?: string;
+    /**
+     * Optional input contract the step reads from its predecessor's `result().ok`.
+     * When present, the whole-harness registry (`generate-harness`) emits a
+     * per-edge `Handoff<>` assertion so a CROSS-FILE handoff mismatch (a missing
+     * field or wrong type vs the prior step's `ok`) is a `tsc` error naming the
+     * field. Absent `needs` = no handoff check (today's behavior, the string-path
+     * backstop). Built by `needs(...)`, the same builder a typed `pipeStep` uses.
+     */
+    readonly needs?: Shape;
 }
-/** Build a railway step that dispatches `agent` (optionally with a task hint). */
-export declare function delegate(agent: string, task?: string): RailwayStep;
+/**
+ * Build a railway step that dispatches `agent`.
+ *
+ *   delegate("planner")                                  // no task, no handoff
+ *   delegate("implementer", "implement the plan")        // task hint only
+ *   delegate("reviewer", undefined, needs({ diff: "string" }))  // + handoff check
+ *
+ * The optional 3rd argument carries the step's input `needs` (built by
+ * `needs(...)`). When present, the whole-harness registry asserts that the
+ * PREVIOUS success-track step's `result().ok` SUPPLIES it — a cross-file
+ * handoff that doesn't line up is a `tsc` error naming the offending field.
+ * Omitting it (the historical 1-/2-arg call) keeps the exact string-path
+ * behavior — fully backwards-compatible.
+ */
+export declare function delegate(agent: string, task?: string, needsContract?: Shape): RailwayStep;
 /**
  * A railway over flat subagents. `steps` run in order on the success track; the
  * first step that returns an error short-circuits to `onError`. `recover`
@@ -450,6 +727,150 @@ export interface Railway {
  *   })
  */
 export declare function railway(spec: Omit<Railway, "_specType">): Railway;
+/**
+ * A subagent's INPUT contract — the fields it reads from the prior step's `ok`.
+ * Declared via `needs(...)` and threaded into the typed agent so `pipe` can
+ * cross-reference it. Independent of `result()` (the output) — an agent both
+ * `needs` an input shape and produces an `ok`/`err` output shape.
+ */
+export type NeedsContract<N extends Shape> = N;
+/**
+ * Declare the input fields a step reads from its predecessor's success payload.
+ * Pass it as `needs:` on a typed pipeline step. `needs({})` (the default) is a
+ * step with no upstream requirement — valid as the FIRST step of a pipeline.
+ *
+ *   needs({ plan: "string", files: "string[]" })
+ */
+export declare function needs<const N extends Shape>(shape: N): NeedsContract<N>;
+/**
+ * A typed pipeline step: a `TypedAgentSpec` paired with the input `needs` it
+ * reads from the prior step's `ok`. `step()` builds one; `pipe` checks that the
+ * prior step's `ok` shape supplies this step's `needs`.
+ */
+export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape> {
+    readonly _step: "typed-delegate";
+    readonly agent: TypedAgentSpec<Ok, Err>;
+    readonly needs: Needs;
+}
+/**
+ * Pair a typed agent with the input it `needs` from the previous step. The first
+ * argument is an `agent()` VALUE (which carries its `result()` shape); the
+ * second is the `needs(...)` input contract.
+ *
+ *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ */
+export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
+/**
+ * True iff `Producer` provides EVERY field `Consumer` needs, with matching
+ * field types. When satisfiable it is `true`; otherwise it collapses to a
+ * descriptive error object naming the offending field (`__missing` /
+ * `__mismatch`), which surfaces at the mismatched call. Shallow (a per-field
+ * mapped type, not a recursion) to avoid TS2589.
+ */
+export type Supplies<Producer extends Shape, Consumer extends Shape> = {
+    [K in keyof Consumer]: K extends keyof Producer ? Producer[K] extends Consumer[K] ? true : {
+        readonly __mismatch: K;
+        readonly expected: Consumer[K];
+        readonly got: Producer[K];
+    } : {
+        readonly __missing: K;
+        readonly required: Consumer[K];
+    };
+}[keyof Consumer];
+/**
+ * Per-edge CROSS-FILE handoff check — the registry-scale form of `Supplies<>`,
+ * mirroring `KnownAgentName` (the dangling-delegate per-edge check). `Producer`
+ * is the prior success-track step's `result().ok` shape (read off the registry
+ * via `OkOf`); `Consumer` is THIS step's `needs(...)` input contract. Collapses
+ * to `true` when the producer supplies every field the consumer needs (matching
+ * types), else to a descriptive error object naming the offending field
+ * (`__handoff_error` wrapping `Supplies`'s `__missing`/`__mismatch`), so
+ * assigning `true` to it is a `tsc` error at edit time. Shallow (one wrap over
+ * the per-field `Supplies` mapped type, no recursion); the generator emits one
+ * assertion per consecutive step pair (O(N)), keeping clear of TS2589.
+ */
+export type Handoff<Producer extends Shape, Consumer extends Shape> = Supplies<Producer, Consumer> extends true ? true : {
+    readonly __handoff_error: Supplies<Producer, Consumer>;
+};
+/** A typed pipeline value — carries the LAST step's `ok` and the UNION of every
+ *  step's `err` (any step can short-circuit to the error track). */
+export interface Pipeline<Ok extends Shape, Err extends Shape> {
+    readonly _specType: "pipeline";
+    /** Ordered agent names — the resolved compose order. */
+    readonly agents: readonly string[];
+    /** The final step's success shape. */
+    readonly ok: Ok;
+    /** The union of every step's error shape. */
+    readonly err: Err;
+    /** The underlying string-path railway, for `compileRailway` reuse. */
+    readonly railway: Railway;
+}
+/**
+ * Begin a typed pipeline from its first step. The first step has no upstream, so
+ * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
+ * carrying that step's `ok`/`err` forward.
+ */
+export declare function start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
+/**
+ * Append a step to a typed pipeline. The handoff is CHECKED: the constraint
+ * `Supplies<PriorOk, Needs>` must be `true`, else the `next` parameter's type
+ * collapses to a `__HANDOFF_ERROR` object and `tsc` rejects the call, naming the
+ * missing/mismatched field. Carries the new step's `ok` forward and accumulates
+ * the error track. Shallow per-call check — no recursive chain type.
+ *
+ * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
+ * exporting a function called `then` becomes a thenable, so `await import()` of
+ * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ */
+export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, Needs extends Shape, Ok extends Shape, Err extends Shape>(prior: Pipeline<PriorOk, PriorErr>, next: Supplies<PriorOk, Needs> extends true ? PipeStep<Needs, Ok, Err> : {
+    readonly __HANDOFF_ERROR: Supplies<PriorOk, Needs>;
+}): Pipeline<Ok, PriorErr | Err>;
+/**
+ * Compose a typed pipeline in one call — the ergonomic form of
+ * `andThen(andThen(start(a), b), c)`. Each adjacent handoff is checked
+ * left-to-right: the FIRST step is the producer, the rest are
+ * `pipeStep(agent, needs(...))` consumers, and the compiler rejects the whole
+ * expression if ANY handoff's producer `ok` does not supply the consumer's
+ * `needs` (variadic chains hit TS2589 quickly, so `pipe` is a fixed set of
+ * overloads over the shallow `start`/`andThen` fold rather than a recursive
+ * variadic type — keep chains to a handful of steps; for longer ones, fold
+ * `andThen` explicitly).
+ *
+ *   pipe(
+ *     planner,                                              // produces ok
+ *     pipeStep(implementer, needs({ plan: "string", files: "string[]" })),
+ *     pipeStep(reviewer, needs({ diff: "string" })),
+ *   ) // ← won't compile if a handoff doesn't line up
+ */
+export declare function pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
+export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+    readonly __HANDOFF_ERROR: Supplies<A, BN>;
+}): Pipeline<B, AE | BE>;
+export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+    readonly __HANDOFF_ERROR: Supplies<A, BN>;
+}, c: Supplies<B, CN> extends true ? PipeStep<CN, C, CE> : {
+    readonly __HANDOFF_ERROR: Supplies<B, CN>;
+}): Pipeline<C, AE | BE | CE>;
+export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape, DN extends Shape, D extends Shape, DE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+    readonly __HANDOFF_ERROR: Supplies<A, BN>;
+}, c: Supplies<B, CN> extends true ? PipeStep<CN, C, CE> : {
+    readonly __HANDOFF_ERROR: Supplies<B, CN>;
+}, d: Supplies<C, DN> extends true ? PipeStep<DN, D, DE> : {
+    readonly __HANDOFF_ERROR: Supplies<C, DN>;
+}): Pipeline<D, AE | BE | CE | DE>;
+/**
+ * Per-edge dangling-`delegate` check. `Target` is a delegate target NAME (a
+ * string literal the generator reads off a `railway()` value); `Names` is the
+ * literal union of every agent name in the harness (emitted by the generator).
+ * Collapses to `true` when the target resolves, else to a descriptive error
+ * object naming the dangling target + the railway it came from — so assigning
+ * `true` to it is a `tsc` error at edit time. Shallow (one conditional, no
+ * recursion); the generator emits one assertion per edge (O(N)).
+ */
+export type KnownAgentName<Target extends string, Names extends string, From extends string = string> = [Target] extends [Names] ? true : {
+    readonly __dangling_delegate: Target;
+    readonly from: From;
+};
 /** Derive the spec filename from an output filename. */
 export type SpecPath<Output extends `${string}.md`> = `${Output}.spec.ts`;
 /** Extract the output filename from a spec filename. */