spree_core 5.6.1 → 6.0.0.beta2

data/app/models/concerns/spree/has_address_book.rb

@@ -0,0 +1,89 @@
+module Spree
+  # Anything that keeps an address book: a customer, a company node, and
+  # whatever comes next.
+  #
+  # Owners already differ in what they call their default slots — a customer
+  # has +bill_address_id+ / +ship_address_id+, a company node
+  # +default_bill_address_id+ / +default_ship_address_id+ — so the columns are
+  # declared once here and every caller asks the owner instead of knowing
+  # which of them it is holding.
+  #
+  #   class Spree::Company < Spree.base_class
+  #     has_address_book bill: :default_bill_address_id, ship: :default_ship_address_id
+  #   end
+  module HasAddressBook
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # @param bill [Symbol] column holding the default billing address id
+      # @param ship [Symbol] column holding the default shipping address id
+      def has_address_book(bill:, ship:)
+        class_attribute :default_address_columns, instance_writer: false, default: { bill: bill, ship: ship }
+      end
+    end
+
+    # Points this owner's default slots at an address.
+    #
+    # Writes the columns directly: callers have already established that the
+    # address is this owner's, so the ownership validation this skips cannot
+    # fail, and skipping it avoids re-running a whole validation set to move
+    # one foreign key.
+    #
+    # Each flag has three meanings, and they are all different: true promotes
+    # this address, false gives up the slot — but only when this address is
+    # what currently holds it, since another entry's default is not this
+    # caller's business — and nil leaves the slot alone.
+    #
+    # @param address_id [Integer]
+    # @param billing [Boolean, nil] promote to, or release, the billing slot
+    # @param shipping [Boolean, nil] promote to, or release, the shipping slot
+    def assign_default_address(address_id:, billing: true, shipping: true)
+      promoted = {}
+      released = []
+
+      { bill: billing, ship: shipping }.each do |kind, flag|
+        column = default_address_columns[kind]
+
+        if flag
+          promoted[column] = address_id
+        elsif flag == false
+          released << column
+        end
+      end
+
+      promote_default_columns(promoted)
+      release_default_columns(released, address_id)
+
+      # Promotion writes the in-memory attributes on its way through; a
+      # release goes around them, so only that leaves this instance stale.
+      reload if persisted? && released.any?
+    end
+
+    # @param kind [Symbol] :bill or :ship
+    # @return [Integer, nil] the address this owner prefills that slot with
+    def default_address_id(kind)
+      public_send(default_address_columns.fetch(kind))
+    end
+
+    private
+
+    def promote_default_columns(columns)
+      return if columns.empty?
+
+      update_columns(**columns, updated_at: Time.current)
+    end
+
+    # Released in one conditional statement rather than read-then-write: a
+    # request giving up a slot must not undo a promotion that landed between
+    # the two. The WHERE clause is the check, so a slot already moved on is
+    # simply not matched.
+    def release_default_columns(columns, address_id)
+      return if columns.empty?
+
+      columns.each do |column|
+        self.class.where(id: id, column => address_id).
+          update_all(column => nil, updated_at: Time.current)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/has_custom_fields.rb

