Module eval_source 

Source evaluation — spec §10.7.0, §10.7.6, §10.7.8.

Lifts IndexFn from a static AST property to a contextual query: every Source variant answers evaluate(ctx) -> EvaluatedSource carrying its materialized values, observed cardinality, and the index function the emitted values actually satisfy.

Why this layer exists

Before this module, crate::iteration::comprehension::metadata computed IndexFn at AST-construction time using only static source attributes (cardinality_hint, declared step, etc.). Two classes of sources couldn’t claim a useful IndexFn:

• Source::Generator { expr } — the spec-text resolves to a list whose shape is only known after evaluation. The static path conservatively declared Lattice { axis_sizes: [N] } from cardinality_hint (or Unbounded without it), regardless of whether the actual values form a regular arithmetic progression.
• Source::WorkloadParamList { name } — same: the parameter’s list contents are unknown until kernel evaluation.

Non-Lex strategies (Diagonal / Extrema / Shells / Halton / Sobol / Lhs) need the input’s real IndexFn shape to validate V4 and dispatch their indexed-form algorithms. Without this module, V4 fires (or fails to fire) against a stale static estimate; with this module, V4 fires against the post-evaluation truth.

Eval classes

Per spec §10.7.0, sources partition into three eval classes:

Class	Variants	evaluate(None) works?
EvalClass::Static	Literal, IntRange, ContinuousInterval, Distribution (and registry-recognized Generators, once PR β lands)	yes
EvalClass::ContextRequired	Generator outside the registry, WorkloadParamList	no — needs &Context
EvalClass::Distribution	ContinuousInterval, Distribution (in their “not yet sampled” state)	yes, but values is empty — enclosing Order(_, sampling-strategy, Some(n)) materializes

The classifier on SourceEval::eval_class is the compile-time signal: if a comprehension’s entire source set is Static, the IR planner can fire V4 early as a usability nicety; otherwise V4 fires at strategy-invocation time per spec §10.7.8.

What this module DOES NOT own

• The runtime walker that combines per-clause EvaluatedSources into the cartesian / zip / union views strategies actually consume — that lives in crate::iteration::comprehension::runtime.
• The strategy invocation itself — see crate::iteration::comprehension::strategies::Strategy::apply.
• The compile-time V4 fire — see crate::iteration::comprehension::validate.

Structs

EvalContext

Per-evaluation context for context-required sources.

EvaluatedSource

Result of evaluating one clause’s source.

Enums

EvalClass

Spec §10.7.0 partitioning.

EvalError

Errors returned by SourceEval::evaluate.

Traits

SourceEval

The source-evaluation surface.