typed_eav 0.2.1 → 0.3.0

data/app/models/typed_eav/field/validated_string.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module TypedEAV
+  module Field
+    # Intermediate STI base for string-valued field families that share a
+    # `min_length` / `max_length` / `pattern` validation surface.
+    #
+    # Leaves: `Field::Text`, `Field::Email`, `Field::Url`.
+    #
+    # Hoists the `string_value` storage declaration, the
+    # `store_accessor :options, :min_length, :max_length, :pattern` line,
+    # the `min_length` / `max_length` numericality validators, the
+    # `max_gte_min_length` guard, the `validate_pattern_syntax` guard, and
+    # the protected `validate_length` / `validate_pattern` helpers — all
+    # previously duplicated across Text/Email/Url with one drift gap
+    # (`max_gte_min_length` was only on Text).
+    #
+    # Default `validate_typed_value` runs `validate_length` plus
+    # `validate_pattern if pattern.present?`. Leaves override and call
+    # `super` to layer on their format-specific check (Email's
+    # `EMAIL_FORMAT`, Url's `URL_FORMAT`).
+    #
+    # Public extension point: external authors can subclass this directly
+    # to inherit the full min/max/pattern surface (see README §"Custom field
+    # types"). STI dispatch is unaffected — leaves still store their own
+    # class names in the `type` column.
+    class ValidatedString < Base
+      value_column :string_value
+
+      store_accessor :options, :min_length, :max_length, :pattern
+
+      validates :min_length, numericality: { only_integer: true, greater_than_or_equal_to: 0 }, allow_nil: true
+      validates :max_length, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
+      validate :max_gte_min_length
+      validate :validate_pattern_syntax
+
+      def validate_typed_value(record, val)
+        validate_length(record, val)
+        validate_pattern(record, val) if pattern.present?
+      end
+
+      protected
+
+      def validate_length(record, val)
+        opts = options_hash
+        str = val.to_s
+        if opts[:min_length] && str.length < opts[:min_length].to_i
+          record.errors.add(:value, :too_short, count: opts[:min_length])
+        end
+        return unless opts[:max_length] && str.length > opts[:max_length].to_i
+
+        record.errors.add(:value, :too_long, count: opts[:max_length])
+      end
+
+      def validate_pattern(record, val)
+        opts = options_hash
+        pattern = opts[:pattern]
+        return if pattern.blank?
+
+        matched = Timeout.timeout(1) { Regexp.new(pattern).match?(val.to_s) }
+        record.errors.add(:value, :invalid) unless matched
+      rescue RegexpError
+        record.errors.add(:value, "has an invalid pattern configured")
+      rescue Timeout::Error
+        record.errors.add(:value, "pattern validation timed out")
+      end
+
+      private
+
+      def max_gte_min_length
+        return unless min_length && max_length
+
+        errors.add(:max_length, "must be >= min_length") if max_length < min_length
+      end
+
+      def validate_pattern_syntax
+        return if pattern.blank?
+
+        Regexp.new(pattern)
+      rescue RegexpError => e
+        errors.add(:pattern, "is invalid: #{e.message}")
+      end
+    end
+  end
+end

data/app/models/typed_eav/value.rb

@@ -86,7 +86,7 @@ module TypedEAV
     def value
       return nil unless field
 
-      field.storage_contract.read(self)
+      field.read_value(self)
     end
 
     def value=(val)
@@ -114,7 +114,7 @@ module TypedEAV
         # decimal_value, raising TypeMismatch at save time.
         # Rails will further cast each column on save via its column type.
         casted, invalid = field.cast(val)
-        field.storage_contract.write(self, casted)
+        field.write_value(self, casted)
         @cast_was_invalid = invalid
       else
         # Field not yet assigned - stash for later
@@ -276,7 +276,7 @@ module TypedEAV
       #      Currency in Phase 05). Reconstructing that shape from
       #      before_value's per-column hash adds complexity for zero benefit
       #      since the per-column values are exactly what we need.
-      field.storage_contract.value_columns.each do |col|
+      field.class.value_columns.each do |col|
         self[col] = version.before_value[col.to_s]
       end
 
@@ -369,20 +369,20 @@ module TypedEAV
     end
 
     # Writes the field's configured default to the typed column(s) via the
