igniter 0.4.3 → 0.5.0

data/docs/TRANSCRIPTION_V1.md

@@ -0,0 +1,403 @@
+# Igniter — LLM::Transcriber
+
+`Igniter::LLM::Transcriber` is a first-class Executor for audio-to-text conversion.
+It plugs into the Contract graph exactly like any other compute node, giving you
+caching, dependency resolution, and parallel execution for free.
+
+```
+audio file / URL
+      │
+      ▼
+ CallTranscriber          ← LLM::Transcriber subclass
+      │  TranscriptResult
+      │   .text, .words, .speakers, .duration
+      ▼
+ CallExtractor            ← LLM::Executor subclass
+      │  Hash (structured JSON)
+      ▼
+  CRM / DB
+```
+
+---
+
+## Quick start
+
+```ruby
+require "igniter/integrations/llm"
+
+Igniter::LLM.configure do |c|
+  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
+end
+
+class MyTranscriber < Igniter::LLM::Transcriber
+  transcription_provider :deepgram
+  model "nova-3"
+  language "en"
+  diarize true
+
+  def call(audio_path:) = transcribe(audio_path)
+end
+
+result = MyTranscriber.call(audio_path: "meeting.mp3")
+puts result.text
+puts result.speakers.map { |s| "#{s.speaker}: #{s.text}" }.join("\n")
+```
+
+---
+
+## Providers
+
+### OpenAI Whisper / gpt-4o-mini-transcribe
+
+| | |
+|---|---|
+| **Sync** | Yes — single POST, immediate response |
+| **Diarization** | **No** |
+| **Word timestamps** | Yes |
+| **Languages** | 99+ (auto-detect or `language:`) |
+| **Max file size** | 20 MB |
+| **Pricing** | whisper-1: `$0.006/min` · gpt-4o-mini-transcribe: `$0.003/min` |
+
+```ruby
+class CallTranscriber < Igniter::LLM::Transcriber
+  transcription_provider :openai
+  model "gpt-4o-mini-transcribe"   # or "whisper-1"
+  language "en"
+
+  def call(audio_url:) = transcribe(audio_url)
+end
+```
+
+**Extra options:** `prompt:` — context hint to improve spelling/vocabulary accuracy.
+
+---
+
+### Deepgram Nova-3
+
+| | |
+|---|---|
+| **Sync** | Yes — binary POST, immediate response |
+| **Diarization** | Yes (`diarize true`) |
+| **Word timestamps** | Yes (always included) |
+| **Languages** | 99+ Nova-3 Multilingual · single-language Nova-3 |
+| **Pricing** | `$0.0077/min` (includes diarization, per-second billing) |
+
+```ruby
+Igniter::LLM.configure do |c|
+  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
+end
+
+class CallTranscriber < Igniter::LLM::Transcriber
+  transcription_provider :deepgram
+  model "nova-3"
+  diarize true
+
+  def call(audio_url:) = transcribe(audio_url)
+end
+```
+
+**Extra options:**
+```ruby
+transcribe(audio_url,
+  sentiment: true,   # per-sentence sentiment scores
+  topics:    true,   # topic detection
+  intents:   true,   # intent recognition
+  summarize: true    # extractive summary
+)
+```
+
+Results accessible via `result.raw["results"]["channels"][0]["alternatives"][0]`.
+
+---
+
+### AssemblyAI Universal-2
+
+| | |
+|---|---|
+| **Sync** | **No** — async: upload → submit → poll |
+| **Diarization** | Yes (`diarize true`) |
+| **Word timestamps** | Yes (millisecond precision) |
+| **Languages** | 99+ |
+| **Pricing** | `$0.0025/min` base + `$0.0003/min` speaker labels ≈ `$0.0028/min` |
+| **Free tier** | 333 hr/month |
+
+```ruby
+Igniter::LLM.configure do |c|
+  c.assemblyai.api_key      = ENV["ASSEMBLYAI_API_KEY"]
+  c.assemblyai.poll_interval = 3    # seconds between status checks
+  c.assemblyai.poll_timeout  = 600  # fail-safe timeout in seconds
+end
+
+class CallTranscriber < Igniter::LLM::Transcriber
+  transcription_provider :assemblyai
+  diarize true
+  poll_interval 3
+  poll_timeout  600
+
+  def call(audio_url:) = transcribe(audio_url)
+end
+```
+
+**Extra options:**
+```ruby
+transcribe(audio_url,
+  sentiment_analysis: true,
+  auto_chapters:      true,
+  entity_detection:   true,
+  pii_redact:         [:phone_number, :name, :email],
+  custom_vocabulary:  ["Acme", "thermidor"]
+)
+```
+
+---
+
+## Provider comparison
+
+| Need | Recommended |
+|------|-------------|
+| Lowest cost, no speakers | `openai` + `gpt-4o-mini-transcribe` — $0.003/min |
+| Lowest cost WITH speakers | `assemblyai` — $0.0028/min |
+| Fastest response (sync) | `deepgram` — typical < 2 s |
+| Richest features | `assemblyai` — chapters, PII, entity detection |
+| Real-time / WebSocket | `deepgram` — same price as REST |
+
+---
+
+## DSL reference
+
+```ruby
+class MyTranscriber < Igniter::LLM::Transcriber
+  # ── Required ──────────────────────────────────────────────────────────
+  transcription_provider :openai   # :openai | :deepgram | :assemblyai
+
+  # ── Optional ──────────────────────────────────────────────────────────
+  model "nova-3"            # defaults: openai→whisper-1, deepgram→nova-3,
+                            #          assemblyai→universal-2
+  language "en"             # BCP-47; nil = auto-detect
+  diarize true              # request speaker labels (not supported by OpenAI)
+  word_timestamps true      # per-word start/end times (default: true)
+
+  # AssemblyAI async polling
+  poll_interval 3           # seconds between poll attempts (default: 2)
+  poll_timeout  600         # max seconds to wait (default: 300)
+
+  def call(**inputs)
+    transcribe(inputs[:audio_url])
+    # or with provider-specific extras:
+    transcribe(inputs[:audio_url], sentiment: true, topics: true)
+  end
+end
+```
+
+---
+
+## Result structure
+
+```ruby
+result = MyTranscriber.call(audio_url: "call.mp3")
+
+result.text       # => "Hello, thank you for calling..."
+result.language   # => "en"
+result.duration   # => 243.5   (seconds)
+result.provider   # => :assemblyai
+result.model      # => "universal-2"
+result.raw        # => Hash — original provider response
+
+# Word-level timestamps
+result.words.first
+# => #<TranscriptWord word="Hello" start_time=0.0 end_time=0.4 confidence=0.99 speaker="A">
+
+# Speaker segments (when diarize: true)
+result.speakers
+# => [
+#   #<SpeakerSegment speaker="A" start_time=0.0  end_time=5.1  text="Hello, thank you...">,
+#   #<SpeakerSegment speaker="B" start_time=5.3  end_time=12.4 text="Hi, I need help...">,
+#   ...
+# ]
+```
+
+> **Note:** AssemblyAI uses letter labels (`"A"`, `"B"`, ...).
+> Deepgram uses integers (`0`, `1`, ...).
+> OpenAI has no speaker labels — `speakers` is `nil`.
+
+---
+
+## In a Contract graph
+
+Transcriber is a full `Igniter::Executor`. Use it as a `compute:` node
+with `cache_ttl:` to avoid re-transcribing the same audio on retries:
+
+```ruby
+class CallAnalysisPipeline < Igniter::Contract
+  define do
+    input :audio_url
+    input :recorded_at, required: false
+
+    compute :transcript, call: CallTranscriber,
+                         with: :audio_url,
+                         cache_ttl: 86_400   # 24 h — same URL = free
+
+    compute :extraction, call: CallExtractor,
+                         with: %i[transcript recorded_at]
+
+    output :transcript, from: :transcript
+    output :extraction, from: :extraction
+  end
+end
+
+result = CallAnalysisPipeline.call(
+  audio_url:   "https://cdn.callrail.com/recordings/abc123.mp3",
+  recorded_at: call.created_at.iso8601
+)
+result[:transcript]  # => TranscriptResult
+result[:extraction]  # => Hash from LLM analysis
+```
+
+---
+
+## Production: call-center CRM (Rails)
+
+See `examples/llm/call_center_analysis.rb` for a complete runnable example.
+
+### Volume / cost estimate (27 000 min/month)
+
+```
+AssemblyAI (transcript + diarization)   ≈  $77/month
+gpt-4o-mini (extraction, 14 000 calls)  ≈   $4/month
+                                         ─────────────
+Total                                    ≈  $81/month
+```
+
+### Rails integration sketch
+
+```ruby
+# app/models/call_recording.rb
+class CallRecording < ApplicationRecord
+  after_create_commit :schedule_analysis, if: :audio_url?
+
+  private
+
+  def schedule_analysis = CallAnalysisJob.perform_later(id)
+end
+
+# app/jobs/call_analysis_job.rb
+class CallAnalysisJob < ApplicationJob
+  queue_as :transcription
+  sidekiq_options retry: 3
+
+  def perform(id)
+    rec    = CallRecording.find(id)
+    result = CallAnalysisPipeline.call(
+      audio_url:   rec.audio_url,
+      recorded_at: rec.created_at.iso8601
+    )
+    t = result[:transcript]
+    e = result[:extraction]
+
+    rec.update!(
+      transcript_text:  t.text,
+      duration_seconds: t.duration,
+      speakers_json:    t.speakers&.map(&:to_h),
+      conversion:       e["conversion"],
+      call_type:        e["call_type"],
+      zip_codes:        e["zip_codes"],
+      addresses:        e["addresses"],
+      phones:           e["phones"],
+      service_names:    e["service_names"],
+      scheduled_at:     e["scheduled_datetime"]&.then { Time.parse(_1) },
+      ai_confidence:    e["confidence"],
+      ai_notes:         e["notes"]
+    )
+  end
+end
+```
+
+### Recommended PostgreSQL columns
+
+```ruby
+add_column :call_recordings, :transcript_text,  :text
+add_column :call_recordings, :duration_seconds, :float
+add_column :call_recordings, :speakers_json,    :jsonb,  default: []
+add_column :call_recordings, :conversion,       :boolean
+add_column :call_recordings, :call_type,        :string
+add_column :call_recordings, :zip_codes,        :string, array: true, default: []
+add_column :call_recordings, :addresses,        :string, array: true, default: []
+add_column :call_recordings, :phones,           :string, array: true, default: []
+add_column :call_recordings, :service_names,    :string, array: true, default: []
+add_column :call_recordings, :scheduled_at,     :datetime
+add_column :call_recordings, :ai_confidence,    :float
+add_column :call_recordings, :ai_notes,         :text
+
+# Useful indexes
+add_index :call_recordings, :conversion
+add_index :call_recordings, :call_type
+add_index :call_recordings, :zip_codes,     using: :gin
+add_index :call_recordings, :service_names, using: :gin
+```
+
+---
+
+## Roadmap: Real-time operator assistance (Asterisk)
+
+Once you own the Asterisk PBX, the path to live analysis:
+
+```
+Asterisk RTP stream
+      │  (audio chunks via AGI/AMI)
+      ▼
+Deepgram WebSocket
+      │  partial + final transcript events
+      ▼
+Igniter Actor (CallMonitorAgent)
+      │  detects key events in real-time
+      ▼
+ActionCable → Operator UI
+      │  "ZIP 77001 detected — pull nearby techs"
+      │  "Customer says 'Samsung washer' — show checklist"
+      │  "Sentiment dropping — offer discount code"
+```
+
+**Cost for real-time Deepgram:** same `$0.0077/min` (no surcharge vs REST).
+Total with real-time: ~$212/month vs $81/month batch.
+The premium pays for live operator assistance and reduced handle time.
+
+### Agent sketch
+
+```ruby
+class CallMonitorAgent < Igniter::Agent
+  on :transcript_chunk do |payload|
+    text = payload[:text]
+    next if text.length < 40   # wait for meaningful chunks
+
+    hints = ContextExtractor.call(partial_text: text)
+    next if hints.empty?
+
+    broadcast(:operator_hint,
+      call_id:     payload[:call_id],
+      operator_id: payload[:operator_id],
+      hints:       hints)
+  end
+end
+```
+
+---
+
+## Configuration reference
+
+```ruby
+Igniter::LLM.configure do |c|
+  # OpenAI (used by both chat executors and openai transcription provider)
+  c.openai.api_key  = ENV["OPENAI_API_KEY"]
+  c.openai.base_url = "https://api.openai.com"  # override for Azure/proxy
+  c.openai.timeout  = 120
+
+  # Deepgram
+  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
+  c.deepgram.timeout = 300   # pre-recorded audio; allow for large files
+
+  # AssemblyAI
+  c.assemblyai.api_key       = ENV["ASSEMBLYAI_API_KEY"]
+  c.assemblyai.poll_interval = 3    # start polling after N seconds
+  c.assemblyai.poll_timeout  = 600  # raise ProviderError if not done in time
+end
+```

