exactly-once

Idempotency middleware for agent side-effects

The primitive agent frameworks forgot. Wrap any tool call that must never fire twice — a payment, an email, an onchain transaction — and exactly-once guarantees it runs a single time, even across retries, crashes, and replays.

See it prevent a double-charge in one command:
python examples/crash_mid_payment.py — an agent crashes mid-payment, resumes, and does not double-charge (with vs without).

v0.1 — zero-LLM, tiny surface, drop-in.

Why

Agents retry. They crash and resume. They get replayed during debugging. Every one of those can fire a side-effect twice — a card charged twice, an email sent twice, a transaction submitted twice. In systems that touch money, duplicate side-effects are the difference between a bug and a lawsuit. Frameworks give you retries and checkpoints but not idempotency for the effects those retries cause.

Install

pip install exactly-once            # core, zero heavy deps
pip install "exactly-once[redis]"   # + Redis store   (also: [postgres])

Quickstart

from exactly_once import once, Store, current_key

store = Store.sqlite("effects.db")   # or .memory() / .redis(url) / .postgres(dsn)

@once(store, key=lambda order, **_: f"charge:{order.id}")
def charge_card(order):
    # pass our key through as Stripe's own idempotency key — belt and suspenders
    return stripe.charge(order.customer, order.amount, idempotency_key=current_key())

charge_card(order)   # runs the charge
charge_card(order)   # replays the stored result — Stripe is NOT called again

# context-manager form for an inline effect
with once(store, key="send-welcome:user-4471") as guard:
    if guard.fresh:
        guard.result = send_email(...)        # skipped on any replay

⚠️ Key on stable business identity (order_id), never on a mutable value like amount — two distinct $50 charges must not collapse into one.

See it prevent a double-charge in 15 seconds:

python examples/crash_mid_payment.py    # agent crashes mid-payment, with vs without

More runnable examples in examples/.

The guarantee (honestly scoped)

Classic idempotency-key pattern adapted for agents: compute a stable key → atomically check-and-claim → if committed, return the stored result without re-running; if in-flight, block/deny per policy; if new, run and commit. On a crash mid-effect the key is left in-flight and quarantined — a half-completed payment must never silently re-fire. Single-writer semantics are strong; multi-writer needs a real transactional store (documented, not overpromised).

Pluggable stores: memory · SQLite · Redis · Postgres. An onchain adapter (dedupe by nonce + calldata-hash) is planned for v0.2. See SPEC.md and ROADMAP.md.

What it guarantees — and what it doesn't

Guarantees (given a store with an atomic claim): the effect is entered at most once per key across retries, concurrent workers, crashes, and replays; after a commit every later call replays the stored result; a concurrent second caller never runs in parallel; a crash mid-effect never auto-re-fires.

Does not: it is exactly-once effect (at-most-once execution + replay-on-success), not exactly-once delivery — that's impossible (Two Generals / FLP). It can't know the outcome of a crash-mid-effect; it refuses to guess (quarantine) and lets a prober or a provider idempotency key narrow the window. It's only as strong as the store you pick:

Full boundary in docs/ARCHITECTURE.md §9.

Development

uv venv --python 3.11 && uv pip install -e ".[dev]"
uv run pytest                              # full suite (Redis/Postgres tests need Docker)
uv run mypy src/exactly_once               # strict typing
uv run ruff check src tests examples       # lint
uv run python scripts/check_docs_honesty.py  # the docs-honesty gate
uv run python scripts/benchmark.py           # per-call overhead (NFR-8)

Overhead per guarded call is one store round-trip plus key/codec work — a few microseconds on the in-memory store; real deployments are dominated by the store's own latency.

Part of the Swarm Proof toolkit

Trust infrastructure for the agent economy — seven projects, one thesis.

License

MIT. No LLM anywhere — it's plumbing. Citable via CITATION.cff.