igniter 0.4.5 → 0.5.1

data/packages/igniter-core/lib/igniter/core/compiler/validators/agent_validator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class AgentValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          @context.runtime_nodes.each do |node|
+            next unless node.kind == :agent
+
+            validate_agent_name!(node)
+            validate_message_name!(node)
+            validate_timeout!(node)
+            validate_mode!(node)
+            validate_reply_mode!(node)
+            validate_finalizer!(node)
+            validate_tool_loop_policy!(node)
+            validate_session_policy!(node)
+            validate_routing!(node)
+          end
+        end
+
+        private
+
+        def validate_agent_name!(node)
+          return unless node.agent_name.to_s.strip.empty?
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} requires a non-empty via:"
+          )
+        end
+
+        def validate_message_name!(node)
+          return unless node.message_name.to_s.strip.empty?
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} requires a non-empty message:"
+          )
+        end
+
+        def validate_timeout!(node)
+          return if node.timeout.positive?
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} timeout must be positive"
+          )
+        end
+
+        def validate_mode!(node)
+          return if Model::AgentInteractionContract::MODES.include?(node.mode)
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} mode must be :call or :cast"
+          )
+        end
+
+        def validate_reply_mode!(node)
+          unless Model::AgentInteractionContract::REPLY_MODES.include?(node.reply_mode)
+            raise @context.validation_error(
+              node,
+              "agent :#{node.name} reply must be :single, :deferred, :stream, or :none"
+            )
+          end
+
+          return unless node.mode == :cast && node.reply_mode != :none
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} mode :cast only supports reply: :none"
+          )
+        end
+
+        def validate_finalizer!(node)
+          return if node.finalizer.nil?
+          return if node.reply_mode == :stream
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} finalizer requires reply: :stream"
+          )
+        end
+
+        def validate_tool_loop_policy!(node)
+          return if node.tool_loop_policy.nil?
+
+          unless Model::AgentInteractionContract::TOOL_LOOP_POLICIES.include?(node.tool_loop_policy)
+            raise @context.validation_error(
+              node,
+              "agent :#{node.name} tool_loop_policy must be :ignore, :resolved, or :complete"
+            )
+          end
+
+          return if node.reply_mode == :stream
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} tool_loop_policy requires reply: :stream"
+          )
+        end
+
+        def validate_session_policy!(node)
+          return if node.session_policy.nil?
+
+          unless Model::AgentInteractionContract::SESSION_POLICIES.include?(node.session_policy)
+            raise @context.validation_error(
+              node,
+              "agent :#{node.name} session_policy must be :interactive, :single_turn, or :manual"
+            )
+          end
+
+          return if node.reply_mode == :stream
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} session_policy requires reply: :stream"
+          )
+        end
+
+        def validate_routing!(node)
+          return if Model::AgentInteractionContract::ROUTING_MODES.include?(node.routing_mode)
+
+          raise @context.validation_error(
+            node,
+            "agent :#{node.name} routing mode must be :local, :static, :capability, or :pinned"
+          )
+        end
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/compiler/validators/dependencies_validator.rb

@@ -19,6 +19,7 @@ module Igniter
             validate_composition_node!(node) if node.kind == :composition
             validate_branch_node!(node) if node.kind == :branch
             validate_collection_node!(node) if node.kind == :collection
+            validate_aggregate_node!(node)   if node.kind == :aggregate
 
             node.dependencies.each do |dependency_name|
               next if @context.dependency_resolvable?(dependency_name)
@@ -83,7 +84,13 @@ module Igniter
           raise @context.validation_error(node, "Branch '#{node.name}' must define at least one `on` case") if node.cases.empty?
           raise @context.validation_error(node, "Branch '#{node.name}' must define a `default` contract") unless node.default_contract
 
-          duplicate_matches = node.cases.group_by { |entry| entry[:match] }.select { |_match, entries| entries.size > 1 }.keys
+          validate_branch_case_matchers!(node)
+
+          duplicate_matches = node.cases
+            .flat_map { |entry| exact_branch_values(entry) }
+            .group_by(&:itself)
+            .select { |_match, entries| entries.size > 1 }
+            .keys
           return if duplicate_matches.empty?
 
           raise @context.validation_error(
@@ -92,6 +99,39 @@ module Igniter
           )
         end
 
