phronomy 0.5.4 → 0.7.0

data/lib/phronomy/workflow_context.rb

@@ -11,7 +11,7 @@ module Phronomy
   # Field update policies:
   #   :replace (default) -- overwrites with the new value
   #   :append            -- appends to an Array
-  #   :merge             -- deep-merges into a Hash
+  #   :merge             -- shallow-merges into a Hash (top-level keys are merged; nested objects are replaced)
   #
   # @example
   #   class ScanContext
@@ -31,7 +31,16 @@ module Phronomy
       # @param name [Symbol]
       # @param type [Symbol] :replace / :append / :merge
       # @param default [Object, Proc, nil]
+      # @raise [ArgumentError] if +default+ is a plain Array or Hash (use a Proc instead)
+      # @api public
       def field(name, type: :replace, default: nil)
+        if default.is_a?(Array) || default.is_a?(Hash)
+          raise ArgumentError,
+            "Mutable default for field #{name.inspect} must be wrapped in a Proc " \
+            "to avoid shared state across instances. " \
+            "Use `default: -> { #{default.inspect} }` instead."
+        end
+
         @fields[name] = {type: type, default: default}
         attr_accessor name
       end
@@ -49,14 +58,16 @@ module Phronomy
     # Encoding:
     #   :__end__           — workflow completed (or not yet started)
     #   :awaiting_<name>   — halted at a wait_state(:awaiting_<name>) declaration
-    #   :<node>            — resuming at <node> (workflow paused before its execution)
+    #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
+    # @api public
     def phase
       @phase || :__end__
     end
 
     # Returns true if the workflow is paused mid-execution (not yet completed).
     # @return [Boolean]
+    # @api public
     def halted?
       phase != :__end__
     end
@@ -64,6 +75,7 @@ module Phronomy
     # Sets internal workflow metadata. Returns self.
     # @param thread_id [String, nil]
     # @param phase [Symbol, nil]
+    # @api public
     def set_graph_metadata(thread_id: nil, phase: nil)
       @thread_id = thread_id unless thread_id.nil?
       @phase = phase unless phase.nil?
@@ -71,6 +83,9 @@ module Phronomy
     end
 
     def initialize(**attrs)
+      unknown = attrs.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       self.class.fields.each do |name, config|
         default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
         send(:"#{name}=", attrs.fetch(name, default))
@@ -79,11 +94,19 @@ module Phronomy
       @phase = :__end__
     end
 
-    # Immutably updates context fields. Returns a new instance with the applied changes.
-    # Internal workflow metadata (thread_id, phase) is preserved.
+    # Returns a new context instance with the specified field updates applied.
+    # Updated fields follow the field's declared +:type+ semantics (:replace, :append,
+    # or :merge). Unchanged fields are deep-copied on a best-effort basis — objects
+    # that do not support +#dup+ (e.g. integers, frozen objects) are carried over
+    # by reference. Internal workflow metadata (thread_id, phase) is preserved.
     # @param updates [Hash] { field_name => new_value }
     # @return [self.class] new context instance
+    # @raise [ArgumentError] if updates contains keys that are not declared fields
+    # @api public
     def merge(updates)
+      unknown = updates.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       new_attrs = {}
       self.class.fields.each_key do |name|
         field_config = self.class.fields[name]
@@ -97,7 +120,7 @@ module Phronomy
             updates[name]
           end
         else
-          send(name)
+          deep_dup_value(send(name))
         end
       end
       new_context = self.class.new(**new_attrs)
@@ -110,10 +133,37 @@ module Phronomy
 
     # Converts user-defined fields to a Hash (excludes internal workflow metadata).
     # @return [Hash]
+    # @api public
     def to_h
       self.class.fields.keys.each_with_object({}) do |name, h|
         h[name] = send(name)
       end
     end
