chore(release): prepare 0.59.0 on develop

.github/workflows/ci.yml

@@ -921,6 +921,22 @@ jobs:
         printf 'Differential/parity tests:\n- %s\n' "${parity_tests[@]}"
         python -B -m pytest -vv -n auto "${parity_tests[@]}"
 
+  gpu-gate-audit:
+    # Ungated: a guard against a silent coverage gap must not itself be conditionally
+    # silent, and the path filters do not cover every file it cross-checks.
+    name: gpu-gate-audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+
+    - name: Audit cuDF test gates and the CI coverage they lack
+      run: |
+        python bin/ci_gpu_gate_audit.py
+
   cypher-frontend-surface-guard:
     name: cypher-frontend-surface-guard
     needs: [changes]
@@ -1577,7 +1593,9 @@ jobs:
     needs: [changes, test-minimal-python, test-gfql-core, generate-lockfiles]
     if: ${{ ((needs.changes.outputs.python == 'true' && needs.changes.outputs.narrow_python_only != 'true') || needs.changes.outputs.gfql == 'true' || needs.changes.outputs.pandas_compat == 'true' || needs.changes.outputs.core == 'true' || needs.changes.outputs.infra == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && !(needs.changes.outputs.docs_only_latest == 'true' && (github.event_name == 'push' || github.event_name == 'pull_request')) }}
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    # The py3.12 coverage cell takes ~9m40s on a 2-vCPU hosted runner before
+    # setup, the coverage audit, and artifact upload; keep deterministic margin.
+    timeout-minutes: 15
 
     strategy:
       matrix:

DEVELOP.md

@@ -248,12 +248,31 @@ Ruff additionally rejects `getattr(x, "const")` / `setattr(x, "const", v)`
 
 ### GPU CI
 
-GPU CI can be manually triggered by core dev team members:
+**Today, no CI lane executes cuDF.** `ci.yml` never sets `TEST_CUDF` and no lane
+installs `cudf`, and `ci-gpu.yml` is disabled: its jobs are gated on the
+`GRAPHISTRY_ENABLE_GPU_PUBLIC` repository variable (unset), it needs the
+`gpu_public` self-hosted runner, and a `gpu-disabled-guard` job hard-fails any
+manual trigger. So a `TEST_CUDF=1` receipt is **developer-local evidence only** --
+a cuDF-gated test can contradict the CPU contract, or rot outright, and stay green
+on master indefinitely. Treat a GPU claim in a PR as unprotected until a GPU lane
+exists: re-run it yourself rather than trusting the last receipt.
+
+`bin/ci_gpu_gate_audit.py` (lane `gpu-gate-audit`) keeps the size of that gap
+visible: it counts the cuDF gates, requires each to be attributable (a `reason=`
+naming `TEST_CUDF`, so `pytest -rs` names what was not run rather than reporting a
+bare `s`) and to actually read the flag from the environment, and cross-checks this note against
+whether any workflow sets `TEST_CUDF`. Wiring a real GPU lane retires the note;
+deleting the note without wiring a lane fails the audit. The audit is static -- it
+proves the gates are well formed, never that the gated assertions hold.
+
+GPU CI can be manually triggered by core dev team members, once the lane is
+re-enabled:
 
 1. Push intended changes to protected branches `gpu-public` or `master`
 2. Manually trigger action [ci-gpu](https://github.com/graphistry/pygraphistry/actions/workflows/ci-gpu.yml) on one of the above branches
 
-GPU tests can also be run locally via `./docker/test-gpu-local.sh` .
+GPU tests can also be run locally via `./docker/test-gpu-local.sh` , or directly
+with `TEST_CUDF=1 pytest ...` on a RAPIDS-equipped box.
 
 ## Debugging Tips
 

bin/ci_comment_density_baseline.json

@@ -29,7 +29,7 @@
       "graphistry/compute/gfql/cypher/_boolean_expr_text.py": 1,
       "graphistry/compute/gfql/cypher/ast.py": 5,
       "graphistry/compute/gfql/cypher/ast_normalizer.py": 1,
-      "graphistry/compute/gfql/cypher/lowering.py": 49,
+      "graphistry/compute/gfql/cypher/lowering.py": 48,
       "graphistry/compute/gfql/cypher/parser.py": 24,
       "graphistry/compute/gfql/cypher/reentry/compiletime.py": 2,
       "graphistry/compute/gfql/cypher/reentry/execution.py": 5,
@@ -49,7 +49,7 @@
       "graphistry/compute/gfql/index/explain.py": 1,
       "graphistry/compute/gfql/index/lookup.py": 1,
       "graphistry/compute/gfql/index/registry.py": 4,
-      "graphistry/compute/gfql/index/traverse.py": 15,
+      "graphistry/compute/gfql/index/traverse.py": 13,
       "graphistry/compute/gfql/index/types.py": 3,
       "graphistry/compute/gfql/index/wire.py": 2,
       "graphistry/compute/gfql/ir/pushdown_safety.py": 5,
@@ -59,14 +59,13 @@
       "graphistry/compute/gfql/lazy/engine/polars/chain.py": 47,
       "graphistry/compute/gfql/lazy/engine/polars/degrees.py": 3,
       "graphistry/compute/gfql/lazy/engine/polars/dtypes.py": 3,
-      "graphistry/compute/gfql/lazy/engine/polars/hop.py": 2,
-      "graphistry/compute/gfql/lazy/engine/polars/hop_eager.py": 19,
+      "graphistry/compute/gfql/lazy/engine/polars/hop_eager.py": 18,
       "graphistry/compute/gfql/lazy/engine/polars/lowering_context.py": 2,
-      "graphistry/compute/gfql/lazy/engine/polars/nan_clean.py": 2,
+      "graphistry/compute/gfql/lazy/engine/polars/nan_clean.py": 1,
       "graphistry/compute/gfql/lazy/engine/polars/pattern_apply.py": 9,
       "graphistry/compute/gfql/lazy/engine/polars/predicates.py": 18,
       "graphistry/compute/gfql/lazy/engine/polars/projection.py": 5,
-      "graphistry/compute/gfql/lazy/engine/polars/row_pipeline.py": 84,
+      "graphistry/compute/gfql/lazy/engine/polars/row_pipeline.py": 82,
       "graphistry/compute/gfql/lazy/engine/polars/search.py": 3,
       "graphistry/compute/gfql/lazy/engine/polars/varlen_rows.py": 1,
       "graphistry/compute/gfql/logical_planner.py": 1,
@@ -77,7 +76,7 @@
       "graphistry/compute/gfql/row/entity_props.py": 1,
       "graphistry/compute/gfql/row/frame_ops.py": 6,
       "graphistry/compute/gfql/row/ordering.py": 1,
-      "graphistry/compute/gfql/row/pipeline.py": 40,
+      "graphistry/compute/gfql/row/pipeline.py": 38,
       "graphistry/compute/gfql/same_path/multihop.py": 1,
       "graphistry/compute/gfql/same_path/native_shortest_path.py": 3,
       "graphistry/compute/gfql/search_any.py": 4,
@@ -89,7 +88,7 @@
       "graphistry/compute/gfql_unified.py": 21,
       "graphistry/compute/gfql_validate.py": 3,
       "graphistry/compute/graph_operation.py": 1,
-      "graphistry/compute/hop.py": 6,
+      "graphistry/compute/hop.py": 4,
       "graphistry/compute/predicates/comparison.py": 9,
       "graphistry/compute/predicates/from_json.py": 1,
       "graphistry/compute/predicates/is_in.py": 4,
@@ -145,7 +144,7 @@
       "graphistry/ArrowFileUploader.py": 3,
       "graphistry/compute/ComputeMixin.py": 3,
       "graphistry/compute/ast.py": 1,
-      "graphistry/compute/chain.py": 7,
+      "graphistry/compute/chain.py": 6,
       "graphistry/compute/chain_fast_paths.py": 4,
       "graphistry/compute/chain_lean_combine.py": 2,
       "graphistry/compute/gfql/agg_types.py": 1,
@@ -162,12 +161,8 @@
       "graphistry/compute/gfql/index/explain.py": 1,
       "graphistry/compute/gfql/index/lookup.py": 3,
       "graphistry/compute/gfql/index/registry.py": 5,
-      "graphistry/compute/gfql/index/traverse.py": 9,
       "graphistry/compute/gfql/lazy/__init__.py": 7,
-      "graphistry/compute/gfql/lazy/engine/polars/chain.py": 7,
       "graphistry/compute/gfql/lazy/engine/polars/degrees.py": 1,
-      "graphistry/compute/gfql/lazy/engine/polars/hop_eager.py": 2,
-      "graphistry/compute/gfql/lazy/engine/polars/nan_clean.py": 2,
       "graphistry/compute/gfql/lazy/engine/polars/pattern_apply.py": 1,
       "graphistry/compute/gfql/lazy/engine/polars/predicates.py": 1,
       "graphistry/compute/gfql/lazy/engine/polars/projection.py": 1,
@@ -177,9 +172,8 @@
       "graphistry/compute/gfql/row/pipeline.py": 8,
       "graphistry/compute/gfql/same_path/native_shortest_path.py": 1,
       "graphistry/compute/gfql/temporal/constructors.py": 1,
-      "graphistry/compute/gfql_fast_paths.py": 17,
+      "graphistry/compute/gfql_fast_paths.py": 1,
       "graphistry/compute/gfql_unified.py": 1,
-      "graphistry/compute/hop.py": 4,
       "graphistry/feature_utils.py": 1,
       "graphistry/layout/gib/gib.py": 1,
       "graphistry/layout/gib/partitioned_layout.py": 1,
@@ -242,7 +236,7 @@
       "graphistry/compute/gfql/cypher/_boolean_expr_text.py": 1,
       "graphistry/compute/gfql/cypher/ast.py": 3,
       "graphistry/compute/gfql/cypher/ast_normalizer.py": 1,
-      "graphistry/compute/gfql/cypher/lowering.py": 10,
+      "graphistry/compute/gfql/cypher/lowering.py": 8,
       "graphistry/compute/gfql/cypher/parser.py": 7,
       "graphistry/compute/gfql/cypher/reentry/execution.py": 2,
       "graphistry/compute/gfql/cypher/reentry/flatten.py": 1,
@@ -257,11 +251,10 @@
       "graphistry/compute/gfql/lazy/engine/polars/chain.py": 10,
       "graphistry/compute/gfql/lazy/engine/polars/degrees.py": 1,
       "graphistry/compute/gfql/lazy/engine/polars/hop.py": 1,
-      "graphistry/compute/gfql/lazy/engine/polars/hop_eager.py": 4,
       "graphistry/compute/gfql/lazy/engine/polars/pattern_apply.py": 1,
       "graphistry/compute/gfql/lazy/engine/polars/projection.py": 6,
       "graphistry/compute/gfql/lazy/engine/polars/reserved_columns.py": 1,
-      "graphistry/compute/gfql/lazy/engine/polars/row_pipeline.py": 10,
+      "graphistry/compute/gfql/lazy/engine/polars/row_pipeline.py": 6,
       "graphistry/compute/gfql/lazy/engine/polars/varlen_rows.py": 1,
       "graphistry/compute/gfql/passes/predicate_pushdown.py": 1,
       "graphistry/compute/gfql/rollout.py": 1,

bin/ci_cypher_surface_guard_baseline.json

@@ -13,5 +13,5 @@
       "max_properties": 0
     }
   },
