/**
 * Data-driven reasoning ladders for routed providers.
 *
 * Routed providers rarely publish per-model effort ladders: OpenCode Zen Go answers /models
 * with ids only (id/object/created/owned_by), so opencodex had to hardcode ladders in
 * registry.ts and synthesise max/ultra for codex-rs catalog membership. The public models.dev
 * catalogue DOES publish them per model:
 *   reasoning: true
 *   reasoning_options: [{type:"effort",values:["low","high","max"]}, {type:"toggle"},
 *                       {type:"budget_tokens"}]
 * This module snapshots that catalogue to disk and hands configuredReasoningEfforts() a
 * fallback ladder, so the Codex catalog AND the wire clamp agree with the model instead of a
 * hand-written guess.
 *
 * Failure policy: a missing or corrupt snapshot yields undefined, and an expired snapshot still
 * serves its last ladder while a best-effort refresh runs in the background. The second
 * cache records rungs the upstream actually rejected (400/403 naming reasoning_effort), so an
 * entitlement gap (muse-spark max needs an active Muse Code subscription) costs one rejected
 * request instead of failing every turn that selects that rung.
 */
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
// Leaf modules on purpose: this file is imported from reasoning-effort.ts, which combos/types.ts
// already imports. Going through the ../config barrel closes a cycle back into account-namespaces.ts
// and leaves COMBO_NAMESPACE in its temporal dead zone for entry points that start at combos/types.ts.
import { atomicWriteFile } from "../config/atomic-write";
import { getConfigDir } from "../config/paths";
import type { OcxProviderConfig } from "../types";
import { resolveProviderApiKey } from "./api-key-resolve";

const FILENAME = "reasoning-metadata-cache.json";
const SUPPORT_FILENAME = "reasoning-support-cache.json";
const SOURCE_URL = "https://models.dev/api.json";
const USER_AGENT = "opencodex-reasoning-metadata/1.0 (+https://github.com/lidge-jun/opencodex)";
/** Snapshot age that triggers a background refresh. Older snapshots still serve reads. */
const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
/** A learned "this rung is refused" fact expires: entitlements change. */
const SUPPORT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
const PERSIST_DEBOUNCE_MS = 250;

/** Canonical Codex ladder order; mirrors reasoning-effort.ts CODEX_REASONING_LEVELS. */
const LADDER_ORDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
/** Ranked rungs used for downgrade planning; ultra is client-only and folds to max. */
const RANKED = ["low", "medium", "high", "xhigh", "max"];
/** Mirror of registry.ts THINKING_TOGGLE_EFFORTS / THINKING_BUDGET_EFFORTS. */
const CLASSIFIED_STYLE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];

/**
 * models.dev provider key for a provider config. OcxProviderConfig carries no id, so the
 * destination URL is the stable handle. Only destinations this patch has evidence for are
 * listed; an unlisted provider simply keeps its current behaviour.
 */
const BASE_URL_TO_METADATA_PROVIDER: Record<string, string> = {
  "https://opencode.ai/zen/go/v1": "opencode-go",
  "https://opencode.ai/zen/v1": "opencode",
};

/**
 * Both sides of the mapping are compared after this normalisation, so a trailing slash or a
 * `/v1` suffix never decides whether a destination resolves. models.dev publishes each
 * provider's own `api` URL; the snapshot keeps it (v2) so the mapping can be checked against
 * published data instead of trusted blindly.
 */
export function normalizeDestinationUrl(url: string | undefined): string | undefined {
  if (typeof url !== "string" || url.trim() === "") return undefined;
  try {
    const parsed = new URL(url.trim());
    const path = parsed.pathname.replace(/\/+$/, "").replace(/\/v1$/i, "");
    return (parsed.protocol + "//" + parsed.host + path).toLowerCase();
  } catch {
    return undefined;
  }
}

