@oh-my-pi/pi-catalog 18.2.0 → 18.2.2

package/src/compat/types.ts

@@ -293,6 +293,12 @@ export interface CompiledExcludeModels {
 	match: CompiledMatchList;
 }
 
+/** Exact upstream discovery modes excluded from one provider's coding-model roster. */
+export interface CompiledExcludeDiscoveryModes {
+	provider: string;
+	modes: string[];
+}
+
 /** Provider plan-requirement tiers keyed by matcher token lists. */
 export interface CompiledPlanRequirement {
 	provider: string;
@@ -306,6 +312,12 @@ export interface CompiledPricingPeer {
 	aliases: { model: string; peerId: string }[];
 }
 
+/** Provider timezone assumption for offset-less absolute retry-reset timestamps. */
+export interface CompiledRetryResetTimezone {
+	provider: string;
+	offset: string;
+}
+
 /** Compiled runtime behavior vocabulary (`runtime/behavior.kdl`). */
 export interface CompiledBehavior {
 	openaiResponsesHeuristic?: CompiledResponsesHeuristic;
@@ -316,10 +328,13 @@ export interface CompiledBehavior {
 	hostedDefaults: CompiledHostedDefault[];
 	apiRoutes: CompiledApiRoutes[];
 	modelLimits: CompiledModelLimits[];
+	excludeDiscoveryModes: CompiledExcludeDiscoveryModes[];
 	excludeModels: CompiledExcludeModels[];
 	planRequirements: CompiledPlanRequirement[];
 	pricingPeers: CompiledPricingPeer[];
+	retryResetTimezones: CompiledRetryResetTimezone[];
 	retiredProviders: string[];
+	referenceIsolatedProviders: string[];
 }
 
 /**
@@ -672,4 +687,12 @@ export interface ResolvedAxes {
 	wire: Record<string, unknown>;
 	thinking: Record<string, unknown>;
 	catalog: Record<string, unknown>;
+	/**
+	 * Reasoning capability after the exact-model effort upgrade: `true` when the
+	 * target reported reasoning or an exact rule declares a ladder for it (the
+	 * reviewed correction to metadata-less discovery rows). Compat resolvers
+	 * read this instead of the raw spec flag, or one id resolves two different
+	 * wire contracts depending on whether it came from discovery or the bake.
+	 */
+	reasoning: boolean;
 }

package/src/discovery/antigravity.ts

@@ -1,4 +1,5 @@
 import { type } from "@oh-my-pi/omptype";
+import type { FetchImpl } from "@oh-my-pi/pi-utils";
 import { collapseVariants, type VariantCollapseTable } from "../compat/collapse";
 import type { ModelSpec } from "../types";
 import { discoveryFetch, toPositiveNumber } from "../utils";
@@ -51,6 +52,7 @@ export interface AntigravityDiscoveryAgentModelSort {
 export interface AntigravityDiscoveryApiResponse {
 	models?: Record<string, AntigravityDiscoveryApiModel>;
 	agentModelSorts?: AntigravityDiscoveryAgentModelSort[];
+	imageGenerationModelIds?: string[];
 }
 const AntigravityDiscoveryApiModelSchema = type({
 	"displayName?": type("unknown").pipe(value => (typeof value === "string" ? value : undefined)),
@@ -123,6 +125,9 @@ const AntigravityDiscoveryApiResponseSchema = type({
 		}
 		return result;
 	}),
+	"imageGenerationModelIds?": type("unknown").pipe(value =>
+		Array.isArray(value) ? value.filter((modelId): modelId is string => typeof modelId === "string") : undefined,
+	),
 });
 /**
  * Options for fetching Antigravity discovery models.
@@ -139,7 +144,7 @@ export interface FetchAntigravityDiscoveryModelsOptions {
 	/** Optional abort signal for request cancellation. */
 	signal?: AbortSignal;
 	/** Optional fetch implementation override for tests. */
-	fetcher?: typeof fetch;
+	fetcher?: FetchImpl;
 	/**
 	 * Hand collapse table to apply to the discovered list. Defaults to the
 	 * Antigravity (budget-transport) table; `googleGeminiCli` passes the
@@ -157,6 +162,78 @@ export interface FetchAntigravityDiscoveryModelsOptions {
 export async function fetchAntigravityDiscoveryModels(
 	options: FetchAntigravityDiscoveryModelsOptions,
 ): Promise<ModelSpec<"google-gemini-cli">[] | null> {
+	const discovered = await fetchAntigravityDiscoveryResponse(options);
+	if (!discovered) {
+		return null;
+	}
+
+	const models: ModelSpec<"google-gemini-cli">[] = [];
+	const apiModels = discovered.payload.models;
+	if (apiModels) {
+		for (const modelId in apiModels) {
+			const model = apiModels[modelId];
+			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId)) {
+				continue;
+			}
+			if (model.isInternal === true) {
+				continue;
+			}
+
+			const supportsImages = model.supportsImages === true;
+			models.push({
+				id: modelId,
+				name: model.displayName || modelId,
+				api: "google-gemini-cli",
+				provider: "google-antigravity",
+				baseUrl: discovered.endpoint,
+				reasoning: model.supportsThinking === true,
+				input: supportsImages ? ["text", "image"] : ["text"],
+				cost: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+				},
+				contextWindow: toPositiveNumber(model.maxTokens, DEFAULT_CONTEXT_WINDOW),
+				maxTokens: toPositiveNumber(model.maxOutputTokens, DEFAULT_MAX_TOKENS),
+			});
+		}
+	}
+
+	// Collapse effort-tier variants at the source so runtime discovery,
+	// the gemini-cli re-provision, and the catalog generator all see
+	// logical ids only.
+	const collapsed = collapseVariants(
+		models,
+		options.collapseTable === undefined ? undefined : { table: options.collapseTable },
+	);
+	collapsed.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+	return collapsed;
+}
+
+/** Advertised image model and serving endpoint for one Antigravity account. */
+export interface AntigravityImageModel {
+	id: string;
+	endpoint: string;
+}
+
+/** Resolves the first image-generation model advertised by an Antigravity account. */
+export async function fetchAntigravityImageModel(
+	options: FetchAntigravityDiscoveryModelsOptions,
+): Promise<AntigravityImageModel | null> {
+	const discovered = await fetchAntigravityDiscoveryResponse(options);
+	const id = discovered?.payload.imageGenerationModelIds?.find(modelId => modelId.length > 0);
+	return id && discovered ? { id, endpoint: discovered.endpoint } : null;
+}
+
+interface AntigravityDiscoveryResponse {
+	payload: AntigravityDiscoveryApiResponse;
+	endpoint: string;
+}
+
+async function fetchAntigravityDiscoveryResponse(
+	options: FetchAntigravityDiscoveryModelsOptions,
+): Promise<AntigravityDiscoveryResponse | null> {
 	if (options.userAgent === undefined) {
 		await ensureAntigravityVersion(options.fetcher ?? fetch, options.signal);
 	}
@@ -195,49 +272,9 @@ export async function fetchAntigravityDiscoveryModels(
 		}
 
 		const parsed = parseAntigravityDiscoveryResponse(payload);
-		if (!parsed) {
-			continue;
+		if (parsed) {
+			return { payload: parsed, endpoint };
 		}
-
-		const models: ModelSpec<"google-gemini-cli">[] = [];
-
-		for (const [modelId, model] of Object.entries(parsed.models ?? {})) {
-			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId)) {
-				continue;
-			}
-			if (model.isInternal === true) {
-				continue;
-			}
-
-			const supportsImages = model.supportsImages === true;
-			models.push({
-				id: modelId,
-				name: model.displayName || modelId,
-				api: "google-gemini-cli",
-				provider: "google-antigravity",
-				baseUrl: endpoint,
-				reasoning: model.supportsThinking === true,
-				input: supportsImages ? ["text", "image"] : ["text"],
-				cost: {
-					input: 0,
-					output: 0,
-					cacheRead: 0,
-					cacheWrite: 0,
-				},
-				contextWindow: toPositiveNumber(model.maxTokens, DEFAULT_CONTEXT_WINDOW),
-				maxTokens: toPositiveNumber(model.maxOutputTokens, DEFAULT_MAX_TOKENS),
-			});
-		}
-
-		// Collapse effort-tier variants at the source so runtime discovery,
-		// the gemini-cli re-provision, and the catalog generator all see
-		// logical ids only.
-		const collapsed = collapseVariants(
-			models,
-			options.collapseTable === undefined ? undefined : { table: options.collapseTable },
-		);
-		collapsed.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
-		return collapsed;
 	}
 
 	return null;

