phronomy 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0aaadfedad1ee8b4afa1efb2e205a626a20cd636f268e711dce29128c84b6fe
-  data.tar.gz: f781f66ae3d570caca771d2b5579874169acef5eeed7f6cf99474a4c82fd077a
+  metadata.gz: 84f1944fd2628cdc04bfdaabab8ca91beeb624b7904ea9f50499f863e86e3f4c
+  data.tar.gz: 96b4b7c5258b3f2b9c710115e1b27230a87013c9e4953c05d40ea7ae227c43d8
 SHA512:
-  metadata.gz: 73793efee9cf2c0cb81828fc86927181edca2b4d3fa830a6cefa176b30fd70c57c75e71173d57b51d385377ec3795f1d8cb42e25c3650be40eff543fc2f856fd
-  data.tar.gz: b7dd9cc538e478774d46cf7823e4f5e52b599a02fdd1edf300439287dabfe2fc9a90e93f50647fffa246f7f3c90bd4abf6cf258e9723af1222f836d89125dc59
+  metadata.gz: d0cc9d4473f67a88f449c0b120d66f8975a21fda6feac2e361d8ba5931176a4aee38766cff5efd21a92344808a03e332611ac8c0d33fff1f547d25ea2dab54f4
+  data.tar.gz: 650e770db4aedfe6d6dc63deeef096014a574c73ac05438bcff6dce03605ec6b079a50f9fe860890e127f49b84e0970d7716d26606956f471665d56cec66a940

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.1] — Unreleased
+
+### Changed
+
+- **`WorkflowRunner` — state_machines fully drives execution** (architecture overhaul).
+  Previously `state_machines` was used only for post-hoc transition validation;
+  the next-node was calculated by Phronomy internally (`resolve_next_node`).
+  As of 0.3.0, all state transition decisions — including guard evaluation for
+  routing events — are delegated entirely to `state_machines`.
+  - `PhaseTracker` now exposes `attr_accessor :context` so guard lambdas can
+    access the `WorkflowContext` via `m.context`.
+  - Guard bridge pattern: `if: ->(m) { guard_proc.call(m.context) }`.
+  - Three event types registered per workflow:
+    1. `advance_<from>` — unconditional after-transitions
+    2. `<routing_event>` — guarded branching from action states (name is the
+       event name used in the DSL, e.g. `:route`, `:route_review`)
+    3. `<external_event>` — human-in-the-loop triggers from wait states
+  - Invalid transitions now raise `ArgumentError` instead of logging warnings.
+- **`WorkflowRunner` initializer signature changed** — `edges:`,
+  `conditional_edges:`, and `wait_states:` replaced by `after_transitions:`,
+  `route_transitions:`, `external_events:`, and `wait_state_names:`.
+  This is an **internal-only** change; the public `Phronomy::Workflow.define` DSL
+  is unchanged.
+
+### Removed (internal)
+
+- `WorkflowRunner#resolve_next_node` — logic moved to state_machines
+- `WorkflowRunner#advance_phase` — replaced by `fire_event!`
+- `Workflow::Builder#build_edges`, `#build_conditional_edges`,
+  `#build_wait_states` — replaced by unified event classification in `build`
+
+---
+
 ## [Unreleased]
 
 ### Added

