From 42c2ec03a42c412fbd5bb291bf8d65cbc36a4706 Mon Sep 17 00:00:00 2001
From: Jamis Buck <jamis.buck@mongodb.com>
Date: Wed, 31 Jul 2024 14:58:35 -0600
Subject: [PATCH 1/3] MONGOID-5734 Custom polymorphic types (#5845)

* first pass at a global resolver registry

* tests

* fix problem with interpreting nested attribute data

* need to register subclasses, too

* raise custom exceptions when failing to resolve models

* fix specs to implement functional around(:context)

* trailing white space
---
 lib/config/locales/en.yml                     |  16 ++
 lib/mongoid/association/accessors.rb          |   3 +-
 lib/mongoid/association/nested/one.rb         |  15 +-
 .../association/referenced/belongs_to.rb      |  15 ++
 .../referenced/belongs_to/binding.rb          |   8 +-
 .../referenced/belongs_to/buildable.rb        |   2 +-
 .../association/referenced/has_many.rb        |  17 +-
 .../referenced/has_one/buildable.rb           |  11 +-
 .../referenced/with_polymorphic_criteria.rb   |  41 +++++
 lib/mongoid/attributes/nested.rb              |   3 +-
 lib/mongoid/composable.rb                     |   2 +
 lib/mongoid/document.rb                       |   1 +
 lib/mongoid/errors.rb                         |   3 +
 .../errors/unrecognized_model_alias.rb        |  53 ++++++
 lib/mongoid/errors/unrecognized_resolver.rb   |  27 +++
 lib/mongoid/errors/unregistered_class.rb      |  47 +++++
 lib/mongoid/identifiable.rb                   |  28 +++
 lib/mongoid/model_resolver.rb                 | 154 ++++++++++++++++
 lib/mongoid/traversable.rb                    |   3 +-
 .../associations/belongs_to_spec.rb           | 129 ++++++++++++++
 .../referenced/belongs_to/proxy_spec.rb       |   1 +
 .../association/referenced/belongs_to_spec.rb |  79 ++++++---
 .../referenced/has_many/buildable_spec.rb     |   4 +
 spec/mongoid/attributes/nested_spec.rb        |   1 +
 spec/mongoid/model_resolver_spec.rb           | 167 ++++++++++++++++++
 25 files changed, 787 insertions(+), 43 deletions(-)
 create mode 100644 lib/mongoid/association/referenced/with_polymorphic_criteria.rb
 create mode 100644 lib/mongoid/errors/unrecognized_model_alias.rb
 create mode 100644 lib/mongoid/errors/unrecognized_resolver.rb
 create mode 100644 lib/mongoid/errors/unregistered_class.rb
 create mode 100644 lib/mongoid/identifiable.rb
 create mode 100644 lib/mongoid/model_resolver.rb
 create mode 100644 spec/mongoid/model_resolver_spec.rb

diff --git a/lib/config/locales/en.yml b/lib/config/locales/en.yml
index 0b1394d172..723ae5b39b 100644
--- a/lib/config/locales/en.yml
+++ b/lib/config/locales/en.yml
@@ -626,6 +626,22 @@ en:
           resolution: "The _type field is a reserved one used by Mongoid to determine the
             class for instantiating an object. Please don't save data in this field or ensure
             that any values in this field correspond to valid models."
+        unrecognized_model_alias:
+          message: "Cannot find any model with type %{model_alias}"
+          summary: "A document is trying to load a polymorphic association, but the data refers to a type of object that can't be resolved (%{model_alias}). It might be that you've renamed the target class."
+          resolution: "Register the old name as an alias on the refactored target object, using `identify_as`. This will allow Mongoid to find the target type even if the name no longer matches what was stored in the database."
+        unrecognized_resolver:
+          message: "The model resolver %{resolver} was referenced, but never registered."
+          summary: "A polymorphic association has been configured to use a resolver
+            named %{resolver}, but that resolver has not yet been registered. This
+            might be a typo. Currently registered resolvers are: %{resolvers}."
+          resolution: "Register custom resolvers with
+            `Mongoid::ModelResolver.register_resolver` before attempting to query
+            a polymorphic association."
+        unregistered_class:
+          message: "The class %{klass} is not registered with the resolver %{resolver}."
+          summary: "A polymorphic association using the resolver %{resolver} has tried to link to a model of type %{klass}, but the resolver has no knowledge of any such model. This can happen if the association is configured to use a different resolver than the target mode."
+          resolution: "Make sure the target model is registered with the same resolver as the polymorphic association, using `identify_as`."
         unsaved_document:
           message: "Attempted to save %{document} before the parent %{base}."
           summary: "You cannot call create or create! through the
diff --git a/lib/mongoid/association/accessors.rb b/lib/mongoid/association/accessors.rb
index 16a5b0c0df..4c7524fc76 100644
--- a/lib/mongoid/association/accessors.rb
+++ b/lib/mongoid/association/accessors.rb
@@ -41,7 +41,8 @@ def __build__(name, object, association, selected_fields = nil)
       #
       # @return [ Proxy ] The association.
       def create_relation(object, association, selected_fields = nil)
-        type = @attributes[association.inverse_type]
+        key = @attributes[association.inverse_type]
+        type = key ? association.resolver.model_for(key) : nil
         target = if t = association.build(self, object, type, selected_fields)
           association.create_relation(self, t)
         else
diff --git a/lib/mongoid/association/nested/one.rb b/lib/mongoid/association/nested/one.rb
index 37a417838f..7c16ec2398 100644
--- a/lib/mongoid/association/nested/one.rb
+++ b/lib/mongoid/association/nested/one.rb
@@ -50,12 +50,25 @@ def initialize(association, attributes, options)
           @attributes = attributes.with_indifferent_access
           @association = association
           @options = options
-          @class_name = options[:class_name] ? options[:class_name].constantize : association.klass
+          @class_name = class_from(options[:class_name])
           @destroy = @attributes.delete(:_destroy)
         end
 
         private
 
+        # Coerces the argument into a class, or defaults to the association's class.
+        #
+        # @param [ String | Mongoid::Document | nil ] name_or_class the value to coerce
+        #
+        # @return [ Mongoid::Document ] the resulting class
+        def class_from(name_or_class)
+          case name_or_class
+          when nil, false then association.klass
+          when String then name_or_class.constantize
+          else name_or_class
+          end
+        end
+
         # Extracts and converts the id to the expected type.
         #
         # @return [ BSON::ObjectId | String | Object | nil ] The converted id,
diff --git a/lib/mongoid/association/referenced/belongs_to.rb b/lib/mongoid/association/referenced/belongs_to.rb
index 9409c63bc2..5bb1f83438 100644
--- a/lib/mongoid/association/referenced/belongs_to.rb
+++ b/lib/mongoid/association/referenced/belongs_to.rb
@@ -102,6 +102,21 @@ def polymorphic?
           @polymorphic ||= !!@options[:polymorphic]
         end
 
+        # Returns the object responsible for converting polymorphic type references into
+        # class objects, and vice versa. This is obtained via the `:polymorphic` option
+        # that was given when the association was defined.
+        #
+        # See Mongoid::ModelResolver.resolver for how the `:polymorphic` option is 
+        # interpreted here.
+        #
+        # @raise KeyError if no such resolver has been registered under the given
+        #   identifier.
+        #
+        # @return [ nil | Mongoid::ModelResolver ] the resolver to use
+        def resolver
+          @resolver ||= Mongoid::ModelResolver.resolver(@options[:polymorphic])
+        end
+
         # The name of the field used to store the type of polymorphic association.
         #
         # @return [ String ] The field used to store the type of polymorphic association.
diff --git a/lib/mongoid/association/referenced/belongs_to/binding.rb b/lib/mongoid/association/referenced/belongs_to/binding.rb
index 2ac07ab4d1..bb7053b754 100644
--- a/lib/mongoid/association/referenced/belongs_to/binding.rb
+++ b/lib/mongoid/association/referenced/belongs_to/binding.rb
@@ -22,7 +22,13 @@ def bind_one
             binding do
               check_polymorphic_inverses!(_target)
               bind_foreign_key(_base, record_id(_target))
-              bind_polymorphic_inverse_type(_base, _target.class.name)
+
+              # set the inverse type (e.g. "#{name}_type") for new polymorphic associations
+              if _association.inverse_type && !_base.frozen?
+                key = _association.resolver.default_key_for(_target)
+                bind_polymorphic_inverse_type(_base, key)
+              end
+
               if inverse = _association.inverse(_target)
                 if set_base_association
                   if _base.referenced_many?
diff --git a/lib/mongoid/association/referenced/belongs_to/buildable.rb b/lib/mongoid/association/referenced/belongs_to/buildable.rb
index e59b40d1f4..79fe0d4788 100644
--- a/lib/mongoid/association/referenced/belongs_to/buildable.rb
+++ b/lib/mongoid/association/referenced/belongs_to/buildable.rb
@@ -32,7 +32,7 @@ def execute_query(object, type)
           end
 
           def query_criteria(object, type)
-            cls = type ? type.constantize : relation_class
+            cls = type ? (type.is_a?(String) ? type.constantize : type) : relation_class
             crit = cls.criteria
             crit = crit.apply_scope(scope)
             crit.where(primary_key => object)
diff --git a/lib/mongoid/association/referenced/has_many.rb b/lib/mongoid/association/referenced/has_many.rb
index a8c9f9fa6d..cebd53809b 100644
--- a/lib/mongoid/association/referenced/has_many.rb
+++ b/lib/mongoid/association/referenced/has_many.rb
@@ -5,6 +5,7 @@
 require 'mongoid/association/referenced/has_many/proxy'
 require 'mongoid/association/referenced/has_many/enumerable'
 require 'mongoid/association/referenced/has_many/eager'
+require 'mongoid/association/referenced/with_polymorphic_criteria'
 
 module Mongoid
   module Association
@@ -14,6 +15,7 @@ module Referenced
       class HasMany
         include Relatable
         include Buildable
+        include WithPolymorphicCriteria
 
         # The options available for this type of association, in addition to the
         # common ones.
@@ -130,6 +132,12 @@ def type
         # @param [ Class ] object_class The object class.
         #
         # @return [ Mongoid::Criteria ] The criteria object.
+        #
+        # @deprecated in 9.0.x
+        #
+        # It appears as if this method is an artifact left over from a refactoring that renamed it
+        # `with_polymorphic_criterion`, and made it private. Regardless, this method isn't referenced
+        # anywhere else, and is unlikely to be useful to external clients. We should remove it.
         def add_polymorphic_criterion(criteria, object_class)
           if polymorphic?
             criteria.where(type => object_class.name)
@@ -137,6 +145,7 @@ def add_polymorphic_criterion(criteria, object_class)
             criteria
           end
         end
+        Mongoid.deprecate(self, :add_polymorphic_criterion)
 
         # Is this association polymorphic?
         #
@@ -221,14 +230,6 @@ def query_criteria(object, base)
           with_ordering(crit)
         end
 
-        def with_polymorphic_criterion(criteria, base)
-          if polymorphic?
-            criteria.where(type => base.class.name)
-          else
-            criteria
-          end
-        end
-
         def with_ordering(criteria)
           if order
             criteria.order_by(order)
diff --git a/lib/mongoid/association/referenced/has_one/buildable.rb b/lib/mongoid/association/referenced/has_one/buildable.rb
index f23e3b2f3b..66dd27ca27 100644
--- a/lib/mongoid/association/referenced/has_one/buildable.rb
+++ b/lib/mongoid/association/referenced/has_one/buildable.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'mongoid/association/referenced/with_polymorphic_criteria'
+
 module Mongoid
   module Association
     module Referenced
@@ -7,6 +9,7 @@ class HasOne
 
         # The Builder behavior for has_one associations.
         module Buildable
+          include WithPolymorphicCriteria
 
           # This method either takes an _id or an object and queries for the
           # inverse side using the id or sets the object after clearing the
@@ -56,14 +59,6 @@ def execute_query(object, base)
             query_criteria(object, base).take
           end
 
-          def with_polymorphic_criterion(criteria, base)
-            if polymorphic?
-              criteria.where(type => base.class.name)
-            else
-              criteria
-            end
-          end
-
           def query?(object)
             object && !object.is_a?(Mongoid::Document)
           end
diff --git a/lib/mongoid/association/referenced/with_polymorphic_criteria.rb b/lib/mongoid/association/referenced/with_polymorphic_criteria.rb
new file mode 100644
index 0000000000..ce21f2df32
--- /dev/null
+++ b/lib/mongoid/association/referenced/with_polymorphic_criteria.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Referenced
+      # Implements the `with_polymorphic_criteria` shared behavior.
+      #
+      # @api private
+      module WithPolymorphicCriteria
+        # If the receiver represents a polymorphic association, applies
+        # the polymorphic search criteria to the given `criteria` object.
+        #
+        # @param [ Mongoid::Criteria ] criteria the criteria to append to
+        #   if receiver is polymorphic.
+        # @param [ Mongoid::Document ] base the document to use when resolving
+        #   the polymorphic type keys.
+        #
+        # @return [ Mongoid::Criteria] the resulting criteria, which may be
+        #   the same as the input.
+        def with_polymorphic_criterion(criteria, base)
+          if polymorphic?
+            # 1. get the resolver for the inverse association
+            resolver = klass.reflect_on_association(as).resolver
+
+            # 2. look up the list of keys from the resolver, given base
+            keys = resolver.keys_for(base)
+
+            # 3. use equality if there is just one key, `in` if there are multiple
+            if keys.many?
+              criteria.where(type => { :$in => keys })
+            else
+              criteria.where(type => keys.first)
+            end
+          else
+            criteria
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/attributes/nested.rb b/lib/mongoid/attributes/nested.rb
index 1e70b31533..f120a1c5e6 100644
--- a/lib/mongoid/attributes/nested.rb
+++ b/lib/mongoid/attributes/nested.rb
@@ -59,7 +59,8 @@ def accepts_nested_attributes_for(*args)
             re_define_method(meth) do |attrs|
               _assigning do
                 if association.polymorphic? and association.inverse_type
-                  options = options.merge!(:class_name => self.send(association.inverse_type))
+                  klass = association.resolver.model_for(send(association.inverse_type))
+                  options = options.merge!(:class_name => klass)
                 end
                 association.nested_builder(attrs, options).build(self)
               end
diff --git a/lib/mongoid/composable.rb b/lib/mongoid/composable.rb
index 4e8d08f68a..60dc8c9294 100644
--- a/lib/mongoid/composable.rb
+++ b/lib/mongoid/composable.rb
@@ -3,6 +3,7 @@
 require "mongoid/changeable"
 require "mongoid/collection_configurable"
 require "mongoid/findable"
+require 'mongoid/identifiable'
 require "mongoid/indexable"
 require "mongoid/inspectable"
 require "mongoid/interceptable"
@@ -41,6 +42,7 @@ module Composable
     include Attributes
     include Evolvable
     include Fields
+    include Identifiable
     include Indexable
     include Inspectable
     include Matchable
diff --git a/lib/mongoid/document.rb b/lib/mongoid/document.rb
index 3c30ccfed2..bf61bc37dc 100644
--- a/lib/mongoid/document.rb
+++ b/lib/mongoid/document.rb
@@ -32,6 +32,7 @@ module Document
 
     included do
       Mongoid.register_model(self)
+      Mongoid::ModelResolver.register(self)
     end
 
     # Regex for matching illegal BSON keys.
diff --git a/lib/mongoid/errors.rb b/lib/mongoid/errors.rb
index 4042593bb9..c3363e47f2 100644
--- a/lib/mongoid/errors.rb
+++ b/lib/mongoid/errors.rb
@@ -59,6 +59,9 @@
 require "mongoid/errors/too_many_nested_attribute_records"
 require "mongoid/errors/unknown_attribute"
 require "mongoid/errors/unknown_model"
+require 'mongoid/errors/unrecognized_model_alias'
+require 'mongoid/errors/unrecognized_resolver'
+require 'mongoid/errors/unregistered_class'
 require "mongoid/errors/unsaved_document"
 require "mongoid/errors/unsupported_javascript"
 require "mongoid/errors/validations"
diff --git a/lib/mongoid/errors/unrecognized_model_alias.rb b/lib/mongoid/errors/unrecognized_model_alias.rb
new file mode 100644
index 0000000000..46392b3651
--- /dev/null
+++ b/lib/mongoid/errors/unrecognized_model_alias.rb
@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when a polymorphic association is queried, but the type of the
+    # association cannot be resolved. This usually happens when the data in
+    # the database references a type that no longer exists.
+    #
+    # For example, consider the following model:
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: true
+    #   end
+    #
+    # Imagine there is a document in the `managers` collection that looks
+    # something like this:
+    #
+    #   { _id: ..., unit_id: ..., unit_type: 'Department::Engineering' }
+    #
+    # If, at some point in your refactoring, you rename the `Department::Engineering`
+    # model to something else, Mongoid will no longer be able to resolve the
+    # type of this association, and asking for `manager.unit` will raise this
+    # exception.
+    #
+    # To fix this exception, you can add an alias to the model class so that it
+    # can still be found, even after renaming it:
+    #
+    #   module Engineering
+    #     class Department
+    #       include Mongoid::Document
+    #
+    #       identify_as 'Department::Engineering'
+    #
+    #       # ...
+    #     end
+    #   end
+    #
+    # Better practice would be to use unique strings instead of class names to
+    # identify these polymorphic types in the database (e.g. 'dept' instead of
+    # 'Department::Engineering').
+    class UnrecognizedModelAlias < MongoidError
+      def initialize(model_alias)
+        super(
+          compose_message(
+            'unrecognized_model_alias',
+            model_alias: model_alias.inspect
+          )
+        )
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/errors/unrecognized_resolver.rb b/lib/mongoid/errors/unrecognized_resolver.rb
new file mode 100644
index 0000000000..c4d29614ba
--- /dev/null
+++ b/lib/mongoid/errors/unrecognized_resolver.rb
@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when a model resolver is referenced, but not registered.
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: :org
+    #   end
+    #
+    # If `:org` has not previously been registered as a model resolver,
+    # Mongoid will raise UnrecognizedResolver when it tries to resolve
+    # a manager's unit.
+    class UnrecognizedResolver < MongoidError
+      def initialize(resolver)
+        super(
+          compose_message(
+            'unrecognized_resolver',
+            resolver: resolver.inspect,
+            resolvers: [ :default, *Mongoid::ModelResolver.resolvers.keys ].inspect
+          )
+        )
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/errors/unregistered_class.rb b/lib/mongoid/errors/unregistered_class.rb
new file mode 100644
index 0000000000..15432a9747
--- /dev/null
+++ b/lib/mongoid/errors/unregistered_class.rb
@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+    # Raised when Mongoid tries to query the identifier to use for a given
+    # class in a polymorphic association, but the class has not previously
+    # been registered by resolver that was used for the query.
+    #
+    # Here's an exammple:
+    #
+    #   class Department
+    #     include Mongoid::Document
+    #     has_many :managers, as: :unit
+    #   end
+    #
+    #   class Manager
+    #     include Mongoid::Document
+    #     belongs_to :unit, polymorphic: :org
+    #   end
+    #
+    # The Manager class is configured to use a custom resolver named `:org`
+    # when resolving the polymorphic `unit` association. However, the `Department`
+    # class is not registered with that resolver. When the program tries to
+    # associate a manager record with a department, it will not be able to find
+    # the required key in the `:org` resolver, and will fail with this exception.
+    #
+    # The solution is to make sure the `Department` class is properly registered
+    # with the `:org` resolver:
+    #
+    #   class Department
+    #     include Mongoid::Document
+    #     identify_as resolver: :org
+    #     has_many :managers, as: :unit
+    #   end
+    class UnregisteredClass < MongoidError
+      def initialize(klass, resolver)
+        super(
+          compose_message(
+            'unregistered_class',
+            klass: klass,
+            resolver: resolver.inspect
+          )
+        )
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/identifiable.rb b/lib/mongoid/identifiable.rb
new file mode 100644
index 0000000000..b7e9e3484b
--- /dev/null
+++ b/lib/mongoid/identifiable.rb
@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'mongoid/model_resolver'
+
+module Mongoid
+  # Implements the "identify_as" interface (for specifying type aliases
+  # for document classes).
+  module Identifiable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Specifies aliases that may be used to identify this document
+      # class in polymorphic situations. By default, classes are identified
+      # by their class names, but alternative aliases may be used instead,
+      # if desired.
+      #
+      # @param [ Array<String | Symbol> ] aliases the list of aliases to
+      #   assign to this class.
+      # @param [ Mongoid::ModelResolver::Interface | Symbol | :default ] resolver the
+      #   resolver instance to use when registering the type. If :default, the default
+      #   `ModelResolver` instance will be used. If any other symbol, it must identify a
+      #   previously registered ModelResolver instance.
+      def identify_as(*aliases, resolver: :default)
+        Mongoid::ModelResolver.resolver(resolver).register(self, *aliases)
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/model_resolver.rb b/lib/mongoid/model_resolver.rb
new file mode 100644
index 0000000000..b5cd11a1ab
--- /dev/null
+++ b/lib/mongoid/model_resolver.rb
@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Mongoid
+  # The default class for resolving model classes based on discriminant keys.
+  # Given a key, it will return the corresponding model class, if any. By
+  # default, it looks for classes with names that match the given keys, but
+  # additional mappings may be provided.
+  #
+  # It is also possible to instantiate multiple resolvers---and even implement
+  # your own---so that different sets of classes can use independent resolution
+  # mechanics.
+  class ModelResolver
+    # The mutex instance used to make the `.instance` method thread-safe.
+    #
+    # @api private
+    INSTANCE_MUTEX = Mutex.new
+
+    class << self
+      extend Forwardable
+      def_delegators :instance, :register
+
+      # Returns the default instance of the ModelResolver.
+      #
+      # @return [ Mongoid::ModelResolver ] the default ModelResolver instance.
+      def instance
+        @instance ||= INSTANCE_MUTEX.synchronize { @instance ||= new }
+      end
+
+      # Returns the map of registered resolvers. The default resolver is not
+      # included here.
+      #
+      # @return [ Hash<Symbol => Mongoid::ModelResolver::Interface> ] the hash of
+      #   resolver instances, mapped by symbol identifier.
+      def resolvers
+        @resolvers ||= {}
+      end
+
+      # Returns the resolver instance that corresponds to the argument.
+      #
+      # @param [ nil | true | false Symbol | String | Mongoid::ModelResolver::Interface ] identifier_or_object
+      #   When nil or false, returns nil. When true or :default, corresponds to the default resolver.
+      #   When any other symbol or string, corresponds to the registered resolver with that identifier.
+      #   Otherwise, it must be a resolver instance itself.
+      #
+      # @raise Mongoid::Errors::UnrecognizedResolver if the given identifier is a
+      #   symbol or string and it does not match any registered resolver.
+      #
+      # @return [ Mongoid::ModelResolver::Interface ] the resolver instance corresponding to the
+      #   given argument.
+      def resolver(identifier_or_object = :default)
+        case identifier_or_object
+        when nil, false then nil
+        when true, :default then instance
+        when String, Symbol
+          resolvers.fetch(identifier_or_object.to_sym) do |key|
+            raise Mongoid::Errors::UnrecognizedResolver, key
+          end
+        else identifier_or_object
+        end
+      end
+
+      # Register the given resolver under the given name.
+      #
+      # @param [ Mongoid::ModelResolver::Interface ] resolver the resolver to register.
+      # @param [ String | Symbol ] name the identifier to use to register the resolver.
+      def register_resolver(resolver, name)
+        resolvers[name.to_sym] = resolver
+        self
+      end
+    end
+
+    # Instantiates a new ModelResolver instance.
+    def initialize
+      @key_to_model = {}
+      @model_to_keys = {}
+    end
+
+    # Registers the given model class with the given keys. In addition to the given keys, the
+    # class name itself will be included as a key to identify the class. Keys are given in priority
+    # order, with highest priority keys first and lowest last. The class name, if not given explicitly,
+    # is always given lowest priority.
+    #
+    # If called more than once, newer keys have higher priority than older keys. All duplicate keys will
+    # be removed.
+    #
+    # @param [ Mongoid::Document ] klass the document class to register
+    # @param [ Array<String> ] *keys the list of keys to use as an alias (optional)
+    def register(klass, *keys)
+      default_key = klass.name
+
+      @model_to_keys[klass] = [ *keys, *@model_to_keys[klass], default_key ].uniq
+      @key_to_model[default_key] = klass
+
+      keys.each do |key|
+        @key_to_model[key] = klass
+      end
+
+      self
+    end
+
+    # The `Interface` concern represents the interface that custom resolvers
+    # must implement.
+    concerning :Interface do
+      # Returns the default (highest priority) key for the given record. This is typically
+      # the key that will be used when saving a new polymorphic association.
+      #
+      # @param [ Mongoid::Document ] record the record instance for which to query the default key.
+      #
+      # @raise Mongoid::Errors::UnregisteredClass if the record's class has not been registered with this resolver.
+      #
+      # @return [ String ] the default key for the record's class.
+      def default_key_for(record)
+        keys_for(record).first
+      end
+
+      # Returns the list of all keys for the given record's class, in priority order (with highest
+      # priority keys first).
+      #
+      # @param [ Mongoid::Document] record the record instance for which to query the registered keys.
+      #
+      # @raise Mongoid::Errors::UnregisteredClass if the record's class has not been registered with this resolver.
+      #
+      # @return [ Array<String> ] the list of keys that have been registered for the given class.
+      def keys_for(record)
+        @model_to_keys.fetch(record.class) do |klass|
+          # figure out which resolver this is
+          resolver = if self == Mongoid::ModelResolver.instance
+                       :default
+                     else
+                       Mongoid::ModelResolver.resolvers.keys.detect { |k| Mongoid::ModelResolver.resolvers[k] == self }
+                     end
+          resolver ||= self # if it hasn't been registered, we'll show it the best we can
+          raise Mongoid::Errors::UnregisteredClass.new(klass, resolver)
+        end
+      end
+
+      # Returns the document class that has been registered by the given key.
+      #
+      # @param [ String ] key the key by which to query the corresponding class.
+      #
+      # @raise Mongoid::Errors::UnrecognizedModelAlias if the given key has not
+      #   been registered with this resolver.
+      #
+      # @return [ Class ] the document class that has been registered with the given key.
+      def model_for(key)
+        @key_to_model.fetch(key) do
+          raise Mongoid::Errors::UnrecognizedModelAlias, key
+        end
+      end
+    end
+  end
+end
diff --git a/lib/mongoid/traversable.rb b/lib/mongoid/traversable.rb
index ee0ca440da..a13de934fb 100644
--- a/lib/mongoid/traversable.rb
+++ b/lib/mongoid/traversable.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "mongoid/fields/validators/macro"
+require 'mongoid/fields/validators/macro'
+require 'mongoid/model_resolver'
 
 module Mongoid
 
diff --git a/spec/integration/associations/belongs_to_spec.rb b/spec/integration/associations/belongs_to_spec.rb
index 7b08e0b4b9..efce75adbe 100644
--- a/spec/integration/associations/belongs_to_spec.rb
+++ b/spec/integration/associations/belongs_to_spec.rb
@@ -1,8 +1,40 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'support/feature_sandbox'
+
 require_relative '../../mongoid/association/referenced/has_one_models'
 
+def quarantine(context, polymorphic:, dept_aliases:, team_aliases:)
+  state = {}
+
+  context.before(:context) do
+    state[:quarantine] = FeatureSandbox.start_quarantine
+
+    # Have to eval this, because otherwise we get syntax errors when defining a class
+    # inside a method.
+    #
+    # I know the scissors are sharp! But I want to run with them anwyay!
+    Object.class_eval <<-RUBY
+      class SandboxManager; include Mongoid::Document; end
+      class SandboxDepartment; include Mongoid::Document; end
+      class SandboxTeam; include Mongoid::Document; end
+    RUBY
+
+    SandboxManager.belongs_to :unit, polymorphic: polymorphic
+
+    SandboxDepartment.identify_as *dept_aliases, resolver: polymorphic
+    SandboxDepartment.has_many :sandbox_managers, as: :unit
+
+    SandboxTeam.identify_as *team_aliases, resolver: polymorphic
+    SandboxTeam.has_one :sandbox_manager, as: :unit
+  end
+
+  context.after(:context) do
+    FeatureSandbox.end_quarantine(state[:quarantine])
+  end
+end
+
 describe 'belongs_to associations' do
   context 'referencing top level classes when source class is namespaced' do
     let(:college) { HomCollege.create! }
@@ -30,4 +62,101 @@
       expect(instance.movie).to eq movie
     end
   end
+
+  context 'when the association is polymorphic' do
+    let(:dept_manager) { SandboxManager.create(unit: department) }
+    let(:team_manager) { SandboxManager.create(unit: team) }
+    let(:department) { SandboxDepartment.create }
+    let(:team) { SandboxTeam.create }
+
+    shared_context 'it finds the associated records' do
+      it 'successfully finds the manager\'s unit' do
+        expect(dept_manager.reload.unit).to be == department
+        expect(team_manager.reload.unit).to be == team
+      end
+
+      it 'successfully finds the unit\'s manager' do
+        dept_manager; team_manager # make sure these are created first...
+
+        expect(department.reload.sandbox_managers).to be == [ dept_manager ]
+        expect(team.reload.sandbox_manager).to be == team_manager
+      end
+    end
+
+    shared_context 'it searches for alternative aliases' do
+      it 'successfully finds the corresponding unit when unit_type is a different alias' do
+        dept_manager.update unit_type: 'sandbox_dept'
+        dept_manager.reload
+
+        team_manager.update unit_type: 'group'
+        team_manager.reload
+
+        expect(dept_manager.reload.unit_type).to be == 'sandbox_dept'
+        expect(dept_manager.unit).to be == department
+
+        expect(team_manager.reload.unit_type).to be == 'group'
+        expect(team_manager.unit).to be == team
+      end
+    end
+
+    context 'when the association uses the default resolver' do
+      context 'when there are no aliases given' do
+        quarantine(self, polymorphic: true, dept_aliases: [], team_aliases: [])
+
+        it 'populates the unit_type with the class name' do
+          expect(dept_manager.unit_type).to be == 'SandboxDepartment'
+          expect(team_manager.unit_type).to be == 'SandboxTeam'
+        end
+
+        it_behaves_like 'it finds the associated records'
+      end
+
+      context 'when there are multiple aliases given' do
+        quarantine(self, polymorphic: true, dept_aliases: %w[ dept sandbox_dept ], team_aliases: %w[ team group ])
+
+        it 'populates the unit_type with the first alias' do
+          expect(dept_manager.unit_type).to be == 'dept'
+          expect(team_manager.unit_type).to be == 'team'
+        end
+
+        it_behaves_like 'it finds the associated records'
+        it_behaves_like 'it searches for alternative aliases'
+      end
+    end
+
+    context 'when the association uses a registered resolver' do
+      before(:context) { Mongoid::ModelResolver.register_resolver Mongoid::ModelResolver.new, :sandbox }
+      quarantine(self, polymorphic: :sandbox, dept_aliases: %w[ dept sandbox_dept ], team_aliases: %w[ team group ])
+
+      it 'does not include the aliases in the default resolver' do
+        expect(Mongoid::ModelResolver.instance.keys_for(SandboxDepartment.new)).not_to include('dept')
+      end
+
+      it 'populates the unit_type with the first alias' do
+        expect(dept_manager.unit_type).to be == 'dept'
+        expect(team_manager.unit_type).to be == 'team'
+      end
+
+      it_behaves_like 'it finds the associated records'
+      it_behaves_like 'it searches for alternative aliases'
+    end
+
+    context 'when the association uses an unregistered resolver' do
+      quarantine(self, polymorphic: Mongoid::ModelResolver.new,
+        dept_aliases: %w[ dept sandbox_dept ],
+        team_aliases: %w[ team group ])
+
+      it 'does not include the aliases in the default resolver' do
+        expect(Mongoid::ModelResolver.instance.keys_for(SandboxDepartment.new)).not_to include('dept')
+      end
+
+      it 'populates the unit_type with the first alias' do
+        expect(dept_manager.unit_type).to be == 'dept'
+        expect(team_manager.unit_type).to be == 'team'
+      end
+
+      it_behaves_like 'it finds the associated records'
+      it_behaves_like 'it searches for alternative aliases'
+    end
+  end
 end
diff --git a/spec/mongoid/association/referenced/belongs_to/proxy_spec.rb b/spec/mongoid/association/referenced/belongs_to/proxy_spec.rb
index d19a69a372..1e1b43f547 100644
--- a/spec/mongoid/association/referenced/belongs_to/proxy_spec.rb
+++ b/spec/mongoid/association/referenced/belongs_to/proxy_spec.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "spec_helper"
+require 'support/models/canvas'
 require_relative '../belongs_to_models.rb'
 
 describe Mongoid::Association::Referenced::BelongsTo::Proxy do
diff --git a/spec/mongoid/association/referenced/belongs_to_spec.rb b/spec/mongoid/association/referenced/belongs_to_spec.rb
index 5bd4867d7d..1fe655095f 100644
--- a/spec/mongoid/association/referenced/belongs_to_spec.rb
+++ b/spec/mongoid/association/referenced/belongs_to_spec.rb
@@ -3,6 +3,10 @@
 require "spec_helper"
 require_relative './has_one_models'
 
+BELONGS_TO_RESOLVER_ID__ = :__belongs_to_resolver_id
+BELONGS_TO_RESOLVER = Mongoid::ModelResolver.new
+Mongoid::ModelResolver.register_resolver BELONGS_TO_RESOLVER, BELONGS_TO_RESOLVER_ID__
+
 describe Mongoid::Association::Referenced::BelongsTo do
 
   before do
@@ -198,47 +202,76 @@ class BelongingObject; include Mongoid::Document; end
 
       context 'when the polymorphic option is provided' do
 
-        context 'when the polymorphic option is true' do
+        [ true, :default ].each do |opt|
+          context "when the polymorphic option is #{opt.inspect}" do
+            let(:options) { { polymorphic: opt } }
+            before { association }
 
-          let(:options) do
-            {
-              polymorphic: true
-            }
+            it 'set the polymorphic attribute on the owner class' do
+              expect(belonging_class.polymorphic).to be(true)
+            end
+
+            it 'sets up a field for the inverse type' do
+              expect(belonging_class.fields.keys).to include(association.inverse_type)
+            end
+
+            it 'uses the default resolver' do
+              expect(association.resolver).to be == Mongoid::ModelResolver.instance
+            end
           end
+        end
 
-          before do
-            association
+        [ false, nil ].each do |opt|
+          context "when the polymorphic option is #{opt.inspect}" do
+            let(:options) { { polymorphic: opt } }
+
+            it 'does not set the polymorphic attribute on the owner class' do
+              expect(belonging_class.polymorphic).to be(false)
+            end
+
+            it 'does not set up a field for the inverse type' do
+              expect(belonging_class.fields.keys).not_to include(association.inverse_type)
+            end
+
+            it 'does not use a resolver' do
+              expect(association.resolver).to be_nil
+            end
           end
+        end
 
-          it 'set the polymorphic attribute on the owner class' do
-            expect(belonging_class.polymorphic).to be(true)
+        context 'when the polymorphic option is set to an unregistered id' do
+          let(:options) { { polymorphic: :bogus } }
+
+          # This behavior is intentional, so that the resolver can be registered after the classes
+          # are loaded.
+          it 'does not immediately raise an exception' do
+            expect { association }.not_to raise_error
           end
 
-          it 'sets up a field for the inverse type' do
-            expect(belonging_class.fields.keys).to include(association.inverse_type)
+          it 'raises error when resolver is accessed' do
+            expect { association.resolver }.to raise_error(Mongoid::Errors::UnrecognizedResolver)
           end
         end
 
-        context 'when the polymorphic option is false' do
+        context 'when the polymorphic option is set to a registered id' do
+          let(:options) { { polymorphic: BELONGS_TO_RESOLVER_ID__ } }
+          before { association }
 
-          let(:options) do
-            {
-              polymorphic: false
-            }
+          it 'set the polymorphic attribute on the owner class' do
+            expect(belonging_class.polymorphic).to be(true)
           end
 
-          it 'does not set the polymorphic attribute on the owner class' do
-            expect(belonging_class.polymorphic).to be(false)
+          it 'sets up a field for the inverse type' do
+            expect(belonging_class.fields.keys).to include(association.inverse_type)
           end
 
-          it 'does not set up a field for the inverse type' do
-            expect(belonging_class.fields.keys).not_to include(association.inverse_type)
+          it 'connects the association to the corresponding resolver' do
+            expect(association.resolver).to be == BELONGS_TO_RESOLVER
           end
         end
       end
 
       context 'when the polymorphic option is not provided' do
-
         it 'does not set the polymorphic attribute on the owner class' do
           expect(belonging_class.polymorphic).to be(false)
         end
@@ -246,6 +279,10 @@ class BelongingObject; include Mongoid::Document; end
         it 'does not set up a field for the inverse type' do
           expect(belonging_class.fields.keys).not_to include(association.inverse_type)
         end
+
+        it 'does not use a resolver' do
+          expect(association.resolver).to be_nil
+        end
       end
     end
 
diff --git a/spec/mongoid/association/referenced/has_many/buildable_spec.rb b/spec/mongoid/association/referenced/has_many/buildable_spec.rb
index 73b6d27d14..335c4b1ac3 100644
--- a/spec/mongoid/association/referenced/has_many/buildable_spec.rb
+++ b/spec/mongoid/association/referenced/has_many/buildable_spec.rb
@@ -99,6 +99,10 @@
         Post.where(association.foreign_key => object, 'ratable_type' => 'Rating')
       end
 
+      before do
+        Post.belongs_to :ratable, polymorphic: true
+      end
+
       it "adds the type to the criteria" do
         expect(documents).to eq(criteria)
       end
diff --git a/spec/mongoid/attributes/nested_spec.rb b/spec/mongoid/attributes/nested_spec.rb
index 577a801349..bcf9b29a1f 100644
--- a/spec/mongoid/attributes/nested_spec.rb
+++ b/spec/mongoid/attributes/nested_spec.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "spec_helper"
+require 'support/models/sandwich'
 require_relative '../association/referenced/has_many_models'
 require_relative '../association/referenced/has_and_belongs_to_many_models'
 require_relative './nested_spec_models'
diff --git a/spec/mongoid/model_resolver_spec.rb b/spec/mongoid/model_resolver_spec.rb
new file mode 100644
index 0000000000..8b8c3c6b79
--- /dev/null
+++ b/spec/mongoid/model_resolver_spec.rb
@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'support/feature_sandbox'
+
+MONGOID_MODEL_RESOLVER_KEY__ = :__separate_instance_spec_key
+Mongoid::ModelResolver.register_resolver Mongoid::ModelResolver.new, MONGOID_MODEL_RESOLVER_KEY__
+
+def quarantine(context, &block)
+  state = {}
+
+  context.before(:context) do
+    state[:quarantine] = FeatureSandbox.start_quarantine
+    block&.call
+  end
+
+  context.after(:context) do
+    FeatureSandbox.end_quarantine(state[:quarantine])
+  end
+end
+
+describe Mongoid::ModelResolver do
+  shared_examples 'a resolver' do |**kwargs|
+    it 'includes the class name when asked for all keys of the given model' do
+      expect(resolver.keys_for(model_class.new)).to include(model_class.name)
+    end
+
+    if kwargs[:with_aliases].nil?
+      it 'uses the class name as the default key for the given model' do
+        expect(resolver.default_key_for(model_class.new)).to eq model_class.name
+      end
+    elsif kwargs[:with_aliases].is_a?(Array)
+      it 'uses the first alias as the default key for the given model' do
+        expect(resolver.default_key_for(model_class.new)).to eq kwargs[:with_aliases].first
+      end
+    else
+      it 'uses the alias as the default key for the given model' do
+        expect(resolver.default_key_for(model_class.new)).to eq kwargs[:with_aliases]
+      end
+    end
+
+    it 'returns the model class when queried with the class name' do
+      expect(resolver.model_for(model_class.name)).to eq model_class
+    end
+
+    Array(kwargs[:with_aliases]).each do |model_alias|
+      it "includes the alias #{model_alias.inspect} when asked for all keys of the given model" do
+        expect(resolver.keys_for(model_class.new)).to include(model_alias)
+      end
+
+      it "returns the model class when queried with #{model_alias.inspect}" do
+        expect(resolver.model_for(model_alias)).to eq model_class
+      end
+    end
+  end
+
+  context 'when using the default instance' do
+    let(:resolver) { described_class.instance }
+
+    context 'when an alias is not specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module DefaultInstance
+            class Vanilla; include Mongoid::Document; end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::DefaultInstance::Vanilla }
+
+      it_behaves_like 'a resolver'
+    end
+
+    context 'when one alias is specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module DefaultInstance
+            class Aliased
+              include Mongoid::Document
+              identify_as 'aliased'
+            end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::DefaultInstance::Aliased }
+
+      it_behaves_like 'a resolver', with_aliases: 'aliased'
+    end
+
+    context 'when multiple aliases are specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module DefaultInstance
+            class AliasedMultiple
+              include Mongoid::Document
+              identify_as 'aliased', 'alias2', 'alias3'
+            end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::DefaultInstance::AliasedMultiple }
+
+      it_behaves_like 'a resolver', with_aliases: %w[ aliased alias2 alias3 ]
+    end
+  end
+
+  context 'when using a separate instance' do
+    let(:resolver) { described_class.resolver(MONGOID_MODEL_RESOLVER_KEY__) }
+
+    it 'does not refer to the default instance' do
+      expect(resolver).not_to eq described_class.instance
+    end
+
+    context 'when an alias is not specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module SeparateInstance
+            class Vanilla
+              include Mongoid::Document
+              identify_as resolver: MONGOID_MODEL_RESOLVER_KEY__
+            end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::SeparateInstance::Vanilla }
+
+      it_behaves_like 'a resolver'
+    end
+
+    context 'when one alias is specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module SeparateInstance
+            class Aliased
+              include Mongoid::Document
+              identify_as 'aliased', resolver: MONGOID_MODEL_RESOLVER_KEY__
+            end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::SeparateInstance::Aliased }
+
+      it_behaves_like 'a resolver', with_aliases: 'aliased'
+    end
+
+    context 'when multiple aliases are specified' do
+      quarantine(self) do
+        Object.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          module Mongoid; module Specs; module SeparateInstance
+            class AliasedMultiple
+              include Mongoid::Document
+              identify_as 'aliased', 'alias2', 'alias3', resolver: MONGOID_MODEL_RESOLVER_KEY__
+            end
+          end; end; end
+        RUBY
+      end
+
+      let(:model_class) { Mongoid::Specs::SeparateInstance::AliasedMultiple }
+
+      it_behaves_like 'a resolver', with_aliases: %w[ aliased alias2 alias3 ]
+    end
+  end
+end