export type ReasoningMetadataOption = { type: string; values?: string[] };
export type ReasoningMetadataModel = { reasoning: boolean; options: ReasoningMetadataOption[] };

interface MetadataSnapshot {
  version: 1 | 2;
  fetchedAt: number;
  source: string;
  providers: Record<string, Record<string, ReasoningMetadataModel>>;
  /**
   * v2: models.dev provider key -> that provider's published api URL (normalised). v1 snapshots
   * predate the field and keep working through BASE_URL_TO_METADATA_PROVIDER.
   */
  apis?: Record<string, string>;
}

interface SupportSnapshot {
  version: 2;
  rows: Record<string, { effort: string; at: number; evidence?: string }>;
}

let snapshotMemo: MetadataSnapshot | null | undefined;
let supportMemo: Map<string, number> | undefined;
let persistTimer: ReturnType<typeof setTimeout> | null = null;
let refreshInFlight: Promise<unknown> | null = null;

/** Test seam: drop the memoised snapshot/support caches so a suite can drive the load paths. */
export function resetReasoningMetadataCachesForTests(): void {
  snapshotMemo = undefined;
  supportMemo = undefined;
  if (persistTimer) {
    clearTimeout(persistTimer);
    persistTimer = null;
  }
  refreshInFlight = null;
}

function readJsonFile<T>(filename: string): T | null {
  try {
    const path = join(getConfigDir(), filename);
    if (!existsSync(path)) return null;
    return JSON.parse(readFileSync(path, "utf8")) as T;
  } catch {
    // A corrupt cache must never break routing, the catalog, or the dashboard.
    return null;
  }
}

/** Canonical order + dedupe. Local mirror of sanitizeCodexReasoningEfforts (import cycle). */
function sanitizeLadder(values: readonly string[] | undefined): string[] | undefined {
  if (!Array.isArray(values)) return undefined;
  const seen = new Set(values.filter((value): value is string => typeof value === "string"));
  const ordered = LADDER_ORDER.filter(effort => seen.has(effort));
  return ordered.length > 0 ? ordered : undefined;
}

function metadataProviderKey(provider: OcxProviderConfig): string | undefined {
  const normalized = normalizeDestinationUrl(typeof provider.baseUrl === "string" ? provider.baseUrl : undefined);
  if (!normalized) return undefined;
  for (const [destination, key] of Object.entries(BASE_URL_TO_METADATA_PROVIDER)) {
    if (normalizeDestinationUrl(destination) === normalized) return key;
  }
  return undefined;
}

/** Whether catalog sync should bootstrap metadata for this destination. */
export function providerUsesReasoningMetadata(provider: OcxProviderConfig): boolean {
  return metadataProviderKey(provider) !== undefined;
}

/**
 * Local mirror of `modelRecordValue()` from `src/reasoning-effort.ts`, which imports this
 * module and so cannot be imported back. Exact id, then the `family:` prefix, then a
 * case-folded match — a configured ladder must resolve here exactly as it does there, or the
 * downgrade rung is chosen off a different ladder than the catalog advertises.
 */
function modelLadderValue(
  record: Record<string, string[]> | undefined,
  modelId: string,
): readonly string[] | undefined {
  if (!record) return undefined;
  if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];
  const colon = modelId.indexOf(":");
  if (colon > 0) {
    const family = modelId.slice(0, colon);
    if (Object.prototype.hasOwnProperty.call(record, family)) return record[family];
  }
  const folded = modelId.toLowerCase();
  for (const [key, value] of Object.entries(record)) {
    if (key.toLowerCase() === folded) return value;
  }
  return undefined;
}

