Documentation
Nine written guides, and the repository's canonical documents rendered in place — mechanically synced, drift-gated, and searchable. The repository copy always wins.
Orientation: read How it works first — it is the mental model the rest assumes. Guides are for doing (install, integrate, operate); Designis why the engine is shaped this way; Benchmark is the measurement method and its governance; Contracts are the machine-validated schemas; Governance andDecisions are how changes are controlled, append-only. Internal working material (the hash-pinned master document, the human review queue) deliberately stays in the repository rather than here — linked below, never forked.
Guides
- Getting started
From clone to the recorded flagship demo: uv, Docker, irrevon init, doctor, and the two-leg demo run.
- CLI reference
Every irrevon subcommand, captured verbatim from the CLI's own --help output — generated, drift-gated, never paraphrased.
- Integration guide
Wiring Irrevon into an agent's tool boundary: register_intent then dispatch, with reconcile, sweep, and resolve driven by the library.
- Adapter development
What a destination adapter is, why every adapter ships a machine-readable capability declaration, and the boundary between verified reference adapters and provider drafts.
- Architecture
The engine's components and the three-dimension state model — a guided narrative over the canonical design documents, with links into each.
- Benchmark reproduction
The intended IrrevonBench reproduction contract, with synthetic development pilots disclosed and no live-sandbox or confirmatory result yet.
- What happens when an API commits but its response is lost?
A direct guide to ambiguous API outcomes: why a timeout is not proof of failure, what evidence is safe to use, and when a retry can create a duplicate external effect.
- Idempotency keys versus destination reconciliation
When idempotency keys are sufficient, where their guarantee ends, and why authoritative destination read-back is a different recovery mechanism rather than a replacement.
- Durable workflows, transactional outbox, sagas, and reconciliation
A boundary-focused comparison of durable execution, transactional outbox, sagas, idempotency, and Irrevon's destination-authoritative reconciliation.
Reference — rendered from the repository
Each page below is a rendered copy of a repository document, carrying its source path and content hash. A sync script regenerates them; CI fails on any drift, so these cannot fork the truth.
Design
- RFC-001 — the first vertical slice
The first vertical slice: scope, wire-in points, flagship demo contract, and the M3 acceptance ladder.
docs/rfc-001-first-slice.md - RFC-002 — engine design
Implementation-ready engine mechanics: canonical state tables, append-only ledger, claim protocol, gate, recovery, sweep, and the conformance test plan.
docs/rfc-002-engine-design.md
Benchmark
- IrrevonBench preregistration (DRAFT)
The IrrevonBench preregistration DRAFT: hypotheses, baseline ladder, metrics, analysis plan, sealed holdout, and the falsification criterion.
docs/benchmark-preregistration.md - IrrevonBench guide — measurement, governance, adoption
The benchmark guide: exact measurement boundary, oracle and causal-history checking, tracks and anti-cheating rules, governance, adoption path, and the BetterBench self-assessment.
docs/benchmark.md - Effect-semantics mappings — declarations over existing protocols
How Irrevon's capability declaration projects onto MCP, A2A, OpenAPI, HTTP, and ACP — and where those protocols carry no effect semantics at all.
docs/effect-semantics-mappings.md - Worked example — incident replay to permanent regression
A complete synthetic walkthrough: compile a payments double-charge incident into a private, drift-gated regression suite; reproduce it against the baseline ladder; keep it permanent in CI; export sanitized evidence.
docs/incident-replay-example.md
Contracts
- Schemas — machine-readable contracts
The machine-readable contract map: thirteen shipped JSON Schemas, their example suites, and what is deliberately deferred.
schemas/README.md
Governance
- Execution plan — phases and gates
Phases P0–P8, their gates, and the public-release gate. Order is load-bearing; nothing here is a date.
docs/execution-plan.md - CI — how this repository builds
The CI workflow map: tiers, required checks, owner settings checklist, and local parity via make targets.
docs/ci.md - Security policy — development process
The development threat model and agent execution policy: what agents may do, what is human-only, and the enforcement layers.
docs/security-policy.md - Licensing status
Apache-2.0 licensing and contribution posture: inbound=outbound, mandatory DCO 1.1 sign-off, no CLA, and the remaining trademark and release gates.
LICENSING.md - Operations — running Irrevon as a service
Operator documentation: deployment shape, probes, shutdown and upgrades, the ten operator questions, SLO guidance, backup/restore, incident containment.
docs/operations.md
Decisions
- Decision records — index and policy
The append-only ADR index and policy. If a decision is not in the index, it has not been made.
docs/decisions/README.md
Canonical, linked only
- Master document
The single authoritative document: thesis, evidence, architecture, state model, benchmark design, decisions, operations. Hash-pinned and amended only by human ratification — deliberately linked, not rendered, so no second copy can drift.
pinned sha256 aef24e814529bb8e… - Review queue
Open questions and proposed amendments awaiting human resolution — a working queue, linked for transparency.
docs/review-queue.md - Workbench README
The read-only evidence workbench: budgets, fixture provenance, and zero-external-request guarantees.
web/README.md
Evidence: Verified evidenceTechnical provenance