saga_forge-dashboard 0.1.0

data/app/presenters/saga_forge/dashboard/context_presenter.rb

@@ -0,0 +1,50 @@
+module SagaForge
+  module Dashboard
+    class ContextPresenter
+      Node = Struct.new(:key, :type, :bytes, :preview)
+
+      # Above this many elements, a Hash/Array value isn't fully serialized
+      # just to build a 200-char preview; only its size is reported. Guards
+      # against a single giant context value (e.g. a batch job's collected
+      # results) doing an unbounded JSON serialization on every page load.
+      LARGE_COLLECTION_THRESHOLD = 50
+
+      def initialize(state)
+        @context = state.context || {}
+      end
+
+      def user_nodes
+        @user_nodes ||= @context.except("__saga_forge").map { |k, v| node(k, v) }
+      end
+
+      def saga_meta = @context["__saga_forge"] # nil or the reserved sub-hash
+
+      private
+
+      def node(key, value)
+        type = ruby_type(value)
+        if large_collection?(value)
+          Node.new(key: key, type: type, bytes: nil, preview: "(#{type}, #{value.size} entries, too large to preview)")
+        else
+          json = value.to_json
+          Node.new(key: key, type: type, bytes: json.bytesize, preview: json.truncate(200))
+        end
+      end
+
+      def large_collection?(v)
+        (v.is_a?(Hash) || v.is_a?(Array)) && v.size > LARGE_COLLECTION_THRESHOLD
+      end
+
+      def ruby_type(v)
+        case v
+        when Hash then "object"
+        when Array then "array"
+        when Numeric then "number"
+        when TrueClass, FalseClass then "boolean"
+        when NilClass then "null"
+        else "string"
+        end
+      end
+    end
+  end
+end

data/app/presenters/saga_forge/dashboard/saga_graph.rb

@@ -0,0 +1,59 @@
+module SagaForge
+  module Dashboard
+    # Turns a Definition#to_graph (structured nodes + typed chain/jump/stay
+    # edges) into Cytoscape.js "elements", optionally overlaying one saga
+    # instance's status onto the nodes. Rendering-only: no DB, no analysis.
+    class SagaGraph
+      RANK = {"failed" => 3, "stalled" => 2, "processed" => 1}.freeze
+
+      def initialize(graph, definition, state = nil)
+        @graph = graph # SagaForge::Dashboard::Graph
+        @definition = definition
+        @state = state
+      end
+
+      def to_h
+        {nodes: node_elements, edges: edge_elements}
+      end
+
+      private
+
+      # Each event is attributed to a node via Definition#state_for_event,
+      # the EXACT handler table, not a scan of edge labels (which are only
+      # best-effort for jump/stay and would misattribute events on states
+      # reached solely by a computed transition). A state colors to the worst
+      # of its events' statuses (failed > stalled > processed; pending events
+      # don't color anything). The current state always wins as :active,
+      # regardless of what its own events say: it's "in progress", not
+      # judged by history.
+      def status_map
+        return {} unless @state
+        @status_map ||= begin
+          by_node = {}
+          @state.events.each do |e|
+            node = @definition.state_for_event(e.event_name)&.to_s
+            next unless node
+            rank = RANK[e.status.to_s] || 0
+            next if rank.zero?
+            by_node[node] = e.status.to_s if rank > (RANK[by_node[node]] || 0)
+          end
+          by_node[@state.current_state.to_s] = "active"
+          by_node
+        end
+      end
+
+      def node_elements
+        @graph.nodes.map do |n|
+          status = status_map[n.id] || "none"
+          {data: {id: n.id, label: n.label}, classes: "kind-#{n.kind} status-#{status}"}
+        end
+      end
+
+      def edge_elements
+        @graph.edges.each_with_index.map do |e, i|
+          {data: {id: "e#{i}", source: e.from, target: e.to, label: e.label.to_s}, classes: "kind-#{e.kind}"}
+        end
+      end
+    end
+  end
+end

data/app/presenters/saga_forge/dashboard/timeline_presenter.rb

