Animated explainer · 0:22 · An animation of the repo's own demo (npm run demo): the same lost response, handled by a naive retry and by Corrobo. The code is abridged from the example's contract.ts, and every value on screen comes from the demo's output.What's in it: A $50 credit is posted and the ledger commits it, but the response is lost. The usual catch-and-retry loop posts again and the ledger ends up with two credits. Corrobo instead asks the ledger by the operation's reference, finds the credit, marks it APPLIED and stops at one. The code being run is shown alongside.

In its demo, a naive retry credits an account twice. Corrobo credits it once.

Layman's Version

Say your code credits a customer $50. The request goes out, the ledger records the credit, and the reply gets lost on the way back. From your side, that looks exactly like a failure.

The usual reaction is to try again. If the first attempt actually went through, the customer gets credited twice. Corrobo's demo shows it with a real ledger: the naive retry credits the account twice.

Corrobo is a small TypeScript library that wraps actions like these. Before deciding anything, it asks the other system what really happened. If the write landed, it stops. If it didn't, it retries. If it can't tell, it says so and hands the call to a person instead of guessing.

Technical Version

The loop

  1. record attempt
  2. execute
  3. observe
  4. reconcile
  5. recover

Each consequential call gets an effect contract. execute() makes the change. observe() reads the authoritative system and is required to be read-only, so recovery never re-runs the effect through it. Reconciliation turns what observe() saw into evidence, and recovery picks what's safe to do next.

Corrobo records the attempt before calling out, so a crash between the write and the bookkeeping still leaves something to reconcile against.

Evidence and decisions are separate

APPLIED, NOT_APPLIED, CONFLICTED, PENDING and UNKNOWN describe what the evidence says. COMPLETE, RETRY, REPLAN, REVIEW and INVESTIGATE describe what's safe to do about it. Keeping the two apart is what lets UNKNOWN stay unknown instead of quietly becoming a retry.

Late landings

A timed-out request isn't undone; it can still land after the first check. A NOT_APPLIED after a failed call only turns into RETRY once the contract's declared in-flight window has passed, and each attempt records the window it was sent under, so a later deploy can't shorten it.

Approvals for agent actions

runEffect() makes attempts and takes no review decision, so the code that makes attempts can't approve them. reviewEffect() records who approved what, bound to one review's token and the recorded intent, and never executes anything. A decision made against an older review is refused with STALE_REVIEW_TOKEN.

That's an API boundary that makes it possible to separate the two roles, not a privilege boundary, and the docs say so.

Since 0.6.0, every hook gets its own copy of the recorded intent. Before, a hook that changed the intent object could change what was executed while the approval still covered the recorded one. An outside reviewer reported it with a reproduction.

Agent tool retries

When a refund tool times out after the refund went through, a model may call the tool again. That's a new tool call with a new toolCallId, so an idempotency key per toolCallId, or Corrobo keyed on it, refunds twice. Keyed on the decision itself, Corrobo refunds once. The agent-tool-retry example runs all five cases offline.

Persistence and concurrency

PostgresStore reserves an attempt before execution, serializes same-identity callers with advisory locks, and uses version-checked writes so a caller that lost its lock can't overwrite anything. Time windows come from the database clock, not the app server's. InMemoryStore exists for tests.

Testing

Every row of the failure matrix (lost responses, late landings, crashes at each boundary, races, lost locks, review, identity misuse) cites the test that proves it, and CI fails if a cited test disappears.

A model-based test runs random sequences of runs, review decisions, crashes, clock jumps and rolling upgrades against an independent oracle, in memory and against Postgres. A mutation script reintroduces 35 known bugs one at a time, and the model-based test catches all of them.

At 0.6.0 (Nov 9, 2026), the suite ran 905 passing tests locally, with 58 Postgres tests skipped for lack of a database; CI runs those against Postgres 16.

How it was built

I used Codex and Claude heavily for implementation and review. The architecture, contracts, boundaries, tests and release checks are mine. Corrobo generalizes a pattern I first built in Relay, a smaller demo that's in the lab.

It has outside contributors now: a GitHub-issue example from @sergioprica, where search can't prove absence, and security reports with reproductions from Ömer Faruk Koç that led to the fixes in 0.5.0 and 0.6.0.

Terminal output of Corrobo's demo. After a lost response, a naive retry credits the account twice; Corrobo reads the ledger, finds the credit, and stops at one.
The real terminal output of npm run demo, from the repo. Plays once.

Limitations

  • A library, not a workflow engine, queue or scheduler. It doesn't decide when to call again.
  • It doesn't claim exactly-once execution against third-party systems, and it can't see writes made outside it.
  • It's only as honest as each contract's observe(). A lookup that can't prove absence must return UNKNOWN.
  • Postgres persistence is opt-in, and retention is up to the application.