smith-agents 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6e0cbabc0bd3db4447206b0326a96996b5b3a6b46ec82e0533298f4074b0659
-  data.tar.gz: 1e4f9346f46675db971627676f5d85621120d3387e95fab5258ef5de88f22939
+  metadata.gz: 1c5a7f554819eb342aa2284fb010eba8126f22fba1348683a36fbc4fa9d5383f
+  data.tar.gz: b72e10a5415340c5b337751c0cc92f2f59ed0ddb62850e03746df217be374721
 SHA512:
-  metadata.gz: c91ea9dfb9d21c284278a46a12380b94aba48091370a9db358ea2a5ddb96a21b1a18a453d6d0b431f2839a153a20e5d93bd9a611573f93c99efb59b9e48a21dd
-  data.tar.gz: f75d0d058c722e640c1299cb62beaafb7a3051f13d786460b289187a7c4a15c5e32aa2f2f5d8b68369d5b5d1b8d6e479147bbf2beb668a2273e740ef7a21f882
+  metadata.gz: 75d149a61196f2c0cd22748ff6d5a6c4530bc9d91c61b163c027e44d555b9fd0f1ca5ef0a283c6025d6906b6d984923265fba05190fa3da37a60cfe864e5f6f8
+  data.tar.gz: 906bc56189df0f84ad62cb643ed8141a05780a328bf9a3770db55c575d71db86b94ad39e91517ba0e2d76f05942f84358dc234b2e685ad0701dba059bed65d36

data/CHANGELOG.md

@@ -8,6 +8,58 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 No unreleased changes.
 
+## [0.4.2] - 2026-07-02
+
+Patch release for bounded fan-out and retry workflow primitives. This remains
+workflow-first and host-owned: Smith executes declared transitions and exposes
+inspection metadata, while durable scheduling, long waits, tool adapter
+contracts, and deployment packaging stay with the host application.
+
+### Added
+
+- `fan_out branches: {...}` transition DSL for bounded heterogeneous
+  multi-agent fan-out with stable branch keys and named aggregate results.
+- `retry_on` transition DSL for bounded local retries using explicit error
+  classes or Smith's built-in retryability classifier.
+- Graph inspection metadata for `:fanout` transitions and retry policy details.
+
+### Changed
+
+- Fan-out branch execution preserves branch identity, branch-specific budgets,
+  agent guardrails, tool guardrails, deadlines, and usage accounting.
+- Parallel/fan-out failure handling now prefers the initiating branch error over
+  cooperative cancellation errors.
+- Failed-but-billable provider attempts are included in budget reconciliation
+  for retry, fallback, and fan-out settlement paths.
+- Retry `max_delay` remains a hard cap even when jitter is configured.
+
+### Test coverage
+
+- Default suite: 880 examples, 0 failures.
+- Practical gem-level execution probe covering heterogeneous `fan_out`,
+  same-agent parallel execution, `retry_on`, failed-but-billable budget
+  settlement, cancellation cause preservation, branch input guardrail ordering
+  before session preparation, graph metadata, and invalid declaration rejection.
+- Added focused coverage for heterogeneous fan-out, retry policies,
+  failed-but-billable retry budget accounting, cancellation cause preservation,
+  and graph inspection metadata.
+
+## [0.4.1] - 2026-06-28
+
+Patch release for static workflow graph inspection. This is additive and diagnostic-only: Smith exposes declared workflow topology for hosts to render, lint, or cache without executing agents, advancing state, owning progress projection, or changing durability/recovery boundaries.
+
+### Added
+
+- `Smith::Workflow.graph` — returns a read-only inspection object for a workflow class.
+- `Smith::Workflow.validate_graph` — returns a structured report with validity status, diagnostics, suggestions, transition snapshots, and graph metrics.
+- Pre-runtime graph diagnostics for missing initial states, undefined transition states, unresolved `on_success` / `on_failure` targets, unresolved router route/fallback targets, target-state mismatch warnings, and unreachable-transition warnings.
+- Transition snapshots that preserve declared names exactly and expose `name`, `from`, `to`, `kind`, success/failure targets, router routes, and router fallback.
+
+### Test coverage
+
+- Default suite: 862 examples, 0 failures.
+- Touched Ruby files: 17 files inspected by RuboCop, 0 offenses.
+
 ## [0.4.0] - 2026-06-24
 
 Two more host-ergonomic primitives that close the deferred-from-0.3.0 backlog: `Workflow.stuck_for?` for liveness probing and `Context.persist :auto` for write-tracked context persistence. Both are purely additive.

