import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
import { delimiter, dirname, join, resolve } from "node:path";
import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../../config";
import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "../paths";
import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, isModelsFetchCoolingDown, markModelsFetchFailure, setCached } from "../model-cache";
import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
import type { OcxConfig, OcxProviderConfig } from "../../types";
import { modelInList } from "../../types";
import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
import { getProviderRegistryEntry } from "../../providers/registry";
import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import {
  COMBO_NAMESPACE,
  comboModelId,
  getCombo,
  listComboIds,
  targetKey,
} from "../../combos";
import type { NormalizedComboConfig } from "../../combos/types";
import { providerDestinationResolvedError } from "../../lib/destination-policy";
import { redactSecretString } from "../../lib/redact";
import { isPassiveRead } from "../../lib/passive-read";
import upstreamModelsSnapshot from "../data/upstream-models.json";
import { decodeOverlayState } from "../shim-state-file";


import { activeCodexModelsCachePath, catalogBackupPathFor, ensureStrictCatalogFields, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing";
import { retainedNativeInheritanceTemplate } from "./native-template";
import type { RawCatalog, RawEntry } from "./parsing";
import { isSpawnableCodexCandidate } from "../exec-invocation";
import { validatedCodexExecInvocation, validatedCodexExecInvocationAsync } from "../exec-boundary";
import { macCodexAppCommands } from "../mac-app-bundle";
import { isPlainObject } from "../../lib/plain-data";
import {
  parsePersistedCodexRuntime,
  peekCodexRuntimeProcessCache,
  resolveAndPersistCodexRuntime,
  resolveAndPersistCodexRuntimeAsync,
  codexRuntimeSelectionIdentity,
  codexRuntimeStateEpoch,
  execCodexFileAsync,
  codexRuntimeIsUnresolved,
} from "../runtime";
import type {
  DeepReadonly,
  EffortClampDiagnostic,
  ResolveCodexRuntimeResult,
  ResolvedCodexRuntime,
} from "../runtime";
import type {
  CatalogGatherEvidenceSession,
  CatalogGatherReadableSourceRole,
} from "./filesystem-evidence";

export { isSpawnableCodexCandidate, codexExecInvocation } from "../exec-invocation";
export type {
  CatalogGatherEvidenceSession,
  CatalogGatherReadableSourceRole,
} from "./filesystem-evidence";

export const BUNDLED_CATALOG_CACHE_MS = 60_000;

export type ReadonlyRawCatalog = DeepReadonly<RawCatalog>;

interface BundledCatalogMemo {
  /** Selected runtime identity; must change when doctor/sync picks a different binary. */
  readonly key: string;
  readonly inputs: string;
  readonly expiresAt: number;
  readonly refreshAt: number;
  readonly epoch: number;
  readonly valueIdentity: string;
  readonly value: ReadonlyRawCatalog | null;
}

export interface BundledCatalogCacheState {
  readonly epoch: number;
  readonly valueIdentity: string | null;
}

let bundledCatalogEpoch = 0;
let bundledCatalogCache: BundledCatalogMemo | null = null;
let bundledCatalogRetry: { inputs: string; epoch: number; after: number } | null = null;
let bundledCatalogFlight: { inputs: string; epoch: number; controller: AbortController; promise: Promise<ReadonlyRawCatalog | null> } | null = null;
const catalogAlwaysCurrent = () => true;

function cloneAndDeepFreeze<T>(value: T): DeepReadonly<T> {
  const clone = (current: unknown): unknown => {
    if (Array.isArray(current)) return current.map(clone);
    if (current && typeof current === "object") {
      const out: Record<string, unknown> = {};
      for (const [key, child] of Object.entries(current)) out[key] = clone(child);
      return out;
    }
    return current;
  };
  const freeze = (current: unknown): unknown => {
    if (!current || typeof current !== "object" || Object.isFrozen(current)) return current;
    for (const child of Object.values(current)) freeze(child);
    return Object.freeze(current);
  };
  return freeze(clone(value)) as DeepReadonly<T>;
}

function bundledRuntimeKey(
  runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
  opencodexHome: string = process.env.OPENCODEX_HOME ?? "",
): string {
  return [runtime.command, runtime.version ?? "", opencodexHome].join("\0");
}

function publishBundledCatalogCache(
  key: string,
  expiresAt: number,
  value: RawCatalog | null,
): void {
  const epoch = ++bundledCatalogEpoch;
  bundledCatalogCache = {
    key,
    inputs: codexRuntimeSelectionIdentity({ discoverAlternatives: false }),
    expiresAt,
    refreshAt: Math.min(expiresAt, Date.now() + 15_000),
    epoch,
    valueIdentity: `bundled:${epoch}`,
    value: value === null ? null : cloneAndDeepFreeze(value),
  };
  bundledCatalogRetry = null;
}

function clearBundledCatalogCache(): void {
  bundledCatalogFlight?.controller.abort();
  bundledCatalogEpoch += 1;
  bundledCatalogCache = null;
}

export function bundledCatalogCacheState(): Readonly<BundledCatalogCacheState> {
  return Object.freeze({
    epoch: bundledCatalogEpoch,
    valueIdentity: bundledCatalogCache?.valueIdentity ?? null,
  });
}

/** Test-only: clear the bundled-catalog cache (owned here; sync.ts calls this instead of assigning the import). */
export function resetBundledCatalogCacheForTests(): void {
  clearBundledCatalogCache();
}

/** Drop the process-local bundled catalog memo (e.g. after runtime selection changes). */
export function invalidateBundledCatalogCache(): void {
  clearBundledCatalogCache();
}

/** Test-only owner mutation seam; input is cloned and frozen before publication. */
export function setBundledCatalogCacheForTests(
  runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
  value: RawCatalog | null,
  options: Readonly<{ expiresAt?: number; opencodexHome?: string }> = {},
): void {
  publishBundledCatalogCache(
    bundledRuntimeKey(runtime, options.opencodexHome),
    options.expiresAt ?? Date.now() + BUNDLED_CATALOG_CACHE_MS,
    value,
  );
}

export type ExecFile = (
  file: string,
  args: string[],
  options: {
    encoding: "utf8";
    stdio: ["ignore", "pipe", "ignore"];
    timeout: number;
    windowsHide: boolean;
    shell?: boolean;
    windowsVerbatimArguments?: boolean;
    signal?: AbortSignal;
    maxBuffer?: number;
  },
) => string;

export interface BundledCatalogDeps {
  /** Already-observed source for server clamping; null never triggers a probe. */
  observedCatalog?: ReadonlyRawCatalog | null;
  commandCandidates?: () => string[];
  /**
   * The resolver selection `commandCandidates` came from, when the caller resolved first. Only an
   * unresolved selection lets the macOS probe add the ChatGPT.app CLI (#8360); without it, injected
   * candidates are probed as given.
   */
  selectedRuntime?: Pick<ResolvedCodexRuntime, "source" | "version">;
  execFileSync?: ExecFile;
  execFile?: (...args: Parameters<ExecFile>) => Promise<string>;
  onEffortClamp?: (diagnostic: EffortClampDiagnostic) => void;
  configDir?: string;
  env?: NodeJS.ProcessEnv;
  platform?: NodeJS.Platform;
  existsSync?: (path: string) => boolean;
  readFileSync?: (path: string, encoding: "utf8") => string;
  /** Exec-boundary bundle trust for sync drivers (resolve + debug exec). */
  macBundleTrustReason?: (bundleRoot: string, binary: string) => string | null;
  /** Exec-boundary bundle trust for async drivers; injected checks bypass the runtime memo. */
  macBundleTrustReasonAsync?: (bundleRoot: string, binary: string, signal?: AbortSignal) => Promise<string | null>;
  /** Exec-boundary spawnability predicate (regular file + X_OK). */
  executable?: (path: string) => boolean;
  /** Exec-boundary canonicalizer; returns null when the path cannot be resolved. */
  realpath?: (path: string) => string | null;
  now?: () => number;
  discoverAlternatives?: boolean;
}

export function unique(values: string[]): string[] {
  return [...new Set(values.filter(Boolean))];
}

export function codexCommandCandidates(): string[] {
  const envPath = process.env.CODEX_CLI_PATH?.trim();
  const candidates = envPath ? [envPath] : [];
  candidates.push(...codexShimCommandCandidates());
  if (process.platform === "win32") {
    for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
      candidates.push(join(dir, "codex.exe"), join(dir, "codex.cmd"));
    }
  }
  candidates.push("codex");
  return unique(candidates);
}

