igniter 0.4.5 → 0.5.1

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

@@ -96,10 +96,6 @@ module Igniter
         compute(name, with: from, call: callable, **{ category: :project }.merge(metadata))
       end
 
-      def aggregate(name, depends_on: nil, with: nil, call: nil, executor: nil, **metadata, &block)
-        compute(name, depends_on: depends_on, with: with, call: call, executor: executor, **{ category: :aggregate }.merge(metadata), &block)
-      end
-
       def guard(name, depends_on: nil, with: nil, call: nil, executor: nil, message: nil,
                 eq: UNDEFINED_GUARD_MATCHER, in: UNDEFINED_GUARD_MATCHER, matches: UNDEFINED_GUARD_MATCHER,
                 **metadata, &block)
@@ -210,7 +206,7 @@ module Igniter
         )
       end
 
-      def collection(name, with:, each:, key:, mode: :collect, depends_on: nil, map_inputs: nil, using: nil, **metadata)
+      def collection(name, with:, each:, key:, mode: :collect, window: nil, depends_on: nil, map_inputs: nil, using: nil, **metadata)
         raise CompileError, "collection :#{name} cannot use both `map_inputs:` and `using:`" if map_inputs && using
 
         add_node(
@@ -221,6 +217,7 @@ module Igniter
             contract_class: each,
             key_name: key,
             mode: mode,
+            window: window,
             context_dependencies: normalize_dependencies(depends_on: depends_on, with: nil),
             input_mapper: map_inputs || using,
             path: scoped_path(name),
@@ -229,10 +226,115 @@ module Igniter
         )
       end
 
