command_tower 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bce961e0a6770bd17a23396e3fdb5066655dbe937f91c85b00c4605802c48f7d
-  data.tar.gz: e5247dda098ad94825317ec31cfff34c1fa060aac6fcf432ca5a082f93c83e02
+  metadata.gz: 9e983f8f191ccb75948cdad73067d1cd43b7b1e5a8a3e0d34fc0130a76c313da
+  data.tar.gz: 5ef89ea100c06425afe3aee6f87b8b71503e4d28be6a4ff6e309af8a5b02c83f
 SHA512:
-  metadata.gz: dd5117447c0bf551b4b55e3a402fbda78a915c8bd0e31a2fbc10a785ef747cc9c6b7c5c8e3aa5306978872fd89910233fb67a69563a3dc1c5105fe06ce67834b
-  data.tar.gz: bb8d35c52ca0e32b44134015a81462350357fa5e678e3e3bce0daa11a3f76c2e14ff7d2e0731f8ddea812185f579df464886e01464670e68a375490d21528b03
+  metadata.gz: 6555727a8b33efc95493ecdeec48067e39c8ee9eb4f1750c8fd183599a8d41bf1e763d538d379d0be7888697e6f09ca0795ebb643817d5aea2c548c61cd867f6
+  data.tar.gz: ca51dafb697b03848b2509f16660df1e9e349f325a01da7d589300ac7db0ee087df33c08d46194a97e60ae6cbc984de8bcbf1fbc65f41d7bd31f31013d64add4

data/app/controllers/command_tower/me/experience_states_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Me
+    class ExperienceStatesController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def index
+        result = CommandTower::Workflows::Me::ExperienceStates::ListWorkflow.call(
+          current_user: current_user,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      def complete
+        deserialized = CommandTower::Deserializers::Me::ExperienceStates::CompleteDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        result = CommandTower::Workflows::Me::ExperienceStates::CompleteWorkflow.call(
+          current_user: current_user,
+          experience_key: deserialized.input.experience_key,
+          scope_type: deserialized.input.scope_type,
+          scope_identifier: deserialized.input.scope_identifier,
+          version: deserialized.input.version,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [
+              CommandTower::Errors::ValidationError.new(
+                details: { base: "Missing or invalid experience state completion fields" },
+              ),
+            ],
+            http_status: :unprocessable_entity,
+          ),
+        )
+      end
+    end
+  end
+end

data/app/controllers/command_tower/me/push_controller.rb

@@ -51,6 +51,14 @@ module CommandTower
         render_application_result(result)
       end
 
+      def test
+        result = CommandTower::Workflows::Me::Push::TestWorkflow.call(
+          current_user: current_user,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
       private
 
       def render_deserializer_errors

data/app/deserializers/command_tower/deserializers/me/experience_states/complete_deserializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      module ExperienceStates
+        class CompleteDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:experience_key, :scope_type, :scope_identifier, :version)
+
+          MAX_LENGTH = 128
+
+          def call(params)
+            experience_key = extract(params, :experienceKey, :experience_key)
+            scope_type = extract(params, :scopeType, :scope_type)
+            scope_identifier = extract(params, :scopeIdentifier, :scope_identifier)
+            version = extract(params, :version, :Version)
+
+            if [experience_key, scope_type, scope_identifier, version].any?(&:blank?)
+              return failure(errors: { message: "missing_required_fields" })
+            end
+
+            if [experience_key, scope_type, scope_identifier, version].any? { |value| value.length > MAX_LENGTH }
+              return failure(errors: { message: "invalid_field_length" })
+            end
+
+            success(
+              Input.new(
+                experience_key:,
+                scope_type:,
+                scope_identifier:,
+                version:,
+              ),
+            )
+          end
+
+          private
+
+          def extract(params, *keys)
+            keys.each do |key|
+              raw = params[key] || params[key.to_s]
+              next if raw.nil?
+
+              value = raw.to_s.strip
+              return value unless value.empty?
+            end
+            ""
+          end
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/experience_states_host_unconfigured_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class ExperienceStatesHostUnconfiguredError < CommandTower::Errors::ApplicationError
+        def code
+          "experience_states_host_unconfigured"
+        end
+
+        def message
+          "Experience states are currently unavailable"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/push_test_no_endpoint_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PushTestNoEndpointError < CommandTower::Errors::ApplicationError
+        def code
+          "push_test_no_endpoint"
+        end
+
+        def message
+          "No active push endpoint is registered for this account"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/push_test_rate_limit_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PushTestRateLimitError < CommandTower::Errors::ApplicationError
+        def initialize(retry_after_seconds: nil)
+          super(details: retry_after_seconds ? { retry_after_seconds: retry_after_seconds } : nil)
+        end
+
+        def code
+          "push_test_rate_limited"
+        end
+
+        def message
+          "Too many push test notifications. Please try again later."
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/models/command_tower/user_experience_state.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  class UserExperienceState < CommandTower::ApplicationRecord
+    self.table_name = "user_experience_states"
+
+    belongs_to :user
+
+    validates :host_key, :experience_key, :scope_type, :scope_identifier, :version, presence: true
+    validates :experience_key,
+              uniqueness: {
+                scope: %i[user_id host_key scope_type scope_identifier version],
+              }
+
+    scope :for_user_and_host, ->(user:, host_key:) { where(user:, host_key:) }
+  end
+end

