igniter 0.3.1 → 0.4.3

data/lib/igniter/errors.rb

@@ -29,18 +29,23 @@ module Igniter
       context[:source_location]
     end
 
+    def execution_id
+      context[:execution_id]
+    end
+
     private
 
-    def format_message(message, context)
+    def format_message(message, context) # rubocop:disable Metrics/AbcSize
       details = []
       details << "graph=#{context[:graph]}" if context[:graph]
       details << "node=#{context[:node_name]}" if context[:node_name]
       details << "path=#{context[:node_path]}" if context[:node_path]
+      details << "execution=#{context[:execution_id]}" if context[:execution_id]
       details << "location=#{context[:source_location]}" if context[:source_location]
 
       return message if details.empty?
 
-      "#{message} [#{details.join(', ')}]"
+      "#{message} [#{details.join(", ")}]"
     end
   end
 
@@ -53,6 +58,7 @@ module Igniter
   class ResolutionError < Error; end
   class CompositionError < Error; end
   class BranchSelectionError < Error; end
+
   class PendingDependencyError < Error
     attr_reader :deferred_result
 
@@ -61,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)

data/lib/igniter/extensions/invariants.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/invariant"
+
+module Igniter
+  module Extensions
+    # Patches Igniter::Contract with:
+    #   - Class method: invariant(name) { |output:, **| condition }
+    #   - Instance method: check_invariants → Array<InvariantViolation>
+    #   - Automatic post-execution check in resolve_all (raises InvariantError)
+    #
+    # Invariant blocks receive ONLY the contract's declared output values as
+    # keyword args — the stable public interface, independent of internal nodes.
+    # Use ** to absorb outputs you don't need.
+    #
+    # @example
+    #   class PricingContract < Igniter::Contract
+    #     define do
+    #       input  :price
+    #       input  :quantity
+    #       compute :total, depends_on: %i[price quantity] do |price:, quantity:|
+    #         price * quantity
+    #       end
+    #       output :total
+    #     end
+    #
+    #     invariant(:total_non_negative) { |total:, **| total >= 0 }
+    #   end
+    #
+    # This module is applied globally via:
+    #   Igniter::Contract.include(Igniter::Extensions::Invariants)
+    #
+    module Invariants
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(InstanceMethods)
+      end
+
+      # ── Class-level DSL ──────────────────────────────────────────────────────
+
+      module ClassMethods
+        # Declare a condition that must always hold after successful execution.
+        #
+        # The block receives the contract's declared output values as keyword
+        # arguments; use ** to absorb outputs you don't care about. Return a
+        # truthy value to indicate the invariant holds, falsy to indicate
+        # a violation.
+        #
+        # @example
+        #   invariant(:positive_total) { |total:, **| total >= 0 }
+        #
+        # @param name [Symbol]
+        def invariant(name, &block)
+          @_invariants ||= {}
+          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
+        end
+
+        # @return [Hash{Symbol => Igniter::Invariant}]
+        def invariants
+          @_invariants || {}
+        end
+      end
+
+      # ── Instance override + new public method ───────────────────────────────
+
+      module InstanceMethods
+        # Intercepts resolve_all to run invariant checks after execution.
+        # Uses a thread-local flag so that property testing can disable the
+        # automatic raise and collect violations as data instead.
+        def resolve_all(...)
+          result = super
+          validate_invariants! unless Thread.current[:igniter_skip_invariants]
+          result
+        end
+
+        # Run all invariants without raising. Returns violations as data.
+        # Safe to call at any time after execution.
+        #
+        # @return [Array<Igniter::InvariantViolation>]
+        def check_invariants
+          return [] if self.class.invariants.empty?
+
+          resolved = collect_output_values
+          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
+        end
+
+        private
+
+        def validate_invariants!
+          violations = check_invariants
+          return if violations.empty?
+
+          names = violations.map { |v| ":#{v.name}" }.join(", ")
+          raise Igniter::InvariantError.new(
+            "#{violations.size} invariant(s) violated: #{names}",
+            violations: violations,
+            context: { contract: self.class.name }
+          )
+        end
+
+        # Collect all declared output values from the resolved cache.
+        # Keyed by output name (not source node name).
+        def collect_output_values
+          cache = execution.cache
+          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
+            state = cache.fetch(output_node.source_root)
+            acc[output_node.name] = state.value if state&.succeeded?
+          end
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Invariants)

