typed_eav 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37b913418c998e4620c90efb72a0be8c93b838a2977db0347c9198b743ced2f3
-  data.tar.gz: 0a8a7f3a622712cc29b5738b8b0f4a54e3df3ffc56657277a69ebb956d3c46bf
+  metadata.gz: 312b444b0c7b29eb298af1ef5bba02d3ba56ad811399b3ffcd2dfd2afd88267b
+  data.tar.gz: cfa3ca85088eaff46dff6657d098f9fcf38fec9129b53792cfb37cc19e4358ad
 SHA512:
-  metadata.gz: c5bdc06300d8bb92538c93cfe23ac3afb6bed9719a29f6f7590740e6d4f56ac14998e21b4230c58fa2eed10e89dfe053af86144f3cbcf9637049c3d5b811d90b
-  data.tar.gz: 4760251616a62f91b7ed931dafc8b92a25653047cab8fcbd21dd027fe6353fdd2e7209a0629233306c69f77ec8eec08459854e8cc81443595d0b68e0503f4e8b
+  metadata.gz: abcb3cde1dc9d09da1ea014165c245d74aa2ef2f5fd566ecc9f86343b8e30b1ca32bcc10eb9735a06a23641bb0ccef7c1078d2be288a724a20b6d7e44468e6d9
+  data.tar.gz: b259edd0ece6e756569a151194368fc0adda83063d56683f9113d6373c0eede174cb545f9d1ca0ccc70e2dd512239494299f3da8608567aa5e47989e3b780eb3

data/CHANGELOG.md

