igniter 0.5.0 → 0.5.2

data/README.md

@@ -1,724 +1,216 @@
 # Igniter
 
-Igniter is a Ruby gem for expressing business logic as a validated dependency graph and executing that graph with:
-
-- lazy output resolution and selective cache invalidation
-- typed input validation with defaults and required fields
-- nested contract composition with isolated child executions
-- declarative routing (`branch`) and fan-out (`collection`)
-- distributed workflows: `await` events across process boundaries
-- multi-node deployments via `igniter-server` and the `remote:` DSL
-- LLM compute nodes with Ollama, Anthropic, and OpenAI providers
-- Rails integration: ActiveJob, ActionCable, webhook handlers, generators
-- runtime auditing, diagnostics reports, and reactive side effects
-- graph and runtime introspection (text, Mermaid)
-- ergonomic DSL helpers: `const`, `lookup`, `map`, `project`, `aggregate`, `guard`, `export`, `expose`, `effect`, `on_success`, `scope`, `namespace`
-- `Igniter::Application` — application scaffold with YAML config, autoloading, scheduler, and `igniter-server new` generator
-- capability-based security: declare executor resource requirements, enforce `Policy` at runtime
-- temporal contracts: reproducible historical execution via an explicit `as_of` time input
-- content-addressed computation: `pure` executors cached by input fingerprint across executions and processes
-
-## Installation
+Igniter is a pre-v1 Ruby framework for building contracts-native applications,
+companions, and agent-aware systems.
 
