durable_flow 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43d876d7d9d09c0c0c883d510fb18634f6a6b7f81445287b1414353294181bd4
-  data.tar.gz: ed01f4612ff81e58afb7cbdbf2a2a8ab8aa236973d5062fca60726d59db25261
+  metadata.gz: 958d0ca64fa3941faa0ac018e61d07dddadf9529e50aeeb5ecf462244cac0586
+  data.tar.gz: 127aa82a9307c5fb3550cba8cbb466160f423d9c594a97a4fde0ad34885e66f5
 SHA512:
-  metadata.gz: 9d24efb9075c6755a7f4cc67408c1c79b42adc1656134d468af2e6a1c7c259707819c6f7771843e145daed37777ead0577e990a048d8940aff2477eadc28df06
-  data.tar.gz: 81ca1ec109939a621565d94bd858dde30091ab87e275263db52bdb6a37ad15b589cfa5606200aab9bbcac1671657bcd2c128f8e0102488597e7a4a388163f222
+  metadata.gz: 7010c414b4529becbcd04338cd6655732f506a892991befd602141466aa43c7764602aa64c093b80263357690b123ff464f3cbc44477814b247166b8318423b8
+  data.tar.gz: 78eadf53c4c16297308f125399c120de4754353ef53334cfba84f383f25daa54e122e1212d816af4eaa7fbdb6d0135ab0de2dd6d8723723a8e1fc822908d4424

data/README.md

@@ -7,17 +7,17 @@ It lets you write long-running business workflows as normal Ruby methods. Side e
 ```ruby
 class WelcomeWorkflow < DurableFlow::Workflow
   def perform(user_id:, trial_id:)
-    user = step(:load_user) { User.find(user_id) }
+    user = step.run(:load_user) { User.find(user_id) }
 
-    step(:send_welcome) { UserMailer.welcome(user).deliver_now }
+    step.run(:send_welcome) { UserMailer.welcome(user).deliver_now }
 
     step.sleep(:trial_delay, 1.day)
 
-    trial = step(:start_trial) { Billing.start_trial!(user, trial_id:) }
+    trial = step.run(:start_trial) { Billing.start_trial!(user, trial_id:) }
 
     event = step.wait_for_event(:trial_confirmed, timeout: 7.days, match: { trial_id: trial.id })
 
-    step(:finalize) { user.update!(onboarded_at: Time.current, confirmed_at: event[:confirmed_at]) }
+    step.run(:finalize) { user.update!(onboarded_at: Time.current, confirmed_at: event[:confirmed_at]) }
   end
 end
 ```
@@ -30,12 +30,16 @@ DurableFlow is alpha software. The API and storage model will likely change as t
 
 ## UI
 
-DurableFlow ships with a small mountable Rails engine for inspecting workflow runs, step timelines, waits, workflow logs, arguments, and errors.
+DurableFlow ships with a small mountable Rails engine for inspecting workflow runs, definition DAGs, step timelines, waits, workflow logs, arguments, and errors.
 
 ![DurableFlow workflow runs index](docs/screenshots/workflow-runs.png)
 
 ![DurableFlow workflow run detail](docs/screenshots/workflow-run-detail.png)
 
+Each run detail links to a definition DAG view that statically analyzes the workflow class and overlays runtime status from that run.
+
+![DurableFlow workflow definition DAG](docs/screenshots/workflow-definition-dag.png)
+
 ## Live Updates
 
 DurableFlow emits committed lifecycle changes for workflow runs, steps, waits, events, and workflow logs. The default broadcaster is a no-op, so live UI is opt-in.
@@ -147,6 +151,8 @@ Verified behavior:
 - Durable sleep through `perform_later(wait_until:)`.
 - Event waits through `Rails.event`.
 - Parent workflows waiting for child workflow completion.
+- Parent workflows choosing whether child failures raise or return completion payloads.
+- Active Job retry/discard handling reflected in workflow and step status.
 - Solid Queue `1.1.2` integration.
 - Database-backed workflow execution leases to prevent concurrent execution of the same run.
 - Opt-in live lifecycle broadcasts through `DurableFlow.live_broadcaster`.
