igniter-extensions 0.5.2

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

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module CollectionPack
+        INTERNAL_SOURCE = :__collection_items__
+
+        Invocation = Struct.new(:operation, :items, :inputs, :compiled_graph, :profile, :key_name, :window,
+                                keyword_init: true) do
+          def initialize(operation:, items:, inputs:, compiled_graph:, profile:, key_name:, window:)
+            super(
+              operation: operation,
+              items: Array(items),
+              inputs: inputs.transform_keys(&:to_sym).freeze,
+              compiled_graph: compiled_graph,
+              profile: profile,
+              key_name: key_name.to_sym,
+              window: window
+            )
+          end
+        end
+
+        module LocalInvoker
+          module_function
+
+          def call(invocation:)
+            environment = Igniter::Contracts::Environment.new(profile: invocation.profile)
+            session = Igniter::Extensions::Contracts::DataflowPack.session(
+              environment,
+              source: INTERNAL_SOURCE,
+              key: invocation.key_name,
+              context: invocation.inputs.keys,
+              window: invocation.window,
+              compiled_graph: invocation.compiled_graph
+            )
+
+            result = session.run(inputs: invocation.inputs.merge(INTERNAL_SOURCE => invocation.items))
+            result.processed
+          end
+        end
+
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_collection,
+              node_contracts: [Igniter::Contracts::PackManifest.node(:collection)],
+              registry_contracts: [
+                Igniter::Contracts::PackManifest.validator(:collection_dependencies),
+                Igniter::Contracts::PackManifest.validator(:collection_contracts),
+                Igniter::Contracts::PackManifest.validator(:collection_invokers)
+              ],
+              requires_packs: [DataflowPack, IncrementalPack],
+              metadata: { category: :orchestration },
+              provides_capabilities: %i[collection keyed_sessions incremental_collection]
+            )
+          end
+
+          def install_into(kernel)
+            kernel.nodes.register(:collection,
+                                  Igniter::Contracts::NodeType.new(kind: :collection,
+                                                                   metadata: { category: :orchestration }))
+            kernel.dsl_keywords.register(:collection, collection_keyword)
+            kernel.validators.register(:collection_dependencies, method(:validate_collection_dependencies))
+            kernel.validators.register(:collection_contracts, method(:validate_collection_contracts))
+            kernel.validators.register(:collection_invokers, method(:validate_collection_invokers))
+            kernel.runtime_handlers.register(:collection, method(:handle_collection))
+            kernel
+          end
+
+          def collection_keyword
+            Igniter::Contracts::DslKeyword.new(:collection) do |name, from:, key:, builder:, inputs: {}, window: nil, contract: nil, via: nil, &block|
+              compiled_graph = compile_contract(name: name, contract: contract, profile: builder.profile, block: block)
+              input_map = normalize_inputs(inputs)
+              source_name = from.to_sym
+
+              builder.add_operation(
+                kind: :collection,
+                name: name,
+                from: source_name,
+                key_name: key.to_sym,
+                depends_on: [source_name, *extract_dependencies(input_map)].uniq,
+                inputs: input_map,
+                window: window,
+                compiled_graph: compiled_graph,
+                invoker: via
+              )
+            end
+          end
+
+          def validate_collection_dependencies(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+            available = operations.reject(&:output?).map(&:name)
+            missing = operations.select { |operation| operation.kind == :collection }
+                                .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_collection_dependencies,
+              message: "collection dependencies are not defined: #{missing.map(&:to_s).join(", ")}",
+              subjects: missing
+            )]
+          end
+
+          def validate_collection_contracts(operations:, profile:)
+            collection_operations = operations.select { |operation| operation.kind == :collection }
+            findings = []
+
+            invalid_contracts = collection_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_collection_contract,
+                message: "collection nodes require a compiled item graph: #{invalid_contracts.map(&:name).join(", ")}",
+                subjects: invalid_contracts.map(&:name)
+              )
+            end
+
+            mismatched = collection_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: :collection_profile_mismatch,
+                message: "collection item graphs were compiled against a different profile: #{mismatched.map(&:name).join(", ")}",
+                subjects: mismatched.map(&:name)
+              )
+            end
+
+            findings
+          end
+
+          def validate_collection_invokers(operations:, profile: nil) # rubocop:disable Lint/UnusedMethodArgument
+            invalid = operations.select { |operation| operation.kind == :collection }
+                                .reject do |operation|
+              invoker = operation.attributes[:invoker]
+              invoker.nil? || invoker.respond_to?(:call)
+            end
+            return [] if invalid.empty?
+
+            [Igniter::Contracts::ValidationFinding.new(
+              code: :invalid_collection_invoker,
+              message: "collection via: must be callable: #{invalid.map(&:name).join(", ")}",
+              subjects: invalid.map(&:name)
+            )]
+          end
+
+          def handle_collection(operation:, state:, profile:, **)
+            items = state.fetch(operation.attributes.fetch(:from))
+            invocation = Invocation.new(
+              operation: operation,
+              items: items,
+              inputs: resolve_inputs(operation, state: state),
+              compiled_graph: operation.attributes.fetch(:compiled_graph),
+              profile: profile,
+              key_name: operation.attributes.fetch(:key_name),
+              window: operation.attributes[:window]
+            )
+            invoker = operation.attributes[:invoker] || LocalInvoker
+            result = invoker.call(invocation: invocation)
+            unless result.is_a?(Igniter::Extensions::Contracts::Dataflow::CollectionResult)
+              raise Igniter::Contracts::Error,
+                    "collection invoker for #{operation.name} must return a CollectionResult"
+            end
+
+            result
+          end
+
+          private
+
+          def compile_contract(name:, contract:, profile:, block:)
+            if contract && block
+              raise ArgumentError,
+                    "collection :#{name} accepts either contract: or a block, not both"
+            end
+
+            source = contract || block
+            raise ArgumentError, "collection :#{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, "collection :#{name} contract must be a compiled graph or callable"
+          end
+
+          def normalize_inputs(inputs)
+            raise ArgumentError, "collection 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module CommercePack
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_commerce,
+              requires_packs: [LookupPack, AggregatePack],
+              registry_contracts: [
+                Igniter::Contracts::PackManifest.dsl_keyword(:order_items),
+                Igniter::Contracts::PackManifest.dsl_keyword(:subtotal),
+                Igniter::Contracts::PackManifest.dsl_keyword(:tax_amount),
+                Igniter::Contracts::PackManifest.dsl_keyword(:grand_total)
+              ]
+            )
+          end
+
+          def install_into(kernel)
+            install_dsl_keywords(kernel)
+            kernel
+          end
+
+          def install_dsl_keywords(kernel)
+            kernel.dsl_keywords.register(:order_items, order_items_keyword)
+            kernel.dsl_keywords.register(:subtotal, subtotal_keyword)
+            kernel.dsl_keywords.register(:tax_amount, tax_amount_keyword)
+            kernel.dsl_keywords.register(:grand_total, grand_total_keyword)
+          end
+
+          def order_items_keyword
+            Igniter::Contracts::DslKeyword.new(:order_items) do |name = :items, from:, builder:, key: :items|
+              builder.profile.dsl_keyword(:lookup).call(
+                name,
+                from: from.to_sym,
+                key: key.to_sym,
+                builder: builder
+              )
+            end
+          end
+
+          def subtotal_keyword
+            Igniter::Contracts::DslKeyword.new(:subtotal) do |name = :subtotal, from:, builder:, amount_key: :amount|
+              builder.profile.dsl_keyword(:sum).call(
+                name,
+                from: from.to_sym,
+                using: amount_key.to_sym,
+                builder: builder
+              )
+            end
+          end
+
+          def tax_amount_keyword
+            Igniter::Contracts::DslKeyword.new(:tax_amount) do |name = :tax, amount:, rate:, builder:|
+              dependencies = [amount.to_sym, rate.to_sym]
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: dependencies,
+                callable: lambda do |**values|
+                  values.fetch(amount.to_sym) * values.fetch(rate.to_sym)
+                end
+              )
+            end
+          end
+
+          def grand_total_keyword
+            Igniter::Contracts::DslKeyword.new(:grand_total) do |name = :grand_total, subtotal:, builder:, tax: nil, shipping: nil, discount: nil|
+              dependency_names = [subtotal, tax, shipping, discount].compact.map(&:to_sym)
+
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: dependency_names,
+                callable: lambda do |**values|
+                  total = values.fetch(subtotal.to_sym)
+                  total += values.fetch(tax.to_sym) if tax
+                  total += values.fetch(shipping.to_sym) if shipping
+                  total -= values.fetch(discount.to_sym) if discount
+                  total
+                end
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/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/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/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/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