igniter 0.4.0 → 0.4.3

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

@@ -248,6 +248,21 @@ module Igniter
         )
       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(
@@ -306,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

data/lib/igniter/errors.rb

@@ -45,7 +45,7 @@ module Igniter
 
       return message if details.empty?
 
-      "#{message} [#{details.join(', ')}]"
+      "#{message} [#{details.join(", ")}]"
     end
   end
 
@@ -58,6 +58,7 @@ module Igniter
   class ResolutionError < Error; end
   class CompositionError < Error; end
   class BranchSelectionError < Error; end
+
   class PendingDependencyError < Error
     attr_reader :deferred_result
 
@@ -66,4 +67,13 @@ module Igniter
       super(message, context: context)
     end
   end
+
+  class InvariantError < Error
+    attr_reader :violations
+
+    def initialize(message = nil, violations: [], context: {})
+      @violations = violations.freeze
+      super(message, context: context)
+    end
+  end
 end

data/lib/igniter/execution_report/builder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Igniter
+  module ExecutionReport
+    # Builds an ExecutionReport::Report by reading the compiled graph's
+    # resolution order and matching each node against the execution cache.
+    #
+    # Works for both successful and failed executions — nodes that never
+    # ran (because a dependency failed) appear with status :pending.
+    class Builder
+      class << self
+        def build(contract)
+          new(contract).build
+        end
+      end
+
+      def initialize(contract)
+        @contract = contract
+        @graph    = contract.execution.compiled_graph
+        @cache    = contract.execution.cache
+      end
+
+      def build
+        entries = @graph.resolution_order.map { |node| entry_for(node) }
+        Report.new(contract_class: @contract.class, entries: entries)
+      end
+
+      private
+
+      def entry_for(node) # rubocop:disable Metrics/MethodLength
+        state = @cache.fetch(node.name)
+
+        status = if state.nil?
+                   :pending
+                 elsif state.succeeded?
+                   :succeeded
+                 elsif state.failed?
+                   :failed
+                 else
+                   :pending
+                 end
+
+        NodeEntry.new(
+          name: node.name,
+          kind: node.kind,
+          status: status,
+          value: state&.value,
+          error: state&.error,
+          effect_type: node.respond_to?(:effect_type) ? node.effect_type : nil
+        )
+      end
+    end
+  end
+end

data/lib/igniter/execution_report/formatter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Igniter
+  module ExecutionReport
+    # Formats an ExecutionReport::Report as human-readable text.
+    #
+    # Example:
+    #
+    #   Contract: OrderWorkflow
+    #   Success:  NO
+    #
+    #     [ok]     input      :order_id
+    #     [ok]     input      :amount
+    #     [ok]     compute    :reserve_stock
+    #     [fail]   compute    :charge_card
+    #                error: Insufficient funds
+    #     [pend]   compute    :send_confirmation
+    #
+    module Formatter
+      class << self
+        def format(report)
+          lines = []
+          lines << "Contract: #{report.contract_class.name}"
+          lines << "Success:  #{report.success? ? "YES" : "NO"}"
+          lines << ""
+
+          report.entries.each do |entry|
+            append_entry(entry, lines)
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def append_entry(entry, lines)
+          tag = case entry.status
+                when :succeeded then "[ok]  "
+                when :failed    then "[fail]"
+                else                 "[pend]"
+                end
+          kind_label = entry.effect_type ? "effect:#{entry.effect_type}" : entry.kind.to_s
+          kind_str = kind_label.ljust(10)
+          lines << "  #{tag}  #{kind_str}  :#{entry.name}"
+          lines << "               error: #{entry.error.message}" if entry.failed? && entry.error
+        end
+      end
+    end
+  end
+end

data/lib/igniter/execution_report/node_entry.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Igniter
+  module ExecutionReport
+    # Snapshot of a single node's execution state.
+    class NodeEntry
+      attr_reader :name, :kind, :status, :value, :error, :effect_type
+
+      def initialize(name:, kind:, status:, value: nil, error: nil, effect_type: nil) # rubocop:disable Metrics/ParameterLists
+        @name        = name
+        @kind        = kind
+        @status      = status
+        @value       = value
+        @error       = error
+        @effect_type = effect_type
+        freeze
+      end
+
+      def succeeded? = status == :succeeded
+      def failed?    = status == :failed
+      def pending?   = !succeeded? && !failed?
+    end
+  end
+end

data/lib/igniter/execution_report/report.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Igniter
+  module ExecutionReport
+    # Structured post-hoc report of what happened during contract execution.
+    #
+    # Built from the compiled graph's resolution order + execution cache state.
+    # Can be generated any time after resolve_all (including after an error).
+    #
+    # Attributes:
+    #   contract_class — the contract class that was executed
+    #   entries        — Array<NodeEntry> in resolution order
+    class Report
+      attr_reader :contract_class, :entries
+
+      def initialize(contract_class:, entries:)
+        @contract_class = contract_class
+        @entries        = entries.freeze
+        freeze
+      end
+
+      # True when no nodes failed.
+      def success?
+        entries.none?(&:failed?)
+      end
+
+      # Symbol names of nodes that succeeded.
+      def resolved_nodes
+        entries.select(&:succeeded?).map(&:name)
+      end
+
+      # Symbol names of nodes that failed.
+      def failed_nodes
+        entries.select(&:failed?).map(&:name)
+      end
+
+      # Symbol names of nodes that never ran.
+      def pending_nodes
+        entries.select(&:pending?).map(&:name)
+      end
+
+      # Map of { node_name => error } for failed nodes.
+      def errors
+        entries.select(&:failed?).each_with_object({}) { |e, h| h[e.name] = e.error }
+      end
+
+      # Human-readable execution report.
+      def explain
+        Formatter.format(self)
+      end
+
+      alias to_s explain
+
+      def to_h
+        {
+          contract: contract_class.name,
+          success: success?,
+          nodes: entries.map do |e|
+            { name: e.name, kind: e.kind, status: e.status, error: e.error&.message }
+          end
+        }
+      end
+    end
+  end
+end

data/lib/igniter/execution_report.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "execution_report/node_entry"
+require_relative "execution_report/formatter"
+require_relative "execution_report/report"
+require_relative "execution_report/builder"
+
+module Igniter
+  # Post-hoc execution report — answers "what ran, what succeeded, what failed?"
+  #
+  # Reconstructs a structured timeline from the compiled graph's resolution
+  # order and the execution cache.  Works regardless of whether the contract
+  # succeeded or raised an error.
+  #
+  # Usage:
+  #
+  #   require "igniter/extensions/execution_report"
+  #
+  #   contract = MyContract.new(inputs)
+  #   contract.resolve_all rescue nil   # run regardless of outcome
+  #
+  #   report = contract.execution_report
+  #   report.success?         # => false
+  #   report.failed_nodes     # => [:charge_card]
+  #   report.pending_nodes    # => [:send_confirmation]
+  #   puts report.explain     # formatted table
+  #
+  module ExecutionReport
+    class ExecutionReportError < Igniter::Error; end
+  end
+end

data/lib/igniter/extensions/differential.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/differential"
+
+module Igniter
+  module Extensions
+    # Patches Igniter::Contract with:
+    #   - Class method: shadow_with(candidate, async:, on_divergence:, tolerance:)
+    #   - Instance method: diff_against(candidate_class, tolerance:)
+    #   - Automatic shadow execution after resolve_all (when shadow_with is declared)
+    #
+    # This module is applied globally via:
+    #   Igniter::Contract.include(Igniter::Extensions::Differential)
+    #
+    module Differential
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(InstanceMethods)
+      end
+
+      # ── Class-level DSL ────────────────────────────────────────────────────
+
+      module ClassMethods
+        # Declare a shadow candidate that runs alongside every resolve_all call.
+        #
+        # @param candidate_class [Class<Igniter::Contract>]
+        # @param async [Boolean]  run the shadow in a background Thread
+        # @param on_divergence [#call, nil] invoked with a Report when outputs differ
+        # @param tolerance [Numeric, nil]  passed to the differential runner
+        def shadow_with(candidate_class, async: false, on_divergence: nil, tolerance: nil)
+          @_shadow_candidate = candidate_class
+          @_shadow_async = async
+          @_shadow_on_divergence = on_divergence
+          @_shadow_tolerance = tolerance
+        end
+
+        def shadow_candidate = @_shadow_candidate
+        def shadow_async? = @_shadow_async || false
+        def shadow_on_divergence = @_shadow_on_divergence
+        def shadow_tolerance = @_shadow_tolerance
+      end
+
+      # ── Instance override + new public method ─────────────────────────────
+
+      module InstanceMethods
+        # Intercepts resolve_all to trigger shadow execution when shadow_with
+        # has been declared.  Uses a thread-local flag to prevent recursive
+        # shadow calls when the runner itself invokes resolve_all internally.
+        def resolve_all(...)
+          result = super
+          run_shadow unless Thread.current[:igniter_skip_shadow]
+          result
+        end
+
+        # Compare the already-executed primary contract against +candidate_class+.
+        # Avoids re-running the primary (reads outputs from the existing cache).
+        #
+        # Raises DifferentialError if resolve_all has not been called yet.
+        #
+        # @return [Igniter::Differential::Report]
+        def diff_against(candidate_class, tolerance: nil)
+          unless execution.cache.values.any?
+            raise Igniter::Differential::DifferentialError,
+                  "Contract has not been executed — call resolve_all first"
+          end
+
+          inputs = extract_inputs_from_execution
+          runner = Igniter::Differential::Runner.new(self.class, candidate_class, tolerance: tolerance)
+          runner.run_with_primary_execution(execution, inputs)
+        end
+
+        private
+
+        def run_shadow # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          candidate = self.class.shadow_candidate
+          return unless candidate
+
+          on_divergence = self.class.shadow_on_divergence
+          tolerance = self.class.shadow_tolerance
+          inputs = extract_inputs_from_execution
+
+          task = lambda do
+            runner = Igniter::Differential::Runner.new(self.class, candidate, tolerance: tolerance)
+            report = runner.run_with_primary_execution(execution, inputs)
+            on_divergence.call(report) if on_divergence && !report.match?
+          end
+
+          if self.class.shadow_async?
+            Thread.new { task.call }
+          else
+            task.call
+          end
+        end
+
+        # Reads input node values from the resolved cache for re-use in
+        # secondary executions (shadow / diff_against).
+        def extract_inputs_from_execution
+          graph = execution.compiled_graph
+          cache = execution.cache
+
+          graph.nodes.each_with_object({}) do |node, acc|
+            next unless node.kind == :input
+
+            state = cache.fetch(node.name)
+            acc[node.name] = state&.value
+          end
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Differential)

data/lib/igniter/extensions/execution_report.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/execution_report"
+
+module Igniter
+  module Extensions
+    # Adds execution_report method to all Igniter contracts.
+    #
+    # Applied globally via:
+    #   Igniter::Contract.include(Igniter::Extensions::ExecutionReport)
+    #
+    module ExecutionReport
+      # Build a structured execution report from the current execution state.
+      #
+      # Can be called after resolve_all succeeds OR after it raises — in both
+      # cases the cache contains partial or full execution state.
+      #
+      # @return [Igniter::ExecutionReport::Report]
+      def execution_report
+        Igniter::ExecutionReport::Builder.build(self)
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::ExecutionReport)