@@ -280,12 +286,14 @@ Wake it with a Rails event:
 Rails.event.notify(:trial_activated, trial_id: trial.id, source: "checkout")
 ```
 
+For a dense API reference optimized for coding agents, see [docs/llm-reference.md](docs/llm-reference.md).
+
 ## Step API
 
 Memoized side-effect step:
 
 ```ruby
-order = step(:create_order) { Order.create!(cart:) }
+order = step.run(:create_order) { Order.create!(cart:) }
 ```
 
 Durable sleep:
@@ -293,6 +301,7 @@ Durable sleep:
 ```ruby
 step.sleep(:retry_tomorrow, 1.day)
 step.sleep(:wait_until_send_at, until: campaign.send_at)
+step.sleep_until(:wait_until_send_at, campaign.send_at)
 ```
 
 Wait for a Rails event:
@@ -307,17 +316,72 @@ Use a different event name than the step name:
 event = step.wait_for_event(:wait_for_charge, event: :stripe_charge_succeeded, match: { charge_id: charge.id })
 ```
 
-Wait for a child workflow:
+Invoke a child workflow and wait for its result:
+
+```ruby
+completion = step.invoke(:send_invoice, SendInvoiceWorkflow, invoice.id, timeout: 1.hour)
+```
+
+If child startup needs custom code, return the enqueued job or run id from a block:
+
+```ruby
+completion = step.invoke(:send_invoice, timeout: 1.hour) do
+  SendInvoiceWorkflow.perform_later(invoice.id, source: "renewal")
+end
+```
+
+Fan out to child workflows and wait for all of them:
+
+```ruby
+completions = step.invoke_each(:send_invoice, invoices, timeout: 1.hour, concurrency: 25) do |invoice|
+  step.workflow(SendInvoiceWorkflow, invoice.id, key: invoice.id)
+end
+```
+
+The block passed to `step.invoke_each` only declares child workflow requests. DurableFlow starts each child inside a named durable step, then waits for matching child completion events. This mirrors Inngest `step.invoke` and Restate workflow calls while keeping Ruby call sites explicit.
+
+For workflows that read better as explicit starts, use the builder form:
+
+```ruby
+completions = step.child_workflows(:send_invoices, timeout: 1.hour) do |children|
+  invoices.each do |invoice|
+    children.workflow(SendInvoiceWorkflow, invoice.id, key: invoice.id)
+  end
+end
+```
+
+If the item itself knows how to start its child workflow, it can provide a stable `workflow_key` and either `perform_later` or `workflow_class` with `workflow_args` / `workflow_kwargs`:
+
+```ruby
+class SendInvoiceRequest
+  def initialize(invoice)
+    @invoice = invoice
+  end
+
+  def workflow_key = @invoice.id
+  def workflow_class = SendInvoiceWorkflow
+  def workflow_args = [ @invoice.id ]
+end
+```
+
+`step.invoke_each` and `step.child_workflows` start every child in the batch before waiting for the first one. Pass `concurrency:` to process requests in fixed-size batches. Child failures raise `DurableFlow::ChildWorkflowFailedError` in the parent workflow.
+
+If a parent should collect child failures and decide what to do, pass `on_failure: :return`:
 
 ```ruby
-child_run_id = step(:start_child) { SendInvoiceWorkflow.perform_later(invoice.id).job_id }
-completion = step.wait_for_workflow(:child_finished, child_run_id, timeout: 1.hour)
+completions = step.invoke_each(:deliver_invoice, invoices, timeout: 1.hour, on_failure: :return) do |invoice|
+  step.workflow(DeliverInvoiceWorkflow, invoice.id, key: invoice.id)
+end
+
+failed = completions.select { |completion| completion.fetch("status") == "failed" }
 ```
 
+The default is `on_failure: :raise`, which fails the parent workflow when a child finishes failed. Returned failure completions include the child run id, status, workflow class, and error fields from the child completion event.
+
 Write structured workflow logs:
 
 ```ruby
-step(:create_refund) do
+step.run(:create_refund) do
   log.info("Creating refund", refund_id: refund.id, amount_cents: refund.amount_cents)
   Refunds.create!(refund)
 end
@@ -349,15 +413,26 @@ end
 Parallel or high-cardinality work: fan out to child workflows.
 
 ```ruby
