typed_eav 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 630fefbfa32546ed8863b3971600d58188322895db16e80525eac5b8500f7cea
-  data.tar.gz: 77a27d9c81984d5c109fac16d87dd79ea34eb15bd10d00a0d62d3c4d9716c65c
+  metadata.gz: 66997bbaca41b0302fe7a86baf9b22233f2ade442c2255c3323a900245bd78fb
+  data.tar.gz: 90498aa57c720504bc09a34e62fab81d0377baaeab3ea2d0598317d6d5b38a93
 SHA512:
-  metadata.gz: 53ab3bd2e9ea76c602e9bfc556d97a20a4caa0b986fce7c3704c149f51b0ba8fedbe25994a40fa38fb227f5dfdec7c54db4c6e9c77af6f6a67fc33edc0edf3f0
-  data.tar.gz: 1e5abe7926aa77074b753edc7ad3b6f9b243595acc62d13bfdaf432ef5b71ee17afbb05566732c99543c6eaf30ee2d0bfbd368f1aec6ae02b6eab3415e60f4fe
+  metadata.gz: a67ca56147f16ca0b6ffa02121f5783dc10f588ae36bc4d6b9df73c5de19bfac22be3b76613c693719156d15b8442723de4fd05479f72dc8074ad5b272c2599e
+  data.tar.gz: f4802412a11f7d5010487c2bede22037a6302653269eaf2dd4a933f98612296d38b2a6ce4bdd6244db1286c6572ac706615e9723ed73a2bc0ac582289af7ebd8

data/CHANGELOG.md

@@ -5,6 +5,138 @@ 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.1] - 2026-05-25
+
+Documentation-only release. No code or behavior changes.
+
+### Added
+
+- README §"Architecture" — full overview of the post-0.3.0 internal
+  module layout: macro entry (`HasTypedEav`), the two-altitude query
+  pattern (`EntityQuery` → `FilterQuery` → `QueryBuilder`), `BulkRead`
+  and `BulkWrite` siblings, `InstanceMethods`, `Field::TypedStorage`
+  concern, family intermediate bases (`ValidatedString`, `RangeBounded`,
+  `Optionable`), `ScopeTuple`, `Partition`, `EventDispatcher`, and the
+  Phase-6 modules (`SchemaPortability`, `CSVMapper`). Anchored to ADRs
+  0001–0005 throughout.
+
+### Removed
+
+- `TEST_PLAN.md` — pre-0.3.0 test-sweep planning artifact (2026-04-08).
+  Described specs for modules deleted in #9. Git history preserves it.
+- `typed_eav-enhancement-plan.md` — pre-0.3.0 phased roadmap. References
+  v0.1.0 line numbers and Phase-1 work that has since shipped. Git
+  history preserves it.
+
+## [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.
@@ -96,6 +228,8 @@ worked examples.
 
 Initial release.
 
