feat(agent-bff): reject nested relation field paths in top-level list and count

[nbouliol]

What

Adds a pure, syntactic guard in agent-bff that rejects any top-level list/count field path carrying the relation separator : (e.g. company:name) with 422 relation_field_not_supported.

Why

The agent has an authority gap: a top-level list checks browse/scope on the top collection only (packages/agent/src/routes/access/list.ts), whereas listRelated browse-checks the foreign collection (list-related.ts). A relation-target field can thus be projected without the target collection browse/scope check. The BFF must not propagate that gap, so v1 rejects nested relation paths on top-level list/count outright.

Scope

• relationFieldNotSupported(fields) factory on the existing BffHttpError contract — envelope { error: { type, status, message, details: { fields } } }, details.fields always an array.
• assertNoRelationFieldPaths(paths) — throwing guard; offending paths deduped, first-seen order; direct-only and empty input pass through. Syntactic only (no schema/allow-list consulted).
• Guard is internal (imported by path); not exported from the public index.ts.

Non-goals

• Wiring into live list/count handlers (data-endpoints slice / PRD-639).
• listRelated/countRelated, allow-list validation, capabilities validation.

Tests

10 focused unit tests: nested path in projection/filter/sort (list) and filter (count); multiple offending; single-as-array; dedupe + order; direct-field & empty pass-through; one toErrorBody wire-envelope assertion. Full agent-bff suite green (374/374), lint clean.

Fixes PRD-669

🤖 Generated with Claude Code

Note

Reject nested relation field paths in top-level list and count requests

• Adds assertNoRelationFieldPaths that scans field paths for : (relation separator) and throws a 422 error listing the offending paths if any are found.
• Adds a relationFieldNotSupported error factory producing a BffHttpError with status 422, type relation_field_not_supported, and the offending fields in details.fields.
• Behavioral Change: top-level list and count requests that include nested relation field paths now return 422 instead of being processed.

^{Macroscope summarized 843b80c.}

[linear-code]

PRD-669

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/http/bff-http-error.ts	100.0%
	packages/agent-bff/src/validation/relation-field-guard.ts	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.