igniter 0.3.1 → 0.4.3

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/execution.rb

@@ -11,10 +11,10 @@ module Igniter
         @runner_strategy = runner
         @max_workers = max_workers
         @store = store
-        @input_validator = InputValidator.new(compiled_graph)
+        @events = Events::Bus.new
+        @input_validator = InputValidator.new(compiled_graph, execution_id: @events.execution_id)
         @inputs = @input_validator.normalize_initial_inputs(inputs)
         @cache = Cache.new
-        @events = Events::Bus.new
         @audit = Extensions::Auditing::Timeline.new(self)
         @events.subscribe(@audit)
         @resolver = Resolver.new(self)

data/lib/igniter/runtime/input_validator.rb

@@ -3,8 +3,9 @@
 module Igniter
   module Runtime
     class InputValidator
-      def initialize(compiled_graph)
+      def initialize(compiled_graph, execution_id: nil)
         @compiled_graph = compiled_graph
+        @execution_id = execution_id
       end
 
       def normalize_initial_inputs(raw_inputs)
@@ -106,7 +107,7 @@ module Igniter
         hash.each_with_object({}) { |(key, value), memo| memo[key.to_sym] = value }
       end
 
-      def input_error(input_node, message)
+      def input_error(input_node, message) # rubocop:disable Metrics/MethodLength
         InputError.new(
           message,
           context: {
@@ -114,7 +115,8 @@ module Igniter
             node_id: input_node.id,
             node_name: input_node.name,
             node_path: input_node.path,
-            source_location: input_node.source_location
+            source_location: input_node.source_location,
+            execution_id: @execution_id
           }
         )
       end

data/lib/igniter/runtime/resolver.rb

@@ -25,6 +25,12 @@ module Igniter
                   resolve_branch(node)
                 when :collection
                   resolve_collection(node)
+                when :effect
+                  resolve_effect(node)
+                when :await
+                  resolve_await(node)
+                when :remote
+                  resolve_remote(node)
                 else
                   raise ResolutionError, "Unsupported node kind: #{node.kind}"
                 end
@@ -59,6 +65,56 @@ 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 },
+          source_node: node.name,
+          waiting_on: node.name
+        )
+        raise PendingDependencyError.new(deferred, "Waiting for external event '#{node.event_name}'")
+      end
+
+      def resolve_remote(node) # rubocop:disable Metrics/MethodLength
+        unless defined?(Igniter::Server::Client)
+          raise ResolutionError,
+                "remote: nodes require `require 'igniter/server'` (server integration not loaded)"
+        end
+
+        inputs = node.input_mapping.each_with_object({}) do |(child_input, dep_name), memo|
+          memo[child_input] = resolve_dependency_value(dep_name)
+        end
+
+        client   = Igniter::Server::Client.new(node.node_url, timeout: node.timeout)
+        response = client.execute(node.contract_name, inputs: inputs)
+
+        case response[:status]
+        when :succeeded
+          NodeState.new(node: node, status: :succeeded, value: response[:outputs])
+        when :failed
+          error_message = response.dig(:error, :message) || response.dig(:error, "message")
+          raise ResolutionError,
+                "Remote #{node.contract_name}@#{node.node_url}: #{error_message}"
+        else
+          raise ResolutionError,
+                "Remote #{node.contract_name}@#{node.node_url}: unexpected status '#{response[:status]}'"
+        end
+      rescue Igniter::Server::Client::ConnectionError => e
+        raise ResolutionError, "Cannot reach #{node.node_url}: #{e.message}"
+      end
+
       def resolve_compute(node)
         dependencies = node.dependencies.each_with_object({}) do |dependency_name, memo|
           memo[dependency_name] = resolve_dependency_value(dependency_name)
@@ -310,7 +366,8 @@ module Igniter
             node_id: node.id,
             node_name: node.name,
             node_path: node.path,
-            source_location: node.source_location
+            source_location: node.source_location,
+            execution_id: @execution.events.execution_id
           }
         )
       end

