igniter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9146f111caa1071ea7ba8ede536e39a00450193c60748a176ab2e6a0cb0fc15
-  data.tar.gz: 6f120c1d14c286dea458b58dbefbdd1d908a3eca77edad22fe933b145103639a
+  metadata.gz: 5cac7a900895eb96dbf1b12c619e8ff0ea0cb54557b8d605694710984b4baa37
+  data.tar.gz: 16b610374e8bbfaedeae1e01b57878e52ff2399ff4a566a62ff5926203ece4c5
 SHA512:
-  metadata.gz: d6de8e1d3228aaa17148abba206fe1185458ef316bd9a7153e3b02b460297bc7d838df47f6c3a95b266a56759bbc3aab3a2de0af68d0834005b863ae1a64f66a
-  data.tar.gz: 74f0b01d50f7d301c5519af7e54ce4042b02736321af2ae6d9beba3cb79dcbf1464e6ec59751668025cc0ad9012cce5a42ec36ee2fb1b46d23d43306e4366656
+  metadata.gz: 28cddf140914921cf31d05255122aeebcb892f5cae91daf27eb37ec4433be7e96b640a9c82175ef4e2995085cd036762d38963d275e4916b1ecbc5f9225cf18c
+  data.tar.gz: 2fbea23399d3d17d453ea83b9bf747a3a73d45eeb3cf01546d6e73e64c9354808414c7821c6dab28b070133a11d31440108aca3fe63a5a4ee0838407b207732c

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-19
+
+- Add executor metadata and global executor registry for self-describing, schema-friendly execution steps.
+- Split compiler validation into a pluggable validation pipeline and add shared type compatibility checks.
+- Introduce planner/runner runtime architecture with `:inline`, `:thread_pool`, and store-backed execution modes.
+- Add deferred nodes, pending state, snapshot/restore, token-based resume, worker-style resume flow, and reference file/ActiveRecord/Redis store adapters.
+- Expand the DSL with `with`, matcher-style `guard`, `scope`, `namespace`, `branch`, `collection`, `expose`, `on_failure`, and `on_exit`.
+- Add `branch` and `collection` as graph primitives with compile-time validation, nested runtime support, and item-level collection events.
+- Improve diagnostics and auditing with collection summaries, partial-failure visibility, item-level failure reporting, and richer markdown/text output.
+- Add production-like runnable examples for async resume, ergonomic domain contracts, collection partial failure, and nested branch + collection routing.
+- Add design docs for branches, collections, store adapters, and orchestration patterns.
+
 ## [0.2.0] - 2026-03-18
 
 - Complete the `arbor` to `igniter` rename across runtime, docs, examples, console setup, and shipped signatures.

data/README.md

@@ -9,7 +9,10 @@ Igniter is a Ruby gem for expressing business logic as a validated dependency gr
 - runtime auditing
 - diagnostics reports
 - reactive side effects
+- ergonomic DSL helpers (`with`, `const`, `lookup`, `map`, `guard`, `export`, `expose`, `effect`, `on_success`, `scope`, `namespace`, `branch`, `collection`)
 - graph and runtime introspection
+- async-capable pending nodes with snapshot/restore
+- store-backed execution resume flows
 
 The repository now contains a working v2 core built around explicit compile-time and runtime boundaries.
 
@@ -66,18 +69,25 @@ contract.diagnostics_text
 - 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.
+- Ergonomics: use compact DSL helpers for common lookup, transform, guard, export, and side-effect patterns.
 
 ## 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).
