igniter-contracts 0.5.2

data/lib/igniter/contracts/execution/compiler.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class Compiler
+        class << self
+          def compile(profile:, &block)
+            compilation_report(profile: profile, &block).to_compiled_graph
+          end
+
+          def compilation_report(profile:, &block)
+            builder = Builder.build(profile: profile, &block)
+            operations = normalize(builder.operations, profile: profile)
+            findings = validate(operations, profile: profile)
+            validation_report = ValidationReport.new(
+              operations: operations,
+              findings: findings,
+              profile_fingerprint: profile.fingerprint
+            )
+            compiled_graph = if validation_report.ok?
+                               CompiledGraph.new(operations: operations,
+                                                 profile_fingerprint: profile.fingerprint)
+                             end
+
+            CompilationReport.new(
+              operations: operations,
+              validation_report: validation_report,
+              compiled_graph: compiled_graph,
+              profile_fingerprint: profile.fingerprint
+            )
+          end
+
+          def validation_report(profile:, &block)
+            compilation_report(profile: profile, &block).validation_report
+          end
+
+          private
+
+          def normalize(operations, profile:)
+            hook_spec = Assembly::HookSpecs.fetch(:normalizers)
+
+            profile.normalizers.each do |entry|
+              operations = entry.value.call(operations: operations, profile: profile)
+              operations = hook_spec.validate_result!(entry.key, operations)
+            end
+            operations
+          end
+
+          def validate(operations, profile:)
+            hook_spec = Assembly::HookSpecs.fetch(:validators)
+            findings = []
+
+            profile.validators.each do |entry|
+              validator_findings = entry.value.call(operations: operations, profile: profile)
+              validated_findings = hook_spec.validate_result!(entry.key, validator_findings)
+              findings.concat(validated_findings || [])
+            end
+
+            findings
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/const_runtime.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module ConstRuntime
+        module_function
+
+        def handle_const(operation:, **)
+          operation.attributes[:value]
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/diagnostics.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module Diagnostics
+        module_function
+
+        def build_report(result:, profile:)
+          report = DiagnosticsReport.new
+
+          profile.diagnostics_contributors.each do |entry|
+            contributor = entry.value
+            next unless contributor.respond_to?(:augment)
+
+            contributor.augment(report: report, result: result, profile: profile)
+          end
+
+          report
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/diagnostics_report.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class DiagnosticsReport
+        attr_reader :sections
+
+        def initialize
+          @sections = {}
+        end
+
+        def add_section(name, value)
+          section = DiagnosticsSection.new(name: name, value: value)
+          sections[section.name] = section
+          section
+        end
+
+        def section(name)
+          value = section_object(name).value
+          value.is_a?(NamedValues) ? value.to_h : value
+        end
+
+        def section_object(name)
+          sections.fetch(name.to_sym)
+        end
+
+        def section_names
+          sections.keys
+        end
+
+        def to_h
+          {
+            sections: sections.transform_values(&:to_h)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/diagnostics_section.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class DiagnosticsSection
+        attr_reader :name, :value
+
+        def initialize(name:, value:)
+          @name = name.to_sym
+          @value = normalize_value(value)
+          freeze
+        end
+
+        def to_h
+          {
+            name: name,
+            value: StructuredDump.dump(value)
+          }
+        end
+
+        private
+
+        def normalize_value(value)
+          case value
+          when NamedValues
+            value
+          when Hash
+            NamedValues.new(value)
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/effect_invocation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class EffectInvocation
+        attr_reader :payload, :context, :profile
+
+        def initialize(payload:, context:, profile:)
+          @payload = payload
+          @context = context.is_a?(NamedValues) ? context : NamedValues.new(context)
+          @profile = profile
+          freeze
+        end
+
+        def to_h
+          {
+            payload: StructuredDump.dump(payload),
+            context: context.to_h,
+            profile_fingerprint: profile.fingerprint
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/execution_request.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class ExecutionRequest
+        attr_reader :compiled_graph, :inputs, :profile, :runtime
+
+        def initialize(compiled_graph:, inputs:, profile:, runtime:)
+          @compiled_graph = compiled_graph
+          @inputs = inputs.is_a?(NamedValues) ? inputs : NamedValues.new(inputs)
+          @profile = profile
+          @runtime = runtime
+          freeze
+        end
+
+        def to_h
+          {
+            compiled_graph: StructuredDump.dump(compiled_graph),
+            inputs: inputs.to_h,
+            profile_fingerprint: profile.fingerprint,
+            runtime: runtime.name
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/execution_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class ExecutionResult
+        attr_reader :state, :outputs, :profile_fingerprint, :compiled_graph
+
+        def initialize(state:, outputs:, profile_fingerprint:, compiled_graph:)
+          @state = state
+          @outputs = outputs
+          @profile_fingerprint = profile_fingerprint
+          @compiled_graph = compiled_graph
+          freeze
+        end
+
+        def output(name)
+          outputs.fetch(name.to_sym)
+        end
+
+        def to_h
+          {
+            state: state.to_h,
+            outputs: outputs.to_h,
+            profile_fingerprint: profile_fingerprint,
+            compiled_graph: compiled_graph.to_h
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/inline_executor.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module InlineExecutor
+        module_function
+
+        def call(invocation:)
+          invocation.runtime.execute(
+            invocation.compiled_graph,
+            inputs: invocation.inputs,
+            profile: invocation.profile
+          )
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/mutable_named_values.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class MutableNamedValues
+        def initialize(values = {})
+          normalized_values =
+            case values
+            when NamedValues
+              values.to_h
+            when MutableNamedValues
+              values.snapshot.to_h
+            else
+              values
+            end
+
+          @values = normalized_values.transform_keys(&:to_sym)
+        end
+
+        def write(name, value)
+          @values[name.to_sym] = value
+          value
+        end
+
+        def fetch(name)
+          @values.fetch(name.to_sym)
+        end
+
+        def [](name)
+          @values[name.to_sym]
+        end
+
+        def key?(name)
+          @values.key?(name.to_sym)
+        end
+
+        def keys
+          @values.keys
+        end
+
+        def length
+          @values.length
+        end
+
+        def snapshot
+          NamedValues.new(@values)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/named_values.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class NamedValues
+        def initialize(values = {})
+          normalized_values =
+            case values
+            when NamedValues
+              values.to_h
+            when MutableNamedValues
+              values.snapshot.to_h
+            else
+              values
+            end
+
+          @values = normalized_values.transform_keys(&:to_sym).freeze
+          freeze
+        end
+
+        def fetch(name)
+          @values.fetch(name.to_sym)
+        end
+
+        def [](name)
+          @values[name.to_sym]
+        end
+
+        def key?(name)
+          @values.key?(name.to_sym)
+        end
+
+        def keys
+          @values.keys
+        end
+
+        def length
+          @values.length
+        end
+
+        def to_h
+          @values.to_h { |key, value| [key, StructuredDump.dump(value)] }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/operation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class Operation
+        attr_reader :kind, :name, :attributes
+
+        def initialize(kind:, name:, attributes: {})
+          @kind = kind.to_sym
+          @name = name.to_sym
+          @attributes = attributes.transform_keys(&:to_sym).freeze
+          freeze
+        end
+
+        def attribute(key)
+          attributes.fetch(key.to_sym)
+        end
+
+        def attribute?(key)
+          attributes.key?(key.to_sym)
+        end
+
+        def with_attributes(updated_attributes)
+          self.class.new(kind: kind, name: name, attributes: updated_attributes)
+        end
+
+        def output?
+          kind == :output
+        end
+
+        def to_h
+          {
+            kind: kind,
+            name: name,
+            attributes: StructuredDump.dump(attributes)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/runtime.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class Runtime
+        class << self
+          def execute(compiled_graph, inputs:, profile:)
+            validate_profile!(compiled_graph, profile: profile)
+
+            normalized_inputs = NamedValues.new(inputs)
+            state = MutableNamedValues.new
+            outputs = MutableNamedValues.new
+
+            compiled_graph.operations.each do |operation|
+              handler = profile.runtime_handler(operation.kind)
+              value = handler.call(operation: operation, state: state, outputs: outputs, inputs: normalized_inputs,
+                                   profile: profile)
+              state.write(operation.name, value) unless operation.output?
+              outputs.write(operation.name, value) if operation.output?
+            end
+
+            ExecutionResult.new(
+              state: state.snapshot,
+              outputs: outputs.snapshot,
+              profile_fingerprint: profile.fingerprint,
+              compiled_graph: compiled_graph
+            )
+          end
+
+          private
+
+          def validate_profile!(compiled_graph, profile:)
+            return if compiled_graph.profile_fingerprint == profile.fingerprint
+
+            raise ProfileMismatchError,
+                  "compiled graph fingerprint #{compiled_graph.profile_fingerprint} does not match profile #{profile.fingerprint}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/step_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class StepResult
+        attr_reader :value, :failure, :metadata
+
+        def self.success(value, metadata: {})
+          new(value: value, failure: nil, metadata: metadata)
+        end
+
+        def self.failure(code:, message:, details: {}, metadata: {})
+          new(
+            value: nil,
+            failure: {
+              code: code.to_sym,
+              message: message,
+              details: details
+            },
+            metadata: metadata
+          )
+        end
+
+        def initialize(value:, failure:, metadata: {})
+          @value = value
+          @failure = failure&.transform_keys(&:to_sym)
+          @metadata = metadata.transform_keys(&:to_sym).freeze
+          freeze
+        end
+
+        def success?
+          failure.nil?
+        end
+
+        def failure?
+          !success?
+        end
+
+        def to_h
+          {
+            success: success?,
+            value: StructuredDump.dump(value),
+            failure: StructuredDump.dump(failure),
+            metadata: StructuredDump.dump(metadata)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/step_result_diagnostics.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module StepResultDiagnostics
+        module_function
+
+        def augment(report:, result:, profile:) # rubocop:disable Lint/UnusedMethodArgument
+          report.add_section(:step_trace, step_trace(result))
+        end
+
+        def step_trace(result)
+          result.compiled_graph.operations.filter_map do |operation|
+            next unless operation.kind == :step
+
+            step_result = result.state[operation.name]
+            next unless step_result.is_a?(StepResult)
+
+            trace_entry(operation, step_result)
+          end
+        end
+
+        def trace_entry(operation, step_result)
+          {
+            name: operation.name,
+            status: step_result.success? ? :success : :failed,
+            dependencies: Array(operation.attributes[:depends_on]).map(&:to_sym),
+            failure: StructuredDump.dump(step_result.failure)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/step_result_runtime.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module StepResultRuntime
+        module_function
+
+        def handle_step(operation:, state:, **)
+          failed_dependency = failed_step_dependency(operation, state: state)
+          return halted_dependency_result(operation, failed_dependency) if failed_dependency
+
+          callable = operation.attributes[:callable]
+          normalize_step_result(callable.call(**step_dependency_values(operation, state: state)))
+        end
+
+        def failed_step_dependency(operation, state:)
+          Array(operation.attributes[:depends_on]).filter_map do |dependency|
+            dependency_name = dependency.to_sym
+            value = state.fetch(dependency_name)
+
+            { name: dependency_name, result: value } if value.is_a?(StepResult) && value.failure?
+          end.first
+        end
+
+        def halted_dependency_result(operation, dependency)
+          StepResult.failure(
+            code: :halted_dependency,
+            message: "step #{operation.name} halted because dependency #{dependency.fetch(:name)} failed",
+            details: {
+              dependency: dependency.fetch(:name),
+              failure: dependency.fetch(:result).failure
+            }
+          )
+        end
+
+        def step_dependency_values(operation, state:)
+          Array(operation.attributes[:depends_on]).each_with_object({}) do |dependency, memo|
+            dependency_name = dependency.to_sym
+            value = state.fetch(dependency_name)
+            memo[dependency_name] = value.is_a?(StepResult) ? value.value : value
+          end
+        end
+
+        def normalize_step_result(value)
+          value.is_a?(StepResult) ? value : StepResult.success(value)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/execution/step_result_validators.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module StepResultValidators
+        module_function
+
+        def validate_step_dependencies(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          available = operations.reject(&:output?).map(&:name)
+          missing = step_operations(operations)
+                    .flat_map { |operation| Array(operation.attributes[:depends_on]) }
+                    .map(&:to_sym)
+                    .reject { |name| available.include?(name) }
+                    .uniq
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :missing_step_dependencies,
+            message: "step dependencies are not defined: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_step_callables(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          missing = step_operations(operations)
+                    .reject { |operation| operation.attributes[:callable].respond_to?(:call) }
+                    .map(&:name)
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :missing_step_callable,
+            message: "step nodes require a callable: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def step_operations(operations)
+          operations.select { |operation| operation.kind == :step }
+        end
+      end
+    end
+  end
+end