igniter 0.5.1 → 0.5.2

data/packages/igniter-core/lib/igniter/core/extensions/introspection/plan_formatter.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class PlanFormatter
-        def self.to_text(execution, output_names = nil)
-          new(execution, output_names).to_text
-        end
-
-        def initialize(execution, output_names = nil)
-          @execution = execution
-          @plan = execution.plan(output_names)
-        end
-
-        def to_text
-          lines = []
-          lines << "Plan #{@execution.compiled_graph.name}"
-          lines << "Targets: #{format_list(@plan[:targets])}"
-          lines << "Ready: #{format_list(@plan[:ready])}"
-          lines << "Blocked: #{format_list(@plan[:blocked])}"
-          if @plan[:agent_profiles] && @plan[:agent_profiles][:total].positive?
-            lines << "Agents: total=#{@plan[:agent_profiles][:total]}, interactive=#{@plan[:agent_profiles][:interactive]}, manual=#{@plan[:agent_profiles][:manual]}, single_turn=#{@plan[:agent_profiles][:single_turn]}, streaming=#{@plan[:agent_profiles][:streaming]}, deferred=#{@plan[:agent_profiles][:deferred]}"
-          end
-          if @plan[:orchestration] && @plan[:orchestration][:total].positive?
-            lines << "Orchestration: attention_required=#{@plan[:orchestration][:attention_required]}, resumable=#{@plan[:orchestration][:resumable]}, interactive_sessions=#{@plan[:orchestration][:interactive_sessions]}, manual_sessions=#{@plan[:orchestration][:manual_sessions]}, single_turn_sessions=#{@plan[:orchestration][:single_turn_sessions]}, deferred_calls=#{@plan[:orchestration][:deferred_calls]}, single_reply_calls=#{@plan[:orchestration][:single_reply_calls]}, delivery_only=#{@plan[:orchestration][:delivery_only]}"
-            if @plan[:orchestration][:attention_nodes].any?
-              lines << "Attention Nodes: #{format_list(@plan[:orchestration][:attention_nodes])}"
-            end
-            if @plan[:orchestration][:actions].any?
-              lines << "Orchestration Actions: #{@plan[:orchestration][:actions].map { |action| "#{action[:node]}(#{action[:action]})" }.join(', ')}"
-            end
-          end
-          lines << "Nodes:"
-
-          @plan[:nodes].each_value do |entry|
-            lines << format_node(entry)
-          end
-
-          lines.join("\n")
-        end
-
-        private
-
-        def format_node(entry)
-          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
-          line += " ready=true" if entry[:ready]
-          line += " blocked=true" if entry[:blocked]
-          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
-          if entry[:kind] == :agent
-            line += " via=#{entry[:via].inspect}"
-            line += " message=#{entry[:message].inspect}"
-            line += " mode=#{entry[:mode]}"
-            line += " reply=#{entry[:reply_mode]}"
-            line += " session_policy=#{entry[:session_policy]}" if entry[:session_policy]
-            line += " tool_loop_policy=#{entry[:tool_loop_policy]}" if entry[:tool_loop_policy]
-            line += " finalizer=#{entry[:finalizer].inspect}" if entry[:finalizer]
-            if entry[:orchestration]
-              line += " orchestration=#{entry[:orchestration][:interaction]}"
-              line += " guidance=#{entry[:orchestration][:guidance].inspect}"
-              line += " attention_required=true" if entry[:orchestration][:attention_required]
-              line += " resumable=true" if entry[:orchestration][:resumable]
-              line += " allows_continuation=true" if entry[:orchestration][:allows_continuation]
-              line += " requires_explicit_completion=true" if entry[:orchestration][:requires_explicit_completion]
-              line += " auto_finalization=#{entry[:orchestration][:auto_finalization]}"
-            end
-          end
-
-          dependency_summary = entry[:dependencies].map do |dependency|
-            "#{dependency[:name]}(#{dependency[:status]})"
-          end
-          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
-          line
-        end
-
-        def format_list(values)
-          array = Array(values)
-          return "none" if array.empty?
-
-          array.join(",")
-        end
-      end
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/introspection/runtime_formatter.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class RuntimeFormatter
-        def self.states(execution)
-          new(execution).states
-        end
-
-        def self.explain_output(execution, output_name)
-          new(execution).explain_output(output_name)
-        end
-
-        def initialize(execution)
-          @execution = execution
-        end
-
-        def states
-          @execution.cache.to_h.each_with_object({}) do |(node_name, state), memo|
-            memo[node_name] = serialize_state(state)
-          end
-        end
-
-        def explain_output(output_name)
-          output = @execution.compiled_graph.fetch_output(output_name)
-          source = @execution.compiled_graph.fetch_node(output.source_root)
-
-          explanation = {
-            output_id: output.id,
-            output: output.name,
-            path: output.path,
-            source_id: source.id,
-            source: source.name,
-            source_path: source.path,
-            dependencies: dependency_tree(source)
-          }
-
-          if output.composition_output?
-            explanation[:child_output] = output.child_output_name
-            explanation[:child_output_path] = output.source.to_s
-          end
-
-          explanation
-        end
-
-        private
-
-        def dependency_tree(node)
-          state = @execution.cache.fetch(node.name)
-          {
-            id: node.id,
-            name: node.name,
-            path: node.path,
-            kind: node.kind,
-            source_location: node.source_location,
-            status: state&.status,
-            invalidated_by: invalidation_details(state),
-            value: serialize_value(state&.value),
-            error: state&.error&.message,
-            dependencies: node.dependencies.map do |dependency_name|
-              dependency_tree(@execution.compiled_graph.fetch_dependency(dependency_name))
-            end
-          }
-        end
-
-        def serialize_state(state)
-          {
-            id: state.node.id,
-            path: state.node.path,
-            kind: state.node.kind,
-            source_location: state.node.source_location,
-            status: state.status,
-            version: state.version,
-            invalidated_by: invalidation_details(state),
-            details: state.details,
-            value: serialize_value(state.value),
-            error: state.error&.message
-          }
-        end
-
-        def invalidation_details(state)
-          return nil unless state&.invalidated_by
-
-          invalidating_node = @execution.compiled_graph.fetch_node(state.invalidated_by)
-          {
-            node_id: invalidating_node.id,
-            node_name: invalidating_node.name,
-            node_path: invalidating_node.path
-          }
-        end
-
-        def serialize_value(value)
-          case value
-          when Igniter::Runtime::StreamResult
-            {
-              type: :stream,
-              token: value.token,
-              payload: value.payload,
-              source_node: value.source_node,
-              waiting_on: value.waiting_on,
-              phase: value.phase,
-              events: value.events,
-              event_count: value.events.size,
-              status_count: value.status_events.size,
-              tool_call_count: value.tool_calls.size,
-              tool_result_count: value.tool_results.size,
-              tool_interaction_count: value.tool_interactions.size,
-              pending_tool_interaction_count: value.pending_tool_interactions.size,
-              completed_tool_interaction_count: value.completed_tool_interactions.size,
-              orphan_tool_interaction_count: value.orphan_tool_interactions.size,
-              tool_loop_status: value.tool_loop_status,
-              tool_loop_complete: value.tool_loop_complete?,
-              tool_loop_summary: value.tool_loop_summary,
-              tool_runtime: value.tool_runtime,
-              artifact_count: value.artifacts.size,
-              chunks: value.chunks,
-              chunk_count: value.chunks.size
-            }
-          when Igniter::Runtime::DeferredResult
-            {
-              type: :deferred,
-              token: value.token,
-              payload: value.payload,
-              source_node: value.source_node,
-              waiting_on: value.waiting_on
-            }
-          when Igniter::Runtime::Result
-            {
-              type: :result,
-              graph: value.execution.compiled_graph.name,
-              execution_id: value.execution.events.execution_id
-            }
-          when Array
-            value.map { |item| serialize_value(item) }
-          else
-            value
-          end
-        end
-      end
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/introspection.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "introspection/graph_formatter"
-require_relative "introspection/plan_formatter"
-require_relative "introspection/runtime_formatter"
-
-module Igniter
-  module Extensions
-    module Introspection
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/invariants.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../contract"
-require_relative "../errors"
-require_relative "../invariant"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Class method: invariant(name) { |output:, **| condition }
-    #   - Instance method: check_invariants -> Array<InvariantViolation>
-    #   - Automatic post-execution check in resolve_all (raises InvariantError)
-    module Invariants
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-
-      module ClassMethods
-        def invariant(name, &block)
-          @_invariants ||= {}
-          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
-        end
-
-        def invariants
-          @_invariants || {}
-        end
-      end
-
-      module InstanceMethods
-        def resolve_all(...)
-          result = super
-          validate_invariants! unless Thread.current[:igniter_skip_invariants]
-          result
-        end
-
-        def check_invariants
-          return [] if self.class.invariants.empty?
-
-          resolved = collect_output_values
-          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
-        end
-
-        private
-
-        def validate_invariants!
-          violations = check_invariants
-          return if violations.empty?
-
-          names = violations.map { |v| ":#{v.name}" }.join(", ")
-          raise Igniter::InvariantError.new(
-            "#{violations.size} invariant(s) violated: #{names}",
-            violations: violations,
-            context: { contract: self.class.name }
-          )
-        end
-
-        def collect_output_values
-          cache = execution.cache
-          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
-            state = cache.fetch(output_node.source_root)
-            acc[output_node.name] = state.value if state&.succeeded?
-          end
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Invariants)

