Serialize reservations
SQLite BEGIN IMMEDIATE, WAL mode and a busy timeout make concurrent reserve attempts converge on one durable receipt.
CASE STUDY / SIDE-EFFECT RELIABILITY
Idempotency Receipt Ledger.
A dependency-free SQLite ledger for the moment before an automation performs an irreversible external effect: should this attempt execute, skip, retry, or stop as a conflict?
THE PROBLEM
A timeout does not prove the side effect failed.
A payment request, webhook consumer, notification sender or file export can succeed remotely and still return a local timeout. Blindly replaying the same operation may create a duplicate charge, message, record or delivery. Retry logic therefore needs durable memory of what was attempted and what already completed.
Design constraint
The ledger decides whether a caller may execute. It never performs the side effect itself, never silently retries failed work, and never stores a raw payload when the caller uses file fingerprinting.
Make replay state explicit.
FIRST ATTEMPT
EXECUTE
A new idempotency key and fingerprint create a reserved receipt with attempt 1.
IN FLIGHT
SKIP_IN_FLIGHT
A competing process sees the existing reservation instead of performing the same external action again.
COMPLETED
SKIP_SUCCEEDED
Once the receipt is marked successful, future attempts remain a skip rather than becoming a fresh execution.
KEY MISUSE
CONFLICT
The same key with a different fingerprint is treated as a semantic conflict and exits with code 3.
FAILED WORK
SKIP_FAILED
A failure is not automatically replayed. The default is to stop and preserve the existing receipt state.
EXPLICIT RETRY
RETRY
Only --allow-failed-retry reopens a failed receipt and increments the attempt number.
Small database, deliberate semantics.
Fingerprint payloads
--payload-file stores a SHA-256 fingerprint rather than the raw payload, reducing accidental retention of customer or secret data.
Deterministic exit codes
Normal decisions return 0, invalid input returns 2, and idempotency-key fingerprint conflicts return 3 for orchestration or CI.
Put the receipt before the side effect.
$ receipt-ledger --db receipts.db reserve --key order:42 --fingerprint send-v1
decision=EXECUTE state=reserved attempt=1
$ receipt-ledger --db receipts.db succeed --key order:42 --result-json '{"delivery_id":"d_42"}'
state=succeeded attempt=1
$ receipt-ledger --db receipts.db reserve --key order:42 --fingerprint send-v1
decision=SKIP_SUCCEEDED state=succeeded attempt=1
decision=EXECUTE state=reserved attempt=1
$ receipt-ledger --db receipts.db succeed --key order:42 --result-json '{"delivery_id":"d_42"}'
state=succeeded attempt=1
$ receipt-ledger --db receipts.db reserve --key order:42 --fingerprint send-v1
decision=SKIP_SUCCEEDED state=succeeded attempt=1
The caller performs the actual payment, message, write or webhook action only after an EXECUTE or explicitly approved RETRY decision.
The duplicate paths are tested.
11 regression tests
Coverage includes in-flight duplicates, completed duplicates, fingerprint conflicts, failed-retry gating, missing receipts and CLI exit behavior.
Concurrent connections
A two-connection test asserts that the same key cannot produce two EXECUTE decisions.
Three Python versions
GitHub Actions runs the suite on Python 3.10, 3.12 and 3.13 so the public repository carries reproducible compatibility evidence.
Useful anywhere retries can duplicate money or work.
WEBHOOKS
Deduplicate event consumers
Use provider event IDs or business keys to prevent repeated handling when delivery is retried.
AI AGENTS
Guard tool side effects
Wrap email sends, record creation, file writes and other non-idempotent tools with a durable decision boundary.
AUTOMATION
Recover without guessing
Persist the last known state so a restarted worker can distinguish completed, in-flight, failed and conflicting attempts.
Have a workflow where “retry” can mean “duplicate”?
I can add an idempotency and receipt boundary around webhook, API, AI-agent or automation side effects without hiding the retry decision.