Deterministic workflow kernel for AI systems — replay + diff for AI decisions
npm install verist



Deterministic workflow kernel for AI systems — replay + diff for AI decisions.
Update a prompt or model, recompute against past inputs, and see exactly what decisions would change before shipping. Human corrections survive recomputation by design.
``bash`
npm install verist zod
`ts
import { defineStep, run, recompute, formatDiff } from "verist";
import { z } from "zod";
const OutputSchema = z.object({ claims: z.array(z.string()) });
// v1: precise extraction
const extractV1 = defineStep({
name: "extract-claims",
input: z.object({ text: z.string() }),
output: OutputSchema,
run: async (input) => ({
output: { claims: ["Revenue: $5M", "Headcount: 45"] },
}),
});
const baseline = await run(extractV1, { text: "Revenue was $5M..." });
// v2: changed logic — what breaks?
const extractV2 = defineStep({
name: "extract-claims",
input: z.object({ text: z.string() }),
output: OutputSchema,
run: async (input) => ({
output: { claims: ["Revenue was strong"] },
}),
});
const result = await recompute(baseline.value, extractV2);
if (result.ok) {
console.log(result.value.status); // "value_changed"
console.log(formatDiff(result.value.outputDiff));
// claims[0]: "Revenue: $5M" → "Revenue was strong"
// - claims[1]: "Headcount: 45"
}
`
For LLM-powered steps, see @verist/llm which adds extract() and defineExtractionStep().
- defineStep(config) — define a step with Zod input/output schemas and a run functionrun(step, input, opts?)
- — execute a step, returns ResultrunStep(params)
- — execute with explicit workflow context (ID, version, artifact capture)fail(code, message, opts?)
- — return a structured error from a step (preserves error code and retryable flag)
- recompute(baseline, step, opts?) — rerun a step against a previous result or snapshot, returns diff + status
- compareSnapshots(before, after) — diff two snapshots directly
- diff(a, b) — compute a diff between any two objects
- formatDiff(diff) — human-readable diff output
- applyDiff(target, diff) — apply a diff to produce a new object
- createSnapshotFromResult(result) — capture a StepResult as an immutable snapshot
- defineWorkflow(config) — declare a workflow with named steps
- createContextFactory(adapters) — create execution contexts with metadata and artifact capture
Steps can return commands that describe what should happen next:
- invoke(step, input) — trigger another step
- fanout(step, items) — trigger a step for each item
- review(reason, payload?) — pause for human review
- suspend(reason, opts?) — pause until external resume
- emit(type, payload) — emit a domain event
Errors are values, not exceptions:
`ts`
const result = await run(step, input);
if (result.ok) {
console.log(result.value.output);
} else {
// "input_validation" | "output_validation" | "execution_failed" | custom codes via fail()
console.log(result.error.code, result.error.retryable);
}
recompute() classifies results for CI integration:
| Status | Meaning |
| ------------------ | ------------------------------------------- |
| clean | Output identical to baseline |value_changed
| | Output differs (regression or improvement) |schema_violation
| | New output fails baseline schema validation |
| Package | Description |
| -------------------------------------------------------------------- | ---------------------------------------------- |
| verist | Core kernel (this package) |
| @verist/cli | CLI — verist init, capture, diff, test |@verist/llm
| | LLM adapters (OpenAI, Anthropic) with tracing |@verist/storage
| | Storage interface + in-memory store |@verist/storage-pg` | PostgreSQL adapter (Drizzle ORM) |
|
- Getting Started
- Replay and Diff Guide
- GitHub