@@ -0,0 +1,360 @@
+module Spree
+  module HasCustomFields
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # @param key_with_namespace [String] the dotted `"namespace.key"` form
+      # @param store [Spree::Store, nil] the store the definition belongs to;
+      #   defaults to the current request's store, since definitions are
+      #   store-owned and there is no global schema to fall back on.
+      def ensure_custom_field_definition_exists!(key_with_namespace, store: Spree::Current.store)
+        namespace, key = extract_namespace_and_key(key_with_namespace)
+        raise ArgumentError, 'a store is required to create a custom field definition' if store.nil?
+
+        store.custom_field_definitions.find_or_create_by!(
+          namespace: namespace, key: key, resource_type: self.name
+        )
+      end
+
+      def extract_namespace_and_key(key_with_namespace)
+        namespace = key_with_namespace.to_s.split('.').first
+        key = key_with_namespace.to_s.split('.').last
+        [namespace, key]
+      end
+
+      # Deprecated 6.0 names, removed in 6.1.
+      def ensure_metafield_definition_exists!(key_with_namespace, store: Spree::Current.store)
+        Spree::Deprecation.warn('ensure_metafield_definition_exists! is deprecated and will be removed in Spree 6.1. Use ensure_custom_field_definition_exists! instead.')
+        ensure_custom_field_definition_exists!(key_with_namespace, store: store)
+      end
+
+      def with_metafield_key(key_with_namespace)
+        Spree::Deprecation.warn('.with_metafield_key is deprecated and will be removed in Spree 6.1. Use .with_custom_field_key instead.')
+        with_custom_field_key(key_with_namespace)
+      end
+
+      def with_metafield_key_value(key_with_namespace, value)
+        Spree::Deprecation.warn('.with_metafield_key_value is deprecated and will be removed in Spree 6.1. Use .with_custom_field_key_value instead.')
+        with_custom_field_key_value(key_with_namespace, value)
+      end
+    end
+
+    included do
+      has_many :custom_fields, -> { includes(:custom_field_definition) }, as: :resource, class_name: 'Spree::CustomField', dependent: :destroy
+      has_many :storefront_custom_fields, -> { includes(:custom_field_definition).storefront_visible }, as: :resource, class_name: 'Spree::CustomField'
+
+      # Deprecated 6.0 association names, removed in 6.1. `private_metafields`
+      # has no replacement — read `custom_fields` and filter, or query
+      # Spree::CustomField.admin_only directly.
+      has_many :metafields, -> { includes(:custom_field_definition) }, as: :resource, class_name: 'Spree::CustomField', deprecated: true
+      has_many :public_metafields, -> { includes(:custom_field_definition).storefront_visible }, as: :resource, class_name: 'Spree::CustomField', deprecated: true
+      has_many :private_metafields, -> { includes(:custom_field_definition).admin_only }, as: :resource, class_name: 'Spree::CustomField', deprecated: true
+
+      accepts_nested_attributes_for :custom_fields, allow_destroy: true, reject_if: lambda { |attrs|
+                                                                                     attrs[:custom_field_definition_id].blank? || (attrs[:id].blank? && attrs[:value].blank?)
+                                                                                   }
+
+      # Override custom_fields_attributes= to automatically mark existing custom fields
+      # with empty values for destruction
+      def custom_fields_attributes=(attributes)
+        attributes = attributes.values if attributes.is_a?(Hash)
+
+        attributes.each do |attrs|
+          # If this is an existing custom field (has an id) and value is blank,
+          # mark it for destruction
+          if attrs[:id].present? && value_blank?(attrs[:value])
+            attrs[:_destroy] = true
+          end
+        end
+
+        super(attributes)
+      end
+
+      # Bulk writer reached via flat params on the admin API v3
+      # (`custom_fields: [...]`); also works through
+      # `Model.new(permitted_params)` since Rails routes the key to this writer.
+      #
+      # Upsert semantics by `custom_field_definition_id`: existing entries
+      # for the same definition are updated, missing entries are created.
+      # Partial: definitions NOT in the array are left untouched, so the
+      # client can patch one field at a time without resending the rest.
+      # Blank values on an existing custom field destroy it (mirrors the dedicated
+      # endpoint's behavior via `custom_fields_attributes=`).
+      def custom_fields=(attributes)
+        return if attributes.blank?
+        return super(attributes) if attributes.first.is_a?(Spree::CustomField)
+
+        assign_custom_field_attrs(attributes)
+      end
+
+      after_save :apply_pending_custom_fields, if: -> { @pending_custom_field_attrs.present? }
+
+      scope :with_custom_field_key, ->(key_with_namespace) {
+        namespace, key = extract_namespace_and_key(key_with_namespace)
+        joins(custom_fields: :custom_field_definition).
+          where(Spree::CustomFieldDefinition.table_name => { namespace: namespace, key: key })
+      }
+      scope :with_custom_field_key_value, ->(key_with_namespace, value) {
+        namespace, key = extract_namespace_and_key(key_with_namespace)
+
+        joins(custom_fields: :custom_field_definition)
+          .where(Spree::CustomFieldDefinition.table_name => { namespace: namespace, key: key })
+          .where(Spree::CustomField.table_name => { value: value })
+      }
+
+      def extract_namespace_and_key(key_with_namespace)
+        self.class.extract_namespace_and_key(key_with_namespace)
+      end
+
+      # Upsert a single custom field value on this resource. The first
+      # argument locates the definition by any of:
+      #
+      # - `"namespace.key"` string — auto-creates the definition if missing
+      #   (backend-internal callers that don't know the id upfront).
+      # - {Spree::CustomFieldDefinition} instance.
+      # - Integer / numeric String — raw definition id.
+      # - Prefixed-id String (`"cfdef_..."`) — decoded to the definition id.
+      #
+      # Blank values (nil or empty/whitespace string) destroy any existing
+      # custom field for the definition. Empty containers (`[]`, `{}`) and
+      # numeric / boolean falsy values are real values, not blanks.
+      #
+      # @param definition_or_key [String, Integer, Spree::CustomFieldDefinition]
+      # @param value [Object] the value to persist; type is enforced by the
+      #   typed custom-field subclass (Boolean, Number, Json, ShortText, …).
+      # @return [Spree::CustomField, nil] the persisted custom field, or nil when
+      #   the value was blank and any existing row was destroyed.
+      # @raise [ArgumentError] if `definition_or_key` doesn't resolve to a
+      #   known definition.
+      def set_custom_field(definition_or_key, value)
+        definition_id = resolve_custom_field_definition_id(definition_or_key)
+        custom_field = custom_fields.find_or_initialize_by(custom_field_definition_id: definition_id)
+        if value_blank?(value)
+          custom_field.destroy if custom_field.persisted?
+          return nil
+        end
+
+        # JSON custom fields store canonical JSON in the underlying text column.
+        # Coerce Hash/Array values BEFORE assignment, since the STI subclass
+        # (`Spree::CustomFields::Json`) isn't switched on until before_validation,
+        # so its custom `value=` writer doesn't run yet on a fresh
+        # `find_or_initialize_by` record.
+        if (value.is_a?(Hash) || value.is_a?(Array)) &&
+           custom_field.custom_field_definition&.field_type == 'json'
+          value = value.to_json
+        end
+
+        custom_field.value = value
+        custom_field.save!
+        custom_field
+      end
+
+      def get_custom_field(key_with_namespace)
+        namespace, key = extract_namespace_and_key(key_with_namespace)
+        custom_fields.with_key(namespace, key).first
+      end
+
+      def has_custom_field?(key_with_namespace)
+        if key_with_namespace.is_a?(Spree::CustomFieldDefinition)
+          namespace = key_with_namespace.namespace
+          key = key_with_namespace.key
+        elsif key_with_namespace.is_a?(String)
+          namespace, key = extract_namespace_and_key(key_with_namespace)
+        else
+          raise ArgumentError, "Invalid key_with_namespace: #{key_with_namespace.inspect}"
+        end
+
+        custom_fields.with_key(namespace, key).exists?
+      end
+
+      # Deprecated 6.0 names, removed in 6.1.
+      def set_metafield(definition_or_key, value)
+        Spree::Deprecation.warn('#set_metafield is deprecated and will be removed in Spree 6.1. Use #set_custom_field instead.')
+        set_custom_field(definition_or_key, value)
+      end
+
+      def get_metafield(key_with_namespace)
+        Spree::Deprecation.warn('#get_metafield is deprecated and will be removed in Spree 6.1. Use #get_custom_field instead.')
+        get_custom_field(key_with_namespace)
+      end
+
+      def has_metafield?(key_with_namespace)
+        Spree::Deprecation.warn('#has_metafield? is deprecated and will be removed in Spree 6.1. Use #has_custom_field? instead.')
+        has_custom_field?(key_with_namespace)
+      end
+
+      # Legacy payloads key the definition as `metafield_definition_id`, which
+      # the new writer rejects — translate rather than silently dropping them.
+      def metafields_attributes=(attributes)
+        Spree::Deprecation.warn('#metafields_attributes= is deprecated and will be removed in Spree 6.1. Use #custom_fields_attributes= instead.')
+
+        attributes = attributes.values if attributes.is_a?(Hash)
+        translated = attributes.map do |attrs|
+          attrs = attrs.respond_to?(:to_h) ? attrs.to_h : attrs
+          attrs = attrs.with_indifferent_access
+          attrs[:custom_field_definition_id] ||= attrs.delete(:metafield_definition_id)
+          attrs
+        end
+
+        self.custom_fields_attributes = translated
+      end
+
+      private
+
+      # Decide whether a custom-field value should trigger the destroy-existing
+      # branch. Ruby's `blank?` reports `false`, `0`, `[]`, `{}` as blank, but
+      # for typed custom fields those are real values:
+      #
+      # - Boolean `false` / Numeric `0` — real values, never destroy.
+      # - Empty Array / Hash — a JSON custom field storing `[]` or `{}` is a
+      #   meaningful value (an empty list / object), not a clear signal.
+      #
+      # Only `nil` and empty/whitespace strings count as "missing".
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def value_blank?(value)
+        return true if value.nil?
+        return value.strip.empty? if value.is_a?(String)
+
+        false
+      end
+
+      def assign_custom_field_attrs(attributes)
+        if new_record?
+          # Persisting custom_fields requires a persisted parent (resource_id NOT
+          # NULL). Stash the attrs and replay them after the parent is saved.
+          @pending_custom_field_attrs = attributes
+          return
+        end
+
+        apply_custom_field_attrs(attributes)
+      end
+
+      def apply_pending_custom_fields
+        attrs = @pending_custom_field_attrs
+        @pending_custom_field_attrs = nil
+        apply_custom_field_attrs(attrs)
+      end
+
+      def apply_custom_field_attrs(attributes)
+        attributes = attributes.values if attributes.is_a?(Hash)
+        attributes.each_with_index do |raw, index|
+          attrs = raw.respond_to?(:to_h) ? raw.to_h : raw
+          attrs = attrs.with_indifferent_access
+          definition_id = attrs[:custom_field_definition_id] || attrs[:metafield_definition_id]
+          next if definition_id.blank?
+
+          begin
+            set_custom_field(definition_id, attrs[:value])
+          rescue ArgumentError => e
+            # Convert an unknown / malformed definition id into a field-level
+            # validation error so the controller returns 422 with structured
+            # `details`, instead of leaking ArgumentError as a 400/500.
+            errors.add("custom_fields[#{index}].custom_field_definition_id", e.message)
+            raise ActiveRecord::RecordInvalid, self
+          end
+        end
+      end
+
+      # Resolve any of the supported reference shapes to a raw definition id.
+      # See {#set_custom_field} for the accepted shapes.
+      #
+      # Every shape is checked against this record's store: definitions are
+      # store-owned, so one store's record must not end up carrying another
+      # store's definition whichever way the caller names it.
+      #
+      # @param definition_or_key [String, Integer, Spree::CustomFieldDefinition]
+      # @return [Integer, String] the definition's primary key value (Integer
+      #   for legacy integer-id setups, String for UUID setups).
+      # @raise [ArgumentError] for unknown / malformed input, or a definition
+      #   belonging to another store.
+      def resolve_custom_field_definition_id(definition_or_key)
+        case definition_or_key
+        when Spree::CustomFieldDefinition
+          # A loaded record already carries its store, so compare in memory
+          # rather than paying a lookup to learn what is in hand.
+          unless definition_or_key.store_id == custom_field_definition_store.id
+            raise ArgumentError, "Unknown custom field definition id: #{definition_or_key.full_key.inspect}"
+          end
+
+          definition_or_key.id
+        when Integer
+          find_definition_id_in_store!(definition_or_key, definition_or_key)
+        when String
+          resolve_custom_field_definition_id_from_string(definition_or_key)
+        else
+          raise ArgumentError, "Invalid definition_or_key: #{definition_or_key.inspect}"
+        end
+      end
+
+      # @param value [String] one of: `"namespace.key"`, a prefixed id
+      #   (`"cfdef_..."`), or a bare numeric id (`"42"`).
+      # @return [Integer, String] the resolved definition's primary key value.
+      # @raise [ArgumentError] if the string doesn't match any known shape.
+      def resolve_custom_field_definition_id_from_string(value)
+        # `"namespace.key"` — backend-internal callers that don't know the id;
+        # auto-create the definition if missing.
+        if value.include?('.')
+          namespace, key = extract_namespace_and_key(value)
+          return custom_field_definition_store.custom_field_definitions.find_or_create_by!(
+            namespace: namespace, key: key, resource_type: self.class.name
+          ).id
+        end
+
+        # Prefixed id (`"cfdef_..."`/`"mfd_..."`). Use the canonical predicate
+        # so single-segment names with underscores (e.g. `"product_specs"`)
+        # don't get mistaken for prefixed ids.
+        #
+        # Both id shapes are resolved through the store rather than the class.
+        # That is what stops one store's record carrying another store's
+        # definition, and it also covers the phantom-id case: Sqids will
+        # happily decode any all-lowercase alphanumeric string to an integer
+        # that matches no row, and without the existence check
+        # `find_or_initialize_by(custom_field_definition_id: phantom_id)` would
+        # later raise a confusing "CustomField definition must exist" 422
+        # instead of an "unknown id" one.
+        if Spree::PrefixedId.prefixed_id?(value)
+          decoded = Spree::CustomFieldDefinition.decode_prefixed_id(value)
+          return find_definition_id_in_store!(decoded, value)
+        end
+
+        # Bare numeric id ("42"). Reject anything else outright.
+        raise ArgumentError, "Invalid custom field definition reference: #{value.inspect}" unless /\A\d+\z/.match?(value)
+
+        find_definition_id_in_store!(value, value)
+      end
+
+      # @param id [Integer, String, nil] the decoded primary key
+      # @param reference [String] what the caller passed, for the error message
+      # @return [Integer, String] the definition's own primary key value
+      # @raise [ArgumentError] when this store has no such definition.
+      def find_definition_id_in_store!(id, reference)
+        definition = id && custom_field_definition_store.custom_field_definitions.find_by(id: id)
+        raise ArgumentError, "Unknown custom field definition id: #{reference.inspect}" if definition.nil?
+
+        definition.id
+      end
+
+      # The store whose custom-field schema this record's fields are defined
+      # in. A record that owns a store answers with it; one that reaches a
+      # store through its owner overrides this (see Spree::Payment,
+      # Spree::Variant); the genuinely global records — a customer, an
+      # address — fall through to the current request's store, since their
+      # fields still belong to one.
+      #
+      # Override rather than extending a chain here: which owner holds the
+      # store is the host's own fact, and a chain of `try`s silently answers
+      # for the wrong one when a host matches none of its steps.
+      #
+      # @return [Spree::Store]
+      # @raise [ArgumentError] when none is available.
+      def custom_field_definition_store
+        store = try(:store) || Spree::Current.store
+        raise ArgumentError, 'a store is required to resolve a custom field definition' if store.nil?
+
+        store
+      end
+    end
+  end
+end

