igniter 0.4.0 → 0.4.5

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

data/lib/igniter/saga.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "saga/compensation"
+require_relative "saga/compensation_record"
+require_relative "saga/formatter"
+require_relative "saga/result"
+require_relative "saga/executor"
+
+module Igniter
+  # Saga pattern — compensating transactions for Igniter contracts.
+  #
+  # When a contract execution fails partway through, the saga system
+  # automatically runs the compensating actions for all previously
+  # SUCCEEDED nodes, in reverse topological order.
+  #
+  # Usage:
+  #
+  #   require "igniter/extensions/saga"
+  #
+  #   class OrderWorkflow < Igniter::Contract
+  #     define do
+  #       input  :order_id
+  #       input  :amount
+  #
+  #       compute :reserve_stock, depends_on: :order_id do |order_id:|
+  #         InventoryService.reserve(order_id)
+  #       end
+  #
+  #       compute :charge_card, depends_on: %i[order_id amount reserve_stock] do |amount:, **|
+  #         raise "Declined" if amount > 1000
+  #         PaymentService.charge(amount)
+  #       end
+  #
+  #       output :charge_card
+  #     end
+  #
+  #     compensate :charge_card do |inputs:, value:|
+  #       PaymentService.refund(value[:charge_id])
+  #     end
+  #
+  #     compensate :reserve_stock do |inputs:, value:|
+  #       InventoryService.release(value[:reservation_id])
+  #     end
+  #   end
+  #
+  #   result = OrderWorkflow.new(order_id: "x1", amount: 1500).resolve_saga
+  #   result.success?            # => false
+  #   result.failed_node         # => :charge_card
+  #   result.compensations.map(&:node_name)  # => [:reserve_stock]
+  #   puts result.explain
+  #
+  module Saga
+    class SagaError < Igniter::Error; end
+  end
+end

data/lib/igniter/stream_loop.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Runs an Igniter contract in a continuous tick-loop.
+  #
+  # Each tick resolves the contract with the current inputs and delivers the
+  # result to the on_result callback. Useful for sensor polling, feed
+  # processing, or any recurring computation.
+  #
+  #   stream = Igniter::StreamLoop.new(
+  #     contract:      SensorContract,
+  #     tick_interval: 0.1,
+  #     inputs:        { sensor_id: "temp-1", threshold: 25.0 },
+  #     on_result:     ->(result) { puts result.status },
+  #     on_error:      ->(err)    { warn err.message }
+  #   )
+  #
+  #   stream.start
+  #   stream.update_inputs(threshold: 30.0)  # hot-swap inputs between ticks
+  #   stream.stop
+  #
+  class StreamLoop
+    def initialize(contract:, tick_interval: 1.0, inputs: {}, on_result: nil, on_error: nil)
+      @contract_class = contract
+      @tick_interval  = tick_interval.to_f
+      @on_result      = on_result
+      @on_error       = on_error
+      @mutex          = Mutex.new
+      @current_inputs = inputs.dup
+      @running        = false
+      @thread         = nil
+    end
+
+    # Start the loop in a background thread. Returns self.
+    def start
+      @running = true
+      @thread  = Thread.new { loop_body }
+      @thread.abort_on_exception = false
+      self
+    end
+
+    # Stop the loop and wait for the current tick to finish.
+    def stop(timeout: 5)
+      @running = false
+      @thread&.join(timeout)
+      self
+    end
+
+    # Merge +new_inputs+ into the current input set. Takes effect on the next tick.
+    def update_inputs(new_inputs)
+      @mutex.synchronize { @current_inputs.merge!(new_inputs) }
+      self
+    end
+
+    def alive?
+      @thread&.alive? || false
+    end
+
+    private
+
+    def loop_body
+      while @running
+        tick_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        run_tick
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - tick_start
+        sleep_for = [@tick_interval - elapsed, 0].max
+        sleep(sleep_for) if sleep_for.positive? && @running
+      end
+    end
+
+    def run_tick
+      inputs   = @mutex.synchronize { @current_inputs.dup }
+      contract = @contract_class.new(**inputs)
+      contract.resolve_all
+      @on_result&.call(contract.result)
+    rescue StandardError => e
+      @on_error&.call(e)
+    end
+  end
+end