-    "lowering_py_max_lines": 9861
+  "lowering_py_max_lines": 9895
 }

bin/ci_gpu_gate_audit.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Audit the cuDF test gates and keep the size of the unprotected surface visible.
+
+No CI lane installs cudf or sets ``TEST_CUDF``, so every cuDF-gated test is
+developer-local evidence only. This guard makes that gap loud rather than silent:
+
+1. every cuDF gate must be attributable -- a ``reason=`` naming ``TEST_CUDF``, so
+   ``pytest -rs`` names what was not run rather than reporting a bare ``s``;
+2. every cuDF gate must read the flag from the environment, so a gate cannot
+   quietly become a constant;
+3. ``DEVELOP.md`` must carry the unprotected-receipts note exactly while no
+   workflow sets ``TEST_CUDF`` -- wiring a real GPU lane retires the note, and
+   deleting the note without wiring a lane fails.
+
+The audit is static: it proves the gates are well formed and counts them. It does
+not and cannot prove the gated assertions are true; only a GPU lane does that.
+"""
+import ast
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+REPO = Path(__file__).resolve().parent.parent
+TESTS = REPO / "graphistry" / "tests"
+WORKFLOWS = REPO / ".github" / "workflows"
+DEVELOP = REPO / "DEVELOP.md"
+
+FLAG = "TEST_CUDF"
+UNPROTECTED_NOTE = "no CI lane executes cuDF"
+
+
+class Gate:
+    def __init__(self, path: Path, lineno: int, source: str, reason: Optional[str]) -> None:
+        self.path = path
+        self.lineno = lineno
+        self.source = source
+        self.reason = reason
+
+    def where(self) -> str:
+        return f"{self.path.relative_to(REPO)}:{self.lineno}"
+
+
+def _reason_of(call: ast.Call) -> Optional[str]:
+    for kw in call.keywords:
+        if kw.arg == "reason" and isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str):
+            return kw.value.value
+    return None
+
+
+def _skip_message_of(call: ast.Call) -> Optional[str]:
+    for arg in call.args:
+        if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+            return arg.value
+    return _reason_of(call)
+
+
+def _callee_name(call: ast.Call) -> str:
+    node = call.func
+    parts: List[str] = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+    return ".".join(reversed(parts))
+
+
+def _gate_context(text: str, call: ast.Call, parents) -> str:
+    """Source that decides the gate: the call, widened to the ``if`` that guards a bare skip."""
+    segment = ast.get_source_segment(text, call) or ""
+    node = call
+    while node in parents:
+        node = parents[node]
+        if isinstance(node, ast.If):
+            return (ast.get_source_segment(text, node.test) or "") + "\n" + segment
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module)):
+            break
+    return segment
+
+
+def collect_gates(root: Path) -> Tuple[List[Gate], List[str]]:
+    gates: List[Gate] = []
+    parse_errors: List[str] = []
+    for path in sorted(root.rglob("*.py")):
+        text = path.read_text(encoding="utf-8")
+        if FLAG not in text:
+            continue
+        try:
+            tree = ast.parse(text, filename=str(path))
+        except SyntaxError as e:
+            parse_errors.append(f"{path.relative_to(REPO)}: {e}")
+            continue
+        parents = {}
+        for parent in ast.walk(tree):
+            for child in ast.iter_child_nodes(parent):
+                parents[child] = parent
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            name = _callee_name(node)
+            if not (name.endswith("skipif") or name.endswith("skip")):
+                continue
+            segment = ast.get_source_segment(text, node) or ""
+            if FLAG not in segment:
+                continue
+            reason = _reason_of(node) if name.endswith("skipif") else _skip_message_of(node)
+            gates.append(Gate(path, node.lineno, _gate_context(text, node, parents), reason))
+    return gates, parse_errors
+
+
+def workflows_setting_flag(root: Path) -> List[str]:
+    if not root.is_dir():
+        return []
+    assignments = (f"{FLAG}:", f"{FLAG}=")
+    return sorted(
+        p.name for p in root.glob("*.yml")
+        if any(a in p.read_text(encoding="utf-8") for a in assignments)
+    )
+
+
+def emit(line: str) -> None:
+    print(line)
+    summary = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary:
+        with open(summary, "a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+
+
+def main() -> int:
+    gates, parse_errors = collect_gates(TESTS)
+    wired = workflows_setting_flag(WORKFLOWS)
+    develop = DEVELOP.read_text(encoding="utf-8")
+    failures: List[str] = []
+
+    failures.extend(f"test file does not parse: {e}" for e in parse_errors)
+
+    if not gates:
+        failures.append(
+            f"found zero {FLAG} gates under {TESTS.relative_to(REPO)}; the gating convention moved "
+            "and this audit is now blind -- update it"
+        )
+
+    for gate in gates:
+        if not gate.reason or FLAG not in gate.reason:
+            failures.append(
+                f"{gate.where()}: cuDF gate has no reason naming {FLAG}, so `pytest -rs` cannot "
+                f"attribute the skip: {gate.source.splitlines()[0]}"
+            )
+        if "environ" not in gate.source and "getenv" not in gate.source:
+            failures.append(
+                f"{gate.where()}: cuDF gate does not read {FLAG} from the environment, so it "
+                f"cannot be turned on: {gate.source.splitlines()[0]}"
+            )
+
+    note_present = UNPROTECTED_NOTE in develop
+    if wired and note_present:
+        failures.append(
+            f"workflow(s) {wired} now set {FLAG}; remove the '{UNPROTECTED_NOTE}' note from DEVELOP.md"
+        )
+    if not wired and not note_present:
+        failures.append(
+            f"no workflow sets {FLAG}, so cuDF receipts are unprotected; DEVELOP.md must say "
+            f"'{UNPROTECTED_NOTE}'"
+        )
+
+    files = sorted({str(g.path.relative_to(REPO)) for g in gates})
+    emit(f"cuDF gates: {len(gates)} across {len(files)} test files")
+    emit(f"workflows setting {FLAG}: {wired or 'NONE -- these gates are never executed by CI'}")
+
+    if failures:
+        for f in failures:
+            print(f"ERROR: {f}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())