igniter 0.5.0 → 0.5.1

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

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Igniter
+  class App
+    module Orchestration
+      class Inbox
+        RESOLVED_STATUSES = %i[resolved dismissed].freeze
+
+        def initialize(clock: -> { Time.now.utc.iso8601 })
+          @clock = clock
+          @items = []
+        end
+
+        def open(action, source:, graph: nil, execution_id: nil, session: nil)
+          existing = find_active(action[:id])
+          return existing if existing
+
+          timestamp = @clock.call
+          item = {
+            item_id: SecureRandom.uuid,
+            id: action[:id],
+            action: action[:action],
+            policy: action[:policy],
+            node: action[:node],
+            interaction: action[:interaction],
+            reason: action[:reason],
+            guidance: action[:guidance],
+            attention_required: action[:attention_required],
+            resumable: action[:resumable],
+            lane: action[:lane],
+            routing: action[:routing],
+            source: source.to_sym,
+            graph: graph,
+            execution_id: execution_id,
+            assignee: action.dig(:routing, :assignee),
+            queue: action.dig(:routing, :queue),
+            channel: action.dig(:routing, :channel),
+            handoff_count: 0,
+            handoff_history: [].freeze,
+            action_history: [
+              action_event(
+                event: :opened,
+                status: :open,
+                timestamp: timestamp,
+                audit: { source: source.to_sym }
+              )
+            ].freeze,
+            status: :open,
+            created_at: timestamp
+          }.merge(session_item_attributes(session)).compact.freeze
+
+          @items << item
+          item
+        end
+
+        def find(id)
+          @items.reverse_each.find { |item| item[:id] == id.to_s }
+        end
+
+        def find_active(id)
+          @items.reverse_each.find { |item| item[:id] == id.to_s && !RESOLVED_STATUSES.include?(item[:status]) }
+        end
+
+        def acknowledge(id, note: nil, audit: nil)
+          transition(id, to: :acknowledged, timestamp_key: :acknowledged_at, note: note, audit: audit)
+        end
+
+        def handoff(id, assignee: nil, queue: nil, channel: nil, note: nil, audit: nil)
+          current = find(id)
+          return nil unless current
+
+          validate_handoff_target!(assignee: assignee, queue: queue, channel: channel, id: id)
+
+          timestamp = @clock.call
+          handoff_entry = {
+            at: timestamp,
+            assignee: assignee,
+            queue: queue,
+            channel: channel
+          }
+          handoff_entry[:note] = note unless note.nil? || note.to_s.empty?
+
+          updated = current.merge(
+            status: :acknowledged,
+            acknowledged_at: current[:acknowledged_at] || timestamp,
+            handed_off_at: timestamp,
+            assignee: assignee || current[:assignee],
+            queue: queue || current[:queue],
+            channel: channel || current[:channel],
+            handoff_count: current.fetch(:handoff_count, 0) + 1,
+            handoff_history: (Array(current[:handoff_history]) + [handoff_entry.freeze]).freeze,
+            action_history: append_action_event(
+              current,
+              action_event(
+                event: :handoff,
+                status: :acknowledged,
+                timestamp: timestamp,
+                note: note,
+                audit: audit,
+                assignee: assignee || current[:assignee],
+                queue: queue || current[:queue],
+                channel: channel || current[:channel]
+              )
+            )
+          )
+          updated[:note] = note unless note.nil? || note.to_s.empty?
+          updated = updated.freeze
+
+          index = @items.index(current)
+          @items[index] = updated
+          updated
+        end
+
+        def resolve(id, note: nil, metadata: {}, audit: nil)
+          transition(id, to: :resolved, timestamp_key: :resolved_at, note: note, metadata: metadata, audit: audit)
+        end
+
+        def dismiss(id, note: nil, audit: nil)
+          transition(id, to: :dismissed, timestamp_key: :dismissed_at, note: note, audit: audit)
+        end
+
+        def items(status: nil)
+          selected = status ? @items.select { |item| item[:status] == status.to_sym } : @items
+          selected.map(&:dup)
+        end
+
+        def query
+          InboxQuery.new(items)
+        end
+
+        def clear!
+          @items.clear
+          self
+        end
+
+        def snapshot(limit: 20)
+          selected = limit ? @items.last(limit) : @items
+
+          {
+            total: @items.size,
+            open: @items.count { |item| item[:status] == :open },
+            acknowledged: @items.count { |item| item[:status] == :acknowledged },
+            resolved: @items.count { |item| item[:status] == :resolved },
+            dismissed: @items.count { |item| item[:status] == :dismissed },
+            actionable: @items.count { |item| !RESOLVED_STATUSES.include?(item[:status]) },
+            by_status: @items.each_with_object(Hash.new(0)) { |item, memo| memo[item[:status]] += 1 },
+            by_action: @items.each_with_object(Hash.new(0)) { |item, memo| memo[item[:action]] += 1 },
+            by_policy: @items.each_with_object(Hash.new(0)) do |item, memo|
+              memo[item.dig(:policy, :name)] += 1 if item[:policy]
+            end,
+            by_lane: @items.each_with_object(Hash.new(0)) do |item, memo|
+              memo[item.dig(:lane, :name)] += 1 if item[:lane]
+            end,
+            by_assignee: @items.each_with_object(Hash.new(0)) do |item, memo|
+              memo[item[:assignee]] += 1 if item[:assignee]
+            end,
+            by_queue: @items.each_with_object(Hash.new(0)) do |item, memo|
+              memo[item[:queue]] += 1 if item[:queue]
+            end,
+            by_channel: @items.each_with_object(Hash.new(0)) do |item, memo|
+              memo[item[:channel]] += 1 if item[:channel]
+            end,
+            latest_action: @items.last&.dig(:action),
+            latest_node: @items.last&.dig(:node),
+            latest_policy: @items.last&.dig(:policy, :name),
+            latest_lane: @items.last&.dig(:lane, :name),
+            latest_assignee: @items.last&.dig(:assignee),
+            latest_queue: @items.last&.dig(:queue),
+            latest_channel: @items.last&.dig(:channel),
+            latest_status: @items.last&.dig(:status),
+            latest_action_source: @items.last&.dig(:action_history)&.last&.dig(:source),
+            latest_action_actor: @items.last&.dig(:action_history)&.last&.dig(:actor),
+            latest_action_origin: @items.last&.dig(:action_history)&.last&.dig(:origin),
+            latest_action_event: @items.last&.dig(:action_history)&.last&.dup,
+            items: selected.map(&:dup)
+          }
+        end
+
+        private
+
+        def transition(id, to:, timestamp_key:, note:, metadata: {}, audit: nil)
+          current = find(id)
+          return nil unless current
+
+          timestamp = @clock.call
+          updated = current.merge(
+            status: to,
+            timestamp_key => timestamp,
+            action_history: append_action_event(
+              current,
+              action_event(
+                event: transition_event_name(to),
+                status: to,
+                timestamp: timestamp,
+                note: note,
+                audit: audit,
+                metadata: metadata
+              )
+            )
+          )
+          updated[:note] = note unless note.nil? || note.to_s.empty?
+          metadata.each do |key, value|
+            updated[key] = value unless value.nil?
+          end
+          updated = updated.freeze
+
+          index = @items.index(current)
+          @items[index] = updated
+          updated
+        end
+
+        def session_item_attributes(session)
+          return {} unless session
+
+          {
+            token: session.token,
+            reply_mode: session.reply_mode,
+            waiting_on: session.waiting_on,
+            source_node: session.source_node,
+            phase: session.phase,
+            turn: session.turn,
+            graph: session.graph,
+            execution_id: session.execution_id
+          }
+        end
+
+        def validate_handoff_target!(assignee:, queue:, channel:, id:)
+          return if assignee || queue || channel
+
+          raise ArgumentError, "orchestration item #{id.inspect} handoff requires assignee:, queue:, or channel:"
+        end
+
+        def append_action_event(current, event)
+          (Array(current[:action_history]) + [event]).freeze
+        end
+
+        def transition_event_name(status)
+          case status.to_sym
+          when :acknowledged then :acknowledged
+          when :resolved then :resolved
+          when :dismissed then :dismissed
+          else
+            status.to_sym
+          end
+        end
+
+        def action_event(event:, status:, timestamp:, note: nil, audit: nil, metadata: {}, assignee: nil, queue: nil, channel: nil)
+          normalized_audit = normalize_audit(audit)
+          payload = {
+            at: timestamp,
+            event: event.to_sym,
+            status: status.to_sym
+          }
+          payload[:note] = note unless note.nil? || note.to_s.empty?
+          payload[:source] = normalized_audit[:source] if normalized_audit[:source]
+          payload[:actor] = normalized_audit[:actor] if normalized_audit[:actor]
+          payload[:origin] = normalized_audit[:origin] if normalized_audit[:origin]
+          payload[:actor_channel] = normalized_audit[:actor_channel] if normalized_audit[:actor_channel]
+          payload[:requested_operation] = normalized_audit[:requested_operation] if normalized_audit[:requested_operation]
+          payload[:lifecycle_operation] = normalized_audit[:lifecycle_operation] if normalized_audit[:lifecycle_operation]
+          payload[:execution_operation] = normalized_audit[:execution_operation] if normalized_audit[:execution_operation]
+          payload[:handler] = normalized_audit[:handler] if normalized_audit[:handler]
+          payload[:assignee] = assignee if assignee
+          payload[:queue] = queue if queue
+          payload[:channel] = channel if channel
+          metadata.each do |key, value|
+            payload[key] = value unless value.nil?
+          end
+          payload.freeze
+        end
+
+        def normalize_audit(audit)
+          audit.to_h.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class InboxQuery
+        include Enumerable
+
+        ORDERABLE_DIMENSIONS = %i[
+          id action node status interaction reason resumable attention_required
+          created_at acknowledged_at resolved_at dismissed_at handed_off_at
+          assignee queue channel handoff_count
+        ].freeze
+        FACETABLE_DIMENSIONS = %i[
+          status action node interaction reason attention_required resumable
+          assignee queue channel handoff_count policy lane
+        ].freeze
+
+        def initialize(items)
+          @items = Array(items).map(&:dup).freeze
+          @filters = [].freeze
+          @orderings = [].freeze
+          @limit_count = nil
+          freeze
+        end
+
+        def status(*statuses)
+          normalized = statuses.map(&:to_sym)
+          add_filter { |item| normalized.include?(item[:status]) }
+        end
+
+        def actionable
+          add_filter { |item| !Inbox::RESOLVED_STATUSES.include?(item[:status]) }
+        end
+
+        def resolved
+          status(:resolved)
+        end
+
+        def dismissed
+          status(:dismissed)
+        end
+
+        def open
+          status(:open)
+        end
+
+        def acknowledged
+          status(:acknowledged)
+        end
+
+        def action(*actions)
+          normalized = actions.map(&:to_sym)
+          add_filter { |item| normalized.include?(item[:action]) }
+        end
+
+        def policy(*names)
+          normalized = names.map(&:to_sym)
+          add_filter { |item| normalized.include?(item.dig(:policy, :name)) }
+        end
+
+        def lane(*names)
+          normalized = names.map(&:to_sym)
+          add_filter { |item| normalized.include?(item.dig(:lane, :name)) }
+        end
+
+        def queue(*queues)
+          normalized = queues.map(&:to_s)
+          add_filter { |item| normalized.include?(item[:queue].to_s) }
+        end
+
+        def channel(*channels)
+          normalized = channels.map(&:to_s)
+          add_filter { |item| normalized.include?(item[:channel].to_s) }
+        end
+
+        def assignee(*assignees)
+          normalized = assignees.map(&:to_s)
+          add_filter { |item| normalized.include?(item[:assignee].to_s) }
+        end
+
+        def node(*nodes)
+          normalized = nodes.map(&:to_sym)
+          add_filter { |item| normalized.include?(item[:node]) }
+        end
+
+        def interaction(*interactions)
+          normalized = interactions.map(&:to_sym)
+          add_filter { |item| normalized.include?(item[:interaction]) }
+        end
+
+        def reason(*reasons)
+          normalized = reasons.map(&:to_sym)
+          add_filter { |item| normalized.include?(item[:reason]) }
+        end
+
+        def attention_required(value = true)
+          expected = !!value
+          add_filter { |item| item[:attention_required] == expected }
+        end
+
+        def resumable(value = true)
+          expected = !!value
+          add_filter { |item| item[:resumable] == expected }
+        end
+
+        def graph(*graphs)
+          normalized = graphs.map(&:to_s)
+          add_filter { |item| normalized.include?(item[:graph].to_s) }
+        end
+
+        def execution_id(*ids)
+          normalized = ids.map(&:to_s)
+          add_filter { |item| normalized.include?(item[:execution_id].to_s) }
+        end
+
+        def with_token
+          add_filter { |item| !item[:token].nil? }
+        end
+
+        def handed_off
+          add_filter { |item| item.fetch(:handoff_count, 0).positive? }
+        end
+
+        def where(&block)
+          raise ArgumentError, "where requires a block" unless block
+
+          add_filter(&block)
+        end
+
+        def order_by(dimension, direction: :asc)
+          raise ArgumentError, "direction must be :asc or :desc" unless %i[asc desc].include?(direction)
+          unless ORDERABLE_DIMENSIONS.include?(dimension) || dimension.respond_to?(:call)
+            raise ArgumentError, "Unknown ordering dimension: #{dimension.inspect}. Use one of #{ORDERABLE_DIMENSIONS.inspect} or a Proc."
+          end
+
+          clone_query do |query|
+            query.instance_variable_set(:@orderings, (@orderings + [{ dimension: dimension, direction: direction }]).freeze)
+          end
+        end
+
+        def limit(count)
+          clone_query { |query| query.instance_variable_set(:@limit_count, count) }
+        end
+
+        def to_a
+          result = @items.select { |item| match?(item) }
+          result = apply_orderings(result) unless @orderings.empty?
+          @limit_count ? result.first(@limit_count) : result
+        end
+
+        def each(&block)
+          to_a.each(&block)
+        end
+
+        def count
+          @items.count { |item| match?(item) }
+        end
+
+        def empty?
+          !@items.any? { |item| match?(item) }
+        end
+
+        def first(count = nil)
+          count ? to_a.first(count) : to_a.first
+        end
+
+        def facet(dimension, include_nil: false)
+          validate_facet_dimension!(dimension)
+
+          to_a.each_with_object(Hash.new(0)) do |item, memo|
+            value = facet_value(item, dimension)
+            next if value.nil? && !include_nil
+
+            memo[value] += 1
+          end
+        end
+
+        def facets(*dimensions, include_nil: false)
+          dims = dimensions.flatten
+          dims = FACETABLE_DIMENSIONS if dims.empty?
+
+          dims.each_with_object({}) do |dimension, memo|
+            memo[dimension] = facet(dimension, include_nil: include_nil)
+          end.freeze
+        end
+
+        def summary
+          {
+            total: count,
+            actionable: actionable.count,
+            open: open.count,
+            acknowledged: acknowledged.count,
+            resolved: resolved.count,
+            dismissed: dismissed.count,
+            handed_off: handed_off.count,
+            by_status: facet(:status),
+            by_action: facet(:action),
+            by_policy: facet(:policy),
+            by_lane: facet(:lane),
+            by_queue: facet(:queue),
+            by_channel: facet(:channel),
+            by_assignee: facet(:assignee),
+            by_interaction: facet(:interaction),
+            by_reason: facet(:reason),
+            attention_required: attention_required.count,
+            resumable: resumable.count
+          }.freeze
+        end
+
+        def explain
+          lines = ["InboxQuery(#{@items.size} candidates)"]
+          lines << "  filters: #{@filters.size}"
+          unless @orderings.empty?
+            order_desc = @orderings.map { |entry| "#{entry[:dimension]} #{entry[:direction]}" }.join(", ")
+            lines << "  order_by: #{order_desc}"
+          end
+          lines << "  limit: #{@limit_count}" if @limit_count
+          lines.join("\n")
+        end
+
+        private
+
+        def add_filter(&block)
+          clone_query do |query|
+            query.instance_variable_set(:@filters, (@filters + [block]).freeze)
+          end
+        end
+
+        def validate_facet_dimension!(dimension)
+          return if FACETABLE_DIMENSIONS.include?(dimension)
+
+          raise ArgumentError, "Unknown facet dimension: #{dimension.inspect}. Use one of #{FACETABLE_DIMENSIONS.inspect}."
+        end
+
+        def clone_query
+          query = self.class.allocate
+          query.instance_variable_set(:@items, @items)
+          query.instance_variable_set(:@filters, @filters.dup.freeze)
+          query.instance_variable_set(:@orderings, @orderings.dup.freeze)
+          query.instance_variable_set(:@limit_count, @limit_count)
+          yield query
+          query.freeze
+          query
+        end
+
+        def match?(item)
+          @filters.all? { |filter| filter.call(item) }
+        end
+
+        def apply_orderings(items)
+          items.sort do |left, right|
+            comparison = 0
+            @orderings.each do |ordering|
+              left_value = dimension_value(left, ordering[:dimension])
+              right_value = dimension_value(right, ordering[:dimension])
+              comparison = compare_values(left_value, right_value, ordering[:direction])
+              break unless comparison.zero?
+            end
+            comparison
+          end
+        end
+
+        def dimension_value(item, dimension)
+          return dimension.call(item) if dimension.respond_to?(:call)
+
+          item[dimension]
+        end
+
+        def facet_value(item, dimension)
+          case dimension
+          when :policy then item.dig(:policy, :name)
+          when :lane then item.dig(:lane, :name)
+          else item[dimension]
+          end
+        end
+
+        def compare_values(left, right, direction)
+          if left.nil? && right.nil?
+            0
+          elsif left.nil?
+            1
+          elsif right.nil?
+            -1
+          else
+            result = left <=> right
+            direction == :desc ? -result : result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class LaneRegistry
+        class << self
+          def register(action, lane:, queue: nil, channel: nil, routing: nil, policy: nil, handler: nil, description: nil)
+            normalized_routing = normalize_routing(routing || {})
+            normalized_queue = queue || normalized_routing[:queue]
+            normalized_channel = channel || normalized_routing[:channel]
+
+            registry[registry_key(action, lane: lane)] = {
+              action: normalize_action(action),
+              name: normalize_lane(lane),
+              queue: normalize_queue(normalized_queue),
+              channel: normalized_channel,
+              routing: normalized_routing.merge(
+                queue: normalize_queue(normalized_queue),
+                channel: normalized_channel
+              ).compact.freeze,
+              policy: normalize_policy(policy),
+              handler: normalize_handler(handler),
+              description: description&.to_s
+            }.freeze
+          end
+
+          def fetch(action, lane: nil, queue: nil)
+            entry = find(action, lane: lane, queue: queue)
+            raise KeyError, "orchestration lane not registered for #{action.inspect}#{lane ? " lane=#{lane.inspect}" : ""}#{queue ? " queue=#{queue.inspect}" : ""}" unless entry
+
+            entry
+          end
+
+          def find(action, lane: nil, queue: nil)
+            if lane
+              keyed = registry_key(action, lane: lane)
+              return registry[keyed] if registry.key?(keyed)
+            end
+
+            normalized_queue = normalize_queue(queue)
+            return nil unless normalized_queue
+
+            lanes(action).find { |entry| entry[:queue] == normalized_queue }
+          end
+
+          def lanes(action)
+            normalized_action = normalize_action(action)
+            registry.values.select { |entry| entry[:action] == normalized_action }
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def normalize_action(action)
+            action.to_sym
+          end
+
+          def normalize_lane(lane)
+            lane.to_sym
+          end
+
+          def normalize_queue(queue)
+            return nil if queue.nil?
+
+            queue.to_s
+          end
+
+          def normalize_routing(routing)
+            routing.each_with_object({}) do |(key, value), memo|
+              memo[key.to_sym] = value
+            end.freeze
+          end
+
+          def normalize_policy(policy)
+            return nil unless policy
+
+            policy.respond_to?(:name) ? policy.name.to_sym : policy
+          end
+
+          def normalize_handler(handler)
+            return nil unless handler
+
+            handler.class.name || handler.class.to_s
+          end
+
+          def registry_key(action, lane:)
+            {
+              action: normalize_action(action),
+              lane: normalize_lane(lane)
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end