igniter 0.2.0 → 0.3.1

data/lib/igniter/dsl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "dsl/contract_builder"
+require_relative "dsl/schema_builder"
 
 module Igniter
   module DSL

data/lib/igniter/errors.rb

@@ -48,6 +48,17 @@ module Igniter
   class ValidationError < CompileError; end
   class CycleError < ValidationError; end
   class InputError < Error; end
+  class CollectionInputError < Error; end
+  class CollectionKeyError < Error; end
   class ResolutionError < Error; end
   class CompositionError < Error; end
+  class BranchSelectionError < Error; end
+  class PendingDependencyError < Error
+    attr_reader :deferred_result
+
+    def initialize(deferred_result, message = "Dependency is pending", context: {})
+      @deferred_result = deferred_result
+      super(message, context: context)
+    end
+  end
 end

data/lib/igniter/events/bus.rb

@@ -34,6 +34,11 @@ module Igniter
       def subscribe(subscriber = nil, &block)
         @subscribers << (subscriber || block)
       end
+
+      def restore!(events:, execution_id: nil)
+        @execution_id = execution_id if execution_id
+        @events = Array(events).map { |event| event.is_a?(Event) ? event : Event.from_h(event) }
+      end
     end
   end
 end

data/lib/igniter/events/event.rb

@@ -16,6 +16,20 @@ module Igniter
       :timestamp,
       keyword_init: true
     ) do
+      def self.from_h(data)
+        new(
+          event_id: value_from(data, :event_id),
+          type: value_from(data, :type).to_sym,
+          execution_id: value_from(data, :execution_id),
+          node_id: value_from(data, :node_id),
+          node_name: value_from(data, :node_name)&.to_sym,
+          path: value_from(data, :path),
+          status: value_from(data, :status)&.to_sym,
+          payload: value_from(data, :payload) || {},
+          timestamp: parse_timestamp(value_from(data, :timestamp))
+        )
+      end
+
       def to_h
         {
           event_id: event_id,
@@ -36,6 +50,21 @@ module Igniter
 
       private
 
+      def self.parse_timestamp(value)
+        case value
+        when Time
+          value
+        when String
+          Time.iso8601(value)
+        else
+          value
+        end
+      end
+
+      def self.value_from(data, key)
+        data[key] || data[key.to_s]
+      end
+
       def serialize_value(value)
         case value
         when Time

data/lib/igniter/executor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Executor
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@executor_inputs, executor_inputs.transform_values(&:dup))
+        subclass.instance_variable_set(:@executor_metadata, executor_metadata.dup)
+      end
+
+      def input(name, required: true, type: nil, **metadata)
+        executor_inputs[name.to_sym] = metadata.merge(required: required, type: type).compact
+      end
+
+      def executor_inputs
+        @executor_inputs ||= {}
+      end
+
+      def executor_metadata
+        @executor_metadata ||= {}
+      end
+
+      def executor_key(value = nil)
+        metadata_value(:key, value)
+      end
+
+      def label(value = nil)
+        metadata_value(:label, value)
+      end
+
+      def category(value = nil)
+        metadata_value(:category, value)
+      end
+
+      def summary(value = nil)
+        metadata_value(:summary, value)
+      end
+
+      def tags(*values)
+        return Array(executor_metadata[:tags]).freeze if values.empty?
+
+        executor_metadata[:tags] = values.flatten.compact.map(&:to_sym).freeze
+      end
+
+      def output_schema(value = nil)
+        metadata_value(:output_schema, value)
+      end
+
+      def call(**dependencies)
+        new.call(**dependencies)
+      end
+
+      private
+
+      def metadata_value(key, value)
+        return executor_metadata[key] if value.nil?
+
+        executor_metadata[key] = value
+      end
+    end
+
+    attr_reader :execution, :contract
+
+    def initialize(execution: nil, contract: nil)
+      @execution = execution
+      @contract = contract
+    end
+
+    def defer(token: nil, payload: {})
+      Runtime::DeferredResult.build(token: token, payload: payload)
+    end
+  end
+end

data/lib/igniter/executor_registry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  class ExecutorRegistry
+    Definition = Struct.new(:key, :executor_class, :metadata, keyword_init: true)
+
+    def initialize
+      @definitions = {}
+    end
+
+    def register(key, executor_class, **metadata)
+      normalized_key = key.to_s
+      raise CompileError, "executor registry key cannot be empty" if normalized_key.empty?
+
+      unless executor_class.is_a?(Class) && executor_class <= Igniter::Executor
+        raise CompileError, "Executor registry key '#{normalized_key}' must reference an Igniter::Executor subclass"
+      end
+
+      @definitions[normalized_key] = Definition.new(
+        key: normalized_key,
+        executor_class: executor_class,
+        metadata: executor_class.executor_metadata.merge(metadata).merge(key: normalized_key)
+      )
+    end
+
+    def fetch(key)
+      @definitions.fetch(key.to_s)
+    rescue KeyError
+      raise CompileError, "Unknown executor registry key: #{key}"
+    end
+
+    def registered?(key)
+      @definitions.key?(key.to_s)
+    end
+
+    def definitions
+      @definitions.values.sort_by(&:key)
+    end
+
+    def clear
+      @definitions.clear
+    end
+  end
+end

