[Tonours]

Moves the per-collection filter schema derivation out of unfolded-paths.ts into unfolded-filter-schema.ts. Pure move: the served document is byte-identical.

fixes PRD-1546

What

File	Change
packages/agent-bff/src/openapi/unfolded-filter-schema.ts (new, 176 lines)	AGGREGATORS, isFieldSetKnown, isFilterSetKnown, groupByOperators, leafShape, filterLeaves, filterSchema (default export), copied verbatim with their comments
packages/agent-bff/src/openapi/unfolded-paths.ts (786 to 618 lines)	Keeps request bodies, relation and action schemas, operation registration

Why

• Follow-up promised in the R1 review (PRD-1542): this file mixed three jobs and took 13 commits in 90 days.
• isFieldSetKnown moves too and is exported back: isFilterSetKnown needs it and fieldRefs still reads it, so leaving it behind would make the two files import each other.
• filterSchema and filterLeaves now type their inputs as { pool } and { key, collection } instead of Deps and Pick<CollectionPlan, ...>, the same shapes, so the new module needs nothing from unfolded-paths.ts.
• AGGREGATORS had no other user (data/agent-query.ts declares its own).

How to test

Check	Result
Render of generateOpenApiDocument + serializeOpenApi before and after, 8 cases: generic, generic with AI route, generic with publicUrl + basePath, unfolded (test fixture), unfolded with AI route, unfolded without actions, unfolded with no_fields, unfolded with an empty filterable marked undocumentableFilter	diff -r empty, 8 files identical
Trust bench, subject 1c6ab81 vs baseline e98f1bd (main), real stack: smoke (forest-bff CLI against a v1-express agent, API key, includes the served OpenAPI check) and gateway-api-rename (generic and unfolded document served over cli, bff and gateway mounts)	0 differences over 164 assertions; smoke PASS on both roles; api-rename fails the same 13 assertions on both roles (recipe pins old package versions and fixture tables), so no PR effect
yarn workspace @forestadmin/agent-bff test	111 suites, 2290 tests passed
git diff --stat origin/main -- packages/agent-bff/test	empty, no test touched
npx tsc --noEmit -p packages/agent-bff, npx eslint on both files	clean

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

[linear-code]

PRD-1546

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 4): filterSchema	1

[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/openapi/unfolded-paths.ts	100.0%
	packages/agent-bff/src/openapi/unfolded-filter-schema.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.

[PMerlet]

Spec (PRD-1546): conforms. The filter schema moves to its own module with no behaviour change, and no test assertion was edited.

[PMerlet]

Claude Opus 5.5 (claude-opus-5-5): Preferential: a reader of this guard looks for fieldsEnum above and does not find it in this file.

Code

The comment at unfolded-filter-schema.ts:50 points above, but fieldsEnum stayed behind at unfolded-paths.ts:84.

A way out: name unfolded-paths.ts in the comment instead of saying above.

[Tonours]

Fixed in 0abca46: the comment is gone rather than reworded, since the guard reads on its own. For the record, the reason it exists: an empty operator set would emit enum: [], which makes the filter leaf unsatisfiable (the same trap fieldsEnum guards in unfolded-paths.ts).

[PMerlet]

Approved after /validator run 2036-20261023150129-PMerlet: nothing blocking posted, 1 preferential or code style, 0 suppressed below all.