igniter 0.4.0 → 0.4.3

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"

data/lib/igniter/invariant.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Represents a named condition that must always hold for a contract's outputs.
+  #
+  # An Invariant wraps a block that receives the contract's declared output values
+  # as keyword arguments and returns a truthy value when the condition holds.
+  #
+  # @example
+  #   inv = Igniter::Invariant.new(:total_non_negative) { |total:, **| total >= 0 }
+  #   inv.check(total: 42)    # => nil  (passed)
+  #   inv.check(total: -1)    # => InvariantViolation
+  class Invariant
+    attr_reader :name, :block
+
+    def initialize(name, &block)
+      raise ArgumentError, "invariant :#{name} requires a block" unless block
+
+      @name  = name.to_sym
+      @block = block
+      freeze
+    end
+
+    # Evaluate invariant against the resolved output values.
+    #
+    # @param resolved_values [Hash] output_name => value for all declared outputs
+    # @return [InvariantViolation, nil] nil when the invariant holds
+    def check(resolved_values)
+      passed = block.call(**resolved_values)
+      passed ? nil : InvariantViolation.new(name: name, passed: false)
+    rescue StandardError => e
+      InvariantViolation.new(name: name, passed: false, error: e)
+    end
+  end
+
+  # Records a single invariant check outcome.
+  class InvariantViolation
+    attr_reader :name, :error
+
+    def initialize(name:, passed:, error: nil)
+      @name   = name.to_sym
+      @passed = passed
+      @error  = error
+      freeze
+    end
+
+    def passed? = @passed
+    def failed? = !@passed
+  end
+end

