igniter 0.4.0 → 0.4.5

data/examples/differential.rb

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

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

@@ -0,0 +1,184 @@
+# 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
+
+require_relative "../lib/igniter"
+require_relative "../lib/igniter/extensions/saga"
+require_relative "../lib/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:)
+    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:, message:)
+    raise "Email delivery failed" if user[:tier] == "suspended"
+
+    puts "  [email] Sending '#{message}' to #{user[:name]}"
+    { delivered: true, recipient: user[:name] }
+  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 do
+      # notify depends on user
+    end
+
+    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
+  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/incremental.rb

@@ -0,0 +1,142 @@
+# 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
+
+require_relative "../lib/igniter"
+require_relative "../lib/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?}"