data/app/serializers/command_tower/serializers/me/experience_states/experience_state_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      module ExperienceStates
+        class ExperienceStateSerializer
+          def self.serialize(state)
+            new(state).serialize
+          end
+
+          def self.serialize_collection(states)
+            {
+              experienceStates: Array(states).map { |state| serialize(state) },
+            }
+          end
+
+          def initialize(state)
+            @state = state
+          end
+
+          def serialize
+            {
+              hostKey: @state.host_key,
+              experienceKey: @state.experience_key,
+              scopeType: @state.scope_type,
+              scopeIdentifier: @state.scope_identifier,
+              version: @state.version,
+              completedAt: @state.completed_at&.iso8601,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/complete.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class Complete < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :experience_key, is_a: String, required: true
+          validate :scope_type, is_a: String, required: true
+          validate :scope_identifier, is_a: String, required: true
+          validate :version, is_a: String, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            identity = {
+              user:,
+              host_key:,
+              experience_key:,
+              scope_type:,
+              scope_identifier:,
+              version:,
+            }
+
+            existing = CommandTower::UserExperienceState.find_by(identity)
+            if existing
+              context.experience_state = existing
+              context.created = false
+              return
+            end
+
+            begin
+              created = CommandTower::UserExperienceState.create!(
+                identity.merge(completed_at: Time.current),
+              )
+              context.experience_state = created
+              context.created = true
+            rescue ActiveRecord::RecordNotUnique
+              recovered = CommandTower::UserExperienceState.find_by!(identity)
+              context.experience_state = recovered
+              context.created = false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class List < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            context.experience_states = CommandTower::UserExperienceState.for_user_and_host(
+              user:,
+              host_key:,
+            ).order(:completed_at, :id).to_a
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/check_self_test_rate_limit.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        # Enforces Me push self-test rate limits via existing RateLimits::Check.
+        # Ceiling and window come from config.messaging.expo composers — not hardcoded here.
+        class CheckSelfTestRateLimit < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            expo = CommandTower.config.messaging.expo
+            limit = expo.self_test_per_user_hour
+            ttl_seconds = expo.self_test_window_seconds
+
+            result = CommandTower::Services::RateLimits::Check.call(
+              key: "me:push:self_test:user:#{user.id}",
+              ttl_seconds:,
+            )
+            if result.failure?
+              context.fail!(application_error: result.errors.first)
+              return
+            end
+
+            count = result.data[:count]
+            return if count <= limit
+
+            ttl = result.data[:ttl]
+            retry_after = ttl.positive? ? ttl : nil
+            context.fail!(
+              application_error: CommandTower::Errors::Account::PushTestRateLimitError.new(
+                retry_after_seconds: retry_after,
+              ),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/send_self_test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        # Me self-test: Produce a host-registered push_delivery_test communication.
+        # Does not bypass Messaging; does not talk to Expo directly.
+        class SendSelfTest < CommandTower::Services::ApplicationService
+          NOTIFICATION_TYPE_KEY = "push_delivery_test"
+          TITLE = "Push notifications"
+          BODY = "This is a test notification from your account."
+
+          validate :user, is_a: User, required: true
+
+          def call
+            list_result = CommandTower::Services::Account::Push::List.call(user:)
+            unless list_result.success?
+              context.fail!(application_error: list_result.errors.first)
+              return
+            end
+
+            if Array(list_result.data[:safe_views]).empty?
+              context.fail!(application_error: CommandTower::Errors::Account::PushTestNoEndpointError.new)
+              return
+            end
+
+            rate_result = CommandTower::Services::Account::Push::CheckSelfTestRateLimit.call(user:)
+            unless rate_result.success?
+              context.fail!(application_error: rate_result.errors.first)
+              return
+            end
+
+            produce_result = CommandTower::Services::Messaging::Communications::Produce.call(
+              user:,
+              notification_type_key: NOTIFICATION_TYPE_KEY,
+              host_event_identity: "push_delivery_test/#{user.id}/#{SecureRandom.uuid}",
+              title: TITLE,
+              body: BODY,
+              metadata: {},
+              platform_enabled_channels: CommandTower::Services::Messaging::Preferences::PlatformEnabledChannels.call,
+            )
+            unless produce_result.success?
+              context.fail!(application_error: produce_result.errors.first)
+              return
+            end
+
+            context.communication_id = produce_result.data[:communication_id]
+            context.destination_plan_id = produce_result.data[:destination_plan_id]
+            context.selected_channels = produce_result.data[:selected_channels]
+            context.communication_status = produce_result.data[:communication_status]
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/error_mapping.rb

@@ -25,13 +25,16 @@ module CommandTower
                CommandTower::Errors::Account::PushoverAlreadyConfiguredError,
                CommandTower::Errors::Account::PushoverVerificationFailedError,
                CommandTower::Errors::Account::PushEndpointNotFoundError,
+               CommandTower::Errors::Account::PushTestNoEndpointError,
                CommandTower::Errors::ValidationError
             :unprocessable_entity
-          when CommandTower::Errors::Account::PhoneVerificationThrottledError
+          when CommandTower::Errors::Account::PhoneVerificationThrottledError,
+               CommandTower::Errors::Account::PushTestRateLimitError
             :too_many_requests
           when CommandTower::Errors::Account::SmsCapabilityUnavailableError,
                CommandTower::Errors::Account::PushoverCapabilityUnavailableError,
-               CommandTower::Errors::Account::PushCapabilityUnavailableError
+               CommandTower::Errors::Account::PushCapabilityUnavailableError,
+               CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError
             :service_unavailable
           when CommandTower::Errors::Account::PhoneVerificationSendFailedError,
                CommandTower::Errors::Account::PushoverProviderUnavailableError

data/app/workflows/command_tower/workflows/me/experience_states/complete_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        class CompleteWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, experience_key:, scope_type:, scope_identifier:, version:, auth_context: nil)
+            result = CommandTower::Services::Account::ExperienceStates::Complete.call(
+              user: current_user,
+              experience_key:,
+              scope_type:,
+              scope_identifier:,
+              version:,
+            )
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            if result.data[:created]
+              audit(
+                :experience_state_completed,
+                affected_user: current_user,
+                changes: {},
+                scope_class: :host,
+                host_context: {
+                  type: scope_type,
+                  identifier: scope_identifier,
+                },
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_view(result.data[:experience_state]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/experience_states/list_workflow.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        class ListWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, auth_context: nil)
+            result = CommandTower::Services::Account::ExperienceStates::List.call(user: current_user)
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_collection(result.data[:experience_states]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/experience_states/workflow_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        module WorkflowSupport
+          module_function
+
+          def expire_header_effects(auth_context)
+            return if auth_context.nil?
+
+            { set_expire_header: auth_context.token_expires_at }
+          end
+
+          def serialize_view(state)
+            CommandTower::Serializers::Me::ExperienceStates::ExperienceStateSerializer.serialize(state)
+          end
+
+          def serialize_collection(states)
+            CommandTower::Serializers::Me::ExperienceStates::ExperienceStateSerializer.serialize_collection(states)
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/push/test_workflow.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        class TestWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, auth_context: nil)
+            unless CommandTower::Services::Me::PushProductGate.enabled?
+              return failure(**WorkflowSupport.capability_failure)
+            end
+
+            result = CommandTower::Services::Account::Push::SendSelfTest.call(user: current_user)
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: http_status_for(error),
+              )
+            end
+
+            success(
+              payload: {
+                communicationId: result.data[:communication_id],
+                destinationPlanId: result.data[:destination_plan_id],
+                selectedChannels: result.data[:selected_channels],
+                status: result.data[:communication_status],
+              },
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+
+          private
+
+          def http_status_for(error)
+            case error
+            when CommandTower::Errors::ValidationError,
+                 CommandTower::Errors::Messaging::RecipientUnresolvedError,
+                 CommandTower::Errors::Messaging::AcceptRejectedError
+              :unprocessable_entity
+            when CommandTower::Errors::Messaging::IdempotencyConflictError
+              :conflict
+            else
+              CommandTower::Workflows::Me::ErrorMapping.http_status_for(error)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -104,11 +104,16 @@ CommandTower::Engine.routes.draw do
     # Expo push lifecycle always drawn (no route constraints).
     # Product readiness is workflow-gated as 503 push_capability_unavailable.
     # Collection JSON (multi-active). No verification POST — create/replace mark_verified.
+    # Self-test must be declared before :id routes so "test" is not captured as an id.
     get "push", to: "push#index"
     post "push", to: "push#create"
+    post "push/test", to: "push#test"
     patch "push/:id", to: "push#update"
     put "push/:id", to: "push#update"
     delete "push/:id", to: "push#destroy"
+
+    get "experience-states", to: "experience_states#index"
+    post "experience-states/complete", to: "experience_states#complete"
   end
 
   namespace :admin do

data/db/migrate/20260906180000_create_user_experience_states.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateUserExperienceStates < ActiveRecord::Migration[7.2]
+  def change
+    create_table :user_experience_states do |t|
+      t.timestamps
+      t.references :user, null: false, foreign_key: true
+      t.string :host_key, null: false, limit: 128
+      t.string :experience_key, null: false, limit: 128
+      t.string :scope_type, null: false, limit: 128
+      t.string :scope_identifier, null: false, limit: 128
+      t.string :version, null: false, limit: 128
+      t.datetime :completed_at, null: false
+    end
+
+    add_index :user_experience_states,
+              %i[user_id host_key experience_key scope_type scope_identifier version],
+              unique: true,
+              name: "index_user_experience_states_unique"
+
+    add_index :user_experience_states,
+              %i[user_id host_key],
+              name: "index_user_experience_states_on_user_host"
+  end
+end

data/docs/api_reference.md

@@ -447,6 +447,27 @@ There is **no** `POST /me/push/verification`. Create and replace call `Endpoints
 
 ---
 
+## Experience states
+
+Durable completion facts for host-composed experiences. CommandTower stores opaque identity keys only — no League / Season / Tenant semantics and no presentation instructions such as `showWelcome`.
+
+`config.application.host_key` is **server-bound**. The client must not supply `hostKey` / `host_key`. When `host_key` is blank, both routes return **503** `experience_states_host_unconfigured`.
+
+| Method | Path | Body | Notes |
+|--------|------|------|--------|
+| `GET` | `/me/experience-states` | — | `{ experienceStates: [...] }` — **completed rows only** for the configured host |
+| `POST` | `/me/experience-states/complete` | `experienceKey`/`experience_key`, `scopeType`/`scope_type`, `scopeIdentifier`/`scope_identifier`, `version` (snake or camelCase) | Idempotent complete; returns the durable fact |
+
+**Fact fields:** `hostKey`, `experienceKey`, `scopeType`, `scopeIdentifier`, `version`, `completedAt`. Never `showWelcome` / applicability / presentation instructions.
+
+**RBAC:** `me_experience_states` (`index`, `complete`). Grant explicitly on host roles (dummy host `member` includes it).
+
+**Audit:** first durable creation emits `experience_state_completed` (opaque `host_context` type/identifier). Idempotent replay does not emit again.
+
+**Spec:** `spec/requests/command_tower/me/experience_states_spec.rb`.
+
+---
+
 ## Admin Workspace
 
 ### `GET /admin/workspace`

data/docs/controllers.md

@@ -21,6 +21,7 @@ This page is an **index** of route areas. Detailed request/response contracts li
 | Phone | `/me/phone*` | Phone endpoint + verification |
 | Pushover | `/me/pushover*` | Pushover endpoint lifecycle + verification |
 | Push | `/me/push*` | Expo push endpoint collection (register / replace / revoke) |
+| Experience states | `/me/experience-states*` | Durable completed experience-state facts (list / complete) |
 | Admin messaging | `/admin/messaging/announcements` | Cohort announcements |
 
 Exact paths depend on where the host mounts the engine.

data/docs/host_integration_guide.md

@@ -32,10 +32,11 @@ In the host initializer, set at least:
 - `config.jwt.hmac_secret`
 - `config.signup_session.jwt_secret` (or `SIGNUP_SESSION_JWT_SECRET`)
 - `config.password_recovery_session.jwt_secret` (or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`)
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (for example experience states). Not client-supplied. Blank values cause Me experience-state routes to return **503** `experience_states_host_unconfigured`.
 
 Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuration](initializing.md#configuration).
 
-Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb) (sets `host_key` to `"command_tower"`).
 
 ### Email / SMTP
 

