@cats-inc/cats-platform 0.1.21 → 0.3.4

package/build/server/server/routes/providers.js

@@ -1,12 +1,11 @@
-import { isKnownProvider, listProductProviders, } from '../../shared/providerCatalog.js';
+import { isKnownProvider, providerInstanceTarget, listProductProviders, } from '../../shared/providerCatalog.js';
+import { resolveSelectedProviderInstance } from '../../shared/providerSelection.js';
 import { createEmptyProviderSnapshot, loadProviderSnapshot, writeProviderSnapshot, } from './providerSnapshotStore.js';
 const PROVIDER_SNAPSHOT_DEBOUNCE_MS = 1_000;
 const PROVIDER_SNAPSHOT_FLUSH_INFLIGHT_TIMEOUT_MS = 2_000;
-const PROVIDER_CACHE_STALE_IF_ERROR_MS = 10 * 60_000;
 const PROVIDER_CACHE_ERROR_BACKOFF_MS = 30_000;
 const TRUTHFUL_SELECTOR_CACHE_TTL_MS = 30_000;
 const TRUTHFUL_SELECTOR_STALE_WINDOW_MS = 15_000;
-const TRUTHFUL_SELECTOR_CONFIG_ENRICHMENT_BUDGET_MS = 500;
 const PROVIDER_MODEL_CATALOG_CACHE_TTL_MS = 60_000;
 const PROVIDER_MODEL_CATALOG_STALE_WINDOW_MS = 5 * 60_000;
 export const PROVIDER_TARGETS_CACHE_REFRESH_WARNING_PREFIX = 'Using cached provider targets because runtime refresh failed:';