data/lib/igniter/supervisor.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Supervises a group of agents and restarts them when they crash.
+  #
+  # Subclass Supervisor and declare children with the class-level DSL:
+  #
+  #   class AppSupervisor < Igniter::Supervisor
+  #     strategy     :one_for_one   # default
+  #     max_restarts 5, within: 60  # default
+  #
+  #     children do |c|
+  #       c.worker :counter, CounterAgent
+  #       c.worker :logger,  LoggerAgent, initial_state: { level: :info }
+  #     end
+  #   end
+  #
+  #   sup = AppSupervisor.start
+  #   sup.child(:counter).send(:increment, by: 1)
+  #   sup.stop
+  #
+  # Restart strategies:
+  #   :one_for_one  — restart only the crashed agent (default)
+  #   :one_for_all  — stop all agents and restart them all when any one crashes
+  #
+  # Restart budget: if more than +max_restarts+ crashes happen within +within+
+  # seconds, the supervisor logs the failure and stops trying to restart.
+  #
+  class Supervisor
+    class RestartBudgetExceeded < Igniter::Error; end
+
+    # ── ChildSpec ────────────────────────────────────────────────────────────
+
+    ChildSpec = Struct.new(:name, :agent_class, :init_opts, keyword_init: true)
+
+    class ChildSpecBuilder
+      attr_reader :specs
+
+      def initialize
+        @specs = []
+      end
+
+      def worker(name, agent_class, **opts)
+        @specs << ChildSpec.new(name: name.to_sym, agent_class: agent_class, init_opts: opts)
+      end
+    end
+
+    # ── Class-level defaults ─────────────────────────────────────────────────
+
+    @strategy        = :one_for_one
+    @max_restarts    = 5
+    @restart_window  = 60
+    @spec_builder    = ChildSpecBuilder.new
+
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@strategy,       :one_for_one)
+        subclass.instance_variable_set(:@max_restarts,   5)
+        subclass.instance_variable_set(:@restart_window, 60)
+        subclass.instance_variable_set(:@spec_builder,   ChildSpecBuilder.new)
+      end
+
+      def strategy(sym)
+        @strategy = sym
+      end
+
+      def max_restarts(count, within:)
+        @max_restarts   = count
+        @restart_window = within
+      end
+
+      def children(&block)
+        block.call(@spec_builder)
+      end
+
+      def child_specs
+        @spec_builder.specs
+      end
+
+      def start
+        new.tap(&:start_all)
+      end
+    end
+
+    # ── Instance ─────────────────────────────────────────────────────────────
+
+    def initialize
+      @refs          = {}
+      @specs_by_name = {}
+      @restart_log   = []
+      @mutex         = Mutex.new
+    end
+
+    def start_all
+      self.class.child_specs.each do |spec|
+        @specs_by_name[spec.name] = spec
+        start_child(spec)
+      end
+    end
+
+    # Return the Ref for a named child. Returns nil if not found.
+    def child(name)
+      @mutex.synchronize { @refs[name.to_sym] }
+    end
+
+    # Stop all children gracefully.
+    def stop
+      refs = @mutex.synchronize { @refs.values.dup }
+      refs.each do |ref|
+        ref.stop
+      rescue StandardError
+        nil
+      end
+      self
+    end
+
+    private
+
+    def start_child(spec)
+      opts = spec.init_opts.dup
+      opts[:on_crash] = ->(error) { handle_crash(spec, error) }
+      ref = spec.agent_class.start(**opts)
+      @mutex.synchronize { @refs[spec.name] = ref }
+      ref
+    end
+
+    def handle_crash(spec, _error)
+      check_restart_budget!
+
+      case self.class.instance_variable_get(:@strategy)
+      when :one_for_one
+        start_child(spec)
+      when :one_for_all
+        stop_all_children
+        self.class.child_specs.each { |s| start_child(s) }
+      end
+    rescue RestartBudgetExceeded => e
+      warn "Igniter::Supervisor #{self.class.name}: #{e.message}"
+    end
+
+    def check_restart_budget! # rubocop:disable Metrics/MethodLength
+      now    = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      window = self.class.instance_variable_get(:@restart_window).to_f
+      max    = self.class.instance_variable_get(:@max_restarts)
+
+      @mutex.synchronize do
+        @restart_log.reject! { |t| now - t > window }
+        @restart_log << now
+
+        if @restart_log.size > max
+          raise RestartBudgetExceeded,
+                "#{@restart_log.size} crashes in #{window}s (max=#{max})"
+        end
+      end
+    end
+
+    def stop_all_children
+      refs = @mutex.synchronize { @refs.values.dup }
+      refs.each do |ref|
+        ref.stop(timeout: 2)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Igniter
-  VERSION = "0.4.0"
+  VERSION = "0.4.5"
 end

