igniter 0.5.0 → 0.5.2

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.

data/docs/CAPABILITIES_V1.md

@@ -1,207 +0,0 @@
-# Capability-Based Security — v1
-
-Capabilities let executors declare what external resources they need, and let operators
-enforce policies that deny specific capabilities at runtime. This makes the security surface
-of every graph visible and auditable at a glance.
-
-## Quick Start
-
-```ruby
-require "igniter/capabilities"
-
-# 1. Declare capabilities on executors
-class DatabaseLookup < Igniter::Executor
-  capabilities :database
-
-  def call(id:)
-    DB.find(id)
-  end
-end
-
-class PureCalculator < Igniter::Executor
-  pure  # shorthand for capabilities(:pure)
-
-  def call(x:, y:)
-    x + y
-  end
-end
-
-# 2. Enforce a policy
-policy = Igniter::Capabilities::Policy.new(denied: [:database])
-Igniter::Capabilities.policy = policy
-
-# 3. Execution raises CapabilityViolationError for denied nodes
-class MyContract < Igniter::Contract
-  define do
-    input :id
-    compute :record, depends_on: :id, call: DatabaseLookup
-    output :record
-  end
-end
-
-MyContract.new(id: 42).resolve_all
-# => Igniter::Capabilities::CapabilityViolationError:
-#    Node 'record' executor DatabaseLookup uses denied capabilities: database
-```
-
-## Executor DSL
-
-### `capabilities(*caps)`
-
-Declare one or more capabilities required by the executor.
-
-```ruby
-class EmailSender < Igniter::Executor
-  capabilities :network, :external_api
-
-  def call(to:, body:)
-    Mailer.send(to: to, body: body)
-  end
-end
-```
-
-### `pure`
-
-Shorthand for `capabilities(:pure)`. Marks the executor as having no side effects — its
-output is fully determined by its inputs. `pure` executors participate in
-[content-addressed caching](CONTENT_ADDRESSING_V1.md).
-
-```ruby
-class TaxCalculator < Igniter::Executor
-  pure
-
-  def call(amount:, rate:)
-    amount * rate
-  end
-end
-```
-
-### `pure?`
-
-Returns `true` if the executor declares the `:pure` capability.
-
-```ruby
-TaxCalculator.pure?  # => true
-```
-
-### Accessing declared capabilities
-
-```ruby
-EmailSender.declared_capabilities  # => [:network, :external_api]
-TaxCalculator.declared_capabilities  # => [:pure]
-```
-
-## Known Capabilities
-
-| Symbol | Meaning |
-|--------|---------|
-| `:pure` | No side effects; output determined by inputs only |
-| `:network` | Makes outbound TCP/HTTP connections |
-| `:database` | Reads or writes a database |
-| `:filesystem` | Reads or writes the local filesystem |
-| `:external_api` | Calls a third-party API |
-| `:messaging` | Publishes to a message queue or event stream |
-| `:queue` | Reads from a job or task queue |
-| `:cache` | Reads or writes a distributed cache |
-
-You can also use any custom symbol — the system does not restrict you to this list.
-
-## Policy Enforcement
-
-### `Igniter::Capabilities::Policy`
-
-```ruby
-policy = Igniter::Capabilities::Policy.new(denied: [:network, :filesystem])
-Igniter::Capabilities.policy = policy
-```
-
-Setting the policy to `nil` disables all capability checks:
-
-```ruby
-Igniter::Capabilities.policy = nil  # no-op, all executors run freely
-```
-
-The policy is global (process-wide). It is typically set at boot time.
-
-### `CapabilityViolationError`
-
-Raised by the resolver at the start of `resolve_compute` before the executor is invoked.
-The error includes the node name and the violated capabilities in its message:
-
-```ruby
-begin
-  contract.resolve_all
-rescue Igniter::Capabilities::CapabilityViolationError => e
-  puts e.message
-  # => "Node 'fetch_data' executor DataFetcher uses denied capabilities: network"
-end
-```
-
-## Graph Introspection
-
-After `require "igniter/extensions/capabilities"` (or `require "igniter/capabilities"`) the
-compiled graph gains two introspection methods:
-
-### `required_capabilities`
-
-Returns a Hash of `{ node_name => [capabilities] }` for every node whose executor
-declares at least one capability.
-
-```ruby
-require "igniter/capabilities"
-
-class MyContract < Igniter::Contract
-  define do
-    input :id
-    compute :record,   depends_on: :id, call: DatabaseLookup
-    compute :total,    depends_on: :record, call: PureCalculator
-    output :total
-  end
-end
-
-MyContract.compiled_graph.required_capabilities
-# => { record: [:database], total: [:pure] }
-```
-
-### `capabilities_for(node_name)`
-
-Returns the declared capabilities of a single node as an array.
-
-```ruby
-MyContract.compiled_graph.capabilities_for(:record)
-# => [:database]
-
-MyContract.compiled_graph.capabilities_for(:total)
-# => [:pure]
-
-MyContract.compiled_graph.capabilities_for(:id)
-# => []  (input nodes have no executor)
-```
-
-## Environment-Based Policy Pattern
-
-A common pattern is to load the policy from environment configuration so that the
-same codebase enforces different rules in development vs. production:
-
-```ruby
-# config/igniter.rb
-DENIED_CAPS = case ENV["RAILS_ENV"]
-              when "test"       then %i[network database filesystem]
-              when "production" then []
-              else                   []
-              end
-
-Igniter::Capabilities.policy = Igniter::Capabilities::Policy.new(denied: DENIED_CAPS)
-```
-
-This lets your test suite run without real I/O while production executions are unrestricted.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `lib/igniter/capabilities.rb` | `Capabilities` module, `Policy` class, `CapabilityViolationError` |
-| `lib/igniter/extensions/capabilities.rb` | Patches `CompiledGraph` with `required_capabilities` / `capabilities_for` |
-| `lib/igniter/executor.rb` | `capabilities`, `pure`, `pure?`, `declared_capabilities`, `fingerprint` DSL |
-| `lib/igniter/runtime/resolver.rb` | `check_capability_policy!` guard in `resolve_compute` |
-| `spec/igniter/capabilities_spec.rb` | 16 examples |