export function codexShimCommandCandidates(): string[] {
  try {
    const configDir = getConfigDir();
    const state = JSON.parse(readFileSync(join(configDir, "codex-shim.json"), "utf8")) as {
      schema?: unknown;
      mode?: unknown;
      wrapperPath?: unknown;
      originalPath?: unknown;
      backupPath?: unknown;
      wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
    };
    const overlay = decodeOverlayState(state, configDir);
    if ((state.schema !== undefined || state.mode !== undefined) && !overlay) return [];
    const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
    const out: string[] = overlay && isSpawnableCodexCandidate(overlay.launcherPath)
      ? [overlay.launcherPath] : [];
    for (const file of files) {
      for (const value of [file.backupPath, file.originalPath, file.wrapperPath]) {
        if (typeof value !== "string" || value.length === 0) continue;
        if (!isSpawnableCodexCandidate(value)) continue;
        out.push(value);
      }
    }
    return out;
  } catch {
    return [];
  }
}

export function runCodexDebugModels<T>(
  command: string,
  execFile: (...args: Parameters<ExecFile>) => T,
  deps: Pick<BundledCatalogDeps, "env" | "platform" | "existsSync" | "executable" | "realpath" | "macBundleTrustReason"> = {},
): T {
  const args = ["debug", "models", "--bundled"];
  const invocation = validatedCodexExecInvocation(command, args, {
    env: deps.env,
    platform: deps.platform,
    exists: deps.existsSync,
    executable: deps.executable,
    realpath: deps.realpath,
    macBundleTrustReason: deps.macBundleTrustReason,
  });
  return execFile(invocation.file, invocation.args, {
    encoding: "utf8" as const,
    stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
    timeout: 10_000,
    maxBuffer: 64 * 1024 * 1024,
    windowsHide: true,
    ...invocation.options,
  });
}

