spree_core 5.4.3 → 5.5.0.rc1

data/app/models/spree/newsletter_subscriber.rb

@@ -3,6 +3,7 @@ module Spree
     has_prefix_id :sub
 
     include Spree::Metafields
+    include Spree::SingleStoreResource
 
     publishes_lifecycle_events
 
@@ -12,6 +13,7 @@ module Spree
     # Associations
     #
     belongs_to :user, optional: true, class_name: Spree.user_class&.name
+    belongs_to :store, class_name: 'Spree::Store', required: true
 
     #
     # Validations
@@ -19,7 +21,7 @@ module Spree
     validates :email,
               presence: true,
               format: { with: URI::MailTo::EMAIL_REGEXP },
-              uniqueness: { case_sensitive: false, scope: spree_base_uniqueness_scope }
+              uniqueness: { case_sensitive: false, scope: spree_base_uniqueness_scope + [:store_id] }
 
     #
     # Scopes
@@ -30,6 +32,7 @@ module Spree
     #
     # Callbacks
     #
+    before_validation :set_store, unless: :store_id?
     normalizes :email, with: ->(email) { email.to_s.strip.downcase.presence }
 
     #
@@ -52,8 +55,15 @@ module Spree
       Spree::CSV::NewsletterSubscriberPresenter.new(self).call
     end
 
-    def self.subscribe(email:, user: nil)
-      Spree::Newsletter::Subscribe.new(email: email, current_user: user).call
+    def self.subscribe(email:, user: nil, store: nil, redirect_url: nil)
+      store ||= Spree::Current.store
+
+      Spree::Newsletter::Subscribe.new(
+        email: email,
+        current_user: user,
+        current_store: store,
+        redirect_url: redirect_url
+      ).call
     end
 
     def self.verify(token:)
@@ -61,5 +71,11 @@ module Spree
 
       Spree::Newsletter::Verify.new(subscriber: subscriber).call
     end
+
+    private
+
+    def set_store
+      self.store ||= Spree::Current.store
+    end
   end
 end

data/app/models/spree/option_type.rb

@@ -27,7 +27,14 @@ module Spree
     #
     # Associations
     with_options dependent: :destroy, inverse_of: :option_type do
-      has_many :option_values, -> { order(:position) }
+      # `autosave: true` makes the parent's `save`/`update`:
+      #   - persist any built / mutated children in one transaction,
+      #   - collect their validation errors onto `self.errors`,
+      #   - destroy any child marked via `mark_for_destruction`.
+      # The custom `option_values=` writer below leans on this so the v3
+      # ResourceController gets `save returning false` + structured errors
+      # rather than raised exceptions.
+      has_many :option_values, -> { order(:position) }, autosave: true
       has_many :product_option_types
     end
     has_many :products, through: :product_option_types
@@ -73,12 +80,6 @@ module Spree
     after_update :touch_all_products, if: -> { saved_changes.key?(:presentation) }
     after_destroy :touch_all_products
 
-    # legacy, name itself is now parameterized before saving
-    def filter_param
-      Spree::Deprecation.warn('Spree::OptionType#filter_param is deprecated and will be removed in Spree 5.5. Please use Spree::OptionType#name instead.')
-      name.parameterize
-    end
-
     def self.color
       colors.first
     end
@@ -94,6 +95,46 @@ module Spree
       color_swatch?
     end
 