-```ruby
-gem "igniter"
-```
-
-## Quick Start
-
-```ruby
-require "igniter"
-
-class PriceContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country,     type: :string
-    input :vat_rate,    type: :numeric, default: 0.2
-
-    compute :effective_vat_rate, depends_on: %i[country vat_rate] do |country:, vat_rate:|
-      country == "UA" ? vat_rate : 0.0
-    end
-
-    compute :gross_total, depends_on: %i[order_total effective_vat_rate] do |order_total:, effective_vat_rate:|
-      order_total * (1 + effective_vat_rate)
-    end
-
-    output :gross_total
-  end
-end
-
-contract = PriceContract.new(order_total: 100, country: "UA")
-contract.result.gross_total   # => 120.0
-
-contract.update_inputs(order_total: 150)
-contract.result.gross_total   # => 180.0
-
-contract.diagnostics_text     # compact execution summary
-```
-
-## Features
-
-- **Contracts**: declare inputs, compute nodes, outputs, and compositions in a validated graph.
-- **Compiler**: validate dependency graphs, types, and cycles before runtime; errors are surfaced at load time.
-- **Runtime**: cache resolved nodes and invalidate only affected downstream nodes on input change.
-- **Typed inputs**: validate types, defaults, and required fields at execution boundaries.
-- **Composition**: execute nested contracts with isolated child executions.
-- **Branch**: declarative routing — select one child contract from ordered cases at runtime.
-- **Collection**: declarative fan-out — run one child contract per item in an array.
-- **Distributed workflows**: `await` external events; resume via `deliver_event`.
-- **igniter-server**: host contracts as a TCP/Rack HTTP service; call remote contracts with the `remote:` DSL.
-- **LLM integration**: compute nodes powered by Ollama, Anthropic, or OpenAI providers.
-- **Rails integration**: Railtie, ActiveJob base class, ActionCable adapter, webhook controller mixin.
-- **Auditing**: collect execution timelines and snapshots.
-- **Diagnostics**: compact text, Markdown, or structured reports for triage.
-- **Reactive**: subscribe declaratively to runtime events with `effect`, `on_success`, `on_failure`.
-- **Introspection**: render graphs as text or Mermaid; inspect runtime state.
-- **Capabilities**: executors declare what resources they need (`:network`, `:database`, …); `Policy` denies them at runtime.
-- **Temporal contracts**: inject `as_of` time input automatically; replay any historical computation with the original timestamp.
-- **Content addressing**: `pure` executors get a universal cache key — identical inputs return a cached result across executions, processes, and deployments.
-- **Incremental dataflow**: `mode: :incremental` on collection nodes — only added/changed items run, unchanged items reuse cached results, removed items are retracted. O(change) not O(total).
-
-## Quick Start Recipes
-
-Runnable examples live in [`examples/`](examples) and are smoke-tested by `spec/igniter/example_scripts_spec.rb`.
-See [`examples/README.md`](examples/README.md) for a quick index and [`docs/PATTERNS.md`](docs/PATTERNS.md) for composable patterns.
-
-### 1. Basic Pricing Contract
-
-```ruby
-class PriceContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country,     type: :string
-
-    compute :vat_rate, depends_on: [:country] do |country:|
-      country == "UA" ? 0.2 : 0.0
-    end
-
-    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
-      order_total * (1 + vat_rate)
-    end
-
-    output :gross_total
-  end
-end
-
-PriceContract.new(order_total: 100, country: "UA").result.gross_total
-# => 120.0
-```
-
-### 2. Nested Composition
-
-```ruby
-class CheckoutContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country,     type: :string
-
-    compose :pricing, contract: PriceContract, inputs: {
-      order_total: :order_total,
-      country:     :country
-    }
-
-    output :pricing
-  end
-end
-
-CheckoutContract.new(order_total: 100, country: "UA").result.pricing.gross_total
-# => 120.0
-```
-
-### 3. Diagnostics and Introspection
-
-```ruby
-contract = PriceContract.new(order_total: 100, country: "UA")
-contract.result.gross_total
-
-contract.result.states
-contract.result.explain(:gross_total)
-contract.diagnostics.to_h
-contract.diagnostics_text
-contract.diagnostics_markdown
-contract.audit_snapshot
-
-PriceContract.graph.to_text
-PriceContract.graph.to_mermaid
-```
-
-### 4. Machine-Readable Data
-
-```ruby
-contract.result.to_h       # => { gross_total: 120.0 }
-contract.result.as_json
-contract.execution.as_json
-contract.events.map(&:as_json)
-```
-
-### 5. Async Store and Resume
-
-```ruby
-class AsyncQuoteExecutor < Igniter::Executor
-  def call(order_total:)
-    defer(token: "quote-#{order_total}", payload: { kind: "pricing_quote" })
-  end
-end
-
-class AsyncPricingContract < Igniter::Contract
-  run_with runner: :store
-
-  define do
-    input :order_total, type: :numeric
-    compute :quote_total, depends_on: [:order_total], call: AsyncQuoteExecutor
-    compute :gross_total, depends_on: [:quote_total] do |quote_total:|
-      quote_total * 1.2
-    end
-    output :gross_total
-  end
-end
-
-contract     = AsyncPricingContract.new(order_total: 100)
-deferred     = contract.result.gross_total
-execution_id = contract.execution.events.execution_id
-
-resumed = AsyncPricingContract.resume_from_store(
-  execution_id, token: deferred.token, value: 150
-)
-resumed.result.gross_total  # => 180.0
-```
-
-### 6. Ergonomic DSL
-
-```ruby
-class MarketingQuoteContract < Igniter::Contract
-  define do
-    input :service,  type: :string
-    input :zip_code, type: :string
-
-    const :vendor_id, "eLocal"
-
-    scope :routing do
-      map :trade_name, from: :service do |service:|
-        %w[heating cooling ventilation].include?(service.downcase) ? "HVAC" : service
-      end
-    end
-
-    scope :pricing do
-      lookup :trade, with: :trade_name do |trade_name:|
-        { name: trade_name, base_bid: 45.0 }
-      end
-    end
-
-    namespace :validation do
-      guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
-    end
-
-    compute :quote, with: %i[vendor_id trade zip_code zip_supported] do |vendor_id:, trade:, zip_code:, zip_supported:|
-      zip_supported
-      { vendor_id: vendor_id, trade: trade[:name], zip_code: zip_code, bid: trade[:base_bid] }
-    end
-
-    expose :quote, as: :response
-  end
-
-  on_success :response do |value:, **|
-    puts "Persist #{value.inspect}"
-  end
-end
-```
-
-Matcher-style guard shortcuts:
-
-```ruby
-guard :usa_only,          with: :country_code, eq: "USA",            message: "Unsupported country"
-guard :supported_country, with: :country_code, in: %w[USA CAN],      message: "Unsupported country"
-guard :valid_zip,         with: :zip_code,     matches: /\A\d{5}\z/, message: "Invalid zip"
-```
-
-### 7. Declarative Branching
-
-```ruby
-class DeliveryContract < Igniter::Contract
-  define do
-    input :country
-    input :order_total
-
-    branch :delivery_strategy, with: :country, inputs: {
-      country:     :country,
-      order_total: :order_total
-    } do
-      on "US", contract: USDeliveryContract
-      on "UA", contract: LocalDeliveryContract
-      default   contract: DefaultDeliveryContract
-    end
-
-    export :price, :eta, from: :delivery_strategy
-  end
-end
-```
-
-### 8. Declarative Collections
-
-```ruby
-class TechnicianBatchContract < Igniter::Contract
-  define do
-    input :technician_inputs, type: :array
-
-    collection :technicians,
-               with: :technician_inputs,
-               each: TechnicianContract,
-               key:  :technician_id,
-               mode: :collect
-
-    output :technicians
-  end
-end
-```
-
-In `mode: :collect`, an execution succeeds overall while items may individually fail:
-
-- `result.summary`       — collection-level status (`:partial_failure` when any item failed)
-- `result.items_summary` — compact per-item status hash
-- `result.failed_items`  — failed-item error details
-- `result.successes`     — hash of succeeded items only
-
-See [`examples/collection_partial_failure.rb`](examples/collection_partial_failure.rb).
-
-### 9. Distributed Contracts
-
-Use `await` to suspend execution until an external event arrives. `correlate_by` identifies
-which execution should receive the event, so events can be delivered from any process:
+At the center is a small contract graph kernel: validated inputs, computations,
+effects, outputs, diagnostics, and execution plans. Around that kernel Igniter is
+growing into a platform for:
 
