typed_eav 0.2.1 → 0.3.1

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

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
-require "timeout"
-
 module TypedEAV
   module Field
-    # rubocop:disable Metrics/ClassLength -- Field::Base is the central STI parent: associations,
-    # validations, cascade dispatch, partition-aware ordering helpers, default-value handling,
-    # and the partition-aware backfill all live here together because they share the (entity_type,
-    # scope, parent_scope) partition contract. Splitting into concerns would scatter that contract
-    # and obscure the cross-cutting invariants the validators and helpers enforce together.
+    # Field::Base is the central STI parent: associations, validations,
+    # cascade dispatch, partition-aware ordering helpers, default-value
+    # handling, and the partition-aware backfill all live here together
+    # because they share the (entity_type, scope, parent_scope) partition
+    # contract. Validation helpers that were previously co-located (length /
+    # pattern / range / option-inclusion) have moved down to the new family
+    # bases (`Field::ValidatedString`, `Field::RangeBounded`,
+    # `Field::Optionable`) per ADR-0004; `validate_array_size` stays here
+    # because its callers span unrelated families.
     class Base < ApplicationRecord
       self.table_name = "typed_eav_fields"
 
-      include TypedEAV::ColumnMapping
+      include TypedEAV::Field::TypedStorage
 
       # ── Associations ──
 
@@ -244,84 +246,18 @@ module TypedEAV
         [raw, false]
       end
 
-      # ── Phase 05 multi-cell extension points ──
-      #
-      # These three instance methods are the field-side surface that resolves
-      # Value#value semantics, the write path, and the default-application
-      # path. Single-cell field types (every built-in as of Phase 04) inherit
-      # the defaults below and behave identically to the pre-Phase-05 direct-
-      # column-access shape.
-      #
-      # Multi-cell field types (Phase 05: Currency stores `{amount, currency}`
-      # across decimal_value + string_value) override these to compose /
-      # unpack the logical value across multiple physical columns. The
-      # dispatch keeps Value#value, Value#value=, and Value#apply_field_default
-      # oblivious to multi-cell — they always go through the field, so adding
-      # new multi-cell types in the future requires no Value-side changes.
-      #
-      # IMPORTANT: read_value, write_value, and apply_default_to are paired.
-      # Currency overrides ALL THREE — overriding only one creates an
-      # asymmetry where reads see the multi-cell shape but writes / defaults
-      # populate only one column (or vice versa).
-
-      # Returns the logical value for this field as stored on the given
-      # Value record. Default reads `value_record[self.class.value_column]`.
-      # Override in multi-cell field types to compose a hash from multiple
-      # columns (e.g., Field::Currency returns
-      # `{amount: r[:decimal_value], currency: r[:string_value]}`).
-      #
-      # Called from Value#value. The Value#value `return nil unless field`
-      # guard runs before this method, so `self` is always set.
-      def read_value(value_record)
-        value_record[self.class.value_column]
-      end
-
-      # Writes a casted value to the given Value record. Default writes
-      # `value_record[self.class.value_column] = casted`. Override in multi-
-      # cell types to unpack a composite casted value into multiple columns
-      # (e.g., Field::Currency unpacks `{amount: BigDecimal, currency: String}`
-      # into decimal_value + string_value).
-      #
-      # Called from Value#value=. The cast invariant is preserved: `casted`
-      # is whatever the field's `cast(raw)` returned as the first element.
-      # For single-cell types that's a scalar; for Currency it's a Hash.
-      # Without this dispatch, a Currency cast result (a Hash) would be
-      # written to a single typed column, raising TypeMismatch at save time.
-      def write_value(value_record, casted)
-        value_record[self.class.value_column] = casted
-      end
-
-      # Writes this field's configured default to the given Value record.
-      # Default writes `value_record[self.class.value_column] = default_value`,
-      # bypassing Value#value= to avoid re-casting an already-cast default
-      # (default_value is cast at field save time via validate_default_value).
-      # Override in multi-cell types to populate multiple columns from a
-      # composite default (e.g., Field::Currency unpacks `default_value`'s
-      # `{amount: ..., currency: ...}` hash into decimal_value + string_value).
-      #
-      # Called from Value#apply_field_default in two contexts:
-      #   1. Initial value assignment when no `value:` kwarg was passed
-      #      (UNSET_VALUE sentinel resolution path).
-      #   2. Pending-value resolution (apply_pending_value branch where
-      #      @pending_value was UNSET_VALUE and the field arrived later).
-      def apply_default_to(value_record)
-        value_record[self.class.value_column] = default_value
-      end
+      # ── Multi-cell extension points ──
+      #
+      # The three override-point instance methods (`read_value`,
+      # `write_value`, `apply_default`) and the concrete snapshot helpers
+      # (`value_changed?`, `before_snapshot`, `after_snapshot`) live in the
+      # `Field::TypedStorage` concern included above. Field types that span
+      # more than one typed column override all three to compose / unpack the
+      # logical value across multiple cells; `Field::Currency` is the
+      # canonical example.
 
       # ── Introspection ──
 