+    # Syncs option values from an array of hashes by mutating the in-memory
+    # `option_values` association — built/assigned children get persisted by
+    # `autosave: true` when the parent saves, and absent IDs get destroyed
+    # via `mark_for_destruction`. The single transaction is owned by the
+    # parent's `save`, so validation failures surface as `errors` and the
+    # whole thing rolls back together.
+    #
+    # Falls back to ActiveRecord's collection writer when given OptionValue
+    # records (e.g. from `accepts_nested_attributes_for` used by the legacy admin).
+    #
+    # @param option_values_params [Array<Hash>] array of option value attribute hashes
+    # @return [void]
+    def option_values=(option_values_params)
+      return super if option_values_params.blank? || option_values_params.first.is_a?(Spree::OptionValue)
+
+      # Load the association into the in-memory collection so subsequent
+      # `option_values.build` / `mark_for_destruction` mutations stay on the
+      # same instances `autosave` will traverse at parent-save time.
+      existing_by_id = option_values.to_a.index_by(&:id)
+      retained_ids = []
+
+      option_values_params.each do |value_data|
+        data = value_data.to_h.with_indifferent_access
+        value_id = data.delete(:id)
+
+        record = if value_id.present?
+                   existing_by_id[Spree::PrefixedId.decode_prefixed_id(value_id) || value_id] ||
+                     raise(ActiveRecord::RecordNotFound.new("Couldn't find Spree::OptionValue with param=#{value_id}", 'Spree::OptionValue'))
+                 else
+                   option_values.build
+                 end
+        record.assign_attributes(data)
+        retained_ids << record.id if record.persisted?
+      end
+
+      existing_by_id.each_value do |existing|
+        existing.mark_for_destruction unless retained_ids.include?(existing.id)
+      end
+    end
+
     private
 
     def touch_all_products

data/app/models/spree/order/checkout.rb

@@ -135,7 +135,7 @@ module Spree
           def subscribe_to_newsletter
             return unless accept_marketing?
 
-            Spree::NewsletterSubscriber.subscribe(email: email, user: user)
+            Spree::NewsletterSubscriber.subscribe(email: email, user: user, store: store)
           end
 
           def self.go_to_state(name, options = {})
@@ -317,8 +317,8 @@ module Spree
           # attributes for a single payment and its source, discarding attributes
           # for payment methods other than the one selected
           #
-          # In case a existing credit card is provided it needs to build the payment
-          # attributes from scratch so we can set the amount. example payload:
+          # If an existing credit card is provided, build the payment attributes
+          # from scratch so the amount can be set. Example payload:
           #
           #   {
           #     "order": {

data/app/models/spree/order.rb

@@ -9,6 +9,11 @@ module Spree
   class Order < Spree.base_class
     has_prefix_id :or  # Stripe: or_
 
+    # Legacy free-text `channel` column was replaced by the `channel_id` FK
+    # (see 6.0-order-routing.md). The string column stays in the DB so the
+    # 5.4-to-5.5 backfill rake can read it; AR ignores it everywhere else.
+    self.ignored_columns += ['channel']
+
     PAYMENT_STATES = %w(balance_due credit_owed failed paid void)
     SHIPMENT_STATES = %w(backorder canceled partial pending ready shipped)
     LINE_ITEM_REMOVABLE_STATES = %w(cart address delivery payment confirm resumed)
@@ -104,23 +109,42 @@ module Spree
       go_to_state :complete
     end
 
-    self.whitelisted_ransackable_associations = %w[shipments user created_by approver canceler promotions bill_address ship_address line_items store]
+    self.whitelisted_ransackable_associations = %w[shipments user created_by approver canceler promotions bill_address ship_address line_items store channel tags]
     self.whitelisted_ransackable_attributes = %w[
-      completed_at email number state payment_state shipment_state
-      total item_total item_count considered_risky channel
+      completed_at email number state status payment_state shipment_state
+      total item_total item_count considered_risky channel_id currency
     ]
-    self.whitelisted_ransackable_scopes = %w[refunded partially_refunded search multi_search]
+    self.whitelisted_ransackable_scopes = %w[complete incomplete refunded partially_refunded search multi_search]
 
     attr_reader :coupon_code
     attr_accessor :temporary_address
 
+    # Set to false on admin-initiated flows to suppress customer-facing emails.
+    attr_accessor :notify_customer
+
     attribute :state_machine_resumed, :boolean
 
+    STATUSES = %w[draft placed canceled].freeze
+
+    attribute :status, :string, default: 'draft'
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :drafts,         -> { where(status: 'draft') }
+    scope :placed_orders,  -> { where(status: 'placed') }
+    scope :canceled_orders, -> { where(status: 'canceled') }
+
     acts_as_taggable_on :tags
     acts_as_taggable_tenant :store_id
 
+    def tags=(tags)
+      self.tag_list = tags
+    end
+
     ASSOCIATED_USER_ATTRIBUTES = [:user_id, :email, :bill_address_id, :ship_address_id]
 