data/packages/igniter-core/lib/igniter/core/extensions/reactive/engine.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require "set"
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Engine
-        attr_reader :execution, :contract, :reactions, :errors
-
-        def initialize(execution:, contract:, reactions:)
-          @execution = execution
-          @contract = contract
-          @reactions = reactions
-          @errors = []
-          @fired_reactions = Set.new
-        end
-
-        def call(event)
-          reactions.each do |reaction|
-            next unless Matcher.new(reaction, event).match?
-            next if already_fired?(reaction, event)
-
-            mark_fired(reaction, event)
-            call_action(
-              reaction.action,
-              event: event,
-              contract: contract,
-              execution: execution,
-              value: value_for(event)
-            )
-          rescue StandardError => e
-            @errors << {
-              event: event,
-              reaction: reaction,
-              error: e
-            }
-          end
-        end
-
-        private
-
-        def call_action(action, **kwargs)
-          parameters = action.parameters
-          accepts_any_keywords = parameters.any? { |kind, _name| kind == :keyrest }
-
-          if accepts_any_keywords
-            action.call(**kwargs)
-            return
-          end
-
-          accepted_keywords = parameters.select { |kind, _name| %i[key keyreq].include?(kind) }.map(&:last)
-          filtered_kwargs = kwargs.slice(*accepted_keywords)
-          action.call(**filtered_kwargs)
-        end
-
-        def value_for(event)
-          return nil unless %i[node_succeeded node_resumed node_pending].include?(event.type)
-          return nil unless event.node_name
-
-          state = execution.cache.fetch(event.node_name)
-          state&.value
-        end
-
-        def already_fired?(reaction, event)
-          return false unless reaction.once_per_execution
-
-          @fired_reactions.include?(reaction_key(reaction, event))
-        end
-
-        def mark_fired(reaction, event)
-          return unless reaction.once_per_execution
-
-          @fired_reactions << reaction_key(reaction, event)
-        end
-
-        def reaction_key(reaction, event)
-          [reaction.object_id, event.execution_id]
-        end
-      end
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/reactive/matcher.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Matcher
-        def initialize(reaction, event)
-          @reaction = reaction
-          @event = event
-        end
-
-        def match?
-          return false unless @reaction.event_type == @event.type
-          return true unless @reaction.path
-
-          @reaction.path == @event.path
-        end
-      end
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/reactive/reaction.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Reaction
-        attr_reader :event_type, :path, :action, :once_per_execution
-
-        def initialize(event_type:, path: nil, action:, once_per_execution: false)
-          @event_type = event_type.to_sym
-          @path = path&.to_s
-          @action = action
-          @once_per_execution = once_per_execution
-        end
-      end
-    end
-  end
-end

data/packages/igniter-core/lib/igniter/core/extensions/reactive.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "reactive/reaction"
-require_relative "reactive/matcher"
-require_relative "reactive/engine"
-
-module Igniter
-  module Extensions
-    module Reactive
-    end
-  end
-end

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

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "extensions/auditing"
-require_relative "extensions/reactive"
-require_relative "extensions/introspection"
-
-module Igniter
-  module Extensions
-  end
-end

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

@@ -1,43 +0,0 @@
-# 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/packages/igniter-core/lib/igniter/core/incremental/formatter.rb

@@ -1,81 +0,0 @@
-# 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/packages/igniter-core/lib/igniter/core/incremental/result.rb

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