job-workflow 0.5.0 → 0.6.1

data/app/views/job_workflow/monitoring/executions/show.html.erb

@@ -0,0 +1,200 @@
+<% status_class = case @execution.workflow_status
+                 when :succeeded then "text-bg-success"
+                 when :failed then "text-bg-danger"
+                 when :running then "text-bg-primary"
+                 else "text-bg-secondary"
+                 end %>
+<% dag_layout = @execution.dag_layout %>
+
+<section class="d-flex flex-column flex-lg-row justify-content-between align-items-lg-start gap-3 mb-4">
+  <div>
+    <div class="text-body-secondary small mb-1">Execution</div>
+    <h1 class="display-6 fw-semibold mb-3"><%= @execution.job_class_name %></h1>
+    <div class="d-flex flex-wrap gap-2">
+      <span class="badge <%= status_class %>"><%= @execution.workflow_status %></span>
+      <span class="badge text-bg-light border text-dark">task <%= @execution.current_task_name || "-" %></span>
+      <span class="badge text-bg-light border text-dark">failed <%= @execution.failed_task_name || "-" %></span>
+    </div>
+  </div>
+  <div class="d-flex flex-wrap gap-2">
+    <%= link_to "Back to executions", workflow_executions_path(@workflow.name), class: "btn btn-outline-secondary" %>
+    <% if @execution.mission_control_job_path %>
+      <%= link_to "Mission Control Jobs", @execution.mission_control_job_path, class: "btn btn-primary" %>
+    <% end %>
+  </div>
+</section>
+
+<div class="row g-4 mb-4">
+  <div class="col-12 col-xl-4">
+    <div class="card jw-card h-100">
+      <div class="card-header bg-white fw-semibold">Execution Summary</div>
+      <div class="card-body">
+        <dl class="row mb-0">
+          <dt class="col-sm-4">Job ID</dt>
+          <dd class="col-sm-8 jw-mono"><%= @execution.job_id %></dd>
+          <dt class="col-sm-4">Queue</dt>
+          <dd class="col-sm-8"><%= @execution.queue_name || "-" %></dd>
+          <dt class="col-sm-4">Current</dt>
+          <dd class="col-sm-8"><%= @execution.current_task_name || "-" %></dd>
+          <dt class="col-sm-4">Failed</dt>
+          <dd class="col-sm-8"><%= @execution.failed_task_name || "-" %></dd>
+        </dl>
+      </div>
+    </div>
+  </div>
+
+  <div class="col-12 col-xl-8">
+    <div class="card jw-card h-100">
+      <div class="card-header bg-white fw-semibold">Arguments</div>
+      <div class="card-body">
+        <pre class="jw-pre"><%= JSON.pretty_generate(@execution.filtered_arguments.as_json) %></pre>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="card jw-card">
+  <div class="card-header bg-white fw-semibold">DAG</div>
+  <% if dag_layout[:nodes].any? %>
+    <div class="card-body border-bottom" aria-hidden="true">
+      <div class="small text-body-secondary mb-3">graph overview</div>
+      <div class="jw-dag-viewport">
+        <div
+          class="jw-dag-canvas"
+          style="width: <%= dag_layout[:width] %>px; height: <%= dag_layout[:height] %>px;"
+        >
+          <svg
+            class="jw-dag-svg"
+            viewBox="0 0 <%= dag_layout[:width] %> <%= dag_layout[:height] %>"
+            preserveAspectRatio="xMinYMin meet"
+          >
+            <% dag_layout[:edges].each do |edge| %>
+              <path class="jw-dag-edge" d="<%= edge[:path] %>"></path>
+            <% end %>
+          </svg>
+
+          <% dag_layout[:nodes].each do |task| %>
+            <% graph_status_class = case task[:status]
+                                   when :succeeded then "text-bg-success"
+                                   when :failed then "text-bg-danger"
+                                   when :running then "text-bg-primary"
+                                   else "text-bg-secondary"
+                                   end %>
+            <div
+              class="jw-dag-node"
+              style="left: <%= task[:x] %>px; top: <%= task[:y] %>px; width: <%= task[:width] %>px; height: <%= task[:height] %>px;"
+            >
+              <div class="d-flex flex-column align-items-start gap-1">
+                <div class="fw-semibold jw-dag-node-title" title="<%= task[:label] %>"><%= task[:truncated_label] %></div>
+                <span class="badge <%= graph_status_class %>"><%= task[:status] %></span>
+              </div>
+
+              <% if task[:meta_label] %>
+                <div class="jw-dag-node-meta"><%= task[:meta_label] %></div>
+              <% end %>
+            </div>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  <% end %>
+  <div class="list-group list-group-flush">
+    <% @execution.tasks.each do |task| %>
+      <% task_status_class = case task[:status]
+                            when :succeeded then "text-bg-success"
+                            when :failed then "text-bg-danger"
+                            when :running then "text-bg-primary"
+                            else "text-bg-secondary"
+                            end %>
+      <div class="list-group-item p-4">
+        <div class="d-flex flex-column flex-lg-row justify-content-between gap-3">
+          <div>
+            <div class="d-flex flex-wrap align-items-center gap-2 mb-2">
+              <span class="fw-semibold"><%= task[:name] %></span>
+              <span class="badge <%= task_status_class %>"><%= task[:status] %></span>
+              <% if task[:each] %>
+                <span class="badge text-bg-light border text-dark">
+                  each <%= task[:each_progress][:succeeded] %>/<%= task[:each_progress][:total] %>
+                </span>
+              <% end %>
+            </div>
+            <% if task[:depends_on].any? %>
+              <div class="text-body-secondary small">depends on <%= task[:depends_on].join(", ") %></div>
+            <% end %>
+          </div>
+
+          <% if task[:each] %>
+            <div class="text-lg-end">
+              <div class="small text-body-secondary mb-1">fan-out progress</div>
+              <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="<%= task[:each_progress][:total] %>" aria-valuenow="<%= task[:each_progress][:succeeded] %>">
+                <div
+                  class="progress-bar"
+                  style="width: <%= task[:each_progress][:total].positive? ? (task[:each_progress][:succeeded] * 100 / task[:each_progress][:total]) : 0 %>%"
+                ></div>
+              </div>
+            </div>
+          <% end %>
+        </div>
+
+        <div class="row g-3 mt-1">
+          <div class="col-12 col-xl-6">
+            <div class="small text-body-secondary mb-2">configuration</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:configuration].as_json) %></pre>
+          </div>
+
+          <div class="col-12 col-xl-6">
+            <div class="small text-body-secondary mb-2">progress</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:each_progress].as_json) %></pre>
+          </div>
+        </div>
+
+        <% if task[:outputs].any? %>
+          <div class="mt-3">
+            <div class="small text-body-secondary mb-2">outputs</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:outputs].as_json) %></pre>
+          </div>
+        <% end %>
+
+        <% if Array(task[:sub_task_jobs]).any? %>
+          <div class="mt-3">
+            <div class="small text-body-secondary mb-2">sub task jobs</div>
+            <div class="table-responsive">
+              <table class="table table-sm align-middle mb-0">
+                <thead>
+                  <tr>
+                    <th>Each</th>
+                    <th>Status</th>
+                    <th>Job ID</th>
+                    <th class="text-end">Mission Control</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <% Array(task[:sub_task_jobs]).each do |sub_task_job| %>
+                    <% sub_task_status_class = case sub_task_job[:status]
+                                              when :succeeded then "text-bg-success"
+                                              when :failed then "text-bg-danger"
+                                              when :running then "text-bg-primary"
+                                              else "text-bg-secondary"
+                                              end %>
+                    <tr>
+                      <td><%= sub_task_job[:each_index] %></td>
+                      <td><span class="badge <%= sub_task_status_class %>"><%= sub_task_job[:status] %></span></td>
+                      <td class="jw-mono"><%= sub_task_job[:job_id] %></td>
+                      <td class="text-end">
+                        <% if sub_task_job[:mission_control_job_path] %>
+                          <%= link_to "Open", sub_task_job[:mission_control_job_path], class: "btn btn-sm btn-outline-primary" %>
+                        <% else %>
+                          <span class="text-body-secondary">-</span>
+                        <% end %>
+                      </td>
+                    </tr>
+                  <% end %>
+                </tbody>
+              </table>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/job_workflow/monitoring/workflows/index.html.erb