data/docs/initializing.md

@@ -107,6 +107,7 @@ Required for production-ready hosts:
 - `config.jwt.hmac_secret` — typically `SECRET_KEY_BASE` / `Rails.application.secret_key_base`
 - `config.signup_session.jwt_secret` — or `SIGNUP_SESSION_JWT_SECRET`
 - `config.password_recovery_session.jwt_secret` — or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (experience states). Not client-supplied. Blank → Me experience-state routes return **503**.
 
 Optional / feature-gated:
 

data/docs/upgrades/0.15.0.md

@@ -0,0 +1,32 @@
+# Upgrade: CommandTower 0.15.0
+
+**From:** `0.14.0`  
+**To:** `0.15.0`
+
+Minor release: Me push self-test (`POST /me/push/test`) through Messaging Produce, with configurable rate limits. No schema migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `POST /api/me/push/test` | Authenticated self-test. Produces `push_delivery_test` via Communications::Produce (Expo path). Requires at least one active push endpoint. Returns Produce identifiers only (no Expo tokens). |
+| RBAC `me_push` | Adds action `test` (same entity). Hosts that already grant `me_push` get the new action. |
+| `config.messaging.expo.self_test_per_user_hour` | Max self-test sends per user per rolling window (default **10**). |
+| `config.messaging.expo.self_test_window_seconds` | Rolling window length (default **3600**). |
+| Rate limit HTTP | Exceeded limit → **429** `push_test_rate_limited` with `retry_after_seconds` details (existing CT envelope). |
+| No endpoint | **422** `push_test_no_endpoint`. |
+| Gate off | **503** `push_capability_unavailable` (same as other `/me/push*` when Expo adapter disabled). |
+
+## Host actions
+
+1. Bump gem to `0.15.0` (or `>= 0.15.0`).
+2. **No new migration.**
+3. **Required before enabling Account Push notifications settings:** register notification type `push_delivery_test` with push-only plan (e.g. `allowed/default %w[push]`, `inbox_available: false`, `user_configurable: false`, not preference-visible). CT hardcodes this type key for Me self-test.
+4. Set `config.messaging.expo.self_test_per_user_hour` explicitly when product policy differs from the default (Pick’em: **10**).
+5. Keep Expo adapter enabled (`http` / `fake`) and `me_push` granted for roles that use push.
+
+## Not in this release
+
+- CT FE Account Push notifications settings / device lifecycle migration
+- Host Pick’em enablement / type registration / IPA
+- Physical TestFlight proof

