igniter 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5634161e393aef6bad7be0b3584d7376e933c70b9ba81e6a2055adede34a05b1
-  data.tar.gz: 5d136cf57c9c115d5d76ea4f84d011f4d6f383989907b60475aadcef8be439d9
+  metadata.gz: 71035dd880de5a8a81bcc14cd0bf1097dbbb03ec9c2a915e36ae821bb3e25d70
+  data.tar.gz: a6bb66b9f865230e09c21e5db140ecf3b6705a934b2a5172f3dd2d6198dd5371
 SHA512:
-  metadata.gz: fb93db3831bceffc0d6e9fc83a3e1ecff6e105356c168b9428a694049a8a4bd857aa9f3378580885ec9a8007c55d0896d8d8cb5ea00c149829262a9eec8c1244
-  data.tar.gz: bbfbd87106e660d958ce5b3b92b82e3394a9e7771686f62926cedc397b4ffb73fbabb9fbab3ea491a51fa0984d330b61d71c1042c3c874ef0738519e2fd89cc1
+  metadata.gz: 0d59ee3a5cab0e01e5f0bdae733eb991296be4ff0ef107b305e1795da1c0de2629a629dbeef18326ca606e142376542eb919470cd66ac1baee7db4210eeccd4c
+  data.tar.gz: 79d4cabcebcfa3b93cb9fd409c1f4173001125f59dde18bb79a21a8021f45877613de5023de0caf6a0400418bfe71541a61ec8a42125d9aab526ddc23be3c211

