igniter 0.5.1 → 0.5.2

data/docs/guide/igniter-lang-foundation.md

@@ -0,0 +1,133 @@
+# Igniter Lang Foundation
+
+Igniter Lang is currently an additive contracts-facing foundation, not a
+separate production language runtime.
+
+Use it when you want a small reference surface for:
+
+- loading the Lang namespace with `require "igniter/lang"`
+- compiling and executing through the current contracts runtime
+- attaching definition-time descriptors such as `History`, `BiHistory`,
+  `OLAPPoint`, and `Forecast`
+- inspecting a read-only `VerificationReport`
+- seeing declared metadata in a report-only `MetadataManifest`
+
+## Quick Start
+
+Run the compact example:
+
+```bash
+ruby examples/contracts/lang_foundation.rb
+```
+
+For the accepted evaluator proof path, see
+[Getting Started](./getting-started.md).
+
+Minimal usage:
+
+```ruby
+require "igniter/lang"
+
+backend = Igniter::Lang.ruby_backend
+history_type = Igniter::Lang::History[Numeric]
+
+compiled = backend.compile do
+  input :price_history, type: history_type
+
+  compute :latest_price,
+          depends_on: [:price_history],
+          return_type: Numeric,
+          deadline: 50,
+          wcet: 20 do |price_history:|
+    price_history.fetch(:latest)
+  end
+
+  output :latest_price
+end
+
+result = backend.execute(compiled, inputs: { price_history: { latest: 120.0 } })
+report = backend.verify(compiled)
+
+result.output(:latest_price)
+report.metadata_manifest.to_h
+```
+
+## Ruby Backend Wrapper
+
+`Igniter::Lang.ruby_backend` returns `Igniter::Lang::Backends::Ruby`, a thin
+wrapper over the existing `Igniter::Contracts` compile, execute, diagnose, and
+verify surfaces.
+
+It does not introduce a new compiler, runtime, scheduler, parser, or AST. The
+compiled artifact is still a contracts artifact, and execution behavior stays
+the same as ordinary contracts execution.
+
+## Descriptors
+
+Descriptors are immutable definition-time metadata objects:
+
+```ruby
+Igniter::Lang::History[Numeric]
+Igniter::Lang::BiHistory[String]
+Igniter::Lang::OLAPPoint[Numeric, { region: String }]
+Igniter::Lang::Forecast[Float]
+```
+
+They can be attached to operation metadata, usually with `type:`. Today they are
+inspectable declarations. They are not physical unit checks, storage adapters,
+OLAP runtime handlers, temporal rules, or inferred type enforcement.
+
+## Verification Reports
+
+`backend.verify(...)` returns a read-only `Igniter::Lang::VerificationReport`.
+`ok?` follows current compilation findings only.
+
+The report exposes:
+
+- `descriptors`
+- `findings`
+- `metadata_manifest`
+- `to_h`
+
+## Metadata Manifest
+
+`Igniter::Lang::MetadataManifest` reports metadata that was already declared on
+operations:
+
+- `type:` descriptors
+- `return_type:`
+- `deadline:`
+- `wcet:`
+
+Manifest data is declared, not enforced. Requirement-like entries include
+`enforced: false`, and manifest semantics include:
+
+```ruby
+{
+  report_only: true,
+  runtime_enforced: false
+}
+```
+
+This means `return_type`, `deadline`, and `wcet` are visible in reports, but
+they do not create runtime checks, warnings, findings, deadline monitoring, or
+execution-result changes.
+
+## Deferred
+
+These remain future/research phases:
+
+- standalone grammar, parser, AST, and `.il` files
+- Rust backend and certified exports
+- store DSL or Lang metadata builder
+- contract persistence lowering to `Store[T]` / `History[T]`
+- OLAP, time-machine, and temporal-rule runtime behavior
+- physical unit algebra enforcement
+- invariant metadata integration
+- deadline/WCET runtime monitoring, warnings, or findings
+
+## Related
+
+- [Getting Started](./getting-started.md)
+- [Contract Class DSL](./contract-class-dsl.md)
+- [Contract Persistence Target Plan](../dev/contract-persistence-target-plan.md)

data/docs/guide/integrations.md

