The uncertain write
A client sends a write, the request leaves, and then the call times out before a response comes back. The timeout tells you nothing about whether the write landed: the server may have committed the effect and lost only the response, or it may never have processed the request at all. The outcome is genuinely unknown, not failed.
Why a blind retry is unsafe
Retrying on any timeout treats "unknown" as "did not happen". If the first attempt actually committed, the retry executes the effect a second time: a double charge, a duplicate order, a repeated transfer. Naive retry logic turns one uncertain write into two certain ones, and a retry storm multiplies the damage across a dependency that is already struggling.
What retryfuse returns instead
retryfuse classifies a post-write timeout (and a timeout of unknown phase, an
unknown outcome, or a completed record whose effect is unconfirmed)
as reconcile_required with an evidence
status of unknown. The verdict is
"find out what really happened before you act", not "retry" and not "fail".
This correctness check runs before the budget and circuit brake, because
a blind replay is unsafe regardless of how much budget remains.
The contrast across the engine's full set of verdicts:
| Situation | Decision |
|---|---|
| Clean first attempt, or a pre-write failure that provably did not land | replay_safe |
| Already completed under this key with a confirmed effect | replay_stored |
| Write state uncertain (post-write timeout, unknown outcome) | reconcile_required |
| Circuit open from a failure streak or budget burn, or a concurrent in-flight request | brake |
| Idempotency key reused with a different request body | reject_conflict |
How reconciliation works in practice
When retryfuse returns reconcile_required,
the caller reads back the authoritative state keyed by the idempotency key — the
ledger row, the order record, the downstream receipt — and acts on what it finds:
if the effect committed, treat the operation as done; if it provably did not,
replay is now safe. Reconciliation replaces a guess with a fact. The decision
core is pure and versioned (contract version
1), so the same evidence always yields
the same verdict.
Next
See the contract reference for the exact JSON input and the CLI exit codes, or the fixture matrix for the post-write-timeout case (and others) by example.