data/docs/upgrades/0.16.0.md

@@ -0,0 +1,30 @@
+# Upgrade: CommandTower 0.16.0
+
+**From:** `0.15.0`  
+**To:** `0.16.0`
+
+Minor release: generic Me experience-state persistence and HTTP (completion facts only). New migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Table `user_experience_states` | Durable completion rows keyed by `user + host_key + experience_key + scope_type + scope_identifier + version` |
+| `config.application.host_key` | **Required** non-blank String for Me experience-states. Server-bound; never client-supplied. Blank → **503** `experience_states_host_unconfigured` |
+| `GET /api/me/experience-states` | Authenticated list of **completed** facts for the current user on this host only |
+| `POST /api/me/experience-states/complete` | Idempotent complete; audit `experience_state_completed` **only on first durable create** |
+| RBAC `me_experience_states` | New entity (`index`, `complete`). Hosts must **explicitly grant** (not auto-added to a generic Admin role) |
+| Audit | Configurable event `experience_state_completed` with opaque `host_context` |
+
+## Host actions
+
+1. Bump gem to `0.16.0` (or `>= 0.16.0`).
+2. Set `config.application.host_key` (e.g. Pick’em `"pickem"`; CT rails_app `"command_tower"`).
+3. Copy engine migrations and migrate: `bundle exec rails command_tower:install:migrations` then `db:migrate`.
+4. Grant RBAC entity `me_experience_states` to the roles/groups that should use Me experience-states (typically `member`).
+
+## Not in this release
+
+- CommandTower frontend experience-states capability / hydrate hooks
+- Host Welcome product composition
+- Push silent-sync / Welcome notification step

