igniter 0.5.1 → 0.5.2

data/examples/differential.rb

@@ -1,161 +0,0 @@
-# frozen_string_literal: true
-
-# Differential Execution — compare two contract implementations output-by-output.
-#
-# Use cases:
-#   * Validate a refactored contract produces the same results
-#   * Run a shadow/canary contract alongside production, catching divergences
-#   * A/B test alternative business-rule implementations
-#
-# Run: ruby examples/differential.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/differential"
-
-# ── Contracts ─────────────────────────────────────────────────────────────────
-
-# V1 — production contract (10% tax, no discount)
-class PricingV1 < Igniter::Contract
-  define do
-    input :price,    type: :numeric
-    input :quantity, type: :numeric
-
-    compute :subtotal, depends_on: %i[price quantity] do |price:, quantity:|
-      (price * quantity).round(2)
-    end
-
-    compute :tax, depends_on: :subtotal do |subtotal:|
-      (subtotal * 0.10).round(2)
-    end
-
-    compute :total, depends_on: %i[subtotal tax] do |subtotal:, tax:|
-      subtotal + tax
-    end
-
-    output :subtotal
-    output :tax
-    output :total
-  end
-end
-
-# V2 — candidate contract (15% tax + volume discount)
-class PricingV2 < Igniter::Contract
-  define do
-    input :price,    type: :numeric
-    input :quantity, type: :numeric
-
-    compute :subtotal, depends_on: %i[price quantity] do |price:, quantity:|
-      (price * quantity).round(2)
-    end
-
-    compute :tax, depends_on: :subtotal do |subtotal:|
-      (subtotal * 0.15).round(2) # higher rate
-    end
-
-    compute :discount, depends_on: :subtotal do |subtotal:|
-      subtotal > 100 ? 10.0 : 0.0
-    end
-
-    compute :total, depends_on: %i[subtotal tax discount] do |subtotal:, tax:, discount:|
-      (subtotal + tax - discount).round(2)
-    end
-
-    output :subtotal
-    output :tax
-    output :discount # new output — absent in V1
-    output :total
-  end
-end
-
-puts "=== Differential Execution Demo ==="
-puts
-
-# ── 1. Standalone comparison ───────────────────────────────────────────────────
-
-puts "--- Igniter::Differential.compare ---"
-report = Igniter::Differential.compare(
-  primary: PricingV1,
-  candidate: PricingV2,
-  inputs: { price: 50.0, quantity: 3 }
-)
-puts report.explain
-puts
-
-# ── 2. Numeric tolerance ───────────────────────────────────────────────────────
-
-puts "--- compare with tolerance: 10.0 ---"
-report_tol = Igniter::Differential.compare(
-  primary: PricingV1,
-  candidate: PricingV2,
-  inputs: { price: 50.0, quantity: 3 },
-  tolerance: 10.0
-)
-puts "tax within tolerance? #{report_tol.divergences.none? { |d| d.output_name == :tax }}"
-puts
-
-# ── 3. Instance diff_against ───────────────────────────────────────────────────
-
-puts "--- contract.diff_against(PricingV2) ---"
-contract = PricingV1.new(price: 50.0, quantity: 3)
-contract.resolve_all
-report2 = contract.diff_against(PricingV2)
-puts "match?      = #{report2.match?}"
-puts "diverged:   #{report2.divergences.map(&:output_name).inspect}"
-puts "cand. only: #{report2.candidate_only.keys.inspect}"
-puts
-
-# ── 4. Query API on Report ─────────────────────────────────────────────────────
-
-puts "--- Report query API ---"
-report.divergences.each do |div|
-  puts "  #{div.output_name}: #{div.primary_value} → #{div.candidate_value}  (delta: #{div.delta})"
-end
-puts "summary: #{report.summary}"
-puts
-
-# ── 5. Shadow mode ─────────────────────────────────────────────────────────────
-
-puts "--- shadow_with (sync) ---"
-
-class PricingWithShadow < Igniter::Contract
-  shadow_with PricingV2, on_divergence: ->(r) { puts "  [shadow] #{r.summary}" }
-  define do
-    input :price,    type: :numeric
-    input :quantity, type: :numeric
-
-    compute :subtotal, depends_on: %i[price quantity] do |price:, quantity:|
-      (price * quantity).round(2)
-    end
-
-    compute :tax, depends_on: :subtotal do |subtotal:|
-      (subtotal * 0.10).round(2)
-    end
-
-    compute :total, depends_on: %i[subtotal tax] do |subtotal:, tax:|
-      subtotal + tax
-    end
-
-    output :subtotal
-    output :tax
-    output :total
-  end
-end
-
-shadow_contract = PricingWithShadow.new(price: 50.0, quantity: 3)
-shadow_contract.resolve_all # shadow runs automatically
-puts "primary total = #{shadow_contract.result.total}"
-puts
-
-# ── 6. Matching contracts ──────────────────────────────────────────────────────
-
-puts "--- identical contracts match ---"
-matching = Igniter::Differential.compare(
-  primary: PricingV1,
-  candidate: PricingV1,
-  inputs: { price: 50.0, quantity: 3 }
-)
-puts "match? = #{matching.match?}"
-puts
-
-puts "done=true"

