igniter 0.4.5 → 0.5.1

data/lib/igniter/stack.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "monorepo_packages"
+require "igniter/sdk"
+require "igniter/app/stack_pack"

data/lib/igniter.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 
-require_relative "igniter/version"
-require_relative "igniter/errors"
-require_relative "igniter/type_system"
-require_relative "igniter/executor"
-require_relative "igniter/executor_registry"
-require_relative "igniter/effect"
-require_relative "igniter/effect_registry"
-require_relative "igniter/model"
-require_relative "igniter/compiler"
-require_relative "igniter/events"
-require_relative "igniter/runtime"
-require_relative "igniter/dsl"
-require_relative "igniter/extensions"
-require_relative "igniter/diagnostics"
-require_relative "igniter/contract"
+require_relative "igniter/monorepo_packages"
+
+require "igniter/core/version"
+require "igniter/core/errors"
+require "igniter/core/type_system"
+require "igniter/core/executor"
+require "igniter/core/executor_registry"
+require "igniter/core/effect"
+require "igniter/core/effect_registry"
+require "igniter/core/model"
+require "igniter/core/compiler"
+require "igniter/core/events"
+require "igniter/core/runtime"
+require "igniter/core/dsl"
+require "igniter/core/extensions"
+require "igniter/core/diagnostics"
+require "igniter/core/contract"
 
 module Igniter
   class << self
+    def use(*names)
+      require "igniter/sdk"
+
+      @sdk_capabilities ||= []
+      resolved_names = names.flatten.map(&:to_sym)
+      SDK.activate!(*resolved_names, layer: :core)
+      @sdk_capabilities |= resolved_names
+      self
+    end
+
+    def sdk_capabilities
+      @sdk_capabilities ||= []
+    end
+
     def executor_registry
       @executor_registry ||= ExecutorRegistry.new
     end
@@ -30,6 +46,23 @@ module Igniter
       @execution_store = store
     end
 
+    # TTL cache backend for compute nodes. nil = disabled (default).
+    # Set to Igniter::NodeCache::Memory.new (or a Redis-backed equivalent).
+    def node_cache
+      defined?(Igniter::NodeCache) ? Igniter::NodeCache.cache : nil
+    end
+
+    def node_cache=(cache)
+      require "igniter/core/node_cache"
+      Igniter::NodeCache.cache = cache
+    end
+
+    # When true, auto-creates a CoalescingLock alongside the configured node cache.
+    def node_coalescing=(enabled)
+      require "igniter/core/node_cache"
+      Igniter::NodeCache.coalescing_lock = enabled ? Igniter::NodeCache::CoalescingLock.new : nil
+    end
+
     def register_executor(key, executor_class, **metadata)
       executor_registry.register(key, executor_class, **metadata)
     end

data/packages/igniter-agents/README.md

@@ -0,0 +1,22 @@
+# igniter-agents
+
+Local monorepo gem that owns Igniter's actor runtime and agent libraries:
+
+- `Igniter::Agent`, `Igniter::Registry`, `Igniter::Supervisor`
+- `Igniter::Agents`
+- `Igniter::AI::Agents`
+
+Primary entrypoints:
+
+- `require "igniter-agents"`
+- `require "igniter/agent"`
+- `require "igniter/supervisor"`
+- `require "igniter/registry"`
+- `require "igniter/agents"`
+- `require "igniter/ai/agents"`
+
+Docs:
+
+- [Guide](../../docs/guide/README.md)
+- [Current](../../docs/current/README.md)
+- [Dev](../../docs/dev/README.md)

data/{lib → packages/igniter-agents/lib}/igniter/agent/ref.rb

@@ -28,6 +28,7 @@ module Igniter
         mailbox.push(Message.new(type: type.to_sym, payload: payload, reply_to: reply_box))
         reply = reply_box.pop(timeout: timeout)
         raise TimeoutError, "Agent did not reply within #{timeout}s" unless reply
+        raise reply.payload[:error] if reply.payload[:error]
 
         reply.payload[:value]
       end

data/{lib → packages/igniter-agents/lib}/igniter/agent/runner.rb

@@ -65,6 +65,10 @@ module Igniter
 
         state  = @state_holder.get
         result = handler.call(state: state, payload: message.payload)
+      rescue Igniter::PendingDependencyError => e
+        send_error_reply(message, e)
+        return
+      else
 
         case result
         when Hash
@@ -89,6 +93,14 @@ module Igniter
         )
       end
 
