igniter 0.4.0 → 0.4.3

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/invariants.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# examples/invariants.rb
+#
+# Demonstrates Igniter Invariants and Property Testing — declare conditions
+# that must always hold for a contract's outputs, then verify them against
+# hundreds of randomly generated inputs.
+#
+# Run with: bundle exec ruby examples/invariants.rb
+
+require_relative "../lib/igniter"
+require_relative "../lib/igniter/extensions/invariants"
+require_relative "../lib/igniter/property_testing"
+
+# ── 1. Define a contract with invariants ──────────────────────────────────────
+
+class PricingContract < Igniter::Contract
+  define do
+    input :price
+    input :quantity
+
+    compute :subtotal, depends_on: %i[price quantity] do |price:, quantity:|
+      price * quantity
+    end
+
+    compute :discount, depends_on: :subtotal do |subtotal:|
+      subtotal > 100 ? subtotal * 0.1 : 0.0
+    end
+
+    compute :total, depends_on: %i[subtotal discount] do |subtotal:, discount:|
+      subtotal - discount
+    end
+
+    output :total
+    output :subtotal
+    output :discount
+  end
+
+  # Block receives only declared output values as keyword args.
+  # Use ** to absorb outputs you don't need to check.
+  invariant(:total_non_negative)    { |total:, **|             total >= 0 }
+  invariant(:discount_non_negative) { |discount:, **|          discount >= 0 }
+  invariant(:total_le_subtotal)     { |total:, subtotal:, **|  total <= subtotal }
+end
+
+# ── 2. Happy path — invariants pass ───────────────────────────────────────────
+
+puts "=" * 60
+puts "HAPPY PATH — invariants pass"
+puts "=" * 60
+puts
+
+contract = PricingContract.new(price: 20.0, quantity: 10)
+contract.resolve_all
+
+puts "  total:    #{contract.result.total}"
+puts "  subtotal: #{contract.result.subtotal}"
+puts "  discount: #{contract.result.discount}"
+puts
+puts "  check_invariants: #{contract.check_invariants.inspect}"
+puts
+
+# ── 3. Manual violation check — does not raise ───────────────────────────────
+
+puts "=" * 60
+puts "MANUAL CHECK — does not raise, returns violations"
+puts "=" * 60
+puts
+
+class NegativePriceContract < Igniter::Contract
+  define do
+    input :price
+    input :quantity
+    compute :total, depends_on: %i[price quantity] do |price:, quantity:|
+      price * quantity # can be negative if price < 0
+    end
+    output :total
+  end
+
+  invariant(:total_non_negative) { |total:, **| total >= 0 }
+end
+
+c = NegativePriceContract.new(price: -5.0, quantity: 3)
+
+# Disable auto-raise to inspect violations manually
+Thread.current[:igniter_skip_invariants] = true
+c.resolve_all
+Thread.current[:igniter_skip_invariants] = false
+
+violations = c.check_invariants
+puts "  violations: #{violations.map(&:name).inspect}"
+puts "  total: #{c.result.total}"
+puts
+
+# ── 4. Automatic raise on violation ───────────────────────────────────────────
+
+puts "=" * 60
+puts "AUTO-RAISE — resolve_all raises InvariantError"
+puts "=" * 60
+puts
+
+begin
+  NegativePriceContract.new(price: -5.0, quantity: 3).resolve_all
+rescue Igniter::InvariantError => e
+  puts "  Caught InvariantError: #{e.message}"
+  puts "  violations: #{e.violations.map(&:name).inspect}"
+end
+puts
+
+# ── 5. Property testing — all inputs valid ────────────────────────────────────
+
+puts "=" * 60
+puts "PROPERTY TEST — PricingContract with valid inputs"
+puts "=" * 60
+puts
+
+G = Igniter::PropertyTesting::Generators
+
+result = PricingContract.property_test(
+  generators: {
+    price: G.float(0.0..500.0),
+    quantity: G.positive_integer(max: 100)
+  },
+  runs: 200,
+  seed: 42
+)
+
+puts result.explain
+puts
+
+# ── 6. Property testing — finds a counterexample ─────────────────────────────
+
+puts "=" * 60
+puts "PROPERTY TEST — NegativePriceContract with unconstrained inputs"
+puts "=" * 60
+puts
+
+failing_result = NegativePriceContract.property_test(
+  generators: {
+    price: G.float(-100.0..100.0), # can be negative!
+    quantity: G.positive_integer(max: 10)
+  },
+  runs: 100,
+  seed: 1
+)
+
+puts failing_result.explain
+puts
+puts "  First counterexample inputs: #{failing_result.counterexample&.inputs.inspect}"
+puts
+
+# ── 7. Property testing — execution errors captured ──────────────────────────
+
+puts "=" * 60
+puts "PROPERTY TEST — execution errors captured as failed runs"
+puts "=" * 60
+puts
+
+class FragileContract < Igniter::Contract
+  define do
+    input :value
+    compute :result, depends_on: :value do |value:|
+      raise ArgumentError, "value must be positive" if value <= 0
+
+      Math.sqrt(value)
+    end
+    output :result
+  end
+
+  invariant(:result_non_negative) { |result:, **| result >= 0 }
+end
+
+fragile_result = FragileContract.property_test(
+  generators: { value: G.integer(min: -10, max: 10) },
+  runs: 50,
+  seed: 7
+)
+
+puts fragile_result.explain