-    # `field.apply_default_to(self)` dispatch. Does NOT route through value=
+    # `field.apply_default(self)` dispatch. Does NOT route through value=
     # because field.default_value is already cast via
     # cast(default_value_meta["v"]).first — re-casting would be redundant.
     # Field-side validate_default_value (field/base.rb) catches invalid raw
-    # defaults at field save time, so what apply_default_to writes is always
+    # defaults at field save time, so what apply_default writes is always
     # either a castable value or nil.
     #
     # Multi-cell forward-compat: single-cell types fall through to
-    # `self[value_column] = field.default_value` (Field::Base default).
-    # Currency / future multi-cell types override `apply_default_to` to
+    # `self[value_columns.first] = field.default_value` (TypedStorage default).
+    # Currency / future multi-cell types override `apply_default` to
     # populate multiple columns from a composite default. The dispatch
     # preserves the bypass-Value#value= contract end-to-end.
     def apply_field_default
-      field.storage_contract.apply_default(self)
+      field.apply_default(self)
     end
 
     def validate_value
@@ -540,7 +540,7 @@ module TypedEAV
       # code) cell would silently be missed by the dispatch gate, and
       # Phase 04 versioning would never see it (Scout §3 / Discrepancy D3
       # from plan 04-01).
-      return unless field.storage_contract.changed?(self)
+      return unless field.value_changed?(self)
 
       TypedEAV::EventDispatcher.dispatch_value_change(self, :update)
     end

data/lib/typed_eav/bulk_read.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Bulk-read query object. Returns `{ record_id => { field_name => value } }`
+  # for an Enumerable of host records — the class-method bulk variant of
+  # `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)
+  #
+  #   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)
+  #   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.
+  #
+  # ## Query bound
+  #
+  #   - 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
+  #
+  # Total: 2 + (unique partition tuples) queries — independent of record count.
+  #
+  # ## 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)`.
+  class BulkRead
+    def initialize(host_class:, records:)
+      @host_class = host_class
+      @records    = records
+    end
+
+    def to_hash
+      records = coerce_records
+      return {} if records.empty?
+
+      validate_record_classes!(records)
+
+      tuples_by_record = group_by_tuple(records)
+      winning_ids_by_tuple = winning_ids_by_tuple(tuples_by_record.values.uniq)
+      values_by_record_id = preload_values(records)
+
+      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+    end
+
+    private
+
+    attr_reader :host_class
+
+    def coerce_records
+      raise ArgumentError, "typed_eav_hash_for requires an Enumerable of records, got nil" if @records.nil?
+
+      @records.to_a
+    end
+
+    def validate_record_classes!(records)
+      return if records.all?(host_class)
+
+      classes = records.map { |r| r.class.name }.uniq
+      raise ArgumentError,
+            "typed_eav_hash_for expects records of class #{host_class.name} (or its subclasses); " \
+            "got mixed classes: #{classes.join(", ")}"
+    end
+
+    def group_by_tuple(records)
+      # Memo of record -> tuple key so each record only computes its tuple once.
+      records.index_with { |r| [r.typed_eav_scope, r.typed_eav_parent_scope] }
+    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)
+      end
+    end
+
+    def preload_values(records)
+      rows = TypedEAV::Value
+             .includes(:field)
+             .where(entity_type: host_class.name, entity_id: records.map(&:id))
+             .to_a
+      rows.group_by(&:entity_id)
+    end
+
+    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+      records.each_with_object({}) do |record, result|
+        tuple_key            = tuples_by_record[record]
+        winning_ids_by_name  = winning_ids_by_tuple.fetch(tuple_key, {})
+        rows                 = values_by_record_id.fetch(record.id, [])
+        result[record.id]    = inner_hash_for(rows, winning_ids_by_name)
+      end
+    end
+
+    # Builds the inner `{ field_name => value }` hash for a single record.
+    #
+    # Skips orphans (`tv.field` nil — definition deleted via raw SQL or a
+    # Phase 02 `:nullify` cascade). When a winning field_id is registered
+    # for the name, only its row may surface (scoped-beats-global collision
+    # precedence). When no winner is registered (definition deleted while
+    # values remain), fall back to first-wins so the hash isn't lossy.
+    def inner_hash_for(value_rows, winning_ids_by_name)
+      value_rows.each_with_object({}) do |tv, inner|
+        next unless tv.field
+
+        name = tv.field.name
+        winning_id = winning_ids_by_name[name]
+        next assign_with_precedence(inner, name, tv, winning_id) if winning_id
+
+        inner[name] = tv.value unless inner.key?(name)
+      end
+    end
+
+    def assign_with_precedence(inner, name, value_row, winning_id)
+      effective_id = value_row.field_id || value_row.field&.id
+      inner[name] = value_row.value if effective_id == winning_id
+    end
+  end
+end

