igniter 0.2.0 → 0.3.0

data/docs/EXECUTION_MODEL_V2.md

@@ -162,6 +162,8 @@ Canonical kernel events:
 - `node_started`
 - `node_succeeded`
 - `node_failed`
+- `node_pending`
+- `node_resumed`
 - `node_invalidated`
 
 Suggested event fields:
@@ -181,6 +183,7 @@ 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
 
@@ -215,6 +218,80 @@ Reasons:
 
 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:
@@ -227,6 +304,8 @@ These invariants should be enforced by tests:
 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
 

data/docs/PATTERNS.md

@@ -0,0 +1,222 @@
+# Igniter Patterns
+
+This document collects recommended orchestration shapes that already have runnable examples in the repository.
+
+The goal is not to introduce new primitives, but to show how the existing DSL composes into readable contracts.
+
+## 1. Linear Derivation
+
+Use this when the flow is a straight dependency chain with no routing or fan-out.
+
+Example:
+
+- [basic_pricing.rb](/Users/alex/dev/hotfix/igniter/examples/basic_pricing.rb)
+
+Use:
+
+- pricing
+- totals
+- normalization pipelines
+- simple business formulas
+
+Shape:
+
+```ruby
+input :order_total
+input :country
+
+compute :vat_rate, with: :country do |country:|
+  country == "UA" ? 0.2 : 0.0
+end
+
+compute :gross_total, with: %i[order_total vat_rate] do |order_total:, vat_rate:|
+  order_total * (1 + vat_rate)
+end
+
+output :gross_total
+```
+
+## 2. Stage Composition
+
+Use this when one contract should orchestrate several bounded subgraphs.
+
+Examples:
+
+- [composition.rb](/Users/alex/dev/hotfix/igniter/examples/composition.rb)
+- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
+
+Use:
+
+- reusable business stages
+- transport shell + domain pipeline
+- larger flows with clear internal boundaries
+
+Guideline:
+
+- keep the parent contract thin
+- export child outputs explicitly
+- read child diagnostics from the child execution, not from the parent by default
+
+## 3. Scoped Domain Flow
+
+Use this when the graph is still one contract, but a flat node list becomes hard to read.
+
+Example:
+
+- [marketing_ergonomics.rb](/Users/alex/dev/hotfix/igniter/examples/marketing_ergonomics.rb)
+
+Use:
+
+- routing
+- validation
+- pricing
+- response shaping
+
+Shape:
+
+```ruby
+scope :routing do
+  map :trade_name, from: :service do |service:|
+    ...
+  end
+end
+
+namespace :validation do
+  guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
+end
+```
+
+Guideline:
+
+- use `scope` and `namespace` for readability first
+- do not treat them as runtime boundaries
+
+## 4. Declarative Routing
+
+Use this when control flow depends on a selector value and should stay visible in the graph.
+
+Examples:
+
+- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
+
+Use:
+
+- vendor routing
+- status routing
+- country-specific flows
+- mode-specific processing
+
+Shape:
+
+```ruby
+branch :status_route, with: :telephony_status, inputs: {
+  extension_id: :extension_id,
+  telephony_status: :telephony_status,
+  active_calls: :active_calls
+} do
+  on "CallConnected", contract: CallConnectedContract
+  on "NoCall", contract: NoCallContract
+  default contract: UnknownStatusContract
+end
+```
+
+Guideline:
+
+- keep branch contracts on a shared input interface
+- let compile-time validation force interface consistency
+- use explicit `export` from the branch node
+
+## 5. Fan-Out With Stable Identity
+
+Use this when a node should run the same child contract for many item inputs.
+
+Examples:
+
+- [collection.rb](/Users/alex/dev/hotfix/igniter/examples/collection.rb)
+- [collection_partial_failure.rb](/Users/alex/dev/hotfix/igniter/examples/collection_partial_failure.rb)
+- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
+
+Use:
+
+- technicians
+- calls
+- locations
+- vendors
+- external records
+
+Shape:
+
+```ruby
+collection :technicians,
+  with: :technician_inputs,
+  each: TechnicianContract,
+  key: :technician_id,
+  mode: :collect
+```
+
+Guideline:
+
+- feed `collection` an array of item input hashes
+- choose a stable `key:`
+- keep item logic in the child contract, not in a giant parent `compute`
+
+## 6. Partial Failure Without Failing The Whole Execution
+
+Use `mode: :collect` when you want item-level failures surfaced, but not promoted to parent execution failure.
+
+Example:
+
+- [collection_partial_failure.rb](/Users/alex/dev/hotfix/igniter/examples/collection_partial_failure.rb)
+
+What to read:
+
+- `result.summary`
+- `result.items_summary`
+- `result.failed_items`
+- `contract.diagnostics_text`
+- `contract.diagnostics_markdown`
+
+Guideline:
+
+- parent execution can still be `succeeded`
+- collection summary may be `:partial_failure`
+- diagnostics should be read at collection level, not only at execution status level
+
+## 7. Nested Branch + Collection
+
+Use this when routing chooses a stage, and that stage performs fan-out or per-item routing.
+
+Example:
+
+- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
+
+Observed semantics:
+
+- parent execution records top-level `branch_selected`
+- collection item events belong to the selected child execution
+- child diagnostics is usually the best place to inspect collection status
+
+Guideline:
+
+- inspect parent audit for high-level routing
+- inspect child audit for item-level fan-out behavior
+
+## 8. Async Resume Flow
+
+Use this when a node cannot complete immediately and should suspend the execution.
+
+Example:
+
+- [async_store.rb](/Users/alex/dev/hotfix/igniter/examples/async_store.rb)
+
+Use:
+
+- external jobs
+- long-running enrichment
+- async pricing or classification
+
+Guideline:
+
+- model the slow step as a deferred node
+- resume with store-backed execution restore
+- keep downstream graph pure and resumable