data/app/models/concerns/spree/has_external_references.rb

@@ -0,0 +1,95 @@
+module Spree
+  # Gives a model identities in external systems (ERP, PIM, DAM, CRM) through
+  # {Spree::ExternalReference}. Opt-in per resource rather than on
+  # {Spree::Base}: only records a connector actually syncs need the association.
+  module HasExternalReferences
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :external_references, class_name: 'Spree::ExternalReference', as: :resource, dependent: :destroy
+
+      # Scope-friendly so controllers can chain it onto an already store-scoped
+      # relation: `current_store.products.with_external_id('erp', 'MAT-100')`.
+      # Scoping the lookup to the store is the caller's job, exactly as with any
+      # other id coming off a request.
+      scope :with_external_id, lambda { |system, external_id|
+        joins(:external_references).where(
+          spree_external_references: {
+            system: Spree::ExternalReference.normalize_system(system),
+            external_id: external_id.to_s.strip
+          }
+        )
+      }
+    end
+
+    # @param system [String, Symbol] the external system's key
+    # @return [String, nil] the identifier that system knows this record by
+    def external_id_for(system)
+      key = Spree::ExternalReference.normalize_system(system)
+
+      if external_references.loaded?
+        external_references.detect { |reference| reference.system == key }&.external_id
+      else
+        external_references.for_system(key).pick(:external_id)
+      end
+    end
+
+    # Creates or updates this record's identity in one external system.
+    #
+    # @param system [String, Symbol] the external system's key
+    # @param external_id [String, nil] blank removes the reference
+    # @param metadata [Hash, nil] connector bookkeeping (version, etag, synced at)
+    # @return [Spree::ExternalReference, nil] nil when the reference was removed
+    def set_external_id(system, external_id, metadata: nil)
+      key = Spree::ExternalReference.normalize_system(system)
+      reference = external_references.for_system(key).first
+
+      if external_id.to_s.strip.blank?
+        reference&.destroy
+        external_references.reset
+        return nil
+      end
+
+      reference ||= external_references.build(system: key)
+      reference.external_id = external_id
+      reference.metadata = metadata if metadata.present?
+      reference.store ||= external_reference_store
+      # A connector re-sending what it read is the steady state; an unchanged
+      # reference must not pay the two uniqueness SELECTs a save costs.
+      reference.save! if reference.new_record? || reference.changed?
+      # Reset rather than reload: the next reader refetches, and a batch of
+      # writes pays for one SELECT at the end instead of one per system.
+      external_references.reset
+      reference
+    end
+
+    # Writes several references at once, leaving systems the payload does not
+    # mention untouched — a connector states its own key without disturbing
+    # another system's. Accepts the `{ system => external_id }` map the admin
+    # serializers render, or a list of `{ system:, external_id: }` entries.
+    #
+    # @param references [Hash{String,Symbol=>String}, Array<Hash>]
+    # @return [void]
+    def assign_external_references(references)
+      Spree::ExternalReference.normalize_references(references).each do |reference|
+        set_external_id(reference[:system], reference[:external_id], metadata: reference[:metadata])
+      end
+    end
+
+    private
+
+    # A reference belongs to the same store as the record it identifies.
+    #
+    # Store-owning models answer directly;
+    # variants and stock levels carry no store of their own and reach it
+    # through the product. Anything else is left nil here — the reference
+    # includes {Spree::SingleStoreResource}, whose ensure_store callback
+    # falls back to the request's store, and stating that fallback twice
+    # would let the two quietly diverge.
+    def external_reference_store
+      return store if respond_to?(:store) && store.present?
+
+      product.store if respond_to?(:product) && product&.store.present?
+    end
+  end
+end

