@pgflow/core 0.6.0 → 0.7.0

package/README.md

@@ -94,6 +94,106 @@ The SQL Core handles the workflow lifecycle through these key operations:
 
 <a href="./assets/flow-lifecycle.svg"><img src="./assets/flow-lifecycle.svg" alt="Flow Lifecycle" width="25%" height="25%"></a>
 
+## Step Types
+
+pgflow supports two fundamental step types that control how tasks are created and executed:
+
+### Single Steps (Default)
+
+Single steps are the standard step type where each step creates exactly one task when started. These steps process their input as a whole and return a single output value.
+
+```sql
+-- Regular single step definition
+SELECT pgflow.add_step('my_flow', 'process_data');
+```
+
+### Map Steps
+
+Map steps enable parallel processing of arrays by automatically creating multiple tasks - one for each array element. The system handles task distribution, parallel execution, and output aggregation transparently.
+
+```sql
+-- Map step definition (step_type => 'map')
+SELECT pgflow.add_step(
+  flow_slug => 'my_flow',
+  step_slug => 'process_items',
+  deps_slugs => ARRAY['fetch_items'],
+  step_type => 'map'
+);
+```
+
+#### Key Characteristics
+
+- **Multiple Task Creation**: The SQL core creates N tasks for a map step (one per array element), unlike single steps which create one task
+- **Element Distribution**: The SQL core distributes individual array elements to tasks based on `task_index`
+- **Output Aggregation**: The SQL core aggregates task outputs back into an array for dependent steps
+- **Constraint**: Map steps can have at most one dependency (which must return an array), or zero dependencies (then flow input must be an array)
+
+#### Map Step Execution Flow
+
+1. **Array Input Validation**: The SQL core validates that the input is an array
+2. **Task Creation**: The SQL core creates N tasks with indices 0 to N-1
+3. **Element Distribution**: The SQL core assigns `array[task_index]` as input to each task
+4. **Parallel Execution**: Edge workers execute tasks independently in parallel
+5. **Output Collection**: The SQL core aggregates outputs preserving array order
+6. **Dependent Activation**: The SQL core passes the aggregated array to dependent steps
+
+#### Root Map vs Dependent Map
+
+**Root Map Steps** process the flow's input array directly:
+```sql
+-- Root map: no dependencies, processes flow input
+SELECT pgflow.add_step(
+  flow_slug => 'batch_processor',
+  step_slug => 'process_each',
+  step_type => 'map'
+);
+
+-- Starting the flow with array input
+SELECT pgflow.start_flow(
+  flow_slug => 'batch_processor',
+  input => '[1, 2, 3, 4, 5]'::jsonb
+);
+```
+
+**Dependent Map Steps** process another step's array output:
+```sql
+-- Dependent map: processes the array from 'fetch_items'
+SELECT pgflow.add_step(
+  flow_slug => 'data_pipeline',
+  step_slug => 'transform_each',
+  deps_slugs => ARRAY['fetch_items'],
+  step_type => 'map'
+);
+```
+
+#### Edge Cases and Special Behaviors
+
+1. **Empty Array Cascade**: When a map step receives an empty array (`[]`):
+   - The SQL core completes it immediately without creating tasks
+   - The completed map step outputs an empty array
+   - Any dependent map steps also receive empty arrays and complete immediately
+   - This cascades through the entire chain of map steps in a single transaction
+   - Example: `[] → map1 → [] → map2 → [] → map3 → []` all complete together
+
+2. **NULL Values**: NULL array elements are preserved and distributed to their respective tasks
+
+3. **Non-Array Input**: The SQL core fails the step when input is not an array
+
+4. **Type Violations**: When a single step outputs non-array data to a map step, the SQL core fails the entire run (stores the invalid output for debugging, archives all queued messages, prevents orphaned tasks)
+
+#### Implementation Details
+
+Map steps utilize several database fields for state management:
+- `initial_tasks`: Number of tasks to create (NULL until array size is known)
+- `remaining_tasks`: Tracks incomplete tasks for the step
+- `task_index`: Identifies which array element each task processes
+- `step_type`: Column value 'map' triggers map behavior
+
+The aggregation process ensures:
+- **Order Preservation**: Task outputs maintain array element ordering
+- **NULL Handling**: NULL outputs are included in the aggregated array
+- **Atomicity**: Aggregation occurs within the same transaction as task completion
+
 ## Example flow and its life
 
 Let's walk through creating and running a workflow that fetches a website,
