@oh-my-pi/pi-catalog 15.10.11

package/src/identity/family.ts

@@ -0,0 +1,88 @@
+/**
+ * Model-family id predicates: the shared vocabulary for "is this id a member
+ * of family X" checks that gate wire-level behavior across hosts (a Kimi or
+ * DeepSeek model keeps its quirks no matter which OpenAI-compatible proxy
+ * serves it). Looser per-feature heuristics (e.g. stream-markup healing)
+ * deliberately keep their own patterns — only provably-shared matchers live
+ * here.
+ */
+
+import { bareModelId, isFableOrMythos, parseAnthropicModel, semverGte } from "./classify";
+
+/** Kimi family ids in any namespace form (`moonshotai/kimi-*`, `kimi-k2.6`, `vendor/kimi.x`). */
+export function isKimiModelId(modelId: string): boolean {
+	return modelId.includes("moonshotai/kimi") || /(^|\/)kimi[-.]/i.test(modelId);
+}
+
+/** Kimi K2.6 specifically (preserved-thinking transport on Moonshot-native hosts). */
+export function isKimiK26ModelId(modelId: string): boolean {
+	return /(^|\/)kimi-k2\.6(?:[-:]|$)/i.test(modelId);
+}
+
+/** Claude ids in any namespace form (`claude-*`, `vendor/claude.x`). */
+export function isClaudeModelId(modelId: string): boolean {
+	return /(^|\/)claude[-.]/i.test(modelId);
+}
+
+/** `anthropic/`-namespaced ids (aggregator catalogs like OpenRouter). */
+export function isAnthropicNamespacedModelId(modelId: string): boolean {
+	return /(^|\/)anthropic\//i.test(modelId);
+}
+
+/** Qwen family ids (substring match — Qwen SKUs have no stable prefix shape). */
+export function isQwenModelId(modelId: string): boolean {
+	return modelId.toLowerCase().includes("qwen");
+}
+
+/** DeepSeek family by id or display name (proxies often rename the id but keep the name). */
+export function isDeepseekModelIdOrName(value: string): boolean {
+	return value.toLowerCase().includes("deepseek");
+}
+
+/** Xiaomi MiMo family by id or display name. */
+export function isMimoModelIdOrName(value: string): boolean {
+	return value.toLowerCase().includes("mimo");
+}
+
+/**
+ * Adaptive thinking `display` is supported starting with Claude Opus 4.7 and
+ * the Claude Fable/Mythos 5 generation. Older adaptive-thinking models
+ * (Opus 4.6, Sonnet 4.6+) reject the field. Classifier-based, so dotted and
+ * dashed version forms both match while bare dated ids
+ * (`claude-opus-4-20250514` = Opus 4.0) stay excluded.
+ */
+export function supportsAdaptiveThinkingDisplay(modelId: string): boolean {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	if (!parsed) return false;
+	if (isFableOrMythos(parsed.kind)) return semverGte(parsed.version, "5");
+	return parsed.kind === "opus" && semverGte(parsed.version, "4.7");
+}
+
+/**
+ * Returns true for Anthropic models with Opus 4.7+/Fable/Mythos API restrictions:
+ * - Sampling parameters (temperature/top_p/top_k) return 400 error
+ * - Thinking content is omitted by default (needs display: "summarized")
+ */
+export function hasOpus47ApiRestrictions(modelId: string): boolean {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	if (!parsed) return false;
+	return (parsed.kind === "opus" && semverGte(parsed.version, "4.7")) || isFableOrMythos(parsed.kind);
+}
+
+/**
+ * Mid-conversation `role: "system"` messages (system instructions appended at
+ * non-first positions in the `messages` array) are supported starting with
+ * Claude Opus 4.8 and the Claude Fable/Mythos 5 generation. Earlier Claude
+ * models reject the role.
+ * @see https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
+ */
+export function supportsMidConversationSystemMessages(modelId: string): boolean {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	if (!parsed) return false;
+	return (parsed.kind === "opus" && semverGte(parsed.version, "4.8")) || isFableOrMythos(parsed.kind);
+}
+
+export function isAnthropicFableOrMythosModel(modelId: string): boolean {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	return parsed !== null && isFableOrMythos(parsed.kind);
+}