+      def send_error_reply(message, error)
+        return unless message.reply_to
+
+        message.reply_to.push(
+          Message.new(type: :reply, payload: { error: error })
+        )
+      end
+
       # Returns seconds until the next timer fires, or nil if no timers.
       def nearest_timer_delay
         return nil if @timers.empty?

data/{lib → packages/igniter-agents/lib}/igniter/agent.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require "igniter/core/errors"
+require "igniter/core/runtime/agent_adapter"
+require_relative "registry"
 require_relative "agent/message"
 require_relative "agent/mailbox"
 require_relative "agent/state_holder"
 require_relative "agent/runner"
 require_relative "agent/ref"
+require_relative "runtime/registry_agent_adapter"
 
 module Igniter
   # Base class for stateful, message-driven actors.
@@ -153,3 +157,5 @@ module Igniter
     end
   end
 end
+
+Igniter::Runtime.activate_agent_adapter! if Igniter::Runtime.agent_adapter.instance_of?(Igniter::Runtime::AgentAdapter)

data/packages/igniter-agents/lib/igniter/agents/observability/metrics_agent.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Agents
+    # In-process metrics collection with Prometheus text export.
+    #
+    # Supports three metric types:
+    # * **counter**   — monotonically increasing value (:increment)
+    # * **gauge**     — arbitrary current value (:gauge)
+    # * **histogram** — observed value distribution (:observe)
+    #
+    # All metric names are coerced to strings. Tags (labels) are stored but not
+    # yet aggregated — they are included in the snapshot for external processing.
+    #
+    # @example
+    #   ref = MetricsAgent.start
+    #   ref.send(:increment, name: "http.requests", by: 1, tags: { method: "GET" })
+    #   ref.send(:gauge,     name: "queue.depth",   value: 42)
+    #   ref.send(:observe,   name: "response_time", value: 0.123)
+    #
+    #   snap = ref.call(:snapshot)
+    #   puts snap.counters["http.requests"]   # => 1.0
+    #
+    #   puts ref.call(:prometheus_text)
+    class MetricsAgent < Igniter::Agent
+      # Returned by the sync :snapshot query.
+      Snapshot = Struct.new(:counters, :gauges, :histograms, keyword_init: true)
+
+      initial_state counters: {}, gauges: {}, histograms: {}
+
+      # Increment a counter.
+      #
+      # Payload keys:
+      #   name [String, Symbol]  — metric name
+      #   by   [Numeric]         — increment amount (default: 1)
+      #   tags [Hash]            — labels (stored, not aggregated)
+      on :increment do |state:, payload:|
+        name     = payload.fetch(:name).to_s
+        by       = payload.fetch(:by, 1).to_f
+        counters = state[:counters].dup
+        counters[name] = (counters[name] || 0.0) + by
+        state.merge(counters: counters)
+      end
+
+      # Set a gauge to an exact value.
+      #
+      # Payload keys:
+      #   name  [String, Symbol]
+      #   value [Numeric]
+      #   tags  [Hash]
+      on :gauge do |state:, payload:|
+        name   = payload.fetch(:name).to_s
+        value  = payload.fetch(:value).to_f
+        gauges = state[:gauges].merge(name => value)
+        state.merge(gauges: gauges)
+      end
+
+      # Record a histogram observation.
+      #
+      # Payload keys:
+      #   name  [String, Symbol]
+      #   value [Numeric]
+      on :observe do |state:, payload:|
+        name       = payload.fetch(:name).to_s
+        value      = payload.fetch(:value).to_f
+        histograms = state[:histograms].dup
+        bucket     = histograms[name] || { count: 0, sum: 0.0, min: Float::INFINITY,
+                                           max: -Float::INFINITY, values: [] }
+        updated    = bucket.merge(
+          count:  bucket[:count] + 1,
+          sum:    bucket[:sum]   + value,
+          min:    [bucket[:min], value].min,
+          max:    [bucket[:max], value].max,
+          values: bucket[:values] + [value]
+        )
+        state.merge(histograms: histograms.merge(name => updated))
+      end
+
+      # Sync snapshot query — returns all current metric values.
+      #
+      # @return [Snapshot]
+      on :snapshot do |state:, **|
+        Snapshot.new(
+          counters:   state[:counters].dup,
+          gauges:     state[:gauges].dup,
+          histograms: state[:histograms].transform_values { |h|
+            { count: h[:count], sum: h[:sum], min: h[:min], max: h[:max],
+              avg: h[:count] > 0 ? h[:sum] / h[:count] : 0.0 }
+          }
+        )
+      end
+
+      # Sync query — render metrics in Prometheus text format.
+      #
+      # @return [String]
+      on :prometheus_text do |state:, **|
+        render_prometheus(state)
+      end
+
+      # Reset all metrics.
+      on :reset do |state:, **|
+        state.merge(counters: {}, gauges: {}, histograms: {})
+      end
+
+      class << self
+        # Render state as Prometheus exposition format.
+        #
+        # @param state [Hash]
+        # @return [String]
+        def render_prometheus(state)
+          lines = []
+          state[:counters].each do |name, value|
+            lines << "# TYPE #{name} counter"
+            lines << "#{name} #{value}"
+          end
+          state[:gauges].each do |name, value|
+            lines << "# TYPE #{name} gauge"
+            lines << "#{name} #{value}"
+          end
+          state[:histograms].each do |name, h|
+            lines << "# TYPE #{name} histogram"
+            lines << "#{name}_count #{h[:count]}"
+            lines << "#{name}_sum #{h[:sum]}"
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/packages/igniter-agents/lib/igniter/agents/pipeline/batch_processor_agent.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Agents
+    # Processes items in configurable batches with error tracking.
+    #
+    # Items are enqueued via :enqueue and processed synchronously via
+    # :process_next (one batch) or :drain (all remaining items).
+    # Failed items are tracked with their errors for inspection.
+    #
+    # @example
+    #   processor = ->(item:) { DataStore.upsert(item) }
+    #
+    #   ref = BatchProcessorAgent.start(initial_state: { batch_size: 50 })
+    #   ref.send(:enqueue, items: records, callable: processor)
+    #   ref.send(:drain)
+    #
+    #   status = ref.call(:status)
+    #   puts "processed=#{status.processed} failed=#{status.failed}"
+    class BatchProcessorAgent < Igniter::Agent
+      # Returned by the sync :status query.
+      Status = Struct.new(:queue_size, :processed, :failed, keyword_init: true)
+
+      initial_state queue: [], processed: 0, failed: 0, errors: [], batch_size: 10
+
+      # Add items to the processing queue.
+      #
+      # Payload keys:
+      #   items    [Array]  — required; items to process
+      #   callable [#call]  — receives (item:); required unless set via :configure
+      on :enqueue do |state:, payload:|
+        items    = Array(payload.fetch(:items))
+        callable = payload[:callable] || state[:callable]
+        raise ArgumentError, ":callable required" unless callable
+
+        jobs     = items.map { |item| { item: item, callable: callable } }
+        state.merge(queue: state[:queue] + jobs)
+      end
+
+      # Process the next batch_size items.
+      #
+      # Payload keys:
+      #   batch_size [Integer] — override class default (optional)
+      on :process_next do |state:, payload:|
+        size  = payload.fetch(:batch_size, state[:batch_size])
+        agent = new
+        agent.send(:run_batch, state, size)
+      end
+
+      # Process all remaining items synchronously (blocks until queue is empty).
+      on :drain do |state:, payload:|
+        size  = payload.fetch(:batch_size, state[:batch_size])
+        agent = new
+        agent.send(:run_all, state, size)
+      end
+
+      # Sync status query.
+      #
+      # @return [Status]
+      on :status do |state:, **|
+        Status.new(
+          queue_size: state[:queue].size,
+          processed:  state[:processed],
+          failed:     state[:failed]
+        )
+      end
+
+      # Return error log for failed items.
+      #
+      # @return [Array<Hash>]
+      on :errors do |state:, **|
+        state[:errors]
+      end
+
+      # Reset counters and clear errors (queue is preserved).
+      on :reset_stats do |state:, **|
+        state.merge(processed: 0, failed: 0, errors: [])
+      end
+
+      # Set default batch_size and/or default callable.
+      #
+      # Payload keys:
+      #   batch_size [Integer]  — new default
+      #   callable   [#call]    — new default callable
+      on :configure do |state:, payload:|
+        state.merge(
+          batch_size: payload.fetch(:batch_size, state[:batch_size]),
+          callable:   payload.fetch(:callable, state[:callable])
+        )
+      end
+
+      private
+
+      def run_batch(state, size)
+        batch     = state[:queue].first(size)
+        remaining = state[:queue].drop(size)
+        result    = process_jobs(batch)
+        apply_result(state, remaining, result)
+      end
+
+      def run_all(state, size)
+        current = state
+        current = run_batch(current, size) until current[:queue].empty?
+        current
+      end
+
+      def process_jobs(batch)
+        processed = 0
+        failed    = 0
+        errors    = []
+        batch.each do |job|
+          job[:callable].call(item: job[:item])
+          processed += 1
+        rescue StandardError => e
+          failed += 1
+          errors << { item: job[:item], error: e.message }
+        end
+        { processed: processed, failed: failed, errors: errors }
+      end
+
+      def apply_result(state, remaining, result)
+        state.merge(
+          queue:     remaining,
+          processed: state[:processed] + result[:processed],
+          failed:    state[:failed]    + result[:failed],
+          errors:    state[:errors]    + result[:errors]
+        )
+      end
+    end
+  end
+end

