ros-apartment 4.0.0.alpha11 → 4.0.0.alpha12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad60ba3db98c859ff52e1aa0f312d18a8a3e99a6b2703518a94f1ab4abc95eb5
-  data.tar.gz: a782d5dc9690202676d2e30529da89aeb226961bffaf9af7fc821292266d97c6
+  metadata.gz: 2bb81b710aa16f388e8861ad84d358eee5ec751ff6cce1ad3121513e9a0ef46e
+  data.tar.gz: 49adf108763c408b893a314f223756697ccaf21b950087656b357aeb93f33dcd
 SHA512:
-  metadata.gz: 18aaad1312c4eb812c1a7f4a1bcd676325a90db1326efcd2bb4aa71961f38e689240a589497ae6fa7bb16f362276649b36610d76b4b63284567d1999a4a20b5f
-  data.tar.gz: 2f445f6e7d07ef0c4146242aadbb724636fa55184e4c16400daf5870e84a46a6566530cca0a10e130813709c27a08dfed1ba8b6eb4589ab97087b37966ce0b24
+  metadata.gz: 773ee7eff98a2f2287c53aef4b1b8172c97b2251c3d82e3f4b099e60b9602f7093cec92b8bdef9669d71a864bece4f767a2ba7dad9109816a80e8478b6087ed7
+  data.tar.gz: 1cf4884cd5b476e57481e8f928c39575e95cdc75249b86fa24dbfeb6885d28f9af1567795f22d1d71270cd402755711727f6614ecc566998d85a47cae780635c

data/lib/apartment/CLAUDE.md

