igniter 0.4.3 → 0.5.0

data/lib/igniter/dataflow.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "igniter/dataflow/diff"
+require "igniter/dataflow/diff_state"
+require "igniter/dataflow/window_filter"
+require "igniter/dataflow/incremental_collection_result"
+require "igniter/dataflow/aggregate_operators"
+require "igniter/dataflow/aggregate_state"
+require "igniter/model/aggregate_node"
+
+module Igniter
+  # Incremental Dataflow — Phase 1: differential collection processing.
+  #
+  # Adds `mode: :incremental` to the `collection` DSL node. In this mode the
+  # resolver tracks per-item state between `update_inputs` calls and re-runs
+  # child contracts only for items that were added or changed. Removed items
+  # are retracted automatically. Unchanged items reuse their cached results
+  # with zero re-computation cost.
+  #
+  # Optional `window:` filter limits the active item set before diff computation:
+  #
+  #   window: { last: 100 }
+  #     Keep only the last 100 items (most recent last in the array).
+  #
+  #   window: { seconds: 300, field: :received_at }
+  #     Keep items where item[:received_at] >= Time.now - 300.
+  #
+  # == Usage
+  #
+  #   require "igniter/extensions/dataflow"
+  #
+  #   class SensorPipeline < Igniter::Contract
+  #     define do
+  #       input :readings, type: :array
+  #
+  #       collection :processed,
+  #                  with: :readings,
+  #                  each: SensorContract,
+  #                  key: :sensor_id,
+  #                  mode: :incremental,
+  #                  window: { last: 500 }
+  #
+  #       output :processed
+  #     end
+  #   end
+  #
+  #   contract = SensorPipeline.new(readings: initial_readings)
+  #   contract.resolve_all
+  #
+  #   contract.update_inputs(readings: updated_readings)
+  #   contract.resolve_all
+  #
+  #   result = contract.result.processed
+  #   result.diff.added     # => [:sensor_42]   — child contract was re-run
+  #   result.diff.changed   # => [:sensor_7]    — child contract was re-run
+  #   result.diff.removed   # => [:sensor_3]    — retracted from result
+  #   result.diff.unchanged # => [:sensor_1, :sensor_2]  — result reused
+  #
+  #   # Convenience: push events as a diff instead of replacing the full array
+  #   contract.feed_diff(:readings, add: [new_reading], remove: [:sensor_3])
+  #
+  module Dataflow
+    class DataflowError < Igniter::Error; end
+  end
+end

data/lib/igniter/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,55 @@ 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, 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 && pinned_to
+          raise CompileError, "remote :#{name}: capability: and pinned_to: are mutually exclusive"
+        end
+
+        if capability.nil? && pinned_to.nil? && (node.nil? || node.to_s.strip.empty?)
+          raise CompileError, "remote :#{name} requires a node: URL"
+        end
 
         add_node(
           Model::RemoteNode.new(
@@ -242,6 +284,8 @@ module Igniter
             node_url: node.to_s,
             input_mapping: inputs,
             timeout: timeout,
+            capability: capability,
+            pinned_to: pinned_to,
             path: scoped_path(name),
             metadata: with_source_location(metadata)
           )
@@ -399,6 +443,26 @@ 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
         def self.build(&block)
           new.tap { |builder| builder.instance_eval(&block) }.to_h

data/lib/igniter/executor.rb

@@ -7,6 +7,7 @@ module Igniter
         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)
@@ -51,6 +52,65 @@ module Igniter
         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)

