@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/catalog/effort.ts

@@ -9,10 +9,11 @@ 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 { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJawcodeModelMetadata, resolveJawcodeProvider } from "../../generated/jawcode-model-metadata";
+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 { applyProviderContextCap, providerContextCap, resolveUnknownRoutedContextWindow } from "../../providers/context-cap";
+import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
@@ -31,11 +32,12 @@ import { redactSecretString, redactUserPath } from "../../lib/redact";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 
-import { readCatalog, readCodexCatalogPath } from "./parsing";
+import { generatedModelMetadata, readCatalog, readCodexCatalogPath } from "./parsing";
 import type { CatalogModel, RawEntry } from "./parsing";
 import { UPSTREAM_NATIVE_ENTRIES } from "./metadata";
+import { nativeOpenAiCapabilitySourceSlug } from "./native-models";
 import { loadBundledCodexCatalog } from "./bundled";
-import type { BundledCatalogDeps } from "./bundled";
+import type { BundledCatalogDeps, ReadonlyRawCatalog } from "./bundled";
 import { deriveEntry } from "./sync";
 import {
   formatClampLogLines,
@@ -116,18 +118,34 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
   if (model.provider === COMBO_NAMESPACE) entry.owned_by = model.owned_by ?? COMBO_NAMESPACE;
   // displayName is DISPLAY-ONLY: it relabels the picker row but never touches the routing
   // slug, alias, or provider. deriveEntry already stamped the slug as display_name; a
-  // configured displayName overrides just the label. The `/` separator is rejected at every
-  // input boundary (CLI `ocx models add`, management API), so the catalog trusts its source.
-  // Combos carry no displayName, and natives never reach here (no CatalogModel), so genuine
-  // upstream marketing names and combo alias labels are preserved untouched.
+  // configured displayName overrides just the label. Custom-model inputs reject `/`; combos
+  // validate their bounded display label independently. Natives never reach here (no CatalogModel),
+  // so genuine upstream marketing names are preserved untouched.
   const displayName = typeof model.displayName === "string" ? model.displayName.trim() : "";
   if (displayName) entry.display_name = displayName;
-  if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
-    entry.context_window = model.contextWindow;
-    entry.max_context_window = model.contextWindow;
-    entry.auto_compact_token_limit = Math.min(
-      Math.floor(model.contextWindow * 0.9),
-      model.maxInputTokens ?? Number.POSITIVE_INFINITY,
+  const resolvedContext = typeof model.contextWindow === "number" && model.contextWindow > 0
+    ? model.contextWindow
+    : (model.contextCap !== undefined ? resolveUnknownRoutedContextWindow(model.contextCap) : undefined);
+  if (typeof resolvedContext === "number" && resolvedContext > 0) {
+    entry.context_window = resolvedContext;
+    entry.max_context_window = resolvedContext;
+    entry.auto_compact_token_limit = clampAutoCompactTokenLimit(
+      resolvedContext,
+      model.maxInputTokens,
+      model.autoCompactTokenLimit,
+    );
+  } else if (
+    typeof entry.context_window === "number"
+    && entry.context_window > 0
+    && typeof model.maxInputTokens === "number"
+    && model.maxInputTokens > 0
+  ) {
+    // A conservative routed fallback is not evidence for applying the optional soft policy,
+    // but a measured/configured input ceiling is still a hard bound. Compact before that
+    // ceiling even when the provider supplied no authoritative context window.
+    entry.auto_compact_token_limit = clampAutoCompactTokenLimit(
+      entry.context_window,
+      model.maxInputTokens,
     );
   }
   if (Array.isArray(model.inputModalities) && model.inputModalities.length > 0) {
@@ -139,6 +157,63 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
   if (typeof model.supportsReasoningSummaries === "boolean") {
     entry.supports_reasoning_summaries = model.supportsReasoningSummaries;
   }
+  if (model.supportsServiceTier === true) {
+    entry.default_service_tier = null;
+    entry.service_tiers = [{
+      id: "priority",
+      name: "Fast",
+      description: model.fastTierDescription ?? "1.5x speed, increased usage",
+    }];
+    entry.additional_speed_tiers = ["fast"];
+  }
+  stampCapabilityProvenance(entry, model);
+}
+
+/**
+ * Record which capability values a real source actually asserted (#1796).
+ *
+ * `ensureStrictCatalogFields` fills `context_window` and `input_modalities` with
+ * compatibility defaults so Codex's strict parser accepts the file, which means
+ * an entry ALWAYS carries both and their presence proves nothing. Routing has to
+ * tell "the provider said text-only" apart from "nobody said anything", so it
+ * reads this block and never the entry itself ("unknown is not zero",
+ * src/routing/capability.ts).
+ *
+ * Two real sources exist and both are consulted here, in the same precedence the
+ * writers use (`applyCatalogMetadata` runs first, the model's own fields
+ * overwrite it): the `CatalogModel` and the generated jawcode metadata table.
+ * Reading only the model would silently drop every provider whose capabilities
+ * live in that table.
+ */
+function stampCapabilityProvenance(entry: RawEntry, model: CatalogModel): void {
+  // Virtual combo rows are synthesized from last-resort defaults (a generic 128k
+  // context and a `["text"]` modality), so their values are placeholders rather
+  // than assertions. Stamping them would reintroduce the exact false-evidence
+  // defect this block exists to prevent.
+  if (model.provider === COMBO_NAMESPACE) return;
+
+  const meta = generatedModelMetadata(model.provider, model.id);
+  const metaContext = typeof meta?.contextWindow === "number" && meta.contextWindow > 0
+    // The generated context is capped before it reaches the entry, so provenance
+    // must apply the same cap or routing would advertise a window the cap refused.
+    ? applyProviderContextCap(meta.contextWindow, model.contextCap) ?? meta.contextWindow
+    : undefined;
+  const contextWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
+    ? model.contextWindow
+    : metaContext;
+  const inputModalities = Array.isArray(model.inputModalities) && model.inputModalities.length > 0
+    ? model.inputModalities
+    : (Array.isArray(meta?.input) && meta.input.length > 0 ? meta.input : undefined);
+
+  entry.opencodex_capability_provenance = {
+    provider: model.provider,
+    model_id: model.id,
+    ...(contextWindow !== undefined ? { context_window: contextWindow } : {}),
+    ...(inputModalities !== undefined ? { input_modalities: [...inputModalities] } : {}),
+    ...(Array.isArray(model.capabilities) && model.capabilities.length > 0
+      ? { capabilities: [...model.capabilities] }
+      : {}),
+  };
 }
 
 export function applyReasoningLevels(
@@ -153,8 +228,9 @@ export function applyReasoningLevels(
   // (no ultra->max client conversion) and codex-rs validates it by catalog membership,
   // so a missing max rung hard-fails spawn_agent effort overrides. The wire stays honest:
   // routed adapters clamp via clampToSupportedCodexEffort and natives via
-  // nativeEffortClamp (max -> the model's real top rung).
-  if (!preserveExact && efforts.length > 0) {
+  // nativeEffortClamp (max -> the model's real top rung). A `none`-only ladder is NOT
+  // reasoning-capable, so it must not grow synthetic top rungs.
+  if (!preserveExact && efforts.length > 0 && efforts.some(effort => effort !== "none" && effort !== "minimal")) {
     const additions: string[] = [];
     if (!efforts.includes("max")) additions.push("max");
     if (!efforts.includes("ultra")) additions.push("ultra");
@@ -177,11 +253,13 @@ export function applyReasoningLevels(
   }
   entry.default_reasoning_level = defaultOverride && efforts.includes(defaultOverride)
     ? defaultOverride
-    : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high" : efforts[0];
+    : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
+    // Sentinels never become the implicit default when real rungs are declared.
+    : efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
 }
 
 export function isGpt56NativeSlug(slug: string): boolean {
-  return !slug.includes("/") && slug.startsWith("gpt-5.6-");
+  return !slug.includes("/") && nativeOpenAiCapabilitySourceSlug(slug).startsWith("gpt-5.6-");
 }
 
 export function ensureGpt56ReasoningLevels(entry: RawEntry): void {
@@ -214,11 +292,13 @@ export function ensureUltraReasoningLevel(entry: RawEntry): void {
   entry.supported_reasoning_levels = levels;
 }
 
-export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps = {}): Set<string> | null {
-  const bundled = loadBundledCodexCatalog(deps);
-  if (!bundled) return null;
+/** Derive the installed Codex effort vocabulary from caller-observed bundled catalog bytes. */
+export function supportedCodexReasoningEffortsFromObservedCatalog(
+  catalog: ReadonlyRawCatalog | null,
+): ReadonlySet<string> | null {
+  if (!catalog) return null;
   const efforts = new Set<string>();
-  for (const model of bundled.models ?? []) {
+  for (const model of catalog.models ?? []) {
     if (typeof model.slug !== "string" || model.slug.includes("/")) continue;
     const levels = Array.isArray(model.supported_reasoning_levels) ? model.supported_reasoning_levels : [];
     for (const level of levels) {
@@ -230,6 +310,10 @@ export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps = {}): S
   return efforts.size > 0 ? efforts : null;
 }
 
+export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps = {}): ReadonlySet<string> | null {
+  return supportedCodexReasoningEffortsFromObservedCatalog(loadBundledCodexCatalog(deps));
+}
+
 export function clampedDefaultEffort(original: string, surviving: readonly string[]): string {
   if (surviving.length === 0) return "medium";
   const ranked = [...surviving]
@@ -240,7 +324,10 @@ export function clampedDefaultEffort(original: string, surviving: readonly strin
   return (atOrBelow.at(-1) ?? ranked[0]!).effort;
 }
 
-export function clampEntryToCodexSupportedEfforts(entry: RawEntry, supported: Set<string> | null): void {
+export function clampEntryToCodexSupportedEfforts(
+  entry: RawEntry,
+  supported: ReadonlySet<string> | null,
+): void {
   if (!supported) return;
   const levels = Array.isArray(entry.supported_reasoning_levels)
     ? entry.supported_reasoning_levels as Array<{ effort?: string }>
@@ -263,12 +350,17 @@ export function clampEntryToCodexSupportedEfforts(entry: RawEntry, supported: Se
   }
 }
 
-export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: BundledCatalogDeps = {}): RawEntry[] {
-  const supported = codexSupportedReasoningEfforts(deps);
-  if (!supported) {
-    if (!deps.commandCandidates) persistEffortClamp(null, { configDir: deps.configDir });
-    return models;
-  }
+export interface ObservedCatalogEffortClamp {
+  readonly removedEfforts: readonly string[];
+  readonly affectedModels: readonly string[];
+}
+
+/** Apply an already-observed runtime ladder without probing, logging, or writing diagnostics. */
+export function clampCatalogModelsToObservedCodexSupport(
+  models: RawEntry[],
+  supported: ReadonlySet<string> | null,
+): ObservedCatalogEffortClamp {
+  if (!supported) return { removedEfforts: [], affectedModels: [] };
 
   const removed = new Set<string>();
   const affected: string[] = [];
@@ -301,6 +393,20 @@ export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: Bundl
     }
   }
 
+  return {
+    removedEfforts: [...removed].sort(),
+    affectedModels: affected,
+  };
+}
+
+export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: BundledCatalogDeps = {}): RawEntry[] {
+  const supported = codexSupportedReasoningEfforts(deps);
+  if (!supported) {
+    if (!deps.commandCandidates) persistEffortClamp(null, { configDir: deps.configDir });
+    return models;
+  }
+  const clamp = clampCatalogModelsToObservedCodexSupport(models, supported);
+
   let runtimePath = "codex";
   let runtimeVersion: string | null = null;
   if (!deps.commandCandidates) {
@@ -337,12 +443,12 @@ export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: Bundl
     }
   }
 
-  if (removed.size > 0) {
+  if (clamp.removedEfforts.length > 0) {
     const diagnostic: EffortClampDiagnostic = {
       runtimePath,
       runtimeVersion,
-      removedEfforts: [...removed].sort(),
-      affectedModels: affected,
+      removedEfforts: [...clamp.removedEfforts],
+      affectedModels: [...clamp.affectedModels],
     };
     for (const line of formatClampLogLines(diagnostic)) console.warn(line);
     if (!deps.commandCandidates) persistEffortClamp(diagnostic, { configDir: deps.configDir });

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";