igniter 0.4.5 → 0.5.1

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.

data/docs/BACKLOG.md

@@ -1,166 +0,0 @@
-# Igniter Backlog
-
-This file is a lightweight backlog for ideas that are worth preserving before they turn into active implementation work.
-
-## Collections v1
-
-Status: idea
-Priority: high
-
-Problem:
-
-- Real orchestration often needs fan-out over a list of homogeneous items.
-- Without a collection primitive, users will hide loops inside `compute` nodes.
-- That reduces graph transparency and makes diagnostics, invalidation, and async execution weaker.
-
-Example direction:
-
-```ruby
-collection :technicians,
-  depends_on: :technician_inputs,
-  each: TechnicianContract,
-  key: :technician_id,
-  mode: :collect
-```
-
-Likely semantics:
-
-- `depends_on:` should resolve to an array of item input hashes
-- `each:` should point to a child contract or executor-like collection worker
-- `key:` should provide stable item identity for invalidation, resume, and diagnostics
-- `mode:` should control failure semantics, for example `:collect` vs `:fail_fast`
-
-Why it matters:
-
-- enables explicit fan-out/fan-in in the graph model
-- fits naturally with `thread_pool` execution
-- creates a path toward item-level async/pending/resume
-- improves diagnostics over collection workflows
-
-Open design questions:
-
-- result shape: array, keyed hash, or dedicated `CollectionResult`
-- compile-time validation for item schema and key extraction
-- per-item invalidation and snapshot/restore behavior
-- item-level events and auditing model
-- parent failure semantics when some items fail or remain pending
-
-Suggested implementation order:
-
-1. write a short design doc for Collections v1
-2. define graph/model/runtime semantics
-3. add compile-time validators
-4. add a minimal synchronous implementation
-5. extend to parallel runner
-6. later extend to pending/store-backed item execution
-
-## Conditional Branches v1
-
-Status: idea
-Priority: high
-
-Problem:
-
-- Real orchestration often needs explicit conditional routing.
-- Without a branching primitive, users push control flow into `compute` blocks or executors.
-- That hides workflow structure and weakens diagnostics and introspection.
-
-Example direction:
-
-```ruby
-branch :delivery_strategy, depends_on: :country do
-  on "US", contract: USDeliveryContract
-  on "UA", contract: LocalDeliveryContract
-  else contract: DefaultDeliveryContract
-end
-```
-
-Why it matters:
-
-- makes control flow explicit in the graph
-- keeps routing logic out of generic `compute` nodes
-- improves explainability by showing which branch was selected
-- fits future schema/UI-driven graph composition
-
-Likely semantics:
-
-- `depends_on:` resolves the selector input
-- one branch is selected at runtime based on ordered matching
-- the selected branch behaves like a composition-like node
-- diagnostics and events should include which branch matched
-
-Open design questions:
-
-- exact-match only vs predicate-based matching
-- whether `else` is required or optional
-- compatibility of outputs across different branches
-- how branch nodes appear in plans, graphs, and runtime state
-- whether branches select contracts only or also arbitrary nodes/executors
-
-Suggested implementation order:
-
-1. write a short design doc for Branches v1
-2. define graph/model/runtime semantics
-3. add compile-time validation for branch definitions
-4. implement a minimal contract-branching version
-5. add introspection and diagnostics for selected branch visibility
-6. later extend to schema-driven graph builders
-
-## Namespaces / Scopes v1
-
-Status: idea
-Priority: medium
-
-Problem:
-
-- Larger contracts need a way to group related nodes without extracting every subgraph into a separate top-level contract.
-- Without grouping, large orchestration graphs become flat and harder to scan.
-- Users may want a local container for related calculations before deciding whether the logic deserves a standalone contract.
-
-Example direction:
-
-```ruby
-scope :availability do
-  lookup :vendor, depends_on: %i[trade vendor_id], call: LookupVendor
-  lookup :zip_code, depends_on: [:zip_code_raw], call: LookupZipCode
-  compute :geo_bids, depends_on: %i[zip_code vendor], call: LookupGeoBids
-  compute :availability, depends_on: %i[vendor zip_code], call: CalculateAvailability
-end
-```
-
-Possible extended direction:
-
-```ruby
-namespace :availability do
-  input :vendor_id
-  input :zip_code_raw
-
-  compute :vendor, ...
-  compute :availability, ...
-
-  output :availability
-end
-```
-
-Why it matters:
-
-- improves readability of larger contracts
-- creates a middle layer between a flat graph and full contract composition
-- may provide a path toward inline-contract semantics
-- could improve future graph visualization and schema editing UX
-
-Open design questions:
-
-- purely visual grouping vs real runtime/model boundary
-- whether scoped nodes get path prefixes like `availability.vendor`
-- whether scopes can define local inputs/outputs
-- how scopes differ from composition and when users should prefer one over the other
-- whether inline contracts should compile into the same graph or nested child executions
-
-Suggested implementation order:
-
-1. write a short design note comparing scopes vs composition
-2. decide whether v1 is visual/logical grouping only or a true subgraph primitive
-3. define path, output, and introspection semantics
-4. implement minimal grouping support
-5. later evaluate inline-contract execution semantics