+    # 6.0 forward-compat: User→Customer rename. Column stays user_id in 5.x.
+    alias_attribute :customer_id, :user_id
+
     belongs_to :user, class_name: "::#{Spree.user_class}", optional: true, autosave: true
     belongs_to :created_by, class_name: "::#{Spree.admin_user_class}", optional: true
     belongs_to :approver, class_name: "::#{Spree.admin_user_class}", optional: true
@@ -140,6 +164,8 @@ module Spree
 
     belongs_to :store, class_name: 'Spree::Store'
     belongs_to :market, class_name: 'Spree::Market', optional: true
+    belongs_to :channel, class_name: 'Spree::Channel', optional: true
+    belongs_to :preferred_stock_location, class_name: 'Spree::StockLocation', optional: true
 
     with_options dependent: :destroy do
       has_many :state_changes, as: :stateful, class_name: 'Spree::StateChange'
@@ -148,11 +174,14 @@ module Spree
       has_many :payment_sessions, inverse_of: :order, class_name: 'Spree::PaymentSession'
       has_many :return_authorizations, inverse_of: :order, class_name: 'Spree::ReturnAuthorization'
       has_many :adjustments, -> { order(:created_at) }, as: :adjustable, class_name: 'Spree::Adjustment'
+      has_many :cancellations, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderCancellation'
+      has_many :approvals, -> { order(:created_at) }, inverse_of: :order, class_name: 'Spree::OrderApproval'
     end
     has_many :reimbursements, inverse_of: :order, class_name: 'Spree::Reimbursement'
     has_many :customer_returns, class_name: 'Spree::CustomerReturn', through: :return_authorizations
     has_many :line_item_adjustments, through: :line_items, source: :adjustments
     has_many :inventory_units, inverse_of: :order, class_name: 'Spree::InventoryUnit'
+    has_many :stock_reservations, class_name: 'Spree::StockReservation', inverse_of: :order, dependent: :destroy
     has_many :return_items, through: :inventory_units, class_name: 'Spree::ReturnItem'
     has_many :variants, through: :line_items
     has_many :products, through: :variants
@@ -194,6 +223,7 @@ module Spree
     # Needs to happen before save_permalink is called
     before_validation :ensure_store_presence
     before_validation :ensure_market_presence
+    before_validation :ensure_channel_presence
     before_validation :ensure_currency_presence
     before_validation :ensure_locale_presence
     before_validation :resolve_market_from_currency, if: -> { persisted? && currency_changed? && !skip_market_resolution }
@@ -348,6 +378,21 @@ module Spree
       completed_at.present?
     end
 
+    # True when the order is mid-checkout: past the `cart` state but not yet
+    # completed or canceled. Used by stock reservation hooks and any flow
+    # that should only run during the active checkout phase.
+    def in_checkout?
+      !cart? && !complete? && !canceled?
+    end
+
+    def draft?
+      status == 'draft'
+    end
+
+    def placed?
+      status == 'placed'
+    end
+
     # Checks if the order is fully refunded
     # @return [Boolean]
     def order_refunded?
@@ -459,6 +504,12 @@ module Spree
       self.market ||= Spree::Current.market || store&.default_market
     end
 
+    def ensure_channel_presence
+      return if channel_id.present?
+
+      self.channel = store&.default_channel
+    end
+
     def allow_cancel?
       return false if !completed? || canceled?
 
@@ -591,6 +642,7 @@ module Spree
       end
 
       updater.update_shipment_state
+      self.status = 'placed'
       save!
       updater.run_hooks
 
@@ -719,7 +771,34 @@ module Spree
       # and are not returned or shipped should be deleted
       inventory_units.on_hand_or_backordered.delete_all
 