data/packages/igniter-agents/lib/igniter/agents/proactive/alert_agent.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "../proactive_agent"
+
+module Igniter
+  module Agents
+    # Threshold-based alerting agent.
+    #
+    # AlertAgent extends ProactiveAgent with an opinionated DSL for declaring
+    # numeric thresholds.  A single +monitor+ / +threshold+ pair registers both
+    # the watcher and the trigger automatically.
+    #
+    # @example
+    #   class ApiAlerts < Igniter::Agents::AlertAgent
+    #     intent "Alert when API error rate or latency spikes"
+    #     scan_interval 15.0
+    #
+    #     monitor :error_rate,  source: -> { Metrics.error_rate }
+    #     monitor :p99_latency, source: -> { Metrics.p99 }
+    #
+    #     threshold :error_rate,  above: 0.05
+    #     threshold :p99_latency, above: 500
+    #   end
+    #
+    #   ref    = ApiAlerts.start
+    #   alerts = ref.call(:alerts)   # => Array<AlertRecord>
+    class AlertAgent < ProactiveAgent
+      # Immutable record created when a threshold is breached.
+      AlertRecord = Struct.new(:metric, :value, :kind, :threshold,
+                               :fired_at, keyword_init: true)
+
+      proactive_initial_state alerts: [], silenced: false
+
+      class << self
+        # Register a polling source for a named metric.
+        # Usually called before +threshold+ for the same metric name.
+        #
+        # @param metric [Symbol, String]
+        # @param source [#call]  — zero-argument callable returning a Numeric
+        def monitor(metric, source:)
+          watch(metric.to_sym, poll: source)
+        end
+
+        # Declare a threshold for a watched metric.
+        # Automatically registers a trigger that fires when the condition is met.
+        #
+        # @param metric [Symbol, String]
+        # @param above  [Numeric, nil]  — breach if value > above
+        # @param below  [Numeric, nil]  — breach if value < below
+        def threshold(metric, above: nil, below: nil)
+          name = metric.to_sym
+
+          trigger(:"threshold_#{name}",
+            condition: ->(ctx) {
+              val = ctx[name]
+              return false if val.nil?
+
+              (above && val.to_f > above.to_f) ||
+                (below && val.to_f < below.to_f)
+            },
+            action: ->(state:, context:) {
+              next state if state[:silenced]
+
+              val  = context[name]
+              kind = above && val.to_f > above.to_f ? :above : :below
+              rec  = AlertRecord.new(
+                metric:    name,
+                value:     val,
+                kind:      kind,
+                threshold: kind == :above ? above : below,
+                fired_at:  Time.now
+              )
+              state.merge(alerts: (state[:alerts] + [rec]).last(200))
+            }
+          )
+        end
+      end
+
+      # ── Inheritance ────────────────────────────────────────────────────────
+      # Re-inject AlertAgent-specific handlers into every subclass so that
+      # anonymous test classes (Class.new(AlertAgent)) also have them.
+      def self.inherited(subclass)
+        super  # ProactiveAgent.inherited → resets @handlers, injects proactive ones
+        inject_alert_handlers!(subclass)
+      end
+
+      private_class_method def self.inject_alert_handlers!(klass)
+        klass.on(:silence)      { |state:, **| state.merge(silenced: true)  }
+        klass.on(:unsilence)    { |state:, **| state.merge(silenced: false) }
+        klass.on(:alerts)       { |state:, **| state.fetch(:alerts, []).dup }
+        klass.on(:clear_alerts) { |state:, **| state.merge(alerts: []) }
+      end
+
+      # Suppress alert creation (scans and condition checks still run).
+      on :silence   do |state:, **| state.merge(silenced: true)  end
+      on :unsilence do |state:, **| state.merge(silenced: false) end
+
+      # Sync query — all recorded AlertRecord objects.
+      #
+      # @return [Array<AlertRecord>]
+      on :alerts do |state:, **|
+        state.fetch(:alerts, []).dup
+      end
+
+      # Clear alert history.
+      on :clear_alerts do |state:, **|
+        state.merge(alerts: [])
+      end
+    end
+  end
+end

