igniter 0.5.0 → 0.5.1

data/packages/igniter-app/lib/igniter/app/operator/handlers/ignite_handler.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      module Handlers
+        class IgniteHandler < Base
+          def call(app_class:, record:, operation: nil, target: nil, value: Igniter::Runtime::Execution::UNDEFINED_RESUME_VALUE, assignee: nil, queue: nil, channel: nil, note: nil, audit: nil)
+            payload = record[:ignition_target] || {}
+            policy = Igniter::App::Operator::Policy.from_h(record.fetch(:policy))
+            action_resolution = resolve_operator_action(
+              policy,
+              operation,
+              context: "ignition item #{record.fetch(:id).inspect}"
+            )
+            audit_payload = app_class.send(:normalize_ignite_operator_audit, audit)
+
+            app_class.send(:stack_context_for!).ignition_trail.record(
+              :"ignition_operator_#{action_resolution[:handled_operation]}",
+              source: audit_payload[:source],
+              payload: {
+                target_id: payload[:target_id],
+                requested_operation: action_resolution[:requested_operation],
+                operation: action_resolution[:handled_operation],
+                lifecycle_operation: action_resolution[:handled_lifecycle_operation],
+                execution_operation: action_resolution[:handled_execution_operation],
+                note: note,
+                actor: audit_payload[:actor],
+                origin: audit_payload[:origin],
+                actor_channel: audit_payload[:actor_channel]
+              }.compact
+            )
+
+            updated_report = execute_operation(
+              app_class,
+              payload,
+              action_resolution.fetch(:handled_execution_operation),
+              action_resolution.fetch(:handled_operation),
+              note: note
+            )
+
+            build_result(
+              id: record.fetch(:id),
+              policy: policy,
+              action: record[:action],
+              action_resolution: action_resolution,
+              lane: record.dig(:lane, :name),
+              queue: record[:queue],
+              channel: record[:channel],
+              note: note,
+              audit: audit_payload,
+              status: app_class.operator_query(filters: { id: record.fetch(:id) }).first&.dig(:status) || payload[:status],
+              report_status: updated_report&.status
+            )
+          end
+
+          private
+
+          def execute_operation(app_class, payload, execution_operation, handled_operation, note: nil)
+            stack = app_class.send(:stack_context_for!)
+
+            case execution_operation
+            when :dismiss
+              stack.latest_ignition_report
+            when :approve, :retry_bootstrap
+              stack.ignite(**app_class.send(:ignite_operator_options, payload, operation: handled_operation))
+            when :detach
+              report = stack.latest_ignition_report
+              raise ArgumentError, "no persisted ignition report is available for detach" unless report
+
+              stack.detach_ignite_target(
+                report: report,
+                target_id: payload.fetch(:target_id),
+                mesh: app_class.send(:default_ignite_mesh),
+                metadata: { reason: note }.compact
+              )
+            when :teardown
+              report = stack.latest_ignition_report
+              raise ArgumentError, "no persisted ignition report is available for teardown" unless report
+
+              stack.teardown_ignite_target(
+                report: report,
+                target_id: payload.fetch(:target_id),
+                mesh: app_class.send(:default_ignite_mesh),
+                metadata: { reason: note }.compact
+              )
+            when :reignite
+              stack.reignite_target(
+                target_id: payload.fetch(:target_id),
+                **app_class.send(:ignite_operator_options, payload, operation: handled_operation)
+              )
+            when :reconcile_join
+              report = stack.latest_ignition_report
+              raise ArgumentError, "no persisted ignition report is available for reconcile" unless report
+
+              mesh = app_class.send(:default_ignite_mesh)
+              raise ArgumentError, "reconcile_join requires an active mesh" unless mesh
+
+              stack.reconcile_ignite(report: report, mesh: mesh)
+            else
+              raise ArgumentError, "unsupported ignition operation #{execution_operation.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/handlers/orchestration_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      module Handlers
+        class OrchestrationHandler < Base
+          def call(app_class:, record:, operation: nil, target: nil, value: Igniter::Runtime::Execution::UNDEFINED_RESUME_VALUE, assignee: nil, queue: nil, channel: nil, note: nil, audit: nil)
+            item = record[:inbox_item] || app_class.orchestration_inbox.find(record.fetch(:id))
+            return nil unless item
+
+            handler = app_class.orchestration_handler(item)
+            kwargs = {
+              app_class: app_class,
+              item: item,
+              operation: operation,
+              target: target,
+              value: value,
+              assignee: assignee,
+              queue: queue,
+              channel: channel,
+              note: note,
+              audit: audit
+            }
+            kwargs.delete(:audit) unless app_class.send(:callable_accepts_keyword?, handler, :audit)
+
+            handler.call(**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/handlers.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "handlers/base"
+require_relative "handlers/orchestration_handler"
+require_relative "handlers/ignite_handler"

data/packages/igniter-app/lib/igniter/app/operator/lifecycle_contract.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      class LifecycleContract
+        TERMINAL_STATUSES = %i[resolved dismissed joined failed torn_down].freeze
+
+        attr_reader :record_kind, :status, :combined_state, :default_operation,
+                    :allowed_operations, :runtime_completion, :attention_required,
+                    :resumable, :actionable, :terminal, :history_count
+
+        def initialize(record_kind:, status:, combined_state:, default_operation: nil,
+                       allowed_operations: [], runtime_completion: nil,
+                       attention_required:, resumable:, actionable:, terminal: nil,
+                       history_count: 0)
+          @record_kind = record_kind.to_sym
+          @status = status&.to_sym
+          @combined_state = combined_state&.to_sym
+          @default_operation = default_operation&.to_sym
+          @allowed_operations = Array(allowed_operations).map(&:to_sym).freeze
+          @runtime_completion = runtime_completion&.to_sym
+          @attention_required = !!attention_required
+          @resumable = !!resumable
+          @actionable = !!actionable
+          @terminal = terminal.nil? ? infer_terminal : !!terminal
+          @history_count = Integer(history_count || 0)
+          freeze
+        end
+
+        def to_h
+          {
+            record_kind: record_kind,
+            status: status,
+            combined_state: combined_state,
+            default_operation: default_operation,
+            allowed_operations: allowed_operations,
+            runtime_completion: runtime_completion,
+            attention_required: attention_required,
+            resumable: resumable,
+            actionable: actionable,
+            terminal: terminal,
+            history_count: history_count
+          }.freeze
+        end
+
+        private
+
+        def infer_terminal
+          TERMINAL_STATUSES.include?(status)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/policy.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      class Policy
+        attr_reader :name, :default_operation, :allowed_operations, :runtime_completion,
+                    :description, :lifecycle_operations, :operation_aliases,
+                    :default_routing, :operation_lifecycle, :execution_operations
+
+        def initialize(name:, default_operation:, allowed_operations:, runtime_completion:,
+                       description:, lifecycle_operations:, operation_aliases: {},
+                       default_routing: {}, operation_lifecycle: nil, execution_operations: nil)
+          @name = name.to_sym
+          @default_operation = default_operation.to_sym
+          @allowed_operations = Array(allowed_operations).map(&:to_sym).freeze
+          @runtime_completion = runtime_completion.to_sym
+          @description = description.to_s
+          @lifecycle_operations = Array(lifecycle_operations).map(&:to_sym).freeze
+          @operation_aliases = normalize_aliases(operation_aliases)
+          @default_routing = normalize_routing(default_routing)
+          @operation_lifecycle = normalize_map(operation_lifecycle)
+          @execution_operations = normalize_map(execution_operations)
+          freeze
+        end
+
+        def self.from_h(policy_hash)
+          normalized = policy_hash.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+
+          new(
+            name: normalized.fetch(:name),
+            default_operation: normalized.fetch(:default_operation),
+            allowed_operations: normalized.fetch(:allowed_operations),
+            runtime_completion: normalized.fetch(:runtime_completion),
+            description: normalized.fetch(:description),
+            lifecycle_operations: normalized.fetch(:lifecycle_operations),
+            operation_aliases: normalized.fetch(:operation_aliases, {}),
+            default_routing: normalized.fetch(:default_routing, {}),
+            operation_lifecycle: normalized.fetch(:operation_lifecycle, nil),
+            execution_operations: normalized.fetch(:execution_operations, nil)
+          )
+        end
+
+        def allows_operation?(operation)
+          normalized = operation.to_sym
+          canonical = canonical_operation_for(normalized)
+          allowed_operations.include?(normalized) ||
+            allowed_operations.include?(canonical) ||
+            lifecycle_operations.include?(normalized) ||
+            lifecycle_operations.include?(canonical)
+        end
+
+        def canonical_operation_for(operation)
+          operation_aliases.fetch(operation.to_sym, operation.to_sym)
+        end
+
+        def lifecycle_operation_for(operation)
+          normalized = operation.to_sym
+          canonical = canonical_operation_for(normalized)
+          operation_lifecycle.fetch(canonical, operation_lifecycle.fetch(normalized, canonical))
+        end
+
+        def execution_operation_for(operation)
+          normalized = operation.to_sym
+          canonical = canonical_operation_for(normalized)
+          execution_operations.fetch(canonical, execution_operations.fetch(normalized, canonical))
+        end
+
+        def default_lifecycle_operation
+          lifecycle_operation_for(default_operation)
+        end
+
+        def default_execution_operation
+          execution_operation_for(default_operation)
+        end
+
+        def with(**overrides)
+          merged_operation_aliases =
+            if overrides.key?(:operation_aliases)
+              operation_aliases.merge(normalize_aliases(overrides[:operation_aliases]))
+            else
+              operation_aliases
+            end
+
+          merged_default_routing =
+            if overrides.key?(:default_routing)
+              default_routing.merge(normalize_routing(overrides[:default_routing]))
+            else
+              default_routing
+            end
+
+          merged_operation_lifecycle =
+            if overrides.key?(:operation_lifecycle)
+              operation_lifecycle.merge(normalize_map(overrides[:operation_lifecycle]))
+            else
+              operation_lifecycle
+            end
+
+          merged_execution_operations =
+            if overrides.key?(:execution_operations)
+              execution_operations.merge(normalize_map(overrides[:execution_operations]))
+            else
+              execution_operations
+            end
+
+          Policy.new(
+            name: overrides.fetch(:name, name),
+            default_operation: overrides.fetch(:default_operation, default_operation),
+            allowed_operations: overrides.fetch(:allowed_operations, allowed_operations),
+            lifecycle_operations: overrides.fetch(:lifecycle_operations, lifecycle_operations),
+            operation_aliases: merged_operation_aliases,
+            default_routing: merged_default_routing,
+            operation_lifecycle: merged_operation_lifecycle,
+            execution_operations: merged_execution_operations,
+            runtime_completion: overrides.fetch(:runtime_completion, runtime_completion),
+            description: overrides.fetch(:description, description)
+          )
+        end
+
+        def to_h
+          {
+            name: name,
+            default_operation: default_operation,
+            allowed_operations: allowed_operations,
+            lifecycle_operations: lifecycle_operations,
+            operation_aliases: operation_aliases,
+            operation_lifecycle: operation_lifecycle,
+            execution_operations: execution_operations,
+            default_routing: default_routing,
+            runtime_completion: runtime_completion,
+            description: description
+          }.freeze
+        end
+
+        private
+
+        def normalize_aliases(operation_aliases)
+          normalize_map(operation_aliases)
+        end
+
+        def normalize_routing(routing)
+          routing.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end.freeze
+        end
+
+        def normalize_map(mapping)
+          (mapping || {}).each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value.to_sym
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "operator/policy"
+require_relative "operator/handler_result"
+require_relative "operator/lifecycle_contract"
+require_relative "operator/handler_registry"
+require_relative "operator/dispatcher"
+require_relative "operator/handlers"
+
+Igniter::App::Operator::HandlerRegistry.register(
+  :orchestration,
+  Igniter::App::Operator::Handlers::OrchestrationHandler.new
+)
+Igniter::App::Operator::HandlerRegistry.register(
+  :ignition,
+  Igniter::App::Operator::Handlers::IgniteHandler.new
+)

data/packages/igniter-app/lib/igniter/app/orchestration/action_result_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class ActionResultBuilder
+        def self.build(item:, requested_operation:, handled_operation:, handled_lifecycle_operation:,
+                       handled_execution_operation:, handled_policy:, handled_lane: nil,
+                       handled_queue: nil, handled_channel: nil, handled_handler_queue: nil,
+                       handled_assignee: nil, note: nil, audit: nil)
+          audit_payload = (audit || {}).dup
+          latest_history = Array(item[:action_history]).last || {}
+
+          {
+            id: item[:id],
+            action: item[:action],
+            operation: {
+              requested: requested_operation&.to_sym,
+              handled: handled_operation&.to_sym,
+              lifecycle: handled_lifecycle_operation&.to_sym,
+              execution: handled_execution_operation&.to_sym
+            }.compact.freeze,
+            policy: {
+              name: handled_policy&.to_sym,
+              lane: handled_lane&.to_sym,
+              queue: handled_queue,
+              channel: handled_channel,
+              handler_queue: handled_handler_queue
+            }.compact.freeze,
+            audit: {
+              source: audit_payload[:source]&.to_sym,
+              actor: audit_payload[:actor],
+              origin: audit_payload[:origin],
+              actor_channel: audit_payload[:actor_channel],
+              assignee: handled_assignee,
+              note: note
+            }.compact.freeze,
+            workflow: {
+              status: item[:status]&.to_sym,
+              queue: item[:queue],
+              channel: item[:channel],
+              assignee: item[:assignee],
+              action_history_count: Array(item[:action_history]).size,
+              latest_event: latest_history[:event]&.to_sym
+            }.compact.freeze,
+            runtime: runtime_slice(item)
+          }.compact.freeze
+        end
+
+        def self.runtime_slice(item)
+          runtime = {
+            status: item[:orchestration_runtime_status]&.to_sym,
+            state: item[:orchestration_runtime_state]&.to_sym,
+            state_class: item[:orchestration_runtime_state_class]&.to_sym,
+            latest_transition: item[:orchestration_runtime_latest_transition]&.dup,
+            latest_event: item[:orchestration_runtime_latest_event]&.dup,
+            result: item[:orchestration_runtime_result]&.dup
+          }.compact
+
+          runtime.empty? ? nil : runtime.freeze
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/followup_request.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class FollowupRequest
+        attr_reader :app_class, :actions, :source, :summary
+
+        def initialize(app_class:, actions:, source:, summary: {})
+          @app_class = app_class
+          @actions = Array(actions).map { |action| action.freeze }.freeze
+          @source = source.to_sym
+          @summary = summary.freeze
+          freeze
+        end
+
+        def empty?
+          actions.empty?
+        end
+
+        def action_ids
+          actions.map { |action| action[:id] }
+        end
+
+        def to_h
+          {
+            app: app_class.name,
+            source: source,
+            actions: actions,
+            summary: summary
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/handler_registry.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class HandlerRegistry
+        class << self
+          def register(action, handler = nil, queue: nil, &block)
+            resolved_handler = handler || block
+            raise ArgumentError, "orchestration handler registration requires a callable handler" unless resolved_handler
+
+            registry[registry_key(action, queue: queue)] = resolved_handler
+          end
+
+          def fetch(action, queue: nil)
+            if queue
+              keyed = registry_key(action, queue: queue)
+              return registry.fetch(keyed) if registry.key?(keyed)
+            end
+
+            registry.fetch(registry_key(action))
+          end
+
+          def registered?(action, queue: nil)
+            registry.key?(registry_key(action, queue: queue))
+          end
+
+          def actions
+            registry.keys.map { |key| key[:action] }.uniq
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def normalize_action(action)
+            action.to_sym
+          end
+
+          def normalize_queue(queue)
+            return nil if queue.nil?
+
+            queue.to_s
+          end
+
+          def registry_key(action, queue: nil)
+            {
+              action: normalize_action(action),
+              queue: normalize_queue(queue)
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/handlers.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      module Handlers
+        class Base < Igniter::App::Operator::Handlers::Base
+          def call(app_class:, item:, operation: nil, target: nil, value: Igniter::Runtime::Execution::UNDEFINED_RESUME_VALUE, assignee: nil, queue: nil, channel: nil, note: nil, audit: nil)
+            policy = app_class.orchestration_policy(item)
+            action_resolution = resolve_operator_action(
+              policy,
+              operation || default_operation(item, policy),
+              context: "orchestration item #{item[:id].inspect}"
+            )
+            applied_audit = { source: :orchestration_handler }.merge(normalize_audit(audit)).merge(
+              requested_operation: action_resolution[:requested_operation],
+              lifecycle_operation: action_resolution[:handled_lifecycle_operation],
+              execution_operation: action_resolution[:handled_execution_operation],
+              handler: self.class.name
+            )
+
+            updated_item = case action_resolution[:handled_operation]
+            when :handoff
+              app_class.handoff_orchestration_item(
+                item[:id],
+                assignee: assignee,
+                queue: queue,
+                channel: channel,
+                note: note,
+                audit: applied_audit
+              )
+            else
+              case action_resolution[:handled_lifecycle_operation]
+            when :acknowledge
+              app_class.acknowledge_orchestration_item(item[:id], note: note, audit: applied_audit)
+            when :resolve
+              app_class.resolve_orchestration_item(item[:id], target: target, value: value, note: note, audit: applied_audit)
+            when :dismiss
+              app_class.dismiss_orchestration_item(item[:id], note: note, audit: applied_audit)
+            else
+              raise ArgumentError, "unsupported orchestration operation #{action_resolution[:handled_lifecycle_operation].inspect}"
+              end
+            end
+
+            return nil unless updated_item
+
+            payload = updated_item.reject do |key, _|
+              %i[
+                id handled_action handled_operation handled_lifecycle_operation
+                handled_execution_operation handled_policy handled_lane handled_queue
+                handled_channel handled_handler_queue handled_audit_source handled_actor
+                handled_origin handled_actor_channel handled_assignee note status
+                report_status
+              ].include?(key)
+            end
+            payload[:orchestration_action_result] = ActionResultBuilder.build(
+              item: updated_item,
+              requested_operation: action_resolution[:requested_operation],
+              handled_operation: action_resolution[:handled_operation],
+              handled_lifecycle_operation: action_resolution[:handled_lifecycle_operation],
+              handled_execution_operation: action_resolution[:handled_execution_operation],
+              handled_policy: policy.name,
+              handled_lane: item.dig(:lane, :name),
+              handled_queue: updated_item[:queue],
+              handled_channel: updated_item[:channel],
+              handled_handler_queue: item[:queue],
+              handled_assignee: updated_item[:assignee],
+              note: note,
+              audit: applied_audit
+            )
+
+            build_result(
+              id: item[:id],
+              policy: policy,
+              action: item[:action],
+              action_resolution: action_resolution,
+              lane: item.dig(:lane, :name),
+              queue: updated_item[:queue],
+              channel: updated_item[:channel],
+              handler_queue: item[:queue],
+              assignee: updated_item[:assignee],
+              note: note,
+              audit: applied_audit,
+              status: updated_item[:status],
+              payload: payload
+            )
+          end
+
+          private
+
+          def normalize_operation(operation)
+            operation.to_sym
+          end
+
+          def default_operation(_item, policy)
+            policy.default_operation
+          end
+        end
+
+        class InteractiveSessionHandler < Base; end
+
+        class CompletionHandler < Base; end
+      end
+    end
+  end
+end