Module wcoj_var_ordering 

Variable-ordering cost model for WCOJ dispatch.

The trait WcojVariableOrderingModel picks the kernel leader slot (slot 0) for triangle and 4-cycle WCOJ shapes. The leader is the input that drives the outer iteration; smaller leaders mean fewer iterations.

The default implementation LeaderCardinalityModel picks the min-cardinality input as leader IFF the ratio min_card / default_leader_card ≤ config.effective_wcoj_var_ordering_threshold(). Marginal cases (above threshold) return None so the promoter leaves var_order = None and default WCOJ dispatch behavior is preserved.

The trait returns only the leader index in the promoter’s canonical input order — the promoter is responsible for building the full [xlog_ir::rir::VariableOrder] using the canonical permutation tables (because computing kernel_output_cols requires the rule’s head-variable order, which only the promoter has).

Canonical permutation tables

Triangle (canonical inputs [e_xy, e_yz, e_xz], vars {X, Y, Z}):

Leader	Slot 0	Slot 1	Slot 2	Lookup col-swaps	Kernel-direct output
e_xy 0	e_xy	e_yz	e_xz	none	(X, Y, Z)
e_yz 1	e_yz	e_xz↔	e_xy↔	e_xz, e_xy	(Y, Z, X)
e_xz 2	e_xz	e_yz↔	e_xy	e_yz	(X, Z, Y)

4-cycle (canonical inputs [e_wx, e_xy, e_yz, e_zw], vars {W, X, Y, Z}) — all rotation-only, no col-swaps:

Leader	Slot 0	Slot 1	Slot 2	Slot 3	Kernel-direct output
e_wx 0	e_wx	e_xy	e_yz	e_zw	(W, X, Y, Z)
e_xy 1	e_xy	e_yz	e_zw	e_wx	(X, Y, Z, W)
e_yz 2	e_yz	e_zw	e_wx	e_xy	(Y, Z, W, X)
e_zw 3	e_zw	e_wx	e_xy	e_yz	(Z, W, X, Y)

Structs

HeatAwareLeaderModel

Heat-aware cost model: combines cardinality, access heat, and observed join selectivity into a fixed composite score formula. Higher score = more expensive to iterate over → demote from the leader (slot 0). The model picks argmin(score) as leader, gated by the same effective_wcoj_var_ordering_threshold as the leader-cardinality model.

LeaderCardinalityModel

Default implementation: pick the min-cardinality input as leader, gated by the configurable wcoj_var_ordering_threshold ratio.

WcojCostGateParams

Named K-clique WCOJ-vs-hash gate parameters.

Constants

WCOJ_COST_GATE_PARAMS

Default K-clique cost-gate policy.

Traits

WcojVariableOrderingModel

Trait that picks a leader slot for triangle / 4-cycle WCOJ.

Functions

build_cycle4_var_order

Promoter helper: build a complete VariableOrder for a 4-cycle from the cost model’s leader_idx decision.

build_triangle_var_order

Promoter helper: build a complete VariableOrder for a triangle from the cost model’s leader_idx decision.

cycle4_kernel_output_cols

Promoter helper: 4-cycle canonical head-projection table.

cycle4_lookup_perms

Promoter helper: 4-cycle canonical permutation table.

triangle_kernel_output_cols

Promoter helper: triangle canonical head-projection table.

triangle_lookup_perms

Promoter helper: triangle canonical permutation table.

wcoj_cost_gate_predicts_wcoj

Returns true when the named K-clique cost-gate policy routes WCOJ.