data/lib/igniter.rb

@@ -5,6 +5,8 @@ require_relative "igniter/errors"
 require_relative "igniter/type_system"
 require_relative "igniter/executor"
 require_relative "igniter/executor_registry"
+require_relative "igniter/effect"
+require_relative "igniter/effect_registry"
 require_relative "igniter/model"
 require_relative "igniter/compiler"
 require_relative "igniter/events"
@@ -32,6 +34,14 @@ module Igniter
       executor_registry.register(key, executor_class, **metadata)
     end
 
+    def effect_registry
+      @effect_registry ||= EffectRegistry.new
+    end
+
+    def register_effect(key, adapter_class, **metadata)
+      effect_registry.register(key, adapter_class, **metadata)
+    end
+
     def compile(&block)
       DSL::ContractBuilder.compile(&block)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: igniter
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.5
 platform: ruby
 authors:
 - Alexander
@@ -57,19 +57,36 @@ files:
 - docs/DISTRIBUTED_CONTRACTS_V1.md
 - docs/EXECUTION_MODEL_V2.md
 - docs/IGNITER_CONCEPTS.md
+- docs/LLM_V1.md
 - docs/PATTERNS.md
+- docs/SERVER_V1.md
 - docs/STORE_ADAPTERS.md
 - examples/README.md
+- examples/agents.rb
 - examples/async_store.rb
 - examples/basic_pricing.rb
 - examples/collection.rb
 - examples/collection_partial_failure.rb
 - examples/composition.rb
 - examples/diagnostics.rb
+- examples/differential.rb
+- examples/distributed_server.rb
 - examples/distributed_workflow.rb
+- examples/effects.rb
+- examples/incremental.rb
+- examples/invariants.rb
 - examples/marketing_ergonomics.rb
+- examples/order_pipeline.rb
+- examples/provenance.rb
 - examples/ringcentral_routing.rb
+- examples/saga.rb
 - lib/igniter.rb
+- lib/igniter/agent.rb
+- lib/igniter/agent/mailbox.rb
+- lib/igniter/agent/message.rb
+- lib/igniter/agent/ref.rb
+- lib/igniter/agent/runner.rb
+- lib/igniter/agent/state_holder.rb
 - lib/igniter/compiler.rb
 - lib/igniter/compiler/compiled_graph.rb
 - lib/igniter/compiler/graph_compiler.rb
@@ -91,26 +108,49 @@ files:
 - lib/igniter/diagnostics/introspection/formatters/mermaid_formatter.rb
 - lib/igniter/diagnostics/introspection/formatters/text_tree_formatter.rb
 - lib/igniter/diagnostics/report.rb
+- lib/igniter/differential.rb
+- lib/igniter/differential/divergence.rb
+- lib/igniter/differential/formatter.rb
+- lib/igniter/differential/report.rb
+- lib/igniter/differential/runner.rb
 - lib/igniter/dsl.rb
 - lib/igniter/dsl/contract_builder.rb
 - lib/igniter/dsl/schema_builder.rb
+- lib/igniter/effect.rb
+- lib/igniter/effect_registry.rb
 - lib/igniter/errors.rb
 - lib/igniter/events.rb
 - lib/igniter/events/bus.rb
 - lib/igniter/events/event.rb
