typed_eav 0.6.0 → 0.7.0

data/db/migrate/20260816000000_use_partial_covering_scalar_indexes.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+class UsePartialCoveringScalarIndexes < ActiveRecord::Migration[7.1]
+  # Concurrent create-before-drop keeps the replacement indexes available
+  # throughout the upgrade and leaves rollback able to recreate legacy DDL.
+  disable_ddl_transaction!
+
+  TABLE = :typed_eav_values
+
+  INDEXES = [
+    {
+      column: :integer_value,
+      replacement: "idx_te_values_field_int_present",
+      legacy: "idx_te_values_field_int",
+      value_opclass: "int8_ops",
+    },
+    {
+      column: :decimal_value,
+      replacement: "idx_te_values_field_dec_present",
+      legacy: "idx_te_values_field_dec",
+      value_opclass: "numeric_ops",
+    },
+    {
+      column: :date_value,
+      replacement: "idx_te_values_field_date_present",
+      legacy: "idx_te_values_field_date",
+      value_opclass: "date_ops",
+    },
+    {
+      column: :datetime_value,
+      replacement: "idx_te_values_field_dt_present",
+      legacy: "idx_te_values_field_dt",
+      value_opclass: "timestamp_ops",
+    },
+    {
+      column: :boolean_value,
+      replacement: "idx_te_values_field_bool_present",
+      legacy: "idx_te_values_field_bool",
+      value_opclass: "bool_ops",
+    },
+    {
+      column: :string_value,
+      replacement: "idx_te_values_field_str_present",
+      legacy: "idx_te_values_field_str",
+      value_opclass: "text_pattern_ops",
+    },
+  ].freeze
+
+  def up
+    INDEXES.each { |definition| ensure_index!(replacement_definition(definition)) }
+    assert_all_valid!(INDEXES.map { |definition| replacement_definition(definition) })
+    INDEXES.each { |definition| remove_expected_index!(legacy_definition(definition)) }
+  end
+
+  def down
+    INDEXES.each { |definition| ensure_index!(legacy_definition(definition)) }
+    assert_all_valid!(INDEXES.map { |definition| legacy_definition(definition) })
+    INDEXES.each { |definition| remove_expected_index!(replacement_definition(definition)) }
+  end
+
+  private
+
+  def replacement_definition(definition)
+    definition.merge(
+      name: definition.fetch(:replacement),
+      include: ["entity_id"],
+      predicate: "#{definition.fetch(:column)} IS NOT NULL",
+    )
+  end
+
+  def legacy_definition(definition)
+    definition.merge(
+      name: definition.fetch(:legacy),
+      include: %w[entity_id entity_type],
+      predicate: nil,
+    )
+  end
+
+  def ensure_index!(expected)
+    actual = catalog_index(expected.fetch(:name))
+    return create_and_validate!(expected) unless actual
+    return if exact_definition?(actual, expected) && usable?(actual)
+
+    unless exact_definition?(actual, expected)
+      raise ActiveRecord::MigrationError,
+            "index #{expected.fetch(:name)} exists with unexpected definition: #{actual.inspect}"
+    end
+
+    say "repairing invalid interrupted index #{expected.fetch(:name)}"
+    remove_index TABLE, name: expected.fetch(:name), algorithm: :concurrently
+    create_and_validate!(expected)
+  end
+
+  def create_and_validate!(expected)
+    options = {
+      name: expected.fetch(:name),
+      include: expected.fetch(:include),
+      algorithm: :concurrently,
+    }
+    options[:where] = expected.fetch(:predicate) if expected.fetch(:predicate)
+    if expected.fetch(:value_opclass) == "text_pattern_ops"
+      options[:opclass] = { expected.fetch(:column) => :text_pattern_ops }
+    end
+
+    add_index TABLE, [:field_id, expected.fetch(:column)], **options
+    actual = catalog_index(expected.fetch(:name))
+    return if actual && exact_definition?(actual, expected) && usable?(actual)
+
+    raise ActiveRecord::MigrationError,
+          "concurrent index #{expected.fetch(:name)} was not created with its exact valid definition"
+  end
+
+  def assert_all_valid!(expected_indexes)
+    invalid = expected_indexes.filter_map do |expected|
+      actual = catalog_index(expected.fetch(:name))
+      expected.fetch(:name) unless actual && exact_definition?(actual, expected) && usable?(actual)
+    end
+    return if invalid.empty?
+
+    raise ActiveRecord::MigrationError,
+          "refusing to remove existing indexes before all replacements are valid: #{invalid.join(", ")}"
+  end
+
+  def remove_expected_index!(expected)
+    actual = catalog_index(expected.fetch(:name))
+    return unless actual
+
+    unless exact_definition?(actual, expected)
+      raise ActiveRecord::MigrationError,
+            "index #{expected.fetch(:name)} exists with unexpected definition: #{actual.inspect}"
+    end
+
+    remove_index TABLE, name: expected.fetch(:name), algorithm: :concurrently
+  end
+
+  def usable?(actual)
+    actual.fetch("valid") && actual.fetch("ready")
+  end
+
+  def exact_definition?(actual, expected)
+    actual.fetch("method") == "btree" &&
+      !actual.fetch("unique") &&
+      actual.fetch("columns") == ["field_id", expected.fetch(:column).to_s, *expected.fetch(:include)] &&
+      actual.fetch("key_count") == 2 &&
+      actual.fetch("opclasses") == ["int8_ops", expected.fetch(:value_opclass)] &&
+      normalized_predicate(actual.fetch("predicate")) == normalized_predicate(expected.fetch(:predicate))
+  end
+
+  def normalized_predicate(predicate)
+    predicate&.gsub(/[()\s"]/, "")&.downcase
+  end
+
+  def catalog_index(name)
+    quoted_name = connection.quote(name)
+    row = connection.select_one(<<~SQL.squish)
+      SELECT
+        index_state.indisvalid AS valid,
+        index_state.indisready AS ready,
+        index_state.indisunique AS unique,
+        access_method.amname AS method,
+        index_state.indnkeyatts AS key_count,
+        pg_get_expr(index_state.indpred, index_state.indrelid) AS predicate,
+        array_to_string(ARRAY(
+          SELECT attribute.attname
+          FROM unnest(index_state.indkey) WITH ORDINALITY AS index_column(attnum, position)
+          JOIN pg_attribute attribute
+            ON attribute.attrelid = index_state.indrelid
+           AND attribute.attnum = index_column.attnum
+          ORDER BY index_column.position
+        ), ',') AS columns,
+        array_to_string(ARRAY(
+          SELECT operator_class.opcname
+          FROM unnest(index_state.indclass) WITH ORDINALITY AS index_opclass(opcoid, position)
+          JOIN pg_opclass operator_class ON operator_class.oid = index_opclass.opcoid
+          WHERE index_opclass.position <= index_state.indnkeyatts
+          ORDER BY index_opclass.position
+        ), ',') AS opclasses
+      FROM pg_class index_relation
+      JOIN pg_index index_state ON index_state.indexrelid = index_relation.oid
+      JOIN pg_class table_relation ON table_relation.oid = index_state.indrelid
+      JOIN pg_namespace namespace ON namespace.oid = table_relation.relnamespace
+      JOIN pg_am access_method ON access_method.oid = index_relation.relam
+      WHERE namespace.nspname = ANY (current_schemas(false))
+        AND table_relation.relname = 'typed_eav_values'
+        AND index_relation.relname = #{quoted_name}
+    SQL
+    return unless row
+
+    row.merge(
+      "valid" => ActiveModel::Type::Boolean.new.cast(row.fetch("valid")),
+      "ready" => ActiveModel::Type::Boolean.new.cast(row.fetch("ready")),
+      "unique" => ActiveModel::Type::Boolean.new.cast(row.fetch("unique")),
+      "key_count" => row.fetch("key_count").to_i,
+      "columns" => row.fetch("columns").split(","),
+      "opclasses" => row.fetch("opclasses").split(","),
+    )
+  end
+end

data/lib/typed_eav/bulk_read.rb

@@ -6,13 +6,12 @@ module TypedEAV
   # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
   # record count or field count.
   #
-  # ## Pipeline (one query per unique partition tuple + one bulk value preload)
+  # ## Pipeline (one batched definition query + one bulk value preload)
   #
   #   1. validate_records!    — nil -> ArgumentError; single-class invariant
   #   2. group_by_tuple       — `[typed_eav_scope, typed_eav_parent_scope]`
-  #   3. winning_ids_by_tuple — `typed_eav_definitions` per unique tuple via
-  #                             `Partition.definitions_by_name` (shared
-  #                             collision-precedence helper)
+  #   3. winning_ids_by_tuple — one exact-partition definition query, then
+  #                             `Partition.definitions_by_name` 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.
@@ -21,9 +20,9 @@ module TypedEAV
   #
   #   - 1 SELECT typed_eav_values WHERE entity_type=? AND entity_id IN (?)
   #   - 1 SELECT typed_eav_fields WHERE id IN (?)           (via includes)
-  #   - 1 SELECT typed_eav_fields per unique partition tuple
+  #   - 1 SELECT typed_eav_fields for the union of requested partitions
   #
-  # Total: 2 + (unique partition tuples) queries — independent of record count.
+  # Total: 3 queries — independent of record count and partition cardinality.
   #
   # ## Single-class invariant
   #
@@ -74,10 +73,43 @@ module TypedEAV
     end
 
     def winning_ids_by_tuple(tuples)
-      tuples.each_with_object({}) do |(s, ps), memo|
-        defs = host_class.typed_eav_definitions(scope: s, parent_scope: ps)
-        memo[[s, ps]] = TypedEAV::Partition.definitions_by_name(defs).transform_values(&:id)
+      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"
     end
 
     def preload_values(records)

data/lib/typed_eav/bulk_upsert.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Reduced-semantics, SQL-oriented bulk value writer.
+  #
+  # This API runs casting/domain/entity/partition validation and validation
+  # callbacks, but does not run host callbacks/validations or host saves, Value
+  # 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.
+  module BulkUpsert
+    TYPE_COLUMNS = %i[
+      string_value text_value boolean_value integer_value decimal_value date_value datetime_value json_value
+    ].freeze
+
+    class << self
+      # rubocop:disable Metrics/ParameterLists -- transaction controls are explicit API contract.
+      def execute(
+        host_class:, records:, values_by_field_name:, acknowledge_reduced_semantics:, transaction: :all, chunk_size: nil
+      )
+        validate_options!(records, values_by_field_name, acknowledge_reduced_semantics, transaction, chunk_size)
+        records = records.to_a
+        return 0 if records.empty?
+
+        validate_record_classes!(host_class, records)
+        reject_duplicate_or_unpersisted!(records)
+        ensure_connection_owner!(host_class)
+        values_by_field_name = normalize_values!(values_by_field_name)
+        units = transaction == :all ? [records] : records.each_slice(chunk_size)
+        units.sum { |unit| write_unit(host_class, unit, values_by_field_name) }
+      end
+
+      private
+
+      # 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
+        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|
+            field = fields[name.to_s]
+            raise ArgumentError, "bulk_upsert field is not visible for #{record.class.name}: #{name}" unless field
+
+            build_row(host_class, record, field, raw)
+          end
+        end
+        return 0 if rows.empty?
+
+        host_class.transaction do
+          # rubocop:disable Rails/SkipsModelValidations -- every row is prevalidated in :bulk_upsert context.
+          TypedEAV::Value.upsert_all(
+            rows,
+            unique_by: :idx_te_values_entity_field,
+            update_only: (TYPE_COLUMNS + [:updated_at]),
+            record_timestamps: false,
+          )
+          # rubocop:enable Rails/SkipsModelValidations
+        end
+        rows.length
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def build_row(host_class, record, field, raw)
+        value = TypedEAV::Value.new(entity: record, field: field)
+        value.value = raw
+        value.valid?(:bulk_upsert)
+        errors = value.errors.to_hash
+        raise ArgumentError, "bulk_upsert validation failed for #{field.name}: #{errors.inspect}" if errors.any?
+
+        now = Time.current
+        row = {
+          entity_type: host_class.polymorphic_name,
+          entity_id: record.id,
+          field_id: field.id,
+          created_at: now,
+          updated_at: now,
+        }
+        TYPE_COLUMNS.each { |column| row[column] = value[column] }
+        row
+      end
+
+      def validate_options!(records, values, acknowledged, transaction, chunk_size)
+        raise ArgumentError, "bulk_upsert requires an Enumerable of records" if records.nil?
+        raise ArgumentError, "bulk_upsert requires a Hash of values_by_field_name" unless values.is_a?(Hash)
+        raise ArgumentError, "bulk_upsert requires acknowledge_reduced_semantics: true" unless acknowledged == true
+        return if transaction == :all
+        return if transaction == :chunks && chunk_size.is_a?(Integer) && chunk_size.positive?
+
+        raise ArgumentError, "transaction must be :all or :chunks with a positive chunk_size"
+      end
+
+      def normalize_values!(values)
+        normalized = {}
+        values.each do |name, raw|
+          key = name.to_s
+          if normalized.key?(key)
+            raise ArgumentError, "bulk_upsert field keys collide after string normalization: #{key}"
+          end
+
+          normalized[key] = raw
+        end
+        normalized
+      end
+
+      def validate_record_classes!(host_class, records)
+        return if records.all?(host_class)
+
+        raise ArgumentError, "bulk_upsert expects records of class #{host_class.name}"
+      end
+
+      def reject_duplicate_or_unpersisted!(records)
+        raise ArgumentError, "bulk_upsert requires persisted records" if records.any? { |record| !record.persisted? }
+        return if records.map(&:id).uniq.length == records.length
+
+        raise ArgumentError, "bulk_upsert does not accept duplicate entity records"
+      end
+
+      def ensure_connection_owner!(host_class)
+        pools = [host_class.connection_pool, TypedEAV::Value.connection_pool, TypedEAV::Field::Base.connection_pool]
+        return if pools.map(&:object_id).uniq.one?
+
+        raise ArgumentError, "bulk_upsert requires host, value, and field connections to share a pool"
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+end

data/lib/typed_eav/bulk_write.rb

@@ -16,7 +16,8 @@ module TypedEAV
   # allocate field UUIDs, and then hand off to `execute_pairs(pairs,
   # effective_grouping, field_uuids)` — a single shared loop that takes
   # ordered `[record, vbn]` pairs and runs the outer-transaction-plus-
-  # savepoint-per-record envelope.
+  # savepoint-per-record envelope; `transaction: :chunks` repeats that
+  # envelope per chunk so completed chunks can commit independently.
   #
   # Pair-shaped (not Hash-shaped) so `execute`'s `[record, vbn]` list can
   # carry duplicate in-memory instances of the same persisted row without
@@ -24,19 +25,25 @@ module TypedEAV
   # `execute`'s byte-for-byte behavior contract.
   module BulkWrite
     class << self
-      def execute(host_class:, records:, values_by_field_name:, version_grouping: :default)
-        validate_inputs!(records, values_by_field_name, version_grouping)
+      # rubocop:disable Metrics/ParameterLists -- transaction controls are explicit API contract.
+      def execute(
+        host_class:, records:, values_by_field_name:, version_grouping: :default, transaction: :all, chunk_size: nil
+      )
+        validate_inputs!(records, values_by_field_name, version_grouping, transaction, chunk_size)
 
         records = records.to_a
         return { successes: [], errors_by_record: {} } if records.empty?
 
         validate_record_classes!(host_class, records)
+        ensure_connection_owner!(host_class)
 
         effective_grouping = resolve_grouping(version_grouping)
         vbn = values_by_field_name.transform_keys(&:to_s)
         field_uuids = effective_grouping == :per_field ? vbn.keys.index_with { SecureRandom.uuid } : nil
 
-        execute_pairs(records.map { |r| [r, vbn] }, effective_grouping, field_uuids)
+        execute_pairs(
+          host_class, records.map { |r| [r, vbn] }, effective_grouping, field_uuids, transaction, chunk_size
+        )
       end
 
       # Per-record-varying sibling to `execute`. Accepts a `Hash<host_record,
@@ -45,12 +52,15 @@ module TypedEAV
       #
       # Empty `values_by_record` short-circuits to the empty result without
       # opening a transaction (matches `execute`'s empty-records contract).
-      def execute_per_record(host_class:, values_by_record:, version_grouping: :default)
-        validate_per_record_inputs!(values_by_record, version_grouping)
+      def execute_per_record(
+        host_class:, values_by_record:, version_grouping: :default, transaction: :all, chunk_size: nil
+      )
+        validate_per_record_inputs!(values_by_record, version_grouping, transaction, chunk_size)
 
         return { successes: [], errors_by_record: {} } if values_by_record.empty?
 
         validate_record_classes!(host_class, values_by_record.keys, method: :bulk_set_typed_eav_values_per_record)
+        ensure_connection_owner!(host_class)
 
         effective_grouping = resolve_grouping(version_grouping)
         pairs = values_by_record.map { |record, vbn| [record, vbn.transform_keys(&:to_s)] }
@@ -58,15 +68,11 @@ module TypedEAV
                         pairs.flat_map { |(_record, vbn)| vbn.keys }.uniq.index_with { SecureRandom.uuid }
                       end
 
-        execute_pairs(pairs, effective_grouping, field_uuids)
+        execute_pairs(host_class, pairs, effective_grouping, field_uuids, transaction, chunk_size)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def apply_record_save(record:, vbn:, effective_grouping:, uuids:, accumulator:)
-        push_uuid = case effective_grouping
-                    when :per_record then uuids[:record]
-                    when :per_field  then uuids[:field].values.first
-                    end
-
         do_save = lambda do
           record.typed_eav_attributes = vbn.map { |name, value| typed_eav_entry_for(name, value) }
           stamp_pending_version_group_ids(record, effective_grouping, uuids)
@@ -79,11 +85,7 @@ module TypedEAV
           end
         end
 
-        if push_uuid
-          TypedEAV.with_context(version_group_id: push_uuid, &do_save)
-        else
-          do_save.call
-        end
+        do_save.call
       end
 
       private
@@ -97,26 +99,31 @@ module TypedEAV
       # the same persisted row iterate each instance separately — matters
       # for `execute`'s byte-for-byte behavior contract on
       # `[Entity.find(1), Entity.find(1)]`-shaped input.
-      def execute_pairs(pairs, effective_grouping, field_uuids)
+      # rubocop:disable Metrics/MethodLength -- transaction wrapper retains one readable semantic loop.
+      # rubocop:disable Metrics/ParameterLists -- internal transaction controls stay explicit.
+      def execute_pairs(host_class, pairs, effective_grouping, field_uuids, transaction, chunk_size)
         successes = []
         errors_by_record = {}
 
         with_bulk_definitions_memo do
-          ActiveRecord::Base.cache do
-            ActiveRecord::Base.transaction do
-              pairs.each do |(record, vbn)|
-                record_uuid = effective_grouping == :per_record ? SecureRandom.uuid : nil
-                record_field_uuids = record_scoped_field_uuids(field_uuids, vbn)
-
-                with_record_scope(record) do
-                  ActiveRecord::Base.transaction(requires_new: true) do
-                    apply_record_save(
-                      record: record,
-                      vbn: vbn,
-                      effective_grouping: effective_grouping,
-                      uuids: { record: record_uuid, field: record_field_uuids },
-                      accumulator: { successes: successes, errors_by_record: errors_by_record },
-                    )
+          host_class.cache do
+            units = transaction == :all ? [pairs] : pairs.each_slice(chunk_size)
+            units.each do |unit|
+              host_class.transaction do
+                unit.each do |(record, vbn)|
+                  record_uuid = effective_grouping == :per_record ? SecureRandom.uuid : nil
+                  record_field_uuids = record_scoped_field_uuids(field_uuids, vbn)
+
+                  with_record_scope(record) do
+                    host_class.transaction(requires_new: true) do
+                      apply_record_save(
+                        record: record,
+                        vbn: vbn,
+                        effective_grouping: effective_grouping,
+                        uuids: { record: record_uuid, field: record_field_uuids },
+                        accumulator: { successes: successes, errors_by_record: errors_by_record },
+                      )
+                    end
                   end
                 end
               end
@@ -126,6 +133,8 @@ module TypedEAV
 
         { successes: successes, errors_by_record: errors_by_record }
       end
+      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/MethodLength
 
       # For `:per_field`, the global `field_uuids` map covers the union of
       # field names across all records' value hashes. The per-record save
@@ -184,7 +193,7 @@ module TypedEAV
         ActiveRecord::Type::Boolean.new.cast(flag)
       end
 
-      def validate_inputs!(records, values_by_field_name, version_grouping)
+      def validate_inputs!(records, values_by_field_name, version_grouping, transaction, chunk_size)
         if records.nil?
           raise ArgumentError,
                 "bulk_set_typed_eav_values requires an Enumerable of records, got nil"
@@ -197,9 +206,17 @@ module TypedEAV
         end
 
         validate_grouping!(version_grouping)
+        validate_transaction!(transaction, chunk_size)
       end
 
-      def validate_per_record_inputs!(values_by_record, version_grouping)
+      def ensure_connection_owner!(host_class)
+        pools = [host_class.connection_pool, TypedEAV::Value.connection_pool, TypedEAV::Field::Base.connection_pool]
+        return if pools.map(&:object_id).uniq.one?
+
+        raise ArgumentError, "bulk_write requires host, value, and field connections to share a pool"
+      end
+
+      def validate_per_record_inputs!(values_by_record, version_grouping, transaction, chunk_size)
         unless values_by_record.is_a?(Hash)
           raise ArgumentError,
                 "bulk_set_typed_eav_values_per_record requires a Hash of values_by_record, " \
@@ -215,6 +232,14 @@ module TypedEAV
         end
 
         validate_grouping!(version_grouping)
+        validate_transaction!(transaction, chunk_size)
+      end
+
+      def validate_transaction!(transaction, chunk_size)
+        return if transaction == :all
+        return if transaction == :chunks && chunk_size.is_a?(Integer) && chunk_size.positive?
+
+        raise ArgumentError, "transaction must be :all or :chunks with a positive chunk_size"
       end
 
       def validate_grouping!(version_grouping)
@@ -225,11 +250,12 @@ module TypedEAV
                 "Supported values: #{valid_grouping.map(&:inspect).join(", ")}."
         end
 
-        return unless %i[per_record per_field].include?(version_grouping) && !TypedEAV.config.versioning
+        return unless %i[per_record per_field].include?(version_grouping) &&
+                      !TypedEAV::Versioning.atomic_callbacks_installed?
 
         raise ArgumentError,
-              "version_grouping: #{version_grouping.inspect} was passed but versioning is disabled. " \
-              "Set TypedEAV.config.versioning = true in your initializer, or pass " \
+              "version_grouping: #{version_grouping.inspect} was passed but versioning is disabled or not installed. " \
+              "Enable versioning at boot, or pass " \
               "version_grouping: :none to opt out explicitly, or omit the kwarg to silently no-op."
       end
 
@@ -244,7 +270,7 @@ module TypedEAV
 
       def resolve_grouping(version_grouping)
         if version_grouping == :default
-          TypedEAV.config.versioning ? :per_record : :none
+          TypedEAV::Versioning.atomic_callbacks_installed? ? :per_record : :none
         else
           version_grouping
         end