igniter 0.5.0 → 0.5.1

data/examples/catalog.rb

@@ -0,0 +1,412 @@
+# frozen_string_literal: true
+
+module IgniterExamples
+  ROOT = File.expand_path("..", __dir__)
+
+  Example = Struct.new(
+    :id,
+    :path,
+    :summary,
+    :smoke,
+    :autonomous,
+    :runnable,
+    :timeout,
+    :args,
+    :expected_fragments,
+    :skip_reason,
+    keyword_init: true
+  ) do
+    def full_path
+      File.expand_path(path, ROOT)
+    end
+
+    def command_args
+      Array(args)
+    end
+
+    def smoke?
+      smoke
+    end
+
+    def autonomous?
+      autonomous
+    end
+
+    def runnable?
+      runnable
+    end
+
+    def status
+      return :smoke if smoke?
+      return :manual if runnable?
+
+      :unsupported
+    end
+  end
+
+  ALL = [
+    Example.new(
+      id: "agents",
+      path: "examples/agents.rb",
+      summary: "Supervision, registry lookups, and stream loops.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["=== Supervised agents ===", "done=true"]
+    ),
+    Example.new(
+      id: "agent_orchestration",
+      path: "examples/agent_orchestration.rb",
+      summary: "Current agent-node orchestration, deferred replies, and provenance.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["contract_status=pending", "lineage_reason=awaiting_review"]
+    ),
+    Example.new(
+      id: "async_store",
+      path: "examples/async_store.rb",
+      summary: "Store-backed deferred execution and resume flow.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["pending_token=quote-100", "resumed_gross_total=180.0"]
+    ),
+    Example.new(
+      id: "basic_pricing",
+      path: "examples/basic_pricing.rb",
+      summary: "Minimal contract with recomputation after input updates.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["gross_total=120.0", "updated_gross_total=180.0"]
+    ),
+    Example.new(
+      id: "collection",
+      path: "examples/collection.rb",
+      summary: "Collection fan-out with per-item child results.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["keys=[1, 2]", ":status=>:succeeded"]
+    ),
+    Example.new(
+      id: "collection_partial_failure",
+      path: "examples/collection_partial_failure.rb",
+      summary: "Partial-failure collection diagnostics and summaries.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: [
+        "summary={:mode=>:collect, :total=>3, :succeeded=>2, :failed=>1, :status=>:partial_failure}",
+        "failed_items={2=>{:type=>\"Igniter::ResolutionError\""
+      ]
+    ),
+    Example.new(
+      id: "composition",
+      path: "examples/composition.rb",
+      summary: "Nested contracts via compose.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["pricing={:pricing=>{:gross_total=>120.0}}"]
+    ),
+    Example.new(
+      id: "consensus",
+      path: "examples/consensus.rb",
+      summary: "Consensus-style bid selection across competing vendors.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Igniter::Cluster::Consensus Demo", "Winner: vendor=betacor"]
+    ),
+    Example.new(
+      id: "dataflow",
+      path: "examples/dataflow.rb",
+      summary: "Incremental collections and maintained aggregates.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["PART 1", "PART 2"]
+    ),
+    Example.new(
+      id: "diagnostics",
+      path: "examples/diagnostics.rb",
+      summary: "Text diagnostics and machine-readable result output.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Diagnostics PriceContract", ":outputs=>{:gross_total=>120.0}"]
+    ),
+    Example.new(
+      id: "differential",
+      path: "examples/differential.rb",
+      summary: "Primary-vs-shadow differential execution.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Differential Execution Demo"]
+    ),
+    Example.new(
+      id: "distributed_server",
+      path: "examples/distributed_server.rb",
+      summary: "Distributed await/deliver_event workflow over a store.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["pending=true", "success=true"]
+    ),
+    Example.new(
+      id: "distributed_workflow",
+      path: "examples/distributed_workflow.rb",
+      summary: "Correlated await workflow that aggregates external events.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["==> Starting execution...", "success? true"]
+    ),
+    Example.new(
+      id: "effects",
+      path: "examples/effects.rb",
+      summary: "Effect nodes, registry lookup, and saga compensation.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["HAPPY PATH", "Compensations:"]
+    ),
+    Example.new(
+      id: "incremental",
+      path: "examples/incremental.rb",
+      summary: "Incremental recomputation with backdating and memoization.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Igniter Incremental Computation Demo", "fully_memoized? true"]
+    ),
+    Example.new(
+      id: "introspection",
+      path: "examples/introspection.rb",
+      summary: "Compiled graph text, Mermaid output, plans, and runtime explain output.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["=== Graph Text ===", "runtime_state={:status=>:succeeded, :value=>120.0}"]
+    ),
+    Example.new(
+      id: "invariants",
+      path: "examples/invariants.rb",
+      summary: "Invariant checks plus property-based testing.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["HAPPY PATH", "PROPERTY TEST"]
+    ),
+    Example.new(
+      id: "llm/research_agent",
+      path: "examples/llm/research_agent.rb",
+      summary: "Research flow with LLM executors and awaited search results.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Research Agent Example", "Done!"]
+    ),
+    Example.new(
+      id: "llm/tool_use",
+      path: "examples/llm/tool_use.rb",
+      summary: "Offline LLM tool-use pipeline with a mock provider.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["=== Feedback Triage Pipeline ===", "response=We have logged this issue"]
+    ),
+    Example.new(
+      id: "llm_tools",
+      path: "examples/llm_tools.rb",
+      summary: "Tool declarations, capability guards, and registry export.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Igniter::Tool Demo", "Done."]
+    ),
+    Example.new(
+      id: "marketing_ergonomics",
+      path: "examples/marketing_ergonomics.rb",
+      summary: "Ergonomic DSL helpers on a compact domain graph.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Plan MarketingQuoteContract", "outbox=["]
+    ),
+    Example.new(
+      id: "mesh",
+      path: "examples/mesh.rb",
+      summary: "Static mesh routing and remote-node behaviour.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Mesh configured with 2 peers:"]
+    ),
+    Example.new(
+      id: "mesh_gossip",
+      path: "examples/mesh_gossip.rb",
+      summary: "Peer convergence through gossip without seed access.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Scenario 2", "Convergence achieved without seed: true"]
+    ),
+    Example.new(
+      id: "order_pipeline",
+      path: "examples/order_pipeline.rb",
+      summary: "Guard + collection + branch + export pipeline.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["order_subtotal=199.96", "error=Order cannot be placed: items are out of stock"]
+    ),
+    Example.new(
+      id: "provenance",
+      path: "examples/provenance.rb",
+      summary: "Output provenance and trace visibility.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Provenance Demo"]
+    ),
+    Example.new(
+      id: "reactive_auditing",
+      path: "examples/reactive_auditing.rb",
+      summary: "Reactive hooks plus audit timeline snapshots.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["effect_values=[120.0, 180.0]", "invalidations=[:order_total]"]
+    ),
+    Example.new(
+      id: "ringcentral_routing",
+      path: "examples/ringcentral_routing.rb",
+      summary: "Webhook routing via branch plus nested collection fan-out.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Plan RingcentralWebhookContract", "status_route_branch=CallConnected"]
+    ),
+    Example.new(
+      id: "saga",
+      path: "examples/saga.rb",
+      summary: "Saga compensation walkthrough.",
+      smoke: true,
+      autonomous: true,
+      runnable: true,
+      timeout: 10,
+      expected_fragments: ["Saga Demo"]
+    ),
+    Example.new(
+      id: "llm/call_center_analysis",
+      path: "examples/llm/call_center_analysis.rb",
+      summary: "Transcription + analysis flow for a supplied audio URL.",
+      smoke: false,
+      autonomous: false,
+      runnable: true,
+      timeout: 20,
+      skip_reason: "requires an <audio_url> argument"
+    ),
+    Example.new(
+      id: "mesh_discovery",
+      path: "examples/mesh_discovery.rb",
+      summary: "Dynamic mesh discovery from a seed registry.",
+      smoke: false,
+      autonomous: false,
+      runnable: false,
+      timeout: 10,
+      skip_reason: "needs a refresh for the current mesh router API"
+    ),
+    Example.new(
+      id: "server/node1",
+      path: "examples/server/node1.rb",
+      summary: "Long-lived orchestrator server for the two-node demo.",
+      smoke: false,
+      autonomous: false,
+      runnable: false,
+      timeout: 10,
+      skip_reason: "legacy server entrypoint; multi-terminal demo not wired into the runner yet"
+    ),
+    Example.new(
+      id: "server/node2",
+      path: "examples/server/node2.rb",
+      summary: "Long-lived sentiment-analysis server for the two-node demo.",
+      smoke: false,
+      autonomous: false,
+      runnable: false,
+      timeout: 10,
+      skip_reason: "legacy server entrypoint; multi-terminal demo not wired into the runner yet"
+    ),
+    Example.new(
+      id: "elocal_webhook",
+      path: "examples/elocal_webhook.rb",
+      summary: "Placeholder stub reserved for the eLocal webhook walkthrough.",
+      smoke: false,
+      autonomous: false,
+      runnable: false,
+      timeout: 10,
+      skip_reason: "placeholder stub with no executable scenario yet"
+    )
+  ].freeze
+
+  def self.all
+    ALL
+  end
+
+  def self.smoke
+    ALL.select(&:smoke?)
+  end
+
+  def self.autonomous
+    ALL.select(&:autonomous?)
+  end
+
+  def self.find(name)
+    normalized = normalize(name)
+
+    ALL.find do |example|
+      normalize(example.id) == normalized ||
+        normalize(example.path) == normalized ||
+        normalize(example.path.sub(%r{\Aexamples/}, "")) == normalized
+    end
+  end
+
+  def self.normalize(name)
+    value = name.to_s
+    value = value.sub(%r{\Aexamples/}, "")
+    value = value.delete_prefix("./")
+    value = value.sub(/\.rb\z/, "")
+    value
+  end
+end

