typed_eav 0.5.0 → 0.7.0

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

@@ -147,9 +147,7 @@ module TypedEAV
           # field def has a non-NULL value for it. Union the non-missing
           # entity_ids across all per-tenant field defs, then complement at
           # the host level. ADR-0006.
-          non_missing_ids = fields.flat_map do |f|
-            TypedEAV::QueryBuilder.entity_ids(f, :is_not_null, nil).pluck(:entity_id)
-          end.uniq
+          non_missing_ids = union_entity_ids(fields, :is_not_null, nil)
           query.where.not(id: non_missing_ids)
         else
           union_ids = union_entity_ids(fields, spec[:operator], spec[:value])
@@ -168,11 +166,15 @@ module TypedEAV
     end
 
     # OR-across all field_ids that share the same name (across tenants),
-    # while preserving AND between filters via the chained `.where`. Use the
-    # underlying Value scope (`.filter`) and `pluck(:entity_id)` to collapse
-    # to a plain integer array we can union across tenants.
+    # while preserving AND between filters via the chained `.where`. Keep the
+    # union as a composable entity-id subquery so matching IDs never need to
+    # be materialized in Ruby.
     def union_entity_ids(fields, operator, value)
-      fields.flat_map { |f| TypedEAV::QueryBuilder.filter(f, operator, value).pluck(:entity_id) }.uniq
+      fields
+        .map { |field| TypedEAV::QueryBuilder.filter(field, operator, value) }
+        .reduce { |union, relation| union.or(relation) }
+        .distinct
+        .select(:entity_id)
     end
 
     def parse_filter(filter)

data/lib/typed_eav/has_typed_eav/instance_methods.rb

@@ -166,13 +166,14 @@ module TypedEAV
         typed_values.filter_map { |tv| tv.field_id || tv.field&.id }
       end
 
-      # Selects the candidate value for `typed_eav_value`. On a collision,
-      # prefer the row attached to the winning field_id; otherwise fall back
-      # to the first orphan/non-collision candidate.
+      # Selects the candidate value for `typed_eav_value`. When a definition
+      # wins for the current partition, only a row attached to that field_id
+      # may surface. Retained rows from a host's former partition must not be
+      # used as a fallback when the current winner has no value yet.
       def select_winning_value(candidates, winning)
         return candidates.first unless winning
 
-        candidates.detect { |v| (v.field_id || v.field&.id) == winning.id } || candidates.first
+        candidates.detect { |v| (v.field_id || v.field&.id) == winning.id }
       end
 
       # Hash-builder helper for `typed_eav_hash`. When a winner is registered
@@ -234,10 +235,12 @@ module TypedEAV
       # fast without forcing that contract.
       def loaded_typed_values_with_fields
         if typed_values.loaded?
-          # Don't re-query if the caller already preloaded; ensure each value's
-          # field is materialized (fall back to per-row load if the nested
-          # `:field` was not preloaded).
-          typed_values.to_a
+          values = typed_values.to_a
+          missing_fields = values.reject { |value| value.association(:field).loaded? }
+          if missing_fields.any?
+            ActiveRecord::Associations::Preloader.new(records: missing_fields, associations: :field).call
+          end
+          values
         else
           typed_values.includes(:field).to_a
         end

data/lib/typed_eav/partition.rb

@@ -21,13 +21,18 @@ module TypedEAV
       # scope-only rows, and full-tuple rows. Passing mode: :all_partitions is
       # the deliberate admin bypass; it is distinct from `scope: nil`, which
       # means the global partition only.