data/lib/phronomy/state_store/file.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Phronomy
+  module StateStore
+    # File-system-backed state store.
+    # Persists graph state as a JSON file under a configurable directory.
+    # No additional server or database migration is required — it works with
+    # the local file system out of the box.
+    #
+    # Each thread_id is stored as a separate file named "<thread_id>.json".
+    # The thread_id is sanitised before use as a filename to prevent path
+    # traversal: only alphanumeric characters, hyphens, underscores, and dots
+    # are allowed; all other characters are replaced with underscores.
+    #
+    # @note This store is suitable for single-process use (development, CLI
+    #   tools, tests).  It is not safe for concurrent access across multiple
+    #   processes without external locking.
+    #
+    # @example
+    #   store = Phronomy::StateStore::File.new(dir: "tmp/workflow_states")
+    #   Phronomy::Workflow.define(MyContext, state_store: store) do
+    #     # ...
+    #   end
+    class File < Base
+      # @param dir [String] directory where state files are stored.
+      #   Created automatically if it does not exist.
+      def initialize(dir: ::File.join(::Dir.tmpdir, "phronomy_states"))
+        @dir = ::File.expand_path(dir)
+        ::FileUtils.mkdir_p(@dir)
+      end
+
+      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
+      # @return [self]
+      def save(state)
+        ::File.write(path(state.thread_id), serialize_state(state))
+        self
+      end
+
+      # @param thread_id [String]
+      # @return [Object, nil] state instance or nil if not found
+      def load(thread_id)
+        file = path(thread_id)
+        return nil unless ::File.exist?(file)
+
+        deserialize_state(::File.read(file))
+      end
+
+      # Removes the saved state file for the given thread_id.
+      # @param thread_id [String]
+      # @return [self]
+      def clear(thread_id)
+        file = path(thread_id)
+        ::File.delete(file) if ::File.exist?(file)
+        self
+      end
+
+      # Removes all state files managed by this store instance.
+      # @return [self]
+      def clear_all
+        ::Dir.glob(::File.join(@dir, "*.json")).each { |f| ::File.delete(f) }
+        self
+      end
+
+      # @return [String] the directory used by this store
+      def directory
+        @dir
+      end
+
+      private
+
+      # Converts a thread_id into a safe filename component.
+      # Characters outside [A-Za-z0-9._-] are replaced with underscores.
+      def sanitize(thread_id)
+        thread_id.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+      end
+
+      def path(thread_id)
+        ::File.join(@dir, "#{sanitize(thread_id)}.json")
+      end
+    end
+  end
+end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/phronomy/workflow.rb

@@ -53,10 +53,11 @@ module Phronomy
 
     # Defines a new Workflow.
     # @param context_class [Class] class that includes Phronomy::WorkflowContext
+    # @param state_store [Object, nil] optional state store override (passed to WorkflowRunner)
     # @yield block evaluated in DSL context
     # @return [Phronomy::Workflow] compiled and ready-to-run workflow instance
-    def self.define(context_class, &block)
-      builder = Builder.new(context_class)
+    def self.define(context_class, state_store: nil, &block)
+      builder = Builder.new(context_class, state_store: state_store)
       builder.instance_eval(&block)
       builder.build
     end
@@ -109,8 +110,9 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class)
+      def initialize(context_class, state_store: nil)
         @context_class = context_class
+        @state_store = state_store
         @initial = nil
         # { node_name => callable }
         @states = {}
@@ -170,112 +172,50 @@ module Phronomy
       # Builds and returns a Phronomy::Workflow backed by a WorkflowRunner.
       def build
         nodes = @states.dup
-        edges = build_edges
-        conditional_edges = build_conditional_edges
-        wait_states = build_wait_states
+
+        # After-transitions: { from => to }
+        # Unconditional transitions that fire automatically after an action state completes.
+        after_transitions = @after_transitions.each_with_object({}) do |t, h|
+          h[t[:from]] = t[:to]
+        end
+
+        # Route transitions: { from => {event_name:, entries: [{guard:, to:}, ...]} }
+        # Events declared from action states (not wait states) fire automatically
+        # after the action completes. The event name is used to register the
+        # state_machines event and may be any symbol (e.g. :route, :route_review).
+        # Declaration order is preserved so guarded entries appear before fallbacks.
+        route_transitions = {}
+
+        # External events: { event_name => [{from:, to:, guard:}, ...] }
+        # Events declared from wait states, triggered by human input (e.g. :approve).
+        external_events = {}
+
+        @event_transitions.each do |t|
+          if @wait_state_names.include?(t[:from])
+            # Source is a wait state → external event
+            external_events[t[:name]] ||= []
+            external_events[t[:name]] << {from: t[:from], to: t[:to], guard: t[:guard]}
+          else
+            # Source is an action state → routing event (auto-fires after action)
+            # The event name is taken from the first declaration for each from-state.
+            route_transitions[t[:from]] ||= {event_name: t[:name], entries: []}
+            route_transitions[t[:from]][:entries] << {guard: t[:guard], to: t[:to]}
+          end
+        end
 
         runner = Phronomy::WorkflowRunner.new(
           state_class: @context_class,
           nodes: nodes,
-          edges: edges,
-          conditional_edges: conditional_edges,
+          after_transitions: after_transitions,
+          route_transitions: route_transitions,
+          external_events: external_events,
           entry_point: @initial || nodes.keys.first,
-          wait_states: wait_states
+          wait_state_names: @wait_state_names,
+          state_store: @state_store
         )
 
         Workflow.new(runner)
       end
