@tzyc/dsh-model-visibility 1.9.1 → 1.10.1

package/lib/learned-catalog.js

@@ -0,0 +1,294 @@
+/**
+ * The learned local capability snapshot.
+ *
+ * The plugin used to bundle a static pi-ai / models.dev snapshot; most relay
+ * providers publish neither reasoning ladders nor context windows, so that
+ * snapshot aged quickly and had to be regenerated by hand. It is gone: the
+ * replacement is this store, seeded by the settings page's "verify all
+ * models" run (public catalogs plus the checker model the user picked) and
+ * persisted in `$DSH_HOME/dsh-model-visibility/learned.json`.
+ *
+ * A verified fact is keyed by *normalized model id* rather than by provider,
+ * so the same model served under a second route, or a `:free` variant its
+ * relay invents later, resolves to the cached row without another sweep.
+ * Fields mirror the provider schema where possible so writes into provider
+ * settings and learned facts stay one transform apart.
+ *
+ * The Host reads the file synchronously and re-reads it when the mtime
+ * changes, following the same pattern as `lib/model-overrides.js`: a hand
+ * edit of `learned.json` is enough to apply a fix.
+ *
+ * @module lib/learned-catalog
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { MODEL_KINDS } from './capability-catalog.js'
+import { modelIdVariants } from './model-id.js'
+
+import { sanitizeEfforts, sanitizeModalities, text } from './model-overrides.js'
+
+/** Absolute path of the learned snapshot below `$DSH_HOME`. */
+export function learnedFile(home) {
+  const base = home || process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+  return path.join(base, 'dsh-model-visibility', 'learned.json')
+}
+
+/**
+ * Normalize one verified fact into the store's detached record.
+ * @param input - a check result entry, possibly malformed.
+ * @returns `{ id, idSource, entry }` or undefined when nothing usable remains.
+ */
+export function sanitizeLearned(input) {
+  if (input === null || typeof input !== 'object') return undefined
+  const id =
+    text(input.id) ??
+    (input.provider !== undefined && input.model !== undefined
+      ? text(input.model)
+      : undefined)
+  if (id === undefined || text(id) === '') return undefined
+  const entry = {}
+  if (typeof input.type === 'string' && MODEL_KINDS.includes(input.type)) entry.type = input.type
+  const inputModalities = sanitizeModalities(input.input)
+  if (inputModalities !== undefined) entry.input = inputModalities
+  const output = sanitizeModalities(input.output)
+  if (output !== undefined) entry.output = output
+  if (Number.isSafeInteger(input.contextWindow) && input.contextWindow > 0) {
+    entry.contextWindow = input.contextWindow
+  }
+  if (Number.isSafeInteger(input.maxTokens) && input.maxTokens > 0) entry.maxTokens = input.maxTokens
+  const efforts = sanitizeEfforts(input.reasoningEfforts ?? input.efforts)
+  if (efforts !== undefined) entry.reasoningEfforts = efforts
+  const defaultEffort = text(input.defaultEffort)
+  if (defaultEffort !== undefined) entry.defaultEffort = defaultEffort
+  if (typeof input.reasoning === 'boolean') entry.reasoning = input.reasoning
+  const provider = text(input.provider)
+  if (provider !== undefined) entry.provider = provider
+  const declared =
+    entry.type !== undefined ||
+    entry.input !== undefined ||
+    entry.output !== undefined ||
+    entry.contextWindow !== undefined ||
+    entry.maxTokens !== undefined ||
+    entry.reasoningEfforts !== undefined ||
+    entry.reasoning !== undefined
+  if (!declared) return undefined
+  const origins = Array.isArray(input.origins)
+    ? [...new Set(input.origins.filter((item) => item === 'public' || item === 'checker' || item === 'manual'))]
+    : []
+  const verifiedAt = Number(input.verifiedAt)
+  return {
+    id,
+    idSource: typeof input.idSource === 'string' ? input.idSource : 'id',
+    entry: {
+      ...entry,
+      verifiedAt: Number.isSafeInteger(verifiedAt) && verifiedAt > 0 ? verifiedAt : Date.now(),
+      ...(origins.length > 0 ? { origins } : { origins: [] }),
+      ...(input.checker !== null && typeof input.checker === 'object'
+        ? { checker: input.checker }
+        : {}),
+    },
+  }
+}
+
+/**
+ * A file-backed store of verified capability facts, keyed by normalized id.
+ *
+ * @param options - `{ file?, home?, logger?, now? }`.
+ * @returns `{ file, meta, list, get, upsertEntries, invalidate }`.
+ */
+export function createLearnedCatalog(options = {}) {
+  const file = options.file || learnedFile(options.home)
+  const logger = options.logger ?? console
+  const now = typeof options.now === 'function' ? options.now : Date.now
+  /** `variants -> canonical id`, rebuilt whenever the file changes. */
+  let index = new Map()
+  /** canonical id -> detached record (entry keys, provider shape). */
+  let records = new Map()
+  let store = null
+  let loaded = false
+  let loadedMtime = -Infinity
+
+  const warn = (message, error) => {
+    if (typeof logger.warn === 'function') {
+      logger.warn(message)
+      if (error !== undefined) logger.warn(error)
+    }
+  }
+
+  const mtimeOf = () => {
+    try {
+      return fs.statSync(file).mtimeMs
+    } catch (_error) {
+      return -Infinity
+    }
+  }
+
+  const buildIndex = () => {
+    index = new Map()
+    for (const [canonical, record] of records) {
+      for (const variant of modelIdVariants(record.id)) {
+        if (!index.has(variant)) index.set(variant, canonical)
+      }
+      if (!index.has(canonical)) index.set(canonical, canonical)
+    }
+  }
+
+  const readRecord = (raw) => {
+    const sanitized = sanitizeLearned(raw)
+    if (sanitized === undefined) return undefined
+    const record = sanitized.entry
+    return { id: sanitized.id, ...record }
+  }
+
+  const load = (force = false) => {
+    const mtime = mtimeOf()
+    if (!force && loaded && mtime === loadedMtime) return
+    loaded = true
+    loadedMtime = mtime
+    records = new Map()
+    store = null
+    if (mtime === -Infinity) {
+      buildIndex()
+      return
+    }
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+      store = parsed !== null && typeof parsed === 'object' ? parsed : null
+      const source =
+        store !== null && store.models !== null && typeof store.models === 'object'
+          ? store.models
+          : null
+      if (source !== null) {
+        for (const [key, raw] of Object.entries(source)) {
+          const record = readRecord(raw)
+          if (record !== undefined && !records.has(key)) records.set(key, record)
+        }
+      }
+    } catch (error) {
+      warn('model-visibility: could not read the learned snapshot; starting empty', error)
+      store = null
+    }
+    buildIndex()
+  }
+
+  const persistLocked = () => {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const body = {
+      version: 1,
+      ...(store?.checker !== undefined ? { checker: store.checker } : {}),
+      updatedAt: now(),
+      models: Object.fromEntries([...records.entries()].map(([key, record]) => [key, record])),
+    }
+    const temp = `${file}.${process.pid}.tmp`
+    fs.writeFileSync(temp, `${JSON.stringify(body, null, 2)}\n`)
+    fs.renameSync(temp, file)
+    loadedMtime = mtimeOf()
+  }
+
+  /** Footer facts for the settings page (full file read). */
+  const meta = () => {
+    load()
+    return {
+      file,
+      models: records.size,
+      updatedAt:
+        store !== null && Number.isSafeInteger(store.updatedAt) ? store.updatedAt : undefined,
+      checker: store !== null && store.checker !== null && typeof store.checker === 'object' ? store.checker : undefined,
+    }
+  }
+
+  /** Detached copies of every fact, in normalized-key order. */
+  const list = () => {
+    load()
+    return [...records.values()].map((record) => ({ ...record }))
+  }
+
+  /** One verified fact for any spelling of the model id, or undefined. */
+  const get = (value) => {
+    if (typeof value !== 'string') return undefined
+    const variants = modelIdVariants(value)
+    if (variants.length === 0) return undefined
+    load()
+    let fallback
+    for (const variant of variants) {
+      const canonical = index.get(variant)
+      if (canonical === undefined) {
+        if (fallback === undefined && records.has(variant)) fallback = records.get(variant)
+        continue
+      }
+      const record = records.get(canonical)
+      if (record === undefined) continue
+      return { ...record }
+    }
+    return fallback === undefined ? undefined : { ...fallback }
+  }
+
+  /**
+   * Merge verified facts in; later entries win per field and `verifiedAt`.
+   *
+   * The same model may arrive twice (its id from one relay, a corrected id
+   * from the checker), so records merge instead of replacing: newer facts
+   * overwrite older ones field by field and the freshest `verifiedAt` stays.
+   * @param inputs - check results, each `{ id | provider+model, …facts }`.
+   */
+  const upsertEntries = (inputs, extra = {}) => {
+    load(true)
+    const source = Array.isArray(inputs) ? inputs : [inputs]
+    let changed = false
+    for (const raw of source) {
+      const sanitized = sanitizeLearned(raw)
+      if (sanitized === undefined) continue
+      // Call-side provenance beats the entry's own stamps: the orchestrator
+      // knows the run that produced the fact.
+      const provenance = {}
+      if (extra?.verifiedAt !== undefined) provenance.verifiedAt = extra.verifiedAt
+      if (extra?.origins !== undefined) provenance.origins = extra.origins
+      if (extra?.checker !== undefined) provenance.checker = extra.checker
+      const record = { provider: raw?.provider, ...sanitized.entry, ...provenance, id: sanitized.id }
+      const key = modelIdVariants(record.id)[0] ?? sanitized.id
+      const existing = records.get(key)
+      if (existing === undefined) {
+        records.set(key, record)
+        changed = true
+        continue
+      }
+      const next = { ...existing }
+      for (const [field, value] of Object.entries(record)) {
+        if (value === undefined || value === null) continue
+        if (field === 'verifiedAt') {
+          next.verifiedAt = Math.max(existing.verifiedAt ?? 0, value)
+          continue
+        }
+        if (field === 'origins' && Array.isArray(existing.origins)) {
+          const union = [...new Set([...existing.origins, ...value])]
+          if (JSON.stringify(union) === JSON.stringify(existing.origins)) continue
+          next.origins = union
+          continue
+        }
+        next[field] = value
+      }
+      if (JSON.stringify(next) !== JSON.stringify(existing)) {
+        records.set(key, next)
+        changed = true
+      }
+    }
+    if (changed) {
+      buildIndex()
+      try {
+        persistLocked()
+      } catch (error) {
+        warn('model-visibility: could not write the learned snapshot', error)
+      }
+    }
+  }
+
+  /** Forget the memoized copy; the next read consults the file again. */
+  const invalidate = () => {
+    loaded = false
+    loadedMtime = -Infinity
+  }
+
+  return { file, meta, list, get, upsertEntries, invalidate }
+}

