igniter 0.4.5 → 0.5.1

data/packages/igniter-core/lib/igniter/core/metrics/collector.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Metrics
+    # Thread-safe event subscriber that collects execution-level metrics.
+    #
+    # Subscribes to an Igniter::Events::Bus (via the Events::Bus#subscribe interface)
+    # and maintains in-memory counters and histograms for:
+    #   - Total executions (by graph, by status)
+    #   - Execution duration histogram (by graph)
+    #   - HTTP request counts and durations (recorded directly by the server)
+    #
+    # All state is protected by a Mutex. Snapshot returns a frozen copy
+    # safe to read outside the lock.
+    class Collector
+      HISTOGRAM_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0].freeze
+
+      def initialize
+        @mutex = Mutex.new
+        @counters   = Hash.new(0)  # String(metric{labels}) → Integer
+        @histograms = {}           # String(metric_name) → Hash(label_key → histogram_entry)
+        @exec_start = {}           # execution_id → Time (for duration tracking)
+        @exec_graph = {}           # execution_id → graph_name
+      end
+
+      # Called by Events::Bus for every event emitted during an execution.
+      def call(event) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+        case event.type
+        when :execution_started   then on_execution_started(event)
+        when :execution_finished  then on_execution_finished(event, "succeeded")
+        when :execution_failed    then on_execution_finished(event, "failed")
+        end
+      end
+
+      # Record an HTTP request (called directly by the server/router).
+      def record_http(method:, path:, status:, duration:)
+        @mutex.synchronize do
+          inc("igniter_http_requests_total",
+              method: method, path: normalized_path(path), status: status.to_s)
+          observe_locked("igniter_http_request_duration_seconds", duration,
+                         method: method, path: normalized_path(path))
+        end
+      end
+
+      # Snapshot returns frozen copies of counters and histograms.
+      def snapshot
+        @mutex.synchronize do
+          Snapshot.new(
+            counters: @counters.dup.freeze,
+            histograms: deep_freeze(@histograms)
+          )
+        end
+      end
+
+      private
+
+      def on_execution_started(event)
+        @mutex.synchronize do
+          @exec_start[event.execution_id] = event.timestamp
+          @exec_graph[event.execution_id] = event.payload[:graph].to_s
+        end
+      end
+
+      def on_execution_finished(event, status)
+        @mutex.synchronize do
+          graph      = @exec_graph.delete(event.execution_id) || event.payload[:graph].to_s
+          started_at = @exec_start.delete(event.execution_id)
+
+          inc("igniter_executions_total", graph: graph, status: status)
+
+          if started_at
+            duration = event.timestamp - started_at
+            observe_locked("igniter_execution_duration_seconds", duration, graph: graph)
+          end
+        end
+      end
+
+      def inc(name, labels)
+        @counters[metric_key(name, labels)] += 1
+      end
+
+      def observe_locked(name, value, labels)
+        lkey = label_key(labels)
+        @histograms[name] ||= {}
+        entry = @histograms[name][lkey] ||= new_histogram_entry(labels)
+        HISTOGRAM_BUCKETS.each { |b| entry[:buckets][b] += 1 if value <= b }
+        entry[:sum] += value
+        entry[:count] += 1
+      end
+
+      def new_histogram_entry(labels)
+        { labels: labels, buckets: Hash.new(0), sum: 0.0, count: 0 }
+      end
+
+      def metric_key(name, labels)
+        "#{name}#{label_selector(labels)}"
+      end
+
+      def label_key(labels)
+        label_selector(labels)
+      end
+
+      def label_selector(labels)
+        return "" if labels.empty?
+
+        pairs = labels.map { |k, v| "#{k}=\"#{v}\"" }.join(",")
+        "{#{pairs}}"
+      end
+
+      def normalized_path(path)
+        # Collapse dynamic path segments to avoid high-cardinality labels
+        path.to_s
+            .gsub(%r{/v1/contracts/[^/]+/}, "/v1/contracts/:name/")
+            .gsub(%r{/v1/executions/[^/]+}, "/v1/executions/:id")
+      end
+
+      def deep_freeze(hash)
+        hash.each_with_object({}) do |(name, by_label), memo|
+          memo[name] = by_label.each_with_object({}) do |(lkey, entry), inner|
+            inner[lkey] = {
+              labels: entry[:labels].dup.freeze,
+              buckets: entry[:buckets].dup.freeze,
+              sum: entry[:sum],
+              count: entry[:count]
+            }.freeze
+          end.freeze
+        end.freeze
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/metrics/prometheus_exporter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Metrics
+    # Formats a Collector snapshot into Prometheus text exposition format (0.0.4).
+    #
+    # https://prometheus.io/docs/instrumenting/exposition_formats/
+    #
+    # Usage:
+    #   exporter = PrometheusExporter.new(collector, store: store, registry: registry)
+    #   text = exporter.export          # → String in Prometheus text format
+    #   content_type = exporter.content_type
+    class PrometheusExporter
+      CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+      COUNTER_META = {
+        "igniter_executions_total" =>
+          "Total contract executions completed",
+        "igniter_http_requests_total" =>
+          "Total HTTP requests received by igniter-stack"
+      }.freeze
+
+      HISTOGRAM_META = {
+        "igniter_execution_duration_seconds" =>
+          "Contract execution duration in seconds",
+        "igniter_http_request_duration_seconds" =>
+          "HTTP request processing duration in seconds"
+      }.freeze
+
+      def initialize(collector, store:, registry:)
+        @collector = collector
+        @store     = store
+        @registry  = registry
+      end
+
+      def content_type
+        CONTENT_TYPE
+      end
+
+      def export # rubocop:disable Metrics/MethodLength
+        snap  = @collector.snapshot
+        lines = []
+
+        emit_counters(lines, snap.counters)
+        emit_histograms(lines, snap.histograms)
+        emit_pending_gauge(lines)
+
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def emit_counters(lines, counters) # rubocop:disable Metrics/MethodLength
+        by_metric = counters.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(key, val), memo|
+          name = key.split("{").first
+          memo[name] << [key, val]
+        end
+
+        by_metric.each do |name, entries|
+          lines << "# HELP #{name} #{COUNTER_META.fetch(name, name)}"
+          lines << "# TYPE #{name} counter"
+          entries.each { |key, val| lines << "#{key} #{val}" }
+          lines << ""
+        end
+      end
+
+      def emit_histograms(lines, histograms)
+        histograms.each do |name, by_label|
+          lines << "# HELP #{name} #{HISTOGRAM_META.fetch(name, name)}"
+          lines << "# TYPE #{name} histogram"
+          by_label.each_value { |entry| emit_histogram_entry(lines, name, entry) }
+          lines << ""
+        end
+      end
+
+      def emit_histogram_entry(lines, name, entry) # rubocop:disable Metrics/MethodLength
+        lstr = entry[:labels].map { |k, v| "#{k}=\"#{v}\"" }.join(",")
+        sep  = lstr.empty? ? "" : ","
+
+        Collector::HISTOGRAM_BUCKETS.each do |b|
+          le = b.to_s
+          lines << "#{name}_bucket{#{lstr}#{sep}le=\"#{le}\"} #{entry[:buckets][b]}"
+        end
+        lines << "#{name}_bucket{#{lstr}#{sep}le=\"+Inf\"} #{entry[:count]}"
+        lines << "#{name}_sum{#{lstr}} #{format("%.6f", entry[:sum])}"
+        lines << "#{name}_count{#{lstr}} #{entry[:count]}"
+      end
+
+      def emit_pending_gauge(lines) # rubocop:disable Metrics/MethodLength
+        lines << "# HELP igniter_pending_executions Currently pending executions in store"
+        lines << "# TYPE igniter_pending_executions gauge"
+
+        @registry.names.each do |name|
+          count = @store.list_pending(graph: name).size
+          lines << "igniter_pending_executions{graph=\"#{name}\"} #{count}"
+        rescue StandardError
+          lines << "igniter_pending_executions{graph=\"#{name}\"} 0"
+        end
+
+        lines << ""
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/metrics/snapshot.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Metrics
+    # Immutable snapshot of collected metrics, safe to read from any thread.
+    Snapshot = Struct.new(:counters, :histograms, keyword_init: true)
+  end
+end