@@ -97,9 +97,13 @@ All inherit from `AbstractAdapter`. Override `resolve_connection_config`, `creat
 
 **Identity:** `apartment_pinned?` — the class answers whether it is pinned (ivars + superclass walk). `Apartment.pinned_model?(klass)` delegates to `klass.apartment_pinned?` when the concern is included; otherwise it falls back to registry lookup (`pinned_models`) for `excluded_models` shim classes that never included the concern.
 
-**Table naming:** `apartment_explicit_table_name?` — whether `self.table_name` was explicitly set vs convention (compares `@table_name` to `compute_table_name`). Lives here so adapters do not read `@table_name` or call `compute_table_name` from outside; **class instance variable access for pinning is confined to this concern**.
+**Table naming:** `apartment_explicit_table_name?` — whether the cached `@table_name` is one Rails' convention machinery would rebuild (compares `@table_name` to `compute_table_name`). Lives here so adapters do not read `@table_name` or call `compute_table_name` from outside; **class instance variable access for pinning is confined to this concern**. It selects a **restore** strategy only — it is *not* a qualification discriminator, and using it as one shipped three silent no-ops (see `docs/designs/v4-shared-pinned-connections.md`): `compute_table_name` honours `full_table_name_prefix` only on its `base_class?` branch, so prefix-based qualification is discarded outright for subclasses and for models whose module parent defines `table_name_prefix`. Qualification always assigns `table_name` directly.
 
-**Lifecycle:** `apartment_pinned_processed?`, `apartment_mark_processed!`, `apartment_restore!` — qualification state and teardown. Adapters call these; `Apartment.clear_config` uses `apartment_restore!` with `respond_to?` so shim-registered models without the concern still clear safely. `apartment_mark_pinned!` — sets the pinned flag without triggering processing (used by `process_pinned_model` for shim classes to avoid `pin_tenant` recursion).
+**Lifecycle:** `apartment_pinned_processed?`, `apartment_mark_processed!`, `apartment_restore!` — qualification state and teardown. Paths are `:computed` (convention rebuilds the name; restore drops the `@table_name` override and recomputes), `:explicit` (restore assigns the saved name back verbatim), `:prefix` (abstract base; restore puts back the app's `table_name_prefix`), and `nil` (separate-pool; nothing to undo). **Abstract bases are the one case still qualified via `table_name_prefix`**, because `pin_tenant` early-returns once a superclass is pinned — so concrete descendants are never registered and only a `class_attribute` broadcast reaches them. Adapters call these; `Apartment.clear_config` uses `apartment_restore!` with `respond_to?` so shim-registered models without the concern still clear safely. `apartment_mark_pinned!` — sets the pinned flag without triggering processing (used by `process_pinned_model` for shim classes to avoid `pin_tenant` recursion).
+
+**Subclasses of a pinned model:** `pin_tenant` is idempotent **per class**, not per hierarchy — it keys on the class's own flag, not `apartment_pinned?` (which walks the superclass chain). A subclass declaring its own table must register and qualify on its own merits, since the parent's qualification cannot reach a different table; keying on the chain made that call silently no-op. A subclass that *shares* the parent's table still needs nothing and is skipped at qualification time by `AbstractAdapter#inherits_pinned_table?`. A subclass that declares its own table and is never registered gets a boot warning (`warn_unregistered_pinned_subclasses`, descendants-based, so complete only under eager loading). See `docs/designs/v4-shared-pinned-connections.md`.
+
+**Descendant memos:** Rails memoizes `@table_name` per class and never invalidates a descendant's copy when an ancestor changes, so an early read (initializer, gem, route constraint) would freeze the *unqualified* name and the pinned model would read the tenant's table forever. `qualify_pinned_table_name` and `apartment_restore!` bracket their mutation with `apartment_descendants_inheriting_table_name` (collected **before**, while a stale memo is still distinguishable from a declaration) and `apartment_resync_descendant_table_names!` (`reset_table_name` after, which clears `@quoted_table_name`/`@arel_table` via Rails' own setter).
 
 **Guards:** `pin_tenant` raises `ArgumentError` if called on a non-AR class or module. For anonymous classes (`Class.new`), it warns that `TracePoint(:end)` won't fire and skips deferral; call `process_pinned_model` explicitly after assigning the constant.
 

data/lib/apartment/adapters/abstract_adapter.rb

@@ -148,12 +148,96 @@ module Apartment
         !tenant_container_exists?(tenant)
       end
 
-      # Qualify a pinned model's table_name so it targets the default
-      # tenant's tables from any tenant connection. Subclasses must
-      # implement when shared_pinned_connection? returns true.
-      def qualify_pinned_table_name(_klass)
+      # The namespace that makes the default tenant's tables reachable from any
+      # tenant connection — a schema (PostgreSQL) or a database (MySQL).
+      # Subclasses must implement when shared_pinned_connection? returns true.
+      def pinned_table_qualifier
         raise(NotImplementedError,
-              "#{self.class}#qualify_pinned_table_name must be implemented when shared_pinned_connection? is true")
+              "#{self.class}#pinned_table_qualifier must be implemented when shared_pinned_connection? is true")
+      end
+
+      # Qualify a pinned model's table_name so it targets the default tenant's
+      # tables from any tenant connection.
+      #
+      # Always assigns table_name directly. The tempting alternative — set
+      # table_name_prefix and let Rails recompose — is unsound, because
+      # compute_table_name only consults full_table_name_prefix on its
+      # base_class? branch:
+      #
+      #   * a class that is not its own base_class gets base_class.table_name
+      #     verbatim, so the prefix is discarded outright;
+      #   * full_table_name_prefix prefers the first module parent that responds
+      #     to table_name_prefix, so an engine-namespaced model ignores the
+      #     prefix set on the class itself;
+      #   * overwriting the prefix drops one the app set, silently retargeting
+      #     the model at a different table.
+      #
+      # Each case left the model resolving to the *tenant's* table with no
+      # error. Reading table_name first lets Rails compute the conventional
+      # name — honouring any prefix, suffix, or nesting the app declared —
+      # before we qualify the result.
+      def qualify_pinned_table_name(klass)
+        # Captured before the mutation below: afterwards there is no way to
+        # tell a descendant's stale memo from a table it declared itself.
+        inheriting = klass.apartment_descendants_inheriting_table_name
+        apply_pinned_qualification(klass)
+        klass.apartment_resync_descendant_table_names!(inheriting)
+      end
+
+      def apply_pinned_qualification(klass)
+        return qualify_pinned_table_name_prefix(klass) if klass.abstract_class?
+        return klass.apartment_mark_processed! if inherits_pinned_table?(klass)
+
+        # Captured before the assignment below, which would otherwise make
+        # every model look explicitly named.
+        path = klass.apartment_explicit_table_name? ? :explicit : :computed
+        original = klass.table_name
+        klass.table_name = "#{pinned_table_qualifier}.#{original.sub(/\A[^.]+\./, '')}"
+        klass.apartment_mark_processed!(path, (original if path == :explicit))
+      end
+
+      # An abstract class has no table of its own — table_name is nil — so
+      # there is nothing to assign. Pinning one is a supported pattern (an
+      # abstract `connects_to` base is pinned so Apartment does not build
+      # tenant pools for it), and its qualifier still has to reach the concrete
+      # descendants that inherit the pin.
+      #
+      # Those descendants are never qualified directly: pin_tenant early-returns
+      # once any superclass is pinned (apartment_pinned? walks the chain), so
+      # they are never registered and process_pinned_models never sees them.
+      # table_name_prefix is a class_attribute, so setting it here broadcasts
+      # down the inheritance chain and each descendant composes it in its own
+      # compute_table_name. Any prefix the app set is preserved rather than
+      # overwritten, so `myapp_` becomes `<qualifier>.myapp_`.
+      #
+      # This is the one place the prefix mechanism is still correct, because
+      # here it is a broadcast to other classes rather than an attempt to
+      # qualify this class's own name.
+      def qualify_pinned_table_name_prefix(klass)
+        original_prefix = klass.table_name_prefix
+        klass.table_name_prefix = "#{pinned_table_qualifier}.#{original_prefix}"
+        klass.apartment_mark_processed!(:prefix, original_prefix)
+      end
+
+      # Whether +klass+ reaches its table through an already-pinned base class
+      # and so needs no qualification of its own. Rails resolves a subclass's
+      # table through base_class.table_name, which the base's qualification
+      # already covers; assigning here would freeze a copy of the base's
+      # qualified name onto the child and desynchronise the two on teardown.
+      #
+      # Scoped narrowly on purpose. A subclass that declares its own table —
+      # the transitional shape when migrating an STI child off a pinned
+      # parent's table — is NOT covered and qualifies normally, because the
+      # parent's qualification cannot reach a different table. And a subclass
+      # whose base class is not pinned (e.g. an app model extending a gem's
+      # model) is not covered either, which is the case that motivated
+      # qualifying by assignment in the first place.
+      def inherits_pinned_table?(klass)
+        return false if klass.base_class?
+        return false if klass.apartment_explicit_table_name?
+
+        base = klass.base_class
+        base.respond_to?(:apartment_pinned?) && base.apartment_pinned?
       end
 
       # Process all pinned models. When shared_pinned_connection? is true, qualifies
