typed_eav 0.6.0 → 0.7.0

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

@@ -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/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/version.rb

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