Resolve an idempotency key into "start this run" or "replay that one".
The order of the checks below IS the semantics:
Reserve. A brand-new key that also wins the claim is the only path that
starts anything.
Persisted state, BEFORE the reservation's own state. A run that persisted
is answerable whatever the reservation says, and reading the row's state
first would let a stale started refuse a retry whose run is sitting
right there, finished.
reserved with nothing persisted means the first caller died between the
insert and the claim, having executed nothing — so this caller may take
the claim and proceed with the SAME runId. That convergence is what makes
a crashed reservation self-healing instead of a wedged key.
started with nothing persisted is the only ambiguous state in the
system, and the liveness probe is what resolves it.
terminal with nothing persisted is a completed run whose summary aged
out. Spent, never re-run.
Throws the applicable structured taxonomy errors; a surface renders them
through doErrorResponse (or its router's equivalent) with no re-mapping.
Across the public keyed-start surface the eight codes are the five decision
refusals — IDEMPOTENT_START_OWNER_MISMATCH (403),
IDEMPOTENT_START_TARGET_MISMATCH (409), IDEMPOTENT_START_PENDING
(503), IDEMPOTENT_START_UNRESOLVABLE (409), and
IDEMPOTENT_START_ALREADY_SETTLED (409) — plus IDEMPOTENT_START_UNSUPPORTED
(503), INVALID_START_IDEMPOTENCY_REQUEST (400), and
IDEMPOTENT_START_UNREADABLE (503).
Resolve an idempotency key into "start this run" or "replay that one".
The order of the checks below IS the semantics:
startedrefuse a retry whose run is sitting right there, finished.reservedwith nothing persisted means the first caller died between the insert and the claim, having executed nothing — so this caller may take the claim and proceed with the SAME runId. That convergence is what makes a crashed reservation self-healing instead of a wedged key.startedwith nothing persisted is the only ambiguous state in the system, and the liveness probe is what resolves it.terminalwith nothing persisted is a completed run whose summary aged out. Spent, never re-run.Throws the applicable structured taxonomy errors; a surface renders them through
doErrorResponse(or its router's equivalent) with no re-mapping. Across the public keyed-start surface the eight codes are the five decision refusals — IDEMPOTENT_START_OWNER_MISMATCH (403), IDEMPOTENT_START_TARGET_MISMATCH (409), IDEMPOTENT_START_PENDING (503), IDEMPOTENT_START_UNRESOLVABLE (409), and IDEMPOTENT_START_ALREADY_SETTLED (409) — plus IDEMPOTENT_START_UNSUPPORTED (503), INVALID_START_IDEMPOTENCY_REQUEST (400), and IDEMPOTENT_START_UNREADABLE (503).