data/examples/incremental.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# examples/incremental.rb
+#
+# Demonstrates Igniter's incremental computation: only the minimal set of
+# nodes is re-executed when inputs change.
+#
+# Inspired by Salsa (Rust, rust-analyzer) and Adapton.
+#
+# Run with: bundle exec ruby examples/incremental.rb
+
+require_relative "../lib/igniter"
+require_relative "../lib/igniter/extensions/incremental"
+
+# ─── Contract ──────────────────────────────────────────────────────────────
+#
+#   base_price ──┐
+#                ├→ adjusted_price ──┐
+#   user_tier ──→ tier_discount ──┘   ├→ converted_price
+#                                     │
+#   exchange_rate ────────────────────┘
+#
+# When only exchange_rate changes:
+#   ✓ tier_discount   → SKIPPED (doesn't depend on exchange_rate)
+#   ✓ adjusted_price  → SKIPPED (doesn't depend on exchange_rate)
+#   ✓ converted_price → RECOMPUTED (directly depends on exchange_rate)
+#
+class PricingContract < Igniter::Contract
+  define do
+    input :base_price
+    input :user_tier
+    input :exchange_rate
+
+    compute :tier_discount, depends_on: :user_tier, call: lambda { |user_tier:|
+      case user_tier
+      when "gold"     then 0.20
+      when "silver"   then 0.10
+      else                 0.0
+      end
+    }
+
+    compute :adjusted_price, depends_on: %i[base_price tier_discount], call: lambda { |base_price:, tier_discount:|
+      base_price * (1.0 - tier_discount)
+    }
+
+    compute :converted_price, depends_on: %i[adjusted_price exchange_rate], call: lambda { |adjusted_price:, exchange_rate:|
+      (adjusted_price * exchange_rate).round(2)
+    }
+
+    output :tier_discount
+    output :adjusted_price
+    output :converted_price
+  end
+end
+
+# ─── Helper to show node value_versions ────────────────────────────────────
+def show_versions(contract, label)
+  puts "\n#{label}"
+  puts "-" * 50
+  %i[base_price user_tier exchange_rate tier_discount adjusted_price converted_price].each do |name|
+    node_name = name
+    state = contract.execution.cache.fetch(node_name)
+    next unless state
+
+    status = state.status
+    vv     = state.value_version
+    val    = state.value
+    mark   = case status
+             when :stale     then "~"
+             when :succeeded then "✓"
+             else                 " "
+             end
+    puts "  #{mark} :#{name.to_s.ljust(20)} val=#{val.inspect.ljust(10)} vv=#{vv}"
+  end
+end
+
+# ─── Run ───────────────────────────────────────────────────────────────────
+puts "=" * 60
+puts "Igniter Incremental Computation Demo"
+puts "=" * 60
+
+contract = PricingContract.new(
+  base_price: 100.0,
+  user_tier: "gold",
+  exchange_rate: 1.0
+)
+
+contract.resolve_all
+show_versions(contract, "After initial resolve_all")
+
+puts "\n" + "=" * 60
+puts "Scenario 1: exchange_rate changes 1.0 → 1.12"
+puts "(tier_discount and adjusted_price should be SKIPPED)"
+puts "=" * 60
+
+result = contract.resolve_incrementally(exchange_rate: 1.12)
+
+show_versions(contract, "After resolve_incrementally(exchange_rate: 1.12)")
+puts "\nIncrementalResult:"
+puts result.explain
+
+puts "\nKey assertions:"
+puts "  Skipped nodes:  #{result.skipped_nodes.inspect}"
+puts "  Backdated:      #{result.backdated_nodes.inspect}"
+puts "  Changed:        #{result.changed_nodes.inspect}"
+puts "  Recomputed:     #{result.recomputed_count}"
+puts "  Changed output: converted_price #{result.changed_outputs[:converted_price]&.values_at(:from, :to)&.join(" → ")}"
+
+puts "\n" + "=" * 60
+puts "Scenario 2: user_tier changes gold → silver"
+puts "(tier_discount, adjusted_price, converted_price all recompute)"
+puts "=" * 60
+
+result2 = contract.resolve_incrementally(user_tier: "silver")
+show_versions(contract, "After resolve_incrementally(user_tier: 'silver')")
+puts "\nIncrementalResult:"
+puts result2.explain
+
+puts "\n" + "=" * 60
+puts "Scenario 3: same exchange_rate again (no change)"
+puts "(fully memoized — nothing recomputes)"
+puts "=" * 60
+
+result3 = contract.resolve_incrementally(exchange_rate: 1.12)
+puts "\nIncrementalResult:"
+puts result3.explain
+puts "\nfully_memoized? #{result3.fully_memoized?}"
+puts "outputs_changed? #{result3.outputs_changed?}"
+
+puts "\n" + "=" * 60
+puts "Scenario 4: base_price changes 100 → 100 (same value)"
+puts "(demonstrates value-equality backdating in adjusted_price)")
+puts "=" * 60
+
+contract2 = PricingContract.new(base_price: 100.0, user_tier: "gold", exchange_rate: 1.0)
+contract2.resolve_all
+
+# Now change base_price to the same value — cache.write sees same value → value_version stays
+result4 = contract2.resolve_incrementally(base_price: 100.0)
+puts "\nIncrementalResult:"
+puts result4.explain
+puts "outputs_changed? #{result4.outputs_changed?}"

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/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