@@ -0,0 +1,68 @@
+module SagaForge
+  module Dashboard
+    # One time-ordered stream for a saga instance: the event ledger merged with
+    # the compensation progress the engine records in context["__saga_forge"].
+    # The engine does not pre-merge these, so the dashboard owns it.
+    class TimelinePresenter
+      # index: this entry's position in its own source array (the event ledger,
+      # or the compensated/comp_error list), a tertiary sort key so #sorted is
+      # deterministic. Array#sort_by is not guaranteed stable, and every
+      # compensation entry shares the same synthetic `at` (see below), so
+      # without this tiebreak a multi-step compensation can render out of its
+      # actual (recorded) order with no indication anything is wrong.
+      Entry = Struct.new(:at, :kind, :label, :status, :detail, :index)
+
+      # A stay-loop saga can accumulate thousands of event rows; rendering all
+      # of them (each with a full payload/backtrace) doesn't scale. Cap to the
+      # most recent MAX_ENTRIES, mirroring StatsQuery::CAP's spirit. Compensation
+      # entries are small (derived from context, not a separate table) and are
+      # never capped.
+      MAX_ENTRIES = 500
+
+      def initialize(state)
+        @state = state
+      end
+
+      def entries
+        @entries ||= event_entries + compensation_entries
+      end
+
+      def sorted
+        @sorted ||= entries.sort_by { |e| [e.at || Time.at(0), (e.kind == :event) ? 0 : 1, e.index] }
+      end
+
+      # True when the event ledger was truncated to the most recent MAX_ENTRIES.
+      # Side-effect-free (derived from total_event_count alone) so it gives the
+      # right answer even if called before entries/sorted have run.
+      def truncated? = total_event_count > MAX_ENTRIES
+
+      def total_event_count = @total_event_count ||= @state.events.count
+
+      private
+
+      def meta = @state.context["__saga_forge"] || {}
+
+      def event_entries
+        rows = @state.history.last(MAX_ENTRIES)
+        rows.each_with_index.map do |e, i|
+          Entry.new(at: e.created_at, kind: :event, label: e.event_name, status: e.status,
+            detail: {payload: e.payload, attempts: e.attempts, stall_count: e.stall_count,
+                     retry_budgets: e.retry_budgets, error: e.error}, index: i)
+        end
+      end
+
+      def compensation_entries
+        done = meta["compensated"] || []
+        list = done.each_with_index.map do |name, i|
+          Entry.new(at: @state.updated_at, kind: :compensation, label: name, status: "processed",
+            detail: {attempts: meta.dig("comp_attempts", name)}, index: i)
+        end
+        if (err = meta["comp_error"])
+          list << Entry.new(at: @state.updated_at, kind: :compensation, label: err["name"], status: "failed",
+            detail: {error: err}, index: list.size)
+        end
+        list
+      end
+    end
+  end
+end

data/app/queries/saga_forge/dashboard/overview_query.rb

@@ -0,0 +1,32 @@
+module SagaForge
+  module Dashboard
+    # Fleet-wide breakdown: how many instances of each saga class sit in each
+    # current_state. One GROUP BY scan feeds the whole "classes" frame, the
+    # honest cost of a "totals across everything" view (unlike StatsQuery's
+    # per-class counts, a fleet-wide total can't be capped the way a single
+    # class's hot list can).
+    class OverviewQuery
+      # {saga_class => {current_state => count}}. current_state is a plain
+      # string column here (no enum), so the GROUP BY key is already the raw
+      # label, no enum int-vs-label normalization needed.
+      def rows
+        SagaForge::State.group(:saga_class, :current_state).count
+          .each_with_object(Hash.new { |h, k| h[k] = {} }) do |((klass, state), n), acc|
+            acc[klass][state] = n
+          end
+      end
+
+      # Fleet-wide card totals, reusing the engine's own derived scopes
+      # (State.stalled/.suspended/.compensating) rather than reimplementing
+      # their subqueries here, same discipline as SagasQuery/StatsQuery.
+      def totals
+        {
+          all: SagaForge::State.count,
+          stalled: SagaForge::State.stalled.count,
+          suspended: SagaForge::State.suspended.count,
+          compensating: SagaForge::State.compensating.count
+        }
+      end
+    end
+  end
+end

data/app/queries/saga_forge/dashboard/sagas_query.rb

