igniter-extensions 0.5.2

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        class Result
+          attr_reader :execution_result, :error, :failed_node, :compensations
+
+          def initialize(success:, execution_result:, error: nil, failed_node: nil, compensations: [])
+            @success = success
+            @execution_result = execution_result
+            @error = error
+            @failed_node = failed_node&.to_sym
+            @compensations = compensations.freeze
+            freeze
+          end
+
+          def success?
+            @success
+          end
+
+          def failed?
+            !success?
+          end
+
+          def output(name)
+            execution_result.output(name)
+          end
+
+          def explain
+            Formatter.format(self)
+          end
+
+          alias to_s explain
+
+          def to_h
+            {
+              success: success?,
+              failed_node: failed_node,
+              error: error&.message,
+              compensations: compensations.map do |record|
+                {
+                  node: record.node_name,
+                  success: record.success?,
+                  error: record.error&.message
+                }
+              end,
+              execution_result: execution_result.to_h
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Saga
+        class SagaError < Igniter::Contracts::Error; end
+
+        class Runner
+          def initialize(compiled_graph:, profile:, compensations:)
+            @compiled_graph = compiled_graph
+            @profile = profile
+            @compensations = normalize_compensations(compensations)
+          end
+
+          def run(inputs:)
+            state = Igniter::Contracts::MutableNamedValues.new
+            outputs = Igniter::Contracts::MutableNamedValues.new
+            normalized_inputs = Igniter::Contracts::NamedValues.new(inputs)
+            completed_operations = []
+            failed_operation = nil
+
+            @compiled_graph.operations.each do |operation|
+              failed_operation = 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?
+              completed_operations << operation unless operation.output?
+            end
+
+            Result.new(
+              success: true,
+              execution_result: execution_result_for(state, outputs)
+            )
+          rescue StandardError => e
+            execution_result = execution_result_for(state, outputs)
+
+            Result.new(
+              success: false,
+              execution_result: execution_result,
+              error: e,
+              failed_node: failed_operation&.name,
+              compensations: run_compensations(
+                completed_operations.reverse,
+                execution_result: execution_result,
+                inputs: normalized_inputs
+              )
+            )
+          end
+
+          private
+
+          def normalize_compensations(compensations)
+            case compensations
+            when CompensationSet
+              compensations
+            else
+              CompensationSet.new.tap do |set|
+                compensations.each do |node_name, handler|
+                  set.compensate(node_name, &handler)
+                end
+                set.finalize!
+              end
+            end
+          end
+
+          def execution_result_for(state, outputs)
+            Igniter::Contracts::ExecutionResult.new(
+              state: state.snapshot,
+              outputs: outputs.snapshot,
+              profile_fingerprint: @profile.fingerprint,
+              compiled_graph: @compiled_graph
+            )
+          end
+
+          def run_compensations(operations, execution_result:, inputs:)
+            operations.filter_map do |operation|
+              compensation = @compensations[operation.name]
+              next unless compensation
+
+              attempt_compensation(compensation, operation, execution_result: execution_result, inputs: inputs)
+            end
+          end
+
+          def attempt_compensation(compensation, operation, execution_result:, inputs:)
+            compensation.run(
+              inputs: compensation_inputs_for(operation, execution_result: execution_result, inputs: inputs),
+              value: execution_result.state[operation.name]
+            )
+            CompensationRecord.new(node_name: compensation.node_name, success: true)
+          rescue StandardError => e
+            CompensationRecord.new(node_name: compensation.node_name, success: false, error: e)
+          end
+
+          def compensation_inputs_for(operation, execution_result:, inputs:)
+            dependency_names_for(operation).each_with_object({}) do |dependency_name, memo|
+              memo[dependency_name] =
+                if execution_result.state.key?(dependency_name)
+                  execution_result.state[dependency_name]
+                else
+                  inputs[dependency_name]
+                end
+            end
+          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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "saga/compensation"
+require_relative "saga/compensation_record"
+require_relative "saga/compensation_set"
+require_relative "saga/formatter"
+require_relative "saga/result"
+require_relative "saga/runner"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module SagaPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_saga,
+            metadata: { category: :orchestration }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def build(&block)
+          Saga::CompensationSet.build(&block)
+        end
+
+        def run(environment, inputs:, compensations:, compiled_graph: nil, &block)
+          profile = environment.profile
+          ensure_installed!(profile)
+          graph = compiled_graph || environment.compile(&block)
+
+          Saga::Runner.new(
+            compiled_graph: graph,
+            profile: profile,
+            compensations: compensations
+          ).run(inputs: inputs)
+        end
+
+        def explain(result)
+          result.explain
+        end
+
+        def ensure_installed!(profile)
+          return if profile.pack_names.include?(:extensions_saga)
+
+          raise Saga::SagaError,
+                "SagaPack is not installed in profile #{profile.fingerprint}; add Igniter::Extensions::Contracts::SagaPack"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts.rb

@@ -0,0 +1,445 @@
+# frozen_string_literal: true
+
+require "igniter/contracts"
+require_relative "contracts/aggregate_pack"
+require_relative "contracts/audit_pack"
+require_relative "contracts/branch_pack"
+require_relative "contracts/capabilities_pack"
+require_relative "contracts/collection_pack"
+require_relative "contracts/commerce_pack"
+require_relative "contracts/compose_pack"
+require_relative "contracts/content_addressing_pack"
+require_relative "contracts/creator_pack"
+require_relative "contracts/dataflow_pack"
+require_relative "contracts/debug_pack"
+require_relative "contracts/differential_pack"
+require_relative "contracts/execution_report_pack"
+require_relative "contracts/incremental_pack"
+require_relative "contracts/invariants_pack"
+require_relative "contracts/journal_pack"
+require_relative "contracts/language/formula_pack"
+require_relative "contracts/language/piecewise_pack"
+require_relative "contracts/language/scale_pack"
+require_relative "contracts/lookup_pack"
+require_relative "contracts/mcp_pack"
+require_relative "contracts/provenance_pack"
+require_relative "contracts/reactive_pack"
+require_relative "contracts/saga_pack"
+
+module Igniter
+  module Extensions
+    module Contracts
+      DEFAULT_PACKS = [
+        ExecutionReportPack,
+        LookupPack
+      ].freeze
+
+      AVAILABLE_PACKS = (
+        DEFAULT_PACKS +
+        [AggregatePack, AuditPack, BranchPack, CapabilitiesPack, CollectionPack, CommercePack, ComposePack,
+         ContentAddressingPack, CreatorPack, DataflowPack, DebugPack, DifferentialPack, IncrementalPack,
+         InvariantsPack, JournalPack, Language::FormulaPack, Language::PiecewisePack, Language::ScalePack,
+         McpPack, ProvenancePack, ReactivePack, SagaPack]
+      ).freeze
+
+      PRESETS = {
+        default: DEFAULT_PACKS,
+        commerce: [ExecutionReportPack, CommercePack]
+      }.freeze
+
+      class << self
+        def default_packs
+          DEFAULT_PACKS
+        end
+
+        def available_packs
+          AVAILABLE_PACKS
+        end
+
+        def presets
+          PRESETS
+        end
+
+        def packs_for(name)
+          presets.fetch(name.to_sym)
+        rescue KeyError
+          raise ArgumentError, "unknown contracts preset #{name}"
+        end
+
+        def build_profile(*packs)
+          Igniter::Contracts.build_profile(*normalize_packs(packs))
+        end
+
+        def with(*packs)
+          Igniter::Contracts.with(*normalize_packs(packs))
+        end
+
+        def build_preset_profile(name)
+          build_profile(*packs_for(name))
+        end
+
+        def with_preset(name)
+          with(*packs_for(name))
+        end
+
+        def lineage(result, output_name)
+          ProvenancePack.lineage(result, output_name)
+        end
+
+        def explain(result, output_name)
+          ProvenancePack.explain(result, output_name)
+        end
+
+        def build_compensations(&block)
+          SagaPack.build(&block)
+        end
+
+        def run_saga(environment, inputs:, compensations:, compiled_graph: nil, &block)
+          SagaPack.run(
+            environment,
+            inputs: inputs,
+            compensations: compensations,
+            compiled_graph: compiled_graph,
+            &block
+          )
+        end
+
+        def build_incremental_session(environment, compiled_graph: nil, &block)
+          IncrementalPack.session(environment, compiled_graph: compiled_graph, &block)
+        end
+
+        def build_dataflow_session(environment, source:, key:, window: nil, context: [], &block)
+          DataflowPack.session(
+            environment,
+            source: source,
+            key: key,
+            window: window,
+            context: context,
+            &block
+          )
+        end
+
+        def compare_differential(
+          inputs:,
+          primary_environment: nil,
+          primary_compiled_graph: nil,
+          primary_result: nil,
+          candidate_environment: nil,
+          candidate_compiled_graph: nil,
+          candidate_result: nil,
+          tolerance: nil,
+          primary_name: "primary",
+          candidate_name: "candidate"
+        )
+          DifferentialPack.compare(
+            inputs: inputs,
+            primary_environment: primary_environment,
+            primary_compiled_graph: primary_compiled_graph,
+            primary_result: primary_result,
+            candidate_environment: candidate_environment,
+            candidate_compiled_graph: candidate_compiled_graph,
+            candidate_result: candidate_result,
+            tolerance: tolerance,
+            primary_name: primary_name,
+            candidate_name: candidate_name
+          )
+        end
+
+        def shadow_differential(**arguments)
+          DifferentialPack.shadow(**arguments)
+        end
+
+        def audit_snapshot(result)
+          AuditPack.snapshot(result)
+        end
+
+        def audit_report(environment, inputs: nil, compiled_graph: nil, &block)
+          AuditPack.report(environment, inputs: inputs, compiled_graph: compiled_graph, &block)
+        end
+
+        def build_reactions(&block)
+          ReactivePack.build(&block)
+        end
+
+        def dispatch_reactive(target, reactions:)
+          ReactivePack.dispatch(target, reactions: reactions)
+        end
+
+        def run_reactive(environment, inputs:, reactions:, compiled_graph: nil, &block)
+          ReactivePack.run(environment, inputs: inputs, reactions: reactions, compiled_graph: compiled_graph, &block)
+        end
+
+        def run_incremental_reactive(session, inputs:, reactions:)
+          ReactivePack.run_incremental(session, inputs: inputs, reactions: reactions)
+        end
+
+        def build_invariants(&block)
+          InvariantsPack.build(&block)
+        end
+
+        def check_invariants(target, invariants:)
+          InvariantsPack.check(target, invariants: invariants)
+        end
+
+        def validate_invariants!(target, invariants:)
+          InvariantsPack.validate!(target, invariants: invariants)
+        end
+
+        def run_invariants(environment, inputs:, invariants:, compiled_graph: nil, &block)
+          InvariantsPack.run(environment, inputs: inputs, invariants: invariants, compiled_graph: compiled_graph,
+                             &block)
+        end
+
+        def verify_invariant_cases(environment, cases:, invariants:, compiled_graph: nil, &block)
+          InvariantsPack.verify_cases(environment,
+                                      cases: cases, invariants: invariants, compiled_graph: compiled_graph, &block)
+        end
+
+        def declare_capabilities(*capabilities, callable: nil, &block)
+          CapabilitiesPack.declare(*capabilities, callable: callable, &block)
+        end
+
+        def pure_callable(callable: nil, &block)
+          CapabilitiesPack.pure(callable: callable, &block)
+        end
+
+        def capability_policy(denied: [], required: [], on_undeclared: :ignore)
+          CapabilitiesPack.policy(denied: denied, required: required, on_undeclared: on_undeclared)
+        end
+
+        def required_capabilities(compiled_graph)
+          CapabilitiesPack.required_capabilities(compiled_graph)
+        end
+
+        def capabilities_for(compiled_graph, node_name)
+          CapabilitiesPack.capabilities_for(compiled_graph, node_name)
+        end
+
+        def profile_capabilities(profile_or_environment)
+          profile = profile_or_environment.respond_to?(:profile) ? profile_or_environment.profile : profile_or_environment
+          CapabilitiesPack.profile_capabilities(profile)
+        end
+
+        def capability_report(compiled_graph, profile: nil, policy: nil)
+          CapabilitiesPack.report(compiled_graph, profile: profile, policy: policy)
+        end
+
+        def check_capabilities!(compiled_graph, policy:, profile: nil)
+          CapabilitiesPack.check!(compiled_graph, profile: profile, policy: policy)
+        end
+
+        def content_addressed(callable: nil, fingerprint: nil, capabilities: [:pure],
+                              cache: ContentAddressingPack.cache, &block)
+          ContentAddressingPack.content_addressed(
+            callable: callable,
+            fingerprint: fingerprint,
+            capabilities: capabilities,
+            cache: cache,
+            &block
+          )
+        end
+
+        def pure_content_callable(callable: nil, fingerprint: nil, cache: ContentAddressingPack.cache, &block)
+          ContentAddressingPack.pure(callable: callable, fingerprint: fingerprint, cache: cache, &block)
+        end
+
+        def content_key(inputs:, fingerprint: nil, callable: nil)
+          ContentAddressingPack.content_key(fingerprint: fingerprint, callable: callable, inputs: inputs)
+        end
+
+        def content_cache
+          ContentAddressingPack.cache
+        end
+
+        def reset_content_cache!
+          ContentAddressingPack.reset_cache!
+        end
+
+        def debug_profile(target)
+          profile = target.respond_to?(:profile) ? target.profile : target
+          DebugPack.profile_snapshot(profile)
+        end
+
+        def debug_pack(pack_or_name, target)
+          profile = target.respond_to?(:profile) ? target.profile : target
+          DebugPack.pack_snapshot(pack_or_name, profile: profile)
+        end
+
+        def audit_pack(pack, target = nil)
+          profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          DebugPack.audit(pack, profile: profile)
+        end
+
+        def creator_profiles
+          CreatorPack.available_profiles
+        end
+
+        def creator_scopes
+          CreatorPack.available_scopes
+        end
+
+        def scaffold_pack(name:, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                          scope: :monorepo_package)
+          CreatorPack.scaffold(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope
+          )
+        end
+
+        def creator_report(name:, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                           scope: :monorepo_package, pack: nil, target: nil)
+          runtime_profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          CreatorPack.report(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope,
+            pack: pack,
+            target_profile: runtime_profile
+          )
+        end
+
+        def creator_workflow(name:, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                             scope: :monorepo_package, pack: nil, target: nil)
+          runtime_profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          CreatorPack.workflow(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope,
+            pack: pack,
+            target_profile: runtime_profile
+          )
+        end
+
+        def creator_wizard(name: nil, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                           scope: nil, root: nil, mode: :skip_existing, pack: nil, target: nil)
+          runtime_profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          CreatorPack.wizard(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope,
+            root: root,
+            mode: mode,
+            pack: pack,
+            target_profile: runtime_profile
+          )
+        end
+
+        def creator_writer(name:, root:, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil, capabilities: nil,
+                           scope: :monorepo_package, pack: nil, target: nil, mode: :skip_existing)
+          runtime_profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          CreatorPack.writer(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope,
+            pack: pack,
+            target_profile: runtime_profile,
+            root: root,
+            mode: mode
+          )
+        end
+
+        def write_pack_scaffold(name:, root:, kind: nil, namespace: "MyCompany::IgniterPacks", profile: nil,
+                                capabilities: nil, scope: :monorepo_package, pack: nil, target: nil, mode: :skip_existing)
+          runtime_profile =
+            case target
+            when nil
+              nil
+            else
+              target.respond_to?(:profile) ? target.profile : target
+            end
+
+          CreatorPack.write(
+            name: name,
+            kind: kind,
+            namespace: namespace,
+            profile: profile,
+            capabilities: capabilities,
+            scope: scope,
+            pack: pack,
+            target_profile: runtime_profile,
+            root: root,
+            mode: mode
+          )
+        end
+
+        def mcp_tools
+          McpPack.tool_catalog
+        end
+
+        def mcp_call(tool_name, target: nil, **arguments, &block)
+          McpPack.call(tool_name, target: target, **arguments, &block)
+        end
+
+        def mcp_creator_session(target: nil, **arguments)
+          mcp_call(:creator_session_start, target: target, **arguments)
+        end
+
+        def debug_snapshot(result, profile:)
+          DebugPack.snapshot(result, profile: profile)
+        end
+
+        def debug_report(environment, inputs: nil, compiled_graph: nil, &block)
+          DebugPack.report(environment, inputs: inputs, compiled_graph: compiled_graph, &block)
+        end
+
+        private
+
+        def normalize_packs(packs)
+          normalized = packs.flatten.compact
+          normalized.empty? ? default_packs : normalized
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+  end
+end

data/lib/igniter-extensions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/extensions"