data/README.md

@@ -5,11 +5,19 @@ Workflow-first multi-agent orchestration for Ruby. Smith sits on top of `RubyLLM
 > [!WARNING]
 > Smith is pre-1.0. Expect contract tightening between minor versions. Pin to an exact version in production.
 
+## Verification Discipline
+
+Tests are required, but they are never enough for runtime primitive changes.
+Every Smith workflow slice must also run practical gem-level execution probes.
+When a host application consumes unreleased Smith changes, point that host app at
+the local Smith repository and exercise the changed workflow paths in the host
+environment before calling the slice complete.
+
 ## Installation
 
 ```ruby
 # Gemfile
-gem "smith-agents", "~> 0.2.0", require: "smith"
+gem "smith-agents", "~> 0.4.2", require: "smith"
 ```
 
 ```bash
@@ -87,6 +95,7 @@ end
 | Pipeline | sequential transitions | Multi-step workflow with explicit success/failure routing. |
 | Router | `route :classifier, routes: {...}` | Branch on a classifier agent's output. |
 | Parallel fan-out | `execute :agent, parallel: true` | Concurrent agent calls under one ledger. |
+| Heterogeneous fan-out | `fan_out branches: {...}` | Concurrent calls to different agents with named branch results. |
 | Nested workflow | `workflow OtherWorkflow` | Reuse a subflow as one transition. |
 | Evaluator-Optimizer | `optimize generator:, evaluator:, ...` | Generate-then-critique refinement loops. |
 | Orchestrator-Worker | `orchestrate orchestrator:, worker:, ...` | Dynamic task fan-out with delegation rounds. |
@@ -94,6 +103,21 @@ end
 
 The full pattern guide with working examples for each lives in [`docs/PATTERNS.md`](docs/PATTERNS.md).
 
+## Workflow Graph Inspection
+
+Smith can inspect a workflow's declared graph without running agents or advancing state. This is useful for host apps that want to render, lint, or cache a workflow shape before execution.
+
+```ruby
+report = ReplyWorkflow.validate_graph
+
+report.valid?        # => true
+report.transitions   # => read-only transition snapshots
+report.diagnostics   # => errors and warnings for missing states or routes
+report.metrics       # => state, transition, reachability, and terminal-state counts
+```
+
+Graph inspection is static and diagnostic-only. Runtime execution, persistence, progress projection, retries, and recovery remain host-owned concerns.
+
 ## Configuration
 
 ```ruby
@@ -215,6 +239,19 @@ Smith::Errors.retryable_classes
 # => [Smith::AgentError, Smith::DeadlineExceeded]  (for ActiveJob retry_on)
 ```
 
