forest_liana 9.22.0 → 9.22.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6042deb02adc0ae0d73c97cac99e2abdf0807cdf759cfd0cde116bf94fdc3dff
-  data.tar.gz: 351c37c6fd6cfc17e9c4de3c8f760b84527ca7c1d7a0e2df6976b67b8d549329
+  metadata.gz: 2519878c68b98965bc3b8e31cf9ae9e8253f9d215cf724d99233e55cb37ab8c5
+  data.tar.gz: ae92f459f29ab022290ad09f33e9d1cec654d86fce2784cb425e8c8924b87e59
 SHA512:
-  metadata.gz: 7a952e5b05d2c1491f74b77a53e16012d89419af19040e6168488e000afba0651ebea4f3d7cb21b1ef3045598be8317c30930f7a1e6a681fd5458b8ce956672f
-  data.tar.gz: 9884f0447c34ccb867abf7a2b41326229391e6a3c2689ad9884a15d09ac0ad067ba3a7ebfb30df13cab9502524ef29cd69de941779bfd3185cd385a893261960
+  metadata.gz: 6aaa74f4333c30a763077f5ef1e03247e9c42fd190608ef453263406485ecee48aae37fe8b8b927be1e5fadcf5eb12105c9ea9f5e1b43d7e6e66f78d6a1799af
+  data.tar.gz: 18e7851795ff42410beb2a87db9fb0cec346e4734cd04401461974529bf3d8e4a4ee61fca0e1d143428447f199b6c42cafe48f7c40a4e2d0c2841773e4bf254c

data/app/serializers/forest_liana/serializer_factory.rb

@@ -222,7 +222,20 @@ module ForestLiana
               if reflection_primary_key != klass_primary_key
                 data[attribute_name] = attr_data.merge({
                                                          attr_or_block: proc {
-                                                           relation.klass.find_by(reflection_primary_key => object.send(relation.foreign_key))
+                                                           # The find_by below reads once per row, undoing any preload, and
+                                                           # resolves less than ActiveRecord does: it drops the association's
+                                                           # own scope and matches a nil key against a target row whose key is
+                                                           # NULL too. Both branches answer the same record only once it is
+                                                           # aligned on the preloader, which is what scope_for does — and what
+                                                           # raises on a relation declaring no scope at all, the common case.
+                                                           association = object.association(attribute_name)
+                                                           next association.target if association.loaded? && !association.stale_target?
+
+                                                           key = object.send(relation.foreign_key)
+                                                           next nil if key.nil?
+
+                                                           scoped = relation.scope ? relation.scope_for(relation.klass.all, object) : relation.klass
+                                                           scoped.find_by(reflection_primary_key => key)
                                                          }
                                                        })
                 next

data/app/services/forest_liana/base_getter.rb

@@ -38,7 +38,9 @@ module ForestLiana
       polymorphic, preload_loads = analyze_associations(resource)
       result = records.eager_load(@includes.uniq - preload_loads - polymorphic - @optional_includes)
 
-      result = result.preload(preload_loads) if Rails::VERSION::MAJOR >= 7 && force_preload
+      if Rails::VERSION::MAJOR >= 7 && force_preload
+        result = result.preload(selectable_preloads(result, preload_loads))
+      end
 
       result
     end
@@ -48,6 +50,7 @@ module ForestLiana
     # instance_eval, once per record — loaded here in one query for the whole page instead.
     def apply_smart_field_preloads(records)
       preloads = smart_field_preloads
+      preloads = preloads.slice(*selectable_preloads(records, preloads.keys))
 
       preloads.empty? ? records : records.preload(preloads)
     end
@@ -192,6 +195,153 @@ module ForestLiana
       end
     end
 
