igniter 0.2.0

data/docs/ARCHITECTURE_V2.md

@@ -0,0 +1,317 @@
+# 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.

data/docs/EXECUTION_MODEL_V2.md

@@ -0,0 +1,245 @@
+# 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_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`
+
+## 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.
+
+## 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
+
+## 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/IGNITER_CONCEPTS.md

@@ -0,0 +1,81 @@
+# Igniter: Concepts and Principles
+
+This document describes the high-level concepts, philosophy, and architectural principles behind the Igniter framework.
+
+## What is Igniter?
+
+**Igniter** is a Ruby framework for building **declarative, auditable, and reactive business processes**.
+
+It allows you to describe complex business logic not as a sequence of imperative steps, but as a **dependency graph** of
+data and computations. Igniter handles the orchestration of this graph: it determines *when* and in *what order* to
+perform computations, and it does so lazily—only when a result is actually needed.
+
+The core idea is to separate the description of **WHAT** needs to be done (the graph's structure) from **HOW** it's
+done (the Ruby logic within the computations).
+
+## Philosophy
+
+1. **Declarative Structure, Imperative Logic.**
+   The process structure (inputs, outputs, dependencies) is described using a simple and limited DSL. The computations
+   and business rules themselves are written in pure, powerful, and familiar Ruby. We are not inventing a new language,
+   but providing a framework for organizing existing code.
+
+2. **Explicit is better than Implicit.**
+   Dependencies between components are always declared explicitly (`depends_on: ...`). The framework avoids "magic," automatic
+   dependency injection, or hidden behaviors. If node `A` depends on node `B`, it's always visible in the code.
+
+3. **Separation of Concerns.**
+   Igniter is architecturally divided into independent modules:
+    * **Definition:** The static "description" of a contract.
+    * **Runtime:** The "live" execution and computation of the graph.
+    * **DSL:** The tools for building the definition graph.
+    * **Auditing:** Recording and replaying the execution history.
+    * **Reactive:** Reacting to events within the graph.
+
+4. **Transparency and Debugging "out of the box."**
+   The framework is designed so that its execution is easy to trace. Built-in graph/runtime introspection and
+   auditing snapshots are not add-ons, but an integral part of the core.
+
+## Key Concepts
+
+#### Contract
+
+The main unit of work in Igniter. A class inheriting from `Igniter::Contract` that encapsulates a single business process.
+
+#### Definition Graph
+
+The static "blueprint" or "plan" of a contract. It is created once when the class is loaded, within the
+`define do ... end` block. This graph describes all the nodes, their types, and the dependencies between them. It is
+immutable during execution.
+
+#### Runtime Graph
+
+The "live" representation of the contract at runtime. It contains `Runtime::NodeState` objects, which store the computed
+values, statuses (`:succeeded`, `:failed`, `:stale`), and errors for each node.
+
+#### Nodes
+
+The basic building blocks of the graph. The main node types in the DSL are:
+
+* **`input`**: The entry point for data into the contract.
+* **`compute`**: The main workhorse node. It performs data transformation. It can be a simple computation (with a `Proc`
+  or method) or a composition of another contract.
+* **`output`**: The public interface of the contract. It declares which internal nodes are the official result of the
+  process.
+* **`composition`**: A special kind of `compute` that encapsulates and executes another contract, allowing for the
+  construction of a process hierarchy.
+* **`reaction`**: A node describing a side effect that should occur in response to an event on the graph (e.g., on the
+  successful computation of another node).
+
+## Contract Lifecycle
+
+1. **Definition:** Ruby loads the contract class. The `context` block is executed, building the static
+   compiled graph.
+2. **Initialization:** `MyContract.new(inputs)` is called. An instance of the contract and its execution context (
+   `Runtime::Execution`) are created. The input data is stored.
+3. **Execution:** a result reader such as `contract.result.total` or `contract.resolve_all` is called. Igniter begins to lazily traverse the dependency graph, starting from the
+   `output` nodes. It only computes the nodes necessary to produce the result. Computation results are cached.
+4. **Result:** After resolution completes, the `contract.result` object provides access to the outputs and the overall
+   status (`success?`/`failed?`).
+5. **Update and Re-computation:** When input data is changed with `contract.update_inputs(...)`, Igniter invalidates only the parts of the graph that depend on the changed input and re-computes only
+   them.

data/examples/README.md

@@ -0,0 +1,77 @@
+# Examples
+
+These scripts are intended to be runnable entry points for new users.
+Each one can be executed directly from the project root with `ruby examples/<name>.rb`.
+
+## Available Scripts
+
+### `basic_pricing.rb`
+
+Run:
+
+```bash
+ruby examples/basic_pricing.rb
+```
+
+Shows:
+
+- defining a basic contract
+- lazy output resolution through `result`
+- selective recomputation after `update_inputs`
+
+Expected output:
+
+```text
+gross_total=120.0
+updated_gross_total=180.0
+```
+
+### `composition.rb`
+
+Run:
+
+```bash
+ruby examples/composition.rb
+```
+
+Shows:
+
+- nested contracts through `compose`
+- returning child results through an output
+- serializing composed output values with `result.to_h`
+
+Expected output:
+
+```text
+pricing={:pricing=>{:gross_total=>120.0}}
+```
+
+### `diagnostics.rb`
+
+Run:
+
+```bash
+ruby examples/diagnostics.rb
+```
+
+Shows:
+
+- diagnostics text summary
+- machine-readable `result.as_json`
+- execution state visibility after a successful run
+
+Expected output shape:
+
+```text
+Diagnostics PriceContract
+Execution <uuid>
+Status: succeeded
+Outputs: gross_total=120.0
+...
+---
+{:graph=>"PriceContract", ...}
+```
+
+## Validation
+
+These scripts are exercised by [example_scripts_spec.rb](/Users/alex/dev/hotfix/igniter/spec/igniter/example_scripts_spec.rb), so the documented commands and outputs stay aligned with the code.