data/docs/upgrades/README.md

@@ -4,6 +4,8 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.16.0](0.16.0.md) | Me experience-states (`GET`/`POST complete`); `host_key`; `user_experience_states` migration; `me_experience_states` RBAC |
+| [0.15.0](0.15.0.md) | Me `POST /me/push/test` → Produce (`push_delivery_test`); configurable Expo self-test rate limit composers; `me_push#test` |
 | [0.14.0](0.14.0.md) | Expo push Messaging channel (`config.messaging.expo`) + `/api/me/push*` registration HTTP; `me_push` RBAC |
 | [0.13.1](0.13.1.md) | Canonical `Intervention::Severity` constants (`blocking`, `warning`, `informational`) |
 | [0.13.0](0.13.0.md) | Account self-service deletion (`DELETE /api/me/account`); tombstone + PII scrub; `me_account` RBAC; `users.deleted_at` migration |

data/lib/command_tower/authorization/default.yml

@@ -75,6 +75,12 @@ entities:
       - create
       - update
       - destroy
+      - test
+  - name: me_experience_states
+    controller: CommandTower::Me::ExperienceStatesController
+    only:
+      - index
+      - complete
   - name: me_audit_events
     controller: CommandTower::Me::AuditEventsController
     only:

data/lib/command_tower/configuration/application/config.rb

