igniter 0.5.1 → 0.5.2

data/docs/dev/execution-model.md

@@ -0,0 +1,324 @@
+# Igniter v2 Execution Model
+
+## Execution Lifecycle
+
+Each contract instance owns one runtime execution session.
+
+Lifecycle:
+
+1. caller provides inputs
+2. contract builds or reuses a compiled graph
+3. execution is created with input state, cache, and event bus
+4. caller requests one output or all outputs
+5. runtime resolves only required nodes
+6. cache stores node states
+7. input updates invalidate downstream nodes
+8. subsequent resolution reuses valid states and recomputes stale states only
+
+## Core Runtime Objects
+
+### `Execution`
+
+Public runtime session.
+
+Responsibilities:
+
+- own compiled graph
+- own input store
+- own cache
+- own event bus
+- expose `resolve`, `resolve_all`, `update_inputs`, `result`
+
+### `Resolver`
+
+Single responsibility: resolve a node into a `NodeState`.
+
+Responsibilities:
+
+- resolve dependencies first
+- execute the node's callable or adapter
+- wrap success/failure into `NodeState`
+- emit start/success/failure events
+
+### `NodeState`
+
+Represents runtime state for one compiled node.
+
+Fields:
+
+- `node_id`
+- `path`
+- `status`
+- `value`
+- `error`
+- `version`
+- `resolved_at`
+- `stale`
+
+Statuses:
+
+- `:pending`
+- `:running`
+- `:succeeded`
+- `:failed`
+- `:stale`
+
+### `Cache`
+
+Stores `NodeState` by node id.
+
+Responsibilities:
+
+- fetch current state
+- write new state
+- mark state stale
+- answer freshness queries
+
+### `Invalidator`
+
+Knows downstream dependency edges and invalidates affected nodes after input changes.
+
+Responsibilities:
+
+- walk reverse dependency graph
+- mark stale states
+- emit invalidation events
+
+## Resolution Rules
+
+### Lazy by default
+
+`result.total` should resolve only the nodes required for `total`.
+
+`result.to_h` may resolve all declared outputs, but should still use lazy node-level resolution internally.
+
+### Cached by default
+
+If a node is already resolved and not stale, the cached state is returned.
+
+### Deterministic order
+
+When a set of nodes must be resolved together, Igniter uses the compiler-generated topological order. This gives:
+
+- predictable behavior
+- deterministic event ordering
+- easier testing and auditing
+
+## Input Update Rules
+
+When inputs change:
+
+1. validate input keys
+2. update input values
+3. find all downstream nodes
+4. mark cached downstream states as stale
+5. emit `input_updated` and `node_invalidated` events
+
+No recomputation happens during invalidation itself unless explicitly requested by the caller.
+
+## Failure Rules
+
+Failures are stored as node state, not hidden in logs.
+
+If dependency resolution fails:
+
+- dependent node resolves to failed state
+- failure is explicit
+- dependent nodes can choose fail-fast behavior
+
+Default kernel policy:
+
+- input node failures are validation failures
+- compute node failures wrap exceptions in `ResolutionError`
+- output nodes mirror source node state
+
+## Composition Execution
+
+Composition node resolution:
+
+1. resolve parent-side mapping dependencies
+2. build child inputs
+3. instantiate child execution
+4. resolve child outputs inside the child execution
+5. return child `Result`
+
+Composition should not flatten child state into the parent cache. Child execution remains isolated.
+
+Recommended metadata on composition events:
+
+- `parent_execution_id`
+- `child_execution_id`
+- `composition_node_id`
+- `child_contract`
+
+## Event Contract
+
+Canonical kernel events:
+
+- `execution_started`
+- `execution_finished`
+- `execution_failed`
+- `input_updated`
+- `node_started`
+- `node_succeeded`
+- `node_failed`
+- `node_pending`
+- `node_resumed`
+- `node_invalidated`
+
+Suggested event fields:
+
+- `event_id`
+- `execution_id`
+- `timestamp`
+- `type`
+- `node_id`
+- `node_name`
+- `path`
+- `status`
+- `payload`
+
+Current payload examples:
+
+- composition success payload includes `child_execution_id` and `child_graph`
+- `execution_failed` includes `graph`, `targets`, and `error`
+- `node_invalidated` includes `cause`
+- `node_pending` includes deferred token/payload
+
+## Public Resolution API
+
+Recommended public behavior:
+
+```ruby
+contract = PriceContract.new(order_total: 100, country: "UA")
+
+contract.result.total
+contract.result.to_h
+
+contract.update_inputs(order_total: 120)
+contract.result.total
+```
+
+The runtime contract should be:
+
+- reads are lazy
+- writes invalidate
+- recomputation is explicit via subsequent reads
+
+## Concurrency
+
+The first version should be synchronous and single-threaded.
+
+Reasons:
+
+- deterministic semantics first
+- simpler cache invariants
+- easier event ordering
+- easier debugging
+
+Thread-safe or parallel execution can be added later behind explicit executors.
+
+Current core now supports:
+
+- `:inline` runner
+- `:thread_pool` runner
+- `:store` runner for pending snapshot persistence
+
+## Pending And Resume
+
+Executors may return a deferred value instead of a final result:
+
+```ruby
+class AsyncQuoteExecutor < Igniter::Executor
+  def call(order_total:)
+    defer(token: "quote-#{order_total}", payload: { kind: "pricing_quote" })
+  end
+end
+```
+
+Runtime behavior:
+
+1. node resolves to `:pending`
+2. a `DeferredResult` is stored in cache
+3. downstream nodes that depend on it also resolve to `:pending`
+4. caller may persist a snapshot
+5. later, runtime resumes the source node with a final value
+
+Public resume API:
+
+```ruby
+contract.execution.resume(:quote_total, value: 150)
+contract.execution.resume_by_token("quote-100", value: 150)
+```
+
+## Snapshot And Store Flow
+
+Execution snapshot contains:
+
+- graph name
+- execution id
+- runner metadata
+- normalized inputs
+- serialized cache states
+- serialized events
+
+Current store implementations:
+
+- `Igniter::Runtime::Stores::MemoryStore`
+- `Igniter::Runtime::Stores::FileStore`
+
+Store-backed flow:
+
+```ruby
+class AsyncPricingContract < Igniter::Contract
+  run_with runner: :store
+end
+
+contract = AsyncPricingContract.new(order_total: 100)
+deferred = contract.result.gross_total
+
+execution_id = contract.execution.events.execution_id
+restored = AsyncPricingContract.restore_from_store(execution_id)
+restored.execution.resume_by_token(deferred.token, value: 150)
+```
+
+Worker entrypoint:
+
+```ruby
+AsyncPricingContract.resume_from_store(
+  execution_id,
+  token: deferred.token,
+  value: 150
+)
+```
+
+## Kernel Invariants
+
+These invariants should be enforced by tests:
+
+1. compiled graph is immutable
+2. node path is stable
+3. same fresh node is not recomputed twice
+4. stale downstream nodes are recomputed on next read
+5. unrelated nodes are not invalidated
+6. event order is deterministic
+7. failures remain inspectable in cache/result
+8. composition creates isolated child executions
+9. pending nodes are not treated as succeeded
+10. restored executions preserve pending tokens and event identity
+
+## Testing Strategy
+
+Minimum runtime test matrix:
+
+- resolves a linear graph
+- resolves a branching graph
+- skips unrelated nodes
+- caches resolved nodes
+- invalidates only downstream nodes
+- preserves unaffected cached nodes
+- captures compute exceptions as failed node state
+- resolves nested composition
+- emits expected events in order
+- exposes machine-readable execution/result/event payloads
+- exposes diagnostics reports for both success and failure flows