@@ -0,0 +1,47 @@
+# Integrations
+
+Use this page for environment-specific surfaces that adapt Igniter into a host
+framework or UI/runtime package.
+
+## Current Integration Surfaces
+
+- `require "igniter/plugins/rails"` for Rails integration
+- `require "igniter-web"` for current human-authored web surfaces
+- schema-driven rendering remains a guide-level authoring direction, not a
+  current package entrypoint in this repository
+
+## Rails Integration
+
+Use `require "igniter/plugins/rails"` when Rails is the host application and
+Igniter is embedded inside it.
+
+That entrypoint is intentionally narrow:
+
+- it loads the embedded Igniter kernel plus Rails adapters
+- it does not silently pull application hosting, web rendering, or cluster
+  coordination
+- it is the canonical public surface; `require "igniter/rails"` is not
+
+Reach for it when you want controllers, jobs, or channels to call contracts
+without promoting the whole app into a larger Igniter hosting profile.
+
+## Practical Split
+
+Use:
+
+- runtime layers for execution/hosting concerns
+- extension packs for optional shared capabilities
+- integrations for framework or environment adaptation
+
+For Rails specifically:
+
+- embedded Rails usage stays in integrations
+- app/server/cluster remain separate runtime choices
+- crossing into those layers should be explicit in code and docs
+
+## Current Reading Path
+
+- [App](./app.md)
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [`packages/igniter-web/README.md`](../../packages/igniter-web/README.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)

data/docs/guide/interactive-app-structure.md

@@ -0,0 +1,91 @@
+# Interactive App Structure
+
+Use this guide for small real applications that combine `igniter-application`
+and `igniter-web` without inventing a public framework API.
+
+This is a copyable convention, not a compatibility contract.
+
+## Current Examples
+
+- `examples/application/interactive_operator/`
+- `examples/application/operator_signal_inbox/`
+- `examples/application/lense/`
+- `examples/application/chronicle/`
+- `examples/application/scout/`
+- `examples/application/dispatch/`
+
+Run the richer showcases:
+
+```bash
+ruby examples/application/lense_poc.rb
+ruby examples/application/chronicle_poc.rb
+ruby examples/application/scout_poc.rb
+ruby examples/application/dispatch_poc.rb
+```
+
+Add `server` for manual browser review. Server mode is example scaffolding, not
+production server behavior.
+
+## App Shape
+
+- `app.rb` is the composition boundary.
+- `contracts/` owns deterministic business graphs.
+- `services/` owns loading, mutable state, commands, and snapshots.
+- `reports/` owns receipt/report artifacts when the workflow has evidence.
+- `web/` owns the mounted Arbre surface.
+- the launcher script owns smoke and optional server mode.
+
+Keep domain names, command results, snapshot fields, feedback codes, markers,
+routes, receipts, thresholds, and readiness rules local until repeated apps
+prove a package API is worth extracting.
+
+## Runtime Loop
+
+A serious one-process showcase should have:
+
+- app-local services that load inputs and own session state
+- one contracts-native graph for core analysis/readiness/payload
+- command routes that return app-local success/refusal results
+- deterministic action facts recorded at command boundaries
+- one detached snapshot shared by Web rendering, `/events`, and smoke
+- one receipt/report artifact when the workflow reaches a useful checkpoint
+- explicit mutation-boundary proof
+
+Do not imply hidden LLM calls, external connectors, schedulers, databases,
+auth, live transport, production hosting, or cluster placement in the first
+slice.
+
+## Web Surface
+
+Use one mounted web surface:
+
+- mount through `Igniter::Web.mount` and app-local `mount_web`
+- read state through `MountContext`
+- render from one app-owned snapshot
+- keep command routes in `app.rb`
+- expose stable app-local `data-` markers for smoke and manual review
+- keep `/events` on the same snapshot shape as the visible surface
+- add `/report` or `/receipt` only when the app owns a stable artifact
+
+Marker vocabulary is local. Do not extract a UI kit, marker DSL, route DSL, or
+`interactive_app` facade until repetition makes local readability worse.
+
+## Proof Checklist
+
+The smoke path should prove:
+
+- initial HTML render and top-level surface marker
+- one successful command path
+- one refusal path when the app has one
+- feedback marker and feedback code
+- domain counters/records through app-local `data-` markers
+- recent activity from the same snapshot
+- `/events` parity
+- receipt/report validity when present
+- no unintended fixture or target mutation
+
+Manual browser review should confirm the same seams through the printed local
+URL.
+
+For the showcase map, see
+[Application Showcase Portfolio](./application-showcase-portfolio.md).

data/docs/guide/store-adapters.md