data/app/models/concerns/spree/has_iso_geography.rb

@@ -0,0 +1,71 @@
+module Spree
+  # Geography as reference data (docs/plans/6.0-drop-country-state-models.md):
+  # a model stores ISO codes — `country_code`, and `state_code` where
+  # subdivisions matter — and reads them back as {Spree::Country} /
+  # {Spree::State} value objects.
+  #
+  #   class Spree::StockLocation < Spree.base_class
+  #     has_iso_geography
+  #   end
+  #
+  # Included into {Spree::Base}, so the macro is available on every model and
+  # nothing happens until one calls it. Callers assign codes — the macro
+  # defines no country=/state= object writers; a model that needs them
+  # ({Spree::Address}) layers its own on top.
+  module HasIsoGeography
+    extend ActiveSupport::Concern
+
+    # Matching compares stored codes verbatim, so 'us' has to become 'US'
+    # before it is written. Applied through +normalizes+, it also normalizes
+    # values passed to `where` queries against these columns.
+    UPCASE = ->(value) { value.presence&.to_s&.upcase }
+
+    class_methods do
+      # @param state [Boolean] whether the model also carries a `state_code` column
+      def has_iso_geography(state: true)
+        normalizes :country_code, with: UPCASE
+
+        # @return [Spree::Country, nil]
+        define_method(:country) do
+          Spree::Country.by_iso(country_code) if country_code.present?
+        end
+
+        # A code nothing recognises is rejected rather than stored: every
+        # consumer matches codes verbatim, so a bad one silently matches
+        # nothing. Gated on change so historical rows stay updatable even if
+        # the registry's curation shifts under them.
+        validate :country_code_must_resolve, if: -> { new_record? || will_save_change_to_country_code? }
+        define_method(:country_code_must_resolve) do
+          return if country_code.blank?
+
+          errors.add(:country_code, :invalid) if Spree::Country.by_iso(country_code).nil?
+        end
+        private :country_code_must_resolve
+
+        return unless state
+
+        normalizes :state_code, with: UPCASE
+
+        # @return [Spree::State, nil]
+        define_method(:state) do
+          Spree::State.resolve(country_code, state_code) if country_code.present? && state_code.present?
+        end
+
+        # A subdivision code is only meaningful within its country, so it is
+        # checked against the country's own list (retired codes resolve
+        # through their successors). Without a country there is nothing to
+        # check against — the code is left alone.
+        validate :state_code_must_resolve,
+                 if: -> { new_record? || will_save_change_to_state_code? || will_save_change_to_country_code? }
+        define_method(:state_code_must_resolve) do
+          return if state_code.blank? || country_code.blank?
+          # An unresolvable country already got its own error.
+          return if Spree::Country.by_iso(country_code).nil?
+
+          errors.add(:state_code, :invalid) if Spree::IsoData.subdivision_code(country_code, state_code).nil?
+        end
+        private :state_code_must_resolve
+      end
+    end
+  end
+end