-child_run_ids = step(:start_children) do
-  account.users.find_each.map { |user| SyncUserWorkflow.perform_later(user.id).job_id }
+step.invoke_each(:sync_user, account.users.to_a, timeout: 30.minutes, concurrency: 25) do |user|
+  step.workflow(SyncUserWorkflow, user.id, key: user.id)
 end
+```
 
-child_run_ids.each do |run_id|
-  step.wait_for_workflow("child-#{run_id}", run_id, timeout: 30.minutes)
-end
+## Definition DAGs
+
+DurableFlow can statically analyze a workflow's `perform` method and produce a conservative definition graph from durable primitives:
+
+```ruby
+graph = DurableFlow::DefinitionAnalyzer.call(IvwDailyDeliveryWorkflow)
+graph.nodes # durable steps, sleeps, waits, calls, fan-out groups
+graph.edges # possible execution order, including branch conditions
+graph.warnings # dynamic Ruby that could not be represented precisely
 ```
 
+The analyzer uses Prism and recognizes calls such as `step.run`, `step.sleep_until`, `step.wait_for_event`, `step.invoke`, and `step.invoke_each`. It does not execute workflow code. Ruby branches become conditional edges, fan-out calls become grouped nodes, and dynamic loops with hidden durable steps are reported as warnings.
+
+Runtime timelines remain the source of truth for a specific run; definition DAGs are the static map.
+
 ## Rules
 
 - Put side effects inside `step` blocks.
@@ -428,7 +503,7 @@ class TrialOnboardingWorkflowTest < ActiveSupport::TestCase
 end
 ```
 
-Useful helpers include `perform_durable_flow_jobs`, `resume_workflows_for`, `travel_to_next_workflow_wake`, `durable_flow_run_for`, `durable_flow_timeline_for`, `assert_workflow_completed`, `assert_workflow_sleeping`, `assert_workflow_waiting_for`, `assert_step_succeeded`, `assert_step_result`, `assert_step_attempts`, `assert_workflow_log`, `assert_step_log`, `capture_durable_flow_changes`, and `assert_durable_flow_change`.
+Useful helpers include `perform_durable_flow_jobs`, `perform_durable_flow_until_idle`, `resume_workflows_for`, `travel_to_next_workflow_wake`, `durable_flow_run_for`, `durable_flow_timeline_for`, `assert_workflow_completed`, `assert_workflow_sleeping`, `assert_workflow_waiting_for`, `assert_workflow_waiting_for_workflow`, `assert_step_succeeded`, `assert_step_result`, `assert_step_attempts`, `assert_workflow_log`, `assert_step_log`, `capture_durable_flow_changes`, and `assert_durable_flow_change`.
 
 Run the suite against the vendored Rails copy:
 
@@ -445,7 +520,7 @@ RAILS_VERSION=8.1.3 mise exec ruby@3.4 -- bundle exec rake test
 Current suite:
 
 ```text
-25 runs, 212 assertions, 0 failures, 0 errors, 0 skips
+49 runs, 346 assertions, 0 failures, 0 errors, 0 skips
 ```
 
 ## Publishing

data/app/controllers/durable_flow/workflow_runs_controller.rb

@@ -5,8 +5,13 @@ module DurableFlow
     layout "durable_flow/application"
 
     helper_method :durable_flow_duration,
+      :durable_flow_definition_class,
+      :durable_flow_definition_graph_layout,
+      :durable_flow_definition_node_status,
+      :durable_flow_definition_short_condition,
       :durable_flow_format_time,
       :durable_flow_json,
+      :durable_flow_node_label,
       :durable_flow_status_class
 
     def index
@@ -20,7 +25,138 @@ module DurableFlow
       @workflow_timeline = @workflow_run.timeline
     end
 
