fix(gfql/polars): version-stable is_in id-set membership — polars 1.21 shape errors (#2082) - #2085

…rding, categorical ids via Utf8, category-set canon

- polars raises its `is_in` deprecation from Rust: under a `-W error` filter it is printed,
  not raised (a mutant that always used the bare Series RHS passed `-W error::DeprecationWarning`
  on polars 1.35), so the membership tests record warnings and assert none is a
  DeprecationWarning, the way test_hop_kernel_contracts already does.
- polars cannot cast Int64 -> Categorical directly ("cannot cast numeric types to
  'Categorical'"); the categorical-id fixtures route through Utf8.
- test_seeded_node_lookup_fastpath._canon drops unused categories before comparing: the
  category SET is a polars-version artifact (1.21 keeps the full rev-map through filter/join,
  1.35 trims it), not part of the row contract; values and categorical dtype still compare.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

…s, hoist the hop universe, lane/coverage registration

- gfql_unified: the OPTIONAL arm-prune and reentry seed-restrict filters used the bare
  `is_in(<Series>)` form outside the engine directory; both now go through `is_in_ids`
  (the CHANGELOG's "remaining bare-Series warnings" claim now holds).
- membership.id_set(): the prepared RHS, so hop_eager keeps master's single hoisted universe
  instead of imploding once per endpoint on polars >= 1.28.
- bin/test-polars.sh: register the new test module (test_polars_lane_completeness gate);
  coverage_baselines/ci-polars-py3.12.json: baseline membership.py at 85 (one is_in_ids arm
  is unreachable per polars version).
- tests: to_fixed_point=True so the direction matrix actually runs the eager endpoint gate
  (hops=1 takes the lazy semi-join lane); direct kernel pin on Utf8/Categorical ids;
  deprecation assertion narrowed to the polars is_in message; importorskip before engine
  imports; docstrings corrected.
- engine_arrays.py comment dated the is_in deprecation to "polars 1.42"; it is 1.28.0.
- membership docstring: why the < 1.28 branch is live despite the polars>=1.29 extra floor.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

…iscriminating seeded-hop pin, doc pointers

- gfql_unified reentry seed restrict: take the ids from the polars-narrowed seed frame
  (is_polars_df + is_lazy) instead of the pandas-typed SeriesT, so the call type-checks
  in a polars-installed mypy env without an ignore.
- test: the seeded 2-hop pin now seeds at 2 so the result depends on the endpoint gate
  ({(2,3)} with it, {(2,3),(3,4)} without); renamed accordingly.
- docstrings no longer point at the gitignored plans/ directory; hotpaths comment trimmed
  to the fact the name does not carry; engine_arrays comment rewrapped; coverage note
  states the reproducible 93.75 figure.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

…ssue-free product docstring, comment rewrap

- membership._installed_polars_implodes is a maxsize=1 environment singleton; register it
  with cache_registry.register_process_singleton so test_clear_caches_covers_every_cache's
  static lru_cache scan passes.
- membership.py docstring no longer cites issue numbers (bin/ci_comment_density_guard
  issue-rationale rule; the CHANGELOG and tests carry #2082/#1938).
- engine_arrays.py comment actually rewrapped under 127 columns (wave-2 said so, the
  committed hunk was not).
- CHANGELOG: "under RAPIDS 25.02" instead of "in that image".

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

…over pragmas on the two lane-less branches

- imploded_rhs_supported falls back to the bare-Series RHS on an unparseable version
  string instead of raising: that RHS is correct on every release 1.21..1.35 and only
  warns from 1.28, so it is the safe side (idiom: plugins/networkx/policy.py). Test rows
  for local (+cu12), dev (both sides of the floor), unparseable and empty versions.
- Two changed branches have no CI lane and so cannot be covered by
  bin/changed_line_coverage.py: the polars arm of _optional_arm_start_nodes (unreachable —
  its caller routes polars engines to _optional_arm_membership_chain) and id_set's
  polars < 1.28 arm (every CI lane pins polars >= 1.29; validated on dgx RAPIDS 25.02).
  Both now carry the repo's `# pragma: no cover - <reason>` idiom, which also records
  the unreachability in the code rather than only in review notes.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

…n replaces

The polars < 1.28 arm is the whole point of the fix and no CI lane installs a polars
that old, so it had neither a lane nor a test: collapsing id_set to a single spelling
would have stayed green everywhere and silently brought the RAPIDS 25.02
`ComputeError: shapes don't match ... 'is_in'` back. A monkeypatched pin now asserts
both spellings, which also covers the line, so its `# pragma: no cover` comes off.

Also: unparseable-version fallback split into its own named test; the coverage baseline
records the measured figure and a floor with the file's customary margin; and one
docstring covers both dead polars arms of _optional_arm_start_nodes instead of pragma-ing
one and leaving its sibling unmarked.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

The value-level pins protect the helper, not the call sites. A future
`pl.col(x).is_in(ids.implode())` written directly is correct and warning-free on
every CI polars (>= 1.29) and raises ComputeError on the polars 1.21 that RAPIDS
25.02 pins, so no value test in any lane can catch it. This AST scan does.

What it catches: the imploded RHS written in the call, by argument or keyword, and
through a name bound by a plain, annotated or walrus assignment in the same
module — the spelling the reported site itself used (`universe =
resolvable_ids.implode()` then `.is_in(universe)`). The bound value is walked, so
an implode wrapped in another call still binds the name; that over-approximates,
which fails loudly rather than silently. Not caught, and said so in the comment:
binding through a tuple unpack, an attribute or a helper's return value, which
needs real dataflow, and a bare-Series RHS, which is undecidable statically and
only warns.

The lock carries its own controls, because one that silently scans nothing would
pass forever: the exempt helper must exist and sit inside the walked tree, four
routed modules must be among the files parsed (including gfql_unified.py, outside
the engine subtree, so a re-narrowing cannot keep every other pin green), the file
count must clear a floor far below the ~350 shipped modules, and the matcher is
exercised against 16 spellings — 7 it must flag, 9 it must not. Three mutations of
hop_eager back to the pre-fix spelling (plain, annotated, wrapped) each flag line
122; the tree scans clean.

Coverage baseline: membership.py at 92.0, ~8% below the 100.0 measured on the dgx
polars lane, in the file's customary note form.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud

"1792 of the 2361 polars-engine test failures" is a number for the pull request,
not for a user-facing changelog; the entry is already the longest in the section.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_017ropeBMLJUuy6ViYwy15ud