data/lib/typed_eav/engine.rb

@@ -5,7 +5,7 @@ module TypedEAV
     isolate_namespace TypedEAV
 
     initializer "typed_eav.autoload" do
-      require_relative "column_mapping"
+      require_relative "field/typed_storage"
       require_relative "config"
       require_relative "registry"
       # Eager-loaded (not autoloaded) — Phase 04 versioning will register on

data/lib/typed_eav/entity_query.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Class-level query orchestration extended onto host AR models by the
+  # `has_typed_eav` macro. Owns the `UNSET_SCOPE` / `ALL_SCOPES` sentinels
+  # and the `resolve_scope` chain; delegates the heavy lifting to
+  # `FilterQuery` (multi-filter SQL composition) and `BulkRead` (bulk
+  # per-record reads). `bulk_set_typed_eav_values` stays as a 3-line wrapper
+  # around the existing `BulkWrite` executor.
+  module EntityQuery
+    # Sentinel for the `scope:` kwarg default. Distinguishes "kwarg not
+    # passed -> resolve from ambient" (UNSET_SCOPE) from "explicitly nil ->
+    # filter to global-only fields" (preserves prior behavior).
+    UNSET_SCOPE = Object.new.freeze
+
+    # Sentinel returned by `resolve_scope` inside an `unscoped { }` block.
+    # Signals the caller to skip the scope filter entirely (return fields
+    # across all partitions, not just global).
+    ALL_SCOPES = Object.new.freeze
+
+    # Query by custom field values. Accepts an array of filter hashes
+    # or a hash of hashes (from form params).
+    #
+    # Each filter needs:
+    #   :name or :n      - the field name
+    #   :op or :operator - the operator (default: :eq)
+    #   :value or :v     - the comparison value
+    #
+    #   Contact.where_typed_eav(
+    #     { name: "age", op: :gt, value: 21 },
+    #     { name: "city", value: "Portland" }   # op defaults to :eq
+    #   )
+    #
+    # `scope:` and `parent_scope:` behavior:
+    #   - omitted        -> resolve from ambient (`with_scope` -> resolver -> raise/nil)
+    #   - passed a value -> use verbatim (explicit override; admin/test path)
+    #   - passed nil     -> filter to global-only on that axis (prior behavior)
+    def where_typed_eav(*filters, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::FilterQuery.new(
+        model: self,
+        filters: filters,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).to_relation
+    end
+
+    # Shorthand for single-field queries.
+    #
+    #   Contact.with_field("age", :gt, 21)
+    #   Contact.with_field("active", true)      # op defaults to :eq
+    #   Contact.with_field("name", :contains, "smith")
+    #
+    # Accepts both `scope:` and `parent_scope:` kwargs with the same
+    # ambient/explicit/nil semantics as `where_typed_eav`. Single-scope
+    # callers (no `parent_scope:`) are unaffected.
+    def with_field(name, operator_or_value = nil, value = nil, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      filter = if value.nil? && !operator_or_value.is_a?(Symbol)
+                 # Two-arg form: with_field("name", "value") implies :eq
+                 { name: name, op: :eq, value: operator_or_value }
+               else
+                 { name: name, op: operator_or_value, value: value }
+               end
+      where_typed_eav(filter, scope: scope, parent_scope: parent_scope)
+    end
+
+    # Returns field definitions for this entity type.
+    #
+    # `scope:` and `parent_scope:` behavior:
+    #   - omitted        -> resolve from ambient (`with_scope` -> resolver -> raise/nil)
+    #   - passed a value -> use verbatim (explicit override; admin/test path)
+    #   - passed nil     -> filter to global-only on that axis (prior behavior preserved)
+    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)
+      else
+        s, ps = resolved
+        TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
+      end
+    end
+
+    # Bulk read API. Returns `{ record_id => { field_name => value } }` for
+    # an Enumerable of host records — the class-method bulk variant of
+    # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
+    # record count or field count. See `TypedEAV::BulkRead` for the pipeline
+    # and query bound.
+    def typed_eav_hash_for(records)
+      TypedEAV::BulkRead.new(host_class: self, records: records).to_hash
+    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)
+      TypedEAV::BulkWrite.execute(
+        host_class: self,
+        records: records,
+        values_by_field_name: values_by_field_name,
+        version_grouping: version_grouping,
+      )
+    end
+
+    private
+
+    # Translates a resolved scope into the `(scope, parent_scope)` pair
+    # passed to `FilterQuery`. Preserves the `ALL_SCOPES` sentinel through
+    # to `FilterQuery` (it routes to the multimap branch); for resolved
+    # tuples, returns the pair verbatim.
+    def scope_pair(resolved)
+      return [ALL_SCOPES, nil] if resolved.equal?(ALL_SCOPES)
+
+      resolved
+    end
+
+    # Resolves the scope and parent_scope kwargs into a concrete tuple for
+    # field-definition lookup. Returns one of:
+    #   - `ALL_SCOPES`            — inside `TypedEAV.unscoped { }`, atomic bypass.
+    #   - `[scope, parent_scope]` — both elements are String or nil.
+    # Raises:
+    #   - `TypedEAV::ScopeRequired` when the model declares `scope_method:`
+    #     but ambient scope can't be resolved and `require_scope` is true.
+    def resolve_scope(explicit_scope, explicit_parent_scope)
+      return ALL_SCOPES if TypedEAV.unscoped?
+
+      if explicit_given?(explicit_scope, explicit_parent_scope)
+        return resolve_explicit_scope(explicit_scope, explicit_parent_scope)
+      end
+
+      return [nil, nil] unless typed_eav_scope_method
+
+      resolve_ambient_scope
+    end
+
+    def explicit_given?(explicit_scope, explicit_parent_scope)
+      !explicit_scope.equal?(UNSET_SCOPE) || !explicit_parent_scope.equal?(UNSET_SCOPE)
+    end
+
+    # Per-slot normalize via `ScopeTuple.normalize_permissive` to coerce
+    # scalars/AR-records to strings, with UNSET_SCOPE collapsing to nil for
+    # the corresponding slot. Orphan-parent invariant: a request for
+    # parent_scope without scope is dead-letter — silently narrow ps to nil.
+    def resolve_explicit_scope(explicit_scope, explicit_parent_scope)
+      s = normalize_explicit_or_nil(explicit_scope, slot: :scope)
+      ps = normalize_explicit_or_nil(explicit_parent_scope, slot: :parent)
+      ps = nil unless TypedEAV::ScopeTuple.invariant_satisfied?(s, ps)
+      [s, ps]
+    end
+
+    def normalize_explicit_or_nil(value, slot:)
+      return nil if value.equal?(UNSET_SCOPE)
+
+      normalize_explicit_slot(value, slot: slot)
+    end
+
+    def normalize_explicit_slot(value, slot:)
+      tuple = slot == :scope ? [value, nil] : [nil, value]
+      index = slot == :scope ? :first : :last
+      TypedEAV::ScopeTuple.normalize_permissive(tuple)&.public_send(index)
+    end
+
+    # Ambient resolver path (via `with_scope` stack or configured lambda).
+    # `TypedEAV.current_scope` already validates the return shape to
+    # `nil | [a, b]` — no shape check is duplicated here.
+    def resolve_ambient_scope
+      resolved = TypedEAV.current_scope
+      return resolved if resolved
+
+      raise_scope_required if TypedEAV.config.require_scope
+
+      [nil, nil]
+    end
+
+    def raise_scope_required
+      raise TypedEAV::ScopeRequired,
+            "No ambient scope resolvable for #{name}. " \
+            "Wrap the call in `TypedEAV.with_scope(value) { ... }`, " \
+            "configure `TypedEAV.config.scope_resolver`, or use " \
+            "`TypedEAV.unscoped { ... }` to deliberately bypass."
+    end
+  end
+end

