igniter-contracts 0.5.2

data/lib/igniter/contracts/contractable.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Contractable
+      Observation = Struct.new(:name, :value, :metadata, keyword_init: true) do
+        def initialize(name:, value:, metadata: {})
+          super(name: name.to_sym, value: value, metadata: metadata.dup.freeze)
+          freeze
+        end
+
+        def to_h
+          {
+            name: name,
+            value: value,
+            metadata: metadata.dup
+          }
+        end
+      end
+
+      Result = Struct.new(:status, :outputs, :observations, :error, :metadata, keyword_init: true) do
+        def initialize(status:, outputs: {}, observations: [], error: nil, metadata: {})
+          super(
+            status: status.to_sym,
+            outputs: outputs.transform_keys(&:to_sym).freeze,
+            observations: observations.map { |observation| normalize_observation(observation) }.freeze,
+            error: error,
+            metadata: metadata.dup.freeze
+          )
+          freeze
+        end
+
+        def success?
+          status == :success
+        end
+
+        def failure?
+          !success?
+        end
+
+        def to_h
+          {
+            status: status,
+            success: success?,
+            outputs: outputs,
+            observations: observations.map(&:to_h),
+            error: error,
+            metadata: metadata.dup
+          }.compact
+        end
+
+        private
+
+        def normalize_observation(observation)
+          return observation if observation.is_a?(Observation)
+
+          Observation.new(**observation.to_h)
+        end
+      end
+
+      Definition = Struct.new(:method_name, :inputs, :outputs, :role, :stage, :metadata, keyword_init: true) do
+        def initialize(method_name:, inputs: [], outputs: [], role: nil, stage: nil, metadata: {})
+          super(
+            method_name: method_name.to_sym,
+            inputs: inputs.map(&:to_sym).freeze,
+            outputs: outputs.map(&:to_sym).freeze,
+            role: role&.to_sym,
+            stage: stage&.to_sym,
+            metadata: metadata.dup.freeze
+          )
+          freeze
+        end
+
+        def to_h
+          {
+            method_name: method_name,
+            inputs: inputs,
+            outputs: outputs,
+            role: role,
+            stage: stage,
+            metadata: metadata.dup
+          }.compact
+        end
+      end
+
+      class DefinitionBuilder
+        attr_reader :method_name, :inputs, :outputs, :metadata, :role_value, :stage_value
+
+        def initialize(method_name)
+          @method_name = method_name.to_sym
+          @inputs = []
+          @outputs = []
+          @metadata = {}
+          @role_value = nil
+          @stage_value = nil
+        end
+
+        def input(name, **)
+          inputs << name.to_sym
+        end
+
+        def output(name, **)
+          outputs << name.to_sym
+        end
+
+        def role(value)
+          @role_value = value.to_sym
+        end
+
+        def stage(value)
+          @stage_value = value.to_sym
+        end
+
+        def meta(key, value)
+          metadata[key.to_sym] = value
+        end
+
+        def build
+          Definition.new(
+            method_name: method_name,
+            inputs: inputs,
+            outputs: outputs,
+            role: role_value,
+            stage: stage_value,
+            metadata: metadata
+          )
+        end
+      end
+
+      class ExecutionContext
+        attr_reader :observations
+
+        def initialize
+          @observations = []
+        end
+
+        def observe(name, metadata: {})
+          value = yield
+          observations << Observation.new(name: name, value: value, metadata: metadata)
+          value
+        end
+      end
+
+      module InstanceMethods
+        def observe(name, metadata: {}, &block)
+          raise Error, "observe requires a block" unless block
+          raise Error, "observe can only be used during a contractable call" unless @__igniter_contractable_context
+
+          @__igniter_contractable_context.observe(name, metadata: metadata, &block)
+        end
+
+        def success(**outputs)
+          Result.new(status: :success, outputs: outputs, observations: current_observations)
+        end
+
+        def failure(code:, message:, details: {})
+          Result.new(
+            status: :failure,
+            outputs: {},
+            observations: current_observations,
+            error: { code: code.to_sym, message: message, details: details }
+          )
+        end
+
+        private
+
+        def current_observations
+          @__igniter_contractable_context&.observations || []
+        end
+      end
+
+      module ClassMethods
+        def contractable(method_name, &block)
+          builder = DefinitionBuilder.new(method_name)
+          builder.instance_eval(&block) if block
+          @__igniter_contractable_definition = builder.build
+        end
+
+        def contractable_definition
+          @__igniter_contractable_definition || Definition.new(method_name: :call)
+        end
+      end
+
+      class << self
+        def included(base)
+          base.extend(ClassMethods)
+          base.include(InstanceMethods)
+        end
+
+        def invoke(target, **inputs)
+          instance = target.is_a?(Class) ? target.new : target
+          definition = instance.class.contractable_definition
+          input_error = validate_inputs(definition, inputs)
+          return input_error if input_error
+
+          context = ExecutionContext.new
+          instance.instance_variable_set(:@__igniter_contractable_context, context)
+          raw = instance.public_send(definition.method_name, **inputs)
+          result = normalize_result(raw, observations: context.observations)
+          result = with_definition_metadata(result, definition)
+          validate_outputs(definition, result)
+        rescue StandardError => e
+          Result.new(
+            status: :failure,
+            outputs: {},
+            observations: context&.observations || [],
+            metadata: definition ? definition_metadata(definition) : {},
+            error: { code: :contractable_error, message: e.message, class: e.class.name }
+          )
+        ensure
+          instance&.remove_instance_variable(:@__igniter_contractable_context) if instance&.instance_variable_defined?(:@__igniter_contractable_context)
+        end
+
+        def contractable?(target)
+          klass = target.is_a?(Class) ? target : target.class
+          klass.respond_to?(:contractable_definition)
+        end
+
+        private
+
+        def validate_inputs(definition, inputs)
+          missing_inputs = definition.inputs - inputs.keys.map(&:to_sym)
+          return if missing_inputs.empty?
+
+          Result.new(
+            status: :failure,
+            metadata: definition_metadata(definition),
+            error: {
+              code: :contractable_missing_inputs,
+              message: "Missing contractable inputs: #{missing_inputs.join(", ")}",
+              inputs: missing_inputs
+            }
+          )
+        end
+
+        def validate_outputs(definition, result)
+          return result unless result.success?
+          return result if definition.outputs.empty?
+
+          missing_outputs = definition.outputs - result.outputs.keys
+          return result if missing_outputs.empty?
+
+          Result.new(
+            status: :failure,
+            outputs: result.outputs,
+            observations: result.observations,
+            metadata: result.metadata.merge(definition_metadata(definition)),
+            error: {
+              code: :contractable_missing_outputs,
+              message: "Missing contractable outputs: #{missing_outputs.join(", ")}",
+              outputs: missing_outputs
+            }
+          )
+        end
+
+        def with_definition_metadata(result, definition)
+          metadata = definition_metadata(definition)
+          return result if metadata.empty?
+
+          Result.new(
+            status: result.status,
+            outputs: result.outputs,
+            observations: result.observations,
+            error: result.error,
+            metadata: result.metadata.merge(metadata)
+          )
+        end
+
+        def definition_metadata(definition)
+          metadata = definition.metadata.dup
+          metadata[:role] = definition.role if definition.role
+          metadata[:stage] = definition.stage if definition.stage
+          metadata
+        end
+
+        def normalize_result(value, observations:)
+          return value if value.is_a?(Result)
+
+          if value.respond_to?(:to_h)
+            Result.new(status: :success, outputs: value.to_h, observations: observations)
+          else
+            Result.new(status: :success, outputs: { value: value }, observations: observations)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/environment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    class Environment
+      attr_reader :profile
+
+      def initialize(profile:)
+        @profile = profile
+      end
+
+      def compile(&block)
+        Contracts.compile(profile: profile, &block)
+      end
+
+      def validation_report(&block)
+        Contracts.validation_report(profile: profile, &block)
+      end
+
+      def compilation_report(&block)
+        Contracts.compilation_report(profile: profile, &block)
+      end
+
+      def execute(compiled_graph, inputs:)
+        Contracts.execute(compiled_graph, inputs: inputs, profile: profile)
+      end
+
+      def execute_with(executor_name, compiled_graph, inputs:, runtime: Execution::Runtime)
+        Contracts.execute_with(
+          executor_name,
+          compiled_graph,
+          inputs: inputs,
+          profile: profile,
+          runtime: runtime
+        )
+      end
+
+      def run(inputs:, &block)
+        execute(compile(&block), inputs: inputs)
+      end
+
+      def diagnose(result)
+        Contracts.diagnose(result, profile: profile)
+      end
+
+      def apply_effect(effect_name, payload:, context: {})
+        Contracts.apply_effect(effect_name, payload: payload, context: context, profile: profile)
+      end
+    end
+  end
+end

