igniter 0.4.3 → 0.5.0

data/docs/NODE_CACHE_V1.md

@@ -0,0 +1,324 @@
+# Node Cache — v1
+
+Cross-execution TTL cache and in-flight request coalescing for compute nodes.
+
+Activate per-node via `cache_ttl:` and `coalesce:` options on `compute`:
+
+```ruby
+compute :available_slots,
+        with:       [:vendor, :locations, :availability_mode, :current_time],
+        call:       CheckAvailability,
+        cache_ttl:  60,     # reuse result for 60 seconds across executions
+        coalesce:   true    # deduplicate concurrent in-flight requests
+```
+
+Both features are opt-in, zero-overhead for unconfigured nodes, and work independently.
+
+---
+
+## Quick Start
+
+```ruby
+require "igniter/node_cache"
+
+# In-process memory backend (single Ruby process / single Puma worker)
+Igniter.configure do |c|
+  c.node_cache     = Igniter::NodeCache::Memory.new
+  c.node_coalescing = true   # auto-creates a CoalescingLock
+end
+```
+
+Or explicitly:
+
+```ruby
+Igniter::NodeCache.cache           = Igniter::NodeCache::Memory.new
+Igniter::NodeCache.coalescing_lock = Igniter::NodeCache::CoalescingLock.new
+```
+
+---
+
+## Feature 1 — TTL Cache (`cache_ttl:`)
+
+Stores the result of a compute node in a shared cache keyed by:
+
+```
+"ttl:{ContractName}:{node_name}:{dep_fingerprint_hex}"
+```
+
+On the next execution, if the deps haven't changed and the TTL hasn't expired, the cached
+value is returned immediately — the executor is never called.
+
+### Usage
+
+```ruby
+class AvailabilityContract < Igniter::Contract
+  runner :thread_pool, pool_size: 4
+
+  define do
+    input  :vendor_id
+    input  :zip_code
+
+    compute :vendor,
+            with: :vendor_id,
+            call: FindVendor
+
+    compute :available_slots,
+            with:      [:vendor, :zip_code],
+            call:      CheckAvailability,
+            cache_ttl: 60    # cache for 60 seconds
+    output :available_slots
+  end
+end
+```
+
+### Cache Key
+
+The cache key is a 24-hex SHA-256 digest of the serialized dependency values:
+
+```ruby
+dep_hex = Igniter::NodeCache::Fingerprinter.call({ vendor: vendor_obj, zip_code: "10001" })
+key     = Igniter::NodeCache::CacheKey.new("AvailabilityContract", :available_slots, dep_hex)
+key.hex # => "ttl:AvailabilityContract:available_slots:4a9f1c0e23ab7d88e4c2"
+```
+
+For stable cross-execution keys, dependency objects should implement `#igniter_fingerprint`
+(see [AR Fingerprinting](#ar-fingerprinting) below).
+
+### Runtime Event
+
+When a cached value is returned the resolver emits `:node_ttl_cache_hit`:
+
+```ruby
+contract.execution.events.events.select { |e| e.type == :node_ttl_cache_hit }
+# => [#<Event type=:node_ttl_cache_hit node=:available_slots ...>]
+```
+
+### Memory Backend
+
+`NodeCache::Memory` is a thread-safe in-process store:
+
+```ruby
+cache = Igniter::NodeCache::Memory.new
+cache.stats    # => { size: 4, hits: 11, misses: 3 }
+cache.size     # => 4
+cache.prune!   # removes expired entries (call periodically to reclaim memory)
+cache.clear    # removes all entries and resets counters
+```
+
+Entries are automatically expired on `fetch` — no background thread needed.
+
+### Custom / Redis Backend
+
+Replace `Memory` with any object implementing `#fetch(key)` and `#store(key, value, ttl:)`:
+
+```ruby
+class RedisNodeCache
+  def initialize(redis)
+    @redis = redis
+  end
+
+  def fetch(key)
+    raw = @redis.get(key.hex)
+    raw ? Marshal.load(raw) : nil
+  end
+
+  def store(key, value, ttl:)
+    @redis.setex(key.hex, ttl.to_i, Marshal.dump(value))
+    value
+  end
+end
+
+Igniter::NodeCache.cache = RedisNodeCache.new(Redis.new)
+```
+
+A Redis-backed cache shares results across Puma workers and multiple server instances.
+
+---
+
+## Feature 2 — Request Coalescing (`coalesce: true`)
+
+When two (or more) executions race to compute the same `coalesce: true` node with
+identical dependency values, only one actually runs — the **leader**. The others become
+**followers** and wait for the leader's result.
+
+This eliminates redundant work in auction / multi-vendor scenarios where N vendors submit
+requests for the same lead within milliseconds of each other.
+
+### Usage
+
+```ruby
+compute :available_slots,
+        with:     [:vendor, :locations],
+        call:     CheckAvailability,
+        cache_ttl: 60,
+        coalesce:  true   # concurrent requests with same deps share one computation
+```
+
+`coalesce: true` requires `cache_ttl:` to be set (the completed result is stored in the
+TTL cache so followers can retrieve it) and `NodeCache.coalescing_lock` to be configured.
+
+### Leader / Follower Flow
+
+```
+Thread A (leader)                Thread B (follower)
+────────────────                 ─────────────────────
+acquire(:hex) → :leader          acquire(:hex) → :follower
+call CheckAvailability           wait(flight) ← blocks
+finish!(:hex, value: result)  →  unblocked, gets result
+```
+
+If the leader raises an error, `finish!` is called with `error:` — all followers receive
+the error and raise it themselves. A follower that times out (30 s) recomputes independently.
+
+### CoalescingLock API
+
+```ruby
+lock = Igniter::NodeCache::CoalescingLock.new
+
+role, flight = lock.acquire(hex)      # → [:leader, flight] or [:follower, flight]
+lock.finish!(hex, value: result)      # called by leader on success
+lock.finish!(hex, error: exception)   # called by leader on failure
+value, error = lock.wait(flight)      # called by follower
+
+lock.in_flight_count  # => 3
+```
+
+---
+
+## AR Fingerprinting
+
+Cache keys are built from the fingerprints of dependency values. For stable keys that
+survive process restarts (required for Redis-backed caches), dependency objects must
+implement `#igniter_fingerprint`.
+
+### `Igniter::Fingerprint` mixin
+
+Include in any class whose instances are passed as node dependencies:
+
+```ruby
+class Trade < ApplicationRecord
+  include Igniter::Fingerprint
+  # default fingerprint: "Trade:42:1712345678"  (class:id:updated_at_unix)
+end
+```
+
+The default implementation:
+- **With `updated_at`**: `"ClassName:id:updated_at_unix"` — cache is invalidated on record update.
+- **With `id` only**: `"ClassName:id"`.
+- **Fallback**: `"ClassName:object_id"` — stable within a process, not across restarts.
+
+### Custom fingerprints
+
+Override `#igniter_fingerprint` for non-AR objects or custom invalidation logic:
+
+```ruby
+class PricingConfig
+  include Igniter::Fingerprint
+
+  def igniter_fingerprint
+    "PricingConfig:#{version}:#{market}"
+  end
+end
+```
+
+### Rails Railtie
+
+When using the `igniter-rails` integration, `Igniter::Fingerprint` is automatically
+included in `ApplicationRecord` — no per-model setup required.
+
+---
+
+## `runner` Class Macro
+
+The `runner` macro sets the default execution strategy for a contract class, replacing
+the more verbose `run_with`:
+
+```ruby
+class MyContract < Igniter::Contract
+  runner :thread_pool, pool_size: 4
+
+  define do
+    # ...
+  end
+end
+```
+
+Equivalent to `run_with(runner: :thread_pool, max_workers: 4)`. Accepts `pool_size:` or
+`max_workers:` interchangeably.
+
+---
+
+## Full Example
+
+```ruby
+require "igniter"
+require "igniter/node_cache"
+
+Igniter.configure do |c|
+  c.node_cache      = Igniter::NodeCache::Memory.new
+  c.node_coalescing = true
+end
+
+class Vendor
+  include Igniter::Fingerprint
+  attr_reader :id, :updated_at
+  def initialize(id) = (@id = id; @updated_at = Time.now)
+end
+
+class FetchSlots < Igniter::Executor
+  def call(vendor:, zip_code:)
+    puts "  → computing for vendor=#{vendor.id} zip=#{zip_code}"
+    rand(10)
+  end
+end
+
+class SlotContract < Igniter::Contract
+  runner :thread_pool, pool_size: 2
+
+  define do
+    input  :vendor
+    input  :zip_code
+    compute :slots, with: [:vendor, :zip_code], call: FetchSlots,
+                    cache_ttl: 60, coalesce: true
+    output :slots
+  end
+end
+
+vendor = Vendor.new(42)
+
+c1 = SlotContract.new(vendor: vendor, zip_code: "10001").resolve
+c2 = SlotContract.new(vendor: vendor, zip_code: "10001").resolve
+
+puts c1.result.slots   # => 7  (computed)
+puts c2.result.slots   # => 7  (TTL cache hit — FetchSlots not called)
+```
+
+---
+
+## Setup Reference
+
+```ruby
+Igniter.configure do |c|
+  c.node_cache      = Igniter::NodeCache::Memory.new   # or custom Redis backend
+  c.node_coalescing = true                             # auto-creates CoalescingLock
+end
+```
+
+| Option                     | Default | Description |
+|----------------------------|---------|-------------|
+| `node_cache=`              | `nil`   | TTL cache backend; `nil` = disabled |
+| `node_coalescing=`         | `nil`   | `true` creates a `CoalescingLock`; `nil`/`false` = disabled |
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `lib/igniter/node_cache.rb` | `CacheKey`, `Memory`, `CoalescingLock`, `Fingerprinter` |
+| `lib/igniter/fingerprint.rb` | `Igniter::Fingerprint` mixin |
+| `lib/igniter/model/compute_node.rb` | `cache_ttl`, `coalesce?` readers |
+| `lib/igniter/runtime/resolver.rb` | TTL cache + coalescing hooks in `resolve_compute` |
+| `lib/igniter.rb` | `node_cache=`, `node_coalescing=` in configure API |
+| `spec/igniter/node_cache_spec.rb` | 42 examples |
+| `examples/elocal_webhook.rb` | Real-world usage — eLocal auction webhook migration |

data/docs/PROACTIVE_AGENTS_V1.md

@@ -0,0 +1,293 @@
+# Proactive Agents — V1
+
+## Concept
+
+Standard Igniter agents are **reactive** — they wait for messages and respond.
+A **proactive** agent acts *without being asked*: it polls conditions on a
+schedule, evaluates rules, and fires actions when conditions are met.
+
+```
+Reactive:   external message  →  handler  →  new state
+Proactive:  timer tick        →  watchers  →  triggers  →  actions  →  new state
+```
+
+`ProactiveAgent` is an experimental base class that adds four DSL keywords and
+a built-in scan lifecycle on top of the standard `Igniter::Agent` API.
+
+---
+
+## Architecture
+
+```
+ProactiveAgent < Igniter::Agent
+    │
+    ├── scan_interval  — register a recurring :_scan timer
+    ├── watch          — register a named poll callable
+    ├── trigger        — register condition + action pair
+    └── proactive_initial_state
+            │
+            └── :_scan handler (auto-injected into every subclass)
+                    1. Call each watcher → build context Hash
+                    2. Evaluate each trigger condition(ctx)
+                    3. Call action(state:, context:) for truthy conditions
+                    4. Append FiredTrigger records, increment scan_count
+```
+
+### Execution model
+
+Every `scan_interval` seconds the timer fires and posts a `:_scan` message.
+The same `:_scan` handler is also callable programmatically — useful in specs
+and for composing proactive agents with other agents.
+
+When `active: false` (via `:pause`) the scan cycle is a no-op; timer still
+fires but watchers are not called and triggers are not evaluated.
+
+---
+
+## DSL Reference
+
+### `ProactiveAgent`
+
+| Keyword | Description |
+|---|---|
+| `intent "…"` | Human-readable mission string (metadata, shown in `:status`) |
+| `scan_interval N` | Register a recurring timer every N seconds |
+| `watch :name, poll: callable` | Named watcher; callable returns current reading |
+| `trigger :name, condition:, action:` | Register a conditional action |
+| `proactive_initial_state extra` | Set initial state (merges ProactiveAgent defaults) |
+
+### Built-in handlers (injected into every subclass)
+
+| Handler | Type | Description |
+|---|---|---|
+| `:_scan` | state-mutating | Run one scan cycle |
+| `:pause` | state-mutating | Suspend trigger evaluation (active: false) |
+| `:resume` | state-mutating | Resume trigger evaluation (active: true) |
+| `:status` | sync query → `Status` | Counts, intent, watcher/trigger names |
+| `:context` | sync query → Hash | Last context snapshot |
+| `:trigger_history` | sync query → Array | Up to 100 most recent `FiredTrigger` records |
+
+---
+
+## Quick start
+
+```ruby
+require "igniter/agents/proactive_agent"
+
+class ServerTempMonitor < Igniter::Agents::ProactiveAgent
+  intent "Alert when server room temperature exceeds safe range"
+
+  scan_interval 10.0   # check every 10 seconds
+
+  watch :temp_c, poll: -> { SensorAPI.read_temp }
+
+  trigger :overheating,
+    condition: ->(ctx) { ctx[:temp_c].to_f > 30 },
+    action:    ->(state:, context:) {
+      Notifier.alert("Server room temp: #{context[:temp_c]}°C")
+      state.merge(last_alert_at: Time.now)
+    }
+
+  proactive_initial_state last_alert_at: nil
+end
+
+ref = ServerTempMonitor.start
+status = ref.call(:status)
+# => Status(active: true, scan_count: 0, intent: "Alert when …", …)
+```
+
+---
+
+## Subclasses — AlertAgent and HealthCheckAgent
+
+Two production-ready proactive agents are included in the stdlib:
+
+```
+require "igniter/agents"
+```
+
+### `AlertAgent`
+
+Threshold-based numeric monitoring with a concise DSL:
+
+```ruby
+class ApiMonitor < Igniter::Agents::AlertAgent
+  intent "Watch error rate and latency"
+  scan_interval 15.0
+
+  monitor :error_rate, source: -> { Metrics.error_rate }
+  monitor :p99_ms,     source: -> { Metrics.p99_latency }
+
+  threshold :error_rate, above: 0.05   # >5% errors
+  threshold :p99_ms,     above: 800    # >800ms p99
+  threshold :p99_ms,     below: 1      # ghost: no traffic at all
+
+  proactive_initial_state alerts: [], silenced: false
+end
+
+ref    = ApiMonitor.start
+ref.send(:silence)             # suppress new alerts
+alerts = ref.call(:alerts)     # => Array<AlertRecord>
+ref.send(:clear_alerts)
+```
+
+**AlertRecord fields**: `metric`, `value`, `kind` (`:above`/`:below`),
+`threshold`, `fired_at`.
+
+### `HealthCheckAgent`
+
+Service liveness polling with automatic transition detection:
+
+```ruby
+class InfraHealth < Igniter::Agents::HealthCheckAgent
+  intent "Monitor database and cache"
+  scan_interval 30.0
+
+  # poll returns truthy = healthy, falsy / raises = unhealthy
+  check :database, poll: -> { DB.ping }
+  check :cache,    poll: -> { Redis.current.ping == "PONG" }
+
+  proactive_initial_state health: {}, transitions: []
+end
+
+ref         = InfraHealth.start
+health      = ref.call(:health)       # => { database: :healthy, cache: :unhealthy }
+all_ok      = ref.call(:all_healthy)  # => false
+transitions = ref.call(:transitions)  # => [Transition(cache: unknown→unhealthy)]
+```
+
+Transitions are only recorded when status **changes** — no duplicate events for
+persistently unhealthy services.
+
+**Transition fields**: `service`, `from`, `to`, `occurred_at`.
+
+---
+
+## Building your own ProactiveAgent subclass
+
+### Pattern: layering reactive and proactive handlers
+
+```ruby
+class StockWatcher < Igniter::Agents::ProactiveAgent
+  intent "Monitor stock price and fire when it crosses buy/sell thresholds"
+
+  scan_interval 60.0
+
+  watch :price, poll: -> { FinanceAPI.last_price("AAPL") }
+
+  trigger :buy_signal,
+    condition: ->(ctx) { ctx[:price].to_f < 150 },
+    action:    ->(state:, context:) {
+      state.merge(signals: state[:signals] + [{ type: :buy, price: context[:price], at: Time.now }])
+    }
+
+  proactive_initial_state signals: []
+
+  # Reactive handler for manual context override (e.g. in tests)
+  on :inject_price do |state:, payload:|
+    state.merge(context: state[:context].merge(price: payload[:price]))
+  end
+
+  on :signals do |state:, **|
+    state[:signals].dup
+  end
+end
+```
+
+### Pattern: re-injecting handlers in a concrete subclass
+
+Because `Agent.inherited` resets `@handlers`, any handlers defined in a
+parent class (like `AlertAgent`) are NOT automatically present in
+`Class.new(AlertAgent)` (used in tests or further subclasses).
+
+Both `AlertAgent` and `HealthCheckAgent` override `inherited` and call
+`inject_*_handlers!(subclass)` to ensure their handlers are always present.
+Follow the same pattern when building your own concrete subclass:
+
+```ruby
+class MyAgent < Igniter::Agents::ProactiveAgent
+  def self.inherited(subclass)
+    super                          # ProactiveAgent.inherited injects :_scan etc.
+    inject_my_handlers!(subclass)
+  end
+
+  private_class_method def self.inject_my_handlers!(klass)
+    klass.on(:my_query) { |state:, **| state[:my_data].dup }
+  end
+
+  on :my_query do |state:, **|
+    state[:my_data].dup
+  end
+end
+```
+
+### Testing: drive scans without a real timer
+
+```ruby
+RSpec.describe MyAgent do
+  let(:h) { ->(type, state) { MyAgent.handlers[type].call(state: state, payload: {}) } }
+
+  def base_state(extra = {})
+    { active: true, context: {}, scan_count: 0,
+      last_scan_at: nil, trigger_history: [] }.merge(extra)
+  end
+
+  it "fires trigger when condition is met" do
+    # Call :_scan directly — no timer, no threads
+    result = h.call(:_scan, base_state)
+    expect(result[:trigger_history]).not_to be_empty
+  end
+end
+```
+
+---
+
+## Companion example
+
+`examples/companion/proactive/` shows three proactive agents in the context of
+the voice assistant companion application:
+
+| File | Agent | Mission |
+|---|---|---|
+| `conversation_nudge_agent.rb` | `ConversationNudgeAgent` | Detect silence and topic stagnation; propose conversation nudges |
+| `system_watch_agent.rb` | `SystemAlertAgent` / `DependencyHealthAgent` | Monitor API metrics and service liveness |
+| `demo.rb` | All four agents | Self-contained, runnable demonstration |
+
+```bash
+ruby examples/companion/proactive/demo.rb
+```
+
+---
+
+## API quick reference
+
+```ruby
+# Base class DSL
+class MyAgent < Igniter::Agents::ProactiveAgent
+  intent        "…"
+  scan_interval 5.0
+  watch         :metric, poll: -> { source }
+  trigger       :name, condition: ->(ctx) { … }, action: ->(state:, context:) { … }
+  proactive_initial_state key: default_value
+end
+
+# Runtime
+ref = MyAgent.start
+ref.send(:pause)                       # suspend reactions
+ref.send(:resume)                      # resume
+ref.call(:status)                      # => Status struct
+ref.call(:context)                     # => { metric: last_reading, … }
+ref.call(:trigger_history)             # => [FiredTrigger, …]
+
+# AlertAgent
+ref.send(:silence)                     # suppress new alerts
+ref.send(:unsilence)
+ref.call(:alerts)                      # => [AlertRecord, …]
+ref.send(:clear_alerts)
+
+# HealthCheckAgent
+ref.call(:health)                      # => { service: :healthy/:unhealthy }
+ref.call(:all_healthy)                 # => true | false
+ref.call(:transitions)                 # => [Transition, …]
+ref.send(:reset)
+```