docs(gfql): pay-as-you-go resident indexing user guide

[lmeyerov]

Summary

New user guide docs/source/gfql/indexing.rst — Pay-As-You-Go Resident Indexing — the lifecycle-focused companion to the existing index_adjacency.rst (planner/benchmark) page:

• What resident indexes are: node-id index + CSR in/out adjacency sidecars over row positions; build once with gfql_index_all(), reused automatically by seeded GFQL/Cypher lookups and g.hop().
• What engages them on 0.58.0: seeded typed-hop fast paths (whole-row and property RETURNs), including property-seeded lookups when the graph is bound on a different key column (perf(gfql): resident-index gathers engage for property-seeded lookups (SF1-vs-Neo4j lane) #1770), and direct g.hop(). Honestly notes the general polars chain traversal (multi-hop/multi-alias) is not yet covered.
• Staleness/validity contract: identity + fingerprint validation; rebinding .edges()/.nodes() invalidates (edge rebind leaves node_id valid — verified by execution); rebuild via gfql_index_all(); declines are safe — identical results either way.
• Engine notes: pandas/cuDF via AUTO; polars requires gfql_index_all(engine='polars') on 0.58.0 (AUTO swaps polars frames to pandas; fix tracked in fix(gfql): index AUTO preserves resident polars frames (kills the polars-hop O(E) tax) #1767); polars-gpu rides the polars-tagged index.
• Numbers (0.58.0 tag sweep, DGX Spark, warm medians N=30 only): seeded lookup 1.74/1.59 ms (pandas/polars) with the index vs 2.46/2.28 fast-path-only vs 29.9/13.8 general; g.hop() flat 0.159–0.164 ms from 0.25M→32M edges; ~5.7 s build on 30.6M edges.
• Runnable end-to-end example — executed from the worktree; printed outputs in the doc match actual output.

Also: wired into the GFQL toctree + recommended paths (docs/source/gfql/index.rst), CHANGELOG entry under [Development] > Documentation.

Validation

• Full Sphinx HTML build (sphinx-build -b html docs/source ...): build succeeded, zero warnings/errors on the touched files (pre-existing warnings elsewhere unchanged). rstcheck clean on both touched .rst files.
• Example code executed successfully against this worktree (0.58.0 = origin/master), including the decline-safety assertion (index vs no-index results equal) and the staleness demo.

Notes for reviewers

• API surface documented exactly as it exists on master (graphistry/compute/gfql/index/api.py): gfql_index_all, gfql_index_edges, create_index, drop_index, show_indexes — all present; gfql_index_all() skips the node_id index on non-unique ids while explicit create_index("node_id") raises, both documented.

DO NOT MERGE without review sign-off.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y6dQEcjdazEnzuvuwf73ZL

[lmeyerov]

Review-skill pass (session): no findings. Verified against source: show_indexes() columns (name/kind/key_col/engine/backend/n_keys/n_rows/nbytes/valid) match the doc's usage; AUTO-engine cross-reference to engines.rst holds; runnable example executes with the decline-safety parity assert; all quoted numbers are 0.58.0-tag-sweep values (DGX Spark, warm N=30). Sphinx build clean on touched files. Ready for human review.

🤖 Generated with Claude Code