/** Async twin of runCodexDebugModels: same args/options, bundle trust checked off the event loop. */
export async function runCodexDebugModelsAsync<T>(
  command: string,
  execFile: (...args: Parameters<ExecFile>) => Promise<T>,
  deps: Pick<BundledCatalogDeps, "env" | "platform" | "existsSync" | "executable" | "realpath" | "macBundleTrustReasonAsync"> = {},
  signal?: AbortSignal,
): Promise<T> {
  const args = ["debug", "models", "--bundled"];
  const invocation = await validatedCodexExecInvocationAsync(command, args, {
    env: deps.env,
    platform: deps.platform,
    exists: deps.existsSync,
    executable: deps.executable,
    realpath: deps.realpath,
    macBundleTrustReasonAsync: deps.macBundleTrustReasonAsync,
    signal,
  });
  return execFile(invocation.file, invocation.args, {
    encoding: "utf8" as const,
    stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
    timeout: 10_000,
    maxBuffer: 64 * 1024 * 1024,
    windowsHide: true,
    ...invocation.options,
  });
}

function bundledRuntimeDeps(deps: BundledCatalogDeps) {
  return {
      // Forward an INJECTED execFileSync only. Passing the real one unconditionally made
      // resolveCacheKey() bail out (it refuses to memoize injected-dep resolves), so every
      // catalog read re-ran the ~1s `codex --version` probe even on a warm cache hit.
      ...(deps.execFileSync ? { execFileSync: deps.execFileSync } : {}),
      ...(deps.execFile ? { execFile: deps.execFile } : {}),
      configDir: deps.configDir,
      env: deps.env,
      platform: deps.platform,
      existsSync: deps.existsSync,
      readFileSync: deps.readFileSync,
      // Exec-boundary trust deps forwarded so the runtime's own --version probes
      // use the same injected checks as the catalog exec below.
      ...(deps.macBundleTrustReason ? { macBundleTrustReason: deps.macBundleTrustReason } : {}),
      ...(deps.macBundleTrustReasonAsync ? { macBundleTrustReasonAsync: deps.macBundleTrustReasonAsync } : {}),
      ...(deps.executable ? { executable: deps.executable } : {}),
      ...(deps.realpath ? { realpath: deps.realpath } : {}),
      now: deps.now,
      // Catalog loading only consumes `resolved.runtime.command`, never `newerAvailable`.
      // Full PATH discovery probes every candidate launcher (100+ on a dev machine, ~1.2s),
      // which alone can exceed the 3s budget `ocx claude` allows /api/claude-code. Priority
      // selection is identical either way; callers wanting discovery diagnostics opt in.
      discoverAlternatives: deps.discoverAlternatives ?? false,
  };
}

