igniter-extensions 0.5.2

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "provenance/node_trace"
+require_relative "provenance/text_formatter"
+require_relative "provenance/lineage"
+require_relative "provenance/builder"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ProvenancePack
+        module_function
+
+        REPORT_CONTRIBUTOR = Module.new do
+          module_function
+
+          def augment(report:, result:, profile:) # rubocop:disable Lint/UnusedMethodArgument
+            summary = result.outputs.keys.sort.each_with_object({}) do |output_name, memo|
+              lineage = Igniter::Extensions::Contracts::ProvenancePack.lineage(result, output_name)
+              memo[output_name] = {
+                value: lineage.value,
+                contributing_inputs: lineage.contributing_inputs
+              }
+            end
+
+            report.add_section(:provenance, { outputs: summary })
+          end
+        end
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_provenance,
+            registry_contracts: [Igniter::Contracts::PackManifest.diagnostic(:provenance)]
+          )
+        end
+
+        def install_into(kernel)
+          kernel.diagnostics_contributors.register(:provenance, REPORT_CONTRIBUTOR)
+          kernel
+        end
+
+        def lineage(result, output_name)
+          Provenance::Builder.build(output_name, result)
+        end
+
+        def explain(result, output_name)
+          lineage(result, output_name).explain
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class Builder
+          attr_reader :plan
+
+          def initialize
+            @plan = Plan.new(subscriptions: [])
+          end
+
+          def react_to(event_type, path: nil, once_per_dispatch: false, &block)
+            @plan = plan.react_to(event_type, path: path, once_per_dispatch: once_per_dispatch, &block)
+          end
+
+          def effect(path, &block)
+            @plan = plan.effect(path, &block)
+          end
+
+          def on_success(path = nil, &block)
+            @plan = plan.on_success(path, &block)
+          end
+
+          def on_failure(&block)
+            @plan = plan.on_failure(&block)
+          end
+
+          def on_exit(&block)
+            @plan = plan.on_exit(&block)
+          end
+
+          def self.build(&block)
+            builder = new
+            builder.instance_eval(&block) if block
+            builder.plan
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/dispatch_result.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class DispatchResult
+          attr_reader :status, :events, :errors, :result, :execution_result, :execution_error
+
+          def initialize(status:, events:, errors:, result:, execution_result:, execution_error: nil)
+            @status = status.to_sym
+            @events = events.freeze
+            @errors = errors.freeze
+            @result = result
+            @execution_result = execution_result
+            @execution_error = execution_error
+            freeze
+          end
+
+          def success?
+            status == :succeeded
+          end
+
+          def failed?
+            status == :failed
+          end
+
+          def output(name)
+            execution_result&.output(name)
+          end
+
+          def to_h
+            {
+              status: status,
+              success: success?,
+              events: events.map(&:to_h),
+              errors: errors.map do |entry|
+                {
+                  event: entry.fetch(:event).to_h,
+                  subscription: entry.fetch(:subscription).to_h,
+                  error: {
+                    type: entry.fetch(:error).class.name,
+                    message: entry.fetch(:error).message
+                  }
+                }
+              end,
+              execution_error: execution_error && {
+                type: execution_error.class.name,
+                message: execution_error.message
+              },
+              result: result&.to_h,
+              execution_result: execution_result&.to_h
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/engine.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class Engine
+          attr_reader :plan, :errors
+
+          def initialize(plan:)
+            @plan = plan
+            @errors = []
+            @fired = Set.new
+          end
+
+          def call(events:, result:, execution_result:, execution_error: nil)
+            events.each do |event|
+              plan.subscriptions.each do |subscription|
+                next unless Matcher.match?(subscription, event)
+                next if already_fired?(subscription, event)
+
+                mark_fired(subscription, event)
+                call_action(
+                  subscription.action,
+                  event: event,
+                  result: result,
+                  execution_result: execution_result,
+                  execution_error: execution_error,
+                  value: event.value,
+                  status: event.status,
+                  outputs: execution_result&.outputs&.to_h
+                )
+              rescue StandardError => e
+                errors << {
+                  event: event,
+                  subscription: subscription,
+                  error: e
+                }
+              end
+            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 = parameters.select { |kind, _name| %i[key keyreq].include?(kind) }.map(&:last)
+            action.call(**kwargs.slice(*accepted))
+          end
+
+          def already_fired?(subscription, event)
+            return false unless subscription.once_per_dispatch
+
+            @fired.include?(firing_key(subscription, event))
+          end
+
+          def mark_fired(subscription, event)
+            return unless subscription.once_per_dispatch
+
+            @fired << firing_key(subscription, event)
+          end
+
+          def firing_key(subscription, event)
+            [subscription.object_id, event.type, event.path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class Event
+          attr_reader :event_id, :type, :path, :status, :payload
+
+          def initialize(event_id:, type:, path:, status:, payload: {})
+            @event_id = event_id.to_s
+            @type = type.to_sym
+            @path = path&.to_sym
+            @status = status.to_sym
+            @payload = payload.freeze
+            freeze
+          end
+
+          def value
+            payload[:value]
+          end
+
+          def to_h
+            {
+              event_id: event_id,
+              type: type,
+              path: path,
+              status: status,
+              payload: payload
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/matcher.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        module Matcher
+          module_function
+
+          def match?(subscription, event)
+            return false unless subscription.event_type == event.type
+            return true if subscription.path.nil?
+
+            subscription.path == event.path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/plan.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class Plan
+          attr_reader :subscriptions
+
+          def initialize(subscriptions:)
+            @subscriptions = subscriptions.freeze
+            freeze
+          end
+
+          def react_to(event_type, path: nil, once_per_dispatch: false, &block)
+            with_subscription(
+              Subscription.new(
+                event_type: event_type,
+                path: path,
+                action: block,
+                once_per_dispatch: once_per_dispatch
+              )
+            )
+          end
+
+          def effect(path, &block)
+            react_to(:output_produced, path: path, &block)
+          end
+
+          def on_success(path = nil, &block)
+            event_type = path.nil? ? :execution_succeeded : :output_produced
+            react_to(event_type, path: path, once_per_dispatch: true, &block)
+          end
+
+          def on_failure(&block)
+            react_to(:execution_failed, once_per_dispatch: true, &block)
+          end
+
+          def on_exit(&block)
+            react_to(:execution_exited, once_per_dispatch: true, &block)
+          end
+
+          def to_h
+            {
+              subscriptions: subscriptions.map(&:to_h)
+            }
+          end
+
+          private
+
+          def with_subscription(subscription)
+            self.class.new(subscriptions: subscriptions + [subscription])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/reactive/subscription.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Reactive
+        class Subscription
+          attr_reader :event_type, :path, :action, :once_per_dispatch
+
+          def initialize(event_type:, action:, path: nil, once_per_dispatch: false)
+            @event_type = event_type.to_sym
+            @path = path&.to_sym
+            @action = action
+            @once_per_dispatch = once_per_dispatch
+            freeze
+          end
+
+          def to_h
+            {
+              event_type: event_type,
+              path: path,
+              once_per_dispatch: once_per_dispatch
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "reactive/event"
+require_relative "reactive/subscription"
+require_relative "reactive/matcher"
+require_relative "reactive/plan"
+require_relative "reactive/builder"
+require_relative "reactive/dispatch_result"
+require_relative "reactive/engine"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ReactivePack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_reactive,
+            metadata: { category: :orchestration }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def build(&block)
+          Reactive::Builder.build(&block)
+        end
+
+        def dispatch(target, reactions:)
+          result = target
+          execution_result = unwrap_execution_result(target)
+          events = build_events(target, execution_result: execution_result)
+
+          engine = Reactive::Engine.new(plan: reactions)
+          engine.call(events: events, result: result, execution_result: execution_result)
+
+          Reactive::DispatchResult.new(
+            status: :succeeded,
+            events: events,
+            errors: engine.errors,
+            result: result,
+            execution_result: execution_result
+          )
+        end
+
+        def run(environment, inputs:, reactions:, compiled_graph: nil, &block)
+          graph =
+            if block
+              environment.compile(&block)
+            else
+              compiled_graph || raise(ArgumentError, "reactive run requires a block or compiled_graph")
+            end
+
+          begin
+            result = environment.execute(graph, inputs: inputs)
+            dispatch(result, reactions: reactions)
+          rescue StandardError => e
+            dispatch_failure(e, reactions: reactions)
+          end
+        end
+
+        def run_incremental(session, inputs:, reactions:)
+          result = session.run(inputs: inputs)
+          dispatch(result, reactions: reactions)
+        end
+
+        def dispatch_failure(error, reactions:)
+          events = [
+            Reactive::Event.new(
+              event_id: "execution_failed",
+              type: :execution_failed,
+              path: :execution,
+              status: :failed,
+              payload: {
+                error_type: error.class.name,
+                error_message: error.message
+              }
+            ),
+            Reactive::Event.new(
+              event_id: "execution_exited",
+              type: :execution_exited,
+              path: :execution,
+              status: :failed,
+              payload: {
+                error_type: error.class.name,
+                error_message: error.message
+              }
+            )
+          ]
+
+          engine = Reactive::Engine.new(plan: reactions)
+          engine.call(events: events, result: nil, execution_result: nil, execution_error: error)
+
+          Reactive::DispatchResult.new(
+            status: :failed,
+            events: events,
+            errors: engine.errors,
+            result: nil,
+            execution_result: nil,
+            execution_error: error
+          )
+        end
+
+        def unwrap_execution_result(target)
+          return target.execution_result if target.respond_to?(:execution_result)
+
+          target
+        end
+
+        def build_events(target, execution_result:)
+          events = []
+
+          events << Reactive::Event.new(
+            event_id: "execution_succeeded",
+            type: :execution_succeeded,
+            path: :execution,
+            status: :succeeded,
+            payload: {
+              output_names: execution_result.outputs.keys
+            }
+          )
+
+          execution_result.outputs.to_h.each do |name, value|
+            events << Reactive::Event.new(
+              event_id: "output_produced:#{name}",
+              type: :output_produced,
+              path: name,
+              status: :succeeded,
+              payload: {
+                value: value
+              }
+            )
+          end
+
+          if target.respond_to?(:changed_outputs)
+            target.changed_outputs.each do |name, change|
+              events << Reactive::Event.new(
+                event_id: "output_changed:#{name}",
+                type: :output_changed,
+                path: name,
+                status: :succeeded,
+                payload: {
+                  value: execution_result.output(name),
+                  previous_value: change[:from],
+                  current_value: change[:to]
+                }
+              )
+            end
+          end
+
+          events << Reactive::Event.new(
+            event_id: "execution_exited",
+            type: :execution_exited,
+            path: :execution,
+            status: :succeeded,
+            payload: {
+              output_names: execution_result.outputs.keys
+            }
+          )
+
+          events.freeze
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/saga/compensation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        class Compensation
+          attr_reader :node_name, :block
+
+          def initialize(node_name, &block)
+            raise ArgumentError, "compensate :#{node_name} requires a block" unless block
+
+            @node_name = node_name.to_sym
+            @block = block
+            freeze
+          end
+
+          def run(inputs:, value:)
+            block.call(inputs: inputs, value: value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/saga/compensation_record.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        class CompensationRecord
+          attr_reader :node_name, :error
+
+          def initialize(node_name:, success:, error: nil)
+            @node_name = node_name.to_sym
+            @success = success
+            @error = error
+            freeze
+          end
+
+          def success?
+            @success
+          end
+
+          def failed?
+            !success?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/saga/compensation_set.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        class CompensationSet
+          def self.build(&block)
+            new.tap do |set|
+              set.instance_eval(&block) if block
+              set.finalize!
+            end
+          end
+
+          def initialize
+            @compensations = {}
+          end
+
+          def compensate(node_name, &block)
+            @compensations[node_name.to_sym] = Compensation.new(node_name, &block)
+          end
+
+          def [](node_name)
+            @compensations[node_name.to_sym]
+          end
+
+          def key?(node_name)
+            @compensations.key?(node_name.to_sym)
+          end
+
+          def to_h
+            @compensations.dup
+          end
+
+          def keys
+            @compensations.keys
+          end
+
+          def finalize!
+            @compensations.freeze
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/saga/formatter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        module Formatter
+          module_function
+
+          def format(result)
+            lines = []
+            lines << "Status:   #{result.success? ? "SUCCESS" : "FAILED"}"
+            lines << "Profile:  #{result.execution_result.profile_fingerprint}"
+
+            unless result.success?
+              lines << "Error:    #{result.error.message}"
+              lines << "At node:  :#{result.failed_node}" if result.failed_node
+            end
+
+            append_compensations(result, lines)
+            lines.join("\n")
+          end
+
+          def append_compensations(result, lines)
+            return if result.compensations.empty?
+
+            lines << ""
+            lines << "COMPENSATIONS (#{result.compensations.length}):"
+            result.compensations.each do |record|
+              tag = record.success? ? "[ok]   " : "[fail] "
+              lines << "  #{tag} :#{record.node_name}"
+              lines << "    error: #{record.error.message}" if record.failed?
+            end
+          end
+        end
+      end
+    end
+  end
+end