+        def validate_branch_case_matchers!(node)
+          node.cases.each do |entry|
+            case entry[:matcher]
+            when :eq
+              next
+            when :in
+              unless entry[:value].is_a?(Array) && !entry[:value].empty?
+                raise @context.validation_error(node, "Branch '#{node.name}' `in:` cases must use a non-empty Array")
+              end
+            when :matches
+              unless entry[:value].is_a?(Regexp)
+                raise @context.validation_error(node, "Branch '#{node.name}' `matches:` cases must use a Regexp")
+              end
+            else
+              raise @context.validation_error(
+                node,
+                "Branch '#{node.name}' has unsupported matcher #{entry[:matcher].inspect}; use `eq:`, `in:`, or `matches:`"
+              )
+            end
+          end
+        end
+
+        def exact_branch_values(entry)
+          case entry[:matcher]
+          when :eq
+            [entry[:value]]
+          when :in
+            entry[:value]
+          else
+            []
+          end
+        end
+
         def validate_branch_contract!(node, contract_class)
           unless contract_class.is_a?(Class) && contract_class <= Igniter::Contract
             raise @context.validation_error(node, "Branch '#{node.name}' must reference Igniter::Contract subclasses")
@@ -175,10 +215,12 @@ module Igniter
             raise @context.validation_error(node, "Collection '#{node.name}' references an uncompiled contract")
           end
 
-          unless %i[collect fail_fast].include?(node.mode)
-            raise @context.validation_error(node, "Collection '#{node.name}' mode must be `:collect` or `:fail_fast`")
+          unless %i[collect fail_fast incremental].include?(node.mode)
+            raise @context.validation_error(node, "Collection '#{node.name}' mode must be `:collect`, `:fail_fast`, or `:incremental`")
           end
 
+          validate_window_option!(node) if node.window
+
           child_input_names = node.contract_class.compiled_graph.nodes.select { |child_node| child_node.kind == :input }.map(&:name)
           return if child_input_names.include?(node.key_name)
 
@@ -187,6 +229,51 @@ module Igniter
             "Collection '#{node.name}' key '#{node.key_name}' must be a child contract input"
           )
         end
+
+        def validate_window_option!(node) # rubocop:disable Metrics/MethodLength
+          window = node.window
+          unless window.is_a?(Hash)
+            raise @context.validation_error(node, "Collection '#{node.name}' window: must be a Hash")
+          end
+
+          if window.key?(:last)
+            unless window[:last].is_a?(Integer) && window[:last].positive?
+              raise @context.validation_error(node, "Collection '#{node.name}' window: { last: } must be a positive Integer")
+            end
+          elsif window.key?(:seconds)
+            unless window.key?(:field)
+              raise @context.validation_error(node, "Collection '#{node.name}' window: { seconds: } requires a :field key")
+            end
+          else
+            raise @context.validation_error(node, "Collection '#{node.name}' window: must use :last or :seconds")
+          end
+        end
+
+        def validate_aggregate_node!(node)
+          source_sym = node.source_collection
+          source = @context.runtime_nodes.find { |n| n.name == source_sym }
+
+          unless source
+            raise @context.validation_error(
+              node,
+              "Aggregate '#{node.name}' references unknown collection '#{source_sym}'"
+            )
+          end
+
+          unless source.kind == :collection
+            raise @context.validation_error(
+              node,
+              "Aggregate '#{node.name}': source '#{source_sym}' must be a collection node, got :#{source.kind}"
+            )
+          end
+
+          return if source.mode == :incremental
+
+          raise @context.validation_error(
+            node,
+            "Aggregate '#{node.name}': source '#{source_sym}' must use mode: :incremental"
+          )
+        end
       end
     end
   end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/compiler/validators/remote_validator.rb

@@ -25,6 +25,8 @@ module Igniter
         private
 
         def validate_url!(node)