+    def definition
+      @workflow_run = WorkflowRun.find_by!(run_id: params[:run_id])
+      @workflow_class = @workflow_run.workflow_class.safe_constantize
+      @workflow_timeline = @workflow_run.timeline
+      @step_statuses_by_name = @workflow_run.workflow_steps.index_by(&:name).transform_values(&:status)
+
+      if @workflow_class.nil?
+        @definition_error = "Could not constantize #{@workflow_run.workflow_class.inspect}"
+      elsif !(@workflow_class <= DurableFlow::Workflow)
+        @definition_error = "#{@workflow_run.workflow_class} is not a DurableFlow::Workflow"
+      else
+        @definition_graph = DurableFlow::DefinitionAnalyzer.call(@workflow_class)
+      end
+    rescue StandardError => error
+      @definition_error = "#{error.class}: #{error.message}"
+    end
+
     private
+      def durable_flow_definition_node_status(node, statuses_by_name)
+        direct_status = statuses_by_name[node.name]
+        return direct_status if direct_status
+
+        wait_status = statuses_by_name["#{node.name}_wait"]
+        return wait_status if wait_status
+
+        start_status = statuses_by_name["#{node.name}_start"]
+        return durable_flow_child_start_status(start_status) if start_status
+
+        fanout_statuses = statuses_by_name.filter_map do |step_name, status|
+          status if step_name.match?(/\A#{Regexp.escape(node.name)}_.+_(start|wait)\z/)
+        end
+        return "defined" if fanout_statuses.empty?
+
+        durable_flow_aggregate_status(fanout_statuses)
+      end
+
+      def durable_flow_child_start_status(status)
+        status == "succeeded" ? "running" : status
+      end
+
+      def durable_flow_aggregate_status(statuses)
+        return "failed" if statuses.include?("failed")
+        return "waiting" if statuses.include?("waiting")
+        return "sleeping" if statuses.include?("sleeping")
+        return "running" if statuses.any? { |status| %w[pending running retrying ready enqueued].include?(status) }
+        return "succeeded" if statuses.all? { |status| status == "succeeded" }
+
+        "running"
+      end
+
+      def durable_flow_definition_class(node, statuses_by_name)
+        status = durable_flow_definition_node_status(node, statuses_by_name)
+        status == "defined" ? "neutral" : durable_flow_status_class(status)
+      end
+
+      def durable_flow_node_label(type)
+        case type.to_s
+        when "wait_event"
+          "wait event"
+        when "workflow_call"
+          "workflow call"
+        else
+          type.to_s.tr("_", " ")
+        end
+      end
+
+      def durable_flow_definition_short_condition(condition)
+        condition = condition.to_s
+        return condition if condition.length <= 34
+
+        "#{condition.first(31)}…"
+      end
+
+      def durable_flow_definition_graph_layout(graph)
+        nodes = graph.nodes
+        node_width = 300
+        node_height = 76
+        column_gap = 58
+        row_gap = 124
+        padding_x = 56
+        padding_y = 52
+        ranks = durable_flow_definition_node_ranks(graph)
+        nodes_by_rank = nodes.group_by { |node| ranks.fetch(node.id, 0) }
+        max_columns = [ nodes_by_rank.values.map(&:size).max.to_i, 1 ].max
+        width = [ 880, (padding_x * 2) + (max_columns * node_width) + ((max_columns - 1) * column_gap) ].max
+
+        positions = {}
+        nodes_by_rank.keys.sort.each do |rank|
+          ranked_nodes = nodes_by_rank.fetch(rank).sort_by { |node| [ node.source_line || 0, node.id ] }
+          row_width = (ranked_nodes.size * node_width) + ([ ranked_nodes.size - 1, 0 ].max * column_gap)
+          start_x = (width - row_width) / 2
+
+          ranked_nodes.each_with_index do |node, index|
+            positions[node.id] = {
+              x: start_x + (index * (node_width + column_gap)),
+              y: padding_y + (rank * row_gap),
+            }
+          end
+        end
+
+        max_rank = ranks.values.max.to_i
+        {
+          width: width,
+          height: [ (padding_y * 2) + node_height + (max_rank * row_gap), 260 ].max,
+          node_width: node_width,
+          node_height: node_height,
+          positions: positions,
+        }
+      end
+
+      def durable_flow_definition_node_ranks(graph)
+        ranks = graph.nodes.to_h { |node| [ node.id, 0 ] }
+
+        graph.nodes.size.times do
+          changed = false
+
+          graph.edges.each do |edge|
+            next unless ranks.key?(edge.from) && ranks.key?(edge.to)
+
+            next_rank = ranks.fetch(edge.from) + 1
+            if next_rank > ranks.fetch(edge.to)
+              ranks[edge.to] = next_rank
+              changed = true
+            end
+          end
+
+          break unless changed
+        end
+
+        ranks
+      end
+
       def durable_flow_status_class(status)
         case status.to_s
         when "completed", "succeeded", "matched"

data/app/views/durable_flow/workflow_runs/definition.html.erb

@@ -0,0 +1,145 @@
+<div class="df-header">
+  <div>
+    <div class="df-kicker">
+      <%= link_to "Workflow Runs", workflow_runs_path %> /
+      <%= link_to "Run", workflow_run_path(@workflow_run.run_id) %> /
+      Definition DAG
+    </div>
+    <h1><%= @workflow_run.workflow_class %></h1>
+    <p class="df-muted df-mono"><%= @workflow_run.run_id %></p>
+  </div>
+  <div class="df-header-actions">
+    <%= link_to "Timeline", workflow_run_path(@workflow_run.run_id), class: "df-button" %>
+    <span class="df-status <%= durable_flow_status_class(@workflow_run.status) %>"><%= @workflow_run.status %></span>
+  </div>
+</div>
+
+<% if @definition_error.present? %>
+  <section class="df-panel">
+    <div class="df-empty">
+      <strong>Definition graph unavailable.</strong>
+      <div style="margin-top: 8px;"><%= @definition_error %></div>
+    </div>
+  </section>
+<% elsif @definition_graph.nodes.empty? %>
+  <section class="df-panel">
+    <div class="df-empty">
+      No durable primitives were found in <%= @workflow_run.workflow_class %>#perform.
+    </div>
+  </section>
+<% else %>
+  <% layout = durable_flow_definition_graph_layout(@definition_graph) %>
+
+  <div class="df-definition-grid">
+    <section class="df-panel">
+      <div class="df-panel-header">
+        <div>
+          <div class="df-panel-title">Definition Graph</div>
+          <div class="df-panel-subtitle">
+            <%= pluralize(@definition_graph.nodes.size, "node") %>,
+            <%= pluralize(@definition_graph.edges.size, "edge") %>,
+            runtime status overlaid from this run
+          </div>
+        </div>
+      </div>
+
+      <div class="df-dag-wrap">
+        <svg
+          class="df-dag-svg"
+          viewBox="0 0 <%= layout.fetch(:width) %> <%= layout.fetch(:height) %>"
+          role="img"
+          aria-label="DurableFlow definition DAG for <%= @workflow_run.workflow_class %>"
+        >
+          <defs>
+            <marker id="df-dag-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+              <path d="M0,0 L0,6 L9,3 z" fill="#8b93a1" />
+            </marker>
+          </defs>
+
+          <% @definition_graph.edges.each do |edge| %>
+            <% from = layout.fetch(:positions)[edge.from] %>
+            <% to = layout.fetch(:positions)[edge.to] %>
+            <% next unless from && to %>
+            <% start_x = from.fetch(:x) + (layout.fetch(:node_width) / 2) %>
+            <% start_y = from.fetch(:y) + layout.fetch(:node_height) %>
+            <% end_x = to.fetch(:x) + (layout.fetch(:node_width) / 2) %>
+            <% end_y = to.fetch(:y) %>
+            <% mid_y = start_y + ((end_y - start_y) / 2.0) %>
+
+            <path
+              class="df-dag-edge"
+              d="M <%= start_x %> <%= start_y %> C <%= start_x %> <%= mid_y %>, <%= end_x %> <%= mid_y %>, <%= end_x %> <%= end_y %>"
+              marker-end="url(#df-dag-arrow)"
+            />
+
+            <% if edge.condition.present? %>
+              <text class="df-dag-edge-label" x="<%= end_x + 16 %>" y="<%= mid_y - 5 %>">
+                <title><%= edge.condition %></title>
+                <%= durable_flow_definition_short_condition(edge.condition) %>
+              </text>
+            <% end %>
+          <% end %>
+
+          <% @definition_graph.nodes.each do |node| %>
+            <% position = layout.fetch(:positions).fetch(node.id) %>
+            <% status = durable_flow_definition_node_status(node, @step_statuses_by_name) %>
+            <% cls = durable_flow_definition_class(node, @step_statuses_by_name) %>
+            <% metadata = [ durable_flow_node_label(node.type), node.target_workflow_class ].compact.join(" / ") %>
+
+            <g class="df-dag-node" transform="translate(<%= position.fetch(:x) %> <%= position.fetch(:y) %>)">
+              <rect class="df-dag-card <%= cls %>" width="<%= layout.fetch(:node_width) %>" height="<%= layout.fetch(:node_height) %>" rx="8" />
+              <text class="df-dag-node-name" x="16" y="28"><%= node.name %></text>
+              <text class="df-dag-node-meta" x="16" y="52"><%= metadata %></text>
+              <text class="df-dag-status-label" x="<%= layout.fetch(:node_width) - 16 %>" y="28" text-anchor="end"><%= status %></text>
+            </g>
+          <% end %>
+        </svg>
+      </div>
+    </section>
+
+    <aside>
+      <section class="df-panel">
+        <div class="df-panel-header">
+          <div>
+            <div class="df-panel-title">Graph Summary</div>
+            <div class="df-panel-subtitle">Static analysis of the workflow definition</div>
+          </div>
+        </div>
+
+        <div class="df-side-section">
+          <div class="df-kv">
+            <div class="df-kv-key">Workflow</div>
+            <div class="df-kv-value"><%= @definition_graph.workflow_class %></div>
+          </div>
+          <div class="df-kv">
+            <div class="df-kv-key">Source</div>
+            <div class="df-kv-value"><%= @definition_graph.source_file %></div>
+          </div>
+          <div class="df-kv">
+            <div class="df-kv-key">Nodes</div>
+            <div class="df-kv-value"><%= @definition_graph.nodes.map(&:name).join(", ") %></div>
+          </div>
+        </div>
+
+        <% if @definition_graph.warnings.any? %>
+          <div class="df-side-section">
+            <h3>Warnings</h3>
+            <% @definition_graph.warnings.each do |warning| %>
+              <div class="df-warning"><%= warning %></div>
+            <% end %>
+          </div>
+        <% end %>
+      </section>
+
+      <section class="df-panel" style="margin-top: 16px;">
+        <div class="df-panel-header">
+          <div>
+            <div class="df-panel-title">Graph JSON</div>
+            <div class="df-panel-subtitle">DefinitionGraph#to_h</div>
+          </div>
+        </div>
+        <pre class="df-code df-definition-json"><%= durable_flow_json(@definition_graph.to_h) %></pre>
+      </section>
+    </aside>
+  </div>
+<% end %>

data/app/views/durable_flow/workflow_runs/index.html.erb

@@ -52,6 +52,10 @@
           <td>
             <%= link_to run.workflow_class, workflow_run_path(run.run_id), class: "df-run-link" %>
             <div class="df-run-id df-mono"><%= run.run_id %></div>
+            <div class="df-run-actions">
+              <%= link_to "Timeline", workflow_run_path(run.run_id) %>
+              <%= link_to "Definition DAG", definition_workflow_run_path(run.run_id) %>
+            </div>
           </td>
           <td>
             <span class="df-status <%= durable_flow_status_class(run.status) %>"><%= run.status %></span>

data/app/views/durable_flow/workflow_runs/show.html.erb

@@ -4,7 +4,10 @@
     <h1><%= @workflow_run.workflow_class %></h1>
     <p class="df-muted df-mono"><%= @workflow_run.run_id %></p>
   </div>
-  <span class="df-status <%= durable_flow_status_class(@workflow_run.status) %>"><%= @workflow_run.status %></span>
+  <div class="df-header-actions">
+    <%= link_to "Definition DAG", definition_workflow_run_path(@workflow_run.run_id), class: "df-button" %>
+    <span class="df-status <%= durable_flow_status_class(@workflow_run.status) %>"><%= @workflow_run.status %></span>
+  </div>
 </div>
 
 <div class="df-meta-grid">

data/app/views/layouts/durable_flow/application.html.erb

@@ -125,6 +125,14 @@
         margin-bottom: 22px;
       }
 
