igniter 0.5.0 → 0.5.1

data/bin/igniter-stack

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+
+options = {
+  port: 4567,
+  host: "0.0.0.0",
+  requires: [],
+  config: nil,
+  minimal: false,
+  profile: nil
+}
+
+global = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    igniter-stack — stack scaffold and HTTP server toolkit for Igniter
+
+    Usage:
+      igniter-stack start [options]
+      igniter-stack new APP_NAME [--minimal] [--profile dashboard|cluster|playground]
+
+  BANNER
+
+  opts.on("--port PORT", Integer, "Port to listen on (default: 4567)") { |v| options[:port] = v }
+  opts.on("--host HOST",          "Host to bind to (default: 0.0.0.0)") { |v| options[:host] = v }
+  opts.on("--require FILE",       "Require a file (can be used multiple times)") { |v| options[:requires] << v }
+  opts.on("--config FILE",        "Load a server config file") { |v| options[:config] = v }
+  opts.on("--minimal",            "Skip demo scaffold — only create directory structure") { options[:minimal] = true }
+  opts.on("--profile NAME",       "Scaffold profile (e.g. dashboard, cluster, playground)") { |v| options[:profile] = v }
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit
+  end
+  opts.on("-v", "--version", "Show version") do
+    require "igniter/core/version"
+    puts "igniter-stack #{Igniter::VERSION}"
+    exit
+  end
+end
+
+global.parse!
+
+command = ARGV.shift || "start"
+
+case command
+when "start"
+  options[:requires].each { |f| require File.expand_path(f) }
+  load File.expand_path(options[:config]) if options[:config]
+
+  require "igniter/server"
+  require "igniter/core/version"
+
+  Igniter::Server.start(port: options[:port], host: options[:host])
+
+when "new"
+  app_name = ARGV.shift
+  if app_name.nil? || app_name.strip.empty?
+    warn "Usage: igniter-stack new APP_NAME"
+    exit 1
+  end
+
+  if File.exist?(app_name)
+    warn "Error: '#{app_name}' already exists"
+    exit 1
+  end
+
+  require "igniter/app/scaffold_pack"
+
+  mode = options[:minimal] ? " (minimal)" : ""
+  puts "Creating Igniter stack '#{app_name}'#{mode}..."
+  generator_class =
+    case options[:profile].to_s.strip
+    when "", "default", "base"
+      Igniter::App::Generator
+    when "dashboard"
+      Igniter::App::Generators::Dashboard
+    when "cluster"
+      Igniter::App::Generators::Cluster
+    when "playground"
+      Igniter::App::Generators::Playground
+    else
+      warn "Unknown scaffold profile: #{options[:profile].inspect}"
+      warn "Available profiles: dashboard, cluster, playground"
+      exit 1
+    end
+
+  generator_class.new(app_name, minimal: options[:minimal]).generate
+
+else
+  warn "Unknown command: #{command}"
+  warn "Available commands: start, new"
+  exit 1
+end

data/docs/README.md