/**
 * Candidates for the bundled-catalog probe.
 *
 * When discovery finds no Codex CLI it answers with the bare `codex` sentinel, so the probe
 * asks a command that does not exist while a real CLI sits inside ChatGPT.app. Discovery only
 * offers that app candidate after classifying the bundle's XML `Info.plist` identity, so a
 * bundle it cannot classify (a binary plist, or an identity assertion that moved with an app
 * update) left `ocx connect status` reporting `unverified` on a macOS Child whose only Codex
 * was the bundled CLI (#8360).
 *
 * The known app locations are therefore added after a bare sentinel. This list grants no
 * trust: every execution still passes the app-bundle signature and ownership gate in
 * `exec-boundary.ts`, so an unverifiable bundle yields `null` rather than an invented ladder.
 * Windows needs no entry here because its Codex App install root under LOCALAPPDATA is already
 * enumerated by `installedCodexCandidates` in `runtime.ts`.
 */
function bundledCatalogCandidates(
  deps: BundledCatalogDeps,
  resolved: ResolveCodexRuntimeResult | null,
): string[] {
  const candidates = deps.commandCandidates?.() ?? [resolved!.runtime.command];
  // An explicit empty list asks for no probe at all.
  if (candidates.length === 0) return candidates;
  if ((deps.platform ?? process.platform) !== "darwin") return candidates;
  // Decide from the resolver's own result, not from the command's shape: a bare command that ran
  // (a PATH fallback or a bare CODEX_CLI_PATH) is the operator's runtime, and borrowing the app's
  // catalog for it would report a ladder that runtime may reject.
  const selection = resolved?.runtime ?? deps.selectedRuntime;
  if (!selection || !codexRuntimeIsUnresolved(selection)) return candidates;
  const exists = deps.existsSync ?? existsSync;
  return [...candidates, ...macCodexAppCommands(deps).filter(command => exists(command))];
}

function* bundledCatalogSteps(
  candidates: string[],
  cacheKey: string | null,
  current: () => boolean = () => true,
  publishFailure = true,
): Generator<string, ReadonlyRawCatalog | null, string | null> {
  if (cacheKey && bundledCatalogCache?.key === cacheKey && current()) {
    // The driver validated this same command/version under the new pin/env inputs.
    // Re-stamp the memo even if its TTL is due, so failed refresh keeps confirmed rows.
    bundledCatalogCache = { ...bundledCatalogCache,
      inputs: codexRuntimeSelectionIdentity({ discoverAlternatives: false }) };
  }
  if (
    cacheKey
    && bundledCatalogCache
    && bundledCatalogCache.key === cacheKey
    && bundledCatalogCache.inputs === codexRuntimeSelectionIdentity({ discoverAlternatives: false })
    && bundledCatalogCache.expiresAt > Date.now()
  ) {
    if (!current()) return null;
    bundledCatalogCache = { ...bundledCatalogCache, refreshAt: Date.now() + 15_000 };
    return bundledCatalogCache.value === null
      ? null
      : cloneAndDeepFreeze(bundledCatalogCache.value);
  }
  for (const command of unique(candidates)) {
      if (!current()) return null;
      const output = yield command;
      if (!current()) return null;
      const catalog = output === null ? null : parseCatalogJson(output);
      if (catalog && catalog.models?.every(row => row !== null && typeof row === "object" && !Array.isArray(row))
        && findNativeTemplate(catalog)) {
        if (cacheKey) {
          publishBundledCatalogCache(
            cacheKey,
            Date.now() + BUNDLED_CATALOG_CACHE_MS,
            catalog,
          );
          return cloneAndDeepFreeze(bundledCatalogCache!.value!);
        }
        return cloneAndDeepFreeze(catalog);
      }
  }
  if (cacheKey && (publishFailure || bundledCatalogCache?.key !== cacheKey || !bundledCatalogCache?.value) && current()) {
    publishBundledCatalogCache(
      cacheKey,
      Date.now() + BUNDLED_CATALOG_CACHE_MS,
      null,
    );
  }
  return null;
}