+
+    private
+
+    # Performs a deep copy of a value for immutable context propagation.
+    # Arrays and Hashes are deep-duplicated recursively.
+    # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.
+    # Other objects are dup'd (best-effort shallow copy for custom types).
+    # Objects that cannot be dup'd (e.g. Proc, Method) are returned as-is.
+    def deep_dup_value(val)
+      case val
+      when Array
+        val.map { |v| deep_dup_value(v) }
+      when Hash
+        val.each_with_object({}) { |(k, v), h| h[k] = deep_dup_value(v) }
+      when NilClass, Symbol, Integer, Float, TrueClass, FalseClass
+        val
+      else
+        return val if val.frozen?
+
+        begin
+          val.dup
+        rescue TypeError
+          val
+        end
+      end
+    end
   end
 end

data/lib/phronomy/workflow_runner.rb

@@ -5,7 +5,7 @@ require "state_machines"
 
 module Phronomy
   # Execution engine for compiled workflows.
-  # Manages node execution, phase transitions, halt/resume, and wait states.
+  # Manages state entry/exit action execution, phase transitions, halt/resume, and wait states.
   # Instantiated by Phronomy::Workflow and used internally.
   #
   # == Design principle
@@ -16,56 +16,78 @@ module Phronomy
   # 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
+  # Entry and exit actions are registered as state_machines +after_transition to:+
+  # and +before_transition from:+ callbacks respectively. Entry actions may either
+  # mutate the context in place or return a new context (e.g. via +s.merge(...)+).
+  # When an entry action returns a Phronomy::WorkflowContext, that value replaces
+  # the current context; otherwise the return value is ignored.
+  # Exit actions are always mutation-in-place; their return value is ignored.
   #
-  #   1. advance_<from>  — automatic, unconditional after-transitions
-  #                        fired when an action state's action completes
-  #                        (declared with +after :foo, to: :bar+)
+  # The sole exception is the initial state: state_machines does not fire transition
+  # callbacks on initialization, so the entry action for the entry point is invoked
+  # directly by WorkflowRunner before the main execution loop begins.
   #
-  #   2. route           — a single event that carries all guarded transitions
-  #                        (declared with +event :route, from: :foo, guard: ..., to: :bar+)
+  # == Two transition categories registered in PhaseTracker
+  #
+  #   1. state_completed  — all auto-fire transitions (with or without guards).
+  #                        Fired when an action state's action completes.
   #                        Guards are evaluated in declaration order; first match wins.
-  #                        An unguarded fallback, if declared, is evaluated last.
+  #                        (declared with +transition from: :foo, to: :bar+ or
+  #                         +transition from: :foo, guard: ..., to: :bar+)
   #
-  #   3. <event_name>    — external events triggered by human input, originating
+  #   2. <event_name>    — external events triggered by human input, originating
   #                        from wait states
-  #                        (declared with +event :approve, from: :awaiting, to: :run+)
+  #                        (declared with +transition from: :awaiting, on: :approve, to: :run+)
+  # @api private
   class WorkflowRunner
     include Phronomy::Runnable
 
     # Sentinel value for the terminal state of a workflow.
     FINISH = :__end__
 
-    def initialize(state_class:, nodes:, after_transitions:, route_transitions:,
-      external_events:, entry_point:, wait_state_names: [],
-      before_callbacks: {}, after_callbacks: {})
+    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil)
       @state_class = state_class
-      @nodes = nodes
-      @after_transitions = after_transitions  # { from => to }
-      @route_transitions = route_transitions  # { from => [{guard:, to:}, ...] }
+      @entry_actions = entry_actions   # { state_name => [callable, ...] }
+      @declared_states = declared_states
+      # Lookup set: states with at least one auto-fire transition declared.
+      @auto_state_set = auto_transitions.each_with_object({}) { |t, h| h[t[:from]] = true }
       @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
-      @phase_machine_class = build_phase_machine_class
+      @state_store = state_store
+      @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
     end
 
     # 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: }
+    # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id:, state_store: }
     # @return [Object] final context (includes Phronomy::WorkflowContext)