data/examples/distributed_server.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-# Distributed Contract — job application review workflow
-#
-# Shows the full distributed lifecycle:
-#   1. Application submitted   → execution starts, suspends at both await nodes
-#   2. Background screening    → first event delivered, execution still pending
-#   3. Manager review          → second event delivered, execution completes
-#   4. on_success callback     → fires when the decision node resolves
-#
-# Uses an in-process MemoryStore — no real server needed to run this example.
-#
-# Run: ruby examples/distributed_server.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-
-# ── Workflow Contract ─────────────────────────────────────────────────────────
-
-class ApplicationReviewWorkflow < Igniter::Contract
-  correlate_by :application_id
-
-  define do
-    input :application_id
-    input :applicant_name
-    input :position
-
-    # Execution suspends at each await until the named event is delivered
-    await :screening_result, event: :screening_completed
-    await :manager_review,   event: :manager_reviewed
-
-    compute :decision, depends_on: %i[screening_result manager_review] do |screening_result:, manager_review:|
-      passed   = screening_result[:passed]
-      approved = manager_review[:approved]
-
-      if passed && approved
-        { status: :hired,    note: manager_review[:note] }
-      elsif !passed
-        { status: :rejected, note: "Did not pass background screening" }
-      else
-        { status: :rejected, note: manager_review[:note] }
-      end
-    end
-
-    output :decision
-  end
-
-  on_success :decision do |value:, **|
-    puts "[callback] Decision reached: #{value[:status].upcase}"
-  end
-end
-
-# ── Run ───────────────────────────────────────────────────────────────────────
-
-store = Igniter::Runtime::Stores::MemoryStore.new
-
-puts "=== Step 1: Application submitted ==="
-execution = ApplicationReviewWorkflow.start(
-  { application_id: "app-42", applicant_name: "Alice Chen", position: "Senior Engineer" },
-  store: store
-)
-puts "pending=#{execution.pending?}"
-waiting = execution.execution.cache.values
-                   .select { |s| s.pending? && s.node.kind == :await }
-                   .map { |s| s.value.payload[:event] }
-puts "waiting_for=#{waiting.inspect}"
-
-puts "\n=== Step 2: Background screening completed ==="
-ApplicationReviewWorkflow.deliver_event(
-  :screening_completed,
-  correlation: { application_id: "app-42" },
-  payload: { passed: true, score: 92 },
-  store: store
-)
-
-# Restore from store to inspect mid-flight state
-exec_id = store.find_by_correlation(
-  graph: "ApplicationReviewWorkflow",
-  correlation: { application_id: "app-42" }
-)
-mid_state = ApplicationReviewWorkflow.restore_from_store(exec_id, store: store)
-puts "still_pending=#{mid_state.execution.cache.values.any?(&:pending?)}"
-
-puts "\n=== Step 3: Manager review completed ==="
-final = ApplicationReviewWorkflow.deliver_event(
-  :manager_reviewed,
-  correlation: { application_id: "app-42" },
-  payload: { approved: true, note: "Excellent system design skills" },
-  store: store
-)
-
-puts "\n=== Final result ==="
-puts "success=#{final.success?}"
-puts "decision=#{final.result.decision.inspect}"