data/examples/consensus.rb

@@ -2,7 +2,7 @@
 
 # examples/consensus.rb
 #
-# Demonstrates Igniter::Consensus — a Raft-inspired consensus cluster.
+# Demonstrates Igniter::Cluster::Consensus — a Raft-inspired consensus cluster.
 #
 # Two APIs are shown:
 #
@@ -10,15 +10,17 @@
 #   Low-level   Raw Igniter::Contract with Consensus executors (BidAuction)
 #
 # The Raft protocol (leader election, log replication, quorum commits) is
-# fully encapsulated inside Igniter::Consensus::Node. Users only interact
+# fully encapsulated inside Igniter::Cluster::Consensus::Node. Users only interact
 # with Cluster and, optionally, a custom StateMachine subclass.
 #
 # Run: bundle exec ruby examples/consensus.rb
 
-require "igniter/consensus"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/cluster"
 
 puts "=" * 62
-puts "  Igniter::Consensus Demo (5-node Raft cluster)"
+puts "  Igniter::Cluster::Consensus Demo (5-node Raft cluster)"
 puts "=" * 62
 
 NODES = %i[n1 n2 n3 n4 n5].freeze
@@ -28,7 +30,7 @@ NODES = %i[n1 n2 n3 n4 n5].freeze
 # ─────────────────────────────────────────────────────────────────────────────
 puts "\n[1] Starting #{NODES.size}-node cluster"
 