+Workflow transitions can also declare a bounded local retry policy:
+
+```ruby
+transition :draft, from: :idle, to: :done do
+  execute :writer
+  retry_on Smith::AgentError, attempts: 3, backoff: 0.1, max_delay: 1.0
+end
+```
+
+When no classes are passed, `retry_on` uses `Smith::Errors.retryable?`.
+This is a bounded local transition retry policy. Durable scheduling, long waits,
+and external idempotency guarantees remain host-owned.
+
 ## Development
 
 ```bash
@@ -223,4 +260,5 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-770 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the 0.2.0 surface and [`UPSTREAM_PROPOSAL.md`](UPSTREAM_PROPOSAL.md) for the vendored Responses adapter retirement path.
+880 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the current
+release surface.

data/docs/PATTERNS.md

@@ -239,7 +239,47 @@ Why this is valuable:
 - branch failures discard step output and route through normal failure handling
 - prepared input is reused consistently across branches
 
-## Example 6: Nested Workflows
+## Example 6: Heterogeneous Fan-Out
+
+Use heterogeneous fan-out when different specialists should run concurrently and return named branch results under one workflow transition.
+
+```ruby
+class StaticReviewAgent < Smith::Agent
+  register_as :static_review_agent
+  model "gpt-4.1-nano"
+end
+
+class SecurityReviewAgent < Smith::Agent
+  register_as :security_review_agent
+  model "gpt-4.1-nano"
+end
+
+class CodeReviewWorkflow < Smith::Workflow
+  initial_state :idle
+  state :reviewed
+  state :failed
+
+  transition :review, from: :idle, to: :reviewed do
+    fan_out branches: {
+      static: :static_review_agent,
+      security: :security_review_agent
+    }
+    on_failure :fail
+  end
+end
+```
+
+What you get:
+
+- stable branch identity in the step output
+- branch-specific agent budgets, guardrails, tools, and model configuration
+- one shared prepared input for the transition
+- one shared transition result, so downstream joins remain explicit in the workflow
+- branch failures discard partial output and route through normal failure handling
+
+Use same-agent `parallel: true` for repeated homogeneous work. Use `fan_out` when branches are different agents with different responsibilities.
+
+## Example 7: Nested Workflows
 
 Use nested workflows when one part of the system deserves to be a reusable subflow with its own states and transitions.
 
@@ -281,7 +321,7 @@ What you get:
 - nested best-known token/cost totals roll up into the parent result
 - artifact scope is preserved across nesting
 
-## Example 7: Evaluator-Optimizer
+## Example 8: Evaluator-Optimizer
 
 Use `optimize` when one agent generates candidates and another agent evaluates whether the result is acceptable.
 
@@ -335,7 +375,7 @@ Why this matters:
 - exhaustion, malformed evaluator output, and convergence without acceptance fail normally
 - costs and token usage from the full loop roll into the workflow totals
 
-## Example 8: Orchestrator-Worker
+## Example 9: Orchestrator-Worker
 
 Use `orchestrate` when you need an orchestrator that can emit structured tasks for workers and later decide when the system is done.
 
@@ -489,4 +529,3 @@ The yielded step object exposes a narrow, read-heavy surface:
 - **Persistence**: Context writes and written outcomes survive `to_state`/`from_state`. The block itself (a Proc) lives on the class-level Transition and is never serialized.
 - **Trace**: Emits `:deterministic_step` traces for start, success/routed, and failure. When a step writes an outcome, the trace includes `outcome_kind`.
 - **Mutual exclusivity**: `compute` and `run` cannot be combined with `execute`, `route`, `workflow`, `optimize`, or `orchestrate`. A transition declares exactly one primary execution body.
-

data/lib/smith/agent/lifecycle.rb

@@ -46,10 +46,10 @@ module Smith
 
       def build_model_chain(agent_class)
         primary = if agent_class.respond_to?(:model_block) && agent_class.model_block
-          resolve_dynamic_model(agent_class)
-        else
-          agent_class.chat_kwargs[:model]
-        end
+                    resolve_dynamic_model(agent_class)
+                  else
+                    agent_class.chat_kwargs[:model]
+                  end
         fallbacks = agent_class.fallback_models || []
         [primary, *fallbacks].compact
       end
@@ -103,8 +103,8 @@ module Smith
 
         declared = agent_class.inputs || []
         user_declared = declared - Smith::Agent::RESERVED_INPUT_NAMES
-        user_declared.each_with_object({}) do |name, kwargs|
-          kwargs[name] = @context[name]
+        user_declared.to_h do |name|
+          [name, @context[name]]
         end
       end
 
@@ -131,7 +131,9 @@ module Smith
 
         combined_contents = existing_system_contents + prepared_system_contents
         return if combined_contents.empty?
-        return prepared_system_messages.each { |message| chat.add_message(message) } unless combined_contents.all?(String)
+        unless combined_contents.all?(String)
+          return prepared_system_messages.each { |message| chat.add_message(message) }
+        end
 
         if chat.respond_to?(:with_instructions)
           chat.with_instructions(combined_contents.join("\n\n"))
@@ -178,6 +180,8 @@ module Smith
         agent_result = Workflow::AgentResult.new(
           content: nil, input_tokens: input, output_tokens: output, cost: cost, model_used: model_id
         )
+        Thread.current[:smith_failed_agent_results] ||= []
+        Thread.current[:smith_failed_agent_results] << agent_result
         record_usage(agent_class, agent_result, :failed_attempt, model_id)
       end
 

data/lib/smith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

data/lib/smith/workflow/budget_integration.rb

@@ -30,19 +30,33 @@ module Smith
       def reconcile_branch_budget(ledger, estimates, agent_result: nil)
         return unless ledger && estimates
 
-        actuals = extract_actuals(agent_result)
+        actuals = extract_actuals(agent_results_for_settlement(agent_result))
         estimates.each do |dim, amt|
           ledger.reconcile!(dim, amt, actual_for_dimension(dim, actuals[:tokens], actuals[:cost]))
         end
       end
 
-      def extract_actuals(agent_result)
+      def extract_actuals(agent_results)
+        results = Array(agent_results).compact
+
         {
-          tokens: (agent_result&.input_tokens || 0) + (agent_result&.output_tokens || 0),
-          cost: agent_result&.cost || 0
+          tokens: results.sum { |result| (result.input_tokens || 0) + (result.output_tokens || 0) },
+          cost: results.sum { |result| result.cost || 0 }
         }
       end
 
+      def agent_results_for_settlement(agent_result = nil)
+        [*failed_billable_attempts, agent_result].compact
+      end
+
+      def failed_billable_attempts
+        Array(Thread.current[:smith_failed_agent_results])
+      end
+
+      def clear_failed_billable_attempts
+        Thread.current[:smith_failed_agent_results] = []
+      end
+
       def actual_for_dimension(dim, actual_tokens, actual_cost = 0)
         return actual_tokens if TOKEN_DIMENSIONS.include?(dim)
         return actual_cost if COST_DIMENSIONS.include?(dim)
@@ -59,7 +73,7 @@ module Smith
       def settle_budget_on_failure(ledger, estimates, agent_result)
         return unless ledger && estimates
 
-        if agent_result
+        if agent_result || failed_billable_attempts.any?
           reconcile_branch_budget(ledger, estimates, agent_result: agent_result)
         else
           release_branch_budget(ledger, estimates)
@@ -85,6 +99,12 @@ module Smith
         { branch: index, agent: transition.agent_name, output: agent_result ? agent_result.content : result }
       end
 
+      def finalize_named_branch(branch_key, agent_name, result, ledger, reserved)
+        agent_result = result.is_a?(Workflow::AgentResult) ? result : nil
+        reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+        { branch: branch_key, agent: agent_name, output: agent_result ? agent_result.content : result }
+      end
+
       def estimate_for_dimension(dim, limit, branch_count)
         return 0 unless BUDGET_DIMENSIONS.include?(dim)
 

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -91,7 +91,7 @@ module Smith
         when Hash
           deep_symbolize_evaluation(evaluation)
         when String
-          parsed = (JSON.parse(evaluation, symbolize_names: true) rescue nil)
+          parsed = parse_evaluation_json(evaluation)
           parsed.is_a?(Hash) ? parsed : evaluation
         else
           evaluation
@@ -155,9 +155,12 @@ module Smith
 
       def invoke_agent_with_budget(agent_class, prepared_input)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         with_agent_context(agent_class) do
           invoke_with_call_ledger(agent_class, prepared_input)
         end
+      ensure
+        clear_failed_billable_attempts
       end
 
       def invoke_with_call_ledger(agent_class, prepared_input)
@@ -179,12 +182,20 @@ module Smith
       # routes through on_threshold and returns the resulting value
       # (non-nil terminates the loop with that as the step output).
       def check_improvement_threshold!(evaluation, state, round)
-        return nil unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+        unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+          return nil
+        end
 
         handle_exit(state, :on_threshold,
                     "optimization improvement below threshold after round #{round + 1}")
       end
 
+      def parse_evaluation_json(evaluation)
+        JSON.parse(evaluation, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
       def prepare_generator_input(prepared_input, round, prior_candidate, feedback)
         return prepared_input if round.zero?
 

data/lib/smith/workflow/execution.rb

@@ -8,13 +8,15 @@ module Smith
       include EvaluatorOptimizer
       include OrchestratorWorker
       include ParallelExecution
+      include FanoutExecution
+      include RetryExecution
       include DeterministicExecution
 
       private
 
       def execute_step(transition)
         setup_step_context
-        output = with_scoped_artifacts { run_guarded_step(transition) }
+        output = with_scoped_artifacts { run_with_retry_policy(transition) }
         complete_step(transition, output)
       rescue StandardError => e
         @outcome = nil
@@ -40,6 +42,7 @@ module Smith
 
       def run_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
+        return run_guarded_fanout_step(transition) if transition.fanout?
 
         agent_class = resolve_agent_class(transition)
         run_input_guardrails(agent_class)
@@ -93,6 +96,7 @@ module Smith
 
       def execute_serial_step(transition, prepared_input: nil)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         ledger = effective_call_ledger
         reserved = reserve_for_serial(transition, ledger)
         begin
@@ -104,6 +108,7 @@ module Smith
         ensure
           settle_budget_on_failure(ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
           Thread.current[:smith_last_agent_result] = nil
+          clear_failed_billable_attempts
         end
       end
 

data/lib/smith/workflow/fanout_execution.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module FanoutExecution
+      private
+
+      def run_guarded_fanout_step(transition)
+        branches = transition.fanout_config.fetch(:branches)
+        branch_agent_classes = fanout_agent_classes(transition, branches)
+        run_workflow_input_guardrails
+        run_fanout_agent_input_guardrails(branch_agent_classes)
+        prepared_input = build_session&.prepare!
+        output = execute_fanout_step(
+          transition,
+          branches: branches,
+          branch_agent_classes: branch_agent_classes,
+          prepared_input: prepared_input
+        )
+        run_workflow_output_guardrails(output)
+        output
+      end
+
+      def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
+        branches ||= transition.fanout_config.fetch(:branches)
+        branch_agent_classes ||= fanout_agent_classes(transition, branches)
+        env = BranchEnv.new(
+          prepared_input: prepared_input,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+
+        branch_calls = branches.map do |branch_key, agent_name|
+          proc do |signal|
+            run_fanout_branch(branch_key, agent_name, branch_agent_classes.fetch(branch_key), env, signal)
+          end
+        end
+
+        Parallel.execute(branches: branch_calls)
+      end
+
+      def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
+        setup_fanout_branch_context(env, @ledger, agent_class)
+
+        with_agent_context(agent_class) do
+          branch_ledger = effective_call_ledger
+          reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
+          begin
+            result = guarded_fanout_branch_call(agent_class, env, signal)
+            finalize_named_branch(branch_key, agent_name, result, branch_ledger, reserved).tap { reserved = nil }
+          ensure
+            settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+          end
+        end
+      ensure
+        teardown_branch_context(env)
+      end
+
+      def guarded_fanout_branch_call(agent_class, env, signal)
+        check_cancellation!(signal)
+        check_deadline!
+        result = agent_class.model_configured? ? invoke_agent(agent_class, env.prepared_input) : nil
+        output = result.is_a?(AgentResult) ? result.content : result
+        validate_data_volume!(output, agent_class)
+        run_agent_output_guardrails(output, agent_class)
+        check_cancellation!(signal)
+        result
+      end
+
+      def setup_fanout_branch_context(env, ledger, agent_class)
+        setup_branch_context(env, ledger)
+        apply_tool_guardrails(agent_class)
+      end
+
+      def reserve_fanout_branch_call(branch_ledger, branch_estimates, agent_class)
+        return reserve_branch_budget(branch_ledger, branch_estimates: branch_estimates) if @ledger
+
+        reserve_serial_budget(branch_ledger, agent_budget: agent_class&.budget) if branch_ledger
+      end
+
+      def fanout_agent_classes(transition, branches)
+        branches.to_h do |branch_key, agent_name|
+          [branch_key, resolve_fanout_agent_class(transition, agent_name)]
+        end
+      end
+
+      def run_fanout_agent_input_guardrails(branch_agent_classes)
+        branch_agent_classes.each_value do |agent_class|
+          run_agent_input_guardrails(agent_class)
+        end
+      end
+
+      def fanout_branch_estimates(branches, branch_agent_classes)
+        return {} unless @ledger
+
+        branch_count = branches.length
+        branches.each_with_object({}) do |(branch_key, _agent_name), map|
+          agent_class = branch_agent_classes.fetch(branch_key)
+          map[branch_key] = compute_branch_estimates(
+            @ledger,
+            branch_count: branch_count,
+            agent_budget: agent_class&.budget
+          )
+        end
+      end
+
+      def resolve_fanout_agent_class(transition, agent_name)
+        Agent::Registry.fetch!(
+          agent_name,
+          workflow_class: self.class,
+          transition_name: transition&.name,
+          role: :fanout_agent
+        )
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/diagnostic.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Diagnostic
+        attr_reader :severity, :code, :message, :state, :transition, :target, :suggestion
+
+        def initialize(**attributes)
+          @severity = attributes.fetch(:severity)
+          @code = attributes.fetch(:code)
+          @message = attributes.fetch(:message)
+          @state = attributes[:state]
+          @transition = attributes[:transition]
+          @target = attributes[:target]
+          @suggestion = attributes[:suggestion]
+        end
+
+        def to_h
+          {
+            severity: severity,
+            code: code,
+            message: message,
+            state: state,
+            transition: transition,
+            target: target,
+            suggestion: suggestion
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/metrics.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Metrics
+        attr_reader :graph, :reachable_transition_names
+
+        def initialize(graph, reachable_transition_names)
+          @graph = graph
+          @reachable_transition_names = reachable_transition_names
+        end
+
+        def to_h
+          {
+            states_count: graph.states.length,
+            transitions_count: graph.transitions.length,
+            reachable_transitions_count: reachable_transition_names.length,
+            terminal_states: terminal_states
+          }
+        end
+
+        private
+
+        def terminal_states
+          graph.states.select do |state|
+            graph.transitions.values.none? { |transition| transition.from == state }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/reachability.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class Reachability
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def transition_names
+          return [] unless graph.initial_state
+
+          reset_walk
+          drain_queue
+          @seen_transitions.keys
+        end
+
+        private
+
+        def reset_walk
+          @seen_states = { graph.initial_state => true }
+          @seen_transitions = {}
+          @queue = [graph.initial_state]
+        end
+
+        def drain_queue
+          transitions_from(@queue.shift).each { |transition| visit_transition(transition) } until @queue.empty?
+        end
+
+        def visit_transition(transition)
+          return if @seen_transitions.key?(transition.name)
+
+          @seen_transitions[transition.name] = true
+          enqueue_state(transition.to)
+          Targets.for(transition).each { |target_name| visit_named_transition(target_name) }
+        end
+
+        def visit_named_transition(target_name)
+          target = graph.transitions[target_name]
+          visit_transition(target) if target
+        end
+
+        def enqueue_state(state)
+          return if state.nil? || @seen_states.key?(state)
+
+          @seen_states[state] = true
+          @queue << state
+        end
+
+        def transitions_from(state)
+          graph.transitions.values.select { |transition| transition.from == state }
+        end
+      end
+    end
+  end
+end