fix(gfql): Cypher numeric-operator conformance (#1900)

[lmeyerov]

Stacked on #1901. Fixes the #1900 umbrella:

1-3. One numeric-tower root: conformance moved into the runtime evaluators (both engines) — truncated modulo (-7 % 3 = -1), int/int division truncates toward zero on columns (matching the literal lane), integer div/mod by zero raises typed E203 (was inf silently on columns, mislabeled E303 on literals); float/0.0 keeps IEEE inf (Neo4j parity). Polars lowers int /,% natively only with provably nonzero literal divisors (measured: polars // 0 silently nulls) — non-literal divisors NIE to pandas' typed error.
4. bool-vs-number ordering → null semantics across three lanes, with STRICT dtype detection — the value-based bool-like heuristic would have silently nulled IC4's sum(...) > 0 (caught mid-cycle).
5. Simple CASE WHEN null conformed: null never matches, falls to ELSE (openCypher '='); both evaluators + comments.
6. Typing polish: 1 + null nulls on pandas; toInteger('x1') → null (scalar-scoped — TCK forced the narrowing); cross-property STARTS WITH typed E108 (was raw ValueError); typed errors pass through the relabel catch.

44 new pins (red-at-base evidenced). Existing-test changes all oracle-quoted: 5 CASE-WHEN-null pins conformed, 9 sites rewritten to CASE WHEN x IS NULL (preserves intent + values), 2 bool-coercion pins flipped to null-semantics with the BUG-4-family empty-aggregate gap noted. Gates: full-tree byte-identical failure set, cypher 3181P, polars battery 887P, TCK 4145P/0F, ruff+guards green (surface 9686).

🤖 Generated with Claude Code

https://claude.ai/code/session_01MF7uRZLKZaD6Q9FGWSmyXi

[lmeyerov]

GPU sweep receipt (dgx, @d8668fdf7): 8934 passed / 53 skipped / 24 xfailed / 0 failed (4m44s) — +44 vs prior tip, matching the new pin count exactly; numeric-evaluator changes clean on the cudf-shared pandas path and polars-gpu. Log retained (sweep1900.log).

[lmeyerov]

presumably x-engine testing on this

[lmeyerov]

aren't there other unary ops like ~ and ! ?

after handling, does that also mean we have a structural/design error here, like inexhaustive case handling due to static pattern matching?

[lmeyerov]

can we replace the dynamic typing with static patterns?

[lmeyerov]

shouldn't we raise a rich exn / NIE ?

[lmeyerov]

replace with static typing patterns..

[lmeyerov]

Round on the five inline comments. Worked in a fresh worktree at 89abb3c11; polars 1.42 and cudf 25.10 both really execute here, so the GPU lane below is measured, not skipped.

Commits: edfcacf74 (fixes), 2a8744fbe (merge master + comment-density guard), 740484aee + ce820daa0 (pins), be4156e99 (polars CI lane), dbf86d745 (merge the moved base). Head is now dbf86d745.

---

2. row_pipeline.py:328 — "other unary ops like ~ and !? … inexhaustive case handling?"

Yes, inexhaustive by construction — and it was hiding a real bug. Taking the two halves separately.

Which unary ops actually exist. The authoritative set is GFQL_ALLOWED_UNARY_OPS, and the grammar has exactly three productions (uplus, uminus, not_op):

op	status	evidence
~	unreachable — not in the language	parse_expr("~x") raises GFQLExprParseError at col 1
!	unreachable	same
not	handled in every dispatcher	—
-	handled	—
+	polars correctly declined (NIE); pandas + cudf served	asymmetry, no wrong answer

So ~/! were never the risk — pinned as unreachable in test_tilde_and_bang_are_not_in_the_language, so a future grammar change that admits them fails loudly instead of reaching a fallthrough.

The real defect was a fourth case neither of us listed: nested unary over a signed literal. The parser constant-folds the sign into the literal, so - -2 is UnaryOp('-', Literal(-2)), and render_expr_node concatenated it into the unparseable (--2). Legal Cypher n.neg / - -2 failed on every engine with a misleading [invalid-node-reference] parser validation failed. Category: crashes with a mis-typed error (not silently wrong). Honest provenance: this pre-dates the PR — it reproduces identically at base 228d16ae4. Fixed by _sign_separator, a helper named for the rule.

The structural answer. Every dispatcher was an if/elif over UnaryOp.op: str with a silent tail — return None (polars), return False, None (pandas), and a f"({node.op}{operand})" catch-all in expression_text. Now:

• UnaryOpName = Literal["+", "-", "not"] types UnaryOp.op, and GFQL_ALLOWED_UNARY_OPS is derived from it via get_args so the two cannot drift;
• polars closes with assert_never(node.op) — mypy-checked exhaustiveness;
• the pandas evaluator (the terminal fallback, where a decline has nowhere left to go) raises a typed E203 naming the op instead of vanishing;
• polars now lowers unary +, removing the engine asymmetry.

Carriers: test_grammar_admits_exactly_plus_minus_not, test_unknown_unary_op_raises_typed_error_naming_the_op, test_rendered_unary_reparses, test_nested_unary_minus_divisor_serves_truncated_division, test_unary_plus_is_identity.

---

1. predicates.py:117 — "presumably x-engine testing on this"

There was no cudf lane, and adding one found a live defect in this PR. ENGINES in test_numeric_conformance_semantics.py was ["pandas", "polars"] only.

_gfql_truncated_int_div used np.sign, which on a cudf Series dispatches to cupy and needs the nvrtc JIT. Where that isn't loadable the RuntimeError fell outside the typed-error allowlist and got relabelled to [invalid-node-reference] AST evaluator unsupported. Measured on this box:

n.neg / 2 (oracle -3, -4, 3, 4)	base 228d16ae4	this PR before	now
pandas	-3.5, -4.0, … (silently wrong)	correct	correct
polars	-3.5, -4.0, … (silently wrong)	correct	correct
cudf	-3.5, -4.0, … (silently wrong)	hard error	correct

So the PR fixed the silent wrongness on two engines and turned it into a hard failure on the third. Caveat, stated plainly: this depends on the cupy install — a box with a complete nvrtc would likely have served it. The fix removes the cupy dependency entirely (.where instead of np.sign), so the lane no longer depends on that at all.

The predicates.py:117 behaviour itself is now pinned on all three engines (test_bool_column_ordered_against_number_never_matches), with the equality twin (test_bool_column_equality_against_bool_still_served) guarding against the guard over-reaching. The audit also showed the row-lane bool guard was reached only through flipped lowering pins, so test_boolean_ordered_against_number_in_the_row_lane_is_null now covers it directly.

---

4. row/pipeline.py:1657 — "shouldn't we raise a rich exn / NIE?"

Two answers.

The return True, None itself is already correct — openCypher mandates null, not an exception, for a string with no integer value, and the TCK pins it. Verified by test_tointeger_of_a_string_without_an_integer_value_is_null['x1'-None-*].

But the try above it leaked. int(float('inf')) raises OverflowError, which except ValueError did not catch, so it escaped to the relabel and surfaced as [invalid-node-reference] … AST evaluator unsupported — exactly the un-rich error you were pointing at. toInteger('inf'), '-inf' and '1e400' all hit it. Now caught alongside ValueError: unrepresentable is still "not an integer", so it is null like the unparseable case.

---

3 & 5 — static typing (row/pipeline.py:495, comparison.py:233)

No new cast(), no new hygiene-ok; both markers removed, not moved.

• _gfql_cypher_numeric_kind(value: Any) -> Optional[str] → (value: object) -> Optional[CypherNumericKind]. object is genuinely static (it forces the narrowing the body already does) where Any disabled checking, and the stringly-typed "int"/"float" return became a Literal. Its # hygiene-ok: explicit-any is gone.
• comparison.py: getattr(s, "dtype", None) → s.dtype, and the blanket except Exception is gone — verified is_bool_dtype never raises across int/float/bool/object/string/boolean-ext/categorical/datetime/timedelta/empty and the cudf equivalents, under warnings.simplefilter("error"). The new cast(SeriesT, …) # hygiene-ok: explicit-cast this PR added is deleted, and mypy is clean without it or any type: ignore.

Both guards' bool-vs-number conditions became named predicates (_orders_boolean_column_against_number, _orders_boolean_against_number, _orders_boolean_series_against_number), which is what let the prose go.

---

(a) Test amplification — NOT QUIET

• 79 new cells in test_unary_op_surface.py; 2 existing pins strengthened.
• test_polars_lane_completeness caught that the new file was in no CI lane (polars is installed only in test-polars, which runs an explicit file list) — its polars cells would have been dead in CI. Registered in POLARS_TEST_FILES.
• Anti-vacuity: 46 of 79 fail at merge-base 228d16ae4. The 33 that pass are deliberate guardrails (grammar op-set, ~/! unreachability, equality-still-served, empty-frame) and I am not claiming they prove anything about this PR.
• Amplified around row multiplicity as asked: duplicate rows, single-row, empty frame, null cells, plus the unary/predicate surface.
• Mutation audit of the EXISTING pins: no decorative pins. All 7 targeted mutations (truncated div → floor, zero-divisor guard → no-op, truncated % → floored, both bool-ordering guards deleted, CASE-null reverted, _nonzero_int_literal → True) went red. Two extra mutations confirmed the pandas-side guards are uniquely covered.
• What the audit did find, and I fixed rather than reported:
  • 3 polars cells were vacuous — _served_or_nie swallowed NotImplementedError silently. It now asserts the typed row-op decline, so a lane that stops evaluating can no longer pass as agreement.
  • test_simple_case_when_null_never_matches used n.missing (an unknown column), so polars declined instead of evaluating. Repointed at a real null cell; it now genuinely serves on polars. It was also redundant with 5 pre-existing test_lowering.py cells — I strengthened rather than deleted it, since it now covers the executor round-trip those don't.
  • 2 coverage gaps closed: the row-lane bool guard (above), and CASE <alias> WHEN null over an unmatched OPTIONAL alias — this PR changed that value (base 'none' → head 'found', and 'found' is the openCypher-correct answer) but rewrote the test sites instead of pinning it. Now pinned.
• Verdict NOT QUIET — one real pre-existing bug, one cudf portability defect introduced by this PR, one leaked OverflowError, 2 coverage gaps, 3 vacuous cells. Not convergence.

(b) Verbosity / encoding audit

Master's bin/ci_comment_density_guard.py post-dates this PR, so I merged ghhttps/master in and ran it. It failed on 11 file/check pairs.

Zero keeps-with-justification. No guard-ok markers added, no baseline cap raised. Every block this PR added was either deleted or replaced by a named helper — including one I had written myself this round (a 4-line toInteger rationale, now a single line with the rule carried by the pin's name). The four Any+hygiene-ok annotations and the one cast are gone.

Worth flagging honestly: 7 of those failures pre-exist on the base branch — 228d16ae4 fails the guard on its own (lowering.py perf-claim + issue-rationale, flatten.py, gfql_fast_paths.py). Those are #1899/#1896-stack comments, not this PR's. I stripped the issue-number rationale from them so CI is green here, but they properly belong to #1901.

All three guards now pass; ruff clean; mypy 4 errors at head vs 4 at base — zero new (both pre-existing, in hop_eager.py and degrees.py).

---

Not merged, not force-pushed, base unchanged, threads left open.

---

Full-tree gate. graphistry/tests/compute at head: 103 failures, of which 102 fail identically at the merge-base (re-run nodeid-for-nodeid). The one head-only failure was the polars-lane guard above, now fixed. After merging the moved base, the test_hop + gfql sweep is 93 failures with zero outside that pre-existing set.

Two things worth knowing about this box, neither caused by the PR: ~60 of those pre-existing failures are cudf index/ tests failing on a broken cupy libnvrtc — the same missing JIT behind the np.sign defect above — and a second agent was running the same suite concurrently.

The base branch moved to f37833e32 mid-review, which flipped the PR to CONFLICTING and therefore to zero CI runs. Merged in with -c merge.conflictstyle=diff3; now MERGEABLE with runs created.