data/lib/igniter/incremental/result.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Incremental
+    # Structured result of a resolve_incrementally call.
+    #
+    # Attributes:
+    #   changed_nodes   — node names whose value_version increased (value actually changed)
+    #   skipped_nodes   — node names that were stale but memoized (deps unchanged, compute skipped)
+    #   backdated_nodes — node names that recomputed but produced the same value
+    #   changed_outputs — Hash{ Symbol => { from: old_value, to: new_value } }
+    #   recomputed_count — total number of compute calls actually executed
+    class Result
+      attr_reader :changed_nodes, :skipped_nodes, :backdated_nodes,
+                  :changed_outputs, :recomputed_count
+
+      def initialize(changed_nodes:, skipped_nodes:, backdated_nodes:,
+                     changed_outputs:, recomputed_count:)
+        @changed_nodes = changed_nodes.freeze
+        @skipped_nodes = skipped_nodes.freeze
+        @backdated_nodes = backdated_nodes.freeze
+        @changed_outputs = changed_outputs.freeze
+        @recomputed_count = recomputed_count
+        freeze
+      end
+
+      # True when at least one output value changed.
+      def outputs_changed?
+        changed_outputs.any?
+      end
+
+      # True when every stale node was memoized — nothing actually ran.
+      def fully_memoized?
+        recomputed_count.zero?
+      end
+
+      # One-line summary for logging.
+      def summary # rubocop:disable Metrics/AbcSize
+        parts = []
+        parts << "#{changed_nodes.size} node(s) changed" if changed_nodes.any?
+        parts << "#{skipped_nodes.size} skipped (memoized)" if skipped_nodes.any?
+        parts << "#{backdated_nodes.size} backdated (same value)" if backdated_nodes.any?
+        parts << "#{recomputed_count} recomputed"
+        parts.join(", ")
+      end
+
+      # Human-readable ASCII report.
+      def explain
+        Formatter.format(self)
+      end
+
+      alias to_s explain
+
+      def to_h # rubocop:disable Metrics/MethodLength
+        {
+          changed_nodes: changed_nodes,
+          skipped_nodes: skipped_nodes,
+          backdated_nodes: backdated_nodes,
+          changed_outputs: changed_outputs.transform_values do |diff|
+            { from: diff[:from], to: diff[:to] }
+          end,
+          recomputed_count: recomputed_count,
+          outputs_changed: outputs_changed?,
+          fully_memoized: fully_memoized?
+        }
+      end
+    end
+  end
+end

data/lib/igniter/incremental/tracker.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Incremental
+    # Subscribes to execution events and records which nodes were changed,
+    # skipped (memoized), or backdated during an incremental resolve pass.
+    #
+    # Takes a pre-snapshot of value_versions before the resolve pass and compares
+    # after to detect what changed, rather than relying on event payloads alone.
+    class Tracker
+      def initialize(execution)
+        @execution = execution
+        @skipped_nodes = []
+        @backdated_nodes = []
+        @recomputed_nodes = []
+        @pre_node_vv = {}
+        @pre_output_values = {}
+      end
+
+      def start!
+        snapshot_pre_state!
+        @execution.events.subscribe(self)
+      end
+
+      # Called by Events::Bus for every event.
+      def call(event)
+        case event.type
+        when :node_skipped
+          @skipped_nodes << event.node_name
+        when :node_backdated
+          @backdated_nodes << event.node_name
+        when :node_succeeded
+          kind = fetch_node_kind(event.node_name)
+          @recomputed_nodes << event.node_name if %i[compute effect].include?(kind)
+        end
+      end
+
+      def build_result # rubocop:disable Metrics/MethodLength
+        # Deduplicate (events may fire multiple times across execution passes)
+        skipped   = @skipped_nodes.uniq
+        backdated = @backdated_nodes.uniq
+        # recomputed = node_succeeded minus skipped (skipped also fires node_succeeded)
+        recomputed = @recomputed_nodes.uniq - skipped
+
+        changed = detect_changed_nodes
+        changed_outputs = detect_changed_outputs
+
+        Result.new(
+          changed_nodes: changed,
+          skipped_nodes: skipped,
+          backdated_nodes: backdated,
+          changed_outputs: changed_outputs,
+          recomputed_count: recomputed.size
+        )
+      end
+
+      private
+
+      def snapshot_pre_state! # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        @execution.compiled_graph.nodes.each do |node|
+          state = @execution.cache.fetch(node.name)
+          @pre_node_vv[node.name] = state&.value_version
+        end
+
+        @execution.compiled_graph.outputs.each do |output_node|
+          src_state = @execution.cache.fetch(output_node.source_root)
+          @pre_output_values[output_node.name] = {
+            value: src_state&.value,
+            value_version: src_state&.value_version
+          }
+        end
+      end
+
+      def detect_changed_nodes
+        @execution.compiled_graph.nodes.each_with_object([]) do |node, memo|
+          pre_vv = @pre_node_vv[node.name]
+          current_vv = @execution.cache.fetch(node.name)&.value_version
+          # Changed = value_version advanced AND it's a compute/effect node
+          next unless %i[compute effect].include?(node.kind)
+          next unless current_vv && current_vv != pre_vv
+
+          memo << node.name
+        end
+      end
+
+      def detect_changed_outputs
+        @execution.compiled_graph.outputs.each_with_object({}) do |output_node, memo|
+          pre = @pre_output_values[output_node.name]
+          next unless pre
+
+          src_state = @execution.cache.fetch(output_node.source_root)
+          current_vv = src_state&.value_version
+
+          next if pre[:value_version] == current_vv
+
+          memo[output_node.name] = { from: pre[:value], to: src_state&.value }
+        end
+      end
+
+      def fetch_node_kind(node_name)
+        return nil unless node_name
+        return nil unless @execution.compiled_graph.node?(node_name)
+
+        @execution.compiled_graph.fetch_node(node_name).kind
+      end
+    end
+  end
+end

