@hyav/pi-provider 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This file is the authoritative user-facing release history for `@hyav/pi-provider`.
 
+## 0.1.8 - 2026-09-01
+
+- Make Charm Hyper model catalogs online-only: use the last successful online snapshot when refresh is unavailable and an empty catalog when no snapshot exists; remove package-maintained static model, pricing, and model-specific capability fallbacks.
+- Skip malformed individual Charm Hyper models while retaining valid entries, and use Provider metadata before OpenRouter metadata when filling model fields.
+- Add a public model-catalog lifecycle helper for cached snapshot restoration, TTL checks, generation-guarded publication, persistence fallback, complete live replacement, and failure retention; migrate Charm Hyper to it.
+- Share one model-catalog discovery request across concurrent callers with different cancellation signals, while keeping caller cancellation and generation-guarded publication independent.
+- Separate successful-catalog TTL from exponential failure backoff, expose attempt, success, failure-count, and retry diagnostics, and show retry timing in `/status`.
+- Report bounded invalid and duplicate model counts for accepted online catalogs without retaining remote model IDs or payload content.
+- Add accurately named OpenRouter metadata APIs (`fetchOfficialModelMetadata()` and `applyOfficialModelMetadata()`), migrate internal callers, and retain the pricing-named APIs as deprecated compatibility wrappers.
+- Extend field-level provenance to normalized cost and thinking-level maps while keeping `pricing.source` authoritative for known and effective pricing.
+- Normalize partial model costs before applying pricing adjustments so registered model costs and pricing sidecars remain consistent; report fields rewritten at the registration boundary as `normalized`.
+
 ## 0.1.7 - 2026-08-24
 
 - Refresh the active model catalog dynamically on `/status refresh` and `/status check` by delegating to Pi's model registry with forced network revalidation, keeping the displayed model catalog and model counts up to date without requiring `/reload`.

package/README.md

@@ -10,7 +10,7 @@ A provider extension toolkit for [Pi](https://pi.dev). It registers LLM provider
 
 - One Pi Provider Host for registration, status, preflight checks, live checks, and request tuners
 - Provider, status, preflight, and tuner Adapter files discovered by one Pi entrypoint on `/reload`
-- Resilient model catalogs with cached fallback, bounded background refresh, and failure retention
+- Resilient model catalogs with cached online snapshots, bounded background refresh, and failure retention
 - Provider-first pricing metadata with optional OpenRouter completion and quality indicators
 - Explicit diagnostics: cached `/status`, free `/status refresh`, and potentially billable `/status check`
 - Built-in integrations for Charm Hyper, DeepSeek, Google Gemini, OpenAI Codex, OpenCode Zen, and OpenCode Go
@@ -45,7 +45,7 @@ pi install npm:@hyav/pi-provider
 
 Use `/status refresh` for free endpoint, authentication, catalog, and account checks. Use `/status check` only when you explicitly accept a real model request and possible usage charges.
 
-A dynamic Provider whose API key references environment variables keeps its cached or fallback model catalog and skips network catalog refreshes until those variables or a stored credential are available. This prevents unconfigured Providers from surfacing model-refresh warnings.
+A dynamic Provider whose API key references environment variables keeps its last successful online catalog snapshot and skips network catalog refreshes until those variables or a stored credential are available. Providers without a successful snapshot expose an empty catalog rather than inventing models. This prevents unconfigured Providers from surfacing model-refresh warnings.
 
 ## Common configuration
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 - 由一个 Pi Provider Host 统一负责注册、Status、Preflight、实时检查和请求 Tuner
 - 由单一 Pi 入口在 `/reload` 时发现 Provider、Status、Preflight 和 Tuner Adapter 文件
-- 通过缓存回退、有界后台刷新和失败保留提供可靠的模型目录
+- 通过缓存在线快照、有界后台刷新和失败保留提供可靠的模型目录
 - 优先采用 Provider 价格元数据，并可由 OpenRouter 补全价格和质量指标
 - 显式诊断：缓存 `/status`、免费 `/status refresh` 和可能计费的 `/status check`
 - 内置 Charm Hyper、DeepSeek、Google Gemini、OpenAI Codex、OpenCode Zen 和 OpenCode Go 集成
@@ -45,7 +45,7 @@ pi install npm:@hyav/pi-provider
 
 使用 `/status refresh` 执行免费的端点、鉴权、目录和账户检查。只有明确接受一次真实模型请求及其可能产生的用量费用时，才使用 `/status check`。
 
-动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留缓存或回退模型目录并跳过网络刷新，避免未配置的 Provider 产生模型目录刷新警告。
+动态 Provider 的 API Key 引用环境变量时，如果这些变量和已存储凭据均未配置，将保留最近一次成功获取的在线目录快照；如果从未成功获取过在线目录，则使用空目录，并跳过网络刷新，避免未配置的 Provider 产生模型目录刷新警告。
 
 ## 常用配置
 

package/core/adapter-validation.ts

@@ -147,7 +147,9 @@ export function validateProviderAdapter(adapter: unknown): asserts adapter is Pr
 		if (
 			adapter.catalog.source !== "static" &&
 			adapter.catalog.source !== "live" &&
-			adapter.catalog.source !== "fallback"
+			adapter.catalog.source !== "cached" &&
+			adapter.catalog.source !== "fallback" &&
+			adapter.catalog.source !== "empty"
 		) {
 			throw new Error(`Provider ${adapter.id} has invalid catalog source`);
 		}
@@ -160,6 +162,17 @@ export function validateProviderAdapter(adapter: unknown): asserts adapter is Pr
 		}
 		if (adapter.catalog.updatedAt !== undefined)
 			assertFiniteNonNegative(adapter.catalog.updatedAt, "Catalog updatedAt");
+		for (const field of ["lastSuccessfulRefreshAt", "lastAttemptAt", "nextRetryAt"] as const) {
+			if (adapter.catalog[field] !== undefined) {
+				assertFiniteNonNegative(adapter.catalog[field], `Catalog ${field}`);
+			}
+		}
+		for (const field of ["consecutiveFailures", "rejectedCount", "duplicateCount"] as const) {
+			const count = adapter.catalog[field];
+			if (count !== undefined && (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)) {
+				throw new Error(`Provider ${adapter.id} has invalid catalog ${field}`);
+			}
+		}
 		if (adapter.catalog.lastError !== undefined && !isSafeText(adapter.catalog.lastError)) {
 			throw new Error(`Provider ${adapter.id} has invalid catalog error`);
 		}

package/core/host.ts

@@ -17,7 +17,7 @@ import {
 	type PiProviderRuntimeController,
 	prepareProviderRegistration,
 } from "./extension.ts";
-import { fetchOfficialPricing, type OfficialModelMeta, OPENROUTER_MODELS_URL } from "./official-pricing.ts";
+import { fetchOfficialModelMetadata, type OfficialModelMeta, OPENROUTER_MODELS_URL } from "./official-pricing.ts";
 import type { PreflightAdapter } from "./preflight-manager.ts";
 import { refreshProviderRegistrations } from "./provider-registration.ts";
 import { scheduleModelCatalogRefresh } from "./runtime.ts";
