cursor-based pagination with stable ordering for the route list

[mikewheeleer]

Summary

The route list uses offset pagination, which skips/duplicates rows when data changes mid-scan and degrades on large offsets. Replace it with opaque-cursor pagination with a stable total order.

Why this matters

Offset pagination is incorrect under concurrent writes and slow at scale. Cursors give stable, efficient, resumable iteration.

Requirements

• Add opaque-cursor pagination to the route list with a bounded page size.
• Order by a stable, unique key (e.g. created-at + id tiebreak).
• Return a nextCursor (null at end); reject malformed/expired cursors with 400.
• Keep the response envelope stable and documented.

Technical guidance

• Encode the cursor opaquely (base64 of the sort key) — never leak internal offsets.
• Use a compound key so ties are deterministic.

Edge cases — each must have a test

• first page then next -> no gaps or duplicates
• rows inserted mid-scan -> no skipped/duplicated existing rows
• end of list -> nextCursor is null
• invalid cursor -> 400
• page size clamps to the max

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Bidirectional (previous) paging
• Total-count on every page

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[telemarkdigital-publisher]

I can take this on. I inspected the current Express route-list implementation in src/index.ts and the existing GET /api/v1/pairs pagination tests, and the issue looks like a focused replacement of offset cursors with stable keyset-style cursors rather than a new endpoint.

Plan:

• replace the current base64 offset cursor helpers with an opaque cursor that encodes the last stable pair key
• order the route list by canonical pair key so page boundaries are deterministic and inserts before/after the cursor do not duplicate existing rows
• preserve the current response envelope, limit clamping, malformed-cursor 400 behavior, and ETag support
• add/extend integration tests for first/next pages, mid-scan inserts, end-of-list null cursors, malformed cursors, and max page-size clamping
• update docs/OpenAPI references if the cursor semantics change from offset to stable key

Verification target: npm test, npm run lint, and npm run build.