igniter 0.4.0 → 0.4.3

data/lib/igniter/property_testing.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/extensions/invariants"
+require "igniter/property_testing/generators"
+require "igniter/property_testing/run"
+require "igniter/property_testing/result"
+require "igniter/property_testing/formatter"
+require "igniter/property_testing/runner"
+
+module Igniter
+  # Property-based testing for Igniter contracts.
+  #
+  # Generates hundreds of random inputs, runs the contract with each set,
+  # and verifies that all declared invariants hold. Violations are collected
+  # as data so you can inspect the first counterexample.
+  #
+  # @example
+  #   require "igniter/property_testing"
+  #
+  #   G = Igniter::PropertyTesting::Generators
+  #
+  #   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
+  #
+  #   result = PricingContract.property_test(
+  #     generators: { price: G.float(0.0..500.0), quantity: G.positive_integer(max: 100) },
+  #     runs: 200,
+  #     seed: 42
+  #   )
+  #
+  #   puts result.explain
+  #   puts result.counterexample&.inputs
+  #
+  module PropertyTesting
+    # Class methods added to every Igniter::Contract subclass.
+    module ClassMethods
+      # Run the contract against randomly generated inputs and verify invariants.
+      #
+      # Requires at least one `invariant` to be declared on the contract class,
+      # though it will still execute and collect execution errors without any.
+      #
+      # @param generators [Hash{Symbol => #call}] input name → generator callable
+      # @param runs [Integer] number of test runs (default: 100)
+      # @param seed [Integer, nil] optional RNG seed for reproducibility
+      # @return [Igniter::PropertyTesting::Result]
+      def property_test(generators:, runs: 100, seed: nil)
+        Runner.new(self, generators: generators, runs: runs, seed: seed).run
+      end
+    end
+  end
+end
+
+Igniter::Contract.extend(Igniter::PropertyTesting::ClassMethods)

data/lib/igniter/provenance/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Builds a Lineage object for a named output by traversing the compiled
+    # graph and reading resolved values from the execution cache.
+    #
+    # The builder memoises each NodeTrace so that shared dependencies
+    # (diamond patterns) point to the same object rather than being duplicated.
+    class Builder
+      class << self
+        # Build lineage for +output_name+ from a resolved +execution+.
+        def build(output_name, execution)
+          new(execution).build(output_name)
+        end
+      end
+
+      def initialize(execution)
+        @graph = execution.compiled_graph
+        @cache = execution.cache
+      end
+
+      def build(output_name) # rubocop:disable Metrics/MethodLength
+        sym = output_name.to_sym
+
+        raise ProvenanceError, "No output named '#{sym}' in #{@graph.name}" unless @graph.output?(sym)
+
+        output_node = @graph.fetch_output(sym)
+        source_name = output_node.source_root
+
+        source_node = begin
+          @graph.fetch_node(source_name)
+        rescue KeyError
+          raise ProvenanceError, "Source node '#{source_name}' for output '#{sym}' not found in graph"
+        end
+
+        trace = build_trace(source_node, {})
+        Lineage.new(trace)
+      end
+
+      private
+
+      # Recursively build a NodeTrace for +node+.
+      # +memo+ prevents re-processing the same node in diamond-dependency graphs.
+      def build_trace(node, memo) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        return memo[node.name] if memo.key?(node.name)
+
+        # Reserve the slot to handle (unlikely) circular edge during traversal
+        memo[node.name] = nil
+
+        state = @cache.fetch(node.name)
+        value = extract_value(state)
+
+        contributing = {}
+        node.dependencies.each do |dep_name|
+          dep_node = safe_fetch_node(dep_name)
+          next unless dep_node
+
+          contributing[dep_name] = build_trace(dep_node, memo)
+        end
+
+        trace = NodeTrace.new(
+          name: node.name,
+          kind: node.kind,
+          value: value,
+          contributing: contributing
+        )
+        memo[node.name] = trace
+        trace
+      end
+
+      def safe_fetch_node(name)
+        @graph.fetch_node(name)
+      rescue KeyError
+        nil
+      end
+
+      # Extract a display-friendly value from a NodeState.
+      # Composition/Collection results are summarised as hashes.
+      def extract_value(state) # rubocop:disable Metrics/MethodLength
+        return nil unless state
+
+        val = state.value
+        case val
+        when Runtime::Result
+          val.to_h
+        when Runtime::CollectionResult
+          val.summary
+        when Runtime::DeferredResult
+          { pending: true, event: val.waiting_on }
+        else
+          val
+        end
+      end
+    end
+  end
+end