data/lib/igniter/extensions/capabilities.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "igniter/capabilities"
+
+# Patches CompiledGraph with capability introspection methods.
+# The Resolver integration is handled via guard-claused hooks in resolver.rb.
+module Igniter
+  module Compiler
+    class CompiledGraph
+      # Returns a Hash of { node_name => [capabilities] } for every compute/effect
+      # node whose executor declares at least one capability.
+      def required_capabilities
+        (nodes + outputs).each_with_object({}) do |node, memo|
+          caps = node_capabilities(node)
+          memo[node.name] = caps unless caps.empty?
+        end
+      end
+
+      # Returns declared capabilities for a single node by name.
+      def capabilities_for(node_name)
+        sym    = node_name.to_sym
+        target = (nodes + outputs).find { |n| n.name == sym }
+        return [] unless target
+
+        node_capabilities(target)
+      end
+
+      private
+
+      def node_capabilities(node)
+        callable = node.respond_to?(:callable) ? node.callable : nil
+        callable ||= node.respond_to?(:adapter_class) ? node.adapter_class : nil
+        return [] unless callable.is_a?(Class) && callable <= Igniter::Executor
+
+        callable.declared_capabilities
+      end
+    end
+  end
+end

data/lib/igniter/extensions/content_addressing.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Loading this file activates content-addressed caching for pure executors.
+# The Resolver picks up content addressing via a guard clause when this constant is defined.
+require "igniter/content_addressing"

data/lib/igniter/extensions/dataflow.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/dataflow"
+
+# Activates incremental dataflow support for all contracts.
+#
+# After requiring this file:
+#
+#   - `collection` DSL accepts `mode: :incremental` and `window:` options.
+#   - Contracts gain `#feed_diff` — push event-style diffs instead of full arrays.
+#   - Contracts gain `#collection_diff` — inspect what changed after the last resolve.
+#
+# == Usage
+#
+#   require "igniter/extensions/dataflow"
+#
+#   class SensorPipeline < Igniter::Contract
+#     define do
+#       input :readings, type: :array
+#
+#       collection :processed,
+#                  with: :readings,
+#                  each: SensorContract,
+#                  key: :sensor_id,
+#                  mode: :incremental,
+#                  window: { last: 500 }
+#
+#       output :processed
+#     end
+#   end
+#
+#   contract = SensorPipeline.new(readings: initial_readings)
+#   contract.resolve_all
+#
+#   # Push new events without replacing the full array
+#   contract.feed_diff(:readings, add: [new_reading], remove: [:sensor_old])
+#   contract.resolve_all
+#
+#   # Inspect what changed
+#   diff = contract.collection_diff(:processed)
+#   diff.added     # => [:sensor_42]
+#   diff.removed   # => [:sensor_old]
+#   diff.changed   # => []
+#   diff.unchanged # => [:sensor_1, :sensor_2, ...]
+#
+module Igniter
+  module Extensions
+    module Dataflow
+      module InstanceMethods
+        # Push a diff to a collection input without replacing the full array.
+        #
+        # Automatically finds the incremental collection node that uses +input_name+
+        # as its source dependency, uses its key_name to merge the diff into the
+        # current input array, then calls update_inputs.
+        #
+        # @param input_name [Symbol, String]  the contract input holding the collection
+        # @param add        [Array<Hash>]     new items to append
+        # @param remove     [Array]           keys or Hash items to remove (matched by key_name)
+        # @param update     [Array<Hash>]     updated versions of existing items (replace by key)
+        # @return [self]
+        #
+        # @raise [ArgumentError] if no incremental collection node uses the given input
+        def feed_diff(input_name, add: [], remove: [], update: [])
+          sym      = input_name.to_sym
+          key_name = _incremental_node_for(sym).key_name
+          current  = execution.inputs[sym].dup || []
+          items    = _apply_diff(current, key_name, add: add, remove: remove, update: update)
+          execution.update_inputs(sym => items)
+          self
+        end
+
+        # Returns the Diff from the last resolve for a named collection node.
+        #
+        # @param collection_name [Symbol, String]  the collection node name
+        # @return [Igniter::Dataflow::Diff, nil]  nil if not yet resolved or not incremental
+        def collection_diff(collection_name)
+          state = execution.cache.fetch(collection_name.to_sym)
+          value = state&.value
+          value.respond_to?(:diff) ? value.diff : nil
+        end
+
+        private
+
+        def _apply_diff(items, key_name, add:, remove:, update:)
+          remove_keys = Array(remove).map { |e| e.is_a?(Hash) ? e.fetch(key_name) : e }.to_set
+          result = items.reject { |item| remove_keys.include?(item.fetch(key_name)) }
+          _apply_updates(result, key_name, update)
+          result.concat(Array(add))
+        end
+
+        def _apply_updates(items, key_name, updates)
+          Array(updates).each do |updated|
+            k   = updated.fetch(key_name)
+            idx = items.index { |item| item.fetch(key_name) == k }
+            idx ? items[idx] = updated : items << updated
+          end
+        end
+
+        def _incremental_node_for(input_name)
+          node = execution.compiled_graph.nodes.find do |n|
+            n.kind == :collection &&
+              n.mode == :incremental &&
+              n.source_dependency == input_name
+          end
+          return node if node
+
+          raise ArgumentError,
+                "No incremental collection node found for input '#{input_name}'. " \
+                "Ensure the collection is declared with mode: :incremental."
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Dataflow::InstanceMethods)

