PageProof

Mutation-aware pagination consistency verifier for REST/GraphQL-style list APIs.

PageProof tests a property ordinary one-request API tests cannot answer:

Does a complete traversal still satisfy the API's declared visibility, ordering, continuation, and scope guarantees while the collection changes between pages?

Quick start

Python 3.10+. Runtime has no third-party dependencies.

python -m pip install https://github.com/virajsabhaya23/pageproof/releases/download/v0.1.0/pageproof-0.1.0-py3-none-any.whl

python -m pageproof verify examples/offset_concurrent_insert.json \
  --out out/report.json \
  --junit out/report.junit.xml \
  --sarif out/report.sarif.json \
  --minimized out/minimized.json

Unsafe contracts exit 2.

Safe control:

python -m pageproof verify examples/safe_cursor.json

Benchmark:

python -m pageproof benchmark benchmark/corpus.json \
  --out benchmark/results.json

What is implemented

• offset, keyset/cursor, and Relay-style cursor traversal models;
• snapshot, stable-boundary, and best-effort consistency contracts;
• deterministic insert/delete/sort-key mutation schedules;
• duplicate and omission detection;
• monotonic/tie-break ordering checks;
• cursor round-trip checks;
• gateway/SDK continuation-token preservation checks;
• traversal termination;
• scope/filter preservation;
• deterministic SHA-256 result certificates;
• JSON, JUnit, and SARIF output;
• 50-case regression/seeded/safe benchmark;
• CI workflow and evidence manifests.

Corpus interpretation

The 15 issue/release-grounded cases are minimal semantic reproductions of the reported pagination failure class, not copies of the upstream products. They are tagged with their upstream source URL.

The local benchmark does not pretend to be a live run of Schemathesis or RESTler. Those baselines require their actual toolchains and are separately documented as an external validation step.

Security

Default verification is local and mutates only in-memory fixture state. No production endpoint is modified. Contract files cannot execute commands.

Limitations

• v0.1 is a deterministic reference engine rather than an arbitrary remote API traffic driver.
• GraphQL Relay semantics are represented by the connection/cursor contract, not a GraphQL parser.
• A live collection must declare its consistency model; PageProof does not impose snapshot semantics on best-effort APIs.
• Actual Schemathesis and RESTler comparative execution remains required before claiming superiority over those systems.