package/lib/model-id.js

@@ -0,0 +1,50 @@
+/**
+ * Model-id normalization shared by every matching layer.
+ *
+ * Split out of `capability-catalog.js` so the relay aggregator rules stay in
+ * one place after the bundled static catalog was replaced by the learned
+ * local snapshot (`lib/learned-catalog.js`).
+ *
+ * Relays spell ids slightly differently than the canonical model name: an
+ * aggregator namespaces them (`openai/gpt-4o`), request suffixes are stacked
+ * (`glm-5.3:free:batch`), a leading `~` marks a route prefix, and resolution
+ * twins exist (`gpt-5.1` vs `gpt-5-1`). `modelIdVariants` deliberately stays
+ * conservative — over-folding would merge two real models — but the first
+ * variant always matches the canonical catalog row.
+ *
+ * @module lib/model-id
+ */
+
+/** Strip aggregator namespaces, request suffixes and resolution variants. */
+export function normalizeModelId(value) {
+  let id = String(value ?? '').trim().toLowerCase()
+  if (id === '') return ''
+  id = id.replace(/^~/, '')
+  // Providers may stack request variants (for example `:free:thinking`).
+  // Strip them one at a time so aliases remain stable without broad folding.
+  let previous
+  do {
+    previous = id
+    id = id.replace(/:(batch|free|extended|thinking|online|nitro)$/, '')
+    id = id.replace(/-(free|batch)$/, '')
+  } while (id !== previous)
+  const slash = id.lastIndexOf('/')
+  if (slash !== -1) id = id.slice(slash + 1)
+  id = id.replace(/^(global|us|eu|apac|jp|au|ca)\./, '')
+  id = id.replace(/^(anthropic|openai|google|xai|x-ai|meta|mistralai|moonshotai|minimax|nvidia|qwen|z-ai|zai|deepseek|bytedance-seed)\./, '')
+  return id
+}
+
+/** Lookup keys for one model id, most specific first. */
+export function modelIdVariants(value) {
+  const base = normalizeModelId(value)
+  if (base === '') return []
+  const variants = [base]
+  const withoutResolution = base.replace(/-(4k|2k|8k|hd|uhd)$/, '')
+  if (withoutResolution !== base) variants.push(withoutResolution)
+  const withoutSuffix = withoutResolution.replace(/-(latest|preview|new)$/, '')
+  if (!variants.includes(withoutSuffix)) variants.push(withoutSuffix)
+  const compact = base.replace(/[^a-z0-9]+/g, '')
+  if (compact !== '' && !variants.includes(compact)) variants.push(compact)
+  return variants
+}