+    # To-one only: a filter puts a to-many in @includes too, and preloading that would read every
+    # child row of a page that never displays them.
+    PRELOADABLE_CROSS_DATABASE_MACROS = [:belongs_to, :has_one].freeze
+
+    def cross_database_associations(resource)
+      @includes.uniq.select do |name|
+        association = resource.reflect_on_association(name)
+        next false if association.nil? || SchemaUtils.polymorphic?(association)
+        next false unless PRELOADABLE_CROSS_DATABASE_MACROS.include?(association.macro)
+
+        separate_database?(resource, association) && instance_dependent_hop(association).nil?
+      end
+    end
+
+    # Same version split as preload_polymorphic_associations. Nothing reads the loaders back here:
+    # a plain relation lands in the association cache, where the serializer finds it.
+    def preload_cross_database_associations(records, associations)
+      return if associations.empty? || records.empty?
+
+      associations = associations.reject { |name| missing_preload_key?(records, name) }
+      return if associations.empty?
+
+      if Rails::VERSION::MAJOR >= 7
+        ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
+      else
+        ActiveRecord::Associations::Preloader.new.preload(records, associations)
+      end
+    end
+
+    # A missing key raises while resolving the query, out of MissingAttributeValve's reach, and
+    # takes down the whole list rather than the one field (PRD-1316 from the other direction).
+    # Not only a belongs_to: a has_one reads its owner key off this row too when it declares a
+    # primary_key of its own. Per record class, not projected_resource, because that is how the
+    # Preloader resolves the reflection — one record per class is enough, the select being shared.
+    def missing_preload_key?(records, association_name)
+      records.group_by(&:class).any? do |klass, klass_records|
+        association = klass._reflect_on_association(association_name)
+        next false if association.nil?
+
+        missing = preload_owner_keys(association).reject { |key| klass_records.first.has_attribute?(key) }
+        next false if missing.empty?
+
+        warn_cross_database_preload_skipped(association_name, missing)
+        true
+      end
+    end
+
+    def warn_cross_database_preload_skipped(association_name, missing_keys)
+      reason = "its \"#{missing_keys.join('", "')}\" key is not in the projected select"
+      return unless PRELOAD_SKIPS_WARNED.add?([@collection&.name, association_name, reason])
+
+      FOREST_LOGGER.warn "The \"#{association_name}\" relation of the \"#{@collection&.name}\" " \
+        "collection lives in another database and cannot be preloaded (#{reason}) — it falls back " \
+        'to the lazy load, which cannot read that key either and resolves to a null relation.'
+    end
+
+    # The same question as missing_preload_key?, asked of a relation rather than of a page. A
+    # preload attached to a relation resolves after this method returns — per batch for an export,
+    # on #load for a list — so there is no record to test the key against, only the select the
+    # relation already carries. An empty one is SELECT *, which can never be missing anything; a
+    # narrowed one (a segment scope's .select, a default_scope's) can, and reading a key that is
+    # not there raises while resolving the query, out of MissingAttributeValve's reach, taking
+    # down the whole export where the lazy load it replaces degraded to a null relation.
+    def selectable_preloads(records, names)
+      return names if names.empty? || !records.respond_to?(:select_values)
+      return names if records.select_values.empty?
+
+      selected = selected_column_names(records)
+      return names if selected.include?('*')
+
+      names.reject do |name|
+        association = projected_resource.reflect_on_association(name)
+        next false if association.nil?
+
+        missing = preload_owner_keys(association).reject { |key| selected.include?(key.to_s) }
+        next false if missing.empty?
+
+        warn_unselected_preload_key(name, missing)
+        true
+      end
+    end
+
+    # Only a plain column reference can be read back off a select.
+    PLAIN_SELECT_REFERENCE = /\A(?:"?(?<table>\w+)"?\.)?"?(?<column>\w+|\*)"?\z/
+
+    def selected_column_names(records)
+      table = projected_resource.table_name
+
+      records.select_values.each_with_object(Set.new) do |value, names|
+        select_references(value).each do |reference|
+          match = PLAIN_SELECT_REFERENCE.match(reference)
+          next if match.nil? || (match[:table] && match[:table] != table)
+
+          names << match[:column]
+        end
+      end
+    end
+
+    # One select_value can name several columns, which splitting on commas recovers — but only
+    # while no parenthesis is in play: `COALESCE(uri, driver_id, name) AS x` would otherwise read
+    # as naming driver_id, and the preload that lets through raises on a column the row does not
+    # carry, which is the failure this guard exists to prevent. An expression names nothing here,
+    # so the preload is skipped and the relation left to the lazy load — the safe way to be wrong.
+    #
+    # SqlLiteral is a String, and is meant to be read like one. An Arel attribute is not, and
+    # carries its table and column apart, `products.*` included.
+    def select_references(value)
+      case value
+      when String, Symbol
+        text = value.to_s
+        text.include?('(') ? [] : text.split(',').map(&:strip)
+      when Arel::Attributes::Attribute
+        value.relation.respond_to?(:name) ? ["#{value.relation.name}.#{value.name}"] : []
+      else
+        []
+      end
+    end
+
+    # Re-checks the preloads a relation already carries, for the callers that attach them before
+    # the select is final — HasManyGetter builds its query in prepare_query and only projects in
+    # #perform. Judging the intermediate select drops preloads apply_projection was about to make
+    # safe: inherited_load_columns reads preload_values and selects their keys precisely because
+    # they are already attached. So the question is asked here, where the select is the one the
+    # query will run, and #preload only ever adds — removing one means rebuilding the relation.
+    def drop_unselected_preloads(records)
+      values = records.preload_values
+      return records if values.empty?
+
+      kept_names = selectable_preloads(records, association_names(values))
+      kept = values.select do |value|
+        names = value.is_a?(Hash) ? value.keys : [value]
+        names.all? { |name| kept_names.include?(name.to_sym) }
+      end
+
+      kept.size == values.size ? records : records.except(:preload).preload(kept)
+    end
+
+    def warn_unselected_preload_key(association_name, missing_keys)
+      reason = "its \"#{missing_keys.join('", "')}\" key is not in the query's select"
+      return unless PRELOAD_SKIPS_WARNED.add?([@collection&.name, association_name, reason])
+
+      FOREST_LOGGER.warn "The \"#{association_name}\" relation of the \"#{@collection&.name}\" " \
+        "collection cannot be preloaded (#{reason}) — it falls back to the lazy load, which reads " \
+        'it once per record where that key is on the row and resolves to a null relation where ' \
+        'it is not.'
+    end
+
     # records_by_owner's keys are the exact objects the Preloader was given, not copies — no need
     # to re-find them by id, which would also mis-assign on a nil or duplicate id (composite
     # primary keys are supported elsewhere in this gem).
