Defer pin_tenant processing until class body closes

[mnovelo]

Summary

Fixes silent table name qualification bug when pin_tenant is called before self.table_name in a class body under Zeitwerk lazy loading (eager_load = false).

pin_tenant now defers process_pinned_model via a one-shot TracePoint(:end) constrained to Thread.current. Processing runs after the class body's closing end keyword, so self.table_name and other declarations are visible regardless of ordering.

Problem

class EngagementReport < ApplicationRecord
  include Apartment::Model
  pin_tenant                          # processes immediately, sees no @table_name
  # ... associations, scopes ...
  self.table_name = 'reports'         # too late — qualification already happened
end

Under eager_load = false + Zeitwerk, pin_tenant fired process_pinned_model immediately. The gem saw no explicit table name, took the convention path, qualified as public.engagement_reports. Then self.table_name = 'reports' silently overwrote the qualification. Queries hit the wrong schema.

How it works

• Only TracePoint(:end) is used — fires for source-parsed class Foo ... end (Zeitwerk files)
• :b_return rejected: fires for ALL block returns in class context (each, tap, include hooks), not just Class.new closing — would trigger premature processing
• :raise rejected: rescued raises (begin/rescue in class body) still produce :end; unconditional disable would prevent processing on successful load. MRI verified: :end fires even when the body raises (event order [:raise, :end])
• target_thread: Thread.current constrains to the loading thread
• Multiple TracePoints coexist independently; disabling ours does not affect user traces
• process_pinned_model wrapped with begin/rescue/warn/raise for error context

Defensive guards

• pin_tenant raises ArgumentError if called on a non-AR class or module
• Anonymous classes (Class.new): warns that :end won't fire, skips deferral. Use class MyModel < ApplicationRecord or call process_pinned_model explicitly after assigning the constant
• Apartment.process_pinned_model warns when adapter is nil instead of silently returning nil

Changes (8 files, +186 / -28)

File	Change
lib/apartment/concerns/model.rb	apartment_defer_processing! with TracePoint(:end), AR guard, anonymous class warning
lib/apartment.rb	process_pinned_model nil-adapter warning
spec/unit/concerns/model_spec.rb	6 new tests: deferred, source-parsed, table_name ordering, AR guard, module guard, anonymous warning
spec/unit/tenant_spec.rb	Fix test model to inherit from AR::Base (for new guard)
spec/integration/v4/excluded_models_spec.rb	Qualification outcome tests with real adapters
docs/upgrading-to-v4.md	No ordering requirement; Class.new + constant assignment gotcha
lib/apartment/CLAUDE.md	Guards + deferred processing documentation
docs/designs/v4-deferred-pin-tenant-processing.md	Aligned with :end-only implementation

Test plan

• Unit tests: 668 examples, 0 failures
• Appraisal (all Rails versions): 0 failures across 14 gemfiles
• Integration (SQLite): 0 failures
• Rubocop clean

🤖 Generated with Claude Code