-      self.shipments = Spree::Stock::Coordinator.new(self).shipments
+      self.shipments = order_routing_strategy.for_allocation.map do |package|
+        package.to_shipment.tap { |s| s.address_id = ship_address_id }
+      end
+    end
+
+    # Resolves the routing strategy from the channel override first, then the
+    # store default. Only a registered Spree::OrderRouting::Strategy::Base
+    # subclass is used; any other value (an unregistered/typo'd class, or a
+    # strategy that was unregistered after being persisted) is logged and
+    # skipped rather than raised, falling back to the default Rules strategy so
+    # a misconfiguration can't take down cart display or checkout.
+    #
+    # @return [Spree::OrderRouting::Strategy::Base]
+    def order_routing_strategy
+      klass = valid_order_routing_strategy_class(channel&.preferred_order_routing_strategy) ||
+              valid_order_routing_strategy_class(store.preferred_order_routing_strategy) ||
+              Spree::OrderRouting::Strategy::Rules
+
+      klass.new(order: self)
+    end
+
+    # Cascade for the `preferred_location` rule kind. Channel and B2B sources
+    # are layered in by their respective plans.
+    #
+    # @return [Integer, nil]
+    def inferred_preferred_stock_location_id
+      preferred_stock_location_id.presence ||
+        created_by&.try(:preferred_stock_location_id)
     end
 
     # Returns the total weight of the inventory units in the order
@@ -965,6 +1044,19 @@ module Spree
 
     private
 
+    def valid_order_routing_strategy_class(klass_name)
+      return if klass_name.blank?
+
+      klass = Spree.order_routing.strategies.find { |strategy| strategy.to_s == klass_name.to_s }
+      return klass if klass
+
+      Rails.logger.warn(
+        "[Spree] Ignoring unregistered order routing strategy #{klass_name.inspect} " \
+        "for order #{number.inspect}; falling back to the default strategy."
+      )
+      nil
+    end
+
     def link_by_email
       self.email = user.email if user
     end
@@ -998,6 +1090,8 @@ module Spree
     end
 
     def after_cancel
+      update_column(:status, 'canceled')
+
       shipments.each(&:cancel!)
 
       # payments fully covered by gift card won't be refunded
@@ -1015,6 +1109,8 @@ module Spree
     end
 
     def after_resume
+      update_column(:status, 'placed')
+
       shipments.each(&:resume!)
       consider_risk
       send_order_resumed_webhook
@@ -1089,7 +1185,7 @@ module Spree
     end
 
     def publish_order_completed_event
-      publish_event('order.completed')
+      publish_event('order.completed', event_payload.merge(notify_customer: notify_customer))
     end
 
     def publish_order_resumed_event

data/app/models/spree/order_approval.rb

@@ -0,0 +1,19 @@
+module Spree
+  class OrderApproval < Spree.base_class
+    has_prefix_id :appr
+
+    STATUSES = %w[pending approved rejected].freeze
+
+    attribute :metadata, default: -> { {} }
+
+    belongs_to :order, class_name: 'Spree::Order', inverse_of: :approvals
+    belongs_to :approver, polymorphic: true, optional: true
+
+    validates :order, presence: true
+    validates :status, presence: true, inclusion: { in: STATUSES }
+
+    scope :approved, -> { where(status: 'approved') }
+    scope :pending,  -> { where(status: 'pending') }
+    scope :rejected, -> { where(status: 'rejected') }
+  end
+end

data/app/models/spree/order_cancellation.rb

@@ -0,0 +1,19 @@
+module Spree
+  class OrderCancellation < Spree.base_class
+    has_prefix_id :cncl
+
+    REASONS = %w[customer declined fraud inventory staff other expired].freeze
+
+    attribute :restock_items, :boolean, default: false
+    attribute :refund_payments, :boolean, default: false
+    attribute :notify_customer, :boolean, default: false
+    attribute :metadata, default: -> { {} }
+
+    belongs_to :order, class_name: 'Spree::Order', inverse_of: :cancellations
+    belongs_to :canceled_by, polymorphic: true, optional: true
+
+    validates :order, presence: true
+    validates :reason, presence: true, inclusion: { in: REASONS }
+    validates :refund_amount, numericality: { greater_than_or_equal_to: 0, allow_nil: true }
+  end
+end

data/app/models/spree/order_routing/has_strategy_preference.rb

@@ -0,0 +1,28 @@
+module Spree
+  module OrderRouting
+    # Shared validation for models carrying a +preferred_order_routing_strategy+
+    # preference (Spree::Store, Spree::Channel). A blank value is allowed (it
+    # falls back to the next level / the default Rules strategy); a present value
+    # must name a registered Spree::OrderRouting::Strategy::Base subclass.
+    module HasStrategyPreference
+      extend ActiveSupport::Concern
+
+      included do
+        validate :order_routing_strategy_must_be_registered
+      end
+
+      private
+
+      def order_routing_strategy_must_be_registered
+        value = preferred_order_routing_strategy
+        return if value.blank?
+        return if Spree.order_routing.strategies.any? { |strategy| strategy.to_s == value.to_s }
+
+        errors.add(
+          :preferred_order_routing_strategy,
+          Spree.t(:invalid_order_routing_strategy, scope: [:errors, :messages], default: 'is not a registered order routing strategy')
+        )
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/rules/default_location.rb