-cluster = Igniter::Consensus::Cluster.start(nodes: NODES)
+cluster = Igniter::Cluster::Consensus::Cluster.start(nodes: NODES)
 puts "  Nodes: #{NODES.join(", ")}"
 puts "  Quorum needed: #{cluster.quorum_size}/#{NODES.size}"
 
@@ -82,7 +84,7 @@ Igniter::Registry.find(old_leader_id)&.kill
 Igniter::Registry.unregister(old_leader_id)
 
 surviving_ids = NODES.reject { |n| n == old_leader_id }
-surviving = Igniter::Consensus::Cluster.new(nodes: surviving_ids)
+surviving = Igniter::Cluster::Consensus::Cluster.new(nodes: surviving_ids)
 
 puts "  Waiting for new election..."
 new_leader_ref = surviving.wait_for_leader
@@ -105,7 +107,7 @@ puts "  :price after failover = #{q2.result.value}"
 # ─────────────────────────────────────────────────────────────────────────────
 puts "\n[8] Custom state machine (counter)"
 
-class CounterMachine < Igniter::Consensus::StateMachine
+class CounterMachine < Igniter::Cluster::Consensus::StateMachine
   apply :increment do |state, cmd|
     state.merge(cmd[:key] => (state[cmd[:key]] || 0) + cmd[:by])
   end
@@ -114,7 +116,7 @@ class CounterMachine < Igniter::Consensus::StateMachine
   end
 end
 
