The resolution order¶

Four sources, tried in a fixed order:

1. A path the caller passed
2. A library beside the executable
3. The cache
4. The artefact channel

The order is the module's main design decision, and each rung earns its place for a different reason.

An explicit path wins, and is not checked¶

A caller who has said where their runtime is should not be second-guessed. They may be on a platform with no published build, running a distribution package, or testing a build they made themselves — all cases where this module knows less than they do.

The consequence people find surprising is that the path is not checked for existence. Falling back when it does not resolve sounds helpful and is not: a machine you configured would quietly run a different runtime, and the substitution surfaces as an inference result rather than an error. Returning the path unchecked means a wrong path produces the loader's complaint about your path.

This rung is also the documented remedy for ErrNoPlatformBuild, which is why it has to outrank everything — including the channel that would otherwise be authoritative.

Bundled beats cached¶

A library beside the executable is how a packaged application ships one. It was put there deliberately, by whoever built the package, and it is the version that package was tested against. A cached copy is merely the last thing that was downloaded.

Cached beats the network¶

The obvious rung, and the only one that is purely an optimisation. Worth stating anyway: cache entries are populated only through verification, so reading one is not a weaker check than fetching. The bytes were signature- and digest-verified on the way in.

The channel is last¶

Only reached when the first three miss, and it is the only rung that touches the network or can fail for reasons outside the machine.

Why not "try each and fall back on failure"¶

A tempting alternative: try each source, and if one fails move to the next. It is wrong in the same way for every rung. Falling through from an explicit path substitutes a runtime the caller did not choose. Falling through from a bundled library ignores the version the package was built against. Falling through from the cache would hide a corrupted entry rather than report it.

So each rung is a presence test, not an attempt: if the library is there, it is the answer, and any problem with it is reported rather than routed around. The one thing that would be silently wrong is choosing a different runtime, and that is the thing this order refuses to do.