@@ -167,6 +251,86 @@ module Apartment
           raise(Apartment::ConfigurationError,
                 "Failed to process pinned model #{klass.name}: #{e.class}: #{e.message}")
         end
+
+        warn_unregistered_pinned_subclasses
+      end
+
+      # Warn about subclasses of a pinned model that declare their own table and
+      # were never registered. Such a class inherits apartment_pinned? through
+      # the superclass walk but gets no qualification, so on a shared-connection
+      # adapter it silently reads the *tenant's* table — and on a separate-pool
+      # adapter a genuinely tenant-scoped one silently reads the default's. The
+      # shape is transitional (migrating an STI child off a pinned parent's
+      # table), which is exactly when a silent read is most costly: the symptom
+      # looks like a botched backfill.
+      #
+      # Detection walks descendants, so it is complete under eager loading
+      # (production boot, CI) and partial under Zeitwerk lazy loading. That is
+      # tolerable for a warning and would not be for a raise — which is why this
+      # warns rather than raising.
+      # descendants is transitive, so every pinned class in one inheritance
+      # chain sees the same unregistered descendant. Deduplicate, and attribute
+      # each warning to the *nearest* pinned ancestor — the one whose pin the
+      # subclass actually inherits — so the message is deterministic rather than
+      # dependent on registry iteration order.
+      def warn_unregistered_pinned_subclasses
+        # Snapshot the registry and walk it outside its own lock. Concurrent::Set
+        # synchronizes every method on CRuby, #each included, so iterating in
+        # place would hold a process-wide monitor across descendant walking and
+        # stderr I/O. Same leaf-lock discipline as Patches::ConnectionRegistry.
+        pinned = Apartment.pinned_models.to_a
+        registered = Set.new(pinned)
+        seen = Set.new
+
+        pinned.each do |klass|
+          next unless klass.respond_to?(:descendants)
+
+          klass.descendants.each do |sub|
+            check_pinned_subclass(klass, sub, registered) if seen.add?(sub)
+          end
+        end
+      end
+
+      # Advisory only: this runs from process_pinned_models, which Tenant.init
+      # calls in after_initialize, so it must never be able to fail a boot.
+      # Rails' naming machinery raises on shapes we do not control — an
+      # anonymous descendant has no model_name, and Class.new(SomeBase) is
+      # everywhere in test suites.
+      def check_pinned_subclass(klass, sub, registered)
+        return unless unregistered_pinned_subclass?(sub, registered)
+
+        warn_unqualified_subclass(nearest_pinned_ancestor(sub, registered) || klass, sub)
+      rescue StandardError => e
+        warn "[Apartment] could not check pinned subclass #{sub.inspect}: #{e.class}: #{e.message}"
+      end
+
+      # The closest registered ancestor above +klass+, i.e. the pin it inherits.
+      def nearest_pinned_ancestor(klass, registered)
+        ancestor = klass.superclass
+        while ancestor.is_a?(Class) && ancestor < ActiveRecord::Base
+          return ancestor if registered.include?(ancestor)
+
+          ancestor = ancestor.superclass
+        end
+        nil
+      end
+
+      def unregistered_pinned_subclass?(sub, registered)
+        return false if registered.include?(sub)
+        # Anonymous classes have no model_name for Rails to compute a table
+        # from, and nothing actionable to name in a warning.
+        return false if sub.name.nil?
+        return false unless sub.respond_to?(:apartment_explicit_table_name?)
+        return false if sub.abstract_class?
+
+        sub.apartment_explicit_table_name?
+      end
+
+      def warn_unqualified_subclass(klass, sub)
+        warn "[Apartment] #{sub.name || sub.inspect} inherits a pin from " \
+             "#{klass.name || klass.inspect} but declares its own table " \
+             "(#{sub.table_name}) and was never registered, so it is not qualified. " \
+             "Call pin_tenant on it if it should read the default tenant's data."
       end
 
       # Process a single pinned model. Called by process_pinned_models (batch)
