Feature delivery

Use this process to deliver one change from a written request to an approved result without a model account. The first draft passes its own tests but misses a requirement. The review panel catches the miss and sends it back. The line repairs the work, proves it again, and approves the exact final bytes.

Graph

The analyse stage turns the issue into typed acceptance criteria before any code runs. Work with no accepted criteria fails the line.
The implement stage writes the change as real files: src/retry.js and its tests. The first draft covers two of the three criteria.
The test stage runs the tests as a command gate. The line advances only when the command exits 0, never on a self-report.
The review stage is a panel of three reviewers, and two votes pass it. Round one fails with findings, and the panel sends them back to implement as a kickback, bounded by the line’s kickback budget.
The re-run of implement is the repair: it reads the last review’s findings and covers the third criterion. The test and review stages re-run with it, so nothing passes on the strength of the fix alone.
The approve stage binds the approval to the sha256 of the final source. The request, the claim, the answer and the digest are durable events in an approval record beside the run record. The stage reads the answer, and a no fails the line.

Contract

Item	Value
Input	One written issue
Output	A pass result and an approved change
Permissions	Writes only inside its own temporary directory. The test stage starts one `node --test` child process that inherits the run environment. No network access
Limit	Two kickbacks
Evidence	One JSON result on standard output and one JSONL run record read back before exit

Source

Copy examples/production-lines/feature-delivery.line.ts from the repository. The example imports only the public package exports.

import { createHash } from 'node:crypto';
import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import {
  commandSucceeds,
  compileGraph,
  createCallbackGate,
  createStoredCallbackClient,
  dagGraphType,
  defineJob,
  fnJob,
  gateJob,
  persistRunDefinition,
  pipeline,
  resolveGraphPlan,
  reviewPanel,
  revisionRequest,
  run,
  type JobContext,
  type Sha256Digest,
} from '@obversa/runtime';
import { defineGraphDefinition } from '@obversa/runtime/testing';
import { createLocalRunStorage } from '@obversa/runtime/storage/local';

// The request this line delivers. A host reads it from an issue tracker; the
// stages below see it only through the criteria the analyse stage accepts.
const ISSUE =
  'The checkout client must retry a failed request, must cap how many ' +
  'times it retries, and must stop retrying when the caller aborts.';

interface Criterion {
  readonly id: string;
  readonly need: string;
  readonly match: string;
}

const CATALOG: readonly Criterion[] = [
  { id: 'retry', need: 'retries a failing request until it succeeds', match: 'retry' },
  { id: 'cap', need: 'caps the retry attempts', match: 'cap' },
  { id: 'abort', need: 'stops when the caller aborts', match: 'abort' },
];

function acceptedCriteria(ctx: JobContext): readonly Criterion[] {
  const value = ctx.state['criteria'];
  return Array.isArray(value) ? (value as readonly Criterion[]) : [];
}

// The approval record: the request, the claim, the answer and the digest are
// durable events in their own store beside the run record, so a refused
// approval is on the record, not in memory.
const APPROVAL_RUN_ID = 'feature-delivery-approval';
const APPROVAL_STORAGE_POLICY = {
  schemaVersion: 1,
  maxEventPayloadBytes: 64_000,
  maxAppendBatchBytes: 128_000,
  maxArtifactBytes: 1_000_000,
  maxTotalArtifactBytesPerRun: 4_000_000,
  retention: 'until-run-delete',
  sensitiveContent: {
    marked: 'reject',
    exact: 'reject',
    freeText: 'redact-before-hash',
  },
} as const;
const APPROVAL_PACKAGE = {
  source: 'npm:@example/feature-delivery',
  version: '1.0.0',
  digest: `sha256:${'f'.repeat(64)}` as Sha256Digest,
};
const approvalGraph = compileGraph(
  dagGraphType,
  defineGraphDefinition({
    id: 'feature-delivery-approval',
    definitionVersion: 1,
    data: {
      globalConcurrency: 1,
      keyedConcurrency: {},
      stopOnError: true,
      retryCapPerNode: 0,
    },
    nodes: [{ id: 'approve', data: { kind: 'required', key: null } }],
    edges: [],
  }),
);
const approvalPlan = resolveGraphPlan(approvalGraph.describe(), {
  package: APPROVAL_PACKAGE,
  admission: { package: APPROVAL_PACKAGE, permissions: [] },
  executionLanes: [],
});

