spree_api 6.0.0.rc2 → 6.0.0.rc4

data/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb

@@ -6,7 +6,6 @@ module Spree
         # customer-facing. What the customer sees is the label on a tax line.
         class TaxRateSerializer < V3::BaseSerializer
           typelize name: :string,
-                   included_in_price: :boolean,
                    show_rate_in_label: :boolean,
                    tax_category_id: [:string, nullable: true],
                    store_id: [:string, nullable: true],
@@ -15,7 +14,7 @@ module Spree
                    metadata: ['Record<string, unknown>', nullable: true],
                    deleted_at: [:string, nullable: true]
 
-          attributes :name, :included_in_price, :show_rate_in_label, :metadata,
+          attributes :name, :show_rate_in_label, :metadata,
                      created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
 
           rate_attributes :rate, :rate_percent

data/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rb

@@ -32,8 +32,11 @@ module Spree
           # shipped still hold live credentials in the column. Null when the
           # caller cannot read the record the event is about.
           attribute :payload do |delivery|
+            # Fails closed: a reader that passes no gate gets nothing. The
+            # payload keeps the record body by design, so a caller holding
+            # `read_webhooks` alone must not see customer or payment data.
             visible = params[:payload_visible]
-            next nil if visible && !visible.call(delivery)
+            next nil unless visible&.call(delivery)
 
             Spree::WebhookPayloadRedaction.split(delivery.payload).first
           end

data/app/serializers/spree/api/v3/base_serializer.rb

@@ -224,6 +224,20 @@ module Spree
 
         private
 
+        # Adds the fields extensions registered for this class
+        # (Spree.api.extension_fields), read from the registry on every
+        # render as Spree.ransack is, so nothing is copied onto the class. A
+        # field never replaces an attribute the serializer writes itself.
+        def attributes_to_hash(object, hash)
+          super
+          Spree.api.extension_fields.for(self.class).each do |field|
+            next if @_attributes.key?(field.name)
+
+            set_key_and_attribute_body_from(object, field.name, field.reader, hash)
+          end
+          hash
+        end
+
         # Override Alba's fetch_attribute to automatically inject nested expand params
         # into child serializers via nested_params.
         # Uses `key` (the public API name, e.g. :categories) for expand lookup,

data/app/serializers/spree/api/v3/cart_serializer.rb

@@ -74,7 +74,11 @@ module Spree
         # it is dropped rather than redacted for a gated guest: a requirement
         # with its numbers stripped tells them nothing they can act on.
         attribute :requirements do |order|
-          requirements = Spree::Checkout::Requirements.new(order).call
+          # 5.6 storefronts matched the delivery requirement by its field, so
+          # it keeps the old name until 6.1; `code` already carries the new one.
+          requirements = Spree::Checkout::Requirements.new(order).call.map do |requirement|
+            requirement[:field] == 'delivery_method' ? requirement.merge(field: 'shipping_method') : requirement
+          end
           next requirements unless params[:hide_prices]
 
           requirements.reject { |requirement| requirement[:code] == 'order_minimum_not_met' }

data/app/serializers/spree/api/v3/price_history_serializer.rb