data/lib/typed_eav/field/typed_storage.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # One concern owns the entire native-typed-column storage seam.
+    #
+    # Field types declare WHICH typed column(s) hold their value via the
+    # class-level DSL (`value_column`, `value_columns`, `operators`,
+    # `operator_column`), and override three instance methods to compose
+    # multi-cell value shapes (`read_value`, `write_value`, `apply_default`).
+    # Snapshot/change-detection helpers (`value_changed?`, `before_snapshot`,
+    # `after_snapshot`) are concrete and derive from `value_columns`; they
+    # are NOT overridable — the snapshot shape is a versioning-coupled
+    # invariant.
+    #
+    # ## Class-level DSL
+    #
+    #   value_column :integer_value           # single-cell sugar; primary cell
+    #   value_columns :decimal_value, :string_value  # plural form
+    #   operators :eq, :gt, :is_null          # restrict supported operators
+    #   operator_column(:currency_eq)         # override to route ops to cells
+    #
+    # Both `value_column` and `value_columns` share the same `@value_columns`
+    # class instance variable. `value_column` returns the first element of
+    # `value_columns`, preserving the single-cell sugar shape.
+    #
+    # ## Override-point instance methods (the entire extension surface)
+    #
+    # - `read_value(record)` — compose the logical value from the cells.
+    # - `write_value(record, casted)` — unpack the casted value across cells.
+    # - `apply_default(record)` — populate cells from the field's default.
+    #
+    # The default implementations target `value_columns.first` (single-cell
+    # behavior). Multi-cell types override ALL THREE — overriding just one
+    # creates an asymmetry where reads see the multi-cell shape but writes
+    # / defaults populate only one column (or vice versa).
+    #
+    # ## Concrete (non-overridable) snapshot helpers
+    #
+    # - `value_changed?(record)` — true iff ANY value_columns column has a
+    #   saved_change_to_attribute? — used by the Value :update dispatch gate
+    #   so multi-cell types fire the event when only the second cell changed.
+    # - `before_snapshot(record, change_type)` — per-column hash keyed by
+    #   string column names. `:create` returns `{}`.
+    # - `after_snapshot(record, change_type)` — per-column hash keyed by
+    #   string column names. `:destroy` returns `{}`.
+    #
+    # Snapshot keys are stringified so query patterns like
+    # `WHERE before_value->>'integer_value' = '42'` work uniformly.
+    module TypedStorage
+      extend ActiveSupport::Concern
+
+      DEFAULT_OPERATORS_BY_COLUMN = {
+        boolean_value: %i[eq not_eq is_null is_not_null],
+        string_value: %i[eq not_eq contains not_contains starts_with ends_with is_null is_not_null],
+        text_value: %i[eq not_eq contains not_contains starts_with ends_with is_null is_not_null],
+        integer_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        decimal_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        date_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        datetime_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        json_value: %i[contains is_null is_not_null],
+      }.freeze
+      FALLBACK_OPERATORS = %i[eq not_eq is_null is_not_null].freeze
+
+      class_methods do
+        # Declare the typed column(s) this field type stores its value in.
+        #
+        # `value_column :col` — single-cell sugar; equivalent to
+        # `value_columns :col`. Returns `:col` when called without arguments.
+        # Raises NotImplementedError when called without arguments AND no
+        # column has been declared (the "subclass must declare" enforcement).
+        #
+        # Both `value_column` and `value_columns` write to the same
+        # `@value_columns` class instance variable on the declaring class
+        # (Ruby class ivars are NOT inherited, so each subclass that calls
+        # the setter installs its own). `Field::Percentage` re-declares
+        # `value_column :decimal_value` to work around this non-inheritance.
+        def value_column(column_name = nil)
+          if column_name
+            @value_columns = [column_name.to_sym]
+          else
+            cols = value_columns
+            cols.first
+          end
+        end
+
+        # Declare the typed columns this field type stores across (multi-cell
+        # form). Returns the configured Array when called without arguments.
+        # Raises NotImplementedError when no column(s) have been declared
+        # on this class — the same enforcement as `value_column`.
+        #
+        # The primary cell is `value_columns.first`; defaults for
+        # `read_value` / `write_value` / `apply_default` target it.
+        def value_columns(*cols)
+          if cols.any?
+            @value_columns = cols.map(&:to_sym)
+          else
+            @value_columns || raise(NotImplementedError,
+                                    "#{name} must declare `value_column :column_name`")
+          end
+        end
+
+        # The physical column this operator acts on. Defaults to
+        # `value_columns.first` for single-cell field types. Multi-cell
+        # types (Currency: `:currency_eq` → `:string_value`; everything
+        # else → `:decimal_value`) override this to route operators to
+        # different cells.
+        #
+        # Called by `QueryBuilder.filter` AFTER the
+        # `supported_operators.include?(operator)` validation gate, so
+        # `_operator` is always one the field explicitly supports.
+        def operator_column(_operator)
+          value_columns.first
+        end
+
+        # Operators this field type supports for querying. Defaults to the
+        # column-aware default set. Override via `.operators(*ops)`.
+        def supported_operators
+          @supported_operators || default_operators_for(value_columns.first)
+        end
+
+        def operators(*ops)
+          @supported_operators = ops.map(&:to_sym)
+        end
+
+        private
+
+        def default_operators_for(col)
+          DEFAULT_OPERATORS_BY_COLUMN.fetch(col, FALLBACK_OPERATORS)
+        end
+      end
+
+      # ── Override-point instance methods (the entire multi-cell surface) ──
+
+      # Returns the logical value for this field as stored on `value_record`.
+      # Default reads the primary cell. Override in multi-cell types to
+      # compose a hash (e.g., `Field::Currency` returns
+      # `{amount: r[:decimal_value], currency: r[:string_value]}`).
+      def read_value(value_record)
+        value_record[self.class.value_columns.first]
+      end
+
+      # Writes a casted value to `value_record`. Default writes the primary
+      # cell. Override in multi-cell types to unpack the casted value
+      # across multiple cells.
+      def write_value(value_record, casted)
+        value_record[self.class.value_columns.first] = casted
+      end
+
+      # Writes this field's configured default to `value_record`. Default
+      # writes `default_value` to the primary cell, bypassing Value#value=
+      # to avoid re-casting an already-cast default. Override in multi-cell
+      # types to populate multiple cells from a composite default.
+      def apply_default(value_record)
+        value_record[self.class.value_columns.first] = default_value
+      end
+
+      # ── Concrete snapshot helpers (NOT overridable) ──
+
+      # True iff ANY of the field's value_columns had a saved change in the
+      # just-committed save. Used by Value's :update dispatch gate so
+      # multi-cell types correctly fire the event when only the second cell
+      # changed (regression case Phase 5 D3).
+      def value_changed?(value_record)
+        self.class.value_columns.any? do |column|
+          value_record.saved_change_to_attribute?(column)
+        end
+      end
+
+      # Pre-change snapshot keyed by string column names.
+      # - :create  → {} (no before state)
+      # - :update  → {col => attribute_before_last_save(col)}
+      # - :destroy → {col => value_record[col]} (in-memory on the destroyed
+      #   AR record per Phase 03 P04 live-validation)
+      def before_snapshot(value_record, change_type)
+        case change_type.to_sym
+        when :create
+          {}
+        when :update
+          self.class.value_columns.to_h do |column|
+            [column.to_s, value_record.attribute_before_last_save(column.to_s)]
+          end
+        when :destroy
+          self.class.value_columns.to_h { |column| [column.to_s, value_record[column]] }
+        else
+          raise ArgumentError, "Unsupported change_type: #{change_type.inspect}"
+        end
+      end
+
+      # Post-change snapshot keyed by string column names.
+      # - :create / :update → {col => value_record[col]}
+      # - :destroy          → {} (no after state)
+      def after_snapshot(value_record, change_type)
+        case change_type.to_sym
+        when :create, :update
+          self.class.value_columns.to_h { |column| [column.to_s, value_record[column]] }
+        when :destroy
+          {}
+        else
+          raise ArgumentError, "Unsupported change_type: #{change_type.inspect}"
+        end
+      end
+    end
+  end
+end