igniter 0.3.1 → 0.4.3

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

data/lib/igniter/differential/runner.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Differential
+    # Executes two contract classes with identical inputs and builds a Report.
+    #
+    # Uses Thread.current[:igniter_skip_shadow] to prevent recursive shadow
+    # execution when a contract with shadow_with is run inside the runner.
+    class Runner
+      def initialize(primary_class, candidate_class, tolerance: nil)
+        @primary_class = primary_class
+        @candidate_class = candidate_class
+        @tolerance = tolerance
+      end
+
+      # Execute both contracts fresh from +inputs+ and compare outputs.
+      def run(inputs)
+        primary_exec, primary_error = execute(@primary_class, inputs)
+        candidate_exec, candidate_error = execute(@candidate_class, inputs)
+
+        primary_outputs = primary_exec ? extract_outputs(primary_exec) : {}
+        candidate_outputs = candidate_exec ? extract_outputs(candidate_exec) : {}
+
+        build_report(primary_outputs, candidate_outputs, inputs, primary_error, candidate_error)
+      end
+
+      # Compare using an already-resolved primary execution (avoids re-running
+      # the primary contract and its side effects a second time).
+      def run_with_primary_execution(primary_execution, inputs)
+        primary_outputs = extract_outputs(primary_execution)
+        candidate_exec, candidate_error = execute(@candidate_class, inputs)
+        candidate_outputs = candidate_exec ? extract_outputs(candidate_exec) : {}
+
+        build_report(primary_outputs, candidate_outputs, inputs, nil, candidate_error)
+      end
+
+      private
+
+      # Execute +klass+ with +inputs+, suppressing shadow execution to prevent
+      # recursive comparisons.  Returns [execution, nil] on success or
+      # [nil, error] if the contract raises.
+      def execute(klass, inputs)
+        Thread.current[:igniter_skip_shadow] = true
+        contract = klass.new(inputs)
+        contract.resolve_all
+        [contract.execution, nil]
+      rescue Igniter::Error => e
+        [nil, e]
+      ensure
+        Thread.current[:igniter_skip_shadow] = nil
+      end
+
+      # Read all output values from a resolved execution's cache.
+      # Output nodes live in graph.outputs (not graph.nodes).
+      # Each output node's source_root (Symbol) names the computation node in cache.
+      def extract_outputs(execution)
+        graph = execution.compiled_graph
+        cache = execution.cache
+
+        graph.outputs.each_with_object({}) do |node, acc|
+          state = cache.fetch(node.source_root)
+          acc[node.name] = normalize_value(state&.value)
+        end
+      end
+
+      # Flatten Runtime wrapper objects to plain Ruby values so that structural
+      # equality works across independently-resolved executions.
+      def normalize_value(val)
+        case val
+        when Runtime::Result           then val.to_h
+        when Runtime::CollectionResult then val.summary
+        when Runtime::DeferredResult   then { pending: true, event: val.waiting_on }
+        else val
+        end
+      end
+
+      def build_report(primary_outputs, candidate_outputs, inputs, primary_error, candidate_error) # rubocop:disable Metrics/MethodLength
+        common = primary_outputs.keys & candidate_outputs.keys
+        divergences = compare_common(primary_outputs, candidate_outputs, common)
+        primary_only = slice_missing(primary_outputs, candidate_outputs)
+        candidate_only = slice_missing(candidate_outputs, primary_outputs)
+
+        Report.new(
+          primary_class: @primary_class,
+          candidate_class: @candidate_class,
+          inputs: inputs,
+          divergences: divergences,
+          primary_only: primary_only,
+          candidate_only: candidate_only,
+          primary_error: primary_error,
+          candidate_error: candidate_error
+        )
+      end
+
+      # Build Divergence objects for keys present in both hashes but with
+      # differing values.
+      def compare_common(primary, candidate, keys) # rubocop:disable Metrics/MethodLength
+        keys.filter_map do |key|
+          pval = primary[key]
+          cval = candidate[key]
+          next if values_match?(pval, cval)
+
+          Divergence.new(
+            output_name: key,
+            primary_value: pval,
+            candidate_value: cval,
+            kind: divergence_kind(pval, cval)
+          )
+        end
+      end
+
+      # Returns a hash of keys that exist in +source+ but are absent in +other+.
+      def slice_missing(source, other)
+        (source.keys - other.keys).each_with_object({}) { |k, h| h[k] = source[k] }
+      end
+
+      def values_match?(lhs, rhs)
+        return true if lhs == rhs
+        return false unless @tolerance
+        return false unless lhs.is_a?(Numeric) && rhs.is_a?(Numeric)
+
+        (lhs - rhs).abs <= @tolerance
+      end
+
+      def divergence_kind(lhs, rhs)
+        lhs.instance_of?(rhs.class) ? :value_mismatch : :type_mismatch
+      end
+    end
+  end
+end

