igniter 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4caaf4e7e3d207488681fb5d8ed3d575fbd4f419fd67491479969246861445f1
-  data.tar.gz: 8a193a9c50628a8f14177bb8810d0ecf8c20cd767ae719a497c6564fa3463b1f
+  metadata.gz: 445ceabe04a2d6a724c192fa36a91050b88cb44fb382885e78ad12e7bba61f07
+  data.tar.gz: afda09f219308b2333baa4484f9ba30bee896be8ab2378b29e3efb9fcc644e35
 SHA512:
-  metadata.gz: 00dc8b99d83bf9fbbb6c800076e5c1228925081aa57ab44a9bed25c1725d4cf5518701ffb422bf000a17a68aa0a6436815eacf550c34c7cedc24b2ea43a17517
-  data.tar.gz: 33d35169526bcb27dfa55b8e4cc3c4e5f6ad0a368163c626bab55a5daca6152ab93da20dc29c9196e2db0a7f2dafdf6a50baa33758d4e67cd67df97585fd1b8c
+  metadata.gz: 83c7bf576f2ad9dd60e6812ae4080b02223ab87cb5870904f77ca7d760c44168d37b958de3567259df1d8f83ed57bb022855065ee8baa8df85e68443936acd49
+  data.tar.gz: a20d21cc087fd8952bd7f64f81f04a76e267f1909bf8c61eb1ac3f7b46b0f142b4a7e453353b91bf1a5e2ba3e08811d27dddd8a28f987a6680ae8d506d0ab2ce

data/README.md

@@ -1,262 +1,216 @@
 # Igniter
 