data/lib/igniter/extensions/incremental.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/incremental"
+
+module Igniter
+  module Extensions
+    # Patches Igniter::Contract with:
+    #   - Instance method: resolve_incrementally(new_inputs = {}) → Incremental::Result
+    #
+    # The method updates inputs, re-resolves, and returns a structured report
+    # of which nodes changed, were memoized, or were backdated.
+    #
+    # Applied globally via:
+    #   Igniter::Contract.include(Igniter::Extensions::Incremental)
+    #
+    module Incremental
+      def self.included(base)
+        base.include(InstanceMethods)
+      end
+
+      module InstanceMethods
+        # Update inputs and re-resolve, returning a detailed incremental result.
+        #
+        # If called without arguments on an already-resolved contract, it
+        # re-resolves with current inputs (useful for observing memoization).
+        #
+        # @param new_inputs [Hash] input values to update before re-resolving
+        # @return [Igniter::Incremental::Result]
+        def resolve_incrementally(new_inputs = {})
+          unless execution.cache.values.any?
+            raise Igniter::Incremental::IncrementalError,
+                  "Contract has not been executed yet — call resolve_all first, " \
+                  "then resolve_incrementally to get incremental results"
+          end
+
+          tracker = Igniter::Incremental::Tracker.new(execution)
+          tracker.start!
+
+          update_inputs(new_inputs) if new_inputs.any?
+          resolve_all
+
+          tracker.build_result
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Incremental)

data/lib/igniter/extensions/mesh.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Igniter Mesh — Phase 1 (Static) + Phase 2 (Dynamic Discovery)
+#
+# Extends the remote: DSL with capability-based and pinned routing modes, and
+# enables dynamic peer discovery so that the peer topology can be maintained
+# without static add_peer declarations.
+#
+# Usage:
+#   require "igniter/extensions/mesh"
+#
+#   # Phase 1 — static topology (still works):
+#   Igniter::Mesh.configure do |c|
+#     c.add_peer "orders-node",
+#                url: "http://orders.internal:4567",
+#                capabilities: [:orders, :inventory]
+#   end
+#
+#   # Phase 2 — dynamic discovery:
+#   Igniter::Mesh.configure do |c|
+#     c.peer_name          = "api-node"
+#     c.local_url          = "http://api.internal:4567"
+#     c.local_capabilities = [:api]
+#     c.seeds              = %w[http://orders.internal:4567 http://audit.internal:4567]
+#     c.discovery_interval = 30
+#   end
+#   Igniter::Mesh.start_discovery!
+#
+require "igniter"
+require "igniter/server"
+require "igniter/mesh"