// The first draft covers retry and cap but not abort — green on its own tests,
// which is exactly the gap a review panel exists to catch.
const DRAFT_SOURCE = [
  'export const MAX_ATTEMPTS = 3;',
  '',
  'export async function retry(fn, options = {}) {',
  '  const attempts = options.attempts ?? MAX_ATTEMPTS;',
  '  const delayMs = options.delayMs ?? 10;',
  '  let lastError;',
  '  for (let used = 0; used < attempts; used += 1) {',
  '    try {',
  '      return await fn();',
  '    } catch (error) {',
  '      lastError = error;',
  '      if (used + 1 < attempts) {',
  '        await new Promise((resolve) => setTimeout(resolve, delayMs));',
  '      }',
  '    }',
  '  }',
  '  throw lastError;',
  '}',
  '',
].join('\n');

const REPAIRED_SOURCE = [
  'export const MAX_ATTEMPTS = 3;',
  '',
  'export async function retry(fn, options = {}) {',
  '  const attempts = options.attempts ?? MAX_ATTEMPTS;',
  '  const delayMs = options.delayMs ?? 10;',
  '  const signal = options.signal;',
  '  let lastError;',
  '  for (let used = 0; used < attempts; used += 1) {',
  "    if (signal && signal.aborted) {",
  "      throw new Error('aborted');",
  '    }',
  '    try {',
  '      return await fn();',
  '    } catch (error) {',
  '      lastError = error;',
  '      if (used + 1 < attempts) {',
  '        await new Promise((resolve) => setTimeout(resolve, delayMs));',
  '      }',
  '    }',
  '  }',
  '  throw lastError;',
  '}',
  '',
].join('\n');

const DRAFT_TESTS = [
  "import assert from 'node:assert/strict';",
  "import test from 'node:test';",
  "import { retry } from '../src/retry.js';",
  '',
  "test('retry: a failing request is retried until it succeeds', async () => {",
  '  let calls = 0;',
  '  const value = await retry(async () => {',
  '    calls += 1;',
  "    if (calls < 3) throw new Error('flaky');",
  "    return 'ok';",
  '  });',
  "  assert.equal(value, 'ok');",
  '  assert.equal(calls, 3);',
  '});',
  '',
  "test('cap: the retry attempts are capped', async () => {",
  '  let calls = 0;',
  '  await assert.rejects(',
  '    retry(async () => {',
  '      calls += 1;',
  "      throw new Error('down');",
  '    }),',
  '    /down/,',
  '  );',
  '  assert.equal(calls, 3);',
  '});',
  '',
].join('\n');

const REPAIRED_TESTS = [
  DRAFT_TESTS,
  "test('abort: retrying stops when the caller aborts', async () => {",
  '  const controller = new AbortController();',
  '  controller.abort();',
  '  let calls = 0;',
  '  await assert.rejects(',
  '    retry(',
  '      async () => {',
  '        calls += 1;',
  "        return 'ok';",
  '      },',
  '      { signal: controller.signal },',
  '    ),',
  '    /aborted/,',
  '  );',
  '  assert.equal(calls, 0);',
  '});',
  '',
].join('\n');

// 1. Analyse: the issue becomes typed, accepted criteria before any code runs.
const analyse = fnJob('analyse', (ctx) => {
  const text = ISSUE.toLowerCase();
  const criteria = CATALOG.filter((criterion) => text.includes(criterion.match));
  if (!criteria.length) {
    return { status: 'fail', summary: 'the issue names no deliverable work' };
  }
  ctx.state['criteria'] = criteria;
  return {
    status: 'pass',
    summary: `accepted: ${criteria.map((criterion) => criterion.id).join(', ')}`,
  };
});

// 2. Implement: writes the change as real files. The first run writes the
// draft; a kickback re-run reads the review findings and repairs. In a real
// line this stage is an agentJob with an engine — the plumbing around it is
// identical.
const implement = fnJob('implement', async (ctx) => {
  const criteria = acceptedCriteria(ctx);
  if (!criteria.length) {
    return { status: 'fail', summary: 'no accepted criteria to implement' };
  }
  const findings = ctx.lastReview?.revision?.findings ?? [];
  const fixes = new Set(
    findings
      .map((finding) => finding.scope)
      .filter((scope): scope is string => typeof scope === 'string'),
  );
  const unsupported = [...fixes].filter((scope) => scope !== 'abort');
  if (unsupported.length) {
    return {
      status: 'fail',
      summary: `no repair for findings outside the abort criterion: ${unsupported.join(', ')}`,
    };
  }
  const repaired = fixes.size > 0;
  const root = ctx.workspace.dir;
  await mkdir(join(root, 'src'), { recursive: true });
  await mkdir(join(root, 'test'), { recursive: true });
  await writeFile(
    join(root, 'src/retry.js'),
    repaired ? REPAIRED_SOURCE : DRAFT_SOURCE,
  );
  await writeFile(
    join(root, 'test/retry.test.js'),
    repaired ? REPAIRED_TESTS : DRAFT_TESTS,
  );
  return {
    status: 'pass',
    summary: repaired
      ? `repaired from review findings: ${[...fixes].join(', ')}`
      : 'wrote the first draft',
  };
});