+          return if node.routing_mode != :static
+
           return if node.node_url.start_with?("http://", "https://")
 
           raise @context.validation_error(

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

@@ -9,6 +9,7 @@ require_relative "compiler/validators/dependencies_validator"
 require_relative "compiler/validators/callable_validator"
 require_relative "compiler/validators/type_compatibility_validator"
 require_relative "compiler/validators/await_validator"
+require_relative "compiler/validators/agent_validator"
 require_relative "compiler/validators/remote_validator"
 require_relative "compiler/validation_pipeline"
 require_relative "compiler/validator"

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Igniter
+  # Content-addressed computation cache for pure executors.
+  #
+  # When an executor is declared `pure`, its output is fully determined by:
+  #   1. The executor's content fingerprint (class name or explicit version string)
+  #   2. The serialized dependency values
+  #
+  # The content key is SHA-256(fingerprint + serialized_deps), truncated to 24 hex chars.
+  # This key is used as a universal cache key — valid across executions, processes, and nodes.
+  #
+  # == Usage
+  #
+  #   require "igniter/extensions/content_addressing"
+  #
+  #   class TaxCalculator < Igniter::Executor
+  #     pure                           # enables content-addressed caching
+  #     fingerprint "tax_calc_v1"      # optional explicit version (invalidates cache on bump)
+  #
+  #     def call(country:, amount:)
+  #       TAX_RATES[country] * amount  # deterministic — same inputs, same output
+  #     end
+  #   end
+  #
+  # On first call with a given (country, amount) pair, the result is computed and cached.
+  # Subsequent calls (even in different executions) return the cached value instantly.
+  #
+  # == Shared cache (distributed nodes)
+  #
+  # Replace the default in-process cache with a Redis-backed one:
+  #
+  #   Igniter::ContentAddressing.cache = MyRedisContentCache.new(redis: Redis.new)
+  #   # Must implement: #fetch(key) → value | nil, #store(key, value)
+  module ContentAddressing
+    # Immutable content key derived from executor fingerprint + serialized dep values.
+    class ContentKey
+      attr_reader :hex
+
+      def initialize(hex)
+        @hex = hex.freeze
+        freeze
+      end
+
+      def to_s    = "ca:#{@hex}"
+      def inspect = "#<ContentKey #{self}>"
+      def ==(other) = other.is_a?(ContentKey) && other.hex == hex
+
+      class << self
+        # Compute a ContentKey from an executor class and its resolved dependency values.
+        def compute(executor_class, dep_values)
+          fp   = executor_class.content_fingerprint
+          deps = stable_serialize(dep_values)
+          hex  = Digest::SHA256.hexdigest("#{fp}\x00#{deps}")[0..23]
+          new(hex)
+        end
+
+        private
+
+        # Serialize a value to a stable, order-independent string.
+        # Used as part of the content key — must produce identical output for equal values.
+        def stable_serialize(val) # rubocop:disable Metrics/CyclomaticComplexity
+          case val
+          when Hash
+            pairs = val.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}:#{stable_serialize(v)}" }
+            "{#{pairs.join(",")}}"
+          when Array  then "[#{val.map { |v| stable_serialize(v) }.join(",")}]"
+          when String then val.inspect
+          when Symbol then ":#{val}"
+          when Numeric, NilClass, TrueClass, FalseClass then val.inspect
+          else val.hash.to_s
+          end
+        end
+      end
+    end
+
+    # Thread-safe in-process content cache.
+    # Replace with a distributed implementation to share results across nodes.
+    class Cache
+      def initialize
+        @store  = {}
+        @mu     = Mutex.new
+        @hits   = 0
+        @misses = 0
+      end
+
+      # Retrieve a cached value. Returns nil on miss.
+      def fetch(key)
+        @mu.synchronize do
+          val = @store[key.hex]
+          if val.nil?
+            @misses += 1
+            nil
+          else
+            @hits += 1
+            val
+          end
+        end
+      end
+
+      # Store a value under the given content key.
+      def store(key, value)
+        @mu.synchronize { @store[key.hex] = value }
+      end
+
+      def size = @mu.synchronize { @store.size }
+
+      def clear
+        @mu.synchronize do
+          @store.clear
+          @hits = 0
+          @misses = 0
+        end
+      end
+
+      def stats
+        @mu.synchronize { { size: @store.size, hits: @hits, misses: @misses } }
+      end
+    end
+
+    class << self
+      # Global content cache. Default: thread-safe in-process Hash.
+      # Can be replaced with any object responding to #fetch(key) and #store(key, value).
+      attr_writer :cache
+
+      def cache
+        @cache ||= Cache.new
+      end
+    end
+  end
+end

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

@@ -19,13 +19,50 @@ module Igniter
         )
       end
 
-      def run_with(runner:, max_workers: nil)
-        @execution_options = { runner: runner, max_workers: max_workers }.compact
+      def run_with(runner:, max_workers: nil, **opts)
+        @execution_options = { runner: runner, max_workers: max_workers }.merge(opts).compact
+      end
+
+      # Ergonomic alias for run_with. Accepts pool_size: as a clearer name for
+      # max_workers: when using the thread_pool runner.
+      #
+      #   class MyContract < Igniter::Contract
+      #     runner :thread_pool, pool_size: 4
+      #     define do ... end
+      #   end
+      def runner(strategy, pool_size: nil, max_workers: nil, **opts)
+        workers = pool_size || max_workers
+        @execution_options = { runner: strategy, max_workers: workers }.merge(opts).compact
       end
 
       def restore_from_store(execution_id, store: nil)
