Type-safe filter expression API

[shivamka1]

Type-safe filter expression API

What this PR does

Replaces filter construction and execution with a typed expression API, end to
end: rust, python, GraphQL, and the remote python client. The old composite and
builder paths are deleted; the composite enums survive only as the plain-data
wire descriptor the client transports.

// fields and properties are expressions from the start
g.filter(NodeFilter.degree().gt(5))?;
g.filter(EdgeFilter.src().name().eq("alice"))?;
g.filter(NodeFilter.property("score").temporal().max().ge(10i64))?;

// view restrictions embed in the expression
g.filter(EdgeFilter.window(1, 3).property("p").eq(1u64))?;

Expressions compile to per-entity ops evaluated against the pre-transformed
view (create_node_op / create_edge_op), with build-time validation
(operator/type compatibility, aggregability).

The four layers

1. Rust: the expression API (PropertyExprFactory, NodeFilterFactory,
   EntityExprFilterOps, EntityAggOps, view wrappers) is the only filter
   construction path. The builder DSL (PropertyFilterOps, NodeIdFilterOps,
   the *FilterBuilder types, validate.rs) is deleted, and the rust test
   suite runs on expressions.
2. Python: filter objects carry both the compiled expression and the wire
   form (FilterTree), recorded at construction. Local filtering executes the
   expression; nothing is reverse-engineered.
3. GraphQL: the wire schema is unchanged; incoming GqlFilter values lower
   directly onto expressions (expr_lowering.rs). The composite conversions
   from the wire form are gone.
4. Remote python: the client reads the carried FilterTree and sends it as
   GraphQL variables. Filters with no wire form (an expression on the
   right-hand side of a comparison) are rejected at the remote boundary with a
   clear error instead of being mistranslated.

Because the wire schema is untouched, stored permission filters in
pometry-storage (GqlFilter JSON) work unchanged.

Qualifiers and typing

Leading and trailing qualifier forms are equivalent and collapse in the
written order — temporal().any().eq(7) and temporal().eq(7).any() lower
to the same ops; qualifiers float through aggregates (temporal().any().sum()
= per-snapshot sums, any match). The ops report the types they produce
(field types, graph id dtype, List of the property dtype for temporal,
structural aggregate outputs), so validation happens at build time: ordering
is rejected for boolean/map/list properties, string operators require
string-castable operands, qualifiers over scalars are errors, and mistyped
constants fail where they are written (python raises TypeError at the
comparison when the type is statically known).

Behaviour changes

• nodes.filter() defers uniformly for every filter kind, including node
  id/name filters; narrowing membership is spelled nodes[...]/select (or a
  graph-level g.filter(...)). This matches the same change made upstream in
  Node ID and OR filter bug #2754, which landed while this branch was open.
• Constants validate by value-castability: numeric strings parse
  (degree().lt("5") works), non-castable values error where they are
  written. Bool constants coerce to ints (prop >= True behaves like python's
  60 >= True); ints do not coerce to bool.
• Mistyped is_in values reject eagerly instead of silently matching
  nothing — a caller can now distinguish "no matches" from "bad query".
• Invalid aggregation chains reject at build time, including shapes the
  composite engine silently mis-executed (a leading any before avg used to
  be a no-op; it is now an error). In rust, aggregations over scalars no
  longer compile at all.
• Empty and/or combinators are rejected rather than defaulting — the
  previous match-everything fallback for or inverted the caller's intent.
• Client error envelope surfaces each GraphQL error's message text
  instead of the raw JSON object, so quotes inside diagnostics are no longer
  escaped into \".
• Two tests that pinned pre-db_v4 semantics were dropped in favour of their
  filter_tests twins: windowed is_self_loop (the window intentionally has
  no effect) and aggregate overflow (now promotes to Decimal instead of
  excluding).

Follow-ups folded in rather than deferred

• Node-id filters no longer scan. NodeFilter.id().eq(x) and .is_in([…])
  resolve their evaluation domain through the storage index instead of
  visiting every node — the narrowing Node ID and OR filter bug #2754 added to the removed builder op,
  carried onto expressions. Only equality and set membership narrow; a
  constant whose type does not match the graph's id type falls back to the
  full domain rather than guessing, and every other predicate is unchanged.
• sum declares the type it produces. It widens at runtime (any unsigned
  width accumulates into U64, signed into I64, floats into F64, promoting
  to Decimal past those) but declared its element type, so a constant beyond
  the element's range was rejected before the sum ever ran — no comparison
  above 255 was expressible on a List<U8>. The declared type now mirrors the
  evaluator's own match arms. Reductions that return an element (min, max,
  first, last) keep the element type.
• Python stubs and docstrings match the runtime. The generated .pyi still
  described builder classes that no longer exist (PropertyFilterOps,
  NodeIdFilterBuilder, …) and docstrings pointed callers at them.

A bug the rewrite caught