@@ -0,0 +1,62 @@
+# Igniter Docs
+
+`docs/` is organized by section. Start here, then jump into the lane that matches
+what you are trying to do.
+
+## Sections
+
+- [Guide](./guide/README.md) for user-facing docs: getting started, API,
+  configuration, integrations, and how-tos
+- [Concepts](./concepts/README.md) for mental models and design language
+- [Current](./current/README.md) for active current-state notes and near-term
+  direction
+- [Dev](./dev/README.md) for internal architecture, package boundaries, and
+  roadmap work
+- [Assets](./assets/README.md) for shared documentation media such as logos
+
+## Reading Paths
+
+### I want to use Igniter
+
+1. [Guide](./guide/README.md)
+2. [Getting Started](./guide/getting-started.md)
+3. [Core Runtime Features](./guide/core-runtime-features.md)
+4. [Concepts](./concepts/README.md)
+5. [Examples](../examples/README.md)
+
+### I want to build an app or stack
+
+1. [Guide](./guide/README.md)
+2. [How-Tos](./guide/how-tos.md)
+3. [App](./guide/app.md)
+4. [CLI](./guide/cli.md)
+5. [Companion example](../examples/companion/README.md)
+
+### I want distributed execution
+
+1. [Guide](./guide/README.md)
+2. [Deployment Modes](./guide/deployment-modes.md)
+3. [Distributed Workflows](./guide/distributed-workflows.md)
+4. [Cluster](./guide/cluster.md)
+5. [Current](./current/README.md)
+
+### I want to work on the framework
+
+1. [Dev](./dev/README.md)
+2. [Architecture](./dev/architecture.md)
+3. [Module System](./dev/module-system.md)
+4. [Package Map](./dev/package-map.md)
+5. [Roadmap](./dev/roadmap.md)
+
+## Package Docs
+
+Package-local quick reference belongs next to the owning gem under
+`packages/<gem>/README.md`.
+
+Cross-package product docs belong in [`guide/`](./guide/README.md),
+cross-package mental models in [`concepts/`](./concepts/README.md), active
+current-state notes in [`current/`](./current/README.md), and internal design
+work in [`dev/`](./dev/README.md).
+
+Legacy deep reference is cataloged in
+[`dev/legacy-reference.md`](./dev/legacy-reference.md).

data/examples/README.md

@@ -1,370 +1,95 @@
 # Examples
 
-These scripts are intended to be runnable entry points for new users.
-Each one can be executed directly from the project root with `ruby examples/<name>.rb`.
-For higher-level guidance on when to use each style, see [PATTERNS.md](/Users/alex/dev/hotfix/igniter/docs/PATTERNS.md).
+These scripts are the runnable showcase for Igniter's core APIs, runtime flows,
+and package boundaries.
 
-## Available Scripts
+For a higher-level public stack consumer, see
+[examples/companion](/Users/alex/dev/projects/igniter/examples/companion/README.md).
+`examples/` keeps both:
 
-### `basic_pricing.rb`
+- small runnable scripts for focused API/runtime slices
+- larger public proving grounds like `companion`
 
-Run:
+## Runner
 
-```bash
-ruby examples/basic_pricing.rb
-```
-
-Shows:
-
-- defining a basic contract
-- lazy output resolution through `result`
-- selective recomputation after `update_inputs`
-
-Expected output:
-
-```text
-gross_total=120.0
-updated_gross_total=180.0
-```
-
-### `composition.rb`
-
-Run:
+From the project root:
 
 ```bash
-ruby examples/composition.rb
+ruby examples/run.rb list
+ruby examples/run.rb smoke
+ruby examples/run.rb all
+ruby examples/run.rb run basic_pricing
 ```
 
-Shows:
+`smoke` runs the self-contained examples we keep green in CI. `all` prints the
+same pass/fail report but also shows manual or not-yet-updated examples as
+skipped with a reason.
 