data/lib/igniter/runtime/stores/active_record_store.rb

@@ -12,7 +12,7 @@ module Igniter
           @snapshot_column = snapshot_column.to_sym
         end
 
-        def save(snapshot)
+        def save(snapshot, correlation: nil, graph: nil) # rubocop:disable Lint/UnusedMethodArgument
           execution_id = snapshot[:execution_id] || snapshot["execution_id"]
           record = @record_class.find_or_initialize_by(@execution_id_column => execution_id)
           record.public_send(:"#{@snapshot_column}=", JSON.generate(snapshot))
@@ -20,6 +20,18 @@ module Igniter
           execution_id
         end
 
+        def find_by_correlation(graph:, correlation:)
+          raise NotImplementedError, "find_by_correlation is not implemented for ActiveRecordStore"
+        end
+
+        def list_all(graph: nil)
+          raise NotImplementedError, "list_all is not implemented for ActiveRecordStore"
+        end
+
+        def list_pending(graph: nil)
+          raise NotImplementedError, "list_pending is not implemented for ActiveRecordStore"
+        end
+
         def fetch(execution_id)
           record = @record_class.find_by(@execution_id_column => execution_id)
           raise Igniter::ResolutionError, "No execution snapshot found for '#{execution_id}'" unless record

data/lib/igniter/runtime/stores/file_store.rb

@@ -12,12 +12,51 @@ module Igniter
           FileUtils.mkdir_p(@root)
         end
 
-        def save(snapshot)
+        def save(snapshot, correlation: nil, graph: nil)
           execution_id = snapshot[:execution_id] || snapshot["execution_id"]
-          File.write(path_for(execution_id), JSON.pretty_generate(snapshot))
+          data = snapshot.merge(
+            _graph: graph,
+            _correlation: correlation&.transform_keys(&:to_s)
+          ).compact
+          File.write(path_for(execution_id), JSON.pretty_generate(data))
           execution_id
         end
 
+        def find_by_correlation(graph:, correlation:)
+          normalized = correlation.transform_keys(&:to_s)
+          each_snapshot do |data|
+            next unless data["_graph"] == graph
+
+            stored_corr = data["_correlation"] || {}
+            return data["execution_id"] if stored_corr == normalized
+          end
+          nil
+        end
+
+        def list_all(graph: nil)
+          results = []
+          each_snapshot do |data|
+            next if graph && data["_graph"] != graph
+
+            results << data["execution_id"]
+          end
+          results
+        end
+
+        def list_pending(graph: nil)
+          results = []
+          each_snapshot do |data|
+            next if graph && data["_graph"] != graph
+
+            states = data["states"] || {}
+            pending = states.any? do |_name, state|
+              (state["status"] || state[:status]).to_s == "pending"
+            end
+            results << data["execution_id"] if pending
+          end
+          results
+        end
+
         def fetch(execution_id)
           JSON.parse(File.read(path_for(execution_id)))
         rescue Errno::ENOENT
@@ -37,6 +76,15 @@ module Igniter
         def path_for(execution_id)
           File.join(@root, "#{execution_id}.json")
         end
+
+        def each_snapshot(&block)
+          Dir.glob(File.join(@root, "*.json")).each do |file|
+            data = JSON.parse(File.read(file))
+            block.call(data)
+          rescue JSON::ParserError
+            next
+          end
+        end
       end
     end
   end

data/lib/igniter/runtime/stores/memory_store.rb

@@ -6,15 +6,68 @@ module Igniter
       class MemoryStore
         def initialize
           @snapshots = {}
+          @correlation_index = {}
           @mutex = Mutex.new
         end
 
-        def save(snapshot)
+        def save(snapshot, correlation: nil, graph: nil) # rubocop:disable Metrics/MethodLength
           execution_id = snapshot[:execution_id] || snapshot["execution_id"]
