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 invocation/interface/schedule 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.
For public or paid installed apps with a manual run page, do not use
:supersede unless "new run replaces old run" is intentional user-facing
behavior. If users should be able to start another run while a previous run
remains visible or continues working, prefer :coexist.

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 overlap behavior for each invocation/interface/schedule path.
Treating "only the latest installed-app run is visible" as a UI bug before
checking whether :singleton :on-new-version :supersede intentionally caused
the earlier run to be replaced.