igniter 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9146f111caa1071ea7ba8ede536e39a00450193c60748a176ab2e6a0cb0fc15
+  data.tar.gz: 6f120c1d14c286dea458b58dbefbdd1d908a3eca77edad22fe933b145103639a
+SHA512:
+  metadata.gz: d6de8e1d3228aaa17148abba206fe1185458ef316bd9a7153e3b02b460297bc7d838df47f6c3a95b266a56759bbc3aab3a2de0af68d0834005b863ae1a64f66a
+  data.tar.gz: 74f0b01d50f7d301c5519af7e54ce4042b02736321af2ae6d9beba3cb79dcbf1464e6ec59751668025cc0ad9012cce5a42ec36ee2fb1b46d23d43306e4366656

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-03-18
+
+- Complete the `arbor` to `igniter` rename across runtime, docs, examples, console setup, and shipped signatures.
+- Strengthen compile-time validation for proc signatures, composition input mappings, node ids, and node paths.
+- Refine runtime semantics with a dedicated invalidation object, stricter execution lifecycle events, and explicit `execution_failed` signaling.
+- Make composition resolution eager and reliable so parent composition nodes fail when child executions fail.
+- Add structured error context with graph, node, path, and source location metadata.
+- Expand introspection with stable node ids, invalidation details, richer explain output, and machine-readable execution/result/event payloads.
+- Add diagnostics reports with structured, text, and markdown summaries for successful and failed executions.
+- Add runnable example scripts plus smoke-tested quick-start examples and refresh the public documentation.
+
+- Rename the gem and top-level namespace from `arbor` to `igniter`.
+- Replace the legacy prototype with the v2 core runtime, compiler, DSL, and extensions.
+- Add typed inputs, composition, auditing, reactive subscriptions, and introspection.
+
+## [0.1.0] - 2025-08-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Alexander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# Igniter
+
+Igniter is a Ruby gem for expressing business logic as a validated dependency graph and executing that graph with:
+
+- lazy output resolution
+- selective invalidation after input updates
+- typed input validation
+- nested contract composition
+- runtime auditing
+- diagnostics reports
+- reactive side effects
+- graph and runtime introspection
+
+The repository now contains a working v2 core built around explicit compile-time and runtime boundaries.
+
+## Installation
+
+```ruby
+gem "igniter"
+```
+
+## Quick Start
+
+```ruby
+require "igniter"
+
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+    input :vat_rate, type: :numeric, default: 0.2
+
+    compute :effective_vat_rate, depends_on: %i[country vat_rate] do |country:, vat_rate:|
+      country == "UA" ? vat_rate : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total effective_vat_rate] do |order_total:, effective_vat_rate:|
+      order_total * (1 + effective_vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+
+contract.result.gross_total
+# => 120.0
+
+contract.update_inputs(order_total: 150)
+contract.result.gross_total
+# => 180.0
+
+contract.diagnostics_text
+# => compact execution summary
+```
+
+## Features
+
+- Contracts: declare inputs, compute nodes, outputs, and compositions.
+- Compiler: validate dependency graphs before runtime.
+- Runtime: cache resolved nodes and invalidate only affected downstream nodes.
+- Typed inputs: validate types, defaults, and required fields.
+- Composition: execute nested contracts with isolated child executions.
+- Auditing: collect execution timelines and snapshots.
+- Diagnostics: build compact text, markdown, or structured reports for triage.
+- Reactive: subscribe declaratively to runtime events.
+- Introspection: render graphs as text or Mermaid and inspect runtime state.
+
+## Quick Start Recipes
+
+The repository contains runnable examples in [`examples/`](examples).
+They also have matching specs, so they stay in sync with the implementation.
+The examples folder also has its own quick index in [`examples/README.md`](examples/README.md).
+
+| Example | Run | Shows |
+| --- | --- | --- |
+| `basic_pricing.rb` | `ruby examples/basic_pricing.rb` | basic contract, lazy resolution, input updates |
+| `composition.rb` | `ruby examples/composition.rb` | nested contracts and composed results |
+| `diagnostics.rb` | `ruby examples/diagnostics.rb` | diagnostics text plus machine-readable output |
+
+There are also matching living examples in `spec/igniter/examples_spec.rb`.
+Those are useful if you want to read the examples in test form.
+
+### 1. Basic Pricing Contract
+
+```ruby
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, depends_on: [:country] do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+PriceContract.new(order_total: 100, country: "UA").result.gross_total
+# => 120.0
+```
+
+### 2. Nested Composition
+
+```ruby
+class CheckoutContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compose :pricing, contract: PriceContract, inputs: {
+      order_total: :order_total,
+      country: :country
+    }
+
+    output :pricing
+  end
+end
+
+CheckoutContract.new(order_total: 100, country: "UA").result.pricing.gross_total
+# => 120.0
+```
+
+### 3. Diagnostics And Introspection
+
+```ruby
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+
+contract.result.states
+contract.result.explain(:gross_total)
+contract.diagnostics.to_h
+contract.diagnostics_text
+contract.diagnostics_markdown
+contract.audit_snapshot
+```
+
+### 4. Machine-Readable Data
+
+```ruby
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+
+contract.result.to_h
+# => { gross_total: 120.0 }
+
+contract.result.as_json
+contract.execution.as_json
+contract.events.map(&:as_json)
+```
+
+## Composition Example
+
+```ruby
+class PricingContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+
+    compute :gross_total, depends_on: [:order_total] do |order_total:|
+      order_total * 1.2
+    end
+
+    output :gross_total
+  end
+end
+
+class CheckoutContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+
+    compose :pricing, contract: PricingContract, inputs: {
+      order_total: :order_total
+    }
+
+    output :pricing
+  end
+end
+
+CheckoutContract.new(order_total: 100).result.pricing.gross_total
+# => 120.0
+```
+
+## Reactive Example
+
+```ruby
+class NotifyingContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    output :order_total
+  end
+
+  react_to :node_succeeded, path: "order_total" do |event:, **|
+    puts "Resolved #{event.path}"
+  end
+end
+```
+
+## Introspection
+
+```ruby
+PriceContract.graph.to_text
+PriceContract.graph.to_mermaid
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+
+contract.result.states
+contract.result.explain(:gross_total)
+contract.execution.to_h
+contract.execution.as_json
+contract.result.as_json
+contract.events.map(&:as_json)
+contract.diagnostics.to_h
+contract.diagnostics_text
+contract.diagnostics_markdown
+contract.audit_snapshot
+```
+
+## v2 Design Docs
+
+- [Architecture v2](docs/ARCHITECTURE_V2.md)
+- [Execution Model v2](docs/EXECUTION_MODEL_V2.md)
+- [API Draft v2](docs/API_V2.md)
+- [Concepts and Principles](docs/IGNITER_CONCEPTS.md)
+
+## Direction
+
+The v2 rewrite is based on these rules:
+
+- model, compiler, runtime, DSL, and extensions are separate layers
+- graph validation happens before runtime
+- auditing and reactive behavior are extensions over events, not runtime internals
+- the first target is a deterministic synchronous kernel
+
+## Status
+
+The public Ruby surface in `lib/` now contains only the v2 core exposed from `require "igniter"`.
+
+## Development
+
+```bash
+rake spec
+```
+
+Current baseline:
+
+- synchronous runtime
+- compile-time graph validation
+- typed inputs
+- composition
+- auditing
+- diagnostics reporting
+- reactive subscriptions
+- graph/runtime introspection
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/API_V2.md

