igniter 0.4.3 → 0.5.0

data/lib/igniter/consensus.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/integrations/agents"
+require_relative "consensus/errors"
+require_relative "consensus/state_machine"
+require_relative "consensus/node"
+require_relative "consensus/cluster"
+require_relative "consensus/executors"
+require_relative "consensus/read_query"
+
+module Igniter
+  # Consensus protocol primitives built on Igniter::Agent and Igniter::Contract.
+  #
+  # Provides a Raft-inspired cluster where:
+  # - +Igniter::Consensus::Node+  encapsulates the full Raft protocol as an Agent
+  # - +Igniter::Consensus::Cluster+ manages node lifecycle + high-level read/write
+  # - +Igniter::Consensus::StateMachine+ lets users define custom command reducers
+  # - +Igniter::Consensus::ReadQuery+ is a ready-made Contract for cluster reads
+  #
+  # == Minimal example
+  #
+  #   require "igniter/consensus"
+  #
+  #   cluster = Igniter::Consensus::Cluster.start(nodes: %i[n1 n2 n3 n4 n5])
+  #   cluster.wait_for_leader
+  #
+  #   cluster.write(key: :price, value: 99)   # default KV protocol
+  #   cluster.read(:price)                     # => 99
+  #
+  #   cluster.stop!
+  #
+  # == Custom state machine
+  #
+  #   class PriceStore < Igniter::Consensus::StateMachine
+  #     apply :set    do |state, cmd| state.merge(cmd[:key] => cmd[:value]) end
+  #     apply :delete do |state, cmd| state.reject { |k, _| k == cmd[:key] } end
+  #   end
+  #
+  #   cluster = Igniter::Consensus::Cluster.start(
+  #     nodes: %i[n1 n2 n3 n4 n5],
+  #     state_machine: PriceStore,
+  #   )
+  #   cluster.write(type: :set, key: :price, value: 99)
+  #
+  # == Contract integration
+  #
+  #   class PriceCheck < Igniter::Contract
+  #     define do
+  #       input :cluster
+  #       compute :leader, with: :cluster, call: Igniter::Consensus::FindLeader
+  #       compute :price,  with: [:leader], call: MyPriceReader
+  #       output :price
+  #     end
+  #   end
+  module Consensus
+  end
+end

data/lib/igniter/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/contract.rb

@@ -23,6 +23,18 @@ module Igniter
         @execution_options = { runner: runner, max_workers: max_workers }.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)

data/lib/igniter/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

data/lib/igniter/dataflow/aggregate_state.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # Mutable state for a maintained aggregate node.
+    #
+    # Stores per-item contributions so that the aggregate can be updated
+    # incrementally using only the diff (added/changed/removed) from the upstream
+    # incremental collection — not the full item set.
+    #
+    # One AggregateState instance lives on the Execution (keyed by node name) and
+    # persists across update_inputs calls for the lifetime of the contract execution.
+    #
+    # == Update semantics
+    #
+    #   added   → contribute! (project + add into @accum)
+    #   removed → retract!    (subtract from @accum using stored contribution)
+    #   changed → retract!(old) then contribute!(new) — true differential update
+    #   unchanged → no-op
+    #
+    class AggregateState
+      def initialize(operator)
+        @operator      = operator
+        @contributions = {} # key => contribution (what the item "contributes")
+        @accum         = operator.initial
+      end
+
+      # Apply a diff from an IncrementalCollectionResult, updating the aggregate
+      # state in O(changed + added + removed) time.
+      #
+      # @param diff              [Igniter::Dataflow::Diff]
+      # @param collection_result [Igniter::Dataflow::IncrementalCollectionResult]
+      def apply_diff!(diff, collection_result)
+        diff.changed.each do |key|
+          retract!(key)
+          contribute!(key, collection_result[key])
+        end
+        diff.added.each   { |key| contribute!(key, collection_result[key]) }
+        diff.removed.each { |key| retract!(key) }
+      end
+
+      # Current aggregate value (finalized from accumulated state).
+      def value
+        if @operator.recompute
+          @operator.finalize.call(nil, @contributions)
+        else
+          @operator.finalize.call(@accum, @contributions.size)
+        end
+      end
+
+      # Number of items currently tracked in the aggregate.
+      def item_count
+        @contributions.size
+      end
+
+      private
+
+      def contribute!(key, item)
+        contribution = @operator.project.call(item)
+        return if contribution.nil?
+
+        @contributions[key] = contribution
+        return if @operator.recompute
+
+        @accum = @operator.add.call(@accum, contribution)
+      end
+
+      def retract!(key)
+        old_contribution = @contributions.delete(key)
+        return unless old_contribution
+        return if @operator.recompute
+
+        @accum = @operator.remove.call(@accum, old_contribution)
+      end
+    end
+  end
+end

data/lib/igniter/dataflow/diff.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # Immutable record of what changed in an incremental collection resolve.
+    #
+    # @attr added     [Array<Object>] keys of items added since the last resolve
+    # @attr removed   [Array<Object>] keys of items removed since the last resolve
+    # @attr changed   [Array<Object>] keys of items whose content changed
+    # @attr unchanged [Array<Object>] keys of items that were identical to the last resolve
+    Diff = Struct.new(:added, :removed, :changed, :unchanged, keyword_init: true) do
+      # Returns true if any items were added, removed, or changed.
+      def any_changes?
+        added.any? || removed.any? || changed.any?
+      end
+
+      # Returns the total number of items that needed processing (added + changed).
+      def processed_count
+        added.size + changed.size
+      end
+
+      # Returns a compact human-readable summary.
+      def explain # rubocop:disable Metrics/AbcSize
+        parts = []
+        parts << "added(#{added.size}): #{added.inspect}" unless added.empty?
+        parts << "removed(#{removed.size}): #{removed.inspect}" unless removed.empty?
+        parts << "changed(#{changed.size}): #{changed.inspect}" unless changed.empty?
+        parts << "unchanged(#{unchanged.size})" unless unchanged.empty?
+        parts.empty? ? "(no changes)" : parts.join(", ")
+      end
+
+      def to_h
+        { added: added, removed: removed, changed: changed, unchanged: unchanged }
+      end
+    end
+  end
+end