-Igniter is a Ruby framework for building business logic as validated dependency graphs.
-
-At the center is a small, strict idea:
-
-- describe dependencies explicitly
-- validate the graph before runtime
-- resolve only what is needed
-- keep the runtime observable
-
-From there, Igniter scales by layers instead of by reinvention:
-
-- **Core** for contracts, compilation, execution, diagnostics
-- **App** for a single-node runtime/profile
-- **Cluster** for capability-based distributed execution
-- **SDK** for optional packs such as AI, channels, tools, and data
-
-This README is an entrypoint, not the full reference. The reference now lives in
-[`docs/`](./docs/README.md), organized into [`guide`](./docs/guide/README.md),
-[`concepts`](./docs/concepts/README.md), [`current`](./docs/current/README.md),
-and [`dev`](./docs/dev/README.md).
-
-## Why Igniter
-
-Igniter is useful when your domain logic wants more structure than “service objects everywhere” but less ceremony than a full workflow engine.
-
-You define a graph of inputs, computations, branches, collections, compositions, and outputs. Igniter compiles that graph, validates it, and gives you a runtime that is lazy, inspectable, and capable of growing from embedded usage to app hosting and then to a cluster.
-
-## A Tiny Example
-
-```ruby
-require "igniter"
-
-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
-
-contract = PriceContract.new(order_total: 100, country: "UA")
-contract.result.gross_total
-# => 120.0
+Igniter is a pre-v1 Ruby framework for building contracts-native applications,
+companions, and agent-aware systems.
+
+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:
+
+- 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
+
+The short version:
+
+```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
 ```
 
-## One Real Example
-
-Imagine a post-call analysis pipeline for a call center.
-
-The business task is simple to describe:
-
-- take a recording
-- transcribe it
-- extract structured facts
-- score the call
-- prepare CRM updates and supervisor follow-up
-
-In Igniter, that stays one explicit graph:
-
-```ruby
-require "igniter/cluster"
-
-class PostCallAnalysisContract < Igniter::Contract
-  define do
-    input :call_id, type: :string
-    input :audio_url, type: :string
-    input :recorded_at, type: :string
-
-    remote :transcript,
-           contract: "TranscribeCall",
-           query: { all_of: [:audio_transcription], tags: [:gpu] },
-           inputs: { audio_url: :audio_url }
-
-    remote :analysis,
-           contract: "AnalyzeCall",
-           query: { all_of: [:llm_inference] },
-           inputs: {
-             call_id: :call_id,
-             transcript: :transcript,
-             recorded_at: :recorded_at
-           }
-
-    compute :crm_patch, depends_on: [:analysis] do |analysis:|
-      {
-        disposition: analysis[:disposition],
-        sentiment: analysis[:sentiment],
-        next_action: analysis[:next_action],
-        escalation_required: analysis[:escalation_required]
-      }
-    end
-
-    output :analysis
-    output :crm_patch
-  end
-end
-```
+## Status
 
-Why this is interesting:
+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.
 
-- the domain flow is still one contract, not a pile of queue handlers
-- transcription and analysis can land on different nodes with different capabilities
-- the cluster routes by capabilities, not by hard-coded machine roles
-- if one matching node disappears, the network can select another suitable peer without changing the contract
+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:
 
-That is the general Igniter idea: keep the business graph stable, let the runtime grow from local execution to a capability-driven cluster.
+- 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
 
-## The Levels
+Use package READMEs, runnable examples, and track docs to evaluate current
+capability. Production-grade guarantees and compatibility policy belong after
+v1.
 
-### 1. Core
+## Platform Lanes
 
-Start here if you want the kernel:
+### `igniter-contracts`
 
-- contract DSL
-- compiler and graph validation
-- lazy runtime and invalidation
-- diagnostics, events, introspection
+The kernel: DSL authoring, graph compilation, runtime execution, diagnostics,
+effects, and the core `Contractable` service protocol used inside contracts.
 
-Read:
+### `igniter-embed`
 
-- [`docs/guide/core.md`](./docs/guide/core.md)
+The migration bridge for existing applications. It registers host-local
+contracts and wraps opaque services with `contractable` observation/shadowing:
 
-### 2. App
+```text
+legacy primary result
+  -> returned unchanged
+  -> optional candidate/shadow execution
+  -> normalized comparison
+  -> observation / divergence receipts
+```
 
-Use this when you want Igniter to be the runtime shape of an application:
+This is the safest first path for Rails and other host apps.
 
-- app profile
-- host/loader/scheduler seams
-- stack-style project layout
-- app diagnostics and evolution/governance layers
+### `igniter-ledger`
 
-Read:
+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.
 
-- [`docs/guide/app.md`](./docs/guide/app.md)
+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.
 
-### 3. Cluster
+### `igniter-ledger-client`
 
-Use this when execution stops being single-node:
+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.
 
-- mesh and gossip
-- capability-based routing
-- replication and distributed coordination
-- resilience and decentralized runtime concerns
+### `igniter-companion`
 
-Read:
+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.
 
-- [`docs/guide/cluster.md`](./docs/guide/cluster.md)
+### `igniter-application`
 
-### 4. SDK
+Contracts-native application runtime: app manifests, providers, services,
+credentials, agents, sessions, snapshots, boot/shutdown plans, and embedded host
+activation paths.
 
-Use SDK packs when the kernel needs optional capabilities:
+### `igniter-web`
 
-- AI
-- channels
-- tools
-- skills
-- data and app-facing capability packs
+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.
 
-Read:
+### `igniter-agents` and `igniter-ai`
 
-- [`docs/guide/sdk.md`](./docs/guide/sdk.md)
+Agent and AI runtime lanes: runs, turns, traces, serializable state, provider
+registration, and the promotion ladder from observe-only to human-approved
+authority.
 
-## Suggested Reading Paths
+### `igniter-cluster` and `igniter-hub`
 
-If you are new to Igniter:
+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".
 
-1. Read [`docs/guide/`](./docs/guide/README.md)
-2. Read [`docs/concepts/`](./docs/concepts/README.md)
-3. Run one or two scripts from [`examples/README.md`](./examples/README.md)
+### `igniter-mcp-adapter`
 
-If you want to work on Igniter itself:
+Transport-facing MCP surface for exposing tools, protocol reads, and operator
+introspection.
 
-1. Read [`docs/dev/`](./docs/dev/README.md)
-2. Read [`docs/dev/architecture-index.md`](./docs/dev/architecture-index.md)
-3. Then move to the relevant package or layer index
+## Small Contract Example
 
-If you want the standard app shape:
+```ruby
+require "igniter"
 
-1. Read [`docs/guide/`](./docs/guide/README.md)
-2. Read [`docs/guide/app.md`](./docs/guide/app.md)
-3. Read [`docs/guide/cli.md`](./docs/guide/cli.md)
-4. Explore [`examples/companion/README.md`](./examples/companion/README.md)
+environment = Igniter.with
 
-If you want distributed ideas:
+result = environment.run(inputs: { order_total: 100, country: "UA" }) do
+  input :order_total
+  input :country
 
-1. Read [`docs/guide/`](./docs/guide/README.md)
-2. Read [`docs/guide/cluster.md`](./docs/guide/cluster.md)
-3. Run cluster-oriented scripts from [`examples/README.md`](./examples/README.md)
+  compute :vat_rate, depends_on: [:country] do |country:|
+    country == "UA" ? 0.2 : 0.0
+  end
 
-If you are iterating on ideas locally:
+  compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+    order_total * (1 + vat_rate)
+  end
 
-- keep public learning material in [`examples/`](./examples/README.md)
-- keep local-first experiments in [`playgrounds/`](./playgrounds/README.md)
+  output :gross_total
+end
 
