Module reference 

CPU reference evaluator for hypergraph rules.

Pure-Rust, deterministic, deduplicated. Built to be the WCOJ oracle that PR 3+ GPU kernels are validated against, NOT to be fast. Single-rule semantics only — recursive fixpoint is out of scope for PR 2 (planned for the next slice).

Algorithm

For an Eligible rule:

1. Build the HypergraphRule from the AST Rule.
2. For each vertex, compute its domain: the union of values observed at that vertex’s positions across all hyperedges’ relations. Vertices appearing in zero hyperedges (impossible for an eligible rule, but checked) get an empty domain.
3. Recurse over vertices in the order produced by the supplied VariableOrder. At each step, bind the next variable to one of its domain values.
4. At full assignment, verify every positive hyperedge has at least one matching row — accounting for any constants and anonymous wildcards in the source atom.
5. Apply BodyLiteral::Comparison filters.
6. Project the head’s terms into a Vec<RefValue> result row.
7. Sort + dedupe the final row collection (stable, set semantics).

Ineligible rules return an evaluator error — callers must gate on super::analyze / super::analyze_typed before evaluation. See evaluate_rule for the full contract.

Structs

RefRelation

A relation: schema (column types) + rows (lists of typed values).

Enums

RefEvalError

Errors surfaced by evaluate_rule.

RefValue

A typed scalar value produced or consumed by the reference evaluator.

Functions

evaluate_rule

Evaluate rule against relations using order for variable binding. Returns the result rows (one inner Vec<RefValue> per row, with one element per term in the rule head) sorted lexicographically and deduplicated.

Type Aliases

RefRelationStore

Map from predicate name to relation. Sorted iteration is inherent to BTreeMap and contributes to evaluator determinism.