Protocol

Cursors are positions, not page numbers

When an endpoint declares pagination, pass its returned cursor back unchanged. Do not decode it, increment it, compare it lexically, or reuse it with different filters.

Collections can change

New rows may arrive while a client walks a collection. Process items by their stable identity and make downstream writes idempotent so a repeated item is harmless. An empty page with no next cursor ends the traversal; a client-side item count does not.

Collection schemas deliberately name their own rows and continuation fields. For example, session history returns events and nextCursor, while workspace audit returns events, cursor, and done. Keep a small adapter per endpoint instead of forcing unlike pages into one guessed shape.

Bound every walk

Set a page limit the endpoint accepts, cap total work for interactive requests, and resume large background jobs from the last committed cursor. Query and response schemas appear in each endpoint's contract panel.