-- nested contracts through `compose`
-- returning child results through an output
-- serializing composed output values with `result.to_h`
-
-Expected output:
-
-```text
-pricing={:pricing=>{:gross_total=>120.0}}
-```
-
-### `diagnostics.rb`
-
-Run:
+There is also a matching rake task:
 
 ```bash
-ruby examples/diagnostics.rb
-```
-
-Shows:
-
-- diagnostics text summary
-- machine-readable `result.as_json`
-- execution state visibility after a successful run
-
-Expected output shape:
-
-```text
-Diagnostics PriceContract
-Execution <uuid>
-Status: succeeded
-Outputs: gross_total=120.0
-...
----
-{:graph=>"PriceContract", ...}
-```
-
-### `async_store.rb`
-
-Run:
-
-```bash
-ruby examples/async_store.rb
-```
-
-Shows:
-
-- deferred executor output through `defer`
-- file-backed pending execution store
-- restore and resume flow through `resume_from_store`
-
-Expected output shape:
-
-```text
-pending_token=quote-100
-stored_execution_id=<uuid>
-pending_status=true
-resumed_gross_total=180.0
-```
-
-### `marketing_ergonomics.rb`
-
-Run:
+rake examples
+```
+
+For higher-level guidance on when to use each orchestration style, see
+[patterns](../docs/concepts/patterns.md).
+
+## Smoke Examples
+
+- `agents.rb` — supervision, registry lookups, and stream loops.
+- `agent_orchestration.rb` — current `agent` node orchestration, deferred replies, and provenance.
+- `async_store.rb` — deferred execution with store-backed resume.
+- `basic_pricing.rb` — smallest end-to-end contract example.
+- `collection.rb` — `collection` fan-out and `CollectionResult`.
+- `collection_partial_failure.rb` — partial-failure collection diagnostics.
+- `composition.rb` — nested contracts via `compose`.
+- `consensus.rb` — consensus-style vendor bid selection.
+- `dataflow.rb` — incremental collections and maintained aggregates.
+- `diagnostics.rb` — text diagnostics and `as_json` output.
+- `differential.rb` — differential execution against a shadow path.
+- `distributed_server.rb` — `await` / `deliver_event` lifecycle with a store.
+- `distributed_workflow.rb` — correlated external events merged into one report.
+- `effects.rb` — effect nodes, effect registry, and saga compensation.
+- `incremental.rb` — incremental recomputation and memoization.
+- `introspection.rb` — graph text, Mermaid output, plan explanation, and runtime explain output.
+- `invariants.rb` — invariants plus property-based testing.
+- `llm/research_agent.rb` — LLM planning + awaited tool results with mock fallback.
+- `llm/tool_use.rb` — offline tool-use pipeline with a mock provider.
+- `llm_tools.rb` — tool schemas, capability checks, and tool registry.
+- `marketing_ergonomics.rb` — ergonomic DSL helpers on a compact graph.
+- `mesh.rb` — static mesh routing behaviour.
+- `mesh_gossip.rb` — peer convergence through gossip.
+- `order_pipeline.rb` — guard + collection + branch + export.
+- `provenance.rb` — provenance and output traceability.
+- `reactive_auditing.rb` — reactive hooks plus audit timeline snapshots.
+- `ringcentral_routing.rb` — webhook routing with nested collections.
+- `saga.rb` — saga rollback walkthrough.
+
+## Manual Examples
+
+- `llm/call_center_analysis.rb` — requires an `audio_url` argument.
+
+Run it like this:
 
 ```bash