-```ruby
-class LeadWorkflow < Igniter::Contract
-  correlate_by :request_id
-
-  define do
-    input :request_id
-
-    await :crm_data,     event: :crm_received
-    await :billing_data, event: :billing_received
-
-    aggregate :report, with: %i[crm_data billing_data] do |crm_data:, billing_data:|
-      { crm: crm_data, billing: billing_data }
-    end
-
-    output :report
-  end
-
-  on_success :report do |value:, **|
-    puts "Report ready: #{value.inspect}"
-  end
-end
-
-store = Igniter::Runtime::Stores::MemoryStore.new
-
-# Launch — suspends waiting for both events
-execution = LeadWorkflow.start({ request_id: "r1" }, store: store)
-execution.pending?  # => true
+- embedding contract behavior into existing applications
+- observing and shadowing legacy services without changing production responses
+- storing immutable facts, histories, receipts, and replayable decisions
+- building companion apps beside existing systems of record
+- exposing operator surfaces, streams, MCP tools, and eventually cluster peers
+- giving AI agents evidence, receipts, and approval boundaries before authority
 
-# Deliver events from any process or webhook handler
-LeadWorkflow.deliver_event(:crm_received,
-  correlation: { request_id: "r1" },
-  payload: { company: "Acme Corp", tier: "enterprise" },
-  store: store)
+The short version:
 
-LeadWorkflow.deliver_event(:billing_received,
-  correlation: { request_id: "r1" },
-  payload: { mrr: 500 },
-  store: store)
-# => prints "Report ready: { crm: ..., billing: ... }"
+```text
+Contracts
+  -> Embed migration bridge
+  -> Store / Ledger facts and receipts
+  -> Ledger Client protocol boundary
+  -> Companion typed Record/History facade
+  -> Application + Web operator surfaces
+  -> Agents / AI / Cluster / Hub runtime lanes
 ```
 
-See [`examples/distributed_server.rb`](examples/distributed_server.rb) and [`docs/DISTRIBUTED_CONTRACTS_V1.md`](docs/DISTRIBUTED_CONTRACTS_V1.md).
+## Status
 
-### 10. igniter-server
+Igniter is pre-v1. There is no backward-compatibility promise and no stable
+public API guarantee yet. That is intentional: weak shapes should still be
+replaced quickly while the better architecture is visible.
 
-Host contracts as an HTTP service and call them from another graph with the `remote:` DSL:
+The project is now large enough to be treated as a framework/platform, but its
+surface is still being actively shaped by real application pressure. Current
+proofs are strongest in:
 
-```ruby
-# --- Service node on port 4568 ---
-require "igniter/server"
-
-class ScoringContract < Igniter::Contract
-  define do
-    input :value
-    compute :score, depends_on: :value, call: ->(value:) { value * 1.5 }
-    output :score
-  end
-end
+- contract graph authoring and execution
+- host-local embedding and contractable shadowing
+- Store/Ledger facts, WAL, replay, changefeeds, compaction activity, and
+  read-only protocol surfaces
+- application/web package structure and operator-oriented surfaces
+- early agents, AI, hub, and cluster package lanes
 
