igniter 0.4.5 → 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

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+# examples/consensus.rb
+#
+# Demonstrates Igniter::Cluster::Consensus — a Raft-inspired consensus cluster.
+#
+# Two APIs are shown:
+#
+#   High-level  Cluster.start / write / read / read_contract
+#   Low-level   Raw Igniter::Contract with Consensus executors (BidAuction)
+#
+# The Raft protocol (leader election, log replication, quorum commits) is
+# 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
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/cluster"
+
+puts "=" * 62
+puts "  Igniter::Cluster::Consensus Demo (5-node Raft cluster)"
+puts "=" * 62
+
+NODES = %i[n1 n2 n3 n4 n5].freeze
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [1] Start cluster with the default KV state machine
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[1] Starting #{NODES.size}-node cluster"
+
+cluster = Igniter::Cluster::Consensus::Cluster.start(nodes: NODES)
+puts "  Nodes: #{NODES.join(", ")}"
+puts "  Quorum needed: #{cluster.quorum_size}/#{NODES.size}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [2] Wait for a leader — Cluster#wait_for_leader polls until election completes
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[2] Waiting for leader election..."
+
+leader_ref = cluster.wait_for_leader
+puts "  Leader: #{leader_ref.state[:node_id]}  term=#{leader_ref.state[:term]}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [3] Writes — Cluster#write dispatches to the leader
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[3] Writing to consensus log"
+
+cluster.write(key: :price,     value: 99)
+cluster.write(key: :available, value: true)
+sleep 0.5  # allow replication
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [4] Cluster status via Cluster#status
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[4] Cluster state after replication"
+puts "  #{"node".ljust(5)} #{"role".ljust(10)} #{"term".ljust(5)} " \
+     "#{"log".ljust(4)} #{"ci".ljust(4)} state_machine"
+puts "  " + "-" * 58
+
+cluster.status.each do |s|
+  puts "  #{s[:node_id].to_s.ljust(5)} #{s[:role].to_s.ljust(10)} " \
+       "#{s[:term].to_s.ljust(5)} #{s[:log_size].to_s.ljust(4)} " \
+       "#{s[:commit_index].to_s.ljust(4)} #{s[:state_machine].inspect}"
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [5] ReadQuery contract — declarative graph: find_leader → read_value
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[5] ReadQuery contract: reading :price"
+
+q = cluster.read_contract(key: :price)
+q.resolve_all
+puts "  :price=#{q.result.value}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [6] Leader crash → automatic failover
+# ─────────────────────────────────────────────────────────────────────────────
+old_leader_id = leader_ref.state[:node_id]
+puts "\n[6] Crashing leader #{old_leader_id}..."
+
+Igniter::Registry.find(old_leader_id)&.kill
+Igniter::Registry.unregister(old_leader_id)
+
+surviving_ids = NODES.reject { |n| n == old_leader_id }
+surviving = Igniter::Cluster::Consensus::Cluster.new(nodes: surviving_ids)
+
+puts "  Waiting for new election..."
+new_leader_ref = surviving.wait_for_leader
+puts "  New leader: #{new_leader_ref.state[:node_id]}  term=#{new_leader_ref.state[:term]}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [7] Post-failover write + read via ReadQuery
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[7] Write after failover"
+
+surviving.write(key: :price, value: 150)
+sleep 0.4
+
+q2 = surviving.read_contract(key: :price)
+q2.resolve_all
+puts "  :price after failover = #{q2.result.value}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [8] Custom state machine — counter with typed commands
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[8] Custom state machine (counter)"
+
+class CounterMachine < Igniter::Cluster::Consensus::StateMachine
+  apply :increment do |state, cmd|
+    state.merge(cmd[:key] => (state[cmd[:key]] || 0) + cmd[:by])
+  end
+  apply :reset do |state, cmd|
+    state.merge(cmd[:key] => 0)
+  end
+end
+
+counter_cluster = Igniter::Cluster::Consensus::Cluster.start(
+  nodes: %i[cx1 cx2 cx3],
+  state_machine: CounterMachine,
+)
+counter_cluster.wait_for_leader
+counter_cluster.write(type: :increment, key: :page_views, by: 100)
+counter_cluster.write(type: :increment, key: :page_views, by: 250)
+sleep 0.4
+puts "  page_views = #{counter_cluster.read(:page_views)}"
+counter_cluster.stop!
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [9] BidAuction — parallel bid submission with durable consensus log
+#
+# Key Igniter properties:
+#   1. bid1/bid2/bid3 have no mutual deps → thread_pool submits them concurrently
+#   2. winner depends on all three → runs only after every bid is logged
+#   3. Same SubmitBid executor reused for all three bids (captures dep name via **)
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[9] BidAuction — three vendors submit bids in parallel"
+
+class SubmitBid < Igniter::Executor
+  # Called with: cluster: + one named bid dep (vendor1_bid / vendor2_bid / …).
+  # The dep name differs per compute node; ** captures whichever is passed.
+  def call(cluster:, **bid_kwarg)
+    bid = bid_kwarg.values.first   # { vendor_id:, price: }
+    ref = cluster.leader
+    raise Igniter::ResolutionError, "No leader — cannot submit bid" unless ref
+    ref.send(:client_write, command: { key: :"bid_#{bid[:vendor_id]}", value: bid[:price] })
+    bid
+  end
+end
+
+class SelectWinner < Igniter::Executor
+  def call(bid1:, bid2:, bid3:)
+    [bid1, bid2, bid3].min_by { |b| b[:price] }
+  end
+end
+
+class BidAuction < Igniter::Contract
+  runner :thread_pool, pool_size: 3   # bid1, bid2, bid3 run concurrently
+
+  define do
+    input :cluster
+    input :vendor1_bid   # { vendor_id: String, price: Float }
+    input :vendor2_bid
+    input :vendor3_bid
+
+    compute :bid1,   with: [:cluster, :vendor1_bid], call: SubmitBid
+    compute :bid2,   with: [:cluster, :vendor2_bid], call: SubmitBid
+    compute :bid3,   with: [:cluster, :vendor3_bid], call: SubmitBid
+
+    compute :winner, with: [:bid1, :bid2, :bid3], call: SelectWinner
+
+    output :winner
+  end
+end
+
+auction = BidAuction.new(
+  cluster:     surviving,
+  vendor1_bid: { vendor_id: "alpha",   price: 45.00 },
+  vendor2_bid: { vendor_id: "betacor", price: 38.50 },
+  vendor3_bid: { vendor_id: "gamma",   price: 52.00 },
+)
+auction.resolve_all
+winner = auction.result.winner
+puts "  Winner: vendor=#{winner[:vendor_id]}  price=$#{"%.2f" % winner[:price]}"
+
+sleep 0.4
+puts "  Bids in consensus log:"
+surviving.status.each do |s|
+  bids = s[:state_machine].select { |k, _| k.to_s.start_with?("bid_") }
+                           .map    { |k, v| "#{k}=$#{"%.2f" % v}" }
+                           .join("  ")
+  puts "  #{s[:node_id].to_s.ljust(5)} #{s[:role].to_s.ljust(10)} #{bids}"
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [10] Quorum failure — Raft's CP safety guarantee
+#
+# With only 2/5 nodes alive (< quorum 3), no leader can be elected.
+# The cluster becomes unavailable rather than returning stale/inconsistent data.
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[10] Quorum failure: Raft's CP guarantee"
+
+# Identify the current leader among surviving nodes, then kill it plus one follower
+minority_ids = surviving_ids.reject { |n|
+  ref = Igniter::Registry.find(n)
+  ref&.alive? && ref.state[:role] == :leader
+}.first(2)
+
+(surviving_ids - minority_ids).each do |nid|
+  Igniter::Registry.find(nid)&.kill rescue nil
+  Igniter::Registry.unregister(nid) rescue nil
+end
+
+puts "  Surviving: #{minority_ids.join(", ")}  (quorum needs #{cluster.quorum_size}/#{NODES.size})"
+puts "  Waiting — no leader should be elected..."
+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)
+  ref&.alive? ? "#{n}:#{ref.state[:role]}" : "#{n}:dead"
+}
+puts "  States: #{minority_roles.join("  ")}"
+
+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
+  puts "  UNEXPECTED: query succeeded"
+rescue Igniter::Error => e
+  puts "    → #{e.class.name.split("::").last}: #{e.message}"
+  puts "    (correct — cluster is unavailable, not returning stale data)"
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Cleanup
+# ─────────────────────────────────────────────────────────────────────────────
+minority_ids.each { |n| Igniter::Registry.find(n)&.stop(timeout: 2) rescue nil }
+Igniter::Registry.clear
+puts "\nDone."