@@ -364,6 +514,19 @@ module ForestLiana
         select_foreign_keys(select, projected_resource, association, joined?(association, joined_relations))
       end
 
+      # A cross-database to-one relation is never joined, so select_foreign_keys names nothing
+      # owner-side for the has_one half of it — and the preloader reads that key off this row.
+      # Without it here the guard in preload_cross_database_associations fires on every page and
+      # the relation keeps being read once per record, which is the N+1 this file removes. Off
+      # @includes for the same reason as the polymorphic loop above: the preload runs over all of
+      # it, not only the requested subset.
+      cross_database_associations(projected_resource).each do |name|
+        association = projected_resource.reflect_on_association(name)
+        preload_owner_keys(association).each do |key|
+          select << "#{projected_resource.table_name}.#{key}" if column?(projected_resource, key)
+        end
+      end
+
       @field_names_requested.each do |path|
         association = get_one_association(path)
         if association
@@ -473,10 +636,7 @@ module ForestLiana
         association = projected_resource.reflect_on_association(relation_path.relations.first.to_sym)
         next unless association
 
-        preload_owner_keys(association).each do |key|
-          select << "#{projected_resource.table_name}.#{key}" if column?(projected_resource, key)
-        end
-
+        select_dependency_preload_keys(select, relation_path, joined_relations)
         select_foreign_keys(select, projected_resource, association, joined?(association, joined_relations))
 
         # A relation the caller also projects is built off the JOIN, and the preloader leaves an
@@ -528,6 +688,82 @@ module ForestLiana
       Array(reflection.join_foreign_key)
     end
 
