spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/base.rb

@@ -6,11 +6,33 @@ class Spree::Base < ApplicationRecord
   include Spree::IntegrationsConcern
   include Spree::Publishable
   include Spree::PrefixedId
+  include Spree::HasNumber
+  include Spree::HasIsoGeography
   include Spree::TypedAssociations
-
+  include Spree::ValidatesStoreUniqueness
+
+  # Extra writable attributes contributed by extensions, appended to the v3
+  # controller allowlist for this resource. Core attributes belong in the
+  # controller's own list — this exists so an extension that adds a column can
+  # make it writable without decorating a controller:
+  #
+  #   Spree::Product.additional_permitted_attributes += [:brand_id]
+  #
+  # Entries are `params.permit` fragments: bare symbols, or hashes for
+  # collections and nested structures (`{ region_ids: [] }`). Append with `+=`
+  # rather than assigning, so extensions don't clobber each other.
+  class_attribute :additional_permitted_attributes, instance_writer: false, default: [].freeze
+
+  # Backfills preferences added to the class after this row was last saved, so
+  # a reader never sees nil for a newly defined preference. Assigning
+  # unconditionally would dirty every record on load: `preferences` is a
+  # YAML-serialized Hash, so the dirty check compares the serialized string and
+  # the merge reorders keys even when nothing changed — which is enough to make
+  # `with_lock` refuse the record ("unpersisted changes").
   after_initialize do
     if has_attribute?(:preferences) && !preferences.nil?
-      self.preferences = default_preferences.merge(preferences)
+      missing = default_preferences.except(*preferences.keys)
+      self.preferences = preferences.merge(missing) if missing.any?
     end
   end
 
@@ -27,10 +49,6 @@ class Spree::Base < ApplicationRecord
     select("#{klass.table_name}.*").select(*(fields || klass::TRANSLATABLE_FIELDS))
   }
 
-  def self.belongs_to_required_by_default
-    false
-  end
-
   def self.for_store(store)
     plural_model_name = model_name.plural.gsub(/spree_/, '').to_sym
 
@@ -49,22 +67,21 @@ class Spree::Base < ApplicationRecord
     ApplicationRecord.try(:spree_base_uniqueness_scope) || []
   end
 
-  # FIXME: https://github.com/rails/rails/issues/40943
-  def self.has_many_inversing
-    false
-  end
-
   # this can overridden in subclasses to disallow deletion
   def can_be_deleted?
     true
   end
 
+  # @see Spree.mysql? — the single definition; this reads it so a model can
+  #   branch without reaching for the connection itself.
   def mysql_adapter?
-    ActiveRecord::Base.connection.adapter_name.downcase.include?('mysql')
+    Spree.mysql?
   end
 
   def self.json_api_columns
-    column_names.reject { |c| c.match(/_id$|id|preferences|(.*)password|(.*)token|(.*)api_key|^original_(.*)/) }
+    # `_type` goes with `_id`: the two halves of a polymorphic reference name
+    # an internal class, which is no more public than the key beside it.
+    column_names.reject { |c| c.match(/_id$|id|_type$|preferences|(.*)password|(.*)token|(.*)api_key|^original_(.*)/) }
   end
 
   def self.json_api_permitted_attributes
@@ -92,7 +109,96 @@ class Spree::Base < ApplicationRecord
     api_type
   end
 