data/docs/dev/igniter-web-dsl-sketch.md

@@ -0,0 +1,151 @@
+# Igniter Web DSL Sketch
+
+This note captures the current authoring-first direction for `igniter-web`.
+
+It complements:
+
+- [Igniter Web Target Plan](./igniter-web-target-plan.md)
+
+## DSL Thesis
+
+Design `igniter-web` from the shape we want users to write, not from the
+internal routing primitives first.
+
+The package should feel:
+
+- compact
+- expressive
+- low-boilerplate
+- pleasant to scan
+- friendly to long-lived, stream-heavy, non-CRUD web surfaces
+
+## Current Preferred Feel
+
+The intended tone is closer to:
+
+- Sinatra for compactness
+- Rails for pleasant conventions
+- Igniter for contracts/process/stream semantics
+
+Not:
+
+- a controller-heavy ceremony-first framework
+- an ORM-centered CRUD shell
+
+## Initial Authoring Shape
+
+The first DSL pass should make examples like this feel natural:
+
+```ruby
+app = Igniter::Web.application do
+  root title: "Operator" do
+    main class: "shell" do
+      h1 "Operator"
+      para "Cluster is healthy"
+    end
+  end
+
+  page "/projects/:id", title: "Project" do
+    main do
+      h1 assigns[:project_name]
+      para assigns[:status]
+    end
+  end
+
+  command "/projects/:id/advance", to: Contracts::AdvanceProject
+  stream "/projects/:id/events", to: Projections::ProjectEvents
+end
+```
+
+This is intentionally more compact than:
+
+- explicit controller classes
+- explicit template file wiring for every first page
+- multiple ceremony objects before the screen can exist
+
+For agent-managed and process-oriented surfaces, the DSL should also support
+screen intent that can be composed before rendering:
+
+```ruby
+screen :plan_review, intent: :human_decision do
+  title "Plan review"
+
+  show :plan_summary
+  show :risk_panel
+  compare :current_plan, :proposed_plan
+
+  action :approve, run: Contracts::ApprovePlan
+  action :revise, run: Contracts::RequestRevision
+  chat with: Agents::ProjectLead
+
+  compose with: :decision_workspace
+end
+```
+
+## DSL Priorities
+
+Prioritize these authoring wins early:
+
+- `root` and `page` as first-class route + page sugar
+- inline page blocks
+- easy promotion path from inline page to dedicated page class
+- Arbre-backed HTML authoring
+- simple layout defaults
+- compact route declarations for `command`, `query`, `stream`, and `webhook`
+
+## Promotion Path
+
+The DSL should support growth from tiny apps to richer apps without punishing
+the simple case.
+
+Start small:
+
+```ruby
+page "/chat", title: "Chat" do
+  h1 "Chat"
+end
+```
+
+Promote later:
+
+```ruby
+class ChatPage < Igniter::Web::Page
+  title "Chat"
+
+  body do
+    main do
+      h1 "Chat"
+    end
+  end
+end
+
+page "/chat", to: ChatPage
+```
+
+That gives the package a useful spectrum:
+
+- inline for small surfaces
+- classes for reusable or larger surfaces
+
+## First-Class Authoring Objects
+
+The current DSL lane should revolve around:
+
+- `Application`
+- `Page`
+- `Component`
+- `Api`
+- `Record`
+
+The shape is intentionally:
+
+- `Application` for route drawing and web composition
+- `Page` for full-screen HTML surfaces
+- `Component` for reusable UI vocabulary
+- `Api` for contracts-first transport declarations
+- `Record` for optional persistence convenience
+
+## Working Rule
+
+If a proposed API makes small web surfaces longer, noisier, or more ceremonial
+without buying a real capability, it is probably the wrong default DSL.

