igniter 0.3.1 → 0.4.3

data/lib/igniter/agent/runner.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # Runs an agent's message loop in a dedicated Ruby Thread.
+    #
+    # Responsibilities:
+    #   - Pop messages from the Mailbox and dispatch to registered handlers
+    #   - Fire scheduled timers when their interval elapses
+    #   - Apply handler return-value semantics to StateHolder
+    #   - Invoke the on_crash callback when the thread dies unexpectedly
+    #   - Fire lifecycle hooks (after_start, after_crash, after_stop)
+    #
+    # Handler return-value semantics:
+    #   Hash  → replace agent state with the returned hash
+    #   :stop → close the mailbox and exit the loop cleanly
+    #   nil   → leave state unchanged (no reply sent to sync caller)
+    #   other → leave state unchanged; if message has reply_to, send value as reply
+    class Runner
+      def initialize(agent_class:, mailbox:, state_holder:, on_crash: nil)
+        @agent_class   = agent_class
+        @mailbox       = mailbox
+        @state_holder  = state_holder
+        @on_crash      = on_crash
+        @thread        = nil
+        @timers        = build_timers
+      end
+
+      # Start the message loop in a background thread. Returns the Thread.
+      def start
+        @thread = Thread.new { run_loop }
+        @thread.abort_on_exception = false
+        @thread
+      end
+
+      attr_reader :thread
+
+      private
+
+      def run_loop # rubocop:disable Metrics/MethodLength
+        fire_hooks(:start)
+        loop do
+          delay   = nearest_timer_delay
+          message = @mailbox.pop(timeout: delay)
+          fire_due_timers
+          break if message.nil? && @mailbox.closed?
+
+          dispatch(message) if message
+        end
+      rescue StandardError => e
+        @on_crash&.call(e)
+        fire_hooks(:crash, error: e)
+      ensure
+        fire_hooks(:stop)
+      end
+
+      def dispatch(message) # rubocop:disable Metrics/MethodLength
+        handler = @agent_class.handlers[message.type]
+
+        unless handler
+          # Unknown message type — send nil reply if caller is waiting
+          send_reply(message, nil)
+          return
+        end
+
+        state  = @state_holder.get
+        result = handler.call(state: state, payload: message.payload)
+
+        case result
+        when Hash
+          @state_holder.set(result)
+          send_reply(message, nil)
+        when :stop
+          send_reply(message, nil)
+          @mailbox.close
+        when nil
+          send_reply(message, nil)
+        else
+          # Non-state return value — treat as sync reply payload
+          send_reply(message, result)
+        end
+      end
+
+      def send_reply(message, value)
+        return unless message.reply_to
+
+        message.reply_to.push(
+          Message.new(type: :reply, payload: { value: value })
+        )
+      end
+
+      # Returns seconds until the next timer fires, or nil if no timers.
+      def nearest_timer_delay
+        return nil if @timers.empty?
+
+        now      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        next_at  = @timers.map { |t| t[:next_at] }.min
+        [next_at - now, 0].max
+      end
+
+      def fire_due_timers
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @timers.each do |timer|
+          next if timer[:next_at] > now
+
+          state  = @state_holder.get
+          result = timer[:handler].call(state: state)
+          @state_holder.set(result) if result.is_a?(Hash)
+          timer[:next_at] = now + timer[:interval]
+        end
+      end
+
+      def build_timers
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @agent_class.timers.map do |t|
+          t.merge(next_at: now + t[:interval])
+        end
+      end
+
+      def fire_hooks(type, **args)
+        @agent_class.hooks[type]&.each do |hook|
+          hook.call(**args)
+        rescue StandardError
+          nil # hooks must not crash the runner
+        end
+      end
+    end
+  end
+end

data/lib/igniter/agent/state_holder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # Mutex-guarded wrapper around an agent's current state hash.
+    # The state is always stored as a frozen Hash so callers can read it
+    # without holding the lock.
+    class StateHolder
+      def initialize(initial_state)
+        @state = initial_state.freeze
+        @mutex = Mutex.new
+      end
+
+      def get
+        @mutex.synchronize { @state }
+      end
+
+      def set(new_state)
+        @mutex.synchronize { @state = new_state.freeze }
+      end
+    end
+  end
+end