@@ -14,6 +14,11 @@ module CommandTower
           desc: "The default name of the application",
           default_shown: "# Auto Populates to the name of the application"
 
+        add_composer :host_key,
+          allowed: String,
+          default: "",
+          desc: "Server-bound host/product identity for CT-generic user-scoped state. Not client-supplied."
+
         add_composer :communication_name,
           allowed: String,
           dynamic_default: :app_name,

data/lib/command_tower/configuration/messaging/expo.rb

@@ -32,6 +32,19 @@ module CommandTower
                 "Required only if the Expo project enables enhanced push security. Never log.",
           allowed: String,
           default: ""
+
+        add_composer :self_test_per_user_hour,
+          desc: "Max Me push self-test (POST /me/push/test) sends allowed per user per rolling window. " \
+                "Hosts enabling Account Push notifications settings should set this explicitly " \
+                "(Pick'em: 10).",
+          allowed: Integer,
+          default: 10
+
+        add_composer :self_test_window_seconds,
+          desc: "Rolling window length in seconds for Me push self-test rate limiting " \
+                "(default 3600 = one hour).",
+          allowed: Integer,
+          default: 3600
       end
     end
   end

data/lib/command_tower/configuration/registry/audit/config.rb

@@ -265,6 +265,18 @@ module CommandTower
               subject_type: "User",
               affected_user_required: true,
               global_visible_in_host_scope: true