+    # The same keys, but for every hop of a declared path this select can still reach, not only
+    # the first. The first hop reads the root row, which this select builds. The hop after it
+    # reads the rows that first hop produced — and when that hop is a relation the query *joins*,
+    # those rows are the narrowed ones built off the JOIN, so its key has to be named here too.
+    # It was not, and the list answered 500 rather than the one field (PRD-1316).
+    def select_dependency_preload_keys(select, relation_path, joined_relations)
+      chains = flatten_dependency_hops(relation_path.relations)
+      return if chains.empty?
+
+      narrowed_hops(chains, joined_relations).each do |owner, reflection|
+        Array(reflection.join_foreign_key).each do |key|
+          select << "#{owner.table_name}.#{key}" if column?(owner, key)
+        end
+      end
+    end
+
+    # The leading hops whose owner row this query builds itself, narrowed, and whose key it
+    # therefore has to name.
+    #
+    # The first hop always counts: it reads the root row. One hop past a *joined* relation counts
+    # too, its owners being the narrowed rows the JOIN built rather than the whole ones a preload
+    # selects. Two relations can be the joined one, and either shape reaches here:
+    #   - the chain's own first hop, which for a :through is the relation it goes through
+    #     (`island` of `has_one :location, through: :island`): the preloader reuses the loaded
+    #     association and reads the source key off it;
+    #   - the first declared relation, when the request displays it: the preloader then leaves
+    #     that whole declaration alone, and the next declared relation reads its key off the
+    #     joined rows. For a plain relation both are the same hop; for a :through they are not,
+    #     and the second was missed.
+    #
+    # Nothing past those: joined_relations only ever names root relations, so every later hop
+    # comes from a preload of its own, which selects whole rows. Every table named up to here is
+    # in the FROM clause — eager loading a :through joins the tables it goes through as well.
+    def narrowed_hops(chains, joined_relations)
+      declared, head = chains.first
+      hops = chains.flat_map(&:last)
+
+      count = joined?(head.first.last, joined_relations) ? 2 : 1
+      count = [count, head.size + 1].max if joined?(declared, joined_relations)
+
+      hops.first(count)
+    end
+
+    # The direct reflections the preloader really walks for a declared path, grouped by the
+    # relation that declared them and each paired with the model it reads its key off.
+    #
+    # A :through hop is not preloaded as one: Preloader::ThroughAssociation loads the through
+    # relation, then the source relation on those records. So the relation a path names can hide
+    # the one the query joins — `location:coordinates` walking Tree's `has_one :location, through:
+    # :island` really starts on the joined `island`, which the declaration never mentions.
+    def flatten_dependency_hops(relations)
+      model = projected_resource
+
+      relations.map do |name|
+        association = model.reflect_on_association(name.to_sym)
+        return [] if association.nil? || SchemaUtils.polymorphic?(association)
+
+        chain = [association, flatten_through_hops(model, association)]
+        model = association.klass
+        chain
+      end
+    # Same net as preload_skip_reason's, for the same shapes: a :through naming a hop that does
+    # not exist, or a class_name pointing at no model, answers NameError off #klass. Nothing is
+    # selected for such a path — skip_preload? drops it from the preload too, so there is no key
+    # left to select for.
+    rescue NameError, ActiveRecord::ActiveRecordError
+      []
+    end
+
+    def flatten_through_hops(owner, association)
+      return [[owner, association]] unless association.through_reflection?
+
+      flatten_through_hops(owner, association.through_reflection) +
+        flatten_through_hops(association.through_reflection.klass, association.source_reflection)
+    end
+
     def get_one_association(name)
       # Handle composite primary keys - name might be an Array
       name_sym = name.is_a?(Array) ? name : name.to_sym

data/app/services/forest_liana/has_many_getter.rb

@@ -85,11 +85,15 @@ module ForestLiana
     # batch never calls #perform and only reads ids, so it falls back to the plain
     # @base_records_for_batch, which needs no preload.
     def query_for_batch
-      @unprojected_records ? apply_smart_field_preloads(@unprojected_records) : @base_records_for_batch
+      return @base_records_for_batch unless @unprojected_records
+
+      drop_unselected_preloads(apply_smart_field_preloads(@unprojected_records))
     end
 
+    # The preloads were attached in prepare_query, before #perform projected: this is the first
+    # point where the select is the one the query will run.
     def records
-      records = @records.limit(limit).offset(offset)
+      records = drop_unselected_preloads(@records).limit(limit).offset(offset)
       polymorphic_associations, = analyze_associations(model_association)
 
       # Left a Relation (not resolved yet) when there is nothing to preload - some callers still
