retryfuse contract reference: input, decisions, exit codes

Input contract

Input is a single JSON object. operation.endpoint is required; everything else is optional and defaults safely.

contractVersion — must equal 1.
operation.endpoint — the call being guarded (required).
operation.idempotencyKey — optional string, at most 255 characters.
operation.requestHash — a 64-character hex sha256, or supply operation.body and retryfuse computes the fingerprint for you (canonical, key-order independent).
attempts[] — prior attempts, each with an outcome (success, failure, timeout, unknown), a phase (pre_write, post_write, unknown), and a non-negative costUnits. At most 10000 entries.
priorRecord — the idempotency record if one exists: status (in_flight or completed), requestHash, and writeCommitted (true, false, or "unknown").
policy.failureThreshold (default 5) and policy.budgetUnits (default 100) — the circuit brake.

Decisions

Every evaluation returns exactly one decision. Correctness gates (conflict, exactly-once replay, in-flight, uncertain-write reconciliation) are checked before the budget and circuit brake, because a blind replay is unsafe regardless of remaining budget.

Decision	Meaning
`replay_safe`	No committed effect exists (a clean first attempt, or a pre-write failure that provably did not land), and the circuit is within its failure and budget limits. Safe to replay.
`replay_stored`	The operation already completed under this idempotency key with a confirmed committed effect. Return the stored response verbatim — exactly-once, no second execution.
`brake`	Do not replay. Either a request is already in flight under this key, or the circuit is open from a failure streak or budget burn. Braking stops the retry storm.
`reconcile_required`	The write state is uncertain — a post-write timeout, a timeout of unknown phase, an unknown outcome, or a completed record whose effect is unconfirmed. Reconcile the real state before any replay; never blind-retry.
`reject_conflict`	The idempotency key was reused with a different request fingerprint. The second request is client misuse and is refused rather than executed.

Evidence status

Each report carries an evidence status: pass, fail, unknown. unknown is a first-class value, kept distinct from both pass and fail — an uncertain write is not a failing write.

CLI exit codes

The CLI returns an exit code for CI gating:

Exit	Status	Meaning
`0`	`pass`	replay_safe / replay_stored — safe to proceed
`2`	`fail`	brake / reject_conflict — an unsafe condition was detected
`3`	`unknown`	reconcile_required — safety cannot be determined without reconciliation
`1`	`unverified`	malformed input — the request could not be evaluated

node src/cli.mjs INPUT.json            # machine-readable report
node src/cli.mjs INPUT.json --human    # human-readable report

Learn by example

The fixture matrix documents the contract by example, covering positive, negative, malformed, missing-data and adversarial cases.