command_tower 0.3.1 → 0.10.0

data/app/services/command_tower/messaging/accept/operation_logger.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class OperationLogger
+        class << self
+          def around(request:)
+            correlation_id = Contract::Observability::Correlation.resolve
+            started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            base = {
+              correlation_id:,
+              messaging_operation: "accept",
+              recipient_id: request[:recipient_id],
+              notification_type_key: request[:notification_type_key],
+              host_event_identity_digest: RequestNormalizer.digest_host_event_identity(
+                request[:host_event_identity],
+              ),
+            }
+
+            Contract::Observability::StructuredLogger.info(
+              base.merge(event: "messaging.accept.started"),
+            )
+
+            result = yield
+
+            event =
+              if result.idempotent_replay
+                "messaging.accept.idempotent_replay"
+              else
+                "messaging.accept.succeeded"
+              end
+
+            Contract::Observability::StructuredLogger.info(
+              base.merge(
+                event:,
+                duration_ms: elapsed_ms(started_at),
+                communication_id: result.communication_id,
+                destination_plan_id: result.destination_plan_id,
+                idempotent_replay: result.idempotent_replay,
+                selected_channel_count: result.selected_channels.size,
+                inbox_selected: result.inbox_selected ? 1 : 0,
+              ),
+            )
+
+            result
+          rescue IdempotencyConflictError => e
+            log_failure(base, started_at, e, :warn, "idempotency_conflict", "messaging.accept.idempotency_conflict")
+            raise
+          rescue ValidationError, UnknownTypeError, InvalidPreferenceError, IllegalOverrideError,
+                 ImpossibleMandatoryPlanError => e
+            log_failure(base, started_at, e, :warn, error_code_for(e), "messaging.accept.failed")
+            raise
+          rescue PersistenceError, InvariantError => e
+            log_failure(base, started_at, e, :error, error_code_for(e), "messaging.accept.failed")
+            raise
+          rescue StandardError => e
+            log_failure(base, started_at, e, :error, "unexpected", "messaging.accept.failed")
+            raise
+          end
+
+          private
+
+          def log_failure(base, started_at, error, level, error_code, event)
+            Contract::Observability::StructuredLogger.public_send(
+              level,
+              base.merge(
+                event:,
+                duration_ms: elapsed_ms(started_at),
+                error_code:,
+                error_class: error.class.name,
+              ),
+            )
+          end
+
+          def elapsed_ms(started_at)
+            ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          end
+
+          def error_code_for(error)
+            case error
+            when ValidationError then "validation_failed"
+            when UnknownTypeError then "unknown_type"
+            when InvalidPreferenceError then "invalid_preference"
+            when IllegalOverrideError then "illegal_override"
+            when ImpossibleMandatoryPlanError then "impossible_mandatory_plan"
+            when IdempotencyConflictError then "idempotency_conflict"
+            when PersistenceError then "persistence_failed"
+            when InvariantError then "invariant_violation"
+            else "unexpected"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/persistence_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class PersistenceError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/persister.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class Persister
+        def self.call(request:, plan:, fingerprint:)
+          new(request:, plan:, fingerprint:).call
+        end
+
+        def initialize(request:, plan:, fingerprint:)
+          @request = request
+          @plan = plan
+          @fingerprint = fingerprint
+        end
+
+        def call
+          communication = nil
+
+          ActiveRecord::Base.transaction do
+            communication = Messaging::Communication.create!(
+              user_id: @request.fetch(:recipient_id),
+              notification_type_key: @request.fetch(:notification_type_key).to_s,
+              host_event_identity: @request.fetch(:host_event_identity).to_s,
+              accept_request_fingerprint: @fingerprint,
+              status: Messaging::Communication::STATUS_ACCEPTED,
+              execution_handoff_status: Messaging::Communication::HANDOFF_PENDING,
+              title: @request.fetch(:title),
+              body: @request.fetch(:body),
+              metadata: freeze_metadata(@request[:metadata]),
+            )
+
+            Messaging::DestinationPlan.create!(
+              communication:,
+              decision: decision_payload(@plan),
+            )
+
+            if @plan.inbox_selected
+              Messaging::InboxItem.create!(
+                communication:,
+                status: Messaging::InboxItem::STATUS_CREATED,
+              )
+            end
+
+            @plan.selected_channels.each do |channel_key|
+              Messaging::ChannelDelivery.create!(
+                communication:,
+                channel_key: channel_key.to_s,
+                status: Messaging::ChannelDelivery::STATUS_PLANNED,
+              )
+            end
+          end
+
+          reload_aggregate(communication.id)
+        end
+
+        private
+
+        def freeze_metadata(metadata)
+          return nil if metadata.nil?
+
+          metadata.to_h.transform_keys(&:to_s)
+        end
+
+        def decision_payload(plan)
+          {
+            "selected_channels" => Array(plan.selected_channels).map(&:to_s),
+            "inbox_selected" => !!plan.inbox_selected,
+            "mandatory" => !!plan.mandatory,
+            "platform_enabled_channels" => Array(@request[:platform_enabled_channels]).map(&:to_s),
+            "excluded_destinations" => Array(plan.excluded_destinations).map do |excluded|
+              {
+                "destination" => excluded.destination == :inbox ? "inbox" : excluded.destination.to_s,
+                "reason_class" => excluded.reason_class.to_s,
+              }
+            end,
+          }
+        end
+
+        def reload_aggregate(id)
+          Messaging::Communication.includes(
+            :destination_plan,
+            :inbox_item,
+            :channel_deliveries,
+          ).find(id)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/request_normalizer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module CommandTower
+  module Messaging
+    module Accept
+      class RequestNormalizer
+        def self.fingerprint(**kwargs)
+          new(**kwargs).fingerprint
+        end
+
+        def self.digest_host_event_identity(host_event_identity)
+          Digest::SHA256.hexdigest(host_event_identity.to_s)
+        end
+
+        def initialize(
+          title:,
+          body:,
+          metadata:,
+          preference_state:,
+          platform_enabled_channels:,
+          message_overrides:
+        )
+          @title = title
+          @body = body
+          @metadata = metadata
+          @preference_state = preference_state
+          @platform_enabled_channels = platform_enabled_channels
+          @message_overrides = message_overrides
+        end
+
+        def fingerprint
+          Digest::SHA256.hexdigest(canonical_json)
+        end
+
+        def canonical_json
+          JSON.generate(canonical_payload)
+        end
+
+        private
+
+        def canonical_payload
+          {
+            "title" => @title.to_s,
+            "body" => @body.to_s,
+            "metadata" => normalize_value(@metadata),
+            "preference_state" => normalize_value(@preference_state),
+            "platform_enabled_channels" => normalize_channel_list(@platform_enabled_channels),
+            "message_overrides" => normalize_overrides(@message_overrides),
+          }
+        end
+
+        def normalize_overrides(raw)
+          return nil if raw.nil?
+
+          hash = raw.respond_to?(:to_h) ? raw.to_h : raise(ValidationError, "message_overrides must be hash-like")
+          stringified = deep_stringify(hash)
+          {
+            "channels_add" => normalize_channel_list(stringified["channels_add"]),
+            "channels_remove" => normalize_channel_list(stringified["channels_remove"]),
+            "inbox" => stringified.key?("inbox") ? !!stringified["inbox"] : nil,
+          }
+        end
+
+        def normalize_channel_list(value)
+          return [] if value.nil?
+
+          Array(value).map(&:to_s).uniq.sort
+        end
+
+        def normalize_value(value)
+          case value
+          when nil
+            nil
+          when Hash
+            value.to_h.transform_keys(&:to_s).sort.to_h.transform_values { |v| normalize_value(v) }
+          when Array
+            # Prefer set-like sorting for channel lists; preserve nested structure recursively.
+            value.map { |item| normalize_value(item) }
+          else
+            value
+          end
+        end
+
+        def deep_stringify(value)
+          case value
+          when Hash
+            value.to_h.transform_keys(&:to_s).transform_values { |v| deep_stringify(v) }
+          when Array
+            value.map { |item| deep_stringify(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/result.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      Result = Data.define(
+        :communication_id,
+        :destination_plan_id,
+        :recipient_id,
+        :notification_type_key,
+        :host_event_identity,
+        :status,
+        :idempotent_replay,
+        :inbox_item_id,
+        :channel_deliveries,
+        :selected_channels,
+        :inbox_selected,
+        :excluded_destinations,
+      ) do
+        def self.build(
+          communication_id:,
+          destination_plan_id:,
+          recipient_id:,
+          notification_type_key:,
+          host_event_identity:,
+          status:,
+          idempotent_replay:,
+          inbox_item_id:,
+          channel_deliveries:,
+          selected_channels:,
+          inbox_selected:,
+          excluded_destinations:
+        )
+          ordered_channels = Array(selected_channels).map(&:to_s).uniq.sort.freeze
+          ordered_deliveries =
+            Array(channel_deliveries).sort_by { |delivery| delivery.channel_key.to_s }.freeze
+          ordered_excluded =
+            Array(excluded_destinations).sort_by(&:sort_key).freeze
+
+          new(
+            communication_id:,
+            destination_plan_id:,
+            recipient_id:,
+            notification_type_key: notification_type_key.to_s,
+            host_event_identity: host_event_identity.to_s,
+            status: status.to_s,
+            idempotent_replay: !!idempotent_replay,
+            inbox_item_id:,
+            channel_deliveries: ordered_deliveries,
+            selected_channels: ordered_channels,
+            inbox_selected: !!inbox_selected,
+            excluded_destinations: ordered_excluded,
+          ).freeze
+        end
+
+        def self.from_communication(communication, idempotent_replay:)
+          plan = communication.destination_plan
+          raise InvariantError, "accepted communication missing destination plan" if plan.nil?
+
+          decision = plan.decision.is_a?(Hash) ? plan.decision : {}
+          selected = Array(decision["selected_channels"] || decision[:selected_channels]).map(&:to_s)
+          inbox_selected = !!(decision.key?("inbox_selected") ? decision["inbox_selected"] : decision[:inbox_selected])
+          excluded =
+            Array(decision["excluded_destinations"] || decision[:excluded_destinations]).map do |item|
+              hash = item.respond_to?(:to_h) ? item.to_h : item
+              ExcludedDestination.build(
+                destination: hash["destination"] || hash[:destination],
+                reason_class: hash["reason_class"] || hash[:reason_class],
+              )
+            end
+
+          deliveries =
+            Array(communication.channel_deliveries).map do |delivery|
+              ChannelDeliveryResult.build(
+                id: delivery.id,
+                channel_key: delivery.channel_key,
+                status: delivery.status,
+              )
+            end
+
+          build(
+            communication_id: communication.id,
+            destination_plan_id: plan.id,
+            recipient_id: communication.user_id,
+            notification_type_key: communication.notification_type_key,
+            host_event_identity: communication.host_event_identity,
+            status: communication.status,
+            idempotent_replay:,
+            inbox_item_id: communication.inbox_item&.id,
+            channel_deliveries: deliveries,
+            selected_channels: selected,
+            inbox_selected:,
+            excluded_destinations: excluded,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/unknown_type_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class UnknownTypeError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/validation_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class ValidationError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/channel_detectors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    # Shared platform channel configuration detectors.
+    #
+    # Answers transport/deployment readiness questions (is email/SMS/Pushover
+    # configured?). Does not own host channel-set policy (PlatformEnabledChannels),
+    # recipient readiness, or Account UX capability projection.
+    #
+    # SMS product readiness (Messaging notification SMS ∧ Identity OTP SMS) is
+    # exposed separately from sms_configured? so Planner/Execution platform_configured
+    # stays Messaging-only while Me phone HTTP / host SMS policy use the dual-gate.
+    module ChannelDetectors
+      module_function
+
+      def email_configured?
+        Execution::Adapters::Email::Configuration.email_configured?
+      end
+
+      def sms_configured?
+        Execution::Adapters::Sms::Configuration.sms_configured?
+      end
+
+      def pushover_configured?
+        Execution::Adapters::Pushover::Configuration.pushover_configured?
+      end
+
+      # Used by RecipientReadiness#platform_configured_for? (fail-closed).
+      def configured?(channel_key)
+        case channel_key.to_s
+        when "inbox"
+          true
+        when "email"
+          email_configured?
+        when "sms"
+          sms_configured?
+        when "pushover"
+          pushover_configured?
+        else
+          false
+        end
+      end
+
+      # Messaging notification SMS ∧ Identity OTP SMS.
+      def sms_product_ready?
+        sms_configured? &&
+          CommandTower::Identity::PhoneVerification::SmsConfiguration.sms_ready?
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/channels/definition.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Channels
+      Definition = Data.define(
+        :key,
+        :label,
+        :kind,
+        :supports_endpoint_records,
+        :identity_backed,
+        :canonical_provider,
+      ) do
+        def external?
+          kind == :external
+        end
+
+        def inbox?
+          kind == :inbox
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/channels/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Channels
+      class Error < CommandTower::Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/channels/unknown_channel_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Channels
+      class UnknownChannelError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/channels.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Channels
+      module_function
+
+      # identity_backed: readiness uses User Identity facts.
+      # supports_endpoint_records: Endpoint Platform may persist ledger rows.
+      # SMS is Identity-owned only (like email) — not an Endpoint Platform channel.
+      DEFINITIONS = [
+        Definition.new(
+          key: "inbox",
+          label: "Inbox",
+          kind: :inbox,
+          supports_endpoint_records: false,
+          identity_backed: false,
+          canonical_provider: nil,
+        ),
+        Definition.new(
+          key: "email",
+          label: "Email",
+          kind: :external,
+          supports_endpoint_records: false,
+          identity_backed: true,
+          canonical_provider: "smtp",
+        ),
+        Definition.new(
+          key: "sms",
+          label: "SMS",
+          kind: :external,
+          supports_endpoint_records: false,
+          identity_backed: true,
+          canonical_provider: "twilio",
+        ),
+        Definition.new(
+          key: "push",
+          label: "Push",
+          kind: :external,
+          supports_endpoint_records: true,
+          identity_backed: false,
+          canonical_provider: "expo",
+        ),
+        Definition.new(
+          key: "pushover",
+          label: "Pushover",
+          kind: :external,
+          supports_endpoint_records: true,
+          identity_backed: false,
+          canonical_provider: "pushover",
+        ),
+      ].map(&:freeze).freeze
+
+      INDEX = DEFINITIONS.index_by(&:key).freeze
+
+      def known?(key)
+        INDEX.key?(key.to_s)
+      end
+
+      def fetch(key)
+        INDEX[key.to_s]
+      end
+
+      def fetch!(key)
+        normalized = key.to_s
+        definition = INDEX[normalized]
+        raise UnknownChannelError, "unknown channel: #{normalized.inspect}" if definition.nil?
+
+        definition
+      end
+
+      def keys
+        @keys ||= DEFINITIONS.map(&:key).freeze
+      end
+
+      def external_keys
+        @external_keys ||= DEFINITIONS.select(&:external?).map(&:key).freeze
+      end
+
+      def definitions
+        DEFINITIONS
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/contract/communications.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Contract
+      module Communications
+        class << self
+          def find(request)
+            ensure_request!(request, Requests::FindCommunication)
+            Observability::OperationLogger.around(
+              operation: "communications.find",
+              request:,
+            ) do
+              Internal::Finder.call(request)
+            end
+          end
+
+          private
+
+          def ensure_request!(request, expected_class)
+            return if request.is_a?(expected_class)
+
+            raise Contract::ValidationError, "expected #{expected_class}, got #{request.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/contract/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Contract
+      class Error < CommandTower::Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/contract/internal/finder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Contract
+      module Internal
+        class Finder
+          def self.call(request)
+            new(request).call
+          end
+
+          def initialize(request)
+            @request = request
+          end
+
+          def call
+            validate_request!
+
+            scope = Messaging::Communication.includes(
+              :destination_plan,
+              :inbox_item,
+              channel_deliveries: :delivery_attempts,
+            )
+            scope = scope.where(user_id: request.recipient_id) unless request.recipient_id.nil?
+
+            communication = scope.find_by(id: request.communication_id)
+            raise Contract::NotFoundError, "Communication not found" if communication.nil?
+
+            Mappers::CommunicationMapper.to_result(communication)
+          end
+
+          private
+
+          attr_reader :request
+
+          def validate_request!
+            raise Contract::ValidationError, "communication_id is required" if request.communication_id.nil?
+          end
+        end
+      end
+    end
+  end
+end