igniter 0.5.0 → 0.5.2

data/packages/igniter-extensions/lib/igniter/extensions/contracts/compose_pack.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ComposePack
+        Invocation = Struct.new(:operation, :compiled_graph, :inputs, :profile, keyword_init: true) do
+          def initialize(operation:, compiled_graph:, inputs:, profile:)
+            super(
+              operation: operation,
+              compiled_graph: compiled_graph,
+              inputs: inputs,
+              profile: profile
+            )
+          end
+        end
+
+        module LocalInvoker
+          module_function
+
+          def call(invocation:)
+            Igniter::Contracts.execute(
+              invocation.compiled_graph,
+              inputs: invocation.inputs,
+              profile: invocation.profile
+            )
+          end
+        end
+
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_compose,
+              node_contracts: [Igniter::Contracts::PackManifest.node(:compose)],
+              registry_contracts: [
+                Igniter::Contracts::PackManifest.validator(:compose_dependencies),
+                Igniter::Contracts::PackManifest.validator(:compose_contracts),
+                Igniter::Contracts::PackManifest.validator(:compose_invokers)
+              ],
+              metadata: { category: :orchestration },
+              provides_capabilities: %i[subgraph_invocation nested_contracts]
+            )
+          end
+
+          def install_into(kernel)
+            kernel.nodes.register(:compose,
+                                  Igniter::Contracts::NodeType.new(kind: :compose,
+                                                                   metadata: { category: :orchestration }))
+            kernel.dsl_keywords.register(:compose, compose_keyword)
+            kernel.validators.register(:compose_dependencies, method(:validate_compose_dependencies))
+            kernel.validators.register(:compose_contracts, method(:validate_compose_contracts))
+            kernel.validators.register(:compose_invokers, method(:validate_compose_invokers))
+            kernel.runtime_handlers.register(:compose, method(:handle_compose))
+            kernel
+          end
+
+          def compose_keyword
+            Igniter::Contracts::DslKeyword.new(:compose) do |name, builder:, contract: nil, inputs: {}, output: nil, via: nil, &block|
+              compiled_graph = compile_contract(name: name, contract: contract, profile: builder.profile, block: block)
+              input_map = normalize_inputs(inputs)
+
+              builder.add_operation(
+                kind: :compose,
+                name: name,
+                depends_on: extract_dependencies(input_map),
+                inputs: input_map,
+                compiled_graph: compiled_graph,
+                output_name: output&.to_sym,
+                invoker: via
+              )
+            end
+          end
+
+          def validate_compose_dependencies(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+            available = operations.reject(&:output?).map(&:name)
+            missing = operations.select { |operation| operation.kind == :compose }
+                                .flat_map { |operation| Array(operation.attributes[:depends_on]) }
+                                .map(&:to_sym)
+                                .reject { |name| available.include?(name) }
+                                .uniq
+            return [] if missing.empty?
+
+            [Igniter::Contracts::ValidationFinding.new(
+              code: :missing_compose_dependencies,
+              message: "compose dependencies are not defined: #{missing.map(&:to_s).join(", ")}",
+              subjects: missing
+            )]
+          end
+
+          def validate_compose_contracts(operations:, profile:)
+            compose_operations = operations.select { |operation| operation.kind == :compose }
+            findings = []
+
+            invalid_contracts = compose_operations.reject do |operation|
+              operation.attributes[:compiled_graph].is_a?(Igniter::Contracts::CompiledGraph)
+            end
+            if invalid_contracts.any?
+              findings << Igniter::Contracts::ValidationFinding.new(
+                code: :invalid_compose_contract,
+                message: "compose nodes require a compiled contract graph: #{invalid_contracts.map(&:name).join(", ")}",
+                subjects: invalid_contracts.map(&:name)
+              )
+            end
+
+            mismatched = compose_operations.select do |operation|
+              compiled_graph = operation.attributes[:compiled_graph]
+              compiled_graph.is_a?(Igniter::Contracts::CompiledGraph) &&
+                compiled_graph.profile_fingerprint != profile.fingerprint
+            end
+            if mismatched.any?
+              findings << Igniter::Contracts::ValidationFinding.new(
+                code: :compose_profile_mismatch,
+                message: "compose contracts were compiled against a different profile: #{mismatched.map(&:name).join(", ")}",
+                subjects: mismatched.map(&:name)
+              )
+            end
+
+            missing_outputs = compose_operations.filter_map do |operation|
+              output_name = operation.attributes[:output_name]
+              next if output_name.nil?
+
+              compiled_graph = operation.attributes[:compiled_graph]
+              next if compiled_graph.is_a?(Igniter::Contracts::CompiledGraph) && compose_output_names(compiled_graph).include?(output_name)
+
+              operation.name
+            end
+            if missing_outputs.any?
+              findings << Igniter::Contracts::ValidationFinding.new(
+                code: :unknown_compose_output,
+                message: "compose output selections are not defined in the nested contract: #{missing_outputs.map(&:to_s).join(", ")}",
+                subjects: missing_outputs
+              )
+            end
+
+            findings
+          end
+
+          def validate_compose_invokers(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+            invalid = operations.select { |operation| operation.kind == :compose }
+                                .reject do |operation|
+              invoker = operation.attributes[:invoker]
+              invoker.nil? || invoker.respond_to?(:call)
+            end
+            return [] if invalid.empty?
+
+            [Igniter::Contracts::ValidationFinding.new(
+              code: :invalid_compose_invoker,
+              message: "compose via: must be callable: #{invalid.map(&:name).join(", ")}",
+              subjects: invalid.map(&:name)
+            )]
+          end
+
+          def handle_compose(operation:, state:, profile:, **)
+            nested_inputs = resolve_inputs(operation, state: state)
+            invocation = Invocation.new(
+              operation: operation,
+              compiled_graph: operation.attributes.fetch(:compiled_graph),
+              inputs: nested_inputs,
+              profile: profile
+            )
+            invoker = operation.attributes[:invoker] || LocalInvoker
+            result = invoker.call(invocation: invocation)
+            unless result.is_a?(Igniter::Contracts::ExecutionResult)
+              raise Igniter::Contracts::Error,
+                    "compose invoker for #{operation.name} must return an ExecutionResult"
+            end
+
+            output_name = operation.attributes[:output_name]
+            return result if output_name.nil?
+
+            result.output(output_name)
+          end
+
+          private
+
+          def compile_contract(name:, contract:, profile:, block:)
+            raise ArgumentError, "compose :#{name} accepts either contract: or a block, not both" if contract && block
+
+            source = contract || block
+            raise ArgumentError, "compose :#{name} requires contract: or a block" unless source
+
+            return source if source.is_a?(Igniter::Contracts::CompiledGraph)
+            return Igniter::Contracts.compile(profile: profile, &source) if source.respond_to?(:call)
+
+            raise ArgumentError, "compose :#{name} contract must be a compiled graph or callable"
+          end
+
+          def normalize_inputs(inputs)
+            raise ArgumentError, "compose inputs: must be a Hash" unless inputs.is_a?(Hash)
+
+            inputs.each_with_object({}) do |(key, value), memo|
+              memo[key.to_sym] = value
+            end.freeze
+          end
+
+          def extract_dependencies(input_map)
+            input_map.values.grep(Symbol).map(&:to_sym).uniq
+          end
+
+          def resolve_inputs(operation, state:)
+            operation.attributes.fetch(:inputs).each_with_object({}) do |(key, source), memo|
+              memo[key.to_sym] = source.is_a?(Symbol) ? state.fetch(source.to_sym) : source
+            end
+          end
+
+          def compose_output_names(compiled_graph)
+            compiled_graph.operations.select(&:output?).map(&:name)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/content_addressing/cache.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ContentAddressing
+        class Cache
+          def initialize
+            @store = {}
+            @hits = 0
+            @misses = 0
+            @mutex = Mutex.new
+          end
+
+          def fetch(key)
+            @mutex.synchronize do
+              entry = @store[key.hex]
+              if entry.nil?
+                @misses += 1
+                nil
+              else
+                @hits += 1
+                entry
+              end
+            end
+          end
+
+          def store(key, value)
+            @mutex.synchronize do
+              @store[key.hex] = value
+            end
+          end
+
+          def clear
+            @mutex.synchronize do
+              @store.clear
+              @hits = 0
+              @misses = 0
+            end
+          end
+
+          def size
+            @mutex.synchronize { @store.size }
+          end
+
+          def stats
+            @mutex.synchronize do
+              {
+                size: @store.size,
+                hits: @hits,
+                misses: @misses
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/content_addressing/content_key.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ContentAddressing
+        class ContentKey
+          attr_reader :hex
+
+          def initialize(hex)
+            @hex = hex.freeze
+            freeze
+          end
+
+          def to_s
+            "ca:#{hex}"
+          end
+
+          def ==(other)
+            other.is_a?(self.class) && other.hex == hex
+          end
+
+          alias eql? ==
+
+          def hash
+            hex.hash
+          end
+
+          class << self
+            def compute(fingerprint:, inputs:)
+              payload = stable_serialize(inputs)
+              new(Digest::SHA256.hexdigest("#{fingerprint}\x00#{payload}")[0..23])
+            end
+
+            private
+
+            def stable_serialize(value)
+              case value
+              when Hash
+                pairs = value.sort_by { |key, _entry| key.to_s }.map do |key, entry|
+                  "#{key}:#{stable_serialize(entry)}"
+                end
+                "{#{pairs.join(",")}}"
+              when Array
+                "[#{value.map { |entry| stable_serialize(entry) }.join(",")}]"
+              when String
+                value.inspect
+              when Symbol
+                ":#{value}"
+              when Numeric, NilClass, TrueClass, FalseClass
+                value.inspect
+              else
+                value.respond_to?(:to_h) ? stable_serialize(value.to_h) : value.hash.to_s
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/content_addressing/declaration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ContentAddressing
+        class Declaration
+          attr_reader :callable, :fingerprint, :cache, :capabilities
+
+          def initialize(callable:, fingerprint:, cache:, capabilities:)
+            @callable = callable
+            @fingerprint = fingerprint.to_s.freeze
+            @cache = cache
+            @capabilities = Array(capabilities).map(&:to_sym).uniq.freeze
+            freeze
+          end
+
+          def call(**kwargs)
+            key = content_key(kwargs)
+            cached = cache.fetch(key)
+            return cached unless cached.nil?
+
+            value = callable.call(**kwargs)
+            cache.store(key, value)
+            value
+          end
+
+          def declared_capabilities
+            capabilities
+          end
+
+          def pure?
+            capabilities.include?(:pure)
+          end
+
+          def content_fingerprint
+            fingerprint
+          end
+
+          def content_key(inputs)
+            ContentKey.compute(fingerprint: fingerprint, inputs: inputs)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/content_addressing_pack.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "content_addressing/content_key"
+require_relative "content_addressing/cache"
+require_relative "content_addressing/declaration"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ContentAddressingPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_content_addressing,
+            metadata: { category: :runtime, capabilities: [:pure] }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def cache
+          @cache ||= ContentAddressing::Cache.new
+        end
+
+        def cache=(value)
+          @cache = value
+        end
+
+        def reset_cache!
+          cache.clear
+        end
+
+        def stats
+          cache.stats
+        end
+
+        def content_key(inputs:, fingerprint: nil, callable: nil)
+          resolved_fingerprint =
+            if fingerprint
+              fingerprint
+            elsif callable
+              callable.respond_to?(:content_fingerprint) ? callable.content_fingerprint : default_fingerprint_for(callable)
+            else
+              raise ArgumentError, "content_key requires fingerprint: or callable:"
+            end
+
+          ContentAddressing::ContentKey.compute(fingerprint: resolved_fingerprint, inputs: inputs)
+        end
+
+        def content_addressed(callable: nil, fingerprint: nil, capabilities: [:pure], cache: self.cache, &block)
+          target = callable || block
+          raise ArgumentError, "content_addressed requires a callable or block" unless target
+
+          ContentAddressing::Declaration.new(
+            callable: target,
+            fingerprint: fingerprint || default_fingerprint_for(target),
+            cache: cache,
+            capabilities: capabilities
+          )
+        end
+
+        def pure(callable: nil, fingerprint: nil, cache: self.cache, &block)
+          content_addressed(
+            callable: callable,
+            fingerprint: fingerprint,
+            capabilities: [:pure],
+            cache: cache,
+            &block
+          )
+        end
+
+        def default_fingerprint_for(target)
+          if target.respond_to?(:content_fingerprint)
+            target.content_fingerprint
+          elsif target.is_a?(Proc)
+            file, line = target.source_location
+            "proc:#{file}:#{line}"
+          elsif target.respond_to?(:name) && !target.name.nil?
+            target.name
+          else
+            "anonymous_callable"
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/creator/profile.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Creator
+        class Profile
+          REGISTRY_CAPABILITIES = {
+            node: :nodes,
+            dsl_keyword: :dsl_keywords,
+            validator: :validators,
+            runtime_handler: :runtime_handlers,
+            diagnostic: :diagnostics_contributors,
+            effect: :effects,
+            executor: :executors,
+            dependency_pack: :pack_manifests
+          }.freeze
+
+          PRESETS = {
+            feature_node: {
+              kind: :feature,
+              capabilities: %i[node dsl_keyword validator runtime_handler],
+              dependency_hints: [],
+              summary: "feature node pack with DSL, validation, and runtime"
+            },
+            diagnostic_bundle: {
+              kind: :bundle,
+              capabilities: %i[dependency_pack diagnostic],
+              dependency_hints: %w[Igniter::Extensions::Contracts::ExecutionReportPack Igniter::Extensions::Contracts::ProvenancePack],
+              summary: "developer-facing diagnostics bundle pack"
+            },
+            operational_adapter: {
+              kind: :operational,
+              capabilities: %i[effect executor],
+              dependency_hints: [],
+              summary: "effect/executor operational adapter pack"
+            },
+            bundle_pack: {
+              kind: :bundle,
+              capabilities: %i[dependency_pack],
+              dependency_hints: [],
+              summary: "bundle pack that installs or presets other packs"
+            }
+          }.freeze
+
+          attr_reader :name,
+                      :kind,
+                      :capabilities,
+                      :runtime_dependency_hints,
+                      :development_dependency_hints,
+                      :development_hints,
+                      :summary
+
+          def self.available
+            PRESETS.keys
+          end
+
+          def self.build(profile: nil, kind: nil, capabilities: nil)
+            if profile
+              preset = PRESETS.fetch(profile.to_sym) do
+                raise ArgumentError, "unknown creator profile #{profile.inspect}"
+              end
+              effective_capabilities = Array(capabilities)
+              effective_capabilities = preset.fetch(:capabilities) if capabilities.nil? || effective_capabilities.empty?
+
+              runtime_hints = preset.fetch(:dependency_hints)
+              development_pack_hints = development_dependency_hints_for(effective_capabilities, runtime_hints)
+
+              return new(
+                name: profile,
+                kind: preset.fetch(:kind),
+                capabilities: effective_capabilities,
+                runtime_dependency_hints: runtime_hints,
+                development_dependency_hints: development_pack_hints,
+                development_hints: development_hints_for(effective_capabilities, runtime_hints, development_pack_hints),
+                summary: preset.fetch(:summary)
+              )
+            end
+
+            normalized_kind = (kind || infer_kind(Array(capabilities))).to_sym
+            inferred_capabilities = Array(capabilities)
+            inferred_capabilities = default_capabilities_for(normalized_kind) if inferred_capabilities.empty?
+            runtime_hints = dependency_hints_for(inferred_capabilities)
+            development_pack_hints = development_dependency_hints_for(inferred_capabilities, runtime_hints)
+
+            new(
+              name: :custom,
+              kind: normalized_kind,
+              capabilities: inferred_capabilities,
+              runtime_dependency_hints: runtime_hints,
+              development_dependency_hints: development_pack_hints,
+              development_hints: development_hints_for(inferred_capabilities, runtime_hints, development_pack_hints),
+              summary: "custom #{normalized_kind} authoring profile"
+            )
+          end
+
+          def self.dependency_hints_for(capabilities)
+            caps = capabilities.map(&:to_sym)
+            hints = []
+            if caps.include?(:diagnostic)
+              hints.concat([
+                             "Igniter::Extensions::Contracts::ExecutionReportPack",
+                             "Igniter::Extensions::Contracts::ProvenancePack"
+                           ])
+            end
+            hints << "Igniter::Extensions::Contracts::DebugPack" if caps.include?(:dependency_pack) && caps.include?(:diagnostic)
+
+            hints.uniq
+          end
+
+          def self.development_dependency_hints_for(capabilities, dependency_hints)
+            caps = capabilities.map(&:to_sym)
+            hints = []
+            hints << "Igniter::Extensions::Contracts::DebugPack"
+            hints << "Igniter::Extensions::Contracts::JournalPack" if (caps & %i[effect executor]).any?
+            hints << "Igniter::Extensions::Contracts::DebugPack" if caps.include?(:dependency_pack) && caps.include?(:diagnostic)
+            hints.reject { |hint| dependency_hints.include?(hint) }.uniq
+          end
+
+          def self.development_hints_for(capabilities, dependency_hints, development_dependency_hints)
+            caps = capabilities.map(&:to_sym)
+            hints = []
+            hints << "use Igniter::Extensions::Contracts::DebugPack while authoring and validating the pack"
+            hints << "consider Igniter::Extensions::Contracts::JournalPack while developing effect/executor adapters" if (caps & %i[
+              effect executor
+            ]).any?
+            hints << "bundle diagnostics contributors only when they are truly additive and non-semantic" if caps.include?(:diagnostic)
+            hints << "review runtime dependency pack composition carefully: #{dependency_hints.join(", ")}" unless dependency_hints.empty?
+            hints << "keep development-only helper packs out of the runtime bundle surface: #{development_dependency_hints.join(", ")}" unless development_dependency_hints.empty?
+            hints.uniq
+          end
+
+          def self.default_capabilities_for(kind)
+            case kind.to_sym
+            when :feature
+              %i[node dsl_keyword validator runtime_handler]
+            when :operational
+              %i[effect executor]
+            when :bundle
+              %i[dependency_pack]
+            else
+              []
+            end
+          end
+
+          def self.infer_kind(capabilities)
+            caps = capabilities.map(&:to_sym)
+            return :operational if (caps & %i[effect executor]).any?
+            return :bundle if caps.include?(:dependency_pack) && (caps & %i[node dsl_keyword runtime_handler effect
+                                                                            executor]).empty?
+
+            :feature
+          end
+
+          def initialize(name:, kind:, capabilities:, runtime_dependency_hints:, development_dependency_hints:,
+                         development_hints:, summary:)
+            @name = name.to_sym
+            @kind = kind.to_sym
+            @capabilities = capabilities.map(&:to_sym).uniq.freeze
+            @runtime_dependency_hints = runtime_dependency_hints.dup.freeze
+            @development_dependency_hints = development_dependency_hints.dup.freeze
+            @development_hints = development_hints.dup.freeze
+            @summary = summary
+            freeze
+          end
+
+          def dependency_hints
+            runtime_dependency_hints
+          end
+
+          def registry_capabilities
+            capabilities.filter_map { |capability| REGISTRY_CAPABILITIES[capability] }.uniq
+          end
+
+          def capability?(name)
+            capabilities.include?(name.to_sym)
+          end
+
+          def to_h
+            {
+              name: name,
+              kind: kind,
+              capabilities: capabilities,
+              registry_capabilities: registry_capabilities,
+              dependency_hints: dependency_hints,
+              runtime_dependency_hints: runtime_dependency_hints,
+              development_dependency_hints: development_dependency_hints,
+              development_hints: development_hints,
+              summary: summary
+            }
+          end
+        end
+      end
+    end
+  end
+end