data/docs/STORE_ADAPTERS.md

@@ -0,0 +1,126 @@
+# Store Adapters
+
+Igniter ships with reference execution stores for:
+
+- memory
+- file
+- ActiveRecord-style persistence
+- Redis-style persistence
+
+All stores implement the same minimal protocol:
+
+- `save(snapshot)`
+- `fetch(execution_id)`
+- `delete(execution_id)`
+- `exist?(execution_id)`
+
+## Memory Store
+
+Useful for tests and single-process flows.
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::MemoryStore.new
+```
+
+## File Store
+
+Useful for local development and smoke-testing worker flows.
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(
+  root: Rails.root.join("tmp/igniter_executions")
+)
+```
+
+## ActiveRecord Store
+
+Expected record shape:
+
+- one unique `execution_id` column
+- one text/json column for serialized snapshot payload
+
+Example model:
+
+```ruby
+class IgniterExecutionSnapshot < ApplicationRecord
+  validates :execution_id, presence: true, uniqueness: true
+end
+```
+
+Example migration:
+
+```ruby
+class CreateIgniterExecutionSnapshots < ActiveRecord::Migration[7.1]
+  def change
+    create_table :igniter_execution_snapshots do |t|
+      t.string :execution_id, null: false
+      t.jsonb :snapshot_json, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :igniter_execution_snapshots, :execution_id, unique: true
+  end
+end
+```
+
+Store configuration:
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
+  record_class: IgniterExecutionSnapshot,
+  execution_id_column: :execution_id,
+  snapshot_column: :snapshot_json
+)
+```
+
+## Redis Store
+
+Expected client protocol:
+
+- `set(key, value)`
+- `get(key)`
+- `del(key)`
+- `exists?(key)`
+
+Example configuration:
+
+```ruby
+redis = Redis.new(url: ENV.fetch("REDIS_URL"))
+
+Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
+  redis: redis,
+  namespace: "igniter:executions"
+)
+```
+
+## Worker Flow
+
+Store-backed contracts should declare:
+
+```ruby
+class AsyncPricingContract < Igniter::Contract
+  run_with runner: :store
+end
+```
+
+Producer side:
+
+```ruby
+contract = AsyncPricingContract.new(order_total: 100)
+deferred = contract.result.gross_total
+
+execution_id = contract.execution.events.execution_id
+token = deferred.token
+```
+
+Worker side:
+
+```ruby
+AsyncPricingContract.resume_from_store(
+  execution_id,
+  token: token,
+  value: 150
+)
+```
+
+If the resumed execution finishes successfully, the current `StoreRunner` deletes the persisted snapshot automatically.

data/examples/README.md

@@ -2,6 +2,7 @@
 
 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`.
+For higher-level guidance on when to use each style, see [PATTERNS.md](/Users/alex/dev/hotfix/igniter/docs/PATTERNS.md).
 
 ## Available Scripts
 
