@verist/replay

Deterministic replay and recomputation for Verist workflows.

Installation

npm install @verist/replay

Usage

Creating Snapshots

Use createSnapshotFromResult after step execution:

import { run } from "@verist/core";
import {
  createSnapshotFromResult,
  recompute,
  formatDiff,
} from "@verist/replay";

const result = await run(step, input, {
  adapters,
  workflowId: "verify-doc",
  workflowVersion: "1.0.0",
});

if (result.ok) {
  // Create snapshot for later replay/recompute
  const snapshot = await createSnapshotFromResult(result.value, {
    captureCommands: true, // Required for command diffing
  });

  // Store snapshot for later use
  await artifactStore.save(snapshot);
}

Recomputing with Diff

Later, recompute with a fresh execution and compare:

import { recompute, formatDiff } from "@verist/replay";

const recomputed = await recompute(snapshot, step, ctx, {
  validate: true,
  strictOutput: true, // catch missing required fields that .partial() allows
});

if (recomputed.ok) {
  const { status, deltaDiff, commandsDiff, schemaViolations } =
    recomputed.value;

  switch (status) {
    case "schema_violation":
      console.log("Schema violations:", schemaViolations);
      break;
    case "value_changed":
      console.log("State changed:", formatDiff(deltaDiff!));
      break;
    case "clean":
      console.log("No regressions");
      break;
  }

  if (commandsDiff && !commandsDiff.equal) {
    console.log("Control flow changed:", formatDiff(commandsDiff));
  }
}

Loading Stored Output

Load historical results without re-execution:

import { loadOutput } from "@verist/replay";

const output = await loadOutput(snapshot);
if (output.ok) {
  console.log(output.value.delta);
}

API

Hashing

• hashValue(value) — SHA-256 hash of JSON-serializable value (re-exported from @verist/core)
• hashWithContent(value) — Returns both hash and serialized content (async)

Artifacts

• captureArtifact(kind, content, opts?) — Create artifact with hash (async)
• createSnapshot(params) — Create snapshot from raw params (async)
• createSnapshotFromResult(result, opts?) — Create snapshot from step result (async)

Diff

• diff(before, after) — Generate structural diff
• applyDiff(base, diff) — Apply diff to produce new value
• formatDiff(diff) — Human-readable diff output
• formatPath(path) — Format a path array as a dotted string
• diffEffectiveState(before, after) — Diff layered states by effective view

Replay

• loadOutput(snapshot) — Load stored output from snapshot (async)
• recompute(snapshot, step, ctx, options?) — Fresh execution with diff (async). Options: validate, strictOutput, captureArtifacts
• compareSnapshots(original, updated) — Compare two snapshots

Design

This package produces and consumes artifacts but does not store them. Storage is external — bring your own database, S3, or content-addressable store.

The onArtifact callback in @verist/core is the primary integration point. This package provides utilities to consume those artifacts for snapshot creation and recomputation.

See SPEC-replay for detailed documentation.