/** Explicit synchronous CLI driver; request readers use the snapshot below. */
export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): ReadonlyRawCatalog | null {
  const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.execFile && !deps.configDir && !deps.env;
  const resolved = deps.commandCandidates ? null : resolveAndPersistCodexRuntime(bundledRuntimeDeps(deps));
  const inputs = codexRuntimeSelectionIdentity(bundledRuntimeDeps(deps));
  const steps = bundledCatalogSteps(bundledCatalogCandidates(deps, resolved),
    useCache ? bundledRuntimeKey(resolved!.runtime) : null,
    () => inputs === codexRuntimeSelectionIdentity(bundledRuntimeDeps(deps)));
  let step = steps.next();
  while (!step.done) {
    let output: string | null = null;
    try { output = runCodexDebugModels(step.value, deps.execFileSync ?? (execFileSync as unknown as ExecFile), deps); }
    catch { /* try next candidate */ }
    step = steps.next(output);
  }
  return step.value;
}

/** Same candidate/parser authority, with version and bundled-model execs off the event loop. */
export function loadBundledCodexCatalogAsync(
  deps: BundledCatalogDeps = {},
  isCurrent: () => boolean = catalogAlwaysCurrent,
  signal?: AbortSignal,
): Promise<ReadonlyRawCatalog | null> {
  if (signal?.aborted || !isCurrent()) return Promise.resolve(null);
  const view = (promise: Promise<ReadonlyRawCatalog | null>) => {
    if (!signal) return promise.then(value => isCurrent() ? value : null);
    let abort: (() => void) | undefined;
    return Promise.race([promise, new Promise<null>(resolve => {
      abort = () => resolve(null);
      signal.addEventListener("abort", abort, { once: true });
      if (signal.aborted) abort();
    })]).then(value => isCurrent() && !signal.aborted ? value : null)
      .finally(() => { if (abort) signal.removeEventListener("abort", abort); });
  };
  const runtimeDeps = bundledRuntimeDeps(deps);
  const inputs = codexRuntimeSelectionIdentity(runtimeDeps);
  const epoch = bundledCatalogEpoch;
  const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.execFile && !deps.configDir && !deps.env;
  if (useCache && bundledCatalogFlight?.inputs === inputs && bundledCatalogFlight.epoch === epoch) {
    return view(bundledCatalogFlight.promise);
  }
  // A passive read (a Remote Link Child's, #6959) runs no Codex binary and persists no runtime.
  if (isPassiveRead()) return Promise.resolve(null);
  const controller = new AbortController();
  const flight = { inputs, epoch, controller, promise: Promise.resolve<ReadonlyRawCatalog | null>(null) };
  if (useCache && !signal && isCurrent === catalogAlwaysCurrent) {
    bundledCatalogFlight?.controller.abort();
    bundledCatalogFlight = flight;
  }
  const abort = () => controller.abort();
  signal?.addEventListener("abort", abort, { once: true });
  if (signal?.aborted) abort();
  let timer: ReturnType<typeof setTimeout> | undefined;
  let deadlineReached = false;
  const work = (async () => {
    const active = () => !controller.signal.aborted && isCurrent() && bundledCatalogEpoch === epoch;
    const resolved = deps.commandCandidates ? null : await resolveAndPersistCodexRuntimeAsync({ ...runtimeDeps, signal: controller.signal },
      () => active() && codexRuntimeSelectionIdentity(runtimeDeps) === inputs);
    if (!active() || (!deps.commandCandidates && !resolved)) return null;
    flight.inputs = codexRuntimeSelectionIdentity(runtimeDeps);
    const runtimeEpoch = codexRuntimeStateEpoch();
    const current = () => active() && runtimeEpoch === codexRuntimeStateEpoch()
      && flight.inputs === codexRuntimeSelectionIdentity(runtimeDeps);
    const steps = bundledCatalogSteps(bundledCatalogCandidates(deps, resolved),
      useCache ? bundledRuntimeKey(resolved!.runtime) : null, current, false);
    let step = steps.next();
    while (!step.done) {
      let output: string | null = null;
      try { output = await runCodexDebugModelsAsync(step.value,
        (file, args, options) => (deps.execFile ?? execCodexFileAsync)(file, args, { ...options, signal: controller.signal }),
        deps, controller.signal); }
      catch { /* preserve last confirmed evidence on failure */ }
      step = steps.next(output);
    }
    return step.value;
  })().catch(() => null);
  flight.promise = Promise.race([work, new Promise<null>(resolve => {
    timer = setTimeout(() => { deadlineReached = true; controller.abort(); resolve(null); }, 45_000);
    timer.unref?.();
  })]).then(value => {
    if (useCache && value === null && (!controller.signal.aborted || deadlineReached)
      && isCurrent() && bundledCatalogEpoch === epoch
      && flight.inputs === codexRuntimeSelectionIdentity(runtimeDeps)) {
      bundledCatalogRetry = { inputs: flight.inputs, epoch, after: Date.now() + BUNDLED_CATALOG_CACHE_MS };
    }
    return value;
  }).finally(() => {
    clearTimeout(timer);
    signal?.removeEventListener("abort", abort);
    controller.abort();
    if (bundledCatalogFlight === flight) bundledCatalogFlight = null;
  });
  return view(flight.promise);
}