data/examples/distributed_workflow.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift File.join(__dir__, "../lib")
-require "igniter"
-
-store = Igniter::Runtime::Stores::MemoryStore.new
-
-class LeadWorkflow < Igniter::Contract
-  correlate_by :request_id, :company_id
-
-  define do
-    input :request_id
-    input :company_id
-
-    await :crm_data, event: :crm_webhook_received
-    await :billing_data, event: :billing_data_fetched
-
-    compute :report, with: %i[crm_data billing_data] do |crm_data:, billing_data:|
-      { crm: crm_data, billing: billing_data }
-    end
-
-    output :report
-  end
-end
-
-puts "==> Starting execution..."
-execution = LeadWorkflow.start(
-  { request_id: "req-1", company_id: "co-42" },
-  store: store
-)
-puts "pending? #{execution.pending?}"
-
-puts "\n==> Delivering CRM event..."
-execution = LeadWorkflow.deliver_event(
-  :crm_webhook_received,
-  correlation: { request_id: "req-1", company_id: "co-42" },
-  payload: { name: "Acme Corp", tier: "enterprise" },
-  store: store
-)
-puts "still pending? #{execution.pending?}"
-
-puts "\n==> Delivering billing event..."
-execution = LeadWorkflow.deliver_event(
-  :billing_data_fetched,
-  correlation: { request_id: "req-1", company_id: "co-42" },
-  payload: { plan: "pro", mrr: 500 },
-  store: store
-)
-
-puts "\n==> Final result:"
-puts "success? #{execution.success?}"
-puts "report: #{execution.result.report.inspect}"

data/examples/effects.rb

@@ -1,185 +0,0 @@
-# frozen_string_literal: true
-
-# examples/effects.rb
-#
-# Demonstrates the Igniter Effect system — first-class side-effect nodes
-# that participate fully in the computation graph.
-#
-# Run with: bundle exec ruby examples/effects.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/saga"
-require "igniter/extensions/execution_report"
-
-# ── 1. Define effect adapters ──────────────────────────────────────────────────
-
-class UserRepository < Igniter::Effect
-  effect_type :database
-  idempotent  false
-
-  # Simulate a DB lookup
-  def call(user_id:)
-    raise "User #{user_id} not found" if user_id == "missing"
-
-    { id: user_id, name: "Alice", tier: "premium" }
-  end
-
-  # Built-in rollback: undo any changes made by this effect
-  compensate do |**|
-    puts "  [compensate] Rolling back user lookup (no-op for reads)"
-  end
-end
-
-class AuditLogger < Igniter::Effect
-  effect_type :audit
-  idempotent  true
-
-  def call(user_id:, action: "lookup")
-    puts "  [audit] #{action} performed for user #{user_id}"
-    { logged_at: Time.now.iso8601, action: action }
-  end
-end
-
-class EmailNotifier < Igniter::Effect
-  effect_type :notification
-
-  def call(user:, action: "welcome")
-    raise "Email delivery failed" if user[:tier] == "suspended"
-
-    message = "#{action.to_s.tr("_", " ")} for #{user[:name]}"
-    puts "  [email] Sending '#{message}' to #{user[:name]}"
-    { delivered: true, recipient: user[:name], message: message }
-  end
-
-  compensate do |inputs:, **|
-    puts "  [compensate] Cancelling email to #{inputs[:user]&.dig(:name)}"
-  end
-end
-
-# ── 2. Define a contract using effects ────────────────────────────────────────
-
-class WelcomeWorkflow < Igniter::Contract
-  define do
-    input :user_id
-    input :action, default: "welcome"
-
-    effect :user,   uses: UserRepository, depends_on: :user_id
-    effect :log,    uses: AuditLogger,    depends_on: %i[user_id action]
-    effect :email,  uses: EmailNotifier,  depends_on: %i[user action]
-
-    compute :summary, depends_on: %i[user email] do |user:, email:|
-      "Welcomed #{user[:name]}: email=#{email[:delivered]}"
-    end
-
-    output :summary
-    output :user
-    output :log
-  end
-end
-
-# ── 3. Register an effect in the registry (optional, enables symbol lookup) ───
-
-Igniter.register_effect(:user_repo, UserRepository)
-Igniter.register_effect(:audit_log, AuditLogger)
-
-class RegistryWorkflow < Igniter::Contract
-  define do
-    input :user_id
-
-    # Uses registered names instead of class references
-    effect :user_data, uses: :user_repo, depends_on: :user_id
-    effect :log_entry, uses: :audit_log, depends_on: [:user_id]
-
-    output :user_data
-  end
-end
-
-# ── 4. Run the happy path ──────────────────────────────────────────────────────
-
-puts "=" * 60
-puts "HAPPY PATH"
-puts "=" * 60
-
-contract = WelcomeWorkflow.new(user_id: "u42", action: "onboarding")
-contract.resolve_all
-
-puts
-puts "  summary: #{contract.result.summary.inspect}"
-puts "  user:    #{contract.result.user.inspect}"
-puts "  log:     #{contract.result.log.inspect}"
-puts
-
-# Execution report
-report = contract.execution_report
-puts report.explain
-puts
-
-# ── 5. Run via registry ────────────────────────────────────────────────────────
-
-puts "=" * 60
-puts "REGISTRY LOOKUP"
-puts "=" * 60
-puts
-
-rw = RegistryWorkflow.new(user_id: "u99")
-rw.resolve_all
-puts "  user_data: #{rw.result.user_data.inspect}"
-puts
-
-# ── 6. Saga with built-in compensation ────────────────────────────────────────
-
-puts "=" * 60
-puts "SAGA — effect failure triggers built-in compensation"
-puts "=" * 60
-puts
-
-class FailingWorkflow < Igniter::Contract
-  define do
-    input :user_id
-
-    effect :user,    uses: UserRepository, depends_on: :user_id
-    effect :notify,  uses: EmailNotifier,  depends_on: :user
-
-    output :user
-  end
-end
-
-# Build a user that has "suspended" tier to trigger EmailNotifier failure
-class SuspendedUserRepo < Igniter::Effect
-  effect_type :database
-
-  def call(user_id:)
-    { id: user_id, name: "Bob", tier: "suspended" }
-  end
-
-  compensate do |value:, **|
-    puts "  [compensate] Undoing user fetch for #{value[:name]}"
-  end
-end
-
-class FailingWorkflow2 < Igniter::Contract
-  define do
-    input :user_id
-
-    effect :user,   uses: SuspendedUserRepo, depends_on: :user_id
-    effect :notify, uses: EmailNotifier,     depends_on: :user
-
-    output :user
-    output :notify
-  end
-end
-
-saga_result = FailingWorkflow2.new(user_id: "u_suspended").resolve_saga
-puts
-puts "Success: #{saga_result.success?}"
-puts "Failed node: #{saga_result.failed_node}"
-puts "Error: #{saga_result.error.message}"
-puts
-puts "Compensations:"
-saga_result.compensations.each do |record|
-  status = record.success? ? "ok" : "FAILED: #{record.error.message}"
-  puts "  :#{record.node_name} → #{status}"
-end
-puts
-puts saga_result.explain