data/lib/igniter/provenance/lineage.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Lineage captures the full provenance of a single contract output.
+    #
+    # It wraps the NodeTrace tree rooted at the node that produces the output
+    # and exposes query methods for understanding what inputs shaped the result.
+    #
+    # Usage (after `require "igniter/extensions/provenance"`):
+    #
+    #   contract.resolve_all
+    #   lin = contract.lineage(:grand_total)
+    #
+    #   lin.value                      # => 229.95
+    #   lin.contributing_inputs        # => { base_price: 100.0, quantity: 2, ... }
+    #   lin.sensitive_to?(:base_price) # => true
+    #   lin.sensitive_to?(:user_name)  # => false
+    #   lin.path_to(:base_price)       # => [:grand_total, :subtotal, :unit_price, :base_price]
+    #   puts lin                        # prints ASCII tree
+    #
+    class Lineage
+      # The NodeTrace rooted at the output's source computation node.
+      attr_reader :trace
+
+      def initialize(trace)
+        @trace = trace
+        freeze
+      end
+
+      # The output name (same as the root trace node name).
+      def output_name
+        trace.name
+      end
+
+      # The resolved output value.
+      def value
+        trace.value
+      end
+
+      # All :input nodes that transitively contributed to this output.
+      # Returns Hash{ Symbol => value }.
+      def contributing_inputs
+        trace.contributing_inputs
+      end
+
+      # Does this output's value depend (transitively) on the given input?
+      def sensitive_to?(input_name)
+        trace.sensitive_to?(input_name)
+      end
+
+      # Ordered path of node names from the output down to the given input.
+      # Returns nil if the input does not contribute to this output.
+      def path_to(input_name)
+        trace.path_to(input_name)
+      end
+
+      # Human-readable ASCII tree explaining how this output was derived.
+      def explain
+        TextFormatter.format(trace)
+      end
+
+      alias to_s explain
+
+      # Structured (serialisable) representation of the full trace tree.
+      def to_h
+        serialize_trace(trace)
+      end
+
+      private
+
+      def serialize_trace(trc)
+        {
+          node: trc.name,
+          kind: trc.kind,
+          value: trc.value,
+          contributing: trc.contributing.transform_values { |dep| serialize_trace(dep) }
+        }
+      end
+    end
+  end
+end