data/packages/igniter-agents/lib/igniter/agents/proactive/health_check_agent.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../proactive_agent"
+
+module Igniter
+  module Agents
+    # Polls a set of named services and tracks their health status.
+    #
+    # HealthCheckAgent wraps ProactiveAgent with a +check+ DSL keyword that
+    # registers both the watcher (poll callable) and a trigger that fires
+    # when a service transitions to an unhealthy state.
+    #
+    # The poll callable should:
+    # * Return a truthy value when the service is healthy.
+    # * Return falsy OR raise when the service is unhealthy.
+    #
+    # @example
+    #   class InfraHealth < Igniter::Agents::HealthCheckAgent
+    #     intent "Monitor database, cache, and payment gateway"
+    #     scan_interval 30.0
+    #
+    #     check :database,        poll: -> { DB.ping }
+    #     check :redis,           poll: -> { Redis.current.ping == "PONG" }
+    #     check :payment_gateway, poll: -> { PaymentClient.health_check }
+    #   end
+    #
+    #   ref    = InfraHealth.start
+    #   status = ref.call(:health)    # => { database: :healthy, redis: :unhealthy, … }
+    #   all_ok = ref.call(:all_healthy)
+    class HealthCheckAgent < ProactiveAgent
+      # Recorded when a service's health changes (healthy ↔ unhealthy).
+      Transition = Struct.new(:service, :from, :to, :occurred_at, keyword_init: true)
+
+      proactive_initial_state health: {}, transitions: []
+
+      class << self
+        # Register a service health check.
+        # Calling +check+ registers both the watcher and an unhealthy trigger.
+        #
+        # @param service [Symbol, String]
+        # @param poll    [#call]  — returns truthy = healthy, falsy/raises = unhealthy
+        def check(service, poll:)
+          name = service.to_sym
+
+          # Watcher: map poll result to :healthy / :unhealthy symbol
+          watch(name, poll: -> {
+            begin
+              poll.call ? :healthy : :unhealthy
+            rescue StandardError
+              :unhealthy
+            end
+          })
+
+          # Trigger: fires when service is unhealthy AND previous status differs
+          trigger(:"health_#{name}",
+            condition: ->(ctx) { ctx[name] == :unhealthy },
+            action: ->(state:, context:) {
+              prev   = state[:health][name]
+              status = context[name]
+              health = state[:health].merge(name => status)
+
+              # Only record a transition when the status actually changes
+              if prev != status
+                t = Transition.new(
+                  service:     name,
+                  from:        prev || :unknown,
+                  to:          status,
+                  occurred_at: Time.now
+                )
+                transitions = (state[:transitions] + [t]).last(100)
+                state.merge(health: health, transitions: transitions)
+              else
+                state.merge(health: health)
+              end
+            }
+          )
+        end
+      end
+
+      # ── Inheritance ────────────────────────────────────────────────────────
+      # Re-inject HealthCheckAgent-specific handlers so that anonymous test
+      # classes (Class.new(HealthCheckAgent)) also receive them.
+      def self.inherited(subclass)
+        super  # ProactiveAgent.inherited → resets @handlers, injects proactive ones
+        inject_health_handlers!(subclass)
+      end
+
+      private_class_method def self.inject_health_handlers!(klass)
+        klass.on(:health)      { |state:, **| state.fetch(:health, {}).dup }
+        klass.on(:all_healthy) { |state:, **| state.fetch(:health, {}).values.all? { |v| v == :healthy } }
+        klass.on(:transitions) { |state:, **| state.fetch(:transitions, []).dup }
+        klass.on(:reset)       { |state:, **| state.merge(health: {}, transitions: []) }
+      end
+
+      # Sync query — current health status per service.
+      #
+      # @return [Hash<Symbol, :healthy | :unhealthy>]
+      on :health do |state:, **|
+        state.fetch(:health, {}).dup
+      end
+
+      # Sync query — true when all polled services are healthy.
+      #
+      # @return [Boolean]
+      on :all_healthy do |state:, **|
+        state.fetch(:health, {}).values.all? { |v| v == :healthy }
+      end
+
+      # Sync query — list of recorded health transitions.
+      #
+      # @return [Array<Transition>]
+      on :transitions do |state:, **|
+        state.fetch(:transitions, []).dup
+      end
+
+      # Reset health status and transition history.
+      on :reset do |state:, **|
+        state.merge(health: {}, transitions: [])
+      end
+    end
+  end
+end