Take the claim: reserved -> started, for this exact run.
ONE conditional UPDATE, and the whole cross-isolate serialization of the
feature. Exactly one caller changes a row; every other caller sees zero
changes and must go and find out what the winner did rather than starting
anything. The run_id predicate rides along so a claim can never land on a
row that was rewritten underneath it.
Never creates the table: a claim can only ever follow a reserve, which did.
Read one reservation. A PURE read: no lazy DDL, no upsert, nothing that would make consulting a key mutate the database — which is what lets a read-only drain inventory and every replay path use it freely, and what keeps a read-only replica or a revoked-write incident a degrade rather than an outage.
An absent TABLE reads as an absent reservation, because on a deployment where no key has ever been used those are the same fact.
Give the claim back: started -> reserved, for this exact run.
The ONLY backwards transition, and it exists for exactly one caller: a start the EXECUTION FENCE refused. That refusal is special because it is provably pre-execution — the fence is read before the run lock and before any storage write — so the claim it consumed bought nothing and holding on to it would manufacture an UNRESOLVABLE reservation out of an operator action. Leaving the claim taken would mean a deployment that drained, migrated, and reopened had permanently poisoned every key that happened to be in flight.
It is deliberately NOT used for other start failures. Anything that reached the runtime's execution path may have taken effect, and a rollback there would hand the next retry a fresh run — the exact double-charge this whole module exists to prevent.
Every reservation naming one of these runs, for the purge and the inventory. Chunked by the caller; this method binds exactly what it is given, so a caller must respect D1's 100-parameter statement limit.
Decide which run this key means, creating the reservation if it is new.
INSERT OR IGNORE then READ BACK — the resource-ownership idiom, and the only shape that is correct without a transaction: the insert is the race, the read-back is the result, and every caller that lost the insert reads the winner's row rather than its own intention. Two callers can therefore never both believe they created the reservation, whatever order their statements interleave in, and neither needs to know it raced.
This is the ONE method that may create the table. A reservation is the
first write anything here makes, so the schema belongs on its path and
nowhere else — in particular not on read, where lazy DDL would turn the
deployment's read-only drain inventory into a write.
Terminal reconcile, keyed by RUN rather than by key: the runtime observes a run reaching a terminal state and has no idea which key (if any) named it.
Idempotent by construction (state <> 'terminal'), so the several places a
run can reach terminal — completing, failing, being cancelled, timing out —
can all call it without coordinating, and a re-entry after a crash is a
no-op rather than a conflict.
Returns the number of reservations settled, which is 0 for the overwhelming majority of runs (nobody used a key) and 1 for the rest.
The deployment's start reservations, over the SAME D1 database its snapshots, its resource owners, and its execution fence live in — so a reservation cannot be separated from the run it reserves by any binding mistake.