-ruby examples/marketing_ergonomics.rb
+ruby examples/run.rb run llm/call_center_analysis https://example.com/audio.mp3
 ```
 
-Shows:
-
-- ergonomic helpers `with`, `const`, `lookup`, `map`, matcher-style `guard`, `expose`
-- success-side-effect shorthand via `on_success`
-- structural grouping via `scope` and `namespace`
-- pre-execution planning via `contract.explain_plan`
-- a domain-style contract that stays compact without hiding the graph
-
-Expected output shape:
-
-```text
-Plan MarketingQuoteContract
-Targets: quote
-...
----
-response={:vendor_id=>"eLocal", :trade=>"HVAC", :zip_code=>"60601", :bid=>45.0}
-outbox=[{:vendor_id=>"eLocal", :zip_code=>"60601"}]
-```
-
-### `collection.rb`
-
-Run:
-
-```bash
-ruby examples/collection.rb
-```
-
-Shows:
-
-- declarative fan-out via `collection`
-- stable item identity via `key:`
-- `CollectionResult` output surface
-- per-item child contract results in `:collect` mode
-
-Expected output shape:
-
-```text
-keys=[1, 2]
-items={1=>{:key=>1, :status=>:succeeded, ...}, 2=>{:key=>2, :status=>:succeeded, ...}}
-```
-
-### `collection_partial_failure.rb`
-
-Run:
-
-```bash
-ruby examples/collection_partial_failure.rb
-```
-
-Shows:
-
-- `collection` in `mode: :collect`
-- `CollectionResult#summary`
-- `CollectionResult#items_summary`
-- `CollectionResult#failed_items`
-- diagnostics output for partial collection failure without failing the whole execution
-
-Expected output shape:
-
-```text
-summary={:mode=>:collect, :total=>3, :succeeded=>2, :failed=>1, :status=>:partial_failure}
-items_summary={1=>{:status=>:succeeded}, 2=>{:status=>:failed, ...}, ...}
-failed_items={2=>{:type=>"Igniter::ResolutionError", ...}}
-```
-
-### `ringcentral_routing.rb`
-
-Run:
-
-```bash
-ruby examples/ringcentral_routing.rb
-```
-
-Shows:
-
-- top-level routing via `branch`
-- nested fan-out via `collection`
-- trivial field extraction via `project`
-- compact summary building via `aggregate`
-- item input shaping via `collection map_inputs:` or `using:`
-- per-item nested routing via another `branch`
-- `CollectionResult` summary on the selected child contract
-- the practical boundary between parent diagnostics and child diagnostics
-
-Expected output shape:
-
-```text
-Plan RingcentralWebhookContract
-...
----
-routing_summary={:extension_id=>62872332031, ...}
-status_route_branch=CallConnected
-child_collection_summary={:mode=>:collect, :total=>3, ...}
-```
-
-### `order_pipeline.rb`
-
-Run:
-
-```bash
-ruby examples/order_pipeline.rb
-```
-
-Shows:
-
-- `guard` — abort early when a precondition is not met
-- `collection` — fan-out via `LineItemContract` per line item
-- `branch` — route to domestic or international shipping strategy
-- `export` — lift branch outputs (`shipping_cost`, `eta`) to the parent graph
-- end-to-end pipeline: items → subtotal → shipping → grand total
-
-Expected output shape:
-
-```text
-=== US Order ===
-items_summary={:mode=>:collect, :total=>3, :succeeded=>3, :failed=>0, :status=>:succeeded}
-order_subtotal=199.96
-shipping_cost=0.0
-eta=2-3 business days
-grand_total=199.96
-
-=== International Order (DE) ===
-shipping_cost=29.99
-eta=7-14 business days
-grand_total=229.95
-
-=== Out of Stock ===
-error=Order cannot be placed: items are out of stock
-```
-
-### `distributed_server.rb`
-
-Run:
-
-```bash
-ruby examples/distributed_server.rb
-```
-
-Shows:
-
-- `correlate_by` — tag a contract class with correlation keys
-- `Contract.start` — launch an execution that suspends at `await` nodes
-- `Contract.deliver_event` — resume a suspended execution with an event payload
-- `on_success` — callback that fires when the graph completes
-- full lifecycle: submit → screening event → manager event → decision
-
-Expected output shape:
-
-```text
-=== Step 1: Application submitted ===
-pending=true
-waiting_for=[:screening_completed]
-
-=== Step 2: Background screening completed ===
-still_pending=true
-
-=== Step 3: Manager review completed ===
-[callback] Decision reached: HIRED
-
-=== Final result ===
-success=true
-decision={:status=>:hired, :note=>"Excellent system design skills"}
-```
-
-### `llm/tool_use.rb`
-
-Run:
-
-```bash
-ruby examples/llm/tool_use.rb
-```
-
-Shows:
-
-- chained LLM compute nodes (`classify → assess priority → draft response`)
-- tool declaration with the class-level `tools` method
-- conversation context with `Igniter::LLM::Context` for multi-turn messages
-- mock provider so the example runs offline without an API key
-
-Expected output shape (with mock provider):
-
-```text
-=== Feedback Triage Pipeline ===
-category=category: bug_report
-priority=priority: high
-response=We have logged this issue and will address it in the next release.
-
---- Diagnostics ---
-...
-```
-
-### `agents.rb`
-
-Run:
-
-```bash
-ruby examples/agents.rb
-```
-
-Shows:
-
-- `Igniter::Agent` — stateful message-driven actor with `on` handlers and `schedule` timers
-- `Igniter::Supervisor` — one_for_one supervision with restart budget
-- `Igniter::Registry` — thread-safe lookup by name
-- `Igniter::StreamLoop` — continuous contract tick-loop with hot-swap inputs
-
-Expected output shape:
-
-```text
-=== Supervised agents ===
-counter=8
-after_reset=10
-history=[10]
-
-=== Registry lookup ===
-named_counter=42
-
-=== Stream loop ===
-statuses_sample=[:alert, :normal]
-
-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)
-```
+## Pending Refresh
 