data/examples/elocal_webhook.rb

@@ -1 +0,0 @@
-# frozen_string_literal: true

data/examples/incremental.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-# examples/incremental.rb
-#
-# Demonstrates Igniter's incremental computation: only the minimal set of
-# nodes is re-executed when inputs change.
-#
-# Inspired by Salsa (Rust, rust-analyzer) and Adapton.
-#
-# Run with: bundle exec ruby examples/incremental.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/incremental"
-
-# ─── Contract ──────────────────────────────────────────────────────────────
-#
-#   base_price ──┐
-#                ├→ adjusted_price ──┐
-#   user_tier ──→ tier_discount ──┘   ├→ converted_price
-#                                     │
-#   exchange_rate ────────────────────┘
-#
-# When only exchange_rate changes:
-#   ✓ tier_discount   → SKIPPED (doesn't depend on exchange_rate)
-#   ✓ adjusted_price  → SKIPPED (doesn't depend on exchange_rate)
-#   ✓ converted_price → RECOMPUTED (directly depends on exchange_rate)
-#
-class PricingContract < Igniter::Contract
-  define do
-    input :base_price
-    input :user_tier
-    input :exchange_rate
-
-    compute :tier_discount, depends_on: :user_tier, call: lambda { |user_tier:|
-      case user_tier
-      when "gold"     then 0.20
-      when "silver"   then 0.10
-      else                 0.0
-      end
-    }
-
-    compute :adjusted_price, depends_on: %i[base_price tier_discount], call: lambda { |base_price:, tier_discount:|
-      base_price * (1.0 - tier_discount)
-    }
-
-    compute :converted_price, depends_on: %i[adjusted_price exchange_rate], call: lambda { |adjusted_price:, exchange_rate:|
-      (adjusted_price * exchange_rate).round(2)
-    }
-
-    output :tier_discount
-    output :adjusted_price
-    output :converted_price
-  end
-end
-
-# ─── Helper to show node value_versions ────────────────────────────────────
-def show_versions(contract, label)
-  puts "\n#{label}"
-  puts "-" * 50
-  %i[base_price user_tier exchange_rate tier_discount adjusted_price converted_price].each do |name|
-    node_name = name
-    state = contract.execution.cache.fetch(node_name)
-    next unless state
-
-    status = state.status
-    vv     = state.value_version
-    val    = state.value
-    mark   = case status
-             when :stale     then "~"
-             when :succeeded then "✓"
-             else                 " "
-             end
-    puts "  #{mark} :#{name.to_s.ljust(20)} val=#{val.inspect.ljust(10)} vv=#{vv}"
-  end
-end
-
-# ─── Run ───────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Igniter Incremental Computation Demo"
-puts "=" * 60
-
-contract = PricingContract.new(
-  base_price: 100.0,
-  user_tier: "gold",
-  exchange_rate: 1.0
-)
-
-contract.resolve_all
-show_versions(contract, "After initial resolve_all")
-
-puts "\n" + "=" * 60
-puts "Scenario 1: exchange_rate changes 1.0 → 1.12"
-puts "(tier_discount and adjusted_price should be SKIPPED)"
-puts "=" * 60
-
-result = contract.resolve_incrementally(exchange_rate: 1.12)
-
-show_versions(contract, "After resolve_incrementally(exchange_rate: 1.12)")
-puts "\nIncrementalResult:"
-puts result.explain
-
-puts "\nKey assertions:"
-puts "  Skipped nodes:  #{result.skipped_nodes.inspect}"
-puts "  Backdated:      #{result.backdated_nodes.inspect}"
-puts "  Changed:        #{result.changed_nodes.inspect}"
-puts "  Recomputed:     #{result.recomputed_count}"
-puts "  Changed output: converted_price #{result.changed_outputs[:converted_price]&.values_at(:from, :to)&.join(" → ")}"
-
-puts "\n" + "=" * 60
-puts "Scenario 2: user_tier changes gold → silver"
-puts "(tier_discount, adjusted_price, converted_price all recompute)"
-puts "=" * 60
-
-result2 = contract.resolve_incrementally(user_tier: "silver")
-show_versions(contract, "After resolve_incrementally(user_tier: 'silver')")
-puts "\nIncrementalResult:"
-puts result2.explain
-
-puts "\n" + "=" * 60
-puts "Scenario 3: same exchange_rate again (no change)"
-puts "(fully memoized — nothing recomputes)"
-puts "=" * 60
-
-result3 = contract.resolve_incrementally(exchange_rate: 1.12)
-puts "\nIncrementalResult:"
-puts result3.explain
-puts "\nfully_memoized? #{result3.fully_memoized?}"
-puts "outputs_changed? #{result3.outputs_changed?}"
-
-puts "\n" + "=" * 60
-puts "Scenario 4: base_price changes 100 → 100 (same value)"
-puts "(demonstrates value-equality backdating in adjusted_price)"
-puts "=" * 60
-
-contract2 = PricingContract.new(base_price: 100.0, user_tier: "gold", exchange_rate: 1.0)
-contract2.resolve_all
-
-# Now change base_price to the same value — cache.write sees same value → value_version stays
-result4 = contract2.resolve_incrementally(base_price: 100.0)
-puts "\nIncrementalResult:"
-puts result4.explain
-puts "outputs_changed? #{result4.outputs_changed?}"