+- lib/igniter/execution_report.rb
+- lib/igniter/execution_report/builder.rb
+- lib/igniter/execution_report/formatter.rb
+- lib/igniter/execution_report/node_entry.rb
+- lib/igniter/execution_report/report.rb
 - lib/igniter/executor.rb
 - lib/igniter/executor_registry.rb
 - lib/igniter/extensions.rb
 - lib/igniter/extensions/auditing.rb
 - lib/igniter/extensions/auditing/timeline.rb
+- lib/igniter/extensions/differential.rb
+- lib/igniter/extensions/execution_report.rb
+- lib/igniter/extensions/incremental.rb
 - lib/igniter/extensions/introspection.rb
 - lib/igniter/extensions/introspection/graph_formatter.rb
 - lib/igniter/extensions/introspection/plan_formatter.rb
 - lib/igniter/extensions/introspection/runtime_formatter.rb
+- lib/igniter/extensions/invariants.rb
+- lib/igniter/extensions/provenance.rb
 - lib/igniter/extensions/reactive.rb
 - lib/igniter/extensions/reactive/engine.rb
 - lib/igniter/extensions/reactive/matcher.rb
 - lib/igniter/extensions/reactive/reaction.rb
+- lib/igniter/extensions/saga.rb
+- lib/igniter/incremental.rb
+- lib/igniter/incremental/formatter.rb
+- lib/igniter/incremental/result.rb
+- lib/igniter/incremental/tracker.rb
+- lib/igniter/integrations/agents.rb
 - lib/igniter/integrations/llm.rb
 - lib/igniter/integrations/llm/config.rb
 - lib/igniter/integrations/llm/context.rb
@@ -126,17 +166,31 @@ files:
 - lib/igniter/integrations/rails/generators/install/install_generator.rb
 - lib/igniter/integrations/rails/railtie.rb
 - lib/igniter/integrations/rails/webhook_concern.rb
+- lib/igniter/invariant.rb
 - lib/igniter/model.rb
 - lib/igniter/model/await_node.rb
 - lib/igniter/model/branch_node.rb
 - lib/igniter/model/collection_node.rb
 - lib/igniter/model/composition_node.rb
 - lib/igniter/model/compute_node.rb
+- lib/igniter/model/effect_node.rb
 - lib/igniter/model/graph.rb
 - lib/igniter/model/input_node.rb
 - lib/igniter/model/node.rb
 - lib/igniter/model/output_node.rb
 - lib/igniter/model/remote_node.rb
+- lib/igniter/property_testing.rb
+- lib/igniter/property_testing/formatter.rb
+- lib/igniter/property_testing/generators.rb
+- lib/igniter/property_testing/result.rb
+- lib/igniter/property_testing/run.rb
+- lib/igniter/property_testing/runner.rb
+- lib/igniter/provenance.rb
+- lib/igniter/provenance/builder.rb
+- lib/igniter/provenance/lineage.rb
+- lib/igniter/provenance/node_trace.rb
+- lib/igniter/provenance/text_formatter.rb
+- lib/igniter/registry.rb
 - lib/igniter/runtime.rb
 - lib/igniter/runtime/cache.rb
 - lib/igniter/runtime/collection_result.rb
@@ -157,6 +211,12 @@ files:
 - lib/igniter/runtime/stores/file_store.rb
 - lib/igniter/runtime/stores/memory_store.rb
 - lib/igniter/runtime/stores/redis_store.rb
+- lib/igniter/saga.rb
+- lib/igniter/saga/compensation.rb
+- lib/igniter/saga/compensation_record.rb
+- lib/igniter/saga/executor.rb
+- lib/igniter/saga/formatter.rb
+- lib/igniter/saga/result.rb
 - lib/igniter/server.rb
 - lib/igniter/server/client.rb
 - lib/igniter/server/config.rb
@@ -170,6 +230,8 @@ files:
 - lib/igniter/server/rack_app.rb
 - lib/igniter/server/registry.rb
 - lib/igniter/server/router.rb
+- lib/igniter/stream_loop.rb
+- lib/igniter/supervisor.rb
 - lib/igniter/type_system.rb
 - lib/igniter/version.rb
 - sig/igniter.rbs