Metadata-Version: 2.4
Name: pageproof
Version: 0.1.1
Summary: Mutation-aware pagination consistency verifier
Author: Viraj Sabhaya
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/virajsabhaya23/pageproof
Project-URL: Repository, https://github.com/virajsabhaya23/pageproof
Project-URL: Issues, https://github.com/virajsabhaya23/pageproof/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.

```bash
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:

```bash
python -m pageproof verify examples/safe_cursor.json
```

Benchmark:

```bash
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.