@@ -187,6 +351,14 @@ module Apartment
 
         return if klass.apartment_pinned_processed?
 
+        # A subclass that reaches its table through an already-pinned base needs
+        # nothing on either path. Qualifying would freeze a copy of the base's
+        # name onto it; establishing a connection would hand it a *different*
+        # pool from its parent, splitting two classes that share one physical
+        # table across connections and breaking transactional integrity between
+        # them. Mark processed with a nil path so teardown skips it too.
+        return klass.apartment_mark_processed! if inherits_pinned_table?(klass)
+
         if shared_pinned_connection?
           qualify_pinned_table_name(klass)
         else

data/lib/apartment/adapters/mysql2_adapter.rb

@@ -14,20 +14,10 @@ module Apartment
         !Apartment.config.force_separate_pinned_pool
       end
 
-      def qualify_pinned_table_name(klass)
-        db_name = base_config['database']
-
-        if klass.apartment_explicit_table_name?
-          original = klass.table_name
-          table = original.sub(/\A[^.]+\./, '')
-          klass.table_name = "#{db_name}.#{table}"
-          klass.apartment_mark_processed!(:explicit, original)
-        else
-          original_prefix = klass.table_name_prefix
-          klass.table_name_prefix = "#{db_name}."
-          klass.reset_table_name
-          klass.apartment_mark_processed!(:convention, original_prefix)
-        end
+      # Pinned tables live in the default tenant's database; every tenant
+      # connection can reach them by database-qualifying the name.
+      def pinned_table_qualifier
+        base_config['database']
       end
 
       def resolve_connection_config(tenant, base_config: nil)