@@ -0,0 +1,16 @@
+module Spree
+  module OrderRouting
+    module Rules
+      # Ranks the StockLocation marked `default: true` at 0 and others at 1.
+      # Provides a deterministic baseline so the reducer always has a winner
+      # once higher-priority rules abstain or tie.
+      class DefaultLocation < Spree::OrderRoutingRule
+        def rank(_order, locations)
+          locations.map do |loc|
+            LocationRanking.new(location: loc, rank: loc.default? ? 0 : 1)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/rules/minimize_splits.rb

@@ -0,0 +1,45 @@
+module Spree
+  module OrderRouting
+    module Rules
+      # Prefers locations that can fulfill more demand on their own.
+      # Higher coverage → lower (better) rank, so the location that single-handedly
+      # covers the most variants wins. Coverage is counted per distinct variant
+      # so a variant repeated across multiple line items isn't double-counted.
+      class MinimizeSplits < Spree::OrderRoutingRule
+        def rank(order, locations)
+          demand = required_quantity_by_variant(order)
+          counts = stock_item_counts(demand.keys, locations)
+
+          locations.map do |loc|
+            coverage = demand.count do |variant_id, qty|
+              (counts[[loc.id, variant_id]] || 0) >= qty
+            end
+
+            LocationRanking.new(location: loc, rank: -coverage)
+          end
+        end
+
+        private
+
+        def required_quantity_by_variant(order)
+          order.line_items.each_with_object(Hash.new(0)) do |li, h|
+            next if li.variant_id.nil?
+
+            h[li.variant_id] += li.quantity
+          end
+        end
+
+        # One query for the entire location × variant matrix instead of
+        # N variants × M locations stock_item lookups.
+        def stock_item_counts(variant_ids, locations)
+          return {} if variant_ids.empty? || locations.empty?
+
+          Spree::StockItem
+            .where(stock_location_id: locations.map(&:id), variant_id: variant_ids)
+            .pluck(:stock_location_id, :variant_id, :count_on_hand)
+            .each_with_object({}) { |(loc_id, var_id, count), h| h[[loc_id, var_id]] = count }
+        end
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/rules/preferred_location.rb