From 9402eeffa2c0672614bb5e27f6046be032087cd6 Mon Sep 17 00:00:00 2001
From: Jamis Buck <jamis.buck@mongodb.com>
Date: Wed, 31 Jul 2024 15:08:43 -0600
Subject: [PATCH 2/3] port the feature sandbox to 8.1-stable (for tests)

---
 spec/support/feature_sandbox.rb | 72 +++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 spec/support/feature_sandbox.rb

diff --git a/spec/support/feature_sandbox.rb b/spec/support/feature_sandbox.rb
new file mode 100644
index 0000000000..e4808909d0
--- /dev/null
+++ b/spec/support/feature_sandbox.rb
@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+# A helper utility for allowing features to be loaded and constants defined
+# inside a sandbox, where they can be unloaded and undefined when finished.
+#
+# @example Quarantining a block of code.
+#   FeatureSandbox.quarantine do
+#      require "support/rails_mock"
+#      expect(defined?(Rails)).to be == "constant"
+#   end
+#   expect(defined?(Rails)).to be_nil
+module FeatureSandbox
+  extend self
+
+  # Initiates the quarantine by noting the current state of the top-level
+  # constants, the $LOADED_FEATURES array, and the $LOAD_PATH.
+  #
+  # @return Hash The current state of the environment.
+  def start_quarantine
+    { constants: Object.constants.dup,
+      features: $LOADED_FEATURES.dup,
+      load_path: $LOAD_PATH.dup }
+  end
+
+  # Terminates the quarantine indicated by the given state, by rolling back
+  # changes made since the state was created.
+  #
+  # @param [ Hash ] state The state object to roll the environment back to.
+  def end_quarantine(state)
+    restore_load_path(state[:load_path])
+    unload_features($LOADED_FEATURES - state[:features])
+    unload_constants(Object, Object.constants - state[:constants])
+  end
+
+  # A convenience method for starting a quarantine, yielding to a block, and
+  # then ending the quarantine when the block finishes.
+  #
+  # @yield The block will be executed within the quarantine, with all changes
+  #    to state rolled back upon completion.
+  def quarantine
+    state = start_quarantine
+    yield
+  ensure
+    end_quarantine(state)
+  end
+
+  private
+
+  def restore_load_path(list)
+    $LOAD_PATH.replace(list)
+  end
+
+  def unload_features(list)
+    list.each do |path|
+      $LOADED_FEATURES.delete(path)
+    end
+  end
+
+  def unload_constants(parent, list)
+    list.each do |name|
+      obj = parent.const_get(name)
+      if obj.is_a?(Module) && obj.constants(false).any?
+        unload_constants(obj, obj.constants(false))
+      end
+
+      Mongoid.deregister_model(obj) if obj.is_a?(Mongoid::Document)
+
+      parent.send(:remove_const, name)
+    end
+  end
+end

From 1ff23a5c4f81e9f04e067feab7695d162bcfd2ab Mon Sep 17 00:00:00 2001
From: Jamis Buck <jamis.buck@mongodb.com>
Date: Wed, 31 Jul 2024 15:51:36 -0600
Subject: [PATCH 3/3] register subclasses

---
 lib/mongoid/traversable.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/mongoid/traversable.rb b/lib/mongoid/traversable.rb
index a13de934fb..469fd17331 100644
--- a/lib/mongoid/traversable.rb
+++ b/lib/mongoid/traversable.rb
@@ -311,6 +311,9 @@ def hereditary?
       # @param [ Class ] subclass The inheriting class.
       def inherited(subclass)
         super
+
+        Mongoid::ModelResolver.register(subclass)
+
         @_type = nil
         subclass.aliased_fields = aliased_fields.dup
         subclass.localized_fields = localized_fields.dup