data/lib/igniter/incremental.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/incremental/result"
+require "igniter/incremental/tracker"
+require "igniter/incremental/formatter"
+
+module Igniter
+  # Incremental computation for Igniter contracts.
+  #
+  # Implements the Salsa/Adapton incremental model:
+  #   - Each compute node tracks a dep_snapshot: the value_versions of its
+  #     dependencies at last compute time.
+  #   - On re-resolution of a stale node, if all dep value_versions are
+  #     unchanged, the compute is skipped entirely (memoization).
+  #   - If a node recomputes but produces the same output value, its own
+  #     value_version is not incremented (backdating), preventing unnecessary
+  #     downstream recomputation.
+  #
+  # These optimizations are built into the core runtime (NodeState, Cache,
+  # Resolver) and are always active. This module adds the reporting API:
+  #   - contract.resolve_incrementally → Incremental::Result
+  #
+  # Usage:
+  #   require "igniter/extensions/incremental"
+  #
+  #   class PricingContract < Igniter::Contract
+  #     define do
+  #       input :base_price
+  #       input :user_tier
+  #       input :exchange_rate
+  #       compute :tier_discount,   depends_on: :user_tier,   call: -> (user_tier:) { ... }
+  #       compute :adjusted_price,  depends_on: %i[base_price tier_discount], call: -> (**) { ... }
+  #       compute :converted_price, depends_on: %i[adjusted_price exchange_rate], call: -> (**) { ... }
+  #       output :converted_price
+  #     end
+  #   end
+  #
+  #   contract = PricingContract.new(base_price: 100, user_tier: "gold", exchange_rate: 1.0)
+  #   contract.resolve_all
+  #
+  #   result = contract.resolve_incrementally(exchange_rate: 1.12)
+  #   result.skipped_nodes    # => [:tier_discount, :adjusted_price]
+  #   result.changed_outputs  # => { converted_price: { from: 100.0, to: 112.0 } }
+  #   result.explain
+  #
+  module Incremental
+    class IncrementalError < Igniter::Error; end
+  end
+end

data/lib/igniter/runtime/cache.rb

@@ -13,24 +13,27 @@ module Igniter
         @mutex.synchronize { @states[node_name.to_sym] }
       end
 
-      def write(state)
+      def write(state) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         @mutex.synchronize do
           current = @states[state.node.name]
           version = state.version || (current&.running? ? current.version : next_version(current))
+          value_version = compute_value_version(state, current)
           @states[state.node.name] = NodeState.new(
             node: state.node,
             status: state.status,
             value: state.value,
             error: state.error,
             version: version,
+            value_version: value_version,
             resolved_at: state.resolved_at,
-            invalidated_by: state.invalidated_by
+            invalidated_by: state.invalidated_by,
+            dep_snapshot: state.dep_snapshot
           )
           @condition.broadcast
         end
       end
 
-      def begin_resolution(node)
+      def begin_resolution(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         @mutex.synchronize do
           loop do
             current = @states[node.name]
@@ -43,8 +46,10 @@ module Igniter
                 value: current&.value,
                 error: current&.error,
                 version: next_version(current),
+                value_version: current&.value_version,
                 resolved_at: current&.resolved_at || Time.now.utc,
-                invalidated_by: nil
+                invalidated_by: nil,
+                dep_snapshot: current&.dep_snapshot
               )
               return [:started, @states[node.name]]
             end
