@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/windows-installation-files.ts

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import type { Library, Symbols } from "bun:ffi";
+
+const KERNEL_SYMBOLS = {
+  GetDriveTypeW: { args: ["ptr"], returns: "u32" },
+  GetVolumeNameForVolumeMountPointW: { args: ["ptr", "ptr", "u32"], returns: "i32" },
+  CreateFileW: { args: ["ptr", "u32", "u32", "ptr", "u32", "u32", "u64"], returns: "u64" },
+  GetFileInformationByHandleEx: { args: ["u64", "i32", "ptr", "u32"], returns: "i32" },
+  GetFileType: { args: ["u64"], returns: "u32" },
+  ReadFile: { args: ["u64", "ptr", "u32", "ptr", "ptr"], returns: "i32" },
+  CloseHandle: { args: ["u64"], returns: "i32" },
+} as const satisfies Symbols;
+const NT_SYMBOLS = {
+  NtCreateFile: { args: ["ptr", "u32", "ptr", "ptr", "ptr", "u32", "u32", "u32", "u32", "ptr", "u32"], returns: "i32" },
+} as const satisfies Symbols;
+
+export interface WindowsInstallationFileRequest {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly hashOnly?: boolean;
+}
+export interface WindowsInstallationFileIdentity {
+  readonly volumeSerial: string;
+  readonly fileId: string;
+  readonly size: number;
+  readonly lastWriteTime: string;
+  readonly changeTime: string;
+}
+export type WindowsInstallationFilesResult =
+  | { kind: "observed"; files: {
+    path: string; identity: WindowsInstallationFileIdentity; bytes: Uint8Array; digest: string;
+  }[] }
+  | { kind: "refused"; reason: "unsupported-platform" | "invalid-request" | "native-api-unavailable"
+    | "volume-unavailable" | "open-refused" | "reparse-point" | "not-regular-file"
+    | "size-limit" | "read-failed" | "identity-changed" | "inspection-failed" };
+
+type Refusal = Extract<WindowsInstallationFilesResult, { kind: "refused" }>["reason"];
+class InspectionRefusal extends Error {
+  constructor(readonly reason: Refusal) { super(reason); }
+}
+const MIB = 1024 * 1024;
+const REPARSE = 0x400;
+const DIRECTORY = 0x10;
+const INVALID_HANDLE = 0xffffffffffffffffn;
+let openedForTests: (() => void) | undefined;
+/** Runs after handles are held, for real Windows sharing/rename regression fixtures. */
+export function setWindowsInstallationFilesOpenedForTests(callback?: () => void): void {
+  openedForTests = callback;
+}
+
+function components(path: string): { drive: string; names: string[] } | null {
+  if (typeof path !== "string" || path.length > 8192 || !/^[A-Za-z]:[\\/]/.test(path)) return null;
+  const names = path.slice(3).split(/[\\/]/);
+  if (!names.length || names.length > 64 || names.some(name => !name || name === "." || name === ".."
+    || /[\x00-\x1f<>:"|?*]/.test(name) || /[. ]$/.test(name)
+    || /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(name))) return null;
+  return { drive: `${path[0]!.toUpperCase()}:\\`, names };
+}
+
+/**
+ * An explicit, read-only snapshot; never installation authority or a runtime-selection proof.
+ * All component opens are relative to held directory handles, not checked-then-reopened paths.
+ * Windows x64 only: the UNICODE_STRING/OBJECT_ATTRIBUTES layouts below are the x64 ABI.
+ * No candidate runs and no shell/compiler is started. Disk/driver latency is not a hard deadline.
+ * API contracts: learn.microsoft.com/windows/win32/api/winternl/nf-winternl-ntcreatefile
+ * and /windows/win32/api/fileapi/nf-fileapi-getvolumenameforvolumemountpointw.
+ */
+export async function inspectWindowsInstallationFiles(
+  requests: readonly WindowsInstallationFileRequest[],
+): Promise<WindowsInstallationFilesResult> {
+  if (!Array.isArray(requests) || requests.length === 0 || requests.length > 12) {
+    return { kind: "refused", reason: "invalid-request" };
+  }
+  let ceiling = 0;
+  const parsed = requests.map(request => {
+    const parsedPath = request && components(request.path);
+    if (!parsedPath || !Number.isSafeInteger(request.maxBytes) || request.maxBytes < 0
+      || (request.hashOnly !== undefined && typeof request.hashOnly !== "boolean")
+      || request.maxBytes > (request.hashOnly ? 256 * MIB : MIB)) return null;
+    ceiling += request.maxBytes;
+    return parsedPath;
+  });
+  if (parsed.some(path => path === null) || ceiling > 300 * MIB) {
+    return { kind: "refused", reason: "invalid-request" };
+  }
+  if (process.platform !== "win32" || process.arch !== "x64") {
+    return { kind: "refused", reason: "unsupported-platform" };
+  }
+  // Loading FFI is itself opt-in; importing this module performs no Windows inspection.
+  let ffi: typeof import("bun:ffi");
+  try { ffi = await import("bun:ffi"); } catch { return { kind: "refused", reason: "native-api-unavailable" }; }
+  let kernel: Library<typeof KERNEL_SYMBOLS> | undefined;
+  let nt: Library<typeof NT_SYMBOLS> | undefined;
+  const handles: bigint[] = [];
+  try {
+    try {
+      kernel = ffi.dlopen("kernel32.dll", KERNEL_SYMBOLS);
+      nt = ffi.dlopen("ntdll.dll", NT_SYMBOLS);
+    } catch { throw new InspectionRefusal("native-api-unavailable"); }
+    const k = kernel.symbols;
+    const wide = (text: string): Buffer => Buffer.from(`${text}\0`, "utf16le");
+    const keep = (handle: bigint): bigint => {
+      if (handle === 0n || handle === INVALID_HANDLE) throw new InspectionRefusal("open-refused");
+      handles.push(handle);
+      return handle;
+    };
+    const info = (handle: bigint, infoClass: number, length: number): Buffer => {
+      const buffer = Buffer.alloc(length);
+      if (!k.GetFileInformationByHandleEx!(handle, infoClass, ffi.ptr(buffer), length)) {
+        throw new InspectionRefusal("inspection-failed");
+      }
+      return buffer;
+    };
+    const inspect = (handle: bigint, directory: boolean): WindowsInstallationFileIdentity => {
+      if (k.GetFileType!(handle) !== 1) throw new InspectionRefusal("not-regular-file"); // FILE_TYPE_DISK
+      const basic = info(handle, 0, 40); // FILE_BASIC_INFO: 4 LARGE_INTEGERs, attributes.
+      const attributes = basic.readUInt32LE(32);
+      if (attributes & REPARSE) throw new InspectionRefusal("reparse-point");
+      if (Boolean(attributes & DIRECTORY) !== directory) throw new InspectionRefusal("not-regular-file");
+      const id = info(handle, 18, 24); // FILE_ID_INFO: volume serial and 128-bit file ID.
+      const standard = info(handle, 1, 24); // FILE_STANDARD_INFO.EndOfFile
+      const size = standard.readBigInt64LE(8);
+      if (size < 0n || size > BigInt(Number.MAX_SAFE_INTEGER)) throw new InspectionRefusal("size-limit");
+      return { volumeSerial: id.readBigUInt64LE(0).toString(16), fileId: id.subarray(8, 24).toString("hex"),
+        size: Number(size), lastWriteTime: basic.readBigInt64LE(16).toString(), changeTime: basic.readBigInt64LE(24).toString() };
+    };
+    const roots = new Map<string, bigint>();
+    const root = (drive: string): bigint => {
+      const held = roots.get(drive);
+      if (held !== undefined) return held;
+      const mount = wide(drive);
+      const name = Buffer.alloc(100 * 2);
+      if (![2, 3, 5, 6].includes(Number(k.GetDriveTypeW!(ffi.ptr(mount))))) {
+        throw new InspectionRefusal("volume-unavailable");
+      }
+      // Root-only volume management query, never a candidate-controlled ancestor traversal.
+      // This API does not support SMB; only a strict local volume GUID reaches CreateFileW.
+      if (!k.GetVolumeNameForVolumeMountPointW!(ffi.ptr(mount), ffi.ptr(name), 100)) {
+        throw new InspectionRefusal("volume-unavailable");
+      }
+      const guid = name.toString("utf16le").split("\0", 1)[0]!;
+      if (!/^\\\\\?\\Volume\{[0-9a-f-]{36}\}\\$/i.test(guid)) throw new InspectionRefusal("volume-unavailable");
+      const path = wide(guid);
+      const handle = keep(BigInt(k.CreateFileW!(ffi.ptr(path), 0x100081, 1, null, 3, 0x02200000, 0n)));
+      inspect(handle, true);
+      roots.set(drive, handle);
+      return handle;
+    };
+    const relativeOpen = (parent: bigint, component: string, directory: boolean): bigint => {
+      const name = wide(component);
+      const unicode = Buffer.alloc(16);
+      unicode.writeUInt16LE(name.length - 2, 0);
+      unicode.writeUInt16LE(name.length, 2);
+      unicode.writeBigUInt64LE(BigInt(ffi.ptr(name)), 8);
+      const attributes = Buffer.alloc(48);
+      attributes.writeUInt32LE(48, 0);
+      attributes.writeBigUInt64LE(parent, 8);
+      attributes.writeBigUInt64LE(BigInt(ffi.ptr(unicode)), 16);
+      attributes.writeUInt32LE(0x40, 24); // OBJ_CASE_INSENSITIVE; one component only.
+      const output = Buffer.alloc(8);
+      const status = Buffer.alloc(16);
+      // FILE_OPEN; FILE_SYNCHRONOUS_IO_NONALERT; FILE_OPEN_REPARSE_POINT.
+      // Share READ only: while held, writes/reparse edits and delete/rename opens are refused.
+      const result = nt!.symbols.NtCreateFile!(ffi.ptr(output), 0x100081, ffi.ptr(attributes),
+        ffi.ptr(status), null, 0, 1, 1, 0x200020 | (directory ? 1 : 0), null, 0);
+      if (result < 0) throw new InspectionRefusal("open-refused");
+      const handle = keep(output.readBigUInt64LE(0));
+      inspect(handle, directory);
+      return handle;
+    };
+    const directories = new Map<string, bigint>();
+    const files = requests.map((request, index) => {
+      const { drive, names } = parsed[index]!;
+      let parent = root(drive);
+      let key = drive;
+      for (const component of names.slice(0, -1)) {
+        key += `${component}\\`;
+        let handle = directories.get(key);
+        if (handle === undefined) {
+          handle = relativeOpen(parent, component, true);
+          directories.set(key, handle);
+        }
+        parent = handle;
+      }
+      const handle = relativeOpen(parent, names[names.length - 1]!, false);
+      const identity = inspect(handle, false);
+      if (identity.size > request.maxBytes) throw new InspectionRefusal("size-limit");
+      return { request, handle, identity };
+    });
+    openedForTests?.();
+    const observed = files.map(({ request, handle, identity }) => {
+      const hash = createHash("sha256");
+      const bytes = request.hashOnly ? new Uint8Array() : new Uint8Array(identity.size);
+      const chunk = Buffer.alloc(Math.min(MIB, Math.max(1, identity.size)));
+      const read = Buffer.alloc(4);
+      let offset = 0;
+      while (offset < identity.size) {
+        const length = Math.min(chunk.length, identity.size - offset);
+        if (!k.ReadFile!(handle, ffi.ptr(chunk), length, ffi.ptr(read), null)) throw new InspectionRefusal("read-failed");
+        const count = read.readUInt32LE(0);
+        if (!count || count > length) throw new InspectionRefusal("read-failed");
+        hash.update(chunk.subarray(0, count));
+        if (!request.hashOnly) bytes.set(chunk.subarray(0, count), offset);
+        offset += count;
+      }
+      if (!k.ReadFile!(handle, ffi.ptr(chunk), 1, ffi.ptr(read), null) || read.readUInt32LE(0) !== 0) {
+        throw new InspectionRefusal("identity-changed");
+      }
+      return { path: request.path, identity, bytes, digest: hash.digest("hex") };
+    });
+    for (const file of files) {
+      if (JSON.stringify(inspect(file.handle, false)) !== JSON.stringify(file.identity)) {
+        throw new InspectionRefusal("identity-changed");
+      }
+    }
+    return { kind: "observed", files: observed };
+  } catch (error) {
+    return { kind: "refused", reason: error instanceof InspectionRefusal ? error.reason : "inspection-failed" };
+  } finally {
+    for (const handle of handles.reverse()) kernel?.symbols.CloseHandle?.(handle);
+    nt?.close();
+    kernel?.close();
+  }
+}

package/src/combos/failover.ts

@@ -118,23 +118,29 @@ function parseHttpDate(value: string, now: number): number | undefined {
 export function parseRetryAfterMs(
   value: string | null | undefined,
   now = Date.now(),
-  options?: { preserveImmediate?: boolean },
+  options?: { preserveImmediate?: boolean; preserveServerDelay?: boolean },
 ): number | undefined {
   const text = value?.trim();
   if (!text) return undefined;
+  // A local wait ceiling must not make an explicit upstream reset expire early.
+  // Keep legacy bounded parsing for other callers. The opt-in stores a timestamp;
+  // the combo picker still independently limits how long a live request waits.
+  const maximum = options?.preserveServerDelay === true
+    ? Number.MAX_SAFE_INTEGER - Math.max(0, now)
+    : MAX_COOLDOWN_MS;
   if (/^\d+(?:\.\d+)?$/.test(text)) {
     const seconds = Number(text);
     if (
       Number.isFinite(seconds)
       && (seconds > 0 || (options?.preserveImmediate && seconds === 0))
     ) {
-      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), maximum);
     }
   }
   const timestamp = parseHttpDate(text, now);
   if (timestamp === undefined) return undefined;
   const delay = timestamp - now;
-  if (delay > 0) return Math.min(delay, MAX_COOLDOWN_MS);
+  if (delay > 0) return Math.min(delay, maximum);
   return options?.preserveImmediate ? 1 : undefined;
 }
 
