Reservation Before POST

"Write down that you're about to spend, before you spend. A crash between paying and recording is the expensive one."

The Invisible Charge

Here's the naive way to call a paid transcription API: send the request, get the response, save it. It works right up until the moment it doesn't — and the failure is uniquely nasty because it costs money. Picture the crash landing after the provider charged you but before you saved the result. Now you have paid for a transcription you don't possess, and — worse — there is no record anywhere that you paid at all. The money left silently. On a run of thousands of videos, a few of those invisible charges are easy to miss and impossible to reconstruct.

The root problem: the irreversible act (spending money) happened with no durable record of the intent to do it. If the only place the spend is recorded is the response you failed to save, then losing the response loses the entire fact of the charge.

Record the Intent First

Recall fixes this by ordering: before any paid call, the executor must cross a reservation ledger on the control plane. The reservation is a durable row that says, in effect, 'I am about to spend money on this exact piece of work.' It's written and committed before the POST goes out. Only after the reservation exists does the paid call happen. Then the result is recorded against that same reservation.

Now trace the crash again. If the executor dies after the reservation but before the POST — the ledger shows a reservation with no completed response, and you know exactly one call is in question. If it dies after paying but before recording the result — same thing: the reservation is right there, pointing at the call that needs checking. The spend can never be invisible, because its intent was durably recorded before the money could move.

This Is Write-Ahead Logging for Money

You've seen this shape before, even if not by this name. A database with write-ahead logging records what it's about to do before it does it, so a crash mid-write is recoverable. A payment system places an authorization hold before capturing a charge, so the intent to move money exists before the money moves. Recall applies the identical principle to a paid API call: the durable record of intent precedes the irreversible act. The reservation is the write-ahead log for spending. Everything else in this track — identity, ambiguity, retry policy — is built on top of the fact that the intent was written down first.

Code

Reserve (durable) → pay → record. Order is everything.·python

# WRONG: the charge can happen with no durable trace of intent.
response = provider.transcribe(chunk)   # money leaves here
save(response)                          # crash before this = invisible charge

# RIGHT: intent is committed to the ledger BEFORE the money can move.
reservation = control_plane.reserve(chunk_hash, config_hash)
#   ^ durable row: 'about to spend on this identity'
response = provider.transcribe(chunk)   # money leaves here
control_plane.complete(reservation, response)
#   ^ records the result against the reservation

# Crash anywhere: the reservation row makes the spend accountable.
# There is no state where money left with zero durable record.

Exercise

Find an irreversible action in your own code — a payment, an email send, an external API call that has a side effect. Trace the crash window: what happens if the process dies after the side effect but before you record that it happened? If the only record of the action is the thing you failed to save, redesign it to write a durable 'about to do this' record first. Note what that reservation lets you recover that you couldn't before.

Hint

The dangerous shape is 'do the irreversible thing, then record it.' Flip the first step in: 'record intent → do the thing → record result.' Now every crash leaves a durable breadcrumb pointing at exactly the action whose outcome is uncertain, instead of leaving no trace that the action ever happened.