@callback abandon_claim(
  ctx(),
  :system,
  run_id :: String.t(),
  claim_token(),
  abandon_policy()
) :: abandon_result()

Hands back a claim whose vehicle could not begin node execution.

This is the disposition for deterministic pre-execution failure — above all graph compilation incompatibility, where the executing node cannot compile the stored effective graph against its locally installed node contracts. That is a deployment-compatibility condition, not node execution failure, so it must consume neither the run's execution-attempt budget nor be reported through the run's failure machinery. Transient infrastructure errors (for example a failed graph fetch) are not abandons; they use ordinary release_claim/5 or crash into claim expiry.

The operation is fenced on the exact current token and the lease's committed checkpoint sequence, so it applies only before the holder's first lifecycle commit. A matched abandon atomically:

• clears the claim token and claimed time;
• hands the acquisition increment back by decrementing the claim-attempt count (floored at zero), keeping poison-by-attempts exclusively about claims that reached execution;
• increments the consecutive claim-abandon count; and
• either records policy.retry_at as the next wake and returns {:ok, :rescheduled}, or — when the abandon count had already reached policy.max_claim_abandons — records paired poison facts at policy.now with reason "max_claim_abandons_exceeded" and returns {:ok, :poisoned} so persistent incompatibility becomes an explicit operator concern instead of unbounded retry.

It never touches the committed run document, checkpoint_seq, or the run's updated_at. A stale token, an advanced sequence, or an unknown run changes nothing and returns {:ok, :stale}; after a steal or a serialized signal commit the abandon can never disturb the winning claim or schedule. Every return is success-shaped because the caller's next action is identical in all cases — stop without committing; the atom is for telemetry. The abandon count resets on any committed run mutation and on poison recovery.

policy.retry_at must not precede policy.now: the future wake is what keeps an incompatible node from immediately re-claiming the same run. Callers should add jitter to their retry backoff so runs abandoned together do not become due together. A rolling deployment therefore self-heals — a compatible node claims the run at or after retry_at — while a fleet that can never compile the graph poisons it after a bounded number of abandons. Both timestamps are normalized like every other operational timestamp.

@callback claim_due(ctx(), :system, claim_policy()) ::
  {:ok, claim_batch()} | {:error, term()}

Atomically claims a batch of ready or expired runs for system execution.

Ready candidates are non-poisoned running runs with no claim and a wake at or before policy.now. Expired candidates are non-poisoned running runs whose current claim is older than policy.orphan_ttl_ms relative to that same timestamp.

For each selected candidate whose current claim-attempt count is below max_claim_attempts, the store assigns a fresh token, sets claimed_at to policy.now, clears wake_at, increments the count, and returns a lease. If the count has already reached the maximum, the store clears claim and wake, records paired poison facts at policy.now, and returns a poison result without a lease. A maximum of three therefore permits exactly three claims that proceed into node execution; a fourth recovery need poisons the run. Claims handed back through abandon_claim/5 before execution began do not count toward that maximum — they are bounded separately by the abandon policy.

Selection, attempt accounting, claim steal, and poison mutation occur in the same atomic operation. The total number of returned outcomes is at most policy.limit.

Selection keeps both continuously eligible classes making progress:

• With limit >= 2 and both classes non-empty, at least one outcome (lease or poison - the reservation is per outcome, not per lease) goes to each class. The remaining demand follows the implementation's admission order with a stable (eligible_at, id) tie-break inside equal scheduling priority. Legacy uses global age-first order; a partition-fair implementation may put bounded partition rotation ahead of global age.
• With limit == 1, the optional policy.preference class is served first, falling through to the other class when the preferred one is empty so preference never wastes demand. Without a preference, stable age/ID order decides among rows with equal implementation scheduling priority; a partition-fair implementation may put its partition order ahead of global age.

Eligibility-time ordering provides aging, not fairness. Unless a selected implementation publishes a narrower conditional contract, implementations promise no strict FIFO, bounded queue wait, tenant or workload-class fairness, or starvation freedom under sustained arrivals or persistent row locks. Concurrent claimants may skip locked rows, so per-class progress holds only up to rows another transaction currently holds.

@callback fetch_run(ctx(), scope(), run_id :: String.t()) ::
  {:ok, Docket.Run.t()} | {:error, :not_found}

Reads the last committed graph-run document under an explicit scope.

An unknown run or scope mismatch returns {:error, :not_found}. Backend/infrastructure failure and corrupt persisted run state are not collapsed into absence; implementations raise in those cases.

@callback inspect_run(ctx(), scope(), run_id :: String.t()) ::
  {:ok, Docket.RunInfo.t()} | {:error, :not_found}

Reads the committed run with substrate-neutral operational information.

The Docket.RunInfo projection exposes the wake, claimed time, claim-attempt count, and poison facts, but never the current claim token. An unknown run or scope mismatch returns {:error, :not_found}. Backend/infrastructure failure and corrupt persisted run state raise rather than being reported as :not_found.

@callback list_runs(ctx(), scope(), list_query()) :: {:ok, Docket.RunPage.t()}

Lists lightweight run summaries under an explicit scope.

Results are ordered newest first by immutable (started_at, run_id) and use an exclusive keyset cursor. Scope and every requested filter must be enforced by the backing query; implementations must not load out-of-scope rows and filter them in application memory. The full durable run state is deliberately absent from Docket.RunSummary and must not be decoded for a collection read.

No matching rows is successful and returns an empty Docket.RunPage whose next_before preserves the supplied cursor and whose has_more? is false. Page construction trusts implementations to uphold ordering and cursor exclusivity rather than scanning backend output again.

@callback refresh_claim(
  ctx(),
  :system,
  run_id :: String.t(),
  claim_token(),
  now :: DateTime.t()
) :: :ok | {:error, :claim_lost}

Refreshes claim liveness under the exact current token.

Success advances claimed_at, and never backward: the stored time only moves toward the backend's authoritative current time, so a refresh that was delayed in flight cannot regress a fresher value written by a :retain_claim commit and re-expose the run to steal. now is the caller's clock reading; backends with an authoritative clock of their own may prefer that clock over now. A stale token, missing run, or lost claim returns {:error, :claim_lost} and changes nothing.

@callback release_claim(
  ctx(),
  :system,
  run_id :: String.t(),
  claim_token(),
  now :: DateTime.t()
) :: :ok

Releases the claim under the exact current token.

Release is idempotent. A stale token or missing run returns :ok without disturbing a newer claim or the run's schedule. A matching release clears the claim token and claimed time and records an immediate wake at now, so it cannot strand a non-poisoned running row without a claim or schedule.

@callback retry_poisoned_run(ctx(), scope(), run_id :: String.t(), now :: DateTime.t()) ::
  {:ok, Docket.Run.t()} | {:error, :not_found | :inactive_run}

Recovers a non-terminal poisoned run's backend-owned operational state.

Terminal status is checked first and returns {:error, :inactive_run}. Otherwise a poisoned run has its poison facts and claim cleared, its claim attempt and abandon counts reset, and an immediate wake recorded at now. Calling this for an already-unpoisoned non-terminal run is idempotent success and changes nothing. The command consumes neither commit nor event sequence.

An unknown run or scope mismatch returns {:error, :not_found}.