@cueapi/cuechain 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vector Apps Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @cueapi/cuechain
+
+> Cuechain is not an LLM chaining framework. It is a contract verification primitive for TypeScript pipelines.
+
+[![CI](https://github.com/cueapi/cuechain/actions/workflows/ci.yml/badge.svg)](https://github.com/cueapi/cuechain/actions)
+[![npm](https://img.shields.io/npm/v/@cueapi/cuechain)](https://www.npmjs.com/package/@cueapi/cuechain)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## The Problem
+
+Imagine you ask a robot to bake a cake in six steps. At step 1, the robot grabs a tennis ball instead of an egg. It doesn't notice. It "cracks" the tennis ball, adds flour, mixes, pours, bakes, and announces "cake is done." From the outside, everything looks fine. A scheduler would record the execution as successful. But what's on the table is not a cake.
+
+Every non-trivial AI agent workflow is a chain of steps where one step's output feeds the next step's input. LLMs are non-deterministic. They return JSON that almost matches the schema, fields that are the right shape but wrong content, arrays with the wrong length. Without verification at every handoff, bad data propagates silently through the pipeline and surfaces far from its root cause.
+
+**Cuechain catches the tennis ball at step 1.** It validates contracts between every step in a pipeline, runs quality gates on outputs, and feeds failure context back into retries so LLM-driven steps can self-correct.
+
+## Install
+
+```bash
+npm install @cueapi/cuechain zod
+```
+
+Zod is a peer dependency. You probably already have it.
+
+## Quickstart
+
+```typescript
+import { z } from 'zod'
+import { defineStep, pipeline } from '@cueapi/cuechain'
+
+// Step 1: Load data
+const loadData = defineStep({
+  name: 'load-data',
+  input: z.object({ source: z.string() }),
+  output: z.object({ text: z.string(), wordCount: z.number() }),
+  run: async (input) => {
+    const text = `Content from ${input.source}`
+    return { text, wordCount: text.split(/\s+/).length }
+  },
+})
+
+// Step 2: Summarize (with a gate and retry)
+const summarize = defineStep({
+  name: 'summarize',
+  input: z.object({ text: z.string(), wordCount: z.number() }),
+  output: z.object({ summary: z.string() }),
+  gates: [
+    (out) =>
+      out.summary.length <= 200
+        ? { ok: true }
+        : { ok: false, reason: `Summary too long: ${out.summary.length} chars` },
+  ],
+  retry: { maxAttempts: 3, on: ['gate'] },
+  run: async (input, failureContext) => {
+    if (failureContext) {
+      // Use failure context to self-correct
+      return { summary: input.text.slice(0, 100) }
+    }
+    return { summary: input.text }
+  },
+})
+
+// Step 3: Format
+const format = defineStep({
+  name: 'format',
+  input: z.object({ summary: z.string() }),
+  output: z.object({ formatted: z.string() }),
+  run: async (input) => ({ formatted: `RESULT: ${input.summary}` }),
+})
+
+// Compose and run
+const myPipeline = pipeline('my-pipeline')
+  .step(loadData)
+  .step(summarize)
+  .step(format)
+
+const result = await myPipeline.run({ source: 'doc.md' })
+
+if (result.ok) {
+  console.log(result.value.formatted)
+} else {
+  console.error(`Failed at ${result.failure.step}: ${result.failure.reason}`)
+}
+```
+
+## The Five Primitives
+
+### 1. Typed Steps
+
+A step has an input schema, an output schema (both Zod), and an async `run` function. The runtime validates input before running and output after.
+
+```typescript
+const extractTitle = defineStep({
+  name: 'extract-title',
+  input: z.object({ draft: z.string() }),
+  output: z.object({ title: z.string().max(80) }),
+  run: async (input) => {
+    const title = await callLLM(`Extract a title from: ${input.draft}`)
+    return { title }
+  },
+})
+```
+
+### 2. Pipelines
+
+A pipeline chains steps where each step's output feeds the next step's input. TypeScript enforces type compatibility at compile time. Runtime validates at every handoff.
+
+```typescript
+const draft = pipeline('draft-monthly')
+  .step(loadProfile)   // { month: string } -> { profile: Profile }
+  .step(generateDraft) // { profile: Profile } -> { draft: string }
+  .step(extractTitle)  // { draft: string } -> { title: string }
+```
+
+Mismatched types fail the build, not the runtime.
+
+### 3. Quality Gates
+
+A gate is a pure synchronous function that checks a step's output beyond what a schema can express.
+
+```typescript
+const step = defineStep({
+  name: 'validate-draft',
+  input: z.object({ draft: z.string() }),
+  output: z.object({ draft: z.string(), charCount: z.number() }),
+  gates: [
+    (out) =>
+      out.charCount <= 280
+        ? { ok: true }
+        : { ok: false, reason: `Draft is ${out.charCount} chars, max 280` },
+    (out) =>
+      !out.draft.includes('<script>')
+        ? { ok: true }
+        : { ok: false, reason: 'Draft contains unsafe HTML' },
+  ],
+  run: async (input) => ({
+    draft: input.draft,
+    charCount: input.draft.length,
+  }),
+})
+```
+
+Gates are pure code, not LLM calls. Deterministic verification only.
+
+### 4. Retry With Failure Context
+
+When a step fails, Cuechain retries it with the failure reason passed as a second argument. For LLM-driven steps, this means the next prompt can include why the previous attempt failed.
+
+```typescript
+const step = defineStep({
+  name: 'generate',
+  input: z.object({ topic: z.string() }),
+  output: z.object({ text: z.string() }),
+  gates: [(out) => out.text.length < 500 ? { ok: true } : { ok: false, reason: 'too long' }],
+  retry: { maxAttempts: 3, on: ['schema', 'gate'] },
+  run: async (input, failureContext) => {
+    const prompt = failureContext
+      ? `Generate text about ${input.topic}. Previous attempt failed: ${failureContext.reason}`
+      : `Generate text about ${input.topic}`
+    return { text: await callLLM(prompt) }
+  },
+})
+```
+
+`failureContext` includes `{ reason, attempt, type }` where `type` is `'schema'`, `'gate'`, or `'exception'`.
+
+### 5. Structured Failures
+
+Pipelines return `Result<T>` — either success with a value, or a structured failure identifying exactly what went wrong.
+
+```typescript
+const result = await myPipeline.run(input)
+
+if (!result.ok) {
+  result.failure.step      // which step failed
+  result.failure.reason    // human-readable reason
+  result.failure.type      // 'schema_input' | 'schema_output' | 'gate' | 'exception'
+  result.failure.attempts  // how many attempts were made
+  result.failure.input     // what the step received
+  result.failure.output    // what the step produced (if it got that far)
+}
+```
+
+Prefer thrown exceptions? Use `.runOrThrow()`:
+
+```typescript
+try {
+  const value = await myPipeline.runOrThrow(input)
+} catch (error) {
+  if (error instanceof PipelineError) {
+    console.error(error.failure) // same structured failure
+  }
+}
+```
+
+## Introspection
+
+```typescript
+const desc = myPipeline.describe()
+// {
+//   name: 'my-pipeline',
+//   steps: [
+//     { name: 'load-data', inputSchema: {...}, outputSchema: {...}, gates: 0, retry: {...} },
+//     { name: 'summarize', inputSchema: {...}, outputSchema: {...}, gates: 1, retry: {...} },
+//   ]
+// }
+```
+
+Schemas are serialized as JSON Schema via `zod-to-json-schema`.
+
+## Cuechain + CueAPI
+
+Cuechain verifies contracts between steps. [CueAPI](https://cueapi.ai) verifies outcomes against reality. Use one, use both.
+
+**Standalone Cuechain:** run a contract-verified pipeline from any trigger — a button click, an HTTP handler, a test, a local script. No infrastructure required.
+
+**Standalone CueAPI:** schedule a cue that fires a webhook. The handler does whatever it wants internally. No Cuechain required.
+
+**Composed:** CueAPI fires on schedule, the handler invokes a Cuechain pipeline, the pipeline runs contract-verified steps and returns a structured result, the handler reports that result back to CueAPI as the outcome. Outcome verification at the temporal boundary, contract verification at the data boundary.
+
+Cuechain does not import CueAPI. The relationship is compositional, not architectural.
+
+## What Cuechain Is Not
+
+- **Not a scheduler.** That's [CueAPI](https://cueapi.ai).
+- **Not a durable execution engine.** That's Inngest, Trigger.dev, Temporal.
+- **Not a functional effects system.** That's Effect-TS.
+- **Not an LLM framework.** That's LangChain, LangGraph, Mastra. Cuechain runs any async function as a step.
+- **Not a state machine.** That's XState.
+- **Not a UI, dashboard, or hosted service.** It's a library. Zero infrastructure.
+
+Narrow scope is the product.
+
+## API
+
+### `defineStep(config)`
+
+Define a pipeline step.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Step identifier |
+| `input` | `z.ZodType` | Yes | Input schema |
+| `output` | `z.ZodType` | Yes | Output schema |
+| `run` | `(input, failureContext?) => Promise<output>` | Yes | Step function |
+| `gates` | `Gate[]` | No | Quality gate functions |
+| `retry` | `{ maxAttempts?, on? }` | No | Retry config |
+
+### `pipeline(name)`
+
+Create a pipeline builder. Chain `.step()` to add steps.
+
+### `Pipeline.run(input)`
+
+Returns `Result<T>` — `{ ok: true, value }` or `{ ok: false, failure }`.
+
+### `Pipeline.runOrThrow(input)`
+
+Returns the value directly. Throws `PipelineError` on failure.
+
+### `Pipeline.describe()`
+
+Returns `PipelineDescription` with step metadata and JSON Schemas.
+
+## License
+
+MIT. Vector Apps Inc.

package/dist/index.cjs

@@ -0,0 +1,193 @@
+'use strict';
+
+var zodToJsonSchema = require('zod-to-json-schema');
+
+// src/step.ts
+function defineStep(config) {
+  return {
+    name: config.name,
+    inputSchema: config.input,
+    outputSchema: config.output,
+    gates: config.gates ?? [],
+    retry: {
+      maxAttempts: config.retry?.maxAttempts ?? 1,
+      on: config.retry?.on ?? ["schema", "gate"]
+    },
+    run: config.run
+  };
+}
+
+// src/runner.ts
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+    return `${path}${issue.message}`;
+  }).join("; ");
+}
+function runGates(gates, output) {
+  for (const gate of gates) {
+    const result = gate(output);
+    if (!result.ok) {
+      return { reason: result.reason, context: result.context };
+    }
+  }
+  return null;
+}
+async function executeStep(step, input) {
+  const inputResult = step.inputSchema.safeParse(input);
+  if (!inputResult.success) {
+    return {
+      ok: false,
+      failure: {
+        step: step.name,
+        reason: `Input validation failed: ${formatZodError(inputResult.error)}`,
+        type: "schema_input",
+        attempts: 0,
+        input
+      }
+    };
+  }
+  const validatedInput = inputResult.data;
+  const maxAttempts = step.retry.maxAttempts;
+  const retryOn = new Set(step.retry.on);
+  let failureContext;
+  let lastFailure;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const rawOutput = await step.run(validatedInput, failureContext);
+      const outputResult = step.outputSchema.safeParse(rawOutput);
+      if (!outputResult.success) {
+        const reason = `Output validation failed: ${formatZodError(outputResult.error)}`;
+        lastFailure = {
+          step: step.name,
+          reason,
+          type: "schema_output",
+          attempts: attempt,
+          input: validatedInput,
+          output: rawOutput
+        };
+        if (attempt < maxAttempts && retryOn.has("schema")) {
+          failureContext = { reason, attempt, type: "schema" };
+          continue;
+        }
+        return { ok: false, failure: lastFailure };
+      }
+      const validatedOutput = outputResult.data;
+      const gateFailure = runGates(step.gates, validatedOutput);
+      if (gateFailure) {
+        lastFailure = {
+          step: step.name,
+          reason: `Gate failed: ${gateFailure.reason}`,
+          type: "gate",
+          attempts: attempt,
+          input: validatedInput,
+          output: validatedOutput
+        };
+        if (attempt < maxAttempts && retryOn.has("gate")) {
+          failureContext = {
+            reason: gateFailure.reason,
+            attempt,
+            type: "gate"
+          };
+          continue;
+        }
+        return { ok: false, failure: lastFailure };
+      }
+      return { ok: true, value: validatedOutput };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      lastFailure = {
+        step: step.name,
+        reason: `Exception: ${reason}`,
+        type: "exception",
+        attempts: attempt,
+        input: validatedInput
+      };
+      if (attempt < maxAttempts && retryOn.has("exception")) {
+        failureContext = { reason, attempt, type: "exception" };
+        continue;
+      }
+      return { ok: false, failure: lastFailure };
+    }
+  }
+  return {
+    ok: false,
+    failure: lastFailure ?? {
+      step: step.name,
+      reason: "Unknown failure",
+      type: "exception",
+      attempts: maxAttempts,
+      input: validatedInput
+    }
+  };
+}
+
+// src/types.ts
+var PipelineError = class extends Error {
+  constructor(failure) {
+    super(`Pipeline failed at step "${failure.step}": ${failure.reason}`);
+    this.failure = failure;
+    this.name = "PipelineError";
+  }
+  failure;
+};
+
+// src/pipeline.ts
+var PipelineImpl = class _PipelineImpl {
+  constructor(name, steps) {
+    this.name = name;
+    this.steps = steps;
+  }
+  name;
+  steps;
+  step(newStep) {
+    return new _PipelineImpl(this.name, [
+      ...this.steps,
+      newStep
+    ]);
+  }
+  async run(input) {
+    let current = input;
+    for (const step of this.steps) {
+      const result = await executeStep(step, current);
+      if (!result.ok) {
+        return result;
+      }
+      current = result.value;
+    }
+    return { ok: true, value: current };
+  }
+  async runOrThrow(input) {
+    const result = await this.run(input);
+    if (!result.ok) {
+      throw new PipelineError(result.failure);
+    }
+    return result.value;
+  }
+  describe() {
+    return {
+      name: this.name,
+      steps: this.steps.map((step) => ({
+        name: step.name,
+        inputSchema: zodToJsonSchema.zodToJsonSchema(step.inputSchema),
+        outputSchema: zodToJsonSchema.zodToJsonSchema(step.outputSchema),
+        gates: step.gates.length,
+        retry: step.retry
+      }))
+    };
+  }
+};
+function pipeline(name) {
+  return {
+    name,
+    step(firstStep) {
+      return new PipelineImpl(name, [firstStep]);
+    }
+  };
+}
+
+exports.PipelineError = PipelineError;
+exports.defineStep = defineStep;
+exports.pipeline = pipeline;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/step.ts","../src/runner.ts","../src/types.ts","../src/pipeline.ts"],"names":["zodToJsonSchema"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { z } from 'zod'\nimport type { Step, StepConfig } from './types.js'\n\n/**\n * Define a pipeline step with typed input/output schemas, optional quality gates,\n * and retry configuration.\n *\n * @example\n * ```ts\n * const extractTitle = defineStep({\n *   name: 'extract-title',\n *   input: z.object({ draft: z.string() }),\n *   output: z.object({ title: z.string().max(80) }),\n *   gates: [\n *     (out) => out.title.includes(':')\n *       ? { ok: false, reason: 'title must not contain colons' }\n *       : { ok: true }\n *   ],\n *   retry: { maxAttempts: 3, on: ['schema', 'gate'] },\n *   run: async (input, failureContext) => {\n *     return { title: 'extracted title' };\n *   }\n * });\n * ```\n */\nexport function defineStep<TInput, TOutput>(\n  config: StepConfig<TInput, TOutput>,\n): Step<TInput, TOutput> {\n  return {\n    name: config.name,\n    inputSchema: config.input as z.ZodType<TInput>,\n    outputSchema: config.output as z.ZodType<TOutput>,\n    gates: config.gates ?? [],\n    retry: {\n      maxAttempts: config.retry?.maxAttempts ?? 1,\n      on: config.retry?.on ?? ['schema', 'gate'],\n    },\n    run: config.run,\n  }\n}\n","import type { ZodError } from 'zod'\nimport type { FailureContext, Failure, Gate, Result, Step } from './types.js'\n\n/**\n * Format a ZodError into a human-readable reason string.\n */\nfunction formatZodError(error: ZodError): string {\n  return error.issues\n    .map((issue) => {\n      const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : ''\n      return `${path}${issue.message}`\n    })\n    .join('; ')\n}\n\n/**\n * Run quality gates against a step's output.\n * Returns the first failure, or null if all gates pass.\n */\nfunction runGates(gates: Gate<unknown>[], output: unknown): { reason: string; context?: unknown } | null {\n  for (const gate of gates) {\n    const result = gate(output)\n    if (!result.ok) {\n      return { reason: result.reason, context: result.context }\n    }\n  }\n  return null\n}\n\n/**\n * Execute a single step with retry logic.\n * Returns a Result with the validated output or a structured failure.\n */\nexport async function executeStep(\n  step: Step<unknown, unknown>,\n  input: unknown,\n): Promise<Result<unknown>> {\n  // Validate input schema\n  const inputResult = step.inputSchema.safeParse(input)\n  if (!inputResult.success) {\n    return {\n      ok: false,\n      failure: {\n        step: step.name,\n        reason: `Input validation failed: ${formatZodError(inputResult.error)}`,\n        type: 'schema_input',\n        attempts: 0,\n        input,\n      },\n    }\n  }\n\n  const validatedInput = inputResult.data\n  const maxAttempts = step.retry.maxAttempts\n  const retryOn = new Set(step.retry.on)\n\n  let failureContext: FailureContext | undefined\n  let lastFailure: Failure | undefined\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    try {\n      // Run the step function\n      const rawOutput = await step.run(validatedInput, failureContext)\n\n      // Validate output schema\n      const outputResult = step.outputSchema.safeParse(rawOutput)\n      if (!outputResult.success) {\n        const reason = `Output validation failed: ${formatZodError(outputResult.error)}`\n        lastFailure = {\n          step: step.name,\n          reason,\n          type: 'schema_output',\n          attempts: attempt,\n          input: validatedInput,\n          output: rawOutput,\n        }\n\n        if (attempt < maxAttempts && retryOn.has('schema')) {\n          failureContext = { reason, attempt, type: 'schema' }\n          continue\n        }\n        return { ok: false, failure: lastFailure }\n      }\n\n      const validatedOutput = outputResult.data\n\n      // Run quality gates\n      const gateFailure = runGates(step.gates as Gate<unknown>[], validatedOutput)\n      if (gateFailure) {\n        lastFailure = {\n          step: step.name,\n          reason: `Gate failed: ${gateFailure.reason}`,\n          type: 'gate',\n          attempts: attempt,\n          input: validatedInput,\n          output: validatedOutput,\n        }\n\n        if (attempt < maxAttempts && retryOn.has('gate')) {\n          failureContext = {\n            reason: gateFailure.reason,\n            attempt,\n            type: 'gate',\n          }\n          continue\n        }\n        return { ok: false, failure: lastFailure }\n      }\n\n      // Success\n      return { ok: true, value: validatedOutput }\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error)\n      lastFailure = {\n        step: step.name,\n        reason: `Exception: ${reason}`,\n        type: 'exception',\n        attempts: attempt,\n        input: validatedInput,\n      }\n\n      if (attempt < maxAttempts && retryOn.has('exception')) {\n        failureContext = { reason, attempt, type: 'exception' }\n        continue\n      }\n      return { ok: false, failure: lastFailure }\n    }\n  }\n\n  // Should not reach here, but safety net\n  return {\n    ok: false,\n    failure: lastFailure ?? {\n      step: step.name,\n      reason: 'Unknown failure',\n      type: 'exception',\n      attempts: maxAttempts,\n      input: validatedInput,\n    },\n  }\n}\n","import type { z } from 'zod'\n\n/**\n * Result of a quality gate check.\n * Gates are pure synchronous functions — no LLM calls, no async.\n */\nexport type GateResult =\n  | { ok: true }\n  | { ok: false; reason: string; context?: unknown }\n\n/**\n * A quality gate function. Receives a step's validated output\n * and returns a pass/fail verdict.\n */\nexport type Gate<T> = (output: T) => GateResult\n\n/**\n * Context passed to a step's `run` function on retry attempts.\n * Contains the reason the previous attempt failed, the attempt number,\n * and the failure type so the step can self-correct.\n */\nexport interface FailureContext {\n  reason: string\n  attempt: number\n  type: 'schema' | 'gate' | 'exception'\n}\n\n/**\n * What kinds of failures should trigger a retry.\n */\nexport type RetryOn = 'schema' | 'gate' | 'exception'\n\n/**\n * Retry configuration for a step.\n */\nexport interface RetryConfig {\n  /** Maximum number of attempts (including the first). Default: 1 (no retry). */\n  maxAttempts?: number\n  /** Which failure types trigger a retry. Default: ['schema', 'gate'] */\n  on?: RetryOn[]\n}\n\n/**\n * Configuration for defining a step.\n * Generic parameters are inferred value types, not Zod schema types.\n */\nexport interface StepConfig<TInput, TOutput> {\n  name: string\n  input: z.ZodType<TInput, z.ZodTypeDef, unknown>\n  output: z.ZodType<TOutput, z.ZodTypeDef, unknown>\n  gates?: Gate<TOutput>[]\n  retry?: RetryConfig\n  run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>\n}\n\n/**\n * A defined step — the unit of work in a pipeline.\n * Generic parameters are value types (what the step consumes/produces),\n * not Zod schema types. This allows compile-time type checking of\n * step-to-step handoffs without Zod subclass compatibility issues.\n */\nexport interface Step<TInput = unknown, TOutput = unknown> {\n  readonly name: string\n  readonly inputSchema: z.ZodType<TInput>\n  readonly outputSchema: z.ZodType<TOutput>\n  readonly gates: Gate<TOutput>[]\n  readonly retry: Required<RetryConfig>\n  readonly run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>\n}\n\n/**\n * Structured failure returned when a pipeline halts.\n */\nexport interface Failure {\n  step: string\n  reason: string\n  type: 'schema_input' | 'schema_output' | 'gate' | 'exception'\n  attempts: number\n  input: unknown\n  output?: unknown\n}\n\n/**\n * Pipeline result type. Success or structured failure.\n */\nexport type Result<T> =\n  | { ok: true; value: T }\n  | { ok: false; failure: Failure }\n\n/**\n * Metadata returned by pipeline.describe().\n */\nexport interface PipelineDescription {\n  name: string\n  steps: StepDescription[]\n}\n\nexport interface StepDescription {\n  name: string\n  inputSchema: Record<string, unknown>\n  outputSchema: Record<string, unknown>\n  gates: number\n  retry: Required<RetryConfig>\n}\n\n/**\n * Error thrown by .runOrThrow() on pipeline failure.\n */\nexport class PipelineError extends Error {\n  constructor(public readonly failure: Failure) {\n    super(`Pipeline failed at step \"${failure.step}\": ${failure.reason}`)\n    this.name = 'PipelineError'\n  }\n}\n","import { zodToJsonSchema } from 'zod-to-json-schema'\nimport { executeStep } from './runner.js'\nimport type { Failure, PipelineDescription, Result, Step } from './types.js'\nimport { PipelineError } from './types.js'\n\n/**\n * A compiled pipeline that can be run, described, or run-or-throw.\n */\nexport interface Pipeline<TInput, TOutput> {\n  /** Pipeline name */\n  readonly name: string\n\n  /**\n   * Add a step to the pipeline. Returns a new pipeline with the step appended.\n   * TypeScript enforces that the step's input type matches the previous step's output type.\n   */\n  step<TNext>(step: Step<TOutput, TNext>): Pipeline<TInput, TNext>\n\n  /**\n   * Run the pipeline. Returns a Result — either { ok: true, value } or { ok: false, failure }.\n   * No exceptions escape.\n   */\n  run(input: TInput): Promise<Result<TOutput>>\n\n  /**\n   * Run the pipeline and throw a PipelineError on failure.\n   * For developers who prefer thrown exceptions over Result types.\n   */\n  runOrThrow(input: TInput): Promise<TOutput>\n\n  /**\n   * Return structured metadata about the pipeline:\n   * step names, JSON Schema for inputs/outputs, gate count, retry config.\n   */\n  describe(): PipelineDescription\n}\n\n/**\n * Initial pipeline builder returned by pipeline().\n * The first .step() call sets both input and output types.\n */\nexport interface PipelineBuilder {\n  readonly name: string\n  step<TInput, TOutput>(step: Step<TInput, TOutput>): Pipeline<TInput, TOutput>\n}\n\n/**\n * Internal pipeline implementation.\n */\nclass PipelineImpl<TInput, TOutput> implements Pipeline<TInput, TOutput> {\n  constructor(\n    readonly name: string,\n    // Use Step<unknown, unknown> internally; type safety is at the API boundary\n    private readonly steps: Step<unknown, unknown>[],\n  ) {}\n\n  step<TNext>(newStep: Step<TOutput, TNext>): Pipeline<TInput, TNext> {\n    return new PipelineImpl<TInput, TNext>(this.name, [\n      ...this.steps,\n      newStep as Step<unknown, unknown>,\n    ])\n  }\n\n  async run(input: TInput): Promise<Result<TOutput>> {\n    let current: unknown = input\n\n    for (const step of this.steps) {\n      const result = await executeStep(step, current)\n      if (!result.ok) {\n        return result as { ok: false; failure: Failure }\n      }\n      current = result.value\n    }\n\n    return { ok: true, value: current as TOutput }\n  }\n\n  async runOrThrow(input: TInput): Promise<TOutput> {\n    const result = await this.run(input)\n    if (!result.ok) {\n      throw new PipelineError(result.failure)\n    }\n    return result.value\n  }\n\n  describe(): PipelineDescription {\n    return {\n      name: this.name,\n      steps: this.steps.map((step) => ({\n        name: step.name,\n        inputSchema: zodToJsonSchema(step.inputSchema) as Record<string, unknown>,\n        outputSchema: zodToJsonSchema(step.outputSchema) as Record<string, unknown>,\n        gates: step.gates.length,\n        retry: step.retry,\n      })),\n    }\n  }\n}\n\n/**\n * Create a new pipeline with the given name.\n * Call .step() to add the first step — this sets the pipeline's input type.\n *\n * @example\n * ```ts\n * const myPipeline = pipeline('my-pipeline')\n *   .step(loadData)\n *   .step(transformData)\n *   .step(validateResult);\n *\n * const result = await myPipeline.run({ source: 'input.json' });\n * ```\n */\nexport function pipeline(name: string): PipelineBuilder {\n  return {\n    name,\n    step<TInput, TOutput>(firstStep: Step<TInput, TOutput>): Pipeline<TInput, TOutput> {\n      return new PipelineImpl<TInput, TOutput>(name, [firstStep as Step<unknown, unknown>])\n    },\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+
+/**
+ * Result of a quality gate check.
+ * Gates are pure synchronous functions — no LLM calls, no async.
+ */
+type GateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    context?: unknown;
+};
+/**
+ * A quality gate function. Receives a step's validated output
+ * and returns a pass/fail verdict.
+ */
+type Gate<T> = (output: T) => GateResult;
+/**
+ * Context passed to a step's `run` function on retry attempts.
+ * Contains the reason the previous attempt failed, the attempt number,
+ * and the failure type so the step can self-correct.
+ */
+interface FailureContext {
+    reason: string;
+    attempt: number;
+    type: 'schema' | 'gate' | 'exception';
+}
+/**
+ * What kinds of failures should trigger a retry.
+ */
+type RetryOn = 'schema' | 'gate' | 'exception';
+/**
+ * Retry configuration for a step.
+ */
+interface RetryConfig {
+    /** Maximum number of attempts (including the first). Default: 1 (no retry). */
+    maxAttempts?: number;
+    /** Which failure types trigger a retry. Default: ['schema', 'gate'] */
+    on?: RetryOn[];
+}
+/**
+ * Configuration for defining a step.
+ * Generic parameters are inferred value types, not Zod schema types.
+ */
+interface StepConfig<TInput, TOutput> {
+    name: string;
+    input: z.ZodType<TInput, z.ZodTypeDef, unknown>;
+    output: z.ZodType<TOutput, z.ZodTypeDef, unknown>;
+    gates?: Gate<TOutput>[];
+    retry?: RetryConfig;
+    run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>;
+}
+/**
+ * A defined step — the unit of work in a pipeline.
+ * Generic parameters are value types (what the step consumes/produces),
+ * not Zod schema types. This allows compile-time type checking of
+ * step-to-step handoffs without Zod subclass compatibility issues.
+ */
+interface Step<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly inputSchema: z.ZodType<TInput>;
+    readonly outputSchema: z.ZodType<TOutput>;
+    readonly gates: Gate<TOutput>[];
+    readonly retry: Required<RetryConfig>;
+    readonly run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>;
+}
+/**
+ * Structured failure returned when a pipeline halts.
+ */
+interface Failure {
+    step: string;
+    reason: string;
+    type: 'schema_input' | 'schema_output' | 'gate' | 'exception';
+    attempts: number;
+    input: unknown;
+    output?: unknown;
+}
+/**
+ * Pipeline result type. Success or structured failure.
+ */
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    failure: Failure;
+};
+/**
+ * Metadata returned by pipeline.describe().
+ */
+interface PipelineDescription {
+    name: string;
+    steps: StepDescription[];
+}
+interface StepDescription {
+    name: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    gates: number;
+    retry: Required<RetryConfig>;
+}
+/**
+ * Error thrown by .runOrThrow() on pipeline failure.
+ */
+declare class PipelineError extends Error {
+    readonly failure: Failure;
+    constructor(failure: Failure);
+}
+
+/**
+ * Define a pipeline step with typed input/output schemas, optional quality gates,
+ * and retry configuration.
+ *
+ * @example
+ * ```ts
+ * const extractTitle = defineStep({
+ *   name: 'extract-title',
+ *   input: z.object({ draft: z.string() }),
+ *   output: z.object({ title: z.string().max(80) }),
+ *   gates: [
+ *     (out) => out.title.includes(':')
+ *       ? { ok: false, reason: 'title must not contain colons' }
+ *       : { ok: true }
+ *   ],
+ *   retry: { maxAttempts: 3, on: ['schema', 'gate'] },
+ *   run: async (input, failureContext) => {
+ *     return { title: 'extracted title' };
+ *   }
+ * });
+ * ```
+ */
+declare function defineStep<TInput, TOutput>(config: StepConfig<TInput, TOutput>): Step<TInput, TOutput>;
+
+/**
+ * A compiled pipeline that can be run, described, or run-or-throw.
+ */
+interface Pipeline<TInput, TOutput> {
+    /** Pipeline name */
+    readonly name: string;
+    /**
+     * Add a step to the pipeline. Returns a new pipeline with the step appended.
+     * TypeScript enforces that the step's input type matches the previous step's output type.
+     */
+    step<TNext>(step: Step<TOutput, TNext>): Pipeline<TInput, TNext>;
+    /**
+     * Run the pipeline. Returns a Result — either { ok: true, value } or { ok: false, failure }.
+     * No exceptions escape.
+     */
+    run(input: TInput): Promise<Result<TOutput>>;
+    /**
+     * Run the pipeline and throw a PipelineError on failure.
+     * For developers who prefer thrown exceptions over Result types.
+     */
+    runOrThrow(input: TInput): Promise<TOutput>;
+    /**
+     * Return structured metadata about the pipeline:
+     * step names, JSON Schema for inputs/outputs, gate count, retry config.
+     */
+    describe(): PipelineDescription;
+}
+/**
+ * Initial pipeline builder returned by pipeline().
+ * The first .step() call sets both input and output types.
+ */
+interface PipelineBuilder {
+    readonly name: string;
+    step<TInput, TOutput>(step: Step<TInput, TOutput>): Pipeline<TInput, TOutput>;
+}
+/**
+ * Create a new pipeline with the given name.
+ * Call .step() to add the first step — this sets the pipeline's input type.
+ *
+ * @example
+ * ```ts
+ * const myPipeline = pipeline('my-pipeline')
+ *   .step(loadData)
+ *   .step(transformData)
+ *   .step(validateResult);
+ *
+ * const result = await myPipeline.run({ source: 'input.json' });
+ * ```
+ */
+declare function pipeline(name: string): PipelineBuilder;
+
+export { type Failure, type FailureContext, type Gate, type GateResult, type Pipeline, type PipelineBuilder, type PipelineDescription, PipelineError, type Result, type RetryConfig, type RetryOn, type Step, type StepConfig, type StepDescription, defineStep, pipeline };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+
+/**
+ * Result of a quality gate check.
+ * Gates are pure synchronous functions — no LLM calls, no async.
+ */
+type GateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    context?: unknown;
+};
+/**
+ * A quality gate function. Receives a step's validated output
+ * and returns a pass/fail verdict.
+ */
+type Gate<T> = (output: T) => GateResult;
+/**
+ * Context passed to a step's `run` function on retry attempts.
+ * Contains the reason the previous attempt failed, the attempt number,
+ * and the failure type so the step can self-correct.
+ */
+interface FailureContext {
+    reason: string;
+    attempt: number;
+    type: 'schema' | 'gate' | 'exception';
+}
+/**
+ * What kinds of failures should trigger a retry.
+ */
+type RetryOn = 'schema' | 'gate' | 'exception';
+/**
+ * Retry configuration for a step.
+ */
+interface RetryConfig {
+    /** Maximum number of attempts (including the first). Default: 1 (no retry). */
+    maxAttempts?: number;
+    /** Which failure types trigger a retry. Default: ['schema', 'gate'] */
+    on?: RetryOn[];
+}
+/**
+ * Configuration for defining a step.
+ * Generic parameters are inferred value types, not Zod schema types.
+ */
+interface StepConfig<TInput, TOutput> {
+    name: string;
+    input: z.ZodType<TInput, z.ZodTypeDef, unknown>;
+    output: z.ZodType<TOutput, z.ZodTypeDef, unknown>;
+    gates?: Gate<TOutput>[];
+    retry?: RetryConfig;
+    run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>;
+}
+/**
+ * A defined step — the unit of work in a pipeline.
+ * Generic parameters are value types (what the step consumes/produces),
+ * not Zod schema types. This allows compile-time type checking of
+ * step-to-step handoffs without Zod subclass compatibility issues.
+ */
+interface Step<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly inputSchema: z.ZodType<TInput>;
+    readonly outputSchema: z.ZodType<TOutput>;
+    readonly gates: Gate<TOutput>[];
+    readonly retry: Required<RetryConfig>;
+    readonly run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>;
+}
+/**
+ * Structured failure returned when a pipeline halts.
+ */
+interface Failure {
+    step: string;
+    reason: string;
+    type: 'schema_input' | 'schema_output' | 'gate' | 'exception';
+    attempts: number;
+    input: unknown;
+    output?: unknown;
+}
+/**
+ * Pipeline result type. Success or structured failure.
+ */
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    failure: Failure;
+};
+/**
+ * Metadata returned by pipeline.describe().
+ */
+interface PipelineDescription {
+    name: string;
+    steps: StepDescription[];
+}
+interface StepDescription {
+    name: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    gates: number;
+    retry: Required<RetryConfig>;
+}
+/**
+ * Error thrown by .runOrThrow() on pipeline failure.
+ */
+declare class PipelineError extends Error {
+    readonly failure: Failure;
+    constructor(failure: Failure);
+}
+
+/**
+ * Define a pipeline step with typed input/output schemas, optional quality gates,
+ * and retry configuration.
+ *
+ * @example
+ * ```ts
+ * const extractTitle = defineStep({
+ *   name: 'extract-title',
+ *   input: z.object({ draft: z.string() }),
+ *   output: z.object({ title: z.string().max(80) }),
+ *   gates: [
+ *     (out) => out.title.includes(':')
+ *       ? { ok: false, reason: 'title must not contain colons' }
+ *       : { ok: true }
+ *   ],
+ *   retry: { maxAttempts: 3, on: ['schema', 'gate'] },
+ *   run: async (input, failureContext) => {
+ *     return { title: 'extracted title' };
+ *   }
+ * });
+ * ```
+ */
+declare function defineStep<TInput, TOutput>(config: StepConfig<TInput, TOutput>): Step<TInput, TOutput>;
+
+/**
+ * A compiled pipeline that can be run, described, or run-or-throw.
+ */
+interface Pipeline<TInput, TOutput> {
+    /** Pipeline name */
+    readonly name: string;
+    /**
+     * Add a step to the pipeline. Returns a new pipeline with the step appended.
+     * TypeScript enforces that the step's input type matches the previous step's output type.
+     */
+    step<TNext>(step: Step<TOutput, TNext>): Pipeline<TInput, TNext>;
+    /**
+     * Run the pipeline. Returns a Result — either { ok: true, value } or { ok: false, failure }.
+     * No exceptions escape.
+     */
+    run(input: TInput): Promise<Result<TOutput>>;
+    /**
+     * Run the pipeline and throw a PipelineError on failure.
+     * For developers who prefer thrown exceptions over Result types.
+     */
+    runOrThrow(input: TInput): Promise<TOutput>;
+    /**
+     * Return structured metadata about the pipeline:
+     * step names, JSON Schema for inputs/outputs, gate count, retry config.
+     */
+    describe(): PipelineDescription;
+}
+/**
+ * Initial pipeline builder returned by pipeline().
+ * The first .step() call sets both input and output types.
+ */
+interface PipelineBuilder {
+    readonly name: string;
+    step<TInput, TOutput>(step: Step<TInput, TOutput>): Pipeline<TInput, TOutput>;
+}
+/**
+ * Create a new pipeline with the given name.
+ * Call .step() to add the first step — this sets the pipeline's input type.
+ *
+ * @example
+ * ```ts
+ * const myPipeline = pipeline('my-pipeline')
+ *   .step(loadData)
+ *   .step(transformData)
+ *   .step(validateResult);
+ *
+ * const result = await myPipeline.run({ source: 'input.json' });
+ * ```
+ */
+declare function pipeline(name: string): PipelineBuilder;
+
+export { type Failure, type FailureContext, type Gate, type GateResult, type Pipeline, type PipelineBuilder, type PipelineDescription, PipelineError, type Result, type RetryConfig, type RetryOn, type Step, type StepConfig, type StepDescription, defineStep, pipeline };