@@ -231,10 +331,16 @@ The system handles failures by:
    - Preventing processing until the visibility timeout expires
 3. When retries are exhausted:
    - Marking the task as 'failed'
+   - Storing the task output (even for failed tasks)
    - Marking the step as 'failed'
    - Marking the run as 'failed'
    - Archiving the message in PGMQ
-   - Notifying workers to abort pending tasks (future feature)
+   - **Archiving all queued messages for the failed run** (preventing orphaned messages)
+4. Additional failure handling:
+   - **No retries on already-failed runs** - tasks are immediately marked as failed
+   - **Graceful type constraint violations** - handled without exceptions when single steps feed map steps
+   - **Stores invalid output on type violations** - captures the output that caused the violation for debugging
+   - **Performance-optimized message archiving** using indexed queries
 
 #### Retries and Timeouts
 
@@ -268,81 +374,17 @@ delay = base_delay * (2 ^ attempts_count)
 
 Timeouts are enforced by setting the message visibility timeout to the step's timeout value plus a small buffer. If a worker doesn't acknowledge completion or failure within this period, the task becomes visible again and can be retried.
 
-## TypeScript Flow DSL
+## Workflow Definition with TypeScript DSL
 
-> [!NOTE]
-> TypeScript Flow DSL is a Work In Progress and is not ready yet!
-
-### Overview
-
-While the SQL Core engine handles workflow definitions and state management, the primary way to define and work with your workflow logic is via the Flow DSL in TypeScript. This DSL offers a fluent API that makes it straightforward to outline the steps in your flow with full type safety.
-
-### Type Inference System
-
-The most powerful feature of the Flow DSL is its **automatic type inference system**:
-
-1. You only need to annotate the initial Flow input type
-2. The return type of each step is automatically inferred from your handler function
-3. These return types become available in the payload of dependent steps
-4. The TypeScript compiler builds a complete type graph matching your workflow DAG
-
-This means you get full IDE autocompletion and type checking throughout your workflow without manual type annotations.
-
-### Basic Example
-
-Here's an example that matches our website analysis workflow:
-
-```ts
-// Provide a type for the input of the Flow
-type Input = {
-  url: string;
-};
-
-const AnalyzeWebsite = new Flow<Input>({
-  slug: 'analyze_website',
-  maxAttempts: 3,
-  baseDelay: 5,
-  timeout: 10,
-})
-  .step(
-    { slug: 'website' },
-    async (input) => await scrapeWebsite(input.run.url)
-  )
-  .step(
-    { slug: 'sentiment', dependsOn: ['website'], timeout: 30, maxAttempts: 5 },
-    async (input) => await analyzeSentiment(input.website.content)
-  )
-  .step(
-    { slug: 'summary', dependsOn: ['website'] },
-    async (input) => await summarizeWithAI(input.website.content)
-  )
-  .step(
-    { slug: 'saveToDb', dependsOn: ['sentiment', 'summary'] },
-    async (input) =>
-      await saveToDb({
-        websiteUrl: input.run.url,
-        sentiment: input.sentiment.score,
-        summary: input.summary,
-      }).status
-  );
-```
-
-### How Payload Types Are Built
-
-The payload object for each step is constructed dynamically based on:
+The SQL Core is the DAG orchestration engine that handles dependency resolution, step state management, and task spawning. However, workflows are defined using the TypeScript Flow DSL, which compiles user intent into the SQL primitives that populate the definition tables (`flows`, `steps`, `deps`).
 
-1. **The `run` property**: Always contains the original workflow input
-2. **Dependency outputs**: Each dependency's output is available under a key matching the dependency's ID
-3. **DAG structure**: Only outputs from direct dependencies are included in the payload
+See the [@pgflow/dsl package](../dsl/README.md) for complete documentation on:
+- Expressing workflows with type-safe method chaining
+- Step types (`.step()`, `.array()`, `.map()`)
+- Compilation to SQL migrations
+- Type inference and handler context
 