data/lib/igniter/agent.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "agent/message"
+require_relative "agent/mailbox"
+require_relative "agent/state_holder"
+require_relative "agent/runner"
+require_relative "agent/ref"
+
+module Igniter
+  # Base class for stateful, message-driven actors.
+  #
+  # Subclass Agent and use the class-level DSL to declare:
+  #   - `initial_state`  — default state hash for new instances
+  #   - `on`             — handler for a named message type
+  #   - `schedule`       — recurring timer handler
+  #   - `mailbox_size`   — queue capacity (default: 256)
+  #   - `mailbox_overflow` — policy when queue is full (:block/:drop_oldest/
+  #                          :drop_newest/:error, default: :block)
+  #   - `after_start`    — hook called when the agent thread begins
+  #   - `after_crash`    — hook called with the error when the thread crashes
+  #   - `after_stop`     — hook called when the agent thread exits
+  #
+  # Handler return-value semantics:
+  #   Hash  → new state (replaces current state)
+  #   :stop → shut down the agent cleanly
+  #   nil   → unchanged state
+  #   other → unchanged state; sent as reply to sync `call()` callers
+  #
+  # Example:
+  #
+  #   class CounterAgent < Igniter::Agent
+  #     initial_state counter: 0
+  #
+  #     on :increment do |state:, payload:, **|
+  #       state.merge(counter: state[:counter] + payload.fetch(:by, 1))
+  #     end
+  #
+  #     on :count do |state:, **|
+  #       state[:counter]   # returned as sync reply
+  #     end
+  #   end
+  #
+  #   ref = CounterAgent.start
+  #   ref.send(:increment, by: 5)
+  #   ref.call(:count)  # => 5
+  #   ref.stop
+  #
+  class Agent
+    # ── Custom error types ────────────────────────────────────────────────────
+
+    class MailboxFullError < Igniter::Error; end
+    class TimeoutError     < Igniter::Error; end
+
+    # ── Class-level defaults ──────────────────────────────────────────────────
+
+    @handlers         = {}
+    @timers           = []
+    @default_state    = {}
+    @mailbox_capacity = Mailbox::DEFAULT_CAPACITY
+    @mailbox_overflow = :block
+    @hooks            = { start: [], crash: [], stop: [] }
+
+    class << self
+      attr_reader :handlers, :timers, :mailbox_capacity, :hooks
+
+      # ── Inheritance ─────────────────────────────────────────────────────────
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@handlers,         {})
+        subclass.instance_variable_set(:@timers,           [])
+        subclass.instance_variable_set(:@default_state,    {})
+        subclass.instance_variable_set(:@mailbox_capacity, Mailbox::DEFAULT_CAPACITY)
+        subclass.instance_variable_set(:@mailbox_overflow, :block)
+        subclass.instance_variable_set(:@hooks,            { start: [], crash: [], stop: [] })
+      end
+
+      # ── DSL ─────────────────────────────────────────────────────────────────
+
+      # Set the initial state hash. Pass a plain Hash or a block returning one.
+      def initial_state(hash = nil, &block)
+        if block
+          @default_state_proc = block
+        else
+          @default_state = (hash || {}).freeze
+        end
+      end
+
+      # Return the resolved default state (evaluated fresh when a block was given).
+      def default_state
+        @default_state_proc ? @default_state_proc.call : @default_state
+      end
+
+      # Register a handler for messages of the given +type+.
+      def on(type, &handler)
+        @handlers[type.to_sym] = handler
+      end
+
+      # Register a recurring timer. The handler is called every +every+ seconds.
+      # Returning a Hash from the handler updates state; nil leaves it unchanged.
+      def schedule(name, every:, &handler)
+        @timers << { name: name.to_sym, interval: every.to_f, handler: handler }
+      end
+
+      # Maximum number of messages in the mailbox before overflow policy applies.
+      def mailbox_size(capacity)
+        @mailbox_capacity = capacity
+      end
+
+      # Overflow policy when the mailbox is full.
+      # One of: :block (default), :drop_oldest, :drop_newest, :error
+      def mailbox_overflow(policy)
+        @mailbox_overflow = policy
+      end
+
+      def after_start(&hook)
+        @hooks[:start] << hook
+      end
+
+      def after_crash(&hook)
+        @hooks[:crash] << hook
+      end
+
+      def after_stop(&hook)
+        @hooks[:stop] << hook
+      end
+
+      # ── Factory ─────────────────────────────────────────────────────────────
+
+      # Start the agent and return a Ref. The agent runs in a background Thread.
+      #
+      # Options:
+      #   initial_state:  Hash — override class-level default state
+      #   on_crash:       callable(error) — supervisor crash hook
+      #   name:           Symbol/String — register in Igniter::Registry under this name
+      #
+      def start(initial_state: nil, on_crash: nil, name: nil) # rubocop:disable Metrics/MethodLength
+        state_holder = StateHolder.new(initial_state || default_state)
+        mailbox      = Mailbox.new(capacity: mailbox_capacity, overflow: @mailbox_overflow)
+        runner       = Runner.new(
+          agent_class: self,
+          mailbox: mailbox,
+          state_holder: state_holder,
+          on_crash: on_crash
+        )
+        thread = runner.start
+        ref    = Ref.new(thread: thread, mailbox: mailbox, state_holder: state_holder)
+
+        Igniter::Registry.register!(name, ref) if name
+
+        ref
+      end
+    end
+  end
+end