data/lib/apartment/adapters/postgresql_schema_adapter.rb

@@ -18,18 +18,10 @@ module Apartment
         !Apartment.config.force_separate_pinned_pool
       end
 
-      def qualify_pinned_table_name(klass)
-        if klass.apartment_explicit_table_name?
-          original = klass.table_name
-          table = original.sub(/\A[^.]+\./, '')
-          klass.table_name = "#{default_tenant}.#{table}"
-          klass.apartment_mark_processed!(:explicit, original)
-        else
-          original_prefix = klass.table_name_prefix
-          klass.table_name_prefix = "#{default_tenant}."
-          klass.reset_table_name
-          klass.apartment_mark_processed!(:convention, original_prefix)
-        end
+      # Pinned tables live in the default tenant's schema; every tenant
+      # connection can reach them by schema-qualifying the name.
+      def pinned_table_qualifier
+        default_tenant
       end
 
       def resolve_connection_config(tenant, base_config: nil)

data/lib/apartment/concerns/model.rb

@@ -16,12 +16,23 @@ module Apartment
       # their connection always targets the default tenant's database/schema.
       #
       # Safe to call before or after Apartment.activate!.
-      # Idempotent: no-op if this class (or a parent) is already pinned.
+      # Idempotent per class: a second call on the same class is a no-op.
+      #
+      # Deliberately keyed on this class's own flag, NOT on apartment_pinned?
+      # (which walks the superclass chain). A subclass of a pinned model that
+      # declares its own table has to be registered and qualified on its own
+      # merits — the parent's qualification cannot reach a different table.
+      # Keying on the chain made that call accept-and-do-nothing, which is the
+      # wrong answer even for a shape apps should avoid: an API call must
+      # either work or be absent, never silently no-op. Subclasses that share
+      # the parent's table still need nothing, and are skipped at
+      # qualification time rather than here (see
+      # AbstractAdapter#inherits_pinned_table?).
       def pin_tenant
         unless is_a?(Class) && self < ActiveRecord::Base
           raise(ArgumentError, "pin_tenant can only be called on ActiveRecord model classes, got #{inspect}")
         end
-        return if apartment_pinned?
+        return if @apartment_pinned
 
         @apartment_pinned = true
         Apartment.register_pinned_model(self)
@@ -54,10 +65,21 @@ module Apartment
         superclass.apartment_pinned?
       end
 
