@pgflow/core 0.0.0-array-map-steps-cd94242a-20251008042921 → 0.0.0-condition-4354fcb6-20260108134756

package/dist/supabase/migrations/20260108131350_pgflow_step_conditions.sql

@@ -0,0 +1,1515 @@
+-- Modify "step_states" table
+ALTER TABLE "pgflow"."step_states" DROP CONSTRAINT "completed_at_or_failed_at", DROP CONSTRAINT "remaining_tasks_state_consistency", ADD CONSTRAINT "remaining_tasks_state_consistency" CHECK ((remaining_tasks IS NULL) OR (status <> ALL (ARRAY['created'::text, 'skipped'::text]))), DROP CONSTRAINT "status_is_valid", ADD CONSTRAINT "status_is_valid" CHECK (status = ANY (ARRAY['created'::text, 'started'::text, 'completed'::text, 'failed'::text, 'skipped'::text])), ADD CONSTRAINT "completed_at_or_failed_at_or_skipped_at" CHECK (((
+CASE
+    WHEN (completed_at IS NOT NULL) THEN 1
+    ELSE 0
+END +
+CASE
+    WHEN (failed_at IS NOT NULL) THEN 1
+    ELSE 0
+END) +
+CASE
+    WHEN (skipped_at IS NOT NULL) THEN 1
+    ELSE 0
+END) <= 1), ADD CONSTRAINT "skip_reason_matches_status" CHECK (((status = 'skipped'::text) AND (skip_reason IS NOT NULL)) OR ((status <> 'skipped'::text) AND (skip_reason IS NULL))), ADD CONSTRAINT "skipped_at_is_after_created_at" CHECK ((skipped_at IS NULL) OR (skipped_at >= created_at)), ADD COLUMN "skip_reason" text NULL, ADD COLUMN "skipped_at" timestamptz NULL;
+-- Create index "idx_step_states_skipped" to table: "step_states"
+CREATE INDEX "idx_step_states_skipped" ON "pgflow"."step_states" ("run_id", "step_slug") WHERE (status = 'skipped'::text);
+-- Modify "steps" table
+ALTER TABLE "pgflow"."steps" ADD CONSTRAINT "when_failed_is_valid" CHECK (when_failed = ANY (ARRAY['fail'::text, 'skip'::text, 'skip-cascade'::text])), ADD CONSTRAINT "when_unmet_is_valid" CHECK (when_unmet = ANY (ARRAY['fail'::text, 'skip'::text, 'skip-cascade'::text])), ADD COLUMN "condition_pattern" jsonb NULL, ADD COLUMN "condition_not_pattern" jsonb NULL, ADD COLUMN "when_unmet" text NOT NULL DEFAULT 'skip', ADD COLUMN "when_failed" text NOT NULL DEFAULT 'fail';
+-- Create "_cascade_force_skip_steps" function
+CREATE FUNCTION "pgflow"."_cascade_force_skip_steps" ("run_id" uuid, "step_slug" text, "skip_reason" text) RETURNS integer LANGUAGE plpgsql AS $$
+DECLARE
+  v_flow_slug text;
+  v_total_skipped int := 0;
+BEGIN
+  -- Get flow_slug for this run
+  SELECT r.flow_slug INTO v_flow_slug
+  FROM pgflow.runs r
+  WHERE r.run_id = _cascade_force_skip_steps.run_id;
+
+  IF v_flow_slug IS NULL THEN
+    RAISE EXCEPTION 'Run not found: %', _cascade_force_skip_steps.run_id;
+  END IF;
+
+  -- ==========================================
+  -- SKIP STEPS IN TOPOLOGICAL ORDER
+  -- ==========================================
+  -- Use recursive CTE to find all downstream dependents,
+  -- then skip them in topological order (by step_index)
+  WITH RECURSIVE
+  -- ---------- Find all downstream steps ----------
+  downstream_steps AS (
+    -- Base case: the trigger step
+    SELECT
+      s.flow_slug,
+      s.step_slug,
+      s.step_index,
+      _cascade_force_skip_steps.skip_reason AS reason  -- Original reason for trigger step
+    FROM pgflow.steps s
+    WHERE s.flow_slug = v_flow_slug
+      AND s.step_slug = _cascade_force_skip_steps.step_slug
+
+    UNION ALL
+
+    -- Recursive case: steps that depend on already-found steps
+    SELECT
+      s.flow_slug,
+      s.step_slug,
+      s.step_index,
+      'dependency_skipped'::text AS reason  -- Downstream steps get this reason
+    FROM pgflow.steps s
+    JOIN pgflow.deps d ON d.flow_slug = s.flow_slug AND d.step_slug = s.step_slug
+    JOIN downstream_steps ds ON ds.flow_slug = d.flow_slug AND ds.step_slug = d.dep_slug
+  ),
+  -- ---------- Deduplicate and order by step_index ----------
+  steps_to_skip AS (
+    SELECT DISTINCT ON (ds.step_slug)
+      ds.flow_slug,
+      ds.step_slug,
+      ds.step_index,
+      ds.reason
+    FROM downstream_steps ds
+    ORDER BY ds.step_slug, ds.step_index  -- Keep first occurrence (trigger step has original reason)
+  ),
+  -- ---------- Skip the steps ----------
+  skipped AS (
+    UPDATE pgflow.step_states ss
+    SET status = 'skipped',
+        skip_reason = sts.reason,
+        skipped_at = now(),
+        remaining_tasks = NULL  -- Clear remaining_tasks for skipped steps
+    FROM steps_to_skip sts
+    WHERE ss.run_id = _cascade_force_skip_steps.run_id
+      AND ss.step_slug = sts.step_slug
+      AND ss.status IN ('created', 'started')  -- Only skip non-terminal steps
+    RETURNING
+      ss.*,
+      -- Broadcast step:skipped event
+      realtime.send(
+        jsonb_build_object(
+          'event_type', 'step:skipped',
+          'run_id', ss.run_id,
+          'flow_slug', ss.flow_slug,
+          'step_slug', ss.step_slug,
+          'status', 'skipped',
+          'skip_reason', ss.skip_reason,
+          'skipped_at', ss.skipped_at
+        ),
+        concat('step:', ss.step_slug, ':skipped'),
+        concat('pgflow:run:', ss.run_id),
+        false
+      ) as _broadcast_result
+  ),
+  -- ---------- Update run counters ----------
+  run_updates AS (
+    UPDATE pgflow.runs r
+    SET remaining_steps = r.remaining_steps - skipped_count.count
+    FROM (SELECT COUNT(*) AS count FROM skipped) skipped_count
+    WHERE r.run_id = _cascade_force_skip_steps.run_id
+      AND skipped_count.count > 0
+  )
+  SELECT COUNT(*) INTO v_total_skipped FROM skipped;
+
+  RETURN v_total_skipped;
+END;
+$$;
+-- Create "cascade_resolve_conditions" function
+CREATE FUNCTION "pgflow"."cascade_resolve_conditions" ("run_id" uuid) RETURNS boolean LANGUAGE plpgsql SET "search_path" = '' AS $$
+DECLARE
+  v_run_input jsonb;
+  v_run_status text;
+  v_first_fail record;
+  v_iteration_count int := 0;
+  v_max_iterations int := 50;
+  v_processed_count int;
+BEGIN
+  -- ==========================================
+  -- GUARD: Early return if run is already terminal
+  -- ==========================================
+  SELECT r.status, r.input INTO v_run_status, v_run_input
+  FROM pgflow.runs r
+  WHERE r.run_id = cascade_resolve_conditions.run_id;
+
+  IF v_run_status IN ('failed', 'completed') THEN
+    RETURN v_run_status != 'failed';
+  END IF;
+
+  -- ==========================================
+  -- ITERATE UNTIL CONVERGENCE
+  -- ==========================================
+  -- After skipping steps, dependents may become ready and need evaluation.
+  -- Loop until no more steps are processed.
+  LOOP
+    v_iteration_count := v_iteration_count + 1;
+    IF v_iteration_count > v_max_iterations THEN
+      RAISE EXCEPTION 'cascade_resolve_conditions exceeded safety limit of % iterations', v_max_iterations;
+    END IF;
+
+    v_processed_count := 0;
+
+    -- ==========================================
+    -- PHASE 1a: CHECK FOR FAIL CONDITIONS
+    -- ==========================================
+    -- Find first step (by topological order) with unmet condition and 'fail' mode.
+    -- Condition is unmet when:
+    --   (condition_pattern is set AND input does NOT contain it) OR
+    --   (condition_not_pattern is set AND input DOES contain it)
+    WITH steps_with_conditions AS (
+      SELECT
+        step_state.flow_slug,
+        step_state.step_slug,
+        step.condition_pattern,
+        step.condition_not_pattern,
+        step.when_unmet,
+        step.deps_count,
+        step.step_index
+      FROM pgflow.step_states AS step_state
+      JOIN pgflow.steps AS step
+        ON step.flow_slug = step_state.flow_slug
+        AND step.step_slug = step_state.step_slug
+      WHERE step_state.run_id = cascade_resolve_conditions.run_id
+        AND step_state.status = 'created'
+        AND step_state.remaining_deps = 0
+        AND (step.condition_pattern IS NOT NULL OR step.condition_not_pattern IS NOT NULL)
+    ),
+    step_deps_output AS (
+      SELECT
+        swc.step_slug,
+        jsonb_object_agg(dep_state.step_slug, dep_state.output) AS deps_output
+      FROM steps_with_conditions swc
+      JOIN pgflow.deps dep ON dep.flow_slug = swc.flow_slug AND dep.step_slug = swc.step_slug
+      JOIN pgflow.step_states dep_state
+        ON dep_state.run_id = cascade_resolve_conditions.run_id
+        AND dep_state.step_slug = dep.dep_slug
+        AND dep_state.status = 'completed'  -- Only completed deps (not skipped)
+      WHERE swc.deps_count > 0
+      GROUP BY swc.step_slug
+    ),
+    condition_evaluations AS (
+      SELECT
+        swc.*,
+        -- condition_met = (if IS NULL OR input @> if) AND (ifNot IS NULL OR NOT(input @> ifNot))
+        (swc.condition_pattern IS NULL OR
+          CASE WHEN swc.deps_count = 0 THEN v_run_input ELSE COALESCE(sdo.deps_output, '{}'::jsonb) END @> swc.condition_pattern)
+        AND
+        (swc.condition_not_pattern IS NULL OR
+          NOT (CASE WHEN swc.deps_count = 0 THEN v_run_input ELSE COALESCE(sdo.deps_output, '{}'::jsonb) END @> swc.condition_not_pattern))
+        AS condition_met
+      FROM steps_with_conditions swc
+      LEFT JOIN step_deps_output sdo ON sdo.step_slug = swc.step_slug
+    )
+    SELECT flow_slug, step_slug, condition_pattern, condition_not_pattern
+    INTO v_first_fail
+    FROM condition_evaluations
+    WHERE NOT condition_met AND when_unmet = 'fail'
+    ORDER BY step_index
+    LIMIT 1;
+
+    -- Handle fail mode: fail step and run, return false
+    -- Note: Cannot use "v_first_fail IS NOT NULL" because records with NULL fields
+    -- evaluate to NULL in IS NOT NULL checks. Use FOUND instead.
+    IF FOUND THEN
+      UPDATE pgflow.step_states
+      SET status = 'failed',
+          failed_at = now(),
+          error_message = 'Condition not met'
+      WHERE pgflow.step_states.run_id = cascade_resolve_conditions.run_id
+        AND pgflow.step_states.step_slug = v_first_fail.step_slug;
+
+      UPDATE pgflow.runs
+      SET status = 'failed',
+          failed_at = now()
+      WHERE pgflow.runs.run_id = cascade_resolve_conditions.run_id;
+
+      RETURN false;
+    END IF;
+
+    -- ==========================================
+    -- PHASE 1b: HANDLE SKIP CONDITIONS (with propagation)
+    -- ==========================================
+    -- Skip steps with unmet conditions and whenUnmet='skip'.
+    -- Also decrement remaining_deps on dependents and set initial_tasks=0 for map dependents.
+    WITH steps_with_conditions AS (
+      SELECT
+        step_state.flow_slug,
+        step_state.step_slug,
+        step.condition_pattern,
+        step.condition_not_pattern,
+        step.when_unmet,
+        step.deps_count,
+        step.step_index
+      FROM pgflow.step_states AS step_state
+      JOIN pgflow.steps AS step
+        ON step.flow_slug = step_state.flow_slug
+        AND step.step_slug = step_state.step_slug
+      WHERE step_state.run_id = cascade_resolve_conditions.run_id
+        AND step_state.status = 'created'
+        AND step_state.remaining_deps = 0
+        AND (step.condition_pattern IS NOT NULL OR step.condition_not_pattern IS NOT NULL)
+    ),
+    step_deps_output AS (
+      SELECT
+        swc.step_slug,
+        jsonb_object_agg(dep_state.step_slug, dep_state.output) AS deps_output
+      FROM steps_with_conditions swc
+      JOIN pgflow.deps dep ON dep.flow_slug = swc.flow_slug AND dep.step_slug = swc.step_slug
+      JOIN pgflow.step_states dep_state
+        ON dep_state.run_id = cascade_resolve_conditions.run_id
+        AND dep_state.step_slug = dep.dep_slug
+        AND dep_state.status = 'completed'  -- Only completed deps (not skipped)
+      WHERE swc.deps_count > 0
+      GROUP BY swc.step_slug
+    ),
+    condition_evaluations AS (
+      SELECT
+        swc.*,
+        -- condition_met = (if IS NULL OR input @> if) AND (ifNot IS NULL OR NOT(input @> ifNot))
+        (swc.condition_pattern IS NULL OR
+          CASE WHEN swc.deps_count = 0 THEN v_run_input ELSE COALESCE(sdo.deps_output, '{}'::jsonb) END @> swc.condition_pattern)
+        AND
+        (swc.condition_not_pattern IS NULL OR
+          NOT (CASE WHEN swc.deps_count = 0 THEN v_run_input ELSE COALESCE(sdo.deps_output, '{}'::jsonb) END @> swc.condition_not_pattern))
+        AS condition_met
+      FROM steps_with_conditions swc
+      LEFT JOIN step_deps_output sdo ON sdo.step_slug = swc.step_slug
+    ),
+    unmet_skip_steps AS (
+      SELECT * FROM condition_evaluations
+      WHERE NOT condition_met AND when_unmet = 'skip'
+    ),
+    skipped_steps AS (
+      UPDATE pgflow.step_states ss
+      SET status = 'skipped',
+          skip_reason = 'condition_unmet',
+          skipped_at = now()
+      FROM unmet_skip_steps uss
+      WHERE ss.run_id = cascade_resolve_conditions.run_id
+        AND ss.step_slug = uss.step_slug
+      RETURNING
+        ss.*,
+        realtime.send(
+          jsonb_build_object(
+            'event_type', 'step:skipped',
+            'run_id', ss.run_id,
+            'flow_slug', ss.flow_slug,
+            'step_slug', ss.step_slug,
+            'status', 'skipped',
+            'skip_reason', 'condition_unmet',
+            'skipped_at', ss.skipped_at
+          ),
+          concat('step:', ss.step_slug, ':skipped'),
+          concat('pgflow:run:', ss.run_id),
+          false
+        ) AS _broadcast_result
+    ),
+    -- NEW: Update dependent steps (decrement remaining_deps, set initial_tasks=0 for maps)
+    dependent_updates AS (
+      UPDATE pgflow.step_states child_state
+      SET remaining_deps = child_state.remaining_deps - 1,
+          -- If child is a map step and this skipped step is its only dependency,
+          -- set initial_tasks = 0 (skipped dep = empty array)
+          initial_tasks = CASE
+            WHEN child_step.step_type = 'map' AND child_step.deps_count = 1 THEN 0
+            ELSE child_state.initial_tasks
+          END
+      FROM skipped_steps parent
+      JOIN pgflow.deps dep ON dep.flow_slug = parent.flow_slug AND dep.dep_slug = parent.step_slug
+      JOIN pgflow.steps child_step ON child_step.flow_slug = dep.flow_slug AND child_step.step_slug = dep.step_slug
+      WHERE child_state.run_id = cascade_resolve_conditions.run_id
+        AND child_state.step_slug = dep.step_slug
+    ),
+    run_update AS (
+      UPDATE pgflow.runs r
+      SET remaining_steps = r.remaining_steps - (SELECT COUNT(*) FROM skipped_steps)
+      WHERE r.run_id = cascade_resolve_conditions.run_id
+        AND (SELECT COUNT(*) FROM skipped_steps) > 0
+    )
+    SELECT COUNT(*)::int INTO v_processed_count FROM skipped_steps;
+
+    -- ==========================================
+    -- PHASE 1c: HANDLE SKIP-CASCADE CONDITIONS
+    -- ==========================================
+    -- Call _cascade_force_skip_steps for each step with unmet condition and whenUnmet='skip-cascade'.
+    -- Process in topological order; _cascade_force_skip_steps is idempotent.
+    PERFORM pgflow._cascade_force_skip_steps(cascade_resolve_conditions.run_id, ready_step.step_slug, 'condition_unmet')
+    FROM pgflow.step_states AS ready_step
+    JOIN pgflow.steps AS step
+      ON step.flow_slug = ready_step.flow_slug
+      AND step.step_slug = ready_step.step_slug
+    LEFT JOIN LATERAL (
+      SELECT jsonb_object_agg(dep_state.step_slug, dep_state.output) AS deps_output
+      FROM pgflow.deps dep
+      JOIN pgflow.step_states dep_state
+        ON dep_state.run_id = cascade_resolve_conditions.run_id
+        AND dep_state.step_slug = dep.dep_slug
+        AND dep_state.status = 'completed'  -- Only completed deps (not skipped)
+      WHERE dep.flow_slug = ready_step.flow_slug
+        AND dep.step_slug = ready_step.step_slug
+    ) AS agg_deps ON step.deps_count > 0
+    WHERE ready_step.run_id = cascade_resolve_conditions.run_id
+      AND ready_step.status = 'created'
+      AND ready_step.remaining_deps = 0
+      AND (step.condition_pattern IS NOT NULL OR step.condition_not_pattern IS NOT NULL)
+      AND step.when_unmet = 'skip-cascade'
+      -- Condition is NOT met when: (if fails) OR (ifNot fails)
+      AND NOT (
+        (step.condition_pattern IS NULL OR
+          CASE WHEN step.deps_count = 0 THEN v_run_input ELSE COALESCE(agg_deps.deps_output, '{}'::jsonb) END @> step.condition_pattern)
+        AND
+        (step.condition_not_pattern IS NULL OR
+          NOT (CASE WHEN step.deps_count = 0 THEN v_run_input ELSE COALESCE(agg_deps.deps_output, '{}'::jsonb) END @> step.condition_not_pattern))
+      )
+    ORDER BY step.step_index;
+
+    -- Check if run was failed during cascade (e.g., if _cascade_force_skip_steps triggers fail)
+    SELECT r.status INTO v_run_status
+    FROM pgflow.runs r
+    WHERE r.run_id = cascade_resolve_conditions.run_id;
+
+    IF v_run_status IN ('failed', 'completed') THEN
+      RETURN v_run_status != 'failed';
+    END IF;
+
+    -- Exit loop if no steps were processed in this iteration
+    EXIT WHEN v_processed_count = 0;
+  END LOOP;
+
+  RETURN true;
+END;
+$$;
+-- Modify "start_ready_steps" function
+CREATE OR REPLACE FUNCTION "pgflow"."start_ready_steps" ("run_id" uuid) RETURNS void LANGUAGE plpgsql SET "search_path" = '' AS $$
+BEGIN
+-- ==========================================
+-- GUARD: No mutations on terminal runs
+-- ==========================================
+IF EXISTS (
+  SELECT 1 FROM pgflow.runs
+  WHERE pgflow.runs.run_id = start_ready_steps.run_id
+    AND pgflow.runs.status IN ('failed', 'completed')
+) THEN
+  RETURN;
+END IF;
+
+-- ==========================================
+-- PHASE 1: START READY STEPS
+-- ==========================================
+-- NOTE: Condition evaluation and empty map handling are done by
+-- cascade_resolve_conditions() and cascade_complete_taskless_steps()
+-- which are called before this function.
+WITH
+-- ---------- Find ready steps ----------
+-- Steps with no remaining deps and known task count
+ready_steps AS (
+  SELECT *
+  FROM pgflow.step_states AS step_state
+  WHERE step_state.run_id = start_ready_steps.run_id
+    AND step_state.status = 'created'
+    AND step_state.remaining_deps = 0
+    AND step_state.initial_tasks IS NOT NULL  -- Cannot start with unknown count
+    AND step_state.initial_tasks > 0  -- Don't start taskless steps (handled by cascade_complete_taskless_steps)
+  ORDER BY step_state.step_slug
+  FOR UPDATE
+),
+-- ---------- Mark steps as started ----------
+started_step_states AS (
+  UPDATE pgflow.step_states
+  SET status = 'started',
+      started_at = now(),
+      remaining_tasks = ready_steps.initial_tasks  -- Copy initial_tasks to remaining_tasks when starting
+  FROM ready_steps
+  WHERE pgflow.step_states.run_id = start_ready_steps.run_id
+    AND pgflow.step_states.step_slug = ready_steps.step_slug
+  RETURNING pgflow.step_states.*,
+    -- Broadcast step:started event atomically with the UPDATE
+    -- Using RETURNING ensures this executes during row processing
+    -- and cannot be optimized away by the query planner
+    realtime.send(
+      jsonb_build_object(
+        'event_type', 'step:started',
+        'run_id', pgflow.step_states.run_id,
+        'step_slug', pgflow.step_states.step_slug,
+        'status', 'started',
+        'started_at', pgflow.step_states.started_at,
+        'remaining_tasks', pgflow.step_states.remaining_tasks,
+        'remaining_deps', pgflow.step_states.remaining_deps
+      ),
+      concat('step:', pgflow.step_states.step_slug, ':started'),
+      concat('pgflow:run:', pgflow.step_states.run_id),
+      false
+    ) as _broadcast_result  -- Prefix with _ to indicate internal use only
+),
+
+-- ==========================================
+-- PHASE 2: TASK GENERATION AND QUEUE MESSAGES
+-- ==========================================
+-- ---------- Generate tasks and batch messages ----------
+-- Single steps: 1 task (index 0)
+-- Map steps: N tasks (indices 0..N-1)
+message_batches AS (
+  SELECT
+    started_step.flow_slug,
+    started_step.run_id,
+    started_step.step_slug,
+    COALESCE(step.opt_start_delay, 0) as delay,
+    array_agg(
+      jsonb_build_object(
+        'flow_slug', started_step.flow_slug,
+        'run_id', started_step.run_id,
+        'step_slug', started_step.step_slug,
+        'task_index', task_idx.task_index
+      ) ORDER BY task_idx.task_index
+    ) AS messages,
+    array_agg(task_idx.task_index ORDER BY task_idx.task_index) AS task_indices
+  FROM started_step_states AS started_step
+  JOIN pgflow.steps AS step
+    ON step.flow_slug = started_step.flow_slug
+    AND step.step_slug = started_step.step_slug
+  -- Generate task indices from 0 to initial_tasks-1
+  CROSS JOIN LATERAL generate_series(0, started_step.initial_tasks - 1) AS task_idx(task_index)
+  GROUP BY started_step.flow_slug, started_step.run_id, started_step.step_slug, step.opt_start_delay
+),
+-- ---------- Send messages to queue ----------
+-- Uses batch sending for performance with large arrays
+sent_messages AS (
+  SELECT
+    mb.flow_slug,
+    mb.run_id,
+    mb.step_slug,
+    task_indices.task_index,
+    msg_ids.msg_id
+  FROM message_batches mb
+  CROSS JOIN LATERAL unnest(mb.task_indices) WITH ORDINALITY AS task_indices(task_index, idx_ord)
+  CROSS JOIN LATERAL pgmq.send_batch(mb.flow_slug, mb.messages, mb.delay) WITH ORDINALITY AS msg_ids(msg_id, msg_ord)
+  WHERE task_indices.idx_ord = msg_ids.msg_ord
+)
+
+-- ==========================================
+-- PHASE 3: RECORD TASKS IN DATABASE
+-- ==========================================
+INSERT INTO pgflow.step_tasks (flow_slug, run_id, step_slug, task_index, message_id)
+SELECT
+  sent_messages.flow_slug,
+  sent_messages.run_id,
+  sent_messages.step_slug,
+  sent_messages.task_index,
+  sent_messages.msg_id
+FROM sent_messages;
+
+END;
+$$;
+-- Modify "complete_task" function
+CREATE OR REPLACE FUNCTION "pgflow"."complete_task" ("run_id" uuid, "step_slug" text, "task_index" integer, "output" jsonb) RETURNS SETOF "pgflow"."step_tasks" LANGUAGE plpgsql SET "search_path" = '' AS $$
+declare
+  v_step_state pgflow.step_states%ROWTYPE;
+  v_dependent_map_slug text;
+  v_run_record pgflow.runs%ROWTYPE;
+  v_step_record pgflow.step_states%ROWTYPE;
+begin
+
+-- ==========================================
+-- GUARD: No mutations on failed runs
+-- ==========================================
+IF EXISTS (SELECT 1 FROM pgflow.runs WHERE pgflow.runs.run_id = complete_task.run_id AND pgflow.runs.status = 'failed') THEN
+  RETURN QUERY SELECT * FROM pgflow.step_tasks
+    WHERE pgflow.step_tasks.run_id = complete_task.run_id
+      AND pgflow.step_tasks.step_slug = complete_task.step_slug
+      AND pgflow.step_tasks.task_index = complete_task.task_index;
+  RETURN;
+END IF;
+
+-- ==========================================
+-- LOCK ACQUISITION AND TYPE VALIDATION
+-- ==========================================
+-- Acquire locks first to prevent race conditions
+SELECT * INTO v_run_record FROM pgflow.runs
+WHERE pgflow.runs.run_id = complete_task.run_id
+FOR UPDATE;
+
+SELECT * INTO v_step_record FROM pgflow.step_states
+WHERE pgflow.step_states.run_id = complete_task.run_id
+  AND pgflow.step_states.step_slug = complete_task.step_slug
+FOR UPDATE;
+
+-- Check for type violations AFTER acquiring locks
+SELECT child_step.step_slug INTO v_dependent_map_slug
+FROM pgflow.deps dependency
+JOIN pgflow.steps child_step ON child_step.flow_slug = dependency.flow_slug
+                             AND child_step.step_slug = dependency.step_slug
+JOIN pgflow.steps parent_step ON parent_step.flow_slug = dependency.flow_slug
+                              AND parent_step.step_slug = dependency.dep_slug
+JOIN pgflow.step_states child_state ON child_state.flow_slug = child_step.flow_slug
+                                    AND child_state.step_slug = child_step.step_slug
+WHERE dependency.dep_slug = complete_task.step_slug  -- parent is the completing step
+  AND dependency.flow_slug = v_run_record.flow_slug
+  AND parent_step.step_type = 'single'  -- Only validate single steps
+  AND child_step.step_type = 'map'
+  AND child_state.run_id = complete_task.run_id
+  AND child_state.initial_tasks IS NULL
+  AND (complete_task.output IS NULL OR jsonb_typeof(complete_task.output) != 'array')
+LIMIT 1;
+
+-- Handle type violation if detected
+IF v_dependent_map_slug IS NOT NULL THEN
+  -- Mark run as failed immediately
+  UPDATE pgflow.runs
+  SET status = 'failed',
+      failed_at = now()
+  WHERE pgflow.runs.run_id = complete_task.run_id;
+
+  -- Broadcast run:failed event
+  -- Uses PERFORM pattern to ensure execution (proven reliable pattern in this function)
+  PERFORM realtime.send(
+    jsonb_build_object(
+      'event_type', 'run:failed',
+      'run_id', complete_task.run_id,
+      'flow_slug', v_run_record.flow_slug,
+      'status', 'failed',
+      'failed_at', now()
+    ),
+    'run:failed',
+    concat('pgflow:run:', complete_task.run_id),
+    false
+  );
+
+  -- Archive all active messages (both queued and started) to prevent orphaned messages
+  PERFORM pgmq.archive(
+    v_run_record.flow_slug,
+    array_agg(st.message_id)
+  )
+  FROM pgflow.step_tasks st
+  WHERE st.run_id = complete_task.run_id
+    AND st.status IN ('queued', 'started')
+    AND st.message_id IS NOT NULL
+  HAVING count(*) > 0;  -- Only call archive if there are messages to archive
+
+  -- Mark current task as failed and store the output
+  UPDATE pgflow.step_tasks
+  SET status = 'failed',
+      failed_at = now(),
+      output = complete_task.output,  -- Store the output that caused the violation
+      error_message = '[TYPE_VIOLATION] Produced ' ||
+                     CASE WHEN complete_task.output IS NULL THEN 'null'
+                          ELSE jsonb_typeof(complete_task.output) END ||
+                     ' instead of array'
+  WHERE pgflow.step_tasks.run_id = complete_task.run_id
+    AND pgflow.step_tasks.step_slug = complete_task.step_slug
+    AND pgflow.step_tasks.task_index = complete_task.task_index;
+
+  -- Mark step state as failed
+  UPDATE pgflow.step_states
+  SET status = 'failed',
+      failed_at = now(),
+      error_message = '[TYPE_VIOLATION] Map step ' || v_dependent_map_slug ||
+                     ' expects array input but dependency ' || complete_task.step_slug ||
+                     ' produced ' || CASE WHEN complete_task.output IS NULL THEN 'null'
+                                         ELSE jsonb_typeof(complete_task.output) END
+  WHERE pgflow.step_states.run_id = complete_task.run_id
+    AND pgflow.step_states.step_slug = complete_task.step_slug;
+
+  -- Broadcast step:failed event
+  -- Uses PERFORM pattern to ensure execution (proven reliable pattern in this function)
+  PERFORM realtime.send(
+    jsonb_build_object(
+      'event_type', 'step:failed',
+      'run_id', complete_task.run_id,
+      'step_slug', complete_task.step_slug,
+      'status', 'failed',
+      'error_message', '[TYPE_VIOLATION] Map step ' || v_dependent_map_slug ||
+                      ' expects array input but dependency ' || complete_task.step_slug ||
+                      ' produced ' || CASE WHEN complete_task.output IS NULL THEN 'null'
+                                          ELSE jsonb_typeof(complete_task.output) END,
+      'failed_at', now()
+    ),
+    concat('step:', complete_task.step_slug, ':failed'),
+    concat('pgflow:run:', complete_task.run_id),
+    false
+  );
+
+  -- Archive the current task's message (it was started, now failed)
+  PERFORM pgmq.archive(
+    v_run_record.flow_slug,
+    st.message_id  -- Single message, use scalar form
+  )
+  FROM pgflow.step_tasks st
+  WHERE st.run_id = complete_task.run_id
+    AND st.step_slug = complete_task.step_slug
+    AND st.task_index = complete_task.task_index
+    AND st.message_id IS NOT NULL;
+
+  -- Return empty result
+  RETURN QUERY SELECT * FROM pgflow.step_tasks WHERE false;
+  RETURN;
+END IF;
+
+-- ==========================================
+-- MAIN CTE CHAIN: Update task and propagate changes
+-- ==========================================
+WITH
+-- ---------- Task completion ----------
+-- Update the task record with completion status and output
+task AS (
+  UPDATE pgflow.step_tasks
+  SET
+    status = 'completed',
+    completed_at = now(),
+    output = complete_task.output
+  WHERE pgflow.step_tasks.run_id = complete_task.run_id
+    AND pgflow.step_tasks.step_slug = complete_task.step_slug
+    AND pgflow.step_tasks.task_index = complete_task.task_index
+    AND pgflow.step_tasks.status = 'started'
+  RETURNING *
+),
+-- ---------- Get step type for output handling ----------
+step_def AS (
+  SELECT step.step_type
+  FROM pgflow.steps step
+  JOIN pgflow.runs run ON run.flow_slug = step.flow_slug
+  WHERE run.run_id = complete_task.run_id
+    AND step.step_slug = complete_task.step_slug
+),
+-- ---------- Step state update ----------
+-- Decrement remaining_tasks and potentially mark step as completed
+-- Also store output atomically with status transition to completed
+step_state AS (
+  UPDATE pgflow.step_states
+  SET
+    status = CASE
+    WHEN pgflow.step_states.remaining_tasks = 1 THEN 'completed'  -- Will be 0 after decrement
+    ELSE 'started'
+    END,
+    completed_at = CASE
+    WHEN pgflow.step_states.remaining_tasks = 1 THEN now()  -- Will be 0 after decrement
+    ELSE NULL
+    END,
+    remaining_tasks = pgflow.step_states.remaining_tasks - 1,
+    -- Store output atomically with completion (only when remaining_tasks = 1, meaning step completes)
+    output = CASE
+      -- Single step: store task output directly when completing
+      WHEN (SELECT step_type FROM step_def) = 'single' AND pgflow.step_states.remaining_tasks = 1 THEN
+        complete_task.output
+      -- Map step: aggregate on completion (ordered by task_index)
+      WHEN (SELECT step_type FROM step_def) = 'map' AND pgflow.step_states.remaining_tasks = 1 THEN
+        (SELECT COALESCE(jsonb_agg(all_outputs.output ORDER BY all_outputs.task_index), '[]'::jsonb)
+         FROM (
+           -- All previously completed tasks
+           SELECT st.output, st.task_index
+           FROM pgflow.step_tasks st
+           WHERE st.run_id = complete_task.run_id
+             AND st.step_slug = complete_task.step_slug
+             AND st.status = 'completed'
+           UNION ALL
+           -- Current task being completed (not yet visible as completed in snapshot)
+           SELECT complete_task.output, complete_task.task_index
+         ) all_outputs)
+      ELSE pgflow.step_states.output
+    END
+  FROM task
+  WHERE pgflow.step_states.run_id = complete_task.run_id
+    AND pgflow.step_states.step_slug = complete_task.step_slug
+  RETURNING pgflow.step_states.*
+),
+-- ---------- Dependency resolution ----------
+-- Find all child steps that depend on the completed parent step (only if parent completed)
+child_steps AS (
+  SELECT deps.step_slug AS child_step_slug
+  FROM pgflow.deps deps
+  JOIN step_state parent_state ON parent_state.status = 'completed' AND deps.flow_slug = parent_state.flow_slug
+  WHERE deps.dep_slug = complete_task.step_slug  -- dep_slug is the parent, step_slug is the child
+  ORDER BY deps.step_slug  -- Ensure consistent ordering
+),
+-- ---------- Lock child steps ----------
+-- Acquire locks on all child steps before updating them
+child_steps_lock AS (
+  SELECT * FROM pgflow.step_states
+  WHERE pgflow.step_states.run_id = complete_task.run_id
+    AND pgflow.step_states.step_slug IN (SELECT child_step_slug FROM child_steps)
+  FOR UPDATE
+),
+-- ---------- Update child steps ----------
+-- Decrement remaining_deps and resolve NULL initial_tasks for map steps
+child_steps_update AS (
+  UPDATE pgflow.step_states child_state
+  SET remaining_deps = child_state.remaining_deps - 1,
+      -- Resolve NULL initial_tasks for child map steps
+      -- This is where child maps learn their array size from the parent
+      -- This CTE only runs when the parent step is complete (see child_steps JOIN)
+      initial_tasks = CASE
+        WHEN child_step.step_type = 'map' AND child_state.initial_tasks IS NULL THEN
+          CASE
+            WHEN parent_step.step_type = 'map' THEN
+              -- Map->map: Count all completed tasks from parent map
+              -- We add 1 because the current task is being completed in this transaction
+              -- but isn't yet visible as 'completed' in the step_tasks table
+              -- TODO: Refactor to use future column step_states.total_tasks
+              -- Would eliminate the COUNT query and just use parent_state.total_tasks
+              (SELECT COUNT(*)::int + 1
+               FROM pgflow.step_tasks parent_tasks
+               WHERE parent_tasks.run_id = complete_task.run_id
+                 AND parent_tasks.step_slug = complete_task.step_slug
+                 AND parent_tasks.status = 'completed'
+                 AND parent_tasks.task_index != complete_task.task_index)
+            ELSE
+              -- Single->map: Use output array length (single steps complete immediately)
+              CASE
+                WHEN complete_task.output IS NOT NULL
+                     AND jsonb_typeof(complete_task.output) = 'array' THEN
+                  jsonb_array_length(complete_task.output)
+                ELSE NULL  -- Keep NULL if not an array
+              END
+          END
+        ELSE child_state.initial_tasks  -- Keep existing value (including NULL)
+      END
+  FROM child_steps children
+  JOIN pgflow.steps child_step ON child_step.flow_slug = (SELECT r.flow_slug FROM pgflow.runs r WHERE r.run_id = complete_task.run_id)
+                               AND child_step.step_slug = children.child_step_slug
+  JOIN pgflow.steps parent_step ON parent_step.flow_slug = (SELECT r.flow_slug FROM pgflow.runs r WHERE r.run_id = complete_task.run_id)
+                                AND parent_step.step_slug = complete_task.step_slug
+  WHERE child_state.run_id = complete_task.run_id
+    AND child_state.step_slug = children.child_step_slug
+)
+-- ---------- Update run remaining_steps ----------
+-- Decrement the run's remaining_steps counter if step completed
+UPDATE pgflow.runs
+SET remaining_steps = pgflow.runs.remaining_steps - 1
+FROM step_state
+WHERE pgflow.runs.run_id = complete_task.run_id
+  AND step_state.status = 'completed';
+
+-- ==========================================
+-- POST-COMPLETION ACTIONS
+-- ==========================================
+
+-- ---------- Get updated state for broadcasting ----------
+SELECT * INTO v_step_state FROM pgflow.step_states
+WHERE pgflow.step_states.run_id = complete_task.run_id AND pgflow.step_states.step_slug = complete_task.step_slug;
+
+-- ---------- Handle step completion ----------
+IF v_step_state.status = 'completed' THEN
+  -- Broadcast step:completed event FIRST (before cascade)
+  -- This ensures parent broadcasts before its dependent children
+  -- Use stored output from step_states (set atomically during status transition)
+  PERFORM realtime.send(
+    jsonb_build_object(
+      'event_type', 'step:completed',
+      'run_id', complete_task.run_id,
+      'step_slug', complete_task.step_slug,
+      'status', 'completed',
+      'output', v_step_state.output,  -- Use stored output instead of re-aggregating
+      'completed_at', v_step_state.completed_at
+    ),
+    concat('step:', complete_task.step_slug, ':completed'),
+    concat('pgflow:run:', complete_task.run_id),
+    false
+  );
+
+  -- THEN evaluate conditions on newly-ready dependent steps
+  -- This must happen before cascade_complete_taskless_steps so that
+  -- skipped steps can set initial_tasks=0 for their map dependents
+  IF NOT pgflow.cascade_resolve_conditions(complete_task.run_id) THEN
+    -- Run was failed due to a condition with when_unmet='fail'
+    -- Archive the current task's message before returning
+    PERFORM pgmq.archive(
+      (SELECT r.flow_slug FROM pgflow.runs r WHERE r.run_id = complete_task.run_id),
+      (SELECT st.message_id FROM pgflow.step_tasks st
+       WHERE st.run_id = complete_task.run_id
+         AND st.step_slug = complete_task.step_slug
+         AND st.task_index = complete_task.task_index)
+    );
+    RETURN QUERY SELECT * FROM pgflow.step_tasks
+      WHERE pgflow.step_tasks.run_id = complete_task.run_id
+        AND pgflow.step_tasks.step_slug = complete_task.step_slug
+        AND pgflow.step_tasks.task_index = complete_task.task_index;
+    RETURN;
+  END IF;
+
+  -- THEN cascade complete any taskless steps that are now ready
+  -- This ensures dependent children broadcast AFTER their parent
+  PERFORM pgflow.cascade_complete_taskless_steps(complete_task.run_id);
+END IF;
+
+-- ---------- Archive completed task message ----------
+-- Move message from active queue to archive table
+PERFORM (
+  WITH completed_tasks AS (
+    SELECT r.flow_slug, st.message_id
+    FROM pgflow.step_tasks st
+    JOIN pgflow.runs r ON st.run_id = r.run_id
+    WHERE st.run_id = complete_task.run_id
+      AND st.step_slug = complete_task.step_slug
+      AND st.task_index = complete_task.task_index
+      AND st.status = 'completed'
+  )
+  SELECT pgmq.archive(ct.flow_slug, ct.message_id)
+  FROM completed_tasks ct
+  WHERE EXISTS (SELECT 1 FROM completed_tasks)
+);
+
+-- ---------- Trigger next steps ----------
+-- Start any steps that are now ready (deps satisfied)
+PERFORM pgflow.start_ready_steps(complete_task.run_id);
+
+-- Check if the entire run is complete
+PERFORM pgflow.maybe_complete_run(complete_task.run_id);
+
+-- ---------- Return completed task ----------
+RETURN QUERY SELECT *
+FROM pgflow.step_tasks AS step_task
+WHERE step_task.run_id = complete_task.run_id
+  AND step_task.step_slug = complete_task.step_slug
+  AND step_task.task_index = complete_task.task_index;
+
+end;
+$$;
+-- Modify "fail_task" function
+CREATE OR REPLACE FUNCTION "pgflow"."fail_task" ("run_id" uuid, "step_slug" text, "task_index" integer, "error_message" text) RETURNS SETOF "pgflow"."step_tasks" LANGUAGE plpgsql SET "search_path" = '' AS $$
+DECLARE
+  v_run_failed boolean;
+  v_step_failed boolean;
+  v_step_skipped boolean;
+  v_when_failed text;
+  v_task_exhausted boolean;  -- True if task has exhausted retries
+begin
+
+-- If run is already failed, no retries allowed
+IF EXISTS (SELECT 1 FROM pgflow.runs WHERE pgflow.runs.run_id = fail_task.run_id AND pgflow.runs.status = 'failed') THEN
+  UPDATE pgflow.step_tasks
+  SET status = 'failed',
+      failed_at = now(),
+      error_message = fail_task.error_message
+  WHERE pgflow.step_tasks.run_id = fail_task.run_id
+    AND pgflow.step_tasks.step_slug = fail_task.step_slug
+    AND pgflow.step_tasks.task_index = fail_task.task_index
+    AND pgflow.step_tasks.status = 'started';
+
+  -- Archive the task's message
+  PERFORM pgmq.archive(r.flow_slug, ARRAY_AGG(st.message_id))
+  FROM pgflow.step_tasks st
+  JOIN pgflow.runs r ON st.run_id = r.run_id
+  WHERE st.run_id = fail_task.run_id
+    AND st.step_slug = fail_task.step_slug
+    AND st.task_index = fail_task.task_index
+    AND st.message_id IS NOT NULL
+  GROUP BY r.flow_slug
+  HAVING COUNT(st.message_id) > 0;
+
+  RETURN QUERY SELECT * FROM pgflow.step_tasks
+  WHERE pgflow.step_tasks.run_id = fail_task.run_id
+    AND pgflow.step_tasks.step_slug = fail_task.step_slug
+    AND pgflow.step_tasks.task_index = fail_task.task_index;
+  RETURN;
+END IF;
+
+WITH run_lock AS (
+  SELECT * FROM pgflow.runs
+  WHERE pgflow.runs.run_id = fail_task.run_id
+  FOR UPDATE
+),
+step_lock AS (
+  SELECT * FROM pgflow.step_states
+  WHERE pgflow.step_states.run_id = fail_task.run_id
+    AND pgflow.step_states.step_slug = fail_task.step_slug
+  FOR UPDATE
+),
+flow_info AS (
+  SELECT r.flow_slug
+  FROM pgflow.runs r
+  WHERE r.run_id = fail_task.run_id
+),
+config AS (
+  SELECT
+    COALESCE(s.opt_max_attempts, f.opt_max_attempts) AS opt_max_attempts,
+    COALESCE(s.opt_base_delay, f.opt_base_delay) AS opt_base_delay,
+    s.when_failed
+  FROM pgflow.steps s
+  JOIN pgflow.flows f ON f.flow_slug = s.flow_slug
+  JOIN flow_info fi ON fi.flow_slug = s.flow_slug
+  WHERE s.flow_slug = fi.flow_slug AND s.step_slug = fail_task.step_slug
+),
+fail_or_retry_task as (
+  UPDATE pgflow.step_tasks as task
+  SET
+    status = CASE
+      WHEN task.attempts_count < (SELECT opt_max_attempts FROM config) THEN 'queued'
+      ELSE 'failed'
+    END,
+    failed_at = CASE
+      WHEN task.attempts_count >= (SELECT opt_max_attempts FROM config) THEN now()
+      ELSE NULL
+    END,
+    started_at = CASE
+      WHEN task.attempts_count < (SELECT opt_max_attempts FROM config) THEN NULL
+      ELSE task.started_at
+    END,
+    error_message = fail_task.error_message
+  WHERE task.run_id = fail_task.run_id
+    AND task.step_slug = fail_task.step_slug
+    AND task.task_index = fail_task.task_index
+    AND task.status = 'started'
+  RETURNING *
+),
+-- Determine if task exhausted retries and get when_failed mode
+task_status AS (
+  SELECT
+    (select status from fail_or_retry_task) AS new_task_status,
+    (select when_failed from config) AS when_failed_mode,
+    -- Task is exhausted when it's failed (no more retries)
+    ((select status from fail_or_retry_task) = 'failed') AS is_exhausted
+),
+maybe_fail_step AS (
+  UPDATE pgflow.step_states
+  SET
+    -- Status logic:
+    -- - If task not exhausted (retrying): keep current status
+    -- - If exhausted AND when_failed='fail': set to 'failed'
+    -- - If exhausted AND when_failed IN ('skip', 'skip-cascade'): set to 'skipped'
+    status = CASE
+             WHEN NOT (select is_exhausted from task_status) THEN pgflow.step_states.status
+             WHEN (select when_failed_mode from task_status) = 'fail' THEN 'failed'
+             ELSE 'skipped'  -- skip or skip-cascade
+             END,
+    failed_at = CASE
+                WHEN (select is_exhausted from task_status) AND (select when_failed_mode from task_status) = 'fail' THEN now()
+                ELSE NULL
+                END,
+    error_message = CASE
+                    WHEN (select is_exhausted from task_status) THEN fail_task.error_message
+                    ELSE NULL
+                    END,
+    skip_reason = CASE
+                  WHEN (select is_exhausted from task_status) AND (select when_failed_mode from task_status) IN ('skip', 'skip-cascade') THEN 'handler_failed'
+                  ELSE pgflow.step_states.skip_reason
+                  END,
+    skipped_at = CASE
+                 WHEN (select is_exhausted from task_status) AND (select when_failed_mode from task_status) IN ('skip', 'skip-cascade') THEN now()
+                 ELSE pgflow.step_states.skipped_at
+                 END,
+    -- Clear remaining_tasks when skipping (required by remaining_tasks_state_consistency constraint)
+    remaining_tasks = CASE
+                      WHEN (select is_exhausted from task_status) AND (select when_failed_mode from task_status) IN ('skip', 'skip-cascade') THEN NULL
+                      ELSE pgflow.step_states.remaining_tasks
+                      END
+  FROM fail_or_retry_task
+  WHERE pgflow.step_states.run_id = fail_task.run_id
+    AND pgflow.step_states.step_slug = fail_task.step_slug
+  RETURNING pgflow.step_states.*
+)
+-- Update run status: only fail when when_failed='fail' and step was failed
+UPDATE pgflow.runs
+SET status = CASE
+              WHEN (select status from maybe_fail_step) = 'failed' THEN 'failed'
+              ELSE status
+              END,
+    failed_at = CASE
+                WHEN (select status from maybe_fail_step) = 'failed' THEN now()
+                ELSE NULL
+                END,
+    -- Decrement remaining_steps when step was skipped (not failed, run continues)
+    remaining_steps = CASE
+                      WHEN (select status from maybe_fail_step) = 'skipped' THEN pgflow.runs.remaining_steps - 1
+                      ELSE pgflow.runs.remaining_steps
+                      END
+WHERE pgflow.runs.run_id = fail_task.run_id
+RETURNING (status = 'failed') INTO v_run_failed;
+
+-- Capture when_failed mode and check if step was skipped for later processing
+SELECT s.when_failed INTO v_when_failed
+FROM pgflow.steps s
+JOIN pgflow.runs r ON r.flow_slug = s.flow_slug
+WHERE r.run_id = fail_task.run_id
+  AND s.step_slug = fail_task.step_slug;
+
+SELECT (status = 'skipped') INTO v_step_skipped
+FROM pgflow.step_states
+WHERE pgflow.step_states.run_id = fail_task.run_id
+  AND pgflow.step_states.step_slug = fail_task.step_slug;
+
+-- Check if step failed by querying the step_states table
+SELECT (status = 'failed') INTO v_step_failed 
+FROM pgflow.step_states 
+WHERE pgflow.step_states.run_id = fail_task.run_id 
+  AND pgflow.step_states.step_slug = fail_task.step_slug;
+
+-- Send broadcast event for step failure if the step was failed
+IF v_step_failed THEN
+  PERFORM realtime.send(
+    jsonb_build_object(
+      'event_type', 'step:failed',
+      'run_id', fail_task.run_id,
+      'step_slug', fail_task.step_slug,
+      'status', 'failed',
+      'error_message', fail_task.error_message,
+      'failed_at', now()
+    ),
+    concat('step:', fail_task.step_slug, ':failed'),
+    concat('pgflow:run:', fail_task.run_id),
+    false
+  );
+END IF;
+
+-- Handle step skipping (when_failed = 'skip' or 'skip-cascade')
+IF v_step_skipped THEN
+  -- Send broadcast event for step skipped
+  PERFORM realtime.send(
+    jsonb_build_object(
+      'event_type', 'step:skipped',
+      'run_id', fail_task.run_id,
+      'step_slug', fail_task.step_slug,
+      'status', 'skipped',
+      'skip_reason', 'handler_failed',
+      'error_message', fail_task.error_message,
+      'skipped_at', now()
+    ),
+    concat('step:', fail_task.step_slug, ':skipped'),
+    concat('pgflow:run:', fail_task.run_id),
+    false
+  );
+
+  -- For skip-cascade: cascade skip to all downstream dependents
+  IF v_when_failed = 'skip-cascade' THEN
+    PERFORM pgflow._cascade_force_skip_steps(fail_task.run_id, fail_task.step_slug, 'handler_failed');
+  END IF;
+
+  -- Try to complete the run (remaining_steps may now be 0)
+  PERFORM pgflow.maybe_complete_run(fail_task.run_id);
+END IF;
+
+-- Send broadcast event for run failure if the run was failed
+IF v_run_failed THEN
+  DECLARE
+    v_flow_slug text;
+  BEGIN
+    SELECT flow_slug INTO v_flow_slug FROM pgflow.runs WHERE pgflow.runs.run_id = fail_task.run_id;
+
+    PERFORM realtime.send(
+      jsonb_build_object(
+        'event_type', 'run:failed',
+        'run_id', fail_task.run_id,
+        'flow_slug', v_flow_slug,
+        'status', 'failed',
+        'error_message', fail_task.error_message,
+        'failed_at', now()
+      ),
+      'run:failed',
+      concat('pgflow:run:', fail_task.run_id),
+      false
+    );
+  END;
+END IF;
+
+-- Archive all active messages (both queued and started) when run fails
+IF v_run_failed THEN
+  PERFORM pgmq.archive(r.flow_slug, ARRAY_AGG(st.message_id))
+  FROM pgflow.step_tasks st
+  JOIN pgflow.runs r ON st.run_id = r.run_id
+  WHERE st.run_id = fail_task.run_id
+    AND st.status IN ('queued', 'started')
+    AND st.message_id IS NOT NULL
+  GROUP BY r.flow_slug
+  HAVING COUNT(st.message_id) > 0;
+END IF;
+
+-- For queued tasks: delay the message for retry with exponential backoff
+PERFORM (
+  WITH retry_config AS (
+    SELECT
+      COALESCE(s.opt_base_delay, f.opt_base_delay) AS base_delay
+    FROM pgflow.steps s
+    JOIN pgflow.flows f ON f.flow_slug = s.flow_slug
+    JOIN pgflow.runs r ON r.flow_slug = f.flow_slug
+    WHERE r.run_id = fail_task.run_id
+      AND s.step_slug = fail_task.step_slug
+  ),
+  queued_tasks AS (
+    SELECT
+      r.flow_slug,
+      st.message_id,
+      pgflow.calculate_retry_delay((SELECT base_delay FROM retry_config), st.attempts_count) AS calculated_delay
+    FROM pgflow.step_tasks st
+    JOIN pgflow.runs r ON st.run_id = r.run_id
+    WHERE st.run_id = fail_task.run_id
+      AND st.step_slug = fail_task.step_slug
+      AND st.task_index = fail_task.task_index
+      AND st.status = 'queued'
+  )
+  SELECT pgmq.set_vt(qt.flow_slug, qt.message_id, qt.calculated_delay)
+  FROM queued_tasks qt
+  WHERE EXISTS (SELECT 1 FROM queued_tasks)
+);
+
+-- For failed tasks: archive the message
+PERFORM pgmq.archive(r.flow_slug, ARRAY_AGG(st.message_id))
+FROM pgflow.step_tasks st
+JOIN pgflow.runs r ON st.run_id = r.run_id
+WHERE st.run_id = fail_task.run_id
+  AND st.step_slug = fail_task.step_slug
+  AND st.task_index = fail_task.task_index
+  AND st.status = 'failed'
+  AND st.message_id IS NOT NULL
+GROUP BY r.flow_slug
+HAVING COUNT(st.message_id) > 0;
+
+return query select *
+from pgflow.step_tasks st
+where st.run_id = fail_task.run_id
+  and st.step_slug = fail_task.step_slug
+  and st.task_index = fail_task.task_index;
+
+end;
+$$;
+-- Modify "start_flow" function
+CREATE OR REPLACE FUNCTION "pgflow"."start_flow" ("flow_slug" text, "input" jsonb, "run_id" uuid DEFAULT NULL::uuid) RETURNS SETOF "pgflow"."runs" LANGUAGE plpgsql SET "search_path" = '' AS $$
+declare
+  v_created_run pgflow.runs%ROWTYPE;
+  v_root_map_count int;
+begin
+
+-- ==========================================
+-- VALIDATION: Root map array input
+-- ==========================================
+WITH root_maps AS (
+  SELECT step_slug
+  FROM pgflow.steps
+  WHERE steps.flow_slug = start_flow.flow_slug
+    AND steps.step_type = 'map'
+    AND steps.deps_count = 0
+)
+SELECT COUNT(*) INTO v_root_map_count FROM root_maps;
+
+-- If we have root map steps, validate that input is an array
+IF v_root_map_count > 0 THEN
+  -- First check for NULL (should be caught by NOT NULL constraint, but be defensive)
+  IF start_flow.input IS NULL THEN
+    RAISE EXCEPTION 'Flow % has root map steps but input is NULL', start_flow.flow_slug;
+  END IF;
+  
+  -- Then check if it's not an array
+  IF jsonb_typeof(start_flow.input) != 'array' THEN
+    RAISE EXCEPTION 'Flow % has root map steps but input is not an array (got %)', 
+      start_flow.flow_slug, jsonb_typeof(start_flow.input);
+  END IF;
+END IF;
+
+-- ==========================================
+-- MAIN CTE CHAIN: Create run and step states
+-- ==========================================
+WITH
+  -- ---------- Gather flow metadata ----------
+  flow_steps AS (
+    SELECT steps.flow_slug, steps.step_slug, steps.step_type, steps.deps_count
+    FROM pgflow.steps
+    WHERE steps.flow_slug = start_flow.flow_slug
+  ),
+  -- ---------- Create run record ----------
+  created_run AS (
+    INSERT INTO pgflow.runs (run_id, flow_slug, input, remaining_steps)
+    VALUES (
+      COALESCE(start_flow.run_id, gen_random_uuid()),
+      start_flow.flow_slug,
+      start_flow.input,
+      (SELECT count(*) FROM flow_steps)
+    )
+    RETURNING *
+  ),
+  -- ---------- Create step states ----------
+  -- Sets initial_tasks: known for root maps, NULL for dependent maps
+  created_step_states AS (
+    INSERT INTO pgflow.step_states (flow_slug, run_id, step_slug, remaining_deps, initial_tasks)
+    SELECT
+      fs.flow_slug,
+      (SELECT created_run.run_id FROM created_run),
+      fs.step_slug,
+      fs.deps_count,
+      -- Updated logic for initial_tasks:
+      CASE
+        WHEN fs.step_type = 'map' AND fs.deps_count = 0 THEN
+          -- Root map: get array length from input
+          CASE
+            WHEN jsonb_typeof(start_flow.input) = 'array' THEN
+              jsonb_array_length(start_flow.input)
+            ELSE
+              1
+          END
+        WHEN fs.step_type = 'map' AND fs.deps_count > 0 THEN
+          -- Dependent map: unknown until dependencies complete
+          NULL
+        ELSE
+          -- Single steps: always 1 task
+          1
+      END
+    FROM flow_steps fs
+  )
+SELECT * FROM created_run INTO v_created_run;
+
+-- ==========================================
+-- POST-CREATION ACTIONS
+-- ==========================================
+
+-- ---------- Broadcast run:started event ----------
+PERFORM realtime.send(
+  jsonb_build_object(
+    'event_type', 'run:started',
+    'run_id', v_created_run.run_id,
+    'flow_slug', v_created_run.flow_slug,
+    'input', v_created_run.input,
+    'status', 'started',
+    'remaining_steps', v_created_run.remaining_steps,
+    'started_at', v_created_run.started_at
+  ),
+  'run:started',
+  concat('pgflow:run:', v_created_run.run_id),
+  false
+);
+
+-- ---------- Evaluate conditions on ready steps ----------
+-- Skip steps with unmet conditions, propagate to dependents
+IF NOT pgflow.cascade_resolve_conditions(v_created_run.run_id) THEN
+  -- Run was failed due to a condition with when_unmet='fail'
+  RETURN QUERY SELECT * FROM pgflow.runs where pgflow.runs.run_id = v_created_run.run_id;
+  RETURN;
+END IF;
+
+-- ---------- Complete taskless steps ----------
+-- Handle empty array maps that should auto-complete
+PERFORM pgflow.cascade_complete_taskless_steps(v_created_run.run_id);
+
+-- ---------- Start initial steps ----------
+-- Start root steps (those with no dependencies)
+PERFORM pgflow.start_ready_steps(v_created_run.run_id);
+
+-- ---------- Check for run completion ----------
+-- If cascade completed all steps (zero-task flows), finalize the run
+PERFORM pgflow.maybe_complete_run(v_created_run.run_id);
+
+RETURN QUERY SELECT * FROM pgflow.runs where pgflow.runs.run_id = v_created_run.run_id;
+
+end;
+$$;
+-- Modify "start_tasks" function
+CREATE OR REPLACE FUNCTION "pgflow"."start_tasks" ("flow_slug" text, "msg_ids" bigint[], "worker_id" uuid) RETURNS SETOF "pgflow"."step_task_record" LANGUAGE sql SET "search_path" = '' AS $$
+with tasks as (
+    select
+      task.flow_slug,
+      task.run_id,
+      task.step_slug,
+      task.task_index,
+      task.message_id
+    from pgflow.step_tasks as task
+    join pgflow.runs r on r.run_id = task.run_id
+    where task.flow_slug = start_tasks.flow_slug
+      and task.message_id = any(msg_ids)
+      and task.status = 'queued'
+      -- MVP: Don't start tasks on failed runs
+      and r.status != 'failed'
+  ),
+  start_tasks_update as (
+    update pgflow.step_tasks
+    set
+      attempts_count = attempts_count + 1,
+      status = 'started',
+      started_at = now(),
+      last_worker_id = worker_id
+    from tasks
+    where step_tasks.message_id = tasks.message_id
+      and step_tasks.flow_slug = tasks.flow_slug
+      and step_tasks.status = 'queued'
+  ),
+  runs as (
+    select
+      r.run_id,
+      r.input
+    from pgflow.runs r
+    where r.run_id in (select run_id from tasks)
+  ),
+  deps as (
+    select
+      st.run_id,
+      st.step_slug,
+      dep.dep_slug,
+      -- Read output directly from step_states (already aggregated by writers)
+      dep_state.output as dep_output
+    from tasks st
+    join pgflow.deps dep on dep.flow_slug = st.flow_slug and dep.step_slug = st.step_slug
+    join pgflow.step_states dep_state on
+      dep_state.run_id = st.run_id and
+      dep_state.step_slug = dep.dep_slug and
+      dep_state.status = 'completed'  -- Only include completed deps (not skipped)
+  ),
+  deps_outputs as (
+    select
+      d.run_id,
+      d.step_slug,
+      jsonb_object_agg(d.dep_slug, d.dep_output) as deps_output,
+      count(*) as dep_count
+    from deps d
+    group by d.run_id, d.step_slug
+  ),
+  timeouts as (
+    select
+      task.message_id,
+      task.flow_slug,
+      coalesce(step.opt_timeout, flow.opt_timeout) + 2 as vt_delay
+    from tasks task
+    join pgflow.flows flow on flow.flow_slug = task.flow_slug
+    join pgflow.steps step on step.flow_slug = task.flow_slug and step.step_slug = task.step_slug
+  ),
+  -- Batch update visibility timeouts for all messages
+  set_vt_batch as (
+    select pgflow.set_vt_batch(
+      start_tasks.flow_slug,
+      array_agg(t.message_id order by t.message_id),
+      array_agg(t.vt_delay order by t.message_id)
+    )
+    from timeouts t
+  )
+  select
+    st.flow_slug,
+    st.run_id,
+    st.step_slug,
+    -- ==========================================
+    -- INPUT CONSTRUCTION LOGIC
+    -- ==========================================
+    -- This nested CASE statement determines how to construct the input
+    -- for each task based on the step type (map vs non-map).
+    --
+    -- The fundamental difference:
+    -- - Map steps: Receive RAW array elements (e.g., just 42 or "hello")
+    -- - Non-map steps: Receive structured objects with named keys
+    --                  (e.g., {"run": {...}, "dependency1": {...}})
+    -- ==========================================
+    CASE
+      -- -------------------- MAP STEPS --------------------
+      -- Map steps process arrays element-by-element.
+      -- Each task receives ONE element from the array at its task_index position.
+      WHEN step.step_type = 'map' THEN
+        -- Map steps get raw array elements without any wrapper object
+        CASE
+          -- ROOT MAP: Gets array from run input
+          -- Example: run input = [1, 2, 3]
+          --          task 0 gets: 1
+          --          task 1 gets: 2
+          --          task 2 gets: 3
+          WHEN step.deps_count = 0 THEN
+            -- Root map (deps_count = 0): no dependencies, reads from run input.
+            -- Extract the element at task_index from the run's input array.
+            -- Note: If run input is not an array, this will return NULL
+            -- and the flow will fail (validated in start_flow).
+            jsonb_array_element(r.input, st.task_index)
+
+          -- DEPENDENT MAP: Gets array from its single dependency
+          -- Example: dependency output = ["a", "b", "c"]
+          --          task 0 gets: "a"
+          --          task 1 gets: "b"
+          --          task 2 gets: "c"
+          ELSE
+            -- Has dependencies (should be exactly 1 for map steps).
+            -- Extract the element at task_index from the dependency's output array.
+            --
+            -- Why the subquery with jsonb_each?
+            -- - The dependency outputs a raw array: [1, 2, 3]
+            -- - deps_outputs aggregates it into: {"dep_name": [1, 2, 3]}
+            -- - We need to unwrap and get just the array value
+            -- - Map steps have exactly 1 dependency (enforced by add_step)
+            -- - So jsonb_each will return exactly 1 row
+            -- - We extract the 'value' which is the raw array [1, 2, 3]
+            -- - Then get the element at task_index from that array
+            (SELECT jsonb_array_element(value, st.task_index)
+            FROM jsonb_each(dep_out.deps_output)
+            LIMIT 1)
+        END
+
+      -- -------------------- NON-MAP STEPS --------------------
+      -- Regular (non-map) steps receive dependency outputs as a structured object.
+      -- Root steps (no dependencies) get empty object - they access flowInput via context.
+      -- Dependent steps get only their dependency outputs.
+      ELSE
+        -- Non-map steps get structured input with dependency keys only
+        -- Example for dependent step: {
+        --   "step1": {"output": "from_step1"},
+        --   "step2": {"output": "from_step2"}
+        -- }
+        -- Example for root step: {}
+        --
+        -- Note: flow_input is available separately in the returned record
+        -- for workers to access via context.flowInput
+        coalesce(dep_out.deps_output, '{}'::jsonb)
+    END as input,
+    st.message_id as msg_id,
+    st.task_index as task_index,
+    -- flow_input: Original run input for worker context
+    -- Only included for root non-map steps to avoid data duplication.
+    -- Root map steps: flowInput IS the array, useless to include
+    -- Dependent steps: lazy load via ctx.flowInput when needed
+    CASE
+      WHEN step.step_type != 'map' AND step.deps_count = 0
+      THEN r.input
+      ELSE NULL
+    END as flow_input
+  from tasks st
+  join runs r on st.run_id = r.run_id
+  join pgflow.steps step on
+    step.flow_slug = st.flow_slug and
+    step.step_slug = st.step_slug
+  left join deps_outputs dep_out on
+    dep_out.run_id = st.run_id and
+    dep_out.step_slug = st.step_slug
+$$;
+-- Create "add_step" function
+CREATE FUNCTION "pgflow"."add_step" ("flow_slug" text, "step_slug" text, "deps_slugs" text[] DEFAULT '{}', "max_attempts" integer DEFAULT NULL::integer, "base_delay" integer DEFAULT NULL::integer, "timeout" integer DEFAULT NULL::integer, "start_delay" integer DEFAULT NULL::integer, "step_type" text DEFAULT 'single', "condition_pattern" jsonb DEFAULT NULL::jsonb, "condition_not_pattern" jsonb DEFAULT NULL::jsonb, "when_unmet" text DEFAULT 'skip', "when_failed" text DEFAULT 'fail') RETURNS "pgflow"."steps" LANGUAGE plpgsql SET "search_path" = '' AS $$
+DECLARE
+  result_step pgflow.steps;
+  next_idx int;
+BEGIN
+  -- Validate map step constraints
+  -- Map steps can have either:
+  --   0 dependencies (root map - maps over flow input array)
+  --   1 dependency (dependent map - maps over dependency output array)
+  IF COALESCE(add_step.step_type, 'single') = 'map' AND COALESCE(array_length(add_step.deps_slugs, 1), 0) > 1 THEN
+    RAISE EXCEPTION 'Map step "%" can have at most one dependency, but % were provided: %',
+      add_step.step_slug,
+      COALESCE(array_length(add_step.deps_slugs, 1), 0),
+      array_to_string(add_step.deps_slugs, ', ');
+  END IF;
+
+  -- Get next step index
+  SELECT COALESCE(MAX(s.step_index) + 1, 0) INTO next_idx
+  FROM pgflow.steps s
+  WHERE s.flow_slug = add_step.flow_slug;
+
+  -- Create the step
+  INSERT INTO pgflow.steps (
+    flow_slug, step_slug, step_type, step_index, deps_count,
+    opt_max_attempts, opt_base_delay, opt_timeout, opt_start_delay,
+    condition_pattern, condition_not_pattern, when_unmet, when_failed
+  )
+  VALUES (
+    add_step.flow_slug,
+    add_step.step_slug,
+    COALESCE(add_step.step_type, 'single'),
+    next_idx,
+    COALESCE(array_length(add_step.deps_slugs, 1), 0),
+    add_step.max_attempts,
+    add_step.base_delay,
+    add_step.timeout,
+    add_step.start_delay,
+    add_step.condition_pattern,
+    add_step.condition_not_pattern,
+    add_step.when_unmet,
+    add_step.when_failed
+  )
+  ON CONFLICT ON CONSTRAINT steps_pkey
+  DO UPDATE SET step_slug = EXCLUDED.step_slug
+  RETURNING * INTO result_step;
+
+  -- Insert dependencies
+  INSERT INTO pgflow.deps (flow_slug, dep_slug, step_slug)
+  SELECT add_step.flow_slug, d.dep_slug, add_step.step_slug
+  FROM unnest(COALESCE(add_step.deps_slugs, '{}')) AS d(dep_slug)
+  WHERE add_step.deps_slugs IS NOT NULL AND array_length(add_step.deps_slugs, 1) > 0
+  ON CONFLICT ON CONSTRAINT deps_pkey DO NOTHING;
+
+  RETURN result_step;
+END;
+$$;
+-- Drop "add_step" function
+DROP FUNCTION "pgflow"."add_step" (text, text, text[], integer, integer, integer, integer, text);