-      def self.storage_contract_class(contract_class = nil)
-        if contract_class
-          @storage_contract_class = contract_class
-        else
-          @storage_contract_class || TypedEAV::FieldStorageContract
-        end
-      end
-
-      def storage_contract
-        @storage_contract ||= self.class.storage_contract_class.new(self)
-      end
-
       def field_type_name
         self.class.name.demodulize.underscore
       end
@@ -442,8 +378,14 @@ module TypedEAV
       #
       # Default no-op. Subclasses override to enforce their constraints
       # (length, range, pattern, option inclusion, array size, etc.) and
-      # add errors to `record.errors`. Shared helpers below (validate_length,
-      # validate_pattern, validate_range, etc.) are available to subclasses.
+      # add errors to `record.errors`. Family-specific helpers live on the
+      # appropriate family base / concern (`ValidatedString` provides
+      # `validate_length` / `validate_pattern`; `RangeBounded` provides
+      # `validate_range` / `validate_date_range` / `validate_datetime_range`;
+      # `Optionable` provides `validate_option_inclusion` /
+      # `validate_multi_option_inclusion`). `validate_array_size` stays
+      # here because its callers (MultiSelect via Optionable AND
+      # IntegerArray directly) don't share a family.
       def validate_typed_value(record, val)
         # no-op by default
       end
@@ -454,77 +396,6 @@ module TypedEAV
         options&.with_indifferent_access || {}
       end
 
-      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
-
-      def validate_range(record, val)
-        opts = options_hash
-        record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min]) if opts[:min] && val < opts[:min].to_d
-        return unless opts[:max] && val > opts[:max].to_d
-
-        record.errors.add(:value, :less_than_or_equal_to, count: opts[:max])
-      end
-
-      def validate_date_range(record, val)
-        opts = options_hash
-        if opts[:min_date]
-          min = ::Date.parse(opts[:min_date])
-          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_date]) if val < min
-        end
-        if opts[:max_date]
-          max = ::Date.parse(opts[:max_date])
-          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_date]) if val > max
-        end
-      rescue ::Date::Error
-        record.errors.add(:base, "field has invalid date configuration")
-      end
-
-      def validate_datetime_range(record, val)
-        opts = options_hash
-        if opts[:min_datetime]
-          min = ::Time.zone.parse(opts[:min_datetime])
-          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_datetime]) if val < min
-        end
-        if opts[:max_datetime]
-          max = ::Time.zone.parse(opts[:max_datetime])
-          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_datetime]) if val > max
-        end
-      rescue ArgumentError
-        record.errors.add(:base, "field has invalid datetime configuration")
-      end
-
-      def validate_option_inclusion(record, val)
-        return if allowed_option_values.include?(val&.to_s)
-
-        record.errors.add(:value, :inclusion)
-      end
-
-      def validate_multi_option_inclusion(record, val)
-        invalid = Array(val).map(&:to_s) - allowed_option_values
-        record.errors.add(:value, :inclusion) if invalid.any?
-      end
-
       def validate_array_size(record, val)
         opts = options_hash
         arr = Array(val)