data/examples/introspection.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/introspection"
-
-class IntrospectionQuoteContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country, type: :string
-
-    compute :subtotal, with: :order_total do |order_total:|
-      order_total.round(2)
-    end
-
-    scope :taxes do
-      compute :vat_rate, with: :country do |country:|
-        country == "UA" ? 0.2 : 0.0
-      end
-    end
-
-    compute :grand_total, with: %i[subtotal vat_rate] do |subtotal:, vat_rate:|
-      (subtotal * (1 + vat_rate)).round(2)
-    end
-
-    output :grand_total
-  end
-end
-
-contract = IntrospectionQuoteContract.new(order_total: 100, country: "UA")
-
-puts "=== Graph Text ==="
-puts IntrospectionQuoteContract.graph.to_text
-
-puts "\n=== Graph Mermaid ==="
-puts IntrospectionQuoteContract.graph.to_mermaid
-
-puts "\n=== Plan ==="
-puts contract.explain_plan(:grand_total)
-
-contract.result.grand_total
-explanation = contract.execution.explain_output(:grand_total)
-
-puts "\n=== Output Explain ==="
-puts "output=#{explanation[:output]}"
-puts "source=#{explanation[:source]}"
-puts "value=#{explanation.dig(:dependencies, :value)}"
-puts "dependencies=#{explanation.dig(:dependencies, :dependencies)&.map { |dependency| dependency[:name] }.join(",")}"
-puts "runtime_state=#{contract.result.states.fetch(:grand_total).slice(:status, :value).inspect}"