typed_eav 0.6.0 → 0.7.1

data/lib/typed_eav/config.rb

@@ -122,10 +122,9 @@ module TypedEAV
       end
       attr_writer :require_scope # rubocop:disable Style/AccessorGrouping
 
-      # Master kill-switch for Phase 04 versioning. When false (default), the
-      # Phase 04 internal subscriber is NOT registered with EventDispatcher
-      # at engine boot — zero overhead for apps that don't use versioning.
-      # When true, the subscriber registers but only writes a version row
+      # Boot-time switch for transactional versioning. When false (default),
+      # Value's version callbacks are not installed. When true, the callbacks
+      # install after the host configuration is loaded, but only write a row
       # when value.entity_type belongs to a host model that opted in via
       # `has_typed_eav versioned: true` (per-entity opt-in flows through
       # Registry; both layers land in plan 04-02).
@@ -138,7 +137,7 @@ module TypedEAV
       # Default false because the schema migration only matters for apps that
       # opt in. A v0.1.x deployment that pulls in Phase 04 without changing
       # any config or model declarations sees no behavior change — the
-      # subscriber doesn't register, no version rows are written, no perf
+      # callbacks don't register, no version rows are written, no perf
       # impact at all. The migration is still copied (idempotent), but the
       # table sits empty.
       def versioning
@@ -186,13 +185,13 @@ module TypedEAV
       #
       # Errors raised inside this proc are rescued by EventDispatcher and
       # logged via Rails.logger.error — they do NOT propagate to the
-      # user's save call (the row is already committed). Internal subscribers
-      # (Phase 04 versioning, Phase 07 matview) fire BEFORE this proc and
+      # user's save call (the row is already committed). Generic internal
+      # observers fire BEFORE this proc and
       # their errors DO propagate. See 03-CONTEXT.md §User-callback error policy.
       #
-      # Reassignment after gem initialization does NOT disable internal
-      # subscribers — those live on EventDispatcher.value_change_internals,
-      # not here.
+      # Reassigning this public callback does NOT disable transactional
+      # versioning callbacks; they are installed on Value at boot and are
+      # independent of this public slot.
       attr_accessor :on_value_change
 
       # Public single-proc slot for field-change events.
@@ -207,7 +206,8 @@ module TypedEAV
       #
       # :rename fires when `name` is among Field#saved_changes, even
       # combined with other attr changes (sort_order, options, etc.) —
-      # Phase 07 matview needs the rename signal to regenerate column names
+      # Registered consumers may use the rename signal to refresh their own
+      # name-to-field mappings.
       # even when the rename was bundled with other edits.
       attr_accessor :on_field_change
 
@@ -215,7 +215,7 @@ module TypedEAV
       # Field::Image-typed Value gains (or replaces) an attachment. Receives
       # `(value, blob)`. Default nil — no-op when not configured.
       #
-      # Hook ordering: fires AFTER versioning (Phase 04) and AFTER
+      # Hook ordering: fires AFTER the transactional version write and AFTER
       # on_value_change (Phase 03). The hook is informational ("an image
       # was attached"), not mutational; running it last avoids polluting
       # earlier hooks' snapshots / context with attachment-derived state.
@@ -259,22 +259,20 @@ module TypedEAV
         self.field_types = BUILTIN_FIELD_TYPES.dup
         self.scope_resolver = DEFAULT_SCOPE_RESOLVER
         self.require_scope = true
-        # Phase 04 versioning master switch + actor resolver. Reset to defaults
+        # Transactional versioning boot switch + actor resolver. Reset to defaults
         # (false / nil) so test isolation matches `Config.on_value_change` / etc.
-        # Internal subscribers (TypedEAV::Versioning::Subscriber, registered
-        # at engine load by plan 04-02) are deliberately NOT cleared here —
-        # they live on EventDispatcher.value_change_internals and survive
+        # Transactional Value callbacks are deliberately NOT cleared here —
+        # callback installation is boot-latched and survives
         # Config.reset! by design (the snapshot/restore split is locked at
         # 03-CONTEXT.md §Reset split). Test teardown that needs to clear
