igniter 0.5.0 → 0.5.2

data/examples/README.md

@@ -1,370 +1,178 @@
 # 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).
+`examples/` is now the contracts-native runnable surface for Igniter.
 
-## Available Scripts
+Active examples are limited to:
 
-### `basic_pricing.rb`
+- `igniter-contracts`
+- `igniter-extensions`
+- `igniter-application`
+- `igniter-ai`
+- `igniter-agents`
+- `igniter-hub`
+- `igniter-cluster`
+- `igniter-mcp-adapter`
 
-Run:
+Older demos were moved out of the active tree and should not be treated as
+current reference material.
 
-```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:
-
-```bash
-ruby examples/composition.rb
-```
-
-Shows:
-
-- 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:
-
-```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:
-
-```bash
-ruby examples/marketing_ergonomics.rb
-```
-
-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
-```
+## Runner
 
-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:
+From the project root:
 
 ```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 ---
-...
+ruby examples/run.rb list
+ruby examples/run.rb smoke
+ruby examples/run.rb all
+ruby examples/run.rb run contracts/basic_pricing
 ```
 
-### `agents.rb`
+`smoke` and `all` currently point at the same active catalog: the runnable
+contracts-native examples we keep green.
 
-Run:
+There is also a matching rake task:
 
 ```bash
-ruby examples/agents.rb
+rake examples
 ```
 
-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:
+For app-level evaluation, start with the flagship application checks:
 
 ```bash
-ruby examples/companion/demo.rb
+ruby examples/run.rb run application/companion_poc
+ruby examples/run.rb run application/lense_poc
+ruby examples/run.rb run application/chronicle_poc
+ruby examples/run.rb run application/scout_poc
+ruby examples/run.rb run application/dispatch_poc
 ```
 
-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
+These are the richer current application examples. Companion is the
+ready-to-go assistant shell; the others are focused workflow showcases. Their
+portfolio guide lives at
+[Application Showcase Portfolio](../docs/guide/application-showcase-portfolio.md).
 
-For real Ollama inference:
+The focused contracts/lang checks are:
 
 ```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.
+ruby examples/run.rb run contracts/class_pricing
+ruby examples/run.rb run contracts/class_callable
+ruby examples/run.rb run contracts/embed_class_registration
+ruby examples/run.rb run contracts/contractable_shadow
+ruby examples/run.rb run contracts/step_result
+ruby examples/run.rb run contracts/lang_foundation
+```
+
+## Active Example Lane
+
+Active runnable examples live in `examples/application/`,
+`examples/contracts/`, and `examples/cluster/`:
+
+- `application/blueprint.rb`
+- `application/capsule_layout.rb`
+- `application/capsule_authoring_dsl.rb`
+- `application/capsule_assembly_plan.rb`
+- `application/capsule_composition.rb`
+- `application/capsule_handoff_manifest.rb`
+- `application/capsule_host_activation_commit_readiness.rb`
+- `application/capsule_host_activation_dry_run.rb`
+- `application/capsule_host_activation_plan.rb`
+- `application/capsule_host_activation_plan_verification.rb`
+- `application/capsule_host_activation_readiness.rb`
+- `application/capsule_host_activation_ledger_adapter.rb`
+- `application/capsule_inspection.rb`
+- `application/capsule_manifest.rb`
+- `application/interactive_web_poc.rb`
+- `application/signal_inbox_poc.rb`
+- `application/lense_poc.rb`
+- `application/chronicle_poc.rb`
+- `application/scout_poc.rb`
+- `application/dispatch_poc.rb`
+- `application/capsule_transfer_applied_verification.rb`
+- `application/capsule_agent_transfer.rb`
+- `application/capsule_transfer_apply_execution.rb`
+- `application/capsule_transfer_apply_plan.rb`
+- `application/capsule_transfer_bundle_artifact.rb`
+- `application/capsule_transfer_bundle_plan.rb`
+- `application/capsule_transfer_bundle_verification.rb`
+- `application/capsule_transfer_end_to_end.rb`
+- `application/capsule_transfer_intake_plan.rb`
+- `application/capsule_transfer_inventory.rb`
+- `application/capsule_transfer_receipt.rb`
+- `application/capsule_transfer_readiness.rb`
+- `application/feature_flow_report.rb`
+- `application/flow_session.rb`
+- `application/layout.rb`
+- `application/mounts.rb`
+- `application/web_mount.rb`
+- `application/web_surface_structure.rb`
+- `application/web_surface_manifest.rb`
+- `application/agent_native_plan_review.rb`
+- `application/structure_plan.rb`
+- `cluster/incidents.rb`
+- `cluster/incident_workflow.rb`
+- `cluster/mesh_diagnostics.rb`
+- `cluster/remediation.rb`
+- `cluster/routing.rb`
+
+- `contracts/basic_pricing.rb`
+- `contracts/class_pricing.rb`
+- `contracts/class_callable.rb`
+- `contracts/contractable_service.rb`
+- `contracts/embed_class_registration.rb`
+- `contracts/contractable_shadow.rb`
+- `contracts/embed_human_sugar.rb`
+- `contracts/step_result.rb`
+- `contracts/lang_foundation.rb`
+- `contracts/aggregates.rb`
+- `contracts/auditing.rb`
+- `contracts/branching.rb`
+- `contracts/formula.rb`
+- `contracts/piecewise.rb`
+- `contracts/scale.rb`
+- `contracts/build_effect_executor_pack.rb`
+- `contracts/build_your_own_pack.rb`
+- `contracts/capabilities.rb`
+- `contracts/collection.rb`
+- `contracts/commerce.rb`
+- `contracts/composition.rb`
+- `contracts/compose_your_own_packs.rb`
+- `contracts/content_addressing.rb`
+- `contracts/create_pack.rb`
+- `contracts/dataflow.rb`
+- `contracts/debug.rb`
+- `contracts/debug_pack_authoring.rb`
+- `contracts/diagnostics.rb`
+- `contracts/differential.rb`
+- `contracts/effects.rb`
+- `contracts/incremental.rb`
+- `contracts/introspection.rb`
+- `contracts/invariants.rb`
+- `contracts/journal.rb`
+- `contracts/mcp.rb`
+- `contracts/mcp_host.rb`
+- `contracts/mcp_server.rb`
+- `contracts/provenance.rb`
+- `contracts/reactive.rb`
+- `contracts/saga.rb`
+
+These are the examples the runner and the current root specs validate.
+
+`application/interactive_web_poc.rb` is a stable launcher. The copyable
+app-local skeleton for that POC lives in
+`application/interactive_operator/`.
+
+`application/signal_inbox_poc.rb` repeats the same application/web pattern in a
+non-task signal inbox domain. Its copyable skeleton lives in
+`application/operator_signal_inbox/`.
+
+## Archive Note
+
+Legacy-root demos and migration scripts were moved out of the active example
+lane. We are not treating them as the current framework surface anymore; they
+will be recreated intentionally on top of the new package graph.
 
 ## 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](./catalog.rb). Both
+[run.rb](./run.rb) and the current root specs under
+[spec/current](../spec/current) use that same source of truth.