-Igniter::Server.configure { |c| c.port = 4568; c.register "ScoringContract", ScoringContract }
-Igniter::Server.start
+Use package READMEs, runnable examples, and track docs to evaluate current
+capability. Production-grade guarantees and compatibility policy belong after
+v1.
 
-# --- Orchestrator on port 4567 ---
-require "igniter/server"
+## Platform Lanes
 
-class PipelineContract < Igniter::Contract
-  define do
-    input :data
-    remote :scored,
-           contract: "ScoringContract",
-           node:     "http://localhost:4568",
-           inputs:   { value: :data }
-    output :scored
-  end
-end
+### `igniter-contracts`
 
-Igniter::Server.configure { |c| c.port = 4567; c.register "PipelineContract", PipelineContract }
-Igniter::Server.start
-```
+The kernel: DSL authoring, graph compilation, runtime execution, diagnostics,
+effects, and the core `Contractable` service protocol used inside contracts.
 
-**CLI:**
+### `igniter-embed`
 
-```bash
-# Generate a new application scaffold
-igniter-server new my_app
+The migration bridge for existing applications. It registers host-local
+contracts and wraps opaque services with `contractable` observation/shadowing:
 
-# Start a server directly
-igniter-server start --port 4568 --require ./contracts.rb
+```text
+legacy primary result
+  -> returned unchanged
+  -> optional candidate/shadow execution
+  -> normalized comparison
+  -> observation / divergence receipts
 ```
 
-**Rack / Puma (`config.ru`):**
-
-```ruby
-require "igniter/server"
-require_relative "contracts"
-Igniter::Server.configure { |c| c.register "ScoringContract", ScoringContract }
-run Igniter::Server.rack_app
-```
-
-**REST API:**
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/v1/contracts/:name/execute` | Execute a contract synchronously |
-| `POST` | `/v1/contracts/:name/events` | Deliver an event to a distributed contract |
-| `GET`  | `/v1/executions/:id` | Poll execution status |
-| `GET`  | `/v1/health` | Health check with registered contracts list |
-| `GET`  | `/v1/contracts` | List contracts with inputs and outputs |
+This is the safest first path for Rails and other host apps.
 
-See [`docs/SERVER_V1.md`](docs/SERVER_V1.md) for the full API reference, deployment patterns, and security notes.
+### `igniter-ledger`
 
-### 11. LLM Integration
+The Ledger substrate: immutable facts, `Store[T]` and `History[T]` experiments,
+causation, current/time-travel reads, access paths, WAL durability, changefeed,
+Ledger Open Protocol, LedgerServer, compaction lifecycle, and intelligent-ledger
+boundary proofs.
 
-Use language models as first-class compute nodes. Supported providers: Ollama (local, zero API cost),
-Anthropic (Claude), OpenAI (and compatible APIs: Groq, Mistral, Azure OpenAI):
+It is still a POC package, but it is no longer just "persistence research"; it
+is the event memory and receipt substrate for companion systems.
 
-```ruby
-require "igniter/integrations/llm"
+### `igniter-ledger-client`
 
-Igniter::LLM.configure do |c|
-  c.default_provider = :anthropic
-  c.anthropic.api_key = ENV["ANTHROPIC_API_KEY"]
-end
+The protocol-first client boundary for Ledger users. It owns request/response
+envelopes, transports, errors, and future pooling/retry/backpressure policy
+without embedding the storage engine.
 