data/lib/igniter/compiler/compiled_graph.rb

@@ -49,6 +49,10 @@ module Igniter
         raise KeyError, "Unknown dependency '#{name}'"
       end
 
+      def await_nodes
+        @nodes.select { |n| n.kind == :await }
+      end
+
       def to_h
         {
           name: name,
@@ -80,6 +84,7 @@ module Igniter
               base[:mode] = node.mode
               base[:mapper] = node.input_mapper.to_s if node.input_mapper?
             end
+            base[:event] = node.event_name if node.kind == :await
             base
           end,
           outputs: outputs.map do |output|
@@ -117,6 +122,13 @@ module Igniter
               metadata: node.metadata.reject { |key, _| key == :source_location }
             }
           end,
+          awaits: nodes.select { |node| node.kind == :await }.map do |node|
+            {
+              name: node.name,
+              event: node.event_name,
+              metadata: node.metadata.reject { |key, _| key == :source_location }
+            }
+          end,
           branches: nodes.select { |node| node.kind == :branch }.map do |node|
             {
               name: node.name,

data/lib/igniter/compiler/validation_pipeline.rb

@@ -8,7 +8,9 @@ module Igniter
         Validators::OutputsValidator,
         Validators::DependenciesValidator,
         Validators::TypeCompatibilityValidator,
-        Validators::CallableValidator
+        Validators::CallableValidator,
+        Validators::AwaitValidator,
+        Validators::RemoteValidator
       ].freeze
 
       def self.call(context, validators: DEFAULT_VALIDATORS)