data/lib/igniter/dataflow/diff_state.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # Mutable state for an incremental collection node.
+    #
+    # Stores fingerprints of previous items and their resolved CollectionResult::Items
+    # so the resolver can skip unchanged items on subsequent updates.
+    #
+    # One DiffState instance lives on the Execution (keyed by node name) and persists
+    # across update_inputs calls for the lifetime of the contract execution.
+    class DiffState
+      attr_reader :cached_items
+
+      def initialize
+        @snapshots    = {}  # key => fingerprint string
+        @cached_items = {}  # key => Runtime::CollectionResult::Item
+      end
+
+      # Compute a Diff between the current normalized items and the previous state.
+      #
+      # @param current_items [Array<Hash>] normalized item input hashes
+      # @param key_fn        [Proc]        extracts the item key from an item hash
+      # @return [Diff]
+      def compute_diff(current_items, key_fn)
+        current_keys = current_items.to_h { |i| [key_fn.call(i), i] }
+        added, changed, unchanged = partition_items(current_items, key_fn)
+        removed = @snapshots.keys.reject { |k| current_keys.key?(k) }
+        build_diff(added, removed, changed, unchanged, key_fn)
+      end
+
+      # Record a resolved item (after running its child contract).
+      def update!(key, item_inputs, collection_result_item)
+        @snapshots[key]    = fingerprint(item_inputs)
+        @cached_items[key] = collection_result_item
+      end
+
+      # Remove a previously tracked item (on removal from the input).
+      def retract!(key)
+        @snapshots.delete(key)
+        @cached_items.delete(key)
+      end
+
+      # Returns the cached CollectionResult::Item for a key, or nil.
+      def cached_item_for(key)
+        @cached_items[key]
+      end
+
+      private
+
+      def partition_items(items, key_fn)
+        items.each_with_object([[], [], []]) do |item, (added, changed, unchanged)|
+          k = key_fn.call(item)
+          if !@snapshots.key?(k)
+            added << item
+          elsif @snapshots[k] != fingerprint(item)
+            changed << item
+          else
+            unchanged << item
+          end
+        end
+      end
+
+      def build_diff(added, removed, changed, unchanged, key_fn)
+        Diff.new(
+          added: added.map { |i| key_fn.call(i) },
+          removed: removed,
+          changed: changed.map { |i| key_fn.call(i) },
+          unchanged: unchanged.map { |i| key_fn.call(i) }
+        )
+      end
+
+      # Stable fingerprint for change detection — order-independent for Hash items.
+      def fingerprint(item)
+        return item.hash.to_s unless item.is_a?(Hash)
+
+        item.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}:#{v.inspect}" }.hash.to_s
+      end
+    end
+  end
+end

data/lib/igniter/dataflow/incremental_collection_result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # A CollectionResult that carries a Diff describing what changed in the last resolve.
+    #
+    # Inherits all CollectionResult behaviour (successes, failures, summary, to_h, etc.)
+    # and adds:
+    #
+    #   result.diff          → Igniter::Dataflow::Diff
+    #   result.diff.added    → keys added in the last update
+    #   result.diff.removed  → keys removed in the last update
+    #   result.diff.changed  → keys whose item content changed
+    #   result.diff.unchanged → keys that were identical — no child contract was re-run
+    #
+    class IncrementalCollectionResult < Runtime::CollectionResult
+      attr_reader :diff
+
+      def initialize(items:, diff:)
+        super(items: items, mode: :incremental)
+        @diff = diff
+      end
+
+      # Extends the base summary with incremental diff counters.
+      def summary
+        super.merge(
+          added: diff.added.size,
+          removed: diff.removed.size,
+          changed: diff.changed.size,
+          unchanged: diff.unchanged.size
+        )
+      end
+
+      def as_json(*)
+        super.merge(diff: diff.to_h)
+      end
+    end
+  end
+end

data/lib/igniter/dataflow/window_filter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Dataflow
+    # Applies a sliding window filter to an items array before incremental diff computation.
+    #
+    # Two window modes are supported:
+    #
+    #   window: { last: 100 }
+    #     Keep only the last 100 items (by position in the array — most recent last).
+    #
+    #   window: { seconds: 300, field: :received_at }
+    #     Keep only items where item[field] >= Time.now - seconds.
+    #     The field value must respond to `>=` with a Time (e.g., Time, DateTime).
+    class WindowFilter
+      def initialize(options)
+        @options = options
+      end
+
+      # @param items [Array<Hash>] normalized item input hashes
+      # @return [Array<Hash>] filtered items
+      def apply(items)
+        return items unless @options
+
+        if @options.key?(:last)
+          apply_last_n(items)
+        elsif @options.key?(:seconds)
+          apply_time_window(items)
+        else
+          items
+        end
+      end
+
+      private
+
+      def apply_last_n(items)
+        n = @options[:last]
+        items.last(n)
+      end
+
+      def apply_time_window(items)
+        field  = @options[:field].to_sym
+        cutoff = Time.now - @options[:seconds]
+        items.select { |item| item[field] >= cutoff }
+      end
+    end
+  end
+end