-
-      private
-
-      # Converts @after_transitions and non-guarded @event_transitions into
-      # the edges hash expected by WorkflowRunner: { from => [{to:, condition:}] }
-      #
-      # Event transitions whose from-node also has guarded transitions are omitted
-      # here; they are handled inside build_conditional_edges as a fallback.
-      def build_edges
-        edges = {}
-
-        # After-transitions (unconditional edges fired after action completes)
-        @after_transitions.each do |t|
-          edges[t[:from]] ||= []
-          edges[t[:from]] << {to: t[:to], condition: nil}
-        end
-
-        # Collect from-nodes that already have at least one guarded event
-        from_with_guards = @event_transitions.select { |t| t[:guard] }.map { |t| t[:from] }.to_set
-
-        # Unconditional event transitions are plain edges ONLY when no guarded
-        # event exists from the same source node.  When guards are present the
-        # unguarded transition acts as a fallback and is wired inside
-        # build_conditional_edges instead.
-        @event_transitions.reject { |t| t[:guard] }.each do |t|
-          next if from_with_guards.include?(t[:from])
-          edges[t[:from]] ||= []
-          edges[t[:from]] << {to: t[:to], condition: nil}
-        end
-
-        edges
-      end
-
-      # Converts guarded event transitions into the conditional_edges hash:
-      # { from => { condition: Proc, mapping: nil } }
-      #
-      # Multiple guarded transitions from the same source are combined into a
-      # single routing proc.  An unguarded transition from the same source is
-      # used as an automatic fallback when all guards fail.
-      def build_conditional_edges
-        conditional_edges = {}
-
-        guarded = @event_transitions.select { |t| t[:guard] }
-        guarded.group_by { |t| t[:from] }.each do |from, transitions|
-          # Unguarded fallback for this from-node (may be nil)
-          fallback = @event_transitions.find { |t| t[:from] == from && t[:guard].nil? }
-
-          routing = lambda do |state|
-            matched = transitions.find { |t| t[:guard].call(state) }
-            next matched[:to] if matched
-            fallback&.fetch(:to)
-          end
-          conditional_edges[from] = {condition: routing, mapping: nil}
-        end
-
-        conditional_edges
-      end
-
-      # Converts wait_state declarations plus event-driven transitions *to*
-      # wait states into the wait_states hash:
-      # { wait_state_name => { resume_event: Symbol, resume_to: Symbol } }
-      #
-      # For each wait state, we look for the first event declared as
-      # `event :X, from: :wait_state_name, to: :Y` and use that as the
-      # resume_event / resume_to pair. If multiple events exist for the same
-      # wait state, subsequent ones are registered as additional named events.
-      def build_wait_states
-        wait_states = {}
-
-        @wait_state_names.each do |ws|
-          # Find events that originate from this wait state
-          outgoing = @event_transitions.select { |t| t[:from] == ws }
-          primary = outgoing.first
-
-          wait_states[ws] = {
-            resume_event: primary&.fetch(:name),
-            resume_to: primary&.fetch(:to)
-          }
-
-          # Additional events from the same wait state are also registered so
-          # that send_event(:other_event) works for branching wait states.
-          outgoing.drop(1).each do |t|
-            wait_states[:"#{ws}__#{t[:name]}"] = {
-              resume_event: t[:name],
-              resume_to: t[:to]
-            }
-          end
-        end
-
-        wait_states
-      end
     end
   end
 end

data/lib/phronomy/workflow_runner.rb

@@ -8,35 +8,51 @@ module Phronomy
   # Manages node execution, phase transitions, halt/resume, and wait states.
   # Instantiated by Phronomy::Workflow and used internally.
   #
-  # Wait states (registered via wait_states:) are virtual nodes
-  # that automatically halt execution when reached. They can be resumed with
-  # either #resume (generic) or #send_event (event-typed).
+  # == Design principle
   #