data/lib/igniter/fingerprint.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Mixin that enables stable cross-execution cache keys for objects used as
+  # compute node dependencies (e.g. ActiveRecord models).
+  #
+  # Include this module in any class whose instances are passed as node deps:
+  #
+  #   class Trade < ApplicationRecord
+  #     include Igniter::Fingerprint
+  #   end
+  #
+  # The Rails Railtie includes this automatically in ApplicationRecord when
+  # the igniter-rails integration is loaded.
+  #
+  # == Custom fingerprints
+  #
+  # Override #igniter_fingerprint for non-AR objects or custom invalidation logic:
+  #
+  #   class PricingConfig
+  #     include Igniter::Fingerprint
+  #
+  #     def igniter_fingerprint
+  #       "PricingConfig:#{version}:#{market}"
+  #     end
+  #   end
+  module Fingerprint
+    # Returns a stable string that uniquely identifies this object's state.
+    # Changing the returned value invalidates any NodeCache entry that depends on it.
+    #
+    # Default: "{ClassName}:{id}:{updated_at_unix}" — works for any AR record.
+    # Returns "{ClassName}:{id}" for objects without updated_at.
+    def igniter_fingerprint
+      if respond_to?(:updated_at) && updated_at
+        "#{self.class.name}:#{id}:#{updated_at.to_i}"
+      elsif respond_to?(:id)
+        "#{self.class.name}:#{id}"
+      else
+        "#{self.class.name}:#{object_id}"
+      end
+    end
+  end
+end

data/lib/igniter/incremental/formatter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Incremental
+    # Renders an Incremental::Result as a human-readable text block.
+    #
+    # Example output:
+    #
+    #   Incremental Execution Report
+    #   ─────────────────────────────────────────
+    #   Recomputed:  1 node(s)
+    #   Skipped:     2 node(s)  (deps unchanged)
+    #   Backdated:   0 node(s)  (value unchanged)
+    #
+    #   CHANGED OUTPUTS (1):
+    #     :converted_price  1.05 → 1.12
+    #
+    #   SKIPPED NODES (memoized):
+    #     :tier_discount  :adjusted_price
+    #
+    module Formatter
+      VALUE_MAX = 60
+      LINE = "─" * 42
+
+      class << self
+        def format(result) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          lines = []
+          lines << "Incremental Execution Report"
+          lines << LINE
+          lines << "Recomputed:  #{result.recomputed_count} node(s)"
+          lines << "Skipped:     #{result.skipped_nodes.size} node(s)  (deps unchanged)"
+          lines << "Backdated:   #{result.backdated_nodes.size} node(s)  (value unchanged)"
+          lines << ""
+
+          if result.changed_outputs.any?
+            lines << "CHANGED OUTPUTS (#{result.changed_outputs.size}):"
+            result.changed_outputs.each do |name, diff|
+              lines << "  :#{name}  #{fmt(diff[:from])} → #{fmt(diff[:to])}"
+            end
+          else
+            lines << "No output values changed."
+          end
+          lines << ""
+
+          if result.skipped_nodes.any?
+            lines << "SKIPPED (memoized, #{result.skipped_nodes.size}):"
+            lines << "  #{result.skipped_nodes.map { |n| ":#{n}" }.join("  ")}"
+            lines << ""
+          end
+
+          if result.backdated_nodes.any?
+            lines << "BACKDATED (recomputed → same value, #{result.backdated_nodes.size}):"
+            lines << "  #{result.backdated_nodes.map { |n| ":#{n}" }.join("  ")}"
+            lines << ""
+          end
+
+          if result.changed_nodes.any?
+            lines << "CHANGED (#{result.changed_nodes.size}):"
+            lines << "  #{result.changed_nodes.map { |n| ":#{n}" }.join("  ")}"
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def fmt(value) # rubocop:disable Metrics/CyclomaticComplexity
+          str = case value
+                when nil    then "nil"
+                when String then value.inspect
+                when Symbol then value.inspect
+                when Hash   then "{#{value.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
+                when Array  then "[#{value.map(&:inspect).join(", ")}]"
+                else             value.inspect
+                end
+          str.length > VALUE_MAX ? "#{str[0, VALUE_MAX - 3]}..." : str
+        end
+      end
+    end
+  end
+end