[Thom Chiovoloni (thomcc-work)]

Summary

Prevent a backlog of deferred activities from starving unrelated ready work.

Previously, worker fetches selected eligible rows by queue ID alone. Deferred
items retained their original IDs, so if their retry delays expired before the
backlog drained, they could repeatedly be selected ahead of newer ready work.

Migration 0029 changes both session-aware and non-session fetches to order
eligible rows by visible_at, id. A deferred item therefore goes behind work
that was already ready, even after its delay expires.

• Add idx_worker_ready_order on worker_queue(visible_at, id).
• Preserve session ownership, tag filtering, lock handling, and attempt accounting.
• Include a companion migration diff
  showing the function changes against baseline 0016 and the new index.
• Update the changelog and migration guidance.

This is the PostgreSQL-provider companion to microsoft/duroxide#74. It does
not change activity admission APIs or introduce a Duroxide dependency bump.

Migration and compatibility

The migration replaces fetch_work_item without changing its signature or
return shape.

By default, the index is built non-concurrently inside the migration
transaction. For busy or large queues, pre-build the matching index with
CREATE INDEX CONCURRENTLY, outside a transaction, in each target schema
before applying the migration. The migration will then skip the expensive
index build.

Even when reusing a prebuilt index, the migration takes a SHARE lock on
worker_queue and holds it until transaction commit. This blocks worker
fetch, acknowledge, abandon, and lock renewal, as well as orchestration
acknowledgements that write worker rows. The migration sets no lock_timeout,
so lock acquisition can wait indefinitely unless a deployment-session
lock_timeout is configured. Prebuilding reduces the work performed while
holding the lock; it does not make the migration lock-free.

Invalid prebuilt indexes, including those left by failed or cancelled
concurrent builds, are rejected without changing the migration ledger,
fetch function, or queued work.

See the rollout notes
for prebuild, verification, and repair instructions.

Already-running older providers can use the updated function. Older binaries
reject the new migration version on startup, so coordinate migration and
worker rollout.

Validation

Local validation at 9ae067b: 301 related unit, provider-validation, and
migration tests passed; one skipped.

Regression coverage includes:

• Expired deferrals yielding to already-ready work across session/non-session
  and tagged/untagged combinations.
• Rejection of an invalid index left by a failed concurrent build, with
  before/after snapshots proving the migration ledger, fetch function,
  queued work, and index state remain unchanged.
• Successful migration with a valid concurrently prebuilt index, verifying
  that the existing index is reused.
• A unit test requiring embedded migration versions to be unique and
  strictly increasing.

The worker progress tests now reuse panic-safe schema cleanup.

[Todd J. Green (tjgreen42)]

Review by GPT-6.1 Sol.

No actionable correctness findings in this revision. Reviewed the visibility-first dequeue ordering, claim/session eligibility and locking, migration registration and validation, and starvation regression coverage.

Release coordination note: do not ship/apply migration 0029 before #32 supplies 0027/0028; a later combined build would reject that applied ledger as a non-prefix. This dependency is already documented in #41, but would also be useful in this PR description, which still calls the migration 0027.

Scope: static review at 9ae067b. No PostgreSQL integration tests were run. Local nextest validation was blocked by the resolved uuid dependency requiring Rust 1.89 while the available toolchain was 1.88.

[Todd J. Green (tjgreen42)]

Review by GPT-6.1 Sol: The PR description is stale relative to the current diff. Please update it to:

• Refer to migration 0029, not 0027.
• Explain the concurrent index prebuild option and clarify that the migration still takes a SHARE lock on worker_queue until transaction commit, even when reusing the index. Lock acquisition can wait indefinitely unless a deployment-session lock_timeout is configured.
• Mention that invalid prebuilt indexes are rejected without changing the migration ledger, fetch function, or queued work.
• Include the index-validation/reuse regression coverage, embedded migration-version uniqueness test, and companion migration diff.

The core ordering behavior and provider compatibility summary remain accurate.

[Todd J. Green (tjgreen42)]

LGTM