/**
 * Bind learned capability to the credential that supplied the evidence. A digest keeps the
 * credential itself out of the persisted cache while remaining stable across restarts and key
 * selection. Providers without key-auth identity may use metadata, but cannot teach the cache.
 *
 * The hash input is the resolved wire credential, not the configured expression: the catalog
 * path carries the raw config string in apiKey (a keychain:/env reference stays unresolved
 * there), while the request path carries the resolved secret in apiKey and the configured
 * expression in _apiKeyAttempt.reference. The request path hashes apiKey exactly as routed --
 * the reference is only provenance, and re-resolving it at record time could read a credential
 * rotated since the request was served. The catalog path resolves the configured expression,
 * so both sides still bind learned refusals to the same wire credential, and a rotation behind
 * a stable reference starts clean instead of inheriting the previous credential's refusals.
 */
function credentialIdentity(provider: OcxProviderConfig): string | undefined {
  const resolved = provider._apiKeyAttempt?.reference !== undefined
    ? provider.apiKey
    : resolveProviderApiKey(provider.apiKey);
  if (typeof resolved !== "string" || resolved.length === 0) return undefined;
  return createHash("sha256").update(resolved).digest("hex");
}

/** JSON encoding avoids delimiter ambiguity in provider, model, and effort identifiers. */
function supportKey(providerKey: string, credential: string, modelId: string, effort: string): string {
  return JSON.stringify([providerKey, credential, modelId, effort]);
}

function loadSnapshot(): MetadataSnapshot | null {
  if (snapshotMemo !== undefined) return snapshotMemo;
  const parsed = readJsonFile<MetadataSnapshot>(FILENAME);
  snapshotMemo = parsed && (parsed.version === 1 || parsed.version === 2) && parsed.providers && typeof parsed.providers === "object"
    ? parsed
    : null;
  return snapshotMemo;
}

/**
 * Mapping report for diagnostics and tests: every gated destination, the models.dev provider it
 * resolves to, and whether the snapshot (v2) publishes an `api` URL that confirms it. The gate is
 * deliberate -- 36 of the registry's 83 destinations match a models.dev provider, so resolving by
 * URL alone would silently move ladders for providers this change has no evidence for.
 */
export function reasoningMetadataMapping(): Array<{
  destination: string;
  provider: string;
  publishedApi?: string;
  confirmed?: boolean;
  models: number;
}> {
  const snapshot = loadSnapshot();
  return Object.entries(BASE_URL_TO_METADATA_PROVIDER).map(([destination, provider]) => {
    const normalized = normalizeDestinationUrl(destination);
    const publishedApi = snapshot?.apis?.[provider];
    const row = {
      destination,
      provider,
      ...(publishedApi ? { publishedApi } : {}),
      ...(publishedApi ? { confirmed: publishedApi === normalized } : {}),
      models: Object.keys(snapshot?.providers?.[provider] ?? {}).length,
    };
    return row;
  });
}

function loadSupport(): Map<string, number> {
  const nowMs = Date.now();
  if (supportMemo) {
    // The memo lives for the process lifetime, so the TTL has to be re-applied on every read.
    // Checking it only on the disk load meant a long-running proxy kept clamping on a refusal
    // it recorded a month earlier, and `dropLearnedUnsupportedReasoningEfforts` inherited that
    // through the same map.
    for (const [key, at] of supportMemo) {
      if (nowMs - at > SUPPORT_TTL_MS) {
        supportMemo.delete(key);
        supportEvidence.delete(key);
      }
    }
    return supportMemo;
  }
  const rows = new Map<string, number>();
  const parsed = readJsonFile<SupportSnapshot>(SUPPORT_FILENAME);
  // Version 1 rows had no credential identity and are deliberately invalidated: accepting them
  // would preserve destination-wide refusals written by a lower-entitlement account.
  if (parsed && parsed.version === 2 && parsed.rows && typeof parsed.rows === "object") {
    for (const [key, row] of Object.entries(parsed.rows)) {
      if (!row || typeof row.at !== "number") continue;
      if (nowMs - row.at > SUPPORT_TTL_MS) continue;
      rows.set(key, row.at);
    }
  }
  supportMemo = rows;
  return rows;
}

