feat: Introduce worflow level concurrency

Author: octoper

ARCHITECTURE.md

@@ -297,15 +297,52 @@ When the worker encounters this, it executes all steps within the `Promise.all`
 concurrently. It waits for all of them to complete before proceeding. Each step
 attempt is persisted individually as a `step_attempt`.
 
-### 5.2. Workflow Concurrency
+### 5.2. Worker Concurrency
 
 Workers are configured with a concurrency limit (e.g., 10). A worker will
 maintain up to 10 in-flight workflow runs simultaneously. It polls for new work
 only when it has available capacity. The Backend's atomic `dequeue` operation
 (`FOR UPDATE SKIP LOCKED`) ensures that multiple workers can poll the same table
 without race conditions or processing the same run twice.
 
-### 5.3. Handling Crashes During Parallel Execution
+### 5.3. Workflow-Run Concurrency
+
+In addition to worker-slot concurrency, workflows can define a per-run
+concurrency policy in the workflow spec:
+
+```ts
+defineWorkflow(
+  {
+    name: "process-order",
+    concurrency: {
+      key: ({ input }) => `tenant:${input.tenantId}`,
+      limit: ({ input }) => input.maxConcurrentOrders,
+    },
+  },
+  async ({ step }) => {
+    // ...
+  },
+);
+```
+
+`key` and `limit` can each be either static values (`string`/`number`) or
+functions of the validated workflow input. They are resolved once when the run
+is created and persisted on the `workflow_run`.
+Resolved keys are stored verbatim; only empty/all-whitespace keys are rejected.
+
+During claim/dequeue, a run is claimable only when the number of active leased
+`running` runs in the same bucket is below the run's `limit`. The bucket scope
+is:
+
+- `namespace_id`
+- `workflow_name`
+- `version` (version-aware buckets)
+- `concurrency_key`
+
+`pending`, `sleeping`, and expired-lease `running` runs do not consume
+concurrency slots.
+
+### 5.4. Handling Crashes During Parallel Execution
 
 The `availableAt` heartbeat mechanism provides robust recovery. If a worker
 crashes while executing parallel steps, its heartbeat stops. The `availableAt`

packages/docs/docs/workers.mdx

@@ -49,7 +49,7 @@ When a worker picks up a workflow:
 5. **Execute**: New steps are executed and their results are stored
 6. **Complete**: The workflow status is updated to `completed` or `failed`
 
-## Concurrency
+## Worker Concurrency
 
 Workers can process multiple workflow runs simultaneously. Configure concurrency
 in your `openworkflow.config.ts`:
@@ -88,6 +88,38 @@ bunx @openworkflow/cli worker start --concurrency 10
   capacity.
 </Note>
 
+## Workflow Concurrency
+
+Workflow specs can also define concurrency buckets that are enforced at claim
+time:
+
+```ts
+defineWorkflow(
+  {
+    name: "process-order",
+    concurrency: {
+      key: ({ input }) => `tenant:${input.tenantId}`, // or: "tenant:acme"
+      limit: ({ input }) => input.maxConcurrentOrders, // or: 5
+    },
+  },
+  async ({ step }) => {
+    // ...
+  },
+);
+```
+
+Workers will only claim a run when the bucket has capacity. Bucket scope is:
+
+- namespace
+- workflow name
+- workflow version
+- resolved concurrency key
+
+Only active leased `running` runs consume workflow-concurrency slots.
+Resolved keys are stored verbatim; only empty/all-whitespace keys are rejected.
+Sleeping runs are non-consuming until they are claimed again as actively leased
+`running` runs.
+
 ## Heartbeats and Crash Recovery
 
 Workers maintain their claim on workflow runs through a heartbeat mechanism:

packages/docs/docs/workflows.mdx

@@ -189,6 +189,43 @@ defineWorkflow(
 Any `retryPolicy` fields you omit fall back to defaults. See
 [Retries](/docs/retries) for the full behavior and defaults.
 
+### Concurrency (Optional)
+
+Control how many active leased `running` runs are allowed for a workflow bucket:
+
+```ts
+defineWorkflow(
+  {
+    name: "process-order",
+    concurrency: {
+      key: ({ input }) => `tenant:${input.tenantId}`, // or: "tenant:acme"
+      limit: ({ input }) => input.maxConcurrentOrders, // or: 5
+    },
+  },
+  async ({ input, step }) => {
+    // ...
+  },
+);
+```
+
+- `key` can be a string or a function `({ input }) => string`
+- `limit` can be a number or a function `({ input }) => number`
+- key must resolve to a non-empty string
+- limit must resolve to a positive integer
+- resolved keys are stored verbatim; only empty/all-whitespace keys are rejected
+
+When concurrency is configured, runs in the same bucket are constrained by:
+
+- namespace
+- workflow name
+- workflow version
+- resolved `key`
+
+Only actively leased `running` runs consume slots. `pending`, `sleeping`, and
+expired-lease runs do not.
+Sleeping runs become slot-consuming only after they are claimed again as
+actively leased `running` runs.
+
 ### Idempotency Key (Optional)
 
 You can prevent duplicate run creation by providing an idempotency key, though

packages/openworkflow/README.md

@@ -67,11 +67,38 @@ For more details, check out our [docs](https://openworkflow.dev/docs).
 - ✅ **Long pauses** - Sleep for seconds or months
 - ✅ **Scheduled runs** - Start workflows at a specific time
 - ✅ **Parallel execution** - Run steps concurrently
+- ✅ **Workflow concurrency** - Limit active runs by key (static or input-based)
 - ✅ **Idempotency keys** - Deduplicate repeated run requests (24h window)
 - ✅ **No extra servers** - Uses your existing database
 - ✅ **Dashboard included** - Monitor and debug workflows
 - ✅ **Production ready** - PostgreSQL and SQLite support
 
+## Workflow Concurrency
+
+You can limit active leased `running` runs per workflow bucket:
+
+```ts
+const workflow = defineWorkflow(
+  {
+    name: "process-order",
+    concurrency: {
+      key: ({ input }) => `tenant:${input.tenantId}`, // or: "tenant:acme"
+      limit: ({ input }) => input.maxConcurrentOrders, // or: 5
+    },
+  },
+  async ({ step }) => {
+    // ...
+  },
+);
+```
+
+`key` must resolve to a non-empty string and `limit` must resolve to a positive
+integer. Invalid values fail run creation.
+Keys are stored verbatim (for example, `" foo "` and `"foo"` are different
+concurrency keys); only empty or all-whitespace keys are rejected.
+Sleeping runs do not consume workflow-concurrency slots until they are claimed
+again as actively leased `running` runs.
+
 ## Documentation
 
 - [Documentation](https://openworkflow.dev/docs)