data/lib/igniter/extensions/provenance.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../provenance"
+
+module Igniter
+  module Extensions
+    # Adds runtime provenance (data lineage) methods to Igniter::Contract.
+    #
+    # After requiring this file, every resolved contract gains two new methods:
+    #
+    #   contract.resolve_all
+    #
+    #   # Full Lineage object — query API
+    #   lin = contract.lineage(:grand_total)
+    #   lin.contributing_inputs        # => { base_price: 100.0, quantity: 2 }
+    #   lin.sensitive_to?(:base_price) # => true
+    #   lin.path_to(:base_price)       # => [:grand_total, :subtotal, :base_price]
+    #   lin.to_h                        # serialisable Hash
+    #
+    #   # Shorthand: human-readable ASCII tree printed to stdout
+    #   contract.explain(:grand_total)
+    #
+    module Provenance
+      # Return a Lineage object for the named output.
+      # Raises ProvenanceError if the output is unknown or the contract has not
+      # been executed (resolve_all has not been called).
+      def lineage(output_name)
+        unless execution
+          raise Igniter::Provenance::ProvenanceError,
+                "Contract has not been executed — call resolve_all first"
+        end
+
+        Igniter::Provenance::Builder.build(output_name, execution)
+      end
+
+      # Return a human-readable ASCII tree explaining how +output_name+ was derived.
+      def explain(output_name)
+        lineage(output_name).explain
+      end
+    end
+  end
+end
+
+# Patch Igniter::Contract so every contract instance gains the methods.
+Igniter::Contract.include(Igniter::Extensions::Provenance)

data/lib/igniter/extensions/saga.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/saga"
+
+module Igniter
+  module Extensions
+    # Adds saga/compensating-transaction support to all Igniter contracts.
+    #
+    # Class-level DSL:
+    #   compensate :node_name do |inputs:, value:| ... end
+    #
+    # Instance methods added:
+    #   resolve_saga → Igniter::Saga::Result
+    #
+    # Applied globally via:
+    #   Igniter::Contract.include(Igniter::Extensions::Saga)
+    #
+    module Saga
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # ── Class-level DSL ────────────────────────────────────────────────────
+
+      module ClassMethods
+        # Declare a compensating action for a compute node.
+        #
+        # The block is called with:
+        #   inputs: — Hash of the node's dependency values
+        #   value:  — the value the node produced (now being rolled back)
+        #
+        # @param node_name [Symbol]
+        def compensate(node_name, &block)
+          @_compensations ||= {}
+          @_compensations[node_name.to_sym] = Igniter::Saga::Compensation.new(node_name, &block)
+        end
+
+        # @return [Hash{ Symbol => Compensation }]
+        def compensations
+          @_compensations || {}
+        end
+      end
+
+      # ── Instance methods ───────────────────────────────────────────────────
+
+      # Execute the contract and handle compensations on failure.
+      #
+      # Unlike `resolve_all` (which raises on failure), `resolve_saga`:
+      #   - Returns a successful Result when execution completes
+      #   - Catches Igniter::Error, runs compensations, returns a failed Result
+      #
+      # @return [Igniter::Saga::Result]
+      def resolve_saga # rubocop:disable Metrics/MethodLength
+        resolve_all
+        Igniter::Saga::Result.new(success: true, contract: self)
+      rescue Igniter::Error => e
+        executor = Igniter::Saga::Executor.new(self)
+        compensations_ran = executor.run_compensations
+        failed_node = executor.failed_node_name
+
+        Igniter::Saga::Result.new(
+          success: false,
+          contract: self,
+          error: e,
+          failed_node: failed_node,
+          compensations: compensations_ran
+        )
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Saga)

data/lib/igniter/integrations/agents.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Actor system for Igniter — stateful message-driven agents with supervision.
+#
+# Usage:
+#   require "igniter/integrations/agents"
+#
+# Provides:
+#   Igniter::Agent      — base class for stateful actors
+#   Igniter::Supervisor — supervises and restarts child agents
+#   Igniter::Registry   — thread-safe name → Ref lookup
+#   Igniter::StreamLoop — continuous contract-in-a-tick-loop
+#
+
+require_relative "../agent"
+require_relative "../supervisor"
+require_relative "../registry"
+require_relative "../stream_loop"