/** Snapshot health for ocx status / diagnostics. */
export function reasoningMetadataStatus(): { fetchedAt?: number; ageMs?: number; stale: boolean; models: number } {
  const snapshot = loadSnapshot();
  if (!snapshot) return { stale: false, models: 0 };
  const ageMs = Date.now() - snapshot.fetchedAt;
  let models = 0;
  for (const provider of Object.values(snapshot.providers)) models += Object.keys(provider).length;
  return { fetchedAt: snapshot.fetchedAt, ageMs, stale: ageMs > CACHE_TTL_MS, models };
}

export function reasoningMetadataModel(provider: OcxProviderConfig, modelId: string): ReasoningMetadataModel | undefined {
  const key = metadataProviderKey(provider);
  if (!key) return undefined;
  const models = loadSnapshot()?.providers?.[key];
  if (!models) return undefined;
  const model = models[modelId];
  return model && typeof model === "object" ? model : undefined;
}

/** Raw models.dev effort values for a model, canonicalised; undefined when not published. */
export function metadataEffortValues(provider: OcxProviderConfig, modelId: string): string[] | undefined {
  const model = reasoningMetadataModel(provider, modelId);
  if (!model) return undefined;
  const options = Array.isArray(model.options) ? model.options : [];
  const effort = options.find(option => option && option.type === "effort");
  const ladder = sanitizeLadder(effort?.values);
  // none/minimal are sentinels, not picker rungs (mapReasoningEffort folds minimal to low), and
  // advertising them would trip the Codex runtime clamp for no user-visible gain.
  const rungs = ladder?.filter(value => value !== "none" && value !== "minimal");
  return rungs && rungs.length > 0 ? rungs : undefined;
}

/** True when models.dev publishes the named option type (toggle / budget_tokens) for a model. */
export function metadataDeclaresType(provider: OcxProviderConfig, modelId: string, type: string): boolean {
  const model = reasoningMetadataModel(provider, modelId);
  if (!model) return false;
  const options = Array.isArray(model.options) ? model.options : [];
  return options.some(option => option?.type === type);
}

export function isReasoningEffortLearnedUnsupported(provider: OcxProviderConfig, modelId: string, effort: string): boolean {
  const key = metadataProviderKey(provider);
  const credential = credentialIdentity(provider);
  if (!key || !credential) return false;
  return loadSupport().has(supportKey(key, credential, modelId, effort));
}

/**
 * After the ladder is chosen (registry config or models.dev metadata), remove the rungs this
 * account actually had refused. Applied at the configuredReasoningEfforts() exit so a
 * registry-pinned ladder learns exactly like a metadata-derived one; without it a pinned rung
 * the upstream rejects would replay-and-fail on every request. An all-refused ladder keeps the
 * original list: turning "some rungs" into "no effort control" would silently drop the picker.
 */
export function dropLearnedUnsupportedReasoningEfforts(
  provider: OcxProviderConfig,
  modelId: string,
  efforts: readonly string[],
): string[] {
  if (efforts.length === 0) return [...efforts];
  const key = metadataProviderKey(provider);
  const credential = credentialIdentity(provider);
  if (!key || !credential) return [...efforts];
  const support = loadSupport();
  if (support.size === 0) return [...efforts];
  const kept = efforts.filter(effort => !support.has(supportKey(key, credential, modelId, effort)));
  return kept.length === 0 ? [...efforts] : kept;
}

/**
 * Metadata fallback ladder for a provider/model.
 *
 * - Published effort values win.
 * - A model the provider already classifies as thinking-toggle / thinking-budget keeps the
 *   provider's own effort list; a toggle-only entry never invents wire semantics here.
 * - Rungs the upstream actually refused are removed; a ladder emptied by that learning
 *   returns undefined (status quo) rather than advertising "no effort control".
 */
