igniter-extensions 0.5.2

data/lib/igniter/extensions/contracts/incremental/result.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Incremental
+        class Result
+          attr_reader :execution_result, :changed_nodes, :skipped_nodes, :backdated_nodes,
+                      :changed_outputs, :recomputed_count
+
+          def initialize(execution_result:, changed_nodes:, skipped_nodes:, backdated_nodes:, changed_outputs:,
+                         recomputed_count:)
+            @execution_result = execution_result
+            @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
+
+          def outputs_changed?
+            changed_outputs.any?
+          end
+
+          def fully_memoized?
+            recomputed_count.zero?
+          end
+
+          def summary
+            parts = []
+            parts << "#{changed_nodes.length} changed" if changed_nodes.any?
+            parts << "#{skipped_nodes.length} skipped" if skipped_nodes.any?
+            parts << "#{backdated_nodes.length} backdated" if backdated_nodes.any?
+            parts << "#{recomputed_count} recomputed"
+            parts.join(", ")
+          end
+
+          def explain
+            Formatter.format(self)
+          end
+
+          alias to_s explain
+
+          def output(name)
+            execution_result.output(name)
+          end
+
+          def to_h
+            {
+              changed_nodes: changed_nodes,
+              skipped_nodes: skipped_nodes,
+              backdated_nodes: backdated_nodes,
+              changed_outputs: changed_outputs,
+              recomputed_count: recomputed_count,
+              outputs_changed: outputs_changed?,
+              fully_memoized: fully_memoized?,
+              execution_result: execution_result.to_h
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/incremental/session.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Incremental
+        class Session
+          attr_reader :compiled_graph, :profile
+
+          def initialize(compiled_graph:, profile:)
+            @compiled_graph = compiled_graph
+            @profile = profile
+            @node_states = {}
+            @last_result = nil
+          end
+
+          def run(inputs:)
+            normalized_inputs = Igniter::Contracts::NamedValues.new(inputs)
+            current_values = Igniter::Contracts::MutableNamedValues.new
+            current_outputs = Igniter::Contracts::MutableNamedValues.new
+            current_states = {}
+
+            changed_nodes = []
+            skipped_nodes = []
+            backdated_nodes = []
+            recomputed_count = 0
+
+            compiled_graph.operations.each do |operation|
+              if operation.output?
+                current_outputs.write(operation.name, current_values.fetch(operation.name))
+                next
+              end
+
+              if operation.kind == :input
+                state = resolve_input_state(operation, normalized_inputs)
+                current_states[operation.name] = state
+                current_values.write(operation.name, state.value)
+                changed_nodes << operation.name if changed_value?(operation.name, state.value)
+                next
+              end
+
+              dependency_versions = dependency_names_for(operation).each_with_object({}) do |dependency_name, memo|
+                if current_states.key?(dependency_name)
+                  memo[dependency_name] =
+                    current_states.fetch(dependency_name).value_version
+                end
+              end
+
+              previous = @node_states[operation.name]
+
+              if previous && previous.dep_snapshot == dependency_versions
+                current_states[operation.name] = previous
+                current_values.write(operation.name, previous.value)
+                skipped_nodes << operation.name
+                next
+              end
+
+              handler = profile.runtime_handler(operation.kind)
+              value = handler.call(
+                operation: operation,
+                state: current_values,
+                outputs: current_outputs,
+                inputs: normalized_inputs,
+                profile: profile
+              )
+
+              value_version =
+                if previous && previous.value == value
+                  backdated_nodes << operation.name
+                  previous.value_version
+                else
+                  changed_nodes << operation.name if changed_value?(operation.name, value)
+                  previous ? previous.value_version + 1 : 1
+                end
+
+              current_states[operation.name] = NodeState.new(
+                name: operation.name,
+                value: value,
+                value_version: value_version,
+                dep_snapshot: dependency_versions
+              )
+              current_values.write(operation.name, value)
+              recomputed_count += 1
+            end
+
+            execution_result = Igniter::Contracts::ExecutionResult.new(
+              state: current_values.snapshot,
+              outputs: current_outputs.snapshot,
+              profile_fingerprint: profile.fingerprint,
+              compiled_graph: compiled_graph
+            )
+
+            result = Result.new(
+              execution_result: execution_result,
+              changed_nodes: changed_nodes.uniq,
+              skipped_nodes: skipped_nodes.uniq,
+              backdated_nodes: backdated_nodes.uniq,
+              changed_outputs: changed_outputs_for(execution_result),
+              recomputed_count: recomputed_count
+            )
+
+            @node_states = current_states.freeze
+            @last_result = result
+          end
+
+          private
+
+          def resolve_input_state(operation, normalized_inputs)
+            value = normalized_inputs.fetch(operation.name)
+            previous = @node_states[operation.name]
+            value_version = previous && previous.value == value ? previous.value_version : (previous&.value_version || 0) + 1
+
+            NodeState.new(
+              name: operation.name,
+              value: value,
+              value_version: value_version
+            )
+          end
+
+          def dependency_names_for(operation)
+            names = []
+            names.concat(Array(operation.attributes[:depends_on])) if operation.attribute?(:depends_on)
+            names << operation.attributes[:from] if operation.attribute?(:from)
+            names.map(&:to_sym).uniq
+          end
+
+          def changed_outputs_for(execution_result)
+            previous_outputs = @last_result&.execution_result&.outputs
+            execution_result.outputs.keys.each_with_object({}) do |name, memo|
+              previous = previous_outputs&.[](name)
+              current = execution_result.outputs[name]
+              next if previous == current
+
+              memo[name] = { from: previous, to: current }
+            end
+          end
+
+          def changed_value?(name, value)
+            previous = @node_states[name]
+            previous.nil? || previous.value != value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/incremental_pack.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "incremental/node_state"
+require_relative "incremental/formatter"
+require_relative "incremental/result"
+require_relative "incremental/session"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module IncrementalPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_incremental,
+            metadata: { category: :orchestration }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def session(environment, compiled_graph: nil, &block)
+          graph = compiled_graph || environment.compile(&block)
+          ensure_installed!(environment.profile)
+          Incremental::Session.new(compiled_graph: graph, profile: environment.profile)
+        end
+
+        def ensure_installed!(profile)
+          return if profile.pack_names.include?(:extensions_incremental)
+
+          raise Igniter::Contracts::Error,
+                "IncrementalPack is not installed in profile #{profile.fingerprint}; add Igniter::Extensions::Contracts::IncrementalPack"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/builder.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Builder
+          attr_reader :suite
+
+          def initialize
+            @suite = Suite.new(invariants: [])
+          end
+
+          def invariant(name, &block)
+            @suite = suite.invariant(name, &block)
+          end
+
+          def self.build(&block)
+            builder = new
+            builder.instance_eval(&block) if block
+            builder.suite
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/cases_report.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class CasesReport
+          attr_reader :reports
+
+          def initialize(reports:)
+            @reports = reports.freeze
+            freeze
+          end
+
+          def valid?
+            reports.all?(&:valid?)
+          end
+
+          def invalid_cases
+            reports.each_with_index.filter_map do |report, index|
+              next if report.valid?
+
+              {
+                index: index,
+                report: report.to_h
+              }
+            end
+          end
+
+          def summary
+            return "all cases valid" if valid?
+
+            "#{invalid_cases.length} invalid case(s)"
+          end
+
+          def to_h
+            {
+              valid: valid?,
+              case_count: reports.length,
+              invalid_cases: invalid_cases
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Error < StandardError; end
+
+        class InvariantError < Error
+          attr_reader :violations
+
+          def initialize(message = nil, violations: [])
+            @violations = Array(violations).freeze
+            super(message || default_message)
+          end
+
+          def to_h
+            {
+              message: message,
+              violations: violations.map(&:to_h)
+            }
+          end
+
+          private
+
+          def default_message
+            names = violations.map { |violation| ":#{violation.name}" }.join(", ")
+            "#{violations.length} invariant(s) violated: #{names}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/invariant.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Invariant
+          attr_reader :name, :block
+
+          def initialize(name, &block)
+            raise ArgumentError, "invariant #{name.inspect} requires a block" unless block
+
+            @name = name.to_sym
+            @block = block
+            freeze
+          end
+
+          def check(outputs)
+            passed = block.call(**outputs)
+            return nil if passed
+
+            Violation.new(name: name, outputs: outputs)
+          rescue StandardError => e
+            Violation.new(name: name, outputs: outputs, error: e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/report.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Report
+          attr_reader :suite, :outputs, :violations, :execution_result
+
+          def initialize(suite:, outputs:, violations:, execution_result: nil)
+            @suite = suite
+            @outputs = outputs.transform_keys(&:to_sym).freeze
+            @violations = Array(violations).freeze
+            @execution_result = execution_result
+            freeze
+          end
+
+          def valid?
+            violations.empty?
+          end
+
+          def invalid?
+            !valid?
+          end
+
+          def summary
+            return "valid" if valid?
+
+            "invalid - #{violations.length} invariant(s) violated: #{violations.map(&:name).join(", ")}"
+          end
+
+          def to_h
+            {
+              valid: valid?,
+              outputs: outputs,
+              invariants: suite.names,
+              violations: violations.map(&:to_h),
+              execution_result: execution_result&.to_h
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/suite.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Suite
+          attr_reader :invariants
+
+          def initialize(invariants:)
+            @invariants = invariants.freeze
+            freeze
+          end
+
+          def invariant(name, &block)
+            self.class.new(invariants: invariants + [Invariant.new(name, &block)])
+          end
+
+          def empty?
+            invariants.empty?
+          end
+
+          def names
+            invariants.map(&:name)
+          end
+
+          def to_h
+            {
+              invariants: names
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants/violation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Invariants
+        class Violation
+          attr_reader :name, :outputs, :error
+
+          def initialize(name:, outputs:, error: nil)
+            @name = name.to_sym
+            @outputs = outputs.transform_keys(&:to_sym).freeze
+            @error = error
+            freeze
+          end
+
+          def passed?
+            false
+          end
+
+          def failed?
+            true
+          end
+
+          def to_h
+            {
+              name: name,
+              outputs: outputs,
+              error: error && {
+                type: error.class.name,
+                message: error.message
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/invariants_pack.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "invariants/error"
+require_relative "invariants/invariant"
+require_relative "invariants/violation"
+require_relative "invariants/suite"
+require_relative "invariants/builder"
+require_relative "invariants/report"
+require_relative "invariants/cases_report"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module InvariantsPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_invariants,
+            metadata: { category: :validation }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def build(&block)
+          Invariants::Builder.build(&block)
+        end
+
+        def check(target, invariants:)
+          execution_result = unwrap_execution_result(target)
+          outputs = execution_result.outputs.to_h
+          violations = invariants.invariants.filter_map { |invariant| invariant.check(outputs) }
+
+          Invariants::Report.new(
+            suite: invariants,
+            outputs: outputs,
+            violations: violations,
+            execution_result: execution_result
+          )
+        end
+
+        def validate!(target, invariants:)
+          report = check(target, invariants: invariants)
+          raise Invariants::InvariantError.new(nil, violations: report.violations) if report.invalid?
+
+          report
+        end
+
+        def run(environment, inputs:, invariants:, compiled_graph: nil, &block)
+          graph =
+            if block
+              environment.compile(&block)
+            else
+              compiled_graph || raise(ArgumentError, "invariant run requires a block or compiled_graph")
+            end
+
+          result = environment.execute(graph, inputs: inputs)
+          check(result, invariants: invariants)
+        end
+
+        def verify_cases(environment, cases:, invariants:, compiled_graph: nil, &block)
+          graph =
+            if block
+              environment.compile(&block)
+            else
+              compiled_graph || raise(ArgumentError, "verify_cases requires a block or compiled_graph")
+            end
+
+          reports = Array(cases).map do |inputs|
+            result = environment.execute(graph, inputs: inputs)
+            check(result, invariants: invariants)
+          end
+
+          Invariants::CasesReport.new(reports: reports)
+        end
+
+        def unwrap_execution_result(target)
+          return target.execution_result if target.respond_to?(:execution_result)
+
+          target
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/journal_pack.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module JournalPack
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_journal,
+              registry_contracts: [
+                Igniter::Contracts::PackManifest.effect(:journal),
+                Igniter::Contracts::PackManifest.executor(:journaled_inline)
+              ]
+            )
+          end
+
+          def install_into(kernel)
+            kernel.effects.register(:journal, method(:apply_journal_effect))
+            kernel.executors.register(:journaled_inline, method(:execute_journaled_inline))
+            kernel
+          end
+
+          def journal
+            @journal ||= {
+              effects: [],
+              executions: [],
+              results: []
+            }
+          end
+
+          def reset_journal!
+            journal.each_value(&:clear)
+          end
+
+          def apply_journal_effect(invocation:)
+            journal[:effects] << invocation.to_h
+            invocation.payload
+          end
+
+          def execute_journaled_inline(invocation:)
+            journal[:executions] << invocation.to_h
+            result = invocation.runtime.execute(
+              invocation.compiled_graph,
+              inputs: invocation.inputs,
+              profile: invocation.profile
+            )
+            journal[:results] << result.to_h
+            result
+          end
+        end
+      end
+    end
+  end
+end