@@ -72,6 +73,129 @@ Outputs: gross_total=120.0
 {:graph=>"PriceContract", ...}
 ```
 
+### `async_store.rb`
+
+Run:
+
+```bash
+ruby examples/async_store.rb
+```
+
+Shows:
+
+- deferred executor output through `defer`
+- file-backed pending execution store
+- restore and resume flow through `resume_from_store`
+
+Expected output shape:
+
+```text
+pending_token=quote-100
+stored_execution_id=<uuid>
+pending_status=true
+resumed_gross_total=180.0
+```
+
+### `marketing_ergonomics.rb`
+
+Run:
+
+```bash
+ruby examples/marketing_ergonomics.rb
+```
+
+Shows:
+
+- ergonomic helpers `with`, `const`, `lookup`, `map`, matcher-style `guard`, `expose`
+- success-side-effect shorthand via `on_success`
+- structural grouping via `scope` and `namespace`
+- pre-execution planning via `contract.explain_plan`
+- a domain-style contract that stays compact without hiding the graph
+
+Expected output shape:
+
+```text
+Plan MarketingQuoteContract
+Targets: quote
+...
+---
+response={:vendor_id=>"eLocal", :trade=>"HVAC", :zip_code=>"60601", :bid=>45.0}
+outbox=[{:vendor_id=>"eLocal", :zip_code=>"60601"}]
+```
+
+### `collection.rb`
+
+Run:
+
+```bash
+ruby examples/collection.rb
+```
+
+Shows:
+
+- declarative fan-out via `collection`
+- stable item identity via `key:`
+- `CollectionResult` output surface
+- per-item child contract results in `:collect` mode
+
+Expected output shape:
+
+```text
+keys=[1, 2]
+items={1=>{:key=>1, :status=>:succeeded, ...}, 2=>{:key=>2, :status=>:succeeded, ...}}
+```
+
+### `collection_partial_failure.rb`
+
+Run:
+
+```bash
+ruby examples/collection_partial_failure.rb
+```
+
+Shows:
+
+- `collection` in `mode: :collect`
+- `CollectionResult#summary`
+- `CollectionResult#items_summary`
+- `CollectionResult#failed_items`
+- diagnostics output for partial collection failure without failing the whole execution
+
+Expected output shape:
+
+```text
+summary={:mode=>:collect, :total=>3, :succeeded=>2, :failed=>1, :status=>:partial_failure}
+items_summary={1=>{:status=>:succeeded}, 2=>{:status=>:failed, ...}, ...}
+failed_items={2=>{:type=>"Igniter::ResolutionError", ...}}
+```
+
+### `ringcentral_routing.rb`
+
+Run:
+
+```bash
+ruby examples/ringcentral_routing.rb
+```
+
+Shows:
+
+- top-level routing via `branch`
+- nested fan-out via `collection`
+- per-item nested routing via another `branch`
+- `CollectionResult` summary on the selected child contract
+- the practical boundary between parent diagnostics and child diagnostics
+
+Expected output shape:
+
+```text
+Plan RingcentralWebhookContract
+...
+---
+routing_summary={:extension_id=>62872332031, ...}
+status_route_branch=CallConnected
+child_collection_summary={:mode=>:collect, :total=>3, ...}
+```
+
 ## 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.

data/examples/async_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "tmpdir"
+
+class AsyncQuoteExecutor < Igniter::Executor
+  input :order_total, type: :numeric
+
+  def call(order_total:)
+    defer(token: "quote-#{order_total}", payload: { kind: "pricing_quote" })
+  end
+end
+
+class AsyncPricingContract < Igniter::Contract
+  run_with runner: :store
+
+  define do
+    input :order_total, type: :numeric
+
+    compute :quote_total, depends_on: [:order_total], call: AsyncQuoteExecutor
+
+    compute :gross_total, depends_on: [:quote_total] do |quote_total:|
+      quote_total * 1.2
+    end
+
+    output :gross_total
+  end
+end
+
+Dir.mktmpdir("igniter-example-store") do |dir|
+  original_store = Igniter.execution_store
+  Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(root: dir)
+
+  contract = AsyncPricingContract.new(order_total: 100)
+  deferred = contract.result.gross_total
+  execution_id = contract.execution.events.execution_id
+
+  puts "pending_token=#{deferred.token}"
+  puts "stored_execution_id=#{execution_id}"
+  puts "pending_status=#{contract.result.pending?}"
+
+  resumed = AsyncPricingContract.resume_from_store(execution_id, token: deferred.token, value: 150)
+  puts "resumed_gross_total=#{resumed.result.gross_total}"
+ensure
+  Igniter.execution_store = original_store
+end

data/examples/collection.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+
+class TechnicianContract < Igniter::Contract
+  define do
+    input :technician_id
+    input :name
+
+    compute :summary, with: %i[technician_id name] do |technician_id:, name:|
+      { id: technician_id, name: name }
+    end
+
+    output :summary
+  end
+end
+
+class TechnicianBatchContract < Igniter::Contract
+  define do
+    input :technician_inputs, type: :array
+
+    collection :technicians,
+      with: :technician_inputs,
+      each: TechnicianContract,
+      key: :technician_id,
+      mode: :collect
+
+    output :technicians
+  end
+end
+
+contract = TechnicianBatchContract.new(
+  technician_inputs: [
+    { technician_id: 1, name: "Anna" },
+    { technician_id: 2, name: "Mike" }
+  ]
+)
+
+result = contract.result.technicians
+
+puts "keys=#{result.keys.inspect}"
+puts "items=#{result.to_h.inspect}"