data/docs/BRANCHES_V1.md

@@ -1,213 +0,0 @@
-# Branches v1
-
-## Goal
-
-`branch` introduces explicit conditional routing as a graph primitive.
-
-The feature should make control flow:
-
-- declarative
-- visible at compile time
-- visible in graph introspection
-- visible in runtime diagnostics and events
-
-It should avoid pushing routing logic into generic `compute` blocks or executors.
-
-## DSL
-
-### Basic form
-
-```ruby
-branch :delivery_strategy, with: :country do
-  on "US", contract: USDeliveryContract
-  on "UA", contract: LocalDeliveryContract
-  default contract: DefaultDeliveryContract
-end
-```
-
-### Exporting outputs
-
-```ruby
-branch :delivery_strategy, with: :country do
-  on "US", contract: USDeliveryContract
-  on "UA", contract: LocalDeliveryContract
-  default contract: DefaultDeliveryContract
-end
-
-export :price, :eta, from: :delivery_strategy
-```
-
-### Nested result
-
-```ruby
-output :delivery_strategy
-```
-
-This should return a child result object, similar to composition.
-
-## Why `default` and not `else`
-
-`default` is preferred because:
-
-- it is valid Ruby DSL syntax
-- it is not a reserved keyword
-- it reads clearly as a fallback branch
-- it serializes more cleanly into schema-driven representations
-
-## Scope of v1
-
-Branches v1 should stay intentionally narrow.
-
-Supported:
-
-- exact-match branch selection
-- one selector dependency
-- child contracts as branch targets
-- explicit fallback through `default`
-- branch result as a composition-like nested result
-- `export` from the selected branch
-
-Not supported in v1:
-
-- predicate lambdas
-- regex or set matching
-- multiple selectors
-- executor targets
-- node-level arbitrary targets
-- implicit output merging
-
-## Runtime Semantics
-
-1. Resolve the selector dependency.
-2. Match the selector value against declared `on` cases in order.
-3. If no case matches, use `default`.
-4. Instantiate and resolve the selected child contract.
-5. Mark the branch node as succeeded only after the selected child contract succeeds.
-
-If the selected child contract fails, the branch node fails.
-
-Unselected branches must not execute.
-
-## Compile-Time Validation
-
-The compiler should validate:
-
-- branch name uniqueness
-- selector dependency existence
-- at least one `on` case
-- exactly one `default`
-- unique case values within the branch
-- each case has a valid contract
-- the default has a valid contract
-- exported outputs exist across all possible branch contracts
-
-The last point is important:
-
-If the contract exports `price` from a branch, then every possible branch contract must expose `price`.
-
-## Result Semantics
-
-The branch node should behave similarly to composition:
-
-- nested result available via `output :branch_name`
-- child outputs re-exportable through `export`
-
-This keeps branch consistent with the existing composition mental model.
-
-## Graph Model
-
-Branches v1 should introduce a dedicated node kind:
-
-- `:branch`
-
-Suggested internal shape:
-
-```ruby
-BranchNode.new(
-  name: :delivery_strategy,
-  selector: :country,
-  cases: [
-    { match: "US", contract: USDeliveryContract },
-    { match: "UA", contract: LocalDeliveryContract }
-  ],
-  default_contract: DefaultDeliveryContract
-)
-```
-
-This should not be modeled as a normal compute node.
-
-## Events
-
-Branches v1 should add a specific runtime event:
-
-- `branch_selected`
-
-Suggested payload:
-
-```ruby
-{
-  selector: :country,
-  selector_value: "US",
-  matched_case: "US",
-  selected_contract: "USDeliveryContract"
-}
-```
-
-This should improve observability and diagnostics without forcing users to infer branch choice from child execution state.
-
-## Introspection
-
-### Graph text / Mermaid
-
-Branch nodes should render distinctly from compute and composition nodes.
-
-The graph should show:
-
-- selector dependency
-- available branch cases
-- default contract
-
-### Plan
-
-Before execution:
-
-- branch node is blocked on selector resolution
-- available branches are visible as candidates
-
-After execution:
-
-- selected branch is visible in runtime state or diagnostics
-
-### Diagnostics
-
-Diagnostics should surface:
-
-- selector value
-- selected branch case
-- selected child contract
-
-## Error Model
-
-Suggested runtime error:
-
-- `Igniter::BranchSelectionError`
-
-Used for:
-
-- invalid branch configuration reaching runtime
-- missing match if a branch somehow has no `default`
-
-In a well-validated graph, this error should be rare.
-
-## Future Extensions
-
-Possible later additions:
-
-- `in:` matching
-- `matches:` matching
-- predicate matching
-- branch-to-executor targets
-- schema-driven branch authoring
-- branch-aware collections
-
-These should not be part of v1.