@@ -579,8 +450,7 @@ module TypedEAV
       # the same incoherent state as a literal NULL. Same reasoning for
       # `scope.present?`.
       def validate_parent_scope_invariant
-        return if parent_scope.blank?
-        return if scope.present?
+        return if TypedEAV::ScopeTuple.invariant_satisfied?(scope, parent_scope)
 
         errors.add(:parent_scope, "cannot be set when scope is blank")
       end
@@ -775,6 +645,5 @@ module TypedEAV
         TypedEAV::EventDispatcher.dispatch_field_change(self, change_type)
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

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

@@ -5,21 +5,21 @@ module TypedEAV
     # Two-cell field type: stores `{amount: BigDecimal, currency: String}`
     # across decimal_value (amount) + string_value (currency ISO 4217 code).
     #
-    # Phase 05 contract:
-    # - value_columns: [:decimal_value, :string_value] — propagates through
-    #   versioning's snapshot loop (Phase 04) and the Value
-    #   _dispatch_value_change_update filter so a change to either cell
+    # Multi-cell contract:
+    # - `value_columns :decimal_value, :string_value` — both cells propagate
+    #   through versioning's snapshot loop and the Value
+    #   `_dispatch_value_change_update` filter so a change to either cell
     #   correctly fires the :update event.
-    # - operator_column: :currency_eq → :string_value; everything else →
-    #   :decimal_value. Routed via QueryBuilder.filter (plan 05-01).
-    # - read_value / write_value / apply_default_to: paired overrides
-    #   that compose / unpack the {amount, currency} hash across the two
-    #   physical columns. Without all three, single-cell defaults would
-    #   write a Hash to decimal_value and raise TypeMismatch.
-    # - cast: Hash input only. Bare Numeric/String is invalid — explicit
-    #   currency dimension is required at write time. Silently defaulting
-    #   to default_currency would invite bugs where users forget the
-    #   currency dimension entirely.
+    # - `operator_column` routes `:currency_eq` → `:string_value` and every
+    #   other supported op → `:decimal_value`. QueryBuilder reads this.
+    # - `read_value` / `write_value` / `apply_default` are the three
+    #   overrides paired with the multi-cell declaration. Without all three,
+    #   single-cell defaults would write a Hash to decimal_value and raise
+    #   TypeMismatch at save time.
+    # - `cast` requires a Hash input. Bare Numeric/String is invalid —
+    #   explicit currency dimension is required at write time. Silently
+    #   defaulting to default_currency would invite bugs where users forget
+    #   the currency dimension entirely.
     #
     # Operators (explicit narrowing — does NOT inherit string-search ops
     # like :contains/:starts_with from decimal_value's default since those
@@ -39,9 +39,10 @@ module TypedEAV
     # - allowed_currencies: Array<String> of ISO codes. When set,
     #   validate_typed_value enforces inclusion.
     class Currency < Base
-      value_column :decimal_value
-      storage_contract_class TypedEAV::CurrencyStorageContract
+      AMOUNT_COLUMN = :decimal_value
+      CURRENCY_COLUMN = :string_value
 
+      value_columns AMOUNT_COLUMN, CURRENCY_COLUMN
       operators(*%i[eq gt lt gteq lteq between currency_eq is_null is_not_null])
 
       store_accessor :options, :default_currency, :allowed_currencies
@@ -49,12 +50,45 @@ module TypedEAV
       validates :default_currency, format: { with: /\A[A-Z]{3}\z/ }, allow_nil: true
       validate :allowed_currencies_format
 