@@ -0,0 +1,83 @@
+module SagaForge
+  module Dashboard
+    # Keyset pagination over one saga class's State rows. Orders by PK desc,
+    # pages with id < / > cursor, never COUNTs. Virtual filters compose the
+    # engine's derived scopes (stalled/suspended/compensating).
+    class SagasQuery
+      DEFAULT_PER = 50
+      MAX_PER = 200
+
+      def initialize(saga_class:, filter: nil, correlation: nil, before: nil, after: nil, per: DEFAULT_PER)
+        @saga_class = saga_class
+        @filter = filter.presence
+        @correlation = correlation.presence
+        @before = before.presence&.to_i
+        @after = after.presence&.to_i
+        @per = per.to_i.clamp(1, MAX_PER)
+      end
+
+      def records
+        load
+        @records
+      end
+      attr_reader :per
+
+      def has_next? # older rows remain
+        load
+        @has_next
+      end
+
+      def has_prev? # newer rows remain
+        load
+        @has_prev
+      end
+
+      def next_cursor = records.last&.id
+      def prev_cursor = records.first&.id
+
+      private
+
+      def base
+        SagaForge::State.for_saga(@saga_class)
+      end
+
+      def filtered
+        s = case @filter
+        when "stalled" then base.stalled
+        when "suspended" then base.suspended
+        when "compensating" then base.compensating
+        when "finalized" then base.finalized
+        when "active" then base.active
+        when nil, "", "all" then base
+        else base.where(current_state: @filter)
+        end
+        if @correlation
+          s = s.where("correlation_id LIKE ?", "#{SagaForge::State.sanitize_sql_like(@correlation)}%")
+        end
+        s
+      end
+
+      def load
+        return if @loaded
+        @loaded = true
+        col = "#{SagaForge::State.table_name}.id"
+        if @after
+          rows = filtered.where("#{col} > ?", @after).order(id: :asc).limit(@per + 1).to_a
+          @has_prev = rows.size > @per
+          @records = rows.first(@per).reverse
+          # Reaching this page via a real prev_cursor means older rows exist (this
+          # page came from one); a stale/deleted-anchor cursor just self-heals to
+          # the first page on the next click, so hardcoding true here is safe.
+          @has_next = true
+        else
+          scope = filtered
+          scope = scope.where("#{col} < ?", @before) if @before
+          rows = scope.order(id: :desc).limit(@per + 1).to_a
+          @has_next = rows.size > @per
+          @records = rows.first(@per)
+          @has_prev = @before.present?
+        end
+      end
+    end
+  end
+end

data/app/queries/saga_forge/dashboard/stats_query.rb

@@ -0,0 +1,31 @@
+module SagaForge
+  module Dashboard
+    class StatsQuery
+      CAP = 5000
+
+      def initialize(saga_class:)
+        @saga_class = saga_class
+      end
+
+      def counts
+        base = SagaForge::State.for_saga(@saga_class)
+        {
+          all: capped(base),
+          stalled: capped(base.stalled),
+          suspended: capped(base.suspended),
+          compensating: capped(base.compensating),
+          finalized: capped(base.finalized),
+          active: capped(base.active)
+        }
+      end
+
+      def label(n) = (n >= CAP) ? "#{CAP}+" : n.to_s
+
+      private
+
+      def capped(relation)
+        SagaForge::State.from(relation.select(:id).limit(CAP), :capped).count
+      end
+    end
+  end
+end

