docs(gfql): print the benchmark numbers pyg-bench publishes, and re-verify them

[lmeyerov]

Do not merge without human review.

Supersedes #1813, which the owner redirected: "i don't get why this big file is here when we also have docs/source/_ext/gfql_bench.py. more broadly, why is this different from the pyg-bench stuff? should all that be there, and all we do is pretty print their latest json? and if we have any boundary needs, ensure there are data contract tests that run on the pyg-bench side, and we re-verify on our side?"

This is the consuming half of that factoring. The producing half is pyg-bench graphistry/pyg-bench#113 (merged) and graphistry/pyg-bench#114.

	#1813	here
gate	bin/check_bench_numbers.py, 266 lines	none — the rules live in pyg-bench
extension	347 + 420 lines across two modules	1 module
data	generated JSON, unversioned shape	vendored artifact + vendored contract

What this adds

• docs/source/_data/gfql_benchmarks.json — a vendored copy of pyg-bench's published/docs-numbers.json.
• docs/source/_data/gfql_benchmarks.contract.json — a vendored copy of the contract it satisfies.
• docs/source/_ext/gfql_bench.py — resolves :bench: / :bench-diag:, renders bench-provenance / bench-disclosures, and re-verifies the contract before rendering anything.
• docs/test_bench_numbers.py — the same checks in the ordinary test lane.

Build failures, never silent text: a key that is not published; a run measured longer ago than policy.max_age_days; a non-quotable cell printed as a bare number; a page that drops a referenced number's provenance or disclosures; any contract violation at all. Each of those has a test that watches it fail.

The re-verification is written against the contract document, independently of pyg-bench's implementation. A shared library would fail identically on both sides of the boundary and the re-verification would prove nothing.

benchmark_filter_pagerank.rst

Its figures came from a chart generator reading plans/gfql-gpu-pagerank-benchmark/results/ — a path that has never existed in any commit, and plans/ is gitignored, so nobody could re-derive them. pyg-bench ported the runners unchanged and re-ran them on dgx-spark under the perf lock against pygraphistry 49db91cc, with the raw artifacts committed.

	Neo4j + GDS	GFQL CPU	GFQL GPU	GPU vs Neo4j
Twitter (2.4M edges)	11.72 s	1.58 s	0.24 s	49.5x
GPlus (30M edges)	did not complete	32.10 s	2.42 s	—

Every arm reproduces the earlier run's final subgraphs exactly, node for node and edge for edge. The old "46x" measures 49.5x now. The old GPlus ">56x" is gone: that arm lost its connection mid-transaction and never reached a timed run, and a ratio against a run that did not finish is not a speedup.

The two lifecycle SVGs are removed. They render the withdrawn figures as glyph paths and their generator cannot be run.

Verification

• docs/ci.sh run locally (Dockerised Sphinx): build succeeded, extension live, table and provenance render. A docs-only diff skips test-docs in CI (it needs: python-lint-types), so green CI would not have proven the docs built.
• pytest docs/test_bench_numbers.py — 13 passed.
• ruff clean on both new files. .github/workflows/ci.yml untouched.

Not in scope

The hand-typed-literal guard over policy.managed_docs is not here; it would collide with the factual-correction PR currently touching performance.rst / engines.rst. Worth a follow-up once those land. demos/gfql/benchmark_filter_pagerank_cpu_gpu.ipynb still restates the withdrawn Twitter figures (13.51 s / 45x) and needs the same treatment.

[lmeyerov]

CI: 57 SUCCESS / 11 SKIPPED / 1 CANCELLED.

The one cancelled cell is test-polars (3.12), which hit the 10-minute step timeout at 10m16s. It is cancelled on master itself at 49db91c, the commit this branch is based on (run 30324476067) — the budget defect #1814 addresses, not this diff, which touches no polars code.

test-docs ran and passed here because the diff includes a Python file; a purely docs-only diff would have skipped it (it needs: python-lint-types). docs/ci.sh was also run locally against the final tree: Dockerised Sphinx build succeeded, notebook validation passed, exit 0.

One correction landed after the first CI round, worth flagging to a reviewer: the first draft put the contract rules inside the Sphinx extension, so the minimal lane could not import them (no docutils) and the entire gate would have run in the docs build alone. The rules now live in a stdlib-only gfql_bench_data, with a test that stops a docutils import creeping back in.