data/lib/igniter/extensions/auditing/timeline.rb

@@ -19,6 +19,10 @@ module Igniter
           @events.dup
         end
 
+        def restore!(events)
+          @events = Array(events).map { |event| event.is_a?(Igniter::Events::Event) ? event : Igniter::Events::Event.from_h(event) }
+        end
+
         def snapshot
           {
             execution_id: execution.events.execution_id,

data/lib/igniter/extensions/introspection/graph_formatter.rb

@@ -23,9 +23,35 @@ module Igniter
           @graph.nodes.each do |node|
             line = "- #{node.kind} #{node.path}"
             line += " depends_on=#{node.dependencies.join(',')}" if node.dependencies.any?
+            if node.kind == :compute
+              line += " callable=#{node.callable_name}"
+              line += " guard=true" if node.guard?
+              line += " const=true" if node.const?
+              line += " executor_key=#{node.executor_key}" if node.executor_key
+              line += " label=#{node.executor_label}" if node.executor_label
+              line += " category=#{node.executor_category}" if node.executor_category
+              line += " tags=#{node.executor_tags.join(',')}" if node.executor_tags.any?
+              line += " summary=#{node.executor_summary}" if node.executor_summary
+            end
             if node.kind == :composition
               line += " contract=#{node.contract_class.name || 'AnonymousContract'}"
             end
+            if node.kind == :branch
+              cases = node.cases.map { |entry| "#{entry[:match].inspect}:#{entry[:contract].name || 'AnonymousContract'}" }
+              line += " selector=#{node.selector_dependency}"
+              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
+              line += " cases=#{cases.join('|')}"
+              line += " default=#{node.default_contract.name || 'AnonymousContract'}"
+              line += " mapper=#{node.input_mapper}" if node.input_mapper?
+            end
+            if node.kind == :collection
+              line += " with=#{node.source_dependency}"
+              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
+              line += " each=#{node.contract_class.name || 'AnonymousContract'}"
+              line += " key=#{node.key_name}"
+              line += " mode=#{node.mode}"
+              line += " mapper=#{node.input_mapper}" if node.input_mapper?
+            end
             lines << line
           end
           lines << "Outputs:"
@@ -43,11 +69,11 @@ module Igniter
           end
           @graph.outputs.each do |output|
             lines << %(  #{output_id(output)}["output: #{output.name}"])
-            lines << %(  #{node_id(@graph.fetch_node(output.source))} --> #{output_id(output)})
+            lines << %(  #{node_id(@graph.fetch_node(output.source_root))} --> #{output_id(output)})
           end
           @graph.nodes.each do |node|
             node.dependencies.each do |dependency_name|
-              dependency_node = @graph.fetch_node(dependency_name)
+              dependency_node = @graph.fetch_dependency(dependency_name)
               lines << %(  #{node_id(dependency_node)} --> #{node_id(node)})
             end
           end
@@ -57,6 +83,8 @@ module Igniter
         private
 
         def node_id(node)
+          return "output_#{node.name}" if node.kind == :output
+
           "node_#{node.name}"
         end
 
@@ -65,7 +93,9 @@ module Igniter
         end
 
         def node_label(node)
-          "#{node.kind}: #{node.name}"
+          return "#{node.kind}: #{node.path}" unless node.kind == :compute
+
+          "#{node.kind}: #{node.path}\\n#{node.callable_name}"
         end
       end
     end

data/lib/igniter/extensions/introspection/plan_formatter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Introspection
+      class PlanFormatter
+        def self.to_text(execution, output_names = nil)
+          new(execution, output_names).to_text
+        end
+
+        def initialize(execution, output_names = nil)
+          @execution = execution
+          @plan = execution.plan(output_names)
+        end
+
+        def to_text
+          lines = []
+          lines << "Plan #{@execution.compiled_graph.name}"
+          lines << "Targets: #{format_list(@plan[:targets])}"
+          lines << "Ready: #{format_list(@plan[:ready])}"
+          lines << "Blocked: #{format_list(@plan[:blocked])}"
+          lines << "Nodes:"
+
+          @plan[:nodes].each_value do |entry|
+            lines << format_node(entry)
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def format_node(entry)
+          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
+          line += " ready=true" if entry[:ready]
+          line += " blocked=true" if entry[:blocked]
+          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
+
+          dependency_summary = entry[:dependencies].map do |dependency|
+            "#{dependency[:name]}(#{dependency[:status]})"
+          end
+          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
+          line
+        end
+
+        def format_list(values)
+          array = Array(values)
+          return "none" if array.empty?
+
+          array.join(",")
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/introspection/runtime_formatter.rb

@@ -24,9 +24,9 @@ module Igniter
 
         def explain_output(output_name)
           output = @execution.compiled_graph.fetch_output(output_name)
-          source = @execution.compiled_graph.fetch_node(output.source)
+          source = @execution.compiled_graph.fetch_node(output.source_root)
 
-          {
+          explanation = {
             output_id: output.id,
             output: output.name,
             path: output.path,
@@ -35,6 +35,13 @@ module Igniter
             source_path: source.path,
             dependencies: dependency_tree(source)
           }
+
+          if output.composition_output?
+            explanation[:child_output] = output.child_output_name
+            explanation[:child_output_path] = output.source.to_s
+          end
+
+          explanation
         end
 
         private
@@ -52,7 +59,7 @@ module Igniter
             value: serialize_value(state&.value),
             error: state&.error&.message,
             dependencies: node.dependencies.map do |dependency_name|
-              dependency_tree(@execution.compiled_graph.fetch_node(dependency_name))
+              dependency_tree(@execution.compiled_graph.fetch_dependency(dependency_name))
             end
           }
         end
@@ -84,6 +91,14 @@ module Igniter
 
         def serialize_value(value)
           case value
+          when Igniter::Runtime::DeferredResult
+            {
+              type: :deferred,
+              token: value.token,
+              payload: value.payload,
+              source_node: value.source_node,
+              waiting_on: value.waiting_on
+            }
           when Igniter::Runtime::Result
             {
               type: :result,

data/lib/igniter/extensions/introspection.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "introspection/graph_formatter"
+require_relative "introspection/plan_formatter"
 require_relative "introspection/runtime_formatter"
 
 module Igniter

data/lib/igniter/extensions/reactive/engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Igniter
   module Extensions
     module Reactive
@@ -11,16 +13,21 @@ module Igniter
           @contract = contract
           @reactions = reactions
           @errors = []
+          @fired_reactions = Set.new
         end
 
         def call(event)
           reactions.each do |reaction|
             next unless Matcher.new(reaction, event).match?
+            next if already_fired?(reaction, event)
 
-            reaction.action.call(
+            mark_fired(reaction, event)
+            call_action(
+              reaction.action,
               event: event,
               contract: contract,
-              execution: execution
+              execution: execution,
+              value: value_for(event)
             )
           rescue StandardError => e
             @errors << {
@@ -30,6 +37,46 @@ module Igniter
             }
           end
         end
+
+        private
+
+        def call_action(action, **kwargs)
+          parameters = action.parameters
+          accepts_any_keywords = parameters.any? { |kind, _name| kind == :keyrest }
+
+          if accepts_any_keywords
+            action.call(**kwargs)
+            return
+          end
+
+          accepted_keywords = parameters.select { |kind, _name| %i[key keyreq].include?(kind) }.map(&:last)
+          filtered_kwargs = kwargs.slice(*accepted_keywords)
+          action.call(**filtered_kwargs)
+        end
+
+        def value_for(event)
+          return nil unless %i[node_succeeded node_resumed node_pending].include?(event.type)
+          return nil unless event.node_name
+
+          state = execution.cache.fetch(event.node_name)
+          state&.value
+        end
+
+        def already_fired?(reaction, event)
+          return false unless reaction.once_per_execution
+
+          @fired_reactions.include?(reaction_key(reaction, event))
+        end
+
+        def mark_fired(reaction, event)
+          return unless reaction.once_per_execution
+
+          @fired_reactions << reaction_key(reaction, event)
+        end
+
+        def reaction_key(reaction, event)
+          [reaction.object_id, event.execution_id]
+        end
       end
     end
   end

data/lib/igniter/extensions/reactive/reaction.rb

@@ -4,12 +4,13 @@ module Igniter
   module Extensions
     module Reactive
       class Reaction
-        attr_reader :event_type, :path, :action
+        attr_reader :event_type, :path, :action, :once_per_execution
 
-        def initialize(event_type:, path: nil, action:)
+        def initialize(event_type:, path: nil, action:, once_per_execution: false)
           @event_type = event_type.to_sym
           @path = path&.to_s
           @action = action
+          @once_per_execution = once_per_execution
         end
       end
     end

data/lib/igniter/model/branch_node.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    class BranchNode < Node
+      attr_reader :selector_dependency, :cases, :default_contract, :input_mapping, :context_dependencies, :input_mapper
+
+      def initialize(id:, name:, selector_dependency:, cases:, default_contract:, input_mapping:, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
+        dependencies = ([selector_dependency] + input_mapping.values + context_dependencies).uniq
+
+        super(
+          id: id,
+          kind: :branch,
+          name: name,
+          path: (path || name),
+          dependencies: dependencies,
+          metadata: metadata
+        )
+
+        @selector_dependency = selector_dependency.to_sym
+        @cases = cases.map { |entry| normalize_case(entry) }.freeze
+        @default_contract = default_contract
+        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @context_dependencies = Array(context_dependencies).map(&:to_sym).freeze
+        @input_mapper = input_mapper
+      end
+
+      def possible_contracts
+        (cases.map { |entry| entry[:contract] } + [default_contract]).uniq
+      end
+
+      def input_mapper?
+        !input_mapper.nil?
+      end
+
+      private
+
+      def normalize_case(entry)
+        {
+          match: entry.fetch(:match),
+          contract: entry.fetch(:contract)
+        }
+      end
+    end
+  end
+end

data/lib/igniter/model/collection_node.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    class CollectionNode < Node
+      attr_reader :source_dependency, :contract_class, :key_name, :mode, :context_dependencies, :input_mapper
+
+      def initialize(id:, name:, source_dependency:, contract_class:, key_name:, mode:, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
+        super(
+          id: id,
+          kind: :collection,
+          name: name,
+          path: (path || name),
+          dependencies: [source_dependency, *context_dependencies],
+          metadata: metadata
+        )
+
+        @source_dependency = source_dependency.to_sym
+        @contract_class = contract_class
+        @key_name = key_name.to_sym
+        @mode = mode.to_sym
+        @context_dependencies = Array(context_dependencies).map(&:to_sym)
+        @input_mapper = input_mapper
+      end
+
+      def input_mapper?
+        !input_mapper.nil?
+      end
+    end
+  end
+end

data/lib/igniter/model/composition_node.rb

@@ -5,12 +5,12 @@ module Igniter
     class CompositionNode < Node
       attr_reader :contract_class, :input_mapping
 
-      def initialize(id:, name:, contract_class:, input_mapping:, metadata: {})
+      def initialize(id:, name:, contract_class:, input_mapping:, path: nil, metadata: {})
         super(
           id: id,
           kind: :composition,
           name: name,
-          path: name,
+          path: (path || name),
           dependencies: input_mapping.values,
           metadata: metadata
         )

data/lib/igniter/model/compute_node.rb

@@ -5,17 +5,73 @@ module Igniter
     class ComputeNode < Node
       attr_reader :callable
 
-      def initialize(id:, name:, dependencies:, callable:, metadata: {})
+      def initialize(id:, name:, dependencies:, callable:, path: nil, metadata: {})
         super(
           id: id,
           kind: :compute,
           name: name,
-          path: name,
+          path: (path || name),
           dependencies: dependencies,
           metadata: metadata
         )
         @callable = callable
       end
+
+      def callable_name
+        return "const" if const?
+        return "guard" if guard?
+
+        case callable
+        when Proc
+          "proc"
+        when Symbol, String
+          callable.to_s
+        when Class
+          callable.name || "AnonymousClass"
+        else
+          callable.class.name || "AnonymousCallable"
+        end
+      end
+
+      def executor_key
+        metadata[:executor_key] || executor_metadata[:key]
+      end
+
+      def executor_label
+        metadata[:label] || executor_metadata[:label]
+      end
+
+      def executor_category
+        metadata[:category] || executor_metadata[:category]
+      end
+
+      def executor_tags
+        Array(metadata[:tags] || executor_metadata[:tags]).freeze
+      end
+
+      def executor_summary
+        metadata[:summary] || executor_metadata[:summary]
+      end
+
+      def type
+        metadata[:type] || executor_metadata[:type]
+      end
+
+      def const?
+        metadata[:kind] == :const
+      end
+
+      def guard?
+        metadata[:guard] == true || metadata[:kind] == :guard
+      end
+
+      private
+
+      def executor_metadata
+        return {} unless callable.is_a?(Class) && callable <= Igniter::Executor
+
+        callable.executor_metadata
+      end
     end
   end
 end

data/lib/igniter/model/input_node.rb

@@ -3,8 +3,8 @@
 module Igniter
   module Model
     class InputNode < Node
-      def initialize(id:, name:, metadata: {})
-        super(id: id, kind: :input, name: name, path: name, metadata: metadata)
+      def initialize(id:, name:, path: nil, metadata: {})
+        super(id: id, kind: :input, name: name, path: (path || name), metadata: metadata)
       end
 
       def type