@@ -222,9 +226,10 @@ module ForestLiana
       # already routed those (and cross-DB ones) into `preload_loads`, so `move_to_preload` is
       # always safe to preload; only `preload_loads` needs the Rails 7+ gate.
       result = result.preload(move_to_preload)
-      result = result.preload(preload_loads) if Rails::VERSION::MAJOR >= 7
 
-      result
+      # Of the two shapes in preload_loads, 6.1's preloader only refuses the instance-dependent
+      # ones — gating both left it reading a cross-database relation once per row for nothing.
+      result.preload(Rails::VERSION::MAJOR >= 7 ? preload_loads : cross_database_associations(resource))
     end
 
     # Association names (symbols) whose JOIN the current request actually needs, so they must

data/app/services/forest_liana/resources_getter.rb

@@ -75,15 +75,25 @@ module ForestLiana
     # See HasManyGetter#query_for_batch: same dual-use split between a CSV export (which calls
     # #perform first, so this picks up its smart-field preload) and a bulk "select all" batch
     # (which never does, per initialize_resources_getter below, and only reads ids).
+    # On the relation, not a page: find_in_batches then resolves it per batch, so the key guard
+    # reads the select rather than a row. "Unprojected" only means this class did not narrow it —
+    # a segment whose scope calls .select narrows it before prepare_query ever returns.
     def query_for_batch
-      @unprojected_records ? apply_smart_field_preloads(@unprojected_records) : @base_records_for_batch
+      return @base_records_for_batch unless @unprojected_records
+
+      records = apply_smart_field_preloads(@unprojected_records)
+      cross_database = selectable_preloads(records, cross_database_associations(@resource))
+
+      cross_database.empty? ? records : records.preload(cross_database)
     end
 
     def records
       records = @records.offset(offset).limit(limit).to_a
-      polymorphic_association, preload_loads = analyze_associations(@resource)
+      polymorphic_association, = analyze_associations(@resource)
 
       preload_polymorphic_associations(records, polymorphic_association)
+      # On the page, not @records: count and query_for_batch build off the same relation.
+      preload_cross_database_associations(records, cross_database_associations(@resource))
 
       records
     end

data/app/services/forest_liana/schema_utils.rb

@@ -130,7 +130,7 @@ module ForestLiana
     def self.disable_filter_and_sort_if_cross_db!(opts, name, collection_name)
       return unless opts[:reference]
 
-      assoc_name = opts[:reference].split('.').first&.underscore&.to_sym || name
+      assoc_name = name.to_sym
       model = find_model_from_collection_name(collection_name)
       return unless model
 

data/lib/forest_liana/version.rb

@@ -1,3 +1,3 @@
 module ForestLiana
-  VERSION = "9.22.0"
+  VERSION = "9.22.2"
 end

data/spec/dummy/app/models/car.rb

@@ -1,3 +1,12 @@
 class Car < GarageRecord
   belongs_to :driver
-end
+
+  # Cross-database, keyed on a column that is not Driver's primary key.
+  belongs_to :pilot, class_name: 'Driver', primary_key: :firstname, foreign_key: :model,
+             optional: true
+
+  # The same, plus a scope: the preloader applies it and a bare find_by does not, so the
+  # serializer's two branches only agree once the fallback is aligned on the preloader.
+  belongs_to :active_pilot, -> { where.not(firstname: 'retired') }, class_name: 'Driver',
+             primary_key: :firstname, foreign_key: :model, optional: true
+end

data/spec/dummy/app/models/driver.rb

@@ -1,3 +1,6 @@
 class Driver < UserRecord
   has_one :car
-end
+
+  # The inverse of Car#pilot: the preload reads "firstname" off this row, and nothing projects it.
+  has_one :piloted_car, class_name: 'Car', primary_key: :firstname, foreign_key: :model
+end

data/spec/dummy/app/models/location.rb

@@ -1,3 +1,8 @@
 class Location < ActiveRecord::Base
   belongs_to :island
+
+  # Reached as the hop *after* Tree#location, a has_one :through the list displays: the row it
+  # reads `locations.coordinates` off is the narrowed one that relation's own JOIN built
+  # (query_footprint_spec.rb, PRD-1316).
+  has_many :trees_by_coordinates, class_name: 'Tree', primary_key: 'coordinates', foreign_key: 'name'
 end

