igniter 0.2.0 → 0.3.0

data/docs/BACKLOG.md

@@ -0,0 +1,166 @@
+# 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

@@ -0,0 +1,213 @@
+# 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/COLLECTIONS_V1.md

@@ -0,0 +1,303 @@
+# Collections v1
+
+## Goal
+
+`collection` introduces explicit fan-out over a list of homogeneous items as a graph primitive.
+
+The feature should make iteration:
+
+- declarative
+- visible in the graph model
+- visible in runtime diagnostics
+- compatible with future parallel and async execution
+
+It should avoid hiding loops inside generic `compute` blocks.
+
+## DSL
+
+### Basic form
+
+```ruby
+collection :technicians,
+  with: :technician_inputs,
+  each: TechnicianContract,
+  key: :technician_id,
+  mode: :collect
+```
+
+Where `technician_inputs` resolves to an array of hashes:
+
+```ruby
+[
+  { technician_id: 1 },
+  { technician_id: 2 }
+]
+```
+
+### Exporting item results
+
+```ruby
+output :technicians
+```
+
+This should return a dedicated collection result object.
+
+## Why the input should be item hashes
+
+For v1, the input to `collection` should already be normalized item inputs.
+
+Preferred:
+
+```ruby
+compute :technician_inputs, with: :technician_ids do |technician_ids:|
+  technician_ids.map { |id| { technician_id: id } }
+end
+```
+
+Then:
+
+```ruby
+collection :technicians,
+  with: :technician_inputs,
+  each: TechnicianContract,
+  key: :technician_id
+```
+
+This is preferable to implicit input mapping because:
+
+- the graph remains explicit
+- compile-time validation is simpler
+- schema-driven graph building is easier
+
+## Scope of v1
+
+Supported:
+
+- one dependency providing an array of item input hashes
+- child contract execution per item
+- stable key extraction
+- synchronous collection execution
+- explicit failure mode configuration
+
+Not supported in v1:
+
+- executor-based collections
+- nested async item execution
+- item-level `defer` semantics
+- schema inference from arbitrary item shapes
+- implicit item input mapping from primitives
+
+## Suggested DSL Options
+
+- `with:` selector for the collection input
+- `each:` child contract class
+- `key:` stable item identity
+- `mode:` failure behavior
+
+Example:
+
+```ruby
+collection :technicians,
+  with: :technician_inputs,
+  each: TechnicianContract,
+  key: :technician_id,
+  mode: :collect
+```
+
+## Runtime Semantics
+
+1. Resolve the collection input dependency.
+2. Expect an array of hashes.
+3. For each item:
+   - derive item key
+   - instantiate child contract with item hash
+   - resolve child contract
+4. Aggregate results according to `mode`
+
+## Stable Key
+
+`key:` should be required in v1.
+
+Why:
+
+- supports item identity in diagnostics
+- supports future invalidation and resume semantics
+- makes collection output easier to inspect
+
+Possible accepted forms:
+
+- symbol key:
+  ```ruby
+  key: :technician_id
+  ```
+- proc form can be a future extension
+
+For v1, symbol key is enough.
+
+## Failure Modes
+
+Collections need explicit failure semantics.
+
+Suggested v1 options:
+
+- `mode: :collect`
+  - run all items
+  - keep successes and failures
+  - collection node itself succeeds unless collection setup is invalid
+
+- `mode: :fail_fast`
+  - stop on first failed item
+  - collection node fails
+
+Recommended default for v1:
+
+- `:collect`
+
+This is more practical for real orchestration and more useful for diagnostics.
+
+## Result Shape
+
+Collections v1 should return a dedicated result object:
+
+- `Igniter::Runtime::CollectionResult`
+
+Suggested surface:
+
+- `items`
+- `keys`
+- `successes`
+- `failures`
+- `pending`
+- `to_h`
+- `as_json`
+
+Example conceptual shape:
+
+```ruby
+{
+  items: {
+    1 => { status: :succeeded, result: ... },
+    2 => { status: :failed, error: ... }
+  }
+}
+```
+
+Returning a plain array would be too weak for diagnostics and future runtime extensions.
+
+## Compile-Time Validation
+
+The compiler should validate:
+
+- `with:` points to a resolvable dependency
+- `each:` is an `Igniter::Contract` subclass
+- `key:` is present
+- child contract is compiled
+- if the source type is known, it is compatible with an array-like input
+
+## Runtime Validation
+
+At runtime, the collection should validate:
+
+- source value is an array
+- each item is a hash
+- the declared key exists in each item
+- keys are unique within the collection input
+
+These should raise structured runtime errors.
+
+## Events
+
+Collections should introduce collection-aware events in v1 or v2.
+
+Minimum useful event:
+
+- `collection_item_started`
+- `collection_item_succeeded`
+- `collection_item_failed`
+
+Each event should include:
+
+- collection node name
+- item key
+- child contract graph
+
+If this feels too heavy for v1, item information can first live only inside collection result and diagnostics.
+
+## Introspection
+
+### Graph
+
+Collection nodes should render distinctly from compute/composition/branch nodes.
+
+The graph should show:
+
+- source dependency
+- child contract
+- key
+- mode
+
+### Plan
+
+Before execution:
+
+- collection node is blocked on the source dependency
+
+After execution:
+
+- item count
+- item statuses
+
+### Diagnostics
+
+Diagnostics should surface:
+
+- collection size
+- per-item key
+- per-item status
+- per-item errors when present
+
+## Relation to Parallel Execution
+
+Collections are a natural fit for `thread_pool` execution.
+
+But v1 does not need to solve parallel execution immediately.
+
+Recommended rollout:
+
+1. synchronous collection primitive
+2. parallel runner support
+3. later async/pending/store support for items
+
+## Relation to Future Async
+
+Collections should be designed with future item-level async in mind:
+
+- stable keys
+- collection result object
+- explicit item states
+
+But v1 should stay synchronous.
+
+## Error Model
+
+Suggested runtime errors:
+
+- `Igniter::CollectionInputError`
+- `Igniter::CollectionKeyError`
+
+Potentially later:
+
+- `Igniter::CollectionItemError`
+
+## Future Extensions
+
+Possible later additions:
+
+- proc-based `key:`
+- `map_inputs:` from primitive arrays
+- item-level async
+- item-level retries
+- collection-level aggregation helpers
+- branch-aware collections
+
+These should not be part of v1.