+There is also a short patterns guide in [`docs/PATTERNS.md`](docs/PATTERNS.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 |
+| `async_store.rb` | `ruby examples/async_store.rb` | pending execution, file-backed store, worker-style resume |
+| `marketing_ergonomics.rb` | `ruby examples/marketing_ergonomics.rb` | compact domain DSL with `with`, matcher-style `guard`, `scope`/`namespace`, `expose`, `on_success`, and `explain_plan` |
+| `collection.rb` | `ruby examples/collection.rb` | declarative fan-out, stable item keys, and `CollectionResult` |
+| `collection_partial_failure.rb` | `ruby examples/collection_partial_failure.rb` | `:collect` mode, partial failure summary, and collection diagnostics |
+| `ringcentral_routing.rb` | `ruby examples/ringcentral_routing.rb` | top-level `branch`, nested `collection`, per-item routing, and nested diagnostics semantics |
 
 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.
@@ -155,6 +165,195 @@ contract.execution.as_json
 contract.events.map(&:as_json)
 ```
 
+### 5. Async Store And Resume
+
+```ruby
+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
+
+contract = AsyncPricingContract.new(order_total: 100)
+deferred = contract.result.gross_total
+execution_id = contract.execution.events.execution_id
+
+resumed = AsyncPricingContract.resume_from_store(
+  execution_id,
+  token: deferred.token,
+  value: 150
+)
+
+resumed.result.gross_total
+# => 180.0
+```
+
+### 6. Ergonomic DSL
+
+```ruby
+class MarketingQuoteContract < Igniter::Contract
+  define do
+    input :service, type: :string
+    input :zip_code, type: :string
+
+    const :vendor_id, "eLocal"
+
+    scope :routing do
+      map :trade_name, from: :service do |service:|
+        %w[heating cooling ventilation air_conditioning].include?(service.downcase) ? "HVAC" : service
+      end
+    end
+
+    scope :pricing do
+      lookup :trade, with: :trade_name do |trade_name:|
+        { name: trade_name, base_bid: 45.0 }
+      end
+    end
+
+    namespace :validation do
+      guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
+    end
+
+    compute :quote, with: %i[vendor_id trade zip_supported zip_code] do |vendor_id:, trade:, zip_supported:, zip_code:|
+      zip_supported
+      { vendor_id: vendor_id, trade: trade[:name], zip_code: zip_code, bid: trade[:base_bid] }
+    end
+
+    expose :quote, as: :response
+  end
+
+  on_success :response do |value:, **|
+    puts "Persist #{value.inspect}"
+  end
+end
+
+contract = MarketingQuoteContract.new(service: "heating", zip_code: "60601")
+
+contract.explain_plan
+contract.result.response
+```
+
+You can also use matcher-style guards directly:
+
+```ruby
+guard :usa_only, with: :country_code, eq: "USA", message: "Unsupported country"
+guard :supported_country, with: :country_code, in: %w[USA CAN], message: "Unsupported country"
+guard :valid_zip, with: :zip_code, matches: /\A\d{5}\z/, message: "Invalid zip"
+```
+
+### 7. Declarative Branching
+
+```ruby
+class DeliveryContract < Igniter::Contract
+  define do
+    input :country
+    input :order_total
+
+    branch :delivery_strategy, with: :country, inputs: {
+      country: :country,
+      order_total: :order_total
+    } do
+      on "US", contract: USDeliveryContract
+      on "UA", contract: LocalDeliveryContract
+      default contract: DefaultDeliveryContract
+    end
+
+    export :price, :eta, from: :delivery_strategy
+  end
+end
+```
+
+### 8. Branch + Collection Routing
+
+```ruby
+class RingcentralWebhookContract < Igniter::Contract
+  define do
+    input :payload
+
+    scope :parse do
+      map :body, from: :payload do |payload:|
+        payload.fetch("body", {})
+      end
+
+      map :telephony_status, from: :body do |body:|
+        body["telephonyStatus"]
+      end
+
+      map :active_calls, from: :body do |body:|
+        body["activeCalls"] || []
+      end
+    end
+
+    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
+
+    export :routing_summary, from: :status_route
+  end
+end
+```
+
+In nested flows, diagnostics stay attached to the execution that actually owns the node:
+
+- the parent execution sees the top-level `branch_selected`
+- collection item events live on the selected child execution
+- collection summaries are easiest to read from the child contract diagnostics
+
+`branch` is a graph primitive for explicit routing. It selects one child contract from ordered cases and resolves only the chosen branch.
+
+### 8. Declarative Collections
+
+```ruby
+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
+```
+
+`collection` is a graph primitive for explicit fan-out. It runs one child contract per item hash and returns a `CollectionResult` keyed by stable item identity.
+
+In `mode: :collect`, a collection can succeed overall while still containing failed items. In that case:
+
+- `result.summary` gives collection-level status such as `:partial_failure`
+- `result.items_summary` gives compact per-item status
+- `result.failed_items` gives only failed item details
+- `contract.diagnostics_text` and `contract.diagnostics_markdown` include collection failure summaries
+
+See `examples/collection_partial_failure.rb` for a runnable example.
+
 ## Composition Example
 
 ```ruby
@@ -195,7 +394,22 @@ class NotifyingContract < Igniter::Contract
     output :order_total
   end
 
-  react_to :node_succeeded, path: "order_total" do |event:, **|
+  on_success :order_total do |value:, **|
+    puts "Resolved #{value}"
+  end
+end
+```
+
+Or attach directly to a node event when you want the node value:
+
+```ruby
+class NotifyingContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    output :order_total
+  end
+
+  effect "order_total" do |event:, value:, **|
     puts "Resolved #{event.path}"
   end
 end
@@ -212,6 +426,7 @@ contract.result.gross_total
 
 contract.result.states
 contract.result.explain(:gross_total)
+contract.explain_plan
 contract.execution.to_h
 contract.execution.as_json
 contract.result.as_json
@@ -227,6 +442,10 @@ contract.audit_snapshot
 - [Architecture v2](docs/ARCHITECTURE_V2.md)
 - [Execution Model v2](docs/EXECUTION_MODEL_V2.md)
 - [API Draft v2](docs/API_V2.md)
+- [Patterns](docs/PATTERNS.md)
+- [Branches v1](docs/BRANCHES_V1.md)
+- [Collections v1](docs/COLLECTIONS_V1.md)
+- [Store Adapters](docs/STORE_ADAPTERS.md)
 - [Concepts and Principles](docs/IGNITER_CONCEPTS.md)
 
 ## Direction
@@ -251,6 +470,10 @@ rake spec
 Current baseline:
 
 - synchronous runtime
+- parallel thread-pool runner
+- pending/deferred runtime states
+- snapshot/restore execution lifecycle
+- store-backed resume flow
 - compile-time graph validation
 - typed inputs
 - composition

data/docs/API_V2.md

@@ -54,6 +54,7 @@ contract.result.gross_total
 contract.result.to_h
 contract.success?
 contract.failed?
+contract.pending?
 
 contract.update_inputs(order_total: 120)
 contract.result.gross_total
@@ -67,9 +68,11 @@ Suggested instance methods:
 - `update_inputs`
 - `events`
 - `execution`
+- `explain_plan`
 - `diagnostics`
 - `success?`
 - `failed?`
+- `pending?`
 
 ## Result API
 
@@ -82,6 +85,7 @@ Suggested methods:
 - `as_json`
 - `success?`
 - `failed?`
+- `pending?`
 - `errors`
 - `states`
 - `explain`
@@ -119,6 +123,75 @@ Method form:
 compute :vat_rate, depends_on: [:country], call: :resolve_vat_rate
 ```
 
+Executor registry form:
+
+```ruby
+Igniter.register_executor("pricing.multiply", MultiplyExecutor)
+
+compute :gross_total,
+        depends_on: %i[order_total multiplier],
+        executor: "pricing.multiply"
+```
+
+Ergonomic helper forms:
+
+```ruby
+const :vendor_id, "eLocal"
+
+lookup :trade, depends_on: [:trade_name] do |trade_name:|
+  Trade.enabled.find_by!(name: trade_name)
+end
+
+map :normalized_trade_name, from: :service do |service:|
+  service.downcase == "heating" ? "HVAC" : service
+end
+
+guard :business_hours_valid, depends_on: %i[vendor current_time], message: "Closed" do |vendor:, current_time:|
+  current_time.between?(vendor.start_at, vendor.stop_at)
+end
+
+expose :bid_details, as: :response
+```
+
+Short dependency alias:
+
+```ruby
+compute :zip_code, with: :zip_code_raw do |zip_code_raw:|
+  ZipCode.find_by_code!(zip_code_raw)
+end
+```
+
+Matcher-style guards:
+
+```ruby
+guard :usa_only, with: :country_code, eq: "USA", message: "Unsupported country"
+guard :supported_country, with: :country_code, in: %w[USA CAN], message: "Unsupported country"
+guard :valid_zip, with: :zip_code, matches: /\A\d{5}\z/, message: "Invalid zip"
+```
+
+Declarative routing:
+
+```ruby
+branch :delivery_strategy, with: :country, inputs: {
+  country: :country,
+  order_total: :order_total
+} do
+  on "US", contract: USDeliveryContract
+  on "UA", contract: LocalDeliveryContract
+  default contract: DefaultDeliveryContract
+end
+```
+
+Declarative fan-out:
+
+```ruby
+collection :technicians,
+  with: :technician_inputs,
+  each: TechnicianContract,
+  key: :technician_id,
+  mode: :collect
+```
+
 Rules:
 
 - one compute node has one callable
@@ -149,6 +222,99 @@ compose :pricing, contract: PriceContract, inputs: {
 output :pricing, from: :pricing
 ```
 
+Child output export:
+
+```ruby
+output :gross_total, from: "pricing.gross_total"
+```
+
+Bulk child output export:
+
+```ruby
+export :gross_total, :vat_rate, from: :pricing
+```
+
+Branch output export:
+
+```ruby
+export :price, :eta, from: :delivery_strategy
+```
+
+Collection output:
+
+```ruby
+output :technicians
+```
+
+This returns a `CollectionResult` rather than a plain array.
+
+Suggested `CollectionResult` surface:
+
+- `keys`
+- `successes`
+- `failures`
+- `summary`
+- `items_summary`
+- `failed_items`
+- `to_h`
+- `as_json`
+
+Nested routing and fan-out can be combined:
+
+```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
+```
+
+Inside the selected branch contract:
+
+```ruby
+collection :calls,
+  with: :call_inputs,
+  each: CallEventContract,
+  key: :session_id,
+  mode: :collect
+```
+
+Diagnostics and audit stay local to the execution that owns the node:
+
+- the parent execution records top-level branch selection
+- collection item events belong to the selected child execution
+- collection summaries should usually be read from the child contract diagnostics
+
+Pass-through or aliased output exposure:
+
+```ruby
+expose :bid_details, as: :response
+expose :gross_total
+```
+
+Grouped node paths:
+
+```ruby
+scope :availability do
+  lookup :vendor, with: %i[trade vendor_id], call: LookupVendor
+  lookup :zip_code, with: :zip_code_raw, call: LookupZipCode
+  compute :geo_bids, with: %i[zip_code vendor], call: LookupGeoBids
+end
+
+namespace :validation do
+  guard :valid_zip, with: :zip_code, matches: /\A\d{5}\z/, message: "Invalid zip"
+end
+```
+
+`scope` and `namespace` currently improve structure and introspection by prefixing node paths.
+They do not yet introduce a separate runtime boundary.
+
+Branch nodes introduce explicit control flow and behave like composition-like nested results.
+
 Collection composition can be added later, but should not complicate the first kernel API.
 
 ## Introspection API
@@ -161,6 +327,8 @@ PriceContract.graph.to_h
 PriceContract.graph.to_mermaid
 
 contract.execution.states
+contract.execution.plan
+contract.explain_plan
 contract.execution.to_h
 contract.execution.as_json
 contract.result.as_json
@@ -168,6 +336,7 @@ contract.events.map(&:as_json)
 contract.diagnostics.to_h
 contract.diagnostics.to_text
 contract.diagnostics.to_markdown
+contract.snapshot
 ```
 
 The main rule is that introspection reads stable compile/runtime objects rather than poking through private internals.
@@ -191,6 +360,66 @@ Or:
 contract.subscribe(auditor)
 ```
 
+Reactive side-effect shorthand:
+
+```ruby
+class LoggingContract < Igniter::Contract
+  define do
+    input :order_total
+    output :order_total
+  end
+
+  effect "order_total" do |event:, value:, **|
+    AuditLog.create!(path: event.path, value: value)
+  end
+end
+```
+
+Final-output success shorthand:
+
+```ruby
+class PersistingContract < Igniter::Contract
+  define do
+    input :order_total
+    compute :gross_total, depends_on: [:order_total] do |order_total:|
+      order_total * 1.2
+    end
+    expose :gross_total, as: :response
+  end
+
+  on_success :response do |value:, contract:, **|
+    AuditLog.create!(response: value, inputs: contract.execution.inputs)
+  end
+end
+```
+
+Async/store-backed flow:
+
+```ruby
+contract = AsyncPricingContract.new(order_total: 100)
+deferred = contract.result.gross_total
+
+AsyncPricingContract.resume_from_store(
+  contract.execution.events.execution_id,
+  token: deferred.token,
+  value: 150
+)
+```
+
+Reference store adapters:
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
+  record_class: IgniterExecutionSnapshot
+)
+```
+
+```ruby
+Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
+  redis: Redis.new(url: ENV.fetch("REDIS_URL"))
+)
+```
+
 Where a subscriber responds to:
 
 ```ruby
@@ -238,5 +467,13 @@ Each Igniter error also carries structured context when available:
 - collection composition
 - advanced typed schemas
 - retries
-- async executors
 - Rails-specific DSL sugar
+
+### Now Present In v2 Core
+
+- executor registry
+- schema-driven graph compilation
+- thread-pool runner
+- deferred/pending executor protocol
+- execution snapshot/restore
+- store-backed resume flow