+            },
+            experience_state_completed: {
+              label: "Experience state completed",
+              tags: %w[experience account],
+              enabled: true,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: false,
+              affected_user_required: true
             }
           }.freeze
 

data/lib/command_tower/install/baseline.rb

@@ -15,6 +15,7 @@ module CommandTower
         20260817000001_add_scope_columns_to_command_tower_audit_events.rb
         20260817000003_create_command_tower_impersonation_sessions.rb
         20260826140000_add_deleted_at_to_users.rb
+        20260906180000_create_user_experience_states.rb
       ].freeze
 
       module_function

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.14.0"
+  VERSION = "0.16.0"
 end

data/spec/factories/user_experience_states.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :user_experience_state, class: "CommandTower::UserExperienceState" do
+    user
+    host_key { "command_tower" }
+    experience_key { "welcome" }
+    scope_type { "example_scope" }
+    sequence(:scope_identifier) { |n| n.to_s }
+    version { "v1" }
+    completed_at { Time.current }
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -211,6 +211,7 @@ files:
 - app/controllers/command_tower/auth/username/availability_controller.rb
 - app/controllers/command_tower/me/account_controller.rb
 - app/controllers/command_tower/me/audit_events_controller.rb
+- app/controllers/command_tower/me/experience_states_controller.rb
 - app/controllers/command_tower/me/inbox_controller.rb
 - app/controllers/command_tower/me/name_controller.rb
 - app/controllers/command_tower/me/password_controller.rb
@@ -254,6 +255,7 @@ files:
 - app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/change_password_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/delete_account_deserializer.rb
+- app/deserializers/command_tower/deserializers/me/experience_states/complete_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/phone_verification/verify_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/push/token_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb
@@ -262,6 +264,7 @@ files:
 - app/deserializers/command_tower/deserializers/messaging/inbox.rb
 - app/deserializers/command_tower/deserializers/messaging/preferences/show_deserializer.rb
 - app/deserializers/command_tower/deserializers/messaging/preferences/update_deserializer.rb
+- app/errors/command_tower/errors/account/experience_states_host_unconfigured_error.rb
 - app/errors/command_tower/errors/account/phone_already_verified_error.rb
 - app/errors/command_tower/errors/account/phone_missing_error.rb
 - app/errors/command_tower/errors/account/phone_verification_code_invalid_error.rb
@@ -271,6 +274,8 @@ files:
 - app/errors/command_tower/errors/account/phone_verification_throttled_error.rb
 - app/errors/command_tower/errors/account/push_capability_unavailable_error.rb
 - app/errors/command_tower/errors/account/push_endpoint_not_found_error.rb
+- app/errors/command_tower/errors/account/push_test_no_endpoint_error.rb
+- app/errors/command_tower/errors/account/push_test_rate_limit_error.rb
 - app/errors/command_tower/errors/account/pushover_already_configured_error.rb
 - app/errors/command_tower/errors/account/pushover_capability_unavailable_error.rb
 - app/errors/command_tower/errors/account/pushover_not_configured_error.rb
@@ -336,6 +341,7 @@ files:
 - app/models/command_tower/messaging/endpoint_pushover_credential.rb
 - app/models/command_tower/messaging/inbox_item.rb
 - app/models/command_tower/messaging/notification_preference.rb
+- app/models/command_tower/user_experience_state.rb
 - app/models/user.rb
 - app/models/user_secret.rb
 - app/serializers/command_tower/serializers/admin/messaging/announcement_response_serializer.rb