data/lib/igniter/differential.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "differential/divergence"
+require_relative "differential/report"
+require_relative "differential/formatter"
+require_relative "differential/runner"
+
+module Igniter
+  # Differential Execution — compare two contract implementations output-by-output.
+  #
+  # Usage:
+  #
+  #   require "igniter/extensions/differential"
+  #
+  #   # Standalone comparison
+  #   report = Igniter::Differential.compare(
+  #     primary:   PricingV1,
+  #     candidate: PricingV2,
+  #     inputs:    { price: 50.0, quantity: 3 }
+  #   )
+  #   puts report.explain
+  #   puts report.match?          # => false
+  #   puts report.divergences     # => [#<Divergence ...>]
+  #
+  #   # Per-instance diff (primary already resolved)
+  #   contract = PricingV1.new(price: 50.0, quantity: 3)
+  #   contract.resolve_all
+  #   report = contract.diff_against(PricingV2)
+  #
+  #   # Shadow mode (runs candidate alongside primary automatically)
+  #   class PricingContract < Igniter::Contract
+  #     shadow_with PricingV2, on_divergence: ->(r) { Rails.logger.warn(r.summary) }
+  #     define { ... }
+  #   end
+  #
+  module Differential
+    class DifferentialError < Igniter::Error; end
+
+    # Compare +primary+ and +candidate+ contract classes on the given +inputs+.
+    #
+    # @param primary   [Class<Igniter::Contract>]
+    # @param candidate [Class<Igniter::Contract>]
+    # @param inputs    [Hash]
+    # @param tolerance [Numeric, nil] optional allowable numeric difference
+    # @return [Report]
+    def self.compare(primary:, candidate:, inputs:, tolerance: nil)
+      Runner.new(primary, candidate, tolerance: tolerance).run(inputs)
+    end
+  end
+end

data/lib/igniter/dsl/contract_builder.rb

@@ -3,12 +3,13 @@
 module Igniter
   module DSL
     class ContractBuilder
-      def self.compile(name: "AnonymousContract", &block)
-        new(name: name).tap { |builder| builder.instance_eval(&block) }.compile
+      def self.compile(name: "AnonymousContract", correlation_keys: [], &block)
+        new(name: name, correlation_keys: correlation_keys).tap { |builder| builder.instance_eval(&block) }.compile
       end
 
-      def initialize(name:)
+      def initialize(name:, correlation_keys: [])
         @name = name
+        @correlation_keys = correlation_keys
         @nodes = []
         @sequence = 0
         @scope_stack = []
@@ -228,8 +229,60 @@ module Igniter
         )
       end
 