@@ -0,0 +1,39 @@
+<section class="mb-4">
+  <h1 class="display-6 fw-semibold mb-2">Workflow Definitions</h1>
+  <p class="text-body-secondary mb-0">Root execution only. Select one workflow, then drill into its executions.</p>
+</section>
+
+<div class="card jw-card">
+  <div class="card-body p-0">
+    <% if @workflows.empty? %>
+      <div class="p-4 text-body-secondary">No workflows are registered.</div>
+    <% else %>
+      <div class="table-responsive">
+        <table class="table table-hover align-middle mb-0">
+          <thead class="table-light">
+            <tr>
+              <th class="ps-4">Workflow</th>
+              <th>Tasks</th>
+              <th class="text-end pe-4">Executions</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @workflows.each do |workflow| %>
+              <tr>
+                <td class="ps-4">
+                  <div class="fw-semibold"><%= workflow.job_class_name %></div>
+                </td>
+                <td>
+                  <span class="badge text-bg-secondary"><%= workflow.task_count %> tasks</span>
+                </td>
+                <td class="text-end pe-4">
+                  <%= link_to "View executions", workflow_executions_path(workflow.job_class_name), class: "btn btn-sm btn-primary" %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/layouts/job_workflow/monitoring/application.html.erb

@@ -0,0 +1,117 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>JobWorkflow Monitoring</title>
+    <link
+      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
+      rel="stylesheet"
+      integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB"
+      crossorigin="anonymous"
+    >
+    <style>
+      :root {
+        --jw-surface: #f8f9fa;
+        --jw-border: #dee2e6;
+      }
+
+      body {
+        background:
+          radial-gradient(circle at top right, rgba(13, 110, 253, 0.08), transparent 24rem),
+          linear-gradient(180deg, #f8fbff 0%, #f8f9fa 100%);
+      }
+
+      .jw-shell {
+        max-width: 1200px;
+      }
+
+      .jw-mono {
+        font-family: ui-monospace, SFMono-Regular, SFMono-Regular, Menlo, Consolas, monospace;
+        word-break: break-all;
+      }
+
+      .jw-pre {
+        background: #212529;
+        color: #f8f9fa;
+        border-radius: 0.75rem;
+        padding: 1rem;
+        margin: 0;
+        white-space: pre-wrap;
+      }
+
+      .jw-card {
+        border-color: var(--jw-border);
+        box-shadow: 0 0.5rem 1.5rem rgba(33, 37, 41, 0.06);
+      }
+
+      .jw-dag-viewport {
+        overflow-x: auto;
+        padding-bottom: 0.25rem;
+      }
+
+      .jw-dag-canvas {
+        position: relative;
+        min-height: 12rem;
+      }
+
+      .jw-dag-svg {
+        position: absolute;
+        inset: 0;
+        overflow: visible;
+      }
+
+      .jw-dag-edge {
+        fill: none;
+        stroke: #adb5bd;
+        stroke-width: 2;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+      }
+
+      .jw-dag-node {
+        position: absolute;
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-start;
+        gap: 0.4rem;
+        background: #fff;
+        border: 1px solid var(--jw-border);
+        border-radius: 0.85rem;
+        box-shadow: 0 0.4rem 1rem rgba(33, 37, 41, 0.08);
+        padding: 0.75rem 0.875rem;
+      }
+
+      .jw-dag-node-title {
+        font-size: 0.875rem;
+        line-height: 1.15;
+        max-width: 10rem;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .jw-dag-node-meta {
+        color: #6c757d;
+        font-size: 0.72rem;
+      }
+    </style>
+  </head>
+  <body>
+    <nav class="navbar navbar-expand-lg bg-white border-bottom sticky-top">
+      <div class="container-fluid jw-shell px-3 px-lg-4">
+        <a class="navbar-brand fw-semibold" href="<%= root_path %>">JobWorkflow Monitoring</a>
+      </div>
+    </nav>
+
+    <main class="container-fluid jw-shell py-4 py-lg-5 px-3 px-lg-4">
+      <%= yield %>
+    </main>
+
+    <script
+      src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"
+      integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI"
+      crossorigin="anonymous"
+    ></script>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+JobWorkflow::Monitoring::Engine.routes.draw do
+  resources :workflows, only: [:index], param: :job_class_name do
+    resources :executions, only: %i[index show]
+  end
+  root "workflows#index"
+end

data/guides/API_REFERENCE.md

@@ -18,10 +18,9 @@ task(name, **options, &block)
   - `depends_on` (Symbol | Array[Symbol]): Dependent tasks
   - `each` (Proc): Proc that returns an enumerable for map task execution
   - `enqueue` (Hash | Proc | bool): Controls whether task iterations are enqueued as sub-jobs
-    - Hash format (recommended): `{ condition: Proc, queue: String, concurrency: Integer }`
+    - Hash format (recommended): `{ condition: Proc, queue: String }`
       - `condition` (Proc | bool): Determines if task should be enqueued (default: true if Hash is not empty)
       - `queue` (String): Custom queue name for the task (optional)
-      - `concurrency` (Integer): Concurrency limit for parallel processing (default: unlimited)
     - Proc format (legacy): Proc that returns boolean
     - bool format: true/false for simple cases
     - Default: nil (synchronous execution)
@@ -75,7 +74,8 @@ end
 # Parallel processing with collection
 task :process_items,
      each: ->(ctx) { ctx.arguments.items },
-     enqueue: { concurrency: 5 },
+     enqueue: true,
+     throttle: 5,
      output: { result: "String" } do |ctx|
   item = ctx.each_value
   { result: ProcessService.handle(item) }
@@ -187,7 +187,8 @@ class ImportJob < ApplicationJob
 
   task :process,
        each: ->(ctx) { ctx.arguments.items },
-       enqueue: { concurrency: 5 },
+       enqueue: true,
+       throttle: 5,
        output: { result: "String" } do |ctx|
     { result: handle(ctx.each_value) }
   end
@@ -211,7 +212,8 @@ class BatchImportJob < ApplicationJob
 
   task :process,
        each: ->(ctx) { ctx.arguments.items },
-       enqueue: { concurrency: 5 },
+       enqueue: true,
+       throttle: 5,
        output: { result: "String" } do |ctx|
     { result: handle(ctx.each_value) }
   end
@@ -228,7 +230,8 @@ argument :items, "Array[String]"
 
 task :process_items,
      each: ->(ctx) { ctx.arguments.items },
-     enqueue: { concurrency: 5 },
+     enqueue: true,
+     throttle: 5,
      output: { result: "String", status: "Symbol" } do |ctx|
   item = ctx.each_value
   {

data/guides/DEPENDENCY_WAIT.md

@@ -14,7 +14,8 @@ class ExampleJob < ApplicationJob
 
   task :process_items,
        each: ->(ctx) { ctx.arguments.items },
-       enqueue: { concurrency: 5 },
+       enqueue: true,
+       throttle: 5,
        output: { result: "Integer" } do |ctx|
     # This creates many sub-jobs
     { result: ctx.each_value * 2 }
@@ -172,7 +173,8 @@ class DataPipelineJob < ApplicationJob
   # Extract data from multiple sources in parallel
   task :extract_data,
        each: ->(ctx) { %w[users orders products inventory] },
-       enqueue: { concurrency: 4 },
+       enqueue: true,
+       throttle: 4,
        output: { source: "String", count: "Integer" } do |ctx|
     source = ctx.each_value
     data = DataSource.fetch(source, date: ctx.arguments.date)
@@ -210,10 +212,11 @@ class APIAggregatorJob < ApplicationJob
 
   argument :user_ids, "Array[Integer]"
 
-  # Fetch user data with rate limiting
+  # Fetch user data with rate limiting.
+  # Async fan-out is unbounded here; the official execution cap is throttle: 5.
   task :fetch_users,
        each: ->(ctx) { ctx.arguments.user_ids },
-       enqueue: { concurrency: 10 },
+       enqueue: true,
        throttle: { key: "external_api", limit: 5 },
        output: { user_id: "Integer", data: "Hash" } do |ctx|
     user_id = ctx.each_value
@@ -270,7 +273,8 @@ dependency_wait: { poll_timeout: 60, reschedule_delay: 10 }
 # ✅ Good: dependency_wait with parallel sub-jobs
 task :process,
      each: ->(ctx) { ctx.arguments.items },
-     enqueue: { concurrency: 10 } do |ctx|
+     enqueue: true,
+     throttle: 10 do |ctx|
   heavy_process(ctx.each_value)
 end
 

data/guides/MONITORING_UI.md

@@ -0,0 +1,74 @@
+# Monitoring UI
+
+## Overview
+
+JobWorkflow ships with a workflow-oriented monitoring UI. Instead of listing mixed job rows first, the UI starts
+from workflow definitions, then lets you drill into one workflow's root executions and finally into one execution's
+DAG state.
+
+This view is intended to answer workflow-level questions such as:
+
+- which workflow is currently stuck
+- which task is running or failed
+- how `each` fan-out is progressing
+- which arguments and outputs shaped the current execution
+
+## What the UI shows
+
+The current scope includes:
+
+- workflow definition list
+- paginated root execution list per workflow
+- execution detail with a DAG overview, task state, arguments, outputs, and failed task
+- fan-out progress and sub-task job links into Mission Control Jobs
+
+History analytics, retries, and dry-run launch flows are out of scope for now.
+
+## Navigation
+
+The UI is organized around workflows rather than a cross-workflow execution feed:
+
+```text
+workflow definitions
+  └─ one workflow's root executions
+       └─ one root execution with sub-task-job detail
+```
+
+The UI is intentionally scoped to one workflow at a time, so the first screen stays focused on definitions and the
+execution list stays easy to scan.
+
+## Mounting the engine
+
+Add the engine to your application's routes:
+
+```ruby
+# config/routes.rb
+mount JobWorkflow::Monitoring::Engine => "/job_workflow"
+```
+
+After mounting, open `/job_workflow` to browse workflow definitions and executions.
+
+## Authentication and controller inheritance
+
+By default, monitoring controllers inherit from `ApplicationController`. If you already use a dedicated authenticated
+controller for admin tooling, configure monitoring to inherit from it:
+
+```ruby
+config.job_workflow.monitoring.base_controller_class = "AdminController"
+```
+
+If `config.job_workflow.monitoring.base_controller_class` is not set and `MissionControl::Jobs` is installed,
+monitoring falls back to `MissionControl::Jobs.base_controller_class`.
+
+## Root executions and sub-task jobs
+
+Execution lists show **root jobs only**. `SubTaskJob` rows do not appear in the workflow execution list. Instead, the
+detail page shows sub-task job state only after you open one root execution.
+
+This keeps the list view focused on workflow-level monitoring while still preserving the full fan-out story on the
+detail page.
+
+## Query behavior
+
+Root executions are paginated with a cursor and scoped by workflow class. As a user, this means the execution list is
+ordered newest-first within the workflow you selected, without mixing in unrelated job rows.

data/guides/PARALLEL_PROCESSING.md

@@ -54,9 +54,9 @@ task :process_items,
 end
 ```
 
-### Asynchronous Execution with Concurrency
+### Asynchronous Execution with Throttled Concurrency
 
-To execute map task iterations in separate sub-jobs with concurrency control, use the `enqueue:` option with a Hash containing `condition:` and `concurrency:`:
+To execute map task iterations in separate sub-jobs, enable `enqueue:` and use `throttle:` when you need to cap concurrent execution:
 
 ```ruby
 # Simplest form: enable parallel execution with default settings
@@ -69,21 +69,23 @@ end
 # Process up to 10 items concurrently in sub-jobs
 task :process_items,
      each: ->(ctx) { ctx.arguments.items },
-     enqueue: { condition: ->(_ctx) { true }, concurrency: 10 } do |ctx|
+     enqueue: true,
+     throttle: 10 do |ctx|
   process_item(ctx.each_value)
 end
 
-# Simplified syntax when condition is implicitly true
+# Conditional enqueue with a concurrency cap
 task :process_items,
      each: ->(ctx) { ctx.arguments.items },
-     enqueue: { concurrency: 10 } do |ctx|
+     enqueue: { condition: ->(ctx) { ctx.arguments.use_async? } },
+     throttle: 10 do |ctx|
   process_item(ctx.each_value)
 end
 
 # When enqueue is enabled:
 # - Each iteration is executed in a separate sub-job
 # - Sub-jobs are created via perform_all_later
-# - Concurrency limit controls how many sub-jobs run in parallel
+# - `throttle` controls how many iterations can execute concurrently
 # - Parent job waits for all sub-jobs to complete before continuing
 # - Outputs from sub-jobs are automatically collected
 ```
@@ -99,14 +101,18 @@ The `enqueue:` option determines how map task iterations are executed:
 
 - **`enqueue: true`**: Each iteration is enqueued as a separate sub-job with default settings
   - Simplest way to enable parallel execution
-  - No concurrency limit (executes as fast as workers allow)
+  - No throttle limit (executes as fast as workers allow)
   - Good for I/O-bound operations with many workers
 
-- **`enqueue: { condition: ->(_ctx) { true }, concurrency: 10 }`**: Each iteration is enqueued as a separate sub-job
-  - Enables true parallel execution across multiple workers
+- **`enqueue: { condition: ... }`**: Each iteration is enqueued as a separate sub-job when the condition passes
   - Better for I/O-bound operations (API calls, database queries)
-  - Can accept dynamic condition: `enqueue: { condition: ->(ctx) { ctx.arguments.use_concurrency? } }`
-  - Supports `queue:` option for custom queue: `enqueue: { queue: "critical", concurrency: 5 }`
+  - Can accept dynamic condition: `enqueue: { condition: ->(ctx) { ctx.arguments.use_async? } }`
+  - Supports `queue:` option for custom queue: `enqueue: { queue: "critical" }`
+
+- **`throttle: 10`**: Limits how many task executions can run concurrently
+  - This is the official way to cap async map task parallelism
+  - It is enforced at perform time via JobWorkflow semaphores
+  - It does not use SolidQueue `ready` / `blocked` dispatch-state controls
 
 **Note**: `enqueue:` works with both regular tasks and map tasks. For map tasks, it enables asynchronous sub-job execution. For regular tasks, it allows conditional enqueueing as a separate job. Legacy syntax (`enqueue: ->(_ctx) { true }` as a Proc) is still supported for backward compatibility.
 
@@ -129,7 +135,8 @@ class ImportJob < ApplicationJob
 
   task :process_items,
        each: ->(ctx) { ctx.arguments.items },
-       enqueue: { concurrency: 5 },
+       enqueue: true,
+       throttle: 5,
        output: { result: "String" } do |ctx|
     { result: process(ctx.each_value) }
   end
@@ -238,7 +245,8 @@ class DataProcessingJob < ApplicationJob
   task :process_by_region,
        each: ->(ctx) { ctx.arguments.regions },
        output: { region: "String", results: "Array[Hash]" },
-       enqueue: { concurrency: 5 } do |ctx|
+       enqueue: true,
+       throttle: 5 do |ctx|
     region = ctx.each_value
     # This will create sub-tasks for each region
     { region: region, results: [] }
@@ -261,7 +269,8 @@ class DataProcessingJob < ApplicationJob
        },
        depends_on: [:process_by_region],
        output: { region: "String", data_type: "String", result: "Hash" },
-       enqueue: { concurrency: 10 } do |ctx|
+       enqueue: true,
+       throttle: 10 do |ctx|
     item = ctx.each_value
     region = item[:region]
     data_type = item[:data_type]
@@ -290,7 +299,7 @@ DataProcessingJob.perform_later(
   regions: ["us-east-1", "us-west-1", "eu-west-1"],
   data_types: ["user", "order", "product"]
 )
-# => 3 regions × 3 data types = 9 parallel iterations (with concurrency limits)
+# => 3 regions × 3 data types = 9 parallel iterations (with throttled concurrency)
 ```
 
 ### Advanced Matrix with Filtering
@@ -318,7 +327,8 @@ task :process_filtered_matrix,
        end
      },
      output: { region: "String", data_type: "String", status: "Symbol" },
-     enqueue: { concurrency: 10 } do |ctx|
+     enqueue: true,
+     throttle: 10 do |ctx|
   combo = ctx.each_value
   region = combo[:region]
   data_type = combo[:data_type]
@@ -335,9 +345,9 @@ end
 
 When implementing matrix processing:
 
-1. **Concurrency Control**: Set appropriate `concurrency:` limits to avoid overwhelming workers
-   - High concurrency (20+): Suitable for I/O-bound operations (API calls, database queries)
-   - Low concurrency (2-5): Better for CPU-bound operations or rate-limited APIs
+1. **Concurrency Control**: Set appropriate `throttle:` limits to avoid overwhelming workers
+   - High throttle (20+): Suitable for I/O-bound operations (API calls, database queries)
+   - Low throttle (2-5): Better for CPU-bound operations or rate-limited APIs
 
 2. **Output Size**: Watch out for large output collections
    - With N×M combinations, the output array will have N×M elements
@@ -348,7 +358,8 @@ When implementing matrix processing:
    task :process_matrix,
         each: ->(_ctx) { combinations },
         timeout: 300.seconds,  # 5 minutes per iteration
-        enqueue: { concurrency: 5 } do |ctx|
+        enqueue: true,
+        throttle: 5 do |ctx|
      # ...
    end
    ```
@@ -358,7 +369,8 @@ When implementing matrix processing:
    task :process_matrix,
         each: ->(_ctx) { combinations },
         retry: { count: 3, strategy: :exponential },
-        enqueue: { concurrency: 5 } do |ctx|
+        enqueue: true,
+        throttle: 5 do |ctx|
      # ...
    end
    ```