@@ -0,0 +1,22 @@
+module Spree
+  module OrderRouting
+    module Rules
+      # Ranks the order's inferred preferred location at 0 and abstains for
+      # everything else. Lets admins / staff / B2B contexts pin "fulfill from
+      # this location" without preventing fallback when the preferred location
+      # doesn't actually stock the items — subsequent rules tie-break.
+      class PreferredLocation < Spree::OrderRoutingRule
+        def rank(order, locations)
+          preferred_id = order.inferred_preferred_stock_location_id
+
+          locations.map do |loc|
+            LocationRanking.new(
+              location: loc,
+              rank: (preferred_id.present? && loc.id.to_s == preferred_id.to_s) ? 0 : nil
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/strategy/base.rb

@@ -0,0 +1,47 @@
+module Spree
+  module OrderRouting
+    module Strategy
+      # Contract for order routing strategies. Subclasses implement all four
+      # methods — there are no defaults. New routing *signals* (proximity,
+      # day-of-week, etc.) ship as STI subclasses of Spree::OrderRoutingRule;
+      # a custom strategy is appropriate only when the algorithm itself is a
+      # different shape (OMS delegation, ML model, optimization solver).
+      #
+      # Selected per Order via Spree::Order#order_routing_strategy.
+      # See docs/plans/6.0-order-routing.md.
+      class Base
+        attr_reader :order
+
+        # Human label for admin strategy pickers. Override in a subclass or add
+        # an i18n key under +spree.order_routing.strategies+.
+        #
+        # @return [String]
+        def self.display_name
+          Spree.t(name.demodulize.underscore, scope: 'order_routing.strategies', default: name.demodulize.titleize)
+        end
+
+        def initialize(order:)
+          @order = order
+        end
+
+        # @return [Array<Spree::Stock::Package>]
+        def for_allocation
+          raise NotImplementedError, "#{self.class} must implement #for_allocation"
+        end
+
+        # @param fulfillment [Spree::Shipment]
+        def for_sale(fulfillment:)
+          raise NotImplementedError, "#{self.class} must implement #for_sale"
+        end
+
+        def for_release
+          raise NotImplementedError, "#{self.class} must implement #for_release"
+        end
+
+        def for_cancellation
+          raise NotImplementedError, "#{self.class} must implement #for_cancellation"
+        end
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/strategy/legacy.rb

@@ -0,0 +1,33 @@
+module Spree
+  module OrderRouting
+    module Strategy
+      # Pre-5.5 routing behavior. Delegates to Spree::Stock::Coordinator,
+      # which packs every active stock location and lets Prioritizer's
+      # Adjuster distribute units across the resulting packages — no rules
+      # consulted, no merchant-driven preferences, location order is
+      # whatever the database returns.
+      #
+      # Provided as an opt-in escape hatch for merchants upgrading from 5.4
+      # who are not ready to adopt rules-based routing. Configure via:
+      #
+      #   store.update!(preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy')
+      #
+      # Spree 6.0 drops this strategy along with the underlying Coordinator.
+      # See docs/plans/6.0-order-routing.md.
+      class Legacy < Base
+        def for_allocation
+          Spree::Stock::Coordinator.new(order).packages
+        end
+
+        # Stock decrement / restock today happens via Spree::Shipment's state
+        # machine (after_ship / after_cancel). The strategy hooks below are
+        # part of the contract for the future reservation + typed-movement
+        # phase. In 5.5 they are no-ops; existing model callbacks already do
+        # the right thing.
+        def for_sale(fulfillment:); end
+        def for_release; end
+        def for_cancellation; end
+      end
+    end
+  end
+end

data/app/models/spree/order_routing/strategy/reducer.rb

@@ -0,0 +1,68 @@
+require 'set'
+
+module Spree
+  module OrderRouting
+    module Strategy
+      # Walks rules in priority order and applies a "first non-tie wins" reducer.
+      #
+      # For each rule:
+      #   1. Drop rankings where rank is nil (rule abstains for that location).
+      #   2. Find the location(s) with the lowest rank (best).
+      #   3. Unique winner -> return it.
+      #   4. Tie -> carry the tied set forward to the next rule.
+      #
+      # Out of rules with ties: prefer the StockLocation marked default,
+      # then by id. Guarantees a winner whenever locations is non-empty.
+      class Reducer
+        def initialize(rules, order:)
+          @rules = rules
+          @order = order
+        end
+
+        # @param locations [Array<Spree::StockLocation>]
+        # @return [Spree::StockLocation, nil]
+        def pick(locations)
+          return nil if locations.empty?
+
+          remaining = locations
+          remaining_ids = remaining.map(&:id).to_set
+
+          @rules.each do |rule|
+            rankings = rule.rank(@order, remaining).select do |r|
+              r.rank && remaining_ids.include?(r.location.id)
+            end
+            next if rankings.empty?
+
+            min_rank = rankings.map(&:rank).min
+            top = rankings.select { |r| r.rank == min_rank }.map(&:location)
+
+            return top.first if top.size == 1
+
+            remaining = top
+            remaining_ids = top.map(&:id).to_set
+          end
+
+          remaining.min_by { |l| [l.default? ? 0 : 1, l.id] }
+        end
+
+        # Returns every input location, ordered best-first by the same rule
+        # chain that drives #pick. Each successive location is the best of
+        # what remains — used by Strategy::Rules to fan out an allocation
+        # across multiple locations when no single location covers the cart.
+        #
+        # @param locations [Array<Spree::StockLocation>]
+        # @return [Array<Spree::StockLocation>]
+        def rank_all(locations)
+          remaining = locations.dup
+          ordered = []
+          until remaining.empty?
+            chosen = pick(remaining) or break
+            ordered << chosen
+            remaining = remaining.reject { |l| l.id == chosen.id }
+          end
+          ordered
+        end
+      end
+    end
+  end
+end