@@ -190,13 +189,11 @@ function seedTruthfulProviderRegistryFromSnapshot(runtimeClient, snapshot) {
     if (cacheState.entries.has(cacheKey)) {
         return;
     }
-    const now = Date.now();
     cacheState.entries.set(cacheKey, {
         lifecycle: 'error_backoff',
         value: snapshot.registry,
         freshUntilMs: 0,
         staleUntilMs: 0,
-        staleIfErrorUntilMs: now + PROVIDER_CACHE_STALE_IF_ERROR_MS,
         cacheRefreshWarning: {
             kind: 'provider-targets',
             message: 'Using last saved provider targets while cats-runtime reconnects.',
@@ -208,7 +205,6 @@ function seedProviderCatalogsFromSnapshot(runtimeClient, snapshot) {
         return;
     }
     const cacheState = getProviderCatalogCacheState(runtimeClient);
-    const now = Date.now();
     for (const entry of snapshot.catalogs) {
         const cacheKey = buildProviderCatalogCacheKey({
             provider: entry.provider,
@@ -220,7 +216,6 @@ function seedProviderCatalogsFromSnapshot(runtimeClient, snapshot) {
                 value: entry.models,
                 freshUntilMs: 0,
                 staleUntilMs: 0,
-                staleIfErrorUntilMs: now + PROVIDER_CACHE_STALE_IF_ERROR_MS,
                 cacheRefreshWarning: {
                     kind: 'model-catalog',
                     message: 'Using last saved model catalog while cats-runtime reconnects.',
@@ -233,7 +228,6 @@ function seedProviderCatalogsFromSnapshot(runtimeClient, snapshot) {
                 value: entry.advanced,
                 freshUntilMs: 0,
                 staleUntilMs: 0,
-                staleIfErrorUntilMs: now + PROVIDER_CACHE_STALE_IF_ERROR_MS,
                 cacheRefreshWarning: {
                     kind: 'model-catalog',
                     message: 'Using last saved model catalog while cats-runtime reconnects.',
@@ -266,10 +260,7 @@ export async function warmProviderSelectorCache(runtimeClient) {
     }
     const catalogCacheState = getProviderCatalogCacheState(runtimeClient);
     await Promise.allSettled(registry.providers.map(async (provider) => {
-        const defaultInstanceId = provider.defaultInstance
-            ?? provider.instances.find((candidate) => candidate.default)?.id
-            ?? provider.instances[0]?.id
-            ?? null;
+        const defaultInstanceId = resolveSelectedProviderInstance(provider, '') || null;
         if (!defaultInstanceId) {
             return;
         }
@@ -311,7 +302,7 @@ function listSelectableDiagnosticsForProvider(payload, providerId) {
         .filter((entry) => isSelectableAvailabilityStatus(entry.availability.status));
 }
 function findInstanceDiagnostic(entries, instanceId, backend) {
-    return entries.find((entry) => entry.instance === instanceId)
+    return entries.find((entry) => entry.instance === instanceId && entry.backend === backend)
         ?? entries.find((entry) => entry.instance === null
             && backend !== null
             && entry.backend === backend)
@@ -332,7 +323,7 @@ function mergeTruthfulProviderRegistryFromRuntimeConfig(provider, runtimeConfig,
         label: instance.target ?? instance.id,
         target: instance.target,
         backend: instance.backend,
-        default: runtimeProvider.defaultInstance === instance.id,
+        default: runtimeProvider.defaultInstance === instance.id && runtimeProvider.defaultBackend === instance.backend,
         eventCapabilities: instance.eventCapabilities,
     }));
     if (instances.length === 0) {
@@ -352,65 +343,6 @@ function mergeTruthfulProviderRegistryFromRuntimeConfig(provider, runtimeConfig,
         instances,
     };
 }
-function resolveDiagnosticsInstanceId(entry) {
-    return entry.instance?.trim()
-        || entry.backend?.trim()
-        || 'default';
-}
-function resolveDiagnosticsInstanceTarget(entry) {
-    const instanceId = entry.instance?.trim() || '';
-    const backend = entry.backend?.trim() || '';
-    if (instanceId) {
-        if (instanceId.includes('/')) {
-            return instanceId;
-        }
-        return backend ? `${backend}/${instanceId}` : instanceId;
-    }
-    return backend ? `${backend}/default` : null;
-}
-function resolveDiagnosticsInstanceLabel(entry) {
-    return resolveDiagnosticsInstanceTarget(entry)
-        ?? entry.backend?.trim()
-        ?? 'default';
-}
-function buildDiagnosticsOnlyProviderDescriptor(provider, diagnosticsEntries) {
-    const instancesById = new Map();
-    for (const entry of diagnosticsEntries) {
-        const instanceId = resolveDiagnosticsInstanceId(entry);
-        const staticInstance = provider.instances.find((candidate) => candidate.id === instanceId
-            || (candidate.target !== null
-                && candidate.target === resolveDiagnosticsInstanceTarget(entry)));
-        const target = staticInstance?.target ?? resolveDiagnosticsInstanceTarget(entry);
-        instancesById.set(instanceId, {
-            id: instanceId,
-            label: staticInstance?.label ?? resolveDiagnosticsInstanceLabel(entry),
-            target,
-            backend: staticInstance?.backend ?? entry.backend,
-            default: entry.defaultTarget,
-            eventCapabilities: staticInstance?.eventCapabilities ?? null,
-        });
-    }
-    const instances = [...instancesById.values()];
-    if (instances.length === 0) {
-        return null;
-    }
-    const defaultInstance = instances.find((instance) => instance.default)?.id
-        ?? instances.find((instance) => instance.id === provider.defaultInstance)?.id
-        ?? instances[0]?.id
-        ?? null;
-    const defaultBackend = instances.find((instance) => instance.id === defaultInstance)?.backend
-        ?? instances[0]?.backend
-        ?? provider.defaultBackend;
-    return {
-        ...provider,
-        defaultInstance,
-        defaultBackend,
-        instances: instances.map((instance) => ({
-            ...instance,
-            default: instance.id === defaultInstance,
-        })),
-    };
-}
 function mergeTruthfulProviderRegistry(productProviders, runtimeConfig, diagnostics) {
     return productProviders.flatMap((provider) => {
         const diagnosticsEntries = listSelectableDiagnosticsForProvider(diagnostics, provider.id);
@@ -423,8 +355,7 @@ function mergeTruthfulProviderRegistry(productProviders, runtimeConfig, diagnost
         if (merged) {
             return [merged];
         }
-        const diagnosticsOnly = buildDiagnosticsOnlyProviderDescriptor(provider, diagnosticsEntries);
-        return diagnosticsOnly ? [diagnosticsOnly] : [];
+        return [];
     });
 }
 function getTruthfulProviderRegistryCacheState(runtimeClient) {
@@ -440,12 +371,9 @@ function getTruthfulProviderRegistryCacheState(runtimeClient) {
 }
 const TRUTHFUL_PROVIDER_REGISTRY_CACHE_KEY = '*';
 function shouldCacheTruthfulProviderRegistry(value) {
-    // Only 'ready' is authoritative enough for the full TTL+stale window.
-    // 'no_usable_targets' might be transient (e.g. runtime config reload mid-
-    // probe) — we don't want it to displace a recently-good baseline for 30s.
-    // 'runtime_unreachable' is the explicit failure state. Both fall through
-    // to the stale-fallback / short-backoff path below.
-    return value.state === 'ready';
+    // A successful empty read is authoritative too. Only transport failure
+    // retains the previous observation; elapsed time does not authorize it.
+    return value.state !== 'runtime_unreachable';
 }
 function appendProviderCacheWarning(warnings, warning) {
     const existing = Array.isArray(warnings) ? warnings : [];
@@ -475,7 +403,6 @@ function writeProviderCacheErrorBackoff(cached, cacheRefreshWarning, appendWarni
         lifecycle: 'error_backoff',
         freshUntilMs: now + PROVIDER_CACHE_ERROR_BACKOFF_MS,
         staleUntilMs: Math.max(cached.staleUntilMs, now + PROVIDER_CACHE_ERROR_BACKOFF_MS),
-        staleIfErrorUntilMs: cached.staleIfErrorUntilMs,
         cacheRefreshWarning,
     });
     return appendWarning(cached.value, cacheRefreshWarning.message);
@@ -512,6 +439,7 @@ function deriveTruthfulProviderRegistryForProvider(source, providerId) {
     const provider = source.providers.find((entry) => entry.id === providerId);
     if (!provider) {
         return {
+            revision: source.revision,
             state: 'no_usable_targets',
             providers: [],
             recovery: {
@@ -523,12 +451,10 @@ function deriveTruthfulProviderRegistryForProvider(source, providerId) {
     return {
         state: 'ready',
         providers: [provider],
+        revision: source.revision,
         ...(source.warnings ? { warnings: [...source.warnings] } : {}),
     };
 }
-async function readProviderConfig(dependencies) {
-    return dependencies.runtimeClient.getProviderConfig({ selector: true });
-}
 async function readProviderDiagnostics(dependencies, options = {}) {
     return dependencies.runtimeClient.getProviderDiagnostics({
         ...(options.provider?.trim() ? { provider: options.provider.trim() } : {}),
@@ -536,25 +462,15 @@ async function readProviderDiagnostics(dependencies, options = {}) {
     });
 }
 async function readProviderConfigBestEffort(dependencies) {
-    const task = readProviderConfig(dependencies)
-        .then((value) => ({
-        status: 'fulfilled',
-        value,
-    }))
-        .catch(() => ({
-        status: 'rejected',
-    }));
-    const timeoutToken = Symbol('selector-config-timeout');
-    const winner = await Promise.race([
-        task,
-        new Promise((resolve) => {
-            setTimeout(() => resolve(timeoutToken), TRUTHFUL_SELECTOR_CONFIG_ENRICHMENT_BUDGET_MS);
-        }),
-    ]);
-    if (winner === timeoutToken) {
+    try {
+        // Topology is required to establish the first usable selector snapshot.
+        // Let the Runtime client's request deadline bound this read; a shorter
+        // enrichment race discards healthy slow responses on every cold retry.
+        return await dependencies.runtimeClient.getProviderConfig({ selector: true });
+    }
+    catch {
         return null;
     }
-    return winner.status === 'fulfilled' ? winner.value : null;
 }
 async function loadTruthfulProviderRegistryFromRuntime(dependencies, options = {}) {
     const requestedProvider = options.provider?.trim() || null;
@@ -589,7 +505,11 @@ async function loadTruthfulProviderRegistryFromRuntime(dependencies, options = {
         };
     }
     const runtimeConfig = await configTask;
-    const providers = mergeTruthfulProviderRegistry(configuredProductProviders, runtimeConfig ?? null, diagnostics);
+    if (!runtimeConfig) {
+        return { state: 'runtime_unreachable', providers: [], recovery: { retryable: true },
+            warnings: ['Runtime provider configuration is unavailable.'] };
+    }
+    const providers = mergeTruthfulProviderRegistry(configuredProductProviders, runtimeConfig, diagnostics);
     if (providers.length === 0) {
         return {
             state: 'no_usable_targets',
@@ -604,7 +524,52 @@ async function loadTruthfulProviderRegistryFromRuntime(dependencies, options = {
         providers,
     };
 }
+function syncProviderSelectionCache(client, selection) {
+    const state = getTruthfulProviderRegistryCacheState(client);
+    if (state.revision !== selection.revision) {
+        state.entries.clear();
+        state.inflight.clear();
+        providerCatalogCache.delete(client);
+        state.revision = selection.revision;
+    }
+    return state;
+}
+function projectSelectedProviders(value, selection) {
+    const selected = new Set(selection.targets.map((target) => JSON.stringify([target.provider, target.backend, target.instance])));
+    const providers = value.providers.flatMap((provider) => {
+        const instances = provider.instances.filter((instance) => selected.has(JSON.stringify([provider.id, instance.backend, instance.id])));
+        if (!instances.length)
+            return [];
+        const defaultTarget = instances.find((instance) => instance.default) ?? instances[0];
+        return [{ ...provider, instances: instances.map((instance) => ({ ...instance, default: instance === defaultTarget })),
+                defaultInstance: defaultTarget.id, defaultBackend: defaultTarget.backend }];
+    });
+    return { ...value, revision: selection.revision, providers,
+        state: providers.length ? 'ready' : value.state === 'runtime_unreachable' ? value.state : 'no_usable_targets',
+        ...(providers.length ? {} : { recovery: { openRuntimeSetupPath: '/runtime/setup' } }) };
+}
+async function currentSelection(dependencies) {
+    const { selection } = await dependencies.runtimeClient.getSetupState();
+    if (!selection || !Array.isArray(selection.targets))
+        throw new Error('Runtime provider selection is unavailable.');
+    syncProviderSelectionCache(dependencies.runtimeClient, selection);
+    return selection;
+}
+function unavailableSelection() {
+    return { state: 'runtime_unreachable', providers: [], recovery: { retryable: true },
+        warnings: ['Cannot verify the connected Runtime provider selection.'] };
+}
 async function refreshTruthfulProviderRegistry(dependencies, cacheState, options = {}) {
+    let selection;
+    try {
+        selection = await currentSelection(dependencies);
+    }
+    catch {
+        return unavailableSelection();
+    }
+    if (selection.state !== 'selected') {
+        return projectSelectedProviders({ state: 'no_usable_targets', providers: [] }, selection);
+    }
     const cacheKey = TRUTHFUL_PROVIDER_REGISTRY_CACHE_KEY;
     if (!options.force) {
         const inflight = cacheState.inflight.get(cacheKey);
@@ -614,7 +579,18 @@ async function refreshTruthfulProviderRegistry(dependencies, cacheState, options
     }
     let refreshPromise;
     refreshPromise = loadTruthfulProviderRegistryFromRuntime(dependencies)
-        .then((value) => {
+        .then(async (loaded) => {
+        let latest;
+        try {
+            latest = await currentSelection(dependencies);
+        }
+        catch {
+            return unavailableSelection();
+        }
+        if (latest.revision !== selection.revision) {
+            return projectSelectedProviders({ state: 'no_usable_targets', providers: [] }, latest);
+        }
+        const value = projectSelectedProviders(loaded, latest);
         // Stale-probe guard: if a parallel forced refresh has replaced us as
         // the current inflight probe (or already finished and cleaned up), our
         // value is stale by definition. Don't write it to the cache — that
@@ -634,13 +610,12 @@ async function refreshTruthfulProviderRegistry(dependencies, cacheState, options
                 value,
                 freshUntilMs: now + TRUTHFUL_SELECTOR_CACHE_TTL_MS,
                 staleUntilMs: now + TRUTHFUL_SELECTOR_CACHE_TTL_MS + TRUTHFUL_SELECTOR_STALE_WINDOW_MS,
-                staleIfErrorUntilMs: now + PROVIDER_CACHE_STALE_IF_ERROR_MS,
             });
             notifyProviderCacheUpdated(dependencies.runtimeClient);
             return value;
         }
         const cached = cacheState.entries.get(cacheKey);
-        if (cached && cached.staleIfErrorUntilMs > now) {
+        if (cached) {
             return writeTruthfulProviderRegistryErrorBackoff(cacheState, cacheKey, cached, value);
         }
         // With no prior ready baseline, do not turn a cold runtime failure into
@@ -660,14 +635,24 @@ async function refreshTruthfulProviderRegistry(dependencies, cacheState, options
     return refreshPromise;
 }
 async function readTruthfulProviderRegistry(dependencies, options = {}) {
+    let selection;
+    try {
+        selection = await currentSelection(dependencies);
+    }
+    catch {
+        return unavailableSelection();
+    }
+    if (selection.state !== 'selected') {
+        return projectSelectedProviders({ state: 'no_usable_targets', providers: [] }, selection);
+    }
     const cacheState = getTruthfulProviderRegistryCacheState(dependencies.runtimeClient);
     const cacheKey = TRUTHFUL_PROVIDER_REGISTRY_CACHE_KEY;
     const now = Date.now();
     const cached = cacheState.entries.get(cacheKey);
     const requestedProvider = options.provider?.trim() || null;
     const project = (value) => requestedProvider
-        ? deriveTruthfulProviderRegistryForProvider(value, requestedProvider)
-        : value;
+        ? deriveTruthfulProviderRegistryForProvider(projectSelectedProviders(value, selection), requestedProvider)
+        : projectSelectedProviders(value, selection);
     if (cached && cached.freshUntilMs > now) {
         return project(readProviderCacheValue(cached, appendTruthfulProviderRegistryWarning));
     }
@@ -675,7 +660,9 @@ async function readTruthfulProviderRegistry(dependencies, options = {}) {
         void refreshTruthfulProviderRegistry(dependencies, cacheState).catch(() => { });
         return project(readProviderCacheValue(cached, appendTruthfulProviderRegistryWarning));
     }
-    if (cached && cached.staleIfErrorUntilMs > now) {
+    // Expiry triggers refresh, not loss of the last successful result. The
+    // selection check above invalidates all entries when intent changes.
+    if (cached) {
         void refreshTruthfulProviderRegistry(dependencies, cacheState).catch(() => { });
         return project(appendTruthfulProviderRegistryWarning(readProviderCacheValue(cached, appendTruthfulProviderRegistryWarning), PROVIDER_TARGETS_CACHE_REVALIDATION_WARNING));
     }
@@ -687,7 +674,12 @@ async function readTruthfulProviderRegistry(dependencies, options = {}) {
         // slots ahead of the scoped request and recreate the 8s timeout risk.
         const scopedRegistry = await loadTruthfulProviderRegistryFromRuntime(dependencies, { provider: requestedProvider });
         void refreshTruthfulProviderRegistry(dependencies, cacheState).catch(() => { });
-        return scopedRegistry;
+        const latest = await currentSelection(dependencies).catch(() => null);
+        if (!latest)
+            return unavailableSelection();
+        return latest.revision === selection.revision
+            ? project(scopedRegistry)
+            : projectSelectedProviders({ state: 'no_usable_targets', providers: [] }, latest);
     }
     return project(await refreshTruthfulProviderRegistry(dependencies, cacheState));
 }
@@ -732,7 +724,6 @@ function writeProviderCatalogCacheEntry(cacheState, cacheKey, value) {
         staleUntilMs: now
             + PROVIDER_MODEL_CATALOG_CACHE_TTL_MS
             + PROVIDER_MODEL_CATALOG_STALE_WINDOW_MS,
-        staleIfErrorUntilMs: now + PROVIDER_CACHE_STALE_IF_ERROR_MS,
     });
 }
 function writeProviderCatalogErrorBackoff(cacheState, cacheKey, cached, error) {
@@ -741,13 +732,6 @@ function writeProviderCatalogErrorBackoff(cacheState, cacheKey, cached, error) {
         message: `${MODEL_CATALOG_CACHE_REFRESH_WARNING_PREFIX} ${readRuntimeFailureMessage(error, 'Runtime catalog unavailable.')}`,
     }, appendProviderCatalogWarning, (entry) => cacheState.entries.set(cacheKey, entry));
 }
-function pruneExpiredProviderCatalogCacheEntries(cacheState, now) {
-    for (const [cacheKey, cached] of cacheState.entries) {
-        if (cached.staleIfErrorUntilMs <= now && !cacheState.inflight.has(cacheKey)) {
-            cacheState.entries.delete(cacheKey);
-        }
-    }
-}
 function refreshProviderCatalogCacheEntry(cacheState, cacheKey, load, runtimeClient) {
     const inflight = cacheState.inflight.get(cacheKey);
     if (inflight) {
@@ -764,8 +748,7 @@ function refreshProviderCatalogCacheEntry(cacheState, cacheKey, load, runtimeCli
         .catch((error) => {
         const cached = readProviderCatalogCacheEntry(cacheState, cacheKey);
         if (shouldServeStaleProviderCatalogForError(error)
-            && cached
-            && cached.staleIfErrorUntilMs > Date.now()) {
+            && cached) {
             return writeProviderCatalogErrorBackoff(cacheState, cacheKey, cached, error);
         }
         throw error;
@@ -779,7 +762,6 @@ function refreshProviderCatalogCacheEntry(cacheState, cacheKey, load, runtimeCli
 async function readProviderCatalogCached(input) {
     const cacheKey = buildProviderCatalogCacheKey(input);
     const now = Date.now();
-    pruneExpiredProviderCatalogCacheEntries(input.cacheState, now);
     const cached = readProviderCatalogCacheEntry(input.cacheState, cacheKey);
     if (cached && cached.freshUntilMs > now) {
         return readProviderCacheValue(cached, appendProviderCatalogWarning);
@@ -788,7 +770,7 @@ async function readProviderCatalogCached(input) {
         void refreshProviderCatalogCacheEntry(input.cacheState, cacheKey, input.load, input.runtimeClient).catch(() => { });
         return readProviderCacheValue(cached, appendProviderCatalogWarning);
     }
-    if (cached && cached.staleIfErrorUntilMs > now) {
+    if (cached) {
         void refreshProviderCatalogCacheEntry(input.cacheState, cacheKey, input.load, input.runtimeClient).catch(() => { });
         return appendProviderCatalogWarning(readProviderCacheValue(cached, appendProviderCatalogWarning), MODEL_CATALOG_CACHE_REVALIDATION_WARNING);
     }
@@ -834,8 +816,8 @@ export async function handleProviderModels(response, dependencies, provider, ins
         sendRestError(response, 409, 'provider_target_unavailable', `No usable ${provider} target is currently available in cats-runtime.`, { provider, instance: instance ?? null });
         return;
     }
-    const normalizedInstance = instance?.trim() || null;
-    if (normalizedInstance && !providerDescriptor.instances.some((entry) => entry.id === normalizedInstance)) {
+    const normalizedInstance = resolveRequestedInstance(providerDescriptor, instance);
+    if (!normalizedInstance) {
         sendRestError(response, 409, 'provider_target_unavailable', `${provider} instance "${normalizedInstance}" is not currently usable in cats-runtime.`, { provider, instance: normalizedInstance });
         return;
     }
@@ -848,7 +830,12 @@ export async function handleProviderModels(response, dependencies, provider, ins
             load: () => dependencies.runtimeClient.getProviderModels(provider, normalizedInstance),
             runtimeClient: dependencies.runtimeClient,
         });
-        sendJson(response, 200, { catalog });
+        const latest = await currentSelection(dependencies);
+        if (latest.revision !== registry.revision) {
+            sendRestError(response, 409, 'provider_selection_changed', 'Provider selection changed. Refresh the provider list.');
+            return;
+        }
+        sendJson(response, 200, { catalog: { ...catalog, instance: normalizedInstance } });
     }
     catch (error) {
         const runtimeError = error;
@@ -859,6 +846,13 @@ export async function handleProviderModels(response, dependencies, provider, ins
         sendRestError(response, 503, 'provider_catalog_unavailable', error instanceof Error ? error.message : 'Runtime catalog unavailable.', { provider, instance: normalizedInstance });
     }
 }
+function resolveRequestedInstance(provider, instance) {
+    const requested = instance?.trim();
+    if (!requested)
+        return resolveSelectedProviderInstance(provider, '') || null;
+    const matches = provider.instances.filter((target) => providerInstanceTarget(target) === requested || target.id === requested);
+    return matches.length === 1 ? providerInstanceTarget(matches[0]) : null;
+}
 export async function handleAdvancedProviderModels(response, dependencies, provider, instance) {
     if (!isKnownProvider(provider)) {
         sendRestError(response, 404, 'provider_not_found', `Provider not found: ${provider}`);
@@ -874,8 +868,8 @@ export async function handleAdvancedProviderModels(response, dependencies, provi
         sendRestError(response, 409, 'provider_target_unavailable', `No usable ${provider} target is currently available in cats-runtime.`, { provider, instance: instance ?? null });
         return;
     }
-    const normalizedInstance = instance?.trim() || null;
-    if (normalizedInstance && !providerDescriptor.instances.some((entry) => entry.id === normalizedInstance)) {
+    const normalizedInstance = resolveRequestedInstance(providerDescriptor, instance);
+    if (!normalizedInstance) {
         sendRestError(response, 409, 'provider_target_unavailable', `${provider} instance "${normalizedInstance}" is not currently usable in cats-runtime.`, { provider, instance: normalizedInstance });
         return;
     }
@@ -888,7 +882,12 @@ export async function handleAdvancedProviderModels(response, dependencies, provi
             load: () => dependencies.runtimeClient.getAdvancedProviderModels(provider, normalizedInstance),
             runtimeClient: dependencies.runtimeClient,
         });
-        sendJson(response, 200, { catalog });
+        const latest = await currentSelection(dependencies);
+        if (latest.revision !== registry.revision) {
+            sendRestError(response, 409, 'provider_selection_changed', 'Provider selection changed. Refresh the provider list.');
+            return;
+        }
+        sendJson(response, 200, { catalog: { ...catalog, instance: normalizedInstance } });
     }
     catch (error) {
         const runtimeError = error;
@@ -913,10 +912,13 @@ async function refreshProviderCatalogsInternal(dependencies) {
             const task = (async () => {
                 try {
                     const [models, advanced] = await Promise.all([
-                        dependencies.runtimeClient.getProviderModels(provider.id, instance.id, { forceRefresh: true }),
-                        dependencies.runtimeClient.getAdvancedProviderModels(provider.id, instance.id, { forceRefresh: true }),
+                        dependencies.runtimeClient.getProviderModels(provider.id, providerInstanceTarget(instance), { forceRefresh: true }),
+                        dependencies.runtimeClient.getAdvancedProviderModels(provider.id, providerInstanceTarget(instance), { forceRefresh: true }),
                     ]);
-                    const cacheKey = buildProviderCatalogCacheKey({ provider: provider.id, instance: instance.id });
+                    const latest = await currentSelection(dependencies);
+                    if (latest.revision !== registry.revision)
+                        throw new Error('Provider selection changed during catalog refresh.');
+                    const cacheKey = buildProviderCatalogCacheKey({ provider: provider.id, instance: providerInstanceTarget(instance) });
                     writeProviderCatalogCacheEntry(cacheState.models, cacheKey, models);
                     writeProviderCatalogCacheEntry(cacheState.advanced, cacheKey, advanced);
                     notifyProviderCacheUpdated(dependencies.runtimeClient);