@@ -54,7 +59,7 @@ module Igniter
         end
       end
 
-      def stale!(node, invalidated_by:)
+      def stale!(node, invalidated_by:) # rubocop:disable Metrics/MethodLength
         @mutex.synchronize do
           current = @states[node.name]
           return unless current
@@ -65,8 +70,10 @@ module Igniter
             value: current.value,
             error: current.error,
             version: current.version + 1,
+            value_version: current.value_version,
             resolved_at: current.resolved_at,
-            invalidated_by: invalidated_by
+            invalidated_by: invalidated_by,
+            dep_snapshot: current.dep_snapshot
           )
           @condition.broadcast
         end
@@ -92,6 +99,28 @@ module Igniter
       def next_version(current)
         current ? current.version + 1 : 1
       end
+
+      # value_version only increments when the actual value changes.
+      # When state.value_version is set explicitly (backdating from resolver), use it.
+      # For :succeeded states, compare the new value against the old value:
+      #   - same value → preserve value_version
+      #   - different (or first time) → increment
+      # For all other statuses (failed, pending, etc.) → no value_version.
+      def compute_value_version(state, current)
+        return state.value_version if state.value_version
+
+        return nil unless state.status == :succeeded
+
+        base_vv = current&.value_version || 0
+        # When current is :running, current.value holds the pre-stale value for comparison.
+        old_value = current&.value
+
+        if base_vv.positive? && old_value == state.value
+          base_vv
+        else
+          base_vv + 1
+        end
+      end
     end
   end
 end

data/lib/igniter/runtime/execution.rb

@@ -251,10 +251,12 @@ module Igniter
           memo[node_name] = {
             status: state.status,
             version: state.version,
+            value_version: state.value_version,
             resolved_at: state.resolved_at&.iso8601,
             invalidated_by: state.invalidated_by,
             value: serialize_state_value(state.value),
-            error: serialize_state_error(state.error)
+            error: serialize_state_error(state.error),
+            dep_snapshot: state.dep_snapshot
           }
         end
       end
@@ -262,14 +264,18 @@ module Igniter
       def deserialize_states(snapshot_states)
         snapshot_states.each_with_object({}) do |(node_name, state_data), memo|
           node = compiled_graph.fetch_node(node_name)
+          raw_dep_snapshot = state_data[:dep_snapshot] || state_data["dep_snapshot"]
+          dep_snapshot = raw_dep_snapshot&.transform_keys(&:to_sym)
           memo[node.name] = NodeState.new(
             node: node,
             status: (state_data[:status] || state_data["status"]).to_sym,
             value: deserialize_state_value(node, state_data[:value] || state_data["value"]),
             error: deserialize_state_error(state_data[:error] || state_data["error"]),
             version: state_data[:version] || state_data["version"],
+            value_version: state_data[:value_version] || state_data["value_version"],
             resolved_at: deserialize_time(state_data[:resolved_at] || state_data["resolved_at"]),
-            invalidated_by: (state_data[:invalidated_by] || state_data["invalidated_by"])&.to_sym
+            invalidated_by: (state_data[:invalidated_by] || state_data["invalidated_by"])&.to_sym,
+            dep_snapshot: dep_snapshot
           )
         end
       end

data/lib/igniter/runtime/node_state.rb

@@ -3,16 +3,20 @@
 module Igniter
   module Runtime
     class NodeState
-      attr_reader :node, :status, :value, :error, :version, :resolved_at, :invalidated_by
+      attr_reader :node, :status, :value, :error, :version, :value_version,
+                  :resolved_at, :invalidated_by, :dep_snapshot
 
-      def initialize(node:, status:, value: nil, error: nil, version: nil, resolved_at: Time.now.utc, invalidated_by: nil)
+      def initialize(node:, status:, value: nil, error: nil, version: nil, value_version: nil, # rubocop:disable Metrics/ParameterLists
+                     resolved_at: Time.now.utc, invalidated_by: nil, dep_snapshot: nil)
         @node = node
         @status = status
         @value = value
         @error = error
         @version = version
