typed_eav 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baca2cc8536abd74f256197ca9204cab2cd552a1935be48c87cb80fa914ac8e6
-  data.tar.gz: 3f61937a75ab864caa261359104cf4309fee8d8215b5603fbbd98f9be2c93f11
+  metadata.gz: d06c0178a808cf7b67cf2b6970654fb922b02f9fa7a808eba6595f0aa3f1a38f
+  data.tar.gz: 456c0c15222d5ede4e12778ba7c95d0977cc726ecd0506141180badceb7c395b
 SHA512:
-  metadata.gz: ec9cfdb735c0820997082e991b07ed3d204bc362d40f0c85495a92b91320470c1ed89906d75a824573256f545d886df5a4ecf37ef4f866be33ccfc6e9d49c88e
-  data.tar.gz: 1c575620e89da9da387c02a92d891288a7cf9558c6296008afe38081ce65f5716c385e2ad4c7eb4caecf38b376bc3f61a1437c9c15d9754657b2c7f45f328741
+  metadata.gz: 720454235c352fe0151eb533c53d172549e35e3920ae9ff730b66d8781ae3bf7cf1763afdd445cb0f36f559a21758451d336c640230c5741d58a055fd3c8c7db
+  data.tar.gz: 91548d07b441db3f7145b2645264161a0bd0294f5bc466c045f41fef98ea8f6dd240548beb4657c59343ca337b5cb7ac7faef5e6749211634fb812034e125567

data/CHANGELOG.md

