How Neo finishes background jobs

Durable records

inbox_events stores verified callback envelopes, provider identity, conversation key, occurrence marker, payload hash, status, attempts, lease, result, and error. outbox_commands stores command type, aggregate/action identity, stable key, canonical payload, provider, delivery status, attempts, lease, provider reference, and reconciliation state.

Worker loop

stateDiagram-v2
  [*] --> Pending
  Pending --> Processing: claim with SKIP LOCKED and lease
  Processing --> Completed: handler succeeds
  Processing --> Pending: retryable failure and backoff
  Processing --> Reconciling: outcome unknown
  Processing --> DeadLetter: terminal or exhausted
  Reconciling --> Completed: provider evidence
  Reconciling --> Pending: proven not delivered
  DeadLetter --> Pending: audited safe replay

The application runs bounded worker passes and prevents overlapping passes within one process. PostgreSQL claim ordering, leases, and advisory conversation locks protect multi-process behavior.

Replay and reconciliation policy

Generic queue operations can inspect, show, replay, and reconcile ordinary commands. Financial commands fail closed in generic replay/resolution paths and must use provider-specific evidence services. An operator must never convert an ambiguous timeout into another transfer or refund without proving the provider state.

Operational signals

Queue health exposes counts, not payloads. Dead letters and reconciliation items are visible to protected operations and explicit commands. Current process-local counters are useful diagnostics but do not replace durable metrics, alerting, or service-level objectives.

• src/durable-queue.ts
• src/provider-runtime.ts
• scripts/queue-ops.ts
• db/migrations/026_conversation_inbox_outbox.sql
• test/durable-queue.test.ts
• test/provider-runtime.test.ts