data/app/views/layouts/saga_forge/dashboard/application.html.erb

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>SagaForge</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <%= csrf_meta_tags %>
+  <link rel="stylesheet" href="<%= "#{request.script_name}/assets/dashboard.css?v=#{SagaForge::Dashboard.asset_digest("dashboard.css")}" %>">
+  <%# Turbo drives all navigation and form submits (SPA-style, no full reloads).
+      It lives in <head> so Turbo Drive keeps it across body swaps and never
+      re-initialises it; a body <script> would re-run on every visit. %>
+  <script src="<%= request.script_name %>/assets/turbo.min.js?v=<%= SagaForge::Dashboard.asset_digest("turbo.min.js") %>"></script>
+</head>
+<body class="min-h-screen bg-[var(--sf-bg)] font-sans text-[var(--sf-fg)] antialiased" data-poll-interval="<%= poll_interval %>">
+  <% if flash.any? %>
+    <div role="status" aria-live="polite" class="pointer-events-none fixed right-4 top-4 z-50 flex w-80 max-w-[calc(100vw-2rem)] flex-col gap-2">
+      <% flash.each do |type, msg| %>
+        <div data-flash class="pointer-events-auto rounded-md border px-3 py-2 text-sm shadow-md transition-opacity duration-300 <%= type.to_s == "alert" ? "border-[var(--sf-flash-err-border)] bg-[var(--sf-flash-err-bg)] text-[var(--sf-flash-err-fg)]" : "border-[var(--sf-flash-ok-border)] bg-[var(--sf-flash-ok-bg)] text-[var(--sf-flash-ok-fg)]" %>"><%= msg %></div>
+      <% end %>
+    </div>
+  <% end %>
+  <header class="border-b border-[var(--sf-border)] bg-[var(--sf-surface)]">
+    <div class="mx-auto flex max-w-6xl flex-wrap items-center gap-x-6 gap-y-2 px-4 py-3">
+      <a href="<%= root_path %>" class="flex items-center gap-2 font-semibold tracking-tight">
+        <span class="inline-block h-3.5 w-3.5 rounded-sm bg-[var(--sf-accent)]"></span>
+        SagaForge
+      </a>
+      <nav class="flex items-center gap-5 text-sm">
+        <% [
+             ["Sagas", sagas_path],
+             ["Overview", "#{request.script_name}/overview"],
+             ["Stalled", "#{request.script_name}/stalled"],
+             ["Suspended", "#{request.script_name}/suspended"]
+           ].each do |label, href| %>
+          <% active = request.path == href %>
+          <a href="<%= href %>"<% if active %> aria-current="page"<% end %> class="<%= active ? "font-medium text-[var(--sf-fg)]" : "text-[var(--sf-soft)] hover:text-[var(--sf-fg)]" %>"><%= label %></a>
+        <% end %>
+      </nav>
+      <div class="ml-auto flex flex-wrap items-center gap-2">
+        <%# Hidden on pages that opt out of auto-refresh (poll_region? false), so
+            a control that does nothing there doesn't confuse. %>
+        <% if poll_region? %>
+          <% current_poll = poll_interval %>
+          <label class="flex items-center gap-1 text-xs text-[var(--sf-soft)]" title="Auto-refresh">
+            <span>refresh</span>
+            <select data-poll-select class="rounded-md border border-[var(--sf-border)] bg-[var(--sf-surface)] px-1.5 py-1 text-xs text-[var(--sf-fg)]">
+              <% (poll_options | [current_poll]).sort.each do |secs| %>
+                <option value="<%= secs %>" <%= "selected" if secs == current_poll %>><%= poll_label(secs) %></option>
+              <% end %>
+            </select>
+          </label>
+        <% end %>
+        <div class="flex items-center gap-0.5 rounded-md border border-[var(--sf-border)] p-0.5 text-xs" title="Timestamp display">
+          <button type="button" data-time-set="relative" aria-pressed="<%= !absolute_time? %>" class="rounded px-2 py-0.5 <%= absolute_time? ? "text-[var(--sf-soft)] hover:text-[var(--sf-fg)]" : "bg-[var(--sf-accent)] text-[var(--sf-accent-fg)]" %>">relative</button>
+          <button type="button" data-time-set="absolute" aria-pressed="<%= absolute_time? %>" class="rounded px-2 py-0.5 <%= absolute_time? ? "bg-[var(--sf-accent)] text-[var(--sf-accent-fg)]" : "text-[var(--sf-soft)] hover:text-[var(--sf-fg)]" %>">absolute</button>
+        </div>
+      </div>
+    </div>
+  </header>
+  <%# data-poll-region / id: the JS morph-refreshes this region in place (idiomorph
+      preserves filter text, focus, and scroll). Marking <main> makes pages refresh
+      in place; the nav and the refresh/time controls sit in <header>, outside the
+      morph. A page can opt out (poll_region? false) when an in-place refresh would
+      break it (e.g. the definition graph's live Cytoscape canvas). %>
+  <main id="sf-poll-region" class="mx-auto max-w-6xl px-4 py-6" <%= "data-poll-region" if poll_region? %>>
+    <%= yield %>
+  </main>
+  <script src="<%= "#{request.script_name}/assets/dashboard.js?v=#{SagaForge::Dashboard.asset_digest("dashboard.js")}" %>"></script>
+</body>
+</html>

data/app/views/saga_forge/dashboard/definitions/missing.html.erb

@@ -0,0 +1,7 @@
+<div class="mb-5">
+  <h1 class="text-lg font-semibold tracking-tight">State machine</h1>
+</div>
+<div class="sf-card px-4 py-12 text-center text-sm text-[var(--sf-soft)]">
+  <p><code class="font-mono"><%= params[:class] %></code> isn't a registered saga class.</p>
+  <p class="mt-1">It may have been renamed, removed, or never registered with <code class="font-mono">SagaForge::Router</code>.</p>
+</div>

data/app/views/saga_forge/dashboard/definitions/show.html.erb

@@ -0,0 +1,48 @@
+<div class="mb-4 flex items-center justify-between">
+  <div>
+    <h1 class="text-lg font-semibold tracking-tight">State machine</h1>
+    <p class="font-mono text-sm text-[var(--sf-soft)]"><%= @saga_class.name %></p>
+  </div>
+  <% if @state %>
+    <%= link_to "‹ #{@state.correlation_id}", saga_path(@state), class: "sf-btn" %>
+  <% else %>
+    <%= link_to "‹ #{@saga_class.name}", sagas_path(class: @saga_class.name), class: "sf-btn" %>
+  <% end %>
+</div>
+
+<div class="sf-card overflow-hidden">
+  <div class="flex flex-wrap items-center gap-x-4 gap-y-1.5 border-b border-[var(--sf-border)] px-4 py-2.5 text-[11px] text-[var(--sf-soft)]">
+    <span class="inline-flex items-center gap-1.5">
+      <span class="inline-block h-3 w-4 border-t-2 border-[var(--sf-soft)]"></span>chain (event handler order)
+    </span>
+    <span class="inline-flex items-center gap-1.5">
+      <span class="sf-legend-dash inline-block h-3 w-4 border-t-2 border-dashed border-[#8b5cf6]"></span>jump (<code>transition_to</code>)
+    </span>
+    <% {active: "current", processed: "processed event", stalled: "stalled event", failed: "failed event", none: "untouched"}.each do |status, label| %>
+      <span class="inline-flex items-center gap-1.5">
+        <span class="h-2.5 w-2.5 rounded-sm border sf-legend-<%= status %>"></span><%= label %>
+      </span>
+    <% end %>
+  </div>
+  <p class="border-b border-[var(--sf-border)] px-4 py-2 text-[11px] text-[var(--sf-soft)]">
+    Jump edges are best-effort: they're detected by scanning handler source for a
+    literal <code>transition_to</code>, so a computed or conditional
+    transition may not appear here even though the saga can take it at runtime.
+  </p>
+  <%# The graph is passed as JSON in a data attribute, ERB-escaped, so labels
+      round-trip through the DOM untouched. %>
+  <div id="sf-graph" data-graph="<%= @graph.to_json %>" class="h-[68vh] w-full bg-[var(--sf-bg)]"></div>
+  <div id="sf-graph-detail" class="min-h-[3rem] border-t border-[var(--sf-border)] bg-[var(--sf-surface)] px-4 py-3 text-xs"></div>
+</div>
+
+<style>
+  .sf-legend-active{background:var(--sf-badge-indigo-bg);border-color:var(--sf-badge-indigo-border)}
+  .sf-legend-processed{background:var(--sf-badge-green-bg);border-color:var(--sf-badge-green-border)}
+  .sf-legend-stalled{background:var(--sf-badge-amber-bg);border-color:var(--sf-badge-amber-border)}
+  .sf-legend-failed{background:var(--sf-badge-red-bg);border-color:var(--sf-badge-red-border)}
+  .sf-legend-none{background:var(--sf-badge-slate-bg);border-color:var(--sf-badge-slate-border)}
+</style>
+
+<% %w[cytoscape.min.js dagre.min.js cytoscape-dagre.js saga_graph.js].each do |asset| %>
+  <script src="<%= "#{request.script_name}/assets/#{asset}?v=#{SagaForge::Dashboard.asset_digest(asset)}" %>"></script>
+<% end %>

data/app/views/saga_forge/dashboard/overview/_stat_card.html.erb

@@ -0,0 +1,4 @@
+<%= link_to href, class: "sf-card block p-4 hover:border-[var(--sf-accent)]" do %>
+  <div class="text-xs uppercase tracking-wide text-[var(--sf-soft)]"><%= label %></div>
+  <div class="mt-1 font-mono text-2xl font-semibold tabular-nums <%= color %>"><%= number_with_delimiter(count) %></div>
+<% end %>

data/app/views/saga_forge/dashboard/overview/classes.html.erb

@@ -0,0 +1,37 @@
+<turbo-frame id="sf-overview-classes">
+  <div class="sf-card overflow-hidden">
+    <div class="overflow-x-auto">
+      <table class="w-full min-w-[40rem] text-sm">
+        <thead>
+          <tr class="border-b border-[var(--sf-border)] bg-[var(--sf-bg)] text-left text-xs uppercase tracking-wide text-[var(--sf-soft)]">
+            <th class="px-4 py-2.5 font-medium">Class</th>
+            <th class="px-4 py-2.5 text-right font-medium">Total</th>
+            <th class="px-4 py-2.5 font-medium">By state</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-[var(--sf-border)]">
+          <% @rows.sort_by { |klass, _| klass }.each do |klass, states| %>
+            <tr class="hover:bg-[var(--sf-bg)]">
+              <td class="px-4 py-2.5">
+                <%= link_to klass, sagas_path(class: klass), class: "font-mono text-[var(--sf-fg)] hover:underline" %>
+              </td>
+              <td class="px-4 py-2.5 text-right font-mono tabular-nums"><%= number_with_delimiter(states.values.sum) %></td>
+              <td class="px-4 py-2.5">
+                <div class="flex flex-wrap gap-1.5">
+                  <% states.sort_by { |_, n| -n }.each do |state, n| %>
+                    <%= link_to sagas_path(class: klass, filter: state), class: "sf-badge sf-badge-slate" do %>
+                      <%= state %> <span class="opacity-70"><%= n %></span>
+                    <% end %>
+                  <% end %>
+                </div>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+    <% if @rows.none? %>
+      <p class="px-4 py-12 text-center text-sm text-[var(--sf-soft)]">No sagas yet.</p>
+    <% end %>
+  </div>
+</turbo-frame>

data/app/views/saga_forge/dashboard/overview/index.html.erb

@@ -0,0 +1,33 @@
+<div class="mb-5">
+  <h1 class="text-lg font-semibold tracking-tight">Overview</h1>
+  <p class="mt-1 text-sm text-[var(--sf-soft)]">Fleet-wide counts across every saga class, all time.</p>
+</div>
+
+<%# Cards are cheap independent COUNTs; the "Stalled"/"Suspended" cards link
+    straight to their dedicated triage pages. "Compensating" has no dedicated
+    fleet-wide page (sagas#index is scoped to one class), so it links into the
+    default class's list pre-filtered, a modest fallback until/unless a
+    fleet-wide compensating triage page exists. %>
+<div class="mb-5 grid grid-cols-2 gap-3 sm:grid-cols-4">
+  <%= render "stat_card", label: "All", count: @totals[:all], href: sagas_path,
+        color: "text-[var(--sf-fg)]" %>
+  <%= render "stat_card", label: "Stalled", count: @totals[:stalled], href: stalled_index_path,
+        color: (@totals[:stalled] > 0) ? "text-[var(--sf-badge-amber-fg)]" : "text-[var(--sf-fg)]" %>
+  <%= render "stat_card", label: "Suspended", count: @totals[:suspended], href: suspended_index_path,
+        color: (@totals[:suspended] > 0) ? "text-[var(--sf-badge-red-fg)]" : "text-[var(--sf-fg)]" %>
+  <%= render "stat_card", label: "Compensating", count: @totals[:compensating], href: sagas_path(filter: "compensating"),
+        color: "text-[var(--sf-fg)]" %>
+</div>
+
+<%# The per-class GROUP BY, isolated in its own lazily-loaded frame so it
+    streams in on its own clock without holding up the cards above. %>
+<turbo-frame id="sf-overview-classes" src="<%= overview_classes_path %>" loading="lazy" target="_top">
+  <div class="sf-card p-6">
+    <div class="h-4 w-40 animate-pulse rounded bg-[var(--sf-bg)]"></div>
+    <div class="mt-4 space-y-3">
+      <% 5.times do %>
+        <div class="h-3 w-full animate-pulse rounded bg-[var(--sf-bg)]"></div>
+      <% end %>
+    </div>
+  </div>
+</turbo-frame>

data/app/views/saga_forge/dashboard/sagas/_actions.html.erb

@@ -0,0 +1,27 @@
+<%# Operator actions for one saga instance. Retry stalled / Resume only make
+    sense when there's something eligible (@stalled / @suspended, set by
+    SagasController#show); Compensate / Cancel are shown whenever the saga
+    isn't already terminal or mid-compensation, the same "recovery blocked" line
+    the model itself uses to no-op, kept here only for button visibility
+    (the model is still the enforcement point; a stale button just flashes
+    "Nothing to do."). Both require confirmation since they're one-way. %>
+<% recoverable = @state.finalized_at.nil? && @state.current_state != SagaForge::State::COMPENSATING.to_s %>
+<% if @stalled || @suspended || recoverable %>
+  <div class="flex flex-wrap items-center gap-2">
+    <% if @stalled %>
+      <%= button_to "Retry stalled", retry_stalled_saga_path(@state), method: :post, class: "sf-btn sf-btn-primary" %>
+    <% end %>
+    <% if @suspended %>
+      <%= button_to "Resume", resume_saga_path(@state), method: :post, class: "sf-btn sf-btn-primary" %>
+    <% end %>
+    <% if recoverable %>
+      <%= button_to "Compensate", compensate_saga_path(@state), method: :post,
+            form: {data: {confirm: "Compensate #{@state.correlation_id}? This runs the saga's compensating steps and cannot be undone."}}, class: "sf-btn sf-btn-danger" %>
+      <%= form_with url: cancel_saga_path(@state), method: :post, class: "flex items-center gap-1",
+            data: {confirm: "Cancel #{@state.correlation_id}? This compensates the saga toward :cancelled and cannot be undone."} do |f| %>
+        <%= f.text_field :reason, placeholder: "reason (optional)", class: "w-36 rounded-md border border-[var(--sf-border)] bg-[var(--sf-surface)] px-2.5 py-1.5 text-xs placeholder:text-[var(--sf-soft)]" %>
+        <%= f.submit "Cancel", class: "sf-btn sf-btn-danger" %>
+      <% end %>
+    <% end %>
+  </div>
+<% end %>

data/app/views/saga_forge/dashboard/sagas/_compensation.html.erb

@@ -0,0 +1,41 @@
+<% meta = @context.saga_meta %>
+<div class="sf-card p-4">
+  <h2 class="mb-3 text-sm font-semibold">Compensation</h2>
+  <dl class="mb-3 flex flex-wrap gap-x-6 gap-y-1.5 text-sm">
+    <% if meta["target"].present? %>
+      <div>
+        <dt class="text-xs uppercase tracking-wide text-[var(--sf-soft)]">Target</dt>
+        <dd class="font-mono"><%= meta["target"] %></dd>
+      </div>
+    <% end %>
+    <% if meta["failure_reason"].present? %>
+      <div>
+        <dt class="text-xs uppercase tracking-wide text-[var(--sf-soft)]">Failure reason</dt>
+        <dd><%= meta["failure_reason"] %></dd>
+      </div>
+    <% end %>
+  </dl>
+
+  <% compensated = meta["compensated"] || [] %>
+  <% if compensated.any? %>
+    <p class="mb-1 text-xs uppercase tracking-wide text-[var(--sf-soft)]">Compensated steps (most recent first)</p>
+    <ol class="mb-3 flex flex-col gap-1 text-sm">
+      <% compensated.reverse.each do |name| %>
+        <li class="flex items-center gap-2 font-mono">
+          <%= status_badge("processed") %>
+          <span><%= name %></span>
+          <% attempts = meta.dig("comp_attempts", name) %>
+          <% if attempts.present? %><span class="text-xs text-[var(--sf-soft)]">(attempts: <%= attempts %>)</span><% end %>
+        </li>
+      <% end %>
+    </ol>
+  <% else %>
+    <p class="mb-3 text-sm text-[var(--sf-soft)]">No steps compensated yet.</p>
+  <% end %>
+
+  <% if (err = meta["comp_error"]) %>
+    <div class="rounded-md border border-[var(--sf-badge-red-border)] bg-[var(--sf-badge-red-bg)] px-3 py-2 text-sm text-[var(--sf-badge-red-fg)]">
+      <span class="font-mono"><%= err["name"] %></span> failed to compensate: <strong><%= err["class"] %></strong><%= ": #{err["message"]}" if err["message"].present? %>
+    </div>
+  <% end %>
+</div>

data/app/views/saga_forge/dashboard/sagas/_context_tree.html.erb

@@ -0,0 +1,37 @@
+<div class="sf-card overflow-hidden">
+  <h2 class="border-b border-[var(--sf-border)] px-4 py-2.5 text-sm font-semibold">Context</h2>
+
+  <div class="overflow-x-auto">
+    <table class="w-full text-sm">
+      <thead>
+        <tr class="border-b border-[var(--sf-border)] bg-[var(--sf-bg)] text-left text-xs uppercase tracking-wide text-[var(--sf-soft)]">
+          <th class="px-4 py-2 font-medium">Key</th>
+          <th class="px-4 py-2 font-medium">Type</th>
+          <th class="px-4 py-2 font-medium">Size</th>
+          <th class="px-4 py-2 font-medium">Preview</th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-[var(--sf-border)]">
+        <% user_nodes = @context.user_nodes %>
+        <% user_nodes.each do |node| %>
+          <tr>
+            <td class="px-4 py-2 font-mono"><%= node.key %></td>
+            <td class="px-4 py-2"><span class="sf-badge sf-badge-slate"><%= node.type %></span></td>
+            <td class="px-4 py-2 font-mono text-xs text-[var(--sf-soft)]"><%= node.bytes ? format_bytes(node.bytes) : "n/a" %></td>
+            <td class="px-4 py-2 font-mono text-xs text-[var(--sf-soft)]"><%= node.preview %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+    <% if user_nodes.empty? %>
+      <p class="px-4 py-8 text-center text-sm text-[var(--sf-soft)]">No user context keys.</p>
+    <% end %>
+  </div>
+
+  <% if @context.saga_meta.present? %>
+    <details class="border-t border-[var(--sf-border)] px-4 py-2.5 text-sm">
+      <summary class="cursor-pointer select-none text-xs uppercase tracking-wide text-[var(--sf-soft)]">Engine metadata (__saga_forge)</summary>
+      <pre class="mt-2 overflow-x-auto whitespace-pre-wrap font-mono text-xs"><%= JSON.pretty_generate(@context.saga_meta) %></pre>
+    </details>
+  <% end %>
+</div>

data/app/views/saga_forge/dashboard/sagas/_filters.html.erb

@@ -0,0 +1,9 @@
+<%# enforce_utf8: false keeps the legacy `utf8=✓` IE hack out of the GET query string. %>
+<%= form_with url: sagas_path, method: :get, enforce_utf8: false, class: "mb-4 flex flex-wrap items-center gap-2" do |f| %>
+  <%= hidden_field_tag :class, @saga_class.name %>
+  <% if params[:filter].present? %><%= hidden_field_tag :filter, params[:filter] %><% end %>
+  <%# A poll-morph "preserve this field's value across refreshes" hook isn't wired
+      up yet, but the stable field id keeps a target for that future JS. %>
+  <%= f.text_field :q, value: params[:q], placeholder: "Correlation ID prefix…", id: "sf-filter-q", class: "rounded-md border border-[var(--sf-border)] bg-[var(--sf-surface)] px-2.5 py-1.5 text-sm placeholder:text-[var(--sf-soft)]" %>
+  <%= f.submit "Search", class: "sf-btn" %>
+<% end %>