spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/product.rb

@@ -4,22 +4,18 @@
 # Products properties include description, permalink, availability,
 #   shipping category, etc. that do not change by variant.
 #
-# MASTER VARIANT
-# Every product has one master variant, which stores master price and sku, size and weight, etc.
-# The master variant does not have option values associated with it.
-# Price, SKU, size, weight, etc. are all delegated to the master variant.
-# Contains on_hand inventory levels only when there are no variants for the product.
-#
 # VARIANTS
-# All variants can access the product properties directly (via reverse delegation).
-# Inventory units are tied to Variant.
-# The master variant can have inventory units, but not option values.
-# All other variants have option values and may have inventory units.
-# Sum of on_hand each variant's inventory level determine "on_hand" level for the product.
+# Every product has at least one variant. Simple products have a single variant
+# with no option values; products with options have one variant per combination.
+# `default_variant` is the "face" of the product — price, SKU, size, weight, etc.
+# are delegated to it. Inventory units are tied to Variant; the sum of each
+# variant's on_hand determines the product's "on_hand" level.
 #
 
 module Spree
   class Product < Spree.base_class
+    include Spree::CSV::CustomFieldsHelper
+
     has_prefix_id :prod # Stripe: prod_
 
     acts_as_paranoid
@@ -30,40 +26,52 @@ module Spree
     include Spree::ProductScopes
     include Spree::TranslatableResource
     include Spree::MemoizedData
-    include Spree::Metafields
-    include Spree::MetafieldFilterable
+    include Spree::SanitizableRichText
+    include Spree::HasCustomFields
+    include Spree::CustomFieldFilterable
     include Spree::Metadata
+    include Spree::HasExternalReferences
     include Spree::Searchable
-    include Spree::Product::Webhooks
     include Spree::Product::Slugs
     include Spree::Product::Channels
-    include Spree::LegacyMultiStoreSupport unless defined?(SpreeMultiStore)
     include Spree::SearchIndexable
-    if defined?(Spree::VendorConcern)
-      include Spree::VendorConcern
-    end
+    include Spree::StorePreferences
 
     publishes_lifecycle_events
 
