> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Review loop

> Record a bounded generation, review, and repair cycle.

`convergence` is a pure graph form. It folds recorded form events into state
and returns the next command.

The form has one generator, one done check, one repair node, and one or more
review seats. A review seat is an independent reviewer node.

## Run the example

From an Obversa checkout, run:

```bash theme={null}
pnpm example:review-loop
```

The example records two valid passes from separate providers and model
families. It prints this JSON report:

```json theme={null}
{"decision":{"kind":"complete","output":{"iterations":1,"restarts":0,"seats":{"claude-review":"accepted","codex-review":"accepted"},"findings":[]}},"events":8,"planDigest":"sha256:eb9d0cf0279a1e8a735c69b20e3786042c942e8f7fa69b9431d4b89760e8ae54","bounds":{"dispatches":{"min":{"kind":"known","value":4},"max":{"kind":"known","value":11}},"maxConcurrency":{"kind":"known","value":2},"maxFanOut":{"kind":"known","value":2}}}
```

The clean-consumer check compiles and runs the same source from the packed
package with TypeScript 6 and TypeScript 7. Its source is
`examples/packages/review-loop.ts`.

## Define a review loop

The next fragment is from `examples/packages/review-loop.ts`.

```ts theme={null}
import {
  compileGraph,
  convergence,
  type ConvergenceDefinition,
} from '@obversa/runtime';

const claudeLane = {
  id: 'claude-review',
  requested: {
    adapter: 'mock', provider: 'anthropic', modelFamily: 'claude', model: 'mock-claude', tools: [],
  },
  knownSubstitutions: [],
} as const;
const codexLane = {
  id: 'codex-review',
  requested: {
    adapter: 'mock', provider: 'openai', modelFamily: 'gpt', model: 'mock-gpt', tools: [],
  },
  knownSubstitutions: [],
} as const;

const definition: ConvergenceDefinition = {
  id: 'release-review',
  definitionVersion: 1,
  data: {
    maxIterations: 2,
    maxReviewRestarts: 1,
    quorum: 2,
    requireDiversity: true,
    skippableSeats: [],
    seatConcurrency: 2,
    retryCapPerNode: 0,
  },
  nodes: [
    { id: 'draft', data: { role: 'generator' } },
    { id: 'done-check', data: { role: 'evaluator' } },
    {
      id: 'claude-review',
      data: { role: 'seat', lane: claudeLane, evidencePaths: ['draft'] },
    },
    {
      id: 'codex-review',
      data: { role: 'seat', lane: codexLane, evidencePaths: ['draft'] },
    },
    { id: 'repair', data: { role: 'repair' } },
  ],
  edges: [],
};

const graph = compileGraph(convergence, definition);
```

## Recorded behaviour

* **Node records:** The form accepts dispatch, completion, failure, pause, and
  resume records for each node attempt.
* **Review records:** A seat pass includes its confidence, input hashes, and
  workspace fingerprint. Evaluator evidence also names one proof artifact
  digest. Every seat dispatch receives that digest, and every seat result must
  echo it. A missing or changed digest makes that result invalid and dispatches
  the seat again while its retry limit permits. Findings from that result cannot
  enter repair inputs or finding counts. The seat's lane declares the
  provider and model family. `evidencePaths` names the input hashes that can
  invalidate that seat; omitting it makes every input hash relevant. The form
  checks whether a pairwise-distinct provider and model-family subset meets the
  quorum.
* **Repair records:** Findings can send the form to its repair node. A later
  cycle keeps valid seat passes and reruns invalid seats.
* **Policy records:** New evaluator evidence invalidates each seat whose named
  input hash changed. A producer can also invalidate an in-flight seat or record
  a limit pause.

The form consumes the graph executor's upper-case failure codes. `ABORTED`
pauses the run. `ENGINE_UNAVAILABLE` skips a declared skippable seat and pauses
for a required seat. Other node failures use the declared retry cap before the
required seat pauses as unresolved.

## Stored plans and evaluator failures

The convergence graph type uses version 2. A stored plan for version 1 is
refused by `createGraphExecutor` with `STORED_GRAPH_MISMATCH` before a node
starts. The executor does not convert the stored plan. Start a new run with a
plan compiled from version 2 to use this evidence contract.

When the evaluator completes without valid review evidence, the form returns
`fail` with code `CONVERGENCE_REVIEW_EVIDENCE_INVALID`. It dispatches no review
seat. Reopening the run preserves that failure. Correct the evaluator and
start a new run.

## Limits and output

`maxIterations`, `maxReviewRestarts`, and `retryCapPerNode` bound the described
dispatch count. `seatConcurrency` sets the review batch size.

The complete output states the cycle count, repair count, result for each review
seat, and any blocking findings returned by seats outside the accepted quorum.