-      def self.value_columns
-        storage_contract_class.value_columns
+      # Route `:currency_eq` to the currency-code cell; every other supported
+      # operator targets the amount cell. The operator-validation gate in
+      # QueryBuilder.filter has already narrowed `operator` to the set
+      # declared above by the time this runs.
+      def self.operator_column(operator)
+        operator == :currency_eq ? CURRENCY_COLUMN : AMOUNT_COLUMN
       end
 
-      def self.operator_column(operator)
-        storage_contract_class.query_column(operator)
+      # Compose the logical Hash from the two cells. Returns `nil` only
+      # when BOTH cells are nil — a half-populated row still round-trips
+      # as the partial Hash so validation can surface the missing dimension.
+      def read_value(value_record)
+        amount = value_record[AMOUNT_COLUMN]
+        currency = value_record[CURRENCY_COLUMN]
+        return nil if amount.nil? && currency.nil?
+
+        { amount: amount, currency: currency }
+      end
+
+      # Unpack the casted Hash across the two cells. `nil` clears both.
+      def write_value(value_record, casted)
+        if casted.nil?
+          value_record[AMOUNT_COLUMN] = nil
+          value_record[CURRENCY_COLUMN] = nil
+        else
+          value_record[AMOUNT_COLUMN] = casted[:amount]
+          value_record[CURRENCY_COLUMN] = casted[:currency]
+        end
+      end
+
+      # Populate both cells from the field's configured default. Mirrors
+      # `write_value`'s Hash decomposition; tolerates string-keyed defaults
+      # for jsonb round-trip (`default_value_meta` stores raw config).
+      def apply_default(value_record)
+        default = default_value
+        return unless default.is_a?(Hash)
+
+        value_record[AMOUNT_COLUMN] = default[:amount] || default["amount"]
+        value_record[CURRENCY_COLUMN] = default[:currency] || default["currency"]
       end
 
       # Cast Hash input → [{amount: BigDecimal, currency: String}, false]

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

@@ -2,11 +2,26 @@
 
 module TypedEAV
   module Field
-    class Date < Base
+    # Date-typed field with optional min_date/max_date guards. Declares
+    # its own `date_value` storage and `:min_date`/`:max_date`
+    # `store_accessor`. `validate_date_range` is inherited from
+    # `Field::RangeBounded`.
+    #
+    # Latent-bug fix (per ADR-0004): the
+    # `validates :max_date, comparison: { greater_than_or_equal_to: :min_date }`
+    # macro now applies here (previously only Integer/Decimal carried it).
+    # A Date field configured with `max_date < min_date` fails at
+    # field-save instead of saving silently.
+    class Date < RangeBounded
       value_column :date_value
 
       store_accessor :options, :min_date, :max_date
 
+      validates :max_date,
+                comparison: { greater_than_or_equal_to: :min_date },
+                allow_nil: true,
+                if: :min_date
+
       def cast(raw)
         return [nil, false] if raw.nil?
 

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

@@ -2,11 +2,26 @@
 
 module TypedEAV
   module Field
-    class DateTime < Base
+    # DateTime-typed field with optional min_datetime/max_datetime
+    # guards. Declares its own `datetime_value` storage and
+    # `:min_datetime`/`:max_datetime` `store_accessor`.
+    # `validate_datetime_range` is inherited from `Field::RangeBounded`.
+    #
+    # Latent-bug fix (per ADR-0004): the
+    # `validates :max_datetime, comparison: { greater_than_or_equal_to: :min_datetime }`
+    # macro now applies here (previously only Integer/Decimal carried
+    # it). A DateTime field configured with `max_datetime < min_datetime`
+    # fails at field-save instead of saving silently.
+    class DateTime < RangeBounded
       value_column :datetime_value
 
       store_accessor :options, :min_datetime, :max_datetime
 
+      validates :max_datetime,
+                comparison: { greater_than_or_equal_to: :min_datetime },
+                allow_nil: true,
+                if: :min_datetime
+
       def cast(raw)
         return [nil, false] if raw.nil?
         return [raw, false] if raw.is_a?(::Time)

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

@@ -2,7 +2,15 @@
 
 module TypedEAV
   module Field
