igniter 0.4.0 → 0.4.5

data/lib/igniter/agent/ref.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # External handle to a running agent.
+    #
+    # Callers interact with agents exclusively through Ref — they never touch
+    # the Mailbox, StateHolder, or Thread directly. This allows the Supervisor
+    # to swap out internals on restart without invalidating existing Ref objects.
+    class Ref
+      def initialize(thread:, mailbox:, state_holder:)
+        @thread        = thread
+        @mailbox       = mailbox
+        @state_holder  = state_holder
+        @mutex         = Mutex.new
+      end
+
+      # Asynchronous fire-and-forget. Returns self.
+      def send(type, payload = {})
+        mailbox.push(Message.new(type: type.to_sym, payload: payload))
+        self
+      end
+
+      # Synchronous request-reply. Blocks until the handler responds or timeout
+      # elapses. Raises Igniter::Agent::TimeoutError on timeout.
+      def call(type, payload = {}, timeout: 5)
+        reply_box = Mailbox.new(capacity: 1, overflow: :drop_newest)
+        mailbox.push(Message.new(type: type.to_sym, payload: payload, reply_to: reply_box))
+        reply = reply_box.pop(timeout: timeout)
+        raise TimeoutError, "Agent did not reply within #{timeout}s" unless reply
+
+        reply.payload[:value]
+      end
+
+      # Request graceful shutdown. Closes the mailbox so the runner exits after
+      # processing any in-flight message. Blocks until the thread finishes.
+      def stop(timeout: 5)
+        mailbox.close
+        thread&.join(timeout)
+        self
+      end
+
+      # Forcefully terminate the agent thread.
+      def kill
+        thread&.kill
+        mailbox.close
+        self
+      end
+
+      def alive?
+        thread&.alive? || false
+      end
+
+      # Read the current state snapshot without blocking the agent.
+      def state
+        state_holder.get
+      end
+
+      # Supervisor-internal: swap out internals when the agent restarts.
+      # Callers keep the same Ref object; the new thread/mailbox/state_holder
+      # are transparently injected.
+      def rebind(thread:, mailbox:, state_holder:)
+        @mutex.synchronize do
+          @thread        = thread
+          @mailbox       = mailbox
+          @state_holder  = state_holder
+        end
+        self
+      end
+
+      private
+
+      def thread
+        @mutex.synchronize { @thread }
+      end
+
+      def mailbox
+        @mutex.synchronize { @mailbox }
+      end
+
+      def state_holder
+        @mutex.synchronize { @state_holder }
+      end
+    end
+  end
+end

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/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/differential/divergence.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Differential
+    # Captures a single output that differed between primary and candidate.
+    class Divergence
+      attr_reader :output_name, :primary_value, :candidate_value, :kind
+
+      # @param output_name [Symbol]
+      # @param primary_value [Object]
+      # @param candidate_value [Object]
+      # @param kind [Symbol] :value_mismatch | :type_mismatch
+      def initialize(output_name:, primary_value:, candidate_value:, kind:)
+        @output_name = output_name
+        @primary_value = primary_value
+        @candidate_value = candidate_value
+        @kind = kind
+        freeze
+      end
+
+      # Numeric difference (candidate − primary). nil for non-numeric values.
+      def delta
+        return nil unless primary_value.is_a?(Numeric) && candidate_value.is_a?(Numeric)
+
+        candidate_value - primary_value
+      end
+    end
+  end
+end