data/lib/igniter/provenance/node_trace.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Immutable snapshot of a single resolved node and its full dependency chain.
+    #
+    # The tree structure mirrors the contract's dependency graph: each NodeTrace
+    # holds the traced values of all the nodes that contributed to its result.
+    # Input nodes are leaves (no contributing dependencies).
+    #
+    # The tree may share nodes (diamond dependencies in the original graph) but
+    # each shared node is memoised once by the Builder, so the same NodeTrace
+    # object is referenced from multiple parents — it is NOT duplicated.
+    class NodeTrace
+      attr_reader :name, :kind, :value, :contributing
+
+      # contributing: Hash{ Symbol => NodeTrace } — may be empty for leaf inputs
+      def initialize(name:, kind:, value:, contributing: {})
+        @name        = name.to_sym
+        @kind        = kind.to_sym
+        @value       = value
+        @contributing = contributing.freeze
+        freeze
+      end
+
+      def input?
+        kind == :input
+      end
+
+      # True when this node has no dependencies that contributed to its value.
+      def leaf?
+        contributing.empty?
+      end
+
+      # Recursively collect all :input nodes that influenced this trace.
+      # Returns Hash{ Symbol => value }.
+      def contributing_inputs
+        return { name => value } if input?
+
+        contributing.each_value.with_object({}) do |dep, acc|
+          acc.merge!(dep.contributing_inputs)
+        end
+      end
+
+      # Does this trace transitively depend on the named input?
+      def sensitive_to?(input_name)
+        contributing_inputs.key?(input_name.to_sym)
+      end
+
+      # Return the ordered path of node names from this node down to the given
+      # input, or nil if the input does not contribute to this node.
+      def path_to(input_name)
+        target = input_name.to_sym
+        return [name] if name == target
+
+        contributing.each_value do |dep|
+          sub_path = dep.path_to(target)
+          return [name] + sub_path if sub_path
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/provenance/text_formatter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Renders a NodeTrace tree as a human-readable ASCII tree.
+    #
+    # Example output:
+    #
+    #   grand_total = 229.95  [compute]
+    #   ├─ subtotal = 199.96  [compute]
+    #   │  ├─ unit_price = 99.98  [compute]
+    #   │  │  └─ base_price = 100.0  [input]
+    #   │  └─ quantity = 2  [input]
+    #   └─ shipping_cost = 29.99  [compute]
+    #      └─ destination = "US"  [input]
+    #
+    module TextFormatter
+      VALUE_MAX_LENGTH = 60
+
+      def self.format(trace)
+        lines = []
+        render(trace, lines, prefix: "", is_root: true, is_last: true)
+        lines.join("\n")
+      end
+
+      # ── private helpers ──────────────────────────────────────────────────────
+
+      def self.render(trace, lines, prefix:, is_root:, is_last:) # rubocop:disable Metrics/MethodLength
+        if is_root
+          connector = ""
+          child_pad = ""
+        elsif is_last
+          connector = "└─ "
+          child_pad = "   "
+        else
+          connector = "├─ "
+          child_pad = "│  "
+        end
+        child_prefix = prefix + child_pad
+
+        lines << "#{prefix}#{connector}#{trace.name} = #{format_value(trace.value)}  [#{trace.kind}]"
+
+        deps = trace.contributing.values
+        deps.each_with_index do |dep, idx|
+          render(dep, lines,
+                 prefix: child_prefix,
+                 is_root: false,
+                 is_last: idx == deps.size - 1)
+        end
+      end
+      private_class_method :render
+
+      def self.format_value(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
+
+        return str if str.length <= VALUE_MAX_LENGTH
+
+        "#{str[0, VALUE_MAX_LENGTH - 3]}..."
+      end
+      private_class_method :format_value
+    end
+  end
+end

data/lib/igniter/provenance.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "provenance/node_trace"
+require_relative "provenance/text_formatter"
+require_relative "provenance/lineage"
+require_relative "provenance/builder"
+
+module Igniter
+  # Provenance — runtime data lineage for Igniter contracts.
+  #
+  # After a contract has been resolved, provenance lets you ask:
+  #   "How was this output value computed, and which inputs influenced it?"
+  #
+  # Usage:
+  #   require "igniter/extensions/provenance"
+  #
+  #   contract.resolve_all
+  #   lin = contract.lineage(:grand_total)
+  #
+  #   lin.value                        # => 229.95
+  #   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]
+  #   puts lin                          # ASCII tree
+  #
+  module Provenance
+    class ProvenanceError < Igniter::Error; end
+  end
+end

data/lib/igniter/registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Thread-safe process registry mapping names to agent Refs.
+  #
+  # Names can be any object that is a valid Hash key (Symbols recommended).
+  #
+  #   Igniter::Registry.register(:counter, ref)
+  #   Igniter::Registry.find(:counter)    # => ref
+  #   Igniter::Registry.unregister(:counter)
+  #
+  module Registry
+    class RegistryError < Igniter::Error; end
+
+    @store = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Register +ref+ under +name+. Raises RegistryError if the name is taken.
+      def register(name, ref)
+        @mutex.synchronize do
+          raise RegistryError, "Name '#{name}' is already registered" if @store.key?(name)
+
+          @store[name] = ref
+        end
+        ref
+      end
+
+      # Register (or replace) +ref+ under +name+ without uniqueness check.
+      def register!(name, ref)
+        @mutex.synchronize { @store[name] = ref }
+        ref
+      end
+
+      # Return the Ref registered under +name+, or nil if not found.
+      def find(name)
+        @mutex.synchronize { @store[name] }
+      end
+
+      # Return the Ref or raise RegistryError if not found.
+      def fetch(name)
+        @mutex.synchronize do
+          @store.fetch(name) { raise RegistryError, "No agent registered as '#{name}'" }
+        end
+      end
+
+      # Remove and return the Ref registered under +name+.
+      def unregister(name)
+        @mutex.synchronize { @store.delete(name) }
+      end
+
+      def registered?(name)
+        @mutex.synchronize { @store.key?(name) }
+      end
+
+      # Snapshot of the current name→Ref map.
+      def all
+        @mutex.synchronize { @store.dup }
+      end
+
+      # Remove all registrations (useful in tests).
+      def clear
+        @mutex.synchronize { @store.clear }
+      end
+    end
+  end
+end

data/lib/igniter/runtime/resolver.rb

@@ -25,6 +25,8 @@ module Igniter
                   resolve_branch(node)
                 when :collection
                   resolve_collection(node)
+                when :effect
+                  resolve_effect(node)
                 when :await
                   resolve_await(node)
                 when :remote
@@ -63,6 +65,19 @@ module Igniter
         NodeState.new(node: node, status: :succeeded, value: @execution.fetch_input!(node.name))
       end
 
+      def resolve_effect(node)
+        dependencies = node.dependencies.each_with_object({}) do |dep, memo|
+          memo[dep] = resolve_dependency_value(dep)
+        end
+
+        value = node.adapter_class.new(
+          execution: @execution,
+          contract: @execution.contract_instance
+        ).call(**dependencies)
+
+        NodeState.new(node: node, status: :succeeded, value: value)
+      end
+
       def resolve_await(node)
         deferred = Runtime::DeferredResult.build(
           payload: { event: node.event_name },

data/lib/igniter/saga/compensation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Saga
+    # Declares the compensating action for a named compute node.
+    #
+    # The block is called with keyword arguments:
+    #   inputs: Hash{ Symbol => value }  — dependency values the node consumed
+    #   value:  Object                   — the value the node produced
+    #
+    # Example:
+    #   compensate :charge_card do |inputs:, value:|
+    #     PaymentService.refund(value[:charge_id])
+    #   end
+    class Compensation
+      attr_reader :node_name, :block
+
+      def initialize(node_name, &block)
+        raise ArgumentError, "compensate :#{node_name} requires a block" unless block
+
+        @node_name = node_name.to_sym
+        @block = block
+        freeze
+      end
+
+      def run(inputs:, value:)
+        block.call(inputs: inputs, value: value)
+      end
+    end
+  end
+end

data/lib/igniter/saga/compensation_record.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Saga
+    # Immutable record of a single compensation that was attempted.
+    class CompensationRecord
+      attr_reader :node_name, :error
+
+      def initialize(node_name:, success:, error: nil)
+        @node_name = node_name
+        @success = success
+        @error = error
+        freeze
+      end
+
+      def success? = @success
+      def failed?  = !@success
+    end
+  end
+end

data/lib/igniter/saga/executor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Saga
+    # Runs declared compensations for all successfully completed nodes,
+    # in reverse topological order.
+    #
+    # A node is eligible for compensation if:
+    #   1. Its state in the cache is `succeeded?`
+    #   2. A compensation is declared for it, via one of:
+    #      a. Contract-level `compensate :node_name do ... end`  (takes precedence)
+    #      b. Built-in compensation defined on the Igniter::Effect adapter class
+    #
+    # Compensation failures are captured as failed CompensationRecords and
+    # do NOT halt the rollback of other nodes.
+    class Executor
+      def initialize(contract)
+        @contract = contract
+        @graph    = contract.execution.compiled_graph
+        @cache    = contract.execution.cache
+      end
+
+      # @return [Array<CompensationRecord>]
+      def run_compensations
+        eligible_nodes_reversed.filter_map do |node|
+          compensation = find_compensation(node)
+          next unless compensation
+
+          attempt(compensation, node)
+        end
+      end
+
+      # Find the first node whose state is :failed in the cache.
+      # @return [Symbol, nil]
+      def failed_node_name
+        @cache.to_h.find { |_name, state| state.failed? }&.first
+      end
+
+      private
+
+      # Resolve the compensation to use for a node, if any.
+      #
+      # Contract-level `compensate :node_name` takes precedence over built-in
+      # compensation declared on an Igniter::Effect subclass.
+      #
+      # @return [Igniter::Saga::Compensation, nil]
+      def find_compensation(node)
+        declared = @contract.class.compensations
+        return declared[node.name] if declared.key?(node.name)
+
+        return nil unless node.kind == :effect
+
+        built_in = node.adapter_class.built_in_compensation
+        return nil unless built_in
+
+        Compensation.new(node.name, &built_in)
+      end
+
+      # Nodes that succeeded, in reverse resolution order.
+      def eligible_nodes_reversed
+        @graph.resolution_order
+              .select { |node| @cache.fetch(node.name)&.succeeded? }
+              .reverse
+      end
+
+      def attempt(compensation, node)
+        inputs = extract_inputs(node)
+        value  = @cache.fetch(node.name)&.value
+
+        compensation.run(inputs: inputs, value: value)
+        CompensationRecord.new(node_name: compensation.node_name, success: true)
+      rescue StandardError => e
+        CompensationRecord.new(node_name: compensation.node_name, success: false, error: e)
+      end
+
+      # Gather the resolved values of the node's direct dependencies.
+      def extract_inputs(node)
+        node.dependencies.each_with_object({}) do |dep_name, acc|
+          state = @cache.fetch(dep_name)
+          acc[dep_name.to_sym] = state&.value
+        end
+      end
+    end
+  end
+end

data/lib/igniter/saga/formatter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Saga
+    # Formats a SagaResult as a human-readable text block.
+    #
+    # Example:
+    #
+    #   Contract: OrderWorkflow
+    #   Status:   FAILED
+    #   Error:    Insufficient funds
+    #   At node:  :charge_card
+    #
+    #   COMPENSATIONS (1):
+    #     [ok]    :reserve_stock
+    #
+    module Formatter
+      class << self
+        def format(result)
+          lines = []
+          lines << "Contract: #{result.contract.class.name}"
+          lines << "Status:   #{result.success? ? "SUCCESS" : "FAILED"}"
+
+          if result.failed?
+            lines << "Error:    #{result.error&.message}"
+            lines << "At node:  :#{result.failed_node}" if result.failed_node
+          end
+
+          append_compensations(result, lines)
+          lines.join("\n")
+        end
+
+        private
+
+        def append_compensations(result, lines)
+          return if result.compensations.empty?
+
+          lines << ""
+          lines << "COMPENSATIONS (#{result.compensations.size}):"
+          result.compensations.each do |rec|
+            tag = rec.success? ? "[ok]   " : "[fail] "
+            lines << "  #{tag} :#{rec.node_name}"
+            lines << "    error: #{rec.error.message}" if rec.failed?
+          end
+        end
+      end
+    end
+  end
+end