-class ClassifyExecutor < Igniter::LLM::Executor
-  provider :anthropic
-  model    "claude-haiku-4-5-20251001"
-  system_prompt "Classify feedback into: bug_report, feature_request, question."
+### `igniter-companion`
 
-  def call(feedback:)
-    complete("Classify: #{feedback}")
-  end
-end
+Typed application-facing `Record` / `History` facade over `igniter-ledger`.
+It turns raw facts into ergonomic app objects while applying pressure back onto
+Store capabilities such as scopes, partitions, receipts, manifests, and typed
+storage semantics.
 
-class DraftResponseExecutor < Igniter::LLM::Executor
-  provider :anthropic
-  model    "claude-haiku-4-5-20251001"
-  system_prompt "You are a customer success agent. Write one professional response sentence."
+### `igniter-application`
 
-  def call(feedback:, category:)
-    complete("Feedback: #{feedback}\nCategory: #{category}\nDraft a response.")
-  end
-end
+Contracts-native application runtime: app manifests, providers, services,
+credentials, agents, sessions, snapshots, boot/shutdown plans, and embedded host
+activation paths.
 
-class FeedbackTriageContract < Igniter::Contract
-  define do
-    input :feedback
+### `igniter-web`
 
-    compute :category, depends_on: :feedback,             with: ClassifyExecutor
-    compute :response, depends_on: %i[feedback category], with: DraftResponseExecutor
+Operator and interaction surfaces: receipt/report views, event streams,
+dashboards, human approval gates, investigation workspaces, and app-local web
+mounts. It is not trying to replace a Rails admin UI.
 
-    output :category
-    output :response
-  end
-end
-```
+### `igniter-agents` and `igniter-ai`
 
-Multi-step reasoning with conversation history:
+Agent and AI runtime lanes: runs, turns, traces, serializable state, provider
+registration, and the promotion ladder from observe-only to human-approved
+authority.
 
-```ruby
-class MultiStepExecutor < Igniter::LLM::Executor
-  def call(text:, prior_analysis:)
-    ctx = Context.empty(system: self.class.system_prompt)
-      .append_user("Initial: #{text}")
-      .append_assistant(prior_analysis)
-    chat(context: ctx)
-  end
-end
-```
+### `igniter-cluster` and `igniter-hub`
 
-See [`examples/llm/research_agent.rb`](examples/llm/research_agent.rb), [`examples/llm/tool_use.rb`](examples/llm/tool_use.rb), and [`docs/LLM_V1.md`](docs/LLM_V1.md).
+Distributed and sync lanes: capability-aware peers, ownership, leases, health,
+failover, admission/trust, and hub-style synchronization. These should emerge
+from real partitioned domains rather than "distributed everything".
 
-### 12. Igniter::Application
+### `igniter-mcp-adapter`
 
-Package contracts, executors, scheduler, and server config into a single coherent entry point:
+Transport-facing MCP surface for exposing tools, protocol reads, and operator
+introspection.
 
-```bash
-# Scaffold a new application
-igniter-server new my_app
-cd my_app && bundle install && bin/start
-```
+## Small Contract Example
 
 ```ruby
-require "igniter/application"
-
-class MyApp < Igniter::Application
-  config_file "application.yml"       # optional YAML base config
-
-  configure do |c|
-    c.port  = ENV.fetch("PORT", 4567).to_i
-    c.store = Igniter::Runtime::Stores::MemoryStore.new
-  end
-
-  executors_path "executors/"         # eager-require all executors
-  contracts_path "contracts/"         # eager-require all contracts
+require "igniter"
 
-  register "OrderContract", OrderContract
+environment = Igniter.with
 
-  schedule :cleanup, every: "1h" do
-    puts "[cleanup] #{Time.now.strftime("%H:%M")}"
-  end
+result = environment.run(inputs: { order_total: 100, country: "UA" }) do
+  input :order_total
+  input :country
 
-  schedule :report, every: "1d", at: "09:00" do
-    DailyReportContract.new.resolve_all(date: Date.today)
+  compute :vat_rate, depends_on: [:country] do |country:|
+    country == "UA" ? 0.2 : 0.0
   end