+        @value_version = value_version
         @resolved_at = resolved_at
         @invalidated_by = invalidated_by
+        @dep_snapshot = dep_snapshot
       end
 
       def stale?
@@ -40,6 +44,7 @@ module Igniter
           node_name: node.name,
           status: status,
           version: version,
+          value_version: value_version,
           resolved_at: resolved_at,
           invalidated_by: invalidated_by,
           value: value,

data/lib/igniter/runtime/resolver.rb

@@ -115,16 +115,52 @@ module Igniter
         raise ResolutionError, "Cannot reach #{node.node_url}: #{e.message}"
       end
 
-      def resolve_compute(node)
+      def resolve_compute(node) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # Running state preserves dep_snapshot + value_version from the stale state.
+        # These are used for memoization (skip recompute) and value backdating.
+        running_state = @execution.cache.fetch(node.name)
+        old_dep_snapshot = running_state&.dep_snapshot
+        old_value = running_state&.value
+        old_value_version = running_state&.value_version || 0
+
+        # Resolve all dependencies (may recursively recompute upstream nodes).
         dependencies = node.dependencies.each_with_object({}) do |dependency_name, memo|
           memo[dependency_name] = resolve_dependency_value(dependency_name)
         end
 
+        # Build snapshot of current dep value_versions (only regular nodes, not outputs).
+        current_dep_snapshot = build_dep_snapshot(node)
+
+        # Memoization: if all dep value_versions are unchanged, skip the compute entirely.
+        if old_dep_snapshot && old_value && old_value_version.positive? &&
+           dep_snapshot_match?(current_dep_snapshot, old_dep_snapshot)
+          @execution.events.emit(:node_skipped, node: node, status: :succeeded,
+                                                payload: { reason: :deps_unchanged })
+          return NodeState.new(node: node, status: :succeeded, value: old_value,
+                               value_version: old_value_version,
+                               dep_snapshot: current_dep_snapshot)
+        end
+
         value = call_compute(node.callable, dependencies)
-        return NodeState.new(node: node, status: :pending, value: normalize_deferred_result(value, node)) if deferred_result?(value)
+        if deferred_result?(value)
+          return NodeState.new(node: node, status: :pending,
+                               value: normalize_deferred_result(value, node))
+        end
+
         value = normalize_guard_value(node, value)
 
-        NodeState.new(node: node, status: :succeeded, value: value)
+        # Value backdating: if the output is unchanged, preserve value_version so that
+        # downstream nodes whose dep_snapshots reference this node won't see it as changed.
+        if old_value && old_value_version.positive? && value == old_value
+          @execution.events.emit(:node_backdated, node: node, status: :succeeded,
+                                                  payload: { reason: :value_unchanged })
+          return NodeState.new(node: node, status: :succeeded, value: value,
+                               value_version: old_value_version,
+                               dep_snapshot: current_dep_snapshot)
+        end
+
+        NodeState.new(node: node, status: :succeeded, value: value,
+                      dep_snapshot: current_dep_snapshot)
       end
 
       def call_compute(callable, dependencies)
@@ -151,11 +187,9 @@ module Igniter
       end
 
       def call_compute_object(callable, dependencies)
-        if callable.respond_to?(:call)
-          callable.call(**dependencies)
-        else
-          raise ResolutionError, "Unsupported callable: #{callable.class}"
-        end
+        raise ResolutionError, "Unsupported callable: #{callable.class}" unless callable.respond_to?(:call)
+
+        callable.call(**dependencies)
       end
 
       def resolve_composition(node)
@@ -281,13 +315,17 @@ module Igniter
         if @execution.compiled_graph.node?(dependency_name)
           dependency_state = resolve(dependency_name)
           raise dependency_state.error if dependency_state.failed?