-  # Internally, a state_machines-based PhaseTracker class is generated at
-  # initialization time. The tracker validates phase transitions during
-  # execution; invalid transitions are logged as warnings without halting.
+  # State transitions are driven entirely by state_machines. The PhaseTracker
+  # holds a reference to the current WorkflowContext via +attr_accessor :context+,
+  # and guard lambdas evaluate +m.context+ (the WorkflowContext) rather than
+  # the PhaseTracker itself. This ensures that "what happens next" is always
+  # determined by the declared state machine topology, never by Phronomy internals.
+  #
+  # == Three transition categories registered in PhaseTracker
+  #
+  #   1. advance_<from>  — automatic, unconditional after-transitions
+  #                        fired when an action state's action completes
+  #                        (declared with +after :foo, to: :bar+)
+  #
+  #   2. route           — a single event that carries all guarded transitions
+  #                        (declared with +event :route, from: :foo, guard: ..., to: :bar+)
+  #                        Guards are evaluated in declaration order; first match wins.
+  #                        An unguarded fallback, if declared, is evaluated last.
+  #
+  #   3. <event_name>    — external events triggered by human input, originating
+  #                        from wait states
+  #                        (declared with +event :approve, from: :awaiting, to: :run+)
   class WorkflowRunner
     include Phronomy::Runnable
 
     # Sentinel value for the terminal state of a workflow.
     FINISH = :__end__
 
-    def initialize(state_class:, nodes:, edges:, conditional_edges:, entry_point:,
-      before_callbacks: {}, after_callbacks: {}, wait_states: {}, state_store: nil)
+    def initialize(state_class:, nodes:, after_transitions:, route_transitions:,
+      external_events:, entry_point:, wait_state_names: [],
+      before_callbacks: {}, after_callbacks: {}, state_store: nil)
       @state_class = state_class
       @nodes = nodes
-      @edges = edges
-      @conditional_edges = conditional_edges
+      @after_transitions = after_transitions  # { from => to }
+      @route_transitions = route_transitions  # { from => [{guard:, to:}, ...] }
+      @external_events = external_events    # { name => [{from:, to:, guard:}, ...] }
       @entry_point = entry_point
+      @wait_state_names = wait_state_names
       @before_callbacks = before_callbacks.dup
       @after_callbacks = after_callbacks.dup
-      # { wait_state_name => { resume_event: Symbol, resume_to: Symbol } }
-      @wait_states = wait_states.dup
       @state_store_override = state_store
       @phase_machine_class = build_phase_machine_class
     end
 
-    # Executes the workflow from the entry point.
+    # Executes the workflow from the initial state.
     # @param input [Hash] initial context field values
     # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
     # @return [Object] final context (includes Phronomy::WorkflowContext)
@@ -55,9 +71,7 @@ module Phronomy
       end
     end
 
-    # Generic resume. Routes based on the current phase encoding.
-    # Equivalent to +send_event(state:, event: :resume, input:)+.
-    #
+    # Generic resume. Equivalent to +send_event(state:, event: :resume, input:)+.
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
@@ -67,14 +81,11 @@ module Phronomy
 
     # Fires a named event to advance a halted workflow.
     #
-    # The special event +:resume+ is accepted for all halt types:
-    # - Named wait state → resumes at +resume_to+ node
-    #
-    # Any other event name must match the +resume_event:+ declared in
-    # the wait_states configuration.
+    # The special event +:resume+ selects the first external event registered
+    # for the current wait state and fires it.
     #
     # @param state [Object] halted context
-    # @param event [Symbol] +:resume+ for generic resumption, or a named event
+    # @param event [Symbol] named event or +:resume+ for generic resumption
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
     def send_event(state:, event:, input: nil)
@@ -82,21 +93,30 @@ module Phronomy
       event = event.to_sym
       current_phase = state.phase
 
-      if event == :resume
-        # Named wait state: use resume_to
-        if @wait_states.key?(current_phase)
-          return run_graph(state, from_node: @wait_states[current_phase][:resume_to])
+      tracker = new_phase_machine(current_phase)
+      tracker.context = state
+
+      ev_to_fire = if event == :resume
+        # Find the first external event that can originate from the current wait state.
+        name, = @external_events.find { |_, ts| ts.any? { |t| t[:from] == current_phase } }
+        unless name
+          raise ArgumentError,
+            "No external event registered for wait state #{current_phase.inspect}"
+        end
+        name
+      else
+        unless @external_events.key?(event)
+          raise ArgumentError,
+            "Unknown event #{event.inspect}. Valid events: #{@external_events.keys.inspect}"
         end
-        raise ArgumentError, "State has no wait state registered for phase #{current_phase.inspect}"
+        event
       end
 