-      def visible_fields(entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+      def visible_fields(entity_type: nil, scope: nil, parent_scope: nil, mode: :partition)
         validate_mode!(mode)
-        return TypedEAV::Field::Base.where(entity_type: entity_type) if mode == :all_partitions
+        fields = TypedEAV::Field::Base.all
+        fields = fields.where(entity_type: entity_type) if entity_type
+        return fields if mode == :all_partitions
 
         raise ArgumentError, ORPHAN_PARENT_MESSAGE unless ScopeTuple.invariant_satisfied?(scope, parent_scope)
 
-        TypedEAV::Field::Base.for_entity(entity_type, scope: scope, parent_scope: parent_scope)
+        fields.where(
+          scope: [scope, nil].uniq,
+          parent_scope: [parent_scope, nil].uniq,
+        )
       end
 
       # One visible field per name after collision resolution. Most-specific

data/lib/typed_eav/query_builder.rb

@@ -3,16 +3,10 @@
 module TypedEAV
   # Replaces the per-type Finder class hierarchy from active_fields.
   #
-  # Because values live in native typed columns, ActiveRecord already knows
-  # the column types from the schema. Arel predicates (eq, gt, lt, matches, etc.)
-  # automatically go through the column's ActiveRecord::Type for casting.
-  #
-  # This means:
-  #   where(integer_value: "42")  ->  Rails casts "42" to 42 automatically
-  #   arel[:date_value].gt(value) ->  Rails casts string dates to Date objects
-  #
-  # No manual CAST() calls. No per-type caster classes for queries.
-  # One module handles all field types.
+  # Field owns operand casting and operator validation before this layer builds
+  # Arel. Active Record supplies bind plumbing for the already-normalized
+  # typed value; no manual SQL CAST() calls or per-type query caster classes
+  # are needed here.
   #
   # Usage:
   #   QueryBuilder.filter(field, :gt, 42)
@@ -53,6 +47,8 @@ module TypedEAV
         arel_col = values_table[col]
 
         base = value_scope(field)
+        excluded = %i[is_null is_not_null contains not_contains starts_with ends_with]
+        operand = field.cast_query_operand(operator, value) unless excluded.include?(operator)
 
         case operator
         when :eq, :currency_eq
@@ -64,9 +60,9 @@ module TypedEAV
           # dispatch resolved correctly. The operator-validation gate at
           # the top of #filter still narrows :currency_eq to Field::Currency
           # only — no other field type accepts it.
-          eq_predicate(base, arel_col, col, value)
+          eq_predicate(base, arel_col, col, operand)
         when :not_eq
-          not_eq_predicate(base, arel_col, col, value)
+          not_eq_predicate(base, arel_col, col, operand)
         when :references
           # Phase 5 Reference field. `value` may be an Integer FK OR an
           # AR record instance — `field.cast` normalizes both to an
@@ -79,27 +75,21 @@ module TypedEAV
           # The :references operator is registered ONLY on Field::Reference
           # (the operator-validation gate above keeps it from leaking to
           # other types).
-          fk, invalid = field.cast(value)
-          if invalid || fk.nil?
+          if operand.nil?
             base.none
           else
-            base.where(arel_col.eq(fk))
+            base.where(arel_col.eq(operand))
           end
         when :gt
-          base.where(arel_col.gt(value))
+          base.where(arel_col.gt(operand))
         when :gteq
-          base.where(arel_col.gteq(value))
+          base.where(arel_col.gteq(operand))
         when :lt
-          base.where(arel_col.lt(value))
+          base.where(arel_col.lt(operand))
         when :lteq
-          base.where(arel_col.lteq(value))
+          base.where(arel_col.lteq(operand))
         when :between
-          unless value.respond_to?(:first) && value.respond_to?(:last)
-            raise ArgumentError,
-                  ":between expects a Range or two-element Array"
-          end
-
-          base.where(arel_col.between(value.first..value.last))
+          base.where(arel_col.between(operand))
         when :contains
           base.where(arel_col.matches("%#{sanitize_like(value)}%"))
         when :not_contains
@@ -114,10 +104,10 @@ module TypedEAV
           base.where.not(col => nil)
         when :any_eq
           # For json_value arrays: contains the given element
-          base.where("#{col} @> ?", [value].to_json)
+          base.where("#{col} @> ?", [operand].to_json)
         when :all_eq
           # For json_value arrays: contains all given elements
-          base.where("#{col} @> ?", Array(value).to_json)
+          base.where("#{col} @> ?", operand.to_json)
         else
           raise ArgumentError, "Unhandled operator: #{operator}"
         end

data/lib/typed_eav/registry.rb

@@ -25,12 +25,11 @@ module TypedEAV
       # Register an entity type with optional type restrictions and optional
       # versioning opt-in.
       #
-      # `versioned:` is the per-entity Phase 04 opt-in flag. When true, AND
-      # `Config.versioning = true` at engine load (gem-level master switch),
-      # the Phase 04 subscriber writes a TypedEAV::ValueVersion row per
-      # Value mutation on this entity_type. Default false — apps not using
-      # versioning pay zero cost (one Hash#dig per write at most when
-      # `Config.versioning = true`, nothing when off).
+      # `versioned:` is the per-entity opt-in flag. When true and the
+      # boot-latched transactional callbacks are installed, the version
+      # writer records a TypedEAV::ValueVersion row per Value mutation on
+      # this entity_type. Default false — apps not using versioning pay zero
+      # version-row work.
       #
       # Backward compat: existing callers `register(name, types: types)`
       # continue to work — the new kwarg defaults to false. The entry hash
@@ -69,8 +68,8 @@ module TypedEAV
       # Returns the stored boolean for opted-in entities; false for
       # unregistered entities (defensive — callers might query before
       # `has_typed_eav` runs in a particular load order). The Phase 04
-      # subscriber calls this on every Value write when `Config.versioning =
-      # true` — performance is one Hash#dig per write, negligible.
+      # transactional writer calls this only after its boot-latched callback
+      # has been installed; this lookup remains a small Hash#dig per write.
       #
       # `entities.dig(entity_type, :versioned)` returns nil when
       # `entities[entity_type]` is missing (no register call) OR when the

data/lib/typed_eav/schema_portability/import_index.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module SchemaPortability
+    class ImportIndex
+      attr_reader :fields, :sections
+
+      def initialize(field_entries, section_entries)
+        @fields = preload_fields(field_entries)
+        @sections = preload_sections(section_entries)
+      end
+
+      def field_identity(field_or_entry)
+        identity(field_or_entry, :name)
+      end
+
+      def section_identity(section_or_entry)
+        identity(section_or_entry, :code)
+      end
+
+      private
+
+      def preload_fields(entries)
+        return {} if entries.empty?
+
+        identity_relation(TypedEAV::Field::Base, entries, :name)
+          .includes(:field_options)
+          .index_by { |field| field_identity(field) }
+      end
+
+      def preload_sections(entries)
+        return {} if entries.empty?
+
+        identity_relation(TypedEAV::Section, entries, :code)
+          .index_by { |section| section_identity(section) }
+      end
+
+      def identity_relation(model, entries, key)
+        relations = entries.uniq { |entry| identity(entry, key) }.map do |entry|
+          model.where(
+            key => entry[key.to_s],
+            entity_type: entry["entity_type"],
+            scope: entry["scope"],
+            parent_scope: entry["parent_scope"],
+          )
+        end
+        relations.reduce { |union, relation| union.or(relation) }
+      end
+
+      def identity(record_or_entry, key)
+        attributes = [key, :entity_type, :scope, :parent_scope]
+        return attributes.map { |attribute| record_or_entry[attribute.to_s] } if record_or_entry.is_a?(Hash)
+
+        attributes.map { |attribute| record_or_entry.public_send(attribute) }
+      end
+    end
+  end
+end

data/lib/typed_eav/schema_portability.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "schema_portability/import_index"
+
 module TypedEAV
   # Export and import field + section definitions for an exact partition
   # tuple. Value rows are intentionally out of scope.
@@ -89,14 +91,18 @@ module TypedEAV
         validate_conflict_policy!(on_conflict)
 
         result = { "created" => 0, "updated" => 0, "skipped" => 0, "unchanged" => 0, "errors" => [] }
+        field_entries = Array(hash["fields"])
+        section_entries = Array(hash["sections"])
 
         TypedEAV::Field::Base.transaction do
-          Array(hash["fields"]).each do |entry|
-            import_field_entry(entry, on_conflict, result)
+          import_index = ImportIndex.new(field_entries, section_entries)
+
+          field_entries.each do |entry|
+            import_field_entry(entry, on_conflict, result, import_index)
           end
 
-          Array(hash["sections"]).each do |entry|
-            import_section_entry(entry, on_conflict, result)
+          section_entries.each do |entry|
+            import_section_entry(entry, on_conflict, result, import_index)
           end
         end
 
@@ -105,7 +111,7 @@ module TypedEAV
 
       private
 
-      # rubocop:disable Metrics/AbcSize -- flat projection is the canonical field export shape.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- flat projection is the canonical field export shape.
       def export_field_entry(field)
         entry = {
           "name" => field.name,
@@ -141,7 +147,7 @@ module TypedEAV
 
         entry
       end
-      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Lean per-field projection used by {.export_snapshot_schema}. Mirrors
       # the option-row ordering rule from {.export_field_entry} — sort
@@ -207,13 +213,9 @@ module TypedEAV
               "Supported: #{valid_policies.map { |policy| ":#{policy}" }.join(", ")}."
       end
 
-      def import_field_entry(entry, on_conflict, result)
-        existing = TypedEAV::Field::Base.find_by(
-          name: entry["name"],
-          entity_type: entry["entity_type"],
-          scope: entry["scope"],
-          parent_scope: entry["parent_scope"],
-        )
+      def import_field_entry(entry, on_conflict, result, import_index)
+        identity = import_index.field_identity(entry)
+        existing = import_index.fields[identity]
 
         if existing
           reject_type_swap!(existing, entry)
@@ -233,7 +235,7 @@ module TypedEAV
             result["updated"] += 1
           end
         else
-          create_field!(entry)
+          import_index.fields[identity] = create_field!(entry)
           result["created"] += 1
         end
       end
@@ -282,7 +284,7 @@ module TypedEAV
 
       def create_field!(entry)
         field = TypedEAV::Field::Base.create!(entry.except("options_data"))
-        return unless field.optionable?
+        return field unless field.optionable?
 
         Array(entry["options_data"]).each do |option|
           field.field_options.create!(
@@ -291,16 +293,12 @@ module TypedEAV
             sort_order: option["sort_order"],
           )
         end
+        field
       end
 
-      # rubocop:disable Metrics/MethodLength -- mirrors field import for section rows without option replacement.
-      def import_section_entry(entry, on_conflict, result)
-        existing = TypedEAV::Section.find_by(
-          code: entry["code"],
-          entity_type: entry["entity_type"],
-          scope: entry["scope"],
-          parent_scope: entry["parent_scope"],
-        )
+      def import_section_entry(entry, on_conflict, result, import_index)
+        identity = import_index.section_identity(entry)
+        existing = import_index.sections[identity]
 
         if existing
           if section_export_row_equal?(existing, entry)
@@ -322,11 +320,10 @@ module TypedEAV
             result["updated"] += 1
           end
         else
-          TypedEAV::Section.create!(entry)
+          import_index.sections[identity] = TypedEAV::Section.create!(entry)
           result["created"] += 1
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       def raise_divergent_section!(entry)
         raise ArgumentError,

data/lib/typed_eav/version.rb

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

data/lib/typed_eav/versioning/subscriber.rb

@@ -2,15 +2,15 @@
 
 module TypedEAV
   module Versioning
-    # The Phase 04 internal subscriber. Conditionally registered with
-    # EventDispatcher.register_internal_value_change at engine boot via
-    # `TypedEAV::Versioning.register_if_enabled`. When registered, runs
-    # at slot 0 of the value-change subscriber chain.
+    # The transactional version writer. Conditionally installed on Value's
+    # create/update `after` and destroy `before` callbacks at engine boot via
+    # `TypedEAV::Versioning.register_if_enabled`; every write is therefore
+    # part of the source transaction.
     #
     # ## Contract
     #
-    # `call(value, change_type, context)` — called by EventDispatcher.
-    # Returns nil (return value is ignored by EventDispatcher; the
+    # `call(value, change_type, context)` — called by Value's lifecycle
+    # callback. Returns nil (the return value is ignored; the
     # method's job is the side effect of writing a ValueVersion row).
     #
     # Two-gate short-circuit (the master switch is enforced at
@@ -54,16 +54,13 @@ module TypedEAV
     # nil").
     module Subscriber
       class << self
-        # Public entry point. EventDispatcher calls this with the locked
-        # 3-arg signature `(value, change_type, context)`.
+        # Public entry point. Value's transactional callbacks call this with
+        # the locked 3-arg signature `(value, change_type, context)`.
         #
-        # NOTE: there is NO `Config.versioning` gate here. The subscriber
-        # is only registered with EventDispatcher when `Config.versioning`
-        # was true at engine `config.after_initialize` time (see
-        # `TypedEAV::Versioning.register_if_enabled`, invoked from
-        # lib/typed_eav/engine.rb's `config.after_initialize` block). If
-        # versioning is off, the subscriber is never registered and never
-        # reached. The remaining gates are:
+        # NOTE: there is NO `Config.versioning` gate here. The subscriber is
+        # installed only when `Config.versioning` was true at engine
+        # `config.after_initialize` time. If versioning is off, the callback
+        # is never installed and this method is never reached. The remaining gates are:
         #   1. field-presence (orphan guard — Value's field_id may have
         #      been NULLed by Phase 02's ON DELETE SET NULL cascade).
         #   2. per-entity opt-in (Registry.versioned?).
@@ -72,6 +69,8 @@ module TypedEAV
           return unless TypedEAV.registry.versioned?(value.entity_type)
 
           write_version_row(value, change_type, context)
+        ensure
+          value.consume_pending_version_group_id if value.respond_to?(:consume_pending_version_group_id)
         end
 
         private
@@ -85,15 +84,9 @@ module TypedEAV
           before_value = field.before_snapshot(value, change_type)
           after_value  = field.after_snapshot(value, change_type)
 
-          # CRITICAL: for :destroy events, write `value_id: nil`.
-          # By the time `after_commit on: :destroy` fires, the parent row
-          # in `typed_eav_values` has already been deleted (Postgres
-          # commits the DELETE before invoking after_commit callbacks).
-          # The FK is `ON DELETE SET NULL`, but at the moment we INSERT
-          # the version row, Postgres validates the FK against the
-          # current state of typed_eav_values — which no longer contains
-          # the parent. Writing `value.id` (still readable in-memory on
-          # the destroyed AR record) would FK-fail at INSERT.
+          # CRITICAL: for :destroy events, write `value_id: nil`. The row is
+          # written before the source DELETE and must not retain an identity
+          # that the FK will null when the Value is removed.
           #
           # The audit trail for destroy events stays queryable via:
           #   - entity_type + entity_id (host record identity)
@@ -102,8 +95,7 @@ module TypedEAV
           # `field_id` remains populated because destroying a Value does
           # not destroy its Field — `value.field_id` is a live reference.
           #
-          # For :create and :update events, `value_id: value.id` is
-          # correct (parent row exists at after_commit time).
+          # For :create and :update, `value_id: value.id` is correct.
           version_value_id = change_type == :destroy ? nil : value.id
 
           # Phase 06 bulk-operations correlation tag. Two delivery paths:
@@ -113,7 +105,7 @@ module TypedEAV
           #    on each affected Value object BEFORE `record.save`, INSIDE
           #    the per-record `with_context` block. Reading the snapshot
           #    here (not `current_context`) guarantees the UUID survives
-          #    the outer-transaction `after_commit` boundary — by the time
+          #    the source transaction boundary — by the time
           #    we run, the lexical `with_context` block has unwound and
           #    `current_context` would be empty, but the per-Value ivar
           #    persists. Mirrors the existing in-memory ivar pattern at
@@ -127,12 +119,16 @@ module TypedEAV
           #    request id). For those paths the Value ivar is unset; the
           #    `||` falls through to `context[:version_group_id]`. Also
           #    used as the belt-and-suspenders fallback for any future
-          #    after_commit-inside-savepoint dispatch path that bulk writes
+          #    savepoint path that bulk writes
           #    might leverage.
           #
           # When neither path supplies a UUID the column (added in
           # `db/migrate/20260506000001`) stays NULL — backward-compatible:
           # unchanged subscribers and unchanged callers continue to work.
+          pending_group_id = if value.respond_to?(:consume_pending_version_group_id)
+                               value.consume_pending_version_group_id
+                             end
+
           TypedEAV::ValueVersion.create!(
             value_id: version_value_id,
             field_id: value.field_id,
@@ -142,7 +138,7 @@ module TypedEAV
             before_value: before_value,
             after_value: after_value,
             context: context.to_h, # frozen → unfrozen jsonb-serializable hash
-            version_group_id: value.pending_version_group_id || context[:version_group_id],
+            version_group_id: pending_group_id || context[:version_group_id],
             change_type: change_type.to_s,
             changed_at: Time.current,
           )