data/examples/README.md

@@ -328,6 +328,43 @@ log_entries=1
 done=true
 ```
 
+### `companion/demo.rb`
+
+Run:
+
+```bash
+ruby examples/companion/demo.rb
+```
+
+Shows:
+
+- `Igniter::Application` — unified entry point with `config_file`, `configure`, `register`, `schedule`
+- `compose` + `export` — four-stage pipeline (ASR → Intent → Chat → TTS) wired as one graph
+- Mock executors — runs end-to-end without hardware or API keys
+- Turn-by-turn interactive loop with session history
+
+For real Ollama inference:
+
+```bash
+COMPANION_REAL_LLM=1 ruby examples/companion/demo.rb
+```
+
+Expected output per turn:
+
+```text
+── Turn 1 ────────────────────────────────────────────
+  [ASR mock]    → "Hello, are you there?"
+  [Intent mock] → question
+  [Chat mock]   → "I'd need a moment to look that up..."
+  [TTS mock]    → synthesising 76 chars
+  Heard:    "Hello, are you there?"
+  Intent:   question (92%)
+  Response: "I'd need a moment to look that up..."
+  Audio:    4328 chars (Base64 WAV)
+```
+
+See [`companion/README.md`](companion/README.md) for distributed deployment (k3s), ESP32 setup, and real hardware instructions.
+
 ## Validation
 
 These scripts are exercised by [example_scripts_spec.rb](/Users/alex/dev/hotfix/igniter/spec/igniter/example_scripts_spec.rb), so the documented commands and outputs stay aligned with the code.

data/examples/consensus.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# examples/consensus.rb
+#
+# Demonstrates Igniter::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::Consensus::Node. Users only interact
+# with Cluster and, optionally, a custom StateMachine subclass.
+#
+# Run: bundle exec ruby examples/consensus.rb
+
+require "igniter/consensus"
+
+puts "=" * 62
+puts "  Igniter::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::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::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::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::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::Consensus::ELECTION_TIMEOUT_BASE +
+      Igniter::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::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."