Skip to main content

Module dispatch

ff_backend_postgres

Module dispatch 

Source
Expand description

Post-completion dependency-resolution cascade (Wave 5a).

When an execution reaches a terminal outcome the Wave 4b writer (attempt::complete / attempt::fail) / Wave 4c (cancel_flow) emits an ff_completion_event row. The engine’s dispatch loop polls the outbox by event_id and, for each event, calls dispatch_completion. This module is the Postgres twin of the Valkey ff_resolve_dependency FCALL cascade in ff-engine::partition_router::dispatch_dependency_resolution.

§Per-hop-tx (K-2 adjudication)

The round-2 RFC debate locked the cascade to per-hop transactions — NOT one mega-transaction spanning transitive descendants. A fanout of N downstream edges that each fan out to M further edges would otherwise hold ff_edge_group row locks across the entire subgraph for the full cascade duration, which is user-visible on large flows.

The layout here:

  1. Outer function dispatch_completion runs a short claim-tx that atomically flips ff_completion_event.dispatched_at_ms from NULL to now_ms() via UPDATE ... RETURNING — a concurrent dispatcher (retry, reconciler) observes the already-claimed row and short-circuits with DispatchOutcome::NoOp.
  2. For each downstream edge, [advance_edge_group] runs its own read-committed tx with SELECT ... FOR UPDATE on the ff_edge_group row. Counter bump + policy eval + downstream state flip + sibling-cancel bookkeeping all commit together at hop boundary, then release the row lock.
  3. If a hop’s tx exhausts its serialization retries we return [EngineError::Contention(RetryExhausted)]; the Wave 6 reconciler picks up the uncleared dispatched_at_ms via the partial index added in migration 0003.

Failures mid-cascade leave the outbox row marked dispatched (short-circuited) but partial downstream state; the reconciler catches orphaned work on its next scan.

Enums§

DispatchOutcome
Outcome of a single dispatch invocation. Surfaces enough to let callers (the dispatcher loop, tests) distinguish claim-races from real work.

Functions§

dispatch_completion
Public entry point — poll one outbox event and cascade.