/** Serve only the same selection's last confirmed catalog; refresh never holds a request. */
export function bundledCodexCatalogSnapshot(): ReadonlyRawCatalog | null {
  const inputs = codexRuntimeSelectionIdentity({ discoverAlternatives: false });
  const memo = bundledCatalogCache?.inputs === inputs ? bundledCatalogCache : null;
  const cooling = bundledCatalogRetry?.inputs === inputs && bundledCatalogRetry.epoch === bundledCatalogEpoch
    && bundledCatalogRetry.after > Date.now();
  if ((!memo || memo.refreshAt <= Date.now()) && !cooling) void loadBundledCodexCatalogAsync().catch(() => { /* bounded retry */ });
  return memo?.value ? cloneAndDeepFreeze(memo.value) : null;
}

export type CatalogGatherProcessLocalObservation =
  | Readonly<{ state: "unused" }>
  | Readonly<{ state: "used"; epoch: number; valueIdentity: string }>;

export type CodexRuntimeForCatalogGather =
  | Readonly<{
      kind: "available";
      origin: "process-cache" | "persisted";
      runtime: DeepReadonly<ResolvedCodexRuntime>;
      processLocal: CatalogGatherProcessLocalObservation;
    }>
  | Readonly<{
      kind: "runtime-unavailable";
      processLocal: Readonly<{ state: "unused" }>;
    }>;

export type CatalogSourceForGather =
  | Readonly<{
      kind: "available";
      source:
        | "bundled-catalog-template"
        | "active-catalog-merge"
        | "hashed-backup-fallback"
        | "legacy-backup-fallback"
        | "models-cache-fallback";
      catalog: ReadonlyRawCatalog;
      runtimeSupport:
        | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }>
        | Readonly<{ kind: "unavailable" }>;
      processLocal: Readonly<{
        runtime: CatalogGatherProcessLocalObservation;
        bundledCatalog: CatalogGatherProcessLocalObservation;
      }>;
    }>
  | Readonly<{
      kind: "catalog-unavailable";
      processLocal: Readonly<{
        runtime: Readonly<{ state: "unused" }>;
        bundledCatalog: Readonly<{ state: "unused" }>;
      }>;
    }>;