-      # Whether this model has an explicit self.table_name = assignment
-      # (as opposed to Rails' lazy convention computation). Returns false
-      # if the explicit value matches what convention would produce, since
-      # the convention path handles that case correctly.
+      # Whether this model's current table_name would survive a recomputation
+      # — i.e. whether Rails' convention machinery reproduces the value now
+      # cached in @table_name. False means convention rebuilds it exactly, so
+      # qualification can be undone by discarding the override; true means the
+      # name must be saved verbatim and restored verbatim.
+      #
+      # This answers a *restore* question. It is deliberately NOT a
+      # qualification discriminator: a table_name that matches convention is no
+      # evidence that setting table_name_prefix would qualify the model. Rails
+      # ignores the prefix outright for any class that is not its own
+      # base_class (compute_table_name returns base_class.table_name verbatim),
+      # and full_table_name_prefix prefers a module parent's prefix over the
+      # class's own. Qualification therefore always assigns table_name
+      # directly — see AbstractAdapter#qualify_pinned_table_name.
+      #
       # NOTE: compute_table_name is a private Rails API; tested against
       # Rails main as a canary in CI.
       def apartment_explicit_table_name?
@@ -66,40 +88,110 @@ module Apartment
         instance_variable_get(:@table_name) != send(:compute_table_name)
       end
 
+      # Descendants that reach their table name through this class rather than
+      # declaring one of their own, and have already memoized it.
+      #
+      # Rails memoizes @table_name per class on first read and never
+      # invalidates a descendant's copy when an ancestor's name or prefix
+      # changes. Anything touching a descendant's table_name before
+      # qualification runs — an initializer, a gem, a route constraint, a
+      # descendants sweep — freezes the pre-qualification name, and the model
+      # then resolves to the wrong tenant's table for the life of the process.
+      #
+      # MUST be called BEFORE the ancestor is mutated: afterwards
+      # apartment_explicit_table_name? can no longer distinguish a stale memo
+      # from a genuine declaration, since the ancestor's change has moved what
+      # convention computes. Descendants without a memo are omitted — they
+      # compute lazily and will pick the new value up on their own.
+      def apartment_descendants_inheriting_table_name
+        return [] unless respond_to?(:descendants)
+
+        stale = descendants.select do |sub|
+          sub.instance_variable_defined?(:@table_name) &&
+            sub.respond_to?(:apartment_inherited_table_name) &&
+            sub.instance_variable_get(:@table_name) == sub.apartment_inherited_table_name
+        rescue StandardError
+          # Rails' naming machinery raises on shapes we do not control (an
+          # anonymous class has no model_name). Skip rather than guess.
+          false
+        end
+
+        # Reset an intermediate before anything beneath it: reset_table_name on
+        # a class under an abstract parent reads superclass.table_name — the
+        # memo, not base_class — so a grandchild reset first would re-freeze its
+        # parent's stale value. ActiveSupport's descendants happens to be
+        # ancestor-first today, but that ordering is undocumented.
+        stale.sort_by { |sub| sub.ancestors.size }
+      end
+
+      # What Rails' own reset_table_name would recompute for this class right
+      # now. Mirrors ActiveRecord::ModelSchema#reset_table_name deliberately.
+      #
+      # NOT compute_table_name: the two disagree for a class whose superclass
+      # is abstract. reset_table_name prefers `superclass.table_name`, while
+      # compute_table_name treats such a class as its own base_class and builds
+      # from its own model_name. So a concrete class under an abstract
+      # intermediate that carries a table (an abstract class sandwiched under a
+      # concrete pinned parent) inherits `foos` but computes `gkids` — and
+      # keying on compute_table_name misreads that inherited name as an
+      # explicit declaration, skipping the resync and leaving the model on the
+      # tenant's table.
+      def apartment_inherited_table_name
+        if abstract_class?
+          superclass.table_name
+        elsif superclass.abstract_class?
+          superclass.table_name || send(:compute_table_name)
+        else
+          send(:compute_table_name)
+        end
+      end
+
+      # Recompute the table name of each descendant captured above, now that
+      # this class has changed. reset_table_name goes through Rails' own
+      # table_name= setter, so the derived @quoted_table_name and @arel_table
+      # caches are cleared with it.
+      def apartment_resync_descendant_table_names!(subclasses)
+        subclasses.each do |sub|
+          sub.reset_table_name
+        rescue StandardError => e
+          warn "[Apartment] could not reset table name for #{sub.name || sub.inspect}: " \
+               "#{e.class}: #{e.message}"
+        end
+      end
+
       # Whether process_pinned_model has already run for this class.
       def apartment_pinned_processed?
         @apartment_pinned_processed == true
       end
 