package/src/identity/id.ts

@@ -0,0 +1,81 @@
+const LEADING_BRACKETED_AFFIX_PATTERN = /^(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+/u;
+const TRAILING_BRACKETED_AFFIX_PATTERN = /(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+$/u;
+const MODEL_ID_SEGMENT_PATTERN = /[a-z0-9.:-]+/g;
+const MODEL_FAMILY_PREFIX_PATTERN =
+	/^(claude|gemini|gpt|grok|glm|qwen|deepseek|kimi|mimo|doubao|ernie|gpt-oss|gemma|minimax|step|command|jamba|llama|o[1345])/i;
+
+function normalizeModelIdWhitespace(value: string): string {
+	return value.trim().replace(/\s+/g, " ");
+}
+
+/** Ordering for model-like segments: longest first, ties broken lexicographically. */
+function compareSegmentPreference(left: string, right: string): number {
+	return left.length !== right.length ? right.length - left.length : left.localeCompare(right);
+}
+
+export function getModelLikeIdSegments(modelId: string): string[] {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return [];
+	const segments = new Set<string>();
+	for (const segment of matches) {
+		if (MODEL_FAMILY_PREFIX_PATTERN.test(segment) && /\d/.test(segment)) segments.add(segment);
+	}
+	return [...segments].sort(compareSegmentPreference);
+}
+
+export function getLongestModelLikeIdSegment(modelId: string): string | undefined {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return undefined;
+	let best: string | undefined;
+	for (const segment of matches) {
+		if (
+			MODEL_FAMILY_PREFIX_PATTERN.test(segment) &&
+			/\d/.test(segment) &&
+			(best === undefined || compareSegmentPreference(segment, best) < 0)
+		) {
+			best = segment;
+		}
+	}
+	return best;
+}
+
+function hasBracketAffixMarker(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 91 || code === 93 || code === 0x3010 || code === 0x3011) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Strip reseller / wrapper tags that are injected as bracketed affixes around an
+ * upstream model id, e.g.
+ *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
+ *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
+ */
+export function getBracketStrippedModelIdCandidates(modelId: string): string[] {
+	if (!hasBracketAffixMarker(modelId)) return [];
+	const normalized = normalizeModelIdWhitespace(modelId);
+	if (!normalized) return [];
+
+	const strippedLeading = normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "");
+	const withoutLeading = normalizeModelIdWhitespace(strippedLeading);
+	const withoutTrailing = normalizeModelIdWhitespace(normalized.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+	const withoutBoth = normalizeModelIdWhitespace(strippedLeading.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+
+	const candidates = new Set<string>();
+	for (const candidate of [withoutBoth, withoutLeading, withoutTrailing]) {
+		if (candidate && candidate !== normalized) {
+			candidates.add(candidate);
+		}
+	}
+	return [...candidates];
+}
+
+export function stripBracketedModelIdAffixes(modelId: string): string | undefined {
+	return getBracketStrippedModelIdCandidates(modelId)[0];
+}

package/src/identity/index.ts

@@ -0,0 +1,9 @@
+export * from "./bundled";
+export * from "./classify";
+export * from "./equivalence";
+export * from "./family";
+export * from "./id";
+export * from "./markers";
+export * from "./priority";
+export * from "./reference";
+export * from "./selection";

package/src/identity/markers.ts

@@ -0,0 +1,49 @@
+/**
+ * Trailing-marker vocabulary shared by canonical-id resolution and
+ * proxy-reference lookup. A "marker" is a routing/quantization/effort suffix
+ * a reseller or aggregator appends to an upstream model id
+ * (`-thinking`, `:nitro`, `-fp8`, …) that does not change model identity.
+ */
+const TRAILING_MARKERS = [
+	"thinking",
+	"customtools",
+	"high",
+	"low",
+	"medium",
+	"minimal",
+	"xhigh",
+	"free",
+	"cloud",
+	"exacto",
+	"nitro",
+	"original",
+	"optimized",
+	"nvfp4",
+	"fp8",
+	"fp4",
+	"bf16",
+	"int8",
+	"int4",
+] as const;
+
+/**
+ * Markers treated as identity-preserving ONLY when recovering bundled metadata
+ * for a proxied model id, never during canonical-id coalescing: Perplexity's
+ * `sonar-pro-search` is a distinct model from `sonar-pro`, so canonical
+ * resolution must not strip `search`, while a proxy id like
+ * `claude-opus-4-6-search` should still inherit the upstream pricing/limits.
+ */
+const REFERENCE_ONLY_TRAILING_MARKERS = ["search"] as const;
+
+function buildTrailingMarkerPattern(markers: readonly string[]): RegExp {
+	return new RegExp(`[-:](?:${markers.join("|")})$`, "i");
+}
+
+/** Marker pattern used by canonical-id resolution (`search` excluded). */
+export const CANONICAL_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern(TRAILING_MARKERS);
+
+/** Marker pattern used by proxy-reference lookup (`search` included). */
+export const REFERENCE_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern([
+	...TRAILING_MARKERS,
+	...REFERENCE_ONLY_TRAILING_MARKERS,
+]);

package/src/identity/priority.ts

@@ -0,0 +1,56 @@
+const DEFAULT_MODEL_PROVIDER_ORDER = [
+	// First-party / native account providers. Prefer these over relays when the
+	// same upstream model is available in more than one place.
+	"openai-codex",
+	"anthropic",
+	"openai",
+	"google-gemini-cli",
+	"google",
+	"google-vertex",
+	"kimi-code",
+	"moonshot",
+	"qwen-portal",
+	"zai",
+	"xai-oauth",
+	"xai",
+	"mistral",
+	"deepseek",
+	"groq",
+
+	// High-quality aggregators / hosted inference providers.
+	"fireworks",
+	"cerebras",
+	"openrouter",
+	"aimlapi",
+	"together",
+
+	// Generic gateways and editor/proxy providers. These are useful when picked
+	// explicitly, but should not win ambiguous automatic role selection.
+	"alibaba-coding-plan",
+	"google-antigravity",
+	"opencode-zen",
+	"gitlab-duo",
+	"opencode-go",
+	"kilo",
+	"vercel-ai-gateway",
+	"cloudflare-ai-gateway",
+	"nanogpt",
+	"github-copilot",
+] as const;
+
+function addProviderRank(rank: Map<string, number>, provider: string): void {
+	const normalized = provider.trim().toLowerCase();
+	if (!normalized || rank.has(normalized)) return;
+	rank.set(normalized, rank.size);
+}
+
+export function buildModelProviderPriorityRank(configuredProviderOrder?: readonly string[]): Map<string, number> {
+	const rank = new Map<string, number>();
+	for (const provider of configuredProviderOrder ?? []) {
+		addProviderRank(rank, provider);
+	}
+	for (const provider of DEFAULT_MODEL_PROVIDER_ORDER) {
+		addProviderRank(rank, provider);
+	}
+	return rank;
+}

package/src/identity/reference.ts

@@ -0,0 +1,134 @@
+/**
+ * Proxy/reseller reference lookup: given a custom model id served through a
+ * proxy (`[Kiro] claude-opus-4-8`, `gpt-5.4:cloud`, `vendor/claude-sonnet-4-6-thinking`),
+ * find the bundled upstream model so missing pricing/capability metadata can be
+ * inherited while keeping the custom transport.
+ *
+ * Kept separate from canonical-id resolution (`./equivalence`): this lookup
+ * may strip `search`-style markers and prefers cache-pricing-complete
+ * references, both of which would be wrong for canonical coalescing.
+ */
+import type { Api, Model } from "../types";
+import { getBracketStrippedModelIdCandidates, getLongestModelLikeIdSegment, getModelLikeIdSegments } from "./id";
+import { REFERENCE_TRAILING_MARKER_PATTERN } from "./markers";
+
+export interface ModelReferenceIndex {
+	exact: Map<string, Model<Api>>;
+	suffixAlias: Map<string, Model<Api>>;
+}
+
+// Custom provider entries often front a known upstream model through a local proxy.
+// Prefer the reference with the largest limits and complete cache pricing, then
+// first-party OpenAI entries.
+function shouldReplaceReference(existing: Model<Api> | undefined, candidate: Model<Api>): boolean {
+	if (!existing) return true;
+	if (candidate.contextWindow !== existing.contextWindow) {
+		return candidate.contextWindow > existing.contextWindow;
+	}
+	if (candidate.maxTokens !== existing.maxTokens) {
+		return candidate.maxTokens > existing.maxTokens;
+	}
+	const existingHasCachePricing = existing.cost.cacheRead > 0 || existing.cost.cacheWrite > 0;
+	const candidateHasCachePricing = candidate.cost.cacheRead > 0 || candidate.cost.cacheWrite > 0;
+	if (candidateHasCachePricing !== existingHasCachePricing) {
+		return candidateHasCachePricing;
+	}
+	return existing.provider !== "openai" && candidate.provider === "openai";
+}
+
+function normalizeReferenceKey(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+/**
+ * Build a reference index from a model catalog (typically the bundled models).
+ * Pure: callers are responsible for memoizing the result.
+ */
+export function buildModelReferenceIndex(models: Iterable<Model<Api>>): ModelReferenceIndex {
+	const exact = new Map<string, Model<Api>>();
+	for (const candidate of models) {
+		const key = normalizeReferenceKey(candidate.id);
+		if (shouldReplaceReference(exact.get(key), candidate)) {
+			exact.set(key, candidate);
+		}
+	}
+	return { exact, suffixAlias: buildSuffixAliasMap(exact) };
+}
+
+function buildSuffixAliasMap(exactReferences: ReadonlyMap<string, Model<Api>>): Map<string, Model<Api>> {
+	const aliases = new Map<string, Model<Api>>();
+	for (const reference of exactReferences.values()) {
+		const slashIndex = reference.id.lastIndexOf("/");
+		if (slashIndex === -1) {
+			continue;
+		}
+		const suffix = reference.id.slice(slashIndex + 1);
+		const alias = getLongestModelLikeIdSegment(suffix);
+		if (!alias) {
+			continue;
+		}
+		if (shouldReplaceReference(aliases.get(alias), reference)) {
+			aliases.set(alias, reference);
+		}
+	}
+	return aliases;
+}
+
+function stripReferenceTrailingMarker(candidate: string): string | undefined {
+	const match = REFERENCE_TRAILING_MARKER_PATTERN.exec(candidate);
+	return match ? candidate.slice(0, match.index) : undefined;
+}
+
+function getReferenceCandidateIds(modelId: string): string[] {
+	const candidates = new Set<string>();
+	const queue = [modelId];
+	for (let index = 0; index < queue.length; index += 1) {
+		const candidate = queue[index]?.trim();
+		if (!candidate || candidates.has(candidate)) continue;
+		candidates.add(candidate);
+
+		for (const stripped of getBracketStrippedModelIdCandidates(candidate)) {
+			queue.push(stripped);
+		}
+		for (const segment of getModelLikeIdSegments(candidate)) {
+			queue.push(segment);
+		}
+
+		for (const suffix of [":cloud", "-cloud"] as const) {
+			if (candidate.toLowerCase().endsWith(suffix)) {
+				queue.push(candidate.slice(0, -suffix.length));
+			}
+		}
+
+		const slashIndex = candidate.lastIndexOf("/");
+		if (slashIndex !== -1) {
+			queue.push(candidate.slice(slashIndex + 1));
+		}
+
+		const colonToDash = candidate.replace(/:/g, "-");
+		if (colonToDash !== candidate) {
+			queue.push(colonToDash);
+		}
+
+		const lowercased = candidate.toLowerCase();
+		if (lowercased !== candidate) {
+			queue.push(lowercased);
+		}
+
+		const strippedMarker = stripReferenceTrailingMarker(candidate);
+		if (strippedMarker) {
+			queue.push(strippedMarker);
+		}
+	}
+	return [...candidates];
+}
+
+/** Resolve a (possibly proxied/affixed) model id to its bundled upstream reference. */
+export function resolveModelReference(modelId: string, index: ModelReferenceIndex): Model<Api> | undefined {
+	for (const candidate of getReferenceCandidateIds(modelId)) {
+		const key = normalizeReferenceKey(candidate);
+		const reference = index.exact.get(key) ?? index.suffixAlias.get(key);
+		if (reference) return reference;
+	}
+	return undefined;
+}

package/src/identity/selection.ts

@@ -0,0 +1,65 @@
+/**
+ * Canonical-variant selection: pick the preferred variant of a canonical
+ * model record given caller-supplied provider and candidate orderings.
+ */
+import type { Api, Model } from "../types";
+import { type CanonicalModelVariant, formatCanonicalVariantSelector } from "./equivalence";
+
+export interface CanonicalVariantPreferences {
+	/** Lowercased provider id → rank (lower wins). */
+	providerRank: ReadonlyMap<string, number>;
+	/** Variant selector (`provider/id`) → candidate-list position (lower wins). */
+	modelOrder: ReadonlyMap<string, number>;
+}
+
+/** Selector → index map over an ordered candidate list, for `modelOrder` tiebreaks. */
+export function buildCanonicalModelOrder(candidates: readonly Model<Api>[]): Map<string, number> {
+	const modelOrder = new Map<string, number>();
+	for (let index = 0; index < candidates.length; index += 1) {
+		modelOrder.set(formatCanonicalVariantSelector(candidates[index]!), index);
+	}
+	return modelOrder;
+}
+
+const SOURCE_RANK: Record<CanonicalModelVariant["source"], number> = {
+	override: 1,
+	bundled: 1,
+	heuristic: 2,
+	fallback: 3,
+};
+
+/**
+ * Pick the preferred variant. Sort order: configured provider rank →
+ * exact-id match → variant source (override/bundled > heuristic > fallback)
+ * → shorter id → candidate-list order.
+ */
+export function resolveCanonicalVariant(
+	variants: readonly CanonicalModelVariant[],
+	preferences: CanonicalVariantPreferences,
+): CanonicalModelVariant | undefined {
+	if (variants.length === 0) {
+		return undefined;
+	}
+	const { providerRank, modelOrder } = preferences;
+	return [...variants].sort((left, right) => {
+		const leftProviderRank = providerRank.get(left.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
+		const rightProviderRank = providerRank.get(right.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
+		if (leftProviderRank !== rightProviderRank) {
+			return leftProviderRank - rightProviderRank;
+		}
+		const leftExact = left.model.id === left.canonicalId ? 0 : 1;
+		const rightExact = right.model.id === right.canonicalId ? 0 : 1;
+		if (leftExact !== rightExact) {
+			return leftExact - rightExact;
+		}
+		if (SOURCE_RANK[left.source] !== SOURCE_RANK[right.source]) {
+			return SOURCE_RANK[left.source] - SOURCE_RANK[right.source];
+		}
+		if (left.model.id.length !== right.model.id.length) {
+			return left.model.id.length - right.model.id.length;
+		}
+		const leftOrder = modelOrder.get(left.selector) ?? Number.MAX_SAFE_INTEGER;
+		const rightOrder = modelOrder.get(right.selector) ?? Number.MAX_SAFE_INTEGER;
+		return leftOrder - rightOrder;
+	})[0];
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./compat/openai";
+export * from "./discovery";
+export * from "./effort";
+export * from "./fireworks-model-id";
+export * from "./identity";
+export * from "./model-cache";
+export * from "./model-manager";
+export * from "./model-thinking";
+export * from "./models";
+export * from "./provider-models";
+export * from "./types";
+export * from "./utils";
+export * from "./wire/codex";
+export * from "./wire/gemini-headers";
+export * from "./wire/github-copilot";

package/src/model-cache.ts

@@ -0,0 +1,132 @@
+/**
+ * SQLite-backed model cache for atomic cross-process access.
+ * Replaces per-provider JSON files with a single cache.db.
+ */
+import { Database } from "bun:sqlite";
+import { getModelDbPath } from "@oh-my-pi/pi-utils";
+import type { Api, Model, ModelSpec } from "./types";
+
+// Rows persist ModelSpec JSON (sparse `compat`, never the resolved record);
+// the model manager rebuilds via `buildModel` on load. v4 invalidates rows
+// carrying the pre-efforts ThinkingConfig shape (minLevel/maxLevel/levels).
+const CACHE_SCHEMA_VERSION = 4;
+
+interface CacheRow {
+	provider_id: string;
+	version: number;
+	updated_at: number;
+	authoritative: number;
+	static_fingerprint: string;
+	models: string;
+}
+
+interface TableInfoRow {
+	name: string;
+}
+
+interface CacheEntry<TApi extends Api = Api> {
+	models: ModelSpec<TApi>[];
+	fresh: boolean;
+	authoritative: boolean;
+	updatedAt: number;
+	/**
+	 * Hash of the static catalog slice that was merged into `models` when this
+	 * row was written. `resolveProviderModels` compares against the current
+	 * static fingerprint and bypasses the static+cache re-merge when they
+	 * match — the cache already incorporates the same static state.
+	 */
+	staticFingerprint: string;
+}
+
+let sharedDb: Database | null = null;
+let sharedDbPath: string | null = null;
+
+function getDb(dbPath?: string): Database {
+	const resolvedPath = dbPath ?? getModelDbPath();
+	if (sharedDb && sharedDbPath === resolvedPath) {
+		return sharedDb;
+	}
+	if (sharedDb) {
+		sharedDb.close();
+	}
+	const db = new Database(resolvedPath, { create: true });
+	db.run("PRAGMA journal_mode = WAL");
+	db.run("PRAGMA busy_timeout = 3000");
+	db.run(`
+		CREATE TABLE IF NOT EXISTS model_cache (
+			provider_id TEXT PRIMARY KEY,
+			version INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			authoritative INTEGER NOT NULL DEFAULT 0,
+			static_fingerprint TEXT NOT NULL DEFAULT '',
+			models TEXT NOT NULL
+		)
+	`);
+	migrateCacheSchema(db);
+
+	sharedDb = db;
+	sharedDbPath = resolvedPath;
+	return db;
+}
+
+function migrateCacheSchema(db: Database): void {
+	const columns = db.prepare("PRAGMA table_info(model_cache)").all() as TableInfoRow[];
+	if (!columns.some(column => column.name === "static_fingerprint")) {
+		db.run("ALTER TABLE model_cache ADD COLUMN static_fingerprint TEXT NOT NULL DEFAULT ''");
+	}
+	db.run("UPDATE model_cache SET version = ? WHERE version = 2", [CACHE_SCHEMA_VERSION]);
+}
+
+export function readModelCache<TApi extends Api>(
+	providerId: string,
+	ttlMs: number,
+	now: () => number,
+	dbPath?: string,
+): CacheEntry<TApi> | null {
+	try {
+		const db = getDb(dbPath);
+		const row = db.query<CacheRow, [string]>("SELECT * FROM model_cache WHERE provider_id = ?").get(providerId);
+		if (!row || row.version !== CACHE_SCHEMA_VERSION) {
+			return null;
+		}
+		const models = JSON.parse(row.models) as ModelSpec<TApi>[];
+		const ageMs = now() - row.updated_at;
+		const fresh = Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= ttlMs;
+		return {
+			models,
+			fresh,
+			authoritative: row.authoritative === 1,
+			updatedAt: row.updated_at,
+			staticFingerprint: row.static_fingerprint ?? "",
+		};
+	} catch {
+		return null;
+	}
+}
+
+export function writeModelCache<TApi extends Api>(
+	providerId: string,
+	updatedAt: number,
+	models: Model<TApi>[],
+	authoritative: boolean,
+	staticFingerprint: string,
+	dbPath?: string,
+): void {
+	try {
+		const db = getDb(dbPath);
+		db.run(
+			`INSERT OR REPLACE INTO model_cache (provider_id, version, updated_at, authoritative, static_fingerprint, models)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+			[
+				providerId,
+				CACHE_SCHEMA_VERSION,
+				updatedAt,
+				authoritative ? 1 : 0,
+				staticFingerprint,
+				JSON.stringify(models.map(model => ({ ...model, compat: model.compatConfig, compatConfig: undefined }))),
+			],
+		);
+	} catch {
+		// Cache writes are best-effort; failures should not break model resolution.
+	}
+}