igniter 0.5.1 → 0.5.2

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

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

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

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

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

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

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

@@ -1,34 +0,0 @@
-# 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/packages/igniter-core/lib/igniter/core/model/await_node.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    class AwaitNode < Node
-      attr_reader :event_name
-
-      def initialize(id:, name:, event_name:, path: nil, metadata: {})
-        super(
-          id: id,
-          kind: :await,
-          name: name,
-          path: path || name.to_s,
-          dependencies: [],
-          metadata: metadata
-        )
-        @event_name = event_name.to_sym
-      end
-    end
-  end
-end

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

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    class BranchNode < Node
-      attr_reader :selector_dependency, :cases, :default_contract, :input_mapping, :context_dependencies, :input_mapper
-
-      def initialize(id:, name:, selector_dependency:, cases:, default_contract:, input_mapping:, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
-        dependencies = ([selector_dependency] + input_mapping.values + context_dependencies).uniq
-
-        super(
-          id: id,
-          kind: :branch,
-          name: name,
-          path: (path || name),
-          dependencies: dependencies,
-          metadata: metadata
-        )
-
-        @selector_dependency = selector_dependency.to_sym
-        @cases = cases.map { |entry| normalize_case(entry) }.freeze
-        @default_contract = default_contract
-        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
-        @context_dependencies = Array(context_dependencies).map(&:to_sym).freeze
-        @input_mapper = input_mapper
-      end
-
-      def possible_contracts
-        (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
-
-      private
-
-      def normalize_case(entry)
-        matcher = (entry[:matcher] || :eq).to_sym
-        value = entry.key?(:value) ? entry[:value] : entry[: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