@@ -5,6 +5,123 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-05-25
+
+Pre-1.0 architecture cleanup arc (issues #9–#13). No public-API breakage
+for host AR models or registered custom field types; behavior changes are
+limited to two latent-bug fixes (now raised at field-save) and one
+internal helper relocation (see "Changed" below). Anchored by ADRs
+0001–0005.
+
+### Added
+
+- New `TypedEAV::Field::TypedStorage` concern (auto-included on
+  `Field::Base`) collapses the prior storage stack into three paired
+  override points: `read_value(record)`, `write_value(record, casted)`,
+  `apply_default(record)`. Custom multi-cell field types now extend
+  `Field::Base` directly and override only these methods. See README
+  §"Multi-cell field types" and ADR-0001 (issue #9).
+- New top-level `TypedEAV::ScopeTuple` module exposes the
+  `[scope, parent_scope]` normalization surface: `normalize_permissive`,
+  `normalize_strict`, and `invariant_satisfied?`. Used by `Partition`,
+  `TypedEAV.with_scope`, `Config#resolve_scope`, and the query path
+  (issue #10).
+- New top-level query objects extracted from `HasTypedEAV`:
+  `TypedEAV::EntityQuery` (class-method orchestration on host AR models),
+  `TypedEAV::FilterQuery` (multi-filter SQL composition for
+  `where_typed_eav` / `with_field`), and `TypedEAV::BulkRead` (bulk
+  per-record reads via `eav_values_for`). See ADR-0002 (issue #11).
+- New field family intermediate bases collapse per-leaf duplication:
+  - `TypedEAV::Field::ValidatedString` — min/max-length + regex-pattern
+    validation surface for `string_value`-backed types (parent of
+    `Email` and `Url`).
+  - `TypedEAV::Field::RangeBounded` — min/max-bound validation helpers
+    for comparable single-value types (parent of `Integer`, `Decimal`,
+    `Date`, `DateTime`).
+  - `TypedEAV::Field::Optionable` — concern (not parent) for types that
+    draw values from a `Field::Option` set; included by `Select` and
+    `MultiSelect`.
+
+  See README §"Family intermediate bases (extension points)" and
+  ADR-0004 (issue #12).
+
+### Changed
+
+- **Internal helper move.** `TypedEAV::HasTypedEAV.definitions_by_name`
+  and `TypedEAV::HasTypedEAV.definitions_multimap_by_name` moved to
+  `TypedEAV::Partition.definitions_by_name` /
+  `TypedEAV::Partition.definitions_multimap_by_name`. These helpers were
+  technically callable from application code but not documented;
+  partition-tuple precedence is a partition concept and the new home
+  reflects that. External callers (if any) should update the call site.
+  See ADR-0002 (issue #11).
+- `TypedEAV::HasTypedEAV` is now a slim macro module
+  (`lib/typed_eav/has_typed_eav.rb`) that delegates to a per-instance
+  methods file (`lib/typed_eav/has_typed_eav/instance_methods.rb`) plus
+  the new `EntityQuery` / `FilterQuery` / `BulkRead` objects. Public
+  class-method and instance-method signatures on host AR models are
+  unchanged. See ADR-0002 (issue #11).
+- Field validation now runs paired-bound checks at field-save time, not
+  only at value-write time:
+  - `Field::Email` / `Field::Url` (via `ValidatedString`) reject
+    `max_length < min_length` when the field record is saved.
+  - `Field::Date` / `Field::DateTime` (via `RangeBounded` leaves) reject
+    inverted `min_date`/`max_date` (and `min_datetime`/`max_datetime`)
+    bounds when the field record is saved.
+
+  Both were latent bugs prior to v0.3.0 — the bound mismatch was only
+  surfaced when a `Value` was written. Authors of custom field types
+  that store inverted bounds will now see the validation fail earlier.
+  See ADR-0004 (issue #12).
+
+### Removed
+
+- `TypedEAV::Field::FieldStorageContract`,
+  `TypedEAV::Field::CurrencyStorageContract`, and
+  `TypedEAV::Field::ColumnMapping` are deleted; their surface lives on
+  `Field::TypedStorage`. ADR-0001 (issue #9).
+- `TypedEAV::Partition.validate_tuple!` is deleted; callers use
+  `TypedEAV::ScopeTuple.normalize_strict` directly. Issue #10.
+
+### Internal
+
+- `TypedEAV::EventDispatcher` is retained as the synchronous broker
+  between `TypedEAV::Hooks` and `ActiveSupport::Notifications`. The
+  cleanup arc explicitly considered collapsing it and rejected that:
+  the broker is the seam where event-name normalization and the
+  `notifications: false` opt-out live. See ADR-0003.
+- The Phase-6 modules — `TypedEAV::BulkWrite`,
+  `TypedEAV::Importers::CSVMapper`, and
+  `TypedEAV::SchemaPortability::*` — remain independent top-level
+  modules. The cleanup arc explicitly considered consolidating them
+  under a single `TypedEAV::Operations` namespace and rejected that:
+  the modules share no internal contract and the namespace would be
+  cosmetic. See ADR-0005.
+- Cyclomatic-complexity rubocop disables that previously masked the
+  `HasTypedEAV` mega-module are gone — the split files clear the
+  default complexity thresholds.
+
+### References
+
+- Issue #9 — `Field::TypedStorage` concern.
+- Issue #10 — `ScopeTuple` extraction.
+- Issue #11 — `EntityQuery` / `FilterQuery` / `BulkRead` split.
+- Issue #12 — Field family intermediate bases.
+- Issue #13 — release coordination.
+- ADR-0001 — collapse field storage stack.
+- ADR-0002 — split `HasTypedEAV` into query objects.
+- ADR-0003 — retain `EventDispatcher` as broker.
+- ADR-0004 — field family intermediate bases.
+- ADR-0005 — keep Phase-6 modules independent.
+
+## [0.2.1] - 2026-05-08
+
+Metadata-only release.
+
+### Changed
+
+- Updated the RubyGems package author metadata to `dchuk`.
+
 ## [0.2.0] - 2026-04-29
 
 Two-level scope partitioning. Field and section definitions now partition on
@@ -88,5 +205,7 @@ worked examples.
 
 Initial release.
 
+[0.3.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.0
+[0.2.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.2.1
 [0.2.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.2.0
 [0.1.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.1.0

data/README.md

@@ -555,71 +555,189 @@ TypedEAV.configure do |c|
 end
 ```
 
+### Family intermediate bases (extension points)
+
+`Field::Base` is the universal parent, but three intermediate family
+bases collapse the most common per-leaf duplication. Pick the right
+parent and you inherit the family's validation surface for free.
+
+- **`TypedEAV::Field::ValidatedString`** — subclass when your custom
+  type stores in `string_value` and wants a min/max-length + regex-pattern
+  validation surface. Inherits `value_column :string_value`,
+  `store_accessor :options, :min_length, :max_length, :pattern`,
+  numericality validators on `min_length` / `max_length`, a
+  `max_gte_min_length` guard that rejects inverted bounds at field-save,
+  and a `validate_pattern_syntax` guard that rejects bad regexes at
+  field-save. The default `validate_typed_value(record, val)` runs
+  `validate_length` plus `validate_pattern if pattern.present?`. Override
+  it and call `super` to layer on a format-specific check (the built-in
+  `Field::Email` / `Field::Url` are the canonical pattern).
+
+  ```ruby
+  class Fields::Slug < TypedEAV::Field::ValidatedString
+    SLUG_FORMAT = /\A[a-z0-9-]+\z/
+
+    def cast(raw)
+      [raw&.to_s&.strip&.downcase, false]
+    end
+
+    def validate_typed_value(record, val)
+      super  # length + pattern from the family base
+      record.errors.add(:value, "is not a valid slug") unless SLUG_FORMAT.match?(val.to_s)
+    end
+  end
+  ```
+
+- **`TypedEAV::Field::RangeBounded`** — subclass when your custom type
+  stores a single comparable value (numeric or temporal) constrained by
+  a min/max bound. Each leaf still declares its own `value_column` and
+  its own `store_accessor` (key names vary by family member: `:min`/`:max`
+  for numeric; `:min_date`/`:max_date` for date;
+  `:min_datetime`/`:max_datetime` for datetime). The family base
+  provides protected `validate_range` / `validate_date_range` /
+  `validate_datetime_range` helpers. Each leaf should pair its
+  `store_accessor` with the macro
+  `validates :max, comparison: { greater_than_or_equal_to: :min }, allow_nil: true, if: :min`
+  (or the analogous form for the leaf's key names) so inverted bounds
+  fail at field-save.
+
+  ```ruby
+  class Fields::Score < TypedEAV::Field::RangeBounded
+    value_column :integer_value
+
+    store_accessor :options, :min, :max
+    validates :max, comparison: { greater_than_or_equal_to: :min }, allow_nil: true, if: :min
+
+    def cast(raw)
+      raw.nil? ? [nil, false] : [Integer(raw.to_s, exception: false), raw.to_s.empty? ? false : true]
+    end
+
+    def validate_typed_value(record, val)
+      validate_range(record, val)
+    end
+  end
+  ```
+
+- **`TypedEAV::Field::Optionable`** — `include` this concern when your
+  custom type's valid values are drawn from a `Field::Option` set.
+  Provides `optionable? = true`, a public-facing sorted
+  `allowed_values` helper, and protected
+  `validate_option_inclusion` / `validate_multi_option_inclusion`
+  helpers. Mixin (not inheritance) because option-set field types may
+  use different `value_column`s — the built-in `Field::Select` stores in
+  `string_value` while `Field::MultiSelect` stores in `json_value`, and
+  both stay as direct children of `Field::Base`.
+
+  ```ruby
+  class Fields::Tag < TypedEAV::Field::Base
+    include TypedEAV::Field::Optionable
+
+    value_column :string_value
+    operators :eq, :not_eq, :is_null, :is_not_null
+
+    def cast(raw)
+      [raw&.to_s, false]
+    end
+
+    def validate_typed_value(record, val)
+      validate_option_inclusion(record, val)
+    end
+  end
+  ```
+
+The rule of thumb: subclass an intermediate family base when the new
+field type shares its storage and validation surface with the family;
+include `Optionable` when it draws values from an option set; subclass
+`Field::Base` directly (as the `Phone` example above does) when none of
+the family surfaces fit. `validate_array_size` lives on `Field::Base`
+itself — its callers span unrelated families.
+
 ### Multi-cell field types
 
 External field types may store their logical value across multiple typed
-columns. Storage behavior is exposed through `field.storage_contract`,
-which keeps callers from knowing whether a field is single-cell or
-multi-cell. The contract covers:
-
-- `value_columns` - the native typed cells used for storage, snapshots,
-  reverting, and update change detection.
-- `read(value_record)` / `write(value_record, casted)` - logical value
-  reads and writes.
-- `apply_default(value_record)` - default application across the field's
-  storage cells.
-- `query_column(operator)` - query routing for each supported operator.
-- `before_snapshot(value_record, change_type)` /
-  `after_snapshot(value_record, change_type)` - version row jsonb shape.
-- `changed?(value_record)` - update event gating across every storage
-  cell the field owns.
-
-Single-cell field types inherit the default contract. For multi-cell
-fields, create a `TypedEAV::FieldStorageContract` subclass and select it
-from the field class:
+columns. The entire storage surface lives directly on `Field::Base` via
+the `Field::TypedStorage` concern, so a custom multi-cell type is just a
+`Field::Base` subclass that overrides three instance methods.
+
+**Class-level DSL** (declared at class load time):
+
+- `value_column :col` – single-cell sugar; declares the primary cell.
+- `value_columns :a, :b, ...` – plural form for multi-cell types. The
+  primary cell is `value_columns.first`. Both forms share storage;
+  `value_column` and `value_columns` are interchangeable getters/setters.
+- `operators :eq, :gt, ...` – restrict the supported operator set.
+- `self.operator_column(op)` – override to route different operators to
+  different cells. Defaults to `value_columns.first`.
+
+**Override-point instance methods** (the entire extension surface for
+multi-cell types):
+
+- `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 `default_value`.
+
+The defaults target `value_columns.first`, so single-cell field types
+keep working without overrides. The three methods are paired – override
+all three or your reads will see a multi-cell shape that writes / defaults
+cannot produce.
+
+**Concrete snapshot helpers** (NOT overridable; derived from
+`value_columns`):
+
+- `value_changed?(record)` – true iff any cell saw a saved change.
+- `before_snapshot(record, change_type)` / `after_snapshot(record, change_type)`
+  – per-cell hashes keyed by string column names; powers the versioning
+  jsonb shape.
+
+Custom multi-cell type example (matches the built-in `Field::Currency`):
 
 ```ruby
-class MoneyStorageContract < TypedEAV::FieldStorageContract
-  def self.value_columns = %i[decimal_value string_value]
-  def self.query_column(operator) = operator == :currency_eq ? :string_value : :decimal_value
-
-  def read(value_record)
-    amount = value_record[:decimal_value]
-    currency = value_record[:string_value]
-    amount.nil? && currency.nil? ? nil : { amount: amount, currency: currency }
+class Fields::Money < TypedEAV::Field::Base
+  AMOUNT_COLUMN = :decimal_value
+  CURRENCY_COLUMN = :string_value
+
+  value_columns AMOUNT_COLUMN, CURRENCY_COLUMN
+  operators :eq, :gt, :lt, :gteq, :lteq, :between, :currency_eq, :is_null, :is_not_null
+
+  def self.operator_column(operator)
+    operator == :currency_eq ? CURRENCY_COLUMN : AMOUNT_COLUMN
   end
 
-  def write(value_record, casted)
-    value_record[:decimal_value] = casted&.fetch(:amount, nil)
-    value_record[:string_value] = casted&.fetch(:currency, nil)
+  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
+
+  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
 
   def apply_default(value_record)
-    default = field.default_value
+    default = default_value
     return unless default.is_a?(Hash)
 
-    value_record[:decimal_value] = default[:amount] || default["amount"]
-    value_record[:string_value] = default[:currency] || default["currency"]
+    value_record[AMOUNT_COLUMN] = default[:amount] || default["amount"]
+    value_record[CURRENCY_COLUMN] = default[:currency] || default["currency"]
   end
 end
-
-class Fields::Money < TypedEAV::Field::Base
-  value_column :decimal_value
-  storage_contract_class MoneyStorageContract
-end
 ```
 
-Compatibility helpers such as `self.value_columns` and
-`self.operator_column(operator)` may delegate to the selected contract
-when older callers still use those class methods.
-
-Defaults delegate to `value_column` for single-cell storage, so existing
-single-cell types are unchanged. The built-in `Field::Currency` is the
-canonical multi-cell consumer of these extension points.
+The built-in `Field::Currency` is the canonical multi-cell consumer of
+these extension points and reads as a normal `Field::Base` subclass with
+exactly three method overrides.
 
 ### Built-in field types
 
-- **`Currency`:** Stores `{amount: BigDecimal, currency: String}` across two typed columns (`decimal_value` for the amount; `string_value` for the ISO 4217 currency code) through `CurrencyStorageContract`. Operators: `:eq`, `:gt`, `:lt`, `:gteq`, `:lteq`, `:between` target the amount; `:currency_eq` targets the currency code; `:is_null` / `:is_not_null` target the amount column (a Currency value is null when its amount is null). Cast input MUST be a hash with `:amount` and/or `:currency` keys — bare numeric/string values are rejected with `:invalid` to enforce explicit currency dimension at write time. Options: `default_currency` (String ISO code, applied as fallback only when an amount is given without an explicit currency), `allowed_currencies` (Array of ISO codes; `validate_typed_value` enforces inclusion). Versioning snapshots automatically capture both columns through the storage contract. The `:currency_eq` operator is registered ONLY on `Field::Currency`; the QueryBuilder operator-validation gate rejects it with a clear `ArgumentError` if invoked on any other field type.
+- **`Currency`:** Stores `{amount: BigDecimal, currency: String}` across two typed columns (`decimal_value` for the amount; `string_value` for the ISO 4217 currency code). Multi-cell storage is declared via `value_columns :decimal_value, :string_value`; reads, writes, and default application override `read_value`, `write_value`, and `apply_default` directly on `Field::Currency`. Operators: `:eq`, `:gt`, `:lt`, `:gteq`, `:lteq`, `:between` target the amount; `:currency_eq` targets the currency code; `:is_null` / `:is_not_null` target the amount column (a Currency value is null when its amount is null). Cast input MUST be a hash with `:amount` and/or `:currency` keys — bare numeric/string values are rejected with `:invalid` to enforce explicit currency dimension at write time. Options: `default_currency` (String ISO code, applied as fallback only when an amount is given without an explicit currency), `allowed_currencies` (Array of ISO codes; `validate_typed_value` enforces inclusion). Versioning snapshots automatically capture both columns because the snapshot helpers iterate `value_columns`. The `:currency_eq` operator is registered ONLY on `Field::Currency`; the QueryBuilder operator-validation gate rejects it with a clear `ArgumentError` if invoked on any other field type.
 
   ```ruby
   Contact.where_typed_eav(name: "price", op: :currency_eq, value: "USD")
@@ -676,7 +794,7 @@ canonical multi-cell consumer of these extension points.
   Contact.where_typed_eav(name: "manager", op: :references, value: 42)  # filter by FK
   ```
 
-- **Summary:** The built-in field types **Image, File, Reference, Currency, Percentage** all preserve the cast-tuple contract (`[casted, invalid?]`), the operator-dispatch model (`supported_operators` + `operator_column` for multi-cell types), and the no-hardcoded-attribute-references foundational principle. The multi-cell extension surface (`read_value`, `apply_default_to`, `operator_column`, and `write_value`) is the canonical way to build any future external multi-cell field type.
+- **Summary:** The built-in field types **Image, File, Reference, Currency, Percentage** all preserve the cast-tuple contract (`[casted, invalid?]`), the operator-dispatch model (`supported_operators` + `operator_column` for multi-cell types), and the no-hardcoded-attribute-references foundational principle. The multi-cell extension surface (`read_value`, `write_value`, `apply_default`, and `operator_column`) is the canonical way to build any future external multi-cell field type.
 
 ## Validation Behavior
 

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