typed_eav 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 312b444b0c7b29eb298af1ef5bba02d3ba56ad811399b3ffcd2dfd2afd88267b
-  data.tar.gz: cfa3ca85088eaff46dff6657d098f9fcf38fec9129b53792cfb37cc19e4358ad
+  metadata.gz: 026326e328ecf153d7ba72eeac001470ba67307ed17bf5cef68f52548b6abd47
+  data.tar.gz: 6a76dce02983e81312d67662de6837804b51e691ab0d79dbfb13cacc2b25c19c
 SHA512:
-  metadata.gz: abcb3cde1dc9d09da1ea014165c245d74aa2ef2f5fd566ecc9f86343b8e30b1ca32bcc10eb9735a06a23641bb0ccef7c1078d2be288a724a20b6d7e44468e6d9
-  data.tar.gz: b259edd0ece6e756569a151194368fc0adda83063d56683f9113d6373c0eede174cb545f9d1ca0ccc70e2dd512239494299f3da8608567aa5e47989e3b780eb3
+  metadata.gz: 1677489ecff776e1914305db8d9681a6cb52891282c6602b3d6b12acb99b89d2263bca877606e686e64d260ecff1f5170ac0f6a733b8f7f5592447d5f8852b90
+  data.tar.gz: 528cbe73ee76daa4e2bb50806b1e148483a68ac9563e2b3c49a3110ee153fba00bd7a6f79612824dc018fc7d13bfcde7e81ed1b0daa67190b401320ee9ea1e5f