-end
-
-MyApp.start       # blocking built-in HTTP server
-# or
-MyApp.rack_app    # Rack app for Puma / Unicorn
-```
-
-**`application.yml`** — base config loaded before the `configure` block (block always wins):
-
-```yaml
-server:
-  port: 4567
-  host: "0.0.0.0"
-  log_format: json    # text (default) or json
-  drain_timeout: 30
-```
-
-**Scheduler interval formats:** `30` (seconds), `"30s"`, `"5m"`, `"2h"`, `"1d"`, `{ hours: 1, minutes: 30 }`
-
-See [`docs/APPLICATION_V1.md`](docs/APPLICATION_V1.md) for the full reference and companion app example.
-
-### 13. Capability-Based Security
-
-Declare what external resources an executor needs, then deny specific capabilities at the
-policy level — without touching the executors themselves:
-
-```ruby
-require "igniter/capabilities"
-
-class DbLookup < Igniter::Executor
-  capabilities :database
 
-  def call(id:)
-    DB.find(id)
+  compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+    order_total * (1 + vat_rate)
   end
-end
-
-class PureCalc < Igniter::Executor
-  pure  # shorthand for capabilities(:pure)
-
-  def call(x:, y:) = x + y
-end
-
-# Inspect the graph's surface area before deploying
-MyContract.compiled_graph.required_capabilities
-# => { fetch: [:database], total: [:pure] }
-
-# Enforce policy at boot time
-Igniter::Capabilities.policy = Igniter::Capabilities::Policy.new(denied: [:database])
-
-MyContract.new(id: 1).resolve_all
-# => CapabilityViolationError: Node 'fetch' uses denied capabilities: database
-```
-
-See [`docs/CAPABILITIES_V1.md`](docs/CAPABILITIES_V1.md).
-
-### 14. Temporal Contracts
-
-Make time an explicit input so every execution is fully reproducible:
 
-```ruby
-require "igniter/temporal"
-
-class TaxRateContract < Igniter::Contract
-  include Igniter::Temporal
-
-  define do
-    input :country
-    # `as_of` is injected automatically (default: Time.now)
-
-    temporal_compute :rate, depends_on: :country do |country:, as_of:|
-      HISTORICAL_RATES.dig(country, as_of.year) || 0.0
-    end
-
-    output :rate
-  end
+  output :gross_total
 end
 
-# Current rate
-TaxRateContract.new(country: "UA").result.rate
-# => 0.22
-
-# Reproduce the exact 2024 result
-TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.rate
-# => 0.20
+result.output(:gross_total)
+# => 120.0
 ```
 
-See [`docs/TEMPORAL_V1.md`](docs/TEMPORAL_V1.md).
-
-### 15. Content-Addressed Computation
-
-`pure` executors are cached by a fingerprint of their logic + inputs. Identical computation
-is never repeated — within an execution, across executions, or across processes:
-
-```ruby
-require "igniter/extensions/content_addressing"
-
-class TaxCalculator < Igniter::Executor
-  pure
-  fingerprint "tax_calc_v1"   # bump to invalidate the cache when logic changes
-
-  def call(country:, amount:)
-    TAX_RATES[country] * amount
-  end
-end
-
-# First execution — computes and caches
-InvoiceContract.new(country: "UA", amount: 1000).result.tax  # computed
+## Companion Direction
 
-# Second execution — served from cache; TaxCalculator is never called
-InvoiceContract.new(country: "UA", amount: 1000).result.tax  # cache hit
+Igniter is being shaped by real application pressure such as Spark CRM:
 
-# Distributed cache (Redis) — shared across all nodes
-Igniter::ContentAddressing.cache = RedisContentCache.new(Redis.new)
+```text
+Existing app remains the system of record
+  -> Igniter Embed observes/shadows risky services
+  -> Igniter Ledger records facts and receipts
+  -> Ledger boundaries close semantic decisions
+  -> Web/Agents explain, review, and recommend
 ```
 
-See [`docs/CONTENT_ADDRESSING_V1.md`](docs/CONTENT_ADDRESSING_V1.md).
+This is the current strategic pattern: do not rewrite a production app into
+Igniter. Build an Igniter companion beside it, move event-heavy and
+explanation-heavy responsibilities behind explicit facts, receipts, boundaries,
+and approval gates.
 