@@ -0,0 +1,242 @@
+# Igniter v2 API Draft
+
+## Public API Goals
+
+The public API should be:
+
+- small
+- explicit
+- inspectable
+- stable
+
+The user should understand Igniter through three concepts:
+
+- declare a contract
+- execute it with inputs
+- inspect outputs and events
+
+## Contract Shape
+
+Recommended public entry point:
+
+```ruby
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total
+    input :country
+
+    compute :vat_rate, depends_on: [:country], call: :resolve_vat_rate
+    compute :gross_total, depends_on: [:order_total, :vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+
+  def resolve_vat_rate(country:)
+    country == "UA" ? 0.2 : 0.0
+  end
+end
+```
+
+### Why `define`
+
+`define` clearly communicates compile-time declaration.
+
+It is preferable to a more ambiguous `context` name because the graph being created is a model definition, not a runtime scope.
+
+## Contract Runtime API
+
+```ruby
+contract = PriceContract.new(order_total: 100, country: "UA")
+
+contract.result.gross_total
+contract.result.to_h
+contract.success?
+contract.failed?
+
+contract.update_inputs(order_total: 120)
+contract.result.gross_total
+```
+
+Suggested instance methods:
+
+- `result`
+- `resolve`
+- `resolve_all`
+- `update_inputs`
+- `events`
+- `execution`
+- `diagnostics`
+- `success?`
+- `failed?`
+
+## Result API
+
+`Result` is a read facade over outputs and execution state.
+
+Suggested methods:
+
+- output readers by name
+- `to_h`
+- `as_json`
+- `success?`
+- `failed?`
+- `errors`
+- `states`
+- `explain`
+
+Avoid relying on `method_missing` as the main implementation mechanism if explicit generated readers are practical.
+
+## DSL Draft
+
+### Inputs
+
+```ruby
+input :order_total
+input :country
+```
+
+Optional later extension:
+
+```ruby
+input :order_total, type: :decimal, required: true
+```
+
+### Compute Nodes
+
+Block form:
+
+```ruby
+compute :gross_total, depends_on: [:order_total, :vat_rate] do |order_total:, vat_rate:|
+  order_total * (1 + vat_rate)
+end
+```
+
+Method form:
+
+```ruby
+compute :vat_rate, depends_on: [:country], call: :resolve_vat_rate
+```
+
+Rules:
+
+- one compute node has one callable
+- dependencies are explicit
+- runtime injects only declared dependencies
+
+### Outputs
+
+```ruby
+output :gross_total
+output :vat_rate
+```
+
+Optional alias form:
+
+```ruby
+output :total, from: :gross_total
+```
+
+### Composition
+
+```ruby
+compose :pricing, contract: PriceContract, inputs: {
+  order_total: :order_total,
+  country: :country
+}
+
+output :pricing, from: :pricing
+```
+
+Collection composition can be added later, but should not complicate the first kernel API.
+
+## Introspection API
+
+Recommended API:
+
+```ruby
+PriceContract.graph
+PriceContract.graph.to_h
+PriceContract.graph.to_mermaid
+
+contract.execution.states
+contract.execution.to_h
+contract.execution.as_json
+contract.result.as_json
+contract.events.map(&:as_json)
+contract.diagnostics.to_h
+contract.diagnostics.to_text
+contract.diagnostics.to_markdown
+```
+
+The main rule is that introspection reads stable compile/runtime objects rather than poking through private internals.
+
+## Events API
+
+Suggested access patterns:
+
+```ruby
+contract.events.each do |event|
+  puts "#{event.type} #{event.path}"
+end
+
+contract.events.map(&:to_h)
+contract.events.map(&:as_json)
+```
+
+Or:
+
+```ruby
+contract.subscribe(auditor)
+```
+
+Where a subscriber responds to:
+
+```ruby
+call(event)
+```
+
+## Errors API
+
+Suggested public behavior:
+
+```ruby
+begin
+  contract.result.gross_total
+rescue Igniter::ResolutionError => e
+  puts e.message
+end
+```
+
+Result-level inspection should still expose node failures without forcing exception-driven control flow for every error path.
+
+Each Igniter error also carries structured context when available:
+
+- `graph`
+- `node_id`
+- `node_name`
+- `node_path`
+- `source_location`
+
+## Roadmap API Decisions
+
+### Include in the first rewrite
+
+- `Igniter::Contract`
+- `define`
+- `input`
+- `compute`
+- `output`
+- `result`
+- `update_inputs`
+- `events`
+- graph introspection
+
+### Postpone
+
+- collection composition
+- advanced typed schemas
+- retries
+- async executors
+- Rails-specific DSL sugar