data/packages/igniter-core/lib/igniter/core/metrics.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "metrics/snapshot"
+require_relative "metrics/collector"
+require_relative "metrics/prometheus_exporter"
+
+module Igniter
+  # Metrics collection for Igniter contracts and igniter-stack.
+  #
+  # The Collector subscribes to an Igniter::Events::Bus and maintains
+  # in-memory counters and histograms with zero external dependencies.
+  #
+  # Prometheus text format is exported via PrometheusExporter — usable
+  # directly in the /v1/metrics endpoint of igniter-stack.
+  #
+  # Usage (standalone):
+  #   require "igniter/core/metrics"
+  #
+  #   collector = Igniter::Metrics::Collector.new
+  #   contract.execution.events.subscribe(collector)
+  #   contract.resolve_all
+  #
+  #   exporter = Igniter::Metrics::PrometheusExporter.new(
+  #     collector, store: store, registry: registry
+  #   )
+  #   puts exporter.export
+  #
+  # Usage (igniter-stack — automatic when metrics_collector is set):
+  #   Igniter::Server.configure do |c|
+  #     c.metrics_collector = Igniter::Metrics::Collector.new
+  #   end
+  #
+  module Metrics
+    class MetricsError < Igniter::Error; end
+  end
+end

data/packages/igniter-core/lib/igniter/core/model/agent_interaction_contract.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    class AgentInteractionContract
+      SYMBOL_LIST_KEYS = RemoteNode::SYMBOL_LIST_KEYS
+      SYMBOL_SCALAR_KEYS = RemoteNode::SYMBOL_SCALAR_KEYS
+
+      MODES = %i[call cast].freeze
+      REPLY_MODES = %i[single deferred stream none].freeze
+      TOOL_LOOP_POLICIES = %i[ignore resolved complete].freeze
+      SESSION_POLICIES = %i[interactive single_turn manual].freeze
+      ROUTING_MODES = %i[local static capability pinned].freeze
+
+      attr_reader :mode, :reply_mode, :finalizer, :tool_loop_policy, :session_policy,
+                  :node_url, :capability, :capability_query, :pinned_to
+
+      def initialize(mode: :call, reply_mode: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil,
+                     node_url: nil, capability: nil, capability_query: nil, pinned_to: nil)
+        @mode = normalize_mode(mode)
+        @reply_mode = normalize_reply_mode(reply_mode || default_reply_mode(@mode))
+        @finalizer = normalize_finalizer(finalizer || default_finalizer(@reply_mode))
+        @tool_loop_policy = normalize_tool_loop_policy(tool_loop_policy || default_tool_loop_policy(@reply_mode))
+        @session_policy = normalize_session_policy(session_policy || default_session_policy(@reply_mode))
+        @node_url = node_url&.to_s
+        @capability = capability&.to_sym
+        @capability_query = normalize_query(capability_query)
+        @pinned_to = pinned_to&.to_s
+        freeze
+      end
+
+      def routing_mode
+        return :pinned if pinned?
+        return :capability if capability_routed?
+        return :static if static?
+
+        :local
+      end
+
+      def call?
+        mode == :call
+      end
+
+      def cast?
+        mode == :cast
+      end
+
+      def streaming?
+        reply_mode == :stream
+      end
+
+      def static?
+        !node_url.nil? && !node_url.empty?
+      end
+
+      def capability_routed?
+        !capability.nil? || !capability_query.nil?
+      end
+
+      def pinned?
+        !pinned_to.nil? && !pinned_to.empty?
+      end
+
+      def to_h
+        payload = {
+          mode: mode,
+          routing_mode: routing_mode,
+          reply: reply_mode,
+          finalizer: serialized_finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy
+        }
+        payload[:node] = node_url if routing_mode == :static
+        payload[:capability] = capability if capability
+        payload[:query] = capability_query if capability_query
+        payload[:pinned_to] = pinned_to if pinned_to
+        payload.freeze
+      end
+
+      private
+
+      def normalize_mode(mode)
+        return mode.to_sym if mode.is_a?(String) || mode.is_a?(Symbol)
+
+        mode
+      end
+
+      def normalize_reply_mode(reply_mode)
+        return reply_mode.to_sym if reply_mode.is_a?(String) || reply_mode.is_a?(Symbol)
+
+        reply_mode
+      end
+
+      def default_reply_mode(mode)
+        mode == :cast ? :none : :deferred
+      end
+
+      def normalize_finalizer(finalizer)
+        return finalizer.to_sym if finalizer.is_a?(String) || finalizer.is_a?(Symbol)
+
+        finalizer
+      end
+
+      def default_finalizer(reply_mode)
+        reply_mode == :stream ? :join : nil
+      end
+
+      def normalize_tool_loop_policy(tool_loop_policy)
+        return tool_loop_policy.to_sym if tool_loop_policy.is_a?(String) || tool_loop_policy.is_a?(Symbol)
+
+        tool_loop_policy
+      end
+
+      def default_tool_loop_policy(reply_mode)
+        reply_mode == :stream ? :complete : nil
+      end
+
+      def normalize_session_policy(session_policy)
+        return session_policy.to_sym if session_policy.is_a?(String) || session_policy.is_a?(Symbol)
+
+        session_policy
+      end
+
+      def default_session_policy(reply_mode)
+        reply_mode == :stream ? :interactive : nil
+      end
+
+      def normalize_query(query)
+        case query
+        when nil
+          nil
+        when Symbol, String
+          { all_of: [query.to_sym] }.freeze
+        when Array
+          { all_of: query.map(&:to_sym).freeze }.freeze
+        when Hash
+          normalize_query_hash(query).freeze
+        else
+          query
+        end
+      end
+
+      def normalize_query_hash(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          normalized_key = key.to_sym
+          memo[normalized_key] = normalize_query_value(normalized_key, value)
+        end
+      end
+
+      def normalize_query_value(key, value)
+        if SYMBOL_LIST_KEYS.include?(key)
+          Array(value).map { |item| item.is_a?(String) || item.is_a?(Symbol) ? item.to_sym : item }.freeze
+        elsif SYMBOL_SCALAR_KEYS.include?(key) && (value.is_a?(String) || value.is_a?(Symbol))
+          value.to_sym
+        elsif value.is_a?(Hash)
+          normalize_query_hash(value).freeze
+        elsif value.is_a?(Array)
+          value.map { |item| item.is_a?(Hash) ? normalize_query_hash(item).freeze : item }.freeze
+        else
+          value
+        end
+      end
+
+      def serialized_finalizer
+        return nil if finalizer.nil?
+        return finalizer if finalizer.is_a?(Symbol)
+
+        :proc
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/model/agent_node.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a graph node that delegates work to a long-lived agent.
+    #
+    # The node itself is part of the contract graph. Delivery and lookup are
+    # delegated to a runtime adapter so core stays independent from any specific
+    # actor runtime implementation or registry strategy.
+    class AgentNode < Node
+      attr_reader :agent_name, :message_name, :input_mapping, :timeout, :mode,
+                  :interaction_contract
+
+      def initialize(id:, name:, agent_name:, message_name:, input_mapping:, timeout: 5, mode: :call, reply_mode: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil, node_url: nil, capability: nil, capability_query: nil, pinned_to: nil, path: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        super(
+          id: id,
+          kind: :agent,
+          name: name,
+          path: path || name.to_s,
+          dependencies: input_mapping.values.map(&:to_sym),
+          metadata: metadata
+        )
+        @agent_name = normalize_agent_name(agent_name)
+        @message_name = message_name.to_sym
+        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @timeout = Float(timeout)
+        @interaction_contract = AgentInteractionContract.new(
+          mode: mode,
+          reply_mode: reply_mode,
+          finalizer: finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy,
+          node_url: node_url,
+          capability: capability,
+          capability_query: capability_query,
+          pinned_to: pinned_to
+        )
+        @mode = @interaction_contract.mode
+      end
+
+      def routing_mode
+        interaction_contract.routing_mode
+      end
+
+      def reply_mode
+        interaction_contract.reply_mode
+      end
+
+      def finalizer
+        interaction_contract.finalizer
+      end
+
+      def tool_loop_policy
+        interaction_contract.tool_loop_policy
+      end
+
+      def session_policy
+        interaction_contract.session_policy
+      end
+
+      def node_url
+        interaction_contract.node_url
+      end
+
+      def capability
+        interaction_contract.capability
+      end
+
+      def capability_query
+        interaction_contract.capability_query
+      end
+
+      def pinned_to
+        interaction_contract.pinned_to
+      end
+
+      private
+
+      def normalize_agent_name(agent_name)
+        return agent_name.to_sym if agent_name.is_a?(String) || agent_name.is_a?(Symbol)
+
+        agent_name
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/model/aggregate_node.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a maintained aggregate node in the computation graph.
+    #
+    # An AggregateNode computes an aggregate value over an incremental collection
+    # and updates it in O(change) time by processing only the diff (added/changed/removed
+    # items) rather than iterating over the entire collection on every resolve.
+    #
+    # Supported built-in operators: :count, :sum, :avg, :min, :max, :group_count.
+    # Custom aggregates can be defined with initial:, add:, and remove: lambdas.
+    #
+    # The aggregate node depends on exactly one upstream incremental collection node.
+    # The compiler validates this at definition time.
+    class AggregateNode < Node
+      attr_reader :source_collection, :operator
+
+      def initialize(id:, name:, source_collection:, operator:, # rubocop:disable Metrics/ParameterLists
+                     path: nil, metadata: {})
+        super(
+          id: id,
+          kind: :aggregate,
+          name: name,
+          path: path || name.to_s,
+          dependencies: [source_collection],
+          metadata: metadata
+        )
+        @source_collection = source_collection.to_sym
+        @operator = operator
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/model/branch_node.rb

@@ -29,6 +29,16 @@ module Igniter
         (cases.map { |entry| entry[:contract] } + [default_contract]).uniq
       end
 
+      def match_case(selector_value)
+        cases.find { |entry| case_matches?(entry, selector_value) }
+      end
+
+      def case_payload(entry)
+        return entry[:value] if entry[:matcher] == :eq
+
+        entry[:value].inspect
+      end
+
       def input_mapper?
         !input_mapper.nil?
       end
@@ -36,11 +46,37 @@ module Igniter
       private
 
       def normalize_case(entry)
+        matcher = (entry[:matcher] || :eq).to_sym
+        value = entry.key?(:value) ? entry[:value] : entry[:match]
+
         {
-          match: entry.fetch(:match),
+          matcher: matcher,
+          value: normalize_case_value(matcher, value),
           contract: entry.fetch(:contract)
         }
       end
+
+      def normalize_case_value(matcher, value)
+        case matcher
+        when :in
+          Array(value).freeze
+        else
+          value
+        end
+      end
+
+      def case_matches?(entry, selector_value)
+        case entry[:matcher]
+        when :eq
+          entry[:value] == selector_value
+        when :in
+          entry[:value].include?(selector_value)
+        when :matches
+          entry[:value].match?(selector_value.to_s)
+        else
+          false
+        end
+      end
     end
   end
 end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/model/collection_node.rb

@@ -3,9 +3,9 @@
 module Igniter
   module Model
     class CollectionNode < Node
-      attr_reader :source_dependency, :contract_class, :key_name, :mode, :context_dependencies, :input_mapper
+      attr_reader :source_dependency, :contract_class, :key_name, :mode, :window, :context_dependencies, :input_mapper
 
-      def initialize(id:, name:, source_dependency:, contract_class:, key_name:, mode:, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
+      def initialize(id:, name:, source_dependency:, contract_class:, key_name:, mode:, window: nil, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
         super(
           id: id,
           kind: :collection,
@@ -19,6 +19,7 @@ module Igniter
         @contract_class = contract_class
         @key_name = key_name.to_sym
         @mode = mode.to_sym
+        @window = window
         @context_dependencies = Array(context_dependencies).map(&:to_sym)
         @input_mapper = input_mapper
       end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/model/compute_node.rb

@@ -57,6 +57,19 @@ module Igniter
         metadata[:type] || executor_metadata[:type]
       end
 
+      # Seconds to cache this node's result across executions (nil = no TTL cache).
+      # Requires Igniter::NodeCache.cache to be configured.
+      def cache_ttl
+        metadata[:cache_ttl]
+      end
+
+      # When true, concurrent executions with identical dep fingerprints share one
+      # computation (the follower waits for the leader's result).
+      # Requires Igniter::NodeCache.coalescing_lock to be configured.
+      def coalesce?
+        metadata[:coalesce] == true
+      end
+
       def const?
         metadata[:kind] == :const
       end