docs(gfql): refresh perf docs with 0.58.0 release-tag-verified numbers

[lmeyerov]

Summary

Refresh the GFQL performance docs with 0.58.0 release-tag-verified numbers, and — per review feedback — silo all benchmark numbers into performance.rst so a benchmark rerun touches one page (plus index_adjacency.rst, which already silos the index benchmarks). Every other page now carries stable qualitative claims that link into the numbers page.

Provenance of the new numbers: 0.58.0 tag sweep, DGX Spark (GB10), warm medians N=30. Four-engine numbers were kept only after result rows were verified identical across engines; the competitor pairs (vs Neo4j 5.26, vs embedded Kuzu) were validated against expected result rows and cross-database value/row-count checks.

Architecture (who holds what)

• docs/source/gfql/performance.rst — the canonical benchmark-numbers page: the 0.58.0 release-verified section (provenance stated once at the top: seeded typed-hop fast-path table across all four engines, native chain form, resident-index covered-shape lookups with the gfql_index_all(engine='polars') caveat / PR fix(gfql): index AUTO preserves resident polars frames (kills the polars-hop O(E) tax) #1767, flat pandas seeded-hop scaling 0.25M→32M edges, the one-keyword LDBC SNB SF1 polars win 1,299.6→106.1ms / 12.3×, the 5-pair LDBC vs Neo4j table with Neo4j's recent-replies win reported as-is, OLAP q8 200× / q9 14.2× vs Kuzu, and the honest "when not to use GFQL" ratios), plus the prior Orkut/LiveJournal bulk sweep moved in from engines.rst with one dating sentence and its full methodology (incl. the LadybugDB cross-machine disclosure).
• docs/source/gfql/engines.rst — decision matrix, qualitative footnotes, honesty/parity contract, cuDF-vs-polars-gpu, streaming, and a new qualitative "How the engines compare" section; competitor rows (Neo4j, Kuzu, LadybugDB, GraphFrames) state stable win/loss shapes ("GFQL typically wins seeded traversals, covered seeded lookups, multi-join OLAP; embedded engines typically win single-table aggregates and uncovered projection shapes") and link to performance.rst / index_adjacency.rst for the measured pairs. No inline figures or per-claim version labels remain.
• quick.rst / about.rst / overview.rst / index.rst — stable one-liners ("often an order of magnitude faster on query-heavy workloads") with links; no datasets, versions, or ratios.
• CHANGELOG.md — entry under ## [Development] → ### Documentation describing the siloed architecture; rebased on master with the merged docs(gfql): pay-as-you-go resident indexing user guide #1771 entry placed alongside.

Validation

• Rebased on origin/master (post-docs(gfql): pay-as-you-go resident indexing user guide #1771); the only conflict was the CHANGELOG [Development] Documentation section, resolved keep-both.
• Full Sphinx HTML build (python -m sphinx -b html -n --keep-going, Sphinx 8.0.2, graphviz+pandoc via conda): build succeeded, exit 0; grepped the warning log — zero warnings referencing any touched file (repo-wide warnings pre-existing and untouched).
• Cross-ref audit: :ref:gfql-0580-numbers`` target lives in performance.rst; all 5 referring sites in `engines.rst` resolve; no dangling `:doc:`/`:ref:` from the moved content.
• Code claims smoke-tested against the worktree earlier in this PR: gfql(...) on pandas + engine='polars' (identical row counts), gfql_index_all() and gfql_index_all(engine='polars') on polars frames all run clean; no new executable code blocks added.
• Parity language: "results identical" / "verified identical" throughout — never "byte-identical".

Notes for reviewers

• Invariant established: rerunning benchmarks requires touching performance.rst (and index_adjacency.rst) only.
• Old bulk-sweep figures (Orkut/LiveJournal, ~38×, crossover ratios) are retained on the numbers page under a single pre-0.58.0 dating sentence — methodology disclosures kept, nothing invented.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y6dQEcjdazEnzuvuwf73ZL

[lmeyerov]

Review-skill pass (session): 2 minor findings, both FIXED in 3e2208b — (1) dangling methodology grouping bullet reworded self-contained; (2) parity claim scoped accurately (cross-engine identity for 4-engine numbers; expected-rows + cross-DB value checks for Neo4j/Kuzu pairs). Sphinx rebuild clean on touched files after the fix. All quoted numbers are 0.58.0-tag-sweep values (DGX Spark, warm N=30). Note: merge-order note added re #1771 overlap (gfql/index.rst + CHANGELOG). Ready for human review.

🤖 Generated with Claude Code