data/spec/dummy/app/models/manufacturer.rb

@@ -1,3 +1,11 @@
 class Manufacturer < ApplicationRecord
   has_many :products
+
+  # A scope narrowing the select, which HasManyGetter attaches its preload to before
+  # apply_projection widens it — the select the guard must not judge.
+  has_many :narrowed_products, -> { select(:id, :name, :manufacturer_id) }, class_name: 'Product'
+
+  # Cross-database, and named after neither its target model nor anything else declared here.
+  belongs_to :chief, class_name: 'Driver', foreign_key: :name, primary_key: :firstname,
+             optional: true
 end

data/spec/dummy/app/models/product.rb

@@ -2,5 +2,16 @@ class Product < ApplicationRecord
   belongs_to :manufacturer
   belongs_to :driver, optional: true
 
+  # Same database, but the same shape the serializer intercepts: a primary_key that is not the
+  # target's, plus a scope. Joined rather than preloaded, so it pins that the intercept is about
+  # the declared key, not about crossing a database. On a column of its own: a foreign key is not
+  # a serialized attribute, so keying this on `name` would take `name` off every Product payload
+  # in the suite.
+  belongs_to :maker, -> { where.not(name: 'retired') }, class_name: 'Manufacturer',
+             primary_key: :name, foreign_key: :maker_name, optional: true
+
+  # What a segment scope calling .select does to a relation before any getter sees it.
+  scope :narrowed_select, -> { select(:id, :name) }
+
   validates :uri, presence: true, format: { with: URI::DEFAULT_PARSER.make_regexp }
 end

data/spec/dummy/app/models/tree.rb

@@ -9,4 +9,8 @@ class Tree < ActiveRecord::Base
     optional: true
 
   has_one :location, through: :island
+
+  # A :through whose hop is the displayed `belongs_to :owner`: a path naming this relation alone
+  # never names the relation the query joins, which is the shape PRD-1316 crashed on.
+  has_many :owner_named_trees, through: :owner, source: :trees_by_name
 end

data/spec/dummy/app/models/user.rb

@@ -6,6 +6,17 @@ class User < ActiveRecord::Base
   # The only has_and_belongs_to_many of the dummy.
   has_and_belongs_to_many :favourite_trees, class_name: 'Tree', join_table: 'trees_users'
 
+  # Keyed on `name`, not on the primary key, like Owner#trees_by_name — but reached here as the
+  # *second* hop of a dependency path whose first hop the list also displays, so the row it reads
+  # `users.name` off is the narrowed one the JOIN built (query_footprint_spec.rb, PRD-1316).
+  has_many :trees_by_name, class_name: 'Tree', primary_key: 'name', foreign_key: 'name'
+
+  # The same second-hop shape, but with the two keys held apart: the preloader reads
+  # `users.title`, `foreign_key` answers `age`, and `age` is no column of users at all. The one
+  # relation of the dummy that tells join_foreign_key and foreign_key apart on a narrowed row —
+  # everywhere else they either agree or both land on the primary key a join emits anyway.
+  has_many :trees_by_title, class_name: 'Tree', primary_key: 'title', foreign_key: 'age'
+
   # The keyword form is the only one Rails 6.1 knows; Rails 8 only keeps the positional one.
   if Rails.gem_version >= Gem::Version.new('7.0')
     enum :title, [ :king, :villager, :outlaw ]

data/spec/dummy/db/migrate/20260924120000_add_maker_name_to_products.rb

@@ -0,0 +1,5 @@
+class AddMakerNameToProducts < ActiveRecord::Migration[6.0]
+  def change
+    add_column :products, :maker_name, :string
+  end
+end

data/spec/dummy/db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2026_09_22_120000) do
+ActiveRecord::Schema.define(version: 2026_09_24_120000) do
 
   create_table "addresses", force: :cascade do |t|
     t.string "line1"
@@ -75,6 +75,7 @@ ActiveRecord::Schema.define(version: 2026_09_22_120000) do
     t.string "name"
     t.integer "manufacturer_id"
     t.integer "driver_id"
