fix(outbox): avoid backlog scans during event discovery

[icecrasher321]

Summary

• Discover ready outbox event types with index seeks instead of aggregating the pending backlog. Preserve oldest-first scheduling, unknown types during rolling deployments, and existing claim/lease behavior.
• Tune outbox autovacuum thresholds for queue churn and log processing phases with sanitized database causes when a poll fails.

Type of Change

• Bug fix

Testing

• 36 unit tests and 13 PostgreSQL integration tests, including large future/ready backlogs, availability boundaries, more than 128 event types, unknown handlers, locked rows, and concurrent workers.
• App type-check, repository lint, full audit suite, block registry check, generated artifact checks, and migration safety check against staging.
• Applied and replayed the migration on a disposable PostgreSQL database; verified snapshot continuity with staging.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 17, 2026 8:47pm UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with the new discovery behavior supported by schema-compatible indexes and focused unit and PostgreSQL integration coverage.

Summary

This PR replaces backlog aggregation during outbox event discovery with indexed, per-type recursive seeks and adds structured poll-failure diagnostics plus table-local autovacuum tuning.

• Preserves oldest-ready-first scheduling while limiting worker-facing metadata to 128 event types.
• Adds PostgreSQL coverage for future backlogs, unknown types, lock contention, scheduling boundaries, and query-plan cost.
• Logs sanitized infrastructure failures with processing-phase and progress information.
• Adds migration metadata and lower vacuum/analyze scale factors for the churn-heavy outbox table.

Diagram

sequenceDiagram
  participant Scheduler
  participant OutboxService
  participant PostgreSQL
  participant Handler

  Scheduler->>OutboxService: processOutboxEvents()
  OutboxService->>PostgreSQL: Reap expired processing leases
  OutboxService->>PostgreSQL: Recursive indexed seek for each pending type head
  PostgreSQL-->>OutboxService: Up to 128 ready types, oldest first
  loop Until batch or runtime limit
    OutboxService->>PostgreSQL: Claim one row for next type
    PostgreSQL-->>OutboxService: Claimed event or none
    OutboxService->>Handler: Handle claimed event
    Handler-->>OutboxService: Completed, retry, dead letter, or lease lost
    OutboxService->>PostgreSQL: Persist terminal or retry state
  end

Loading

_{Reviews (1) · Last reviewed commit: "fix(outbox): avoid backlog scans during ..."}

[cubic-dev-ai]

No issues found across 7 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>