@linxiraos/pi-catalog 1.1.27 → 1.2.1

package/src/compat/taxonomy.d.ts

@@ -1,13 +1,3 @@
-/**
- * Runtime model-identity taxonomy: classifies wire model ids into
- * `(class, family, revision)` ranks, applies reviewed identity overrides, and
- * exposes the collapse/discovery vocabularies.
- *
- * Faithful port of the o2 reference (`taxonomy.rs` / `classify.rs`):
- * matchers rank `exact(4) > bounded(3) > namespace(2) > prefix(1) > glob(0)`
- * with token byte length as tiebreak; equal cross-class or cross-family ranks
- * throw unless classification is `lenient` (discovery normalization).
- */
 import type { Effort } from "../effort";
 import type { ModelIdentity } from "./types";
 /** Two classes, families, or reviewed override patterns tie for one model id. */

package/src/compat/taxonomy.ts

@@ -8,6 +8,7 @@
  * with token byte length as tiebreak; equal cross-class or cross-family ranks
  * throw unless classification is `lenient` (discovery normalization).
  */
+import { LRUCache } from "@linxiraos/pi-utils/lru";
 import type { Effort } from "../effort";
 import { globMatch } from "./cascade";
 import { formatRevision, parseRevisionPrefix } from "./revision";
@@ -433,8 +434,8 @@ export function stripThinkingVariantSuffix(model: string): string | undefined {
  * @throws AmbiguousIdentityError on equal-rank cross-class, cross-family, or
  * reviewed-pattern matches unless `opts.lenient`.
  */
-const classifyMemo = new Map<string, ModelIdentity>();
-const CLASSIFY_MEMO_MAX = 4096;
+// LRU sized above the bundled catalog so catalog-wide passes stay hot (a full `clear()` thrashed them).
+const classifyMemo = new LRUCache<string, ModelIdentity>({ max: 16384 });
 
 function classifyMemoKey(provider: string, modelId: string, lenient: boolean): string {
 	return `${provider.length}:${provider}${modelId.length}:${modelId}${lenient ? 1 : 0}`;
@@ -446,7 +447,6 @@ export function classifyModel(provider: string, modelId: string, opts?: Classify
 		const cached = classifyMemo.get(key);
 		if (cached !== undefined) return { ...cached };
 		const identity = classifyModelUncached(provider, modelId, opts);
-		if (classifyMemo.size >= CLASSIFY_MEMO_MAX) classifyMemo.clear();
 		classifyMemo.set(key, Object.freeze(identity));
 		return { ...identity };
 	}

package/src/compat/types.d.ts

@@ -593,6 +593,8 @@ export interface CompiledSeedModel {
     baseUrl: string;
     reasoning: boolean;
     input: ("text" | "image")[];
+    /** Wire model id sent upstream when it differs from the row id (`request-model-id`). */
+    requestModelId?: string;
     supportsTools?: boolean;
     cost: TokenCost;
     contextWindow: number | null;
@@ -622,6 +624,8 @@ export interface CompiledProvider {
     id: string;
     /** Preferred model id when no explicit selection is made. */
     defaultModel: string;
+    /** Whether the provider participates in automatic default selection (defaults to true). */
+    automaticDefault?: boolean;
     /** Env vars consulted, in order, for the runtime API-key fallback. */
     envVars?: string[];
     /** The runtime creates a model manager even without a valid API key. */

package/src/compat/types.ts

@@ -625,6 +625,8 @@ export interface CompiledSeedModel {
 	baseUrl: string;
 	reasoning: boolean;
 	input: ("text" | "image")[];
+	/** Wire model id sent upstream when it differs from the row id (`request-model-id`). */
+	requestModelId?: string;
 	supportsTools?: boolean;
 	cost: TokenCost;
 	contextWindow: number | null;
@@ -656,6 +658,8 @@ export interface CompiledProvider {
 	id: string;
 	/** Preferred model id when no explicit selection is made. */
 	defaultModel: string;
+	/** Whether the provider participates in automatic default selection (defaults to true). */
+	automaticDefault?: boolean;
 	/** Env vars consulted, in order, for the runtime API-key fallback. */
 	envVars?: string[];
 	/** The runtime creates a model manager even without a valid API key. */

package/src/discovery/antigravity.d.ts

@@ -63,13 +63,23 @@ export interface FetchAntigravityDiscoveryModelsOptions {
      */
     collapseTable?: VariantCollapseTable;
 }
+/**
+ * A complete account roster, or a definitive 401/403 credential rejection.
+ * `null` from {@link fetchAntigravityDiscoveryModels} instead means a transient
+ * failure or invalid response, which must not replace an authoritative catalog.
+ */
+export interface AntigravityModelDiscoveryResult {
+    models: ModelSpec<"google-gemini-cli">[];
+    rejectedStatus?: 401 | 403;
+}
 /**
  * Fetches discoverable Antigravity models and normalizes them into canonical model entries.
  *
- * Returns `null` on network/payload/auth failures.
- * Returns `[]` only when the endpoint responds successfully with no usable models.
+ * Returns `null` on network, server, or payload failures; a 401/403 is reported
+ * separately so multi-account discovery can skip a rejected credential.
+ * A successful empty roster has `models: []` without `rejectedStatus`.
  */
-export declare function fetchAntigravityDiscoveryModels(options: FetchAntigravityDiscoveryModelsOptions): Promise<ModelSpec<"google-gemini-cli">[] | null>;
+export declare function fetchAntigravityDiscoveryModels(options: FetchAntigravityDiscoveryModelsOptions): Promise<AntigravityModelDiscoveryResult | null>;
 /** Advertised image model and serving endpoint for one Antigravity account. */
 export interface AntigravityImageModel {
     id: string;

package/src/discovery/antigravity.ts

@@ -153,19 +153,29 @@ export interface FetchAntigravityDiscoveryModelsOptions {
 	collapseTable?: VariantCollapseTable;
 }
 
+/**
+ * A complete account roster, or a definitive 401/403 credential rejection.
+ * `null` from {@link fetchAntigravityDiscoveryModels} instead means a transient
+ * failure or invalid response, which must not replace an authoritative catalog.
+ */
+export interface AntigravityModelDiscoveryResult {
+	models: ModelSpec<"google-gemini-cli">[];
+	rejectedStatus?: 401 | 403;
+}
+
 /**
  * Fetches discoverable Antigravity models and normalizes them into canonical model entries.
  *
- * Returns `null` on network/payload/auth failures.
- * Returns `[]` only when the endpoint responds successfully with no usable models.
+ * Returns `null` on network, server, or payload failures; a 401/403 is reported
+ * separately so multi-account discovery can skip a rejected credential.
+ * A successful empty roster has `models: []` without `rejectedStatus`.
  */
 export async function fetchAntigravityDiscoveryModels(
 	options: FetchAntigravityDiscoveryModelsOptions,
-): Promise<ModelSpec<"google-gemini-cli">[] | null> {
+): Promise<AntigravityModelDiscoveryResult | null> {
 	const discovered = await fetchAntigravityDiscoveryResponse(options);
-	if (!discovered) {
-		return null;
-	}
+	if (!discovered) return null;
+	if ("rejectedStatus" in discovered) return { models: [], rejectedStatus: discovered.rejectedStatus };
 
 	const models: ModelSpec<"google-gemini-cli">[] = [];
 	const apiModels = discovered.payload.models;
@@ -208,7 +218,7 @@ export async function fetchAntigravityDiscoveryModels(
 		options.collapseTable === undefined ? undefined : { table: options.collapseTable },
 	);
 	collapsed.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
-	return collapsed;
+	return { models: collapsed };
 }
 
 /** Advertised image model and serving endpoint for one Antigravity account. */
@@ -222,14 +232,14 @@ 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;
+	if (!discovered || "rejectedStatus" in discovered) return null;
+	const id = discovered.payload.imageGenerationModelIds?.find(modelId => modelId.length > 0);
+	return id ? { id, endpoint: discovered.endpoint } : null;
 }
 
-interface AntigravityDiscoveryResponse {
-	payload: AntigravityDiscoveryApiResponse;
-	endpoint: string;
-}
+type AntigravityDiscoveryResponse =
+	| { payload: AntigravityDiscoveryApiResponse; endpoint: string }
+	| { rejectedStatus: 401 | 403 };
 
 async function fetchAntigravityDiscoveryResponse(
 	options: FetchAntigravityDiscoveryModelsOptions,
@@ -243,6 +253,8 @@ async function fetchAntigravityDiscoveryResponse(
 		? [trimTrailingSlashes(options.endpoint)]
 		: DEFAULT_ANTIGRAVITY_DISCOVERY_ENDPOINTS.map(trimTrailingSlashes);
 
+	let rejectedStatus: 401 | 403 | undefined;
+	let transientFailure = false;
 	for (const endpoint of endpoints) {
 		let response: Response;
 		try {
@@ -257,10 +269,14 @@ async function fetchAntigravityDiscoveryResponse(
 				signal: options.signal,
 			});
 		} catch {
+			transientFailure = true;
 			continue;
 		}
 
 		if (!response.ok) {
+			if (response.status === 401) rejectedStatus = 401;
+			else if (response.status === 403) rejectedStatus = 403;
+			else transientFailure = true;
 			continue;
 		}
 
@@ -268,16 +284,16 @@ async function fetchAntigravityDiscoveryResponse(
 		try {
 			payload = await response.json();
 		} catch {
+			transientFailure = true;
 			continue;
 		}
 
 		const parsed = parseAntigravityDiscoveryResponse(payload);
-		if (parsed) {
-			return { payload: parsed, endpoint };
-		}
+		if (parsed) return { payload: parsed, endpoint };
+		transientFailure = true;
 	}
 
-	return null;
+	return rejectedStatus !== undefined && !transientFailure ? { rejectedStatus } : null;
 }
 
 function parseAntigravityDiscoveryResponse(value: unknown): AntigravityDiscoveryApiResponse | null {

package/src/discovery/cursor.ts

@@ -882,7 +882,8 @@ function buildRichCursorLane(
 			cursorRequiresDataRetention: details.requiresDataRetention,
 			cursorSupportsAgent: details.supportsAgent,
 			cursorSupportsSandboxing: details.supportsSandboxing,
-			isProviderDefault,
+			// Not marked `isProviderDefault`: Cursor keeps its bundled startup default, so
+			// the account default only picks the lane's default wire id and the badge.
 			isRecommended: isProviderDefault || details.defaultOn,
 			description:
 				variant?.tagline ??

package/src/discovery/devin.ts

@@ -9,6 +9,7 @@ import {
 	type ClientModelConfig,
 	DisplayOption,
 	GetCliModelConfigsRequestSchema,
+	type GetCliModelConfigsResponse,
 	GetCliModelConfigsResponseSchema,
 	type Metadata,
 	MetadataSchema,
@@ -346,7 +347,7 @@ export async function fetchDevinModels(
 				GetCliModelConfigsResponseSchema,
 				new Uint8Array(await response.arrayBuffer()),
 			);
-			return decoded ? normalizeDevinModels(decoded.clientModelConfigs, options.baseUrl) : null;
+			return decoded ? normalizeDevinModels(decoded, options.baseUrl) : null;
 		} catch {
 			return null;
 		}
@@ -497,9 +498,12 @@ function routeDevinFusionLead(spec: ModelSpec<"devin-agent">, lead: ModelSpec<"d
 }
 
 function normalizeDevinModels(
-	configs: readonly ClientModelConfig[],
+	response: GetCliModelConfigsResponse,
 	baseUrlOverride: string | undefined,
 ): ModelSpec<"devin-agent">[] {
+	const configs = response.clientModelConfigs;
+	// The model the native client starts this account on (plan-dependent).
+	const accountDefaultUid = response.defaultOverrideModelConfig?.modelUid.trim();
 	const baseUrl = baseUrlOverride ?? DEVIN_DEFAULT_BASE_URL;
 	const specs: ModelSpec<"devin-agent">[] = [];
 	const seen = new Set<string>();
@@ -539,6 +543,7 @@ function normalizeDevinModels(
 		if (lead === null) continue;
 		const spec = devinModelSpec(config, uid, baseUrl, isAssignModelRouter);
 		if (lead !== undefined) routeDevinFusionLead(spec, devinModelSpec(liveConfigs.get(lead)!, lead, baseUrl, false));
+		if (uid === accountDefaultUid) spec.isProviderDefault = true;
 		specs.push(spec);
 		// A router is a server-side dispatcher, not an effort tier: it stays a
 		// standalone model even when upstream files it under a family.
@@ -554,5 +559,18 @@ function normalizeDevinModels(
 	const families = devinDynamicFamilies(lanes.values());
 	const dynamic = families.length > 0 ? collapseVariants(specs, { table: { families } }) : specs;
 	const collapsed = collapseVariants(dynamic);
+	// The account default outranks its family's own default lane when an effort
+	// routes to it, from server metadata or the static table: the family starts
+	// on that wire uid and effort. Other lanes (a no-thinking `off` default) keep
+	// the family's own default.
+	const accountFamily = collapsed.find(spec => spec.isProviderDefault && spec.thinking?.effortRouting);
+	const accountEffort = THINKING_EFFORTS.find(
+		effort => accountFamily?.thinking?.effortRouting?.[effort] === accountDefaultUid,
+	);
+	if (accountFamily?.thinking && accountEffort !== undefined) {
+		accountFamily.thinking = { ...accountFamily.thinking, defaultLevel: accountEffort };
+		if (accountFamily.id === accountDefaultUid) delete accountFamily.requestModelId;
+		else accountFamily.requestModelId = accountDefaultUid;
+	}
 	return collapsed.sort((a, b) => a.id.localeCompare(b.id));
 }

package/src/model-cache.ts

@@ -3,6 +3,7 @@
  * Replaces per-provider JSON files with a single cache.db.
  */
 import type { Database } from "bun:sqlite";
+import * as path from "node:path";
 import { getModelDbPath, isSqliteCorruptionError, logger, openSqliteDatabaseSync, VERSION } from "@linxiraos/pi-utils";
 import RULES from "./compat/rules.json" with { type: "json" };
 import type { Api, Model } from "./types";
@@ -46,14 +47,19 @@ function materializationPolicy(): string {
 	return cachedMaterializationPolicy;
 }
 
-interface CacheRow {
+interface CacheRowMeta {
 	provider_id: string;
 	version: number;
 	materialization_policy: string;
 	updated_at: number;
 	authoritative: number;
 	static_fingerprint: string;
-	models: string;
+	/**
+	 * `Bun.hash` of `models`; empty for rows written before the column existed
+	 * (never equal). An in-place `UPDATE` of `models` that leaves the hash
+	 * untouched resets it to empty (`model_cache_models_hash_reset` trigger).
+	 */
+	models_hash: string;
 	header_omitted_model_ids: string;
 	unrestorable_header_model_ids: string;
 	header_restore_version: number;
@@ -63,6 +69,10 @@ interface CacheRow {
 	refresh_authoritative: number | null;
 }
 
+interface CacheRow extends CacheRowMeta {
+	models: string;
+}
+
 /**
  * Payload rows are multi-MB and SQLite rewrites a whole record (including its
  * overflow pages) on any column update. Freshness that advances without a
@@ -71,15 +81,23 @@ interface CacheRow {
  * the payload row's `updated_at`, so a payload rewritten by another binary
  * silently invalidates it.
  */
-const SELECT_CACHE_ROW = `
-	SELECT m.*,
-		r.payload_updated_at AS refresh_payload_updated_at,
-		r.updated_at AS refresh_updated_at,
-		r.authoritative AS refresh_authoritative
+const CACHE_ROW_FROM = `
 	FROM model_cache m
 	LEFT JOIN model_cache_refresh r ON r.provider_id = m.provider_id
 	WHERE m.provider_id = ?
 `;
+const CACHE_ROW_REFRESH_COLUMNS = `
+		r.payload_updated_at AS refresh_payload_updated_at,
+		r.updated_at AS refresh_updated_at,
+		r.authoritative AS refresh_authoritative`;
+const SELECT_CACHE_ROW = `SELECT m.*, ${CACHE_ROW_REFRESH_COLUMNS} ${CACHE_ROW_FROM}`;
+/** Scalar columns plus `models_hash`: validates a memoized parse without reading the multi-MB payload. */
+const SELECT_CACHE_ROW_META = `
+	SELECT m.provider_id, m.version, m.materialization_policy, m.updated_at, m.authoritative,
+		m.static_fingerprint, m.models_hash, m.header_omitted_model_ids,
+		m.unrestorable_header_model_ids, m.header_restore_version, ${CACHE_ROW_REFRESH_COLUMNS}
+	${CACHE_ROW_FROM}
+`;
 
 /** Cumulative model-cache write counters for this process. */
 export interface ModelCacheWriteStats {
@@ -149,8 +167,11 @@ let sharedDbPath: string | null = null;
 interface ReadRowCacheEntry {
 	/** `PRAGMA data_version` of the shared connection when validated; null for per-call connections. */
 	dataVersion: number | null;
-	/** Raw row the entry was parsed from; null when the row was absent or rejected. */
-	row: CacheRow | null;
+	/**
+	 * Scalar columns (plus `models_hash`) of the row the entry was parsed from;
+	 * null when the row was absent or rejected. Never the multi-MB payload itself.
+	 */
+	meta: CacheRowMeta | null;
 	entry: CacheEntry<Api> | null;
 }
 
@@ -182,7 +203,7 @@ function withFreshness<TApi extends Api>(
 }
 function invalidateReadRow(providerId: string, dbPath?: string): void {
 	try {
-		readRowCache.delete(readCacheKey(dbPath ?? getModelDbPath(), providerId));
+		readRowCache.delete(readCacheKey(resolveCacheDb(dbPath).resolvedPath, providerId));
 	} catch {
 		// Best-effort only; a missed invalidation just costs one extra parse.
 	}
@@ -213,6 +234,7 @@ function initializeDb(db: Database): void {
 			header_omitted_model_ids TEXT NOT NULL DEFAULT '[]',
 			unrestorable_header_model_ids TEXT NOT NULL DEFAULT '[]',
 			header_restore_version INTEGER NOT NULL DEFAULT 0,
+			models_hash TEXT NOT NULL DEFAULT '',
 			models TEXT NOT NULL
 		)
 	`);
@@ -225,6 +247,17 @@ function initializeDb(db: Database): void {
 		)
 	`);
 	migrateCacheSchema(db);
+	// `models_hash` is the only payload-change detector for the read memo and the
+	// unchanged-write skip. Writers here replace whole rows; this keeps an
+	// in-place edit of `models` by any other tool or binary from reusing a stale hash.
+	db.run(`
+		CREATE TRIGGER IF NOT EXISTS model_cache_models_hash_reset
+		AFTER UPDATE OF models ON model_cache
+		WHEN NEW.models_hash = OLD.models_hash
+		BEGIN
+			UPDATE model_cache SET models_hash = '' WHERE provider_id = NEW.provider_id;
+		END
+	`);
 }
 
 function closeSharedDb(): void {
@@ -280,8 +313,22 @@ function runModelCacheDb<T>(resolvedPath: string, shared: boolean, useDb: (db: D
 }
 
 function withModelCacheDb<T>(dbPath: string | undefined, useDb: (db: Database) => T): T {
-	const resolvedPath = dbPath ?? getModelDbPath();
-	return runModelCacheDb(resolvedPath, dbPath === undefined, useDb);
+	const { resolvedPath, shared } = resolveCacheDb(dbPath);
+	return runModelCacheDb(resolvedPath, shared, useDb);
+}
+
+/**
+ * An explicit path naming the default `models.db` (e.g. the SDK passing
+ * `getModelDbPath(agentDir)` for the default agent dir) shares the long-lived
+ * handle, so it gets the `data_version` fast path instead of opening,
+ * initializing and re-reading the row on every call.
+ */
+function resolveCacheDb(dbPath: string | undefined): { resolvedPath: string; shared: boolean } {
+	const defaultPath = getModelDbPath();
+	if (dbPath === undefined || dbPath === defaultPath || path.resolve(dbPath) === path.resolve(defaultPath)) {
+		return { resolvedPath: defaultPath, shared: true };
+	}
+	return { resolvedPath: dbPath, shared: false };
 }
 
 function migrateCacheSchema(db: Database): void {
@@ -306,6 +353,12 @@ function migrateCacheSchema(db: Database): void {
 			// header matching was introduced.
 			db.run("ALTER TABLE model_cache ADD COLUMN header_restore_version INTEGER NOT NULL DEFAULT 0");
 		}
+		if (!columns.some(column => column.name === "models_hash")) {
+			// Rows from older binaries keep '' (never equal), so they are re-read in
+			// full until the next write records their hash; no version bump needed.
+			// Older binaries rewriting a row via INSERT OR REPLACE reset it to ''.
+			db.run("ALTER TABLE model_cache ADD COLUMN models_hash TEXT NOT NULL DEFAULT ''");
+		}
 	} finally {
 		stmt.finalize();
 	}
@@ -419,15 +472,14 @@ export function readModelCache<TApi extends Api>(
 	dbPath?: string,
 ): CacheEntry<TApi> | null {
 	try {
-		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. It is only comparable
 		// across calls on the same connection, so it gates the no-query fast
 		// path for the shared handle only.
-		const shared = dbPath === undefined;
+		const { resolvedPath, shared } = resolveCacheDb(dbPath);
+		const key = readCacheKey(resolvedPath, providerId);
 		return runModelCacheDb(resolvedPath, shared, db => {
 			const dataVersion = shared ? dbDataVersion(db) : null;
 			const cached = readRowCache.get(key);
@@ -436,34 +488,32 @@ export function readModelCache<TApi extends Api>(
 				// cached row's updatedAt so a long-lived process goes stale.
 				return withFreshness(cached.entry as CacheEntry<TApi> | null, ttlMs, now);
 			}
-			// Any commit (to any provider's row) bumps data_version. Re-read this
-			// row, but reuse the parsed entry when its bytes are unchanged.
-			const stmt = db.query<CacheRow, [string]>(SELECT_CACHE_ROW);
-			let row: CacheRow | null;
-			try {
-				row = stmt.get(providerId);
-			} finally {
-				stmt.finalize();
+			// Any commit (to any provider's row) bumps data_version. Validate the
+			// memoized parse against the row's scalar columns and payload hash
+			// first; only a changed payload pays for the multi-MB `models` read.
+			let entry: CacheEntry<TApi> | null = null;
+			let meta: CacheRowMeta | null = null;
+			if (cached?.entry && cached.meta) {
+				meta = queryRow<CacheRowMeta>(db, SELECT_CACHE_ROW_META, providerId);
+				if (meta && meta.materialization_policy === materializationPolicy() && cacheRowsEqual(cached.meta, meta)) {
+					// Payload unchanged; only side-table freshness may have moved.
+					entry = withFreshness(withRowState(cached.entry as CacheEntry<TApi>, meta), ttlMs, now);
+				} else {
+					meta = null;
+				}
 			}
-			let entry: CacheEntry<TApi> | null;
-			if (
-				cached?.entry &&
-				cached.row &&
-				row &&
-				row.materialization_policy === materializationPolicy() &&
-				cacheRowsEqual(cached.row, row)
-			) {
-				// Payload bytes unchanged; only side-table freshness may have moved.
-				entry = withFreshness(withRowState(cached.entry as CacheEntry<TApi>, row), ttlMs, now);
-			} else {
+			if (entry === null) {
+				// One statement reads payload and scalars from the same snapshot.
+				const row = queryRow<CacheRow>(db, SELECT_CACHE_ROW, providerId);
 				entry = parseCacheRow<TApi>(db, providerId, row, ttlMs, now);
+				if (entry !== null && row !== null) {
+					// Drop the payload so the memo never pins the multi-MB `models` string.
+					const { models: _models, ...rowScalars } = row;
+					meta = rowScalars;
+				}
 			}
 			if (readRowCache.size >= READ_ROW_CACHE_MAX) readRowCache.clear();
-			readRowCache.set(key, {
-				dataVersion,
-				row: entry === null ? null : row,
-				entry: entry as CacheEntry<Api> | null,
-			});
+			readRowCache.set(key, { dataVersion, meta, entry: entry as CacheEntry<Api> | null });
 			return entry;
 		});
 	} catch {
@@ -471,8 +521,20 @@ export function readModelCache<TApi extends Api>(
 	}
 }
 
-/** Whether two rows carry the same payload record (refresh side-row columns excluded). */
-function cacheRowsEqual(left: CacheRow, right: CacheRow): boolean {
+function queryRow<T>(db: Database, sql: string, providerId: string): T | null {
+	const stmt = db.query<T, [string]>(sql);
+	try {
+		return stmt.get(providerId);
+	} finally {
+		stmt.finalize();
+	}
+}
+
+/**
+ * Whether two rows carry the same payload record (refresh side-row columns
+ * excluded). Payloads compare by `models_hash`; rows without one never match.
+ */
+function cacheRowsEqual(left: CacheRowMeta, right: CacheRowMeta): boolean {
 	return (
 		left.version === right.version &&
 		left.materialization_policy === right.materialization_policy &&
@@ -482,7 +544,8 @@ function cacheRowsEqual(left: CacheRow, right: CacheRow): boolean {
 		left.header_omitted_model_ids === right.header_omitted_model_ids &&
 		left.unrestorable_header_model_ids === right.unrestorable_header_model_ids &&
 		left.header_restore_version === right.header_restore_version &&
-		left.models === right.models
+		left.models_hash !== "" &&
+		left.models_hash === right.models_hash
 	);
 }
 
@@ -498,7 +561,7 @@ function rowState(row: StoredRowState): { updatedAt: number; authoritative: bool
 	return { updatedAt: row.updated_at, authoritative: row.authoritative === 1 };
 }
 
-function withRowState<TApi extends Api>(entry: CacheEntry<TApi>, row: CacheRow): CacheEntry<TApi> {
+function withRowState<TApi extends Api>(entry: CacheEntry<TApi>, row: StoredRowState): CacheEntry<TApi> {
 	const { updatedAt, authoritative } = rowState(row);
 	return entry.updatedAt === updatedAt && entry.authoritative === authoritative
 		? entry
@@ -648,6 +711,8 @@ export function writeModelCache<TApi extends Api>(
 			const serializedHeaderOmitted = JSON.stringify(headerOmittedModelIds);
 			const serializedUnrestorable = JSON.stringify(unrestorableHeaderModelIds);
 			const serializedModels = JSON.stringify(cachedModels);
+			// Length prefix: a collision would also need an equal payload size.
+			const modelsHash = `${serializedModels.length.toString(36)}:${Bun.hash(serializedModels).toString(36)}`;
 			const outcome = db
 				.transaction((): "skipped" | "refreshed" | "written" => {
 					const matchStmt = db.prepare<
@@ -662,7 +727,7 @@ export function writeModelCache<TApi extends Api>(
 						LEFT JOIN model_cache_refresh r ON r.provider_id = m.provider_id
 						WHERE m.provider_id = ? AND m.version = ? AND m.materialization_policy = ?
 							AND m.static_fingerprint = ? AND m.header_omitted_model_ids = ?
-							AND m.unrestorable_header_model_ids = ? AND m.header_restore_version = ? AND m.models = ?`,
+							AND m.unrestorable_header_model_ids = ? AND m.header_restore_version = ? AND m.models_hash = ?`,
 					);
 					let stored: StoredRowState | null;
 					try {
@@ -674,7 +739,7 @@ export function writeModelCache<TApi extends Api>(
 							serializedHeaderOmitted,
 							serializedUnrestorable,
 							HEADER_RESTORE_VERSION,
-							serializedModels,
+							modelsHash,
 						);
 					} finally {
 						matchStmt.finalize();
@@ -697,8 +762,8 @@ export function writeModelCache<TApi extends Api>(
 						`INSERT OR REPLACE INTO model_cache (
 							provider_id, version, materialization_policy, updated_at, authoritative, static_fingerprint,
 							header_omitted_model_ids, unrestorable_header_model_ids,
-							header_restore_version, models
-						) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+							header_restore_version, models_hash, models
+						) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 						[
 							providerId,
 							CACHE_SCHEMA_VERSION,
@@ -709,6 +774,7 @@ export function writeModelCache<TApi extends Api>(
 							serializedHeaderOmitted,
 							serializedUnrestorable,
 							HEADER_RESTORE_VERSION,
+							modelsHash,
 							serializedModels,
 						],
 					);

package/src/model-manager.d.ts

@@ -35,6 +35,22 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
     cacheTtlMs?: number;
     /** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
     dynamicModelsAuthoritative?: boolean;
+    /**
+     * When true, a provider's dynamic rows are the deployment's whole truth
+     * for input modality: a live text-only row strips the bundled reference's
+     * image support instead of OR-merging it back. Declared by providers whose
+     * capability flags are authoritative and whose endpoints reject
+     * unsupported content (`github-copilot`, `deepinfra`, `coralbricks`).
+     */
+    dynamicInputAuthoritative?: boolean;
+    /** When true, live reasoning capability replaces the fallback, including an explicit false. */
+    dynamicReasoningAuthoritative?: boolean;
+    /**
+     * When true, a live per-million price replaces the fallback even when it is
+     * an explicit `0` (a free model or a dropped cache-write charge). Without it,
+     * a zero discovery price is treated as unknown and the bundled rate is kept.
+     */
+    dynamicCostAuthoritative?: boolean;
     /**
      * When true, a fresh cache never satisfies an online-eligible refresh: the
      * dynamic fetch always runs (an explicit `"offline"` strategy is still