-See [`companion/README.md`](companion/README.md) for distributed deployment (k3s), ESP32 setup, and real hardware instructions.
+- `mesh_discovery.rb` — the script documents the dynamic discovery flow, but it
+  still needs a refresh for the current mesh router API before it can rejoin
+  the smoke suite.
+- `server/node1.rb`
+- `server/node2.rb`
+  These are long-lived multi-terminal server demos and still use the older
+  entrypoint layout, so they are intentionally not part of the automated runner.
+- `elocal_webhook.rb` — placeholder stub, no executable walkthrough yet.
 
 ## 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.
+The catalog lives in [catalog.rb](/Users/alex/dev/projects/igniter/examples/catalog.rb).
+Both [run.rb](/Users/alex/dev/projects/igniter/examples/run.rb) and the specs
+[example_scripts_spec.rb](/Users/alex/dev/projects/igniter/spec/igniter/example_scripts_spec.rb)
+and [example_runner_spec.rb](/Users/alex/dev/projects/igniter/spec/igniter/example_runner_spec.rb)
+use that same source of truth.

data/examples/agent_orchestration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/provenance"
+
+class ReviewQueueAdapter
+  def call(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+    {
+      status: :pending,
+      payload: {
+        queue: :review,
+        requested_name: inputs.fetch(:name)
+      },
+      agent_trace: {
+        adapter: :queue,
+        mode: :call,
+        via: node.agent_name,
+        message: node.message_name,
+        outcome: :deferred,
+        reason: :awaiting_review
+      }
+    }
+  end
+
+  def cast(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+    {
+      status: :succeeded,
+      output: nil,
+      agent_trace: {
+        adapter: :queue,
+        mode: :cast,
+        via: node.agent_name,
+        message: node.message_name,
+        outcome: :sent
+      }
+    }
+  end
+end
+
+class AgentOrchestrationContract < Igniter::Contract
+  runner :inline, agent_adapter: ReviewQueueAdapter.new
+
+  define do
+    input :name, type: :string
+
+    agent :approval,
+          via: :reviewer,
+          message: :review,
+          inputs: { name: :name }
+
+    agent :notify,
+          via: :reviewer,
+          message: :remember,
+          mode: :cast,
+          inputs: { name: :name }
+
+    output :approval
+    output :notify
+  end
+end
+
+contract = AgentOrchestrationContract.new(name: "Alice")
+approval = contract.result.approval
+plan = contract.orchestration_plan
+report = contract.diagnostics.to_h
+trace = contract.lineage(:approval).trace.value
+
+puts "contract_status=#{report[:status]}"
+puts "approval_pending=#{trace[:pending]}"
+puts "approval_token=#{approval.token}"
+puts "notify=#{contract.result.notify.inspect}"
+puts "attention_nodes=#{plan[:attention_nodes].inspect}"
+puts "actions=#{plan[:by_action].inspect}"
+puts "agents=#{report[:agents].slice(:total, :pending, :succeeded, :failed).inspect}"
+puts "lineage_reason=#{trace.dig(:agent_trace, :reason)}"

data/examples/agents.rb

@@ -12,7 +12,8 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "igniter"
-require "igniter/integrations/agents"
+require "igniter/core"
+require "igniter-agents"
 
 # ── Contract used by the stream loop ─────────────────────────────────────────