data/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-04
+
+New SQL-backed query APIs, selective/preloaded bulk reads, logical dirty
+tracking, and read-only schema previews. Existing read defaults are preserved;
+no database migrations or new runtime dependencies are required.
+
+### Added
+
+- Read-only `SchemaPortability.preview_schema` compares exact-partition
+  portable schemas with current definitions, exposing field/section/option
+  differences, conditional import actions, and risk flags. Type swaps remain
+  blocked and omitted definitions are not treated as deletions. Previewing
+  never applies changes or guarantees a later import's success. (#51)
+- `saved_typed_eav_changes` exposes the last successful host save's logical
+  changes inside `after_save` callbacks. Failed saves preserve the prior
+  snapshot; no-op saves, reload, and rollback have explicit lifecycle
+  semantics independent of audit/versioning. (#48)
+- Database-backed `aggregate_typed_eav` min/max/sum for Integer and Decimal
+  field families, including Percentage. Decimal precision, caller host sets,
+  and explicit empty/NULL semantics are preserved; references and multi-cell
+  Currency are rejected instead of silently aggregated. (#50)
+- SQL-backed distinct typed values, exact distinct counts, and bounded
+  per-value host counts. Caller host filters/pagination and field-definition
+  precedence are retained; explicit NULL, false, and empty strings have
+  documented semantics without host or Value hydration. (#49)
+- Explicit `source: :preloaded` bulk reads reuse caller-loaded Value graphs,
+  including unsaved edits, with one batched definition lookup and no duplicate
+  Value hydration. Incomplete required preloads fail clearly; fresh database
+  reads remain the default. (#46)
+- Pending logical typed-value changes via `typed_eav_changes`, covering
+  host-associated named/nested edits and marked removals without loading
+  untouched Value collections. Failed saves retain validation feedback and
+  pending changes; this API is separate from persisted audit history. (#47)
+- Database-backed `order_typed_eav` for scalar fields, with explicit NULL
+  placement and stable primary-key tie-breaking. Caller host filters and
+  partition-definition precedence are preserved without Value hydration. (#44)
+- Field-selective bulk reads with `typed_eav_hash_for(records, fields: names)`.
+  Selected winning field IDs narrow value loading before hydration; omitted
+  `fields:` preserves all-fields reads. Empty, duplicate, unknown, and
+  partition-specific names have explicit projection semantics. (#45)
+
+### Compatibility and usage notes
+
+- Typed sorting and summaries select one effective field definition. Scope
+  arguments do not authorize or filter host records: retain tenant and access
+  filters on the caller's Active Record relation. All-partitions mode and
+  unsupported collection/multi-cell operations fail explicitly.
+- Distinct lists and grouped counts default to 100 values (maximum 1,000),
+  ordered by value rather than frequency. Exact distinct counts include the
+  explicit NULL category; missing rows are omitted. Numeric min/max/sum retain
+  Integer/BigDecimal types and do not aggregate reference IDs or currencies.
+- Preloaded reads are explicit in-memory value snapshots with a current
+  definition lookup; database reads remain the default. Dirty/saved changes
+  describe host-associated editing and save state, not durable audit history
+  or independently executed bulk SQL writes.
+- Schema previews are advisory, exact-partition comparisons. They neither
+  apply changes nor reserve the schema or guarantee a later import's success.
+- Local verification: 1,404 examples, 0 failures; 160 Ruby files lint-clean.
+  The release workflow additionally verifies the supported compatibility
+  matrix and the exact packaged artifact before publication.
+
 ## [0.7.1] - 2026-09-04
 
 A focused patch release for inherited Active Record hosts and multi-partition
@@ -609,7 +670,8 @@ worked examples.
 
 Initial release.
 
-[Unreleased]: https://github.com/dchuk/typed_eav/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/dchuk/typed_eav/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.8.0
 [0.7.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.7.1
 [0.7.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.6.0

data/README.md

@@ -197,6 +197,78 @@ Contact.where(company_id: 42)
        .limit(25)
 ```
 
+### Sorting by a typed field
+
+```ruby
+Contact.where(tenant_id: "t1")
+       .order_typed_eav("age", direction: :desc, nulls: :last, scope: "t1")
+       .limit(25)
+```
+
+`order_typed_eav` returns an Active Record relation and orders in PostgreSQL,
+without loading typed values into Ruby. It replaces prior ordering while
+preserving host filters, STI restrictions, limits, and offsets. `direction:`
+accepts `:asc` (default) or `:desc`; `nulls:` accepts `:first` or `:last`
+(default in either direction). Missing rows and explicit NULLs share that
+placement. Equal values use the host primary key ascending as a stable tie-break.
+
+Scope arguments (or the ambient scope) select the winning field definition;
+**they do not filter host records by tenant**. Keep authorization/tenant filters
+on the caller relation. All-partitions `TypedEAV.unscoped` is rejected for this
+API: choose one effective definition instead. Single native scalar cells are
+supported, using their stored values (for example, reference IDs and attachment
+signed IDs, not display labels). JSON/array and multi-cell fields such as
+Currency are rejected rather than assigned an implicit ordering.
+
+### Distinct values and grouped counts
+
+```ruby
+contacts = Contact.where(tenant_id: "t1")
+contacts.distinct_typed_eav_values("status", scope: "t1", limit: 100)
+# => ["active", "paused", nil]
+contacts.typed_eav_value_counts("status", scope: "t1", limit: 100)
+# => {"active" => 24, "paused" => 3, nil => 2}
+contacts.count_distinct_typed_eav_values("status", scope: "t1")
+# => 3
+```
+
+These scalar queries run in SQL without hydrating hosts or Values. Results
+use native ascending value order, with explicit NULL (`nil`) last. Missing
+value rows contribute nothing; `false` and empty strings remain real values.
+Grouped counts count host identities, not duplicate rows introduced by joins.
+The caller's filters, STI restrictions, distinctness, and pagination determine
+the host set before summarization. Scope arguments choose field-definition
+visibility, not host authorization, just as with typed sorting.
+
+Lists and grouped-count hashes default to 100 values and accept a positive
+Integer `limit:` up to 1,000. They are truncated in value order, not ranked by
+frequency. Compare their length with `count_distinct_typed_eav_values` to
+detect truncation; that exact SQL count includes one NULL category and returns
+only an Integer, regardless of cardinality. It still requires database work
+over the matching set. Collection/multi-cell fields and all-partitions mode
+are unsupported, matching scalar sorting.
+
+### Numeric aggregates
+
+```ruby
+Contact.where(tenant_id: "t1").aggregate_typed_eav(
+  "score", operation: :sum, scope: "t1"
+)
+```
+
+`aggregate_typed_eav` requires `operation: :min`, `:max`, or `:sum` and returns
+one SQL-calculated scalar over the caller's host set. Integer fields return
+Integers; Decimal and Percentage fields preserve `BigDecimal` precision, with
+no Float conversion. Percentage values remain stored fractions, not formatted
+percent strings. Missing rows and explicit NULLs are ignored. With no non-NULL
+values, min/max return `nil` and sum returns the field's typed zero.
+
+The same host filtering, partition visibility, STI, and pagination rules as
+distinct queries apply. Only Integer/Decimal families (including Percentage)
+with a single numeric cell are supported. Reference IDs, text, collections,
+and multi-cell Currency are rejected; the gem does not silently sum identifiers
+or combine currencies. No values or host records are loaded to compute the result.
+
 ### Available Operators
 
 | Operator | Works On | Description |
@@ -1082,6 +1154,55 @@ Production code rarely calls either — they exist for test isolation and
 for the rare case where a host app wants to fully unwire the gem in a
 specific request lifecycle.
 
+## In-memory typed-value changes
+
+```ruby
+contact.set_typed_eav_value("age", 41)
+contact.typed_eav_changes # => {"age" => [40, 41]}
+contact.save!
+contact.typed_eav_changes # => {}
+```
+
+`typed_eav_changes` reports logical `[before, after]` pairs for pending changes
+on this host's in-memory `typed_values` target. It covers named setters,
+`typed_eav_attributes=`, nested `typed_values_attributes=`, association builds,
+edits to target Values, and `mark_for_destruction`/nested `_destroy`. Multi-cell
+fields such as Currency retain their logical shape; returned hashes, pairs,
+and mutable values are copies. Same-value assignments, reversions, and logical
+`nil`-to-`nil` changes are omitted, including creating/removing a NULL value row.
+Invalid input reports the cast logical result without discarding validation errors.
+
+Failed saves retain pending state; successful saves and reload clear it. An
+outer rollback follows Active Record's restored child dirty state. The API
+resolves effective field names using this record's partition precedence, and
+does not load all persisted Values merely to inspect an untouched host.
+
+After saving, `saved_typed_eav_changes` exposes the most recent successful
+host save's logical pairs:
+
+```ruby
+contact.set_typed_eav_value("age", 42)
+contact.save!
+contact.saved_typed_eav_changes # => {"age" => [41, 42]}
+contact.typed_eav_changes       # => {}
+```
+
+Saved changes are available in normal host `after_save` callbacks, including
+values assigned by `before_save`. Each successful save replaces the snapshot;
+a no-op save replaces it with `{}`. Failed validation or a save-callback
+exception preserves the previous successful snapshot. Reload and an outer
+transaction rollback clear saved changes. These are successful-save semantics,
+not proof of a durable commit: use `after_commit` when external effects must
+wait for commit. Exceptions after a transaction has already committed cannot
+undo persisted data. Neither dirty API requires versioning or adds audit rows.
+
+This is in-memory editing state, not audit history. Independently loaded/saved
+Values, reassignment of an existing Value's field identity, SQL/`delete_all`,
+and collection operations that immediately remove rows from the host target
+are not tracked. Use nested destruction or `mark_for_destruction` for tracked
+removal. Reduced `BulkUpsert` does not update unrelated in-memory host objects;
+reload them after external writes. Bulk reads do not create dirty state.
+
 ## Versioning
 
 `typed_eav` ships an opt-in append-only audit log for changes to typed
@@ -1367,9 +1488,50 @@ The gem creates five tables:
   create, update, and destroy events; it retains durable entity identity even
   when the live Value row is later removed
 
+## Read-only schema previews
+
+```ruby
+schema = TypedEAV::SchemaPortability.export_schema(
+  entity_type: "Contact", scope: "t1"
+)
+schema["fields"].first["required"] = true
+preview = TypedEAV::SchemaPortability.preview_schema(schema, on_conflict: :overwrite)
+preview["fields"].first["changes"]
+# => {"required" => {"from" => false, "to" => true}}
+preview["risks"] # => ["required_false_to_true"]
+```
+
+The preview compares a version-1 portable export with the database's exact
+target partition. It requires the envelope's `entity_type`, `scope`, and
+`parent_scope` to match every entry; mixed-target payloads and duplicate
+identities are rejected. This intentionally stricter preview input does not
+change `import_schema` or silently retarget definitions.
+
+The plain Hash result contains envelope metadata, `summary`, `fields`,
+`sections`, `risks`, and `importable`. Each entry includes its exact `identity`,
+`status` (`unchanged`, `added`, `changed`, or `conflict`), conditional `action`,
+and attribute `changes` with `from`/`to` values. Field entries also contain
+option-row `added`, `removed`, and `changed` lists, matched by option value.
+Raw option ordering and key-presence differences remain visible because the
+importer compares the complete exported payload, not just equivalent settings.
+
+`on_conflict: :error` blocks divergent definitions; `:skip` leaves them alone;
+`:overwrite` predicts an update. Type swaps always produce an error action,
+even under skip/overwrite. Risks flag type changes, removed options, newly
+required fields, and changes to options, defaults, or field dependencies.
+Omitted target definitions are **not deletions** and are not listed as such.
+
+`importable: true` means no known conflict-policy/type-swap blocker was found,
+not that validation or a later import is guaranteed to succeed. Actions are
+conditional predictions: a blocking error aborts the existing transactional
+import, including otherwise acceptable additions. Previewing does not save
+definitions, run mutation/validation callbacks, enqueue jobs, execute DDL, or
+convert values. It is an advisory snapshot, not a lock or reservation; model
+validations and concurrent changes still apply to the actual import.
+
 ## Architecture
 
-Internal module layout as of 0.7.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 through ADR-0013.
+Current internal module layout. 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 through ADR-0013.
 
 ### Macro entry: `HasTypedEav`
 
@@ -1410,6 +1572,11 @@ TypedEAV::QueryBuilder                ← low altitude: per-field SQL primitive
 
 `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`.
 
+Scalar ordering and summaries are a separate `EntityQuery` delegation to
+`ScalarQuery`: it resolves one winning definition, checks scalar support, and
+builds SQL over the field's declared native column. It does not add operators
+to the filter DSL or load the host/Value graph to calculate summaries.
+
 ### 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:
@@ -1432,6 +1599,44 @@ measure their own scope cardinality, selected fields, hydration, and contention.
 
 Single-record reads (`typed_eav_value`, `typed_eav_hash`) live on `InstanceMethods` and use the same partition helpers but without batching.
 
+Use `fields:` to load only the values needed by a view or export:
+
+```ruby
+Contact.typed_eav_hash_for(contacts, fields: [:name, :score])
+# => {123 => {"name" => "Ada", "score" => 42}, ...}
+```
+
+Omitting `fields:` (or passing `nil`) retains the all-fields behavior. A single
+String/Symbol or an enumerable of names is accepted; duplicates are removed.
+Unknown names and names unavailable in an individual record's partition are
+omitted, as are missing value rows. An explicitly stored NULL remains `nil`.
+`fields: []` returns an empty inner hash for each record without definition or
+value queries (the supplied collection itself may still need loading). Selected
+winning field IDs constrain the value query before hydration, so unrequested
+values and their field readers are not loaded or evaluated. Definition lookup
+remains batched across the records' partitions.
+
+To explicitly reuse already-loaded values:
+
+```ruby
+contacts = Contact.where(tenant_id: "t1").includes(typed_values: :field).to_a
+Contact.typed_eav_hash_for(contacts, fields: [:name], source: :preloaded)
+```
+
+The default `source: :database` still fetches persisted values afresh, even
+when associations are loaded or edited in memory. `:preloaded` uses the caller's
+association targets, including unsaved Value builds/assignments, without saving
+or mutating them. It performs one fresh batched definition query to choose
+current winners, but no Value or field-association preload queries. This is a
+value snapshot, not a guarantee of current database contents or frozen schema.
+
+Every host's `typed_values` association must be loaded, as must each retained
+Value's `field` association; incomplete preloads raise `ArgumentError` instead
+of silently issuing N+1 queries. With `fields:`, unselected Values need no field
+preload. With all fields selected, all field associations must be loaded
+(including loaded `nil` for orphans). `fields: []` needs neither associations
+nor definition/value queries. Only `:database` and `:preloaded` are valid sources.
+
 ### Bulk writes: `BulkWrite`
 
 `bulk_set_typed_eav_values(records, attrs)` routes through `TypedEAV::BulkWrite`,

data/lib/typed_eav/bulk_read.rb

@@ -6,23 +6,42 @@ module TypedEAV
   # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
   # record count or field count.
   #
-  # ## Pipeline (one batched definition query + one bulk value preload)
+  # `fields:` is an optional projection of field names. A nil selection keeps
+  # the all-fields behavior; a non-nil selection is normalized to unique
+  # strings, and only the selected winning definitions' values are loaded.
+  # Unknown names are ignored, as are names that are not defined for a
+  # particular record's partition tuple. An empty selection returns one empty
+  # inner hash per record without querying definitions or values.
+  #
+  # `source: :database` (the default) always reads a fresh Value graph. The
+  # explicit `source: :preloaded` mode projects only the already-loaded
+  # `typed_values` targets and their loaded `field` associations; it never
+  # falls back to an association query. Incomplete preload requirements raise
+  # `ArgumentError` before projection. The preloaded mode is therefore a
+  # snapshot of caller-owned in-memory records and can include unsaved Value
+  # assignments; it never saves or mutates those records.
+  #
+  # ## Pipeline
   #
   #   1. validate_records!    — nil -> ArgumentError; single-class invariant
   #   2. group_by_tuple       — `[typed_eav_scope, typed_eav_parent_scope]`
   #   3. winning_ids_by_tuple — one `Partition::DefinitionBatch` query, then
   #                             extract the winning field ids per tuple
-  #   4. preload_values       — single SELECT across ALL records
+  #   4. load_values          — fresh `:database` SELECT across ALL records,
+  #                             restricted to selected field IDs when
+  #                             `fields:` is used; or `:preloaded` association
+  #                             targets after a strict loaded-state check
   #   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 for the union of requested partitions
-  #
-  # Total: 3 queries — independent of record count and partition cardinality.
+  # Database mode performs up to three SELECTs — one bulk Value query, one
+  # field-association query for those values, and one definition query for the
+  # union of requested partitions. The preloaded mode performs one fresh
+  # definition SELECT and reads Value/field association targets in memory;
+  # `fields: []` bypasses even that definition query. Both bounds are
+  # independent of record count and partition cardinality.
   #
   # ## Single-class invariant
   #
@@ -31,34 +50,75 @@ module TypedEAV
   # class. Mixed, unrelated input would still be invalid; STI subclasses pass
   # via `records.all?(host_class)`.
   class BulkRead
-    def initialize(host_class:, records:)
+    def initialize(host_class:, records:, fields: nil, source: :database)
       @host_class = host_class
       @records    = records
+      @fields     = fields
+      @source     = source
     end
 
     def to_hash
+      validate_source!
+
       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)
+      selected_names = normalize_fields
+      return empty_results(records) if selected_names == []
 
-      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+      tuples_by_record = group_by_tuple(records)
+      winning_ids_by_tuple = winning_ids_by_tuple(tuples_by_record.values.uniq, selected_names)
+      values_by_record_id = if @source == :preloaded
+                              preloaded_values(records, tuples_by_record, winning_ids_by_tuple, selected_names)
+                            else
+                              preload_values(records, winning_ids_by_tuple, selected_names)
+                            end
+
+      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id, selected_names)
     end
 
     private
 
     attr_reader :host_class
 
+    def validate_source!
+      return if %i[database preloaded].include?(@source)
+
+      raise ArgumentError, "typed_eav_hash_for source must be :database or :preloaded"
+    end
+
+    def normalize_fields
+      return nil if @fields.nil?
+
+      names = if @fields.is_a?(String) || @fields.is_a?(Symbol)
+                [@fields]
+              elsif @fields.respond_to?(:to_a)
+                @fields.to_a
+              else
+                raise ArgumentError, "typed_eav_hash_for fields must be an Enumerable of String/Symbol names"
+              end
+
+      names.map do |name|
+        next name if name.is_a?(String)
+        next name.to_s if name.is_a?(Symbol)
+
+        raise ArgumentError,
+              "typed_eav_hash_for fields must contain only String or Symbol names; got #{name.inspect}"
+      end.uniq
+    end
+
     def coerce_records
       raise ArgumentError, "typed_eav_hash_for requires an Enumerable of records, got nil" if @records.nil?
 
       @records.to_a
     end
 
+    def empty_results(records)
+      records.to_h { |record| [record.id, {}] }
+    end
+
     def validate_record_classes!(records)
       return if records.all?(host_class)
 
@@ -73,26 +133,82 @@ module TypedEAV
       records.index_with { |r| [r.typed_eav_scope, r.typed_eav_parent_scope] }
     end
 
-    def winning_ids_by_tuple(tuples)
+    def winning_ids_by_tuple(tuples, selected_names)
       TypedEAV::Partition::DefinitionBatch
         .resolve(entity_type: host_class.polymorphic_name, tuples: tuples)
-        .transform_values { |fields_by_name| fields_by_name.transform_values(&:id) }
+        .transform_values do |fields_by_name|
+          fields_by_name.each_with_object({}) do |(name, field), winners|
+            next if selected_names&.exclude?(name)
+
+            winners[name] = field.id
+          end
+        end
     end
 
-    def preload_values(records)
-      rows = TypedEAV::Value
-             .includes(:field)
-             .where(entity_type: host_class.polymorphic_name, entity_id: records.map(&:id))
-             .to_a
+    def preload_values(records, winning_ids_by_tuple, selected_names)
+      relation = TypedEAV::Value
+                 .includes(:field)
+                 .where(entity_type: host_class.polymorphic_name, entity_id: records.map(&:id))
+
+      if selected_names
+        field_ids = winning_ids_by_tuple.values.flat_map(&:values).uniq
+        return {} if field_ids.empty?
+
+        relation = relation.where(field_id: field_ids)
+      end
+
+      rows = relation.to_a
       rows.group_by(&:entity_id)
     end
 
-    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+    # Reuse a caller's fully-preloaded association graph without allowing an
+    # accidental association reader to issue an N+1 query. `target` is used
+    # deliberately: unlike `record.typed_values`, it never loads an unloaded
+    # association. For a selected projection, filter each target by the
+    # winning field IDs before checking field associations; unselected Values
+    # therefore need not have their `field` association loaded. The all-fields
+    # path retains the stricter check over every Value, including orphan rows
+    # whose loaded field target is nil.
+    def preloaded_values(records, tuples_by_record, winning_ids_by_tuple, selected_names)
+      unloaded_records = records.reject { |record| record.association(:typed_values).loaded? }
+      if unloaded_records.any?
+        raise ArgumentError,
+              "typed_eav_hash_for source: :preloaded requires the typed_values association " \
+              "to be preloaded for every record"
+      end
+
+      records.to_h do |record|
+        values = record.association(:typed_values).target
+        if selected_names
+          tuple = tuples_by_record.fetch(record)
+          selected_ids = winning_ids_by_tuple.fetch(tuple, {}).values
+          values = values.select { |value| selected_ids.include?(effective_field_id(value)) }
+        end
+
+        unloaded_values = values.reject { |value| value.association(:field).loaded? }
+        if unloaded_values.any?
+          raise ArgumentError,
+                "typed_eav_hash_for source: :preloaded requires the field association " \
+                "to be preloaded for every typed value"
+        end
+
+        [record.id, values]
+      end
+    end
+
+    def effective_field_id(value)
+      return value.field_id if value.field_id
+
+      association = value.association(:field)
+      association.loaded? ? association.target&.id : nil
+    end
+
+    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id, selected_names)
       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)
+        result[record.id]    = inner_hash_for(rows, winning_ids_by_name, selected_names)
       end
     end
 
@@ -103,12 +219,17 @@ module TypedEAV
     # 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)
+    def inner_hash_for(value_rows, winning_ids_by_name, selected_names)
       value_rows.each_with_object({}) do |tv, inner|
         next unless tv.field
 
         name = tv.field.name
         winning_id = winning_ids_by_name[name]
+        # A selected field ID may be visible for another record's partition
+        # tuple because the value preload spans all requested records. In a
+        # projection, a name without a winner for this tuple is absent rather
+        # than eligible for the all-fields stale-row fallback below.
+        next if selected_names && !winning_id
         next assign_with_precedence(inner, name, tv, winning_id) if winning_id
 
         inner[name] = tv.value unless inner.key?(name)