data/lib/igniter/differential/formatter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Differential
+    # Renders a Differential::Report as a human-readable text block.
+    #
+    # Example:
+    #
+    #   Primary:    PricingV1
+    #   Candidate:  PricingV2
+    #   Match:      NO
+    #
+    #   DIVERGENCES (1):
+    #     :tax
+    #       primary:   15.0
+    #       candidate: 22.5
+    #       delta:     +7.5
+    #
+    #   CANDIDATE ONLY (1):
+    #     :discount = 10.0
+    #
+    module Formatter
+      VALUE_MAX = 60
+
+      class << self
+        def format(report) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          lines = []
+          lines << "Primary:    #{report.primary_class.name}"
+          lines << "Candidate:  #{report.candidate_class.name}"
+          lines << "Match:      #{report.match? ? "YES" : "NO"}"
+
+          if report.primary_error
+            lines << ""
+            lines << "PRIMARY ERROR: #{report.primary_error.message}"
+            return lines.join("\n")
+          end
+
+          if report.candidate_error
+            lines << ""
+            lines << "CANDIDATE ERROR: #{report.candidate_error.message}"
+          end
+
+          lines << ""
+
+          if report.divergences.empty? && report.primary_only.empty? && report.candidate_only.empty?
+            lines << "All shared outputs match."
+          else
+            append_divergences(report, lines)
+            append_only_section("CANDIDATE ONLY", report.candidate_only, lines)
+            append_only_section("PRIMARY ONLY", report.primary_only, lines)
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def append_divergences(report, lines) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          return if report.divergences.empty?
+
+          lines << "DIVERGENCES (#{report.divergences.size}):"
+          report.divergences.each do |div|
+            lines << "  :#{div.output_name}"
+            lines << "    primary:   #{fmt(div.primary_value)}"
+            lines << "    candidate: #{fmt(div.candidate_value)}"
+            next unless div.delta
+
+            d = div.delta
+            lines << "    delta:     #{d >= 0 ? "+#{d}" : d}"
+          end
+          lines << ""
+        end
+
+        def append_only_section(label, hash, lines)
+          return if hash.empty?
+
+          lines << "#{label} (#{hash.size}):"
+          hash.each { |name, val| lines << "  :#{name} = #{fmt(val)}" }
+          lines << ""
+        end
+
+        def fmt(value) # rubocop:disable Metrics/CyclomaticComplexity
+          str = case value
+                when nil    then "nil"
+                when String then value.inspect
+                when Symbol then value.inspect
+                when Hash   then "{#{value.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
+                when Array  then "[#{value.map(&:inspect).join(", ")}]"
+                else             value.inspect
+                end
+          str.length > VALUE_MAX ? "#{str[0, VALUE_MAX - 3]}..." : str
+        end
+      end
+    end
+  end
+end

data/lib/igniter/differential/report.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Differential
+    # Structured result of comparing two contract implementations.
+    #
+    # Attributes:
+    #   primary_class    — the reference contract class
+    #   candidate_class  — the contract being validated against the primary
+    #   inputs           — Hash of inputs used for both executions
+    #   divergences      — Array<Divergence> for outputs that differ in value
+    #   primary_only     — Hash{ Symbol => value } outputs absent in candidate
+    #   candidate_only   — Hash{ Symbol => value } outputs absent in primary
+    #   primary_error    — Igniter::Error raised by primary (usually nil)
+    #   candidate_error  — Igniter::Error raised by candidate (nil on success)
+    class Report
+      attr_reader :primary_class, :candidate_class, :inputs,
+                  :divergences, :primary_only, :candidate_only,
+                  :primary_error, :candidate_error
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        primary_class:, candidate_class:, inputs:,
+        divergences:, primary_only:, candidate_only:,
+        primary_error: nil, candidate_error: nil
+      )
+        @primary_class = primary_class
+        @candidate_class = candidate_class
+        @inputs = inputs
+        @divergences = divergences.freeze
+        @primary_only = primary_only.freeze
+        @candidate_only = candidate_only.freeze
+        @primary_error = primary_error
+        @candidate_error = candidate_error
+        freeze
+      end
+
+      # True when candidate produces identical outputs with no errors.
+      def match?
+        divergences.empty? &&
+          primary_only.empty? &&
+          candidate_only.empty? &&
+          primary_error.nil? &&
+          candidate_error.nil?
+      end
+
+      # One-line summary suitable for logging.
+      def summary # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        if match?
+          "match"
+        else
+          parts = []
+          parts << "#{divergences.size} value(s) differ" if divergences.any?
+          parts << "#{primary_only.size} output(s) only in primary" if primary_only.any?
+          parts << "#{candidate_only.size} output(s) only in candidate" if candidate_only.any?
+          parts << "candidate error: #{candidate_error.message}" if candidate_error
+          parts << "primary error: #{primary_error.message}" if primary_error
+          "diverged — #{parts.join(", ")}"
+        end
+      end
+
+      # Human-readable ASCII report.
+      def explain
+        Formatter.format(self)
+      end
+
+      alias to_s explain
+
+      # Structured (serialisable) representation.
+      def to_h # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        {
+          primary: primary_class.name,
+          candidate: candidate_class.name,
+          match: match?,
+          divergences: divergences.map do |d|
+            { output: d.output_name, primary: d.primary_value, candidate: d.candidate_value,
+              kind: d.kind, delta: d.delta }
+          end,
+          primary_only: primary_only,
+          candidate_only: candidate_only,
+          primary_error: primary_error&.message,
+          candidate_error: candidate_error&.message
+        }
+      end
+    end
+  end
+end