-### 16. Incremental Dataflow — O(change) Collection Processing
+## What Is Not Promised Yet
 
-`mode: :incremental` on a collection node makes the runtime diff the input array on
-every `resolve_all`. Only added/changed items have their child contract re-run;
-unchanged items reuse the cached result; removed items are retracted automatically.
+- Stable v1 API compatibility.
+- A production database adapter abstraction.
+- Remote mutating Store operations for compaction/prune/purge.
+- Cluster consensus or deployment guarantees.
+- AI authority without receipts, policies, replay, and human approval paths.
 
-```ruby
-require "igniter/extensions/dataflow"
+## Repository Map
 
-class SensorPipeline < Igniter::Contract
-  define do
-    input :readings, type: :array
+- [docs/](./docs/README.md) — documentation portal
+- [docs/guide/](./docs/guide/README.md) — user-facing guide
+- [docs/concepts/](./docs/concepts/README.md) — mental models and vocabulary
+- [docs/dev/](./docs/dev/README.md) — architecture and package boundaries
+- [examples/](./examples/README.md) — runnable examples
+- [packages/](./packages/README.md) — package list and local package docs
+- [playgrounds/](./playgrounds/README.md) — private/local-first experiments and history
 
-    collection :processed,
-               with: :readings,
-               each: SensorAnalysis,
-               key:  :sensor_id,
-               mode: :incremental,
-               window: { last: 1000 }   # bounded memory
+## Package Docs
 
-    output :processed
-  end
-end
+- [igniter-contracts](./packages/igniter-contracts/README.md)
+- [igniter-extensions](./packages/igniter-extensions/README.md)
+- [igniter-embed](./packages/igniter-embed/README.md)
+- [igniter-ledger](./packages/igniter-ledger/README.md)
+- [igniter-ledger-client](./packages/igniter-ledger-client/README.md)
+- [igniter-companion](./packages/igniter-companion/README.md)
+- [igniter-application](./packages/igniter-application/README.md)
+- [igniter-web](./packages/igniter-web/README.md)
+- [igniter-agents](./packages/igniter-agents/README.md)
+- [igniter-ai](./packages/igniter-ai/README.md)
+- [igniter-cluster](./packages/igniter-cluster/README.md)
+- [igniter-hub](./packages/igniter-hub/README.md)
+- [igniter-mcp-adapter](./packages/igniter-mcp-adapter/README.md)
 
-pipeline = SensorPipeline.new(readings: initial_batch)
-pipeline.resolve_all  # all N items run once
+## Working Principle
 
-# Push only the delta — no full-array replacement needed
-pipeline.feed_diff(:readings,
-  add:    [{ sensor_id: "new-1", value: 10 }],
-  update: [{ sensor_id: "tmp-2", value: 90 }],
-  remove: ["hum-1"]
-)
-pipeline.resolve_all  # only 2 child contracts run (new-1 + tmp-2)
-
-diff = pipeline.collection_diff(:processed)
-diff.processed_count  # => 2
-diff.unchanged.size   # => N - 2
-```
+Igniter evolves through a tight loop:
 