-    MEMOIZED_METHODS = %w[total_on_hand taxonomy_ids taxon_and_ancestors
+    MEMOIZED_METHODS = %w[total_on_hand category_and_ancestors
                           default_variant_id tax_category default_variant variant_for_images
-                          brand_taxon main_taxon
+                          primary_category buy_box_variants resolved_delivery_profile
                           purchasable? in_stock? backorderable? digital?]
 
+    # Statuses an operator sets directly. `bulk_status_update` validates
+    # against this, which is why the review statuses are not in it: reaching
+    # `proposed` is a seller submitting and reaching `rejected` is an operator
+    # deciding, and neither is a value to assign in bulk.
     STATUSES = %w[draft active archived].freeze
 
-    STATUS_TO_WEBHOOK_EVENT = {
-      'active' => 'activated',
-      'draft' => 'drafted',
-      'archived' => 'archived'
-    }.freeze
+    # Where a product sits in the marketplace review lifecycle. Only the
+    # workflows (Products::Propose, ::Approve, ::Reject) move a product in or
+    # out of these; see docs/plans/6.0-seller-product-submission.md.
+    REVIEW_STATUSES = %w[proposed rejected].freeze
+
+    ALL_STATUSES = (STATUSES + REVIEW_STATUSES).freeze
 
     TRANSLATABLE_FIELDS = %i[name description slug meta_description meta_title].freeze
     RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
     translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
 
+    has_spree_rich_text :description
+
+    # Translated descriptions live on the Mobility translation table, so writes
+    # through locale accessors or +upsert_translations+ never touch the base
+    # record's +description+ attribute — the translation model needs its own
+    # sanitization pass.
     self::Translation.class_eval do
+      include Spree::SanitizableRichText
+
       normalizes :name, :meta_title, with: ->(value) { value&.to_s&.squish&.presence }
+      sanitizes_rich_text :description
     end
 
     # we need to have this callback before any dependent: :destroy associations
@@ -72,10 +80,76 @@ module Spree
 
     has_many :product_option_types, -> { order(:position) }, dependent: :destroy, inverse_of: :product
     has_many :option_types, through: :product_option_types
-    has_many :classifications, -> { order(created_at: :asc) }, dependent: :delete_all, inverse_of: :product
-    has_many :taxons, through: :classifications, before_remove: :remove_taxon
-    has_many :categories, through: :classifications, class_name: 'Spree::Category', source: :taxon
-    has_many :taxonomies, through: :taxons
+    has_many :product_categories, -> { order(created_at: :asc) }, class_name: 'Spree::ProductCategory', dependent: :delete_all, inverse_of: :product
+    has_many :categories, through: :product_categories, class_name: 'Spree::Category', source: :category, before_remove: :remove_category
+    has_many :taxonomies, through: :categories, deprecated: true
+
+    # @deprecated The classification_count column was renamed to categories_count in 6.0.
+    alias_attribute :classification_count, :categories_count
+
+    # @deprecated Use #product_categories; removed in 6.1.
+    # The live row in the review trail, or nil for a product nobody submitted.
+    #
+    # @return [Spree::ProductSubmission, nil]
+    def latest_submission
+      submissions.latest_first.first
+    end
+
+    # Why the marketplace turned this listing down, for the seller to read.
+    # Answers nil once the product moves on, so a stale note never shows
+    # against a product that is no longer rejected.
+    #
+    # @return [String, nil]
+    def rejection_reason
+      return unless rejected?
+
+      latest_submission&.review_note
+    end
+
+    # Whether this product is waiting on, or has had, a marketplace decision.
+    #
+    # @return [Boolean]
+    def in_review?
+      REVIEW_STATUSES.include?(status)
+    end
+
+    def classifications
+      Spree::Deprecation.warn('Spree::Product#classifications is deprecated and will be removed in Spree 6.1. Use #product_categories instead.')
+      product_categories
+    end
+
+    # @deprecated Use #categories / #category_ids; removed in 6.1.
+    def taxons
+      Spree::Deprecation.warn('Spree::Product#taxons is deprecated and will be removed in Spree 6.1. Use #categories instead.')
+      categories
+    end
+
+    def taxons=(value)
+      Spree::Deprecation.warn('Spree::Product#taxons= is deprecated and will be removed in Spree 6.1. Use #categories= instead.')
+      self.categories = value
+    end
+
+    def taxon_ids
+      Spree::Deprecation.warn('Spree::Product#taxon_ids is deprecated and will be removed in Spree 6.1. Use #category_ids instead.')
+      category_ids
+    end
+
+    def taxon_ids=(ids)
+      Spree::Deprecation.warn('Spree::Product#taxon_ids= is deprecated and will be removed in Spree 6.1. Use #category_ids= instead.')
+      self.category_ids = ids
+    end
+
+    has_many :product_collections, class_name: 'Spree::ProductCollection', dependent: :destroy_async, inverse_of: :product
+    has_many :collections, through: :product_collections
+    has_many :catalog_products, class_name: 'Spree::CatalogProduct', dependent: :destroy_async, inverse_of: :product
+    has_many :catalogs, through: :catalog_products
+
+    # Dropped with the product so a deleted product stops excluding itself from
+    # delivery methods. Destroyed inline rather than async — a product sits in
+    # at most a handful of exclusion rules, and deferring it would leave the
+    # rule reporting an id the API can no longer resolve.
+    has_many :delivery_method_rule_products, class_name: 'Spree::DeliveryMethodRuleProduct',
+             dependent: :destroy, inverse_of: :product
 
     has_many :product_promotion_rules, class_name: 'Spree::ProductPromotionRule'
     has_many :promotion_rules, through: :product_promotion_rules, class_name: 'Spree::PromotionRule'
@@ -86,65 +160,92 @@ module Spree
                                                              class_name: 'Spree::Promotion',
                                                              source: :promotion
 
-    belongs_to :tax_category, class_name: 'Spree::TaxCategory'
-    belongs_to :shipping_category, class_name: 'Spree::ShippingCategory', inverse_of: :products
-    has_many :shipping_methods, through: :shipping_category, class_name: 'Spree::ShippingMethod'
+    belongs_to :tax_category, class_name: 'Spree::TaxCategory', optional: true
+    belongs_to :product_type, class_name: 'Spree::ProductType', optional: true, counter_cache: :products_count
+    # The seller this product belongs to on a marketplace. Nil is the
+    # operator's own catalog — which is everything, on a store selling only
+    # its own goods.
+    belongs_to :seller, class_name: 'Spree::Seller', optional: true, inverse_of: :products
+
+    # How this product ships: origins, zones and methods all hang off the
+    # profile. Required — a product without one could not be fulfilled at
+    # all — and auto-assigned on create (type template, else the store's
+    # default profile), so callers never have to think about it. The FK is
+    # the renamed 5.x shipping_category_id, so migrated catalogs arrive
+    # already assigned.
+    belongs_to :delivery_profile, class_name: 'Spree::DeliveryProfile', inverse_of: :products
+
+    # Every one of the product's variants now resolves its profile through
+    # +resolved_delivery_profile+, which memoizes — so a reassignment has to
+    # drop the memo, or the whole fleet keeps shipping on the old profile
+    # until the product is saved.
+    %i[delivery_profile delivery_profile_id].each do |name|
+      define_method(:"#{name}=") do |value|
+        @resolved_delivery_profile = nil
+        @digital = nil
+        super(value)
+      end
+    end
 
-    has_one :master,
-            -> { where is_master: true },
-            inverse_of: :product,
-            class_name: 'Spree::Variant'
+    # Guards every write path (including raw prefixed-id assignment) against
+    # linking another store's profile.
+    validate :delivery_profile_must_belong_to_store, if: :delivery_profile_id_changed?
+    # Either side moving breaks the pair, and a product's store is not frozen
+    # after create, so watching only the seller would let a move carry the old
+    # store's seller along.
+    validate :seller_must_belong_to_store, if: -> { seller_id_changed? || store_id_changed? }
 
+    # Every product has at least one variant. `default_variant` is the "face" of
+    # the product (price display, default add-to-cart, property delegation).
     has_many :variants,
-             -> { where(is_master: false).order(:position) },
-             inverse_of: :product,
-             class_name: 'Spree::Variant'
-
-    has_many :variants_including_master,
              -> { order(:position) },
              inverse_of: :product,
              class_name: 'Spree::Variant',
              dependent: :destroy
 
-    has_many :prices, -> { order('spree_variants.position, spree_variants.id, currency') }, through: :variants
+    belongs_to :default_variant, class_name: 'Spree::Variant', optional: true, autosave: true
+
+    has_many :prices, through: :variants
 
-    has_many :stock_items, through: :variants_including_master
+    has_many :stock_levels, through: :variants
 
-    has_many :line_items, through: :variants_including_master
+    has_many :line_items, through: :variants
     has_many :orders, through: :line_items
     has_many :completed_orders, -> { reorder(nil).distinct.complete }, through: :line_items, source: :order
 
-    has_many :media, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'
+    has_many :media, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Media'
 
-    has_many :variant_images, -> { order(:position) }, source: :images, through: :variants_including_master
-    has_many :variant_images_without_master, -> { order(:position) }, source: :images, through: :variants
+    # The review trail for a seller's listing. Append-only: the latest row is
+    # the live one (docs/plans/6.0-seller-product-submission.md).
+    has_many :submissions, class_name: 'Spree::ProductSubmission', dependent: :destroy, inverse_of: :product
 
-    belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_id
+    has_many :variant_images, -> { order(:position) }, source: :images, through: :variants
+
+    belongs_to :primary_media, class_name: 'Spree::Media', optional: true, foreign_key: :primary_media_id
 
     has_many :option_value_variants, class_name: 'Spree::OptionValueVariant', through: :variants
     has_many :option_values, class_name: 'Spree::OptionValue', through: :variants
 
-    has_many :prices_including_master, -> { non_zero }, through: :variants_including_master, source: :prices
-
-    has_many :digitals, through: :variants_including_master
+    has_many :digital_assets, through: :variants, class_name: 'Spree::DigitalAsset'
+    has_many :digitals, through: :variants, class_name: 'Spree::DigitalAsset', source: :digital_assets, deprecated: true
 
-    after_initialize :ensure_master
     after_initialize :assign_default_tax_category
+    # The type's profile is a creation-time template: stamped here, never
+    # synced afterwards — reassigning the type later leaves the product's
+    # profile alone. Falls back to the store's default profile, keeping the
+    # required association satisfiable without the caller naming one.
+    before_validation :stamp_template_delivery_profile, on: :create
 
-    before_validation :validate_master
-    before_validation :ensure_default_shipping_category
+    after_create :sync_associations_from_product_type
+    after_update :sync_associations_from_product_type, if: :saved_change_to_product_type_id?
+    after_create :ensure_default_variant
+    after_create :set_default_variant
 
-    after_create :add_associations_from_prototype
-    after_create :build_variants_from_option_values_hash, if: :option_values_hash
-    after_create :apply_pending_variants, if: :pending_variants?
-    after_save :apply_pending_media, if: :pending_media?
+    after_save :auto_promote_default_variant
+    after_save :run_touch_callbacks, if: :saved_changes?
+    after_touch :touch_categories
 
-    after_save :save_master
-    after_save :run_touch_callbacks, if: :anything_changed?
-    after_save :reset_nested_changes
-    after_touch :touch_taxons
-
-    after_commit :auto_match_taxons, if: :eligible_for_taxon_matching?
+    after_commit :auto_match_collections, if: :eligible_for_collection_matching?
 
     with_options length: { maximum: 255 }, allow_blank: true do
       validates :meta_keywords
@@ -152,44 +253,53 @@ module Spree
     end
     with_options presence: true do
       validates :name
-      validates :shipping_category, if: :requires_shipping_category?
-      validates :price, if: :requires_price?
     end
 
+    # Every persisted product must keep a default variant. It's assigned on
+    # create by +set_default_variant+, so only enforce it on update.
+    validates :default_variant, presence: true, on: :update
+
     validate :discontinue_on_must_be_later_than_make_active_at, if: -> { make_active_at && discontinue_on }
 
     scope :for_store, ->(store) { where(store_id: store.id) }
-    scope :draft, -> { where(status: 'draft') }
-    scope :archived, -> { where(status: 'archived') }
+    # Products belonging to the given seller. Passing nil selects the
+    # operator's own catalog, which on a store with no sellers is everything.
+    # The same answer `Seller#products` gives, as a scope a bulk read can chain.
+    scope :for_seller, ->(seller) { where(seller_id: seller.respond_to?(:id) ? seller.id : seller) }
     scope :not_archived, -> { where.not(status: 'archived') }
     scope :on_sale, lambda { |currency = nil|
                       currency ||= Spree::Store.default.default_currency
-                      joins(:prices_including_master).with_currency(currency).
+                      with_currency(currency).
+                        where.not(spree_prices: { amount: 0 }).
                         where.not(spree_prices: { compare_at_amount: [nil, 0] }).
                         where("#{Spree::Price.table_name}.compare_at_amount > #{Spree::Price.table_name}.amount")
                     }
 
-    scope :search, ->(query) {
+    # @param store [Spree::Store] whose custom-field definitions take part in
+    #   the search. Definitions are store-owned, so the caller says which store
+    #   is searching; `Spree::Current.store` is the request's answer and a
+    #   background caller (an export, say) passes its own.
+    scope :search, ->(query, store = Spree::Current.store) {
       next none if query.blank?
 
       product_ids = Spree::Variant.search_by_product_name_or_sku(query).pluck(:product_id)
 
-      searchable_definitions = Spree::MetafieldDefinition.
+      searchable_definitions = store.custom_field_definitions.
                                for_resource_type('Spree::Product').
                                searchable
 
-      # Only pay for the metafield scan when some definition opts into search;
-      # the leading-wildcard LIKE over spree_metafields can't use an index.
-      metafield_ids = if searchable_definitions.exists?
-                        joins(metafields: :metafield_definition).
+      # Only pay for the custom_field scan when some definition opts into search;
+      # the leading-wildcard LIKE over spree_custom_fields can't use an index.
+      custom_field_ids = if searchable_definitions.exists?
+                        joins(custom_fields: :custom_field_definition).
                           merge(searchable_definitions).
-                          where(search_condition(Spree::Metafield, :value, query)).
+                          where(search_condition(Spree::CustomField, :value, query)).
                           unscope(:order).distinct.pluck(:id)
                       else
                         []
                       end
 
-      where(id: (product_ids + metafield_ids).uniq.compact)
+      where(id: (product_ids + custom_field_ids).uniq.compact)
     }
 
     # Backward compatibility alias — remove in Spree 6.0
@@ -197,19 +307,15 @@ module Spree
 
     scope :archivable, -> { where(status: %w[active draft]) }
     scope :by_source, ->(source) { send(source) }
-    scope :paused, -> { where(status: 'paused') }
     scope :published, -> { where(status: 'active') }
 
-    attr_accessor :option_values_hash
-
     accepts_nested_attributes_for(
       :variants,
       allow_destroy: true,
       reject_if: lambda do |v|
-        v[:option_value_variants_attributes].blank? && v[:stock_items_attributes].blank? && v[:prices_attributes].blank?
+        v[:option_value_variants_attributes].blank? && v[:stock_levels_attributes].blank? && v[:prices_attributes].blank?
       end
     )
-    accepts_nested_attributes_for :master, reject_if: :all_blank
     accepts_nested_attributes_for(
       :product_option_types,
       allow_destroy: true,
@@ -224,178 +330,202 @@ module Spree
       self.tag_list = tags
     end
 
-    # Sets prices on the master variant.
+    # Sets prices on the default variant.
     # Accepts array of { currency:, amount:, compare_at_amount: } hashes.
     def prices=(prices_params)
-      find_or_build_master.prices = prices_params
+      find_or_build_default_variant.prices = prices_params
     end
 
-    # Maps 6.0 API name (category_ids) to model column (taxon_ids).
-    # Accepts both prefixed IDs and raw integer IDs. Only taxons belonging to
-    # the product's own store are assigned — ids from another store's
-    # taxonomies are dropped, preventing cross-store category attachment.
+    # Accepts both prefixed IDs and raw integer IDs. Only categories belonging to
+    # the product's own store are assigned — ids from another store are dropped,
+    # preventing cross-store category attachment. Decodes prefixed IDs, then calls
+    # the generated setter via super.
     def category_ids=(ids)
       decoded_ids = Array(ids).filter_map do |id|
-        id.to_s.include?('_') ? Spree::Taxon.decode_prefixed_id(id) : id
+        id.to_s.include?('_') ? Spree::Category.decode_prefixed_id(id) : id
       end
-      self.taxon_ids = Spree::Taxon.for_store(assignable_store).where(id: decoded_ids).ids
+      super(Spree::Category.for_store(assignable_store).where(id: decoded_ids).ids)
     end
 
-    # Sync media inline. Entries with `id` patch the existing asset
-    # (alt/position/variant_ids); entries with `signed_id` create + attach a
-    # fresh upload; missing items are left alone (delete still goes through
-    # the dedicated DELETE /media endpoint to avoid accidental data loss when
-    # a form ships stale state).
+    # Accepts both prefixed IDs and raw integer IDs. Only collections belonging
+    # to the product's own store are assigned; this overrides the generated
+    # setter and calls super.
     #
-    # Deferred: ActiveStorage attaches require a persisted record, so on new
-    # records we stash the params and replay them in `after_create`.
-    # @param media_params [Array<Hash>]
-    # @return [void]
-    def media=(media_params)
-      # Blank input is a no-op — never call `super` with an empty array,
-      # because the ActiveRecord collection setter would replace media with
-      # `[]` and trigger `dependent: :destroy` on every persisted asset.
-      # Explicit deletes go through the dedicated DELETE /media endpoint.
-      return if media_params.blank?
-      return super if media_params.first.is_a?(Spree::Asset)
-
-      if new_record?
-        @pending_media_params = media_params
-        return
-      end
-
-      apply_media(media_params)
-    end
-
-    # Syncs variants from an array of hashes.
-    # Creates new variants, updates existing ones (matched by :id), and removes unlisted ones.
-    # Must be called on a persisted product (use after_save or call explicitly after create).
-    # @param variants_params [Array<Hash>] array of variant attribute hashes
-    # @return [void]
-    def variants=(variants_params)
-      return super if variants_params.blank? || variants_params.first.is_a?(Spree::Variant)
-
-      # Store for deferred processing if product is not yet persisted
-      if new_record?
-        @pending_variants_params = variants_params
-        return
+    # This is a replace setter, so it governs manual membership only. Automatic
+    # collections are materialized from their rules, which means they must
+    # survive a write that doesn't mention them (otherwise saving a product
+    # would wipe rule-derived membership until the next regeneration) and must
+    # not be assignable by hand (a hand-set member would vanish at that
+    # regeneration). So incoming automatic ids are ignored, and the product's
+    # existing automatic memberships are carried over untouched.
+    def collection_ids=(ids)
+      decoded_ids = Array(ids).filter_map do |id|
+        id.to_s.include?('_') ? Spree::Collection.decode_prefixed_id(id) : id
       end
-
-      apply_variants(variants_params)
+      manual_ids = Spree::Collection.for_store(assignable_store).manual.where(id: decoded_ids).ids
+      super(manual_ids | collections.automatic.ids)
     end
 
-    self.whitelisted_ransackable_attributes = %w[description name slug discontinue_on status available_on created_at updated_at]
-    self.whitelisted_ransackable_associations = %w[taxons categories store channels variants_including_master master variants tags labels
-                                                   shipping_category classifications option_types]
-    self.whitelisted_ransackable_scopes = %w[not_discontinued search_by_name in_taxon in_category in_categories price_between
+    self.whitelisted_ransackable_attributes = %w[description name slug discontinue_on status available_on created_at updated_at seller_id]
+    self.whitelisted_ransackable_associations = %w[categories collections store channels variants default_variant tags labels
+                                                   product_type product_categories option_types seller]
+    self.whitelisted_ransackable_scopes = %w[not_discontinued search_by_name in_taxon in_category in_categories in_collection price_between
                                              price_lte price_gte
                                              search multi_search in_stock out_of_stock with_option_value_ids
 
                                              ascend_by_price descend_by_price]
 
+    # All product-level convenience attributes delegate to the default variant —
+    # one target, no branching. Reads resolve the existing default variant
+    # (nil-safe) and never build one as a side effect; only setters build on
+    # demand, so `product.sku = ...` still works before the product is persisted.
     [
-      :sku, :barcode, :weight, :height, :width, :depth, :is_master, :dimensions_unit, :weight_unit
+      :sku, :barcode, :weight, :height, :width, :depth, :dimensions_unit, :weight_unit,
+      :price_in, :amount_in, :compare_at_amount_in,
+      :cost_currency, :cost_price, :track_inventory
     ].each do |method_name|
-      delegate method_name, :"#{method_name}=", to: :find_or_build_master
+      delegate method_name, to: :default_variant, allow_nil: true
+      delegate :"#{method_name}=", to: :find_or_build_default_variant
     end
 
-    [
-      :price, :price_in, :amount_in, :compare_at_price, :compare_at_amount_in,
-      :currency, :cost_currency, :cost_price, :track_inventory
-    ].each do |method_name|
-      delegate method_name, :"#{method_name}=", to: :default_variant
+    # Read-only delegations: these have no product-level writer. Prices are
+    # written per currency through the default variant's +set_price+.
+    delegate :compare_at_price, :track_inventory?, :images, to: :default_variant, allow_nil: true
+
+    # No state machine — status moves through the Spree::Products workflows
+    # (docs/plans/6.0-service-workflows.md). has_status generates the `draft`
+    # and `archived` scopes and every predicate, but never redefines what the
+    # model already owns: `Product.active` stays the currency-aware scope from
+    # Spree::ProductScopes rather than a plain status lookup.
+    include Spree::HasStatus
+    has_status(*ALL_STATUSES, default: :draft)
+
+    # @deprecated Call Spree.product_activate_workflow — removed in 6.1.
+    def activate!
+      Spree::Deprecation.warn('Spree::Product#activate! is deprecated and will be removed in Spree 6.1. Call Spree.product_activate_workflow instead.')
+      run_status_workflow(Spree.product_activate_workflow)
     end
 
-    delegate :display_amount, :display_price, :has_default_price?, :track_inventory?,
-             :display_compare_at_price, :images, to: :default_variant
+    # @deprecated Call Spree.product_archive_workflow — removed in 6.1.
+    def archive!
+      Spree::Deprecation.warn('Spree::Product#archive! is deprecated and will be removed in Spree 6.1. Call Spree.product_archive_workflow instead.')
+      run_status_workflow(Spree.product_archive_workflow)
+    end
 
-    # Rails doesn't provide _id methods for has_one associations by default
-    delegate :id, to: :master, prefix: true, allow_nil: true
+    # @deprecated Call Spree.product_draft_workflow — removed in 6.1.
+    def draft!
+      Spree::Deprecation.warn('Spree::Product#draft! is deprecated and will be removed in Spree 6.1. Call Spree.product_draft_workflow instead.')
+      run_status_workflow(Spree.product_draft_workflow)
+    end
 
-    alias master_images images
+    def self.bulk_auto_match_collections(store, product_ids)
+      return if store.collections.automatic.none?
 
-    state_machine :status, initial: :draft do
-      event :activate do
-        transition to: :active
-      end
-      after_transition to: :active, do: [:after_activate, :send_product_activated_webhook, :publish_product_activated_event]
+      products_to_auto_match_ids = store.products.not_deleted.not_archived.where(id: product_ids).ids
 
-      event :archive do
-        transition to: :archived
+      auto_match_collections_jobs = products_to_auto_match_ids.map do |product_id|
+        Spree::Products::AutoMatchCollectionsJob.new(product_id).tap { |job| job.scheduled_at = 30.seconds.from_now }
       end
-      after_transition to: :archived, do: [:after_archive, :send_product_archived_webhook, :publish_product_archived_event]
 
-      event :draft do
-        transition to: :draft
-      end
-      after_transition to: :draft, do: [:after_draft, :send_product_drafted_webhook]
+      ActiveJob.perform_all_later(auto_match_collections_jobs)
     end
 
-    def self.bulk_auto_match_taxons(store, product_ids)
-      return if store.taxons.automatic.none?
-
-      products_to_auto_match_ids = store.products.not_deleted.not_archived.where(id: product_ids).ids
+    # The variant this product leads with: its price, its stock, and what the
+    # add-to-cart button buys. On a product only the operator sells this is
+    # simply the cheapest available variant; once sellers share the listing it
+    # is whichever of their offers wins the buy box.
+    #
+    # Computed per read and never stored — it turns on price, stock and who is
+    # currently selling, none of which hold still
+    # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 11).
+    #
+    # @param currency [String, nil]
+    # @param option_value_ids [Array<String, Integer>, nil] narrows to one option
+    #   combination, so a `Condition` option gives a new buy box and a used one
+    # @return [Spree::Variant, nil]
+    def buy_box_variant(currency: nil, option_value_ids: nil)
+      currency ||= Spree::Current.currency
+      key = [currency, option_value_ids]
+      @buy_box_variants ||= {}
+      return @buy_box_variants[key] if @buy_box_variants.key?(key)
 
-      auto_match_taxons_jobs = products_to_auto_match_ids.map do |product_id|
-        Spree::Products::AutoMatchTaxonsJob.new(product_id).tap { |job| job.scheduled_at = 30.seconds.from_now }
-      end
+      @buy_box_variants[key] = Spree::Dependencies.product_buy_box_service.constantize.call(
+        product: self, currency: currency, option_value_ids: option_value_ids
+      ).value
+    end
 
-      ActiveJob.perform_all_later(auto_match_taxons_jobs)
+    # The variant this product leads with in a currency: the buy-box winner,
+    # else the default. One definition, because a caller that prices a page and
+    # a caller that preloads for it must land on the same variant — otherwise
+    # the preload misses and every row falls back to a query of its own.
+    #
+    # @param currency [String, nil]
+    # @return [Spree::Variant, nil]
+    def featured_variant(currency: nil)
+      buy_box_variant(currency: currency) || default_variant
     end
 
-    # Can't use short form block syntax due to https://github.com/Netflix/fast_jsonapi/issues/259
+    # Availability asks whether *anyone who is selling today* has this on the
+    # shelf. It deliberately does not ask the buy box: the winner is picked
+    # by price in one currency, and stock is a fact about the shelf, not about
+    # pricing — a variant stocked but priced only in another currency is still
+    # in stock. What it does share with the buy box is the seller test: a
+    # variant from a seller who is suspended, still onboarding or away is not
+    # for sale, so it cannot make the product available.
     def purchasable?
-      @purchasable ||= default_variant.purchasable? || variants.any?(&:purchasable?)
+      return @purchasable unless @purchasable.nil?
+
+      @purchasable = sellable_variants.any?(&:purchasable?)
     end
 
-    # Can't use short form block syntax due to https://github.com/Netflix/fast_jsonapi/issues/259
     def in_stock?
-      @in_stock ||= default_variant.in_stock? || variants.any?(&:in_stock?)
-    end
+      return @in_stock unless @in_stock.nil?
 
-    # Can't use short form block syntax due to https://github.com/Netflix/fast_jsonapi/issues/259
-    def backorderable?
-      default_variant.backorderable? || variants.any?(&:backorderable?)
+      @in_stock = sellable_variants.any?(&:in_stock?)
     end
 
-    def on_sale?(currency)
-      prices_including_master.find_all { |p| p.currency == currency }.any?(&:discounted?)
+    def backorderable?
+      sellable_variants.any?(&:backorderable?)
     end
 
-    def find_or_build_master
-      master || build_master
+    # The variants a shopper could actually buy from: every one whose seller
+    # is selling today, first-party included. Reads the loaded association so
+    # a serialized list resolves it from variants it already holds.
+    #
+    # @return [Array<Spree::Variant>]
+    def sellable_variants
+      variants.select do |variant|
+        seller = variant.resolved_seller
+        seller.nil? || seller.sellable?
+      end
     end
 
-    # Checks if product has variants (non-master variants)
-    # Uses variant_count counter cache for performance
-    # @return [Boolean]
-    def has_variants?
-      return variants.size.positive? if variants.loaded?
-
-      variant_count.positive?
+    def on_sale?(currency)
+      prices.find_all { |p| p.currency == currency && p.non_zero? }.any?(&:discounted?)
     end
 
-    # Returns default Variant for Product
-    # If `track_inventory_levels` is enabled it will try to find the first Variant
-    # in stock or backorderable, if there's none it will return first Variant sorted
-    # by `position` attribute
-    # If `track_inventory_levels` is disabled it will return first Variant sorted
-    # by `position` attribute
-    #
+    # The default variant is a persisted FK, but before the product is saved (or
+    # if it somehow has no default set) fall back to the first variant —
+    # including one built in memory via the delegated setters.
     # @return [Spree::Variant]
     def default_variant
-      @default_variant ||= if Spree::Config[:track_inventory_levels] && has_variants? && available_variant = variants.detect(&:purchasable?)
-                             available_variant
-                           else
-                             has_variants? ? variants.first : find_or_build_master
-                           end
+      super || variants.first
+    end
+
+    def find_or_build_default_variant
+      default_variant || variants.build
     end
 
-    # Returns default Variant ID for Product
-    # @return [Integer]
-    def default_variant_id
-      @default_variant_id ||= default_variant.id
+    # "Does this product have more than one variant (i.e. options to choose from)?"
+    # Uses the variant_count counter cache for performance.
+    # @return [Boolean]
+    def has_multiple_variants?
+      return variants.size > 1 if variants.loaded?
+
+      variant_count > 1
     end
+    # @deprecated Use #has_multiple_variants? — will be removed in Spree 6.1.
+    alias has_variants? has_multiple_variants?
 
     # Returns the product's media gallery.
     # Uses product-level media if present, otherwise falls back to variant images.
@@ -419,34 +549,19 @@ module Spree
     alias has_variant_images? has_media?
 
     # Returns the variant that should be used for displaying images.
-    # Priority: master > default_variant > first variant with images
+    # Priority: default_variant > first variant with images
     # @return [Spree::Variant, nil]
     def variant_for_images
       @variant_for_images ||= find_variant_for_images
     end
 
-    # @deprecated Use #primary_media instead.
-    def default_image
-      Spree::Deprecation.warn('Spree::Product#default_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')
-      primary_media
-    end
-
-    # @deprecated Use #primary_media instead.
-    def featured_image
-      Spree::Deprecation.warn('Spree::Product#featured_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')
-      primary_media
-    end
-
-    # @deprecated Use #primary_media instead.
-    def primary_image
-      Spree::Deprecation.warn('Spree::Product#primary_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')
-      primary_media
-    end
-
-    # Returns secondary media for Product (for hover effects).
-    # @return [Spree::Asset, nil]
+    # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+    #   Spree calls this — a hover image is a storefront presentation choice,
+    #   not something core should name.
+    # @return [Spree::Media, nil]
     def secondary_image
-      variant_for_images&.secondary_image
+      Spree::Deprecation.warn('Spree::Product#secondary_image is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+      gallery_media.second
     end
 
     # @deprecated Use media_count instead
@@ -458,7 +573,14 @@ module Spree
     # Checks product-level media first, then falls back to variant images.
     # Called when media is added, removed, or reordered.
     def update_thumbnail!
-      first_media = media.order(:position).first || variant_images.order(:position).first
+      # Fresh scopes, never the cached associations — this runs from a media
+      # row's after_commit, where a loaded association is missing its siblings.
+      candidates = media.reload.order(:position).presence || variant_images.reload.order(:position)
+      # Only media that can draw as an image: `thumbnail_url` is rendered in an
+      # <img> everywhere it's used, so a video with no still leaves no
+      # thumbnail at all rather than a broken one.
+      first_media = candidates.find(&:renderable_as_image?)
+
       update_column(:primary_media_id, first_media&.id)
     end
 
@@ -479,12 +601,9 @@ module Spree
     # Returns tax category for Product
     # @return [Spree::TaxCategory, nil]
     def tax_category
-      @tax_category ||= super || TaxCategory.default
+      @tax_category ||= super || TaxCategory.default(assignable_store)
     end
 
-    # Adding properties and option types on creation based on a chosen prototype
-    attr_accessor :prototype_id
-
     def first_or_default_variant(currency)
       if !has_variants?
         default_variant
@@ -495,38 +614,50 @@ module Spree
       end
     end
 
+    # The first variant a shopper can actually buy, in this currency.
+    #
+    # Position order, deliberately — this is "the first one that works", not
+    # the buy box's ranked winner. What it does borrow from the buy box is the
+    # seller check: a variant from a seller who is suspended, still onboarding
+    # or away is not for sale, so it cannot be what the product displays.
     def first_available_variant(currency)
-      variants.find { |v| v.purchasable? && v.price_in(currency).amount.present? }
+      sellable_variants.find do |variant|
+        variant.purchasable? && variant.price_in(currency).amount.present?
+      end
     end
 
+    # Whether the shop price differs between this product's variants. Reads
+    # base prices only: a price list's rows are what one audience pays under an
+    # agreement, and a ladder holds several rows for one variant, so counting
+    # them would report a product as varying when it does not
+    # (docs/plans/6.0-volume-pricing.md).
     def price_varies?(currency)
-      prices_including_master.find_all { |p| p.currency == currency && p.amount.present? }.map(&:amount).uniq.count > 1
+      shop_prices(currency).map(&:amount).uniq.count > 1
     end
 
     def any_variant_available?(currency)
-      if has_variants?
-        first_available_variant(currency).present?
-      else
-        master.purchasable? && master.price_in(currency).amount.present?
-      end
+      first_available_variant(currency).present?
     end
 
     # returns the lowest price for the product in the given currency
-    # prices_including_master are usually already loaded, so this should not trigger an extra query
+    # prices are usually already loaded, so this should not trigger an extra query
     def lowest_price(currency)
-      prices_including_master.find_all { |p| p.currency == currency }.min_by(&:amount)
+      shop_prices(currency).min_by(&:amount)
     end
 
-    # Ensures option_types and product_option_types exist for keys in option_values_hash
-    def ensure_option_types_exist_for_values_hash
-      return if option_values_hash.nil?
-
-      # we need to convert the keys to string to make it work with UUIDs
-      required_option_type_ids = option_values_hash.keys.map(&:to_s)
-      missing_option_type_ids = required_option_type_ids - option_type_ids.map(&:to_s)
-      missing_option_type_ids.each do |id|
-        product_option_types.create(option_type_id: id)
-      end
+    # The prices this product is offered at publicly — one per variant. A price
+    # list's rows are excluded: they are what one audience pays under an
+    # agreement, so surfacing the cheapest of them as the product's "from"
+    # price would quote every shopper a contract they are not party to.
+    #
+    # Filtered in memory rather than through a scope because callers have
+    # already loaded the association, and a scope would re-query per product
+    # in a listing.
+    #
+    # @param currency [String]
+    # @return [Array<Spree::Price>]
+    def shop_prices(currency)
+      prices.find_all { |p| p.currency == currency && p.price_list_id.nil? && p.non_zero? }
     end
 
     # for adding products which are closely related to existing ones
@@ -572,21 +703,14 @@ module Spree
       !!discontinue_on && discontinue_on <= Time.current
     end
 
-    # determine if any variant (including master) can be supplied
+    # determine if any variant can be supplied
     def can_supply?
-      variants_including_master.any?(&:can_supply?)
+      variants.any?(&:can_supply?)
     end
 
-    # determine if any variant (including master) is out of stock and backorderable
+    # determine if any variant is out of stock and backorderable
     def backordered?
-      variants_including_master.any?(&:backordered?)
-    end
-
-    def self.like_any(fields, values)
-      conditions = fields.product(values).map do |(field, value)|
-        arel_table[field].matches("%#{value}%")
-      end
-      where conditions.inject(:or)
+      variants.any?(&:backordered?)
     end
 
     # Suitable for displaying only variants that has at least one option value.
@@ -602,78 +726,91 @@ module Spree
       @total_on_hand ||= if any_variants_not_track_inventory?
                            BigDecimal::INFINITY
                          else
-                           if variants_including_master.loaded?
-                             variants_including_master.sum(&:total_on_hand)
+                           if variants.loaded?
+                             variants.sum(&:total_on_hand)
                            else
-                             stock_items.loaded? ? stock_items.sum(&:count_on_hand) : stock_items.sum(:count_on_hand)
+                             stock_levels.loaded? ? stock_levels.sum(&:available_count) : stock_levels.sum('count_on_hand - allocated_count')
                            end
                          end
     end
 
-    # Master variant may be deleted (i.e. when the product is deleted)
-    # which would make AR's default finder return nil.
-    # This is a stopgap for that little problem.
+    # @deprecated Use {#stock_levels}; removed in 6.1.
+    def stock_items
+      Spree::Deprecation.warn('Spree::Product#stock_items is deprecated and will be removed in Spree 6.1. Use #stock_levels instead.')
+      stock_levels
+    end
+
+    # @deprecated Use #default_variant — the master variant is being removed in Spree 6.1.
     def master
-      super || variants_including_master.with_deleted.find_by(is_master: true)
-    end
-
-    # Returns the brand taxon for the product
-    # @return [Spree::Taxon]
-    def brand_taxon
-      @brand_taxon ||= if classification_count.zero?
-                         nil
-                       elsif Spree.use_translations?
-                         taxons.joins(:taxonomy).
-                           join_translation_table(Taxonomy).
-                           find_by(Taxonomy.translation_table_alias => { name: Spree.t(:taxonomy_brands_name) })
-                       elsif taxons.loaded?
-                         taxons.find { |taxon| taxon.taxonomy.name == Spree.t(:taxonomy_brands_name) }
-                       else
-                         taxons.joins(:taxonomy).find_by(Taxonomy.table_name => { name: Spree.t(:taxonomy_brands_name) })
-                       end
-    end
-
-    # Returns the brand name for the product
-    # @return [String]
-    def brand_name
-      brand_taxon&.name
+      Spree::Deprecation.warn('Spree::Product#master is deprecated and will be removed in Spree 6.1. Use #default_variant instead.')
+      default_variant
     end
 
-    def main_taxon
-      return if classification_count.zero?
+    # @deprecated Use #variants — will be removed in Spree 6.1.
+    def variants_including_master
+      Spree::Deprecation.warn('Spree::Product#variants_including_master is deprecated and will be removed in Spree 6.1. Use #variants instead.')
+      variants
+    end
 
-      @main_taxon ||= taxons.first
+    # @deprecated Use #default_variant_id — will be removed in Spree 6.1.
+    def master_id
+      default_variant_id
     end
 
-    def taxons_for_store(store)
-      return if classification_count.zero?
+    # The product's primary category — the first manually-assigned category.
+    # Renamed from #main_taxon in 6.0.
+    def primary_category
+      return if categories_count.zero?
+
+      @primary_category ||= categories.first
+    end
 
-      taxons.loaded? ? taxons.find_all { |taxon| taxon.taxonomy.store_id == store.id } : taxons.for_store(store)
+    # @deprecated Use {#primary_category}.
+    def main_taxon
+      Spree::Deprecation.warn('Spree::Product#main_taxon is deprecated and will be removed in Spree 6.1. Use #primary_category instead.')
+      primary_category
     end
 
     def any_variant_in_stock_or_backorderable?
       if has_variants?
-        variants_including_master.in_stock_or_backorderable.exists?
+        variants.in_stock_or_backorderable.not_discontinued.exists?
       else
-        master.in_stock_or_backorderable?
+        default_variant.in_stock_or_backorderable?
       end
     end
 
     # Check if the product is digital by checking if any of its shipping methods are digital delivery
     # This is used to determine if the product is digital and should have a digital delivery price
-    # instead of a physical shipping price
+    # instead of a physical shipping price. The profile kind declares it —
+    # capabilities are never stated twice.
     #
     # @return [Boolean]
     def digital?
-      @digital ||= shipping_category&.includes_digital_shipping_method?
+      # Memoized via nil-check: MemoizedData resets caches by assigning nil.
+      return @digital unless @digital.nil?
+
+      @digital = !!resolved_delivery_profile&.digital?
     end
 
-    def auto_match_taxons
+    # The profile that governs this product. The association is required for
+    # new records; the store-default fallback covers rows predating the
+    # backfill (never expected in practice, cheap to be safe about).
+    #
+    # @return [Spree::DeliveryProfile, nil]
+    def resolved_delivery_profile
+      # Memoized via nil-check, like +digital?+ above: the store-default branch
+      # is an uncached lookup, and every variant on the product asks.
+      return @resolved_delivery_profile unless @resolved_delivery_profile.nil?
+
+      @resolved_delivery_profile = delivery_profile || (store && Spree::DeliveryProfile.default_for(store))
+    end
+
+    def auto_match_collections
       return if deleted?
       return if archived?
-      return if store.nil? || store.taxons.automatic.none?
+      return if store.nil? || store.collections.automatic.none?
 
-      Spree::Products::AutoMatchTaxonsJob.set(wait: 30.seconds).perform_later(id)
+      Spree::Products::AutoMatchCollectionsJob.set(wait: 30.seconds).perform_later(id)
     end
 
     def to_csv(store = nil)
@@ -688,21 +825,22 @@ module Spree
                            else
                              []
                            end
-      metafields_for_csv ||= Spree::MetafieldDefinition.for_resource_type('Spree::Product').order(:namespace, :key).map do |mf_def|
-        metafields.find { |mf| mf.metafield_definition_id == mf_def.id }&.csv_value
-      end
-      taxons_for_csv ||= taxons.manual.reorder(depth: :desc).first(3).pluck(:pretty_name)
-      taxons_for_csv.fill(nil, taxons_for_csv.size...3)
+      # Through the shared helper so the value row is built from exactly the
+      # definitions, in exactly the order, that Export#custom_fields_headers
+      # used for the header row — a mismatch shifts every value column.
+      custom_field_values = custom_fields_for_csv(self, store)
+      categories_for_csv ||= categories.reorder(depth: :desc).first(3).pluck(:pretty_name)
+      categories_for_csv.fill(nil, categories_for_csv.size...3)
 
       csv_lines = []
-      all_variants = has_variants? ? variants_including_master.to_a : [master]
+      all_variants = variants.to_a
       default_currency = store.default_currency
       additional_currencies = store.supported_currencies_list.map(&:iso_code) - [default_currency]
 
       # Primary rows in the store's default currency
       all_variants.each_with_index do |variant, index|
-        csv_lines << Spree::CSV::ProductVariantPresenter.new(self, variant, index, properties_for_csv, taxons_for_csv, store,
-                                                             metafields_for_csv).call
+        csv_lines << Spree::CSV::ProductVariantPresenter.new(self, variant, index, properties_for_csv, categories_for_csv, store,
+                                                             custom_field_values).call
       end
 
       # Price-only rows for each additional currency
@@ -732,257 +870,118 @@ module Spree
     private
 
     # Determines which variant should be used for displaying media.
-    # Priority: master > default_variant > first variant with media
+    # Priority: default_variant > first variant with media
     def find_variant_for_images
-      return master if master.has_media?
-      return default_variant if has_variants? && default_variant.has_media?
+      return default_variant if default_variant&.has_media?
       return find_variant_with_images if has_media?
 
       nil
     end
 
-    def pending_variants?
-      @pending_variants_params.present?
-    end
-
-    def apply_pending_variants
-      return unless @pending_variants_params
-
-      apply_variants(@pending_variants_params)
-      @pending_variants_params = nil
-    end
-
-    def pending_media?
-      @pending_media_params.present?
-    end
+    # Additive, unlike the legacy prototype callback which replaced both sets —
+    # the type seeds the product when attached (creation, later assignment,
+    # reassignment) and never removes anything; detaching seeds nothing.
+    # The already-linked sets come from the join tables in one query each: the
+    # cached associations can be stale here (pending variants insert option-type
+    # joins through product_option_types within the same save).
+    def sync_associations_from_product_type
+      return unless product_type
 
-    def apply_pending_media
-      return unless @pending_media_params
+      missing_option_type_ids = product_type.option_type_ids - product_option_types.pluck(:option_type_id)
+      Spree::OptionType.where(id: missing_option_type_ids).each { |option_type| option_types << option_type }
 
-      apply_media(@pending_media_params)
-      @pending_media_params = nil
-    end
-
-    def apply_media(media_params)
-      # Eager-load Asset descendants once so the type allowlist is stable across
-      # the loop (and across requests once subclasses are referenced). Computed
-      # per-call rather than at class-load to avoid forcing autoload of every
-      # Asset subclass during boot.
-      allowed_types = [Spree::Asset, *Spree::Asset.descendants].map(&:name).to_set
-      media_params.each do |raw|
-        attrs = raw.respond_to?(:to_h) ? raw.to_h : raw
-        attrs = attrs.with_indifferent_access
-
-        # Upsert path: entries with an `id` patch an existing asset (alt,
-        # position, variant_ids). Entries with a `signed_id` create+attach.
-        # Omitting an entry leaves it alone — explicit DELETE on the dedicated
-        # media endpoint is still the only way to remove an asset.
-        asset_id = attrs.delete(:id)
-        if asset_id.present?
-          asset = media.find_by_param(asset_id) || next
-          asset.update!(attrs.except(:signed_id, :type))
-          next
-        end
-
-        signed_id = attrs.delete(:signed_id)
-        next if signed_id.blank?
-
-        media_type = attrs.delete(:type) || 'Spree::Image'
-        next unless allowed_types.include?(media_type)
-
-        asset = media.build(attrs.except(:id))
-        asset.type = media_type
-        asset.attachment.attach(signed_id)
-        asset.save!
-      end
-    end
-
-    def apply_variants(variants_params)
-      variant_ids_in_payload = []
-      master_touched = false
-      mutated = false
-
-      variants_params.each do |variant_data|
-        variant_data = variant_data.to_h.with_indifferent_access
-        variant_id = variant_data.delete(:id)
-        options = variant_data[:options]
-
-        if variant_id.present?
-          variant = variants_including_master.find_by_param!(variant_id)
-          variant.update!(variant_data)
-          variant_ids_in_payload << variant.id
-          mutated = true
-        elsif options.blank? || (options.is_a?(Array) && options.empty?)
-          # An entry with no options addresses the master variant. Building a
-          # non-master here would create a phantom duplicate (the auto-built
-          # master already exists, and `variants` excludes it). Upsert onto
-          # the master instead — the merchant-visible "default variant" on a
-          # simple product IS the master.
-          variant_data = variant_data.except(:options)
-          target = find_or_build_master
-          target.assign_attributes(variant_data)
-          target.save!
-          master_touched = true
-          mutated = true
-        else
-          variant = variants.build
-          variant.assign_attributes(variant_data)
-          variant.save!
-          variant_ids_in_payload << variant.id
-          mutated = true
-        end
-      end
-
-      # Remove variants not in the payload (only non-master). If only the
-      # master was touched (simple product), leave existing non-master
-      # variants alone — the payload is partial, not a full replacement.
-      if variant_ids_in_payload.any? && !master_touched
-        removed = variants.where.not(id: variant_ids_in_payload).destroy_all
-        mutated ||= removed.any?
-      end
-
-      sync_variant_state! if mutated
-    end
-
-    # Re-syncs the in-memory derived variant state after `apply_variants`
-    # mutates variants out-of-band (the variant counter is bumped via
-    # `Spree::Product.increment_counter` in a Variant callback, and
-    # `default_variant` is memoized). Without this, a freshly built/updated
-    # product serialized in the same request returns a stale `variant_count`
-    # and a stale `price` (delegated to the memoized `default_variant`).
-    #
-    # The `default_variant` memo reset here changes shape once master is
-    # removed (it becomes a `belongs_to` FK). See
-    # docs/plans/6.0-remove-master-variant.md (Phase 3).
-    # @return [void]
-    def sync_variant_state!
-      # `variant_count` is maintained by a direct counter update in a Variant
-      # callback, so the in-memory attribute is stale here — re-read it from the
-      # row without reloading the whole record.
-      self[:variant_count] = self.class.where(id: id).pick(:variant_count)
-      variants.reset
-      @default_variant = nil
-      @default_variant_id = nil
-    end
-
-    def add_associations_from_prototype
-      if prototype_id && prototype = Spree::Prototype.find_by(id: prototype_id)
-        self.option_types = prototype.option_types
-        self.taxons = prototype.taxons
-      end
+      # Scoped to the product's own store, matching `category_ids=`: a type
+      # pointing at another store's category must not drag it onto the product.
+      missing_category_ids = product_type.category_ids - product_categories.pluck(:category_id)
+      Spree::Category.for_store(assignable_store).where(id: missing_category_ids).
+        each { |category| categories << category }
     end
 
     def any_variants_not_track_inventory?
-      return true unless Spree::Config.track_inventory_levels
+      return true unless store_preference(:track_inventory_levels)
 
-      if variants_including_master.loaded?
-        variants_including_master.any? { |v| !v.track_inventory? }
+      if variants.loaded?
+        variants.any? { |v| !v.track_inventory? }
       else
-        variants_including_master.where(track_inventory: false).exists?
+        variants.where(track_inventory: false).exists?
       end
     end
 
-    # Builds variants from a hash of option types & values
-    def build_variants_from_option_values_hash
-      Spree::Deprecation.warn('Spree::Product#build_variants_from_option_values_hash is deprecated and will be removed in Spree 6.0.')
-      ensure_option_types_exist_for_values_hash
-      values = option_values_hash.values
-      values = values.inject(values.shift) { |memo, value| memo.product(value).map(&:flatten) }
-
-      default_currency = store&.default_currency || Spree::Store.default.default_currency
-      master_price = master.price_in(default_currency).amount
-
-      values.each do |ids|
-        variant = variants.create!(option_value_ids: ids)
-        variant.set_price(default_currency, master_price) if master_price.present?
-      end
-      save
+    # Every product must have at least one variant. If none was built via the
+    # delegated setters or supplied as nested attributes, create an empty one.
+    def ensure_default_variant
+      variants.create! if variants.empty?
     end
 
-    def ensure_master
-      return unless new_record?
+    def set_default_variant
+      return if default_variant_id.present?
 
-      self.master ||= build_master
+      first_variant = preferred_default_variant
+      update_column(:default_variant_id, first_variant.id) if first_variant
     end
 
-    def assign_default_tax_category
-      self.tax_category = Spree::TaxCategory.default if new_record? && self[:tax_category_id].blank?
-    end
+    # Re-point the default variant when the current one has been removed. Sticky
+    # otherwise — an in-stock change never re-points (see the plan's open question).
+    def auto_promote_default_variant
+      current = association(:default_variant).reader
+      return if current && current.deleted_at.nil?
 
-    def anything_changed?
-      saved_changes? || @nested_changes
+      next_variant = preferred_default_variant(reload: true)
+      update_column(:default_variant_id, next_variant&.id) if next_variant && next_variant.id != default_variant_id
     end
 
-    def reset_nested_changes
-      @nested_changes = false
+    # The product's public identity — its headline price, its SKU, and the
+    # Omnibus `prior_price`, which is a compliance claim about this shop's own
+    # pricing history. Where the operator sells the item themselves that is the
+    # listing that should speak for the product, not whichever seller happens
+    # to sort first.
+    def preferred_default_variant(reload: false)
+      candidates = reload ? variants.reload : variants
+      candidates.detect { |variant| variant.resolved_seller_id.nil? } || candidates.first
     end
 
-    def master_updated?
-      master && (
-        master.new_record? ||
-        master.changed? ||
-        (
-          Spree::Config.enable_legacy_default_price &&
-          master.default_price &&
-          (
-            master.default_price.new_record? ||
-            master.default_price.changed?
-          )
-        )
-      )
+    def assign_default_tax_category
+      self.tax_category = Spree::TaxCategory.default(assignable_store) if new_record? && self[:tax_category_id].blank?
     end
 
-    # there's a weird quirk with the delegate stuff that does not automatically save the delegate object
-    # when saving so we force a save using a hook
-    # Fix for issue #5306
-    def save_master
-      if master_updated?
-        master.save!
-        @nested_changes = true
-      end
-    end
+    def stamp_template_delivery_profile
+      return if delivery_profile_id.present?
 
-    # If the master cannot be saved, the Product object will get its errors
-    # and will be destroyed
-    def validate_master
-      if Spree::Config.enable_legacy_default_price
-        # We call master.default_price here to ensure price is initialized.
-        # Required to avoid Variant#check_price validation failing on create.
-        master.default_price
-      end
+      self.delivery_profile_id = product_type&.delivery_profile_id ||
+        (store && Spree::DeliveryProfile.default_for(store)&.id)
+    end
 
-      unless master.valid?
-        master.errors.map { |error| { field: error.attribute, message: error&.message } }.each do |err|
-          next if err[:field].blank? || err[:message].blank?
+    def delivery_profile_must_belong_to_store
+      return if delivery_profile.nil? || store.nil?
+      return if delivery_profile.store_id == store_id
 
-          errors.add(err[:field], err[:message])
-        end
-      end
+      errors.add(:delivery_profile, :invalid)
     end
 
-    def ensure_default_shipping_category
-      return if shipping_category.present?
+    # A seller from another store would put one store's catalog inside another
+    # store's seller — and every seller-scoped read is rooted in exactly that
+    # association.
+    def seller_must_belong_to_store
+      return if seller.nil? || store.nil?
+      return if seller.store_id == store_id
 
-      if new_record?
-        name = I18n.t('spree.seed.shipping.categories.default')
-        self.shipping_category = Spree::ShippingCategory.find_or_create_by!(name: name)
-      end
+      errors.add(:seller, :invalid)
     end
 
     def run_touch_callbacks
       run_callbacks(:touch)
     end
 
-    def taxon_and_ancestors
-      @taxon_and_ancestors ||= taxons.map(&:self_and_ancestors).flatten.uniq
+    def category_and_ancestors
+      @category_and_ancestors ||= categories.map(&:self_and_ancestors).flatten.uniq
     end
 
-    # Iterate through this products taxons and taxonomies and touch their timestamps in a batch
-    def touch_taxons
-      if taxons.any?
-        Spree::Products::TouchTaxonsJob.
+    # Iterate through this product's categories and touch their timestamps in a batch
+    def touch_categories
+      if categories.any?
+        Spree::Products::TouchCategoriesJob.
           set(wait: 5.seconds).
-          perform_later(taxon_and_ancestors.map(&:id), taxonomy_ids.uniq)
+          perform_later(category_and_ancestors.map(&:id))
       end
     end
 
@@ -993,48 +992,33 @@ module Spree
       end
     end
 
-    def remove_taxon(taxon)
-      removed_classifications = classifications.where(taxon: taxon)
-      removed_classifications.each(&:remove_from_list)
+    def remove_category(category)
+      removed_product_categories = product_categories.where(category: category)
+      removed_product_categories.each(&:remove_from_list)
     end
 
     def discontinue_on_must_be_later_than_make_active_at
-      Spree::Deprecation.warn('Spree::Product#discontinue_on_must_be_later_than_make_active_at is deprecated and will be removed in Spree 6.0.')
       if discontinue_on < make_active_at
         errors.add(:discontinue_on, :invalid_date_range)
       end
     end
 
-    def requires_price?
-      Spree::Config[:require_master_price]
-    end
+    # Mirrors the machine's bang events: an illegal move raised.
+    def run_status_workflow(workflow)
+      result = workflow.call(product: self)
+
+      if result.failure?
+        # ResultError#to_s unwraps an ActiveModel::Errors into its full
+        # messages; its `value` would inspect the object into the message.
+        errors.add(:base, result.error.to_s)
+        raise ActiveRecord::RecordInvalid, self
+      end
 
-    def requires_shipping_category?
       true
     end
 
-    def eligible_for_taxon_matching?
+    def eligible_for_collection_matching?
       previously_new_record? || tag_list_previously_changed? || available_on_previously_changed?
     end
-
-    def after_activate
-      # Implement your logic here
-    end
-
-    def after_archive
-      # Implement your logic here
-    end
-
-    def after_draft
-      # Implement your logic here
-    end
-
-    def publish_product_activated_event
-      publish_event('product.activated')
-    end
-
-    def publish_product_archived_event
-      publish_event('product.archived')
-    end
   end
 end