Run Concurrency

Breyta flow run concurrency reference for controlling overlap, per-key execution, and version handoff behavior.

Quick Answer

Flow run concurrency is controlled by :concurrency on the flow definition:

choose model: :singleton or :keyed
choose version policy: :supersede, :drain, or :coexist

This is run-level behavior (between workflow executions), not per-step execution shaping.

Config Shape

Field	Required	Values	Notes
`:type`	Yes	`:singleton`, `:keyed`	Defines run isolation model.
`:on-new-version`	Yes	`:supersede`, `:drain`, `:coexist`	Defines behavior when a new released version starts receiving runs.
`:key-field`	For `:keyed`	keyword or path vector	Extracts run key from input (for example `:order-id` or `[:event :id]`).

Model Behavior

Model	What is unique	Typical use
`:singleton`	One active run slot per flow slug/workspace	Scheduled rollups, singleton workers, periodic sync jobs
`:keyed`	One active run slot per key value	Entity/event scoped flows (order, user, ticket, webhook event)

Version Handoff Policy

`:on-new-version`	Behavior	Use when
`:supersede`	Running older-version executions are terminated and new version runs immediately.	Fast cutover is more important than finishing in-flight work.
`:drain`	Running older-version executions finish first; new version runs wait.	In-flight work must complete before cutover.
`:coexist`	Older and newer versions can run at the same time.	Parallel transition is acceptable and version overlap is intentional.

Canonical Examples

;; One active run at a time; cut over immediately on release.
{:concurrency {:type :singleton
               :on-new-version :supersede}}

;; One active run per order id; drain old version before key-wise cutover.
{:concurrency {:type :keyed
               :key-field :order-id
               :on-new-version :drain}}

Practical Guidance

Start with :singleton unless you explicitly need per-entity parallelism.
Use :keyed only when every trigger path reliably supplies the key field.
Pick :drain when side effects must finish before version change.
Pick :supersede for incident fixes/hot releases where immediate behavior change matters.
Use :coexist deliberately and monitor version mix in runs after release.

Common Mistakes

Confusing flow run concurrency with per-step retries/timeouts (different scope).
Choosing :keyed without ensuring input always contains the key field.
Changing version policy without validating trigger overlap behavior.