[FEA] Finish GFQL/Cypher independent GRAPH subgraph projection

[lmeyerov]

Follow-up to #1662 after #1706. #1662 was closed as completed, but verification against origin/master at 4113fa240f05030607d8f055ceb4eeaa124d7e19 shows the broad independent projection feature is still not landed. #1706 fixed the narrower residual GRAPH mask issue; it did not implement the full V0/E0/E1/V1 projection primitive.

Verified current state

• fix(gfql): apply GRAPH residual predicates as masks #1706 is merged: fix(gfql): apply GRAPH residual predicates as masks #1706
• fix(gfql): apply GRAPH residual predicates as masks #1706 merge commit audited: 4113fa240f05030607d8f055ceb4eeaa124d7e19
• fix(gfql): apply GRAPH residual predicates as masks #1706 does not list [FEA] GFQL/Cypher GRAPH subgraph projection for independent node/edge filters #1662 as a closing issue.
• GRAPH { MATCH (n) WHERE n.score > 0 } preserves isolated matching nodes for the node-only case.
• Existing graph residual masks are limited to single-alias node/edge predicates and Polars declines honestly.

Still TBD

1. Canonical independent projection syntax/API

Issue #1662 proposed a canonical target such as:

GRAPH {
  NODES (n)
  WHERE f(n)

  EDGES (a)-[e]->(b)
  WHERE g(e)

  EDGES BETWEEN SELECTED NODES
  PRUNE ISOLATED false
}

Verification: the master parser only allows MATCH, CALL, and USE inside GRAPH {}. A runtime compile probe for the candidate syntax raises GFQLSyntaxError.

2. Full V0/E0/E1/V1 independent node+edge semantics

Desired semantics from #1662:

V0 = { n | node_pred(n) }
E0 = { e=(src,dst) | edge_pred(e) }
E1 = { e in E0 | e.src in V0 and e.dst in V0 }
V1 = { n in V0 | degree_E1(n) > 0 } if prune_isolated else V0

Verification probe on master:

• nodes: a(score=1), b(score=0), isolated z(score=1)
• edge: a -> b
• query: GRAPH { MATCH (a)-[e]->(b) WHERE a.score > 0 }
• actual: nodes=['a','b'] edges=['ab']
• expected for [FEA] GFQL/Cypher GRAPH subgraph projection for independent node/edge filters #1662 projection with prune false: keep a and z, drop b, drop ab because b is absent from V0.

3. Combined node+edge filters

Verification probe on master:

• query: GRAPH { MATCH (a)-[e]->(b) WHERE a.score > 0 AND e.weight > 0 }
• actual: nodes=['a','b'] edges=['ab']
• expected for independent projection: edge ab should be dropped when endpoint b fails the node predicate.

Residual combined form also rejects today: (a.score > 0 OR a.score IS NULL) AND e.weight > 0 raises that GRAPH residual predicates must reference exactly one node or edge alias.

4. Explicit prune-isolated toggle

Master has workaround-style tests for edge-pattern / EXISTS prune behavior and self-loop variants, but not a first-class PRUNE ISOLATED true/false projection option. Need syntax/API, documentation, and tests for preserving isolated selected nodes by default and pruning them when requested.

5. Polars parity

Verification probe on master:

• GRAPH { MATCH (n) WHERE n.score > 0 OR n.score IS NULL } with engine='polars' raises GFQLValidationError: Cypher GRAPH residual predicates are not yet supported on polars graph execution.

Need pandas/Polars parity for the projection primitive, with honest declines only for explicitly unsupported cases.

6. StreamGL/viz one-dispatch compiler target

Need a canonical PyGraphistry query target so streamgl-viz can express node filters, node exclusions, edge filters, edge exclusions, prune-isolated, and limit in one dispatch instead of multi-query client merge.

7. Planner / hot path

Need static analysis/planner support that fuses node filtering, edge filtering, endpoint reconciliation, optional prune-isolated, and optional limit into one tabular graph-state projection operation. The current residual-mask path is a runtime prefilter before chain dispatch, not the full projection planner path.

8. Tests and benchmarks

Need tests for:

• node-only filters preserve isolated nodes
• edge-only filters apply independently
• combined node+edge filters remove edges with excluded endpoints
• prune_isolated=false keeps isolated selected nodes
• prune_isolated=true removes isolated selected nodes
• self-loop behavior
• exclusions normalization
• pandas/Polars parity and cuDF where available
• policy hook behavior
• planner/hot-path regression

Need benchmarks comparing current multi-dispatch + merge, one projection call without hot path, and one projection call with hot path across pandas/Polars/cuDF where available.

Acceptance criteria

• Documented canonical GFQL/Cypher GRAPH form/API for independent node/edge subgraph projection.
• StreamGL/viz can express combined filters/exclusions/prune-isolated in one PyGraphistry dispatch.
• Isolated filtered nodes are preserved unless prune_isolated is enabled.
• Edges whose endpoints are absent from the filtered node set are removed by default.
• Tests cover pandas/Polars parity and policy-hook behavior.
• Benchmarks show the one-call projection path is not slower than current multi-call workaround and has a clear hot path for common filter/exclusion workloads.

Related

• Original issue: [FEA] GFQL/Cypher GRAPH subgraph projection for independent node/edge filters #1662
• Narrow residual-mask fix: fix(gfql): apply GRAPH residual predicates as masks #1706