data/lib/igniter/compiler/validators/await_validator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class AwaitValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          await_nodes = @context.runtime_nodes.select { |n| n.kind == :await }
+          return if await_nodes.empty?
+
+          validate_correlation_keys_as_inputs!(await_nodes)
+          validate_unique_event_names!(await_nodes)
+        end
+
+        private
+
+        def validate_correlation_keys_as_inputs!(await_nodes) # rubocop:disable Metrics/AbcSize
+          correlation_keys = @context.graph.metadata[:correlation_keys] || []
+          return if correlation_keys.empty?
+
+          input_names = @context.runtime_nodes.select { |n| n.kind == :input }.map(&:name)
+          missing = correlation_keys.reject { |key| input_names.include?(key.to_sym) }
+          return if missing.empty?
+
+          raise @context.validation_error(
+            await_nodes.first,
+            "Correlation keys #{missing.inspect} must be declared as inputs"
+          )
+        end
+
+        def validate_unique_event_names!(await_nodes)
+          event_names = await_nodes.map(&:event_name)
+          duplicates = event_names.select { |e| event_names.count(e) > 1 }.uniq
+          return if duplicates.empty?
+
+          node = await_nodes.find { |n| duplicates.include?(n.event_name) }
+          raise @context.validation_error(
+            node,
+            "Duplicate await event names: #{duplicates.inspect}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/igniter/compiler/validators/callable_validator.rb

@@ -14,14 +14,32 @@ module Igniter
 
         def call
           @context.runtime_nodes.each do |node|
-            next unless node.kind == :compute
-
-            validate_callable_signature!(node)
+            if node.kind == :compute
+              validate_callable_signature!(node)
+            elsif node.kind == :effect
+              validate_effect_adapter!(node)
+            end
           end
         end
 
         private
 
+        def validate_effect_adapter!(node)
+          adapter = node.adapter_class
+          unless adapter.is_a?(Class) && adapter <= Igniter::Effect
+            raise @context.validation_error(
+              node,
+              "Effect '#{node.name}' adapter must be a subclass of Igniter::Effect"
+            )
+          end
+
+          validate_parameters_signature!(
+            node,
+            adapter.instance_method(:call).parameters,
+            adapter.name || "effect"
+          )
+        end
+
         def validate_callable_signature!(node)
           callable = node.callable
 

data/lib/igniter/compiler/validators/dependencies_validator.rb

@@ -12,8 +12,10 @@ module Igniter
           @context = context
         end
 
-        def call
+        def call # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
           @context.runtime_nodes.each do |node|
+            next if node.kind == :await
+
             validate_composition_node!(node) if node.kind == :composition
             validate_branch_node!(node) if node.kind == :branch
             validate_collection_node!(node) if node.kind == :collection
@@ -40,6 +42,7 @@ module Igniter
           end
 
           validate_composition_input_mapping!(node, contract_class.compiled_graph)
+          validate_composition_cycle!(node)
         end
 
         def validate_composition_input_mapping!(node, child_graph)
@@ -126,6 +129,43 @@ module Igniter
           )
         end
 
+        def validate_composition_cycle!(node)
+          child_contract = node.contract_class
+          return unless child_contract.respond_to?(:compiled_graph) && child_contract.compiled_graph
+
+          current_name = @context.graph.name
+          # Skip anonymous contracts to avoid false positives when multiple
+          # anonymous contracts share the same name "AnonymousContract"
+          return if current_name == "AnonymousContract"
+
+          validate_direct_cycle!(node, child_contract, current_name)
+          validate_grandchild_cycles!(node, child_contract, current_name)
+        end
+
+        def validate_direct_cycle!(node, child_contract, current_name)
+          return unless child_contract.compiled_graph.name == current_name
+
+          raise @context.validation_error(
+            node,
+            "Composition cycle: '#{node.name}' composes '#{child_contract.name}' " \
+            "which is the same contract ('#{current_name}')"
+          )
+        end
+
+        def validate_grandchild_cycles!(node, child_contract, current_name) # rubocop:disable Metrics/AbcSize
+          child_contract.compiled_graph.nodes.select { |n| n.kind == :composition }.each do |grandchild|
+            next unless grandchild.contract_class.respond_to?(:compiled_graph)
+            next unless grandchild.contract_class.compiled_graph
+            next unless grandchild.contract_class.compiled_graph.name == current_name
+
+            raise @context.validation_error(
+              node,
+              "Composition cycle: '#{node.name}' -> '#{child_contract.name}' -> " \
+              "'#{grandchild.contract_class.name}' loops back to '#{current_name}'"
+            )
+          end
+        end
+
         def validate_collection_node!(node)
           unless node.contract_class.is_a?(Class) && node.contract_class <= Igniter::Contract
             raise @context.validation_error(node, "Collection '#{node.name}' must reference an Igniter::Contract subclass")

