Backward Pagination with Scope-Bound Opaque Cursors

Trigger

Use this guidance when an API reads older records in descending order, returns each page chronologically, and accepts a continuation cursor that can survive in user-controlled UI state while conversations or filters change.

Practical steps

1. Establish a deterministic descending sort with a unique immutable key. If one field is not unique, use the complete sort tuple plus a unique tie-breaker.
2. On the first request, fix the authorized resource, canonical filters, backward direction, sort definition, and snapshot boundary.
3. Fetch page size plus one rows in descending order. If overflow exists, remove the final row, which is the oldest fetched row, before reversing the retained page for chronological presentation.
4. For an exclusive next-page predicate, set the resume position to the oldest retained row. Do not use the discarded overflow row because that would be skipped.
5. Make the public cursor opaque. Prefer a random signed handle whose server-side state binds caller or tenant, internal resource identity, canonical filter digest, direction, sort definition, snapshot, resume position, version, and expiry. A visible signed serialization protects integrity but does not conceal identifiers; use authenticated encryption if state must be self-contained.
6. Before querying, verify token structure, signature, expiry, authorization, and every request binding. Reject altered, expired, cross-resource, cross-filter, cross-direction, and incompatible-sort cursors with one generic invalid-cursor response.
7. Issue each next cursor with the same bindings and snapshot, changing only the exclusive resume position. A UI should discard its cursor when scope changes, but the server must still enforce the binding.

Limits

A maximum-sequence snapshot excludes later inserts but does not freeze deletions, edits, filter membership, or mutable ordering. Describe it as insertion-stable unless immutable data or an as-of database mechanism provides a full historical snapshot. Redact cursors from logs, rotate signing keys safely, bound token lifetime and size, and retain normal authorization checks.

Failure prevented

This prevents missing the overflow record, duplicating page boundaries, reusing a stale cursor against another conversation or filter set, tampering with resume positions, and leaking internal identifiers through cursor contents.

Evidence level

Support is reasoned analysis with a manual sequential trace and an independent reasoning review. No tests were executed.