-    class Decimal < Base
+    # Decimal-typed field with optional min/max guards and optional
+    # `precision_scale` rounding. Declares its own `decimal_value`
+    # storage and `:min`/`:max`/`:precision_scale` `store_accessor`; the
+    # `validate :max, comparison:` macro guards against inverted bounds
+    # at field-save. `validate_range` is inherited from
+    # `Field::RangeBounded`. `Field::Percentage` extends this class to
+    # add the 0..1 invariant (chain depth becomes
+    # `Percentage < Decimal < RangeBounded < Base`).
+    class Decimal < RangeBounded
       value_column :decimal_value
 
       store_accessor :options, :min, :max, :precision_scale

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

@@ -2,12 +2,20 @@
 
 module TypedEAV
   module Field
-    class Email < Base
+    # Email-typed field. Inherits `string_value` storage shape, the
+    # `min_length` / `max_length` / `pattern` `store_accessor`, the
+    # `max_gte_min_length` guard, and the `validate_pattern_syntax` guard
+    # from `Field::ValidatedString`. Adds the `EMAIL_FORMAT` regex and
+    # layers the format check onto `validate_typed_value` via `super`.
+    #
+    # Latent-bug fix (per ADR-0004): `max_gte_min_length` (previously
+    # only on Text) now applies here — an Email field configured with
+    # `max_length < min_length` fails at field-save.
+    class Email < ValidatedString
+      # Re-declare value_column for Ruby class-ivar non-inheritance — see
+      # comment on Field::Text. STI dispatch is unaffected.
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-      validate :validate_pattern_syntax
-
       EMAIL_FORMAT = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
 
       def cast(raw)
@@ -21,20 +29,9 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
+        super
         record.errors.add(:value, "is not a valid email address") unless email_format_valid?(val)
       end
-
-      private
-
-      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/field/integer.rb

@@ -2,7 +2,12 @@
 
 module TypedEAV
   module Field
-    class Integer < Base
+    # Integer-typed field with optional min/max guards. Declares its own
+    # `integer_value` storage and `:min`/`:max` `store_accessor`; the
+    # `validate :max, comparison:` macro guards against inverted bounds
+    # at field-save. `validate_range` is inherited from
+    # `Field::RangeBounded`.
+    class Integer < RangeBounded
       value_column :integer_value
 
       store_accessor :options, :min, :max

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

@@ -2,6 +2,15 @@
 
 module TypedEAV
   module Field
+    # Long-text-typed field stored in the `text_value` column. Kept as a
+    # direct child of `Field::Base` (per ADR-0004 — array types,
+    # LongText, File, Image, Reference all stay direct children; only
+    # Text/Email/Url moved into the new `Field::ValidatedString` family).
+    # Inlines its own min_length / max_length check rather than joining
+    # the ValidatedString family because LongText does NOT carry the
+    # `:pattern` option, the `max_gte_min_length` guard, or the
+    # `validate_pattern_syntax` guard — the family base would attach
+    # validation surface LongText doesn't want.
     class LongText < Base
       value_column :text_value
 
@@ -12,7 +21,14 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        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
     end
   end

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

@@ -2,21 +2,24 @@
 
 module TypedEAV
   module Field
+    # Multi-choice option-set field. Stores the chosen values as a JSON
+    # array in `json_value`. Inherits `optionable? = true`, the
+    # public-facing sorted `allowed_values` helper, and the protected
+    # `validate_multi_option_inclusion` helper from `Field::Optionable`.
+    # Stays a direct child of `Field::Base` — Optionable is a concern
+    # (mixin), not an intermediate STI class, because Select and
+    # MultiSelect don't share a `value_column`.
+    #
+    # `validate_array_size` is called directly from `Field::Base`
+    # (cross-family outlier; also used by `Field::IntegerArray`).
     class MultiSelect < Base
+      include Optionable
+
       value_column :json_value
       operators :any_eq, :all_eq, :is_null, :is_not_null
 