export function reasoningEffortsFromMetadata(provider: OcxProviderConfig, modelId: string): string[] | undefined {
  const published = metadataEffortValues(provider, modelId);
  let ladder = published;
  if (!ladder) {
    const classified = (provider.thinkingToggleModels ?? []).includes(modelId)
      || (provider.thinkingBudgetModels ?? []).includes(modelId);
    ladder = classified ? CLASSIFIED_STYLE_EFFORTS : undefined;
  }
  if (!ladder || ladder.length === 0) return undefined;
  const kept = ladder.filter(effort => !isReasoningEffortLearnedUnsupported(provider, modelId, effort));
  if (kept.length === 0) return undefined;
  return kept;
}

const supportEvidence = new Map<string, string>();

/**
 * Record that the upstream refused a rung. Persisted (debounced) so the next catalog sync and
 * every later request clamp before dispatch. Returns true when this is new information.
 */
export function recordUnsupportedReasoningEffort(
  provider: OcxProviderConfig,
  modelId: string,
  effort: string,
  evidence?: string,
): boolean {
  const key = metadataProviderKey(provider);
  const credential = credentialIdentity(provider);
  if (!key || !credential || !effort) return false;
  const rowKey = supportKey(key, credential, modelId, effort);
  const rows = loadSupport();
  if (rows.has(rowKey)) return false;
  rows.set(rowKey, Date.now());
  if (evidence) supportEvidence.set(rowKey, evidence.slice(0, 240));
  if (persistTimer) clearTimeout(persistTimer);
  persistTimer = setTimeout(() => {
    persistTimer = null;
    try {
      const out: SupportSnapshot["rows"] = {};
      for (const [rowKey, at] of rows) {
        const evidenceText = supportEvidence.get(rowKey);
        out[rowKey] = {
          effort: JSON.parse(rowKey)[3] ?? "",
          at,
          ...(evidenceText ? { evidence: evidenceText } : {}),
        };
      }
      atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
    } catch {
      // Best-effort persistence only.
    }
  }, PERSIST_DEBOUNCE_MS);
  return true;
}

/** Test seam: flush a pending support write so a script sees the snapshot immediately. */
export function flushReasoningSupportCache(): void {
  if (!persistTimer) return;
  clearTimeout(persistTimer);
  persistTimer = null;
  try {
    const rows = loadSupport();
    const out: SupportSnapshot["rows"] = {};
    for (const [rowKey, at] of rows) {
      const evidenceText = supportEvidence.get(rowKey);
      out[rowKey] = { effort: JSON.parse(rowKey)[3] ?? "", at, ...(evidenceText ? { evidence: evidenceText } : {}) };
    }
    atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
  } catch {
    // Best-effort persistence only.
  }
}

/**
 * Words an upstream uses when it is refusing the parameter it just named. Requiring one of
 * these beside the effort term is what separates "the gateway rejected reasoning effort" from
 * "the gateway rejected something else and echoed the request back".
 */
const REJECTION_LANGUAGE = /unsupported|not supported|does not support|invalid|unrecognized|unknown|not allowed|not permitted|must be|requires|required|cannot|can't|out of range/i;

/**
 * How far from the effort term the rejection language may sit and still be about it. Kept
 * deliberately short: an error body that echoes the request back puts unrelated field names and
 * their complaints within a hundred characters of each other, so a generous window classifies
 * every 400 that mentions effort as a refusal of it.
 */
const REJECTION_WINDOW = 48;

/**
 * The `invalid_request_error` type tag rides along on essentially every 400 an OpenAI-shaped
 * gateway emits, so it is evidence of nothing. Blanked before the language scan rather than
 * dropped from the pattern, because `invalid` is real evidence when it is the message.
 */
const GENERIC_ERROR_TYPE = /invalid_request_error/gi;