-      # Named event lookup
-      _, wait_cfg = @wait_states.find { |_, c| c[:resume_event] == event }
-      unless wait_cfg
-        valid = @wait_states.values.filter_map { |c| c[:resume_event] }.uniq
-        raise ArgumentError, "Unknown event #{event.inspect}. Valid events: #{valid.inspect}"
-      end
-      run_graph(state, from_node: wait_cfg[:resume_to])
+      fire_event!(tracker, ev_to_fire, current_phase)
+
+      next_phase = tracker.phase.to_sym
+      next_node = (next_phase == :__end__) ? FINISH : next_phase
+      run_graph(state, from_node: next_node)
     end
 
     # Streaming execution. Yields { node: Symbol, state: Object } after each node completes.
@@ -121,6 +141,7 @@ module Phronomy
     def run_graph(state, from_node: nil, recursion_limit: 25, &event_block)
       current_node = from_node || @entry_point
       tracker = new_phase_machine(current_node)
+      tracker.context = state
       step = 0
 
       while current_node && current_node != FINISH
@@ -129,15 +150,15 @@ module Phronomy
             "Recursion limit (#{recursion_limit}) exceeded"
         end
 
-        # Auto-halt at wait states.
-        if @wait_states.key?(current_node)
+        # Auto-halt at wait states: save context and return to caller.
+        if @wait_state_names.include?(current_node)
           state.set_graph_metadata(thread_id: state.thread_id, phase: current_node)
           state_store&.save(state)
           return state
         end
 
         node_fn = @nodes[current_node]
-        raise ArgumentError, "Node #{current_node} is not defined" unless node_fn
+        raise ArgumentError, "Node #{current_node.inspect} is not defined" unless node_fn
 
         result = node_fn.call(state)
         state = case result
@@ -146,14 +167,29 @@ module Phronomy
         when nil then state
         else
           raise ArgumentError,
-            "Node #{current_node} returned #{result.class}; expected Hash, #{@state_class}, or nil"
+            "Node #{current_node} returned #{result.class}; " \
+            "expected Hash, #{@state_class}, or nil"
         end
 
+        # Update tracker so guards see the freshest context.
+        tracker.context = state
+
         event_block&.call({node: current_node, state: state})
 
-        next_n = resolve_next_node(current_node, state)
-        advance_phase(tracker, current_node, next_n || FINISH)
-        current_node = next_n
+        # Delegate transition decision to state_machines.
+        if @after_transitions.key?(current_node)
+          fire_event!(tracker, :"advance_#{current_node}", current_node)
+        elsif @route_transitions.key?(current_node)
+          ev_name = @route_transitions[current_node][:event_name]
+          fire_event!(tracker, ev_name, current_node)
+        end
+        # Nodes with no declared outgoing transition are treated as terminal:
+        # next_phase == current_node triggers the FINISH assignment below.
+
+        next_phase = tracker.phase.to_sym
+        # When next_phase == current_node: no transition fired (terminal node) → end.
+        # When next_phase == :__end__ (== FINISH): route led to finish → exit loop.
+        current_node = (next_phase == current_node) ? FINISH : next_phase
 
         step += 1
       end
@@ -163,100 +199,87 @@ module Phronomy
       state
     end
 
-    def resolve_next_node(current, state)
-      if (cond = @conditional_edges[current])
-        result = cond[:condition].call(state)
-        if cond[:mapping]
-          unless cond[:mapping].key?(result)
-            raise ArgumentError,
-              "Conditional edge from #{current.inspect} returned #{result.inspect}, " \
-              "which is not present in the mapping (#{cond[:mapping].keys.inspect})"
-          end
-          return cond[:mapping][result]
-        end
-        return result
-      end
+    # Fires +event_name+ on +tracker+, raising a descriptive error if no
+    # transition matches. state_machines event methods return false when no
+    # transition can be taken (invalid state or all guards fail).
+    def fire_event!(tracker, event_name, from_node)
+      return if tracker.send(event_name)
 
-      edges = @edges[current]
-      return nil unless edges&.any?
-
-      matched = edges.find { |edge| edge[:condition].nil? || edge[:condition].call(state) }
-      matched&.fetch(:to)
+      raise ArgumentError,
+        "Transition from #{from_node.inspect} via event #{event_name.inspect} failed. " \
+        "Ensure at least one guard matches or add a fallback (no-guard) transition."
     end
 
-    # Builds a state_machines-based PhaseTracker class encoding the workflow topology.
-    # Returns nil if the build fails (execution continues without phase validation).
+    # Builds the PhaseTracker class backed by state_machines.
+    #
+    # Three event types are registered:
+    #   advance_<from>  — unconditional after-transitions
+    #   route           — all guarded routing transitions (one event, multiple transitions)
+    #   <external_name> — external events originating from wait states
+    #
+    # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
     def build_phase_machine_class
       entry = @entry_point
