igniter-extensions 0.5.2

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Dataflow
+        class Result
+          attr_reader :processed, :diff, :aggregates, :inputs
+
+          def initialize(processed:, aggregates:, inputs:)
+            @processed = processed
+            @diff = processed.diff
+            @aggregates = aggregates.transform_keys(&:to_sym).freeze
+            @inputs = inputs
+            freeze
+          end
+
+          alias collection processed
+
+          def aggregate(name)
+            aggregates.fetch(name.to_sym)
+          end
+
+          def output(name)
+            aggregate(name)
+          end
+
+          def summary
+            {
+              diff: diff.to_h,
+              aggregates: aggregates
+            }
+          end
+
+          def to_h
+            {
+              processed: processed.to_h,
+              aggregates: aggregates,
+              inputs: inputs.to_h
+            }
+          end
+
+          def method_missing(name, *args)
+            return super unless args.empty?
+            return processed if name.to_sym == :processed
+            return aggregate(name) if aggregates.key?(name.to_sym)
+
+            super
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            name.to_sym == :processed || aggregates.key?(name.to_sym) || super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/dataflow/session.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Dataflow
+        class Session
+          attr_reader :environment, :compiled_graph, :source, :key_name, :window, :context, :last_result
+
+          def initialize(environment:, compiled_graph:, source:, key:, window: nil, context: [],
+                         aggregate_operators: {})
+            @environment = environment
+            @compiled_graph = compiled_graph
+            @source = source.to_sym
+            @key_name = key.to_sym
+            @window = window
+            @context = Array(context).map(&:to_sym).freeze
+            @aggregate_states = aggregate_operators.transform_values { |operator| AggregateState.new(operator) }
+            @item_sessions = {}
+            @snapshots = {}
+            @cached_items = {}
+            @last_inputs = nil
+            @last_result = nil
+          end
+
+          def run(inputs:)
+            normalized_inputs = Igniter::Contracts::NamedValues.new(inputs)
+            items = filtered_items(normalized_inputs.fetch(source))
+            diff = compute_diff(items)
+            processed_items = build_processed_items(items, normalized_inputs, diff)
+            delete_removed_sessions(diff.removed)
+
+            collection_result = CollectionResult.new(items: processed_items, diff: diff)
+            update_aggregate_states(collection_result)
+
+            @snapshots = snapshot_items(items)
+            @cached_items = processed_items.dup
+            @last_inputs = normalized_inputs
+            @last_result = Result.new(
+              processed: collection_result,
+              aggregates: @aggregate_states.transform_values(&:value),
+              inputs: normalized_inputs
+            )
+          end
+
+          def feed_diff(add: [], remove: [], update: [], inputs: {})
+            current_inputs = @last_inputs.to_h
+            current_items = Array(current_inputs.fetch(source, []))
+            merged_items = apply_diff(current_items, add: add, remove: remove, update: update)
+
+            run(inputs: current_inputs.merge(inputs).merge(source => merged_items))
+          end
+
+          def collection_diff
+            @last_result&.diff
+          end
+
+          private
+
+          def filtered_items(items)
+            normalized_items = Array(items).map { |item| normalize_item(item) }
+            WindowFilter.new(window).apply(normalized_items)
+          end
+
+          def normalize_item(item)
+            raise TypeError, "dataflow items must be Hash-like" unless item.is_a?(Hash)
+
+            item.transform_keys(&:to_sym)
+          end
+
+          def build_processed_items(items, normalized_inputs, diff)
+            items.each_with_object({}) do |item, memo|
+              key = extract_key(item)
+              memo[key] =
+                if diff.unchanged.include?(key)
+                  @cached_items.fetch(key)
+                else
+                  resolve_item(item, normalized_inputs)
+                end
+            end
+          end
+
+          def resolve_item(item, normalized_inputs)
+            key = extract_key(item)
+            session = @item_sessions[key] ||= Igniter::Extensions::Contracts::IncrementalPack.session(
+              environment,
+              compiled_graph: compiled_graph
+            )
+            item_inputs = context.each_with_object({}) do |name, memo|
+              memo[name] = normalized_inputs.fetch(name)
+            end.merge(item)
+            incremental_result = session.run(inputs: item_inputs)
+
+            ItemResult.new(
+              key: key,
+              inputs: item_inputs,
+              execution_result: incremental_result.execution_result,
+              incremental_result: incremental_result
+            )
+          end
+
+          def compute_diff(items)
+            current_keys = items.to_h { |item| [extract_key(item), item] }
+            added = []
+            changed = []
+            unchanged = []
+
+            items.each do |item|
+              key = extract_key(item)
+              fingerprint = fingerprint(item)
+
+              if !@snapshots.key?(key)
+                added << key
+              elsif @snapshots.fetch(key) != fingerprint
+                changed << key
+              else
+                unchanged << key
+              end
+            end
+
+            removed = @snapshots.keys.reject { |key| current_keys.key?(key) }
+
+            Diff.new(added: added, removed: removed, changed: changed, unchanged: unchanged)
+          end
+
+          def snapshot_items(items)
+            items.to_h { |item| [extract_key(item), fingerprint(item)] }
+          end
+
+          def fingerprint(item)
+            item.sort_by { |name, _| name.to_s }
+                .map { |name, value| "#{name}:#{value.inspect}" }
+                .hash
+                .to_s
+          end
+
+          def extract_key(item)
+            item.fetch(key_name)
+          end
+
+          def delete_removed_sessions(removed_keys)
+            removed_keys.each do |key|
+              @item_sessions.delete(key)
+            end
+          end
+
+          def update_aggregate_states(collection_result)
+            @aggregate_states.each_value do |state|
+              state.apply_diff!(collection_result.diff, collection_result)
+            end
+          end
+
+          def apply_diff(items, add:, remove:, update:)
+            remove_keys = Array(remove).map do |entry|
+              entry.is_a?(Hash) ? normalize_item(entry).fetch(key_name) : entry
+            end
+            result = items.map { |item| normalize_item(item) }
+                          .reject { |item| remove_keys.include?(item.fetch(key_name)) }
+
+            Array(update).each do |entry|
+              updated = normalize_item(entry)
+              key = updated.fetch(key_name)
+              index = result.index { |item| item.fetch(key_name) == key }
+              index ? result[index] = updated : result << updated
+            end
+
+            result.concat(Array(add).map { |entry| normalize_item(entry) })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/dataflow/window_filter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Dataflow
+        class WindowFilter
+          def initialize(options)
+            @options = options
+            validate!
+          end
+
+          def apply(items)
+            return items unless @options
+
+            if @options.key?(:last)
+              items.last(@options.fetch(:last))
+            else
+              cutoff = Time.now - @options.fetch(:seconds)
+              field = @options.fetch(:field).to_sym
+              items.select { |item| item.fetch(field) >= cutoff }
+            end
+          end
+
+          private
+
+          def validate!
+            return unless @options
+            raise ArgumentError, "window must be a Hash" unless @options.is_a?(Hash)
+
+            if @options.key?(:last)
+              return if @options.fetch(:last).is_a?(Integer) && @options.fetch(:last).positive?
+
+              raise ArgumentError, "window { last: } must be a positive Integer"
+            end
+
+            if @options.key?(:seconds)
+              raise ArgumentError, "window { seconds: } requires a :field key" unless @options.key?(:field)
+
+              return
+            end
+
+            raise ArgumentError, "window must use :last or :seconds"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "incremental_pack"
+require_relative "dataflow/aggregate_operators"
+require_relative "dataflow/aggregate_state"
+require_relative "dataflow/builder"
+require_relative "dataflow/collection_result"
+require_relative "dataflow/diff"
+require_relative "dataflow/item_result"
+require_relative "dataflow/result"
+require_relative "dataflow/session"
+require_relative "dataflow/window_filter"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module DataflowPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_dataflow,
+            metadata: { category: :orchestration }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def session(environment, source:, key:, window: nil, context: [], compiled_graph: nil, &block)
+          ensure_installed!(environment.profile)
+          Igniter::Extensions::Contracts::IncrementalPack.ensure_installed!(environment.profile)
+
+          item_graph, aggregate_operators =
+            if compiled_graph
+              raise ArgumentError, "DataflowPack.session accepts either compiled_graph: or a block, not both" if block
+
+              [compiled_graph, {}]
+            else
+              builder = Dataflow::Builder.new(source: source, key: key, window: window, context: context)
+              builder.instance_eval(&block) if block
+              builder.build!(environment)
+            end
+
+          Dataflow::Session.new(
+            environment: environment,
+            compiled_graph: item_graph,
+            source: source,
+            key: key,
+            window: window,
+            context: context,
+            aggregate_operators: aggregate_operators
+          )
+        end
+
+        def ensure_installed!(profile)
+          return if profile.pack_names.include?(:extensions_dataflow)
+
+          raise Igniter::Contracts::Error,
+                "DataflowPack is not installed in profile #{profile.fingerprint}; add Igniter::Extensions::Contracts::DataflowPack"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/debug/pack_audit.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative "pack_snapshot"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Debug
+        class PackAudit
+          REGISTRIES = {
+            node_kinds: ->(kernel) { kernel.nodes.to_h.keys.sort },
+            dsl_keywords: ->(kernel) { kernel.dsl_keywords.to_h.keys.sort },
+            validators: ->(kernel) { kernel.validators.entries.map(&:key).sort },
+            normalizers: ->(kernel) { kernel.normalizers.entries.map(&:key).sort },
+            runtime_handlers: ->(kernel) { kernel.runtime_handlers.to_h.keys.sort },
+            diagnostics_contributors: ->(kernel) { kernel.diagnostics_contributors.entries.map(&:key).sort },
+            effects: ->(kernel) { kernel.effects.to_h.keys.sort },
+            executors: ->(kernel) { kernel.executors.to_h.keys.sort }
+          }.freeze
+
+          attr_reader :pack_snapshot,
+                      :installed_in_target_profile,
+                      :target_profile_fingerprint,
+                      :draft_registered_keys,
+                      :missing_node_definitions,
+                      :missing_dsl_keywords,
+                      :missing_runtime_handlers,
+                      :missing_registry_contracts,
+                      :install_error,
+                      :finalize_error
+
+          def self.build(pack, profile: nil)
+            manifest = pack.manifest
+            baseline_snapshot = registry_snapshot(Igniter::Contracts.build_kernel)
+            draft_snapshot, install_error = install_snapshot(pack)
+
+            new(
+              pack_snapshot: PackSnapshot.new(manifest),
+              installed_in_target_profile: profile ? profile.pack_names.include?(manifest.name) : false,
+              target_profile_fingerprint: profile&.fingerprint,
+              draft_registered_keys: registry_delta(baseline_snapshot, draft_snapshot),
+              missing_node_definitions: missing_node_definitions(manifest, draft_snapshot),
+              missing_dsl_keywords: missing_dsl_keywords(manifest, draft_snapshot),
+              missing_runtime_handlers: missing_runtime_handlers(manifest, draft_snapshot),
+              missing_registry_contracts: missing_registry_contracts(manifest, draft_snapshot),
+              install_error: install_error,
+              finalize_error: finalize_error_for(pack)
+            )
+          end
+
+          def self.install_snapshot(pack)
+            kernel = Igniter::Contracts.build_kernel
+            error = nil
+
+            begin
+              kernel.install(pack)
+            rescue StandardError => e
+              error = "#{e.class}: #{e.message}"
+            end
+
+            [registry_snapshot(kernel), error]
+          end
+
+          def self.finalize_error_for(pack)
+            kernel = Igniter::Contracts.build_kernel
+            kernel.install(pack)
+            kernel.finalize
+            nil
+          rescue StandardError => e
+            "#{e.class}: #{e.message}"
+          end
+
+          def self.registry_snapshot(kernel)
+            REGISTRIES.to_h { |name, reader| [name, reader.call(kernel)] }
+          end
+
+          def self.registry_delta(before, after)
+            REGISTRIES.keys.to_h do |name|
+              [name, after.fetch(name) - before.fetch(name)]
+            end
+          end
+
+          def self.missing_node_definitions(manifest, snapshot)
+            manifest.node_contracts.map(&:kind).reject { |kind| snapshot.fetch(:node_kinds).include?(kind) }
+          end
+
+          def self.missing_dsl_keywords(manifest, snapshot)
+            required = manifest.node_contracts.select(&:requires_dsl).map(&:kind)
+            required.reject { |kind| snapshot.fetch(:dsl_keywords).include?(kind) }
+          end
+
+          def self.missing_runtime_handlers(manifest, snapshot)
+            required = manifest.node_contracts.select(&:requires_runtime).map(&:kind)
+            required.reject { |kind| snapshot.fetch(:runtime_handlers).include?(kind) }
+          end
+
+          def self.missing_registry_contracts(manifest, snapshot)
+            manifest.registry_contracts.each_with_object({}) do |contract, memo|
+              registry = normalize_registry(contract.registry)
+              available = snapshot.fetch(registry)
+              next if available.include?(contract.key)
+
+              memo[registry] ||= []
+              memo[registry] << contract.key
+            end.transform_values(&:sort)
+          end
+
+          def self.normalize_registry(name)
+            case name.to_sym
+            when :nodes
+              :node_kinds
+            else
+              name.to_sym
+            end
+          end
+
+          def initialize(pack_snapshot:, installed_in_target_profile:, target_profile_fingerprint:,
+                         draft_registered_keys:, missing_node_definitions:, missing_dsl_keywords:, missing_runtime_handlers:, missing_registry_contracts:, install_error:, finalize_error:)
+            @pack_snapshot = pack_snapshot
+            @installed_in_target_profile = installed_in_target_profile
+            @target_profile_fingerprint = target_profile_fingerprint
+            @draft_registered_keys = draft_registered_keys
+            @missing_node_definitions = missing_node_definitions.freeze
+            @missing_dsl_keywords = missing_dsl_keywords.freeze
+            @missing_runtime_handlers = missing_runtime_handlers.freeze
+            @missing_registry_contracts = missing_registry_contracts.transform_values(&:freeze).freeze
+            @install_error = install_error
+            @finalize_error = finalize_error
+            freeze
+          end
+
+          def name
+            pack_snapshot.name
+          end
+
+          def ok?
+            install_error.nil? &&
+              finalize_error.nil? &&
+              missing_node_definitions.empty? &&
+              missing_dsl_keywords.empty? &&
+              missing_runtime_handlers.empty? &&
+              missing_registry_contracts.empty?
+          end
+
+          def to_h
+            {
+              pack: pack_snapshot.to_h,
+              installed_in_target_profile: installed_in_target_profile,
+              target_profile_fingerprint: target_profile_fingerprint,
+              draft_registered_keys: draft_registered_keys,
+              missing: {
+                node_definitions: missing_node_definitions,
+                dsl_keywords: missing_dsl_keywords,
+                runtime_handlers: missing_runtime_handlers,
+                registry_contracts: missing_registry_contracts
+              },
+              install_error: install_error,
+              finalize_error: finalize_error,
+              ok: ok?
+            }
+          end
+
+          def explain
+            return "#{name} looks complete" if ok?
+
+            parts = []
+            parts << "install_error=#{install_error}" if install_error
+            parts << "missing node definitions: #{missing_node_definitions.join(", ")}" unless missing_node_definitions.empty?
+            parts << "missing DSL keywords: #{missing_dsl_keywords.join(", ")}" unless missing_dsl_keywords.empty?
+            parts << "missing runtime handlers: #{missing_runtime_handlers.join(", ")}" unless missing_runtime_handlers.empty?
+            missing_registry_contracts.each do |registry, keys|
+              parts << "missing #{registry}: #{keys.join(", ")}"
+            end
+            parts << "finalize_error=#{finalize_error}" if finalize_error
+            parts.join("; ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/debug/pack_snapshot.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Debug
+        class PackSnapshot
+          attr_reader :manifest
+
+          def initialize(manifest)
+            @manifest = manifest
+            freeze
+          end
+
+          def name
+            manifest.name
+          end
+
+          def metadata
+            manifest.metadata
+          end
+
+          def node_kinds
+            manifest.node_contracts.map(&:kind)
+          end
+
+          def registry_contracts
+            manifest.registry_contracts.each_with_object({}) do |contract, memo|
+              memo[contract.registry] ||= []
+              memo[contract.registry] << contract.key
+            end.transform_values(&:sort)
+          end
+
+          def to_h
+            {
+              name: name,
+              metadata: metadata,
+              node_kinds: node_kinds,
+              registry_contracts: registry_contracts
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/debug/profile_snapshot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "pack_snapshot"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Debug
+        class ProfileSnapshot
+          attr_reader :profile
+
+          def initialize(profile:)
+            @profile = profile
+            freeze
+          end
+
+          def pack_names
+            profile.pack_names.sort
+          end
+
+          def packs
+            profile.pack_manifests.map { |manifest| PackSnapshot.new(manifest) }
+          end
+
+          def registry_keys
+            {
+              node_kinds: profile.nodes.keys.sort,
+              dsl_keywords: profile.dsl_keywords.keys.sort,
+              validators: profile.validators.map(&:key).sort,
+              normalizers: profile.normalizers.map(&:key).sort,
+              runtime_handlers: profile.runtime_handlers.keys.sort,
+              diagnostics_contributors: profile.diagnostics_contributors.map(&:key).sort,
+              effects: profile.effects.keys.sort,
+              executors: profile.executors.keys.sort
+            }
+          end
+
+          def to_h
+            {
+              fingerprint: profile.fingerprint,
+              pack_names: pack_names,
+              registry_keys: registry_keys,
+              packs: packs.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/debug/report.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "profile_snapshot"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Debug
+        class Report
+          attr_reader :profile_snapshot,
+                      :compilation_report,
+                      :execution_result,
+                      :diagnostics_report,
+                      :provenance_summary
+
+          def initialize(profile_snapshot:, compilation_report: nil, execution_result: nil, diagnostics_report: nil,
+                         provenance_summary: nil)
+            @profile_snapshot = profile_snapshot
+            @compilation_report = compilation_report
+            @execution_result = execution_result
+            @diagnostics_report = diagnostics_report
+            @provenance_summary = provenance_summary
+            freeze
+          end
+
+          def ok?
+            compilation_report.nil? || compilation_report.ok?
+          end
+
+          def invalid?
+            !ok?
+          end
+
+          def to_h
+            payload = {
+              profile: profile_snapshot.to_h,
+              ok: ok?
+            }
+
+            payload[:compilation] = compilation_report.to_h if compilation_report
+            payload[:execution] = execution_result.to_h if execution_result
+            payload[:diagnostics] = diagnostics_report.to_h if diagnostics_report
+            payload[:provenance] = provenance_summary if provenance_summary
+            payload
+          end
+        end
+      end
+    end
+  end
+end