data/lib/igniter/model/effect_node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a side-effect node in the computation graph.
+    #
+    # An EffectNode wraps an Igniter::Effect adapter class. It participates
+    # in topological ordering, dependency resolution, saga compensations,
+    # and execution reporting like any other node — but is explicitly typed
+    # as a side effect for visibility and audit purposes.
+    class EffectNode < Node
+      attr_reader :adapter_class
+
+      def initialize(id:, name:, dependencies:, adapter_class:, path: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        super(
+          id: id,
+          kind: :effect,
+          name: name,
+          path: path || name,
+          dependencies: dependencies,
+          metadata: metadata
+        )
+        @adapter_class = adapter_class
+      end
+
+      # @return [Symbol] e.g. :database, :http, :cache, :generic
+      def effect_type
+        adapter_class.effect_type
+      end
+
+      # @return [Boolean]
+      def idempotent?
+        adapter_class.idempotent?
+      end
+    end
+  end
+end

data/lib/igniter/model.rb

@@ -10,6 +10,7 @@ require_relative "model/collection_node"
 require_relative "model/output_node"
 require_relative "model/await_node"
 require_relative "model/remote_node"
+require_relative "model/effect_node"
 
 module Igniter
   module Model

data/lib/igniter/property_testing/formatter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Renders a property-test Result as a human-readable ASCII report.
+    class Formatter
+      PASS_LABEL = "PASS"
+      FAIL_LABEL = "FAIL"
+
+      def initialize(result)
+        @result = result
+      end
+
+      def render # rubocop:disable Metrics/MethodLength
+        lines = []
+        lines << header
+        lines << summary_line
+        lines << ""
+
+        if @result.passed?
+          lines << "  All #{@result.total_runs} runs passed."
+        else
+          lines << counterexample_section
+          lines << ""
+          lines << failed_runs_section
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def header
+        label = @result.passed? ? PASS_LABEL : FAIL_LABEL
+        "PropertyTest: #{@result.contract_class.name}  [#{label}]"
+      end
+
+      def summary_line
+        "Runs: #{@result.total_runs} | " \
+          "Passed: #{@result.passed_runs.size} | " \
+          "Failed: #{@result.failed_runs.size}"
+      end
+
+      def counterexample_section
+        cx = @result.counterexample
+        return "" unless cx
+
+        [
+          "COUNTEREXAMPLE (run ##{cx.run_number}):",
+          "  Inputs:  #{cx.inputs.inspect}",
+          "  Failure: #{cx.failure_message}"
+        ].join("\n")
+      end
+
+      def failed_runs_section
+        return "" if @result.failed_runs.empty?
+
+        lines = ["FAILED RUNS:"]
+        @result.failed_runs.each do |run|
+          lines << "  ##{run.run_number.to_s.ljust(5)} #{run.failure_message.ljust(40)} inputs: #{run.inputs.inspect}"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/generators.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Built-in convenience generators for property testing.
+    #
+    # Each method returns a callable (lambda) that produces a random value
+    # when invoked. Pass these as values in the `generators:` hash to
+    # ContractClass.property_test.
+    #
+    # @example
+    #   G = Igniter::PropertyTesting::Generators
+    #
+    #   MyContract.property_test(
+    #     generators: {
+    #       price:    G.float(0.0..500.0),
+    #       quantity: G.positive_integer(max: 100),
+    #       label:    G.string(length: 3..10),
+    #       active:   G.boolean
+    #     },
+    #     runs: 200
+    #   )
+    module Generators
+      # @param min [Integer]
+      # @param max [Integer]
+      # @return [#call]
+      def self.integer(min: -100, max: 100)
+        -> { rand(min..max) }
+      end
+
+      # @param max [Integer]
+      # @return [#call]
+      def self.positive_integer(max: 1000)
+        -> { rand(1..max) }
+      end
+
+      # @param range [Range<Float>]
+      # @return [#call]
+      def self.float(range = 0.0..1.0)
+        -> { range.min + rand * (range.max - range.min) }
+      end
+
+      # @param length [Range<Integer>, Integer]
+      # @param charset [Symbol] :alpha, :alphanumeric, :hex, :printable
+      # @return [#call]
+      def self.string(length: 1..20, charset: :alpha) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        chars = case charset
+                when :alpha        then ("a".."z").to_a + ("A".."Z").to_a
+                when :alphanumeric then ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
+                when :hex          then ("0".."9").to_a + ("a".."f").to_a
+                when :printable    then (32..126).map(&:chr)
+                else raise ArgumentError, "Unknown charset: #{charset}"
+                end
+
+        lambda do
+          len = length.is_a?(Range) ? rand(length) : length
+          Array.new(len) { chars.sample }.join
+        end
+      end
+
+      # Returns one of the supplied values at random.
+      #
+      # @param values [Array]
+      # @return [#call]
+      def self.one_of(*values)
+        raise ArgumentError, "one_of requires at least one value" if values.empty?
+
+        -> { values.sample }
+      end
+
+      # Generates an array of values produced by the given generator.
+      #
+      # @param generator [#call]
+      # @param size [Range<Integer>, Integer]
+      # @return [#call]
+      def self.array(generator, size: 0..10)
+        lambda do
+          len = size.is_a?(Range) ? rand(size) : size
+          Array.new(len) { generator.call }
+        end
+      end
+
+      # @return [#call]
+      def self.boolean
+        -> { [true, false].sample }
+      end
+
+      # Wraps another generator, occasionally returning nil.
+      #
+      # @param generator [#call]
+      # @param null_rate [Float] probability of nil (0.0..1.0)
+      # @return [#call]
+      def self.nullable(generator, null_rate: 0.1)
+        -> { rand < null_rate ? nil : generator.call }
+      end
+
+      # Generates a Hash where each key maps to a generated value.
+      #
+      # @param fields [Hash{Symbol => #call}]
+      # @return [#call]
+      def self.hash_of(**fields)
+        -> { fields.transform_values(&:call) }
+      end
+
+      # Always returns the same constant value. Useful for pinning one input
+      # while randomising others.
+      #
+      # @param value [Object]
+      # @return [#call]
+      def self.constant(value)
+        -> { value }
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/result.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Aggregated result of a full property-test run.
+    class Result
+      attr_reader :contract_class, :total_runs, :runs
+
+      def initialize(contract_class:, total_runs:, runs:)
+        @contract_class = contract_class
+        @total_runs     = total_runs
+        @runs           = runs.freeze
+      end
+
+      def passed?     = failed_runs.empty?
+      def failed_runs = runs.select(&:failed?)
+      def passed_runs = runs.select(&:passed?)
+
+      # The first failing run — the counterexample to inspect and debug.
+      # nil when all runs passed.
+      #
+      # @return [Run, nil]
+      def counterexample = failed_runs.first
+
+      # @return [String]
+      def explain = Formatter.new(self).render
+
+      # @return [Hash]
+      def to_h # rubocop:disable Metrics/MethodLength
+        {
+          contract: contract_class.name,
+          total_runs: total_runs,
+          passed: passed_runs.size,
+          failed: failed_runs.size,
+          passed?: passed?,
+          counterexample: counterexample && {
+            run_number: counterexample.run_number,
+            inputs: counterexample.inputs,
+            failure: counterexample.failure_message
+          }
+        }
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/run.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Result of a single property-test execution.
+    #
+    # A run can fail in two ways:
+    #   - :execution_error  — the contract raised an error
+    #   - :invariant_violation — the contract completed but an invariant was violated
+    class Run
+      attr_reader :run_number, :inputs, :execution_error, :violations
+
+      def initialize(run_number:, inputs:, execution_error: nil, violations: [])
+        @run_number      = run_number
+        @inputs          = inputs.freeze
+        @execution_error = execution_error
+        @violations      = violations.freeze
+        freeze
+      end
+
+      def passed? = execution_error.nil? && violations.empty?
+      def failed? = !passed?
+
+      # @return [Symbol, nil] :execution_error, :invariant_violation, or nil
+      def failure_type
+        if execution_error
+          :execution_error
+        elsif violations.any?
+          :invariant_violation
+        end
+      end
+
+      # @return [String, nil]
+      def failure_message
+        if execution_error
+          execution_error.message
+        elsif violations.any?
+          violations.map { |v| ":#{v.name} violated" }.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/runner.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Executes a contract repeatedly with random inputs and collects run results.
+    #
+    # Invariant violations are captured as data (not exceptions) using the
+    # Thread.current[:igniter_skip_invariants] flag, which prevents the
+    # automatic raise in resolve_all.
+    class Runner
+      def initialize(contract_class, generators:, runs: 100, seed: nil)
+        @contract_class = contract_class
+        @generators     = generators
+        @total_runs     = runs
+        @seed           = seed
+      end
+
+      # @return [Result]
+      def run
+        Random.srand(@seed) if @seed
+
+        runs = (1..@total_runs).map { |n| execute_run(n) }
+        Result.new(contract_class: @contract_class, total_runs: @total_runs, runs: runs)
+      end
+
+      private
+
+      def execute_run(run_number)
+        inputs   = generate_inputs
+        contract = @contract_class.new(**inputs)
+
+        Thread.current[:igniter_skip_invariants] = true
+        contract.resolve_all
+        violations = contract.check_invariants
+        Run.new(run_number: run_number, inputs: inputs, violations: violations)
+      rescue StandardError => e
+        Run.new(run_number: run_number, inputs: inputs, execution_error: e)
+      ensure
+        Thread.current[:igniter_skip_invariants] = false
+      end
+
+      def generate_inputs
+        @generators.transform_values(&:call)
+      end
+    end
+  end
+end