// 3. Test: a real command gate. The line advances only when the tests exit 0,
// never on a worker's or a reviewer's self-report.
const testStage = gateJob(
  'test',
  commandSucceeds('node', ['--test', 'test/retry.test.js'], {
    timeoutMs: 30_000,
    captureOutput: true,
  }),
);

// 4. Review: a panel of three reviewers, two votes required. A failing panel
// sends its findings back to the implement stage as a kickback.
function coverageReviewer(
  name: string,
  read: (root: string) => Promise<string>,
  covers: (content: string, criterion: Criterion) => boolean,
) {
  return fnJob(name, async (ctx) => {
    const criteria = acceptedCriteria(ctx);
    const content = await read(ctx.workspace.dir);
    const missing = criteria.filter((criterion) => !covers(content, criterion));
    if (!missing.length) {
      return {
        status: 'pass',
        summary: `${name}: every accepted criterion is covered`,
      };
    }
    return revisionRequest({
      reason: `${name}: ${missing.length} accepted criterion not covered`,
      findings: missing.map((criterion) => ({
        reviewer: name,
        scope: criterion.id,
        evidence: `${name} sees no coverage for "${criterion.need}".`,
      })),
    });
  });
}

const review = reviewPanel({
  label: 'review-panel',
  reviewers: [
    {
      name: 'correctness',
      job: coverageReviewer(
        'correctness',
        (root) => readFile(join(root, 'src/retry.js'), 'utf8'),
        (source, criterion) =>
          criterion.id === 'retry'
            ? source.includes('async function retry')
            : criterion.id === 'cap'
              ? source.includes('attempts')
              : source.includes('signal'),
      ),
    },
    {
      name: 'tests',
      job: coverageReviewer(
        'tests',
        (root) => readFile(join(root, 'test/retry.test.js'), 'utf8'),
        (tests, criterion) => tests.includes(`test('${criterion.id}:`),
      ),
    },
    {
      name: 'api',
      job: fnJob('api', async (ctx) => {
        const source = await readFile(join(ctx.workspace.dir, 'src/retry.js'), 'utf8');
        const shaped =
          source.includes('export async function retry') &&
          source.includes('export const MAX_ATTEMPTS');
        return shaped
          ? { status: 'pass', summary: 'api: exports retry and MAX_ATTEMPTS' }
          : revisionRequest({
              reason: 'api: module shape is wrong',
              findings: [
                {
                  reviewer: 'api',
                  scope: 'shape',
                  evidence: 'src/retry.js must export retry and MAX_ATTEMPTS.',
                },
              ],
            });
      }),
    },
  ],
  pass: 2,
  target: 'implement',
});

// 5. Approve: the change ships only when the responder answers yes. The
// request carries the sha256 of the final source, so approving anything else
// would be a different request. The request, the claim, the answer and the
// digest are durable events in the approval record beside the run record.
// The stage reads the answer: a no fails the line with the reason. A host
// swaps the scripted submit for a human responder; the request, digest and
// claim protocol are the same.
const approve = fnJob('approve', async (ctx) => {
  const bytes = await readFile(join(ctx.workspace.dir, 'src/retry.js'));
  const sha256 = createHash('sha256').update(bytes).digest('hex');
  const storage = createLocalRunStorage({
    directory: join(ctx.workspace.dir, 'approval-record'),
    namespace: 'feature-delivery-example',
    policy: APPROVAL_STORAGE_POLICY,
  });
  await persistRunDefinition(storage, {
    runId: APPROVAL_RUN_ID,
    eventId: 'feature-delivery-approval-started',
    timestamp: '2026-01-01T00:00:00.000Z',
    graphDefinition: approvalGraph.definition,
    resolvedPlan: approvalPlan,
    resolvedInputs: {},
    workspaceBinding: null,
    hostBinding: null,
  });
  const request = createCallbackGate({
    gateId: 'ship-change',
    gateVersion: 1,
    decisionText: 'Approve shipping this exact change?',
    responseSchema: {
      type: 'object',
      properties: { approved: { type: 'boolean' } },
      required: ['approved'],
    },
    input: { file: 'src/retry.js', sha256 },
  });
  const client = await createStoredCallbackClient(storage, APPROVAL_RUN_ID);
  await client.post(request);
  const claim = await client.claim(request.requestId, 'release-owner');
  if (!claim.ok) {
    return { status: 'fail', summary: `the approval could not be claimed: ${claim.kind}` };
  }
  const submitted = await client.submit(
    request.requestId,
    claim.claimToken,
    'release-owner',
    request.digest,
    { approved: true },
    { id: 'release-owner', kind: 'human' },
  );
  if (!submitted.ok) {
    return { status: 'fail', summary: `the approval was not submitted: ${submitted.reason}` };
  }
  const answer = submitted.response as { approved?: unknown };
  if (answer.approved !== true) {
    return {
      status: 'fail',
      summary: 'the approver answered no, so the change does not ship',
    };
  }
  return {
    status: 'pass',
    summary: `approved src/retry.js (${sha256.slice(0, 12)})`,
  };
});

