feat(config): bind catalog and route resolution

[Hmbown]

Summary

• Bind each compiled provider catalog to the exact RouteResolver projected from it.
• Return an honest receipt for catalog-backed, custom-endpoint, and unlisted pass-through routes.
• Preserve cache health only when an explicit secret-free scope status is supplied.

Closes #5755 (Phase 1 contract only). This does not claim provider readiness, credential validity, endpoint health, or UI/runtime migration.

Verification

• scripts/dev-test.sh config — 628 passed, 1 skipped
• cargo nextest run -p codewhale-config --lib authority::tests --locked — 4 passed
• cargo clippy -p codewhale-config --lib --tests --locked -- -D warnings
• cargo test -p codewhale-config --doc --locked — 1 passed

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-31T00:29:30.143082Z	860f522	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @Hmbown's task in 2m 43s —— View job

---

Review: feat(config): bind catalog and route resolution

• Gather context (diff, changed files, AGENTS.md contracts)
• Read crates/config/src/route/authority.rs and mod.rs changes
• Check correctness (panics, unwraps, exhaustive matches)
• Check provider/model/route safety invariant (EPIC v0.8.65 EPIC: Separate provider facts, model facts, offerings, and route resolution #2608)
• Check reuse/simplification vs existing route/config code
• Check test coverage
• Check security (secrets, scope status handling)
• Post final review

Summary

This is a clean, well-scoped Phase 1 addition: RouteAuthoritySnapshot binds a compiled CatalogSnapshot to the RouteResolver projected from it, and CatalogOfferingReceipt gives callers honest provenance (Catalog / CustomEndpoint / NotCataloged). It isn't wired into any consumer yet, matches the PR's stated "Phase 1 contract only" scope, and the four new tests exercise the three receipt kinds plus explicit scope-status defaulting to Unknown. No secrets are touched — RouteCatalogScope only carries a provider string and an already-redacted fingerprint, matching the doc comment.

Correctness finding

authority.rs:176 — CustomEndpoint classification diverges from the resolver's own definition, and can misreport a catalog-backed route as unverified.

let receipt = if request.base_url_override.is_some() {
    CatalogOfferingReceipt::CustomEndpoint { .. }
} ...

The resolver does not treat every base_url_override as "custom." resolver.rs's request_uses_custom_endpoint (used to decide whether to clear catalog capabilities/pricing) only returns true when the override differs from the provider's official base URL, via provider_preserves_custom_base_url_model → base_url_is_custom_for_provider (crates/config/src/lib.rs:4883-4896). If a caller supplies base_url_override equal to the provider's official endpoint, the resolver keeps the full catalog-derived capabilities/pricing (nothing is cleared) — yet RouteAuthoritySnapshot::resolve will still report CustomEndpoint, discarding the exact, accurate CatalogOffering match.

This isn't a hypothetical: crates/tui/src/client.rs:1401/1453/2144 always call the resolver with base_url_override: Some(self.base_url.clone()), regardless of whether that URL is the provider's default. Once this snapshot type is adopted by a real caller (per its own module doc, that's the whole point of the seam), routes for providers running on their official URL would get mislabeled CustomEndpoint instead of Catalog — directly undermining the "honest receipt" goal stated in the module doc and PR summary.

Suggested fix: reuse the resolver's own notion of "custom" instead of re-deriving it. ReadyRouteCandidate already exposes provider_kind() (candidate.rs:257), so this could become:

let receipt = if request.base_url_override.as_deref().is_some_and(|url| {
    crate::provider_preserves_custom_base_url_model(candidate.provider_kind(), url)
}) { ... }

(or better, have the resolver surface its custom_endpoint decision on ReadyRouteCandidate so both call sites share one source of truth instead of two independent implementations of "is this a custom endpoint").

Fix this →

Minor / test coverage

• No test exercises base_url_override set to a provider's official default URL — the exact case above. Worth adding once the classification is fixed, to lock in the corrected behavior.
• CatalogSnapshot's dedup-by-(provider, wire_model_id) guarantee (relied on by the .find() in resolve) is enforced by CatalogCompiler::compile — confirmed this holds, so the .find() correctly returns the single de-duplicated, precedence-resolved row rather than an arbitrary layer match.

Provider/route safety (EPIC #2608)

No prefix-based provider/model inference introduced. CustomEndpoint/NotCataloged receipts correctly avoid presenting unverified facts as catalog truth (aside from the classification bug above), and the doc comments are explicit that a catalog row is not proof of runnability/auth/health.

Note on verification

I was not able to execute cargo test/cargo nextest in this sandbox (command approval unavailable), so the above is based on static reading of authority.rs, resolver.rs, and catalog.rs, not a re-run of the suite. The PR's reported 627 passed, 1 skipped plus the 4 new-test run were not independently reproduced here.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 860f5228d3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Classify only genuinely custom endpoint overrides

When base_url_override names an official endpoint—such as https://api.deepseek.com/v1 or another accepted URL in the provider's official endpoint family—the resolver treats it as non-custom and retains the matched catalog facts, but this unconditional is_some() returns CustomEndpoint and hides the exact offering. Use the resolver's official/custom endpoint classification here as well so the receipt agrees with the candidate's provenance.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Scope live offerings to the resolved endpoint

When a snapshot contains live rows for the same provider from multiple base-URL fingerprints—which ProviderCatalogCache explicitly supports—projecting every row into one resolver drops that endpoint scope. A request for the provider's default endpoint can consequently resolve using a row fetched from a different custom endpoint and inherit its endpoint key, limits, capabilities, and pricing; the authority should filter live offerings to the request's base-URL fingerprint (while retaining endpoint-independent layers) before resolution.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve curated transport offerings in the authority

When this authority is built from the normal bundled catalog snapshot, catalog.to_offerings() omits the curated route::bundled_offerings() seam that RouteResolver::new() deliberately gives precedence for transport facts. For example, the Models.dev-shaped DeepSeek Flash row is projected with endpoint_key = "chat" instead of its required Responses route, and the bundled asset has no OpenCode Zen provider rows at all, so migrating those routes to this advertised replacement either selects the wrong protocol or rejects supported Zen models. Merge the curated transport offerings with the catalog projection using the same precedence as the default resolver.

Useful? React with 👍 / 👎.

[codewhale-agent]

Codewhale review

PR #5766 adds RouteAuthoritySnapshot to pair a compiled CatalogSnapshot with its RouteResolver, plus provenance receipts for resolved routes. The core direct/custom/pass-through tests are present and the API is generally coherent.

Findings

• [WARNING] Deserialize bypasses RouteCatalogScope normalization (crates/config/src/route/authority.rs:34)
  RouteCatalogScope::new trims both fields, but the derived Deserialize implementation populates the private fields directly and does not call new. JSON containing whitespace such as {"provider":" deepseek ","base_url_fingerprint":" fingerprint-a "} will produce a key that does not compare equal to the same scope created via new, causing scope_status BTreeMap lookups to miss. If deserialization is part of the public contract, implement a custom deserializer or validate/normalize after deserialization; otherwise remove Deserialize.
• [WARNING] Catalog receipt matching ignores endpoint_key (crates/config/src/route/authority.rs:181)
  resolve() determines the Catalog receipt by matching only provider and wire_model_id. If the compiled catalog can contain more than one offering for the same provider/wire pair with different endpoint_key values, the first match may not be the offering the resolver actually selected. This can make the receipt point at different limits/pricing/source than the executable candidate. Prefer using an effective-offering lookup/index from the resolver, or include endpoint_key in the comparison, and add a multi-endpoint test.
• [INFO] Missing tests for public serde shape and status replacement (crates/config/src/route/authority.rs:291)
  CatalogOfferingReceipt is a public Serialize type with an internal tag, but there is no test asserting the kind strings ("catalog", "custom_endpoint", "not_cataloged") or that a later with_scope_status call overwrites an earlier value. These are low-cost tests for a public contract.

Assessment

The API is a reasonable phase 1 seam and the included tests cover the primary direct/custom/pass-through cases. Address the deserialization normalization and offering-lookup precision issues before exposing the receipt in production; otherwise it may report a coherent-looking but incorrect receipt.

---

Advisory review by Codewhale (codewhale review --pr 5766 --post, head 860f5228d364c58f92f2519d0c172b137c35517c). Line-specific findings are also posted as inline review comments; mechanical fixes arrive as committable suggestions you can apply from the Files tab. CODEOWNERS approval still governs merge.

[codewhale-agent]

[WARNING] Deserialize bypasses RouteCatalogScope normalization

RouteCatalogScope::new trims both fields, but the derived Deserialize implementation populates the private fields directly and does not call new. JSON containing whitespace such as {"provider":" deepseek ","base_url_fingerprint":" fingerprint-a "} will produce a key that does not compare equal to the same scope created via new, causing scope_status BTreeMap lookups to miss. If deserialization is part of the public contract, implement a custom deserializer or validate/normalize after deserialization; otherwise remove Deserialize.

[codewhale-agent]

[WARNING] Catalog receipt matching ignores endpoint_key

resolve() determines the Catalog receipt by matching only provider and wire_model_id. If the compiled catalog can contain more than one offering for the same provider/wire pair with different endpoint_key values, the first match may not be the offering the resolver actually selected. This can make the receipt point at different limits/pricing/source than the executable candidate. Prefer using an effective-offering lookup/index from the resolver, or include endpoint_key in the comparison, and add a multi-endpoint test.

[codewhale-agent]

[INFO] Missing tests for public serde shape and status replacement

CatalogOfferingReceipt is a public Serialize type with an internal tag, but there is no test asserting the kind strings ("catalog", "custom_endpoint", "not_cataloged") or that a later with_scope_status call overwrites an earlier value. These are low-cost tests for a public contract.