irrevon
Reconciliation for irreversible agent effects

Agents retry.
Destinations don’t forgive.

An agent that crashes mid-call, retries a timeout, or re-synthesizes its arguments can charge a card twice, book the wrong slot, or leave an orphaned order no process reconciles. Irrevon is an open-source reference engine with a benchmark design documented in a draft preregistration.

Evidence: Evidence-backed analysis · Verified evidenceTechnical provenance

Install v0.1.0How it worksView the sourceAsk a question or share feedback

v0.1.0 Alpha published on PyPI on · Apache-2.0 · draft benchmark methodology, synthetic development evidence

Evidence, not a promise

One crash, one lost response, one re-synthesized retry. Two very different endings.

The flagship demo persists an intent, loses the dispatch response on cue, is really SIGKILLed, and recovers by asking the destination — then rejects the agent’s re-worded retry as a duplicate of the same stable identity. A developmental file-journal durable-runtime comparison (benchmark arm B5), under the identical fault schedule, creates the duplicate.

The recorded run

Recorded artifactseed 777engine 0a22114refdest-c2
  1. — Irrevon leg —
  2. 1registeredeffect 0bb7e8d64711… · lifecycle PERSISTED
  3. 2dispatch_response_lostfault response_lost · lifecycle AMBIGUOUS
  4. 3crashexit_status -9 (SIGKILL, mid-run)
  5. 4recoveredrestart · scanned 1 · adjudicated 1 — before any redispatch
  6. 5settled_confirmed_uniqueSETTLED_COMMITTED · CONFIRMED_UNIQUE (destination queried)
  7. 6resynthesis_collapsedreplayed true · parameter_variant sha256:074abd63…98c2cd
  8. 7duplicate_rejectedoutcome denied · deny_check dedup · decision_id 2
  9. — B5 contrast leg —developmental file-journal B5 stand-in: durable retry + stable op-IDs + idempotency keys
  10. 8b5_response_losttransport_outcome LOST (identical fault schedule)
  11. 9b5_restartdurable runtime restarts the workflow
  12. 10b5_retriedretried wf-order-9410-activity-0 — key sent, destination ignores it
  13. 11b5_duplicatedestination_effects 2
Irrevon leg1 destination effectduplicate rejected · SETTLED_COMMITTED
B5 leg2 destination effectsduplicate created · same fault schedule
contrast_holdstruerecorded in the artifact summary
Recorded from a real engine run (seed 777, engine commit 0a22114) against the reference C2 destination — queryable status, no honored idempotency. Not live, not production; reproducible from the repository with uv run irrevon demo.

Evidence: Verified evidenceTechnical provenance

The mechanism

Three deterministic moves

01

Identity from business facts, never model output

Effect identity is a hash of stable upstream identifiers — order IDs, invoice IDs, authorization IDs — plus effect type and scope. A re-synthesized retry with different wording collapses to the same identity. No key-derivation path reads model output; that is conformance-tested.

Evidence: Design specificationTechnical provenance

02

Persist before dispatch

Nothing is sent without a durable record carrying the operation identity and idempotency evidence. A crash before persistence is therefore provably effect-free — and a crash after it leaves a record that recovery must adjudicate.

Evidence: Design specificationTechnical provenance

03

Reconcile by asking the destination

Ambiguous outcomes are resolved by querying the destination’s authoritative status — never by believing the caller. Anything unrecognized stays AMBIGUOUS, never silently FAILED, so evidence is never discarded.

Evidence: Design specificationTechnical provenance

Stated up front, not in a footnote

What Irrevon cannot do

The non-guarantees carry the same weight as the guarantees. That is the point of the project.

No universal exactly-once

Impossible per Two Generals / FLP. The achievable target is at-least-once delivery plus idempotent or reconciled processing — and the guarantee depends on what the destination exposes.

Evidence: Verified evidenceTechnical provenance

Compensation is not rollback

A committed irreversible effect cannot be un-committed. Compensation is a new effect with its own failure modes — measured, never assumed.

Evidence: Design specificationTechnical provenance

No advantage on destinations with native idempotency (tier C1)

Destinations with dependable native idempotency already prevent duplicates. Irrevon expects to add nothing there, and the benchmark pre-commits to reporting that null as prominently as any win.

Evidence: Testable hypothesisTechnical provenance

Opaque destinations are an impossibility boundary (tier C3)

Opaque destinations — no key, no query, no stable ID — make lost and orphaned effects undetectable for every method. The benchmark demonstrates that boundary instead of hiding it.

Evidence: Design specificationTechnical provenance

The product surface

Every claim ends in an inspectable record

The workbench is a local, read-only viewer over the ledger: lifecycle, classification, and resolution as three separate dimensions, per-effect causal evidence, and findings with their evidence digests.

Irrevon workbench Effects table listing recorded effects with separate lifecycle, classification, and resolution columns; a synthetic-fixture banner is visible at the top.Irrevon workbench Effects table in dark theme, listing recorded effects with separate lifecycle, classification, and resolution columns; a synthetic-fixture banner is visible at the top.
The workbench pictured is running against schema-validated fixtures captured from a real engine run (seed 777) — the SYNTHETIC FIXTURE banner is part of the product, not an accident of the screenshot.
Recorded artifact

Evidence: Verified evidenceTechnical provenance

Inspect the Workbench boundary and evidence model →

IrrevonBench

The benchmark design is public before live evidence — including the result that would kill the project

Draft methodology — no scientific results yet

The preregistration is a draft; nothing is frozen. Synthetic reference-destination development pilots (S-REF) have occurred and are disclosed, but no live-sandbox observation or confirmatory run has occurred. If the preselected composite comparator matches Irrevon on queryable destinations (tier C2), the pre-committed falsification criterion fires: Irrevon is unnecessary, and the project says so.

Evidence: Verified evidence · Testable hypothesisTechnical provenance

Read the benchmark design and the kill criterion →

Get started

Clone it and run the flagship demo

The source path is deterministic and self-contained. The demo runs locally against a reference destination with uv, Docker, and loopback-only PostgreSQL.

git clone https://github.com/PranavMishra28/irrevon.git && cd irrevon
uv sync --locked                # toolchain + deps, pinned by uv.lock
uv run irrevon init             # writes config, compose.yaml, and .env.example
cp .env.example .env            # local migration bootstrap; no credential
set -a && . ./.env && set +a    # export the generated migration DSN
docker compose up -d --wait     # digest-pinned Postgres 17, loopback only
uv run irrevon init             # now applies the plain-SQL migrations
uv run irrevon doctor           # checks, including a rolled-back write probe
uv run irrevon demo             # the two-leg flagship story

Evidence: Verified evidenceTechnical provenance

Open the repositoryRead the documentation