Merge origin/master into fix/gfql-auto-engine-polars-native

Resolve CHANGELOG.md: rewrite the #1743 entry to describe behavior only
(AUTO on all-polars-frame graphs routes to the native polars engine with
legacy fallback on decline; explicit engines and policy-bearing calls
unchanged; AUTO never selects polars-gpu; cuDF untouched) and drop stale
perf numbers per the docs benchmark-numbers convention.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011AB4RZpph3uSFUpzKnZJcr

Author: lmeyerov

CHANGELOG.md

@@ -129,6 +129,69 @@ python bin/ci_cypher_surface_guard.py --write-baseline
 
 Then commit both code changes and baseline update together.
 
+### Type Hygiene Guard
+
+`bin/lint.sh` (run by the `python-lint-types` matrix on py3.8-3.14) runs
+`bin/ci_type_hygiene_guard.py`, a stdlib-only AST check over `graphistry/`
+(tests excluded, matching `mypy.ini`). It exists to catch the defect classes
+that keep coming back in code review, so a reviewer does not have to.
+
+| Check | What it flags |
+|---|---|
+| `missing-annotations` | a parameter or return without a type annotation (same ground as ruff `ANN001/002/003/201/202/204/205/206`) |
+| `explicit-any` | `Any` anywhere inside an annotation |
+| `explicit-cast` | a `cast(...)` call |
+| `bare-generic` | unsubscripted `list` / `dict` / `List` / `Dict` / ... in an annotation |
+| `plottable-setattr` | `setattr()` onto a parameter annotated as a `Plottable` |
+| `plottable-attr-write` | `param.attr = ...` onto a parameter annotated as a `Plottable` |
+| `vocab-str-param` | a closed-vocabulary parameter (`table`, `kind`, `direction`, `how`, `mode`, `engine`) annotated as plain `str` |
+
+Enforcement is a **per-file count ratchet** against
+`bin/ci_type_hygiene_baseline.json`: a file may not gain findings, and a file
+absent from the baseline must have zero. Existing debt is grandfathered, new and
+moved code is not.
+
+```bash
+./bin/ci_type_hygiene_guard.py             # what CI runs
+./bin/ci_type_hygiene_guard.py --report    # totals per check
+./bin/ci_type_hygiene_guard.py --list plottable-setattr
+./bin/ci_type_hygiene_guard.py --strict    # show files that improved; time to retighten
+```
+
+When a finding is genuinely correct, annotate that line and say why:
+
+```python
+setattr(res, f"_{kind}_dbscan", dbscan)  # hygiene-ok: plottable-setattr -- res is a fresh copy
+```
+
+Do **not** raise a cap with `--update-baseline` to make a new finding go away.
+Lowering caps after fixing debt is the intended use; commit the code change and
+the baseline update together.
+
+#### Conventions behind the checks
+
+- **Never write to a caller's `Plottable`.** Caching by `setattr` keyed on
+  `id()` leaked results across `gfql()` calls and returned stale answers after
+  an in-place frame mutation (issue #1825). Return a new object, or thread a
+  per-execution cache.
+- **Prefer engine-agnostic `SeriesT` / `DataFrameT` plus a localized
+  `# type: ignore`** over `Any` plus call-site `cast()`.
+- **Parameterize generics.** `list[str]` needs `from __future__ import
+  annotations` on py3.8 lanes; `List[str]` works without it. Both satisfy the
+  check -- only the unsubscripted form is flagged.
+- **A fixed vocabulary is a `Literal`, not a `str`.** A column name is legitimately
+  `str`; an engine name, a `table=`/`kind=` of `'nodes'`/`'edges'`, a `how=`, or a
+  `direction=` is not. Reuse an existing alias where one exists (e.g.
+  `GraphEntityKind = Literal['nodes', 'edges']` in
+  `graphistry/models/compute/features.py`) rather than declaring a new one.
+  `vocab-str-param` only knows the six parameter names above -- it is a floor, not
+  a full check; reviewers still own the general case.
+
+Ruff additionally rejects `getattr(x, "const")` / `setattr(x, "const", v)`
+(`B009`/`B010`) outright; today's offenders are grandfathered in
+`pyproject.toml`'s `per-file-ignores` and are retired with
+`ruff check --fix --select B009,B010 <file>`.
+
 ### GPU CI
 
 GPU CI can be manually triggered by core dev team members:

DEVELOP.md

@@ -1,10 +1,20 @@
 #!/usr/bin/env python3
 """FAIR GFQL-vs-Ladybug: run Ladybug's benchmark ops as GFQL Cypher MATCH...RETURN
-(the row pipeline), NOT dataframe shortcuts. Compares against LadybugDB's PUBLISHED
-5M/20M numbers (their figures, their hardware — a cross-machine comparison; treat
-ratios as indicative). Ladybug best (5M/20M, ms): full_scan 3789, range 7.5,
-point 0.3, count 3.3, out_degree100 59.8, scan_rel_props 15722,
-scan_rel_rowid 14562. Kuzu count 46.
+(the row pipeline), NOT dataframe shortcuts. Op shapes follow
+https://github.com/LadybugDB/kuzu-ladybug-benchmark.
+
+The `LADYBUG` reference column below is a MEASUREMENT, not a literal: LadybugDB 0.18.1,
+embedded, on the same host and in the same session as the GFQL arm, on the same generated
+5M-node / 20M-edge graph, warm medians (2 warmups + 5 timed runs, median across two
+position-balanced slots), timed at Ladybug's FASTEST result-producing scope of the four
+measured (zero-copy Arrow / polars / pandas / row iterator) -- Arrow for every scan,
+the row iterator for the single-row point lookup -- because GFQL returns a materialized
+columnar frame and choosing a slower scope for the competitor is not a comparison. Result values were digest-identical
+across the two engines on every op. Runner, raw JSON and full provenance:
+pyg-bench `benchmarks/ladybug_scan/` and `results/ladybug-scan-20260728/`.
+
+Numbers here are from dgx-spark (GB10); on another box, re-run the pyg-bench lane rather
+than reusing these.
 
 FAIRNESS: each engine is benchmarked on a graph built in ITS OWN NATIVE frame type
 (pandas/polars/cuDF), built ONCE outside the timing loop. An earlier version built the
@@ -49,8 +59,9 @@ def build(engine):
     "scan_rel_props": "MATCH (a)-[o]->(b) RETURN a.id, b.id, o.since",
     "scan_rel_rowid": "MATCH (a)-[r]->(b) RETURN a.id, b.id",
 }
-LADYBUG = {"full_scan": 3789, "range": 7.5, "point": 0.3, "count": 3.3,
-           "scan_rel_props": 15722, "scan_rel_rowid": 14562}
+# LadybugDB 0.18.1, dgx-spark, 2026-07-28, Arrow materialization (see module docstring).
+LADYBUG = {"full_scan": 364.28, "range": 7.57, "point": 0.30, "count": 3.08,
+           "scan_rel_props": 1925.61, "scan_rel_rowid": 1449.13}
 
 def _size(res):
     df = getattr(res, "_nodes", None)

benchmarks/gfql/bench_ladybug_cypher.py

@@ -13,5 +13,5 @@
       "max_properties": 0
     }
   },
-  "lowering_py_max_lines": 9255
+  "lowering_py_max_lines": 9260
 }