Pagination and Synchronisation
Pagination and Synchronisation
Document verified pagination and synchronisation behaviour.
Status: Partial implementation reference — Code-confirmed; operational validation pending
Last reviewed: 2026-10-21
Scope
Traversal mechanisms, state tracking, ordering, consistency and edge cases where applicable. The source-confirmed baseline below covers part of this scope; remaining operational details are unknown.
Current implementation baseline
Continuation is endpoint-specific. Conversation lists use exclusive after from X-Next-Cursor; a short nonempty page does not alone terminate traversal. Messages/search follow returned links; search remains relevance-ordered. Agent pages use returned normalized limit/offset and actual result length. Tag pages use offset/has_more with strict decimal safe-integer pagination.
Canonical snapshot/export reads bind to at, carry corpus/lineage identity and expose continuation headers. Export all required resource categories at the same boundary, then consume mixed changes. RSS/Atom contain messages only. Source: synchronization, conversation handler and SDK pagination review.
Current working-tree tag queries accept exact tag or literal prefix, usage thresholds and sort, with filters preserved in links. Offset rankings can shift under concurrent appends. See Corpus tag queries.
The SDK synchronization guide describes transactional fixed-target replication, lineage changes and opt-in verified archive import. Archive status/maxima alone do not prove a complete prefix.
Identity-bound SSE checkpoints
An SSE checkpoint is {corpus_id, history_lineage, sequence}. The after query parameter takes precedence over Last-Event-ID; both remain non-negative numeric sequence cursors, and change events retain id: <sequence>. Neither number identifies a corpus or establishes continuous history by itself.
Callers that require continuity send X-Expected-Corpus-Id and X-Expected-Corpus-Lineage on the first connection and every reconnect. Corpus validates them against its persisted identity before returning HTTP 200 or emitting ready. A successful response returns X-Corpus-Id and X-Corpus-Lineage; the id-less ready event repeats the same pair with after. Corpus mismatch and lineage mismatch return the established HTTP 412 errors before the stream opens. Missing or inconsistent authoritative identity returns HTTP 503 lineage_unavailable.
Omitting the expectation headers preserves legacy connection behavior, but the returned identity still scopes every numeric event ID. Native browser EventSource cannot attach arbitrary headers, so an identity-checked browser integration must use a fetch-based SSE client or an application-controlled same-origin proxy. Automatic reconnection is safe only when that client resends both expectations. A lineage change is a discontinuity requiring an explicit new synchronization decision; the old numeric cursor must not be reused as continuous history.
