Closes #1468.

Summary

• Added structured logical_plan_defer_code metadata for Cypher logical-planner deferrals.
• Limited residual logical_plan is None runtime chain fallback to approved defer-code buckets:
  • anonymous_match
  • non_top_level_optional_match
  • multiple_match_stages
  • scalar_projection_alias_match
  • optional_match_reentry
• Added fail-fast runtime guards for unclassified/unknown logical_plan is None compiled programs.
• Added positive runtime coverage for all current approved residual fallback buckets and negative coverage for missing/unknown defer codes.
• Updated CHANGELOG.md.
• Updated bin/ci_cypher_surface_guard_baseline.json for the intentional compiled-query metadata surface growth (CompiledCypherQuery.logical_plan_defer_code) and the corresponding lowering.py line-count increase.

Audit

• Corpus probe over graphistry/tests/compute/gfql/**/*.py: string_queries=517, compiled=442, compile_errors=75, deferred_instances=49.
• Post-change all 49 deferred instances carry structured approved codes:
  • multiple_match_stages: 37
  • non_top_level_optional_match: 10
  • anonymous_match: 1
  • scalar_projection_alias_match: 1

Validation

• python3 -m pytest -q graphistry/tests/compute/gfql/test_logical_planner.py graphistry/tests/compute/gfql/test_runtime_physical_cutover.py graphistry/tests/compute/gfql/cypher/test_lowering.py::test_logical_plan_route_for_query_defers_unknown_alias_match_shape_by_default graphistry/tests/compute/gfql/cypher/test_lowering.py::test_logical_plan_route_for_query_allows_unknown_alias_match_shape_when_opted_in graphistry/tests/compute/gfql/cypher/test_lowering.py::test_logical_plan_route_for_query_emits_filter_for_where_predicate -> 46 passed, 4 warnings
• ./bin/ruff.sh graphistry/compute/gfql_unified.py graphistry/compute/gfql/logical_planner.py graphistry/compute/gfql/cypher/lowering.py graphistry/compute/gfql/cypher/reentry/compiletime.py graphistry/tests/compute/gfql/test_runtime_physical_cutover.py graphistry/tests/compute/gfql/cypher/test_lowering.py -> green
• ./bin/typecheck.sh -> Success: no issues found in 262 source files
• python3 -m pytest -q graphistry/tests/compute/gfql/cypher/test_lowering.py graphistry/tests/compute/gfql/test_runtime_physical_cutover.py graphistry/tests/compute/gfql/test_logical_planner.py -k 'not cudf' -> 985 passed, 12 skipped, 112 deselected, 55 warnings
• git diff --check -> clean
• python3 bin/ci_cypher_surface_guard.py -> green after intentional baseline refresh
• python3 -m pytest -q graphistry/tests/compute/gfql/test_runtime_physical_cutover.py -> 21 passed
• ./bin/ruff.sh graphistry/tests/compute/gfql/test_runtime_physical_cutover.py -> green
• Review skill loop -> converged; wave 1 test brittleness fixed, waves 2 and 3 clean on 9582b2c6
• Supplemental test-only review waves 4 and 5 clean on 6fd66a4b
• DGX RAPIDS 25.02 full GFQL: 2383 passed, 22 skipped, 15 xfailed, 102 warnings (/tmp/pygraphistry-1468-dgx/rapids-25.02-gfql.log)
• DGX RAPIDS 26.02 full GFQL: 2383 passed, 22 skipped, 15 xfailed, 101 warnings (/tmp/pygraphistry-1468-dgx/rapids-26.02-gfql.log)

Notes

• ./bin/test-minimal-lite.sh starts with a python -> python3 shim, but local bare-root collection picks up ignored plans/ and test_env/ directories. Scoped to graphistry/tests, it reaches the suite but fails on pre-existing local cuDF/no-CUDA-device and UMAP/cuML auto-selection paths (cudaErrorNoDevice). DGX RAPIDS 25.02 + 26.02 full GFQL validation passed.
• Surface guard rationale: GFQL deletion: retire residual unplanned Cypher chain-execution fallback #1468 needs a structured control signal for the residual unplanned-chain fallback boundary. Adding logical_plan_defer_code avoids runtime dispatch based on message text and makes the remaining fallback audited/explicit.