@@ -215,7 +221,11 @@ export function coolComboTarget(
   // A server-provided Retry-After is authoritative, including an immediate `0` directive.
   // A quota reset is the next-most-specific signal (#3256); configured and default cooldowns
   // are only fallbacks when upstream supplied neither usable value.
-  const cooldownMs = parseRetryAfterMs(options?.retryAfter, now, { preserveImmediate: true })
+  const serverDelayMs = parseRetryAfterMs(options?.retryAfter, now, {
+    preserveImmediate: true,
+    preserveServerDelay: true,
+  });
+  const cooldownMs = serverDelayMs
     ?? parseResetCooldownMs(options?.resetAt, now)
     ?? options?.cooldownMs
     ?? (isTransientRequestRateLimit({
@@ -224,7 +234,9 @@ export function coolComboTarget(
       message: options?.message,
     }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
   targetCooldowns.set(cooldownMapKey(comboId, target), {
-    cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
+    // Only the locally chosen fallback is capped at ten minutes. An explicit
+    // server lower bound (including one hour) remains authoritative.
+    cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
   });
   sweepExpiredOnWrite(now);
 }
@@ -387,6 +399,9 @@ function isRequestLocalTargetIncompatibility(status: number, message: string, co
     if (errorCode === "unsupported_value"
       && (e.param === "reasoning.effort" || e.param === "reasoning_effort")
       && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true;
+    if (e.code === null
+      && e.param === "reasoning_effort"
+      && /^Function tools with reasoning_effort are not supported for gpt-6-astra(?:-\d{4}-\d{2}-\d{2})? in \/v1\/chat\/completions\. To use function tools, use \/v1\/responses or set reasoning_effort to 'none'\.$/.test(e.message)) return true;
     return e.param === "input"
       && (errorCode === "" || errorCode === "invalid_request_error")
       && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message);
@@ -394,6 +409,103 @@ function isRequestLocalTargetIncompatibility(status: number, message: string, co
   return false;
 }
 
+/**
+ * Codes a gateway uses when it declines a request field it cannot serve.
+ *
+ * Wider than the set {@link isRequestLocalTargetIncompatibility} accepts, by exactly one member:
+ * Alibaba's gateway reports `invalid_parameter_error`. It is kept in its own set rather than
+ * added to the shared one, because that set also governs the `user` parameter and image-input
+ * branches and widening it there would admit shapes those branches were reasoned about without.
+ */
+const RESPONSE_FORMAT_REFUSAL_CODES = new Set([
+  "",
+  "invalid_request_error",
+  "invalid_parameter_error",
+  "unsupported_parameter",
+  "unsupported_value",
+]);
+
+/**
+ * Does this message say the target cannot PROVIDE `response_format`, rather than that the
+ * request's `response_format` was malformed?
+ *
+ * That distinction is the whole point of #4903 and it is why neither obvious option was taken.
+ * Hopping on every 400 would replay a genuinely malformed request against every remaining
+ * target. Dropping `response_format` would silently change the output contract the caller
+ * asked for, on a path whose entire purpose is a structured result.
+ *
+ * So both halves are required: the message must name the field, AND it must say the field is
+ * unavailable or unsupported. "Invalid schema for response_format" names the field and claims
+ * nothing about capability, so it stays terminal.
+ *
+ * `param` may be absent or explicitly null -- the reported gateway sends `param: null` -- but a
+ * param naming a DIFFERENT field contradicts the message and fails closed.
+ */
+function namesResponseFormatIncapability(message: string, param: unknown): boolean {
+  if (param !== undefined && param !== null && param !== "response_format") return false;
+  const text = message.toLowerCase();
+  if (!text.includes("response_format")) return false;
+  return /(unavailable|not available|unsupported|not supported|does not support|doesn't support|cannot be used|is not enabled)/u
+    .test(text);
+}
+
+/**
+ * A `response_format` capability gap is target-local: this model cannot produce the requested
+ * output shape, which says nothing about the next target in the combo.
+ *
+ * Reported against a shadow title-generation call, where a combo's first target rejects
+ * `response_format` and the chain stops instead of trying the target behind it (#4903).
+ *
+ * The next target receives the SAME request, `response_format` included, so a target that can
+ * honour the contract honours it and one that cannot is skipped in turn. Traversal stays finite
+ * because combo excludes each attempted target and policy tries each candidate once.
+ *
+ * The envelope is bounded exactly like {@link isRequestLocalTargetIncompatibility}: an intact
+ * provider JSON object, a depth budget, `type: "invalid_request_error"`, and a code from a
+ * closed set. Nothing is inferred from echoed prompt text and no field is removed.
+ */
+function isResponseFormatCapabilityRefusal(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 400 || message.length > 16_384) return false;
+  if (!RESPONSE_FORMAT_REFUSAL_CODES.has(normalizedFailureCode(code))) return false;
+  let text = message.trim();
+  for (let depth = 0; depth < 3; depth += 1) {
+    if (text.startsWith("Provider error 400: ")) {
+      text = text.slice("Provider error 400: ".length).trim();
+    }
+    // A chat gateway can report the refusal inside a single SSE frame, and the combo consumer
+    // keeps the raw text when that frame stops the error object from being extracted -- which is
+    // why the reported classification text reads `data: {"error":...}` and why the structured
+    // code arrives undefined. Exactly one `data:` prefix is removed, and only when the body is
+    // one line: this unwraps a single frame rather than parsing a stream, so a multi-event body
+    // is left alone and still fails closed.
+    if (text.startsWith("data:") && !text.includes("\n")) {
+      text = text.slice("data:".length).trim();
+    }
+    let payload: unknown;
+    try { payload = JSON.parse(text); } catch { return false; }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+    const error = (payload as Record<string, unknown>).error;
+    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
+    const e = error as Record<string, unknown>;
+    if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false;
+    if (typeof e.message !== "string") return false;
+    // Our own wrapper, re-wrapped by a downstream hop. Peel it and look again, within budget.
+    if (e.message.startsWith("Provider error 400: ") && e.param === undefined) {
+      text = e.message;
+      continue;
+    }
+    if (e.type !== "invalid_request_error") return false;
+    const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined);
+    if (!RESPONSE_FORMAT_REFUSAL_CODES.has(errorCode)) return false;
+    return namesResponseFormatIncapability(e.message, e.param);
+  }
+  return false;
+}
+
 export function comboFailureCooldownScope(
   status: number,
   message: string,
@@ -411,6 +523,9 @@ export function comboFailureCooldownScope(
     || isProviderTargetContextOverflow(status, message, options?.code)
     || isDefiniteContextOverflow(status, message)
     || isRequestLocalTargetIncompatibility(status, message, options?.code)
+    // A capability gap says the target is healthy and the request did not fit it, which is the
+    // same reason every other entry here refuses to cool a target.
+    || isResponseFormatCapabilityRefusal(status, message, options?.code)
   ) return "none";
   if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider";
   // A rejected or unpaid credential is provider-wide evidence: every target that routes
@@ -595,6 +710,11 @@ export function comboFailureDecision(
   // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here.
   if (failureCode === "free_rate_limited") return "hop";
   if (isRequestLocalTargetIncompatibility(status, message, options?.code)) return "hop";
+  // Must precede the generic `invalid_request_error` stop below, which is where this refusal
+  // ended the chain: the gateway reports `type: "invalid_request_error"`, so the classifier
+  // reaches that list and returns terminal before anything can ask whether the next target
+  // could have served the request (#4903).
+  if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/config/admitted-identity.ts

@@ -0,0 +1,222 @@
+import { readConfigAdmissionSnapshot } from "./diagnostics";
+import { getConfigPath } from "./paths";
+import { canonicalPlainData, copyPlainData, isPlainObject, ownDataKeys } from "../lib/plain-data";
+import type { OcxConfig } from "../types";
+
+/**
+ * A configuration a roster may be built from, detached from the object the caller holds.
+ *
+ * The detachment is the point. A gather suspends, and while it is suspended a management route can
+ * edit the resident configuration in place; gathering from one state and projecting from another
+ * would produce rows that belong to neither. Every authoritative pass uses this copy from
+ * beginning to end, so what the resident object does in the meantime becomes a question about
+ * whether the result may be retained rather than a question about what the result is.
+ *
+ * What this deliberately does NOT do is require the resident configuration to equal the file on
+ * disk. The proxy routes by the configuration it is holding, so that is the configuration a
+ * preview and the mutation it authorizes must both describe. A file the operator has edited and
+ * the process has not adopted is a supported state rather than a fault: live reconciliation
+ * (src/config/live-reconcile.ts) merges persisted state while deliberately retaining live changes
+ * and the active listener binding, and can persist a binding the resident object does not have.
+ * Demanding equality would make preview permanently unavailable on exactly those configurations
+ * while proving nothing about the rows, which come from the resident object either way.
+ */
+export interface ExportConfigAdmission {
+  readonly config: OcxConfig;
+}
+
+/**
+ * What was true when an admission was captured, kept here rather than on the admission object.
+ *
+ * None of it is data a consumer has any business reading: the file term is a digest of the
+ * operator's configuration file and the canonical form contains their credentials. Holding it in a
+ * module WeakMap means an admission can be passed around, and even serialized by a careless
+ * caller, without carrying any of it.
+ */
+interface AdmissionEvidence {
+  readonly path: string;
+  readonly file: string;
+  readonly data: string;
+  readonly executors: ReadonlyMap<string, unknown>;
+}
+
+const evidence = new WeakMap<ExportConfigAdmission, AdmissionEvidence>();
+
+/**
+ * Detach the configuration a roster is about to be built from, and record what it was.
+ *
+ * Two things are recorded because two things can move independently. The resident configuration is
+ * what the rows are derived from, so its complete structure is captured: structurally rather than
+ * as a list of the fields that seemed to matter, because such a list is only as complete as
+ * whoever last thought about it and this one had already missed export-affecting configuration.
+ * The configuration file is recorded beside it, so a roster does not outlive an operator editing
+ * the configuration under a process that has not adopted it yet.
+ *
+ * Null when the file cannot be read, when it is there but the loader would have had to salvage it,
+ * and when the configuration object cannot be copied as plain data. Every caller fails closed on
+ * it: refusing a preview costs an ordinary load, and serving one that describes a configuration
+ * nobody has costs a file the operator did not ask for.
+ */
+export function captureExportConfigAdmission(live: OcxConfig): ExportConfigAdmission | null {
+  const path = getConfigPath();
+  const file = admittedFileTerm();
+  if (file === null) return null;
+  const resident = detachConfig(live);
+  if (resident === null) return null;
+  const config = withExecutors(resident);
+  if (config === null) return null;
+  const admission: ExportConfigAdmission = { config };
+  evidence.set(admission, { path, file, data: canonicalPlainData(resident.data), executors: resident.executors });
+  return admission;
+}
+
+/**
+ * Whether an admission still describes the configuration in hand and the file it was taken beside.
+ *
+ * Three things are checked because three things can move: the file can be rewritten, the resident
+ * object can be edited in place, and a consumer of the detached copy can mutate what it was given.
+ * The last matters as much as the others, because a pass that edited its own input and then
+ * published would be retaining a roster under a state that no longer describes even that input.
+ *
+ * Passive: it reads the configuration file and nothing else. No credential is resolved, no
+ * provider is contacted, no path is hardened and nothing is written.
+ */
+export function isExportConfigAdmissionCurrent(admission: ExportConfigAdmission, live: OcxConfig): boolean {
+  const captured = evidence.get(admission);
+  if (captured === undefined) return false;
+  // A different configuration home is a different question, not a stale answer to this one.
+  if (getConfigPath() !== captured.path) return false;
+  const file = admittedFileTerm();
+  if (file === null || file !== captured.file) return false;
+  const resident = detachConfig(live);
+  if (resident === null || canonicalPlainData(resident.data) !== captured.data) return false;
+  if (!sameExecutors(resident.executors, captured.executors)) return false;
+  const working = detachConfig(admission.config);
+  return working !== null
+    && canonicalPlainData(working.data) === captured.data
+    && sameExecutors(working.executors, captured.executors);
+}
+
+/**
+ * A plain-data copy of a configuration for a consumer that must not observe later edits, or null.
+ *
+ * The integration writer is the case this exists for. It freezes every other resolution seam
+ * before its first await and then held the configuration by reference, so a plan checked under one
+ * configuration could be written from another: the check and the document it authorized were
+ * reading the same object at two different moments. One copy taken before the await gives both of
+ * them the same configuration.
+ *
+ * Null rather than the caller's object when the copy cannot be made. Handing back the reference
+ * would have been a copy in name only, and the caller would have gone on to describe it as the
+ * configuration it checked.
+ */
+export function detachedConfigSnapshot(config: OcxConfig): OcxConfig | null {
+  const detached = detachConfig(config);
+  return detached === null ? null : withExecutors(detached);
+}
+
+/**
+ * The configuration file as an opaque term: its exact bytes, or the distinguished absence of one.
+ *
+ * This is a byte observation and nothing more. It says the operator's configuration file has not
+ * been rewritten since a roster was built; it is not a claim about whether the configuration the
+ * process is holding agrees with that file.
+ *
+ * Null for a file that cannot be read, because then a later read cannot tell whether it changed.
+ * Null too for one that is there and does not load cleanly, which is the existing contract for a
+ * derived roster rather than an inference about the resident configuration. Before this, a digest
+ * was accepted ahead of any look at what the parse produced.
+ *
+ * Absence is a configuration rather than the lack of one. No file means defaults, which is an
+ * ordinary fresh install and the ordinary state in CI.
+ */
+function admittedFileTerm(): string | null {
+  const snapshot = readConfigAdmissionSnapshot();
+  const { source, error } = snapshot.diagnostics;
+  if (snapshot.kind === "read") return source === "file" && error === null ? snapshot.contentSha256 : null;
+  return source === "default" && error === null ? "absent" : null;
+}
+
+interface DetachedConfig {
+  readonly data: Record<string, unknown>;
+  readonly executors: ReadonlyMap<string, unknown>;
+}
+
+/**
+ * A configuration as plain data, with the transport executors kept out of it.
+ *
+ * The copier refuses everything JSON could not have produced, so the one thing that needs handling
+ * here is a provider's fetch executor: a caller owns it and the gather uses it instead of the
+ * global transport. It is held by reference for the detached copy and compared by reference
+ * afterwards, so replacing it invalidates the binding while it is never serialized.
+ */
+function detachConfig(live: OcxConfig): DetachedConfig | null {
+  const executors = new Map<string, unknown>();
+  const root = live as unknown;
+  if (!isPlainObject(root)) return null;
+  const data: Record<string, unknown> = {};
+  for (const key of ownDataKeys(root)) {
+    if (key === null) return null;
+    const value = root[key];
+    if (value === undefined) continue;
+    if (key !== "providers") {
+      const copied = copyPlainData(value);
+      if (!copied.ok) return null;
+      data[key] = copied.value;
+      continue;
+    }
+    if (!isPlainObject(value)) return null;
+    const providers: Record<string, unknown> = {};
+    for (const name of ownDataKeys(value)) {
+      if (name === null) return null;
+      const provider = value[name];
+      if (provider === undefined) continue;
+      if (!isPlainObject(provider)) return null;
+      const copiedProvider: Record<string, unknown> = {};
+      for (const field of ownDataKeys(provider)) {
+        if (field === null) return null;
+        const fieldValue = provider[field];
+        if (fieldValue === undefined) continue;
+        // The executor exception applies to an executor. A provider entry keeps unknown
+        // configuration keys, so a fetch value that is not a function is something an operator
+        // wrote into the file, and it is copied and compared as the data it is. Discovery reads it
+        // the same way: the outbound transport takes its built-in path unless the value is
+        // callable.
+        if (field === "fetch" && typeof fieldValue === "function") {
+          executors.set(name, fieldValue);
+          continue;
+        }
+        const copied = copyPlainData(fieldValue);
+        if (!copied.ok) return null;
+        copiedProvider[field] = copied.value;
+      }
+      providers[name] = copiedProvider;
+    }
+    data[key] = providers;
+  }
+  return { data, executors };
+}
+
+/** The copy a consumer runs against, with the executors put back by reference. */
+function withExecutors(detached: DetachedConfig): OcxConfig | null {
+  // A second copy, so what is compared later is never the object handed to a consumer.
+  const copied = copyPlainData(detached.data);
+  if (!copied.ok) return null;
+  const config = copied.value;
+  const providers = config.providers;
+  if (isPlainObject(providers)) {
+    for (const [name, executor] of detached.executors) {
+      const provider = providers[name];
+      if (isPlainObject(provider)) provider.fetch = executor;
+    }
+  }
+  return config as unknown as OcxConfig;
+}
+
+function sameExecutors(left: ReadonlyMap<string, unknown>, right: ReadonlyMap<string, unknown>): boolean {
+  if (left.size !== right.size) return false;
+  for (const [name, executor] of left) {
+    if (!right.has(name) || right.get(name) !== executor) return false;
+  }
+  return true;
+}