-        # subscribers too calls EventDispatcher.reset!.
+        # generic observers too calls EventDispatcher.reset!.
         self.versioning = false
         self.actor_resolver = nil
         # Test isolation: scoping_spec/field_spec/etc. call Config.reset! in
         # `after` hooks — this ensures user procs set in earlier tests don't
-        # leak across examples. Internal subscribers
-        # (EventDispatcher.value_change_internals/field_change_internals) are
-        # deliberately NOT reset here — they're populated at engine load by
-        # Phase 04+ and must persist across Config.reset!. Test teardown
+        # leak across examples. Generic EventDispatcher observers
+        # (value_change_internals/field_change_internals) are deliberately NOT
+        # reset here — they persist across Config.reset!. Test teardown
         # that needs to clear EVERYTHING calls EventDispatcher.reset! too.
         self.on_value_change = nil
         self.on_field_change = nil

data/lib/typed_eav/csv_mapper.rb

@@ -70,7 +70,7 @@ module TypedEAV
     # `errors.empty?`. Callers that need to combine multiple row Results
     # into a batch view do so by composing the immutable Hashes in their
     # own code (e.g., `results.flat_map(&:errors).reduce({}, :merge)`); the
-    # mapper does not provide a "merge" helper in v0.6.0.
+    # mapper does not provide a "merge" helper.
     class Result
       attr_reader :attributes, :errors
 

data/lib/typed_eav/engine.rb

@@ -8,12 +8,10 @@ module TypedEAV
       require_relative "field/typed_storage"
       require_relative "config"
       require_relative "registry"
-      # Eager-loaded (not autoloaded) — Phase 04 versioning will register on
-      # EventDispatcher at engine boot, before any model reference triggers
-      # autoload. Without this require_relative, Phase 04's engine-time
-      # `register_internal_value_change` call would const-resolve the module
-      # for the first time and run a fresh `@value_change_internals = []`
-      # AFTER versioning had already pushed onto a different instance.
+      # Eager-loaded (not autoloaded) — transactional versioning registers its
+      # Value callbacks at engine boot, before any model reference triggers
+      # autoload. Keeping the dispatcher loaded early gives public and
+      # generic observers one stable broker instance.
       require_relative "event_dispatcher"
     end
 
@@ -24,11 +22,11 @@ module TypedEAV
       end
     end
 
-    # Phase 04 versioning subscriber registration.
+    # Transactional versioning callback registration.
     #
     # CONDITIONAL on TypedEAV.config.versioning. When false (the default
-    # for apps that don't enable versioning), no subscriber is registered:
-    # zero callable in EventDispatcher.value_change_internals, zero per-write
+    # for apps that don't enable versioning), no Value callback is registered:
+    # zero transactional callback overhead.
     # dispatch overhead, zero config reads on the hot path. This is the
     # locked CONTEXT contract — line 17 says "zero overhead for apps that
     # don't use versioning", which means literally no callable, not "callable
@@ -46,21 +44,17 @@ module TypedEAV
     # has fired (e.g., a Rails console session that monkey-patches Config,
     # or a feature-flag flip mid-process) will NOT get versioning until
     # process restart. Runtime toggle is not a documented use case — adding
-    # a register/deregister API is out of scope for Phase 04. The Risk §1
+    # a register/deregister API is out of scope for boot-latched versioning. The Risk §1
     # late-toggle concern from RESEARCH is acceptably narrowed by this
     # trade-off.
     #
-    # Slot 0 ordering: Phase 07 (future matview) will register its
-    # subscriber via its own `config.after_initialize` block declared LATER
-    # in this same engine file. Rails runs `after_initialize` blocks in
-    # declaration order within a single Engine class, so versioning's block
-    # fires first → slot 0. The regression spec (plan 04-03 P03) is the
-    # ongoing guard.
+    # Version rows are written in the source transaction. Public and generic
+    # observer ordering remains owned by EventDispatcher after commit.
     #
     # Why a one-line callable to a class method (not inline registration):
     # `TypedEAV::Versioning.register_if_enabled` is the testable seam. The
-    # slot-0 regression spec (plan 04-03 P03) and the zero-overhead
-    # verification spec (this plan, subscriber_spec) cannot reboot the Rails
+    # callback-chain regression spec and the zero-overhead verification spec
+    # cannot reboot the Rails
     # process inside RSpec — but they CAN call the helper directly against
     # a fresh internals array to exercise both branches (versioning on/off)
     # in-process. Inlining the `if` here would force tests to either reboot