-      def optionable? = true
       def array_field? = true
 
-      def allowed_values
-        if field_options.loaded?
-          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
-        else
-          field_options.sorted.pluck(:value)
-        end
-      end
-
       def cast(raw)
         return [nil, false] if raw.nil?
 

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Concern (mixin) for field types whose valid values are constrained
+    # to an enumeration of `Field::Option` rows.
+    #
+    # Included by: `Field::Select`, `Field::MultiSelect`. Both leaves stay
+    # as direct children of `Field::Base` — Select uses `string_value`,
+    # MultiSelect uses `json_value`. Inheritance can't unify storage for
+    # both, so we use a concern instead of an intermediate class.
+    #
+    # Provides:
+    #
+    # - `optionable?` overridden to `true` (default on `Field::Base` is
+    #   `false`).
+    # - `allowed_values` — the public-facing, **sorted** option-values
+    #   helper. When `field_options` is loaded, sorts in memory by
+    #   `[sort_order || 0, label]`; otherwise issues a `sorted.pluck`
+    #   query. Matches the per-leaf implementation that was duplicated
+    #   verbatim between Select and MultiSelect pre-refactor.
+    # - `validate_option_inclusion` / `validate_multi_option_inclusion`
+    #   protected helpers (moved from `Field::Base`). Both call into
+    #   `allowed_option_values` (the validator-facing fast path that still
+    #   lives on `Field::Base`) so they avoid the sort overhead on the hot
+    #   validation path.
+    #
+    # Public extension point: external authors can `include
+    # TypedEAV::Field::Optionable` to opt into the option-set surface
+    # without joining the Select/MultiSelect inheritance chain (see
+    # README §"Custom field types").
+    module Optionable
+      extend ActiveSupport::Concern
+
+      def optionable? = true
+
+      def allowed_values
+        if field_options.loaded?
+          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
+        else
+          field_options.sorted.pluck(:value)
+        end
+      end
+
+      protected
+
+      def validate_option_inclusion(record, val)
+        return if allowed_option_values.include?(val&.to_s)
+
+        record.errors.add(:value, :inclusion)
+      end
+
+      def validate_multi_option_inclusion(record, val)
+        invalid = Array(val).map(&:to_s) - allowed_option_values
+        record.errors.add(:value, :inclusion) if invalid.any?
+      end
+    end
+  end
+end

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

@@ -23,10 +23,10 @@ module TypedEAV
     # - decimal_places: Integer >= 0 (default 2). Format-time precision.
     # - display_as: :fraction | :percent (default :fraction).
     class Percentage < Decimal
-      # Re-declare value_column :decimal_value. ColumnMapping's value_column
-      # stores the column on `@value_column` (a class instance variable on
-      # the declaring class) — Ruby class instance variables are NOT
-      # inherited through subclass lookup, so `Percentage.value_column`
+      # Re-declare value_column :decimal_value. TypedStorage's `value_column`
+      # / `value_columns` setters write to `@value_columns` (a class instance
+      # variable on the declaring class) — Ruby class instance variables are
+      # NOT inherited through subclass lookup, so `Percentage.value_column`
       # would raise NotImplementedError without this re-declaration.
       # Re-declaring with the same column is BC-safe and explicit; STI
       # behavior (the `type` column stores "TypedEAV::Field::Percentage")
@@ -38,9 +38,9 @@ module TypedEAV
       validate :decimal_places_format
       validate :display_as_inclusion
 
-      # Inherits supported_operators (DEFAULT_OPERATORS_BY_COLUMN
+      # Inherits supported_operators (TypedStorage::DEFAULT_OPERATORS_BY_COLUMN
       # [:decimal_value]) and cast (BigDecimal parse) from Decimal.
-      # Inherits read_value / write_value / apply_default_to defaults from
+      # Inherits read_value / write_value / apply_default defaults from
       # Field::Base via Decimal's chain.
 
       def validate_typed_value(record, val)