-          raise PendingDependencyError.new(dependency_state.value, context: pending_context(dependency_state.node)) if dependency_state.pending?
+
+          if dependency_state.pending?
+            raise PendingDependencyError.new(dependency_state.value,
+                                             context: pending_context(dependency_state.node))
+          end
 
           dependency_state.value
         elsif @execution.compiled_graph.outputs_by_name.key?(dependency_name.to_sym)
           output = @execution.compiled_graph.fetch_output(dependency_name)
           value = @execution.send(:resolve_exported_output, output)
-          raise PendingDependencyError.new(value) if deferred_result?(value)
+          raise PendingDependencyError, value if deferred_result?(value)
 
           value
         else
@@ -372,6 +410,21 @@ module Igniter
         )
       end
 
+      def build_dep_snapshot(node)
+        node.dependencies.each_with_object({}) do |dep_name, memo|
+          next unless @execution.compiled_graph.node?(dep_name)
+
+          dep_state = @execution.cache.fetch(dep_name.to_sym)
+          memo[dep_name] = dep_state&.value_version
+        end
+      end
+
+      def dep_snapshot_match?(current, old)
+        return false if current.size != old.size
+
+        current.all? { |name, vv| old[name] == vv }
+      end
+
       def normalize_guard_value(node, value)
         return value unless node.respond_to?(:guard?) && node.guard?
         return true if value
@@ -389,9 +442,7 @@ module Igniter
       end
 
       def normalize_collection_items(node, items, context_values = {})
-        if node.input_mapper? && items.is_a?(Hash)
-          items = items.to_a
-        end
+        items = items.to_a if node.input_mapper? && items.is_a?(Hash)
 
         unless items.is_a?(Array)
           raise CollectionInputError.new(
@@ -440,14 +491,17 @@ module Igniter
 
       def ensure_unique_collection_keys!(node, items)
         keys = items.map do |item|
-          item.fetch(node.key_name) { raise CollectionKeyError.new("Collection '#{node.name}' item is missing key '#{node.key_name}'", context: collection_context(node)) }
+          item.fetch(node.key_name) do
+            raise CollectionKeyError.new("Collection '#{node.name}' item is missing key '#{node.key_name}'",
+                                         context: collection_context(node))
+          end
         end
 
         duplicates = keys.group_by(&:itself).select { |_key, entries| entries.size > 1 }.keys
         return if duplicates.empty?
 
         raise CollectionKeyError.new(
-          "Collection '#{node.name}' has duplicate keys: #{duplicates.join(', ')}",
+          "Collection '#{node.name}' has duplicate keys: #{duplicates.join(", ")}",
           context: collection_context(node)
         )
       end

data/lib/igniter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Igniter
-  VERSION = "0.4.3"
+  VERSION = "0.4.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: igniter
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Alexander
@@ -73,6 +73,7 @@ files:
 - examples/distributed_server.rb
 - examples/distributed_workflow.rb
 - examples/effects.rb
+- examples/incremental.rb
 - examples/invariants.rb
 - examples/marketing_ergonomics.rb
 - examples/order_pipeline.rb
@@ -133,6 +134,7 @@ files:
 - lib/igniter/extensions/auditing/timeline.rb
 - lib/igniter/extensions/differential.rb
 - lib/igniter/extensions/execution_report.rb
+- lib/igniter/extensions/incremental.rb
 - lib/igniter/extensions/introspection.rb
 - lib/igniter/extensions/introspection/graph_formatter.rb
 - lib/igniter/extensions/introspection/plan_formatter.rb
@@ -144,6 +146,10 @@ files:
 - lib/igniter/extensions/reactive/matcher.rb
 - lib/igniter/extensions/reactive/reaction.rb
 - lib/igniter/extensions/saga.rb
+- lib/igniter/incremental.rb
+- lib/igniter/incremental/formatter.rb
+- lib/igniter/incremental/result.rb
+- lib/igniter/incremental/tracker.rb
 - lib/igniter/integrations/agents.rb
 - lib/igniter/integrations/llm.rb
 - lib/igniter/integrations/llm/config.rb