@@ -78,7 +72,7 @@ module TypedEAV
     # that don't use Image/File field types pay zero overhead, AND the
     # gemspec stays free of an activestorage hard-dependency.
     #
-    # When AS IS loaded (Rails 7.1+ with the rails meta-gem, or an
+    # When AS is loaded (on supported Rails versions with the rails meta-gem, or an
     # explicit `gem 'activestorage'` line), TypedEAV::Value gains a
     # single :attachment has_one_attached association that covers BOTH
     # Field::Image and Field::File typed Values. The Image vs File
@@ -94,20 +88,15 @@ module TypedEAV
     # Value row (Text, Integer, etc.), even when no attachment is in
     # play. RESEARCH §Risk 3 documents this rationale.
     #
-    # Second after_initialize block (versioning's is the first): Rails
-    # runs after_initialize blocks in declaration order within a single
-    # Engine class. Versioning's slot-0 dispatcher position at the
-    # EventDispatcher level is preserved (dispatcher slots are an
-    # EventDispatcher-internal concern; the engine's after_initialize
-    # ordering is independent). Phase 07 matview will append its own
-    # block after this one.
+    # This second after_initialize block is independent of transactional
+    # versioning; it only handles Active Storage association setup.
     #
     # Why a one-line callable to a class method (testable seam): the
     # active_storage_soft_detect_spec cannot reboot Rails inside RSpec
     # to exercise both branches. By extracting the body into
     # `Engine.register_attachment_associations!`, specs call the helper
     # directly with whatever ::ActiveStorage state they need to test.
-    # Pattern matches Phase 04's `Versioning.register_if_enabled`.
+    # Pattern matches `Versioning.register_if_enabled`.
     config.after_initialize do
       TypedEAV::Engine.register_attachment_associations!
     end

data/lib/typed_eav/entity_query.rb

