@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/catalog/bundled.ts

@@ -34,28 +34,121 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { activeCodexModelsCachePath, catalogBackupPathFor, findNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing";
 import type { RawCatalog, RawEntry } from "./parsing";
 import { codexExecInvocation, isSpawnableCodexCandidate } from "../exec-invocation";
-import { resolveAndPersistCodexRuntime } from "../runtime";
-import type { EffortClampDiagnostic } from "../runtime";
+import {
+  parsePersistedCodexRuntime,
+  peekCodexRuntimeProcessCache,
+  resolveAndPersistCodexRuntime,
+} from "../runtime";
+import type {
+  DeepReadonly,
+  EffortClampDiagnostic,
+  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 let bundledCatalogCache: {
+export type ReadonlyRawCatalog = DeepReadonly<RawCatalog>;
+
+interface BundledCatalogMemo {
   /** Selected runtime identity; must change when doctor/sync picks a different binary. */
-  key: string;
-  expiresAt: number;
-  value: RawCatalog | null;
-} | null = null;
+  readonly key: string;
+  readonly expiresAt: 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;
+
+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,
+    expiresAt,
+    epoch,
+    valueIdentity: `bundled:${epoch}`,
+    value: value === null ? null : cloneAndDeepFreeze(value),
+  };
+}
+
+function clearBundledCatalogCache(): void {
+  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 {
-  bundledCatalogCache = null;
+  clearBundledCatalogCache();
 }
 
 /** Drop the process-local bundled catalog memo (e.g. after runtime selection changes). */
 export function invalidateBundledCatalogCache(): void {
-  bundledCatalogCache = null;
+  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 = (
@@ -143,7 +236,7 @@ export function runCodexDebugModels(
   });
 }
 
-export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatalog | null {
+export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): ReadonlyRawCatalog | null {
   const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.configDir && !deps.env;
   const execFile = deps.execFileSync ?? (execFileSync as unknown as ExecFile);
   // Prefer the single resolved runtime so sync/clamp never probe a different binary
@@ -168,11 +261,7 @@ export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatal
       discoverAlternatives: deps.discoverAlternatives ?? false,
     });
     if (useCache) {
-      cacheKey = [
-        resolved.runtime.command,
-        resolved.runtime.version ?? "",
-        process.env.OPENCODEX_HOME ?? "",
-      ].join("\0");
+      cacheKey = bundledRuntimeKey(resolved.runtime);
     }
     return [resolved.runtime.command];
   })();
@@ -183,33 +272,193 @@ export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatal
     && bundledCatalogCache.key === cacheKey
     && bundledCatalogCache.expiresAt > Date.now()
   ) {
-    return bundledCatalogCache.value;
+    return bundledCatalogCache.value === null
+      ? null
+      : cloneAndDeepFreeze(bundledCatalogCache.value);
   }
   for (const command of unique(candidates)) {
     try {
       const catalog = parseCatalogJson(runCodexDebugModels(command, execFile, deps));
       if (catalog && findNativeTemplate(catalog)) {
         if (useCache && cacheKey) {
-          bundledCatalogCache = {
-            key: cacheKey,
-            expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
-            value: catalog,
-          };
+          publishBundledCatalogCache(
+            cacheKey,
+            Date.now() + BUNDLED_CATALOG_CACHE_MS,
+            catalog,
+          );
+          return cloneAndDeepFreeze(bundledCatalogCache!.value!);
         }
-        return catalog;
+        return cloneAndDeepFreeze(catalog);
       }
     } catch { /* try next candidate */ }
   }
   if (useCache && cacheKey) {
-    bundledCatalogCache = {
-      key: cacheKey,
-      expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
-      value: null,
-    };
+    publishBundledCatalogCache(
+      cacheKey,
+      Date.now() + BUNDLED_CATALOG_CACHE_MS,
+      null,
+    );
   }
   return 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;
+      processLocal: Readonly<{
+        runtime: CatalogGatherProcessLocalObservation;
+        bundledCatalog: CatalogGatherProcessLocalObservation;
+      }>;
+    }>
+  | Readonly<{
+      kind: "catalog-unavailable";
+      processLocal: Readonly<{
+        runtime: Readonly<{ state: "unused" }>;
+        bundledCatalog: Readonly<{ state: "unused" }>;
+      }>;
+    }>;
+
+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,
+): CatalogSourceForGather {
+  const bundledMemo = bundledCatalogCache;
+  if (bundledMemo?.value && bundledMemo.expiresAt > Date.now()) {
+    const runtime = peekCodexRuntimeForCatalogGather(evidenceSession);
+    if (runtime.kind === "available" && bundledMemo.key === bundledRuntimeKey(runtime.runtime)) {
+      return cloneAndDeepFreeze({
+        kind: "available" as const,
+        source: "bundled-catalog-template" as const,
+        catalog: bundledMemo.value,
+        processLocal: {
+          runtime: runtime.processLocal,
+          bundledCatalog: {
+            state: "used" as const,
+            epoch: bundledMemo.epoch,
+            valueIdentity: bundledMemo.valueIdentity,
+          },
+        },
+      });
+    }
+  }
+
+  const roles = [
+    "active-catalog-merge",
+    "hashed-backup-fallback",
+    "legacy-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 || !findNativeTemplate(catalog)) continue;
+    return cloneAndDeepFreeze({
+      kind: "available" as const,
+      source: role,
+      catalog,
+      processLocal: {
+        runtime: UNUSED_PROCESS_LOCAL,
+        bundledCatalog: UNUSED_PROCESS_LOCAL,
+      },
+    });
+  }
+
+  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;
@@ -219,7 +468,7 @@ export function materializeBundledCodexCatalog(path: string, deps: BundledCatalo
   } catch {
     return null;
   }
-  return catalog;
+  return JSON.parse(JSON.stringify(catalog)) as RawCatalog;
 }
 
 export function loadCatalogForSync(path: string): RawCatalog | null {
@@ -236,16 +485,17 @@ export function loadCatalogForSync(path: string): RawCatalog | null {
 
 export function readCurrentCatalogOrCache(): RawCatalog | null {
   const path = readCodexCatalogPath();
-  return (isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null)
-    ?? readCatalog(path)
-    ?? readCatalog(activeCodexModelsCachePath());
+  const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
+  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
+  return readCatalog(path) ?? readCatalog(activeCodexModelsCachePath());
 }
 
 export function loadCatalogTemplate(): RawEntry | null {
   const catalogPath = readCodexCatalogPath();
+  const bundled = loadBundledCodexCatalog();
   const native = findNativeTemplate(readCatalog(catalogPath))
     ?? findNativeTemplate(readCatalogBackup(catalogPath))
     ?? findNativeTemplate(readCatalog(activeCodexModelsCachePath()))
-    ?? findNativeTemplate(loadBundledCodexCatalog());
+    ?? findNativeTemplate(bundled ? JSON.parse(JSON.stringify(bundled)) as RawCatalog : null);
   return native ? JSON.parse(JSON.stringify(native)) : null;
 }

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;
+}