Module router_resolve 

Path resolution algorithm per ADR-021 §2.

Given a RouterConfig and a SecretPath, decide which source serves the path and what context the source needs to produce a reference. The decision is pure data — no source plugin is invoked here. Turning the decision into an actual (source, reference) pair is the next layer’s job (P5.4 wires the cache + plugin lookup; P6 ships the concrete sources).

Splitting the resolver from the source-call layer lets tests exercise the routing rules with TOML fixtures alone, without standing up real backends. doctor (P7.2 / P10.1) reuses the same pure function to pre-flight a project’s manifest against the active config.

Algorithm

Per ADR-021 §2:

1. Per-secret override. If [secret."<path>"] matches the queried path, return RouteDecision::Explicit with the user-supplied source + reference. Wins over everything else.
2. Longest prefix. Walk [[route]] blocks; pick the one whose prefix is the longest string that the queried path starts with. Return RouteDecision::Prefix with the route’s source name + verbatim settings. Source-specific path-tail-to-reference mapping (Vault joins mount + tail, 1Password builds an op:// URL, …) is delegated to the plugin.
3. Default route. No [secret] and no [[route]] matched. Return RouteDecision::Default carrying the default source + the optional fallback hint (used by the caller’s is_available() == NotInstalled retry — see ADR-021 §2 step 3).
4. No fall-through. No matching [secret], no matching [[route]], and no [default] either: fail with ResolveError::NoRoute.

Prefix [[route]] already enforces a trailing / at config load (router_config::RouterConfigError::BadRoutePrefix), so the resolver does not have to worry about partial-segment matches like team/ vs teamfoo/x.

Ties between routes of equal length resolve by declaration order — earlier [[route]] wins. That’s deterministic and matches what the user sees when they read the file top to bottom.

Structs

PathResolver

Read-only view over a RouterConfig that answers “which source serves this path?” without invoking any source plugin.

Enums

ResolveError

Failure modes for PathResolver::resolve.

RouteDecision

Outcome of resolving a path against a RouterConfig.