+[0.3.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.1
+[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 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_record, casted)
-    value_record[:decimal_value] = casted&.fetch(:amount, nil)
-    value_record[:string_value] = casted&.fetch(:currency, nil)
+  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
 
@@ -1121,6 +1239,128 @@ The gem creates four tables:
 - `typed_eav_options` - allowed values for select/multi-select fields
 - `typed_eav_sections` - optional UI grouping
 
+## Architecture
+
+Internal module layout as of 0.3.0. Most consumers never reach for these directly — the public surface is the `has_typed_eav` macro and the instance/class methods it installs — but the split matters if you're extending the gem, debugging an integration, or evaluating it for production. Decisions are anchored by [ADR-0001](docs/adr/0001-collapse-column-mapping-stack.md) through [ADR-0005](docs/adr/0005-keep-phase-six-modules-independent.md).
+
+### Macro entry: `HasTypedEav`
+
+`lib/typed_eav/has_typed_eav.rb` (~120 LOC) is the macro shell. When you call `has_typed_eav` on an AR model, it:
+
+1. `extend`s `TypedEAV::EntityQuery` onto the class (class-level query methods).
+2. `include`s `TypedEAV::HasTypedEav::InstanceMethods` (per-record accessors).
+3. Wires scope/parent-scope kwargs into the model's class-level configuration.
+4. Registers the model with `TypedEAV::Registry`.
+
+The macro is intentionally thin. All real behavior lives in the modules it pulls in.
+
+### Class-level reads: two-altitude query pattern
+
+```
+Contact.where_typed_eav(...)         ← public class method
+       │
+       ▼
+TypedEAV::EntityQuery                 ← high altitude: orchestrator
+  • resolves scope/parent_scope from ambient context or explicit kwargs
+  • owns the UNSET_SCOPE / ALL_SCOPES sentinels
+  • delegates to FilterQuery
+       │
+       ▼
+TypedEAV::FilterQuery                 ← multi-filter composition
+  • normalizes filter input shapes (positional, hash, hash-of-hashes)
+  • looks up field definitions via TypedEAV::Partition
+  • per filter, asks QueryBuilder for the SQL fragment
+  • unions/intersects per-field entity-id sets
+  • returns an ActiveRecord::Relation scoped to the host model
+       │
+       ▼
+TypedEAV::QueryBuilder                ← low altitude: per-field SQL primitive
+  • turns a single (field, op, value) into a WHERE clause against typed_eav_values
+  • knows about typed-column projections (integer_value, string_value, etc.)
+  • knows about operator-specific column choice (currency-cents vs currency-code)
+```
+
+`QueryBuilder` is the single place that decides "given this field and this operator, which column and which SQL fragment?" `FilterQuery` never builds SQL fragments directly; `EntityQuery` never touches columns. Splitting the two altitudes keeps custom field types extending only the column-mapping surface (`value_column`, `operators`, `operator_column`) without ever subclassing `FilterQuery`.
+
+### Bulk reads: `BulkRead`
+
+`typed_eav_hash_for(records)` (the plural read) routes through `TypedEAV::BulkRead`. Given a record collection and an effective `(scope, parent_scope)`, it:
+
+1. Groups records by partition tuple via `TypedEAV::Partition.definitions_by_name`.
+2. Issues one batched `WHERE entity_id IN (...) AND field_id IN (...)` query per partition.
+3. Returns a `{record_id => {field_name => value}}` map.
+
+Single-record reads (`typed_eav_value`, `typed_eav_hash`) live on `InstanceMethods` and use the same partition helpers but without batching.
+
+### Bulk writes: `BulkWrite`
+
+`bulk_set_typed_eav_values(records, attrs)` routes through `TypedEAV::BulkWrite`, an executor that:
+
+1. Memoizes field definitions for the call via `Thread.current[:typed_eav_bulk_defs_memo]`.
+2. Validates each attribute against its field type's cast contract.
+3. Upserts in a single SQL round trip per typed column.
+
+`BulkWrite` and `BulkRead` are siblings — one read path, one write path — but they don't share a base class. Per [ADR-0005](docs/adr/0005-keep-phase-six-modules-independent.md), keeping them independent preserves the option to evolve each on its own schedule.
+
+### Per-record reads/writes: `InstanceMethods`
+
+`lib/typed_eav/has_typed_eav/instance_methods.rb` (~250 LOC) holds the per-record API:
+
+- `typed_eav_value(name)` / `typed_eav_hash` — reads
+- `set_typed_eav_value(name, value)` / `typed_eav_attributes=` — writes
+- `typed_eav_changes` — dirty tracking
+- `typed_eav_scope` / `typed_eav_parent_scope` — scope resolution per record
+
+Every method uses `TypedEAV::Partition.definitions_by_name` so the collision-precedence rules for ambient/explicit/parent scopes are computed in one place.
+
+### Field types and storage: `Field::TypedStorage`
+
+`TypedEAV::Field::Base` is the STI parent of every field type. The shared storage surface lives in the `TypedEAV::Field::TypedStorage` concern (`lib/typed_eav/field/typed_storage.rb`, ~200 LOC), auto-included on `Field::Base`. Per [ADR-0001](docs/adr/0001-collapse-column-mapping-stack.md), it provides:
+
+- **Class DSL**: `value_column`, `value_columns`, `operators`, `operator_column`, `supported_operators` — describe where typed values live and which operators they support.
+- **Instance override points**: `read_value(record)`, `write_value(record, casted)`, `apply_default(record)` — the three methods a multi-cell field type overrides.
+- **Concrete snapshot helpers**: `value_changed?`, `before_snapshot`, `after_snapshot` — derived automatically from `value_columns`; not overridable.
+
+Custom multi-cell field types subclass `Field::Base` directly and override only the three instance methods. See §[Multi-cell field types](#multi-cell-field-types) for `Currency` as the canonical worked example.
+
+### Field families: intermediate STI bases
+
+Per [ADR-0004](docs/adr/0004-field-family-intermediate-bases.md), three intermediate STI parents factor shared validation behavior out of `Field::Base`:
+
+- **`TypedEAV::Field::ValidatedString`** — parent of `Text`, `Email`, `Url`. Owns string-length and pattern-validation helpers including `max_gte_min_length` (which now covers Email/Url, not just Text).
+- **`TypedEAV::Field::RangeBounded`** — parent of `Integer`, `Decimal`, `Date`, `DateTime` (and `Percentage < Decimal`). Owns range-validation helpers including `validates :max, comparison: { greater_than_or_equal_to: :min }` (which now covers Date/DateTime, not just Integer/Decimal).
+- **`TypedEAV::Field::Optionable`** — a Rails concern included by `Select` and `MultiSelect`. Owns the public-facing sorted `allowed_values` reader and the option-inclusion validators.
+
+`Color`, `Boolean`, `Json`, and the array field types (`TextArray`, `IntegerArray`, `DecimalArray`, `DateArray`) remain direct children of `Field::Base`. See §[Family intermediate bases](#family-intermediate-bases-extension-points) for extension examples.
+
+### Scope tuple normalization: `ScopeTuple`
+
+`TypedEAV::ScopeTuple` (`lib/typed_eav/scope_tuple.rb`, ~120 LOC) is the canonical source of truth for the `(scope, parent_scope)` partition tuple. It provides:
+
+- `normalize_permissive(scope)` — coerces input to a tuple; tolerates bare scalars (used by `with_scope`, `normalize_scope`, `Field#validate_parent_scope_invariant`).
+- `normalize_strict(scope)` — same shape, but raises on bare-scalar input (used by `current_scope`; preserves Phase-1's asymmetric contract that `Config.scope_resolver` must return a tuple).
+- `invariant_satisfied?(scope, parent_scope)` — Boolean check for the orphan-parent invariant (`parent_scope` set without `scope` = invalid).
+
+Each calling site keeps its own response policy (raise / AR error / silent narrow) using the Boolean return — `ScopeTuple` is a predicate, not an enforcer.
+
+### Partition tuple helpers: `Partition`
+
+`TypedEAV::Partition` (`lib/typed_eav/partition.rb`, ~100 LOC) owns the `(entity_type, scope, parent_scope)` precedence rules:
+
+- `definitions_by_name(model, scope, parent_scope)` — returns the field-definitions map for a single resolved partition.
+- `definitions_multimap_by_name(model)` — returns the cross-partition multimap used by `unscoped { }` blocks.
+- `visible_fields(model, scope, parent_scope)` / `visible_sections(...)` — scope-respecting field/section iteration with the orphan-parent invariant inlined via `ScopeTuple.invariant_satisfied?`.
+
+The definitions helpers used to live as class methods on `HasTypedEav` before 0.3.0. They moved to `Partition` per [ADR-0002](docs/adr/0002-entity-query-orchestration.md) because they describe the partition domain, not the macro.
+
+### Events: `EventDispatcher`
+
+`TypedEAV::EventDispatcher` (`lib/typed_eav/event_dispatcher.rb`, ~150 LOC) is the broker for `on_value_change` and `on_field_change` callbacks. Per [ADR-0003](docs/adr/0003-keep-event-dispatcher-broker.md), it intentionally stays a broker rather than getting absorbed into either `Value` or `Field` — its multi-publisher / multi-subscriber shape doesn't belong on either model. See §[Event hooks](#event-hooks) for the public callback contract.
+
+### Schema portability and CSV: independent modules
+
+`TypedEAV::SchemaPortability` and `TypedEAV::CSVMapper` (Phase-6 modules) are deliberately decoupled from the core read/write path per [ADR-0005](docs/adr/0005-keep-phase-six-modules-independent.md). They depend on the public `has_typed_eav` macro surface, never on internal modules.
+
 ## License
 
 MIT