-          @mutex.synchronize { @snapshots[execution_id] = deep_copy(snapshot) }
+          @mutex.synchronize do
+            @snapshots[execution_id] = deep_copy(snapshot)
+            if graph
+              @correlation_index[execution_id] = {
+                graph: graph,
+                correlation: (correlation || {}).transform_keys(&:to_sym)
+              }
+            end
+          end
           execution_id
         end
 
+        def find_by_correlation(graph:, correlation:)
+          normalized = correlation.transform_keys(&:to_sym)
+          @mutex.synchronize do
+            @correlation_index.each do |execution_id, entry|
+              next unless entry[:graph] == graph
+              return execution_id if entry[:correlation] == normalized
+            end
+            nil
+          end
+        end
+
+        def list_all(graph: nil)
+          @mutex.synchronize do
+            if graph
+              @correlation_index.select { |_id, entry| entry[:graph] == graph }.keys
+            else
+              @snapshots.keys
+            end
+          end
+        end
+
+        def list_pending(graph: nil) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          ids = @mutex.synchronize do
+            if graph
+              @correlation_index.select { |_id, entry| entry[:graph] == graph }.keys
+            else
+              @snapshots.keys
+            end
+          end
+
+          @mutex.synchronize do
+            ids.select do |id|
+              snapshot = @snapshots[id]
+              next false unless snapshot
+
+              states = snapshot[:states] || snapshot["states"] || {}
+              states.any? do |_name, state|
+                status = state[:status] || state["status"]
+                status.to_s == "pending"
+              end
+            end
+          end
+        end
+
         def fetch(execution_id)
           @mutex.synchronize { deep_copy(@snapshots.fetch(execution_id)) }
         rescue KeyError

data/lib/igniter/runtime/stores/redis_store.rb

@@ -11,12 +11,24 @@ module Igniter
           @namespace = namespace
         end
 
-        def save(snapshot)
+        def save(snapshot, correlation: nil, graph: nil) # rubocop:disable Lint/UnusedMethodArgument
           execution_id = snapshot[:execution_id] || snapshot["execution_id"]
           @redis.set(redis_key(execution_id), JSON.generate(snapshot))
           execution_id
         end
 
+        def find_by_correlation(graph:, correlation:)
+          raise NotImplementedError, "find_by_correlation is not implemented for RedisStore"
+        end
+
+        def list_all(graph: nil)
+          raise NotImplementedError, "list_all is not implemented for RedisStore"
+        end
+
+        def list_pending(graph: nil)
+          raise NotImplementedError, "list_pending is not implemented for RedisStore"
+        end
+
         def fetch(execution_id)
           payload = @redis.get(redis_key(execution_id))
           raise Igniter::ResolutionError, "No execution snapshot found for '#{execution_id}'" unless payload

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

data/lib/igniter/saga/result.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Saga
+    # Immutable result of a saga execution (resolve_saga call).
+    #
+    # Attributes:
+    #   contract      — the contract instance that was executed
+    #   error         — Igniter::Error that caused failure (nil on success)
+    #   failed_node   — Symbol name of the first node that failed (nil on success)
+    #   compensations — Array<CompensationRecord> for all attempted compensations
+    class Result
+      attr_reader :contract, :error, :failed_node, :compensations
+
+      def initialize(success:, contract:, error: nil, failed_node: nil, compensations: [])
+        @success       = success
+        @contract      = contract
+        @error         = error
+        @failed_node   = failed_node
+        @compensations = compensations.freeze
+        freeze
+      end
+
+      def success? = @success
+      def failed?  = !@success
+
+      # Human-readable saga report.
+      def explain
+        Formatter.format(self)
+      end
+
+      alias to_s explain
+
+      # Structured (serialisable) representation.
+      def to_h
+        {
+          success: success?,
+          failed_node: failed_node,
+          error: error&.message,
+          compensations: compensations.map do |rec|
+            { node: rec.node_name, success: rec.success?, error: rec.error&.message }
+          end
+        }
+      end
+    end
+  end
+end