igniter 0.5.0 → 0.5.2

data/lib/igniter/consensus.rb

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

@@ -1,133 +0,0 @@
-# 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/dataflow/aggregate_operators.rb

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

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

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

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

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

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

data/lib/igniter/dataflow.rb

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