igniter 0.5.0 → 0.5.2

data/lib/igniter/effect_registry.rb

@@ -1,78 +0,0 @@
-# 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

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Error < StandardError
-    attr_reader :context
-
-    def initialize(message = nil, context: {})
-      @context = context.compact.freeze
-      super(format_message(message, @context))
-    end
-
-    def graph
-      context[:graph]
-    end
-
-    def node_id
-      context[:node_id]
-    end
-
-    def node_name
-      context[:node_name]
-    end
-
-    def node_path
-      context[:node_path]
-    end
-
-    def source_location
-      context[:source_location]
-    end
-
-    def execution_id
-      context[:execution_id]
-    end
-
-    private
-
-    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(", ")}]"
-    end
-  end
-
-  class CompileError < Error; end
-  class ValidationError < CompileError; end
-  class CycleError < ValidationError; end
-  class InputError < Error; end
-  class CollectionInputError < Error; end
-  class CollectionKeyError < Error; end
-  class ResolutionError < Error; end
-  class CompositionError < Error; end
-  class BranchSelectionError < Error; end
-
-  class PendingDependencyError < Error
-    attr_reader :deferred_result
-
-    def initialize(deferred_result, message = "Dependency is pending", context: {})
-      @deferred_result = deferred_result
-      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/events/bus.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Igniter
-  module Events
-    class Bus
-      attr_reader :execution_id, :events
-
-      def initialize(execution_id: SecureRandom.uuid)
-        @execution_id = execution_id
-        @events = []
-        @subscribers = []
-      end
-
-      def emit(type, node: nil, status: nil, payload: {})
-        event = Event.new(
-          event_id: SecureRandom.uuid,
-          type: type,
-          execution_id: execution_id,
-          node_id: node&.id,
-          node_name: node&.name,
-          path: node&.path,
-          status: status,
-          payload: payload,
-          timestamp: Time.now.utc
-        )
-
-        @events << event
-        @subscribers.each { |subscriber| subscriber.call(event) }
-        event
-      end
-
-      def subscribe(subscriber = nil, &block)
-        @subscribers << (subscriber || block)
-      end
-
-      def restore!(events:, execution_id: nil)
-        @execution_id = execution_id if execution_id
-        @events = Array(events).map { |event| event.is_a?(Event) ? event : Event.from_h(event) }
-      end
-    end
-  end
-end

data/lib/igniter/events/event.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Igniter
-  module Events
-    Event = Struct.new(
-      :event_id,
-      :type,
-      :execution_id,
-      :node_id,
-      :node_name,
-      :path,
-      :status,
-      :payload,
-      :timestamp,
-      keyword_init: true
-    ) do
-      def self.from_h(data)
-        new(
-          event_id: value_from(data, :event_id),
-          type: value_from(data, :type).to_sym,
-          execution_id: value_from(data, :execution_id),
-          node_id: value_from(data, :node_id),
-          node_name: value_from(data, :node_name)&.to_sym,
-          path: value_from(data, :path),
-          status: value_from(data, :status)&.to_sym,
-          payload: value_from(data, :payload) || {},
-          timestamp: parse_timestamp(value_from(data, :timestamp))
-        )
-      end
-
-      def to_h
-        {
-          event_id: event_id,
-          type: type,
-          execution_id: execution_id,
-          node_id: node_id,
-          node_name: node_name,
-          path: path,
-          status: status,
-          payload: payload,
-          timestamp: timestamp
-        }
-      end
-
-      def as_json(*)
-        to_h.transform_values { |value| serialize_value(value) }
-      end
-
-      private
-
-      def self.parse_timestamp(value)
-        case value
-        when Time
-          value
-        when String
-          Time.iso8601(value)
-        else
-          value
-        end
-      end
-
-      def self.value_from(data, key)
-        data[key] || data[key.to_s]
-      end
-
-      def serialize_value(value)
-        case value
-        when Time
-          value.iso8601
-        when Hash
-          value.each_with_object({}) { |(key, nested_value), memo| memo[key] = serialize_value(nested_value) }
-        when Array
-          value.map { |item| serialize_value(item) }
-        else
-          value
-        end
-      end
-    end
-  end
-end

data/lib/igniter/events.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "events/event"
-require_relative "events/bus"
-
-module Igniter
-  module Events
-  end
-end

data/lib/igniter/execution_report/builder.rb

@@ -1,54 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,65 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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/executor.rb