const productionLine = defineJob(
  pipeline(
    'feature-delivery',
    [
      { name: 'analyse', job: analyse },
      { name: 'implement', job: implement },
      { name: 'test', job: testStage },
      { name: 'review', job: review },
      { name: 'approve', job: approve },
    ],
    { maxKickbacks: 2 },
  ),
);

interface RecordedEvent {
  kind?: string;
  label?: string;
  accepted?: boolean;
}

async function main(): Promise<void> {
  const workspace = await realpath(await mkdtemp(join(tmpdir(), 'feature-delivery-')));
  try {
    const result = await run(productionLine, {
      cwd: workspace,
      runId: 'feature-delivery-example',
      recordTo: 'auto',
    });
    const events: RecordedEvent[] = result.recordPath
      ? (await readFile(result.recordPath, 'utf8'))
          .split('\n')
          .filter(Boolean)
          .map((line) => JSON.parse(line) as RecordedEvent)
      : [];
    console.log(
      JSON.stringify(
        {
          status: result.outcome.status,
          implementRuns: events.filter(
            (event) => event.kind === 'job:end' && event.label === 'implement',
          ).length,
          reviewRounds: events.filter(
            (event) => event.kind === 'job:end' && event.label === 'review-panel',
          ).length,
          acceptedKickbacks: events.filter(
            (event) => event.kind === 'dag:kickback' && event.accepted === true,
          ).length,
        },
        null,
        2,
      ),
    );
    if (result.outcome.status !== 'pass') process.exitCode = 1;
  } finally {
    await rm(workspace, { recursive: true, force: true });
  }
}

void main();

Run the line

From an Obversa checkout, run:

pnpm example:feature

The result is:

{
  "status": "pass",
  "implementRuns": 2,
  "reviewRounds": 2,
  "acceptedKickbacks": 1
}

The line reads its own record back before it exits. implementRuns and reviewRounds count the recorded stage runs, and acceptedKickbacks counts the accepted dag:kickback events, so the numbers come from the record rather than from memory. The approval answer lands in its own durable record beside the run record. After you copy the source into a project that has @obversa/runtime and tsx installed, pnpm exec tsx feature-delivery.line.ts runs the same line.

Failure behavior

The line allows two kickbacks. If the panel keeps rejecting the work, the budget is spent, the review’s failed verdict stands, and the process exits with code 1. A refused approval fails the line the same way: the approver who answers no stops the ship, and the no is a durable event in the approval record. The line never advances past a failing test command, so an unproven draft cannot reach the panel or the approval.

Pause, resume, and retry behavior

This line does not pause and stores nothing outside its own temporary directory, which is removed when it exits. It changes nothing a reader owns, so a full retry from the start is safe.

Engine lanes

This line uses function jobs. It does not call an engine, and it needs no model account. Each stage names where an engine goes: replace implement’s fnJob with agentJob and an engine, and the same line drives a model that writes the change; replace the panel’s reviewer jobs with agentCheck conditions and models read the code; put a person behind the approval gate in place of the scripted submit, answering through the same claim and digest protocol against the same record. The stages, the kickback, and the records stay the same.

Start

Concepts

Memory

Workspace

Graphs

Proof

Storage

Runtime

Processes

Hosts

Packages

Feature delivery

Graph

Contract

Source

Run the line

Failure behavior

Pause, resume, and retry behavior

Engine lanes

​Graph

​Contract

​Source

​Run the line

​Failure behavior

​Pause, resume, and retry behavior

​Engine lanes

Graph

Contract

Source

Run the line

Failure behavior

Pause, resume, and retry behavior

Engine lanes