Recording view chains at construction initially inverted non-commuting chains
on the wire: window(0,5).latest() meant latest-within-window locally but
window-of-latest remotely. Both wire builders now nest views in application
order (outermost = applied last), and parity tests pin both orders of
window+latest at graph, node and edge scope. Single views and commuting
chains were never affected, which is why broad suites missed it.

Implementation notes

• The python filter factories erase to Arc<dyn …> before wrapping views;
  wrapping the concrete factory made monomorphisation non-terminating the
  first time anything compiled the bindings under --all-features.
• GqlFilter implements CreateFilter by lowering on the fly, so server
  resolvers pass wire values straight through.
• The wire recording lives in python/filter/wire.rs: each construction step
  records its fragment, predicates finish it into a FilterTree, combinators
  compose trees structurally.

What the review threads asked for

The six open threads all asked for the same thing — that the old filter
machinery go away. It has:

Asked about	Now
state/ops/filter.rs ("this whole thing should go away", NodeNameFilterOp)	The builder ops are deleted; the file keeps only the combinators the expression ops use (OrOp/AndOp/NotOp/Mask), which also carry the #2754 const-value fixes
node_filter/ops.rs, node_filter/validate.rs, property_filter/builders.rs	Files deleted; validation happens at expression build time
property_filter/mod.rs ("also left-over?")	The CreateFilter impls are deleted. PropertyFilter stays as the wire data type, and its matches() survives because namespace metadata filtering evaluates single values through it

Testing

• Rust: full workspace, 0 failures; the filter_tests suite runs the same
  scenarios through the expression API.
• Python filter suite: 566 tests, all passing.
• GraphQL python suite (server e2e + local/remote parity): 2425 tests, all
  passing, including per-side discrimination checks that rule out silently
  dropped filters and both orders of non-commuting view chains.
• The domain-narrowing tests were watched failing with the optimisation
  disabled before being kept, so they pin the narrowing rather than passing
  vacuously.
• pometry-storage compile-verified against this branch: raphtory-auth fails
  identically here and against plain db_v4 (pre-existing plugin drift), so
  nothing here regresses it. On submodule bump the outer workspace needs
  dyn-clone, typetag and inventory in [workspace.dependencies].

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rust Benchmark'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 2.

Benchmark suite	Current: db8d4b1	Previous: 9823ef7	Ratio
lotr_graph/num_edges	6 ns/iter (± 0)	0 ns/iter (± 0)	+∞
lotr_graph/num_nodes	6 ns/iter (± 0)	1 ns/iter (± 0)	6
lotr_graph/graph_latest	3 ns/iter (± 0)	0 ns/iter (± 0)	+∞
lotr_graph_materialise/materialize	7737053 ns/iter (± 44875)	1564816 ns/iter (± 35303)	4.94
lotr_graph_window_100/num_nodes	15 ns/iter (± 0)	5 ns/iter (± 0)	3
lotr_graph_window_100_materialise/materialize	7817487 ns/iter (± 34513)	1669150 ns/iter (± 10700)	4.68
lotr_graph_window_10/has_node_existing	138 ns/iter (± 9)	62 ns/iter (± 11)	2.23
lotr_graph_window_10_materialise/materialize	3386528 ns/iter (± 12063)	971980 ns/iter (± 4278)	3.48
lotr_graph_subgraph_10pc_materialise/materialize	2060727 ns/iter (± 24511)	334634 ns/iter (± 1287)	6.16
lotr_graph_subgraph_10pc_windowed/has_node_existing	141 ns/iter (± 7)	62 ns/iter (± 14)	2.27
lotr_graph_subgraph_10pc_windowed_materialise/materialize	1294611 ns/iter (± 13512)	230399 ns/iter (± 2617)	5.62
lotr_graph_window_50_layered/num_edges_temporal	141029 ns/iter (± 3517)	70121 ns/iter (± 7586)	2.01
lotr_graph_window_50_layered/has_node_existing	390 ns/iter (± 20)	129 ns/iter (± 12)	3.02
lotr_graph_window_50_layered/graph_latest	81751 ns/iter (± 2733)	36649 ns/iter (± 916)	2.23
lotr_graph_window_50_layered_materialise/materialize	30479885 ns/iter (± 151669)	3488825 ns/iter (± 24948)	8.74
lotr_graph_persistent_window_50_layered/num_edges_temporal	587231 ns/iter (± 5273)	192686 ns/iter (± 1569)	3.05
lotr_graph_persistent_window_50_layered/has_node_existing	415 ns/iter (± 366)	174 ns/iter (± 83)	2.39
lotr_graph_persistent_window_50_layered/graph_latest	123939 ns/iter (± 1465)	57549 ns/iter (± 4809)	2.15
lotr_graph_persistent_window_50_layered_materialise/materialize	52787032 ns/iter (± 227728)	5298035 ns/iter (± 147912)	9.96

This comment was automatically generated by workflow using github-action-benchmark.