data/docs/dev/igniter-web-target-plan.md

@@ -0,0 +1,56 @@
+# Igniter Web Target Plan
+
+This note defines the current public target for `igniter-web`.
+
+## Thesis
+
+`igniter-web` should be the contracts-first web layer for Igniter applications.
+It should make app-owned state visible and operable without turning Igniter into
+a CRUD-first Rails clone.
+
+The primary surfaces are:
+
+- dashboards
+- operator workspaces
+- command/refusal flows
+- chats and streams when they are backed by explicit app contracts
+- receipt, report, and event review screens
+
+## Ownership
+
+`igniter-web` owns:
+
+- mounted web surfaces
+- request handling for example/review surfaces
+- screen composition primitives
+- `MountContext`
+- surface structure and surface manifest metadata
+
+It does not own:
+
+- application boot
+- provider or service registration
+- contract registration
+- app mutation policy
+- production deployment behavior
+- cluster placement
+
+Those remain application, host, or cluster concerns.
+
+## Current Proof
+
+The current proof comes from Lense, Chronicle, Scout, and Dispatch. Each app
+mounts one web surface, renders from an app-owned snapshot, exposes `/events`,
+and emits `/report` or `/receipt` evidence.
+
+Public review path:
+
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Interactive App Structure](../guide/interactive-app-structure.md)
+
+## Extraction Rule
+
+Keep repeated web shapes local until the showcase portfolio proves a stable
+abstraction. Public package APIs should be promoted only when they preserve
+clear ownership between application state, command handling, and web rendering.

data/docs/dev/mcp-adapter-package-spec.md