data/lib/igniter/contracts/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    Error = Class.new(StandardError)
+
+    class ValidationError < Error
+      attr_reader :findings
+
+      def initialize(message = nil, findings: [])
+        @findings = Array(findings).freeze
+        super(message || default_message)
+      end
+
+      private
+
+      def default_message
+        return "validation failed" if findings.empty?
+
+        findings.map(&:message).join("; ")
+      end
+
+      public
+
+      def to_h
+        {
+          message: message,
+          findings: findings.map(&:to_h)
+        }
+      end
+    end
+
+    FrozenKernelError = Class.new(Error)
+    FrozenRegistryError = Class.new(Error)
+    DuplicateRegistrationError = Class.new(Error)
+    UnknownDslKeywordError = Class.new(Error)
+    UnknownNodeKindError = Class.new(Error)
+    UnknownEffectError = Class.new(Error)
+    UnknownExecutorError = Class.new(Error)
+    ProfileMismatchError = Class.new(Error)
+    IncompletePackError = Class.new(Error)
+    UnknownPackDependencyError = Class.new(Error)
+    CircularPackDependencyError = Class.new(Error)
+    InvalidHookImplementationError = Class.new(Error)
+    InvalidHookResultError = Class.new(Error)
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module BaselineNormalizers
+        module_function
+
+        def normalize_operation_attributes(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          operations.map do |operation|
+            attributes = operation.attributes
+            normalized_attributes = attributes.dup
+
+            next operation unless normalized_attributes.key?(:depends_on)
+
+            normalized_attributes[:depends_on] = Array(normalized_attributes[:depends_on]).map(&:to_sym)
+            operation.with_attributes(normalized_attributes)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module BaselineRuntime
+        module_function
+
+        def handle_input(operation:, inputs:, **)
+          inputs.fetch(operation.name)
+        end
+
+        def handle_compute(operation:, state:, **)
+          callable = operation.attributes[:callable]
+          kwargs = resolve_dependency_values(operation, state: state)
+          callable.call(**kwargs)
+        end
+
+        def handle_effect(operation:, state:, profile:, **)
+          callable = operation.attributes[:callable]
+          effect_name = operation.attributes.fetch(:using).to_sym
+          dependency_values = resolve_dependency_values(operation, state: state)
+          payload = callable.call(**dependency_values)
+          invocation = EffectInvocation.new(
+            payload: payload,
+            context: {
+              node_name: operation.name,
+              effect_name: effect_name,
+              dependencies: dependency_values
+            },
+            profile: profile
+          )
+
+          profile.effect(effect_name).call(invocation: invocation)
+        end
+
+        def handle_output(operation:, state:, **)
+          state.fetch(operation.name)
+        end
+
+        def unsupported(kind)
+          lambda do |**|
+            raise NotImplementedError, "#{kind} runtime handler is not implemented in the baseline runtime yet"
+          end
+        end
+
+        def resolve_dependency_values(operation, state:)
+          Array(operation.attributes[:depends_on]).each_with_object({}) do |dependency, memo|
+            memo[dependency.to_sym] = state.fetch(dependency.to_sym)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      module BaselineValidators
+        module_function
+
+        def validate_uniqueness(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          names = operations.reject(&:output?).map(&:name)
+          duplicates = names.group_by(&:itself).select { |_name, entries| entries.length > 1 }.keys
+          return [] if duplicates.empty?
+
+          [ValidationFinding.new(
+            code: :duplicate_node_names,
+            message: "duplicate node names: #{duplicates.map(&:to_s).join(", ")}",
+            subjects: duplicates
+          )]
+        end
+
+        def validate_outputs(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          available = operations.reject(&:output?).map(&:name)
+          missing = operations.select(&:output?)
+                              .map(&:name)
+                              .reject { |name| available.include?(name) }
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :missing_output_targets,
+            message: "output targets are not defined: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_dependencies(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          available = operations.reject(&:output?).map(&:name)
+          missing = operations.select { |operation| operation.kind == :compute }
+                              .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_compute_dependencies,
+            message: "compute dependencies are not defined: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_callables(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          missing = operations.select { |operation| operation.kind == :compute }
+                              .reject { |operation| operation.attributes[:callable].respond_to?(:call) }
+                              .map(&:name)
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :missing_compute_callable,
+            message: "compute nodes require a callable: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_effect_dependencies(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          available = operations.reject(&:output?).map(&:name)
+          missing = operations.select { |operation| operation.kind == :effect }
+                              .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_effect_dependencies,
+            message: "effect dependencies are not defined: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_effect_payload_builders(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          missing = operations.select { |operation| operation.kind == :effect }
+                              .reject { |operation| operation.attributes[:callable].respond_to?(:call) }
+                              .map(&:name)
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :missing_effect_payload_builder,
+            message: "effect nodes require a payload callable: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_effect_adapters(operations:, profile:)
+          missing = operations.select { |operation| operation.kind == :effect }
+                              .map { |operation| operation.attributes[:using] }
+                              .reject { |effect_name| profile.supports_effect?(effect_name) }
+                              .uniq
+          return [] if missing.empty?
+
+          [ValidationFinding.new(
+            code: :unknown_effect_adapters,
+            message: "effect adapters are not registered in profile: #{missing.map(&:to_s).join(", ")}",
+            subjects: missing
+          )]
+        end
+
+        def validate_types(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class Builder
+        def self.build(profile:, &block)
+          builder = new(profile: profile)
+          builder.instance_eval(&block)
+          builder
+        end
+
+        attr_reader :profile, :operations
+
+        def initialize(profile:)
+          @profile = profile
+          @operations = []
+        end
+
+        def add_operation(kind:, name:, **attributes)
+          normalized_kind = kind.to_sym
+          unless profile.supports_node_kind?(normalized_kind)
+            raise UnknownNodeKindError,
+                  "unknown node kind #{normalized_kind}"
+          end
+
+          operations << Operation.new(kind: normalized_kind, name: name, attributes: attributes)
+        end
+
+        def method_missing(name, *args, **kwargs, &block)
+          keyword = profile.dsl_keyword(name)
+          keyword.call(*args, builder: self, **kwargs, &block)
+        rescue KeyError
+          raise UnknownDslKeywordError, "unknown DSL keyword #{name}"
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          profile.dsl_keywords.key?(name.to_sym) || super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      class CompilationReport
+        attr_reader :operations, :validation_report, :compiled_graph, :profile_fingerprint
+
+        def initialize(operations:, validation_report:, compiled_graph:, profile_fingerprint:)
+          @operations = operations.freeze
+          @validation_report = validation_report
+          @compiled_graph = compiled_graph
+          @profile_fingerprint = profile_fingerprint
+          freeze
+        end
+
+        def ok?
+          validation_report.ok?
+        end
+
+        def invalid?
+          validation_report.invalid?
+        end
+
+        def findings
+          validation_report.findings
+        end
+
+        def to_compiled_graph
+          validation_report.raise_if_invalid!
+          compiled_graph
+        end
+
+        def to_h
+          {
+            operations: StructuredDump.dump(operations),
+            validation_report: validation_report.to_h,
+            compiled_graph: StructuredDump.dump(compiled_graph),
+            profile_fingerprint: profile_fingerprint,
+            ok: ok?
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Execution
+      CompiledGraph = Struct.new(:operations, :profile_fingerprint, keyword_init: true) do
+        def initialize(operations:, profile_fingerprint:)
+          frozen_operations = operations.freeze
+          super(operations: frozen_operations, profile_fingerprint: profile_fingerprint)
+        end
+
+        def to_h
+          {
+            operations: StructuredDump.dump(operations),
+            profile_fingerprint: profile_fingerprint
+          }
+        end
+      end
+    end
+  end
+end