/**
 * Evidence test for a rejection body: does it blame reasoning effort?
 *
 * The parameter name on its own is not evidence. A 400 that refuses `max_tokens` may still
 * echo the whole request body back, `reasoning_effort` included, and treating that as a
 * refusal spends this request's one downgrade replay on a rung the upstream never objected to
 * — and persists a false refusal that clamps every later turn for thirty days.
 */
export function isReasoningEffortRejection(text: string | undefined): boolean {
  if (!text) return false;
  if (/unsupported.{0,24}effort/i.test(text)) return true;
  // An upstream that names the offending parameter has already said which one it means.
  if (/["']?param["']?\s*[:=]\s*["']?(?:reasoning[._ ]effort|reasoning)/i.test(text)) return true;
  const scanned = text.replace(GENERIC_ERROR_TYPE, " ");
  const term = /reasoning\.effort|reasoning_effort|reasoning effort|thinking budget|reasoning_parameters/gi;
  for (let match = term.exec(scanned); match; match = term.exec(scanned)) {
    const from = Math.max(0, match.index - REJECTION_WINDOW);
    const to = Math.min(scanned.length, match.index + match[0].length + REJECTION_WINDOW);
    if (REJECTION_LANGUAGE.test(scanned.slice(from, to))) return true;
  }
  return false;
}

/**
 * Plan a single-rung downgrade for a rejected request: records the refusal (so later turns
 * clamp before dispatch) and returns the next lower rung the model does publish.
 */
export function planReasoningEffortDowngrade(args: {
  provider: OcxProviderConfig;
  modelId: string;
  requested?: string;
  rejectionText?: string;
}): { effort: string; recorded: boolean } | undefined {
  const requested = args.requested === "ultra" ? "max" : args.requested;
  if (!requested || !RANKED.includes(requested)) return undefined;
  const recorded = recordUnsupportedReasoningEffort(args.provider, args.modelId, requested, args.rejectionText);
  // Same precedence as configuredReasoningEfforts(): a hand-written ladder is a contract and
  // models.dev is only consulted when nothing was configured for this model. Reading metadata
  // first would have picked the downgrade rung off the published ladder even where a pinned
  // one disagreed, so the replay could land on a rung the registry deliberately excludes.
  const effective = sanitizeLadder(modelLadderValue(args.provider.modelReasoningEfforts, args.modelId))
    ?? sanitizeLadder(args.provider.reasoningEfforts)
    ?? metadataEffortValues(args.provider, args.modelId);
  const ladder = (effective ?? []).filter(effort => RANKED.includes(effort));
  if (ladder.length === 0) return undefined;
  const candidates = ladder
    .filter(effort => RANKED.indexOf(effort) < RANKED.indexOf(requested))
    .filter(effort => !isReasoningEffortLearnedUnsupported(args.provider, args.modelId, effort));
  if (candidates.length === 0) return undefined;
  return { effort: candidates[candidates.length - 1], recorded };
}

/**
 * Refresh the models.dev snapshot. Best-effort and idempotent: never throws, never blocks a
 * request, keeps the previous snapshot on failure. Ladders are stored for the gated destinations
 * only (OpenCode Zen + Zen Go: about 130 models), while every published provider `api` URL is
 * kept so the gate can be checked against real data and widened without another format change.
 * Non-reasoning models carry no ladder and are dropped.
 */
type RefreshOutcome = {
  ok: boolean;
  reason: string;
  providers?: number;
  models?: number;
};

/** Bound a caller's wait without cancelling the shared refresh job. */
function waitForRefresh(work: Promise<RefreshOutcome>, waitMs: number | undefined): Promise<RefreshOutcome> {
  if (waitMs === undefined) return work;
  if (!Number.isSafeInteger(waitMs) || waitMs < 0) {
    return Promise.resolve({ ok: false, reason: "invalid wait budget" });
  }
  let timer: ReturnType<typeof setTimeout> | undefined;
  const deadline = new Promise<RefreshOutcome>(resolve => {
    timer = setTimeout(() => resolve({ ok: false, reason: "wait budget exceeded" }), waitMs);
    timer.unref?.();
  });
  return Promise.race([work, deadline]).finally(() => {
    if (timer) clearTimeout(timer);
  });
}