-See [`docs/DATAFLOW_V1.md`](docs/DATAFLOW_V1.md).
-
-## Examples
-
-| Example | Run | Shows |
-|---------|-----|-------|
-| `basic_pricing.rb` | `ruby examples/basic_pricing.rb` | Basic contract, lazy resolution, input updates |
-| `composition.rb` | `ruby examples/composition.rb` | Nested contracts and composed results |
-| `diagnostics.rb` | `ruby examples/diagnostics.rb` | Diagnostics text and machine-readable output |
-| `async_store.rb` | `ruby examples/async_store.rb` | Pending execution, file-backed store, worker-style resume |
-| `marketing_ergonomics.rb` | `ruby examples/marketing_ergonomics.rb` | `const`, `lookup`, `map`, `guard`, `scope`, `namespace`, `expose`, `on_success`, `explain_plan` |
-| `collection.rb` | `ruby examples/collection.rb` | Fan-out, stable item keys, `CollectionResult` |
-| `collection_partial_failure.rb` | `ruby examples/collection_partial_failure.rb` | `:collect` mode, partial failure summary, collection diagnostics |
-| `ringcentral_routing.rb` | `ruby examples/ringcentral_routing.rb` | `branch`, nested `collection`, `project`, `aggregate`, diagnostics |
-| `order_pipeline.rb` | `ruby examples/order_pipeline.rb` | `guard` + `collection` + `branch` + `export` in one flow |
-| `distributed_server.rb` | `ruby examples/distributed_server.rb` | `await`, `correlate_by`, `start`, `deliver_event`, `on_success` |
-| `server/node1.rb` + `node2.rb` | run both, then curl | Two-node igniter-server with `remote:` DSL |
-| `llm/research_agent.rb` | `ruby examples/llm/research_agent.rb` | Multi-step LLM pipeline with Ollama |
-| `llm/tool_use.rb` | `ruby examples/llm/tool_use.rb` | LLM tool declarations, chained LLM nodes, `Context` |
-| `companion/demo.rb` | `ruby examples/companion/demo.rb` | End-to-end voice AI pipeline using `Igniter::Application` |
-| `dataflow.rb` | `ruby examples/dataflow.rb` | Incremental sensor pipeline: `mode: :incremental`, `feed_diff`, sliding window |
-
-## Design Docs
-
-- [Architecture v2](docs/ARCHITECTURE_V2.md)
-- [Execution Model v2](docs/EXECUTION_MODEL_V2.md)
-- [API Draft v2](docs/API_V2.md)
-- [Patterns](docs/PATTERNS.md)
-- [Branches v1](docs/BRANCHES_V1.md)
-- [Collections v1](docs/COLLECTIONS_V1.md)
-- [Distributed Contracts v1](docs/DISTRIBUTED_CONTRACTS_V1.md)
-- [Store Adapters](docs/STORE_ADAPTERS.md)
-- [igniter-server v1](docs/SERVER_V1.md)
-- [LLM Integration v1](docs/LLM_V1.md)
-- [Application scaffold v1](docs/APPLICATION_V1.md)
-- [Capabilities v1](docs/CAPABILITIES_V1.md)
-- [Temporal Contracts v1](docs/TEMPORAL_V1.md)
-- [Content Addressing v1](docs/CONTENT_ADDRESSING_V1.md)
-- [Incremental Dataflow v1](docs/DATAFLOW_V1.md)
-- [Concepts and Principles](docs/IGNITER_CONCEPTS.md)
-
-## Development
-
-```bash
-rake          # specs + RuboCop
-rake spec     # tests only
-rake rubocop  # lint only
-rake build    # build gem
+```text
+real app pressure
+  -> proof-local experiment
+  -> receipt-backed package primitive
+  -> protocol/read surface
+  -> docs compression
+  -> next pressure
 ```
 
-Current feature baseline:
-
-- synchronous runtime + parallel thread-pool runner
-- pending / deferred node states with snapshot / restore
-- store-backed resume flow (MemoryStore, FileStore)
-- compile-time graph validation, typed inputs, cycle detection
-- composition, branch, collection, guard, scope / namespace
-- distributed workflows: `await`, `correlate_by`, `start`, `deliver_event`
-- igniter-server: TCP server, Rack adapter, CLI, `remote:` DSL
-- LLM compute nodes: Ollama, Anthropic, OpenAI providers
-- Rails integration: Railtie, ActiveJob, ActionCable, webhook controller mixin
-- `Igniter::Application`: YAML config, autoloading, scheduler, generator (`igniter-server new`)
-- auditing, diagnostics, reactive subscriptions, graph introspection
-- capability-based security: `capabilities`, `pure`, `Policy`, `CapabilityViolationError`
-- temporal contracts: `include Igniter::Temporal`, `temporal_compute`, `as_of` input, historical reproduction
-- content-addressed computation: `pure`, `fingerprint`, universal `ContentKey`, pluggable `ContentCache`
-- incremental dataflow: `mode: :incremental`, `window:`, `feed_diff`, `collection_diff`, `DiffState`, `IncrementalCollectionResult`
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+That loop is why some docs live beside packages, some live in public guide/dev
+sections, and older long-form research is compressed into `playgrounds/docs/`
+instead of being used as public onboarding.