igniter 0.4.0 → 0.4.3

data/examples/order_pipeline.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Order Pipeline — guard + collection + branch + export
+#
+# Flow:
+#   1. guard      — require in_stock == true before proceeding
+#   2. collection — compute subtotal per line item (LineItemContract per item)
+#   3. compute    — aggregate item subtotals into order_subtotal
+#   4. branch     — choose domestic or international shipping strategy
+#   5. export     — pull shipping_cost and eta out of the selected branch
+#   6. output     — order_subtotal, shipping_cost, eta, grand_total
+#
+# Run: ruby examples/order_pipeline.rb
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+
+# ── Line Item ────────────────────────────────────────────────────────────────
+
+class LineItemContract < Igniter::Contract
+  define do
+    input :sku,        type: :string
+    input :quantity,   type: :numeric
+    input :unit_price, type: :numeric
+
+    compute :subtotal, depends_on: %i[quantity unit_price] do |quantity:, unit_price:|
+      (quantity * unit_price).round(2)
+    end
+
+    output :sku
+    output :subtotal
+  end
+end
+
+# ── Shipping Strategies ──────────────────────────────────────────────────────
+
+class DomesticShippingContract < Igniter::Contract
+  define do
+    input :country,  type: :string
+    input :subtotal, type: :numeric
+
+    compute :shipping_cost, depends_on: :subtotal do |subtotal:|
+      subtotal >= 100 ? 0.0 : 9.99
+    end
+
+    compute :eta, depends_on: :country do |country:|
+      country == "US" ? "2-3 business days" : "3-5 business days"
+    end
+
+    output :shipping_cost
+    output :eta
+  end
+end
+
+class InternationalShippingContract < Igniter::Contract
+  define do
+    input :country,  type: :string
+    input :subtotal, type: :numeric
+
+    compute :shipping_cost, depends_on: :subtotal do |subtotal:|
+      (subtotal * 0.15).round(2)
+    end
+
+    compute :eta, depends_on: :country do |**|
+      "7-14 business days"
+    end
+
+    output :shipping_cost
+    output :eta
+  end
+end
+
+# ── Order Pipeline ────────────────────────────────────────────────────────────
+
+class OrderPipelineContract < Igniter::Contract
+  define do # rubocop:disable Metrics/BlockLength
+    input :line_items, type: :array
+    input :country,    type: :string
+    input :in_stock,   type: :boolean
+
+    # Guard fires before anything else is computed
+    guard :stock_available,
+          with: :in_stock,
+          eq: true,
+          message: "Order cannot be placed: items are out of stock"
+
+    # Gate node: depends on the guard — if guard fails, this node fails too,
+    # which blocks the collection and all downstream nodes from running.
+    compute :gated_items, depends_on: %i[line_items stock_available] do |line_items:, **|
+      line_items
+    end
+
+    # Fan-out: one LineItemContract per item hash
+    collection :items,
+               with: :gated_items,
+               each: LineItemContract,
+               key: :sku,
+               mode: :collect
+
+    # Sum succeeded item subtotals
+    compute :order_subtotal, depends_on: :items do |items:|
+      items.successes.values.sum { |item| item.result.subtotal }.round(2)
+    end
+
+    # Route to the right shipping strategy based on country
+    branch :shipping,
+           with: :country,
+           inputs: { country: :country, subtotal: :order_subtotal } do
+      on "US", contract: DomesticShippingContract
+      on "CA", contract: DomesticShippingContract
+      default contract: InternationalShippingContract
+    end
+
+    # Lift shipping outputs up to the top-level graph
+    # export calls output internally, so no separate output declarations needed
+    export :shipping_cost, :eta, from: :shipping
+
+    compute :grand_total, depends_on: %i[order_subtotal shipping_cost] do |order_subtotal:, shipping_cost:|
+      (order_subtotal + shipping_cost).round(2)
+    end
+
+    output :items
+    output :order_subtotal
+    output :grand_total
+  end
+end
+
+# ── Run ───────────────────────────────────────────────────────────────────────
+
+line_items = [
+  { sku: "ruby-book",    quantity: 2, unit_price: 29.99 },
+  { sku: "rails-course", quantity: 1, unit_price: 49.99 },
+  { sku: "keyboard",     quantity: 1, unit_price: 89.99 }
+]
+
+# US order — free shipping over $100
+us_order = OrderPipelineContract.new(line_items: line_items, country: "US", in_stock: true)
+us_order.resolve_all
+
+puts "=== US Order ==="
+puts "items_summary=#{us_order.result.items.summary.inspect}"
+puts "order_subtotal=#{us_order.result.order_subtotal}"
+puts "shipping_cost=#{us_order.result.shipping_cost}"
+puts "eta=#{us_order.result.eta}"
+puts "grand_total=#{us_order.result.grand_total}"
+
+# International order — 15% shipping
+intl_order = OrderPipelineContract.new(line_items: line_items, country: "DE", in_stock: true)
+intl_order.resolve_all
+
+puts "\n=== International Order (DE) ==="
+puts "shipping_cost=#{intl_order.result.shipping_cost}"
+puts "eta=#{intl_order.result.eta}"
+puts "grand_total=#{intl_order.result.grand_total}"
+
+# Out of stock — guard fires and raises ResolutionError
+oos_order = OrderPipelineContract.new(line_items: line_items, country: "US", in_stock: false)
+begin
+  oos_order.resolve_all
+rescue Igniter::ResolutionError => e
+  puts "\n=== Out of Stock ==="
+  puts "error=#{e.message.split(" [").first}"
+end

data/examples/provenance.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Provenance — data lineage for Igniter contracts
+#
+# After a contract resolves, provenance answers:
+#   "How was this output computed, and which inputs influenced it?"
+#
+# Run: ruby examples/provenance.rb
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/provenance"
+
+# ── Contracts ─────────────────────────────────────────────────────────────────
+
+class TierDiscountContract < Igniter::Contract
+  TIERS = { bronze: 0, silver: 10, gold: 20, platinum: 30 }.freeze
+
+  define do
+    input :user_tier, type: :symbol
+
+    compute :discount_pct, depends_on: :user_tier do |user_tier:|
+      TierDiscountContract::TIERS.fetch(user_tier, 0)
+    end
+
+    output :discount_pct
+  end
+end
+
+class PricingContract < Igniter::Contract
+  define do
+    input :base_price,     type: :numeric
+    input :quantity,       type: :numeric
+    input :user_tier,      type: :symbol
+
+    compute :unit_price, depends_on: :base_price do |base_price:|
+      (base_price * 1.08).round(2) # +8% margin
+    end
+
+    compute :subtotal, depends_on: %i[unit_price quantity] do |unit_price:, quantity:|
+      (unit_price * quantity).round(2)
+    end
+
+    compose :tier_info, contract: TierDiscountContract,
+                        inputs: { user_tier: :user_tier }
+
+    compute :discount_amount, depends_on: %i[subtotal tier_info] do |subtotal:, tier_info:|
+      (subtotal * tier_info.discount_pct / 100.0).round(2)
+    end
+
+    compute :grand_total, depends_on: %i[subtotal discount_amount] do |subtotal:, discount_amount:|
+      (subtotal - discount_amount).round(2)
+    end
+
+    output :unit_price
+    output :subtotal
+    output :discount_amount
+    output :grand_total
+  end
+end
+
+# ── Run ───────────────────────────────────────────────────────────────────────
+
+puts "=== Provenance Demo ==="
+puts
+
+contract = PricingContract.new(
+  base_price: 100.0,
+  quantity: 3,
+  user_tier: :gold
+)
+contract.resolve_all
+
+puts "grand_total=#{contract.result.grand_total}"
+puts
+
+# ── ASCII tree ────────────────────────────────────────────────────────────────
+
+puts "--- explain(:grand_total) ---"
+puts contract.explain(:grand_total)
+puts
+
+# ── Query API ─────────────────────────────────────────────────────────────────
+
+lin = contract.lineage(:grand_total)
+
+puts "--- contributing_inputs ---"
+lin.contributing_inputs.each do |input_name, val|
+  puts "  #{input_name} = #{val.inspect}"
+end
+puts
+
+puts "--- sensitive_to? ---"
+puts "sensitive_to?(:base_price)  = #{lin.sensitive_to?(:base_price)}"
+puts "sensitive_to?(:quantity)    = #{lin.sensitive_to?(:quantity)}"
+puts "sensitive_to?(:user_tier)   = #{lin.sensitive_to?(:user_tier)}"
+puts "sensitive_to?(:unknown_key) = #{lin.sensitive_to?(:unknown_key)}"
+puts
+
+puts "--- path_to(:base_price) ---"
+puts lin.path_to(:base_price).inspect
+puts
+
+puts "--- path_to(:user_tier) ---"
+puts lin.path_to(:user_tier).inspect
+puts
+
+# ── Composition output lineage ────────────────────────────────────────────────
+
+puts "--- explain(:discount_amount) ---"
+puts contract.explain(:discount_amount)
+puts
+
+# ── Structured lineage (to_h) ─────────────────────────────────────────────────
+
+puts "--- lineage(:subtotal).to_h (keys only) ---"
+h = contract.lineage(:subtotal).to_h
+puts "node=#{h[:node]}, kind=#{h[:kind]}, value=#{h[:value]}"
+puts "contributing=#{h[:contributing].keys.inspect}"
+puts
+
+puts "done=true"

data/examples/saga.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Saga Pattern — compensating transactions for Igniter contracts.
+#
+# When a step fails mid-execution, the saga system automatically runs
+# compensating actions for all previously completed steps in reverse order.
+#
+# Run: ruby examples/saga.rb
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/saga"
+require "igniter/extensions/execution_report"
+
+# ── Contracts ─────────────────────────────────────────────────────────────────
+
+class OrderWorkflow < Igniter::Contract
+  define do
+    input :order_id, type: :string
+    input :amount,   type: :numeric
+
+    compute :reserve_stock, depends_on: :order_id do |order_id:|
+      puts "  [forward] reserve_stock for order #{order_id}"
+      { reservation_id: "rsv-#{order_id}" }
+    end
+
+    compute :charge_card, depends_on: %i[order_id amount reserve_stock] do |order_id:, amount:, **|
+      puts "  [forward] charge_card: $#{amount}"
+      raise "Card declined: amount $#{amount} exceeds limit" if amount > 500
+
+      { charge_id: "chg-#{order_id}", amount: amount }
+    end
+
+    compute :send_confirmation, depends_on: %i[reserve_stock charge_card] do |charge_card:, **|
+      puts "  [forward] send_confirmation for charge #{charge_card[:charge_id]}"
+      { sent: true }
+    end
+
+    output :reserve_stock
+    output :charge_card
+    output :send_confirmation
+  end
+
+  compensate :charge_card do |_inputs:, value:|
+    puts "  [compensate] refunding charge #{value[:charge_id]}"
+  end
+
+  compensate :reserve_stock do |_inputs:, value:|
+    puts "  [compensate] releasing reservation #{value[:reservation_id]}"
+  end
+end
+
+puts "=== Saga Demo ==="
+puts
+
+# ── 1. Successful saga ─────────────────────────────────────────────────────────
+
+puts "--- 1. Successful execution (amount=$100) ---"
+result_ok = OrderWorkflow.new(order_id: "ord-001", amount: 100.0).resolve_saga
+puts result_ok.explain
+puts
+
+# ── 2. Failed saga — compensations triggered ───────────────────────────────────
+
+puts "--- 2. Failed execution (amount=$999 — exceeds limit) ---"
+result_fail = OrderWorkflow.new(order_id: "ord-002", amount: 999.0).resolve_saga
+puts result_fail.explain
+puts
+
+# ── 3. Result query API ────────────────────────────────────────────────────────
+
+puts "--- 3. Result query API ---"
+puts "success?          = #{result_fail.success?}"
+puts "failed_node       = #{result_fail.failed_node.inspect}"
+puts "error             = #{result_fail.error.message}"
+puts "compensations_ran = #{result_fail.compensations.map(&:node_name).inspect}"
+puts "all compensations ok? #{result_fail.compensations.all?(&:success?)}"
+puts
+
+# ── 4. Execution report ────────────────────────────────────────────────────────
+
+puts "--- 4. execution_report (after failed saga) ---"
+failed_contract = OrderWorkflow.new(order_id: "ord-003", amount: 999.0)
+begin
+  failed_contract.resolve_all
+rescue Igniter::Error
+  nil
+end
+puts failed_contract.execution_report.explain
+puts
+
+# ── 5. Execution report on successful contract ────────────────────────────────
+
+puts "--- 5. execution_report (successful) ---"
+ok_contract = OrderWorkflow.new(order_id: "ord-004", amount: 50.0)
+ok_contract.resolve_all
+puts ok_contract.execution_report.explain
+puts
+
+# ── 6. to_h / structured output ───────────────────────────────────────────────
+
+puts "--- 6. result.to_h ---"
+h = result_fail.to_h
+puts "success:       #{h[:success]}"
+puts "failed_node:   #{h[:failed_node].inspect}"
+puts "error:         #{h[:error]}"
+puts "compensations: #{h[:compensations].map { |c| [c[:node], c[:success]] }.inspect}"
+puts
+
+puts "done=true"

data/lib/igniter/agent/mailbox.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # Thread-safe bounded queue for passing Messages between threads.
+    #
+    # Overflow policies (applied when capacity is reached):
+    #   :block      — block the caller until space is available (default)
+    #   :drop_oldest — discard the oldest message and enqueue the new one
+    #   :drop_newest — discard the incoming message silently
+    #   :error      — raise Igniter::Agent::MailboxFullError
+    class Mailbox
+      DEFAULT_CAPACITY = 256
+
+      def initialize(capacity: DEFAULT_CAPACITY, overflow: :block)
+        @capacity = capacity
+        @overflow = overflow
+        @queue    = []
+        @mutex    = Mutex.new
+        @not_empty = ConditionVariable.new
+        @not_full  = ConditionVariable.new
+        @closed    = false
+      end
+
+      # Enqueue a message. Returns self (chainable).
+      def push(message) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+        @mutex.synchronize do
+          return self if @closed
+
+          if @queue.size >= @capacity
+            case @overflow
+            when :block
+              @not_full.wait(@mutex) while @queue.size >= @capacity && !@closed
+              return self if @closed
+            when :drop_oldest
+              @queue.shift
+            when :drop_newest
+              return self
+            when :error
+              raise MailboxFullError, "Mailbox full (capacity=#{@capacity})"
+            end
+          end
+
+          @queue << message
+          @not_empty.signal
+        end
+        self
+      end
+
+      # Dequeue the next message. Blocks until a message arrives or the mailbox
+      # is closed. Returns nil if closed and empty, or if +timeout+ expires.
+      def pop(timeout: nil) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        @mutex.synchronize do
+          if timeout
+            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+            while @queue.empty? && !@closed
+              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              return nil if remaining <= 0
+
+              @not_empty.wait(@mutex, remaining)
+            end
+          else
+            @not_empty.wait(@mutex) while @queue.empty? && !@closed
+          end
+
+          return nil if @queue.empty?
+
+          msg = @queue.shift
+          @not_full.signal
+          msg
+        end
+      end
+
+      # Close the mailbox. Blocked callers in +pop+ wake up and return nil.
+      def close
+        @mutex.synchronize do
+          @closed = true
+          @not_empty.broadcast
+          @not_full.broadcast
+        end
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def size
+        @mutex.synchronize { @queue.size }
+      end
+
+      def empty?
+        @mutex.synchronize { @queue.empty? }
+      end
+    end
+  end
+end

data/lib/igniter/agent/message.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # Immutable message passed between agents through a Mailbox.
+    #
+    #   type     — Symbol identifying the message kind (e.g. :increment, :get)
+    #   payload  — frozen Hash of message data (default: {})
+    #   reply_to — one-shot Mailbox for sync request-reply (nil for async)
+    class Message
+      attr_reader :type, :payload, :reply_to
+
+      def initialize(type:, payload: {}, reply_to: nil)
+        @type     = type.to_sym
+        @payload  = (payload || {}).freeze
+        @reply_to = reply_to
+        freeze
+      end
+    end
+  end
+end

data/lib/igniter/agent/ref.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Agent
+    # External handle to a running agent.
+    #
+    # Callers interact with agents exclusively through Ref — they never touch
+    # the Mailbox, StateHolder, or Thread directly. This allows the Supervisor
+    # to swap out internals on restart without invalidating existing Ref objects.
+    class Ref
+      def initialize(thread:, mailbox:, state_holder:)
+        @thread        = thread
+        @mailbox       = mailbox
+        @state_holder  = state_holder
+        @mutex         = Mutex.new
+      end
+
+      # Asynchronous fire-and-forget. Returns self.
+      def send(type, payload = {})
+        mailbox.push(Message.new(type: type.to_sym, payload: payload))
+        self
+      end
+
+      # Synchronous request-reply. Blocks until the handler responds or timeout
+      # elapses. Raises Igniter::Agent::TimeoutError on timeout.
+      def call(type, payload = {}, timeout: 5)
+        reply_box = Mailbox.new(capacity: 1, overflow: :drop_newest)
+        mailbox.push(Message.new(type: type.to_sym, payload: payload, reply_to: reply_box))
+        reply = reply_box.pop(timeout: timeout)
+        raise TimeoutError, "Agent did not reply within #{timeout}s" unless reply
+
+        reply.payload[:value]
+      end
+
+      # Request graceful shutdown. Closes the mailbox so the runner exits after
+      # processing any in-flight message. Blocks until the thread finishes.
+      def stop(timeout: 5)
+        mailbox.close
+        thread&.join(timeout)
+        self
+      end
+
+      # Forcefully terminate the agent thread.
+      def kill
+        thread&.kill
+        mailbox.close
+        self
+      end
+
+      def alive?
+        thread&.alive? || false
+      end
+
+      # Read the current state snapshot without blocking the agent.
+      def state
+        state_holder.get
+      end
+
+      # Supervisor-internal: swap out internals when the agent restarts.
+      # Callers keep the same Ref object; the new thread/mailbox/state_holder
+      # are transparently injected.
+      def rebind(thread:, mailbox:, state_holder:)
+        @mutex.synchronize do
+          @thread        = thread
+          @mailbox       = mailbox
+          @state_holder  = state_holder
+        end
+        self
+      end
+
+      private
+
+      def thread
+        @mutex.synchronize { @thread }
+      end
+
+      def mailbox
+        @mutex.synchronize { @mailbox }
+      end
+
+      def state_holder
+        @mutex.synchronize { @state_holder }
+      end
+    end
+  end
+end