@@ -1,134 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Executor
-    class << self
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@executor_inputs, executor_inputs.transform_values(&:dup))
-        subclass.instance_variable_set(:@executor_metadata, executor_metadata.dup)
-        # capabilities and fingerprint are NOT inherited — each subclass declares its own
-      end
-
-      def input(name, required: true, type: nil, **metadata)
-        executor_inputs[name.to_sym] = metadata.merge(required: required, type: type).compact
-      end
-
-      def executor_inputs
-        @executor_inputs ||= {}
-      end
-
-      def executor_metadata
-        @executor_metadata ||= {}
-      end
-
-      def executor_key(value = nil)
-        metadata_value(:key, value)
-      end
-
-      def label(value = nil)
-        metadata_value(:label, value)
-      end
-
-      def category(value = nil)
-        metadata_value(:category, value)
-      end
-
-      def summary(value = nil)
-        metadata_value(:summary, value)
-      end
-
-      def tags(*values)
-        return Array(executor_metadata[:tags]).freeze if values.empty?
-
-        executor_metadata[:tags] = values.flatten.compact.map(&:to_sym).freeze
-      end
-
-      def output_schema(value = nil)
-        metadata_value(:output_schema, value)
-      end
-
-      def call(**dependencies)
-        new.call(**dependencies)
-      end
-
-      # ─── Capabilities DSL ────────────────────────────────────────────────────
-      #
-      # Declare what this executor is allowed to do. Capabilities are purely
-      # declarative — enforcement requires Igniter::Capabilities::Policy.
-      #
-      # Known capabilities:
-      #   :pure         — deterministic, no side effects; enables content-addressed caching
-      #   :network      — makes outbound HTTP/TCP connections
-      #   :database     — reads or writes a database
-      #   :filesystem   — reads or writes files
-      #   :external_api — calls a third-party API
-      #   :messaging    — publishes to a message queue or broker
-      #   :cache        — reads or writes an external cache
-      #
-      # Example:
-      #   class PaymentExecutor < Igniter::Executor
-      #     capabilities :network, :external_api
-      #   end
-      def capabilities(*caps)
-        if caps.empty?
-          @declared_capabilities ||= []
-        else
-          existing = @declared_capabilities || []
-          @declared_capabilities = (existing + caps.flatten.map(&:to_sym)).uniq.freeze
-        end
-      end
-
-      def declared_capabilities
-        @declared_capabilities || []
-      end
-
-      # Shorthand for `capabilities :pure`.
-      # A pure executor is fully deterministic: same inputs → same output, always.
-      # Pure executors participate in content-addressed cross-execution caching.
-      def pure
-        capabilities(:pure)
-      end
-
-      def pure?
-        declared_capabilities.include?(:pure)
-      end
-
-      # ─── Content-addressing fingerprint ──────────────────────────────────────
-      #
-      # Optional explicit version string used as part of the content-addressing key.
-      # Set a new value to invalidate the content cache after changing executor logic
-      # while keeping the class name stable.
-      #
-      #   fingerprint "tax_calculator_v2"
-      def fingerprint(value = nil)
-        return @content_fingerprint || name || "anonymous_executor" if value.nil?
-
-        @content_fingerprint = value.to_s.freeze
-      end
-
-      def content_fingerprint
-        @content_fingerprint || name || "anonymous_executor"
-      end
-
-      private
-
-      def metadata_value(key, value)
-        return executor_metadata[key] if value.nil?
-
-        executor_metadata[key] = value
-      end
-    end
-
-    attr_reader :execution, :contract
-
-    def initialize(execution: nil, contract: nil)
-      @execution = execution
-      @contract = contract
-    end
-
-    def defer(token: nil, payload: {})
-      Runtime::DeferredResult.build(token: token, payload: payload)
-    end
-  end
-end

data/lib/igniter/executor_registry.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class ExecutorRegistry
-    Definition = Struct.new(:key, :executor_class, :metadata, keyword_init: true)
-
-    def initialize
-      @definitions = {}
-    end
-
-    def register(key, executor_class, **metadata)
-      normalized_key = key.to_s
-      raise CompileError, "executor registry key cannot be empty" if normalized_key.empty?
-
-      unless executor_class.is_a?(Class) && executor_class <= Igniter::Executor
-        raise CompileError, "Executor registry key '#{normalized_key}' must reference an Igniter::Executor subclass"
-      end
-
-      @definitions[normalized_key] = Definition.new(
-        key: normalized_key,
-        executor_class: executor_class,
-        metadata: executor_class.executor_metadata.merge(metadata).merge(key: normalized_key)
-      )
-    end
-
-    def fetch(key)
-      @definitions.fetch(key.to_s)
-    rescue KeyError
-      raise CompileError, "Unknown executor registry key: #{key}"
-    end
-
-    def registered?(key)
-      @definitions.key?(key.to_s)
-    end
-
-    def definitions
-      @definitions.values.sort_by(&:key)
-    end
-
-    def clear
-      @definitions.clear
-    end
-  end
-end