-        snapshot = (store || Igniter.execution_store).fetch(execution_id)
-        restore(snapshot)
+        resolved_store = store || Igniter.execution_store
+        snapshot = resolved_store.fetch(execution_id)
+        restore(snapshot, store: resolved_store)
+      end
+
+      def agent_session_query_from_store(execution_id, store: nil)
+        restore_from_store(execution_id, store: store).execution.agent_session_query
+      end
+
+      def agent_session_summary_from_store(execution_id, store: nil)
+        agent_session_query_from_store(execution_id, store: store).summary
+      end
+
+      def orchestration_overview_from_store(execution_id, store: nil)
+        restore_from_store(execution_id, store: store).execution.orchestration_overview
+      end
+
+      def orchestration_summary_from_store(execution_id, store: nil)
+        orchestration_overview_from_store(execution_id, store: store)[:summary]
+      end
+
+      def orchestration_transition_overview_from_store(execution_id, store: nil, limit: 20)
+        restore_from_store(execution_id, store: store).execution.orchestration_transition_overview(limit: limit)
+      end
+
+      def orchestration_transition_summary_from_store(execution_id, store: nil)
+        restore_from_store(execution_id, store: store).execution.orchestration_transition_summary
       end
 
       def resume_from_store(execution_id, token:, value:, store: nil)
@@ -36,6 +73,30 @@ module Igniter
         )
       end
 
+      def resume_agent_session_from_store(execution_id, session:, node_name: nil, value: Runtime::Execution::UNDEFINED_RESUME_VALUE, store: nil)
+        Runtime::JobWorker.new(self, store: store || Igniter.execution_store).resume_agent_session(
+          execution_id: execution_id,
+          session: session,
+          node_name: node_name,
+          value: value
+        )
+      end
+
+      def continue_agent_session_from_store(execution_id, session:, payload:, trace: nil, token: nil, waiting_on: nil,
+                                            request: nil, reply: nil, phase: nil, store: nil)
+        Runtime::JobWorker.new(self, store: store || Igniter.execution_store).continue_agent_session(
+          execution_id: execution_id,
+          session: session,
+          payload: payload,
+          trace: trace,
+          token: token,
+          waiting_on: waiting_on,
+          request: request,
+          reply: reply,
+          phase: phase
+        )
+      end
+
       def define_schema(schema)
         @compiled_graph = DSL::SchemaBuilder.compile(schema, name: contract_name)
       end
@@ -79,11 +140,12 @@ module Igniter
         instance
       end
 
-      def restore(snapshot)
+      def restore(snapshot, store: nil)
         instance = new(
           snapshot[:inputs] || snapshot["inputs"] || {},
           runner: snapshot[:runner] || snapshot["runner"],
-          max_workers: snapshot[:max_workers] || snapshot["max_workers"]
+          max_workers: snapshot[:max_workers] || snapshot["max_workers"],
+          store: store
         )
         instance.restore_execution(snapshot)
       end
@@ -301,6 +363,26 @@ module Igniter
       execution.explain_plan(output_names)
     end
 
+    def orchestration_plan(output_names = nil)
+      execution.orchestration_plan(output_names)
+    end
+
+    def orchestration_overview(output_names = nil)
+      execution.orchestration_overview(output_names)
+    end
+
+    def orchestration_summary(output_names = nil)
+      execution.orchestration_summary(output_names)
+    end
+
+    def agent_session_query
+      execution.agent_session_query
+    end
+
+    def agent_session_summary
+      execution.agent_session_summary
+    end
+
     def success?
       execution.success?
     end