-      nodes = @nodes.keys
-      ws_names = @wait_states.keys
-
-      # Collect all valid (from, to) pairs; use a Hash to deduplicate.
-      trans = {}
-
-      @edges.each do |from, edge_list|
-        edge_list.each do |edge|
-          to = (edge[:to] == FINISH) ? :__end__ : edge[:to]
-          trans[[from, to]] = true
-        end
-      end
-
-      @conditional_edges.each do |from, cfg|
-        targets = cfg[:mapping] ? cfg[:mapping].values : (nodes + ws_names + [:__end__])
-        targets.each do |to|
-          t = (to == FINISH) ? :__end__ : to
-          trans[[from, t]] = true
-        end
-      end
-
-      # Any node can be terminal (no outgoing edge = implicit advance to :__end__).
-      nodes.each { |n| trans[[n, :__end__]] = true }
-
-      all_states = (nodes + ws_names + [:__end__]).uniq
-      trans_pairs = trans.keys
+      all_states = (@nodes.keys + @wait_state_names + [:__end__]).uniq
+      after_trans = @after_transitions   # { from => to }
+      route_trans = @route_transitions   # { from => [{guard:, to:}, ...] }
+      ext_events = @external_events     # { name => [{from:, to:, guard:}, ...] }
 
       Class.new do
+        # Holds the current WorkflowContext so guards can read it.
+        attr_accessor :context
+
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
-          trans_pairs.each do |from, to|
-            event :"advance_#{from}_to_#{to}" do
+
+          # 1. After-transitions: unconditional, fire on action completion.
+          after_trans.each do |from, to|
+            event :"advance_#{from}" do
               transition from => to
             end
           end
+
+          # 2. Route events: one named event per from-state (name may vary).
+          #    Declaration order is preserved; guards first, unguarded fallback last.
+          route_trans.each do |from, routing|
+            event routing[:event_name] do
+              routing[:entries].each do |t|
+                if t[:guard]
+                  guard_proc = t[:guard]
+                  transition from => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                else
+                  transition from => t[:to]
+                end
+              end
+            end
+          end
+
+          # 3. External events: human-in-the-loop triggers from wait states.
+          ext_events.each do |ev_name, transitions|
+            event ev_name do
+              transitions.each do |t|
+                if t[:guard]
+                  guard_proc = t[:guard]
+                  transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                else
+                  transition t[:from] => t[:to]
+                end
+              end
+            end
+          end
         end
       end
     rescue => e
-      warn "[Phronomy] Could not build phase machine: #{e.message}"
-      nil
+      raise ArgumentError, "Failed to build phase machine: #{e.message}"
     end
 
-    # Creates a PhaseTracker instance initialised to +from_node+.
+    # Creates a PhaseTracker instance initialized to +from_node+.
     def new_phase_machine(from_node)
-      return nil unless @phase_machine_class && from_node
-
       machine = @phase_machine_class.new
+      # Override the initial state set by state_machine's initializer so we can
+      # resume from an arbitrary node (e.g. after a wait state).
       machine.instance_variable_set(:@phase, from_node.to_s)
       machine
-    rescue => e
-      warn "[Phronomy] Phase machine init failed: #{e.message}"
-      nil
-    end
-
-    # Fires a transition event on the tracker from +from+ to +to+.
-    # Logs a warning if the transition is not declared; does not raise.
-    def advance_phase(tracker, from, to)
-      return unless tracker && from
-
-      to_sym = case to
-      when nil, FINISH then :__end__
-      else to
-      end
-      event_name = :"advance_#{from}_to_#{to_sym}"
-      unless tracker.fire_events(event_name)
-        warn "[Phronomy] Unexpected phase transition #{from.inspect} → #{to_sym.inspect}"
-      end
-    rescue => e
-      warn "[Phronomy] Phase tracker error (#{from}→#{to}): #{e.message}"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -157,6 +157,7 @@ files:
 - lib/phronomy/state_store/encryptor.rb
 - lib/phronomy/state_store/encryptor/active_support.rb
 - lib/phronomy/state_store/encryptor/base.rb
+- lib/phronomy/state_store/file.rb
 - lib/phronomy/state_store/in_memory.rb
 - lib/phronomy/state_store/redis.rb
 - lib/phronomy/thread_actor_registry.rb