data/lib/igniter/compiler/validators/remote_validator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class RemoteValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          @context.runtime_nodes.each do |node|
+            next unless node.kind == :remote
+
+            validate_url!(node)
+            validate_contract_name!(node)
+            validate_dependencies!(node)
+          end
+        end
+
+        private
+
+        def validate_url!(node)
+          return if node.node_url.start_with?("http://", "https://")
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} has invalid node: URL '#{node.node_url}'. Must start with http:// or https://"
+          )
+        end
+
+        def validate_contract_name!(node)
+          return unless node.contract_name.strip.empty?
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} requires a non-empty contract: name"
+          )
+        end
+
+        def validate_dependencies!(node)
+          node.dependencies.each do |dep_name|
+            next if @context.dependency_resolvable?(dep_name)
+
+            raise @context.validation_error(
+              node,
+              "remote :#{node.name} depends on '#{dep_name}' which is not defined in the graph"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/compiler.rb

@@ -8,6 +8,8 @@ require_relative "compiler/validators/outputs_validator"
 require_relative "compiler/validators/dependencies_validator"
 require_relative "compiler/validators/callable_validator"
 require_relative "compiler/validators/type_compatibility_validator"
+require_relative "compiler/validators/await_validator"
+require_relative "compiler/validators/remote_validator"
 require_relative "compiler/validation_pipeline"
 require_relative "compiler/validator"
 require_relative "compiler/graph_compiler"

data/lib/igniter/contract.rb

@@ -3,8 +3,20 @@
 module Igniter
   class Contract
     class << self
+      def correlate_by(*keys)
+        @correlation_keys = keys.map(&:to_sym).freeze
+      end
+
+      def correlation_keys
+        @correlation_keys || []
+      end
+
       def define(&block)
-        @compiled_graph = DSL::ContractBuilder.compile(name: contract_name, &block)
+        @compiled_graph = DSL::ContractBuilder.compile(
+          name: contract_name,
+          correlation_keys: correlation_keys,
+          &block
+        )
       end
 
       def run_with(runner:, max_workers: nil)
@@ -28,6 +40,45 @@ module Igniter
         @compiled_graph = DSL::SchemaBuilder.compile(schema, name: contract_name)
       end
 
+      def start(inputs = {}, store: nil, **keyword_inputs)
+        resolved_store = store || Igniter.execution_store
+        all_inputs = inputs.merge(keyword_inputs)
+
+        instance = new(all_inputs, runner: :store, store: resolved_store)
+        instance.resolve_all
+
+        correlation = correlation_keys.each_with_object({}) do |key, hash|
+          hash[key] = all_inputs[key] || all_inputs[key.to_s]
+        end
+
+        resolved_store.save(instance.snapshot, correlation: correlation.compact, graph: contract_name)
+        instance
+      end
+
+      def deliver_event(event_name, correlation:, payload:, store: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        resolved_store = store || Igniter.execution_store
+        execution_id = resolved_store.find_by_correlation(
+          graph: contract_name,
+          correlation: correlation.transform_keys(&:to_sym)
+        )
+        unless execution_id
+          raise ResolutionError,
+                "No pending execution found for #{contract_name} with given correlation"
+        end
+
+        instance = restore_from_store(execution_id, store: resolved_store)
+
+        await_node = instance.execution.compiled_graph.await_nodes
+                             .find { |n| n.event_name == event_name.to_sym }
+        raise ResolutionError, "No await node found for event '#{event_name}' in #{contract_name}" unless await_node
+
+        instance.execution.resume(await_node.name, value: payload)
+        instance.resolve_all
+
+        resolved_store.save(instance.snapshot, correlation: correlation.transform_keys(&:to_sym), graph: contract_name)
+        instance
+      end
+
       def restore(snapshot)
         instance = new(
           snapshot[:inputs] || snapshot["inputs"] || {},
@@ -159,9 +210,9 @@ module Igniter
       end
     end
 
-    attr_reader :execution, :result
+    attr_reader :execution, :result, :reactive
 
-    def initialize(inputs = nil, runner: nil, max_workers: nil, **keyword_inputs)
+    def initialize(inputs = nil, runner: nil, max_workers: nil, store: nil, **keyword_inputs)
       graph = self.class.compiled_graph
       raise CompileError, "#{self.class.name} has no compiled graph. Use `define`." unless graph
 
@@ -175,7 +226,7 @@ module Igniter
         end
 
       execution_options = self.class.execution_options.merge(
-        { runner: runner, max_workers: max_workers }.compact
+        { runner: runner, max_workers: max_workers, store: store }.compact
       )
       execution_options[:store] ||= Igniter.execution_store if execution_options[:runner]&.to_sym == :store
 
@@ -220,10 +271,6 @@ module Igniter
       execution.audit.snapshot
     end
 
-    def reactive
-      @reactive
-    end
-
     def subscribe(subscriber = nil, &block)
       execution.events.subscribe(subscriber, &block)
       self
@@ -261,5 +308,9 @@ module Igniter
     def failed?
       execution.failed?
     end
+
+    def pending?
+      execution.pending?
+    end
   end
 end