@@ -86,7 +86,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 			refreshProviderRegistrations(pi, installedDefinition.definition.providers, runtime, snapshot);
 		};
 		const officialPricing = runtime.enableOfficialPricingFallback
-			? fetchOfficialPricingForHost(runtime, { allowNetwork: false })
+			? fetchOfficialModelMetadataForHost(runtime, { allowNetwork: false })
 			: Promise.resolve({});
 		const bridge: StartupBridge = { dependencies: runtime, officialPricing };
 
@@ -98,7 +98,7 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 			}
 			const controller = new AbortController();
 			pricingRefreshController = controller;
-			void fetchOfficialPricingForHost(runtime, { signal: controller.signal })
+			void fetchOfficialModelMetadataForHost(runtime, { signal: controller.signal })
 				.then((snapshot) => {
 					if (controller.signal.aborted || disposed) return;
 					onBackgroundRefresh(snapshot);
@@ -465,11 +465,11 @@ export function createPiProviderHost(dependencies: Partial<PiProviderDependencie
 	};
 }
 
-function fetchOfficialPricingForHost(
+function fetchOfficialModelMetadataForHost(
 	runtime: PiProviderDependencies,
 	options: { allowNetwork?: boolean; signal?: AbortSignal } = {},
 ) {
-	return fetchOfficialPricing(
+	return fetchOfficialModelMetadata(
 		runtime.fetch,
 		runtime.officialPricingUrl,
 		runtime.officialPricingTimeoutMs,

package/core/model-catalog.ts

@@ -0,0 +1,277 @@
+import type { ModelCatalogSource, ModelCatalogStatus, ProviderModelDraft, ProviderRefreshContext } from "./types.ts";
+
+export interface ModelCatalogDiagnostics {
+	rejectedCount?: number;
+	duplicateCount?: number;
+}
+
+export interface ModelCatalogDiscoveryResult {
+	models: ProviderModelDraft[];
+	diagnostics?: ModelCatalogDiagnostics;
+}
+
+export interface ModelCatalogLifecycleOptions {
+	initialModels?: ProviderModelDraft[];
+	initialSource?: ModelCatalogSource;
+	ttlMs: number;
+	failureBackoffMs?: number;
+	maxFailureBackoffMs?: number;
+	now?: () => number;
+	discover(
+		context: ProviderRefreshContext,
+	): Promise<ProviderModelDraft[] | ModelCatalogDiscoveryResult> | ProviderModelDraft[] | ModelCatalogDiscoveryResult;
+	restore(stored: ProviderRefreshContext["stored"]): ProviderModelDraft[] | undefined;
+	persist(models: ProviderModelDraft[], checkedAt: number): NonNullable<ProviderRefreshContext["stored"]>;
+	onUpdate(models: ProviderModelDraft[]): void;
+	errorCode(error: unknown): string;
+}
+
+export interface ModelCatalogLifecycle {
+	catalog: ModelCatalogStatus;
+	getModels(): ProviderModelDraft[];
+	refreshModels(context: ProviderRefreshContext): Promise<ProviderModelDraft[]>;
+}
+
+function isAbortError(error: unknown): boolean {
+	return error !== null && typeof error === "object" && "name" in error && error.name === "AbortError";
+}
+
+function isValidTimestamp(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+async function publish(
+	context: ProviderRefreshContext,
+	update: () => void,
+	persist?: NonNullable<ProviderRefreshContext["stored"]>,
+): Promise<boolean> {
+	try {
+		return await context.publish({ ...(persist ? { persist } : {}), update });
+	} catch {
+		if (!persist) return false;
+		// Persistence is an optimization. Retry the generation-checked update without it.
+		try {
+			return await context.publish({ update });
+		} catch {
+			return false;
+		}
+	}
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function waitForCaller<T>(request: Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = () => reject(abortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		void request.then(
+			(value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			},
+			(error) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			},
+		);
+	});
+}
+
+const DEFAULT_FAILURE_BACKOFF_MS = 30_000;
+const DEFAULT_MAX_FAILURE_BACKOFF_MS = 15 * 60_000;
+
+function finiteNonNegative(value: number | undefined, fallback: number, label: string): number {
+	const resolved = value ?? fallback;
+	if (!Number.isFinite(resolved) || resolved < 0)
+		throw new RangeError(`${label} must be a finite non-negative number`);
+	return resolved;
+}
+
+interface NormalizedCatalogDiscoveryResult {
+	models: ProviderModelDraft[];
+	diagnostics: Required<ModelCatalogDiagnostics>;
+}
+
+function diagnosticCount(value: number | undefined, label: string): number {
+	const count = value ?? 0;
+	if (!Number.isSafeInteger(count) || count < 0) {
+		throw new RangeError(`Model catalog ${label} must be a non-negative safe integer`);
+	}
+	return count;
+}
+
+function normalizeDiscoveryResult(
+	result: ProviderModelDraft[] | ModelCatalogDiscoveryResult,
+): NormalizedCatalogDiscoveryResult {
+	const models = Array.isArray(result) ? result : result.models;
+	const diagnostics = Array.isArray(result) ? undefined : result.diagnostics;
+	return {
+		models,
+		diagnostics: {
+			rejectedCount: diagnosticCount(diagnostics?.rejectedCount, "rejected count"),
+			duplicateCount: diagnosticCount(diagnostics?.duplicateCount, "duplicate count"),
+		},
+	};
+}
+
+interface ActiveCatalogRefresh {
+	request: Promise<NormalizedCatalogDiscoveryResult>;
+	publication: Promise<void>;
+	waiters: number;
+	settled: boolean;
+	applied: boolean;
+	failureRecorded: boolean;
+}
+
+export function createModelCatalogLifecycle(options: ModelCatalogLifecycleOptions): ModelCatalogLifecycle {
+	const now = options.now ?? Date.now;
+	const failureBackoffMs = finiteNonNegative(
+		options.failureBackoffMs,
+		DEFAULT_FAILURE_BACKOFF_MS,
+		"Model catalog failure backoff",
+	);
+	const maxFailureBackoffMs = finiteNonNegative(
+		options.maxFailureBackoffMs,
+		DEFAULT_MAX_FAILURE_BACKOFF_MS,
+		"Model catalog maximum failure backoff",
+	);
+	if (maxFailureBackoffMs < failureBackoffMs) {
+		throw new RangeError("Model catalog maximum failure backoff must not be less than its initial backoff");
+	}
+	let models = [...(options.initialModels ?? [])];
+	let lastCatalogUpdatedAt: number | undefined;
+	let inFlight: ActiveCatalogRefresh | undefined;
+	const catalog: ModelCatalogStatus = {
+		source: options.initialSource ?? (models.length > 0 ? "static" : "empty"),
+		modelCount: models.length,
+		consecutiveFailures: 0,
+	};
+
+	const applyModels = (
+		nextModels: ProviderModelDraft[],
+		source: ModelCatalogSource,
+		updatedAt?: number,
+		diagnostics: Required<ModelCatalogDiagnostics> = { rejectedCount: 0, duplicateCount: 0 },
+	) => {
+		models = [...nextModels];
+		options.onUpdate(models);
+		catalog.source = source;
+		catalog.modelCount = models.length;
+		catalog.rejectedCount = diagnostics.rejectedCount;
+		catalog.duplicateCount = diagnostics.duplicateCount;
+		catalog.lastError = undefined;
+		catalog.consecutiveFailures = 0;
+		catalog.nextRetryAt = undefined;
+		if (updatedAt !== undefined) {
+			catalog.updatedAt = updatedAt;
+			catalog.lastSuccessfulRefreshAt = updatedAt;
+			lastCatalogUpdatedAt = updatedAt;
+		}
+	};
+
+	const restoreStored = async (context: ProviderRefreshContext): Promise<void> => {
+		const restored = options.restore(context.stored);
+		if (!restored) return;
+		const checkedAt = isValidTimestamp(context.stored?.checkedAt) ? context.stored.checkedAt : undefined;
+		if (lastCatalogUpdatedAt !== undefined && (checkedAt === undefined || checkedAt <= lastCatalogUpdatedAt)) return;
+		await publish(context, () => {
+			applyModels(restored, "cached", checkedAt);
+		});
+	};
+
+	const clearSettledRefresh = (active: ActiveCatalogRefresh) => {
+		if (inFlight === active && active.settled && active.waiters === 0) inFlight = undefined;
+	};
+
+	const recordFailure = (active: ActiveCatalogRefresh, error: unknown) => {
+		if (active.failureRecorded || isAbortError(error)) return;
+		active.failureRecorded = true;
+		const failedAt = now();
+		const consecutiveFailures = (catalog.consecutiveFailures ?? 0) + 1;
+		const multiplier = 2 ** Math.min(30, consecutiveFailures - 1);
+		catalog.consecutiveFailures = consecutiveFailures;
+		catalog.nextRetryAt = failedAt + Math.min(maxFailureBackoffMs, failureBackoffMs * multiplier);
+		catalog.lastError = options.errorCode(error);
+	};
+
+	const startRefresh = (context: ProviderRefreshContext): ActiveCatalogRefresh => {
+		const active: ActiveCatalogRefresh = {
+			request: Promise.resolve({
+				models: [],
+				diagnostics: { rejectedCount: 0, duplicateCount: 0 },
+			}),
+			publication: Promise.resolve(),
+			waiters: 0,
+			settled: false,
+			applied: false,
+			failureRecorded: false,
+		};
+		const sharedContext = { ...context, signal: new AbortController().signal };
+		catalog.lastAttemptAt = now();
+		active.request = Promise.resolve()
+			.then(() => options.discover(sharedContext))
+			.then(normalizeDiscoveryResult)
+			.catch((error: unknown) => {
+				recordFailure(active, error);
+				throw error;
+			})
+			.finally(() => {
+				active.settled = true;
+				clearSettledRefresh(active);
+			});
+		inFlight = active;
+		return active;
+	};
+
+	const refreshModels = async (context: ProviderRefreshContext): Promise<ProviderModelDraft[]> => {
+		await restoreStored(context);
+		if (context.allowNetwork !== true || context.signal.aborted) return [...models];
+
+		const currentTime = now();
+		const isFresh =
+			catalog.lastSuccessfulRefreshAt !== undefined &&
+			Math.max(0, currentTime - catalog.lastSuccessfulRefreshAt) <= Math.max(0, options.ttlMs);
+		if (!context.force && catalog.lastError === undefined && isFresh) return [...models];
+		if (
+			!context.force &&
+			inFlight === undefined &&
+			catalog.nextRetryAt !== undefined &&
+			currentTime < catalog.nextRetryAt
+		) {
+			return [...models];
+		}
+
+		const active = inFlight ?? startRefresh(context);
+		active.waiters++;
+		try {
+			const discovered = await waitForCaller(active.request, context.signal);
+			const attempt = active.publication.then(async () => {
+				if (active.applied || context.signal.aborted) return;
+				const updatedAt = now();
+				await publish(
+					context,
+					() => {
+						applyModels(discovered.models, "live", updatedAt, discovered.diagnostics);
+						active.applied = true;
+					},
+					options.persist(discovered.models, updatedAt),
+				);
+			});
+			active.publication = attempt.catch(() => undefined);
+			await waitForCaller(attempt, context.signal);
+			return [...models];
+		} catch (error) {
+			if (!context.signal.aborted) recordFailure(active, error);
+			throw error;
+		} finally {
+			active.waiters = Math.max(0, active.waiters - 1);
+			clearSettledRefresh(active);
+		}
+	};
+
+	options.onUpdate(models);
+	return { catalog, getModels: () => [...models], refreshModels };
+}

package/core/official-pricing.ts

@@ -41,7 +41,7 @@ export interface OfficialModelMeta {
 	};
 }
 
-export interface OfficialPricingFetchOptions {
+export interface OfficialModelMetadataFetchOptions {
 	/** Optional persistent cache file. Omit for process-only caching (for example, in unit tests). */
 	cachePath?: string;
 	/** Return the current snapshot immediately and refresh an expired/missing cache in the background. */
@@ -54,6 +54,9 @@ export interface OfficialPricingFetchOptions {
 	signal?: AbortSignal;
 }
 
+/** @deprecated Use OfficialModelMetadataFetchOptions. */
+export type OfficialPricingFetchOptions = OfficialModelMetadataFetchOptions;
+
 interface PricingCacheEntry {
 	snapshot: Record<string, OfficialModelMeta>;
 	updatedAt: number;
@@ -659,14 +662,14 @@ function observeBackgroundRefresh(
 	);
 }
 
-export async function fetchOfficialPricing(
+export async function fetchOfficialModelMetadata(
 	fetchFn: typeof globalThis.fetch,
 	pricingUrl = OPENROUTER_MODELS_URL,
 	timeoutMs = 3_000,
 	cacheTtlMs = DEFAULT_PRICING_CACHE_TTL_MS,
 	maxStaleMs = DEFAULT_PRICING_MAX_STALE_MS,
 	now: () => number = Date.now,
-	options: OfficialPricingFetchOptions = {},
+	options: OfficialModelMetadataFetchOptions = {},
 ): Promise<Record<string, OfficialModelMeta>> {
 	const currentTime = now();
 	const cachedAge = getPricingCacheAge(pricingUrl, currentTime);
@@ -715,6 +718,19 @@ export async function fetchOfficialPricing(
 	return request;
 }
 
+/** @deprecated Use fetchOfficialModelMetadata. */
+export function fetchOfficialPricing(
+	fetchFn: typeof globalThis.fetch,
+	pricingUrl = OPENROUTER_MODELS_URL,
+	timeoutMs = 3_000,
+	cacheTtlMs = DEFAULT_PRICING_CACHE_TTL_MS,
+	maxStaleMs = DEFAULT_PRICING_MAX_STALE_MS,
+	now: () => number = Date.now,
+	options: OfficialPricingFetchOptions = {},
+): Promise<Record<string, OfficialModelMeta>> {
+	return fetchOfficialModelMetadata(fetchFn, pricingUrl, timeoutMs, cacheTtlMs, maxStaleMs, now, options);
+}
+
 export function findOfficialCost(
 	modelId: string,
 	dynamicPricing: Record<string, OfficialModelMeta | ProviderCost> = {},
@@ -868,12 +884,12 @@ export function findOfficialMeta(
 	return result;
 }
 
-export function applyOfficialModelCosts(
+export function applyOfficialModelMetadata(
 	models: ProviderModelDraft[],
-	dynamicPricing: Record<string, OfficialModelMeta | ProviderCost> = {},
+	dynamicMetadata: Record<string, OfficialModelMeta | ProviderCost> = {},
 ): ProviderModelDraft[] {
 	return models.map((model) => {
-		const meta = findOfficialMeta(model.id, dynamicPricing);
+		const meta = findOfficialMeta(model.id, dynamicMetadata);
 		if (!meta) return model;
 
 		const useOfficialCost =
@@ -897,3 +913,11 @@ export function applyOfficialModelCosts(
 		return merged;
 	});
 }
+
+/** @deprecated Use applyOfficialModelMetadata. */
+export function applyOfficialModelCosts(
+	models: ProviderModelDraft[],
+	dynamicPricing: Record<string, OfficialModelMeta | ProviderCost> = {},
+): ProviderModelDraft[] {
+	return applyOfficialModelMetadata(models, dynamicPricing);
+}

package/core/provider-registration.ts

@@ -1,6 +1,6 @@
 import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
 import { validateProviderModelDrafts } from "./adapter-validation.ts";
-import { applyOfficialModelCosts, findOfficialMeta, type OfficialModelMeta } from "./official-pricing.ts";
+import { applyOfficialModelMetadata, findOfficialMeta, type OfficialModelMeta } from "./official-pricing.ts";
 import { resolvePricingDetails } from "./pricing-adjustments.ts";
 import type { PiProviderDependencies } from "./runtime-config.ts";
 import type {
@@ -114,6 +114,60 @@ function selectPricingAdjustment(
 	return model.pricingAdjustment ?? policy?.models?.[model.id.trim()] ?? policy?.defaultAdjustment;
 }
 
+function costsEqual(left: ProviderModelDraft["cost"], right: ProviderCost): boolean {
+	if (left === undefined) return false;
+	const candidate = left as Partial<ProviderCost>;
+	if (
+		candidate.input !== right.input ||
+		candidate.output !== right.output ||
+		candidate.cacheRead !== right.cacheRead ||
+		candidate.cacheWrite !== right.cacheWrite
+	) {
+		return false;
+	}
+	const leftTiers = candidate.tiers ?? [];
+	const rightTiers = right.tiers ?? [];
+	return (
+		leftTiers.length === rightTiers.length &&
+		leftTiers.every((tier, index) => {
+			const normalized = rightTiers[index];
+			return (
+				normalized !== undefined &&
+				tier.inputTokensAbove === normalized.inputTokensAbove &&
+				tier.input === normalized.input &&
+				tier.output === normalized.output &&
+				tier.cacheRead === normalized.cacheRead &&
+				tier.cacheWrite === normalized.cacheWrite
+			);
+		})
+	);
+}
+
+function inputsEqual(left: ProviderModelDraft["input"], right: ProviderModel["input"]): boolean {
+	return Array.isArray(left) && left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function getDraftCostSource(
+	draft: ProviderModelDraft | undefined,
+	officialMeta: OfficialModelMeta | undefined,
+	normalizedCost: ProviderCost,
+): ProviderPricingSource | "default" | "normalized" {
+	const candidate = draft?.cost ?? (officialMeta?.costKnown !== false ? officialMeta?.cost : undefined);
+	if (candidate === undefined) return "default";
+	if (!costsEqual(candidate, normalizedCost)) return "normalized";
+	return draft?.cost !== undefined ? (draft.pricingSource ?? "provider") : "official";
+}
+
+function getFieldSource(
+	providerValue: unknown,
+	officialValue: unknown,
+	wasNormalized: boolean,
+): "provider" | "official" | "default" | "normalized" {
+	if (providerValue === undefined && officialValue === undefined) return "default";
+	if (wasNormalized) return "normalized";
+	return providerValue !== undefined ? "provider" : "official";
+}
+
 function resolveModelRegistration(
 	adapter: ProviderAdapter,
 	runtime: PiProviderDependencies,
@@ -121,42 +175,46 @@ function resolveModelRegistration(
 	officialPricing: Record<string, OfficialModelMeta>,
 ): { models: ProviderModel[]; modelMetadata: Record<string, ProviderModelMetadata> } {
 	validateProviderModelDrafts(modelDrafts, `Provider ${adapter.id}`);
-	const enrichedDrafts = applyOfficialModelCosts(modelDrafts, officialPricing);
+	const enrichedDrafts = applyOfficialModelMetadata(modelDrafts, officialPricing);
 	const pricingPolicy = runtime.pricingPolicies?.[adapter.id] ?? adapter.pricing;
 	const metadata: Record<string, ProviderModelMetadata> = {};
 	const adjustedDrafts = enrichedDrafts.map((model, index) => {
 		const modelId = model.id.trim();
 		const originalDraft = modelDrafts[index];
 		const officialMeta = findOfficialMeta(modelId, officialPricing);
+		const normalizedModel = normalizeProviderModel(model);
+		const normalizedCost = normalizeCost(model.cost);
 		const fieldSources = {
-			contextWindow:
-				originalDraft?.contextWindow !== undefined
-					? ("provider" as const)
-					: officialMeta?.contextWindow !== undefined
-						? ("official" as const)
-						: ("default" as const),
-			maxTokens:
-				originalDraft?.maxTokens !== undefined
-					? ("provider" as const)
-					: officialMeta?.maxTokens !== undefined
-						? ("official" as const)
-						: ("default" as const),
-			input:
-				originalDraft?.input !== undefined
-					? ("provider" as const)
-					: officialMeta?.input !== undefined
-						? ("official" as const)
-						: ("default" as const),
-			reasoning:
-				originalDraft?.reasoning !== undefined
-					? ("provider" as const)
-					: officialMeta?.reasoning !== undefined
-						? ("official" as const)
-						: ("default" as const),
+			cost: getDraftCostSource(originalDraft, officialMeta, normalizedCost),
+			contextWindow: getFieldSource(
+				originalDraft?.contextWindow,
+				officialMeta?.contextWindow,
+				model.contextWindow !== undefined && model.contextWindow !== normalizedModel.contextWindow,
+			),
+			maxTokens: getFieldSource(
+				originalDraft?.maxTokens,
+				officialMeta?.maxTokens,
+				model.maxTokens !== undefined && model.maxTokens !== normalizedModel.maxTokens,
+			),
+			input: getFieldSource(
+				originalDraft?.input,
+				officialMeta?.input,
+				model.input !== undefined && !inputsEqual(model.input, normalizedModel.input),
+			),
+			reasoning: getFieldSource(
+				originalDraft?.reasoning,
+				officialMeta?.reasoning,
+				model.reasoning !== undefined && model.reasoning !== normalizedModel.reasoning,
+			),
+			thinkingLevelMap: getFieldSource(originalDraft?.thinkingLevelMap, officialMeta?.thinkingLevelMap, false),
 		};
 		const source: ProviderPricingSource | "none" =
 			model.cost === undefined ? "none" : (model.pricingSource ?? "provider");
-		const pricing = resolvePricingDetails(model.cost, source, selectPricingAdjustment(adapter, model, pricingPolicy));
+		const pricing = resolvePricingDetails(
+			model.cost === undefined ? undefined : normalizedCost,
+			source,
+			selectPricingAdjustment(adapter, model, pricingPolicy),
+		);
 		metadata[modelId] = {
 			pricing,
 			fieldSources,

package/core/public-adapters.ts

@@ -29,6 +29,13 @@ export {
 	mergeDiagnosticHeaders,
 } from "./diagnostic-auth.ts";
 export { isProviderDataError, ProviderDataError } from "./errors.ts";
+export type {
+	ModelCatalogDiagnostics,
+	ModelCatalogDiscoveryResult,
+	ModelCatalogLifecycle,
+	ModelCatalogLifecycleOptions,
+} from "./model-catalog.ts";
+export { createModelCatalogLifecycle } from "./model-catalog.ts";
 export { createOpenCodeCatalogPreflightAdapter } from "./opencode-preflight.ts";
 export type {
 	PreflightAdapter,

package/core/runtime.ts

@@ -3,7 +3,7 @@ import type { PiProviderDefinition } from "./definition.ts";
 import { validatePiProviderDefinition } from "./definition.ts";
 import { LiveCheckManager, type LiveCheckResult } from "./live-check-manager.ts";
 import {
-	fetchOfficialPricing,
+	fetchOfficialModelMetadata,
 	findOfficialMeta,
 	getPricingCacheAge,
 	type OfficialModelMeta,
@@ -180,10 +180,12 @@ function getNativeModelMetadata(
 				: {}),
 		},
 		fieldSources: {
+			cost: "native",
 			contextWindow: "native",
 			maxTokens: "native",
 			input: "native",
 			reasoning: "native",
+			thinkingLevelMap: model.thinkingLevelMap === undefined ? "default" : "native",
 		},
 		...(officialMeta?.quality
 			? {
@@ -467,8 +469,8 @@ export function createPiProviderRuntime(
 		let pricingRefreshController: AbortController | undefined;
 		const cachePath =
 			runtime.officialPricingUrl === OPENROUTER_MODELS_URL ? runtime.openRouterMetadataCachePath : undefined;
-		const fetchPricing = (options: { allowNetwork?: boolean; signal?: AbortSignal } = {}) =>
-			fetchOfficialPricing(
+		const fetchMetadata = (options: { allowNetwork?: boolean; signal?: AbortSignal } = {}) =>
+			fetchOfficialModelMetadata(
 				runtime.fetch,
 				runtime.officialPricingUrl,
 				runtime.officialPricingTimeoutMs,
@@ -478,7 +480,7 @@ export function createPiProviderRuntime(
 				{ cachePath, ...options },
 			);
 		const officialPricingPromise = runtime.enableOfficialPricingFallback
-			? fetchPricing({ allowNetwork: false })
+			? fetchMetadata({ allowNetwork: false })
 			: Promise.resolve({});
 		const definitionPromise = loadDefinition(runtime);
 		const [officialPricing, definition] = await Promise.all([officialPricingPromise, definitionPromise]);
@@ -492,7 +494,7 @@ export function createPiProviderRuntime(
 			}
 			const controller = new AbortController();
 			pricingRefreshController = controller;
-			void fetchPricing({ signal: controller.signal })
+			void fetchMetadata({ signal: controller.signal })
 				.then((snapshot) => {
 					if (disposed || controller.signal.aborted) return;
 					installedController?.updateOfficialPricing?.(snapshot);

package/core/status-report.ts

@@ -177,7 +177,9 @@ function formatModelFieldSource(source: ModelFieldSource | undefined): string {
 					? "OpenRouter"
 					: source === "fallback"
 						? "Provider fallback"
-						: "Pi default";
+						: source === "normalized"
+							? "Normalized catalog value"
+							: "Pi default";
 	return ` · ${label}`;
 }
 
@@ -279,7 +281,18 @@ function formatCatalog(
 	const statusParts = freshness ? [freshness, source] : [source];
 	if (catalog?.updatedAt !== undefined) statusParts.push(formatAge(now, catalog.updatedAt));
 	const lines = [`Status: ${statusParts.join(" · ")}`, `Models: ${count}`];
+	const rejectedCount = catalog?.rejectedCount ?? 0;
+	const duplicateCount = catalog?.duplicateCount ?? 0;
+	if (rejectedCount > 0 || duplicateCount > 0) {
+		lines.push(`Skipped: ${rejectedCount} invalid · ${duplicateCount} duplicate`);
+	}
 	if (catalog?.lastError) lines.push(`Error: ${catalog.lastError}`);
+	if (catalog?.lastError && catalog.nextRetryAt !== undefined) {
+		const failures = catalog.consecutiveFailures ?? 1;
+		lines.push(
+			`Retry: ${formatUntil(now, catalog.nextRetryAt)} · ${failures} consecutive failure${failures === 1 ? "" : "s"}`,
+		);
+	}
 	const issue =
 		catalog?.lastError !== undefined
 			? {
@@ -578,6 +591,11 @@ export function formatProviderStatus(
 		`  Max output: ${formatTokens(model.maxTokens)}${formatModelFieldSource(fieldSources?.maxTokens)}`,
 		`  Input: ${model.input?.join(", ") || "unknown"}${formatModelFieldSource(fieldSources?.input)}`,
 		`  Reasoning: ${formatReasoning(model)}${formatModelFieldSource(fieldSources?.reasoning)}`,
+		...(model.thinkingLevelMap
+			? [
+					`  Thinking levels: ${getSupportedReasoningLevels(model).join(", ") || "none"}${formatModelFieldSource(fieldSources?.thinkingLevelMap)}`,
+				]
+			: []),
 		`  Pricing: ${formatPricing(model, options.modelMetadata)}${pricingSource}`,
 		...(model.cost?.tiers?.map((tier) => `  Pricing tier: ${formatPricingTier(tier)}`) ?? []),
 		...(options.modelMetadata?.pricing?.note ? [`  Pricing note: ${options.modelMetadata.pricing.note}`] : []),

package/core/types.ts

@@ -14,7 +14,7 @@ export type PricingSku = "input" | "output" | "cacheRead" | "cacheWrite";
 /** Pricing provenance used by Pi Provider sidecars; not added to Pi model objects. */
 export type ProviderPricingSource = "provider" | "fallback" | "official";
 export type ModelPricingSource = ProviderPricingSource | "native";
-export type ModelFieldSource = ProviderPricingSource | "native" | "default";
+export type ModelFieldSource = ProviderPricingSource | "native" | "default" | "normalized";
 export type ModelMetadataState = "fresh" | "stale" | "checking" | "unavailable";
 
 export interface ModelMetadataStatus {
@@ -42,10 +42,12 @@ export interface ProviderRequestAuth {
 }
 
 export interface ModelFieldSources {
+	cost?: ModelFieldSource;
 	contextWindow?: ModelFieldSource;
 	maxTokens?: ModelFieldSource;
 	input?: ModelFieldSource;
 	reasoning?: ModelFieldSource;
+	thinkingLevelMap?: ModelFieldSource;
 }
 
 export interface ProviderPricingAdjustment {
@@ -112,12 +114,18 @@ export type ProviderDefinition = Omit<ProviderConfig, "models" | "refreshModels"
 	refreshModels?: (context: ProviderRefreshContext) => Promise<ProviderModelDraft[]>;
 };
 
-export type ModelCatalogSource = "static" | "live" | "fallback";
+export type ModelCatalogSource = "static" | "live" | "cached" | "fallback" | "empty";
 
 export interface ModelCatalogStatus {
 	source: ModelCatalogSource;
 	modelCount: number;
 	updatedAt?: number;
+	lastSuccessfulRefreshAt?: number;
+	lastAttemptAt?: number;
+	consecutiveFailures?: number;
+	nextRetryAt?: number;
+	rejectedCount?: number;
+	duplicateCount?: number;
 	lastError?: string;
 }
 

package/index.ts

@@ -54,9 +54,18 @@ export type {
 	LiveCheckSnapshot,
 } from "./core/live-check-manager.ts";
 export { getLiveCheckKey, LIVE_CHECK_SCOPE, LiveCheckManager } from "./core/live-check-manager.ts";
+export type {
+	ModelCatalogDiagnostics,
+	ModelCatalogDiscoveryResult,
+	ModelCatalogLifecycle,
+	ModelCatalogLifecycleOptions,
+} from "./core/model-catalog.ts";
+export { createModelCatalogLifecycle } from "./core/model-catalog.ts";
 export {
 	applyOfficialModelCosts,
+	applyOfficialModelMetadata,
 	clearPricingCache,
+	fetchOfficialModelMetadata,
 	fetchOfficialPricing,
 	findOfficialCost,
 	findOfficialMeta,
@@ -64,6 +73,7 @@ export {
 	getPricingCache,
 	getPricingCacheAge,
 	type OfficialModelMeta,
+	type OfficialModelMetadataFetchOptions,
 	type OfficialPricingFetchOptions,
 	OPENROUTER_MODELS_URL,
 	parseOpenRouterModels,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyav/pi-provider",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Provider extension toolkit for Pi to integrate and manage custom LLM providers with dynamic models, request tuners, and account status.",
   "author": "hyav",
   "license": "MIT",

package/providers/charm-hyper.ts

@@ -1,5 +1,5 @@
 import type {
-	ModelCatalogStatus,
+	ModelCatalogDiscoveryResult,
 	ProviderAdapter,
 	ProviderModel,
 	ProviderModelDraft,
@@ -7,6 +7,7 @@ import type {
 	ThinkingLevel,
 } from "@hyav/pi-provider";
 import {
+	createModelCatalogLifecycle,
 	defineProviderExtension,
 	isProviderDataError,
 	MAX_PROVIDER_MODEL_COUNT,
@@ -21,17 +22,6 @@ export { HYPER_BASE_URL, HYPER_USER_AGENT } from "./charm-hyper/constants.ts";
 export const HYPER_PROVIDER_URL = "https://hyper.charm.land/v1/provider";
 export const HYPER_MODELS_URL = "https://hyper.charm.land/v1/models";
 export const HYPER_MODEL_CATALOG_TTL_MS = 4 * 60 * 60 * 1_000;
-const zeroCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
-
-const officialCostFallbacks: Partial<Record<string, ProviderModel["cost"]>> = {
-	"deepseek-v4-flash": { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
-	"deepseek-v4-pro": { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
-	"glm-5": { input: 1, output: 3.2, cacheRead: 0, cacheWrite: 0 },
-	"glm-5.1": { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
-	"kimi-k2.5": { input: 0.6, output: 3, cacheRead: 0.1, cacheWrite: 0 },
-	"kimi-k2.6": { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
-	"mistral-large-instruct-2411": { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
-};
 
 const thinkingLevels = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const baseHyperCompat: NonNullable<ProviderModel["compat"]> = {
@@ -50,21 +40,6 @@ const onOffThinkingLevelMap: NonNullable<ProviderModel["thinkingLevelMap"]> = {
 	max: "max",
 };
 
-const modelOverrides: Record<string, Partial<ProviderModelDraft>> = {
-	"qwen3-coder-480b-a35b-instruct-int4-mixed-ar": { reasoning: false },
-	"qwen3-next-80b-a3b-instruct": { reasoning: false },
-	"gpt-oss-120b": {
-		thinkingLevelMap: {
-			minimal: null,
-			low: "low",
-			medium: "medium",
-			high: "high",
-			xhigh: "high",
-		},
-		compat: { supportsReasoningEffort: true },
-	},
-};
-
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -77,63 +52,6 @@ function isFiniteNonNegative(value: unknown): value is number {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
 
-function costFallbackFor(id: string): ProviderModel["cost"] {
-	return { ...(officialCostFallbacks[id] ?? zeroCost) };
-}
-
-function fallbackModel(
-	id: string,
-	name: string,
-	contextWindow: number,
-	overrides: Partial<ProviderModelDraft> = {},
-): ProviderModelDraft {
-	const { compat: overrideCompat, ...rest } = overrides;
-	return {
-		id,
-		name,
-		reasoning: true,
-		input: ["text", "image"],
-		contextWindow,
-		maxTokens: Math.floor(contextWindow / 10),
-		cost: costFallbackFor(id),
-		pricingSource: "fallback",
-		headers: { ...hyperModelHeaders },
-		compat: { ...baseHyperCompat, ...overrideCompat },
-		...rest,
-	};
-}
-
-export function getHyperFallbackModels(): ProviderModelDraft[] {
-	return [
-		fallbackModel("deepseek-v4-flash", "DeepSeek V4 Flash", 1_048_576),
-		fallbackModel("deepseek-v4-pro", "DeepSeek V4 Pro", 1_048_576),
-		fallbackModel("gemma-4-26b-a4b-it", "Gemma 4 26B A4B", 32_768, { input: ["text"] }),
-		fallbackModel("glm-5", "GLM-5", 202_752),
-		fallbackModel("glm-5.1", "GLM-5.1", 202_752),
-		fallbackModel("gpt-oss-120b", "GPT-OSS-120B", 131_072, {
-			input: ["text"],
-			thinkingLevelMap: { minimal: null, low: "low", medium: "medium", high: "high", xhigh: "high" },
-			compat: { supportsReasoningEffort: true },
-		}),
-		fallbackModel("kimi-k2.5", "Kimi K2.5", 262_144),
-		fallbackModel("kimi-k2.6", "Kimi K2.6", 32_768),
-		fallbackModel("llama-3.3-70b-instruct", "Llama 3.3 70B Instruct", 128_000, { input: ["text"] }),
-		fallbackModel("llama-4-maverick-17b-128e-instruct-fp8", "Llama 4 Maverick 17B 128E", 430_000),
-		fallbackModel("mistral-large-instruct-2411", "Mistral Large Instruct 2411", 128_000, {
-			reasoning: false,
-			input: ["text"],
-		}),
-		fallbackModel("qwen3-coder-480b-a35b-instruct-int4-mixed-ar", "Qwen3 Coder 480B INT4", 106_000, {
-			reasoning: false,
-			input: ["text"],
-		}),
-		fallbackModel("qwen3-next-80b-a3b-instruct", "Qwen3 Next 80B A3B", 262_144, {
-			reasoning: false,
-			input: ["text"],
-		}),
-	];
-}
-
 function mapHyperPricing(value: unknown): ProviderModel["cost"] | undefined {
 	if (!isRecord(value)) return undefined;
 	if (!isFiniteNonNegative(value.input) || !isFiniteNonNegative(value.output)) return undefined;
@@ -163,16 +81,6 @@ function buildThinkingLevelMap(levels: readonly string[]): NonNullable<ProviderM
 	};
 }
 
-function applyModelOverride(model: ProviderModelDraft): ProviderModelDraft {
-	const override = modelOverrides[model.id];
-	if (override === undefined) return model;
-	return {
-		...model,
-		...override,
-		...(override.compat ? { compat: { ...(model.compat ?? {}), ...override.compat } } : {}),
-	};
-}
-
 function readEffortLevels(model: Record<string, unknown>): ThinkingLevel[] {
 	const reasoning = isRecord(model.reasoning) ? model.reasoning : undefined;
 	const currentLevels = Array.isArray(reasoning?.effort_levels)
@@ -238,41 +146,81 @@ function parseCurrentHyperModel(value: unknown): ProviderModelDraft | undefined
 		compat: { ...baseHyperCompat, supportsReasoningEffort: reportedReasoningLevels.length > 0 },
 		...(thinkingLevelMap ? { thinkingLevelMap } : {}),
 	};
-	return applyModelOverride(mapped);
+	return mapped;
+}
+
+interface ParsedHyperCatalog {
+	models: ProviderModelDraft[];
+	diagnostics: {
+		rejectedCount: number;
+		duplicateCount: number;
+	};
 }
 
-function parseCurrentHyperModels(payload: Record<string, unknown>): ProviderModelDraft[] | undefined {
+function parseCurrentHyperModels(payload: Record<string, unknown>): ParsedHyperCatalog | undefined {
 	if (!Array.isArray(payload.models)) return undefined;
-	if (payload.models.length > MAX_PROVIDER_MODEL_COUNT) return [];
+	if (payload.models.length > MAX_PROVIDER_MODEL_COUNT) {
+		return { models: [], diagnostics: { rejectedCount: payload.models.length, duplicateCount: 0 } };
+	}
 	const models: ProviderModelDraft[] = [];
 	const seenIds = new Set<string>();
+	let rejectedCount = 0;
+	let duplicateCount = 0;
 	for (const value of payload.models) {
 		const model = parseCurrentHyperModel(value);
-		if (model === undefined) return [];
+		if (model === undefined) {
+			rejectedCount++;
+			continue;
+		}
 		const normalizedId = model.id.toLowerCase();
-		if (seenIds.has(normalizedId)) continue;
+		if (seenIds.has(normalizedId)) {
+			duplicateCount++;
+			continue;
+		}
 		seenIds.add(normalizedId);
 		models.push(model);
 	}
-	return models;
+	return { models, diagnostics: { rejectedCount, duplicateCount } };
 }
 
-function parseLegacyHyperModels(payload: Record<string, unknown>): ProviderModelDraft[] {
-	if (!Array.isArray(payload.data) || payload.data.length > MAX_PROVIDER_MODEL_COUNT) return [];
+function parseLegacyHyperModels(payload: Record<string, unknown>): ParsedHyperCatalog {
+	if (!Array.isArray(payload.data)) {
+		return { models: [], diagnostics: { rejectedCount: 0, duplicateCount: 0 } };
+	}
+	if (payload.data.length > MAX_PROVIDER_MODEL_COUNT) {
+		return { models: [], diagnostics: { rejectedCount: payload.data.length, duplicateCount: 0 } };
+	}
 	const models: ProviderModelDraft[] = [];
 	const seenIds = new Set<string>();
+	let rejectedCount = 0;
+	let duplicateCount = 0;
 
 	for (const value of payload.data) {
-		if (!isRecord(value) || typeof value.id !== "string" || value.id.trim() === "") continue;
+		if (!isRecord(value) || typeof value.id !== "string" || value.id.trim() === "") {
+			rejectedCount++;
+			continue;
+		}
 		const id = value.id.trim();
 		const normalizedId = id.toLowerCase();
-		if (seenIds.has(normalizedId)) continue;
-		if (value.context_window !== undefined && !isPositiveInteger(value.context_window)) continue;
-		if (value.max_output_tokens !== undefined && !isPositiveInteger(value.max_output_tokens)) continue;
+		if (value.context_window !== undefined && !isPositiveInteger(value.context_window)) {
+			rejectedCount++;
+			continue;
+		}
+		if (value.max_output_tokens !== undefined && !isPositiveInteger(value.max_output_tokens)) {
+			rejectedCount++;
+			continue;
+		}
 
 		const contextWindow = isPositiveInteger(value.context_window) ? value.context_window : undefined;
 		const maxTokens = isPositiveInteger(value.max_output_tokens) ? value.max_output_tokens : undefined;
-		if (contextWindow !== undefined && maxTokens !== undefined && maxTokens > contextWindow) continue;
+		if (contextWindow !== undefined && maxTokens !== undefined && maxTokens > contextWindow) {
+			rejectedCount++;
+			continue;
+		}
+		if (seenIds.has(normalizedId)) {
+			duplicateCount++;
+			continue;
+		}
 		const reasoning = isRecord(value.reasoning) ? value.reasoning : undefined;
 		const capabilities = isRecord(value.capabilities) ? value.capabilities : undefined;
 		const reasoningEffortLevels = readEffortLevels(value);
@@ -310,27 +258,29 @@ function parseLegacyHyperModels(payload: Record<string, unknown>): ProviderModel
 			headers: { ...hyperModelHeaders },
 			...(contextWindow !== undefined ? { contextWindow } : {}),
 			...(maxTokens !== undefined ? { maxTokens } : {}),
-			cost: cost ?? costFallbackFor(id),
-			pricingSource: cost ? "provider" : "fallback",
+			...(cost ? { cost, pricingSource: "provider" as const } : {}),
 			compat: { ...baseHyperCompat, supportsReasoningEffort },
 		};
-		models.push(applyModelOverride(mapped));
+		models.push(mapped);
 		seenIds.add(normalizedId);
 	}
-	return models;
+	return { models, diagnostics: { rejectedCount, duplicateCount } };
+}
+
+function parseHyperCatalog(payload: unknown): ParsedHyperCatalog {
+	if (!isRecord(payload)) return { models: [], diagnostics: { rejectedCount: 0, duplicateCount: 0 } };
+	return parseCurrentHyperModels(payload) ?? parseLegacyHyperModels(payload);
 }
 
 export function parseHyperModels(payload: unknown): ProviderModelDraft[] {
-	if (!isRecord(payload)) return [];
-	const currentModels = parseCurrentHyperModels(payload);
-	return currentModels ?? parseLegacyHyperModels(payload);
+	return parseHyperCatalog(payload).models;
 }
 
 async function discoverHyperModels(
 	fetchFn: typeof globalThis.fetch,
 	timeoutMs: number,
 	externalSignal?: AbortSignal,
-): Promise<ProviderModelDraft[]> {
+): Promise<ModelCatalogDiscoveryResult> {
 	return withDeadline(
 		async (signal) => {
 			let endpoint = HYPER_PROVIDER_URL;
@@ -354,12 +304,12 @@ async function discoverHyperModels(
 					"badjson",
 				);
 			}
-			const models = parseHyperModels(payload);
-			if (models.length === 0) {
+			const parsed = parseHyperCatalog(payload);
+			if (parsed.models.length === 0) {
 				throw new ProviderDataError("Charm Hyper model discovery returned no valid models", "badjson");
 			}
-			normalizeProviderModels(models);
-			return models;
+			normalizeProviderModels(parsed.models);
+			return parsed;
 		},
 		timeoutMs,
 		externalSignal,
@@ -384,10 +334,6 @@ type HyperStoredModel = NonNullable<HyperModelsStoreEntry>["models"][number] & {
 	pricingSource?: ProviderModelDraft["pricingSource"];
 };
 
-function isValidTimestamp(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
 function draftsFromStoredModels(entry: HyperModelsStoreEntry): ProviderModelDraft[] | undefined {
 	if (!entry || !Array.isArray(entry.models) || entry.models.length === 0) return undefined;
 	try {
@@ -412,113 +358,23 @@ function storedModelsFromDrafts(models: ProviderModelDraft[]): HyperStoredModel[
 	});
 }
 
-async function publishCatalog(
-	context: ProviderRefreshContext,
-	models: ProviderModelDraft[],
-	checkedAt: number,
-	update: () => void,
-): Promise<boolean> {
-	try {
-		return await context.publish({ persist: { models: storedModelsFromDrafts(models), checkedAt }, update });
-	} catch {
-		// Persistence is an optimization. Retry the generation-checked in-memory update without it.
-		try {
-			return await context.publish({ update });
-		} catch {
-			return false;
-		}
-	}
-}
-
 export function createCharmHyperAdapter(
 	fetchFn: typeof globalThis.fetch,
 	discoveryTimeoutMs: number,
 	now: () => number = Date.now,
 ): ProviderAdapter {
-	let models = getHyperFallbackModels();
-	let lastRefreshAt: number | undefined;
-	let lastCatalogUpdatedAt: number | undefined;
-	let inFlightRefresh: { signal: AbortSignal; request: Promise<ProviderModelDraft[]> } | undefined;
-	const catalog: ModelCatalogStatus = { source: "fallback", modelCount: models.length };
 	let provider: ProviderAdapter["provider"];
-
-	const publishModels = (
-		nextModels: ProviderModelDraft[],
-		source: ModelCatalogStatus["source"],
-		updatedAt?: number,
-	) => {
-		models = nextModels;
-		provider.models = models;
-		catalog.source = source;
-		catalog.modelCount = models.length;
-		catalog.lastError = undefined;
-		if (updatedAt !== undefined) {
-			catalog.updatedAt = updatedAt;
-			lastCatalogUpdatedAt = updatedAt;
-		}
-	};
-
-	const restoreStoredModels = async (context: ProviderRefreshContext, entry: HyperModelsStoreEntry): Promise<void> => {
-		const restoredModels = draftsFromStoredModels(entry);
-		if (!restoredModels) return;
-		const checkedAt = isValidTimestamp(entry?.checkedAt) ? entry.checkedAt : undefined;
-		if (lastCatalogUpdatedAt !== undefined && checkedAt !== undefined && checkedAt <= lastCatalogUpdatedAt) return;
-		if (lastCatalogUpdatedAt !== undefined && checkedAt === undefined) return;
-		try {
-			await context.publish({
-				update: () => {
-					publishModels(restoredModels, "live", checkedAt);
-					if (checkedAt !== undefined) lastRefreshAt = checkedAt;
-				},
-			});
-		} catch {
-			// A stale or cancelled refresh must not replace the current in-memory catalog.
-		}
-	};
-
-	const isFresh = (timestamp: number | undefined, currentTime: number): boolean =>
-		timestamp !== undefined && Math.max(0, currentTime - timestamp) <= HYPER_MODEL_CATALOG_TTL_MS;
-
-	const refreshModels = async (context: ProviderRefreshContext): Promise<ProviderModelDraft[]> => {
-		await restoreStoredModels(context, context.stored);
-		if (context?.allowNetwork !== true || context.signal?.aborted) return [...models];
-
-		const currentTime = now();
-		if (!context.force && isFresh(lastRefreshAt, currentTime)) return [...models];
-		if (inFlightRefresh?.signal === context.signal) return inFlightRefresh.request;
-
-		const request = (async (): Promise<ProviderModelDraft[]> => {
-			try {
-				const refreshedModels = await discoverHyperModels(fetchFn, discoveryTimeoutMs, context.signal);
-				if (context.signal?.aborted) {
-					throw context.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
-				}
-				const updatedAt = now();
-				await publishCatalog(context, refreshedModels, updatedAt, () => {
-					publishModels(refreshedModels, "live", updatedAt);
-					lastRefreshAt = updatedAt;
-				});
-				return [...models];
-			} catch (error) {
-				if (!context.signal.aborted && !isAbortError(error)) {
-					lastRefreshAt = now();
-					catalog.lastError = catalogErrorCode(error);
-				}
-				throw error;
-			}
-		})();
-		const activeRefresh = { signal: context.signal, request };
-		inFlightRefresh = activeRefresh;
-		void request.then(
-			() => {
-				if (inFlightRefresh === activeRefresh) inFlightRefresh = undefined;
-			},
-			() => {
-				if (inFlightRefresh === activeRefresh) inFlightRefresh = undefined;
-			},
-		);
-		return request;
-	};
+	const lifecycle = createModelCatalogLifecycle({
+		ttlMs: HYPER_MODEL_CATALOG_TTL_MS,
+		now,
+		discover: (context) => discoverHyperModels(fetchFn, discoveryTimeoutMs, context.signal),
+		restore: draftsFromStoredModels,
+		persist: (models, checkedAt) => ({ models: storedModelsFromDrafts(models), checkedAt }),
+		onUpdate: (models) => {
+			if (provider) provider.models = models;
+		},
+		errorCode: catalogErrorCode,
+	});
 
 	provider = {
 		name: "Charm Hyper",
@@ -526,12 +382,12 @@ export function createCharmHyperAdapter(
 		apiKey: "$HYPER_API_KEY",
 		authHeader: true,
 		api: "openai-completions",
-		models,
-		refreshModels,
+		models: lifecycle.getModels(),
+		refreshModels: lifecycle.refreshModels,
 		oauth: createCharmHyperOAuth(fetchFn, now),
 	};
 
-	return { id: "charm-hyper", catalog, provider };
+	return { id: "charm-hyper", catalog: lifecycle.catalog, provider };
 }
 
 const charmHyperProviderExtension = defineProviderExtension({