export type CatalogGatherPathKind = "default" | "custom";

const UNUSED_PROCESS_LOCAL = Object.freeze({ state: "unused" as const });

function sameRuntimeIdentity(
  left: Pick<ResolvedCodexRuntime, "command" | "version">,
  right: Pick<ResolvedCodexRuntime, "command" | "version">,
): boolean {
  return left.command === right.command && (left.version ?? null) === (right.version ?? null);
}

/**
 * Observe an already-resolved runtime only. The evidence owner supplies the
 * exact persisted bytes (or observed absence); this path never probes or writes.
 */
export function peekCodexRuntimeForCatalogGather(
  evidenceSession: CatalogGatherEvidenceSession,
): CodexRuntimeForCatalogGather {
  const persistedBytes = evidenceSession.readSource("runtime-selection");
  const persisted = persistedBytes === null
    ? null
    : parsePersistedCodexRuntime(persistedBytes);
  const processMemo = peekCodexRuntimeProcessCache();

  if (processMemo.kind === "available") {
    const runtime = processMemo.value.runtime;
    if (persistedBytes === null || (persisted && sameRuntimeIdentity(runtime, {
      command: persisted.command,
      version: persisted.selectedVersion ?? null,
    }))) {
      return cloneAndDeepFreeze({
        kind: "available" as const,
        origin: "process-cache" as const,
        runtime,
        processLocal: {
          state: "used" as const,
          epoch: processMemo.epoch,
          valueIdentity: processMemo.valueIdentity,
        },
      });
    }
  }

  if (persisted) {
    return cloneAndDeepFreeze({
      kind: "available" as const,
      origin: "persisted" as const,
      runtime: {
        command: persisted.command,
        version: persisted.selectedVersion ?? null,
        source: persisted.source,
      },
      processLocal: UNUSED_PROCESS_LOCAL,
    });
  }

  return Object.freeze({
    kind: "runtime-unavailable" as const,
    processLocal: UNUSED_PROCESS_LOCAL,
  });
}

/**
 * Resolve only already-observed catalog sources. A cold process cache falls
 * through to evidence-owned persisted sources and never becomes probe authority.
 */
export function resolveCatalogSourceForGather(
  evidenceSession: CatalogGatherEvidenceSession,
  pathKind: CatalogGatherPathKind,
): CatalogSourceForGather {
  const bundledMemo = bundledCatalogCache;
  let runtimeSupport:
    | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }>
    | Readonly<{ kind: "unavailable" }> = Object.freeze({ kind: "unavailable" });
  let processLocal: Readonly<{
    runtime: CatalogGatherProcessLocalObservation;
    bundledCatalog: CatalogGatherProcessLocalObservation;
  }> = {
    runtime: UNUSED_PROCESS_LOCAL,
    bundledCatalog: UNUSED_PROCESS_LOCAL,
  };
  if (bundledMemo?.value && bundledMemo.expiresAt > Date.now()) {
    const runtime = peekCodexRuntimeForCatalogGather(evidenceSession);
    if (runtime.kind === "available" && bundledMemo.key === bundledRuntimeKey(runtime.runtime)) {
      runtimeSupport = Object.freeze({
        kind: "available" as const,
        catalog: bundledMemo.value,
      });
      processLocal = {
        runtime: runtime.processLocal,
        bundledCatalog: {
          state: "used" as const,
          epoch: bundledMemo.epoch,
          valueIdentity: bundledMemo.valueIdentity,
        },
      };
      if (pathKind === "default") {
        return cloneAndDeepFreeze({
          kind: "available" as const,
          source: "bundled-catalog-template" as const,
          catalog: bundledMemo.value,
          runtimeSupport,
          processLocal,
        });
      }
    }
  }

  const roles = pathKind === "default"
    ? [
        "active-catalog-merge",
        "hashed-backup-fallback",
        "legacy-backup-fallback",
        "models-cache-fallback",
      ] as const
    : [
        "active-catalog-merge",
        "hashed-backup-fallback",
        "models-cache-fallback",
      ] as const;
  for (const role of roles) {
    const bytes = evidenceSession.readSource(role);
    if (bytes === null) continue;
    const catalog = parseCatalogJson(Buffer.from(bytes).toString("utf8"));
    if (!catalog) continue;
    // Custom catalogs may intentionally contain only routed rows. Keep their existing source
    // priority (active, then backup/cache) without imposing the default catalog's native-template
    // requirement; a valid active custom file therefore remains authoritative over stale fallbacks.
    if (pathKind === "default" && !findNativeTemplate(catalog)) continue;
    return cloneAndDeepFreeze({
      kind: "available" as const,
      source: role,
      catalog,
      runtimeSupport,
      processLocal,
    });
  }

  return Object.freeze({
    kind: "catalog-unavailable" as const,
    processLocal: Object.freeze({
      runtime: UNUSED_PROCESS_LOCAL,
      bundledCatalog: UNUSED_PROCESS_LOCAL,
    }),
  });
}

