Module resolve 

Kernel-target resolution: which compiled target serves a checkpoint.

Split out of lib.rs so the selection RULES are pure functions over plain declarations — unit-testable on a GPU-free host where ATLAS_SKIP_BUILD=1 leaves all_ptx_sets() empty.

Why (model_type, hidden_size) alone is not enough

Qwen3.8-27B is architecturally identical to Qwen3.6-27B: same model_type (qwen3_5), same hidden_size (5120), same every numeric config field — the checkpoints differ only in weights. Two kernel targets therefore declare the SAME exact (qwen3_5, 5120) pair, and the historical resolver (.find() over build-order-sorted targets) would have silently picked whichever sorted first. A silent wrong pick mis-serves the MLPerf-edge flagship’s sampling presets and behavior flags, so ambiguity must never resolve by iteration order.

The rules

1. Exact (model_type, Some(hidden_size)) declarations beat wildcard (model_type, None) declarations (unchanged).
2. Within the winning tier, if exactly ONE target (by name) matches, it is selected (unchanged — covers every non-colliding model).
3. If SEVERAL differently-named targets match, the tie is broken by the checkpoint reference: each colliding target declares explicit match_names needles in its MODEL.toml ([model] match_names), and a candidate survives when any needle is a case-insensitive substring of any reference (HF id, --model-name, resolved model dir). Exactly one survivor wins — and the selection is explicit, because the needles are declared per target, not inferred.
4. Anything else — zero or multiple survivors — is TargetResolveError::Ambiguous. It never falls through to the wildcard tier and never picks by order.
5. --kernel-target <name> pins resolution to a named target, bypassing the tie-break — but the pinned target must still declare compatibility with the checkpoint’s (model_type, hidden_size), otherwise TargetResolveError::PinIncompatible. This is the escape hatch for checkpoints whose references carry no identity (e.g. --model-from-path /model).

build.rs enforces at compile time that every set of differently-named targets sharing a (model_type, hidden_size) declaration carries explicit match_names, so rule 3 can never reach a colliding target with nothing declared.

Structs

ResolveCandidate

The resolution-relevant slice of one compiled target. Borrowed views so tests can drive the rules with synthetic declarations and production wraps TargetPtxSets without copying module blobs.

Enums

TargetResolveError

Why resolution could not choose a target. Every variant is a hard error at the call site — resolution must never fall back to iteration order.

Functions

ptx_for_config

Find the PTX module set matching a checkpoint.

ptx_for_exact_target

The compiled target with exactly this (model, quant) identity.

resolve_pinned

Resolve a --kernel-target pin: the named target wins unconditionally over the tie-break, but must exist and must declare the checkpoint’s (model_type, hidden_size) (exact or wildcard).

resolve_target

Resolve which candidate serves (model_type, hidden_size) for a checkpoint identified by model_refs. Returns the index of the winning candidate, Ok(None) when nothing declares the pair at all, and TargetResolveError::Ambiguous when a collision cannot be broken to exactly one target name.