[b-erdem]

Stacked on #6 — review that one first; this diff is the replay work alone.

Belay already journals the result of every step, so a failed job carries everything needed to run its code again on the exact values it saw. Until now that was reachable only as Belay.Replay.dry_run/2, against a configured instance.

Replaying

$ mix belay.replay 4821 --url $DATABASE_URL

replaying job 4821 (MyApp.Reconcile) over 6 steps

diverged at step "settle_v2"

The journal has: fetch, normalize, match, price, settle
Today's code asked for "settle_v2", which production never ran.

Nothing executes. Steps, sleeps and spawns replay from the recording, emit/2 and debit/3 are inert, the database is only read — so replaying a job that is still running is safe.

Four answers: completed, diverged at <step>, blocked, raised. Divergence is the useful one: it names the point where today's code departs from what production ran, which is also how you find out whether in-flight jobs will survive a worker change before deploying it.

Fixtures

$ mix belay.replay 4821 --url $DATABASE_URL --out test/regressions/job_4821_test.exs

Writes a self-contained ExUnit file — worker, input, journal. No database, no instance. Fix the bug, keep the file, and the production data that broke you is in CI forever.

Belay.Replay.from_journal/4 is the storage-free entry point behind it: it stands up an ephemeral in-memory instance for the call and tears it down after, so fixtures run anywhere mix test runs.

Verified end to end, not just unit tested

I ran a real job into the Postgres test database, replayed it, generated a fixture, and ran mix test on the result — with the memory adapter, no database present. It passed. The generated file is in the guide.

Privacy

Fixtures embed step values copied out of the database. The task moduledoc, the guide, and the generated file's own header all say so. I considered a --redact flag and left it out: redacting the values breaks the replay, so it would be a flag that produces a file which cannot do the one thing it exists for. Documenting it honestly seemed better than a half-feature.

Also

New guides/debugging.md, linked from the README and registered in mix.exs extras. It is the differentiating feature, so it is in the guide list rather than buried in the API docs.

201 tests on Memory, 219 on PostgreSQL, both green; format, warnings-as-errors and docs clean. No version bump.