-      def remote(name, contract:, node:, inputs:, timeout: 30, **metadata) # rubocop:disable Metrics/MethodLength
+      # Declares a maintained aggregate over an incremental collection node.
+      #
+      # The aggregate updates in O(change) time: only added/changed/removed items
+      # affect the result; unchanged items contribute zero work.
+      #
+      # @param name        [Symbol]  output name
+      # @param from        [Symbol]  name of an upstream incremental collection node
+      # @param count       [Proc, nil]  ->(item) { bool } — count items matching predicate (nil = count all)
+      # @param sum         [Proc, nil]  ->(item) { numeric }
+      # @param avg         [Proc, nil]  ->(item) { numeric }
+      # @param min         [Proc, nil]  ->(item) { numeric }  (O(n) on removal)
+      # @param max         [Proc, nil]  ->(item) { numeric }  (O(n) on removal)
+      # @param group_count [Proc, nil]  ->(item) { group_key } — Hash{key => count}
+      # @param initial     [Object, nil]  initial accumulator for custom aggregates
+      # @param add         [Proc, nil]  ->(acc, item) { new_acc } — custom add
+      # @param remove      [Proc, nil]  ->(acc, item) { new_acc } — custom remove
+      #
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+      def aggregate(name, from:, count: nil, sum: nil, avg: nil, min: nil, max: nil,
+                    group_count: nil, initial: nil, add: nil, remove: nil, **metadata)
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+        operator = build_aggregate_operator(
+          count: count, sum: sum, avg: avg, min: min, max: max,
+          group_count: group_count, initial: initial, add: add, remove: remove
+        )
+        add_node(
+          Model::AggregateNode.new(
+            id: next_id,
+            name: name,
+            source_collection: from,
+            operator: operator,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def remote(name, contract:, inputs:, node: nil, timeout: 30, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+                 capability: nil, query: nil, trust: nil, governance: nil, policy: nil, decision: nil, pinned_to: nil, **metadata)
         raise CompileError, "remote :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
         raise CompileError, "remote :#{name} requires a contract: name" if contract.nil? || contract.to_s.strip.empty?
-        raise CompileError, "remote :#{name} requires a node: URL"     if node.nil?    || node.to_s.strip.empty?
+
+        if [capability, query, pinned_to].count { |value| !value.nil? } > 1
+          raise CompileError, "remote :#{name}: capability:, query:, and pinned_to: are mutually exclusive"
+        end
+
+        if trust && pinned_to
+          raise CompileError, "remote :#{name}: trust: cannot be combined with pinned_to:"
+        end
+
+        if governance && pinned_to
+          raise CompileError, "remote :#{name}: governance: cannot be combined with pinned_to:"
+        end
+
+        if policy && pinned_to
+          raise CompileError, "remote :#{name}: policy: cannot be combined with pinned_to:"
+        end
+
+        if decision && pinned_to
+          raise CompileError, "remote :#{name}: decision: cannot be combined with pinned_to:"
+        end
+
+        if trust && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: trust: requires capability: or query:"
+        end
+
+        if governance && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: governance: requires capability: or query:"
+        end
+
+        if policy && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: policy: requires capability: or query:"
+        end
+
+        if decision && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: decision: requires capability: or query:"
+        end
+
+        if trust && query.is_a?(Hash) && query.key?(:trust)
+          raise CompileError, "remote :#{name}: trust: duplicates query[:trust]"
+        end
+
+        if governance && query.is_a?(Hash) && query.key?(:governance)
+          raise CompileError, "remote :#{name}: governance: duplicates query[:governance]"
+        end
+
+        if policy && query.is_a?(Hash) && query.key?(:policy)
+          raise CompileError, "remote :#{name}: policy: duplicates query[:policy]"
+        end
+
+        if decision && query.is_a?(Hash) && query.key?(:decision)
+          raise CompileError, "remote :#{name}: decision: duplicates query[:decision]"
+        end
+
+        if capability.nil? && query.nil? && pinned_to.nil? && (node.nil? || node.to_s.strip.empty?)
+          raise CompileError, "remote :#{name} requires a node: URL"
+        end
+
+        capability_query =
+          if trust || governance || policy || decision
+            base_query = query ? query.dup : { all_of: [capability] }
+            base_query[:trust] = trust if trust
+            base_query[:governance] = governance if governance
+            base_query[:policy] = policy if policy
+            base_query[:decision] = decision if decision
+            base_query
+          else
+            query
+          end
 
         add_node(
           Model::RemoteNode.new(
@@ -242,6 +344,78 @@ module Igniter
             node_url: node.to_s,
             input_mapping: inputs,
             timeout: timeout,
+            capability: (trust || governance || policy || decision) ? nil : capability,
+            capability_query: capability_query,
+            pinned_to: pinned_to,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def agent(name, via:, message:, inputs:, timeout: 5, mode: :call, reply: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil, node: nil, capability: nil, query: nil, pinned_to: nil, **metadata) # rubocop:disable Metrics/ParameterLists
+        normalized_mode = mode.respond_to?(:to_sym) ? mode.to_sym : mode
+        normalized_reply = reply.respond_to?(:to_sym) ? reply.to_sym : reply
+        normalized_finalizer = finalizer.respond_to?(:to_sym) ? finalizer.to_sym : finalizer
+        normalized_tool_loop_policy = tool_loop_policy.respond_to?(:to_sym) ? tool_loop_policy.to_sym : tool_loop_policy
+        normalized_session_policy = session_policy.respond_to?(:to_sym) ? session_policy.to_sym : session_policy
+
+        raise CompileError, "agent :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
+        raise CompileError, "agent :#{name} requires via:" if via.nil? || via.to_s.strip.empty?
+        raise CompileError, "agent :#{name} requires message:" if message.nil? || message.to_s.strip.empty?
+        raise CompileError, "agent :#{name} timeout must be positive" unless timeout.to_f.positive?
+        raise CompileError, "agent :#{name} mode must be :call or :cast" unless Model::AgentInteractionContract::MODES.include?(normalized_mode)
+        unless normalized_reply.nil? || Model::AgentInteractionContract::REPLY_MODES.include?(normalized_reply)
+          raise CompileError, "agent :#{name} reply must be :single, :deferred, :stream, or :none"
+        end
+        if normalized_mode == :cast && !normalized_reply.nil? && normalized_reply != :none
+          raise CompileError, "agent :#{name} mode :cast only supports reply: :none"
+        end
+        if normalized_mode == :call && normalized_reply == :none
+          raise CompileError, "agent :#{name} mode :call cannot use reply: :none"
+        end
+        if !normalized_finalizer.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} finalizer requires reply: :stream"
+        end
+        unless normalized_finalizer.nil? || normalized_finalizer.is_a?(Symbol) || normalized_finalizer.respond_to?(:call)
+          raise CompileError, "agent :#{name} finalizer must be a Symbol, String, or callable"
+        end
+        if !normalized_tool_loop_policy.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} tool_loop_policy requires reply: :stream"
+        end
+        unless normalized_tool_loop_policy.nil? || Model::AgentInteractionContract::TOOL_LOOP_POLICIES.include?(normalized_tool_loop_policy)
+          raise CompileError, "agent :#{name} tool_loop_policy must be :ignore, :resolved, or :complete"
+        end
+        if !normalized_session_policy.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} session_policy requires reply: :stream"
+        end
+        unless normalized_session_policy.nil? || Model::AgentInteractionContract::SESSION_POLICIES.include?(normalized_session_policy)
+          raise CompileError, "agent :#{name} session_policy must be :interactive, :single_turn, or :manual"
+        end
+        if [capability, query, pinned_to].count { |value| !value.nil? } > 1
+          raise CompileError, "agent :#{name}: capability:, query:, and pinned_to: are mutually exclusive"
+        end
+        if capability.nil? && query.nil? && pinned_to.nil? && !node.nil? && node.to_s.strip.empty?
+          raise CompileError, "agent :#{name} requires a non-empty node: URL"
+        end
+
+        add_node(
+          Model::AgentNode.new(
+            id: next_id,
+            name: name.to_sym,
+            agent_name: via,
+            message_name: message,
+            input_mapping: inputs,
+            timeout: timeout,
+            mode: normalized_mode,
+            reply_mode: normalized_reply,
+            finalizer: normalized_finalizer,
+            tool_loop_policy: normalized_tool_loop_policy,
+            session_policy: normalized_session_policy,
+            node_url: node,
+            capability: capability,
+            capability_query: query,
+            pinned_to: pinned_to,
             path: scoped_path(name),
             metadata: with_source_location(metadata)
           )
@@ -399,7 +573,29 @@ module Igniter
         "#{@scope_stack.join('.')}.output.#{name}"
       end
 
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def build_aggregate_operator(count:, sum:, avg:, min:, max:, group_count:, initial:, add:, remove:)
+        if add && remove
+          Dataflow::AggregateOperators.custom(initial: initial || 0, add: add, remove: remove)
+        elsif sum
+          Dataflow::AggregateOperators.sum(projection: sum)
+        elsif avg
+          Dataflow::AggregateOperators.avg(projection: avg)
+        elsif min
+          Dataflow::AggregateOperators.min(projection: min)
+        elsif max
+          Dataflow::AggregateOperators.max(projection: max)
+        elsif group_count
+          Dataflow::AggregateOperators.group_count(projection: group_count)
+        else
+          Dataflow::AggregateOperators.count(filter: count)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
       class BranchBuilder
+        UNDEFINED_BRANCH_MATCHER = :__igniter_branch_matcher_undefined__
+
         def self.build(&block)
           new.tap { |builder| builder.instance_eval(&block) }.to_h
         end
@@ -409,8 +605,33 @@ module Igniter
           @default_contract = nil
         end
 
-        def on(match, contract:)
-          @cases << { match: match, contract: contract }
+        def on(match = UNDEFINED_BRANCH_MATCHER, contract:, eq: UNDEFINED_BRANCH_MATCHER, in: UNDEFINED_BRANCH_MATCHER, matches: UNDEFINED_BRANCH_MATCHER) # rubocop:disable Metrics/ParameterLists
+          matcher_options = {
+            eq: eq,
+            in: binding.local_variable_get(:in),
+            matches: matches
+          }.reject { |_key, value| value == UNDEFINED_BRANCH_MATCHER }
+
+          if match != UNDEFINED_BRANCH_MATCHER && matcher_options.any?
+            raise CompileError, "branch `on` cannot combine a positional match with `eq:`, `in:`, or `matches:`"
+          end
+
+          if match == UNDEFINED_BRANCH_MATCHER && matcher_options.empty?
+            raise CompileError, "branch `on` requires a positional match or one of `eq:`, `in:`, or `matches:`"
+          end
+
+          if matcher_options.size > 1
+            raise CompileError, "branch `on` supports only one matcher option at a time"
+          end
+
+          matcher, value =
+            if match != UNDEFINED_BRANCH_MATCHER
+              [:eq, match]
+            else
+              matcher_options.first
+            end
+
+          @cases << { matcher: matcher, value: value, contract: contract }
         end
 
         def default(contract:)

data/packages/igniter-core/lib/igniter/core/dto/record.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Igniter
+  module DTO
+    class Record
+      UNSET = Object.new
+
+      class << self
+        def field(name, required: false, allow_nil: !required, default: UNSET, coerce: nil, merge: false)
+          local_fields[name.to_sym] = {
+            name: name.to_sym,
+            required: required,
+            allow_nil: allow_nil,
+            default: default,
+            coerce: coerce,
+            merge: merge
+          }.freeze
+
+          attr_reader name unless method_defined?(name)
+        end
+
+        def from_h(attributes)
+          new(**normalize_input_attributes(attributes))
+        end
+
+        def dto_fields
+          inherited_fields.merge(local_fields)
+        end
+
+        def field_names
+          dto_fields.keys.freeze
+        end
+
+        private
+
+        def inherited_fields
+          return {} unless superclass.respond_to?(:dto_fields)
+
+          superclass.dto_fields
+        end
+
+        def local_fields
+          @local_fields ||= {}
+        end
+
+        def normalize_input_attributes(attributes)
+          symbolize_hash(attributes || {})
+        end
+
+        def symbolize_hash(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+        end
+
+        def resolve_default(spec)
+          default = spec.fetch(:default, UNSET)
+          return UNSET if default.equal?(UNSET)
+
+          value = default.respond_to?(:call) ? default.call : deep_dup(default)
+          deep_freeze(value)
+        end
+
+        def coerce_field_value(spec, value)
+          coerce = spec[:coerce]
+          return value if coerce.nil?
+
+          case coerce
+          when Symbol
+            send(coerce, value)
+          else
+            coerce.arity == 2 ? coerce.call(value, spec) : coerce.call(value)
+          end
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[deep_dup(key)] = deep_dup(nested)
+            end
+          when Array
+            value.map { |item| deep_dup(item) }
+          else
+            value.dup
+          end
+        rescue TypeError
+          value
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each do |key, nested|
+              deep_freeze(key)
+              deep_freeze(nested)
+            end
+          when Array
+            value.each { |item| deep_freeze(item) }
+          end
+
+          value.freeze if value.respond_to?(:freeze)
+          value
+        end
+
+        def serialize_value(value)
+          case value
+          when Record
+            value.to_h
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key] = serialize_value(nested)
+            end
+          when Array
+            value.map { |item| serialize_value(item) }
+          else
+            value
+          end
+        end
+      end
+
+      def initialize(**attributes)
+        normalized = self.class.send(:normalize_input_attributes, attributes)
+        unknown_keys = normalized.keys - self.class.field_names
+        unless unknown_keys.empty?
+          raise ArgumentError, "#{self.class} received unknown fields: #{unknown_keys.map(&:inspect).join(", ")}"
+        end
+
+        self.class.dto_fields.each do |name, spec|
+          value = if normalized.key?(name)
+                    normalized[name]
+                  else
+                    self.class.send(:resolve_default, spec)
+                  end
+
+          if value.equal?(UNSET)
+            raise ArgumentError, "#{self.class} requires #{name}" if spec[:required]
+
+            value = nil
+          end
+
+          if value.nil?
+            raise ArgumentError, "#{self.class} requires #{name}" unless spec[:allow_nil]
+          else
+            value = self.class.send(:coerce_field_value, spec, value)
+            value = self.class.send(:deep_freeze, value)
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+
+        freeze
+      end
+
+      def with(**overrides)
+        normalized = self.class.send(:normalize_input_attributes, overrides)
+
+        merged = self.class.dto_fields.each_with_object({}) do |(name, spec), memo|
+          current = public_send(name)
+
+          if normalized.key?(name)
+            override = normalized[name]
+            memo[name] =
+              if spec[:merge] && current.respond_to?(:merge) && override.is_a?(Hash)
+                current.merge(override)
+              else
+                override
+              end
+          else
+            memo[name] = current
+          end
+        end
+
+        self.class.new(**merged)
+      end
+
+      def to_h
+        self.class.dto_fields.each_with_object({}) do |(name, _spec), memo|
+          value = public_send(name)
+          memo[name] = self.class.send(:serialize_value, value) unless value.nil?
+        end.freeze
+      end
+
+      alias attributes to_h
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "dto/record"
+
+module Igniter
+  module DTO
+  end
+end

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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+require_relative "runtime/deferred_result"
+require_relative "executor"
+
 module Igniter
   # Base class for side-effect adapters.
   #

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

@@ -62,9 +62,32 @@ module Igniter
   class PendingDependencyError < Error
     attr_reader :deferred_result
 
-    def initialize(deferred_result, message = "Dependency is pending", context: {})
-      @deferred_result = deferred_result
-      super(message, context: context)
+    def initialize(deferred_result, message = "Dependency is pending", context: {}, token: nil, source_node: nil, waiting_on: nil, payload: nil)
+      @deferred_result, resolved_message = normalize_pending_deferred(
+        deferred_result,
+        message,
+        token: token,
+        source_node: source_node,
+        waiting_on: waiting_on,
+        payload: payload
+      )
+      super(resolved_message, context: context)
+    end
+
+    private
+
+    def normalize_pending_deferred(deferred_result, message, token:, source_node:, waiting_on:, payload:)
+      deferred_class = defined?(Igniter::Runtime::DeferredResult) ? Igniter::Runtime::DeferredResult : nil
+      return [deferred_result, message] if deferred_class && deferred_result.is_a?(deferred_class)
+
+      built_deferred = deferred_class&.build(
+        token: token,
+        source_node: source_node,
+        waiting_on: waiting_on || source_node,
+        payload: payload || {}
+      )
+
+      [built_deferred || deferred_result, deferred_result]
     end
   end
 

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Executor
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@executor_inputs, executor_inputs.transform_values(&:dup))
+        subclass.instance_variable_set(:@executor_metadata, executor_metadata.dup)
+        # capabilities and fingerprint are NOT inherited — each subclass declares its own
+      end
+
+      def input(name, required: true, type: nil, **metadata)
+        executor_inputs[name.to_sym] = metadata.merge(required: required, type: type).compact
+      end
+
+      def executor_inputs
+        @executor_inputs ||= {}
+      end
+
+      def executor_metadata
+        @executor_metadata ||= {}
+      end
+
+      def executor_key(value = nil)
+        metadata_value(:key, value)
+      end
+
+      def label(value = nil)
+        metadata_value(:label, value)
+      end
+
+      def category(value = nil)
+        metadata_value(:category, value)
+      end
+
+      def summary(value = nil)
+        metadata_value(:summary, value)
+      end
+
+      def tags(*values)
+        return Array(executor_metadata[:tags]).freeze if values.empty?
+
+        executor_metadata[:tags] = values.flatten.compact.map(&:to_sym).freeze
+      end
+
+      def output_schema(value = nil)
+        metadata_value(:output_schema, value)
+      end
+
+      def call(**dependencies)
+        new.call(**dependencies)
+      end
+
+      # ─── Capabilities DSL ────────────────────────────────────────────────────
+      #
+      # Declare what this executor is allowed to do. Capabilities are purely
+      # declarative — enforcement requires Igniter::Capabilities::Policy.
+      #
+      # Known capabilities:
+      #   :pure         — deterministic, no side effects; enables content-addressed caching
+      #   :network      — makes outbound HTTP/TCP connections
+      #   :database     — reads or writes a database
+      #   :filesystem   — reads or writes files
+      #   :external_api — calls a third-party API
+      #   :messaging    — publishes to a message queue or broker
+      #   :cache        — reads or writes an external cache
+      #
+      # Example:
+      #   class PaymentExecutor < Igniter::Executor
+      #     capabilities :network, :external_api
+      #   end
+      def capabilities(*caps)
+        if caps.empty?
+          @declared_capabilities ||= []
+        else
+          existing = @declared_capabilities || []
+          @declared_capabilities = (existing + caps.flatten.map(&:to_sym)).uniq.freeze
+        end
+      end
+
+      def declared_capabilities
+        @declared_capabilities || []
+      end
+
+      # Shorthand for `capabilities :pure`.
+      # A pure executor is fully deterministic: same inputs → same output, always.
+      # Pure executors participate in content-addressed cross-execution caching.
+      def pure
+        capabilities(:pure)
+      end
+
+      def pure?
+        declared_capabilities.include?(:pure)
+      end
+
+      # ─── Content-addressing fingerprint ──────────────────────────────────────
+      #
+      # Optional explicit version string used as part of the content-addressing key.
+      # Set a new value to invalidate the content cache after changing executor logic
+      # while keeping the class name stable.
+      #
+      #   fingerprint "tax_calculator_v2"
+      def fingerprint(value = nil)
+        return @content_fingerprint || name || "anonymous_executor" if value.nil?
+
+        @content_fingerprint = value.to_s.freeze
+      end
+
+      def content_fingerprint
+        @content_fingerprint || name || "anonymous_executor"
+      end
+
+      private
+
+      def metadata_value(key, value)
+        return executor_metadata[key] if value.nil?
+
+        executor_metadata[key] = value
+      end
+    end
+
+    attr_reader :execution, :contract
+
+    def initialize(execution: nil, contract: nil)
+      @execution = execution
+      @contract = contract
+    end
+
+    def defer(token: nil, payload: {})
+      Runtime::DeferredResult.build(token: token, payload: payload)
+    end
+  end
+end