-This means your step handlers receive exactly the data they need, properly typed, without any manual type declarations beyond the initial Flow input type.
-
-### Benefits of Automatic Type Inference
-
-- **Refactoring safety**: Change a step's output, and TypeScript will flag all dependent steps that need updates
-- **Discoverability**: IDE autocompletion shows exactly what data is available in each step
-- **Error prevention**: Catch typos and type mismatches at compile time, not runtime
-- **Documentation**: The types themselves serve as living documentation of your workflow's data flow
+The SQL Core executes these compiled definitions, managing when steps are ready, how many tasks to create (1 for single steps, N for map steps), and how to aggregate results.
 
 ## Data Flow
 
@@ -379,6 +421,46 @@ The `saveToDb` step depends on both `sentiment` and `summary`:
 }
 ```
 
+### Map Step Handler Inputs
+
+Map step tasks receive a fundamentally different input structure than single step tasks. Instead of receiving an object with `run` and dependency keys, **map tasks receive only their assigned array element**:
+
+#### Example: Processing user IDs
+
+```json
+// Flow input (for root map) or dependency output:
+["user123", "user456", "user789"]
+
+// What each map task receives:
+// Task 0: "user123"
+// Task 1: "user456"
+// Task 2: "user789"
+
+// NOT this:
+// { "run": {...}, "dependency": [...] }
+```
+
+This means:
+- Map handlers process individual elements in isolation
+- Map handlers cannot access the original flow input (`run`)
+- Map handlers cannot access other dependencies
+- Map handlers focus solely on transforming their assigned element
+
+#### Map Step Outputs Become Arrays
+
+When a step depends on a map step, it receives the aggregated array output:
+
+```json
+// If 'process_users' is a map step that processed ["user1", "user2"]
+// and output [{"name": "Alice"}, {"name": "Bob"}]
+
+// A step depending on 'process_users' receives:
+{
+  "run": { /* original flow input */ },
+  "process_users": [{"name": "Alice"}, {"name": "Bob"}]  // Full array
+}
+```
+
 ### Run Completion
 
 When all steps in a run are completed, the run status is automatically updated to 'completed' and its output is set. The output is an aggregation of all the outputs from final steps (steps that have no dependents):

package/dist/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @pgflow/core
 
+## 0.7.0
+
+### Minor Changes
+
+- 524db03: Add map step type infrastructure in SQL core
+
+  ⚠️ **This migration includes automatic data migration**
+
+  The migration will automatically update existing `step_states` rows to satisfy new constraints. This should complete without issues due to strict check constraints enforced in previous versions.
+
+  💡 **Recommended: Verify before deploying to production**
+
+  If you have existing production data and want to verify the migration will succeed cleanly, run this **read-only check query** (does not modify data) in **Supabase Studio** against your **production database**:
+
+  1. Open Supabase Studio → SQL Editor
+  2. Copy contents of `pkgs/core/queries/PRE_MIGRATION_CHECK_20251006073122.sql`
+  3. Execute against your production database (not local dev!)
+  4. Review results
+
+  **Expected output for successful migration:**
+
+  ```
+  type                       | identifier                | details
+  ---------------------------|---------------------------|------------------------------------------
+  DATA_BACKFILL_STARTED      | run=def67890 step=process | initial_tasks will be set to 1 (...)
+  DATA_BACKFILL_COMPLETED    | Found 100 completed steps | initial_tasks will be set to 1 (...)
+  INFO_SUMMARY               | total_step_states=114     | created=0 started=1 completed=113 failed=0
+  ```
+
+  **Interpretation:**
+
+  - ✅ Only `DATA_BACKFILL_*` and `INFO_SUMMARY` rows? **Safe to migrate**
+  - ⚠️ These are expected data migrations handled automatically by the migration
+  - 🆘 Unexpected rows or errors? Copy output and share on Discord for help
+
+  📝 **Note:** This check identifies data that needs migration but does not modify anything. Only useful for production databases with existing runs.
+
+  **Automatic data updates:**
+
+  - Sets `initial_tasks = 1` for all existing steps (correct for pre-map-step schema)
+  - Sets `remaining_tasks = NULL` for 'created' status steps (new semantics)
+
+  No manual intervention required.
+
+  ***
+
+  ## Changes
+
+  This patch introduces the foundation for map step functionality in the SQL core layer:
+
+  ### Schema Changes
+
+  - Added `step_type` column to `steps` table with constraint allowing 'single' or 'map' values
+  - Added `initial_tasks` column to `step_states` table (defaults to 1, stores planned task count)
+  - Modified `remaining_tasks` column to be nullable (NULL = not started, >0 = active countdown)
+  - Added constraint `remaining_tasks_state_consistency` to ensure `remaining_tasks` is only set when step has started
+  - Removed `only_single_task_per_step` constraint from `step_tasks` table to allow multiple tasks per step
+
+  ### Function Updates
+
+  - **`add_step()`**: Now accepts `step_type` parameter (defaults to 'single') with validation that map steps can have at most 1 dependency
+  - **`start_flow()`**: Sets `initial_tasks = 1` for all steps (map step array handling will come in future phases)
+  - **`start_ready_steps()`**: Copies `initial_tasks` to `remaining_tasks` when starting a step, maintaining proper task counting semantics
+
+  ### Testing
+
+  - Added comprehensive test coverage for map step creation and validation
+  - All existing tests pass with the new schema changes
+  - Tests validate the new step_type parameter and dependency constraints for map steps
+
+  This is Phase 2a of the map step implementation, establishing the SQL infrastructure needed for parallel task execution in future phases.
+
+### Patch Changes
+
+- 524db03: Improve failure handling and prevent orphaned messages in queue
+
+  - Archive all queued messages when a run fails to prevent resource waste
+  - Handle type constraint violations gracefully without exceptions
+  - Store output on failed tasks (including type violations) for debugging
+  - Add performance index for efficient message archiving
+  - Prevent retries on already-failed runs
+  - Update table constraint to allow output storage on failed tasks
+
+- Updated dependencies [524db03]
+- Updated dependencies [524db03]
+  - @pgflow/dsl@0.7.0
+
+## 0.6.1
+
+### Patch Changes
+
+- @pgflow/dsl@0.6.1
+
 ## 0.6.0
 
 ### Patch Changes

package/dist/PgflowSqlClient.js

@@ -33,7 +33,7 @@ export class PgflowSqlClient {
       SELECT pgflow.complete_task(
         run_id => ${stepTask.run_id}::uuid,
         step_slug => ${stepTask.step_slug}::text,
-        task_index => ${0}::int,
+        task_index => ${stepTask.task_index}::int,
         output => ${this.sql.json(output || null)}::jsonb
       );
     `;
