igniter 0.5.0 → 0.5.1

data/docs/APPLICATION_V1.md

@@ -1,253 +0,0 @@
-# Igniter::Application v1
-
-`Igniter::Application` is an optional base class that packages contracts, executors, YAML config, a background scheduler, and server startup into a single coherent entry point. It replaces the raw `Igniter::Server.configure` boilerplate and provides a conventional project layout.
-
----
-
-## Quick Start
-
-### 1. Generate a scaffold
-
-```bash
-igniter-server new my_app
-cd my_app
-bundle install
-bin/start
-```
-
-This creates:
-
-```
-my_app/
-├── application.rb       ← Application class (entry point)
-├── application.yml      ← base config (port, log_format, etc.)
-├── Gemfile
-├── config.ru            ← Rack entry point for Puma / Unicorn
-├── bin/start            ← convenience start script
-├── contracts/           ← put Contract subclasses here
-└── executors/           ← put Executor subclasses here
-```
-
-### 2. Define your Application
-
-```ruby
-# application.rb
-require "igniter"
-require "igniter/server"
-require "igniter/application"
-
-Dir[File.join(__dir__, "executors/**/*.rb")].sort.each { |f| require f }
-Dir[File.join(__dir__, "contracts/**/*.rb")].sort.each { |f| require f }
-
-class MyApp < Igniter::Application
-  config_file File.join(__dir__, "application.yml")   # optional
-
-  configure do |c|
-    c.port  = ENV.fetch("PORT", 4567).to_i
-    c.store = Igniter::Runtime::Stores::MemoryStore.new
-  end
-
-  register "OrderContract",   OrderContract
-  register "InvoiceContract", InvoiceContract
-
-  schedule :cleanup, every: "1h" do
-    puts "[cleanup] #{Time.now.strftime("%H:%M")}"
-  end
-
-  schedule :daily_report, every: "1d", at: "09:00" do
-    DailyReportContract.new.resolve_all(date: Date.today)
-  end
-end
-
-MyApp.start if $PROGRAM_NAME == __FILE__
-```
-
-### 3. Run
-
-```bash
-# Built-in HTTP server (blocking)
-ruby application.rb
-
-# Rack / Puma
-bundle exec puma config.ru
-```
-
----
-
-## DSL Reference
-
-### `config_file(path)`
-
-Load a YAML file as the base configuration. Applied **before** the `configure` block — values in the block always win.
-
-```ruby
-config_file File.join(__dir__, "application.yml")
-```
-
-### `configure { |c| ... }`
-
-Block receives an `AppConfig` instance. May be called multiple times; blocks are applied in order.
-
-```ruby
-configure do |c|
-  c.host              = "0.0.0.0"
-  c.port              = 4567
-  c.log_format        = :json          # :text (default) or :json
-  c.drain_timeout     = 30             # seconds for SIGTERM drain
-  c.store             = my_store       # any store adapter
-  c.metrics_collector = Igniter::Metrics::Collector.new
-end
-```
-
-### `executors_path(path)` / `contracts_path(path)`
-
-Eagerly require all `.rb` files under the given directory on startup.
-
-```ruby
-executors_path "executors/"
-contracts_path "contracts/"
-```
-
-### `register(name, contract_class)`
-
-Register a contract for HTTP dispatch.
-
-```ruby
-register "OrderContract", OrderContract
-```
-
-### `schedule(name, every:, at: nil) { ... }`
-
-Define a recurring background job. Starts automatically with `start` / `rack_app`.
-
-```ruby
-schedule :heartbeat, every: "30s" do
-  HealthCheckContract.new.resolve_all
-end
-
-schedule :daily_report, every: "1d", at: "09:00" do
-  DailyReportContract.new.resolve_all(date: Date.today)
-end
-```
-
-**Interval formats:**
-
-| Format | Meaning |
-|--------|---------|
-| `30` | 30 seconds (Integer) |
-| `"30s"` | 30 seconds |
-| `"5m"` | 5 minutes |
-| `"2h"` | 2 hours |
-| `"1d"` | 1 day |
-| `{ hours: 1, minutes: 30 }` | 90 minutes |
-
-`at: "HH:MM"` delays the first run until the next occurrence of that wall-clock time, then repeats with `every:`.
-
----
-
-## application.yml Reference
-
-```yaml
-server:
-  port: 4567
-  host: "0.0.0.0"
-  log_format: text      # "text" (default) or "json"
-  drain_timeout: 30     # seconds for graceful SIGTERM shutdown
-```
-
-Keys under `server:` map 1-to-1 to `AppConfig` attributes. Values from YAML are applied first; the `configure` block runs afterwards and overrides anything.
-
-ENV variables are not expanded in YAML — read them in the `configure` block:
-
-```ruby
-configure do |c|
-  c.port = ENV.fetch("PORT", 4567).to_i
-end
-```
-
----
-
-## Lifecycle
-
-### `MyApp.start`
-
-Builds the config, registers contracts, starts background jobs, then starts the built-in pure-Ruby HTTP server (blocking). Registers `at_exit` to stop the scheduler.
-
-### `MyApp.rack_app`
-
-Same as `start` but returns a Rack-compatible application instead of blocking. Use with Puma, Unicorn, or any Rack server:
-
-```ruby
-# config.ru
-require_relative "application"
-run MyApp.rack_app
-```
-
-```bash
-bundle exec puma config.ru -p 4567
-```
-
-### `MyApp.config`
-
-Returns the `AppConfig` instance (populated after the first call to `start` or `rack_app`).
-
----
-
-## Build Order
-
-1. YAML file loaded → values applied to `AppConfig`
-2. `executors_path` / `contracts_path` directories required
-3. `configure` blocks run in declaration order (override YAML)
-4. `Server::Config` built from `AppConfig`
-5. Contracts registered on the server registry
-6. Scheduler started (one thread per job)
-
----
-
-## Subclass Isolation
-
-Each `Igniter::Application` subclass gets its own isolated set of registered contracts, scheduled jobs, and configure blocks via the `inherited` hook. Subclasses do not share state:
-
-```ruby
-class AppA < Igniter::Application
-  register "ContractA", ContractA
-end
-
-class AppB < Igniter::Application
-  register "ContractB", ContractB
-end
-# AppA and AppB have completely independent registries
-```
-
----
-
-## Companion App Example
-
-`examples/companion/` is a full production-style application built with `Igniter::Application`. It implements a distributed voice AI assistant pipeline:
-
-```
-ESP32 microphone → ASR → Intent → Chat (LLM) → TTS → ESP32 speaker
-```
-
-**Single-process demo (mock executors, no hardware):**
-
-```bash
-ruby examples/companion/demo.rb
-```
-
-**Orchestrator node (HP t740, real Ollama):**
-
-```bash
-# Requires: ollama serve (llama3.1:8b pulled)
-bundle exec ruby examples/companion/application.rb
-```
-
-**See also:** [`examples/companion/README.md`](../examples/companion/README.md)
-
----
-
-## Integration with igniter-server
-
-`Igniter::Application` is a thin wrapper around `Igniter::Server`. The underlying `Server::Config` and `HttpServer` are the same — you can still use `Igniter::Server.configure` directly when you don't need the Application scaffold.
-
-The two approaches are compatible in the same process: `Igniter::Application#start` calls `Igniter::Server::HttpServer.new(config).start` internally.