export async function refreshReasoningMetadata(options: { force?: boolean; waitMs?: number } = {}): Promise<RefreshOutcome> {
  const snapshot = loadSnapshot();
  if (!options.force && snapshot && Date.now() - snapshot.fetchedAt <= CACHE_TTL_MS) {
    return { ok: true, reason: "fresh" };
  }
  if (refreshInFlight) {
    return waitForRefresh(refreshInFlight.then(() => ({ ok: true, reason: "coalesced" })), options.waitMs);
  }
  const job = (async () => {
    const response = await fetch(SOURCE_URL, {
      headers: { "user-agent": USER_AGENT, accept: "application/json" },
      // A hanging connection must not pin refreshInFlight for the life of the process.
      signal: AbortSignal.timeout(15_000),
    });
    if (!response.ok) throw new Error("models.dev HTTP " + response.status);
    const raw = await response.json() as Record<string, { api?: unknown; models?: Record<string, unknown> }>;
    const providers: MetadataSnapshot["providers"] = {};
    const apis: Record<string, string> = {};
    const gated = new Set(Object.values(BASE_URL_TO_METADATA_PROVIDER));
    let models = 0;
    for (const [providerKey, entry] of Object.entries(raw ?? {})) {
      const api = normalizeDestinationUrl(typeof entry?.api === "string" ? entry.api : undefined);
      if (api) apis[providerKey] = api;
      if (!gated.has(providerKey)) continue;
      const out: Record<string, ReasoningMetadataModel> = {};
      for (const [modelId, value] of Object.entries(entry?.models ?? {})) {
        const model = value as { reasoning?: unknown; reasoning_options?: unknown };
        if (model?.reasoning !== true) continue;
        const options: ReasoningMetadataOption[] = [];
        if (Array.isArray(model?.reasoning_options)) {
          for (const option of model.reasoning_options) {
            if (!option || typeof option !== "object") continue;
            const type = (option as { type?: unknown }).type;
            if (typeof type !== "string") continue;
            const values = (option as { values?: unknown }).values;
            options.push({
              type,
              ...(Array.isArray(values)
                ? { values: values.filter((v): v is string => typeof v === "string").slice(0, 12) }
                : {}),
            });
          }
        }
        out[modelId] = { reasoning: model?.reasoning === true, options };
        models += 1;
      }
      if (Object.keys(out).length === 0) continue;
      providers[providerKey] = out;
    }
    const next: MetadataSnapshot = { version: 2, fetchedAt: Date.now(), source: SOURCE_URL, providers, apis };
    atomicWriteFile(join(getConfigDir(), FILENAME), JSON.stringify(next) + "\n");
    snapshotMemo = next;
    return { ok: true, reason: "refreshed", providers: Object.keys(providers).length, models };
  })();
  refreshInFlight = job.catch(() => undefined).finally(() => { refreshInFlight = null; });
  const settled = job.catch((error): RefreshOutcome => ({
    ok: false,
    reason: error instanceof Error ? error.message : String(error),
  }));
  return waitForRefresh(settled, options.waitMs);
}

/**
 * Optional background refresh for callers that do not wait for a snapshot. Catalog sync uses
 * refreshReasoningMetadata with a bounded wait; an expired ladder read can request this refresh.
 * A classified toggle/budget model can have a fallback ladder without any snapshot, so this
 * path must never bootstrap a missing snapshot. One refresh per process; failures are ignored.
 */
export function ensureReasoningMetadataSnapshot(): void {
  const snapshot = loadSnapshot();
  if (!snapshot || Date.now() - snapshot.fetchedAt <= CACHE_TTL_MS) return;
  if (refreshInFlight) return;
  void refreshReasoningMetadata().catch(() => undefined);
}