-      # Record that qualification has been applied, and what path was used.
+      # Record that qualification has been applied, and how it must be undone.
       # Called by qualify_pinned_table_name (adapters) after mutations succeed,
       # or by process_pinned_model after establish_connection on separate-pool path.
+      #
+      # :computed — the pre-qualification name was reproducible by convention;
+      #   restore by discarding the override and recomputing.
+      # :explicit — the name was assigned in a way convention cannot rebuild;
+      #   +original_value+ is that name, restored verbatim.
+      # :prefix — an abstract base, qualified by broadcasting through
+      #   table_name_prefix to the descendants that inherit its pin;
+      #   +original_value+ is the prefix the app had set.
+      # nil — separate-pool models; nothing to undo.
       def apartment_mark_processed!(path = nil, original_value = nil)
         @apartment_pinned_processed = true
         @apartment_qualification_path = path
         case path
         when :explicit then @apartment_original_table_name = original_value
-        when :convention then @apartment_original_table_name_prefix = original_value
+        when :prefix then @apartment_original_table_name_prefix = original_value
         end
       end
 
       # Undo table name qualification and clear tracking state.
-      # Convention path: restore original prefix so reset_table_name recomputes.
-      # Explicit path: restore the original table_name that was overwritten.
-      # nil path: separate-pool models — no table name changes to undo.
       def apartment_restore!
         return unless @apartment_pinned_processed
 
-        case @apartment_qualification_path
-        when :convention
-          self.table_name_prefix = @apartment_original_table_name_prefix || ''
-          reset_table_name
-        when :explicit
-          self.table_name = @apartment_original_table_name if @apartment_original_table_name
-        when nil then nil
-        else
-          warn "[Apartment] #{name}: unexpected qualification_path #{@apartment_qualification_path.inspect}"
-        end
+        inheriting = apartment_descendants_inheriting_table_name
+        apartment_undo_qualification!
+        apartment_resync_descendant_table_names!(inheriting)
 
         @apartment_pinned_processed = nil
         @apartment_qualification_path = nil
@@ -109,6 +201,31 @@ module Apartment
 
       private
 
+      # Reverse whichever mutation qualify_pinned_table_name applied.
+      def apartment_undo_qualification!
+        case @apartment_qualification_path
+        when :computed then apartment_recompute_table_name!
+        when :explicit then apartment_restore_table_name!
+        when :prefix then self.table_name_prefix = @apartment_original_table_name_prefix || ''
+        when nil then nil
+        else
+          warn "[Apartment] #{name}: unexpected qualification_path #{@apartment_qualification_path.inspect}"
+        end
+      end
+
+      # Drop the qualified override and recompute from convention. The ivar is
+      # removed first so nothing can keep the qualified value; the recompute
+      # then runs through Rails' table_name= setter, which also clears the
+      # derived @quoted_table_name and @arel_table caches.
+      def apartment_recompute_table_name!
+        remove_instance_variable(:@table_name) if instance_variable_defined?(:@table_name)
+        reset_table_name
+      end
+
+      def apartment_restore_table_name!
+        self.table_name = @apartment_original_table_name if @apartment_original_table_name
+      end
+
       # Register a one-shot TracePoint(:end) that fires after the class body
       # closes. Only :end is used — :b_return fires for ALL block returns in
       # class context (each, tap, include hooks) and would trigger prematurely.

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '4.0.0.alpha11'
+  VERSION = '4.0.0.alpha12'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha11
+  version: 4.0.0.alpha12
 platform: ruby
 authors:
 - Ryan Brunner