-## Documentation Layout
+result.output(:gross_total)
+# => 120.0
+```
 
-- [`docs/guide/`](./docs/guide/README.md) — user-facing docs: getting started, API, how-tos, configuration
-- [`docs/concepts/`](./docs/concepts/README.md) — durable mental models and patterns
-- [`docs/current/`](./docs/current/README.md) — current-state notes and near-term direction
-- [`docs/dev/`](./docs/dev/README.md) — internal docs: architecture, package boundaries, migration plans, backlog
-- [`packages/*/README.md`](./packages/igniter-core/README.md) — package-local quick reference owned by each gem
-- [`docs/`](./docs/README.md) — top-level docs portal that routes between sections
+## Companion Direction
 
-If you want to scaffold a new stack quickly:
+Igniter is being shaped by real application pressure such as Spark CRM:
 
-```bash
-bin/igniter-stack new my_app
-bin/igniter-stack new my_hub --profile dashboard
-bin/igniter-stack new mesh_lab --profile cluster
-bin/igniter-stack new playgrounds/home-lab --profile playground
+```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
 ```
 
-## Installation
-
-```ruby
-gem "igniter"
+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.
+
+## What Is Not Promised Yet
+
+- 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.
+
+## Repository Map
+
+- [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
+
+## Package Docs
+
+- [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)
+
+## Working Principle
+
+Igniter evolves through a tight loop:
+
+```text
+real app pressure
+  -> proof-local experiment
+  -> receipt-backed package primitive
+  -> protocol/read surface
+  -> docs compression
+  -> next pressure
 ```
 
-## Public Entry Points
-
-| Need | Require |
-|------|---------|
-| Core contracts/runtime | `require "igniter"` |
-| Contract/tool kernel | `require "igniter/core"` |
-| Actor runtime and built-in agents | `require "igniter/agent"` or `require "igniter/agents"` |
-| SDK registry | `require "igniter/sdk"` |
-| App runtime/profile | `require "igniter/app"` |
-| Cluster runtime | `require "igniter/cluster"` |
-
-The fuller map lives in [`docs/guide/README.md`](./docs/guide/README.md).
-
-## Repository Landmarks
-
-- [`docs/`](./docs/README.md) — structured documentation portal
-- [`docs/guide/`](./docs/guide/README.md) — user-facing docs
-- [`docs/dev/`](./docs/dev/README.md) — contributor-facing docs
-- [`examples/`](./examples/README.md) — public runnable examples
-- [`examples/companion/`](./examples/companion/README.md) — canonical stack-style demo
-- [`playgrounds/`](./playgrounds/README.md) — local-first experiments such as home-lab work
-
-## Status
-
-Igniter is intentionally being shaped as layered infrastructure:
-
-- keep `core` small and strict
-- let `app` and `cluster` grow above it
-- move reusable optional capabilities into `sdk`
-- keep user docs in `docs/guide/`
-- keep internal architecture and planning docs in `docs/dev/`
-- keep package-local quick reference next to each package README
-
-For the full documentation map, start at [`docs/README.md`](./docs/README.md).
+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.

data/docs/README.md

@@ -8,10 +8,9 @@ what you are trying to do.
 - [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
+- [Dev](./dev/README.md) for public architecture and package boundaries
+- [Research](./research/README.md) for compact horizon notes and decision
+  filters before architecture acceptance
 - [Assets](./assets/README.md) for shared documentation media such as logos
 
 ## Reading Paths
@@ -27,10 +26,9 @@ what you are trying to do.
 ### 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)
+2. [Application Showcase Portfolio](./guide/application-showcase-portfolio.md)
+3. [Interactive App Structure](./guide/interactive-app-structure.md)
+4. [Examples](../examples/README.md)
 
 ### I want distributed execution
 
@@ -38,7 +36,6 @@ what you are trying to do.
 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
 
@@ -46,7 +43,6 @@ what you are trying to do.
 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
 
@@ -54,9 +50,10 @@ 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).
+cross-package mental models in [`concepts/`](./concepts/README.md), and public
+architecture work in [`dev/`](./dev/README.md). Research staging belongs in
+[`research/`](./research/README.md) only when it is compressed enough to avoid
+leaking private cycle history into public onboarding.
 
-Legacy deep reference is cataloged in
-[`dev/legacy-reference.md`](./dev/legacy-reference.md).
+Legacy deep references and internal history are private working material under
+`playgrounds/docs/`, not public onboarding.

data/docs/assets/README.md

@@ -0,0 +1,8 @@
+# Igniter Assets
+
+Shared documentation media lives here.
+
+## Current Assets
+
+- [logo.svg](./logo.svg)
+- [logo.png](./logo.png)

data/docs/concepts/README.md

@@ -0,0 +1,18 @@
+# Igniter Concepts
+
+Use this section for durable mental models and vocabulary.
+
+## What Belongs Here
+
+- framework concepts that help explain how Igniter thinks
+- conceptual patterns that cut across packages
+- stable design language that should outlive a single implementation pass
+
+## Canonical Concepts
+
+- [Igniter](./igniter.md)
+
+## Related Sections
+
+- [Guide](../guide/README.md) for practical usage
+- [Dev](../dev/README.md) for internal architecture and implementation work

data/docs/concepts/igniter.md

@@ -0,0 +1,119 @@
+# Igniter: Concepts and Principles
+
+This document describes the core ideas behind Igniter in the shortest possible form.
+For the filesystem and layer map, start with
+[Package Map](../dev/package-map.md).
+
+## What is Igniter?
+
+**Igniter** is a Ruby framework for expressing business logic as a **validated dependency graph**.
+
+Instead of writing one long imperative flow, you describe:
+
+- the required inputs
+- the derived computations
+- the exposed outputs
+- the dependencies between them
+
+Igniter then compiles that graph, validates it, and executes it lazily at runtime.
+
+The central separation is:
+
+- **what** the graph is: model + DSL + compiler
+- **how** values are produced: runtime + executors
+
+## Philosophy
+
+1. **Declarative structure, imperative logic.**
+   Graph structure is declared with a constrained DSL. The actual business logic stays in normal Ruby.
+
+2. **Explicit dependencies.**
+   Data flow is always declared. If node `A` depends on node `B`, that relationship should be visible in code.
+
+3. **Compile first, execute second.**
+   Contracts are validated and frozen before runtime starts. Execution should never operate on a half-built graph.
+
+4. **Lazy and inspectable runtime.**
+   Igniter resolves only what is needed, caches resolved nodes, and keeps execution observable through events, diagnostics, and introspection.
+
+5. **Optional layers over a hard core.**
+   Core contracts stay the same whether you use embedded mode, AI features, server hosting, or a cluster.
+
+## Core Concepts
+
+### Contract
+
+The main unit of work in Igniter.
+
+A contract is a class inheriting from `Igniter::Contract`. It defines:
+
+- inputs
+- compute nodes
+- outputs
+- optional composition, routing, collections, effects, and reactive behavior
+
+### Definition graph
+
+The static blueprint of a contract.
+
+It is created once when the class is loaded inside the `define do ... end` block.
+The compiler validates this graph and produces a frozen compiled representation.
+
+### Execution
+
+The live runtime session for one input set.
+
+An execution owns:
+
+- current inputs
+- node states
+- cache
+- event stream
+- resolution behavior
+
+### Nodes
+
+The building blocks of the graph. Common DSL node types are:
+
+- `input` — external data entering the graph
+- `compute` — derived value or delegated executor call
+- `output` — public result exposed by the contract
+- `compose` — nested contract execution
+- `branch` — declarative runtime routing
+- `collection` — fan-out over an array of item inputs
+- `await` — suspend until an external event arrives
+- `effect` / reactive hooks — side effects driven by runtime events
+
+## Contract Lifecycle
+
+1. **Definition**
+   Ruby loads the contract class and executes `define do ... end`.
+
+2. **Compilation**
+   Igniter validates the graph and freezes the compiled form.
+
+3. **Initialization**
+   `MyContract.new(inputs)` creates a contract instance and its `Runtime::Execution`.
+
+4. **Resolution**
+   A result reader such as `contract.result.total` or `contract.resolve_all` triggers lazy resolution of only the required nodes.
+
+5. **Observation**
+   Events, diagnostics, audit snapshots, and introspection tools expose what happened during execution.
+
+6. **Update and invalidation**
+   `contract.update_inputs(...)` marks affected downstream nodes stale. Re-computation happens only when values are requested again.
+
+## Architectural View
+
+Igniter is intentionally layered:
+
+- **Core**: DSL, model, compiler, runtime, events, diagnostics
+- **Agents**: actor runtime, supervision, registry, reusable agent implementations
+- **Core features**: tools, memory, metrics, temporal support, caches
+- **Extensions**: auditing, provenance, incremental, dataflow, invariants, and similar behavioral add-ons
+- **Capability layers**: AI and Channels
+- **Hosting/profile layers**: Server, App, Cluster
+- **Plugins**: framework-specific integrations such as Rails
+
+That layering exists so that embedded use stays small, while larger deployments can add hosting and distributed concerns without rewriting domain contracts.