+    # @api private
     def invoke(input, config: {})
       caller_meta = {}
       caller_meta[:user_id] = config[:user_id] if config[:user_id]
       caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
-      trace("graph.invoke", input: input.inspect, **caller_meta) do |_span|
+      trace("workflow.invoke", input: input.inspect, **caller_meta) do |_span|
         thread_id = config[:thread_id] || SecureRandom.uuid
         recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-        state = @state_class.new(**input)
+
+        store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
+        snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
+        initial_fields = if snapshot && snapshot[:fields]
+          snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
+        else
+          input
+        end
+
+        state = @state_class.new(**initial_fields)
         state.set_graph_metadata(thread_id: thread_id)
-        result = run_graph(state, recursion_limit: recursion_limit)
+        result = if Phronomy.configuration.event_loop
+          run_via_event_loop(state, recursion_limit: recursion_limit)
+        else
+          run_workflow(state, recursion_limit: recursion_limit)
+        end
+        store&.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) if config[:thread_id]
         [result, nil]
       end
     end
@@ -74,6 +96,7 @@ module Phronomy
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
+    # @api private
     def resume(state:, input: nil)
       send_event(state: state, event: :resume, input: input)
     end
@@ -87,14 +110,12 @@ module Phronomy
     # @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
+    # @api private
     def send_event(state:, event:, input: nil)
       state = state.merge(input) if input
       event = event.to_sym
       current_phase = state.phase
 
-      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 } }
@@ -111,162 +132,199 @@ module Phronomy
         event
       end
 
-      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)
+      if Phronomy.configuration.event_loop
+        run_via_event_loop(state,
+          recursion_limit: Phronomy.configuration.recursion_limit,
+          resume_event: ev_to_fire, resume_phase: current_phase)
+      else
+        run_workflow(state, resume_event: ev_to_fire, resume_phase: current_phase)
+      end
     end
 
-    # Streaming execution. Yields { node: Symbol, state: Object } after each node completes.
+    # Streaming execution. Yields { state: Symbol, context: Object } after each state action completes.
     # @param input [Hash]
     # @param config [Hash]
     # @yield [Hash]
     # @return [Object] final context
+    # @api private
     def stream(input, config: {}, &block)
       thread_id = config[:thread_id] || SecureRandom.uuid
       recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
       state = @state_class.new(**input)
       state.set_graph_metadata(thread_id: thread_id)
-      run_graph(state, recursion_limit: recursion_limit, &block)
+      run_workflow(state, recursion_limit: recursion_limit, &block)
     end
 
     private
 
