Statistically-fair PostgreSQL admission engine.
One set-based claim statement samples up to limit active scopes from
docket_claim_schedule in random order, reads a bounded per-scope page of
due ready work through the v2 partial indexes, and admits candidates
breadth-first across scopes: every sampled scope's first-ranked run is
considered before any scope's second-ranked run. Expired-claim recovery
is scope-blind and identical to Docket.Postgres.ClaimPolicy.Legacy.
Admission is sticky within a scope. A run's first claim installs
tenant_admitted_at, and admitted due work ranks ahead of unadmitted work
in that scope's page, so runs already in progress are re-acquired and
driven to completion before new runs start. A scope's in-flight cohort
therefore stays near its share of each claim batch, with no configured
cap: new work is admitted only when a batch slot reaches the scope and no
admitted run is due. Poisoning clears the marker. Promotion order is
near-FIFO rather than strict: a locked or stale queue head does not block
later promotions.
The engine claims only under the windowed admission mode, holds no
cursor, and takes no policy-row lock beyond the shared admission gate, so
concurrent dispatchers admit in parallel. Startup configuration is
last-boot-wins: it normalizes the persisted admission mode to windowed
when a previous configuration left it in another mode, so a rebooted
instance always claims, while dispatchers still running another engine
fail closed. Scope sampling considers only scopes that currently hold due
ready work, so a single-claim call cannot land on a scope whose runs are
all sleeping while due work exists elsewhere. Fairness across tenants is
statistical — per fetch and across nodes — rather than deterministic, and
per-tenant caps are not enforced. Requires schema version 2 for
docket_claim_schedule and the scoped partial indexes.