@@ -0,0 +1,183 @@
+# Store Adapters
+
+This guide describes execution snapshot stores: persistence for contract
+executions, pending nodes, and resume flows.
+
+Do not confuse this with the newer contract persistence target, where ordinary
+contracts may declare record, workflow, credential-local, or signal persistence
+as part of their own capability. That direction is tracked in
+[Contract Persistence Target Plan](../dev/contract-persistence-target-plan.md).
+
+Igniter ships with reference execution stores for:
+
+- memory
+- file
+- sqlite
+- ActiveRecord-style persistence
+- Redis-style persistence
+
+All stores implement the same protocol:
+
+| Method | Description |
+|--------|-------------|
+| `save(snapshot, correlation: nil, graph: nil)` | Persist a snapshot; build secondary indexes for query |
+| `fetch(execution_id)` | Load a snapshot by ID; raises on missing |
+| `delete(execution_id)` | Remove a snapshot and clean up indexes |
+| `exist?(execution_id)` | Check existence without raising |
+| `find_by_correlation(graph:, correlation:)` | Find execution_id by correlation hash |
+| `list_all(graph: nil)` | All execution_ids, optionally filtered by graph name |
+| `list_pending(graph: nil)` | Execution_ids that have at least one node in `:pending` state |
+
+## Memory Store
+
+Useful for tests and single-process flows.
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::MemoryStore.new
+```
+
+## File Store
+
+Useful for local development and smoke-testing worker flows.
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(
+  root: Rails.root.join("tmp/igniter_executions")
+)
+```
+
+## SQLite Store
+
+Useful for single-node application profiles that want durable local execution
+snapshots without pulling in Redis or ActiveRecord.
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::SQLiteStore.new(
+  path: "var/igniter_executions.sqlite3"
+)
+```
+
+`sqlite3` now ships as a standard Igniter dependency, so this path works out of
+the box in the default stack and gem installation shape.
+
+The store keeps one row per execution snapshot and secondary indexes for:
+
+- `graph`
+- `pending`
+- `(graph, correlation_json)`
+
+## ActiveRecord Store
+
+Expected record shape:
+
+- one unique `execution_id` column
+- one text/json column for serialized snapshot payload
+
+Example model:
+
+```ruby
+class IgniterExecutionSnapshot < ApplicationRecord
+  validates :execution_id, presence: true, uniqueness: true
+end
+```
+
+Example migration:
+
+```ruby
+class CreateIgniterExecutionSnapshots < ActiveRecord::Migration[7.1]
+  def change
+    create_table :igniter_execution_snapshots do |t|
+      t.string :execution_id, null: false
+      t.jsonb :snapshot_json, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :igniter_execution_snapshots, :execution_id, unique: true
+  end
+end
+```
+
+Store configuration:
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
+  record_class: IgniterExecutionSnapshot,
+  execution_id_column: :execution_id,
+  snapshot_column: :snapshot_json
+)
+```
+
+## Redis Store
+
+`RedisStore` maintains secondary indexes so it can answer all query API calls efficiently:
+
+| Key pattern | Redis type | Purpose |
+|-------------|-----------|---------|
+| `{ns}:{execution_id}` | String | Serialized snapshot JSON |
+| `{ns}:all` | Set | All execution IDs |
+| `{ns}:graph:{name}` | Set | Execution IDs for one graph |
+| `{ns}:corr:{graph}` | Hash | `JSON(sorted_correlation)` → execution_id |
+
+The client must support these Redis commands:
+`set`, `get`, `del`, `exists?`, `sadd`, `srem`, `smembers`, `hset`, `hget`.
+
+The standard [`redis` gem](https://github.com/redis/redis-rb) satisfies this interface.
+
+```ruby
+redis = Redis.new(url: ENV.fetch("REDIS_URL"))
+
+Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
+  redis: redis,
+  namespace: "igniter:executions"   # optional, default shown
+)
+```
+
+**Query API:**
+
+```ruby
+store = Igniter::Runtime::Stores::RedisStore.new(redis: redis)
+
+# Find a pending execution by correlation
+execution_id = store.find_by_correlation(
+  graph: "OrderContract",
+  correlation: { order_id: "o-42" }
+)
+
+# List all executions for a graph
+ids = store.list_all(graph: "OrderContract")
+
+# List only pending executions (O(n) scan — acceptable for moderate volumes)
+pending_ids = store.list_pending(graph: "OrderContract")
+```
+
+## Worker Flow
+
+Store-backed contracts should declare:
+
+```ruby
+class AsyncPricingContract < Igniter::Contract
+  run_with runner: :store
+end
+```
+
+Producer side:
+
+```ruby
+contract = AsyncPricingContract.new(order_total: 100)
+deferred = contract.result.gross_total
+
+execution_id = contract.execution.events.execution_id
+token = deferred.token
+```
+
+Worker side:
+
+```ruby
+AsyncPricingContract.resume_from_store(
+  execution_id,
+  token: token,
+  value: 150
+)
+```
+
+If the resumed execution finishes successfully, the current `StoreRunner` deletes the persisted snapshot automatically.

data/docs/research/README.md

@@ -0,0 +1,131 @@
+# Research
+
+Compact research staging for ideas that may shape Igniter's architecture but are
+not accepted public API yet.
+
+Use this directory for governance protocols, long-horizon decisions, and cross-cutting
+design notes. Keep implementation snapshots and package specs in their respective
+`packages/<pkg>/docs/` directories once shipped. See **Rotation Policy** below.
+
+## Index
+
+### Protocols & Governance
+- [Horizon Protocol](./horizon-protocol.md) - working protocol, planning frame,
+  architect/agent roles, and Igniter Lang guardrails.
+- [Vision Handoff Protocol](./vision-handoff-protocol.md) - compact briefing
+  format for giving agents a large horizon with a narrow executable slice.
+- [Project Status Horizon Report](./project-status-horizon-report.md) -
+  whole-project status, verification, strategic insights, and horizon ideas.
+
+### Persistence Design
+- [Contract Persistence Landing Zone](./contract-persistence-landing-zone.md) -
+  placement decision for app-local proof, staged extraction, and future package
+  naming.
+- [Contract Persistence Organic Model](./contract-persistence-organic-model.md) -
+  horizon model for Store/History as future graph-native concepts.
+- [Igniter Lang Convergence Report](./igniter-lang-convergence-report.md) -
+  public synthesis of the private Igniter-Lang research against current Ledger,
+  Ledger Client, and Durable Model direction.
+
+### Wizard Type Spec
+- [Wizard Type Spec Research Request](./wizard-type-spec-research-request.md) -
+  handoff request for spec lineage, materialization, export, and migration
+  analysis.
+- [Wizard Type Spec Architecture](./wizard-type-spec-architecture.md) -
+  research response defining the canonical spec model, export rules, and
+  materializer boundary.
+
+## Moved to Playgrounds
+
+Planning/roadmap docs for work that is now fully shipped. Kept for historical
+reference in `playgrounds/docs/research/`.
+
+| Document | Playgrounds Location |
+|----------|---------------------|
+| Contract Persistence Development Track | [playgrounds/docs/research/](../../playgrounds/docs/research/contract-persistence-development-track.md) |
+| Contract Persistence Roadmap | [playgrounds/docs/research/](../../playgrounds/docs/research/contract-persistence-roadmap.md) |
+
+## Rotated to Package Docs
+
+Implementation snapshots that shipped are kept in their package `docs/` directories:
+
+| Document | New Location |
+|----------|-------------|
+| Igniter Ledger Open Protocol | [packages/igniter-ledger/docs/open-protocol.md](../../packages/igniter-ledger/docs/open-protocol.md) |
+| Contract-Native Store POC spec | [packages/igniter-ledger/docs/poc-specification.md](../../packages/igniter-ledger/docs/poc-specification.md) |
+| Contract-Native Store Server Model | [packages/igniter-ledger/docs/server-model.md](../../packages/igniter-ledger/docs/server-model.md) |
+| Contract Persistence Relations | [packages/igniter-ledger/docs/relations-specification.md](../../packages/igniter-ledger/docs/relations-specification.md) |
+| Companion / Store Convergence | [packages/igniter-ledger/docs/companion-convergence.md](../../packages/igniter-ledger/docs/companion-convergence.md) |
+| Igniter Ledger Progress Summary | [packages/igniter-ledger/docs/progress.md](../../packages/igniter-ledger/docs/progress.md) |
+| Contract-Native Store Research (iterations) | [packages/igniter-ledger/docs/research/store-iterations.md](../../packages/igniter-ledger/docs/research/store-iterations.md) |
+| Contract-Native Store Sync Hub (iterations) | [packages/igniter-ledger/docs/research/sync-hub-iterations.md](../../packages/igniter-ledger/docs/research/sync-hub-iterations.md) |
+| Durable Model Current Status Summary | [packages/igniter-durable-model/docs/current-status.md](../../packages/igniter-durable-model/docs/current-status.md) |
+| Durable Model Persistence App Status | [packages/igniter-durable-model/docs/app-status.md](../../packages/igniter-durable-model/docs/app-status.md) |
+| Durable Model Persistence Manifest Glossary | [packages/igniter-durable-model/docs/manifest-glossary.md](../../packages/igniter-durable-model/docs/manifest-glossary.md) |
+| Durable Model Contract Performance Signal | [packages/igniter-durable-model/docs/performance.md](../../packages/igniter-durable-model/docs/performance.md) |
+| Inter-Agent Compact Handoff (convergence audit) | [docs/store/convergence-audit.md](../store/convergence-audit.md) |
+
+## Read First
+
+Before changing architecture or reviewing an agent proposal, read:
+
+1. [Current Runtime Snapshot](../dev/current-runtime-snapshot.md)
+2. [Package Map](../dev/package-map.md)
+3. [Module System](../dev/module-system.md)
+4. [Igniter Lang Foundation](../guide/igniter-lang-foundation.md)
+5. [Horizon Protocol](./horizon-protocol.md)
+6. [Vision Handoff Protocol](./vision-handoff-protocol.md)
+7. [Project Status Horizon Report](./project-status-horizon-report.md)
+8. [Contract Persistence Landing Zone](./contract-persistence-landing-zone.md)
+9. [Contract Persistence Organic Model](./contract-persistence-organic-model.md)
+10. [Wizard Type Spec Research Request](./wizard-type-spec-research-request.md)
+11. [Wizard Type Spec Architecture](./wizard-type-spec-architecture.md)
+
+## Current Research State
+
+Status date: 2026-05-02.
+
+- Active package family: `igniter-contracts`, `igniter-extensions`,
+  `igniter-embed`, `igniter-application`, `igniter-ai`, `igniter-agents`,
+  `igniter-hub`, `igniter-web`, `igniter-cluster`, `igniter-mcp-adapter`.
+- `Igniter::Lang` is additive and report-only: Ruby backend wrapper,
+  immutable descriptors (`History`, `BiHistory`, `OLAPPoint`, `Forecast`),
+  `VerificationReport`, and `MetadataManifest`.
+- Lang metadata is declared, not enforced. `return_type`, `deadline`, `wcet`,
+  descriptors, stores, and invariants must graduate through reports before
+  runtime checks.
+- AI and agents have first package slices: provider-neutral AI envelopes and
+  minimal single-turn agent state. Tool contracts, memory, handoff, and human
+  gates remain future package work.
+- Companion is the strongest product pressure for persistence and agents. Its
+  app-local proof now covers records, histories, projections, command mutation
+  intents, typed effect intent descriptors, relation manifests, relation health diagnostics,
+  registry/readiness/manifest, `WizardTypeSpec`, static materialization planning,
+  and a review-only materializer/approval audit vertical.
+- `igniter-ledger` has shipped Phase 1 (LedgerServer, NetworkBackend, TCP/Unix transport,
+  graceful drain, stats, PID, CLI) and Phase 2 (SubscriptionRegistry reactive push).
+- `igniter-ledger` now has an Open Protocol proposal: descriptor/fact/receipt/query
+  waist for non-Igniter clients as well as Igniter contracts.
+- `igniter-durable-model` is now the typed Record/History facade over
+  `igniter-ledger`, carrying Companion manifest pressure toward package-level
+  Store/History experiments.
+- Cluster owns distributed placement, routing, ownership, health, remediation,
+  and mesh attempts. Contracts remain local-first and host-agnostic.
+
+## Rotation Policy
+
+When a research document's subject is fully implemented and shipped:
+1. `git mv` it to `packages/<pkg>/docs/` (or `docs/store/` for cross-package convergence records)
+2. Add a row to the **Rotated to Package Docs** table above
+3. Remove it from the **Index** and **Read First** list
+4. Keep governance docs (protocols, long-horizon decisions, landing zones, roadmaps) here permanently
+
+## Compression Rule
+
+Each research document should preserve:
+
+- one claim
+- the boundary it changes
+- the evidence or source pressure
+- the smallest reversible next move
+- the reasons not to ship it yet