+      def remote(name, contract:, node:, inputs:, timeout: 30, **metadata) # rubocop:disable Metrics/MethodLength
+        raise CompileError, "remote :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
+        raise CompileError, "remote :#{name} requires a contract: name" if contract.nil? || contract.to_s.strip.empty?
+        raise CompileError, "remote :#{name} requires a node: URL"     if node.nil?    || node.to_s.strip.empty?
+
+        add_node(
+          Model::RemoteNode.new(
+            id: next_id,
+            name: name.to_sym,
+            contract_name: contract.to_s,
+            node_url: node.to_s,
+            input_mapping: inputs,
+            timeout: timeout,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def effect(name, uses:, depends_on: nil, with: nil, **metadata)
+        adapter_class = resolve_effect_adapter(name, uses)
+
+        add_node(
+          Model::EffectNode.new(
+            id: next_id,
+            name: name,
+            dependencies: normalize_dependencies(depends_on: depends_on, with: with),
+            adapter_class: adapter_class,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def await(name, event:, **metadata)
+        add_node(
+          Model::AwaitNode.new(
+            id: next_id,
+            name: name.to_sym,
+            path: scoped_path(name),
+            event_name: event,
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
       def compile
-        Compiler::GraphCompiler.call(Model::Graph.new(name: @name, nodes: @nodes))
+        Compiler::GraphCompiler.call(
+          Model::Graph.new(
+            name: @name,
+            nodes: @nodes,
+            metadata: { correlation_keys: @correlation_keys || [] }
+          )
+        )
       end
 
       private
@@ -268,6 +321,23 @@ module Igniter
         Array(dependencies)
       end
 
+      def resolve_effect_adapter(name, uses)
+        case uses
+        when Symbol, String
+          Igniter.effect_registry.fetch(uses.to_sym).adapter_class
+        when Class
+          unless uses <= Igniter::Effect
+            raise CompileError,
+                  "effect :#{name} `uses:` must be an Igniter::Effect subclass or a registered effect name"
+          end
+
+          uses
+        else
+          raise CompileError,
+                "effect :#{name} `uses:` must be an Igniter::Effect subclass or a registered effect name"
+        end
+      end
+
       def build_guard_matcher(matcher_name, matcher_value, dependency)
         case matcher_name
         when :eq

data/lib/igniter/effect.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Base class for side-effect adapters.
+  #
+  # An Effect is a first-class node in the computation graph that encapsulates
+  # an external interaction — database, HTTP call, cache write, queue publish, etc.
+  #
+  # Effects are declared in contracts via the `effect` DSL keyword:
+  #
+  #   class UserRepository < Igniter::Effect
+  #     effect_type :database
+  #     idempotent  false
+  #
+  #     def call(user_id:)
+  #       { id: user_id, name: DB.find(user_id) }
+  #     end
+  #
+  #     compensate do |inputs:, value:|
+  #       DB.delete(value[:id])
+  #     end
+  #   end
+  #
+  #   class MyContract < Igniter::Contract
+  #     define do
+  #       input  :user_id
+  #       effect :user_data, uses: UserRepository, depends_on: :user_id
+  #       output :user_data
+  #     end
+  #   end
+  #
+  # Effects participate fully in the graph:
+  #   - Dependency resolution and topological ordering
+  #   - Execution reports (shown as `effect:database`)
+  #   - Saga compensations (built-in or contract-level)
+  #   - Provenance tracing
+  class Effect < Executor
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@effect_type, @effect_type)
+        subclass.instance_variable_set(:@idempotent, @idempotent || false)
+        subclass.instance_variable_set(:@_built_in_compensation, @_built_in_compensation)
+      end
+
+      # Declares the category of side effect (e.g., :database, :http, :cache).
+      # Shown in execution reports as `effect:<type>`.
+      #
+      # @param value [Symbol, nil] — omit to read current value
+      # @return [Symbol]
+      def effect_type(value = nil)
+        return @effect_type || :generic if value.nil?
+
+        @effect_type = value.to_sym
+      end
+
+      # Marks this effect as idempotent — safe to retry without side effects.
+      # Informational metadata; does not change execution behaviour.
+      #
+      # @param value [Boolean]
+      def idempotent(value = true) # rubocop:disable Style/OptionalBooleanParameter
+        @idempotent = value
+      end
+
+      # @return [Boolean]
+      def idempotent?
+        @idempotent || false
+      end
+
+      # Declares a built-in compensating action for this effect.
+      #
+      # Called automatically during a Saga rollback when this effect succeeded
+      # but a downstream node failed. A contract-level `compensate :node_name`
+      # block takes precedence over the built-in one.
+      #
+      # The block receives:
+      #   inputs: — Hash of the node's dependency values when it ran
+      #   value:  — the value produced by this effect (now being undone)
+      def compensate(&block)
+        raise ArgumentError, "Effect.compensate requires a block" unless block
+
+        @_built_in_compensation = block
+      end
+
+      # @return [Proc, nil]
+      def built_in_compensation
+        @_built_in_compensation
+      end
+    end
+  end
+end

data/lib/igniter/effect_registry.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Registry for named effect adapters.
+  #
+  # Allows registering effects by symbolic keys and resolving them in the DSL:
+  #
+  #   Igniter.register_effect(:users_db, UserRepository)
+  #
+  #   # In a contract:
+  #   effect :user_data, uses: :users_db, depends_on: :user_id
+  #
+  # This decouples contracts from concrete adapter classes and enables
+  # environment-specific swaps (e.g. mock adapters in tests):
+  #
+  #   # In spec_helper.rb:
+  #   Igniter.effect_registry.clear
+  #   Igniter.register_effect(:users_db, FakeUserRepository)
+  class EffectRegistry
+    Registration = Struct.new(:key, :adapter_class, :metadata, keyword_init: true)
+
+    def initialize
+      @entries = {}
+    end
+
+    # Register an effect adapter under a symbolic key.
+    #
+    # @param key           [Symbol, String]
+    # @param adapter_class [Class] must be a subclass of Igniter::Effect
+    # @param metadata      [Hash]  optional arbitrary metadata
+    # @return [self]
+    def register(key, adapter_class, **metadata)
+      key = key.to_sym
+      unless adapter_class.is_a?(Class) && adapter_class <= Igniter::Effect
+        raise ArgumentError, "#{adapter_class.inspect} must be a subclass of Igniter::Effect"
+      end
+
+      @entries[key] = Registration.new(key: key, adapter_class: adapter_class, metadata: metadata.freeze)
+      self
+    end
+
+    # Fetch a registration by key.
+    #
+    # @param key [Symbol, String]
+    # @return [Registration]
+    # @raise [KeyError] if not registered
+    def fetch(key)
+      @entries.fetch(key.to_sym) do
+        raise KeyError,
+              "Effect '#{key}' is not registered. " \
+              "Use Igniter.register_effect(:#{key}, AdapterClass) before compiling."
+      end
+    end
+
+    # @param key [Symbol, String]
+    # @return [Boolean]
+    def registered?(key)
+      @entries.key?(key.to_sym)
+    end
+
+    # @return [Array<Registration>]
+    def all
+      @entries.values.freeze
+    end
+
+    # @return [Integer]
+    def size
+      @entries.size
+    end
+
+    # Remove all registrations. Useful in tests.
+    # @return [self]
+    def clear
+      @entries.clear
+      self
+    end
+  end
+end