data/docs/ARCHITECTURE_V2.md

@@ -1,317 +0,0 @@
-# Igniter v2 Architecture
-
-## Goal
-
-Igniter v2 is a Ruby library for describing business logic as a validated dependency graph and executing that graph with:
-
-- deterministic resolution
-- lazy evaluation
-- selective invalidation
-- transparent events
-- optional extensions built on top of the event stream
-
-The core design principle is strict separation between:
-
-- model time: describing the graph
-- compile time: validating and freezing the graph
-- runtime: resolving the graph against inputs
-
-## Design Principles
-
-1. Small, hard core.
-   The kernel should be minimal, strict, and easy to test.
-
-2. Compile first, execute second.
-   No runtime should deal with half-built DSL objects.
-
-3. Explicit data flow.
-   Dependencies, output exposure, and composition mappings are always declared.
-
-4. Extensions over hooks.
-   Auditing, reactions, tracing, and introspection consume runtime events instead of being deeply embedded in execution.
-
-5. Stable identities.
-   Nodes should have stable `id`, `path`, and `kind`. Runtime logic must not depend on Ruby object identity alone.
-
-## Layered Architecture
-
-### 1. `Igniter::Model`
-
-Pure compile-time domain objects. No lazy execution, no caching, no observers.
-
-Primary objects:
-
-- `Igniter::Model::Graph`
-- `Igniter::Model::Node`
-- `Igniter::Model::InputNode`
-- `Igniter::Model::ComputeNode`
-- `Igniter::Model::OutputNode`
-- `Igniter::Model::CompositionNode`
-- `Igniter::Model::Dependency`
-
-Responsibilities:
-
-- represent graph topology
-- store node metadata
-- store dependency declarations
-- store source location metadata for diagnostics
-- expose graph traversal primitives
-
-Constraints:
-
-- immutable after compilation
-- no implicit mutation during runtime
-
-### 2. `Igniter::Compiler`
-
-Transforms draft model definitions into a validated `CompiledGraph`.
-
-Primary objects:
-
-- `Igniter::Compiler::GraphCompiler`
-- `Igniter::Compiler::CompiledGraph`
-- `Igniter::Compiler::Validator`
-- `Igniter::Compiler::ResolutionPlan`
-
-Responsibilities:
-
-- validate node uniqueness
-- validate paths and namespaces
-- validate dependency references
-- detect cycles
-- validate composition mappings
-- compute topological order
-- freeze the result
-
-Compiler output:
-
-- stable node registry by id and path
-- dependency index
-- reverse dependency index
-- topological resolution plan
-- output registry
-
-### 3. `Igniter::Runtime`
-
-Executes a compiled graph for one input set.
-
-Primary objects:
-
-- `Igniter::Runtime::Execution`
-- `Igniter::Runtime::Resolver`
-- `Igniter::Runtime::Cache`
-- `Igniter::Runtime::Invalidator`
-- `Igniter::Runtime::NodeState`
-- `Igniter::Runtime::Result`
-- `Igniter::Runtime::ExecutorRegistry`
-
-Responsibilities:
-
-- hold input values
-- resolve requested outputs or nodes
-- cache node states
-- invalidate downstream nodes on input changes
-- emit lifecycle events
-- expose execution result
-
-Non-responsibilities:
-
-- graph validation
-- DSL parsing
-- auditing persistence
-- reactive policy decisions
-
-### 4. `Igniter::DSL`
-
-Thin syntax layer that produces a graph draft or a builder input for the compiler.
-
-Primary objects:
-
-- `Igniter::DSL::Contract`
-- `Igniter::DSL::Builder`
-- `Igniter::DSL::Reference`
-
-Responsibilities:
-
-- provide ergonomic declaration syntax
-- map user declarations to model/compiler input
-- attach source-location metadata for errors
-
-Rules:
-
-- DSL must not contain execution logic
-- DSL must not decide invalidation or cache behavior
-- DSL should prefer explicit references over `method_missing`
-
-### 5. `Igniter::Events`
-
-Canonical runtime event schema.
-
-Primary objects:
-
-- `Igniter::Events::Event`
-- `Igniter::Events::Bus`
-- `Igniter::Events::Subscriber`
-
-Responsibilities:
-
-- publish structured execution events
-- provide extension point for diagnostics and reactive features
-
-### 6. `Igniter::Extensions`
-
-Optional packages built on top of the event stream and compiled/runtime APIs.
-
-Initial extension namespaces:
-
-- `Igniter::Extensions::Auditing`
-- `Igniter::Extensions::Reactive`
-- `Igniter::Extensions::Introspection`
-
-## Runtime Boundaries
-
-The runtime is split by responsibility:
-
-- `Execution`: public session object
-- `Resolver`: resolves one node using dependencies
-- `Cache`: stores `NodeState` by node id
-- `Invalidator`: marks downstream nodes stale
-- `Result`: output facade for callers
-- `Bus`: emits execution events
-
-This is deliberate. The old shape concentrated orchestration, state mutation, notifications, and invalidation in one class. In v2, each concern gets a dedicated object.
-
-## Node Model
-
-Every compiled node should have:
-
-- `id`
-- `kind`
-- `name`
-- `path`
-- `dependencies`
-- `metadata`
-
-Candidate node kinds for v2:
-
-- `:input`
-- `:compute`
-- `:output`
-- `:composition`
-
-Optional later kinds:
-
-- `:constant`
-- `:projection`
-- `:group`
-
-### Why reduce node kinds
-
-The kernel should start with the smallest set that explains the execution model clearly. Extra node kinds should be added only when they materially simplify the model rather than encode DSL convenience.
-
-## Composition Strategy
-
-Composition is a first-class node kind.
-
-A composition node:
-
-- references another compiled contract
-- defines an input mapping from parent execution to child execution
-- returns either a child `Result` or a collection of child `Result` objects
-
-Composition rules:
-
-- parent and child graphs are independently compiled
-- child execution has its own cache and event stream
-- parent events may carry child execution correlation metadata
-
-## Extension Strategy
-
-Extensions must subscribe to events and read runtime state through stable APIs.
-
-Examples:
-
-- auditing stores a timeline of events and snapshots
-- reactive runs side effects in response to selected events
-- introspection formats compiled graphs and runtime state
-
-The kernel should not know persistence formats, storage adapters, or replay UIs.
-
-## Error Model
-
-Errors should be typed and predictable.
-
-Primary families:
-
-- `Igniter::CompileError`
-- `Igniter::ValidationError`
-- `Igniter::CycleError`
-- `Igniter::InputError`
-- `Igniter::ResolutionError`
-- `Igniter::CompositionError`
-
-Compile errors should include source metadata when available:
-
-- contract class
-- node path
-- line number
-- declaration snippet or declaration type
-
-## Packaging Rules
-
-The public surface should be intentionally small:
-
-- `require "igniter"`
-- `Igniter::Contract`
-- `Igniter.compile`
-- `Igniter.execute`
-
-Autoloading must be optional convenience, not a hard dependency for correctness.
-
-The gem must be valid and packageable without:
-
-- a `.git` directory
-- Rails
-- optional extensions
-
-## Initial Directory Shape
-
-```text
-lib/
-  igniter.rb
-  igniter/
-    version.rb
-    errors.rb
-    contract.rb
-    model/
-    compiler/
-    runtime/
-    events/
-    dsl/
-    extensions/
-      auditing/
-      reactive/
-      introspection/
-spec/
-  compiler/
-  runtime/
-  integration/
-docs/
-  ARCHITECTURE_V2.md
-  EXECUTION_MODEL_V2.md
-  API_V2.md
-```
-
-## Non-Goals for the First Rewrite
-
-These should not block the first working kernel:
-
-- Rails integration
-- persistence adapters
-- replay UI
-- async execution
-- distributed execution
-- type inference
-- speculative optimization
-
-The first target is a strict, reliable, inspectable synchronous engine.