package/lib/model-info.js

@@ -26,10 +26,12 @@
  *                   configured model declares the field.
  *   3. `provider` — capability fields found by probing the relay's own
  *                   `/v1/models` (see `provider-probe.js`).
- *   4. `catalog`  — the pi-ai / models.dev snapshot (see `capability-catalog.js`).
+ *   4. `snapshot` — a verified fact from the learned local snapshot
+ *                   (`lib/learned-catalog.js`), seeded by the settings page's
+ *                   online verification run.
  *   5. `inferred` — conservative name rules for well-known model families.
  *
- * The browser renders `catalog`/`inferred` facts with a dashed tag and explains
+ * The browser renders `snapshot`/`inferred` facts with a dashed tag and explains
  * the source in the tooltip; a missing fact stays "unknown" instead of becoming
  * a false "text only".
  *
@@ -41,18 +43,29 @@
  */
 
 import {
-  CATALOG_GENERATED_AT,
-  CATALOG_PI_AI_VERSION,
-  MODEL_CATALOG,
   MODEL_KINDS,
   inferInputModalities,
   inferModelKind,
-  lookupCatalogModel,
-  modelIdVariants,
 } from './capability-catalog.js'
 import { lookupCorrection } from './capability-corrections.js'
+import { modelIdVariants } from './model-id.js'
+import { createLearnedCatalog } from './learned-catalog.js'
 
