Module eval_source 

Source evaluation — comprehension_forms.md §10.7.0, §10.7.6, §10.7.8.

Makes IndexFn a contextual query as well as a static AST property: 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

crate::iteration::comprehension::metadata computes IndexFn at AST-construction time from static source attributes (cardinality_hint, declared step, etc.). Two classes of sources cannot claim their real IndexFn that way:

• Source::Generator { expr } — the source text resolves to a list whose shape is only known after evaluation. The static path declares Lattice { axis_sizes: [N] } from cardinality_hint (or Unbounded without it).
• Source::WorkloadParamList { name } — 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 check V4 and dispatch their indexed-form algorithms, so V4 fires at strategy invocation against the evaluated shape.

Eval classes

Per comprehension_forms.md §10.7.0, sources partition into three eval classes:

Class	Variants	evaluate(None) works?
EvalClass::Static	Literal, IntRange, a Generator whose expression references no name	yes
EvalClass::ContextRequired	WorkloadParamList, a Generator whose expression references a name	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 class of a generator is decided by the names its expression reads (Source::names_read), never by a table of generator names: a context-free call evaluates in the empty scope (crate::kernel::interp::NoScope), and the compile flattens it into a literal of its values (comprehension::flatten).

SourceEval::eval_class classifies a source for callers that want to know whether evaluate(None) will succeed; the compile-time V4 check in validate works from AST metadata and does not consult it. V4 fires again at strategy-invocation time (comprehension_forms.md §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

The eval-class partition of comprehension_forms.md §10.7.0.

EvalError

Errors returned by SourceEval::evaluate.

NoneRead

A name a source read that made it yield nothing (none_semantics.md Rule 1, comprehension_forms.md §5 V3): the name as read, after composition, so a composed {k_{k}_limits} read with k = 3 is k_3_limits, and all(<cursor>) reads the cursor’s extent outputs.

Traits

SourceEval

The source-evaluation surface.