@@ -367,6 +373,7 @@ files:
 - app/serializers/command_tower/serializers/me/account_serializer.rb
 - app/serializers/command_tower/serializers/me/change_password_response_serializer.rb
 - app/serializers/command_tower/serializers/me/delete_account_response_serializer.rb
+- app/serializers/command_tower/serializers/me/experience_states/experience_state_serializer.rb
 - app/serializers/command_tower/serializers/me/push_serializer.rb
 - app/serializers/command_tower/serializers/me/pushover_serializer.rb
 - app/serializers/command_tower/serializers/messaging/inbox.rb
@@ -597,13 +604,17 @@ files:
 - app/services/command_tower/service_base.rb
 - app/services/command_tower/service_logging.rb
 - app/services/command_tower/services/account/clear_phone.rb
+- app/services/command_tower/services/account/experience_states/complete.rb
+- app/services/command_tower/services/account/experience_states/list.rb
 - app/services/command_tower/services/account/phone_verification/send.rb
 - app/services/command_tower/services/account/phone_verification/verify.rb
+- app/services/command_tower/services/account/push/check_self_test_rate_limit.rb
 - app/services/command_tower/services/account/push/create.rb
 - app/services/command_tower/services/account/push/ct_support.rb
 - app/services/command_tower/services/account/push/destroy.rb
 - app/services/command_tower/services/account/push/list.rb
 - app/services/command_tower/services/account/push/replace.rb
+- app/services/command_tower/services/account/push/send_self_test.rb
 - app/services/command_tower/services/account/pushover/create.rb
 - app/services/command_tower/services/account/pushover/ct_support.rb
 - app/services/command_tower/services/account/pushover/destroy.rb
@@ -734,12 +745,16 @@ files:
 - app/workflows/command_tower/workflows/me/delete_account_workflow.rb
 - app/workflows/command_tower/workflows/me/error_mapping.rb
 - app/workflows/command_tower/workflows/me/error_status.rb
+- app/workflows/command_tower/workflows/me/experience_states/complete_workflow.rb
+- app/workflows/command_tower/workflows/me/experience_states/list_workflow.rb
+- app/workflows/command_tower/workflows/me/experience_states/workflow_support.rb
 - app/workflows/command_tower/workflows/me/phone_verification/send_workflow.rb
 - app/workflows/command_tower/workflows/me/phone_verification/verify_workflow.rb
 - app/workflows/command_tower/workflows/me/push/create_workflow.rb
 - app/workflows/command_tower/workflows/me/push/destroy_workflow.rb
 - app/workflows/command_tower/workflows/me/push/index_workflow.rb
 - app/workflows/command_tower/workflows/me/push/replace_workflow.rb
+- app/workflows/command_tower/workflows/me/push/test_workflow.rb
 - app/workflows/command_tower/workflows/me/push/workflow_support.rb
 - app/workflows/command_tower/workflows/me/pushover/create_workflow.rb
 - app/workflows/command_tower/workflows/me/pushover/destroy_workflow.rb
@@ -769,6 +784,7 @@ files:
 - db/migrate/20260817000001_add_scope_columns_to_command_tower_audit_events.rb
 - db/migrate/20260817000003_create_command_tower_impersonation_sessions.rb
 - db/migrate/20260826140000_add_deleted_at_to_users.rb
+- db/migrate/20260906180000_create_user_experience_states.rb
 - docs/admin_workspace.md
 - docs/api_reference.md
 - docs/architecture.md
@@ -798,6 +814,8 @@ files:
 - docs/upgrades/0.13.0.md
 - docs/upgrades/0.13.1.md
 - docs/upgrades/0.14.0.md
+- docs/upgrades/0.15.0.md
+- docs/upgrades/0.16.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb
@@ -909,6 +927,7 @@ files:
 - spec/factories/messaging.rb
 - spec/factories/role.rb
 - spec/factories/user.rb
+- spec/factories/user_experience_states.rb
 - spec/factories/user_secret.rb
 homepage: https://github.com/matt-taylor/command_tower
 licenses: