fix(agent-bff): document the default page size in the openapi document

[Tonours]

What

The Page and ListResponse component descriptions now say what a list request without page returns: the agent's default page. On the Node agent that is the first page (offset 0) with a limit of 15 records.

The text also says what the body does not: the response is not guaranteed to hold the whole collection, a response of exactly that length is probably truncated, and nothing in the payload flags it. So a consumer is told to send page and walk it.

Description strings only. page stays optional, no request is newly rejected, no wire change.

fixes PRD-1101

Why

A consumer building a client from the document alone had no way to learn that omitting page silently truncates the list — it looked like "the collection", and for any collection over 15 rows it was not.

The number is attributed to the Node agent rather than stated flatly, because agent-bff can front other agent implementations with their own defaults. count is mentioned with its own caveat: a collection can deactivate it.

How to test

cd packages/agent-bff && yarn test test/openapi

Redocly lint on the generic, unfolded and ai-less documents, plus assertions on the generated descriptions — offset 0, limit of 15 records, not guaranteed to be the whole collection, probably truncated — and a separate test naming the limit/offset requirement so it is discoverable by whoever changes it.

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-1101

[qltysh]

Coverage Impact

This PR will not change total coverage.

🚦 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.

[Tonours]

Spec (PRD-1101): conforms — the document now declares page optional and publishes the default page (first page, offset 0, limit of 15 records on the Node agent), which is the ticket's second acceptable outcome; its regression check ("omitting page either 400s or the document states the default page size") is satisfied on the document side, asserted against the generated document.

[nbouliol]

Description strings only, and every claim checks out against the runtime: offset 0 / limit 15 from DEFAULT_PAGE_TO_SKIP and DEFAULT_ITEMS_PER_PAGE, pagination forwarded only when page is set, and the deactivated count caveat. Relation list reuses the same Page and ListResponse, so it is covered too.

[Tonours]

Review pass done, nothing to change. Since this PR is nothing but published claims, each one was checked against the code that produces the behaviour rather than against the ticket:

• No pagination forwarded when page is absent — agent-query.ts:165, if (body.page) is the only writer of page[...], and both list and relation list go through buildListAgentQuery.
• offset 0 / limit 15 — packages/agent/src/utils/query-string.ts:21-22 (DEFAULT_PAGE_TO_SKIP, DEFAULT_ITEMS_PER_PAGE) resolving to new Page(0, 15), applied from routes/access/list.ts and list-related.ts.
• "nothing in the body says so" — response-mappers.ts:23-43 emits countStatus and no length or total marker, so there really is no truncation signal.
• "up to 15" / "probably" — correct for a collection with fewer than, or exactly, 15 rows.
• Count caveat — schema.countable at routes/access/count.ts:18,38.
• Relation list covered — it reuses the same Page and ListResponse components in both document forms.
• "on the Node agent" — justified rather than hedging: the BFF speaks the generic /forest/{collection} wire and nothing pins the upstream to @forestadmin/agent, so another liana can set a different default.

The Page.required assertion asked for in the thread above was already split into its own named test in 2c427c9b5.