Corrobo
When an API call times out, Corrobo checks whether the write actually happened before anything gets retried.
- Status
- Open source · v0.6.0 on npm
- Role
- Solo project
- When
- Sep 2026 – present
- Stack
- TypeScript · PostgreSQL · Vitest
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
- record attempt
- execute
- observe
- reconcile
- 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.
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.