@@ -103,10 +103,10 @@ module TypedEAV
     def typed_eav_definitions(scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
       resolved = resolve_scope(scope, parent_scope)
       if resolved.equal?(ALL_SCOPES)
-        TypedEAV::Partition.visible_fields(entity_type: name, mode: :all_partitions)
+        TypedEAV::Partition.visible_fields(entity_type: polymorphic_name, mode: :all_partitions)
       else
         s, ps = resolved
-        TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
+        TypedEAV::Partition.visible_fields(entity_type: polymorphic_name, scope: s, parent_scope: ps)
       end
     end
 
@@ -120,22 +120,26 @@ module TypedEAV
     end
 
     # Bulk write API. Sets the same `values_by_field_name` Hash on every
-    # record in `records` inside ONE outer ActiveRecord transaction with a
-    # SAVEPOINT-PER-RECORD failure-isolation envelope. See `TypedEAV::BulkWrite`
-    # for the transaction shape, error-aggregation contract, and the
-    # `version_grouping:` semantics.
-    def bulk_set_typed_eav_values(records, values_by_field_name, version_grouping: :default)
+    # record in `records` using an outer transaction with per-record savepoints
+    # (`transaction: :all`) or one such envelope per committed chunk
+    # (`transaction: :chunks`). See `TypedEAV::BulkWrite` for the error and
+    # `version_grouping:` contracts.
+    def bulk_set_typed_eav_values(
+      records, values_by_field_name, version_grouping: :default, transaction: :all, chunk_size: nil
+    )
       TypedEAV::BulkWrite.execute(
         host_class: self,
         records: records,
         values_by_field_name: values_by_field_name,
         version_grouping: version_grouping,
+        transaction: transaction,
+        chunk_size: chunk_size,
       )
     end
 
     # Per-record-varying bulk write API. Sibling to `bulk_set_typed_eav_values`
     # for callers (sync importers, per-row updaters) where each record carries
-    # its own values hash. Routes through the same outer-transaction-plus-
+    # its own values hash. Routes through the same transaction/chunk and
     # savepoint envelope and returns the same
     # `{ successes: [...], errors_by_record: { record => errors_hash } }`
     # shape. See `TypedEAV::BulkWrite` for the transaction shape and the
@@ -195,11 +199,32 @@ module TypedEAV
     # write `"name"` share one UUID for that cell; a record writing
     # `"city"` (that no other record writes) gets its own UUID for
     # `"city"`. Overlapping fields share a version group across records.
-    def bulk_set_typed_eav_values_per_record(values_by_record, version_grouping: :default)
+    def bulk_set_typed_eav_values_per_record(
+      values_by_record, version_grouping: :default, transaction: :all, chunk_size: nil
+    )
       TypedEAV::BulkWrite.execute_per_record(
         host_class: self,
         values_by_record: values_by_record,
         version_grouping: version_grouping,
+        transaction: transaction,
+        chunk_size: chunk_size,
+      )
+    end
+
+    # Reduced-semantics SQL bulk upsert. This deliberately separate API
+    # requires `acknowledge_reduced_semantics: true`; it retains Value
+    # prevalidation/casting and domain/partition checks while skipping host and
+    # Value persistence lifecycle callbacks, versioning, and delete shorthand.
+    def bulk_upsert_typed_eav_values(
+      records, values_by_field_name, acknowledge_reduced_semantics: false, transaction: :all, chunk_size: nil
+    )
+      TypedEAV::BulkUpsert.execute(
+        host_class: self,
+        records: records,
+        values_by_field_name: values_by_field_name,
+        acknowledge_reduced_semantics: acknowledge_reduced_semantics,
+        transaction: transaction,
+        chunk_size: chunk_size,
       )
     end
 

data/lib/typed_eav/event_dispatcher.rb

@@ -2,8 +2,8 @@
 
 module TypedEAV
   # In-process event-dispatch hub for Value and Field after_commit lifecycle
-  # events. Implements the contract that Phase 04 versioning and Phase 07
-  # materialized index both depend on.
+  # events. It carries public callbacks and generic in-gem observers;
+  # durable version rows are written by transactional Value callbacks.
   #
   # ## Contract surface
   #
@@ -11,20 +11,15 @@ module TypedEAV
   #   proc slots (nil-default), backed by ActiveSupport::Configurable. Users
   #   set them via `TypedEAV.configure { |c| c.on_value_change = ->(...) }`.
   # - `register_internal_value_change(callable)` / `register_internal_field_change(callable)`
-  #   are FIRST-PARTY hooks for in-gem features (Phase 04 versioning, Phase 07
-  #   matview DDL regen). They are not private_class_method because Phase 04
-  #   lives in `TypedEAV::Versioning::*` and cannot reach a truly-private class
-  #   method — the `register_internal_*` naming + this comment block signal
-  #   first-party-only intent.
+  #   are FIRST-PARTY hooks for in-gem observers. The explicit registration
+  #   names signal their intended scope.
   # - Internal subscribers fire FIRST, in registration order. User proc fires
-  #   LAST. Phase 04 reserves slot 0 of `value_change_internals` by convention.
+  #   LAST. Durable ValueVersion writing is installed on Value transactions;
+  #   this dispatcher does not own that write.
   #
   # ## Error policy (split, locked at 03-CONTEXT.md §User-callback error policy)
   #
-  # - Internal subscribers: exceptions PROPAGATE (fail-closed). Versioning
-  #   corruption must be loud — silent failure leaves typed_eav_value_versions
-  #   inconsistent with the live row. Without propagation, Phase 04 bugs
-  #   would be invisible until someone audited the version table.
+  # - Internal observers: exceptions PROPAGATE (fail-closed).
   # - User proc: rescued via `rescue StandardError`, logged via
   #   `Rails.logger.error`, and SWALLOWED. The Value/Field row is already
   #   committed by the time the after_commit fires, so re-raising here would
@@ -43,9 +38,8 @@ module TypedEAV
   # design decisions this module implements.
   module EventDispatcher
     class << self
-      # Internal subscribers for Value lifecycle events. Populated at engine
-      # boot by Phase 04 versioning (slot 0) and Phase 07 matview (subsequent
-      # slots). Exposed as a reader for test introspection — first-party
+      # Internal subscribers for Value lifecycle observers. Exposed as a
+      # reader for test introspection — first-party
       # registration goes through `register_internal_value_change`.
       def value_change_internals
         @value_change_internals ||= []
@@ -57,15 +51,12 @@ module TypedEAV
         @field_change_internals ||= []
       end
 
-      # Register an in-gem value-change subscriber. Called at engine boot by
-      # Phase 04 versioning and Phase 07 matview. Subscribers are invoked in
+      # Register an in-gem value-change observer. Observers are invoked in
       # registration order with `(value, change_type, context)`. Exceptions
-      # raised here PROPAGATE — fail-closed because versioning corruption
-      # must be loud. See module-level comment §"Error policy".
+      # raised here PROPAGATE. See module-level comment §"Error policy".
       #
-      # NOT private_class_method: Phase 04 lives in TypedEAV::Versioning::*
-      # and cannot call a truly-private class method. The `register_internal_*`
-      # naming + this comment signal first-party-only intent.
+      # NOT private_class_method: first-party code uses this named seam, and
+      # the `register_internal_*` naming signals its intended scope.
       def register_internal_value_change(callable)
         value_change_internals << callable
       end
@@ -87,9 +78,10 @@ module TypedEAV
       # `change_type` is one of `:create | :update | :destroy`.
       def dispatch_value_change(value, change_type)
         context = TypedEAV.current_context
-        # Internals fire first, in registration order. Exceptions propagate —
-        # versioning failure (Phase 04) must surface, never be silent.
-        value_change_internals.each { |cb| cb.call(value, change_type, context) }
+        # Internals fire first, in registration order. Exceptions propagate.
+        value_change_internals.each do |cb|
+          cb.call(value, change_type, context)
+        end
 
         user = TypedEAV::Config.on_value_change
         return unless user
@@ -137,11 +129,10 @@ module TypedEAV
       # `Config.on_value_change` / `Config.on_field_change` — `Config.reset!`
       # owns the user-proc state.
       #
-      # Splitting reset is load-bearing: Phase 04 versioning registers on the
-      # internal list at engine load. Calling `EventDispatcher.reset!` must
-      # NOT require re-running engine load to restore versioning. Test
-      # teardown that needs to clear EVERYTHING calls Config.reset! AND
-      # EventDispatcher.reset! — see 03-CONTEXT.md §"Reset split".
+      # Transactional versioning callbacks are independently boot-latched on
+      # Value; resetting this dispatcher only resets observer registrations.
+      # Test teardown that needs to clear EVERYTHING calls Config.reset! AND
+      # EventDispatcher.reset!.
       def reset!
         @value_change_internals = []
         @field_change_internals = []

data/lib/typed_eav/field/typed_storage.rb

@@ -155,6 +155,41 @@ module TypedEAV
         value_record[self.class.value_columns.first] = default_value
       end
 
+      # A logical value is missing only when every physical storage cell is
+      # nil. Multi-cell fields may legitimately be partially populated; such
+      # a row is present and must not be overwritten by a default backfill.
+      def logical_value_missing?(value_record)
+        self.class.value_columns.all? { |column| value_record[column].nil? }
+      end
+
+      # Normalize values before QueryBuilder emits SQL. Keeping this beside
+      # the write caster makes query and write semantics use the same rules.
+      def cast_query_operand(operator, raw)
+        case operator.to_sym
+        when :between
+          bounds = if raw.is_a?(Range)
+                     [raw.begin, raw.end]
+                   elsif raw.is_a?(Array) && raw.length == 2
+                     raw
+                   end
+          raise ArgumentError, ":between expects a Range or two-element Array" unless bounds
+
+          casted = bounds.map { |bound| cast_query_value(bound) }
+          casted.first..casted.last
+        when :any_eq
+          raise ArgumentError, ":any_eq expects a single array element" if raw.is_a?(Array)
+
+          values = cast_query_value([raw])
+          values&.first
+        when :all_eq
+          raise ArgumentError, ":all_eq expects an Array" unless raw.is_a?(Array)
+
+          cast_query_value(raw)
+        else
+          cast_query_value(raw)
+        end
+      end
+
       # ── Concrete snapshot helpers (NOT overridable) ──
 
       # True iff ANY of the field's value_columns had a saved change in the
@@ -200,6 +235,19 @@ module TypedEAV
           raise ArgumentError, "Unsupported change_type: #{change_type.inspect}"
         end
       end
+
+      private
+
+      def cast_query_value(raw)
+        casted, invalid = cast(raw)
+        raise ArgumentError, "Invalid #{self.class.name} query operand: #{raw.inspect}" if invalid
+
+        casted
+      rescue TypeError, ArgumentError => e
+        raise e if e.is_a?(ArgumentError) && e.message.start_with?("Invalid ")
+
+        raise ArgumentError, "Invalid #{self.class.name} query operand: #{raw.inspect}"
+      end
     end
   end
 end

data/lib/typed_eav/field_deletion.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Explicit, resumable deletion for large Field value populations. The public
+  # Field#destroy_with_values_in_batches! contract requires a persisted
+  # `field_dependent: :destroy` Field, positive batch size, no open transaction,
+  # and one shared Field/Value/ValueVersion connection pool.
+  module FieldDeletion
+    module_function
+
+    def destroy!(field, batch_size: 1_000)
+      validate!(field, batch_size)
+      last_id = 0
+
+      loop do
+        deleted = delete_batch!(field, last_id, batch_size)
+        break if deleted.empty?
+
+        last_id = deleted.last
+      end
+
+      finalize!(field, batch_size)
+    end
+
+    def validate!(field, batch_size)
+      raise ArgumentError, "field must be persisted" unless field.persisted?
+      raise ArgumentError, "field_dependent must be destroy" unless field.field_dependent == "destroy"
+      unless batch_size.is_a?(Integer) && batch_size.positive?
+        raise ArgumentError, "batch_size must be a positive Integer"
+      end
+      if field.class.connection.transaction_open?
+        raise ArgumentError, "destroy_with_values_in_batches! cannot run inside an open transaction"
+      end
+
+      pools = [field.class.connection_pool, TypedEAV::Value.connection_pool, TypedEAV::ValueVersion.connection_pool]
+      return if pools.uniq.size == 1
+
+      raise ArgumentError, "field deletion requires Field, Value, and ValueVersion to share a connection pool"
+    end
+    private_class_method :validate!
+
+    def delete_batch!(field, last_id, batch_size)
+      field.class.transaction do
+        values = locked_values(field.id, last_id, batch_size).to_a
+        values.each(&:destroy!)
+        values.map(&:id)
+      end
+    end
+    private_class_method :delete_batch!
+
+    def locked_values(field_id, last_id, limit)
+      TypedEAV::Value
+        .where(field_id: field_id)
+        .where("id > ?", last_id)
+        .order(:id)
+        .limit(limit)
+        .lock
+    end
+    private_class_method :locked_values
+
+    def finalize!(field, batch_size)
+      field.class.transaction do
+        field.lock!
+        values = locked_values(field.id, 0, batch_size + 1).to_a
+        raise "field deletion residual drain exceeded batch_size" if values.size > batch_size
+
+        values.each(&:destroy!)
+        raise "field deletion residual proof failed" if TypedEAV::Value.exists?(field_id: field.id)
+
+        field.destroy!
+      end
+    end
+    private_class_method :finalize!
+  end
+end

data/lib/typed_eav/filter_query.rb

@@ -106,10 +106,10 @@ module TypedEAV
 
     def lookup_definitions
       if all_scopes?
-        TypedEAV::Partition.visible_fields(entity_type: model.name, mode: :all_partitions)
+        TypedEAV::Partition.visible_fields(entity_type: model.polymorphic_name, mode: :all_partitions)
       else
         TypedEAV::Partition.visible_fields(
-          entity_type: model.name,
+          entity_type: model.polymorphic_name,
           scope: @scope,
           parent_scope: @parent_scope,
         )

data/lib/typed_eav/has_typed_eav/instance_methods.rb

@@ -262,7 +262,7 @@ module TypedEAV
       # because each record's INSERT clears the cache — so cache-do alone
       # cannot keep field-definition reads N+1-free across the bulk loop.
       # The thread-local memo is the explicit fallback documented in plan
-      # 06-05 §T3 notes; it pre-warms once per `[host_class, scope,
+      # 06-05 §T3 notes; it pre-warms once per `[polymorphic_name, scope,
       # parent_scope]` tuple and reuses across every record in that tuple.
       #
       # Outside a bulk operation the memo is nil and we fall through to
@@ -270,7 +270,7 @@ module TypedEAV
       def typed_eav_defs_by_name
         memo = Thread.current[:typed_eav_bulk_defs_memo]
         if memo
-          key = [self.class.name, typed_eav_scope, typed_eav_parent_scope]
+          key = [self.class.polymorphic_name, typed_eav_scope, typed_eav_parent_scope]
           memo[key] ||= TypedEAV::Partition.definitions_by_name(typed_eav_definitions)
         else
           TypedEAV::Partition.definitions_by_name(typed_eav_definitions)

data/lib/typed_eav/has_typed_eav.rb

@@ -93,7 +93,7 @@ module TypedEAV
 
         accepts_nested_attributes_for :typed_values, allow_destroy: true
 
-        TypedEAV.registry.register(name, types: types, versioned: versioned)
+        TypedEAV.registry.register(polymorphic_name, types: types, versioned: versioned)
       end
 
       private

data/lib/typed_eav/partition/definition_batch.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Partition
+    # Internal batched resolver for field definitions visible to many exact
+    # partition tuples. It performs one definition SELECT, then applies the
+    # same global -> scope -> full-tuple precedence as `definitions_by_name`
+    # independently for every requested tuple.
+    class DefinitionBatch
+      class << self
+        def resolve(entity_type:, tuples:)
+          new(entity_type: entity_type, tuples: tuples).resolve
+        end
+      end
+
+      def initialize(entity_type:, tuples:)
+        @entity_type = entity_type
+        @tuples = tuples.uniq
+      end
+
+      def resolve
+        tuples.each { |scope, parent_scope| validate_tuple!(scope, parent_scope) }
+        return {} if tuples.empty?
+
+        definitions_by_tuple = load_definitions.group_by do |definition|
+          [definition.scope, definition.parent_scope]
+        end
+
+        tuples.to_h do |tuple|
+          visible = candidate_tuples(tuple).flat_map { |candidate| definitions_by_tuple.fetch(candidate, []) }
+          [tuple, TypedEAV::Partition.definitions_by_name(visible)]
+        end
+      end
+
+      private
+
+      attr_reader :entity_type, :tuples
+
+      def load_definitions
+        requested = tuples.map { |scope, parent_scope| { "scope" => scope, "parent_scope" => parent_scope } }
+        TypedEAV::Field::Base.where(entity_type: entity_type).where(<<~SQL.squish, requested.to_json).to_a
+          typed_eav_fields.scope IS NULL AND typed_eav_fields.parent_scope IS NULL
+          OR EXISTS (
+            SELECT 1
+            FROM jsonb_to_recordset(?::jsonb) AS requested(scope text, parent_scope text)
+            WHERE (
+              typed_eav_fields.scope IS NOT DISTINCT FROM requested.scope
+              AND typed_eav_fields.parent_scope IS NOT DISTINCT FROM requested.parent_scope
+            )
+            OR (
+              typed_eav_fields.scope IS NOT DISTINCT FROM requested.scope
+              AND typed_eav_fields.parent_scope IS NULL
+            )
+          )
+        SQL
+      end
+
+      def candidate_tuples(tuple)
+        scope, parent_scope = tuple
+        [[nil, nil], [scope, nil], [scope, parent_scope]].uniq
+      end
+
+      def validate_tuple!(scope, parent_scope)
+        return if TypedEAV::ScopeTuple.invariant_satisfied?(scope, parent_scope)
+
+        raise ArgumentError, "parent_scope cannot be set when scope is blank"
+      end
+    end
+  end
+end

data/lib/typed_eav/partition.rb

@@ -8,6 +8,8 @@ module TypedEAV
   # values. Ambient resolution (`TypedEAV.current_scope`, `with_scope`,
   # `unscoped`) stays with the adapters that know their calling context.
   module Partition
+    autoload :DefinitionBatch, "typed_eav/partition/definition_batch"
+
     # Frozen orphan-parent ArgumentError message. Kept as a module constant
     # so both `visible_fields` and `visible_sections` raise the same string
     # without re-allocating per call. The string is the wire-stable BC error