-    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
-      # Event queue: decouple node execution from transition firing.
-      # Events are enqueued after a node completes and processed at the top
+    # Builds an FSMSession for the given context. Used in EventLoop mode.
+    def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
+      Phronomy::FSMSession.new(
+        id: context.thread_id,
+        context: context,
+        entry_point: @entry_point,
+        entry_actions: @entry_actions,
+        auto_state_set: @auto_state_set,
+        declared_states: @declared_states,
+        wait_state_names: @wait_state_names,
+        external_events: @external_events,
+        phase_machine_class: @phase_machine_class,
+        recursion_limit: recursion_limit,
+        resume_event: resume_event,
+        resume_phase: resume_phase
+      )
+    end
+
+    # Executes the workflow via the singleton EventLoop.
+    # Blocks the calling thread on a completion queue until the workflow
+    # finishes, halts at a wait state, or raises an error.
+    def run_via_event_loop(context, recursion_limit:, resume_event: nil, resume_phase: nil)
+      session = build_session_for(
+        context: context, recursion_limit: recursion_limit,
+        resume_event: resume_event, resume_phase: resume_phase
+      )
+      completion_queue = Phronomy::EventLoop.instance.register(session)
+      result = completion_queue.pop
+      raise result if result.is_a?(Exception)
+      result
+    end
+
+    def run_workflow(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
+      if resume_event
+        # -- Resume from a wait state -------------------------------------------
+        # Fire the external event on a tracker positioned at the wait state.
+        # state_machines will invoke before_transition (exit) and after_transition
+        # (entry) callbacks as part of the transition, so both actions fire here.
+        current_state = resume_phase
+        tracker = new_phase_machine(current_state)
+        tracker.context = ctx
+        fire_event!(tracker, resume_event, current_state)
+        ctx = tracker.context
+        next_phase = tracker.phase.to_sym
+        current_state = (next_phase == current_state) ? FINISH : next_phase
+      else
+        # -- Fresh start --------------------------------------------------------
+        current_state = @entry_point
+        tracker = new_phase_machine(current_state)
+        tracker.context = ctx
+        # state_machines only fires after_transition callbacks on transitions.
+        # The entry point has no prior transition, so we invoke its entry actions directly.
+        @entry_actions[current_state]&.each do |c|
+          result = c.call(ctx)
+          ctx = result if result.is_a?(Phronomy::WorkflowContext)
+        end
+        tracker.context = ctx
+      end
+
+      # Event queue: decouple action execution from transition firing.
+      # Events are enqueued after visiting a state and processed at the top
       # of the next iteration so that guards always see the freshest context.
       event_queue = []
       step = 0
 
       loop do
-        break if current_node == FINISH
+        break if current_state == FINISH
 
         # -- Process next pending event -----------------------------------------
         # Dequeue one event and fire it against the state machine. Guards are
-        # evaluated here (at fire time) so they see the context written by the
-        # node that enqueued the event.
+        # evaluated here (at fire time). Entry/exit callbacks fire inside fire_event!.
         if (event = event_queue.shift)
           if step >= recursion_limit
             raise Phronomy::RecursionLimitError,
               "Recursion limit (#{recursion_limit}) exceeded"
           end
 
-          fire_event!(tracker, event, current_node)
+          fire_event!(tracker, event, current_state)
+          ctx = tracker.context
           next_phase = tracker.phase.to_sym
-          # When next_phase == current_node no transition matched → terminal node.
-          current_node = (next_phase == current_node) ? FINISH : next_phase
+          # When next_phase == current_state no transition matched → terminal state.
+          current_state = (next_phase == current_state) ? FINISH : next_phase
           step += 1
           next
         end
 
         # -- Queue empty: check for halt -----------------------------------------
         # Auto-halt at wait states: persist phase in context and return to caller.
-        # The caller resumes via send_event, which starts a fresh run_graph call.
-        if @wait_state_names.include?(current_node)
-          state.set_graph_metadata(thread_id: state.thread_id, phase: current_node)
-          return state
+        # The caller resumes via send_event.
+        if @wait_state_names.include?(current_state)
+          ctx.set_graph_metadata(thread_id: ctx.thread_id, phase: current_state)
+          return ctx
         end
 
-        # -- Execute node action ------------------------------------------------
-        node_fn = @nodes[current_node]
-        raise ArgumentError, "Node #{current_node.inspect} is not defined" unless node_fn
-
-        result = node_fn.call(state)
-        state = case result
-        when Hash then state.merge(result)
-        when @state_class then result
-        when nil then state
-        else
-          raise ArgumentError,
-            "Node #{current_node} returned #{result.class}; " \
-            "expected Hash, #{@state_class}, or nil"
+        # -- Validate state is known --------------------------------------------
+        unless @declared_states.include?(current_state)
+          raise ArgumentError, "State #{current_state.inspect} is not defined"
         end
 
-        # Update tracker so guards see the freshest context when the event fires.
-        tracker.context = state
+        # -- Emit stream event and enqueue transition ---------------------------
+        # Entry action for current_state has already been invoked (either by the
+        # initial manual call above, or by the after_transition callback fired
+        # inside fire_event! on the previous iteration).
+        event_block&.call({state: current_state, context: ctx})
 
-        event_block&.call({node: current_node, state: state})
-
-        # -- Enqueue transition event -------------------------------------------
-        # node_completed: generic event for all after-transitions (unconditional).
-        # route event:    user-named event carrying guarded conditional branches.
-        # No enqueue:     terminal node — next iteration exits via FINISH check.
-        if @after_transitions.key?(current_node)
-          event_queue << :node_completed
-        elsif @route_transitions.key?(current_node)
-          event_queue << @route_transitions[current_node][:event_name]
+        # state_completed: unified event for all auto-fire transitions.
+        # No enqueue:      terminal state — next iteration exits via FINISH check.
+        if @auto_state_set.key?(current_state)
+          event_queue << :state_completed
         else
-          current_node = FINISH
+          current_state = FINISH
         end
       end
 
-      state.set_graph_metadata(thread_id: state.thread_id, phase: :__end__)
-      state
+      ctx.set_graph_metadata(thread_id: ctx.thread_id, phase: :__end__)
+      ctx
     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)