-counter_cluster = Igniter::Consensus::Cluster.start(
+counter_cluster = Igniter::Cluster::Consensus::Cluster.start(
   nodes: %i[cx1 cx2 cx3],
   state_machine: CounterMachine,
 )
@@ -212,8 +214,8 @@ end
 
 puts "  Surviving: #{minority_ids.join(", ")}  (quorum needs #{cluster.quorum_size}/#{NODES.size})"
 puts "  Waiting — no leader should be elected..."
-sleep Igniter::Consensus::ELECTION_TIMEOUT_BASE +
-      Igniter::Consensus::ELECTION_TIMEOUT_JITTER + 0.3
+sleep Igniter::Cluster::Consensus::ELECTION_TIMEOUT_BASE +
+      Igniter::Cluster::Consensus::ELECTION_TIMEOUT_JITTER + 0.3
 
 minority_roles = minority_ids.map { |n|
   ref = Igniter::Registry.find(n)
@@ -221,7 +223,7 @@ minority_roles = minority_ids.map { |n|
 }
 puts "  States: #{minority_roles.join("  ")}"
 
-minority_cluster = Igniter::Consensus::Cluster.new(nodes: minority_ids)
+minority_cluster = Igniter::Cluster::Consensus::Cluster.new(nodes: minority_ids)
 puts "  ConsensusQuery with #{minority_ids.size}/#{NODES.size} nodes:"
 begin
   minority_cluster.read_contract(key: :price).resolve_all

data/examples/dataflow.rb

@@ -20,8 +20,9 @@
 #
 # Run with: bundle exec ruby examples/dataflow.rb
 
-require_relative "../lib/igniter"
-require_relative "../lib/igniter/extensions/dataflow"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/dataflow"
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # PART 1 — Incremental Collection + Sliding Window

data/examples/distributed_workflow.rb

@@ -15,7 +15,7 @@ class LeadWorkflow < Igniter::Contract
     await :crm_data, event: :crm_webhook_received
     await :billing_data, event: :billing_data_fetched
 
-    aggregate :report, with: %i[crm_data billing_data] do |crm_data:, billing_data:|
+    compute :report, with: %i[crm_data billing_data] do |crm_data:, billing_data:|
       { crm: crm_data, billing: billing_data }
     end
 

data/examples/effects.rb

@@ -7,9 +7,10 @@
 #
 # 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"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/saga"
+require "igniter/extensions/execution_report"
 
 # ── 1. Define effect adapters ──────────────────────────────────────────────────
 
@@ -34,7 +35,7 @@ class AuditLogger < Igniter::Effect
   effect_type :audit
   idempotent  true
 
-  def call(user_id:, action:)
+  def call(user_id:, action: "lookup")
     puts "  [audit] #{action} performed for user #{user_id}"
     { logged_at: Time.now.iso8601, action: action }
   end
@@ -43,11 +44,12 @@ end
 class EmailNotifier < Igniter::Effect
   effect_type :notification
 
-  def call(user:, message:)
+  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] }
+    { delivered: true, recipient: user[:name], message: message }
   end
 
   compensate do |inputs:, **|
@@ -137,9 +139,7 @@ class FailingWorkflow < Igniter::Contract
     input :user_id
 
     effect :user,    uses: UserRepository, depends_on: :user_id
-    effect :notify,  uses: EmailNotifier,  depends_on: :user do
-      # notify depends on user
-    end
+    effect :notify,  uses: EmailNotifier,  depends_on: :user
 
     output :user
   end
@@ -166,6 +166,7 @@ class FailingWorkflow2 < Igniter::Contract
     effect :notify, uses: EmailNotifier,     depends_on: :user
 
     output :user
+    output :notify
   end
 end
 

data/examples/incremental.rb

@@ -9,8 +9,9 @@
 #
 # Run with: bundle exec ruby examples/incremental.rb
 
-require_relative "../lib/igniter"
-require_relative "../lib/igniter/extensions/incremental"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/incremental"
 
 # ─── Contract ──────────────────────────────────────────────────────────────
 #
@@ -129,7 +130,7 @@ 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 "(demonstrates value-equality backdating in adjusted_price)"
 puts "=" * 60
 
 contract2 = PricingContract.new(base_price: 100.0, user_tier: "gold", exchange_rate: 1.0)

data/examples/introspection.rb

@@ -0,0 +1,49 @@
+# 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}"

data/examples/invariants.rb

@@ -8,9 +8,10 @@
 #
 # Run with: bundle exec ruby examples/invariants.rb
 
-require_relative "../lib/igniter"
-require_relative "../lib/igniter/extensions/invariants"
-require_relative "../lib/igniter/property_testing"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/invariants"
+require "igniter/core/property_testing"
 
 # ── 1. Define a contract with invariants ──────────────────────────────────────