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.

[nbouliol]

Code review — commit 843b80c

Reviewed on two axes (repo standards + PRD-669 spec). Verdict: clean, mergeable.

Standards

No hard violations.

• Inline 422 / relation_field_not_supported in bff-http-error.ts are magic values, but consistent with the existing factory pattern in that file (400, 'invalid_timezone', etc.) — fine as-is.
• Low-priority judgement calls: O(n²) dedup via !offending.includes(path) in the loop (a Set would be linear, though input cardinality is tiny); captureError helper used by only 3 of the tests while the rest use toThrow (mild dual-style, but the toEqual-on-details cases legitimately need it).
• Tests are strong: name = assertion, one behavior each, edge cases covered (empty/single/multiple/dedup/passthrough), exact wire-envelope assertion.

Spec (PRD-669)

• All 5 acceptance criteria implemented and tested. Single path-list primitive is explicitly permitted by the spec.
• details.fields always an array incl. single-path case ✓. Syntactic-only (no schema/allow-list) ✓.
• Dedup + first-seen ordering is not named in the spec but is a defensible reading of AC4 and is tested.
• Guard being uncalled by any route is expected — wiring is a non-goal (Slice 3 / PRD-639).

No blocking issues.

🤖 Generated with Claude Code

[PMerlet]

LGTM