package/dist/index.js

@@ -0,0 +1,189 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+// src/step.ts
+function defineStep(config) {
+  return {
+    name: config.name,
+    inputSchema: config.input,
+    outputSchema: config.output,
+    gates: config.gates ?? [],
+    retry: {
+      maxAttempts: config.retry?.maxAttempts ?? 1,
+      on: config.retry?.on ?? ["schema", "gate"]
+    },
+    run: config.run
+  };
+}
+
+// src/runner.ts
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+    return `${path}${issue.message}`;
+  }).join("; ");
+}
+function runGates(gates, output) {
+  for (const gate of gates) {
+    const result = gate(output);
+    if (!result.ok) {
+      return { reason: result.reason, context: result.context };
+    }
+  }
+  return null;
+}
+async function executeStep(step, input) {
+  const inputResult = step.inputSchema.safeParse(input);
+  if (!inputResult.success) {
+    return {
+      ok: false,
+      failure: {
+        step: step.name,
+        reason: `Input validation failed: ${formatZodError(inputResult.error)}`,
+        type: "schema_input",
+        attempts: 0,
+        input
+      }
+    };
+  }
+  const validatedInput = inputResult.data;
+  const maxAttempts = step.retry.maxAttempts;
+  const retryOn = new Set(step.retry.on);
+  let failureContext;
+  let lastFailure;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const rawOutput = await step.run(validatedInput, failureContext);
+      const outputResult = step.outputSchema.safeParse(rawOutput);
+      if (!outputResult.success) {
+        const reason = `Output validation failed: ${formatZodError(outputResult.error)}`;
+        lastFailure = {
+          step: step.name,
+          reason,
+          type: "schema_output",
+          attempts: attempt,
+          input: validatedInput,
+          output: rawOutput
+        };
+        if (attempt < maxAttempts && retryOn.has("schema")) {
+          failureContext = { reason, attempt, type: "schema" };
+          continue;
+        }
+        return { ok: false, failure: lastFailure };
+      }
+      const validatedOutput = outputResult.data;
+      const gateFailure = runGates(step.gates, validatedOutput);
+      if (gateFailure) {
+        lastFailure = {
+          step: step.name,
+          reason: `Gate failed: ${gateFailure.reason}`,
+          type: "gate",
+          attempts: attempt,
+          input: validatedInput,
+          output: validatedOutput
+        };
+        if (attempt < maxAttempts && retryOn.has("gate")) {
+          failureContext = {
+            reason: gateFailure.reason,
+            attempt,
+            type: "gate"
+          };
+          continue;
+        }
+        return { ok: false, failure: lastFailure };
+      }
+      return { ok: true, value: validatedOutput };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      lastFailure = {
+        step: step.name,
+        reason: `Exception: ${reason}`,
+        type: "exception",
+        attempts: attempt,
+        input: validatedInput
+      };
+      if (attempt < maxAttempts && retryOn.has("exception")) {
+        failureContext = { reason, attempt, type: "exception" };
+        continue;
+      }
+      return { ok: false, failure: lastFailure };
+    }
+  }
+  return {
+    ok: false,
+    failure: lastFailure ?? {
+      step: step.name,
+      reason: "Unknown failure",
+      type: "exception",
+      attempts: maxAttempts,
+      input: validatedInput
+    }
+  };
+}
+
+// src/types.ts
+var PipelineError = class extends Error {
+  constructor(failure) {
+    super(`Pipeline failed at step "${failure.step}": ${failure.reason}`);
+    this.failure = failure;
+    this.name = "PipelineError";
+  }
+  failure;
+};
+
+// src/pipeline.ts
+var PipelineImpl = class _PipelineImpl {
+  constructor(name, steps) {
+    this.name = name;
+    this.steps = steps;
+  }
+  name;
+  steps;
+  step(newStep) {
+    return new _PipelineImpl(this.name, [
+      ...this.steps,
+      newStep
+    ]);
+  }
+  async run(input) {
+    let current = input;
+    for (const step of this.steps) {
+      const result = await executeStep(step, current);
+      if (!result.ok) {
+        return result;
+      }
+      current = result.value;
+    }
+    return { ok: true, value: current };
+  }
+  async runOrThrow(input) {
+    const result = await this.run(input);
+    if (!result.ok) {
+      throw new PipelineError(result.failure);
+    }
+    return result.value;
+  }
+  describe() {
+    return {
+      name: this.name,
+      steps: this.steps.map((step) => ({
+        name: step.name,
+        inputSchema: zodToJsonSchema(step.inputSchema),
+        outputSchema: zodToJsonSchema(step.outputSchema),
+        gates: step.gates.length,
+        retry: step.retry
+      }))
+    };
+  }
+};
+function pipeline(name) {
+  return {
+    name,
+    step(firstStep) {
+      return new PipelineImpl(name, [firstStep]);
+    }
+  };
+}
+
+export { PipelineError, defineStep, pipeline };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/step.ts","../src/runner.ts","../src/types.ts","../src/pipeline.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { z } from 'zod'\nimport type { Step, StepConfig } from './types.js'\n\n/**\n * Define a pipeline step with typed input/output schemas, optional quality gates,\n * and retry configuration.\n *\n * @example\n * ```ts\n * const extractTitle = defineStep({\n *   name: 'extract-title',\n *   input: z.object({ draft: z.string() }),\n *   output: z.object({ title: z.string().max(80) }),\n *   gates: [\n *     (out) => out.title.includes(':')\n *       ? { ok: false, reason: 'title must not contain colons' }\n *       : { ok: true }\n *   ],\n *   retry: { maxAttempts: 3, on: ['schema', 'gate'] },\n *   run: async (input, failureContext) => {\n *     return { title: 'extracted title' };\n *   }\n * });\n * ```\n */\nexport function defineStep<TInput, TOutput>(\n  config: StepConfig<TInput, TOutput>,\n): Step<TInput, TOutput> {\n  return {\n    name: config.name,\n    inputSchema: config.input as z.ZodType<TInput>,\n    outputSchema: config.output as z.ZodType<TOutput>,\n    gates: config.gates ?? [],\n    retry: {\n      maxAttempts: config.retry?.maxAttempts ?? 1,\n      on: config.retry?.on ?? ['schema', 'gate'],\n    },\n    run: config.run,\n  }\n}\n","import type { ZodError } from 'zod'\nimport type { FailureContext, Failure, Gate, Result, Step } from './types.js'\n\n/**\n * Format a ZodError into a human-readable reason string.\n */\nfunction formatZodError(error: ZodError): string {\n  return error.issues\n    .map((issue) => {\n      const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : ''\n      return `${path}${issue.message}`\n    })\n    .join('; ')\n}\n\n/**\n * Run quality gates against a step's output.\n * Returns the first failure, or null if all gates pass.\n */\nfunction runGates(gates: Gate<unknown>[], output: unknown): { reason: string; context?: unknown } | null {\n  for (const gate of gates) {\n    const result = gate(output)\n    if (!result.ok) {\n      return { reason: result.reason, context: result.context }\n    }\n  }\n  return null\n}\n\n/**\n * Execute a single step with retry logic.\n * Returns a Result with the validated output or a structured failure.\n */\nexport async function executeStep(\n  step: Step<unknown, unknown>,\n  input: unknown,\n): Promise<Result<unknown>> {\n  // Validate input schema\n  const inputResult = step.inputSchema.safeParse(input)\n  if (!inputResult.success) {\n    return {\n      ok: false,\n      failure: {\n        step: step.name,\n        reason: `Input validation failed: ${formatZodError(inputResult.error)}`,\n        type: 'schema_input',\n        attempts: 0,\n        input,\n      },\n    }\n  }\n\n  const validatedInput = inputResult.data\n  const maxAttempts = step.retry.maxAttempts\n  const retryOn = new Set(step.retry.on)\n\n  let failureContext: FailureContext | undefined\n  let lastFailure: Failure | undefined\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    try {\n      // Run the step function\n      const rawOutput = await step.run(validatedInput, failureContext)\n\n      // Validate output schema\n      const outputResult = step.outputSchema.safeParse(rawOutput)\n      if (!outputResult.success) {\n        const reason = `Output validation failed: ${formatZodError(outputResult.error)}`\n        lastFailure = {\n          step: step.name,\n          reason,\n          type: 'schema_output',\n          attempts: attempt,\n          input: validatedInput,\n          output: rawOutput,\n        }\n\n        if (attempt < maxAttempts && retryOn.has('schema')) {\n          failureContext = { reason, attempt, type: 'schema' }\n          continue\n        }\n        return { ok: false, failure: lastFailure }\n      }\n\n      const validatedOutput = outputResult.data\n\n      // Run quality gates\n      const gateFailure = runGates(step.gates as Gate<unknown>[], validatedOutput)\n      if (gateFailure) {\n        lastFailure = {\n          step: step.name,\n          reason: `Gate failed: ${gateFailure.reason}`,\n          type: 'gate',\n          attempts: attempt,\n          input: validatedInput,\n          output: validatedOutput,\n        }\n\n        if (attempt < maxAttempts && retryOn.has('gate')) {\n          failureContext = {\n            reason: gateFailure.reason,\n            attempt,\n            type: 'gate',\n          }\n          continue\n        }\n        return { ok: false, failure: lastFailure }\n      }\n\n      // Success\n      return { ok: true, value: validatedOutput }\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error)\n      lastFailure = {\n        step: step.name,\n        reason: `Exception: ${reason}`,\n        type: 'exception',\n        attempts: attempt,\n        input: validatedInput,\n      }\n\n      if (attempt < maxAttempts && retryOn.has('exception')) {\n        failureContext = { reason, attempt, type: 'exception' }\n        continue\n      }\n      return { ok: false, failure: lastFailure }\n    }\n  }\n\n  // Should not reach here, but safety net\n  return {\n    ok: false,\n    failure: lastFailure ?? {\n      step: step.name,\n      reason: 'Unknown failure',\n      type: 'exception',\n      attempts: maxAttempts,\n      input: validatedInput,\n    },\n  }\n}\n","import type { z } from 'zod'\n\n/**\n * Result of a quality gate check.\n * Gates are pure synchronous functions — no LLM calls, no async.\n */\nexport type GateResult =\n  | { ok: true }\n  | { ok: false; reason: string; context?: unknown }\n\n/**\n * A quality gate function. Receives a step's validated output\n * and returns a pass/fail verdict.\n */\nexport type Gate<T> = (output: T) => GateResult\n\n/**\n * Context passed to a step's `run` function on retry attempts.\n * Contains the reason the previous attempt failed, the attempt number,\n * and the failure type so the step can self-correct.\n */\nexport interface FailureContext {\n  reason: string\n  attempt: number\n  type: 'schema' | 'gate' | 'exception'\n}\n\n/**\n * What kinds of failures should trigger a retry.\n */\nexport type RetryOn = 'schema' | 'gate' | 'exception'\n\n/**\n * Retry configuration for a step.\n */\nexport interface RetryConfig {\n  /** Maximum number of attempts (including the first). Default: 1 (no retry). */\n  maxAttempts?: number\n  /** Which failure types trigger a retry. Default: ['schema', 'gate'] */\n  on?: RetryOn[]\n}\n\n/**\n * Configuration for defining a step.\n * Generic parameters are inferred value types, not Zod schema types.\n */\nexport interface StepConfig<TInput, TOutput> {\n  name: string\n  input: z.ZodType<TInput, z.ZodTypeDef, unknown>\n  output: z.ZodType<TOutput, z.ZodTypeDef, unknown>\n  gates?: Gate<TOutput>[]\n  retry?: RetryConfig\n  run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>\n}\n\n/**\n * A defined step — the unit of work in a pipeline.\n * Generic parameters are value types (what the step consumes/produces),\n * not Zod schema types. This allows compile-time type checking of\n * step-to-step handoffs without Zod subclass compatibility issues.\n */\nexport interface Step<TInput = unknown, TOutput = unknown> {\n  readonly name: string\n  readonly inputSchema: z.ZodType<TInput>\n  readonly outputSchema: z.ZodType<TOutput>\n  readonly gates: Gate<TOutput>[]\n  readonly retry: Required<RetryConfig>\n  readonly run: (input: TInput, failureContext?: FailureContext) => Promise<TOutput>\n}\n\n/**\n * Structured failure returned when a pipeline halts.\n */\nexport interface Failure {\n  step: string\n  reason: string\n  type: 'schema_input' | 'schema_output' | 'gate' | 'exception'\n  attempts: number\n  input: unknown\n  output?: unknown\n}\n\n/**\n * Pipeline result type. Success or structured failure.\n */\nexport type Result<T> =\n  | { ok: true; value: T }\n  | { ok: false; failure: Failure }\n\n/**\n * Metadata returned by pipeline.describe().\n */\nexport interface PipelineDescription {\n  name: string\n  steps: StepDescription[]\n}\n\nexport interface StepDescription {\n  name: string\n  inputSchema: Record<string, unknown>\n  outputSchema: Record<string, unknown>\n  gates: number\n  retry: Required<RetryConfig>\n}\n\n/**\n * Error thrown by .runOrThrow() on pipeline failure.\n */\nexport class PipelineError extends Error {\n  constructor(public readonly failure: Failure) {\n    super(`Pipeline failed at step \"${failure.step}\": ${failure.reason}`)\n    this.name = 'PipelineError'\n  }\n}\n","import { zodToJsonSchema } from 'zod-to-json-schema'\nimport { executeStep } from './runner.js'\nimport type { Failure, PipelineDescription, Result, Step } from './types.js'\nimport { PipelineError } from './types.js'\n\n/**\n * A compiled pipeline that can be run, described, or run-or-throw.\n */\nexport interface Pipeline<TInput, TOutput> {\n  /** Pipeline name */\n  readonly name: string\n\n  /**\n   * Add a step to the pipeline. Returns a new pipeline with the step appended.\n   * TypeScript enforces that the step's input type matches the previous step's output type.\n   */\n  step<TNext>(step: Step<TOutput, TNext>): Pipeline<TInput, TNext>\n\n  /**\n   * Run the pipeline. Returns a Result — either { ok: true, value } or { ok: false, failure }.\n   * No exceptions escape.\n   */\n  run(input: TInput): Promise<Result<TOutput>>\n\n  /**\n   * Run the pipeline and throw a PipelineError on failure.\n   * For developers who prefer thrown exceptions over Result types.\n   */\n  runOrThrow(input: TInput): Promise<TOutput>\n\n  /**\n   * Return structured metadata about the pipeline:\n   * step names, JSON Schema for inputs/outputs, gate count, retry config.\n   */\n  describe(): PipelineDescription\n}\n\n/**\n * Initial pipeline builder returned by pipeline().\n * The first .step() call sets both input and output types.\n */\nexport interface PipelineBuilder {\n  readonly name: string\n  step<TInput, TOutput>(step: Step<TInput, TOutput>): Pipeline<TInput, TOutput>\n}\n\n/**\n * Internal pipeline implementation.\n */\nclass PipelineImpl<TInput, TOutput> implements Pipeline<TInput, TOutput> {\n  constructor(\n    readonly name: string,\n    // Use Step<unknown, unknown> internally; type safety is at the API boundary\n    private readonly steps: Step<unknown, unknown>[],\n  ) {}\n\n  step<TNext>(newStep: Step<TOutput, TNext>): Pipeline<TInput, TNext> {\n    return new PipelineImpl<TInput, TNext>(this.name, [\n      ...this.steps,\n      newStep as Step<unknown, unknown>,\n    ])\n  }\n\n  async run(input: TInput): Promise<Result<TOutput>> {\n    let current: unknown = input\n\n    for (const step of this.steps) {\n      const result = await executeStep(step, current)\n      if (!result.ok) {\n        return result as { ok: false; failure: Failure }\n      }\n      current = result.value\n    }\n\n    return { ok: true, value: current as TOutput }\n  }\n\n  async runOrThrow(input: TInput): Promise<TOutput> {\n    const result = await this.run(input)\n    if (!result.ok) {\n      throw new PipelineError(result.failure)\n    }\n    return result.value\n  }\n\n  describe(): PipelineDescription {\n    return {\n      name: this.name,\n      steps: this.steps.map((step) => ({\n        name: step.name,\n        inputSchema: zodToJsonSchema(step.inputSchema) as Record<string, unknown>,\n        outputSchema: zodToJsonSchema(step.outputSchema) as Record<string, unknown>,\n        gates: step.gates.length,\n        retry: step.retry,\n      })),\n    }\n  }\n}\n\n/**\n * Create a new pipeline with the given name.\n * Call .step() to add the first step — this sets the pipeline's input type.\n *\n * @example\n * ```ts\n * const myPipeline = pipeline('my-pipeline')\n *   .step(loadData)\n *   .step(transformData)\n *   .step(validateResult);\n *\n * const result = await myPipeline.run({ source: 'input.json' });\n * ```\n */\nexport function pipeline(name: string): PipelineBuilder {\n  return {\n    name,\n    step<TInput, TOutput>(firstStep: Step<TInput, TOutput>): Pipeline<TInput, TOutput> {\n      return new PipelineImpl<TInput, TOutput>(name, [firstStep as Step<unknown, unknown>])\n    },\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@cueapi/cuechain",
+  "version": "0.0.1",
+  "description": "Contract-verification primitive for TypeScript AI agent pipelines",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "format": "biome format --write src/ tests/",
+    "ci": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "pipeline",
+    "contract",
+    "verification",
+    "typescript",
+    "zod",
+    "workflow",
+    "cueapi"
+  ],
+  "author": "Vector Apps Inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cueapi/cuechain.git"
+  },
+  "homepage": "https://github.com/cueapi/cuechain",
+  "bugs": {
+    "url": "https://github.com/cueapi/cuechain/issues"
+  },
+  "dependencies": {
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^25.6.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@biomejs/biome",
+      "esbuild"
+    ]
+  }
+}