export function materializeBundledCodexCatalog(path: string, deps: BundledCatalogDeps = {}): RawCatalog | null {
  const catalog = loadBundledCodexCatalog(deps);
  if (!catalog) return null;
  try {
    mkdirSync(dirname(path), { recursive: true });
    atomicWriteFile(path, JSON.stringify(catalog, null, 2) + "\n");
  } catch {
    return null;
  }
  return JSON.parse(JSON.stringify(catalog)) as RawCatalog;
}

export function loadCatalogForSync(path: string): RawCatalog | null {
  const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
  const catalog = readCatalog(path);
  if (catalog && findNativeTemplate(catalog)) return catalog;
  return readCatalog(catalogBackupPathFor(path))
    ?? (isDefaultCatalogPath(path) ? readCatalog(legacyCatalogBackupPath()) : null)
    ?? readCatalog(activeCodexModelsCachePath())
    ?? materializeBundledCodexCatalog(path)
    ?? catalog;
}

export function readCurrentCatalogOrCache(): RawCatalog | null {
  const path = readCodexCatalogPath();
  const bundled = isDefaultCatalogPath(path) ? bundledCodexCatalogSnapshot() : null;
  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
  return readCatalog(path) ?? readCatalog(activeCodexModelsCachePath());
}

/**
 * Read the user-owned Codex catalog surfaces without substituting the bundled catalog.
 *
 * The bundled catalog is intentionally the authority for static native metadata on the default
 * path. Account-qualified discovery needs the opposite view: an exact model id that Codex has
 * observed in the user's catalog/cache may be account-scoped even when this release does not know
 * it statically yet.
 */
export function readCurrentCodexCatalog(): RawCatalog | null {
  return readCatalog(readCodexCatalogPath());
}

export function readCurrentCodexModelsCache(): RawCatalog | null {
  return readCatalog(activeCodexModelsCachePath());
}

export function loadCatalogTemplate(): RawEntry | null {
  const catalogPath = readCodexCatalogPath();
  const bundled = bundledCodexCatalogSnapshot();
  const fromRows = (catalog: RawCatalog | null) => {
    const template = findSupportedNativeTemplate(catalog
      ? { ...catalog, models: (catalog.models ?? []).filter(isPlainObject) } : null);
    // An emitted native has already passed strict normalization. Match that read surface,
    // including property insertion order, when the native survives only as source evidence.
    return template && template === retainedNativeInheritanceTemplate(catalog)
      ? ensureStrictCatalogFields(structuredClone(template)) : template;
  };
  // Template inheritance only. The validity gates in this file keep `findNativeTemplate`
  // so a catalog carrying only a newly launched native row stays valid (#2813).
  const native = fromRows(readCatalog(catalogPath))
    ?? fromRows(readCatalogBackup(catalogPath))
    ?? fromRows(readCatalog(activeCodexModelsCachePath()))
    ?? fromRows(bundled ? JSON.parse(JSON.stringify(bundled)) as RawCatalog : null);
  return native ? JSON.parse(JSON.stringify(native)) : null;
}