@@ -6,12 +6,17 @@ module Spree
       class PriceHistorySerializer < BaseSerializer
         typelize display_amount: display_money_type(:display_amount, nullable: false),
                  currency: [:string, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
-                 recorded_at: :string
+                 recorded_at: :string,
+                 amount_in_cents: [:number, nullable: true, deprecated: 'Use `amount`. Removed in 6.1.']
 
         attributes :currency
 
         money_attributes :amount, unit_price: true
 
+        attribute :amount_in_cents do |price_history|
+          price_history.amount_in_cents unless params[:hide_prices]
+        end
+
         attributes :display_amount
 
         attribute :recorded_at do |price_history|

data/app/serializers/spree/api/v3/price_serializer.rb

@@ -8,12 +8,22 @@ module Spree
         typelize display_amount: display_money_type(:display_amount),
                  display_compare_at_amount: display_money_type(:display_compare_at_amount),
                  currency: [:string, nullable: true, enum: Spree::Money::Rounding::CURRENCY_CODES, enum_type_name: 'CurrencyCode'],
-                 price_list_id: [:string, nullable: true]
+                 price_list_id: [:string, nullable: true],
+                 amount_in_cents: [:number, nullable: true, deprecated: 'Use `amount`. Removed in 6.1.'],
+                 compare_at_amount_in_cents: [:number, nullable: true, deprecated: 'Use `compare_at_amount`. Removed in 6.1.']
 
         attributes :currency
 
         money_attributes :amount, :compare_at_amount, unit_price: true
 
+        attribute :amount_in_cents do |price|
+          price.amount_in_cents unless params[:hide_prices]
+        end
+
+        attribute :compare_at_amount_in_cents do |price|
+          price.compare_at_amount_in_cents unless params[:hide_prices]
+        end
+
         attribute :display_amount do |price|
           price.display_amount&.to_s
         end

data/app/serializers/spree/api/v3/seller/price_history_serializer.rb

@@ -4,6 +4,7 @@ module Spree
       module Seller
         class PriceHistorySerializer < V3::PriceHistorySerializer
           without_formatted_money(:seller)
+          _attributes.delete(:amount_in_cents)
         end
       end
     end

data/app/serializers/spree/api/v3/seller/price_serializer.rb

@@ -4,6 +4,8 @@ module Spree
       module Seller
         class PriceSerializer < V3::PriceSerializer
           without_formatted_money(:seller)
+          _attributes.delete(:amount_in_cents)
+          _attributes.delete(:compare_at_amount_in_cents)
         end
       end
     end

data/config/routes.rb

@@ -238,6 +238,27 @@ Spree::Core::Engine.add_routes do
         post 'auth/password_resets', to: 'password_resets#create'
         patch 'auth/password_resets/:id', to: 'password_resets#update'
 
+        # OAuth 2.1 consent, read and decided by the dashboard. The admin's
+        # own session authorizes it: a secret key may authenticate here but
+        # can never grant authority on a person's behalf.
+        namespace :oauth do
+          get 'authorize', to: 'authorizations#show'
+          post 'authorize', to: 'authorizations#create'
+          delete 'authorize', to: 'authorizations#destroy'
+
+          # The OAuth clients registered against this store. Deleting one
+          # removes the registration; revoking a connection is the nested
+          # `tokens` resource, because that is what revoking deletes.
+          #
+          # Tokens are plural and addressable: a store registers a client once
+          # and every staff member connects to that same registration, so the
+          # live tokens are who is connected. Revoking one has to cut off that
+          # person and leave their colleagues working.
+          resources :applications, except: :show do
+            resources :tokens, only: %i[index destroy], controller: 'application_tokens'
+          end
+        end
+
         # Semantic reporting (docs/plans/6.0-analytics-semantic-layer.md)
         namespace :reporting do
           post :query
@@ -409,11 +430,12 @@ Spree::Core::Engine.add_routes do
         # preference, so there is nothing here to create.
         resources :payout_providers, only: [:index]
 
-        # Return / claim / refund / cancellation reasons (dropdowns + settings management)
+        # Return / claim / refund / cancellation / tax exemption reasons (dropdowns + settings management)
         resources :return_reasons
         resources :claim_reasons
         resources :refund_reasons
         resources :order_cancellation_reasons
+        resources :tax_exemption_reasons
 
         # Markets
         resources :markets
@@ -1052,6 +1074,14 @@ Spree::Core::Engine.add_routes do
         end
       end
 
+      # RFC 9728 Protected Resource Metadata. One document per protected
+      # resource, named by the surface that registered it, so a client
+      # discovers which authorization server guards the URL it was given.
+      # Unauthenticated: a client has no credential at the point it asks.
+      get 'oauth/protected-resource/:resource_key',
+          to: 'oauth/metadata#show',
+          as: :oauth_protected_resource
+
       # Webhooks (outside of store namespace — no API key authentication)
       namespace :webhooks do
         post 'payments/:payment_method_id', to: 'payments#create', as: :payment_webhook
@@ -1066,4 +1096,34 @@ Spree::Core::Engine.add_routes do
       end
     end
   end
+
+  # The authorization server's own endpoints: /oauth/authorize, /oauth/token,
+  # /oauth/revoke and RFC 8414 metadata. Outside the versioned API namespace —
+  # the OAuth protocol is not a Spree API resource and its paths are fixed by
+  # the spec and by what clients expect to find.
+  #
+  # `authorizations` is NOT skipped. Skipping it would leave the metadata
+  # document without an `authorization_endpoint`, which is required for the
+  # code flow, so a consumer client would have nowhere to send the browser.
+  # The controller is Spree's own and redirects to the dashboard's consent
+  # screen instead of rendering Doorkeeper's HTML.
+  #
+  # The application-management controllers stay skipped: connected apps are
+  # managed through /api/v3/admin/oauth/applications, under the Admin API's
+  # own authentication.
+  # `controllers` is a block method, not an option to `use_doorkeeper`.
+  #
+  # Doorkeeper's own controllers need a leading slash because these routes are
+  # drawn inside Spree::Core::Engine, which isolates the namespace — a bare
+  # `doorkeeper/tokens` resolves as `Spree::Doorkeeper::Tokens` and fails on
+  # the first request. Spree's own authorizations controller is named from the
+  # application root WITHOUT a slash, because the metadata document builds its
+  # URL with `url_for(controller: "/#{name}")` and adds the slash itself.
+  use_doorkeeper scope: 'oauth' do
+    controllers authorizations: 'api/v3/oauth/authorizations',
+                tokens: '/doorkeeper/tokens',
+                token_info: '/doorkeeper/token_info',
+                metadata: '/spree/api/v3/oauth/server_metadata'
+    skip_controllers :applications, :authorized_applications
+  end
 end

data/lib/spree/api/agent_membership_map.rb

@@ -0,0 +1,73 @@
+module Spree
+  module Api
+    # Which parents an agent may curate products into, derived from the
+    # controllers that adopt `Spree::Api::V3::Admin::ProductMembership`.
+    #
+    # Read off the controllers for the same reason {AgentResourceMap} is: a
+    # parent that adopts the concern later is curated without anyone editing
+    # this file, and one that drops it stops being offered.
+    module AgentMembershipMap
+      class << self
+        # @param map [Module]
+        # @return [Integer] how many parents were registered
+        def install(map: Spree::AgentTools::MembershipMap)
+          map.reset!
+
+          curating_controllers.each do |controller|
+            target = target_for(controller)
+            next if target.blank?
+
+            # Addressing a parent an agent cannot otherwise read would hand it
+            # a write with no matching read, and no way to name what it changed.
+            entry = Spree::AgentTools::ResourceMap.find(target.pluralize)
+            next if entry.nil?
+
+            map.register(
+              target: target,
+              permission: write_permission_for(entry),
+              api_path: membership_path_for(controller)
+            )
+          end
+
+          map.all.size
+        end
+
+        private
+
+        # Where this parent's products are added and removed, read from the
+        # routes. The nested path carries the parent's id, which a tool fills
+        # in from the parent it was given.
+        def membership_path_for(controller)
+          route = Spree::Core::Engine.routes.routes.find do |candidate|
+            candidate.defaults[:controller] == controller.controller_path &&
+              candidate.defaults[:action] == 'create'
+          end
+
+          route&.path&.spec.to_s.sub('(.:format)', '').presence
+        end
+
+        def curating_controllers
+          Rails.application.eager_load! unless Rails.application.config.eager_load
+
+          Spree::Api::V3::Admin::ResourceController.descendants.
+            select { |controller| controller.include?(Spree::Api::V3::Admin::ProductMembership) }.
+            sort_by(&:name)
+        end
+
+        # Curating is a write to the parent, so it is gated on the parent's
+        # own write scope — a price list rides `write_products`, a category
+        # `write_categories`, exactly as their controllers do.
+        def write_permission_for(entry)
+          entry.write_permission.presence || "write_#{entry.permission.to_s.sub(/\Aread_/, '')}"
+        end
+
+        # `Admin::Categories::ProductsController` curates a category. The
+        # parent is the namespace the nested controller sits in, which is how
+        # the routes name it too.
+        def target_for(controller)
+          controller.name.to_s.split('::')[-2]&.underscore&.singularize
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_resource_map.rb

@@ -0,0 +1,350 @@
+module Spree
+  module Api
+    # Fills {Spree::AgentTools::ResourceMap} from the Admin API's own
+    # controllers.
+    #
+    # Nothing here is a list. Every admin resource controller already declares
+    # the model it serves, the serializer it renders, the permission scope it
+    # rides and the workflow it writes through — so the map an agent reads is
+    # the API surface by construction, and a resource cannot drift from the
+    # endpoint that serves it. A controller that gains an attribute gains it
+    # for agents in the same commit.
+    #
+    # The one fact a controller does not carry is where the record lives in the
+    # dashboard, which is only used to link to it, so those are kept here.
+    #
+    # See docs/plans/6.0-mcp-server.md.
+    module AgentResourceMap
+      # Dashboard routes, for results that link to the record rather than
+      # describing where to find it. Store-relative: the panel prefixes the
+      # current store segment.
+      DASHBOARD_PATHS = {
+        'products' => '/products/%<id>s',
+        'categories' => '/products/categories/%<id>s',
+        'collections' => '/products/collections/%<id>s',
+        'price_lists' => '/products/price-lists/%<id>s',
+        'orders' => '/orders/%<id>s',
+        'customers' => '/customers/%<id>s',
+        'companies' => '/companies/%<id>s',
+        'sellers' => '/sellers/%<id>s',
+        'promotions' => '/promotions/%<id>s',
+        'channels' => '/settings/channels',
+        'markets' => '/settings/markets',
+        'payment_methods' => '/settings/payment-methods',
+        'delivery_profiles' => '/settings/delivery-profiles',
+        'stock_locations' => '/settings/stock-locations',
+        'tax_categories' => '/settings/tax-categories',
+        'tax_rates' => '/settings/tax-rates',
+        'product_types' => '/settings/product-types',
+        'commission_rates' => '/settings/commission-rates',
+        'roles' => '/settings/roles',
+        'return_reasons' => '/settings/reasons',
+        'allowed_origins' => '/settings/allowed-origins',
+        'imports' => '/settings/imports'
+      }.freeze
+
+      # Resources withheld whatever their controller says, because their
+      # serializer carries a live credential or a bearer instrument. Every
+      # tool result reaches a model and, for a hosted client, a third party.
+      #
+      #   api_keys, integrations, webhook_endpoints — plaintext tokens,
+      #     provider credentials and the secret that signs deliveries.
+      #   gift_cards — the code IS the instrument: whoever reads it can spend
+      #     the balance. A balance tool that never emits a code could be added.
+      #   invitations   — the acceptance link is a bearer token that mints a
+      #                   staff account at the invited role, and the endpoint
+      #                   it addresses is deliberately unauthenticated. The
+      #                   outbound filter drops the link, but a resource whose
+      #                   whole purpose is handing out authority does not
+      #                   belong on a read surface an agent drives.
+      WITHHELD_MODELS = %w[
+        Spree::ApiKey
+        Spree::OauthApplication
+        Spree::Integration
+        Spree::WebhookEndpoint
+        Spree::WebhookDelivery
+        Spree::GiftCard
+        Spree::Invitation
+      ].freeze
+
+      # Controllers that resolve their scope per request rather than declaring
+      # one, because the scope belongs to the resource being imported or
+      # exported — creating a product import is a product write, and reading
+      # its rows exposes the uploaded data. A single static key cannot say
+      # that, so these are registered read-only under the broadest key the
+      # controller can demand, and the write path stays with the endpoint.
+      DYNAMIC_SCOPE_RESOURCES = {
+        'imports' => { model_name: 'Spree::Import', permission: 'read_settings',
+                       serializer_name: 'Spree::Api::V3::Admin::ImportSerializer',
+                       dashboard_path: '/settings/imports' },
+        'exports' => { model_name: 'Spree::Export', permission: 'read_settings',
+                       serializer_name: 'Spree::Api::V3::Admin::ExportSerializer' }
+      }.freeze
+
+      class << self
+        # Registers this walk as how the core map fills itself, and marks the
+        # map stale so the next reader gets a fresh one. Called on every code
+        # reload; the walk itself runs when something actually reads the map.
+        #
+        # @return [void]
+        def stale!
+          Spree::AgentTools::ResourceMap.deriver = -> { install }
+          Spree::AgentTools::ResourceMap.stale!
+        end
+
+        # Walks every admin resource controller and registers what it serves.
+        #
+        # @param map [Class] defaults to the core resource map
+        # @return [Integer] how many resources were registered
+        def install(map: Spree::AgentTools::ResourceMap)
+          map.reset!
+
+          registered = resolve_collisions(controllers.filter_map { |controller| derive(controller) })
+          registered.each { |entry| map.register(**entry) }
+
+          DYNAMIC_SCOPE_RESOURCES.each { |key, attributes| map.register(key: key, **attributes) }
+
+          registered.size + DYNAMIC_SCOPE_RESOURCES.size
+        end
+
+        # Every admin resource controller in the application, the abstract
+        # bases excluded. Eager-loaded first: in development only the
+        # controllers already used would otherwise be known, and the map would
+        # differ between a fresh boot and a warm one.
+        #
+        # @return [Array<Class>]
+        def controllers
+          Rails.application.eager_load! unless Rails.application.config.eager_load
+
+          Spree::Api::V3::Admin::ResourceController.descendants.reject(&:abstract?).sort_by(&:name)
+        end
+
+        # What one controller contributes, or nil when it serves nothing an
+        # agent can address.
+        #
+        # @param controller [Class]
+        # @return [Hash, nil]
+        # Where this controller's operations live, read from the routes rather
+        # than guessed from the key: a nested or renamed resource keeps its
+        # real path, and a controller with no route is not reachable at all.
+        #
+        # The shallowest route wins. A resource reached both at the top level
+        # and under a parent (`/products` and
+        # `/catalogs/:catalog_id/products`) is addressed by the former: a tool
+        # given a product id has no parent id to fill in, and the nested route
+        # would leave `:catalog_id` in the path.
+        #
+        # @return [Hash{Symbol => String}] action => path template
+        # Across colliding controllers, the shallowest path per action.
+        def shallowest_paths(candidates)
+          candidates.flat_map { |entry| Array(entry[:api_paths]).to_a }.
+            group_by(&:first).
+            transform_values { |pairs| pairs.map(&:last).min_by { |path| [path.count(':'), path.length] } }
+        end
+
+        def api_paths_for(controller)
+          candidates = Spree::Core::Engine.routes.routes.filter_map do |route|
+            next unless route.defaults[:controller] == controller.controller_path
+
+            action = route.defaults[:action]&.to_sym
+            next if action.nil?
+
+            [action, route.path.spec.to_s.sub('(.:format)', '')]
+          end
+
+          candidates.group_by(&:first).transform_values do |pairs|
+            pairs.map(&:last).min_by { |path| [path.count(':'), path.length] }
+          end
+        end
+
+        def derive(controller)
+          instance = controller.allocate
+          model = safely(instance, :model_class)
+          return if model.nil? || WITHHELD_MODELS.include?(model.name)
+
+          scope = controller._scoped_resource
+          return if scope.blank?
+
+          serializer = safely(instance, :serializer_class)
+          return if serializer.nil?
+
+          key = key_for(model)
+          return unless store_scoped?(model)
+
+          create_workflow = workflow_key(instance, :create_workflow)
+          update_workflow = workflow_key(instance, :update_workflow)
+          writable = AgentWriteSchemas.attribute_names(key)
+
+          {
+            key: key,
+            model_name: model.name,
+            permission: "read_#{scope}",
+            serializer_name: serializer.name,
+            dashboard_path: DASHBOARD_PATHS[key],
+            api_paths: api_paths_for(controller),
+            write_permission: write_permission_for(model, scope, create_workflow, update_workflow, writable, controller),
+            writable_attributes: writable,
+            create_workflow_key: create_workflow,
+            update_workflow_key: update_workflow,
+            distinct: collection_distinct?(instance)
+          }
+        end
+
+        private
+
+        # What the controller does with its own collection. A controller that
+        # disables DISTINCT has a reason — Postgres refuses it beside an
+        # ORDER BY the select list does not carry — and a search tool adding
+        # it anyway answers with a 500.
+        def collection_distinct?(instance)
+          return true unless instance.respond_to?(:collection_distinct?, true)
+
+          instance.send(:collection_distinct?)
+        rescue StandardError
+          true
+        end
+
+        # A model can be served by more than one controller under different
+        # permission scopes — a tax identifier through customers and through
+        # orders, media through products and through the media library. One
+        # resource key can carry only one permission, and whichever controller
+        # happened to sort last is not an answer: it would grant a key holding
+        # `read_orders` the customers' records too.
+        #
+        # So a collision resolves to the narrowest scope offered, and the
+        # resource stays read-only, because the two controllers do not agree
+        # on who may write it. A caller holding the wider scope reaches the
+        # record through the endpoint, as before.
+        def resolve_collisions(entries)
+          entries.group_by { |entry| entry[:key] }.map do |_key, candidates|
+            next candidates.first if candidates.one?
+
+            narrowest = candidates.min_by { |entry| [scope_breadth(entry[:permission]), entry[:permission]] }
+            contested = candidates.map { |entry| entry[:permission] }.uniq.size > 1
+
+            # A workflow declaration is not in dispute — whichever controller
+            # declares one, that is how the resource is written, and the
+            # refusal has to keep naming that tool. Only the generic write is
+            # withdrawn, and only when the controllers disagree about the
+            # scope guarding it.
+            narrowest.merge(
+              create_workflow_key: candidates.filter_map { |entry| entry[:create_workflow_key] }.first,
+              update_workflow_key: candidates.filter_map { |entry| entry[:update_workflow_key] }.first,
+              write_permission: contested ? nil : narrowest[:write_permission],
+              writable_attributes: contested ? [] : narrowest[:writable_attributes],
+              # One controller refusing DISTINCT is enough: its sort would
+              # make Postgres reject the query, and whichever controller
+              # happened to sort first is not an answer.
+              distinct: candidates.all? { |entry| entry[:distinct] },
+              # The shallowest route across every controller claiming this
+              # key. `narrowest` is chosen by permission breadth, which says
+              # nothing about depth — so a resource served both at the top
+              # level and under a parent kept whichever won on scope, and a
+              # tool was handed a path with an unfillable `:parent_id` in it.
+              api_paths: shallowest_paths(candidates)
+            )
+          end
+        end
+
+        # How much a scope covers, so the narrowest wins a collision. Measured
+        # by the number of resources the catalog grants it, which is the only
+        # ranking the catalog actually gives us.
+        def scope_breadth(permission)
+          _kind, scope = Spree.permissions.resolve_key(permission)
+          scope ? Array(scope.resources).size : Float::INFINITY
+        rescue StandardError
+          Float::INFINITY
+        end
+
+        # A resource is generically writable only when the Admin API writes it
+        # by saving the record, and the OpenAPI document says what a write may
+        # set. A workflow-written resource keeps its workflow key instead (so
+        # the refusal can name the tool); a service-written one is not writable
+        # at all; and a resource with no documented body is read-only here,
+        # because a write tool with no attributes is one an agent can only get
+        # wrong.
+        # Writable when the controller documents a body and does not hand out
+        # authority.
+        #
+        # The list of service-written models this used to consult is gone
+        # (2026-10-10). It existed because a generic write assigned
+        # attributes and saved, so reaching a record whose controller
+        # orchestrates — an order, a refund, a stock level — would have
+        # skipped that orchestration. A dispatched write IS the controller,
+        # so there is nothing left to skip, and the list only withheld writes
+        # the API performs correctly.
+        #
+        # A declared workflow no longer withholds it either: the controller
+        # runs its own workflow, which is what the generic write now reaches.
+        def write_permission_for(model, scope, create_workflow, update_workflow, writable, controller)
+          return if writable.empty?
+          return if hands_out_authority?(controller)
+
+          "write_#{scope}"
+        end
+
+        # A controller that hands out authority — roles, role grants,
+        # invitations, API keys — runs an anti-amplification check the generic
+        # write knows nothing about: a caller may only grant permissions they
+        # themselves hold. Assigning those attributes and calling `save` would
+        # skip it, so writing them stays with the endpoint that guards them.
+        #
+        # Asked of the controller rather than listed, so a surface that adopts
+        # the guard later is covered without anyone remembering this file.
+        def hands_out_authority?(controller)
+          return false unless defined?(Spree::Api::V3::Admin::RoleGrantGuard)
+
+          controller.include?(Spree::Api::V3::Admin::RoleGrantGuard)
+        rescue StandardError
+          false
+        end
+
+        # The plural the resource is addressed by, taken from the model so two
+        # controllers serving the same model (a nested one and a top-level one)
+        # agree on it.
+        def key_for(model)
+          model.model_name.element.pluralize
+        end
+
+        # `Spree::Base.for_store` falls back to the bare class for a model with
+        # no Store association, which would hand this store's agent every
+        # store's rows. A model that defines its own `for_store` has made a
+        # deliberate choice (customers are global by design and say so);
+        # inheriting the fallback is an accident, and a missing resource is
+        # better than a leaking one.
+        def store_scoped?(model)
+          return false unless model.respond_to?(:for_store)
+          return true if model.method(:for_store).owner != Spree::Base.singleton_class
+
+          !model.for_store(probe_store).equal?(model)
+        rescue StandardError
+          false
+        end
+
+        # One unsaved store, reused: the probe asks what `for_store` does with
+        # a store, not with any particular one, and the walk covers every
+        # admin controller.
+        def probe_store
+          @probe_store ||= Spree::Store.new
+        end
+
+        # The workflow a controller writes through, as its dotted key, so a
+        # generic write can name the tool that does the job instead.
+        def workflow_key(instance, method_name)
+          workflow = safely(instance, method_name)
+          workflow.respond_to?(:workflow_key) ? workflow.workflow_key : nil
+        end
+
+        # A controller may raise from any of these — `model_class` is
+        # NotImplementedError on an abstract one, `permitted_attributes` reads
+        # request state on a few — and one such controller must not take the
+        # whole map down at boot.
+        def safely(instance, method_name)
+          instance.send(method_name)
+        rescue StandardError, NotImplementedError
+          nil
+        end
+      end
+    end
+  end
+end