@@ -48,7 +48,7 @@ export class PgflowSqlClient {
       SELECT pgflow.fail_task(
         run_id => ${stepTask.run_id}::uuid,
         step_slug => ${stepTask.step_slug}::text,
-        task_index => ${0}::int,
+        task_index => ${stepTask.task_index}::int,
         error_message => ${errorString}::text
       );
     `;

package/dist/README.md

@@ -94,6 +94,106 @@ The SQL Core handles the workflow lifecycle through these key operations:
 
 <a href="./assets/flow-lifecycle.svg"><img src="./assets/flow-lifecycle.svg" alt="Flow Lifecycle" width="25%" height="25%"></a>
 
+## Step Types
+
+pgflow supports two fundamental step types that control how tasks are created and executed:
+
+### Single Steps (Default)
+
+Single steps are the standard step type where each step creates exactly one task when started. These steps process their input as a whole and return a single output value.
+
+```sql
+-- Regular single step definition
+SELECT pgflow.add_step('my_flow', 'process_data');
+```
+
+### Map Steps
+
+Map steps enable parallel processing of arrays by automatically creating multiple tasks - one for each array element. The system handles task distribution, parallel execution, and output aggregation transparently.
+
+```sql
+-- Map step definition (step_type => 'map')
+SELECT pgflow.add_step(
+  flow_slug => 'my_flow',
+  step_slug => 'process_items',
+  deps_slugs => ARRAY['fetch_items'],
+  step_type => 'map'
+);
+```
+
+#### Key Characteristics
+
+- **Multiple Task Creation**: The SQL core creates N tasks for a map step (one per array element), unlike single steps which create one task
+- **Element Distribution**: The SQL core distributes individual array elements to tasks based on `task_index`
+- **Output Aggregation**: The SQL core aggregates task outputs back into an array for dependent steps
+- **Constraint**: Map steps can have at most one dependency (which must return an array), or zero dependencies (then flow input must be an array)
+
+#### Map Step Execution Flow
+
+1. **Array Input Validation**: The SQL core validates that the input is an array
+2. **Task Creation**: The SQL core creates N tasks with indices 0 to N-1
+3. **Element Distribution**: The SQL core assigns `array[task_index]` as input to each task
+4. **Parallel Execution**: Edge workers execute tasks independently in parallel
+5. **Output Collection**: The SQL core aggregates outputs preserving array order
+6. **Dependent Activation**: The SQL core passes the aggregated array to dependent steps
+
+#### Root Map vs Dependent Map
+
+**Root Map Steps** process the flow's input array directly:
+```sql
+-- Root map: no dependencies, processes flow input
+SELECT pgflow.add_step(
+  flow_slug => 'batch_processor',
+  step_slug => 'process_each',
+  step_type => 'map'
+);
+
+-- Starting the flow with array input
+SELECT pgflow.start_flow(
+  flow_slug => 'batch_processor',
+  input => '[1, 2, 3, 4, 5]'::jsonb
+);
+```
+
+**Dependent Map Steps** process another step's array output:
+```sql
+-- Dependent map: processes the array from 'fetch_items'
+SELECT pgflow.add_step(
+  flow_slug => 'data_pipeline',
+  step_slug => 'transform_each',
+  deps_slugs => ARRAY['fetch_items'],
+  step_type => 'map'
+);
+```
+
+#### Edge Cases and Special Behaviors
+
+1. **Empty Array Cascade**: When a map step receives an empty array (`[]`):
+   - The SQL core completes it immediately without creating tasks
+   - The completed map step outputs an empty array
+   - Any dependent map steps also receive empty arrays and complete immediately
+   - This cascades through the entire chain of map steps in a single transaction
+   - Example: `[] → map1 → [] → map2 → [] → map3 → []` all complete together
+
+2. **NULL Values**: NULL array elements are preserved and distributed to their respective tasks
+
+3. **Non-Array Input**: The SQL core fails the step when input is not an array
+
+4. **Type Violations**: When a single step outputs non-array data to a map step, the SQL core fails the entire run (stores the invalid output for debugging, archives all queued messages, prevents orphaned tasks)
+
+#### Implementation Details
+
+Map steps utilize several database fields for state management:
+- `initial_tasks`: Number of tasks to create (NULL until array size is known)
+- `remaining_tasks`: Tracks incomplete tasks for the step
+- `task_index`: Identifies which array element each task processes
+- `step_type`: Column value 'map' triggers map behavior
+
+The aggregation process ensures:
+- **Order Preservation**: Task outputs maintain array element ordering
+- **NULL Handling**: NULL outputs are included in the aggregated array
+- **Atomicity**: Aggregation occurs within the same transaction as task completion
+
 ## Example flow and its life
 
 Let's walk through creating and running a workflow that fetches a website,
@@ -231,10 +331,16 @@ The system handles failures by:
    - Preventing processing until the visibility timeout expires
 3. When retries are exhausted:
    - Marking the task as 'failed'
+   - Storing the task output (even for failed tasks)
    - Marking the step as 'failed'
    - Marking the run as 'failed'
    - Archiving the message in PGMQ
-   - Notifying workers to abort pending tasks (future feature)
+   - **Archiving all queued messages for the failed run** (preventing orphaned messages)
+4. Additional failure handling:
+   - **No retries on already-failed runs** - tasks are immediately marked as failed
+   - **Graceful type constraint violations** - handled without exceptions when single steps feed map steps
+   - **Stores invalid output on type violations** - captures the output that caused the violation for debugging
+   - **Performance-optimized message archiving** using indexed queries
 
 #### Retries and Timeouts
 
@@ -268,81 +374,17 @@ delay = base_delay * (2 ^ attempts_count)
 
 Timeouts are enforced by setting the message visibility timeout to the step's timeout value plus a small buffer. If a worker doesn't acknowledge completion or failure within this period, the task becomes visible again and can be retried.
 
-## TypeScript Flow DSL
+## Workflow Definition with TypeScript DSL
 
-> [!NOTE]
-> TypeScript Flow DSL is a Work In Progress and is not ready yet!
-
-### Overview
-
-While the SQL Core engine handles workflow definitions and state management, the primary way to define and work with your workflow logic is via the Flow DSL in TypeScript. This DSL offers a fluent API that makes it straightforward to outline the steps in your flow with full type safety.
-
-### Type Inference System
-
-The most powerful feature of the Flow DSL is its **automatic type inference system**:
-
-1. You only need to annotate the initial Flow input type
-2. The return type of each step is automatically inferred from your handler function
-3. These return types become available in the payload of dependent steps
-4. The TypeScript compiler builds a complete type graph matching your workflow DAG
-
-This means you get full IDE autocompletion and type checking throughout your workflow without manual type annotations.
-
-### Basic Example
-
-Here's an example that matches our website analysis workflow:
-
-```ts
-// Provide a type for the input of the Flow
-type Input = {
-  url: string;
-};
-
-const AnalyzeWebsite = new Flow<Input>({
-  slug: 'analyze_website',
-  maxAttempts: 3,
-  baseDelay: 5,
-  timeout: 10,
-})
-  .step(
-    { slug: 'website' },
-    async (input) => await scrapeWebsite(input.run.url)
-  )
-  .step(
-    { slug: 'sentiment', dependsOn: ['website'], timeout: 30, maxAttempts: 5 },
-    async (input) => await analyzeSentiment(input.website.content)
-  )
-  .step(
-    { slug: 'summary', dependsOn: ['website'] },
-    async (input) => await summarizeWithAI(input.website.content)
-  )
-  .step(
-    { slug: 'saveToDb', dependsOn: ['sentiment', 'summary'] },
-    async (input) =>
-      await saveToDb({
-        websiteUrl: input.run.url,
-        sentiment: input.sentiment.score,
-        summary: input.summary,
-      }).status
-  );
-```
-
-### How Payload Types Are Built
-
-The payload object for each step is constructed dynamically based on:
+The SQL Core is the DAG orchestration engine that handles dependency resolution, step state management, and task spawning. However, workflows are defined using the TypeScript Flow DSL, which compiles user intent into the SQL primitives that populate the definition tables (`flows`, `steps`, `deps`).
 
-1. **The `run` property**: Always contains the original workflow input
-2. **Dependency outputs**: Each dependency's output is available under a key matching the dependency's ID
-3. **DAG structure**: Only outputs from direct dependencies are included in the payload
+See the [@pgflow/dsl package](../dsl/README.md) for complete documentation on:
+- Expressing workflows with type-safe method chaining
+- Step types (`.step()`, `.array()`, `.map()`)
+- Compilation to SQL migrations
+- Type inference and handler context
 
-This means your step handlers receive exactly the data they need, properly typed, without any manual type declarations beyond the initial Flow input type.
-
-### Benefits of Automatic Type Inference
-
-- **Refactoring safety**: Change a step's output, and TypeScript will flag all dependent steps that need updates
-- **Discoverability**: IDE autocompletion shows exactly what data is available in each step
-- **Error prevention**: Catch typos and type mismatches at compile time, not runtime
-- **Documentation**: The types themselves serve as living documentation of your workflow's data flow
+The SQL Core executes these compiled definitions, managing when steps are ready, how many tasks to create (1 for single steps, N for map steps), and how to aggregate results.
 
 ## Data Flow
 
@@ -379,6 +421,46 @@ The `saveToDb` step depends on both `sentiment` and `summary`:
 }
 ```
 
+### Map Step Handler Inputs
+
+Map step tasks receive a fundamentally different input structure than single step tasks. Instead of receiving an object with `run` and dependency keys, **map tasks receive only their assigned array element**:
+
+#### Example: Processing user IDs
+
+```json
+// Flow input (for root map) or dependency output:
+["user123", "user456", "user789"]
+
+// What each map task receives:
+// Task 0: "user123"
+// Task 1: "user456"
+// Task 2: "user789"
+
+// NOT this:
+// { "run": {...}, "dependency": [...] }
+```
+
+This means:
+- Map handlers process individual elements in isolation
+- Map handlers cannot access the original flow input (`run`)
+- Map handlers cannot access other dependencies
+- Map handlers focus solely on transforming their assigned element
+
+#### Map Step Outputs Become Arrays
+
+When a step depends on a map step, it receives the aggregated array output:
+
+```json
+// If 'process_users' is a map step that processed ["user1", "user2"]
+// and output [{"name": "Alice"}, {"name": "Bob"}]
+
+// A step depending on 'process_users' receives:
+{
+  "run": { /* original flow input */ },
+  "process_users": [{"name": "Alice"}, {"name": "Bob"}]  // Full array
+}
+```
+
 ### Run Completion
 
 When all steps in a run are completed, the run status is automatically updated to 'completed' and its output is set. The output is an aggregation of all the outputs from final steps (steps that have no dependents):