igniter 0.5.0 → 0.5.2

data/docs/README.md

@@ -0,0 +1,59 @@
+# Igniter Docs
+
+`docs/` is organized by section. Start here, then jump into the lane that matches
+what you are trying to do.
+
+## Sections
+
+- [Guide](./guide/README.md) for user-facing docs: getting started, API,
+  configuration, integrations, and how-tos
+- [Concepts](./concepts/README.md) for mental models and design language
+- [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
+
+### I want to use Igniter
+
+1. [Guide](./guide/README.md)
+2. [Getting Started](./guide/getting-started.md)
+3. [Core Runtime Features](./guide/core-runtime-features.md)
+4. [Concepts](./concepts/README.md)
+5. [Examples](../examples/README.md)
+
+### I want to build an app or stack
+
+1. [Guide](./guide/README.md)
+2. [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
+
+1. [Guide](./guide/README.md)
+2. [Deployment Modes](./guide/deployment-modes.md)
+3. [Distributed Workflows](./guide/distributed-workflows.md)
+4. [Cluster](./guide/cluster.md)
+
+### I want to work on the framework
+
+1. [Dev](./dev/README.md)
+2. [Architecture](./dev/architecture.md)
+3. [Module System](./dev/module-system.md)
+4. [Package Map](./dev/package-map.md)
+
+## Package Docs
+
+Package-local quick reference belongs next to the owning gem under
+`packages/<gem>/README.md`.
+
+Cross-package product docs belong in [`guide/`](./guide/README.md),
+cross-package mental models in [`concepts/`](./concepts/README.md), 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 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.

data/docs/dev/README.md

@@ -0,0 +1,48 @@
+# Igniter Dev
+
+Use this section for public contributor-facing architecture, package boundaries,
+and current design constraints.
+
+Internal cycle history, agent handoffs, research horizon material, external
+expert reports, and legacy deep references live under `playgrounds/docs/` and
+are not part of the public documentation surface.
+
+## Canonical Dev Docs
+
+- [Current Runtime Snapshot](./current-runtime-snapshot.md)
+- [Architecture](./architecture.md)
+- [Execution Model](./execution-model.md)
+- [Contract Persistence Target Plan](./contract-persistence-target-plan.md)
+- [Module System](./module-system.md)
+- [Package Map](./package-map.md)
+- [Data Ownership](./data-ownership.md)
+- [Embed Target Plan](./embed-target-plan.md)
+- [Application Target Plan](./application-target-plan.md)
+- [Application And Web Integration](./application-web-integration.md)
+- [Application Web POC Pattern Guide](./application-web-poc-pattern-guide.md)
+- [AI And Agents Target Plan](./ai-agents-target-plan.md)
+- [Cluster Target Plan](./cluster-target-plan.md)
+- [Igniter Web Target Plan](./igniter-web-target-plan.md)
+- [MCP Adapter Package](./mcp-adapter-package-spec.md)
+- [Document Rotation](./document-rotation.md)
+- [Agent Orchestra DNA](./agent-orchestra-dna.md)
+- [Architect Supervisor Bootstrap](./architect-supervisor-bootstrap.md)
+
+## Package And Layer Boundaries
+
+- [Core](../guide/core.md)
+- [App](../guide/app.md)
+- [Cluster](../guide/cluster.md)
+- [`igniter-extensions`](../../packages/igniter-extensions/README.md)
+
+## Public Docs Rule
+
+- Keep user onboarding in `docs/guide/`.
+- Keep package-local quick reference in `packages/<gem>/README.md`.
+- Keep public architecture and placement decisions in `docs/dev/`.
+- Keep private research, expert analysis, handoff history, and agent working
+  tracks in `playgrounds/docs/`.
+- Prefer updating a package README and guide index before writing new deep
+  public prose.
+- Rotate stale public docs into `playgrounds/docs/` once their accepted content
+  has been compressed into guide, dev, example, or package reference.

data/docs/dev/agent-orchestra-dna.md

@@ -0,0 +1,271 @@
+# Agent Orchestra DNA
+
+Status: portable process seed
+Owner: Architect Supervisor
+Last updated: 2026-05-12
+
+This document describes the minimal repeatable pattern for deploying an
+agent-orchestrated development loop in another project.
+
+It is intentionally project-agnostic. Use it as the DNA for a new workspace,
+then let the local Architect Supervisor adapt names, roles, folders, and cadence
+to the target project.
+
+## Core Thesis
+
+Agents need a map, not the whole history.
+
+The system works when every participant can answer:
+
+- where are we now?
+- what is canonical?
+- what is being worked now?
+- who owns each decision?
+- what evidence proves a change?
+- where should useful pressure route next?
+
+The short formula:
+
+```text
+Role + Context + Card + Lens + Authority + Route
+```
+
+Each part prevents a common failure:
+
+| Part | Prevents |
+| --- | --- |
+| Role | Agent invents its own job or claims another role's authority |
+| Context | Agent rereads history and reconstructs a stale project model |
+| Card | Slice expands beyond the current task |
+| Lens | Review asks the wrong questions |
+| Authority | Discussion or pressure accidentally becomes canon |
+| Route | Useful insight remains prose instead of becoming work |
+
+## Minimal Workspace Shape
+
+Default path for a new project:
+
+```text
+docs/agents/
+  README.md
+  current-status.md
+  operating-model.md
+  roles/
+    README.md
+  handoff/
+    README.md
+    onboarding-card-template.md
+    instance-routing.md
+  tracks/
+    README.md
+  discussions/
+    README.md
+  decisions/
+    README.md
+  lineups/
+    README.md
+  inbox/
+    README.md
+  archive/
+```
+
+If the project already has a documentation convention, adapt the path. The
+important thing is not the folder name. The important thing is that active maps,
+ephemeral tracks, decisions, role profiles, discussions, and archives are not
+mixed together.
+
+## Roles
+
+Start with a small orchestra. Add roles only when the work produces a real
+pressure that a current role cannot hold cleanly.
+
+| Role | Purpose |
+| --- | --- |
+| Architect Supervisor | Owns rounds, scope, authority, gates, and final routing |
+| Implementation Agent | Makes bounded code changes after authority exists |
+| Research Agent | Builds proofs, maps uncertainty, validates hypotheses |
+| Domain Pressure Agent | Pushes from product, user, domain, and business reality |
+| QA/Test Agent | Runs targeted verification and turns failures into evidence |
+| Status Curator | Maintains current maps, round summaries, and next-state clarity |
+| External Pressure Reviewer | Fresh-context critique; pressure only, no canon authority |
+| Archive/Form Expert | Separates history, canon, archive, and zombie documents |
+| Line Up Summarizer | Compresses bulky sources into compact memory cards |
+| History Curator | Long-cycle archaeology, preservation, and context hygiene |
+
+Role and agent are different:
+
+```text
+Agent: [Spark CRM Runtime Reviewer]
+Role:  external-pressure-reviewer
+Lens:  runtime-pressure
+```
+
+One role may have multiple instances. One agent may borrow a lens for a single
+card, but it does not replace the base role.
+
+## Card Codes
+
+Use compact card ids so humans can dispatch parallel work without rereading the
+whole plan.
+
+```text
+Card: S1-R2-C3-P1
+```
+
+Meaning:
+
+| Code | Meaning |
+| --- | --- |
+| `S1` | Stage 1 |
+| `R2` | Supervisor round 2 |
+| `C3` | Card 3 inside the round |
+| `P` | Parallel-safe |
+| `P1`, `P2` | Parallel series; same number may start together |
+| `B` | Blocked or ordered; check dependencies before starting |
+| `S` | Serial or supervisor-only; usually after a round barrier |
+| `A` | Architect/authority decision; no implementation unless scoped |
+| `I` | Implementation/code-writing slice; tests or proofs expected |
+
+Dispatch pattern:
+
+```text
+R = [[C1-P1, C2-P1] -> C3-S -> [C4-P2, C5-P2]]
+```
+
+`C1-P1` and `C2-P1` may run together. `C3-S` runs after P1 closes. `C4-P2` and
+`C5-P2` may run together after the serial barrier.
+
+## Instance Routes
+
+Every agent instance should choose a startup route before work.
+
+| Situation | Route | Use when |
+| --- | --- | --- |
+| New chat / fresh agent | `INIT` | No previous handoff in this chat |
+| Same agent, new card | `UPDATE` | Role is known, work changed |
+| Same card in progress | `IN_FLIGHT_REFRESH` | Need to re-check changed files or maps |
+| Returning after delay | `STALE_REFRESH` | Stage, round, gate, or same-role work moved |
+| Discussion mode | `DISCUSSION` | Producing critique or pressure, not code/canon |
+| Stage-level role | `STAGE_LOOP` | Long-cycle work without per-round cards |
+
+Minimal startup statement:
+
+```text
+Route:
+Agent:
+Role:
+Card:
+Current stage/round observed:
+Neighbor risk:
+```
+
+## Authority Boundary
+
+Output types are not equal.
+
+| Output type | Authority |
+| --- | --- |
+| Inbox note | Unrouted input |
+| Discussion | Pressure only |
+| Review | Signal that needs intake |
+| Track | Evidence for one bounded slice |
+| Proposal | Candidate design or semantics |
+| Spec | Canon after acceptance/sync |
+| Decision | Architect-owned authorization |
+| Implementation | Code inside an authorized surface |
+
+The word `proceed` in a review means "safe to route onward", not "authorized to
+implement".
+
+## Round Loop
+
+The default loop:
+
+```text
+Architect Supervisor
+  -> opens cards and authority boundaries
+Agents
+  -> execute bounded slices and handoff
+External Pressure / QA
+  -> challenge and verify
+Status Curator / Meta
+  -> updates maps and extracts next blockers
+Architect Supervisor
+  -> closes, redirects, authorizes, or opens next round
+```
+
+Keep the loop small enough that the current state can be reloaded from the maps,
+not reconstructed from the archive.
+
+## Document Lifecycle
+
+No document should have an undefined status.
+
+```text
+inbox
+  -> reject
+  -> discussion
+  -> track
+  -> decision
+  -> proposal
+  -> spec
+  -> lineup
+  -> archive
+```
+
+Use lineups for context hoisting:
+
+```text
+large source document
+  -> compact Line Up summary
+  -> source remains authoritative for exact proof logs
+  -> active maps link to Line Up, not bulky history
+```
+
+Use archive mode for history:
+
+```text
+history is preserved
+  but not required reading for new work
+```
+
+## Safety Rules
+
+- Do not read the entire repository unless explicitly assigned archaeology.
+- Do not revert, stage, clean, or remove files that may belong to another agent.
+- Do not promote pressure, discussion, or research into canon without routing.
+- Do not implement behavior before authority exists.
+- Do not hide unresolved blockers behind a positive summary.
+- Prefer exact file links and compact handoffs over narrative memory.
+- Treat multiple instances of the same role as normal.
+
+## Stage 0 Bootstrap
+
+For a new project, the first stage should produce only a map and operating
+surface. Avoid code changes unless the user explicitly asks.
+
+Suggested first round:
+
+```text
+S0-R1-C1-A  Architect Supervisor: create project intake map
+S0-R1-C2-P1 Research Agent: project structure and build/test map
+S0-R1-C3-P1 Domain Pressure Agent: product/domain pain map
+S0-R1-C4-P1 Archive/Form Expert: documentation/context map
+S0-R1-X1-S  External Pressure Reviewer: fresh-context critique
+S0-R1-C5-S  Status Curator: current-status and next round
+```
+
+After Stage 0, the project should have:
+
+- a current status map;
+- a role map;
+- a first backlog of concrete tracks;
+- a clear list of protected surfaces;
+- known build/test commands;
+- known document rotation rules.
+
+## Copy-Paste Bootstrap
+
+Use [Architect Supervisor Bootstrap](./architect-supervisor-bootstrap.md) to
+initialize a new project chat.
+

data/docs/dev/ai-agents-target-plan.md

@@ -0,0 +1,178 @@
+# AI And Agents Target Plan
+
+This track moves live AI and agent behavior out of application examples and
+back into package-owned Igniter surfaces.
+
+Status: accepted direction, not stable API.
+
+## Motivation
+
+Applications should configure AI and agents; they should not invent provider
+clients, agent loops, tool policy, memory, or replay seams locally.
+
+The Companion application is the current proof pressure: it needs live LLM
+value, credentials, stored user state, and future assistant capsules, but those
+capabilities must become reusable package primitives before they harden inside
+one app.
+
+## Package Ownership
+
+### `igniter-ai`
+
+Owns provider-neutral AI execution:
+
+- provider clients and model request/response envelopes
+- credentials-aware client configuration
+- live, fake, and recorded execution modes
+- prompt/message/transcript value objects
+- usage, errors, provider metadata, and response normalization
+- evaluation and replay seams for examples and tests
+
+Does not own:
+
+- long-running agent loops
+- application routing or boot lifecycle
+- web rendering
+- MCP transport
+
+First provider target: OpenAI Responses API, wrapped behind an Igniter request
+envelope so examples do not call provider-specific clients directly.
+
+### `igniter-agents`
+
+Owns agent runtime semantics over contracts and AI:
+
+- agent definitions, runs, turns, traces, and lifecycle state
+- tool catalogs, tool calls, and tool policy
+- memory/context interfaces
+- planning and handoff envelopes
+- human gates, approvals, and resumable waits
+- supervisor and worker coordination vocabulary
+
+Does not own:
+
+- provider-specific HTTP clients
+- Rails/Rack/web rendering
+- distributed mesh placement
+- application-specific assistant features
+
+`igniter-agents` depends conceptually on `igniter-ai` for model execution and
+on contracts for typed tools/results. It should stay usable without web.
+
+## Boundary Rules
+
+- `igniter-application` wires credentials, store choices, boot lifecycle, and
+  app-local configuration into AI/agent packages.
+- `igniter-web` renders chat, approval, stream, and review surfaces from
+  application snapshots; it does not run agent logic.
+- `igniter-mcp-adapter` exposes existing tool catalogs over transport; it does
+  not become the agent runtime.
+- `igniter-extensions` may provide tool packs and diagnostics over contracts,
+  but not provider-specific AI execution.
+- Example apps may demonstrate capabilities, but app-local AI code is treated
+  as temporary until the corresponding package primitive exists.
+
+## Human DSL Shape
+
+The package APIs should support two equal forms:
+
+- agent-facing explicit objects for tests, tooling, replay, and generated code
+- human-facing sugar DSL for compact application configuration
+
+Target application shape:
+
+```ruby
+Igniter::Application.define(:companion) do
+  credential :openai_api_key, env: "OPENAI_API_KEY"
+
+  ai do
+    provider :openai, credential: :openai_api_key, model: "gpt-5.2"
+    mode ENV["COMPANION_LIVE"] == "1" ? :live : :fake
+  end
+
+  agents do
+    assistant :daily_companion do
+      use_model :openai
+      use_tools :reminders, :trackers, :countdowns
+      memory :sqlite, namespace: :companion
+      human_gate :approval, for: :destructive_actions
+    end
+  end
+end
+```
+
+This is illustrative, not accepted API.
+
+## First Implementation Slice
+
+Status: package skeleton, application-level AI provider DSL, and minimal
+single-turn agent runtime landed.
+
+1. Create `packages/igniter-ai` with zero production dependencies.
+2. Move the Companion OpenAI Responses behavior behind
+   `Igniter::AI::Providers::OpenAIResponses`.
+3. Add fake and recorded providers so examples stay offline by default.
+4. Add request/response envelopes with normalized `text`, `usage`, `metadata`,
+   and `error`.
+5. Let `igniter-application` configure AI providers through credentials without
+   provider-specific code in the app.
+6. Keep Companion as the reference consumer and remove its local provider once
+   the package slice is green.
+
+Acceptance:
+
+- no network calls in default specs or example smoke
+- live mode requires explicit environment opt-in
+- provider errors return structured failure envelopes
+- credentials remain redacted in profiles and manifests
+- Companion still runs in fake/offline mode and can opt into live mode
+
+## Second Implementation Slice
+
+Status: minimal package skeleton and application-level agent DSL landed;
+capsule transfer can now carry declared agents as capabilities; memory,
+handoff, human gates, and contracts-first tool execution are still next.
+
+1. Create `packages/igniter-agents` around minimal agent run state.
+2. Treat tools as contracts-first callables.
+3. Add a single-turn assistant runner over `igniter-ai`.
+4. Add trace envelopes that can be rendered by application/web surfaces.
+5. Add human gate state without requiring a web package.
+
+Acceptance:
+
+- agent runs are serializable and replayable
+- tool calls expose typed inputs/results
+- web can render run state without owning runtime logic
+- applications can run a simple assistant without custom loop code
+
+## Agent-Aware Capsule Transfer
+
+Status: first deterministic slice landed.
+
+Capsule transfer treats agents as declared application capabilities. Transfer
+reports carry agent declarations through capsule reports, handoff manifests,
+inventories, intake/apply plans, and receipts. Readiness can block an agent
+capsule when the required AI provider is not declared.
+
+Transfer does not run agents by default. Agents may review reports later, but
+the source of truth remains the deterministic transfer pipeline.
+
+## Legacy Filter
+
+Legacy package layout is useful as vocabulary, not as code to restore blindly.
+
+Accepted concepts:
+
+- separate AI and agent packages
+- provider abstraction
+- tool registry
+- skill/runtime-contract idea
+- registry-backed agent adapter
+
+Rejected for now:
+
+- broad SDK umbrella
+- server-first agent sessions
+- package surfaces that require distributed runtime
+- provider APIs leaking into application examples