data/packages/igniter-core/lib/igniter/core/dataflow/aggregate_operators.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # Built-in operator strategies for AggregateNode.
+    #
+    # Each operator is an Operator struct with:
+    #   initial_fn  – Proc returning a fresh initial accumulator value
+    #   project     – Proc(item) → contribution  (what the item "contributes")
+    #   add         – Proc(acc, contribution) → new_acc  (nil when recompute: true)
+    #   remove      – Proc(acc, contribution) → new_acc  (nil when recompute: true)
+    #   finalize    – Proc(acc, contributions_or_count) → public value
+    #   recompute   – Boolean: when true, finalize receives the full @contributions Hash
+    #                 instead of @accum (used for min/max which aren't O(1)-retractable)
+    #
+    # == Built-ins
+    #
+    #   count(filter: nil)       — total items, optionally filtered
+    #   sum(projection:)         — sum a numeric value extracted per item
+    #   avg(projection:)         — running arithmetic mean
+    #   min(projection:)         — current minimum (O(n) on retraction)
+    #   max(projection:)         — current maximum (O(n) on retraction)
+    #   group_count(projection:) — {group_key => item_count}
+    #   custom(initial:, add:, remove:) — user-supplied retractable logic
+    #
+    module AggregateOperators
+      # Internal struct. Fields are callables (Proc) or primitives.
+      Operator = Struct.new(
+        :initial_fn, :project, :add, :remove, :finalize, :recompute,
+        keyword_init: true
+      ) do
+        # Returns a fresh initial accumulator for a new AggregateState.
+        def initial
+          initial_fn.call
+        end
+      end
+
+      # Count items, optionally filtered by a predicate.
+      #
+      # @param filter [Proc, nil]  ->(item) { true/false }; nil = count all
+      def self.count(filter: nil)
+        Operator.new(
+          initial_fn: -> { 0 },
+          project: ->(item) { filter.nil? || filter.call(item) ? 1 : 0 },
+          add: ->(acc, v) { acc + v },
+          remove: ->(acc, v) { acc - v },
+          finalize: ->(acc, _) { acc },
+          recompute: false
+        )
+      end
+
+      # Sum a numeric value extracted from each item.
+      #
+      # @param projection [Proc]  ->(item) { item.result.value.to_f }
+      def self.sum(projection:)
+        Operator.new(
+          initial_fn: -> { 0 },
+          project: ->(item) { projection.call(item).to_f },
+          add: ->(acc, v) { acc + v },
+          remove: ->(acc, v) { acc - v },
+          finalize: ->(acc, _) { acc },
+          recompute: false
+        )
+      end
+
+      # Running arithmetic mean.
+      #
+      # @param projection [Proc]  ->(item) { numeric }
+      def self.avg(projection:) # rubocop:disable Metrics/AbcSize
+        Operator.new(
+          initial_fn: -> { { sum: 0.0, count: 0 } },
+          project: ->(item) { projection.call(item).to_f },
+          add: ->(acc, v) { { sum: acc[:sum] + v, count: acc[:count] + 1 } },
+          remove: ->(acc, v) { { sum: acc[:sum] - v, count: acc[:count] - 1 } },
+          finalize: ->(acc, _) { acc[:count].zero? ? 0.0 : acc[:sum] / acc[:count] },
+          recompute: false
+        )
+      end
+
+      # Current minimum (O(n) rescan on item removal — n = window size).
+      #
+      # @param projection [Proc]  ->(item) { numeric }
+      def self.min(projection:)
+        Operator.new(
+          initial_fn: -> { nil },
+          project: ->(item) { projection.call(item) },
+          add: nil,
+          remove: nil,
+          finalize: ->(_acc, contribs) { contribs.values.min },
+          recompute: true
+        )
+      end
+
+      # Current maximum (O(n) rescan on item removal — n = window size).
+      #
+      # @param projection [Proc]  ->(item) { numeric }
+      def self.max(projection:)
+        Operator.new(
+          initial_fn: -> { nil },
+          project: ->(item) { projection.call(item) },
+          add: nil,
+          remove: nil,
+          finalize: ->(_acc, contribs) { contribs.values.max },
+          recompute: true
+        )
+      end
+
+      # Group items by a key and count members per group.
+      # Returns a Hash {group_key => count}.
+      #
+      # @param projection [Proc]  ->(item) { group_key }
+      def self.group_count(projection:) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        remove_fn = lambda do |acc, gk|
+          count = (acc[gk] || 1) - 1
+          count <= 0 ? acc.reject { |k, _| k == gk } : acc.merge(gk => count)
+        end
+        Operator.new(
+          initial_fn: -> { {} },
+          project: ->(item) { projection.call(item) },
+          add: ->(acc, gk) { acc.merge(gk => (acc[gk] || 0) + 1) },
+          remove: remove_fn,
+          finalize: ->(acc, _) { acc },
+          recompute: false
+        )
+      end
+
+      # Custom retractable aggregate with user-supplied logic.
+      #
+      # Both +add+ and +remove+ receive the full CollectionResult::Item so that
+      # users can reference +item.result.field+ in both lambdas.
+      #
+      # @param initial [Object]  initial accumulator value (cloned on each new Execution)
+      # @param add     [Proc]    ->(acc, item) { new_acc }
+      # @param remove  [Proc]    ->(acc, item) { new_acc }
+      def self.custom(initial:, add:, remove:)
+        Operator.new(
+          initial_fn: -> { initial },
+          project: ->(item) { item },
+          add: ->(acc, item) { add.call(acc, item) },
+          remove: ->(acc, item) { remove.call(acc, item) },
+          finalize: ->(acc, _) { acc },
+          recompute: false
+        )
+      end
+    end
+  end
+end