+  # `.api_type` for an STI `type` column value, without instantiating the
+  # subclass — use this in serializers instead of `record.class.api_type`,
+  # which reports the *loaded* class and so returns the base type for a record
+  # read through the parent (a plain `Spree::Export` row, a factory that sets
+  # `type` as an attribute, a query on the base relation).
+  #
+  # Resolves against `available_types` where the class defines it, so an
+  # unrecognized column value passes through untouched rather than being
+  # constantized.
+  #
+  # @param type [String, nil] value of the STI `type` column
+  # @return [String]
+  def self.api_type_for(type)
+    return api_type if type.blank?
+
+    type = type.to_s
+    return type unless respond_to?(:available_types)
+
+    available_types.find { |klass| klass.to_s == type }&.api_type || type
+  end
+
+  # Shorthand for a *polymorphic* `*_type` column (`owner_type`,
+  # `viewable_type`, …), where the value names an arbitrary model rather than a
+  # subclass of the serialized one — so `api_type_for`'s registry lookup does
+  # not apply. Demodulizes and underscores the same way `api_type` does, giving
+  # `"Spree::Product"` => `"product"`.
+  #
+  # @param type [String, Class, nil] value of the polymorphic type column
+  # @return [String, nil]
+  def self.polymorphic_api_type(type)
+    return nil if type.blank?
+
+    type.to_s.demodulize.underscore
+  end
+
+  # Prefixed id for a polymorphic reference, encoded from the columns without
+  # loading the row.
+  #
+  # Reads both halves together so a type never appears beside a null id: the
+  # pair names something a client can link to, or neither does. Answers nil for
+  # a model without `has_prefix_id` — an extension may point a polymorphic
+  # column at one, and one such row must not 500 the whole list.
+  #
+  # @param type [String, nil] the polymorphic `*_type` column
+  # @param id [Integer, String, nil] the polymorphic `*_id` column
+  # @return [String, nil]
+  def self.polymorphic_prefixed_id(type, id)
+    return nil if type.blank? || id.blank?
+
+    type.to_s.safe_constantize.try(:prefixed_id_for, id)
+  end
+
+  # Reads the arguments of a two-state ransackable scope — one that answers a
+  # question with two named sides ("erased" / "not erased", "outstanding" /
+  # "spent") rather than narrowing to a value.
+  #
+  # Declare such a scope as `->(*values)`, never `->(value = true)`. Ransack
+  # calls one of three ways, and only a splat survives all of them:
+  #
+  # - a literal boolean `true` invokes the scope with NO arguments, which
+  #   means the affirmative side (this is why an empty list reads as `true`);
+  # - a single value arrives as that value;
+  # - an array predicate is SPLATTED, so a filter offering both sides passes
+  #   two arguments and a fixed-arity lambda raises ArgumentError — a 500 on a
+  #   request the merchant is entitled to make. Asking for every side is no
+  #   constraint at all, which is the `nil` below.
+  #
+  # The scope must also be listed in the model's
+  # `ransackable_scopes_skip_sanitize_args`, or Ransack casts `false` itself
+  # and then declines to apply the scope at all.
+  #
+  # @param values [Array<Object>] whatever Ransack passed through
+  # @return [Boolean, nil] the side asked for, or nil when every side was
+  def self.ransack_flag(*values)
+    # No argument is Ransack's shorthand for the affirmative side, not an
+    # absent filter: `q[erased]=true` reaches the scope with nothing at all.
+    return true if values.empty?
+
+    flags = Array(values).flatten.map { |value| ActiveModel::Type::Boolean.new.cast(value) }.uniq
+    # `size == 1`, not `one?`: the latter counts truthy elements, so a lone
+    # `false` would read as "no side chosen" and drop the filter.
+    return nil unless flags.size == 1
+
+    flags.first
+  end
+
+  # @deprecated Legacy Tom Select helper for the removed Rails admin. No replacement.
   def self.to_tom_select_json
