@remodex/rmx 1.0.2

package/src/codex/catalog/filesystem-evidence.ts

@@ -0,0 +1,302 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+import { expandUserPath } from "../../config";
+import type {
+  CatalogConditionalSourceObservations,
+  CatalogConditionalSourceRole,
+  CatalogFilesystemIdentity,
+  CatalogHomeSelectionObservation,
+  CatalogRequiredSourceObservations,
+  CatalogRequiredSourceRole,
+  CatalogSourceEvidence,
+  CatalogSourceObservation,
+  CatalogSourceRole,
+} from "../convergence-types";
+import { defaultCodexHome } from "../home";
+
+export type CatalogGatherReadableSourceRole =
+  | "active-catalog-merge"
+  | "hashed-backup-fallback"
+  | "legacy-backup-fallback"
+  | "models-cache-fallback"
+  | "runtime-selection";
+
+/** The minimal observe-only source interface consumed by bundled catalog selection. */
+export interface CatalogGatherEvidenceSession {
+  readSource(role: CatalogGatherReadableSourceRole): Uint8Array | null;
+}
+
+/** The exact observe-only auth input consumed by provider discovery. */
+export interface CatalogGatherProviderAuthEvidence {
+  readonly authStoreBuffer: Uint8Array | null;
+}
+
+export type CatalogFilesystemEvidenceSession = CatalogGatherEvidenceSession
+  & CatalogGatherProviderAuthEvidence;
+
+const CONDITIONAL_SOURCE_ROLES = [
+  "bundled-catalog-template",
+  "active-catalog-merge",
+  "hashed-backup-fallback",
+  "legacy-backup-fallback",
+  "models-cache-fallback",
+  "native-catalog-selection",
+  "runtime-selection",
+  "provider-auth-selection",
+] as const satisfies readonly CatalogConditionalSourceRole[];
+
+interface MutableSessionState {
+  homeSelection: CatalogHomeSelectionObservation | null;
+  readonly sourcePaths: Map<CatalogSourceRole, string>;
+  requiredTargetSelection: CatalogSourceObservation<CatalogRequiredSourceRole> | null;
+  readonly conditional: Record<CatalogConditionalSourceRole, CatalogSourceObservation[]>;
+  sealed: boolean;
+}
+
+const sessionStates = new WeakMap<object, MutableSessionState>();
+
+function filesystemIdentity(
+  entry: Readonly<{ dev: bigint; ino: bigint }>,
+): CatalogFilesystemIdentity {
+  return Object.freeze({ volume: String(entry.dev), fileId: String(entry.ino) });
+}
+
+function sessionState(session: CatalogFilesystemEvidenceSession): MutableSessionState {
+  const state = sessionStates.get(session);
+  if (!state) {
+    throw new TypeError("Catalog filesystem evidence session was not created by its owner.");
+  }
+  return state;
+}
+
+function assertOpen(state: MutableSessionState): void {
+  if (state.sealed) throw new Error("Catalog filesystem evidence session is already sealed.");
+}
+
+function observedHomeSelection(): CatalogHomeSelectionObservation {
+  const environmentSelector = process.env.CODEX_HOME?.trim();
+  const selector = environmentSelector
+    ? { kind: "environment" as const, raw: environmentSelector }
+    : { kind: "default" as const, raw: defaultCodexHome() };
+  const selectedPath = selector.kind === "environment"
+    ? resolve(expandUserPath(selector.raw))
+    : resolve(selector.raw);
+  const canonicalCodexHome = realpathSync.native(selectedPath);
+  const root = statSync(canonicalCodexHome, { bigint: true });
+  if (!root.isDirectory()) {
+    throw new Error(`Codex home is not a directory: ${selectedPath}`);
+  }
+  return Object.freeze({
+    selector: Object.freeze(selector),
+    canonicalCodexHome,
+    rootIdentity: filesystemIdentity(root),
+  });
+}
+
+/** Capture and freeze the selector/root authority before any derived path is admitted. */
+export function captureAndSealCatalogHomeSelection(
+  session: CatalogFilesystemEvidenceSession,
+): CatalogHomeSelectionObservation {
+  const state = sessionState(session);
+  assertOpen(state);
+  if (state.homeSelection) return state.homeSelection;
+  state.homeSelection = observedHomeSelection();
+  return state.homeSelection;
+}
+
+/** Bind the next consultation for a closed role without exposing the evidence arrays. */
+export function acceptCatalogGatherSourcePath(
+  session: CatalogFilesystemEvidenceSession,
+  role: CatalogSourceRole,
+  logicalPath: string,
+): void {
+  const state = sessionState(session);
+  assertOpen(state);
+  if (!state.homeSelection) {
+    throw new Error("Catalog home selection must be sealed before accepting a derived path.");
+  }
+  state.sourcePaths.set(role, resolve(logicalPath));
+}
+
+function isMissing(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function observeSource<R extends CatalogSourceRole>(
+  role: R,
+  logicalPath: string,
+): Readonly<{ bytes: Uint8Array | null; observation: CatalogSourceObservation<R> }> {
+  const canonicalParent = realpathSync.native(dirname(logicalPath));
+  const parent = statSync(canonicalParent, { bigint: true });
+  if (!parent.isDirectory()) {
+    throw new Error(`Catalog source parent is not a directory: ${dirname(logicalPath)}`);
+  }
+  const parentIdentity = Object.freeze({
+    canonicalPath: canonicalParent,
+    ...filesystemIdentity(parent),
+  });
+
+  let bytes: Uint8Array;
+  try {
+    bytes = Uint8Array.from(readFileSync(logicalPath));
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+    return Object.freeze({
+      bytes: null,
+      observation: Object.freeze({
+        state: "absent" as const,
+        role,
+        logicalPath,
+        canonicalPath: resolve(canonicalParent, basename(logicalPath)),
+        parentIdentity,
+        fileIdentity: null,
+      }),
+    });
+  }
+
+  const canonicalPath = realpathSync.native(logicalPath);
+  const file = statSync(canonicalPath, { bigint: true });
+  if (!file.isFile()) throw new Error(`Catalog source is not a regular file: ${logicalPath}`);
+  return Object.freeze({
+    bytes,
+    observation: Object.freeze({
+      state: "present" as const,
+      role,
+      logicalPath,
+      canonicalPath,
+      parentIdentity,
+      fileIdentity: filesystemIdentity(file),
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+    }),
+  });
+}
+
+/** Read once, record PRESENT/ABSENT first, then return the exact hashed buffer. */
+export function readCatalogGatherSource<R extends CatalogSourceRole>(
+  session: CatalogFilesystemEvidenceSession,
+  role: R,
+): Uint8Array | null {
+  const state = sessionState(session);
+  assertOpen(state);
+  const logicalPath = state.sourcePaths.get(role);
+  if (!logicalPath) throw new Error(`No catalog source path was accepted for role ${role}.`);
+  if (role === "catalog-target-selection" && state.requiredTargetSelection) {
+    throw new Error(`Required catalog source role ${role} was already observed.`);
+  }
+
+  const observed = observeSource(role, logicalPath);
+  if (role === "catalog-target-selection") {
+    state.requiredTargetSelection = observed.observation as CatalogSourceObservation<"catalog-target-selection">;
+  } else {
+    state.conditional[role as CatalogConditionalSourceRole].push(observed.observation);
+  }
+  return observed.bytes;
+}
+
+function optionalFileIdentity(path: string): Readonly<{ device: string; inode: string }> | null {
+  try {
+    const entry = statSync(path, { bigint: true });
+    return { device: String(entry.dev), inode: String(entry.ino) };
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+}
+
+/** Probe a candidate write target without allowing filesystem mutation. */
+export function captureCatalogGatherTargetIdentity(
+  session: CatalogFilesystemEvidenceSession,
+  path: string,
+): string {
+  const state = sessionState(session);
+  assertOpen(state);
+  if (!state.homeSelection) {
+    throw new Error("Catalog home selection must be sealed before accepting a derived path.");
+  }
+  const textualPath = resolve(path);
+  const canonicalParent = realpathSync.native(dirname(textualPath));
+  const parent = statSync(canonicalParent, { bigint: true });
+  return JSON.stringify({
+    path: textualPath,
+    canonicalParent,
+    parentIdentity: { device: String(parent.dev), inode: String(parent.ino) },
+    fileIdentity: optionalFileIdentity(textualPath),
+  });
+}
+
+function cloneObservation<R extends CatalogSourceRole>(
+  observation: CatalogSourceObservation<R>,
+): CatalogSourceObservation<R> {
+  if (observation.state === "absent") {
+    return Object.freeze({
+      ...observation,
+      parentIdentity: Object.freeze({ ...observation.parentIdentity }),
+      fileIdentity: null,
+    });
+  }
+  return Object.freeze({
+    ...observation,
+    parentIdentity: Object.freeze({ ...observation.parentIdentity }),
+    fileIdentity: Object.freeze({ ...observation.fileIdentity }),
+  });
+}
+
+/** Seal one complete owner-created session into detached, recursively frozen evidence. */
+export function sealCatalogGatherEvidenceSession(
+  session: CatalogFilesystemEvidenceSession,
+): CatalogSourceEvidence {
+  const state = sessionState(session);
+  assertOpen(state);
+  if (!state.homeSelection) throw new Error("Catalog home selection is required before sealing.");
+  const targetSelection = state.requiredTargetSelection;
+  if (!targetSelection) {
+    throw new Error("Required catalog source role catalog-target-selection was not observed.");
+  }
+  for (const role of CONDITIONAL_SOURCE_ROLES) {
+    if (!Object.hasOwn(state.conditional, role)) {
+      throw new Error(`Conditional catalog source role ${role} is missing.`);
+    }
+  }
+
+  const conditional = Object.fromEntries(CONDITIONAL_SOURCE_ROLES.map(role => [
+    role,
+    Object.freeze(state.conditional[role].map(observation => cloneObservation(observation))),
+  ])) as unknown as CatalogConditionalSourceObservations;
+  const required = Object.freeze({
+    "catalog-target-selection": cloneObservation(targetSelection),
+  }) as CatalogRequiredSourceObservations;
+  const evidence = Object.freeze({
+    homeSelection: Object.freeze({
+      ...state.homeSelection,
+      selector: Object.freeze({ ...state.homeSelection.selector }),
+      rootIdentity: Object.freeze({ ...state.homeSelection.rootIdentity }),
+    }),
+    required,
+    conditional: Object.freeze(conditional),
+  });
+  state.sealed = true;
+  return evidence;
+}
+
+/** Create an opaque session; all mutable evidence state remains module-private. */
+export function createCatalogGatherEvidenceSession(): CatalogFilesystemEvidenceSession {
+  let session: CatalogFilesystemEvidenceSession;
+  session = Object.freeze({
+    readSource: (role: CatalogGatherReadableSourceRole) => readCatalogGatherSource(session, role),
+    get authStoreBuffer(): Uint8Array | null {
+      return readCatalogGatherSource(session, "provider-auth-selection");
+    },
+  });
+  sessionStates.set(session, {
+    homeSelection: null,
+    sourcePaths: new Map(),
+    requiredTargetSelection: null,
+    conditional: Object.fromEntries(
+      CONDITIONAL_SOURCE_ROLES.map(role => [role, [] as CatalogSourceObservation[]]),
+    ) as unknown as MutableSessionState["conditional"],
+    sealed: false,
+  });
+  return session;
+}

package/src/codex/catalog/kinds.ts

@@ -0,0 +1,2 @@
+/** Stable ownership marker for a routed combo that deliberately owns a bare native slug. */
+export const CODEX_NATIVE_ALIAS_CATALOG_KIND = "combo-native-alias-v1";

package/src/codex/catalog/metadata.ts

@@ -0,0 +1,287 @@
+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 { modelSourceVisible } from "../../model-sources";
+import {
+  COMBO_NAMESPACE,
+  comboModelId,
+  getCombo,
+  isNativeAliasCombo,
+  listComboIds,
+  targetKey,
+} from "../../combos";
+import type { NormalizedComboConfig } from "../../combos/types";
+import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import { redactSecretString } from "../../lib/redact";
+import upstreamModelsSnapshot from "../data/upstream-models.json";
+
+
+import type { RawEntry } from "./parsing";
+import { readCurrentCatalogOrCache, unique } from "./bundled";
+import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
+import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+import { NATIVE_OPENAI_MODELS, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+export { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+export { NATIVE_OPENAI_MODELS, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+
+export const DOCUMENTED_NATIVE_OPENAI_ADDITIONS = [
+  "gpt-5.3-codex-spark",
+  "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
+];
+
+export function configuredNativeAliasSlugs(
+  config: Pick<OcxConfig, "combos">,
+): Set<string> {
+  const aliases = new Set<string>();
+  for (const raw of Object.values(config.combos ?? {})) {
+    if (!isNativeAliasCombo(raw)) continue;
+    const alias = raw.alias!.trim();
+    if (SUPPORTED_NATIVE_OPENAI_SLUGS.has(alias)) aliases.add(alias);
+  }
+  return aliases;
+}
+
+/**
+ * Bare native rows that must be absent, rather than merely hidden, while Desktop native-alias
+ * compatibility is active. Codex Desktop's remote allowlist can ignore `visibility: "hide"`;
+ * omitting disabled native rows is therefore part of the explicit native-alias opt-in.
+ */
+export function desktopAllowlistSuppressedNativeSlugs(
+  config: Pick<OcxConfig, "combos" | "disabledModels">,
+): Set<string> {
+  const suppressed = configuredNativeAliasSlugs(config);
+  if (suppressed.size === 0) return suppressed;
+  const disabled = disabledNativeSlugs(config);
+  for (const slug of NATIVE_OPENAI_MODELS) {
+    if (disabled.has(slug)) suppressed.add(slug);
+  }
+  return suppressed;
+}
+
+export function isNativeAliasCatalogEntry(entry: RawEntry): boolean {
+  return entry.opencodex_catalog_kind === CODEX_NATIVE_ALIAS_CATALOG_KIND;
+}
+
+export function isUnsupportedOpenAiNativeSlug(slug: string): boolean {
+  if (slug.includes("/")) return false;
+  if (SUPPORTED_NATIVE_OPENAI_SLUGS.has(slug)) return false;
+  return /^(?:gpt|codex)-/.test(slug);
+}
+
+export const NATIVE_GPT56_CONTEXT_WINDOW = 372_000;
+
+export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number }> = {
+  "gpt-5.5": { contextWindow: 272_000, maxContextWindow: 272_000 },
+  "gpt-5.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },
+  "gpt-5.3-codex-spark": { contextWindow: 100_000, maxContextWindow: 100_000 },
+  "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
+  "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
+  "gpt-5.6-luna": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
+};
+
+/**
+ * Pinned capability metadata is safe to use as a fallback for every supported native model.
+ * Keep it separate from UPSTREAM_NATIVE_ENTRIES: that narrower map also authorizes replacing
+ * persisted native rows during sync, which is currently intentional only for the GPT-5.6 family.
+ */
+const PINNED_NATIVE_CAPABILITY_ENTRIES: Map<string, RawEntry> = new Map(
+  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
+    .filter(m => typeof m.slug === "string"
+      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string))
+    .map(m => [m.slug as string, m]),
+);
+
+export function nativeOpenAiContextWindow(slug: string): number | undefined {
+  return NATIVE_OPENAI_CONTEXT_OVERRIDES[slug]?.contextWindow
+    ?? (typeof PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug)?.context_window === "number"
+      ? PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug)!.context_window as number
+      : undefined);
+}
+
+export function nativeInputModalities(slug: string): string[] {
+  const upstream = PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug);
+  if (Array.isArray(upstream?.input_modalities) && upstream!.input_modalities!.length > 0) {
+    return [...upstream!.input_modalities as string[]];
+  }
+  // gpt-5.3-codex-spark is not in the upstream snapshot; all supported natives are
+  // text+image capable, so default to the family baseline rather than text-only.
+  return ["text", "image"];
+}
+
+export function nativeReasoningEfforts(slug: string): string[] {
+  const upstream = PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug);
+  const levels = Array.isArray(upstream?.supported_reasoning_levels)
+    ? upstream!.supported_reasoning_levels as Array<{ effort?: string }>
+    : [];
+  if (levels.length > 0) {
+    // Preserve the exact pinned per-model ladder. In particular, GPT-5.6 Sol and Terra
+    // include ultra while Luna intentionally ends at max.
+    return levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);
+  }
+  // gpt-5.3-codex-spark is not in upstream snapshot — use the standard old-ladder default.
+  return ["low", "medium", "high", "xhigh"];
+}
+
+/** Upstream-pinned default for a native slug, when present and non-empty. */
+export function nativeDefaultReasoningEffort(slug: string): string | undefined {
+  const level = PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug)?.default_reasoning_level;
+  return typeof level === "string" && level.length > 0 ? level : undefined;
+}
+
+/** Upstream-pinned multi-agent surface for a supported native slug, when present. */
+export function nativeMultiAgentVersion(slug: string): string | undefined {
+  const version = PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug)?.multi_agent_version;
+  return typeof version === "string" && version.length > 0 ? version : undefined;
+}
+
+export function nativeParallelToolCalls(slug: string): boolean {
+  return PINNED_NATIVE_CAPABILITY_ENTRIES.get(slug)?.supports_parallel_tool_calls === true
+    || false;
+}
+
+export function hasComboTargets(config: { combos?: Record<string, { targets?: unknown[] }> }): boolean {
+  const combos = config.combos;
+  if (!combos) return false;
+  return Object.values(combos).some(c => Array.isArray(c?.targets) && c!.targets!.length > 0);
+}
+
+export function disabledNativeSlugs(config: Pick<OcxConfig, "disabledModels">): Set<string> {
+  return new Set((config.disabledModels ?? []).filter(id => !id.includes("/")));
+}
+
+export function visibleNativeSlugs(
+  config: Pick<OcxConfig, "disabledModels" | "combos" | "modelSourceVisibility">,
+): string[] {
+  if (!modelSourceVisible(config, OPENAI_CODEX_PROVIDER_ID)) return [];
+  const disabled = disabledNativeSlugs(config);
+  const shadowed = configuredNativeAliasSlugs(config);
+  return nativeOpenAiSlugs().filter(slug => !disabled.has(slug) && !shadowed.has(slug));
+}
+
+/** Whether an enabled canonical OpenAI provider can serve exact account-qualified routes. */
+export function shouldIncludeAccountBoundNativeOpenAi(
+  config: Pick<OcxConfig, "providers" | "modelSourceVisibility">,
+): boolean {
+  if (!modelSourceVisible(config, OPENAI_CODEX_PROVIDER_ID)) return false;
+  const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (!provider || provider.disabled === true) return false;
+  // Registry routing defaults an omitted authMode on the built-in OpenAI row to forward.
+  const canonical = provider.authMode === undefined
+    ? { ...provider, authMode: "forward" as const }
+    : provider;
+  return isCanonicalOpenAiForwardProvider(canonical);
+}
+
+/** Whether native ChatGPT/Codex rows belong in this provider configuration. */
+export function shouldIncludeNativeOpenAi(
+  config: Pick<OcxConfig, "providers" | "modelSourceVisibility">,
+): boolean {
+  if (!modelSourceVisible(config, OPENAI_CODEX_PROVIDER_ID)) return false;
+  const hasEnabledProvider = Object.values(config.providers)
+    .some(provider => provider.disabled !== true);
+  // Preserve the existing no-enabled-provider catalog bootstrap, but do not use that bootstrap
+  // exception for account-qualified rows: exact-account routing requires a live OpenAI provider.
+  return !hasEnabledProvider || shouldIncludeAccountBoundNativeOpenAi(config);
+}
+
+/** Native slugs exposed to Claude Desktop show/export/apply (opt-out via claudeCode.desktopNativeModels). */
+export function desktopVisibleNativeSlugs(
+  config: Pick<OcxConfig, "claudeCode" | "disabledModels" | "combos" | "modelSourceVisibility">,
+): string[] {
+  if (config.claudeCode?.desktopNativeModels === false) return [];
+  return visibleNativeSlugs(config);
+}
+
+export function nativeModelRows(config: Pick<OcxConfig, "disabledModels" | "combos">): Array<{ slug: string; disabled: boolean; contextWindow?: number }> {
+  const disabled = disabledNativeSlugs(config);
+  const shadowed = configuredNativeAliasSlugs(config);
+  return NATIVE_OPENAI_MODELS.filter(slug => !shadowed.has(slug)).map(slug => {
+    const contextWindow = nativeOpenAiContextWindow(slug);
+    return { slug, disabled: disabled.has(slug), ...(contextWindow !== undefined ? { contextWindow } : {}) };
+  });
+}
+
+export function applyNativeVisibility(
+  entries: RawEntry[],
+  disabledModels: ReadonlySet<string>,
+  hideBareNative = false,
+): RawEntry[] {
+  for (const entry of entries) {
+    if (isNativeAliasCatalogEntry(entry)) continue;
+    const slug = typeof entry.slug === "string" ? entry.slug : "";
+    const accountBoundSlug = trustedAccountBoundNativeCatalogSlug(entry);
+    const nativeSlug = accountBoundSlug ?? slug;
+    if (!nativeSlug
+      || (!accountBoundSlug && slug.includes("/"))
+      || !SUPPORTED_NATIVE_OPENAI_SLUGS.has(nativeSlug)) continue;
+    const disabled = disabledModels.has(nativeSlug)
+      || (accountBoundSlug !== undefined && disabledModels.has(slug));
+    entry.visibility = disabled || (!accountBoundSlug && hideBareNative)
+      ? "hide"
+      : "list";
+  }
+  return entries;
+}
+
+export const UPSTREAM_NATIVE_ENTRIES: Map<string, RawEntry> = new Map(
+  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
+    .filter(m => typeof m.slug === "string"
+      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string)
+      && (m.slug as string).startsWith("gpt-5.6-"))
+    .map(m => [m.slug as string, m]),
+);
+
+export function upstreamNativeEntry(slug: string): RawEntry | null {
+  const entry = UPSTREAM_NATIVE_ENTRIES.get(slug);
+  if (!entry) return null;
+  const clone = JSON.parse(JSON.stringify(entry)) as RawEntry;
+  delete clone.minimal_client_version;
+  return clone;
+}
+
+export function shouldUpgradeToUpstreamEntry(entry: RawEntry): boolean {
+  return typeof entry.slug === "string"
+    && UPSTREAM_NATIVE_ENTRIES.has(entry.slug)
+    && entry.display_name === entry.slug;
+}
+
+export function nativeOpenAiSlugs(): string[] {
+  const live = listCatalogNativeSlugs();
+  return live.length > 0 ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]) : NATIVE_OPENAI_MODELS;
+}
+
+export function listCatalogNativeSlugs(): string[] {
+  const cat = readCurrentCatalogOrCache();
+  const models = cat?.models ?? [];
+  const live = models.flatMap(entry => {
+    const slug = typeof entry.slug === "string" ? entry.slug : "";
+    return !slug.includes("/") && SUPPORTED_NATIVE_OPENAI_SLUGS.has(slug) ? [slug] : [];
+  });
+  const accountBound = models.flatMap(entry => {
+    const slug = trustedAccountBoundNativeCatalogSlug(entry);
+    return slug !== undefined && SUPPORTED_NATIVE_OPENAI_SLUGS.has(slug) ? [slug] : [];
+  });
+  // Deliberately ignore `visibility`: it is a rendered projection of disabledModels and account
+  // selectors, so treating it as fresh availability would shrink the supported set between syncs.
+  // visibleNativeSlugs applies the current disabledModels source of truth for public consumers.
+  // Ensure documented additions (e.g. gpt-5.3-codex-spark) appear even when the bundled catalog
+  // predates the slug — mirrors nativeOpenAiSlugs() which already merges them for /v1/models.
+  return unique([...live, ...accountBound, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]);
+}

package/src/codex/catalog/native-models.ts

@@ -0,0 +1,7 @@
+/** Native OpenAI model ids that this release can route and restore with authoritative metadata. */
+export const NATIVE_OPENAI_MODELS = [
+  "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
+  "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
+];
+
+export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);