feat(compiler,engine): edge bindings to filter and project edge properties

[azimafroozeh]

This PR adds an optional edge binding to GQ traversals: $p $w:knows $f names the matched edge row, and $w.since then works anywhere a node field works. Edges have always carried declared properties (role, confidence, provenance fields); until now they were stored and written but unreachable from queries, which could use edges only as connectors.

Capability	Example
Filter on edge properties	$w.since >= date("2023-01-01")
Project edge properties	return { $f.name, $w.since }
Aggregate over edge properties	return { $f.name, count($w.since) }
Compose with undirected and not { }	$a $w:<related> $b; in-block use inside not { }

Semantics: a bound traversal returns one row per matching edge row, so parallel edges between the same endpoints stay distinct; unbound traversals keep their existing set-of-pairs semantics. Constructions without a per-row meaning are rejected with a new typecheck code, T23: a binding on a {min,max} multi-hop, rebinding a taken name, bare $w in return, and text and rank functions (search, bm25, nearest, ...) on an edge-bound field, which execute against node scans and would otherwise be silently ignored.

Execution: a bound traversal always resolves the hop by scanning the edge table (the in-memory CSR adjacency index stores no property columns) and attaches the edge's declared columns to the result rows, where the existing filter and projection machinery picks them up.

Future work

Edge-property filter pushdown into the edge-table scan, and Cypher-style bracket syntax as pure parser surface over the same internals.

Testing

Adds parser coverage (directed, undirected, omitted binding), the T23 typecheck family including the search and rank rejections, and an engine end-to-end test covering filtering on real values, null-property flow, parallel-edge cardinality, and aggregation. cargo test -p omnigraph-compiler and cargo test -p omnigraph-engine --test traversal clean. Docs updated in the same change: docs/user/queries/index.md and docs/dev/execution.md.

Greptile Summary

The PR adds optional edge bindings throughout the query compiler and execution engine, making declared edge properties available to filters, projections, and aggregates.

• Extends traversal grammar, AST, typechecking, and IR with edge bindings and explicit unsupported-use diagnostics.
• Adds an edge-table execution path that preserves physical edge-row cardinality and carries edge properties into the wide result batch.
• Updates RRF reconstruction to account for traversal fanout.
• Adds compiler and engine coverage plus user and execution documentation.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the review’s eligible finding set.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/omnigraph-compiler/src/query/typecheck.rs	Introduces edge-kind bindings, property resolution, collision checks, and explicit rejection of unsupported edge-bound expressions.
crates/omnigraph-compiler/src/ir/lower.rs	Propagates optional edge bindings into every traversal-lowering branch.
crates/omnigraph/src/exec/query.rs	Adds edge-row expansion and alignment and updates RRF reconstruction to preserve traversal fanout.
crates/omnigraph/src/table_store.rs	Generalizes endpoint scans to project physical edge IDs and declared property columns.
crates/omnigraph/tests/traversal.rs	Adds end-to-end coverage for edge-property filtering, nulls, parallel-edge cardinality, and aggregation.
docs/user/queries/index.md	Documents edge-binding syntax, semantics, supported expressions, and restrictions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Q["GQ traversal<br/>$p $w:knows $f"] --> P[Parser and AST]
  P --> T[Typecheck edge binding]
  T --> I["Expand IR<br/>edge_binding = w"]
  I --> S[Scan matching edge rows]
  S --> A["Attach w.id and w.* properties"]
  A --> H[Hydrate destination nodes]
  H --> F[Filter / project / aggregate]

Loading

_{Reviews (4): Last reviewed commit: "test(query): register projected edge sca..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Query language pipeline (parse → lint → typecheck → lower)
• Knowledge Base — Query execution engine

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7ed8b88ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".