Repository navigation
Pagination Schemes 0.11.0: scoped coverage and independent temporal guarantees - #691
Merged
Merged
Conversation
added 2 commits
October 24, 2026 08:37
Add Pagination Schemes 0.11.0 coverage, freshness, consistency and closedPrefix contracts, with exact boundaries, explicit unknown defaults, snapshot pinning, scoped provenance and conservative composition rules. Extend schema/document validation and add a reference observer, synthetic examples and regression tests. Existing traversal behavior is unchanged. Claude-Session: codex://threads/01a11a49-4322-7813-aa0d-2f70ada2be33 Codex-Session: codex://threads/01a11a49-4322-7813-aa0d-2f70ada2be33
A later watermark cannot retroactively repair an older possibly stale coverage observation. State that temporal compatibility requirement and retain both observations independently in the regression example. Claude-Session: codex://threads/01a11a49-4322-7813-aa0d-2f70ada2be33 Codex-Session: codex://threads/01a11a49-4322-7813-aa0d-2f70ada2be33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A traversal can return every page without describing what key range was exhaustively observed, how stale the view may be, or whether pages share a snapshot. Pagination Schemes 0.11.0 adds four opt-in contracts:
coverage,freshness,consistency, andclosedPrefix. Existing documents and traversal flags keep their meaning.For an exhaustive ascending unique-key cursor,
after=9 → [10,12,15]now derives(9,15]for the effective selection and authorization scope. Separately declared initial/terminal guarantees control unbounded ends and empty tails. Explicit range-window coverage inherits the existing bounds/cap rules and needs no sorted output. Unknown guarantees stay unknown.Freshness describes convergence or a bounded lag, independently of response/read snapshot coherence. Read snapshots require captured, carried and verified tokens; equality across polling loops is not global snapshot identity. Closed-prefix metadata describes later first visibility without implying immutable records or append-only membership. Allocation order alone cannot justify it.
Add JSON Schema definitions, semantic validation after overrides, two synthetic OpenAPI examples, and a per-response Python reference observer with scoped provenance and conservative composition. Tests cover incomplete/capped responses, wrong bounds/order, empty/final pages, exact large IDs, late visibility, mixed snapshots and pinning failures. The normative text explains stale equal observations, concurrency, lifecycle/property boundaries, and consumer compatibility. No provider overlay or Syncables/PostgreSQL runtime is upgraded; persistence remains follow-up work.
Validation: all 450 tests across 13 extension folders and all 32 validator example documents passed using pinned Python requirements. Pagination contributes 148 tests. Checked local documentation links, JSON snippets and whitespace. AI session disclosure included.
Closes #686.