Module selectivity_pass 

Selectivity-driven join reordering for canonical lowered triangle and 4-cycle bodies.

Behavior

For each rule body that matches the canonical lowered triangle or 4-cycle shape, the pass enumerates the valid candidate inner pairings (3 for triangle, 2 for 4-cycle), computes each candidate’s StatsManager::estimate_join_cardinality with pair-derived join keys from the shared-variable mapping, and rewrites the body so the smallest-cost choice is materialized first. Tie → keep the optimizer’s existing order (deterministic no-op).

Safety floor

If any input atom for a recognized body has no StatsManager entry OR cardinality == 0, the body is left unchanged. Recursive deltas / freshly-uploaded relations / unseeded predicates therefore stay on the optimizer’s default order until stats are populated.

Default-fallback edge case

StatsManager::estimate_join_cardinality returns u64 with no provenance — the caller cannot tell whether the estimate came from the cached JoinSelectivity table, the column-distinct heuristic, or the 10% default fallback. When all input atoms have populated cardinalities but no column statistics, the per-pair estimates may all collapse to the same fallback ratio, making the chosen pairing uninformative. This is an accepted trade-off: row-set parity holds regardless of selectivity quality (the rewrite preserves semantics); the integration checks gate on row-set + WCOJ-dispatch correctness, not on optimal pair choice.

Promoter coordination

The triangle and 4-cycle promoters accept the canonical semantic shape with any valid key combination; they emit MultiWayJoin.inputs and slot_vars in canonical semantic order regardless of the body’s positional layout. Reordered bodies therefore still promote and still dispatch the WCOJ kernel correctly.

Functions

run

Selectivity-driven join reordering for canonical triangle and 4-cycle bodies. See module-level doc.