typed_eav 0.7.1 → 0.8.1

data/docs/index.md

@@ -0,0 +1,44 @@
+---
+title: "Documentation"
+nav_group: Start here
+---
+
+# TypedEAV documentation
+
+Add runtime-defined custom fields to Active Record models using native PostgreSQL
+columns for scalar values and JSONB for collections. Define fields globally or
+per tenant, validate input, and query values through Active Record relations.
+
+## Start here
+
+1. [Install and try TypedEAV](getting-started.md).
+2. [Define fields, assign values, and build forms](guides/usage.md).
+3. [Configure tenant scoping](guides/scoping.md) if your application has tenants.
+4. [Filter, sort, and summarize values](guides/queries.md).
+
+## Guides
+
+| Task | Guide |
+|---|---|
+| Choose field types and create custom types | [Fields and validation](guides/fields.md) |
+| Build forms, manage fields, and inspect pending changes | [Reading, writing, and forms](guides/usage.md) |
+| Configure tenants and inspect effective definitions | [Scoping and partitions](guides/scoping.md) |
+| Search and summarize custom values | [Queries](guides/queries.md) |
+| Read and update many records | [Bulk operations](guides/bulk-operations.md) |
+| Map CSV rows to custom fields | [CSV mapping](guides/csv-import.md) |
+| Move field definitions between environments | [Schema portability](guides/schema.md) |
+| React to changes and keep audit history | [Events and versioning](guides/events-and-versioning.md) |
+| Evaluate indexes and performance tradeoffs | [Storage and performance](guides/performance.md) |
+| Upgrade an existing installation | [Upgrading](guides/upgrading.md) |
+
+## Reference and development
+
+- [Public API and configuration](reference/index.md)
+- [Architecture](guides/architecture.md) and [design decisions](adr/index.md)
+- [Development and test isolation](guides/development.md)
+- [Maintaining and publishing these docs](maintaining.md)
+- [Changelog](changelog.md)
+- [Source and issues](https://github.com/dchuk/typed_eav)
+
+These pages describe the code on the default branch. Check the changelog and
+release tag when using an older gem version.

data/docs/maintaining.md

@@ -0,0 +1,82 @@
+---
+title: "Maintainers"
+---
+
+# Maintaining and publishing the documentation
+
+## Update docs with the API
+
+Review documentation after every repository change, including code, tests, dependencies,
+configuration, tooling, CI, migrations, and releases. Update affected pages in
+the same change; if reader-facing behavior is unchanged, explain why no docs
+update was needed in the handoff. Record user-visible changes in the root
+`CHANGELOG.md` under Unreleased. A public API change includes its documentation
+in the same change. Keep the
+README focused on installation and discovery; maintain detailed usage here.
+
+For each public capability, document a practical example, accepted inputs and
+defaults, return value, and relevant failure behavior. Link its API reference to
+its guide. Check claims against implementation and specs, especially transaction,
+NULL, tenant, and callback behavior. A method being mentioned is not sufficient
+coverage if users cannot work out how to call it.
+
+Add new pages to the [documentation home](index.md) or the
+[reference index](reference/index.md). Keep Markdown links relative between
+published pages; `jekyll-relative-links` converts them to site URLs. Link to
+GitHub for files outside `docs/`. Give new pages YAML front matter with a title
+so Jekyll renders them. The sidebar automatically lists pages by `nav_group`
+(assigned by folder defaults in `_config.yml`, or overridden in front matter).
+Use `nav_exclude: true` for supporting pages that should be reachable only through
+a summary page. Individual ADRs use this setting; their user-facing summary
+appears once under Project. The active page is highlighted; mobile navigation uses an expandable menu.
+
+The [changelog](changelog.md) is generated at build time from the root
+`CHANGELOG.md` by `_plugins/changelog.rb`. Edit that source file only and rebuild
+to preview changes. The workflow also runs when that file changes. Use ordinary Markdown headings and fenced examples.
+
+## Preview locally
+
+The documentation dependencies are isolated from the gem's development bundle.
+From the gem repository:
+
+```sh
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+Open `http://localhost:4000/typed_eav/`. The default layout uses the Minima theme;
+there is no separate frontend application to maintain.
+
+To build and check links from the repository root:
+
+```sh
+BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build --source docs --destination docs/_site
+python3 script/check_docs_site.py docs/_site /typed_eav
+```
+
+The checker verifies local page/asset targets and heading anchors in generated
+HTML. It does not make network requests or certify the accuracy of examples.
+Review examples against the relevant gem specs as part of each change.
+
+## Publish on GitHub Pages
+
+The repository includes `.github/workflows/docs.yml`. Pull requests build and
+check the site; pushes to `main` and manual runs on `main` also deploy it.
+
+1. Commit and push the documentation and workflow to the gem repository.
+2. In the repository's **Settings → Pages**, set **Source** to **GitHub Actions**.
+3. Run the **Documentation** workflow on `main`, or push a documentation change.
+4. Check the deployment URL in the workflow's `github-pages` environment.
+
+The configured project URL is `https://dchuk.github.io/typed_eav/`. It becomes
+available after the first successful deployment. For a different repository or
+custom domain, update `url` and `baseurl` in `_config.yml` and the link-check
+prefix in the workflow.
+
+The site includes guides, references, and ADRs. Internal goal plans and
+`improvement-program.md` are excluded, as are dependency and build files. Build
+output is ignored by Git; GitHub Actions uploads the generated site directly.
+
+See GitHub's [custom Pages workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
+for repository permissions and deployment settings.

data/docs/reference/api.md

@@ -0,0 +1,133 @@
+---
+title: "Public API reference"
+---
+
+# Public API reference
+
+This is an index of application-facing entry points. Linked guides explain
+examples, supported types, validation, and transaction boundaries. Internal
+query builders, dispatchers, caches, and callback methods are not extension APIs.
+
+## Host models and records
+
+Declare `has_typed_eav(scope_method: nil, parent_scope_method: nil, types: nil,
+versioned: false)` on an Active Record model. Scope methods name record accessors;
+`parent_scope_method` requires `scope_method`. `types: nil` allows registered
+types; an array restricts them. Versioning additionally requires the global
+boot-time switch. Use the host's `polymorphic_name` for `entity_type`.
+
+| Record method | Contract |
+| --- | --- |
+| `typed_values` | Active Record association; normal saves validate and persist values with the host. |
+| `typed_eav_definitions` | Visible definitions for this record's partition, including same-name candidates. |
+| `typed_eav_scope`, `typed_eav_parent_scope` | Configured accessor values normalized to strings, or `nil`. |
+| `initialize_typed_values` | Build missing effective fields with defaults in memory; returns `typed_values`. Save separately. |
+| `typed_eav_value(name)` | Logical Ruby value, or `nil` when absent. |
+| `set_typed_eav_value(name, value)` | Stage a value by effective field name; unknown names are ignored. Save separately. |
+| `typed_eav_hash` | Hash of field names to logical values. |
+| `typed_eav_attributes=` / `typed_eav=` | Named entries such as `[{name: "age", value: 30}]`; supports `_destroy`. |
+| `typed_values_attributes=` | Rails nested attributes using `field_id`, optional Value `id`, `value`, and `_destroy`. |
+| `typed_eav_changes` | Pending logical changes as `{name => [before, after]}`. |
+| `saved_typed_eav_changes` | Logical changes from the latest successful host save; reload/rollback clears them. |
+
+See [reading, writing, and forms](../guides/usage.md),
+[defaults](../guides/usage.md#defaults-for-new-and-existing-records), and [scoping](../guides/scoping.md).
+
+## Host queries
+
+These methods are available on the host class and through Active Record relations.
+The query methods below (including `typed_eav_definitions`) accept `scope:` and
+`parent_scope:`. Omitted keywords use ambient resolution; explicit `nil` selects
+the global axis. These select **field definitions**, not authorized host rows:
+start with an appropriately filtered host relation.
+
+| Method | Result and defaults |
+| --- | --- |
+| `where_typed_eav(*filters, include_missing: false)` | Active Record relation; filters use `name`, `op` (default `:eq`), and `value`. |
+| `with_field(name, operator_or_value = nil, value = nil, include_missing: false)` | Single-filter relation; two-argument non-Symbol value implies equality. |
+| `order_typed_eav(name, direction: :asc, nulls: :last)` | Relation ordered by a supported scalar field, then host primary key. Replaces prior ordering. |
+| `distinct_typed_eav_values(name, limit: 100)` | Array of distinct scalar values in database order. |
+| `count_distinct_typed_eav_values(name)` | Integer distinct count, including an explicit NULL category. |
+| `typed_eav_value_counts(name, limit: 100)` | Hash of scalar values to counts. |
+| `aggregate_typed_eav(name, operation:)` | `:min`, `:max`, or `:sum` for Integer/Decimal/Percentage; typed number or `nil` for empty min/max. |
+| `typed_eav_definitions` | Relation of visible field definitions; does not collapse names. |
+
+Missing rows differ from explicit NULL rows. `include_missing: true` broadens
+`:is_null` and is ignored by other operators. Scalar APIs reject unsupported
+field families and all-partition ambiguity with `ArgumentError`. See
+[queries](../guides/queries.md) for operators, NULL behavior, limits, and errors.
+
+## Bulk operations
+
+| Host class method | Result and defaults |
+| --- | --- |
+| `typed_eav_hash_for(records, fields: nil, source: :database)` | `{record.id => {field_name => value}}`; optional selected field names; `source: :preloaded` reads loaded associations. |
+| `bulk_set_typed_eav_values(records, values_by_field_name, version_grouping: :default, transaction: :all, chunk_size: nil)` | Normal host saves; returns `{successes: [...], errors_by_record: {record => errors_hash}}`. |
+| `bulk_set_typed_eav_values_per_record(values_by_record, version_grouping: :default, transaction: :all, chunk_size: nil)` | Same result, with `{record => {field_name => value}}` input. |
+| `bulk_upsert_typed_eav_values(records, values_by_field_name, acknowledge_reduced_semantics: false, transaction: :all, chunk_size: nil)` | Written row count; requires explicit acknowledgement, skips persistence callbacks and audit versions. |
+
+Normal bulk writes collect validation failures per record; an unexpected exception
+can roll back the active transaction. `transaction: :chunks` requires a positive
+`chunk_size`; prior chunks remain committed on later failure. See
+[bulk operations](../guides/bulk-operations.md) before choosing either write path.
+
+## Field definitions and values
+
+Use `TypedEAV::Field::<Type>.create!` and ordinary Active Record updates for field
+metadata; `field_options` holds Select/MultiSelect choices. The
+[fields guide](../guides/fields.md) covers every built-in type and its options.
+
+| API | Purpose |
+| --- | --- |
+| `field.default_value` / `default_value=` | Read/set the logical default. Explicit value assignment can override it with `nil`. |
+| `field.backfill_default!(relation: nil)` | Synchronously apply a configured default to eligible existing hosts in batches; no count/result contract. |
+| `field.destroy!` | Apply the field's `field_dependent` policy. |
+| `field.destroy_with_values_in_batches!(batch_size: 1_000)` | Resumable deletion for persisted `field_dependent: :destroy` fields; requires no open transaction. |
+| `field.move_higher`, `move_lower`, `move_to_top`, `move_to_bottom`, `insert_at(position)` | Reorder within the field's partition. |
+| `field.field_type_name`, `display_name`, `array_field?`, `optionable?`, `allowed_option_values` | Metadata for rendering and field-management interfaces. |
+| `field.cast(raw)` | Custom-type protocol returning `[cast_value, invalid]`; casting alone does not establish validity. |
+| `value.value` / `value=` | Read/write the field's logical value, including multi-cell types. |
+| `value.history` | Versions ordered newest first by timestamp and ID. |
+| `value.revert_to(version)` | Save the version's **before** state and write a new version; rejects another Value's version, create versions, and destroyed source Values. |
+
+See [default initialization and backfill](../guides/usage.md#defaults-for-new-and-existing-records),
+[field deletion](../guides/events-and-versioning.md#public-callback-slots), and
+[custom types](../guides/fields.md#custom-field-types) for their contracts. Full history after Value deletion requires querying
+`TypedEAV::ValueVersion` by entity and field identity; see
+[events and versioning](../guides/events-and-versioning.md).
+
+## Schema and CSV
+
+| API | Result |
+| --- | --- |
+| `TypedEAV::SchemaPortability.export_schema(entity_type:, scope: nil, parent_scope: nil)` | String-keyed versioned schema Hash for an exact partition, including fields and sections; excludes values. |
+| `TypedEAV::SchemaPortability.preview_schema(hash, on_conflict: :error)` | Read-only JSON-safe comparison and predicted actions; advisory, not a reservation or validation guarantee. |
+| `TypedEAV::SchemaPortability.import_schema(hash, on_conflict: :error)` | Counts under `"created"`, `"updated"`, `"skipped"`, `"unchanged"`, plus `"errors"`; import runs in a transaction and failures can raise. |
+| `TypedEAV::SchemaPortability.export_snapshot_schema(entity_type:, scope: nil, parent_scope: nil)` | Lean versioned field projection; not a full import payload or a value backup. |
+| `TypedEAV::CSVMapper.row_to_attributes(row, mapping, fields_by_name: nil)` | Result with frozen `attributes`/`errors` Hashes and `success?`/`failure?`. Does not save records. |
+
+`Field::Base.export_schema` and `.import_schema` remain compatible delegators.
+Conflict policies are `:error`, `:skip`, and `:overwrite`; type swaps are refused.
+CSV mapping uses uniformly String header keys or Integer index keys, with field
+names as values. Typed mode casts via supplied definitions, reports cast errors,
+and skips unknown fields. Normal model validation must still run.
+See [schema portability](../guides/schema.md) and [CSV imports](../guides/csv-import.md).
+
+## Partition helpers
+
+`TypedEAV::Partition` expects explicitly resolved scope values; it does not consult
+ambient scope. Visibility methods accept `scope: nil`, `parent_scope: nil`, and
+`mode: :partition`. Use `mode: :all_partitions` only for an authorized admin bypass.
+Invalid modes and orphan parent scopes raise `ArgumentError` in partition mode.
+
+| Method | Result |
+| --- | --- |
+| `visible_fields(entity_type: nil, ...)` | Field relation, including global, scope-only, and full-tuple candidates. |
+| `effective_fields_by_name(entity_type:, ...)` | `{name => field}` with most-specific precedence; all-partitions mode instead returns `{name => [fields]}`. |
+| `definitions_by_name(defs)` | Collapse supplied definitions by name, most-specific winning. Supply only the intended visible set. |
+| `definitions_multimap_by_name(defs)` | Group supplied definitions as `{name => [fields]}` without collapsing. |
+| `visible_sections(entity_type:, ...)` | Relation of sections visible to the tuple. |
+| `find_visible_section!(id, entity_type:, ...)` | Visible Section, or `ActiveRecord::RecordNotFound`. |
+
+These helpers constrain definition visibility; application authorization still
+belongs to the caller. See [scoping](../guides/scoping.md).

data/docs/reference/configuration.md

@@ -0,0 +1,64 @@
+---
+title: "Configuration reference"
+---
+
+# Configuration reference
+
+Configure the gem in a Rails initializer:
+
+```ruby
+TypedEAV.configure do |config|
+  config.scope_resolver = -> { [Current.account&.id, Current.workspace&.id] }
+  config.require_scope = true
+end
+```
+
+The example assumes those are the same partition identifiers returned by the
+host's declared accessors. `TypedEAV.config` returns the configuration object;
+`configure` also accepts a block.
+
+| Setting | Default | Contract |
+| --- | --- | --- |
+| `scope_resolver` | Auto-detect `ActsAsTenant` | Callable returning `nil` or exactly `[scope, parent_scope]`. Default returns `[ActsAsTenant.current_tenant, nil]` when available, otherwise `nil`. Bare scalars raise `ArgumentError`. |
+| `require_scope` | `true` | Scoped host class queries raise `TypedEAV::ScopeRequired` when scope cannot be resolved. |
+| `versioning` | `false` | Boot-time master switch for transactional audit callbacks; host must also declare `versioned: true`. |
+| `actor_resolver` | `nil` | Optional callable supplying audit actor identity. Missing actor is allowed; applications can enforce stricter requirements in the resolver. |
+| `on_value_change` | `nil` | `->(value, change_type, context) { ... }`; after commit, with `:create`, `:update`, or `:destroy`. |
+| `on_field_change` | `nil` | `->(field, change_type) { ... }`; after commit, with `:create`, `:update`, `:destroy`, or `:rename`. |
+| `on_image_attached` | `nil` | `->(value, blob) { ... }`; image attachment notification after commit, when Active Storage is available. |
+
+Public callback errors are logged rather than propagated to the completed save.
+Versioning is independent of the public callback slots. Configure the versioning
+switch before the engine installs callbacks, not dynamically per request.
+See [events and versioning](../guides/events-and-versioning.md) for ordering,
+actor normalization, payloads, and audit transaction guarantees.
+
+## Field type registration
+
+```ruby
+TypedEAV.configure do |config|
+  config.register_field_type :phone, "MyApp::Fields::Phone"
+end
+```
+
+`config.field_types` maps type-name Symbols to class-name Strings;
+`config.type_names` lists registered names; `config.field_class_for(:phone)`
+constantizes a registered class and raises `ArgumentError` for an unknown type.
+Use registration to extend built-ins and the host macro's `types:` option to
+restrict a model. See [custom field types](../guides/fields.md).
+
+## Block-scoped state
+
+| API | Contract |
+| --- | --- |
+| `TypedEAV.with_scope(value) { ... }` | Temporary ambient scope; accepts a scalar, `[scope, parent_scope]`, or `nil`. Nested blocks restore prior state. |
+| `TypedEAV.current_scope` | Resolved normalized tuple, or `nil`; consults the block stack before the resolver. |
+| `TypedEAV.unscoped { ... }` | Explicit all-partition query mode; differs from `scope: nil` (global definitions only). |
+| `TypedEAV.unscoped?` | Whether that bypass is active. |
+| `TypedEAV.with_context(**kwargs) { ... }` | Temporary merged context for value events and versions; nested blocks restore prior state. |
+| `TypedEAV.current_context` | Frozen current context Hash, empty when unset. |
+
+Scope resolution is for field definitions. Continue to filter and authorize host
+records in the application. Scalar sorting and summaries reject all-partition
+mode because same-name definitions are ambiguous. See
+[scoping](../guides/scoping.md) and [queries](../guides/queries.md).

data/docs/reference/index.md

@@ -0,0 +1,16 @@
+---
+title: "Reference"
+---
+
+# Reference
+
+Use these pages to locate a method, check a default, or find its detailed guide.
+
+- [Public API](api.md): host records, queries, bulk operations, fields, schema/CSV, and partition helpers.
+- [Configuration](configuration.md): initializer settings, type registration, scope blocks, and event context.
+
+For an introduction, start with the [documentation home](../index.md). Reference
+entries describe application-facing contracts rather than every Ruby method in
+the implementation.
+
+- [Design decisions](../adr/index.md): the rationale behind user-facing behavior and extension choices.

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)