+    def fire_event!(tracker, event_name, from_state)
       return if tracker.send(event_name)
 
       raise ArgumentError,
-        "Transition from #{from_node.inspect} via event #{event_name.inspect} failed. " \
+        "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
         "Ensure at least one guard matches or add a fallback (no-guard) transition."
     end
 
     # 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
+    # Four event/callback types are registered:
+    #   state_completed       — all auto-fire transitions (guarded and unguarded)
+    #   <external_name>       — external events originating from wait states
+    #   after_transition to   — entry callbacks (invoked when entering a state)
+    #   before_transition from — exit callbacks (invoked when leaving a state)
     #
     # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
-    def build_phase_machine_class
+    def build_phase_machine_class(auto_transitions, exit_actions)
       entry = @entry_point
-      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:}, ...] }
+      all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+      auto_trans = auto_transitions  # Array of { from:, to:, guard: }
+      ext_events = @external_events
+      entry_acts = @entry_actions
+      exit_acts = exit_actions
 
       Class.new do
-        # Holds the current WorkflowContext so guards can read it.
+        # Holds the current WorkflowContext so guards and callbacks can read it.
         attr_accessor :context
 
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
 
-          # 1. After-transitions: one generic :node_completed event covers all
-          #    unconditional transitions. This keeps event names independent of
-          #    source state names and matches standard state machine semantics.
-          event :node_completed do
-            after_trans.each do |from, to|
-              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
+          # Auto-fire transitions: all auto transitions unified under :state_completed.
+          # Includes unguarded (unconditional) and guarded (conditional) transitions.
+          # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
+          event :state_completed do
+            auto_trans.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
 
-          # 3. External events: human-in-the-loop triggers from wait states.
+          # 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|
@@ -279,18 +337,43 @@ module Phronomy
               end
             end
           end
+
+          # Entry callbacks: fire after_transition into each state.
+          #    Each callable is registered as a separate callback; state_machines
+          #    accumulates them and fires in declaration order.
+          #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
+          #    the returned context replaces the current one on the tracker.
+          entry_acts.each do |state_name, callables|
+            callables.each do |callable|
+              after_transition to: state_name do |machine|
+                result = callable.call(machine.context)
+                machine.context = result if result.is_a?(Phronomy::WorkflowContext)
+              end
+            end
+          end
+
+          # Exit callbacks: fire before_transition out of each state.
+          #    Each callable is registered as a separate callback; state_machines
+          #    accumulates them and fires in declaration order.
+          exit_acts.each do |state_name, callables|
+            callables.each do |callable|
+              before_transition from: state_name do |machine|
+                callable.call(machine.context)
+              end
+            end
+          end
         end
       end
     rescue => e
       raise ArgumentError, "Failed to build phase machine: #{e.message}"
     end
 
-    # Creates a PhaseTracker instance initialized to +from_node+.
-    def new_phase_machine(from_node)
+    # Creates a PhaseTracker instance initialized to +from_state+.
+    def new_phase_machine(from_state)
       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)
+      # resume from an arbitrary state (e.g. after a wait state).
+      machine.instance_variable_set(:@phase, from_state.to_s)
       machine
     end
   end