package/src/discovery/devin.ts

@@ -76,6 +76,8 @@ function supportsDevinThinking(config: ClientModelConfig): boolean {
 const DEVIN_COST_LABEL_INPUT = "input";
 const DEVIN_COST_LABEL_CACHE_READ = "cached input";
 const DEVIN_COST_LABEL_OUTPUT = "output";
+/** Normalized label of the marker dimension separating composite rate cards. */
+const DEVIN_SIDEKICK_LABEL = "sidekick";
 
 /** Leading token count of a cost denominator ("1M tokens", "1K tokens"). */
 const DEVIN_COST_DENOMINATOR_PATTERN = /(\d+(?:\.\d+)?)\s*([kmb])?/i;
@@ -104,10 +106,20 @@ function devinCostDenominatorTokens(denominator: string): number {
  * an estimated rate, not a different unit, so both kinds are read. `cacheWrite`
  * has no Cascade dimension — Devin bills cache writes at the input rate — and
  * stays 0.
+ *
+ * Composite configs (`fusion`) flatten their own rate card plus every
+ * dispatched component's card into one `modelDimensions` list. A `Sidekick`
+ * marker dimension separates the composite's own card from the component
+ * cards, so reading stops there: a headline card may omit dimensions a
+ * component includes, which makes repeated-label detection unreliable.
  */
 function devinModelCost(config: ClientModelConfig): ModelCost {
 	const cost: ModelCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 	for (const dimension of config.modelDimensions) {
+		const label = dimension.label.trim().toLowerCase();
+		if (label === DEVIN_SIDEKICK_LABEL) {
+			break;
+		}
 		if (dimension.kind !== ModelDimensionKind.COST && dimension.kind !== ModelDimensionKind.COST_FUZZY) {
 			continue;
 		}
@@ -115,7 +127,7 @@ function devinModelCost(config: ClientModelConfig): ModelCost {
 		// (0.1 decodes as 0.10000000149011612) at sub-cent precision.
 		const perMillion =
 			Math.round(((dimension.value * 1_000_000) / devinCostDenominatorTokens(dimension.denominator)) * 1e6) / 1e6;
-		switch (dimension.label.trim().toLowerCase()) {
+		switch (label) {
 			case DEVIN_COST_LABEL_INPUT:
 				cost.input = perMillion;
 				break;
@@ -379,14 +391,14 @@ function devinModelSpec(
 	config: ClientModelConfig,
 	uid: string,
 	baseUrl: string,
-	isRouter: boolean,
+	isAssignModelRouter: boolean,
 ): ModelSpec<"devin-agent"> {
 	const features = config.modelInfo?.modelFeatures;
 	const supportsImages =
 		(features !== undefined ? features.supportsImages : config.supportsImages) && !DEVIN_IMAGE_BLIND_UIDS.has(uid);
 	const input: ("text" | "image")[] = supportsImages ? ["text", "image"] : ["text"];
 	const compat: DevinCompat = {};
-	if (isRouter) compat.modelRouter = true;
+	if (isAssignModelRouter) compat.modelRouter = true;
 	if (features?.supportsParallelToolCalls === true) compat.supportsParallelToolCalls = true;
 	const maxOutputTokens = config.modelInfo?.maxOutputTokens ?? 0;
 	const spec: ModelSpec<"devin-agent"> = {
@@ -439,7 +451,13 @@ function normalizeDevinModels(
 		}
 		seen.add(uid);
 		const isRouter = displayOption === DisplayOption.MODEL_ROUTER || config.modelInfo?.isModelRouter === true;
-		specs.push(devinModelSpec(config, uid, baseUrl, isRouter));
+		// `isModelRouter` marks two different things: harness-less routing slots
+		// (`adaptive`, `subagent-default`) that `AssignModel` resolves into a
+		// concrete model, and harness-backed composites (`fusion`,
+		// `fusion-sidekick-*`) that are themselves valid chat uids. Only the
+		// former take the `AssignModel` path — sending a composite uid there 404s.
+		const isAssignModelRouter = isRouter && (config.modelInfo?.harnessUids.length ?? 0) === 0;
+		specs.push(devinModelSpec(config, uid, baseUrl, isAssignModelRouter));
 		// A router is a server-side dispatcher, not an effort tier: it stays a
 		// standalone model even when upstream files it under a family.
 		if (!isRouter) {

package/src/identity/bundled.ts

@@ -6,6 +6,7 @@
  * non-bundled reference data use the pure builder directly
  * ({@link buildModelReferenceIndex}).
  */
+import { isBareIdReferenceProvider } from "../compat/behavior";
 import { getBundledModels, getBundledProviders } from "../models";
 import type { Api, Model } from "../types";
 import { buildModelReferenceIndex, type ModelReferenceIndex } from "./reference";
@@ -13,9 +14,9 @@ import { buildModelReferenceIndex, type ModelReferenceIndex } from "./reference"
 let bundledModels: readonly Model<Api>[] | undefined;
 
 function getBundledModelList(): readonly Model<Api>[] {
-	bundledModels ??= getBundledProviders().flatMap(
-		provider => getBundledModels(provider as Parameters<typeof getBundledModels>[0]) as Model<Api>[],
-	);
+	bundledModels ??= getBundledProviders()
+		.filter(isBareIdReferenceProvider)
+		.flatMap(provider => getBundledModels(provider as Parameters<typeof getBundledModels>[0]) as Model<Api>[]);
 	return bundledModels;
 }
 

package/src/model-cache.ts

@@ -2,9 +2,8 @@
  * 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 { renameSync } from "node:fs";
-import { getModelDbPath, isEnoent, isSqliteCorruptionError, logger, VERSION } from "@oh-my-pi/pi-utils";
+import type { Database } from "bun:sqlite";
+import { getModelDbPath, isSqliteCorruptionError, openSqliteDatabaseSync, VERSION } from "@oh-my-pi/pi-utils";
 import RULES from "./compat/rules.json" with { type: "json" };
 import type { Api, Model } from "./types";
 
@@ -31,12 +30,19 @@ const HEADER_RESTORE_VERSION = 1;
  * Explicit compatibility gate for materialized rows. Bump whenever buildModel
  * semantics change without an app-version change. The compiled-rules content
  * hash catches every KDL policy edit even when the package version is unchanged;
- * it is computed once per process rather than once per provider or model.
+ * computed lazily on first cache access and memoized, so processes that never
+ * touch the model cache skip the stringify entirely.
  */
 const MODEL_MATERIALIZATION_VERSION = 1;
-const MATERIALIZATION_POLICY =
-	`app-${VERSION}:builder-${MODEL_MATERIALIZATION_VERSION}:rules-${RULES.version}-` +
-	Bun.hash(JSON.stringify(RULES)).toString(36);
+let cachedMaterializationPolicy: string | undefined;
+function materializationPolicy(): string {
+	if (cachedMaterializationPolicy === undefined) {
+		cachedMaterializationPolicy =
+			`app-${VERSION}:builder-${MODEL_MATERIALIZATION_VERSION}:rules-${RULES.version}-` +
+			Bun.hash(JSON.stringify(RULES)).toString(36);
+	}
+	return cachedMaterializationPolicy;
+}
 
 interface CacheRow {
 	provider_id: string;
@@ -88,14 +94,50 @@ export interface CacheEntry<TApi extends Api = Api> {
 let sharedDb: Database | null = null;
 let sharedDbPath: string | null = null;
 
-function openDb(resolvedPath: string): Database {
-	const db = new Database(resolvedPath, { create: true });
-	// Install the busy handler BEFORE any lock-taking statement. See
-	// https://github.com/can1357/oh-my-pi/issues/2421.
-	db.run("PRAGMA busy_timeout = 3000");
-	// Schema invalidation can delete rows containing credentials written by old
-	// versions. Overwrite deleted SQLite cells instead of leaving their bytes in
-	// free pages where a raw scan of models.db can still recover them (#5780).
+const readRowCache = new Map<string, { dataVersion: number; entry: CacheEntry<Api> | null }>();
+const READ_ROW_CACHE_MAX = 64;
+
+function readCacheKey(resolvedPath: string, providerId: string): string {
+	return `${resolvedPath} ${providerId}`;
+}
+
+function dbDataVersion(db: Database): number | null {
+	try {
+		const row = db.query<{ data_version: number }, []>("PRAGMA data_version").get();
+		return typeof row?.data_version === "number" ? row.data_version : null;
+	} catch {
+		return null;
+	}
+}
+
+function withFreshness<TApi extends Api>(
+	entry: CacheEntry<TApi> | null,
+	ttlMs: number,
+	now: () => number,
+): CacheEntry<TApi> | null {
+	if (entry === null) return null;
+	const ageMs = now() - entry.updatedAt;
+	const fresh = Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= ttlMs;
+	return fresh === entry.fresh ? entry : { ...entry, fresh };
+}
+function invalidateReadRow(providerId: string, dbPath?: string): void {
+	try {
+		readRowCache.delete(readCacheKey(dbPath ?? getModelDbPath(), providerId));
+	} catch {
+		// Best-effort only; a missed invalidation just costs one extra parse.
+	}
+}
+
+function invalidateReadPath(resolvedPath: string): void {
+	for (const key of readRowCache.keys()) {
+		if (key.startsWith(`${resolvedPath} `)) readRowCache.delete(key);
+	}
+}
+
+function initializeDb(db: Database): void {
+	// The shared opener installs the busy handler before any lock-taking
+	// statement. Schema invalidation can delete rows containing credentials
+	// written by old versions, so scrub deleted cells (#5780).
 	db.run("PRAGMA secure_delete = ON");
 	db.run("PRAGMA journal_mode = WAL");
 	db.run(`
@@ -113,91 +155,53 @@ function openDb(resolvedPath: string): Database {
 		)
 	`);
 	migrateCacheSchema(db);
-	return db;
 }
 
-function getSharedDb(resolvedPath: string): Database {
-	if (sharedDb && sharedDbPath === resolvedPath) {
-		return sharedDb;
-	}
-	if (sharedDb) {
-		sharedDb.close();
-		sharedDb = null;
-		sharedDbPath = null;
-	}
-	const db = openDb(resolvedPath);
-	sharedDb = db;
-	sharedDbPath = resolvedPath;
-	return db;
+function closeSharedDb(): void {
+	if (!sharedDb) return;
+	sharedDb.close();
+	sharedDb = null;
+	sharedDbPath = null;
 }
 
 function runModelCacheDb<T>(resolvedPath: string, shared: boolean, useDb: (db: Database) => T): T {
-	if (shared) return useDb(getSharedDb(resolvedPath));
-	const db = openDb(resolvedPath);
-	try {
-		return useDb(db);
-	} finally {
-		db.close();
-	}
-}
-
-// Paths already reported corrupt this process: the first unrecoverable failure
-// is logged at `error`, later heals at `debug`, so a dying disk cannot spam.
-const reportedCorruptPaths = new Set<string>();
-
-/**
- * Move a physically corrupt `models.db` (plus its `-wal`/`-shm` sidecars) aside
- * so {@link openDb} can recreate a fresh cache at the original path. Renames are
- * best-effort: a vanished sidecar (already healed by a peer process) is fine,
- * and any other rename failure is left for {@link openDb} to surface.
- */
-function quarantineCorruptModelCache(resolvedPath: string): void {
-	const stamp = Date.now();
-	for (const suffix of ["", "-wal", "-shm"]) {
+	if (shared && sharedDb && sharedDbPath !== resolvedPath) closeSharedDb();
+	if (shared && sharedDb) {
 		try {
-			renameSync(`${resolvedPath}${suffix}`, `${resolvedPath}.corrupt-${stamp}${suffix}`);
-		} catch (err) {
-			if (!isEnoent(err)) {
-				logger.debug("model cache: could not quarantine corrupt file", { path: `${resolvedPath}${suffix}` });
-			}
+			return useDb(sharedDb);
+		} catch (error) {
+			if (!isSqliteCorruptionError(error)) throw error;
+			// The opener owns recovery for new handles. Drop this stale handle
+			// first so its WAL cannot remain attached to the replacement.
+			closeSharedDb();
+			invalidateReadPath(resolvedPath);
+			return runModelCacheDb(resolvedPath, shared, useDb);
 		}
 	}
-}
 
-/**
- * Recover from unrecoverable `models.db` corruption: drop the cached handle,
- * quarantine the broken files, and let the next open recreate the cache. A
- * corrupt cache would otherwise be re-queried on every read/write forever,
- * permanently masking a successful live catalog (issue #8867). Only
- * {@link isSqliteCorruptionError} codes reach here; BUSY/permission errors keep
- * their existing best-effort paths.
- */
-function healCorruptModelCache(resolvedPath: string, shared: boolean, err: unknown): void {
-	if (shared && sharedDb) {
-		sharedDb.close();
-		sharedDb = null;
-		sharedDbPath = null;
-	}
-	quarantineCorruptModelCache(resolvedPath);
-	const code = err && typeof err === "object" && "code" in err ? err.code : undefined;
-	if (reportedCorruptPaths.has(resolvedPath)) {
-		logger.debug("model cache: re-healed corrupt database", { path: resolvedPath, code });
-	} else {
-		reportedCorruptPaths.add(resolvedPath);
-		logger.error("model cache corrupt; quarantined and recreated a fresh cache", { path: resolvedPath, code });
-	}
+	return openSqliteDatabaseSync(
+		resolvedPath,
+		db => {
+			initializeDb(db);
+			const result = useDb(db);
+			if (shared) {
+				sharedDb = db;
+				sharedDbPath = resolvedPath;
+			} else {
+				db.close();
+			}
+			return result;
+		},
+		{
+			recoverCorruption: true,
+			onCorruptionPreserved: () => invalidateReadPath(resolvedPath),
+		},
+	);
 }
 
 function withModelCacheDb<T>(dbPath: string | undefined, useDb: (db: Database) => T): T {
 	const resolvedPath = dbPath ?? getModelDbPath();
-	const shared = dbPath === undefined;
-	try {
-		return runModelCacheDb(resolvedPath, shared, useDb);
-	} catch (err) {
-		if (!isSqliteCorruptionError(err)) throw err;
-		healCorruptModelCache(resolvedPath, shared, err);
-		return runModelCacheDb(resolvedPath, shared, useDb);
-	}
+	return runModelCacheDb(resolvedPath, dbPath === undefined, useDb);
 }
 
 function migrateCacheSchema(db: Database): void {
@@ -232,7 +236,7 @@ function migrateCacheSchema(db: Database): void {
 	// compaction path even after CACHE_SCHEMA_VERSION was bumped).
 	db.run("DELETE FROM model_cache WHERE version <> ? OR materialization_policy <> ?", [
 		CACHE_SCHEMA_VERSION,
-		MATERIALIZATION_POLICY,
+		materializationPolicy(),
 	]);
 }
 
@@ -313,7 +317,6 @@ function parseModelIds(serialized: string): string[] | null {
 		return null;
 	}
 }
-
 export function readModelCache<TApi extends Api>(
 	providerId: string,
 	ttlMs: number,
@@ -321,44 +324,74 @@ export function readModelCache<TApi extends Api>(
 	dbPath?: string,
 ): CacheEntry<TApi> | null {
 	try {
-		return withModelCacheDb(dbPath, db => {
-			const stmt = db.query<CacheRow, [string]>("SELECT * FROM model_cache WHERE provider_id = ?");
-			try {
-				const row = stmt.get(providerId);
-				if (!row || row.version !== CACHE_SCHEMA_VERSION || row.materialization_policy !== MATERIALIZATION_POLICY) {
-					return null;
-				}
-				const models = parseMaterializedModels<TApi>(row.models);
-				const headerOmittedModelIds = parseModelIds(row.header_omitted_model_ids);
-				const unrestorableHeaderModelIds = parseModelIds(row.unrestorable_header_model_ids);
-				if (models === null || headerOmittedModelIds === null || unrestorableHeaderModelIds === null) {
-					// Fail closed on corrupt header provenance: treating malformed
-					// markers as empty could return a model with required credentials
-					// silently absent. secure_delete scrubs the rejected payload.
-					db.run("DELETE FROM model_cache WHERE provider_id = ?", [providerId]);
-					return null;
+		const resolvedPath = dbPath ?? getModelDbPath();
+		const key = readCacheKey(resolvedPath, providerId);
+		// Monotonic change signal: same-shaped WAL overwrites after checkpoint
+		// can leave every size:mtime pair identical, so file metadata alone
+		// cannot invalidate. PRAGMA data_version increments on each committed
+		// write transaction visible to a new reader.
+		const entry = withModelCacheDb(dbPath, db => {
+			const dataVersion = dbDataVersion(db);
+			if (dataVersion !== null) {
+				const cached = readRowCache.get(key);
+				if (cached !== undefined && cached.dataVersion === dataVersion) {
+					// Freshness is time-relative: recompute per call from the
+					// cached row's updatedAt so a long-lived process goes stale.
+					return { hit: true as const, entry: withFreshness(cached.entry as CacheEntry<TApi> | null, ttlMs, now) };
 				}
-				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,
-					headerOmittedModelIds,
-					unrestorableHeaderModelIds,
-					legacyHeaderRestoreMarkers: row.header_restore_version < HEADER_RESTORE_VERSION,
-					staticFingerprint: row.static_fingerprint ?? "",
-				};
-			} finally {
-				stmt.finalize();
 			}
+			const fresh = readRowUncached<TApi>(db, providerId, ttlMs, now);
+			if (dataVersion !== null) {
+				if (readRowCache.size >= READ_ROW_CACHE_MAX) readRowCache.clear();
+				readRowCache.set(key, { dataVersion, entry: fresh as CacheEntry<Api> | null });
+			}
+			return { hit: false as const, entry: fresh };
 		});
+		return entry.entry;
 	} catch {
 		return null;
 	}
 }
 
+function readRowUncached<TApi extends Api>(
+	db: Database,
+	providerId: string,
+	ttlMs: number,
+	now: () => number,
+): CacheEntry<TApi> | null {
+	const stmt = db.query<CacheRow, [string]>("SELECT * FROM model_cache WHERE provider_id = ?");
+	try {
+		const row = stmt.get(providerId);
+		if (!row || row.version !== CACHE_SCHEMA_VERSION || row.materialization_policy !== materializationPolicy()) {
+			return null;
+		}
+		const models = parseMaterializedModels<TApi>(row.models);
+		const headerOmittedModelIds = parseModelIds(row.header_omitted_model_ids);
+		const unrestorableHeaderModelIds = parseModelIds(row.unrestorable_header_model_ids);
+		if (models === null || headerOmittedModelIds === null || unrestorableHeaderModelIds === null) {
+			// Fail closed on corrupt header provenance: treating malformed
+			// markers as empty could return a model with required credentials
+			// silently absent. secure_delete scrubs the rejected payload.
+			db.run("DELETE FROM model_cache WHERE provider_id = ?", [providerId]);
+			return null;
+		}
+		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,
+			headerOmittedModelIds,
+			unrestorableHeaderModelIds,
+			legacyHeaderRestoreMarkers: row.header_restore_version < HEADER_RESTORE_VERSION,
+			staticFingerprint: row.static_fingerprint ?? "",
+		};
+	} finally {
+		stmt.finalize();
+	}
+}
+
 /** Whether a live model carries at least one request header. */
 function hasModelHeaders(model: Model<Api>): boolean {
 	const headers = model.headers;
@@ -406,6 +439,7 @@ export function writeModelCache<TApi extends Api>(
 	restorableHeaderFallback?: Record<string, string>,
 ): void {
 	try {
+		invalidateReadRow(providerId, dbPath);
 		withModelCacheDb(dbPath, db => {
 			const headerOmittedModelIds: string[] = [];
 			const unrestorableHeaderModelIds: string[] = [];
@@ -442,7 +476,7 @@ export function writeModelCache<TApi extends Api>(
 				[
 					providerId,
 					CACHE_SCHEMA_VERSION,
-					MATERIALIZATION_POLICY,
+					materializationPolicy(),
 					updatedAt,
 					authoritative ? 1 : 0,
 					staticFingerprint,