+      .df-header-actions {
+        display: flex;
+        align-items: center;
+        justify-content: flex-end;
+        gap: 10px;
+        flex-wrap: wrap;
+      }
+
       .df-kicker {
         color: var(--muted);
         font-size: 12px;
@@ -237,6 +245,7 @@
 
       .df-run-link { font-weight: 700; color: #1d4f91; }
       .df-run-id { margin-top: 4px; color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
+      .df-run-actions { display: flex; gap: 10px; margin-top: 7px; font-size: 12px; font-weight: 700; color: #1d4f91; }
 
       .df-status {
         display: inline-flex;
@@ -270,6 +279,13 @@
         align-items: start;
       }
 
+      .df-definition-grid {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) minmax(340px, 0.38fr);
+        gap: 16px;
+        align-items: start;
+      }
+
       .df-meta-grid {
         display: grid;
         grid-template-columns: repeat(4, minmax(0, 1fr));
@@ -419,12 +435,83 @@
         text-align: center;
       }
 
+      .df-dag-wrap {
+        padding: 12px;
+        overflow: auto;
+      }
+
+      .df-dag-svg {
+        display: block;
+        width: 100%;
+        min-width: 760px;
+        height: auto;
+      }
+
+      .df-dag-edge {
+        fill: none;
+        stroke: var(--subtle);
+        stroke-width: 2;
+      }
+
+      .df-dag-edge-label {
+        fill: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        paint-order: stroke;
+        stroke: #fff;
+        stroke-width: 4px;
+        stroke-linejoin: round;
+      }
+
+      .df-dag-card {
+        fill: #fbfcfd;
+        stroke: var(--line-strong);
+        stroke-width: 1.5;
+        filter: drop-shadow(0 6px 10px rgba(18, 20, 23, 0.08));
+      }
+
+      .df-dag-card.success { fill: var(--green-soft); stroke: var(--green); }
+      .df-dag-card.active { fill: var(--blue-soft); stroke: var(--blue); }
+      .df-dag-card.waiting { fill: var(--amber-soft); stroke: var(--amber); }
+      .df-dag-card.danger { fill: var(--red-soft); stroke: var(--red); }
+      .df-dag-card.neutral { fill: #fbfcfd; stroke: var(--line-strong); }
+
+      .df-dag-node-name {
+        fill: var(--ink);
+        font-size: 14px;
+        font-weight: 800;
+      }
+
+      .df-dag-node-meta,
+      .df-dag-status-label {
+        fill: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+      }
+
+      .df-warning {
+        color: var(--amber);
+        background: var(--amber-soft);
+        border-radius: 8px;
+        padding: 10px 12px;
+        margin-top: 8px;
+        line-height: 1.45;
+      }
+
+      .df-definition-json {
+        margin: 0;
+        border: 0;
+        border-radius: 0;
+        max-height: 520px;
+      }
+
       @media (max-width: 900px) {
         .df-shell { grid-template-columns: 1fr; }
         .df-sidebar { display: none; }
         .df-page { padding: 22px 16px 32px; }
         .df-header { flex-direction: column; }
-        .df-stats, .df-meta-grid, .df-detail-grid { grid-template-columns: 1fr; }
+        .df-header-actions { justify-content: flex-start; }
+        .df-stats, .df-meta-grid, .df-detail-grid, .df-definition-grid { grid-template-columns: 1fr; }
         .df-filter { min-width: 100%; }
         th, td { padding: 11px 12px; }
         .df-hide-sm { display: none; }

data/config/routes.rb

@@ -2,5 +2,9 @@
 
 DurableFlow::Engine.routes.draw do
   root to: "workflow_runs#index"
-  resources :workflow_runs, only: [ :index, :show ], param: :run_id
+  resources :workflow_runs, only: [ :index, :show ], param: :run_id do
+    member do
+      get :definition
+    end
+  end
 end