-export { CATALOG_GENERATED_AT, CATALOG_PI_AI_VERSION }
+/**
+ * Fallback learned snapshot used when the caller does not inject one. The
+ * Host constructs its own store so the settings page and the request-side
+ * image gate share one mtime-memoized read; a plain consumer of this module
+ * (a test double, another tool) still gets learned facts without wiring.
+ */
+let defaultLearned = null
+function lookupLearned(value) {
+  try {
+    if (defaultLearned === null) defaultLearned = createLearnedCatalog({})
+    return defaultLearned.get(value)
+  } catch (_error) {
+    return undefined
+  }
+}
 
 /** Default lifetime of one catalog snapshot, in milliseconds. */
 export const DEFAULT_TTL_MS = 15_000
@@ -217,7 +230,7 @@ function multiModalDefault(input) {
  *
  * Exported for unit tests: it is pure and takes plain values.
  * @param base - `{ id, name, description? }`.
- * @param context - `{ adapter?, infoError?, profile?, configured?, discovered?, catalogEntry?, override? }`.
+ * @param context - `{ adapter?, infoError?, profile?, configured?, discovered?, learned?, override? }`
  * @returns a detached model record with per-field sources.
  */
 export function mergeCapabilities(base, context = {}) {
@@ -226,12 +239,14 @@ export function mergeCapabilities(base, context = {}) {
   const configured = context.configured ?? mapGet(profile?.models, base.id)
   const discovered = context.discovered
   const override = context.override
-  const catalogEntry = context.catalogEntry ?? lookupCatalogModel(base.id)
+  const learned = context.learned ?? lookupLearned(base.id)
   const sources = {}
-  let catalogUsed = false
+  let learnedUsed = false
+  let learnedRecord = null
 
-  const useCatalog = () => {
-    catalogUsed = true
+  const useLearned = (record) => {
+    learnedUsed = true
+    if (record !== null && typeof record === 'object') learnedRecord = record
   }
 
   /* ---------------------------------------------------------------- kind */
@@ -241,10 +256,10 @@ export function mergeCapabilities(base, context = {}) {
   if (discovered?.kind !== undefined) {
     kind = discovered.kind
     sources.kind = 'provider'
-  } else if (catalogEntry?.type !== undefined) {
-    kind = catalogEntry.type
-    sources.kind = 'catalog'
-    useCatalog()
+  } else if (learned?.type !== undefined) {
+    kind = learned.type
+    sources.kind = 'snapshot'
+    useLearned(learned)
   } else if (inferredKind !== undefined) {
     kind = inferredKind
     sources.kind = 'inferred'
@@ -292,11 +307,11 @@ export function mergeCapabilities(base, context = {}) {
     inputModalities = modalityList(discovered.inputModalities)
     if (inputModalities !== undefined) modalitySource = 'provider'
   }
-  if (inputModalities === undefined && catalogEntry?.input !== undefined) {
-    inputModalities = modalityList(catalogEntry.input)
+  if (inputModalities === undefined && learned?.input !== undefined) {
+    inputModalities = modalityList(learned.input)
     if (inputModalities !== undefined) {
-      modalitySource = 'catalog'
-      useCatalog()
+      modalitySource = 'snapshot'
+      useLearned(learned)
     }
   }
   if (inputModalities === undefined && kind === 'chat') {
@@ -315,7 +330,7 @@ export function mergeCapabilities(base, context = {}) {
   let correctionApplied = false
   if (
     correction?.input !== undefined &&
-    (modalitySource === 'catalog' ||
+    (modalitySource === 'snapshot' ||
       modalitySource === 'inferred' ||
       modalitySource === 'unknown' ||
       modalitySource === 'provider')
@@ -356,11 +371,11 @@ export function mergeCapabilities(base, context = {}) {
     contextWindow = positiveInteger(discovered.contextWindow)
     if (contextWindow !== undefined) contextSource = 'provider'
   }
-  if (contextWindow === undefined && catalogEntry?.contextWindow !== undefined) {
-    contextWindow = positiveInteger(catalogEntry.contextWindow)
+  if (contextWindow === undefined && learned?.contextWindow !== undefined) {
+    contextWindow = positiveInteger(learned.contextWindow)
     if (contextWindow !== undefined) {
-      contextSource = 'catalog'
-      useCatalog()
+      contextSource = 'snapshot'
+      useLearned(learned)
     }
   }
   const manualContext = positiveInteger(override?.contextWindow)
@@ -380,10 +395,16 @@ export function mergeCapabilities(base, context = {}) {
   } else if (discovered?.reasoning !== undefined) {
     reasoningSupported = discovered.reasoning === true
     reasoningSource = 'provider'
-  } else if (catalogEntry?.reasoning !== undefined) {
-    reasoningSupported = catalogEntry.reasoning === true
-    reasoningSource = 'catalog'
-    useCatalog()
+  } else if (learned?.reasoning !== undefined) {
+    reasoningSupported = learned.reasoning === true
+    // A learned fact that carries a verified ladder also supplies the ladder.
+    const ladder = detachReasoning({
+      efforts: learned.reasoningEfforts,
+      defaultEffort: learned.defaultEffort,
+    })
+    if (ladder !== undefined) reasoning = ladder
+    reasoningSource = 'snapshot'
+    useLearned(learned)
   }
 
   // A manual ladder is the requested fix for relays that publish no effort
@@ -418,15 +439,15 @@ export function mergeCapabilities(base, context = {}) {
   if (defaultMaxTokens === undefined && discovered?.maxTokens !== undefined) {
     defaultMaxTokens = positiveInteger(discovered.maxTokens)
   }
-  if (defaultMaxTokens === undefined && catalogEntry?.maxTokens !== undefined) {
-    defaultMaxTokens = positiveInteger(catalogEntry.maxTokens)
+  if (defaultMaxTokens === undefined && learned?.maxTokens !== undefined) {
+    defaultMaxTokens = positiveInteger(learned.maxTokens)
   }
 
   /* --------------------------------------------------------- output side */
 
   const outputModalities =
     modalityList(discovered?.outputModalities) ??
-    modalityList(catalogEntry?.output) ??
+    modalityList(learned?.output) ??
     (kind === 'image'
       ? ['image']
       : kind === 'video'
@@ -460,14 +481,17 @@ export function mergeCapabilities(base, context = {}) {
           },
         }
       : {}),
-    ...(catalogUsed
+    ...(learnedUsed && learnedRecord !== null
       ? {
-          catalog: {
-            id: catalogEntry.id,
-            ...(nonEmptyString(catalogEntry.provider) === undefined
-              ? {}
-              : { provider: catalogEntry.provider }),
-            ...(CATALOG_GENERATED_AT === null ? {} : { generatedAt: CATALOG_GENERATED_AT }),
+          learned: {
+            id: learnedRecord.id ?? base.id,
+            ...(Number.isSafeInteger(learnedRecord.verifiedAt)
+              ? { verifiedAt: learnedRecord.verifiedAt }
+              : {}),
+            ...(Array.isArray(learnedRecord.origins) && learnedRecord.origins.length > 0
+              ? { origins: [...learnedRecord.origins] }
+              : {}),
+            ...(learnedRecord.checker !== undefined ? { checker: learnedRecord.checker } : {}),
           },
         }
       : {}),
@@ -503,7 +527,7 @@ export function imageInputDecision(providerId, modelId, context = {}) {
   const discovered = findDiscovered(discoveredIndex, modelId)
   const record = mergeCapabilities(
     { id: modelId, name: modelId },
-    { profile, configured, discovered, override: context.override },
+    { profile, configured, discovered, override: context.override, learned: context.learned },
   )
   const modalities = Array.isArray(record.inputModalities) ? record.inputModalities : []
   if (record.kind !== 'chat') return { allowed: false, record, reason: 'non-chat' }
@@ -524,7 +548,7 @@ export function imageInputDecision(providerId, modelId, context = {}) {
  * @param llm - the Host `ctx.llm` registry (or a test double).
  * @param providerId - provider route the model belongs to.
  * @param model - catalog entry `{ id, name?, description?, inputModalities? }`.
- * @param context - `{ profile?, discovered?, override? }` enrichment for this provider.
+ * @param context - `{ profile?, discovered?, override?, learned? }` enrichment for this provider.
  * @returns a detached model record.
  */
 export async function describeModel(llm, providerId, model, context = {}) {
@@ -553,6 +577,7 @@ export async function describeModel(llm, providerId, model, context = {}) {
     configured: mapGet(profile?.models, model.id),
     discovered,
     override: context.override,
+    learned: context.learned ?? lookupLearned(model.id),
   })
 }
 
@@ -578,7 +603,7 @@ async function resolveEnrichment(options, fresh) {
  *     "kind", "contextWindow", "inputModalities", "reasoning", "sources" }] }],
  *   "failures": [{ "id", "name", "message" }],
  *   "providers": [{ "id", "status", "models", "capabilities" }],
- *   "catalog": { "generatedAt", "piAiVersion", "models" },
+ *   "learned": { "models", "updatedAt?", "checker?" },
  *   "generatedAt": 1700000000000
  * }
  * ```
@@ -586,13 +611,19 @@ async function resolveEnrichment(options, fresh) {
  * Provider failures are isolated exactly like the shipped catalog. Empty
  * provider groups are dropped so the page never shows a header with no rows.
  * @param llm - the Host `ctx.llm` registry (or a test double).
- * @param options - `{ enrichment?, fresh? }`.
+ * @param options - `{ enrichment?, fresh?, learned? }`; `learned` is the
+ *   Host-owned learned-catalog store backing the `snapshot` evidence layer.
  * @returns the catalog value.
  */
 export async function describeCatalog(llm, options = {}) {
   const generatedAt = Date.now()
   const groups = []
   const failures = []
+  // Adopting the caller's store here also points the module-level fallback at
+  // the Host's single mtime-memoized read; direct consumers without a store
+  // keep their lazy default.
+  if (options.learned !== undefined) defaultLearned = options.learned
+  const learnedStore = options.learned ?? (defaultLearned ?? undefined)
   const enrichment = await resolveEnrichment(options, options.fresh === true)
   const profiles = enrichment?.profiles instanceof Map ? enrichment.profiles : new Map()
   const discovered = enrichment?.discovered instanceof Map ? enrichment.discovered : new Map()
@@ -606,7 +637,7 @@ export async function describeCatalog(llm, options = {}) {
       groups,
       failures: [{ id: '*', name: 'providers', message: messageOf(error) }],
       providers: [],
-      catalog: catalogMeta(),
+      learned: catalogMeta(),
       generatedAt,
     }
   }
@@ -632,6 +663,7 @@ export async function describeCatalog(llm, options = {}) {
                 profile,
                 discoveredIndex,
                 override: typeof overrides?.get === 'function' ? overrides.get(id, model.id) : undefined,
+                learned: learnedStore?.get?.(model.id),
               }),
             ),
         )
@@ -652,21 +684,24 @@ export async function describeCatalog(llm, options = {}) {
     groups,
     failures,
     providers: Array.isArray(enrichment?.diagnostics) ? enrichment.diagnostics : [],
-    catalog: catalogMeta(),
+    learned: catalogMeta(),
     generatedAt,
   }
 }
 
-/** Non-secret provenance of the bundled snapshot, for the page footer. */
+/** Non-secret provenance of the learned snapshot, for the page footer. */
 function catalogMeta() {
+  const meta = defaultLearned?.meta?.()
   return {
-    generatedAt: CATALOG_GENERATED_AT ?? null,
-    piAiVersion: CATALOG_PI_AI_VERSION ?? null,
-    models: Object.keys(MODEL_CATALOG).length,
+    models: meta?.models ?? 0,
+    ...(meta?.updatedAt !== undefined ? { updatedAt: meta.updatedAt } : {}),
+    ...(meta?.checker !== undefined ? { checker: meta.checker } : {}),
     // Lets a newer browser half detect an older Host half after an upgrade.
     // `reload` means the route understands `?reload=1` and drops every cache;
-    // `overrides` means the Host persists and serves manual capability edits.
-    features: ['applyInput', 'reload', 'overrides'],
+    // `overrides` means the Host persists and serves manual capability edits;
+    // `verify` means the Host can sweep every model online; `usage` means the
+    // Host serves the token-usage ledger.
+    features: ['applyInput', 'reload', 'overrides', 'verify', 'usage'],
   }
 }
 
@@ -711,6 +746,7 @@ export function createModelInfoService(llm, options = {}) {
     const run = describeCatalog(llm, {
       enrichment: options.enrichment,
       overrides: options.overrides,
+      learned: options.learned,
       fresh,
     })
       .then((value) => {
@@ -764,6 +800,12 @@ export function createModelInfoService(llm, options = {}) {
         profile: profiles?.get(providerId),
         discovered: discovered?.get(providerId),
         override: typeof overrides?.get === 'function' ? overrides.get(providerId, modelId) : undefined,
+        learned:
+          typeof source.learned === 'function'
+            ? source.learned(modelId)
+            : typeof source.learned?.get === 'function'
+              ? source.learned.get(modelId)
+              : source.learned,
       }).allowed
     } catch (_error) {
       // A capability read must never break the request path.

package/lib/model-overrides.js

@@ -52,7 +52,7 @@ const EFFORT_NAMES = {
 const MAX_EFFORTS = 16
 
 /** Read a trimmed non-empty string, or undefined. */
-function text(value) {
+export function text(value) {
   if (typeof value !== 'string') return undefined
   const trimmed = value.trim()
   return trimmed === '' ? undefined : trimmed