+    t.string "maker_name"
     t.index ["driver_id"], name: "index_products_on_driver_id"
     t.index ["manufacturer_id"], name: "index_products_on_manufacturer_id"
   end

data/spec/dummy/lib/forest_liana/collections/tree.rb

@@ -37,6 +37,33 @@ class Forest::Tree
     object.location&.coordinates
   end
 
+  # A multi-hop path whose first hop the list also displays as a column. The hop-2 preload reads
+  # `users.name` off the rows the JOIN built with a narrowed select — the fixture for "is the key
+  # a later hop reads selected on the table it is joined from" (query_footprint_spec.rb).
+  field :owner_named_trees_count, type: 'Number', dependencies: ['owner:trees_by_name:name'] do
+    object.owner.trees_by_name.size
+  end
+
+  # The same failure through a :through, where the joined hop is the one the path never names —
+  # PRD-1316's own declaration shape.
+  field :owner_named_tree_names, type: 'String', dependencies: ['owner_named_trees:name'] do
+    object.owner_named_trees.map(&:name).join(',')
+  end
+
+  # The hop-2 key held apart from the hop's foreign key: `users.title` is what the preloader
+  # reads, `age` what foreign_key answers and no column of users. Reading the wrong one of the
+  # two selects nothing at all, and the list 500s again.
+  field :owner_titled_trees_count, type: 'Number', dependencies: ['owner:trees_by_title:name'] do
+    object.owner.trees_by_title.size
+  end
+
+  # A path that carries on *past* a displayed has_one :through: the preloader leaves the whole
+  # declaration alone and the next hop reads `locations.coordinates` off the rows that relation's
+  # JOIN built. The joined relation is then the one the path names, not the hop it goes through.
+  field :location_trees_count, type: 'Number', dependencies: ['location:trees_by_coordinates:name'] do
+    object.location&.trees_by_coordinates&.size
+  end
+
   # A smart belongs_to: is_virtual with a reference, and no ActiveRecord reflection behind it —
   # the fixture for everything that walks a getter's includes (has_many_getter_spec.rb,
   # associations_spec.rb). Nothing else in the dummy declared one.

data/spec/requests/projection_header_spec.rb

@@ -207,7 +207,7 @@ describe 'Requesting resources with the Forest-Projection header', :type => :req
       expect(response.status).to eq 200
       expect(body['data']['attributes']).to eq('id' => @user.id, 'name' => 'Michel')
       expect(body['data']['relationships'].keys)
-        .to match_array %w[trees_owned trees_cut addresses favourite_trees smart_trees]
+        .to match_array %w[trees_owned trees_cut trees_by_name trees_by_title addresses favourite_trees smart_trees]
       expect(body['data']['relationships']['trees_owned']['links']['related']['href'])
         .to eq "/forest/User/#{@user.id}/relationships/trees_owned"
       expect(body['data']['relationships']['favourite_trees']['links']['related']['href'])
@@ -578,6 +578,32 @@ describe 'Requesting resources with the Forest-Projection header', :type => :req
     end
   end
 
+  # PRD-1316. The hop after a joined one reads its key off the narrowed rows the JOIN built, so
+  # that key belongs to this select — `owner:trees_by_name:name` preloads Tree's owners' trees by
+  # `users.name`, which nothing else here would have selected.
+  describe 'on a dependency path whose first hop the request also projects' do
+    let(:getter) do
+      ForestLiana::ResourceGetter.new(
+        Tree,
+        ActionController::Parameters.new(
+          id: 1, fields: { 'Tree' => 'id,name,owner,owner_named_trees_count' }
+        ),
+        nil
+      )
+    end
+
+    it 'selects the key the next hop reads, on the joined table' do
+      expect(getter.send(:compute_select_fields, [:owner])).to include('users.name')
+    end
+
+    it 'leaves it out when that hop is not joined, its table not being in the FROM clause' do
+      select = getter.send(:compute_select_fields, [])
+
+      expect(select).to include('trees.owner_id')
+      expect(select).not_to include('users.name')
+    end
+  end
+
   # NOTICE: Only a bare column name can be table-qualified. An ordering expression would reach
   #         the SQL as table.LOWER(name) and raise.
   describe 'on a collection ordered by an expression' do