durable_workflow 0.1.0

data/lib/durable_workflow/core/executors/end.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class End < Base
+        FINISHED = '__FINISHED__'
+        Registry.register('end', self)
+
+        def call(state)
+          raw = config.result || state.ctx.dup
+          result = resolve(state, raw)
+          state = store(state, :result, result)
+          continue(state, next_step: FINISHED, output: result)
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/halt.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Halt < Base
+        Registry.register('halt', self)
+
+        def call(state)
+          extra_data = resolve(state, config.data)
+
+          halt(state,
+               data: {
+                 reason: resolve(state, config.reason) || 'Halted',
+                 halted_at: Time.now.iso8601,
+                 **extra_data
+               },
+               resume_step: config.resume_step || next_step,
+               prompt: resolve(state, config.reason))
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/loop.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Loop < Base
+        Registry.register('loop', self)
+        MAX_ITER = 100
+
+        def call(state)
+          config.over ? foreach_loop(state) : while_loop(state)
+        end
+
+        private
+
+        def foreach_loop(state)
+          collection = resolve(state, config.over)
+          raise ExecutionError, "Loop 'over' must be array" unless collection.is_a?(Array)
+
+          item_key = config.as
+          index_key = config.index_as
+          max = config.max
+          raise ExecutionError, "Collection exceeds max (#{max})" if collection.size > max
+
+          results = []
+          collection.each_with_index do |item, i|
+            state = store(state, item_key, item)
+            state = store(state, index_key, i)
+            outcome = execute_body(state)
+
+            # Bubble up halts
+            return outcome if outcome.result.is_a?(HaltResult)
+
+            state = outcome.state
+            results << outcome.result.output
+          end
+
+          state = cleanup(state, item_key, index_key)
+          state = store(state, config.output, results)
+          continue(state)
+        end
+
+        def while_loop(state)
+          cond = config.while
+          max = config.max
+          results = []
+          i = 0
+
+          while ConditionEvaluator.match?(state, cond)
+            i += 1
+            if i > max
+              return config.on_exhausted ? continue(state, next_step: config.on_exhausted) : raise(ExecutionError, 'Loop exceeded max')
+            end
+
+            state = store(state, :iteration, i)
+            outcome = execute_body(state)
+
+            # Bubble up halts
+            return outcome if outcome.result.is_a?(HaltResult)
+
+            state = outcome.state
+            results << outcome.result.output
+            break if state.ctx[:break_loop]
+          end
+
+          state = cleanup(state, :iteration, :break_loop)
+          state = store(state, config.output, results)
+          continue(state)
+        end
+
+        def execute_body(state)
+          body = config.do
+          result = nil
+
+          body.each do |step_def|
+            executor = Registry[step_def.type]
+            raise ExecutionError, "Unknown step type: #{step_def.type}" unless executor
+
+            start_time = Time.now
+            outcome = executor.new(step_def).call(state)
+            duration = ((Time.now - start_time) * 1000).to_i
+
+            record_nested_entry(state, step_def, outcome, duration)
+
+            # Bubble up halts
+            return outcome if outcome.result.is_a?(HaltResult)
+
+            state = outcome.state
+            result = outcome.result
+          end
+
+          StepOutcome.new(state:, result: result || ContinueResult.new)
+        end
+
+        def record_nested_entry(state, step_def, outcome, duration)
+          wf_store = DurableWorkflow.config&.store
+          return unless wf_store
+
+          wf_store.record(Entry.new(
+                            id: SecureRandom.uuid,
+                            execution_id: state.execution_id,
+                            step_id: "#{step.id}:#{step_def.id}",
+                            step_type: step_def.type,
+                            action: outcome.result.is_a?(HaltResult) ? :halted : :completed,
+                            duration_ms: duration,
+                            output: outcome.result.output,
+                            timestamp: Time.now
+                          ))
+        end
+
+        def cleanup(state, *keys)
+          new_ctx = state.ctx.except(*keys)
+          state.with(ctx: new_ctx)
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/parallel.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+begin
+  require 'async'
+  require 'async/barrier'
+rescue LoadError
+  # async gem not available - parallel executor will fail at runtime if used
+end
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Parallel < Base
+        Registry.register('parallel', self)
+
+        def call(state)
+          branches = config.branches
+          return continue(state) if branches.empty?
+
+          raise ExecutionError, "Parallel executor requires 'async' gem. Add it to your Gemfile." unless defined?(Async)
+
+          wait_mode = config.wait
+          required = case wait_mode
+                     when 'all' then branches.size
+                     when 'any' then 1
+                     when Integer then [wait_mode, branches.size].min
+                     else branches.size
+                     end
+
+          outcomes = Array.new(branches.size)
+          errors = []
+
+          Sync do
+            barrier = Async::Barrier.new
+
+            begin
+              branches.each_with_index do |branch, i|
+                barrier.async do
+                  executor = Registry[branch.type]
+                  raise ExecutionError, "Unknown branch type: #{branch.type}" unless executor
+
+                  outcomes[i] = executor.new(branch).call(state)
+                rescue StandardError => e
+                  errors << { branch: branch.id, error: e.message }
+                  outcomes[i] = nil
+                end
+              end
+
+              if wait_mode == 'any'
+                barrier.wait { break if outcomes.compact.size >= required }
+              else
+                barrier.wait
+              end
+            ensure
+              barrier.stop
+            end
+          end
+
+          raise ExecutionError, "Parallel failed: #{errors.size} errors" if wait_mode == 'all' && errors.any?
+          raise ExecutionError, 'Insufficient completions' if outcomes.compact.size < required
+
+          # Merge contexts from all branches
+          # Strategy: last-write-wins (branch processed later overwrites earlier values)
+          merged_ctx = outcomes.compact.reduce(state.ctx) do |ctx, outcome|
+            ctx.merge(outcome.state.ctx)
+          end
+
+          results = outcomes.map { _1&.result&.output }
+          final_state = state.with(ctx: merged_ctx)
+          final_state = store(final_state, config.output, results)
+
+          continue(final_state, output: results)
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Registry
+        @executors = {}
+
+        class << self
+          def register(type, klass)
+            @executors[type.to_s] = klass
+          end
+
+          def [](type)
+            @executors[type.to_s]
+          end
+
+          def types
+            @executors.keys
+          end
+
+          def registered?(type)
+            @executors.key?(type.to_s)
+          end
+        end
+      end
+
+      # Convenience method for registration
+      def self.register(type)
+        ->(klass) { Registry.register(type, klass) }
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/router.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Router < Base
+        Registry.register('router', self)
+
+        def call(state)
+          routes = config.routes
+          default = config.default
+
+          route = ConditionEvaluator.find_route(state, routes)
+
+          if route
+            continue(state, next_step: route.target)
+          elsif default
+            continue(state, next_step: default)
+          else
+            raise ExecutionError, "No matching route and no default for '#{step.id}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/start.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Start < Base
+        Registry.register('start', self)
+
+        def call(state)
+          validate_inputs!(state)
+          state = apply_defaults(state)
+          state = store(state, :input, state.input)
+          continue(state)
+        end
+
+        private
+
+        def workflow_inputs(state)
+          DurableWorkflow.registry[state.workflow_id]&.inputs || []
+        end
+
+        def validate_inputs!(state)
+          workflow_inputs(state).each do |input_def|
+            value = state.input[input_def.name.to_sym]
+
+            raise ValidationError, "Missing required input: #{input_def.name}" if input_def.required && value.nil?
+
+            next if value.nil?
+
+            validate_type!(input_def.name, value, input_def.type)
+          end
+        end
+
+        def validate_type!(name, value, type)
+          valid = case type
+                  when 'string'  then value.is_a?(String)
+                  when 'integer' then value.is_a?(Integer)
+                  when 'number'  then value.is_a?(Numeric)
+                  when 'boolean' then [true, false].include?(value)
+                  when 'array'   then value.is_a?(Array)
+                  when 'object'  then value.is_a?(Hash)
+                  else true
+                  end
+
+          raise ValidationError, "Input '#{name}' must be #{type}, got #{value.class}" unless valid
+        end
+
+        def apply_defaults(state)
+          updates = {}
+          workflow_inputs(state).each do |input_def|
+            key = input_def.name.to_sym
+            updates[key] = input_def.default if state.input[key].nil? && !input_def.default.nil?
+          end
+          return state if updates.empty?
+
+          state.with(input: state.input.merge(updates))
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/transform.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class Transform < Base
+        Registry.register('transform', self)
+
+        OPS = {
+          'map' => lambda { |d, a|
+            if d.is_a?(Array)
+              d.map { |i| a.is_a?(String) ? Transform.dig(i, a) : i }
+            else
+              d
+            end
+          },
+          'select' => ->(d, a) { d.is_a?(Array) ? d.select { |i| Transform.match?(i, a) } : d },
+          'reject' => ->(d, a) { d.is_a?(Array) ? d.reject { |i| Transform.match?(i, a) } : d },
+          'pluck' => ->(d, a) { d.is_a?(Array) ? d.map { |i| Transform.dig(i, a) } : d },
+          'first' => ->(d, a) { d.is_a?(Array) ? d.first(a || 1) : d },
+          'last' => ->(d, a) { d.is_a?(Array) ? d.last(a || 1) : d },
+          'flatten' => ->(d, a) { d.is_a?(Array) ? d.flatten(a || 1) : d },
+          'compact' => ->(d, _) { d.is_a?(Array) ? d.compact : d },
+          'uniq' => ->(d, _) { d.is_a?(Array) ? d.uniq : d },
+          'reverse' => ->(d, _) { d.is_a?(Array) ? d.reverse : d },
+          'sort' => lambda { |d, a|
+            if d.is_a?(Array)
+              a ? d.sort_by { |i| Transform.dig(i, a) } : d.sort
+            else
+              d
+            end
+          },
+          'count' => ->(d, _) { d.respond_to?(:size) ? d.size : 1 },
+          'sum' => lambda { |d, a|
+            if d.is_a?(Array)
+              a ? d.sum { |i| Transform.dig(i, a).to_f } : d.sum(&:to_f)
+            else
+              d
+            end
+          },
+          'keys' => ->(d, _) { d.is_a?(Hash) ? d.keys : [] },
+          'values' => ->(d, _) { d.is_a?(Hash) ? d.values : [] },
+          'pick' => ->(d, a) { d.is_a?(Hash) ? d.slice(*Array(a).map(&:to_sym)) : d },
+          'omit' => ->(d, a) { d.is_a?(Hash) ? d.except(*Array(a).map(&:to_sym)) : d },
+          'merge' => ->(d, a) { d.is_a?(Hash) && a.is_a?(Hash) ? d.merge(a) : d }
+        }.freeze
+
+        def call(state)
+          input = config.input ? resolve(state, "$#{config.input}") : state.ctx.dup
+          expr = config.expression
+
+          result = expr.reduce(input) do |data, (op, arg)|
+            OPS.fetch(op.to_s) { ->(d, _) { d } }.call(data, arg)
+          end
+
+          state = store(state, config.output, result)
+          continue(state, output: result)
+        end
+
+        def self.dig(obj, key)
+          keys = key.to_s.split('.')
+          keys.reduce(obj) { |o, k| o.is_a?(Hash) ? Utils.fetch(o, k) : nil }
+        end
+
+        def self.match?(obj, conditions)
+          conditions.all? { |k, v| dig(obj, k) == v }
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/executors/workflow.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Core
+    module Executors
+      class SubWorkflow < Base
+        Registry.register('workflow', self)
+
+        def call(state)
+          child_wf = DurableWorkflow.registry[config.workflow_id]
+          raise ExecutionError, "Workflow not found: #{config.workflow_id}" unless child_wf
+
+          input = resolve(state, config.input) || {}
+
+          result = with_timeout(config.timeout) do
+            Engine.new(child_wf, store: DurableWorkflow.config&.store).run(input:)
+          end
+
+          case result.status
+          when :completed
+            state = store(state, config.output, result.output)
+            continue(state, output: result.output)
+          when :halted
+            halt(state, data: result.halt.data, resume_step: step.id, prompt: result.halt.prompt)
+          when :failed
+            raise ExecutionError, "Sub-workflow failed: #{result.error}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/core/parser.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module DurableWorkflow
+  module Core
+    class Parser
+      # Hook system for extensions
+      @before_hooks = []
+      @after_hooks = []
+      @config_transformers = {}
+
+      class << self
+        attr_reader :before_hooks, :after_hooks, :config_transformers
+
+        def parse(source)
+          new.parse(source)
+        end
+
+        # Register a before-parse hook (receives raw YAML hash)
+        def before_parse(&block)
+          @before_hooks << block
+        end
+
+        # Register an after-parse hook (receives WorkflowDef, can return modified)
+        def after_parse(&block)
+          @after_hooks << block
+        end
+
+        # Register a config transformer for a step type
+        def transform_config(type, &block)
+          @config_transformers[type.to_s] = block
+        end
+
+        # Reset hooks (for testing)
+        def reset_hooks!
+          @before_hooks = []
+          @after_hooks = []
+          @config_transformers = {}
+        end
+      end
+
+      def parse(source)
+        yaml = load_yaml(source)
+
+        # Run before hooks
+        self.class.before_hooks.each { |hook| yaml = hook.call(yaml) || yaml }
+
+        workflow = build_workflow(yaml)
+
+        # Run after hooks - pass both workflow and raw yaml for extension data
+        self.class.after_hooks.each { |hook| workflow = hook.call(workflow, yaml) || workflow }
+
+        workflow
+      end
+
+      private
+
+      def load_yaml(source)
+        raw = case source
+              when Hash then source
+              when String
+                source.include?("\n") ? YAML.safe_load(source) : YAML.load_file(source)
+              else
+                raise Error, "Invalid source: #{source.class}"
+              end
+        DurableWorkflow::Utils.deep_symbolize(raw)
+      end
+
+      def build_workflow(y)
+        WorkflowDef.new(
+          id: y.fetch(:id),
+          name: y.fetch(:name),
+          version: y[:version],
+          description: y[:description],
+          timeout: y[:timeout],
+          inputs: parse_inputs(y[:inputs]),
+          steps: parse_steps(y.fetch(:steps)),
+          extensions: {} # Extensions populate this via after_parse hooks
+        )
+      end
+
+      def parse_inputs(inputs)
+        return [] unless inputs
+
+        inputs.map do |name, cfg|
+          cfg ||= {}
+          InputDef.new(
+            name: name.to_s,
+            type: cfg[:type],
+            required: cfg.fetch(:required, true),
+            default: cfg[:default],
+            description: cfg[:description]
+          )
+        end
+      end
+
+      def parse_steps(steps)
+        steps.map { parse_step(_1) }
+      end
+
+      def parse_step(s)
+        type = s.fetch(:type)
+        raw_config = extract_config(s)
+        config = build_typed_config(type, raw_config)
+
+        StepDef.new(
+          id: s.fetch(:id),
+          type:,
+          config:,
+          next_step: s[:next],
+          on_error: s[:on_error]
+        )
+      rescue Dry::Struct::Error => e
+        raise ValidationError, "Invalid config for step '#{s[:id]}': #{e.message}"
+      end
+
+      def build_typed_config(type, raw_config)
+        # Check for extension transformer first
+        if (transformer = self.class.config_transformers[type])
+          raw_config = transformer.call(raw_config)
+        end
+
+        # Find config class from registry
+        config_class = Core.config_registry[type]
+
+        config_class ? config_class.new(raw_config) : raw_config
+      end
+
+      def extract_config(s)
+        base = s.except(:id, :type, :next, :on_error)
+
+        case s[:type]
+        when 'call'
+          # Rename method -> method_name to avoid collision with Ruby's Object#method
+          base[:method_name] = base.delete(:method) if base.key?(:method)
+          # Handle output with schema
+          base[:output] = parse_output(base[:output]) if base[:output]
+        when 'router'
+          base[:routes] = parse_routes(base[:routes])
+        when 'loop'
+          base[:while] = parse_condition(base[:while]) if base[:while]
+          base[:do] = base[:do]&.map { parse_step(_1) }
+        when 'parallel'
+          base[:branches] = base[:branches]&.map { parse_step(_1) }
+        end
+
+        base
+      end
+
+      def parse_output(output)
+        case output
+        when Hash
+          if output.key?(:key) || output.key?(:schema)
+            OutputConfig.new(
+              key: output[:key] || output[:name],
+              schema: output[:schema]
+            )
+          else
+            output
+          end
+        when String, Symbol
+          output.to_sym
+        else
+          output
+        end
+      end
+
+      def parse_routes(routes)
+        return [] unless routes
+
+        routes.map do |r|
+          Route.new(
+            field: r.dig(:when, :field),
+            op: r.dig(:when, :op),
+            value: r.dig(:when, :value),
+            target: r[:then]
+          )
+        end
+      end
+
+      def parse_condition(c)
+        return nil unless c
+
+        Condition.new(field: c[:field], op: c[:op], value: c[:value])
+      end
+    end
+  end
+end