+    Spree::Deprecation.warn('Spree::Base.to_tom_select_json is deprecated and will be removed in Spree 6.1.')
+
     pluck(:name, :id).map do |name, id|
       {
         id: id,

data/app/models/spree/base_analytics_event_handler.rb

@@ -24,7 +24,7 @@ module Spree
 
     # Handles the event
     # @param event_name [String] eg. 'order_completed'
-    # @param properties [Hash] eg. { product: Spree::Product, taxon: Spree::Taxon, query: String }
+    # @param properties [Hash] eg. { product: Spree::Product, taxon: Spree::Category, query: String }
     # rubocop:disable Lint/UnusedMethodArgument
     def handle_event(event_name, properties = {})
       raise NotImplementedError, 'Subclasses must implement the handle method'

data/app/models/spree/calculator/shipping/digital_delivery.rb

@@ -3,6 +3,8 @@ require_dependency 'spree/shipping_calculator'
 module Spree
   module Calculator::Shipping
     class DigitalDelivery < ShippingCalculator
+      include Spree::Calculator::CurrencyAmounts
+
       preference :amount, :decimal, default: 0
       preference :currency, :string, default: -> { Spree::Store.default.default_currency }
 
@@ -10,8 +12,9 @@ module Spree
         Spree.t('digital.digital_delivery')
       end
 
-      def compute_package(_package = nil)
-        preferred_amount
+      def compute_package(package = nil)
+        currency = package.respond_to?(:currency) ? package.currency : nil
+        currency ? amount_for(currency) : preferred_amount
       end
 
       def available?(package)

data/app/models/spree/calculator/shipping/flat_rate.rb

@@ -3,14 +3,19 @@ require_dependency 'spree/shipping_calculator'
 module Spree
   module Calculator::Shipping
     class FlatRate < ShippingCalculator
+      include Spree::Calculator::CurrencyAmounts
+
       preference :amount, :decimal, default: 0
+      # @deprecated Together with the single `amount`, superseded by the
+      #   per-currency `amounts` hash; kept as the fallback for its own
+      #   currency so upgraded stores quote unchanged.
       preference :currency, :string, default: -> { Spree::Store.default.default_currency }
 
-      preference :minimum_item_total, :decimal, default: nil, nullable: true
-      preference :maximum_item_total, :decimal, default: nil, nullable: true
+      preference :minimum_item_total, :decimal, default: nil, nullable: true, deprecated: 'Use a Spree::DeliveryMethodRules rule on the delivery method instead; removed in Spree 6.1.'
+      preference :maximum_item_total, :decimal, default: nil, nullable: true, deprecated: 'Use a Spree::DeliveryMethodRules rule on the delivery method instead; removed in Spree 6.1.'
 
-      preference :minimum_weight, :decimal, default: nil, nullable: true
-      preference :maximum_weight, :decimal, default: nil, nullable: true
+      preference :minimum_weight, :decimal, default: nil, nullable: true, deprecated: 'Use a Spree::DeliveryMethodRules rule on the delivery method instead; removed in Spree 6.1.'
+      preference :maximum_weight, :decimal, default: nil, nullable: true, deprecated: 'Use a Spree::DeliveryMethodRules rule on the delivery method instead; removed in Spree 6.1.'
 
       def self.description
         Spree.t(:shipping_flat_rate_per_order)
@@ -23,7 +28,7 @@ module Spree
         return nil if preferred_minimum_item_total.present? && preferred_minimum_item_total >= package.item_total
         return nil if preferred_maximum_item_total.present? && preferred_maximum_item_total < package.item_total
 
-        preferred_amount
+        amount_for(package.currency)
       end
     end
   end

data/app/models/spree/calculator/shipping/flexi_rate.rb

@@ -8,6 +8,12 @@ module Spree
       preference :max_items,       :integer, default: 0
       preference :currency,        :string,  default: -> { Spree::Store.default.default_currency }
 
+      # Single-currency amounts: quoting another currency would mislabel
+      # the configured numbers, so the method stays hidden there.
+      def supports_currency?(currency)
+        preferred_currency.blank? || preferred_currency.casecmp(currency.to_s).zero?
+      end
+
       def self.description
         Spree.t(:shipping_flexible_rate)
       end

data/app/models/spree/calculator/shipping/per_item.rb

@@ -3,6 +3,8 @@ require_dependency 'spree/shipping_calculator'
 module Spree
   module Calculator::Shipping
     class PerItem < ShippingCalculator
+      include Spree::Calculator::CurrencyAmounts
+
       preference :amount, :decimal, default: 0
       preference :currency, :string, default: -> { Spree::Store.default.default_currency }
 
@@ -11,11 +13,14 @@ module Spree
       end
 
       def compute_package(package)
-        compute_from_quantity(package.contents.sum(&:quantity))
+        compute_from_quantity(package.contents.sum(&:quantity), currency: package.currency)
       end
 
-      def compute_from_quantity(quantity)
-        preferred_amount * quantity
+      def compute_from_quantity(quantity, currency: nil)
+        per_item = currency ? amount_for(currency) : preferred_amount
+        return nil if per_item.nil?
+
+        per_item * quantity
       end
     end
   end

data/app/models/spree/calculator/shipping/price_sack.rb

@@ -8,6 +8,12 @@ module Spree
       preference :discount_amount, :decimal, default: 0
       preference :currency, :string, default: -> { Spree::Store.default.default_currency }
 
+      # Single-currency amounts: quoting another currency would mislabel
+      # the configured numbers, so the method stays hidden there.
+      def supports_currency?(currency)
+        preferred_currency.blank? || preferred_currency.casecmp(currency.to_s).zero?
+      end
+
       def self.description
         Spree.t(:shipping_price_sack)
       end

data/app/models/spree/calculator/tiered_flat_rate.rb

@@ -3,6 +3,7 @@ require_dependency 'spree/calculator'
 module Spree
   class Calculator::TieredFlatRate < Calculator
     preference :base_amount, :decimal, default: 0
+    preference :currency, :string, default: -> { Spree::Store.default.default_currency }
     preference :tiers, :hash, default: {}
 
     before_validation do
@@ -18,7 +19,10 @@ module Spree
       Spree.t(:tiered_flat_rate)
     end
 
-    def compute(object)
+    def compute(object = nil)
+      return 0 unless object&.currency.present?
+      return 0 unless preferred_currency.casecmp(object.currency.upcase).zero?
+
       base, amount = preferred_tiers.sort.reverse.detect { |b, _| object.amount >= b }
       amount || preferred_base_amount
     end

data/app/models/spree/calculator.rb

@@ -21,6 +21,16 @@ module Spree
       end
     end
 
+    # Fulfillment replaced Shipment in 6.0; calculators keep their historical
+    # compute_shipment extension point, so fulfillments dispatch to it.
+    def compute_fulfillment(fulfillment)
+      unless respond_to?(:compute_shipment)
+        raise NotImplementedError, "Please implement 'compute_shipment(shipment)' in your calculator: #{self.class.name}"
+      end
+
+      compute_shipment(fulfillment)
+    end
+
     # overwrite to provide description for your calculators
     def self.description
       'Base Calculator'

data/app/models/spree/cart.rb

@@ -0,0 +1,285 @@
+module Spree
+  # The pre-completion (shopping + checkout) phase of a purchase. Completing
+  # checkout copies a cart into an immutable {Spree::Order}; the cart is
+  # retained with +completed_at+ set. Carts have no status column —
+  # +completed_at+ is the only lifecycle marker.
+  class Cart < Spree.base_class
+    has_prefix_id :cart
+
+    # cart.created / cart.updated / cart.deleted — the abandonment-tooling
+    # signal (parity with 5.x, where incomplete orders emitted order.*).
+    # Payload serializes through the V3 cart serializer by convention.
+    publishes_lifecycle_events
+
+    has_secure_token
+
+    extend Spree::DisplayMoney
+
+    include Spree::SingleStoreResource
+    include Spree::Purchase::Channel
+    include Spree::Purchase::Company
+    include Spree::Purchase::Freight
+    include Spree::Purchase::QuantityRules
+    include Spree::Purchase::PurchaseOrder
+    include Spree::Purchase::Market
+    include Spree::Purchase::Currency
+    include Spree::Purchase::Locale
+    include Spree::Purchase::CheckoutSteps
+    include Spree::Purchase::DigitalItems
+    include Spree::Purchase::Taxation
+    include Spree::Purchase::StoreCredits
+    include Spree::Purchase::GiftCards
+    include Spree::Purchase::LineItemCurrencies
+    include Spree::Purchase::LineItemLookup
+    include Spree::Purchase::PaymentProcessing
+    include Spree::Purchase::Addresses
+    include Spree::Purchase::Validations
+    include Spree::Purchase::Totals
+    include Spree::Purchase::Lifecycle
+
+    # Concurrency is manual (the API's OrderLock semantics — compare
+    # client-sent version, 409 on mismatch); Rails auto-locking must not
+    # raise on internal saves.
+    self.lock_optimistically = false
+
+    # Single consolidated metadata JSON column (docs/plans/decisions.md
+    # 2026-03-16 "Consolidate metadata").
+    attribute :metadata, default: -> { {} }
+    attribute :accept_marketing, :boolean, default: false
+
+    # Transient warnings populated by remove_out_of_stock_items!
+    attribute :warnings, default: -> { [] }
+
+    money_methods :item_total, :adjustment_total, :included_tax_total, :additional_tax_total,
+                  :discount_total, :fee_total, :delivery_total, :total, :payment_total, :outstanding_balance,
+                  :tax_total, :pre_tax_item_amount, :pre_tax_total, :amount_due
+
+    alias display_promo_total display_discount_total
+    alias display_ship_total display_delivery_total
+    alias_attribute :ship_total, :delivery_total
+
+    belongs_to :customer, class_name: "::#{Spree.customer_class}", optional: true
+    # Order-parity aliases — shared Cart/Order code (services, Purchase
+    # concerns) reads #user; the cart column is customer_id.
+    alias_method :user, :customer
+    alias_method :user=, :customer=
+    alias_attribute :user_id, :customer_id
+    # Codes are stored stripped + lowercased so lookups stay case-insensitive;
+    # normalizes also applies to finder values.
+    normalizes :coupon_code, with: ->(code) { code.to_s.strip.downcase.presence }
+
+    # Pickup location choice, copied to the order at completion. Prefixed-ID
+    # resolution and the pickup-enabled rule live in Spree::Carts::Update,
+    # matching the Orders::Create twin.
+    belongs_to :preferred_stock_location, class_name: 'Spree::StockLocation', optional: true
+
+    has_many :line_items, -> { order(:created_at) }, class_name: 'Spree::LineItem', inverse_of: :cart, dependent: :destroy
+    has_many :variants, through: :line_items
+    has_many :products, through: :variants
+    has_many :tax_lines, class_name: 'Spree::TaxLine', dependent: :destroy, inverse_of: :cart
+    has_one :tax_identifier, class_name: 'Spree::TaxIdentifier', as: :owner,
+                             dependent: :destroy, inverse_of: :owner
+    has_many :discounts, class_name: 'Spree::Discount', dependent: :destroy, inverse_of: :cart
+    has_many :fees, class_name: 'Spree::Fee', dependent: :destroy, inverse_of: :cart
+    has_many :fulfillments, -> { order(:created_at, :id) }, class_name: 'Spree::Fulfillment', dependent: :destroy, inverse_of: :cart do
+      def states
+        pluck(:status).uniq
+      end
+    end
+    has_many :fulfillment_items, through: :fulfillments, class_name: 'Spree::FulfillmentItem'
+    has_many :order_promotions, class_name: 'Spree::OrderPromotion', inverse_of: :cart, dependent: :destroy
+    has_many :promotions, through: :order_promotions, class_name: 'Spree::Promotion'
+    has_many :payments, class_name: 'Spree::Payment', inverse_of: :cart, dependent: :destroy
+    has_many :payment_sessions, class_name: 'Spree::PaymentSession', inverse_of: :cart, dependent: :destroy
+    has_many :stock_reservations, class_name: 'Spree::StockReservation', inverse_of: :cart, dependent: :destroy
+    has_one :order, class_name: 'Spree::Order', inverse_of: :cart
+    # A cart spanning more than one seller completes into a group of orders
+    # instead of a single one — exactly one of these two is ever set.
+    has_one :order_group, class_name: 'Spree::OrderGroup', inverse_of: :cart
+
+    alias items line_items
+
+    scope :complete, -> { where.not(completed_at: nil) }
+    scope :incomplete, -> { where(completed_at: nil) }
+
+    # Shape only — email presence during checkout is a Checkout::Requirements
+    # concern, never a model validation (guest carts have no email).
+    validates :email, length: { maximum: 254, allow_blank: true }, email: { allow_blank: true }
+
+    self.whitelisted_ransackable_attributes = %w[email completed_at token updated_at]
+
+    before_update :ensure_updated_fulfillments, :homogenize_line_item_currencies, if: :currency_changed?
+
+    delegate :name, to: :customer, prefix: true, allow_nil: true
+
+    # @deprecated Store API bridge — carts have no order-style number; the
+    #   prefixed ID is the identifier. Removed from the API in 6.1.
+    # @return [String]
+    def number
+      prefixed_id
+    end
+
+    # Billed or shipped name, matching {Spree::Order#name}.
+    #
+    # @return [String, nil]
+    def name
+      if (address = bill_address || ship_address)
+        address.full_name
+      end
+    end
+
+    # A completed cart is an immutable audit record — post-checkout life
+    # belongs to the order. Blocks save/update_columns/touch/destroy at the
+    # model level; the completion write itself passes because it fires while
+    # the persisted completed_at is still nil.
+    def readonly?
+      super || (completed_at.present? && !completed_at_changed?)
+    end
+
+    # How long a completion attempt may hold the cart before its claim goes
+    # stale — a crashed completion must not brick its cart.
+    COMPLETING_CLAIM_TTL = 5.minutes
+
+    # @return [Boolean] whether a completion attempt currently holds this cart
+    def completing?
+      completing_at.present?
+    end
+
+    # Whether a live completion attempt holds this cart — its totals are fixed
+    # and money may be moving, so mutations must wait until it finishes or the
+    # claim goes stale.
+    #
+    # @return [Boolean]
+    def completion_claimed?
+      completing_at.present? && completing_at > COMPLETING_CLAIM_TTL.ago
+    end
+
+    # Recomputes and persists money totals (item, tax, promotion, delivery)
+    # and derived item counts. Convenience for
+    # {Spree::Carts::RecalculateTotals}.
+    def recalculate_totals!
+      Spree.cart_recalculate_totals_workflow.call(cart: self)
+    end
+
+    def outstanding_balance
+      total - payment_total
+    end
+
+    # Idempotent delivery-proposal rebuild — replaces the destructive
+    # order-side create_proposed_fulfillments. Open fulfillments are rebuilt from
+    # the current items/address; nothing here touches a completed cart.
+    def rebuild_fulfillments!
+      return if completed?
+
+      discounts.for_fulfillments.delete_all
+      tax_lines.for_fulfillments.delete_all
+      fees.for_fulfillments.delete_all
+
+      fulfillment_ids = fulfillments.map(&:id)
+      DeliveryRate.where(fulfillment_id: fulfillment_ids).delete_all
+      fulfillments.delete_all
+      fulfillment_items.reset
+
+      # Appended rather than assigned: setting `cart` on each proposal already
+      # files it under this cart's `fulfillments` (the association is
+      # inverse_of it), so a collection assignment sees the rows as already
+      # present, writes none of them, and the cart ends up with no proposals at
+      # all.
+      Spree::Stock::Coordinator.new(self).fulfillments.each do |fulfillment|
+        fulfillment.address_id = ship_address_id
+        fulfillment.order = nil
+        fulfillments << fulfillment
+      end
+      prune_undeliverable_fulfillments!
+      fulfillments.reload
+    end
+
+    # Drops proposals that found no delivery rates and surfaces a
+    # delivery_unavailable warning per affected line item (parity with the
+    # order-side ensure_available_delivery_rates).
+    def prune_undeliverable_fulfillments!
+      undeliverable = fulfillments.reload.select { |fulfillment| fulfillment.delivery_rates.empty? }
+      return if undeliverable.empty?
+
+      affected_line_items = undeliverable.flat_map(&:line_items).uniq
+      undeliverable.each(&:destroy)
+      self.warnings |= affected_line_items.map do |line_item|
+        {
+          code: 'delivery_unavailable',
+          message: Spree.t('cart_line_item.delivery_unavailable', li_name: line_item.name),
+          line_item_id: line_item.prefixed_id
+        }
+      end
+    end
+
+    def ensure_available_delivery_rates
+      if fulfillments.empty? || fulfillments.any? { |fulfillment| fulfillment.delivery_rates.blank? }
+        errors.add(:base, :items_cannot_be_shipped, message: Spree.t(:items_cannot_be_shipped))
+        return false
+      end
+      true
+    end
+
+    def set_fulfillments_cost
+      fulfillments.each(&:update_amounts)
+      self.delivery_total = fulfillments.reload.to_a.sum(&:cost)
+      update_columns(
+        delivery_total: delivery_total,
+        total: item_total + delivery_total + adjustment_total,
+        updated_at: Time.current
+      )
+    end
+    alias set_shipments_cost set_fulfillments_cost
+
+    def ensure_updated_fulfillments
+      rebuild_fulfillments! unless completed?
+    end
+
+    # Re-prices, re-taxes and rebuilds delivery proposals — the
+    # recalculation-on-write replacement for transition-triggered rebuilds.
+    # Called by Carts::Update after address/market changes.
+    def recalculate_for_address_change!
+      # One provider round for the whole cart, and persisted: a per-item loop
+      # would ask an external pricing system once per line, and nothing here
+      # saves the line items — rebuild_fulfillments! and recalculate_totals!
+      # reset the association cache and would drop assigned-but-unsaved
+      # figures.
+      # A strict store would rather refuse than reprice on a figure it cannot
+      # stand behind, so a pricing failure stops the recalculation instead of
+      # carrying on with stale prices and a rebuilt delivery quote around them.
+      result = Spree::Carts::PriceItems.new.call(cart: self, line_items: line_items.reload)
+      raise Spree::Pricing::PriceResolution::ProviderUnavailable, result.error.to_s if result.failure?
+
+      Spree::Carts::PriceItems.apply(result.value)
+      rebuild_fulfillments!
+      set_fulfillments_cost
+      recalculate_totals!
+    end
+
+    # Binds a signing-in customer to the cart through the swappable associate
+    # service, the same one Order#associate_customer! calls.
+    def associate_customer!(customer, override_email = true)
+      Spree.cart_associate_service.call(guest_cart: self, customer: customer, override_email: override_email)
+    end
+
+    # Merges another cart into this one through the swappable merge workflow
+    # (Spree::Dependencies.cart_merge_workflow).
+    def merge!(other_cart, customer = nil)
+      Spree.cart_merge_workflow.call(cart: self, other_cart: other_cart, customer: customer)
+      reload
+    end
+
+    # Removes out-of-stock/discontinued items and populates warnings
+    # (mirrors Order#remove_out_of_stock_items!).
+    def remove_out_of_stock_items!
+      existing_warnings = warnings
+      result = Spree::Carts::RemoveOutOfStockItems.call(cart: self)
+      return self unless result.success?
+
+      cart, _messages, new_warnings = result.value
+      cart.warnings = existing_warnings | (new_warnings || [])
+      cart
+    end
+
+  end
+end

data/app/models/spree/carts/item_warning.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Carts
+    # An item a batch upsert did not apply — vetoed by a :validate handler or
+    # unavailable in the cart's currency. The batch still succeeds, so this is
+    # how the caller learns which lines were dropped and why.
+    class ItemWarning
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :item_index, :integer
+      attribute :code, :string
+      attribute :message, :string
+      attr_accessor :variant
+
+      # Same shape as the out-of-stock warnings the cart already carries, so
+      # a client reads one warnings array rather than two vocabularies.
+      # item_index is the batch position, present only for batch upserts.
+      def to_h
+        {
+          code: code,
+          message: message,
+          variant_id: variant&.prefixed_id,
+          item_index: item_index
+        }.compact
+      end
+    end
+  end
+end

data/app/models/spree/carts/resolved_item.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Carts
+    # One entry of an upsert batch after its variant has been looked up:
+    # what Spree::Carts::UpsertItems validates and applies.
+    class ResolvedItem
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :quantity, :integer, default: 1
+      # price is tri-state: absent (price_provided false) leaves pricing to
+      # the resolver, an amount negotiates the line (price_source 'manual'),
+      # an explicit nil reverts a negotiated line to catalog pricing.
+      attribute :price_provided, :boolean, default: false
+      attr_accessor :variant, :metadata, :price
+
+      def metadata
+        @metadata ||= {}
+      end
+
+      # Zero (or less) is how a batch says "this line is gone", which is what
+      # lets one request carry edits and removals together.
+      def remove?
+        quantity <= 0
+      end
+
+      # @return [Boolean] the entry sets a negotiated unit price
+      def manual_price?
+        price_provided && !price.nil?
+      end
+
+      # @return [Boolean] the entry reverts a negotiated line to catalog pricing
+      def revert_price?
+        price_provided && price.nil?
+      end
+    end
+  end
+end