Dispatch queue: the row that guarantees delivery

A dispatch queue is a database table holding units of work that have been committed for a specific worker to claim. In DevPilot it is a Postgres table named dispatch_queue, and it is the delivery guarantee — not an optimisation sitting in front of one.

Why that distinction matters

Most systems treat a queue as transport: a broker moves a message, and the database records the outcome. That arrangement has a window. The database commit and the message publish are two operations against two systems, and a crash between them leaves a session that exists with work that was never dispatched — or work dispatched for a session that does not exist.

Putting the queue in the database removes the window, because the row and the record it refers to commit in the same transaction. enqueueDispatch takes the transaction handle as a required first parameter for exactly this reason: there is no way to call it outside the transaction that created the session.

What a row holds

An id, the owning organization, the target orchestrator, the session it belongs to, the payload, an attempt count, an available_at timestamp for backoff, and a nullable claimed_at.

That nullable column is the whole concurrency mechanism. A worker claims a row with a conditional UPDATE whose WHERE clause includes claimed_at IS NULL; two workers racing the same row cannot both win, because the loser's statement matches zero rows. There is no lock and no coordinator — the mechanics are here.

Consequences

Because delivery is the table, the transport becomes optional. Realtime push tells a machine to look sooner; polling arrives at the same answer more slowly. Both are correct, which is what makes --transport poll a supported mode rather than a degraded fallback. The longer argument is here.

Because a claim can be abandoned — a laptop closes mid-run — claims expire. A sweeper releases rows claimed longer ago than a timeout, returning them to the pool for another orchestrator to take.

Where it does not fit

One row belongs to one worker, so genuine fan-out means writing many rows. If you need the same message delivered to many independent consumers, a broker is the right tool and this pattern will fight you.