fix(agent): serialize every level of a projection deeper than one relation

[PMerlet]

Context

The Forest-Projection header (#352) accepts paths of any depth — FieldValidator recurses through relations — and the datasources fetch them. But the record routes built their JSON:API include list from Projection#relations, which only knows about the first hop. Everything below author was read from the database and then dropped at serialization time.

This is the behaviour agent-nodejs already has: its serializer walks registered relationships recursively, with no include list at all.

What this fixes

• Projection#relation_include_paths returns the dotted path of every hop, so author:company:name yields ['author', 'author.company']. Used by show, list and list_related.
• find_recursive_relationships recursed with the parent's class_name, so author.company was looked up in the parent schema and raised InvalidIncludeError. Depth 2 could not work even with the right include list.
• A nested polymorphic hop now carries its type and foreign-key columns. add_polymorphic_type_fields only covers the root level, so author:documentable:* arrived without author:documentable_type / author:documentable_id — and a target with neither a collection nor an id is silently dropped from the payload.
• A bare nested polymorphic relation is expanded to :* like a bare root one. documentable was normalised at the root but author:documentable returned a 400.

Tests

Every fix has a test that fails without it.

• projection_spec: include paths for 1 / 3 hops, shared hops, polymorphic wildcard

• forest_serializer_spec: three-hop chain in included with its linkages, stop at the requested depth, absent intermediate record, nested polymorphic resolved from its type column, phantom target linkage rebuilt from the foreign key, unlinked target

• query_string_parser_spec: two-hop path kept, validation of the last field, type and key columns added, bare nested polymorphic normalised, field under a polymorphic rejected, to-many hop rejected at any depth

• show_spec / list_spec / list_related_spec: end to end on the three routes, including a related record shared by two rows appearing once in included

• join_to_one_optimization_spec: a two-hop path folded into one JOINed query, columns restricted per level, primary key of every level after with_pks, nil intermediate

• active_record_serializer_spec: nested polymorphic carries type and foreign key, plain field through a polymorphic one-to-one hop

• n_plus_one_spec: the preload path stays batched, whatever the number of rows

• field_validator_spec: the wildcard allowed, a field nested under the relation rejected, a field nested under the wildcard rejected

Suites run locally: forest_admin_agent (870), forest_admin_datasource_toolkit (472), forest_admin_rails (110), forest_admin_datasource_active_record (187), forest_admin_datasource_customizer (691), forest_admin_datasource_rpc (168). RuboCop clean.

No new capability: consumers gate on canUseProjectionViaHeader

Considered and dropped, because this was a ruby-only divergence rather than a feature both agents are gaining.

agent-nodejs has honoured any depth since the day it shipped the header (#1813, 2026-08-10) — that commit already tests id,owner:address:street,owner:address:country:name, and its get-one route serializes with no include list, so there was nothing to truncate. ruby shipped the same header in 1.38.0 (#352) but passed relations(only_keys: true) as the include list.

So canUseProjectionViaHeader has always meant "every hop is honoured" on node, and meant "truncated at one hop" only on ruby 1.38.0, 1.38.1 and 1.38.2 — three patches released between Aug 11 and Aug 13, superseded by the release carrying this PR. Gating depth ≥ 2 on the existing key is therefore correct for every node agent and every ruby ≥ 1.38.3, and it keeps a permanent public contract out of both agents to cover a window that closes before the frontend work (PRD-767 / ForestAdmin/forestadmin#9881) can consume it. A customer sitting on one of those three ruby patches needs a patch bump, not a handshake.

Review follow-ups

• documentable:*:brand used to reach the serializer. FieldValidator destructured with a bare split(':'), so the suffix was *, the wildcard guard passed and the deeper-hop recursion was skipped. Harmless while include paths kept only the first hop; with every hop carried, the serializer looked for a * relationship and raised JSONAPI::Serializer::InvalidIncludeError — which descends from Exception, not StandardError, so the controller's rescue never ran and the client got a bare Rails 500 with nothing in the customer's logger. Now split(':', 2), which makes it the 400 it always should have been, and the controller also rescues JSONAPI::Serializer::Error.
• The four new header-projection helpers are added to the existing private_class_method list instead of landing as public API on a released gem class, POLYMORPHIC_TARGET_WILDCARD is used in both places that build the wildcard, and the two blocks flagged as complex are named (polymorphic_linkage_columns, field_along_path).

Known limits, unchanged by this PR

• An unknown value in a *_type column raises Collection 'X' not found. Verified identical at the root and nested — this PR makes the case reachable one hop further, it does not create it.
• Permissions and scopes are checked on the root collection only, at any depth, in this agent and in agent-nodejs. Traversing a relation through a projection is not permission-checked. Pre-existing, tracked separately.

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

🤖 Generated with Claude Code

Note

Fix serialization of projections deeper than one relation in list, related-list, and show endpoints

• Adds Projection#relation_include_paths to flatten nested relation projections into dot-separated paths (e.g. author.company), replacing the previous relations(only_keys: true) / relations.keys calls that only returned top-level relation names.
• Updates list, related-list, and show route handlers to pass relation_include_paths to JSONAPI::Serializer, enabling correct compound-document includes for multi-hop relationships.
• Refactors ForestSerializerOverride#find_recursive_relationships to resolve the serializer class and class_name once per path hop, fixing nested polymorphic to-one serialization.
• Extends QueryStringParser#build_header_projection_fields with helpers (expand_polymorphic_leaf, nested_polymorphic_linkage_fields) to inject type/key linkage columns for nested polymorphic relations and normalize leaf polymorphic paths to wildcards.
• Risk: serializer include payloads now contain intermediate dot-path segments that were previously omitted; any consumer relying on the old flat key list will see different include behavior.

Changes since #357 opened

• Added require for jsonapi-serializers library in ForestController [6f82c52]
• Added test coverage for JSONAPI::Serializer exception handling in ForestController [6f82c52]

^{Macroscope summarized 989c4ad.}

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 5): nested_polymorphic_linkage_fields	2

[qltysh]

Function with high complexity (count = 5): nested_polymorphic_linkage_fields [qlty:function-complexity]

[qltysh]

Function with high complexity (count = 9): each_field_along_path [qlty:function-complexity]

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.1%.

Modified Files with Diff Coverage (5)

Rating	File	% Diff	Uncovered Line #s
	...forest_admin_datasource_toolkit/components/query/projection.rb	100.0%
	...ib/forest_admin_agent/serializer/forest_serializer_override.rb	100.0%
	...dmin_agent/lib/forest_admin_agent/utils/query_string_parser.rb	100.0%
	..._rails/app/controllers/forest_admin_rails/forest_controller.rb	100.0%
	...forest_admin_datasource_toolkit/validations/field_validator.rb	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[linear-code]

PRD-957

[forest-bot]

🎉 This PR is included in version 1.38.3 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