@@ -0,0 +1,81 @@
+# MCP Adapter Package
+
+## Purpose
+
+`igniter-mcp-adapter` is the transport-facing package that sits on top of the
+tooling semantics already defined in `igniter-extensions`.
+
+Its job is not to invent new tools. Its job is to adapt the existing catalog
+and invocation surface into a package that can host:
+
+- a real MCP server
+- CLI wrappers
+- editor integrations
+- agent-facing bridges
+
+## Source Of Truth
+
+The semantic source of truth stays in `igniter-extensions`:
+
+- `Igniter::Extensions::Contracts.mcp_tools`
+- `Igniter::Extensions::Contracts.mcp_call(...)`
+- `Igniter::Extensions::Contracts.mcp_creator_session(...)`
+
+The adapter package should treat those as authoritative.
+
+## Why A Separate Package
+
+This split gives us scalability by default:
+
+- `igniter-extensions` owns debug/creator/tooling semantics
+- `igniter-mcp-adapter` owns transport/runtime integration concerns
+- future adapters can reuse the same semantic surface without duplicating logic
+
+That means we can add more than one adapter later:
+
+- MCP server adapter
+- CLI adapter
+- IDE adapter
+- web/dev console adapter
+
+## Package Boundary
+
+`igniter-mcp-adapter`:
+
+- depends on `igniter-extensions`
+- should not depend directly on `igniter-contracts` internals
+- should not define new creator/debug semantics
+- should not become a second tool catalog source
+
+## Minimal Public Surface
+
+Near-term public surface:
+
+- `Igniter::MCP::Adapter.tool_catalog`
+- `Igniter::MCP::Adapter.tool_names`
+- `Igniter::MCP::Adapter.tool_definition(name)`
+- `Igniter::MCP::Adapter.invoke(name, ...)`
+- `Igniter::MCP::Adapter.creator_session(...)`
+
+This is intentionally thin. It keeps the adapter package honest.
+
+## Current State
+
+This is already real in the monorepo:
+
+- `Igniter::MCP::Adapter`
+  thin delegation over the semantic tooling surface
+- `Igniter::MCP::Adapter::Server`
+  transport-ready tool definitions and tool result envelopes
+- `Igniter::MCP::Adapter::Host`
+  stdio JSON-RPC host over the server wrapper
+
+So this package is no longer only a design placeholder.
+
+## Next Likely Steps
+
+1. decide whether we want additional MCP surfaces like `resources/list` or
+   `prompts/list`, or whether tools-only is the right first stable contract
+2. keep request validation aligned with generated schemas
+3. only add transport/runtime concerns that do not create a second semantic source
+4. use this package as the only place where MCP transport specifics evolve

data/docs/dev/module-system.md

@@ -0,0 +1,46 @@
+# Module System
+
+Igniter's public module map is pre-v1 and package-first.
+
+## Current Axes
+
+- `igniter-contracts`
+  embedded graph kernel: DSL, compilation, execution, diagnostics
+- `igniter-extensions`
+  optional packs over contracts: dataflow, differential, reporting, tooling
+- `igniter-embed`
+  host integration and configuration, especially Rails-style embedding
+- `igniter-application`
+  local app profile, providers, services, capsules, transfer, activation review
+- `igniter-web`
+  contracts-first web surfaces and app-local interactive screens
+- `igniter-cluster`
+  distributed routing, placement, ownership, health, and remediation
+- `igniter-mcp-adapter`
+  MCP-facing tool catalog and invocation surface
+
+## Rules
+
+- Lower layers must not know about upper layers.
+- Optional behavior should be an explicit pack, not hidden boot mutation.
+- Integrations adapt Igniter to a host; they are not runtime layers.
+- Web owns rendering; application owns app profile and lifecycle.
+- Cluster owns distribution; contracts stay local-first and host-agnostic.
+
+## Rails Boundary
+
+Rails embedding should use `igniter-embed` / Rails integration surfaces. It
+should not implicitly load application hosting, web rendering, or cluster
+coordination.
+
+## Placement Heuristic
+
+Ask in this order:
+
+1. Is it executable graph semantics? Put it in `igniter-contracts`.
+2. Is it optional reusable behavior over contracts? Put it in
+   `igniter-extensions`.
+3. Is it host integration? Put it in `igniter-embed` or a specific adapter.
+4. Is it local app runtime? Put it in `igniter-application`.
+5. Is it human/browser interaction? Put it in `igniter-web`.
+6. Is it distributed execution or coordination? Put it in `igniter-cluster`.