pageSize and pageToken are documented on the instrument list endpoint but ignored by its handler #46

Description

The vendored OpenAPI spec documents pageSize and pageToken on the instrument list endpoint, and since request validation was added the parameters are type-checked, so a non-integer pageSize is correctly rejected with a 400. But no handler ever reads either one. The service advertises pagination it does not implement, and returns the full result set regardless.

A client that passes a valid page size gets a coherent-looking 200 with more items than it asked for, which is worse than an outright error because nothing signals that the parameter was ignored.

Scope: one endpoint, three parameters

pageSize appears in exactly one of the four vendored specs. The other three (allocation-v1, allocation-instruction-v1, transfer-instruction-v1) have no paginated list endpoint, so this is a single-handler gap, not a pattern across the list routes:

• registry/openapi/token-metadata-v1.yaml:37-50 declares pageSize (int32, default: 25) and pageToken on GET /registry/metadata/v1/instruments.
• ListInstrumentsResponse (registry/openapi/token-metadata-v1.yaml:178) carries a nextPageToken field.
• registry/src/routes/metadata.ts:35-40 is the whole implementation. It takes _req (the request object is unused), scans the full active set through activeConfigs, dedupes by (admin, instrumentId), and responds { instruments }.

So pageToken is ignored alongside pageSize, and nextPageToken is never emitted. A client has no continuation mechanism at all, not merely an oversized first page. Any fix has to cover all three.

Steps to reproduce

1. Seed more instruments than the requested page size.
2. Request the instrument list with a page size of 1.

Expected vs actual behavior

Expected: at most one instrument, plus a nextPageToken the client can pass back as pageToken to get the following page.

Actual: every instrument is returned, with no nextPageToken. Both parameters are validated and then discarded.

Note that omitting nextPageToken is by itself spec-legal (it is not in the schema's required list, so its absence just means "no further pages"). Returning more than pageSize items is not: the spec sets default: 25, so even a client that sends no parameter at all is promised at most 25. Nothing in the suite catches the response half of this, because validateResponses is off.

Dropping the parameter is not an option

The original filing offered a second way out: drop the parameter from our surface and document that. That is not available.

registry/openapi/token-metadata-v1.yaml is byte-identical to deps/token-standard/splice-api-token-metadata-v1/openapi/token-metadata-v1.yaml (diff is clean). It is a vendored copy of the CN Token Standard spec, not a surface we own. Editing it would fork the standard, be silently reverted the next time deps are re-vendored, and undermine the conformance work in #43, which is premised on serving the standard's own spec unmodified.

The remaining choice is therefore narrower than first stated:

1. Implement pageSize / pageToken / nextPageToken over the deduped list. This is an in-memory slice: the read is already a full active-set scan and cannot be narrowed server-side (see the note at registry/src/routes/lookup.ts:56), so pagination here bounds the response, not the ledger query.
2. Or leave the handler as it is and document the deviation in our own docs, without touching the vendored YAML.

Additional context

Surfaced twice during review and triaged both times as a pre-existing gap rather than a regression, since the parameter was never wired up. Filing it so the gap is tracked rather than re-triaged a third time.