@oh-my-pi/pi-catalog 18.4.6 → 18.4.9

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.4.9] - 2026-10-01
+
+### Fixed
+
+- Fixed model catalog caching so unchanged catalogs refresh without unnecessary rewrites, and offline snapshots for endpoint-less models (such as Azure models) are now handled correctly across startups.
+
 ## [18.4.6] - 2026-10-01
 
 ### Added

package/dist/types/model-cache.d.ts

@@ -1,4 +1,19 @@
 import type { Api, Model } from "./types.js";
+/** Cumulative model-cache write counters for this process. */
+export interface ModelCacheWriteStats {
+    /** Payload rows (re)written because their stored content changed. */
+    payloadWrites: number;
+    /** Serialized model bytes written by `payloadWrites`. */
+    payloadBytes: number;
+    /** Unchanged payloads whose freshness/authority advanced via the side table. */
+    refreshWrites: number;
+    /** Writes that matched the stored row exactly and touched nothing. */
+    skippedWrites: number;
+    /** Provider ids of the most recent payload writes (bounded). */
+    recentPayloadProviders: readonly string[];
+}
+/** Snapshot of this process's model-cache write counters. */
+export declare function getModelCacheWriteStats(): ModelCacheWriteStats;
 /** Materialized provider snapshot with freshness and header-restoration provenance. */
 export interface CacheEntry<TApi extends Api = Api> {
     /** Trusted, fully materialized rows; request headers remain omitted. */
@@ -21,4 +36,14 @@ export interface CacheEntry<TApi extends Api = Api> {
     staticFingerprint: string;
 }
 export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
+/**
+ * Persist a provider snapshot.
+ *
+ * When the stored payload (models, header provenance, fingerprint, schema and
+ * materialization policy) is byte-identical, the multi-MB row is left alone and
+ * only `model_cache_refresh` records the new freshness and authority; a write
+ * that changes nothing at all is skipped. Every model persisted here is
+ * validated with the reader's own predicate, so a row this writes is never
+ * rejected (and deleted) by `readModelCache`.
+ */
 export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string, staticHeaderSources?: readonly Model<TApi>[], restorableHeaderFallback?: Record<string, string>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "18.4.6",
+	"version": "18.4.9",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"keywords": [
 		"ai",
@@ -93,12 +93,12 @@
 		"gen:proto": "bun scripts/generate-protocols.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.4.6",
-		"@oh-my-pi/pi-utils": "18.4.6"
+		"@oh-my-pi/omptype": "18.4.9",
+		"@oh-my-pi/pi-utils": "18.4.9"
 	},
 	"devDependencies": {
 		"@bgotink/kdl": "0.4.0",
-		"@oh-my-pi/pi-ai": "18.4.6",
+		"@oh-my-pi/pi-ai": "18.4.9",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/model-cache.ts

@@ -3,7 +3,7 @@
  * Replaces per-provider JSON files with a single cache.db.
  */
 import type { Database } from "bun:sqlite";
-import { getModelDbPath, isSqliteCorruptionError, openSqliteDatabaseSync, VERSION } from "@oh-my-pi/pi-utils";
+import { getModelDbPath, isSqliteCorruptionError, logger, openSqliteDatabaseSync, VERSION } from "@oh-my-pi/pi-utils";
 import RULES from "./compat/rules.json" with { type: "json" };
 import type { Api, Model } from "./types";
 
@@ -25,6 +25,8 @@ import type { Api, Model } from "./types";
 // effort-tier variant collapsing (raw `-low`/`-high`/`-thinking` member ids);
 // v4 dropped the pre-efforts ThinkingConfig shape.
 const CACHE_SCHEMA_VERSION = 13;
+/** Oldest schema whose rows are guaranteed never to carry request headers. */
+const FIRST_HEADERLESS_SCHEMA_VERSION = 11;
 const HEADER_RESTORE_VERSION = 1;
 /**
  * Explicit compatibility gate for materialized rows. Bump whenever buildModel
@@ -55,8 +57,58 @@ interface CacheRow {
 	header_omitted_model_ids: string;
 	unrestorable_header_model_ids: string;
 	header_restore_version: number;
+	/** `model_cache_refresh` columns joined onto the payload row; null when absent. */
+	refresh_payload_updated_at: number | null;
+	refresh_updated_at: number | null;
+	refresh_authoritative: number | null;
 }
 
+/**
+ * Payload rows are multi-MB and SQLite rewrites a whole record (including its
+ * overflow pages) on any column update. Freshness that advances without a
+ * payload change therefore lives in `model_cache_refresh`, a small side row
+ * keyed by provider. It applies only while `payload_updated_at` still matches
+ * 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
+	FROM model_cache m
+	LEFT JOIN model_cache_refresh r ON r.provider_id = m.provider_id
+	WHERE m.provider_id = ?
+`;
+
+/** Cumulative model-cache write counters for this process. */
+export interface ModelCacheWriteStats {
+	/** Payload rows (re)written because their stored content changed. */
+	payloadWrites: number;
+	/** Serialized model bytes written by `payloadWrites`. */
+	payloadBytes: number;
+	/** Unchanged payloads whose freshness/authority advanced via the side table. */
+	refreshWrites: number;
+	/** Writes that matched the stored row exactly and touched nothing. */
+	skippedWrites: number;
+	/** Provider ids of the most recent payload writes (bounded). */
+	recentPayloadProviders: readonly string[];
+}
+
+const writeStats = { payloadWrites: 0, payloadBytes: 0, refreshWrites: 0, skippedWrites: 0 };
+const recentPayloadProviders: string[] = [];
+const RECENT_PAYLOAD_PROVIDERS_MAX = 64;
+
+/** Snapshot of this process's model-cache write counters. */
+export function getModelCacheWriteStats(): ModelCacheWriteStats {
+	return { ...writeStats, recentPayloadProviders: [...recentPayloadProviders] };
+}
+
+type StoredRowState = Pick<
+	CacheRow,
+	"updated_at" | "authoritative" | "refresh_payload_updated_at" | "refresh_updated_at" | "refresh_authoritative"
+>;
+
 interface TableInfoRow {
 	name: string;
 }
@@ -144,9 +196,11 @@ function invalidateReadPath(resolvedPath: string): void {
 
 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");
+	// statement. Current rows never persist request headers, so routine
+	// replacements do not need freed overflow pages zero-filled (that doubled
+	// the I/O of every multi-MB refresh). The legacy credential purge (#5780)
+	// re-enables ON just around its DELETE.
+	db.run("PRAGMA secure_delete = FAST");
 	db.run("PRAGMA journal_mode = WAL");
 	db.run(`
 		CREATE TABLE IF NOT EXISTS model_cache (
@@ -162,6 +216,14 @@ function initializeDb(db: Database): void {
 			models TEXT NOT NULL
 		)
 	`);
+	db.run(`
+		CREATE TABLE IF NOT EXISTS model_cache_refresh (
+			provider_id TEXT PRIMARY KEY,
+			payload_updated_at INTEGER NOT NULL,
+			updated_at INTEGER NOT NULL,
+			authoritative INTEGER NOT NULL
+		)
+	`);
 	migrateCacheSchema(db);
 }
 
@@ -237,15 +299,29 @@ function migrateCacheSchema(db: Database): void {
 	} finally {
 		stmt.finalize();
 	}
-	// Delete rows written under any older schema so they cannot be reused. The
-	// legacy `UPDATE ... WHERE version = 2` migration silently promoted the very
-	// first cache version to whatever the current one is, defeating every
-	// subsequent invalidation (see #4146: pre-V2 Codex rows kept the legacy
-	// compaction path even after CACHE_SCHEMA_VERSION was bumped).
-	db.run("DELETE FROM model_cache WHERE version <> ? OR materialization_policy <> ?", [
-		CACHE_SCHEMA_VERSION,
-		materializationPolicy(),
-	]);
+	// Rows predating v11 may carry credential-bearing request headers (v10 could
+	// still persist derived computer-use headers), so purge them and scrub the
+	// freed cells (#5780). Every other non-current row (v11/v12, a newer schema,
+	// or another materialization policy from a different app version sharing
+	// this file) never persisted headers: readers gate on the exact version and
+	// policy, treat it as absent, and the next write for that provider replaces
+	// it lazily, so switching versions does not wipe and re-download every
+	// provider. Never promote old rows in place: the legacy `UPDATE ... WHERE
+	// version = 2` migration did, defeating every later invalidation (#4146).
+	const legacyStmt = db.prepare("SELECT 1 AS found FROM model_cache WHERE version < ? LIMIT 1");
+	let hasLegacyRows: boolean;
+	try {
+		hasLegacyRows = legacyStmt.get(FIRST_HEADERLESS_SCHEMA_VERSION) !== null;
+	} finally {
+		legacyStmt.finalize();
+	}
+	if (!hasLegacyRows) return;
+	db.run("PRAGMA secure_delete = ON");
+	try {
+		db.run("DELETE FROM model_cache WHERE version < ?", [FIRST_HEADERLESS_SCHEMA_VERSION]);
+	} finally {
+		db.run("PRAGMA secure_delete = FAST");
+	}
 }
 
 function isMaterializedModel(value: unknown): value is PersistedModel<Api> {
@@ -260,8 +336,9 @@ function isMaterializedModel(value: unknown): value is PersistedModel<Api> {
 		model.api.length === 0 ||
 		typeof model.provider !== "string" ||
 		model.provider.length === 0 ||
+		// Empty is legitimate: Azure-style providers resolve the endpoint from
+		// configuration at request time, and their bundled rows carry "".
 		typeof model.baseUrl !== "string" ||
-		model.baseUrl.length === 0 ||
 		typeof model.reasoning !== "boolean" ||
 		!Array.isArray(model.input) ||
 		model.input.length === 0 ||
@@ -351,7 +428,7 @@ export function readModelCache<TApi extends Api>(
 			}
 			// 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 * FROM model_cache WHERE provider_id = ?");
+			const stmt = db.query<CacheRow, [string]>(SELECT_CACHE_ROW);
 			let row: CacheRow | null;
 			try {
 				row = stmt.get(providerId);
@@ -366,7 +443,8 @@ export function readModelCache<TApi extends Api>(
 				row.materialization_policy === materializationPolicy() &&
 				cacheRowsEqual(cached.row, row)
 			) {
-				entry = withFreshness(cached.entry as CacheEntry<TApi>, ttlMs, now);
+				// Payload bytes unchanged; only side-table freshness may have moved.
+				entry = withFreshness(withRowState(cached.entry as CacheEntry<TApi>, row), ttlMs, now);
 			} else {
 				entry = parseCacheRow<TApi>(db, providerId, row, ttlMs, now);
 			}
@@ -383,6 +461,7 @@ 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 {
 	return (
 		left.version === right.version &&
@@ -397,6 +476,25 @@ function cacheRowsEqual(left: CacheRow, right: CacheRow): boolean {
 	);
 }
 
+/** Effective freshness/authority: the side row wins while it refers to this payload. */
+function rowState(row: StoredRowState): { updatedAt: number; authoritative: boolean } {
+	if (
+		row.refresh_updated_at !== null &&
+		row.refresh_payload_updated_at === row.updated_at &&
+		row.refresh_authoritative !== null
+	) {
+		return { updatedAt: row.refresh_updated_at, authoritative: row.refresh_authoritative === 1 };
+	}
+	return { updatedAt: row.updated_at, authoritative: row.authoritative === 1 };
+}
+
+function withRowState<TApi extends Api>(entry: CacheEntry<TApi>, row: CacheRow): CacheEntry<TApi> {
+	const { updatedAt, authoritative } = rowState(row);
+	return entry.updatedAt === updatedAt && entry.authoritative === authoritative
+		? entry
+		: { ...entry, updatedAt, authoritative };
+}
+
 function parseCacheRow<TApi extends Api>(
 	db: Database,
 	providerId: string,
@@ -413,17 +511,19 @@ function parseCacheRow<TApi extends Api>(
 	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.
+		// silently absent. Current-schema rows never persist headers, so the
+		// rejected payload needs no secure scrub.
 		db.run("DELETE FROM model_cache WHERE provider_id = ?", [providerId]);
 		return null;
 	}
-	const ageMs = now() - row.updated_at;
+	const { updatedAt, authoritative } = rowState(row);
+	const ageMs = now() - updatedAt;
 	const fresh = Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= ttlMs;
 	return {
 		models,
 		fresh,
-		authoritative: row.authoritative === 1,
-		updatedAt: row.updated_at,
+		authoritative,
+		updatedAt,
 		headerOmittedModelIds,
 		unrestorableHeaderModelIds,
 		legacyHeaderRestoreMarkers: row.header_restore_version < HEADER_RESTORE_VERSION,
@@ -468,6 +568,16 @@ function headersEqual(left: Record<string, string> | undefined, right: Record<st
 	return true;
 }
 
+/**
+ * Persist a provider snapshot.
+ *
+ * When the stored payload (models, header provenance, fingerprint, schema and
+ * materialization policy) is byte-identical, the multi-MB row is left alone and
+ * only `model_cache_refresh` records the new freshness and authority; a write
+ * that changes nothing at all is skipped. Every model persisted here is
+ * validated with the reader's own predicate, so a row this writes is never
+ * rejected (and deleted) by `readModelCache`.
+ */
 export function writeModelCache<TApi extends Api>(
 	providerId: string,
 	updatedAt: number,
@@ -484,8 +594,16 @@ export function writeModelCache<TApi extends Api>(
 			const headerOmittedModelIds: string[] = [];
 			const unrestorableHeaderModelIds: string[] = [];
 			const cachedModels: PersistedModel<TApi>[] = [];
+			const rejectedModelIds: string[] = [];
 			const staticById = new Map(staticHeaderSources.map(model => [model.id, model]));
 			for (const model of models) {
+				const cachedModel = toCachedModel(model);
+				if (!isMaterializedModel(cachedModel)) {
+					// One unreadable model must not make the whole row fail
+					// validation on read (which deletes it and refetches forever).
+					rejectedModelIds.push(model.id);
+					continue;
+				}
 				if (hasModelHeaders(model)) {
 					headerOmittedModelIds.push(model.id);
 					// Synthesized variants (e.g. Copilot `-1m`) have no same-id static
@@ -507,27 +625,97 @@ export function writeModelCache<TApi extends Api>(
 						unrestorableHeaderModelIds.push(model.id);
 					}
 				}
-				cachedModels.push(toCachedModel(model));
+				cachedModels.push(cachedModel);
+			}
+			if (rejectedModelIds.length > 0) {
+				logger.debug("model cache skipped models that would fail cache validation", {
+					provider: providerId,
+					models: rejectedModelIds,
+				});
+			}
+			const policy = materializationPolicy();
+			const authoritativeFlag = authoritative ? 1 : 0;
+			const serializedHeaderOmitted = JSON.stringify(headerOmittedModelIds);
+			const serializedUnrestorable = JSON.stringify(unrestorableHeaderModelIds);
+			const serializedModels = JSON.stringify(cachedModels);
+			const outcome = db
+				.transaction((): "skipped" | "refreshed" | "written" => {
+					const matchStmt = db.prepare<
+						StoredRowState,
+						[string, number, string, string, string, string, number, string]
+					>(
+						`SELECT m.updated_at, m.authoritative,
+							r.payload_updated_at AS refresh_payload_updated_at,
+							r.updated_at AS refresh_updated_at,
+							r.authoritative AS refresh_authoritative
+						FROM model_cache m
+						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 = ?`,
+					);
+					let stored: StoredRowState | null;
+					try {
+						stored = matchStmt.get(
+							providerId,
+							CACHE_SCHEMA_VERSION,
+							policy,
+							staticFingerprint,
+							serializedHeaderOmitted,
+							serializedUnrestorable,
+							HEADER_RESTORE_VERSION,
+							serializedModels,
+						);
+					} finally {
+						matchStmt.finalize();
+					}
+					if (stored) {
+						const state = rowState(stored);
+						if (state.updatedAt === updatedAt && state.authoritative === authoritative) return "skipped";
+						db.run(
+							`INSERT INTO model_cache_refresh (provider_id, payload_updated_at, updated_at, authoritative)
+							VALUES (?, ?, ?, ?)
+							ON CONFLICT(provider_id) DO UPDATE SET
+								payload_updated_at = excluded.payload_updated_at,
+								updated_at = excluded.updated_at,
+								authoritative = excluded.authoritative`,
+							[providerId, stored.updated_at, updatedAt, authoritativeFlag],
+						);
+						return "refreshed";
+					}
+					db.run(
+						`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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+						[
+							providerId,
+							CACHE_SCHEMA_VERSION,
+							policy,
+							updatedAt,
+							authoritativeFlag,
+							staticFingerprint,
+							serializedHeaderOmitted,
+							serializedUnrestorable,
+							HEADER_RESTORE_VERSION,
+							serializedModels,
+						],
+					);
+					db.run("DELETE FROM model_cache_refresh WHERE provider_id = ?", [providerId]);
+					return "written";
+				})
+				.immediate();
+			if (outcome === "skipped") {
+				writeStats.skippedWrites++;
+			} else if (outcome === "refreshed") {
+				writeStats.refreshWrites++;
+			} else {
+				writeStats.payloadWrites++;
+				writeStats.payloadBytes += serializedModels.length;
+				if (recentPayloadProviders.length >= RECENT_PAYLOAD_PROVIDERS_MAX) recentPayloadProviders.shift();
+				recentPayloadProviders.push(providerId);
 			}
-			db.run(
-				`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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-				[
-					providerId,
-					CACHE_SCHEMA_VERSION,
-					materializationPolicy(),
-					updatedAt,
-					authoritative ? 1 : 0,
-					staticFingerprint,
-					JSON.stringify(headerOmittedModelIds),
-					JSON.stringify(unrestorableHeaderModelIds),
-					HEADER_RESTORE_VERSION,
-					JSON.stringify(cachedModels),
-				],
-			);
 		});
 	} catch {
 		// Cache writes are best-effort; failures should not break model resolution.