@@ -7,7 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-No unreleased changes.
+## [0.7.1] - 2026-09-04
+
+A focused patch release for inherited Active Record hosts and multi-partition
+bulk upserts. No new database migrations or public API changes are required.
+
+### Fixed
+
+- Resolve inherited and namespaced Active Record host definitions, filters,
+  bulk reads, writes, and registry/versioning opt-ins through Rails'
+  canonical polymorphic name. STI subclasses now consistently share their
+  base class's EAV schema and stored values while queries retain their host
+  class restriction. Partition isolation and most-specific field precedence
+  are preserved. (#42)
+
+### Performance
+
+- Batch BulkUpsert field-definition resolution into one SELECT per transaction
+  unit while preserving exact tuple isolation and definition precedence. A
+  20-partition regression case now issues one definition SELECT instead of 20;
+  chunked transactions intentionally issue one per chunk. BulkRead and
+  BulkUpsert share the internal batched resolver. This is a query-count
+  improvement, not a universal throughput claim. (#43)
+
+### Compatibility and verification
+
+- BulkUpsert's reduced-semantics acknowledgement, validation, transaction
+  boundaries, and callback/versioning behavior are unchanged.
+- Regression coverage includes true STI and namespaced hosts, public
+  read/filter/write paths, partition isolation, definition precedence, and
+  all/chunk transaction behavior.
 
 ## [0.7.0] - 2026-08-18
 
@@ -580,7 +609,8 @@ worked examples.
 
 Initial release.
 
-[Unreleased]: https://github.com/dchuk/typed_eav/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/dchuk/typed_eav/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.7.1
 [0.7.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.6.0
 [0.5.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.5.0

data/README.md

@@ -119,6 +119,11 @@ tags.field_options.create!([
 ])
 ```
 
+When deriving `entity_type` from a model class, use
+`Contact.polymorphic_name`. Rails stores polymorphic associations under that
+canonical name, which is the base-class type for STI hosts and respects the
+application's namespaced-polymorphism setting.
+
 ### 3. Set values on records
 
 ```ruby
@@ -1157,7 +1162,7 @@ directly:
 
 ```ruby
 TypedEAV::ValueVersion
-  .where(entity_type: contact.class.name, entity_id: contact.id, field_id: age_field.id)
+  .where(entity_type: contact.class.polymorphic_name, entity_id: contact.id, field_id: age_field.id)
   .order(changed_at: :desc, id: :desc)
 # => [<ValueVersion change_type: "destroy" before: {"integer_value" => 42} after: {} value_id: nil>,
 #     <ValueVersion change_type: "update"  before: {"integer_value" => 41} after: {"integer_value" => 42} value_id: nil>,
@@ -1176,7 +1181,7 @@ exports) — drop the `field_id` filter:
 
 ```ruby
 TypedEAV::ValueVersion
-  .where(entity_type: contact.class.name, entity_id: contact.id)
+  .where(entity_type: contact.class.polymorphic_name, entity_id: contact.id)
   .order(changed_at: :desc, id: :desc)
 # => all version rows for every typed field on this contact, most-recent-first.
 # Includes :create, :update, and :destroy events across every field the
@@ -1416,6 +1421,10 @@ TypedEAV::QueryBuilder                ← low altitude: per-field SQL primitive
 3. Returns a `{record_id => {field_name => value}}` map while skipping orphaned
    values and preserving logical missingness.
 
+Definitions, filters, reads, registry entries, and writes all use the host's
+Rails `polymorphic_name`, so an STI leaf class reads and queries the same rows
+written under its base-class polymorphic type.
+
 The final production characterization reduced the 1,002 SQL statements observed
 across 1,000 scopes to three for the same BulkRead shape. This is a statement-
 count result, not a representative throughput claim; applications should still
@@ -1459,6 +1468,12 @@ checks, and Value validation callbacks remain; host callbacks and validations,
 Value persistence callbacks, versioning, delete shorthand, and per-record
 savepoint isolation are skipped.
 
+Within each `transaction: :all` unit—or each requested chunk—the upsert path
+resolves every record partition through one batched field-definition SELECT.
+It shares BulkRead's internal tuple resolver, retaining global, scope-only, and
+full-tuple precedence independently for each record without broadening tenant
+visibility.
+
 `BulkWrite` and `BulkRead` are siblings — one read path, one write path — but they don't share a base class. Per [ADR-0005](docs/adr/0005-keep-phase-six-modules-independent.md), keeping them independent preserves the option to evolve each on its own schedule.
 
 ### Per-record reads/writes: `InstanceMethods`

data/lib/typed_eav/bulk_read.rb

@@ -10,8 +10,8 @@ module TypedEAV
   #
   #   1. validate_records!    — nil -> ArgumentError; single-class invariant
   #   2. group_by_tuple       — `[typed_eav_scope, typed_eav_parent_scope]`
-  #   3. winning_ids_by_tuple — one exact-partition definition query, then
-  #                             `Partition.definitions_by_name` per tuple
+  #   3. winning_ids_by_tuple — one `Partition::DefinitionBatch` query, then
+  #                             extract the winning field ids per tuple
   #   4. preload_values       — single SELECT across ALL records
   #   5. build_result_hash    — per-record inner hash; orphan-skip + winning-id
   #                             precedence mirrored from the instance path.
@@ -26,9 +26,10 @@ module TypedEAV
   #
   # ## Single-class invariant
   #
-  # The polymorphic value query (`entity_type: host_class.name`) targets ONE
-  # class; mixed-class input would silently miss rows of the other class. STI
-  # subclasses pass via `records.all?(host_class)`.
+  # The polymorphic value query targets the host's canonical Rails
+  # `polymorphic_name`, so an STI subclass reads rows stored for its base
+  # class. Mixed, unrelated input would still be invalid; STI subclasses pass
+  # via `records.all?(host_class)`.
   class BulkRead
     def initialize(host_class:, records:)
       @host_class = host_class
@@ -73,49 +74,15 @@ module TypedEAV
     end
 
     def winning_ids_by_tuple(tuples)
-      definitions_by_tuple = batched_definitions(tuples).group_by do |definition|
-        [definition.scope, definition.parent_scope]
-      end
-
-      tuples.to_h do |tuple|
-        s, ps = tuple
-        candidate_tuples = [[nil, nil], [s, nil], [s, ps]].uniq
-        visible = candidate_tuples.flat_map { |candidate| definitions_by_tuple.fetch(candidate, []) }
-        [tuple, TypedEAV::Partition.definitions_by_name(visible).transform_values(&:id)]
-      end
-    end
-
-    def batched_definitions(tuples)
-      tuples.each { |scope, parent_scope| validate_tuple!(scope, parent_scope) }
-      relation = TypedEAV::Field::Base.where(entity_type: host_class.name)
-      requested = tuples.map { |scope, parent_scope| { "scope" => scope, "parent_scope" => parent_scope } }
-      relation.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 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"
+      TypedEAV::Partition::DefinitionBatch
+        .resolve(entity_type: host_class.polymorphic_name, tuples: tuples)
+        .transform_values { |fields_by_name| fields_by_name.transform_values(&:id) }
     end
 
     def preload_values(records)
       rows = TypedEAV::Value
              .includes(:field)
-             .where(entity_type: host_class.name, entity_id: records.map(&:id))
+             .where(entity_type: host_class.polymorphic_name, entity_id: records.map(&:id))
              .to_a
       rows.group_by(&:entity_id)
     end

data/lib/typed_eav/bulk_upsert.rb

@@ -8,7 +8,8 @@ module TypedEAV
   # persistence callbacks, versioning, or per-record error isolation. Callers must
   # acknowledge those semantics explicitly. It pre-casts and validates every
   # row in a transaction unit before issuing one upsert batch on the host
-  # model's connection. Scope resolution and field casting remain authoritative.
+  # model's connection. Field definitions for every tuple in that unit resolve
+  # in one batch; scope precedence and field casting remain authoritative.
   module BulkUpsert
     TYPE_COLUMNS = %i[
       string_value text_value boolean_value integer_value decimal_value date_value datetime_value json_value
@@ -36,19 +37,14 @@ module TypedEAV
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- tuple grouping, validation, and row construction are one durability unit.
       def write_unit(host_class, records, values_by_field_name)
         tuples = records.map { |record| [record.typed_eav_scope, record.typed_eav_parent_scope] }.uniq
-        fields_by_tuple = tuples.to_h do |tuple|
-          # Use the exact tuple at the partition layer. EntityQuery treats
-          # explicit scope kwargs as ALL_SCOPES inside TypedEAV.unscoped;
-          # that administrative bypass must not cross-contaminate tenants.
-          fields = TypedEAV::Partition.definitions_by_name(
-            TypedEAV::Partition.visible_fields(
-              entity_type: host_class.polymorphic_name,
-              scope: tuple[0],
-              parent_scope: tuple[1],
-            ),
-          )
-          [tuple, fields]
-        end
+        # Resolve every exact tuple in this transaction unit with one query.
+        # The shared resolver preserves global/scope/full-tuple precedence per
+        # tuple and never observes EntityQuery's administrative ALL_SCOPES
+        # bypass, so tenants remain isolated inside an unscoped block.
+        fields_by_tuple = TypedEAV::Partition::DefinitionBatch.resolve(
+          entity_type: host_class.polymorphic_name,
+          tuples: tuples,
+        )
         rows = records.flat_map do |record|
           fields = fields_by_tuple.fetch([record.typed_eav_scope, record.typed_eav_parent_scope])
           values_by_field_name.filter_map do |name, raw|

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
 

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

data/lib/typed_eav/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

data/lib/typed_eav/versioned.rb

@@ -62,12 +62,14 @@ module TypedEAV
 
       # Re-register with versioned: true. Preserve the existing types:
       # restriction by reading the current Registry entry.
-      # has_typed_eav already called register(name, types: types,
-      # versioned: false) — we overwrite with versioned: true while
-      # keeping the same types. If the entry doesn't exist (defensive
-      # — shouldn't happen post-has_typed_eav), default types to nil.
-      existing = TypedEAV.registry.entities[name] || {}
-      TypedEAV.registry.register(name, types: existing[:types], versioned: true)
+      # has_typed_eav already registered the canonical Rails polymorphic
+      # name. Reuse it here so including this concern on an STI subclass
+      # enables versioning for the base entity_type actually stored on Value.
+      # If the entry doesn't exist (defensive — shouldn't happen post-
+      # has_typed_eav), default types to nil.
+      entity_type = polymorphic_name
+      existing = TypedEAV.registry.entities[entity_type] || {}
+      TypedEAV.registry.register(entity_type, types: existing[:types], versioned: true)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_eav
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - dchuk
@@ -159,6 +159,7 @@ files:
 - lib/typed_eav/has_typed_eav.rb
 - lib/typed_eav/has_typed_eav/instance_methods.rb
 - lib/typed_eav/partition.rb
+- lib/typed_eav/partition/definition_batch.rb
 - lib/typed_eav/query_builder.rb
 - lib/typed_eav/registry.rb
 - lib/typed_eav/schema_portability.rb