@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/server/management/integration-routes.ts

@@ -31,6 +31,7 @@ import {
   disableIntegrationCoordinated,
   overwriteIntegrationCoordinated,
   restoreIntegrationCoordinated,
+  type CoordinatedIntegrationOptions,
   type IntegrationRestoreInput,
   type IntegrationWriteInput,
   type WriteRefused,
@@ -45,7 +46,13 @@ import {
 import { jsonResponse } from "../auth-cors";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import type { ManagementContext } from "./context";
-import { loadExportModels } from "./model-rows";
+import { exportSnapshotIdentity, loadExportModels, previewExportSnapshot } from "./model-rows";
+import {
+  previewIntegration,
+  type IntegrationMutationPlan,
+  type IntegrationPlanOperation,
+  type PreviewRequest,
+} from "../../integrations/mutation-plan";
 
 
 const INTEGRATION_ROUTE_PREFIX = "/api/client-integrations/";
@@ -246,6 +253,37 @@ async function buildIntegrationWriteInput(
   };
 }
 
+/**
+ * The same input a mutation would build, from the read-only roster.
+ *
+ * It differs from the mutation's in exactly one way, and the difference is deliberate: the roster
+ * comes from `previewExportModels`, which gathers without running the initial-selection finalizer
+ * that persists configuration. Everything else is shared, so a preview and the commit that follows
+ * it cannot disagree for any reason except the state genuinely moving.
+ */
+async function buildIntegrationPreviewInput(
+  clientId: IntegrationClientId,
+  ctx: ManagementContext,
+  store: IntegrationStateStore,
+): Promise<{ input: IntegrationWriteInput; identity: string } | null> {
+  const snapshot = previewExportSnapshot(ctx.config);
+  // No cached roster means no honest snapshot to plan against. Gathering one here would make a
+  // read refresh credentials and write the provider cache, which is the thing preview must not do.
+  if (snapshot === null) return null;
+  return {
+    identity: snapshot.identity,
+    input: {
+      clientId,
+      models: snapshot.models,
+      config: ctx.config,
+      port: Number(ctx.url.port) || ctx.config.port,
+      store,
+      io: integrationMutationTestHooks?.io,
+      ...pathOverrides(),
+    },
+  };
+}
+
 /**
  * The file's current bytes, or `null` when it is missing.
  *
@@ -271,6 +309,97 @@ function invalidClientResponse(ctx: ManagementContext): Response {
   }, 400, ctx.req, ctx.config);
 }
 
+/**
+ * No cached model roster, so there is nothing honest to plan against.
+ *
+ * Answered as a bounded refusal rather than by gathering one: discovery refreshes credentials and
+ * writes the provider cache, and a preview that did either would be a write wearing a read's name.
+ * The caller opens the models view or performs the mutation directly.
+ */
+function previewUnavailableResponse(ctx: ManagementContext): Response {
+  return jsonResponse({
+    error: "no model roster is cached yet, so this change cannot be planned",
+    code: "integration_preview_unavailable",
+  }, 409, ctx.req, ctx.config);
+}
+
+/**
+ * A confirmed plan, or a reason the request cannot carry one.
+ *
+ * Both fields or neither. A half-bound request is rejected rather than quietly treated as
+ * unbound, because dropping one half would answer 200 to a caller who believed their
+ * confirmation was being checked.
+ */
+function planBindingOf(
+  body: Record<string, unknown>,
+): { operation: IntegrationPlanOperation; fingerprint: string } | "none" | "half" | "unknown-operation" {
+  const { operation, planFingerprint } = body;
+  if (operation === undefined && planFingerprint === undefined) return "none";
+  if (operation === undefined || typeof planFingerprint !== "string" || planFingerprint.length === 0) return "half";
+  if (operation !== "apply" && operation !== "overwrite" && operation !== "disable" && operation !== "restore") {
+    return "unknown-operation";
+  }
+  return { operation, fingerprint: planFingerprint };
+}
+
+function halfBoundResponse(ctx: ManagementContext): Response {
+  return jsonResponse({
+    error: "operation and planFingerprint must be sent together",
+    code: "invalid_preview_binding",
+  }, 400, ctx.req, ctx.config);
+}
+
+/**
+ * Re-plan and compare before the mutation runs.
+ *
+ * The fingerprint is an optimistic token, never authorization: management authentication and
+ * every ownership rule still apply. What it adds is that a confirmation stops meaning anything
+ * the moment the state it described moved, and the refusal carries a fresh plan so the operator
+ * decides again against what is true now.
+ */
+function stalePlanGuard(
+  clientId: IntegrationClientId,
+  ctx: ManagementContext,
+  store: IntegrationStateStore,
+  request: PreviewRequest,
+  fingerprint: string,
+  capturedIdentity: string | null,
+): {
+  revalidate: NonNullable<CoordinatedIntegrationOptions["revalidate"]>;
+  response: () => Response | null;
+} {
+  let stale: IntegrationMutationPlan | "unavailable" | null = null;
+  return {
+    revalidate: async frozen => {
+      /*
+       * Plan the coordinator's OWN frozen input, never a freshly built one. Rebuilding here let
+       * the check validate against one roster while the mutation wrote from another, because an
+       * ordinary load can replace the snapshot at any time and nothing serialises that against
+       * this lock. The captured identity is verified separately, so a replacement is detected
+       * without ever swapping the roster this mutation is about to use.
+       */
+      if (exportSnapshotIdentity(ctx.config) !== capturedIdentity) {
+        const refreshed = await buildIntegrationPreviewInput(clientId, ctx, store);
+        stale = refreshed === null ? "unavailable" : previewIntegration(refreshed.input, request);
+        return { ok: false, reason: "conflict", state: "conflict", clientId, message: "the model roster changed while confirming" };
+      }
+      const plan = previewIntegration(frozen, request);
+      if (plan.canApply && plan.fingerprint === fingerprint) return null;
+      stale = plan;
+      return { ok: false, reason: "conflict", state: plan.state, clientId, message: "that confirmation no longer describes this file" };
+    },
+    response: () => {
+      if (stale === null) return null;
+      if (stale === "unavailable") return previewUnavailableResponse(ctx);
+      return jsonResponse({
+        error: "integration preview is stale",
+        code: "integration_preview_stale",
+        plan: stale,
+      }, 409, ctx.req, ctx.config);
+    },
+  };
+}
+
 function internalErrorResponse(error: unknown, ctx: ManagementContext): Response {
   return jsonResponse({
     error: error instanceof Error ? error.message : String(error),
@@ -565,6 +694,88 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
     }
   }
 
+  if (url.pathname === "/api/client-integrations/preview") {
+    if (req.method !== "POST") return null;
+    const parsed = await readJsonBody(ctx);
+    if (parsed instanceof Response) return parsed;
+    if (!isPlainRecord(parsed)) {
+      return jsonResponse({ error: "preview body must be an object", code: "invalid_preview_body" }, 400, req, ctx.config);
+    }
+    const previewClient = parsed.clientId;
+    if (typeof previewClient !== "string"
+      || !(INTEGRATION_CLIENT_IDS as readonly string[]).includes(previewClient)) {
+      return invalidClientResponse(ctx);
+    }
+    /*
+     * Aside is a set of profiles, not one file, and every mutation it has requires a profile. A
+     * plan built here would describe the legacy single-account location and no bound mutation
+     * would accept it, so an operator could confirm something nothing can carry out. The canonical
+     * per-profile preview answers this question properly, and the mutation routes already refuse
+     * the unscoped spelling the same way.
+     */
+    if (previewClient === "aside") {
+      return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
+    }
+    const operation = parsed.operation;
+    if (operation !== "apply" && operation !== "overwrite" && operation !== "disable") {
+      return jsonResponse({
+        error: "operation must be apply, overwrite or disable",
+        code: "invalid_preview_operation",
+      }, 400, req, ctx.config);
+    }
+    try {
+      const captured = await buildIntegrationPreviewInput(previewClient as IntegrationClientId, ctx, integrationStore());
+      if (!captured) return previewUnavailableResponse(ctx);
+      return jsonResponse(previewIntegration(captured.input, { operation }), 200, req, ctx.config);
+    } catch (error) {
+      return internalErrorResponse(error, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/client-integrations/restore/preview") {
+    if (req.method !== "POST") return null;
+    const parsed = await readJsonBody(ctx);
+    if (parsed instanceof Response) return parsed;
+    if (!isPlainRecord(parsed) || typeof parsed.opId !== "string" || parsed.opId.trim().length === 0) {
+      return jsonResponse({ error: "opId must be a non-empty string", code: "invalid_op_id" }, 400, req, ctx.config);
+    }
+    if (parsed.confirmDrift !== undefined && typeof parsed.confirmDrift !== "boolean") {
+      return jsonResponse({ error: "confirmDrift must be a boolean", code: "invalid_confirm_drift" }, 400, req, ctx.config);
+    }
+    const opId = parsed.opId.trim();
+    try {
+      const store = integrationStore();
+      const operation = store.findOperation(opId);
+      /*
+       * Answered as "not found" rather than by reading the row back to the caller. A preview is
+       * reached before any confirmation, so it is the cheapest place to probe journal contents,
+       * and it declines to be one.
+       */
+      if (!operation) {
+        return jsonResponse({
+          error: "integration operation not found",
+          code: "integration_operation_not_found",
+          opId,
+        }, 404, req, ctx.config);
+      }
+      // Same rule, decided after the row is found so an unscoped undo of an Aside operation is
+      // refused for what it is rather than answered as a missing operation.
+      if (operation.clientId === "aside") {
+        return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
+      }
+      const captured = await buildIntegrationPreviewInput(operation.clientId, ctx, store);
+      if (!captured) return previewUnavailableResponse(ctx);
+      const plan = previewIntegration(captured.input, {
+        operation: "restore",
+        opId,
+        confirmDrift: parsed.confirmDrift ?? false,
+      });
+      return jsonResponse(plan, 200, req, ctx.config);
+    } catch (error) {
+      return internalErrorResponse(error, ctx);
+    }
+  }
+
   if (url.pathname === "/api/client-integrations/restore") {
     if (req.method !== "POST") return null;
     const parsed = await readJsonBody(ctx);
@@ -584,7 +795,22 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
 
     const opId = parsed.opId.trim();
     const confirmDrift = parsed.confirmDrift ?? false;
-    const asideRestore = await asideRestoreResponse(ctx, { opId, confirmDrift }, profileOptions);
+    const restoreBinding = planBindingOf(parsed);
+    if (restoreBinding === "half") return halfBoundResponse(ctx);
+    if (restoreBinding === "unknown-operation" || (restoreBinding !== "none" && restoreBinding.operation !== "restore")) {
+      return jsonResponse({
+        error: "operation does not match the requested change",
+        code: "invalid_preview_operation",
+      }, 400, req, ctx.config);
+    }
+    // The binding travels with the request. Dropping it here routed a bound Aside restore into
+    // the unbound path, which executed the mutation while its confirmation went unexamined.
+    const asideRestore = await asideRestoreResponse(ctx, {
+      opId,
+      confirmDrift,
+      ...(parsed.operation === undefined ? {} : { operation: parsed.operation }),
+      ...(parsed.planFingerprint === undefined ? {} : { planFingerprint: parsed.planFingerprint }),
+    }, profileOptions);
     if (asideRestore) return asideRestore;
     let restoreClientId: IntegrationClientId | undefined;
     try {
@@ -607,7 +833,21 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
         }, 410, req, ctx.config);
       }
 
-      const writeInput = await buildIntegrationWriteInput(operation.clientId, ctx, store);
+      const boundRestore = restoreBinding === "none"
+        ? null
+        : await buildIntegrationPreviewInput(operation.clientId, ctx, store);
+      if (restoreBinding !== "none" && boundRestore === null) return previewUnavailableResponse(ctx);
+      const writeInput = boundRestore
+        ? boundRestore.input
+        : await buildIntegrationWriteInput(operation.clientId, ctx, store);
+      const restoreGuard = restoreBinding === "none" ? null : stalePlanGuard(
+        operation.clientId,
+        ctx,
+        store,
+      { operation: "restore", opId, confirmDrift },
+      restoreBinding.fingerprint,
+        boundRestore === null ? null : boundRestore.identity,
+    );
       const restoreInput: IntegrationRestoreInput = {
         ...writeInput,
         opId,
@@ -619,8 +859,11 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
         writeInput.io?.now ?? Date.now,
         () => restoreIntegrationCoordinated(restoreInput, {
           lockSeams: integrationMutationTestHooks?.lockSeams,
+          ...(restoreGuard ? { revalidate: restoreGuard.revalidate } : {}),
         }),
       );
+      const restoreStale = restoreGuard?.response();
+      if (restoreStale) return restoreStale;
       if (!result.ok) {
         /*
          * Drift is NOT special-cased here.
@@ -698,20 +941,59 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
     }, 400, req, ctx.config);
   }
 
+  const requestedOperation: IntegrationPlanOperation = parsed.enabled
+    ? (parsed.overwriteConflict === true ? "overwrite" : "apply")
+    : "disable";
+  const binding = planBindingOf(parsed);
+  if (binding === "half") return halfBoundResponse(ctx);
+  if (binding === "unknown-operation" || (binding !== "none" && binding.operation !== requestedOperation)) {
+    // A confirmation that names a different operation than the request performs is not a
+    // confirmation of this request.
+    return jsonResponse({
+      error: "operation does not match the requested change",
+      code: "invalid_preview_operation",
+    }, 400, req, ctx.config);
+  }
+
   try {
-    const input = await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
+    /*
+     * A bound request is built from the same passive roster the guard re-plans against, and an
+     * unbound one keeps its existing refreshing path. Building the refreshing input first would
+     * have had the mutation and its own confirmation check disagree about the roster by
+     * construction, which is the disagreement this binding exists to detect.
+     */
+    const boundToggle = binding === "none"
+      ? null
+      : await buildIntegrationPreviewInput(requestedClient, ctx, integrationStore());
+    if (binding !== "none" && boundToggle === null) return previewUnavailableResponse(ctx);
+    const input = boundToggle
+      ? boundToggle.input
+      : await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
+    const guard = binding === "none" ? null : stalePlanGuard(
+      requestedClient,
+      ctx,
+      integrationStore(),
+      { operation: binding.operation },
+      binding.fingerprint,
+      boundToggle === null ? null : boundToggle.identity,
+    );
     const result = await runIntegrationMutationFlight(
       requestedClient,
       parsed.enabled ? (parsed.overwriteConflict === true ? "overwrite" : "apply") : "disable",
       input.io?.now ?? Date.now,
       () => {
-        const options = { lockSeams: integrationMutationTestHooks?.lockSeams };
+        const options = {
+          lockSeams: integrationMutationTestHooks?.lockSeams,
+          ...(guard ? { revalidate: guard.revalidate } : {}),
+        };
         if (!parsed.enabled) return disableIntegrationCoordinated(input, options);
         return parsed.overwriteConflict === true
           ? overwriteIntegrationCoordinated(input, options)
           : applyIntegrationCoordinated(input, options);
       },
     );
+    const stale = guard?.response();
+    if (stale) return stale;
     if (!result.ok) return writerFailureResponse(requestedClient, result, ctx);
     return jsonResponse(result satisfies IntegrationToggleEnvelope, 200, req, ctx.config);
   } catch (error) {

package/src/server/management/metrics-routes.ts

@@ -0,0 +1,20 @@
+import type { ManagementContext } from "./context";
+
+export function handleMetricsRoutes(ctx: ManagementContext): Response | null {
+  if (ctx.url.pathname === "/api/metrics" && ctx.req.method === "GET") {
+    if (!ctx.deps.requestMetrics) {
+      return Response.json({ error: { code: "not_found", message: "metrics export is disabled" } }, {
+        status: 404,
+        headers: { "Cache-Control": "no-store" },
+      });
+    }
+    return new Response(ctx.deps.requestMetrics.snapshot(), {
+      status: 200,
+      headers: {
+        "Cache-Control": "no-store",
+        "Content-Type": "text/plain;version=0.0.4",
+      },
+    });
+  }
+  return null;
+}

package/src/server/management/model-rows.ts

@@ -9,6 +9,12 @@
  * Bodies are unchanged from their previous home; only `export` was added.
  */
 import type { CatalogModel } from "../../codex/catalog";
+import { observeModelCacheRevision } from "../../codex/model-cache";
+import {
+  captureExportConfigAdmission,
+  isExportConfigAdmissionCurrent,
+  type ExportConfigAdmission,
+} from "../../config/admitted-identity";
 import {
   catalogModelSlug,
   filterCatalogVisibleModels,
@@ -28,7 +34,7 @@ import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import type { OcxConfig } from "../../types";
 import { ensureCodexEntitlementFreshness } from "../../codex/model-entitlements";
 import { fetchAllModels } from "./shared";
-import { initialModelSelectionPending } from "../../providers/initial-model-selection";
+import { initialModelSelectionPending, pendingModelSelectionProviders } from "../../providers/initial-model-selection";
 import { catalogFastRowEligible, fastRowId } from "../fast-row";
 import { knownEffortRowIds } from "../effort-row";
 
@@ -77,14 +83,29 @@ export function effectiveManagementDisplayName(
  */
 export async function listManagementModelRows(
   config: OcxConfig,
-  options: { entitlementWaitMs?: number } = {},
+  options: {
+    entitlementWaitMs?: number;
+    models?: readonly CatalogModel[];
+    /** Filled with each provider's content revision as of the moment its rows were chosen. */
+    providerContentRevisions?: Map<string, string>;
+  } = {},
 ): Promise<ManagementModelRow[]> {
-  const [models] = await Promise.all([
-    fetchAllModels(config),
-    ensureCodexEntitlementFreshness(config, {
-      waitMs: options.entitlementWaitMs ?? 3_000,
-    }),
-  ]);
+  /*
+   * A supplied roster skips the gather, and that is the point rather than an optimization.
+   * `fetchAllModels` reaches providers and can persist an initial model selection, which a
+   * read-only caller must not do. Everything below this line is the projection — the disabled
+   * computation, native and account-bound rows, custom rows and the public list — so a caller
+   * that brings its own roster still sees exactly what a writer would, and the two cannot
+   * disagree about the roster for any reason except the roster itself.
+   */
+  const models = options.models === undefined
+    ? (await Promise.all([
+      fetchAllModels(config, options.providerContentRevisions),
+      ensureCodexEntitlementFreshness(config, {
+        waitMs: options.entitlementWaitMs ?? 3_000,
+      }),
+    ]))[0]
+    : [...options.models];
   const disabled = new Set(config.disabledModels ?? []);
   // Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
   // from the static supported set so a disabled model stays listed and re-enableable.
@@ -236,10 +257,201 @@ export function toExportModel(row: ManagementModelRow): ExportModel {
  * tab is absent from `/v1/models` and exporting it would hand the client a
  * selector the proxy refuses to route.
  */
-export async function loadExportModels(config: OcxConfig): Promise<ExportModel[]> {
-  const rows = await listManagementModelRows(config);
+export async function loadExportModels(
+  config: OcxConfig,
+  models?: readonly CatalogModel[],
+): Promise<ExportModel[]> {
+  // Initial selection adopts into the live configuration and persists it, so it has to finish
+  // before anything is admitted. Admitting first would bind this roster to bytes the same load is
+  // about to rewrite, and finalizing against a detached copy would adopt the choices into the copy
+  // while leaving the live configuration pending.
+  if (models === undefined && pendingModelSelectionProviders(config).size > 0) {
+    const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
+    await resolvePendingInitialModelSelection(config);
+  }
+  // The configuration this pass will use from beginning to end, proved to be the one on disk.
+  // Without it there is nothing that may be retained, and the caller still gets its rows: only the
+  // preview authority is withheld.
+  const admission = captureExportConfigAdmission(config);
+  const admitted = admission?.config ?? config;
+  // The gather stamps each provider as it chooses its rows, so the roster and the revisions that
+  // vouch for it come from the same moment. Sampling afterwards would let a concurrent flight's
+  // publication be recorded against rows it never produced.
+  const gathered = new Map<string, string>();
+  // Gathering here rather than through the shared fetch is what keeps the detached copy out of the
+  // initial-selection finalizer: the projection below takes a roster, and that branch performs no
+  // discovery and no configuration write. The entitlement refresh keeps the budget it has always
+  // had, and runs alongside as it did inside the projection.
+  const roster = models === undefined
+    ? (await Promise.all([
+      (await import("../../codex/catalog")).gatherRoutedModels(admitted, { providerContentRevisions: gathered }),
+      ensureCodexEntitlementFreshness(admitted, { waitMs: 3_000 }),
+    ]))[0]
+    : models;
+  const rows = await listManagementModelRows(admitted, { models: roster });
   // Management deliberately lists the full roster so hidden models can be enabled.
   // A client picker must also honor the provider selection, not just its blocklist.
-  const visibleRouted = new Set(filterCatalogVisibleModels(rows.filter(row => !row.native), config));
-  return rows.filter(row => !row.disabled && (row.native || visibleRouted.has(row))).map(toExportModel);
+  const visibleRouted = new Set(filterCatalogVisibleModels(rows.filter(row => !row.native), admitted));
+  const exported = rows.filter(row => !row.disabled && (row.native || visibleRouted.has(row))).map(toExportModel);
+  // Retain the FINAL projection, not an input to it. A preview that rebuilt from raw provider
+  // caches would miss static and forward providers, which never populate one, and would skip the
+  // retention, metadata, combo and filtering this function applies afterwards.
+  // A deep clone, not a frozen view of the caller's array. Freezing the array alone left the model
+  // objects shared, so a caller mutating one in place would have silently rewritten the roster a
+  // later preview plans against, and the fingerprint would have moved with it.
+  // Still the configuration these rows were chosen under, on disk and in hand alike. Revalidating
+  // rather than re-reading an identity is what makes this fail closed: a configuration that moved
+  // during the load leaves no snapshot rather than one recorded under a state its rows never had.
+  if (admission === null || !isExportConfigAdmissionCurrent(admission, config)) {
+    lastExportSnapshot = null;
+    return exported;
+  }
+  // Prefer the revisions the gather stamped; fall back to observing only when the roster was
+  // supplied and no gather happened, where there is nothing tighter to use.
+  const cacheStamp = gathered.size > 0 ? stampFrom(admitted, gathered) : modelCacheStamp(admitted);
+  const retained = lastExportSnapshot;
+  /*
+   * An identical roster keeps the identity it already had.
+   *
+   * The generation moved on every load, so an ordinary read that rebuilt the same rows, which the
+   * Integrations collection does, invalidated a confirmation an operator was in the middle of
+   * submitting. Nothing about the roster had changed; only the counter had. The rows themselves
+   * are compared rather than assumed equal from the configuration and the cache stamp, because a
+   * projection also reads entitlement state neither of those two describes.
+   */
+  const projection = Object.freeze(structuredClone(exported));
+  if (retained !== null
+    && retained.cacheStamp === cacheStamp
+    && isExportConfigAdmissionCurrent(retained.admission, config)
+    && JSON.stringify(retained.models) === JSON.stringify(projection)) {
+    return exported;
+  }
+  lastExportSnapshot = { admission, cacheStamp, generation: ++exportSnapshotGeneration, models: projection };
+  return exported;
+}
+
+/**
+ * The completed export roster from the last ordinary load, if it still describes this config.
+ *
+ * A preview may not gather, so it reads only what an authoritative load already finished. The
+ * admission it carries proved, when the roster was built, that the configuration in hand was the
+ * one on disk; a later read repeats that proof, so a rewritten file, an edited resident object or
+ * a mutated working copy each retire the snapshot rather than letting a preview plan against a
+ * configuration nobody has.
+ *
+ * A cold process has no snapshot and the caller answers a bounded refusal, and an ordinary load
+ * populates one: the Integrations collection read calls `loadExportModels`, so the page an
+ * operator opens before confirming anything is usually the page that fills this in. That is not a
+ * repair for every refusal. A configuration that disagrees with its file keeps refusing however
+ * many times the page is opened, because nothing here reloads or reconciles anything; once the
+ * two agree again the next ordinary read rebuilds the snapshot by itself.
+ */
+let lastExportSnapshot:
+  | { admission: ExportConfigAdmission; cacheStamp: string; generation: number; models: readonly ExportModel[] }
+  | null = null;
+let exportSnapshotGeneration = 0;
+
+/**
+ * A process-local prefix for the roster identity a caller carries between a preview and the
+ * mutation that confirms it.
+ *
+ * The identity used to be the configuration digest with a counter appended, which handed a
+ * dashboard an opaque-looking string that was in fact a fingerprint of the operator's
+ * configuration file. It only has to be unforgeable within this process and distinct across
+ * restarts, so it says nothing about the configuration at all.
+ */
+const rosterIdentityPrefix = `r${Math.trunc(Math.random() * 0xffffffff).toString(36)}`;
+
+function rosterIdentity(generation: number): string {
+  return `${rosterIdentityPrefix}:${generation}`;
+}
+
+/**
+ * Where the gathered half of the roster stands, observed without changing it.
+ *
+ * The config key cannot see a provider's models changing underneath an unchanged configuration,
+ * which is exactly what discovery does. This reads the cache's own generation for each configured
+ * provider through the passive observer, so a completed discovery retires the snapshot and a
+ * preview stops planning against a roster that no longer reflects the provider.
+ */
+function modelCacheStamp(config: OcxConfig): string {
+  return Object.keys(config.providers ?? {})
+    .sort()
+    .map(provider => `${provider}=${observeModelCacheRevision(provider)}`)
+    .join(",");
+}
+
+/**
+ * The same stamp shape, built from revisions the gather recorded rather than from observation.
+ *
+ * A provider the gather did not report falls back to observation so the stamp stays total; that
+ * happens for a provider configured after the rows were chosen, and it retires the snapshot on
+ * the next read rather than pretending the roster covered it.
+ */
+function stampFrom(config: OcxConfig, gathered: ReadonlyMap<string, string>): string {
+  return Object.keys(config.providers ?? {})
+    .sort()
+    .map(provider => `${provider}=${gathered.get(provider) ?? observeModelCacheRevision(provider)}`)
+    .join(",");
+}
+
+/**
+ * Opaque identity of the snapshot a caller is holding, or null when there is none for this config.
+ *
+ * A fingerprint check that rebuilt its own roster could validate against one snapshot while the
+ * mutation wrote from another, because an ordinary load can replace the snapshot at any moment and
+ * nothing about that is serialised against the writer lock. Carrying this identity alongside the
+ * captured roster lets a revalidation prove the snapshot it captured is still the current one
+ * without ever swapping the roster the mutation is about to use.
+ */
+export function exportSnapshotIdentity(config: OcxConfig): string | null {
+  const snapshot = lastExportSnapshot;
+  if (snapshot === null) return null;
+  if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
+  if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
+  return rosterIdentity(snapshot.generation);
+}
+
+/** Test seam: a fresh process has no snapshot, and suites must be able to reproduce that. */
+export function resetExportSnapshotForTests(): void {
+  lastExportSnapshot = null;
+}
+
+/**
+ * The export roster for a read that must change nothing at all, or null when there is not one.
+ *
+ * Skipping the initial-selection finalizer was not enough. Discovery itself refreshes credentials
+ * and writes the provider model cache, so a preview that gathered would still be a write dressed
+ * as a read, and "the models list already does this" describes what a GET happens to do rather
+ * than what a preview is allowed to do.
+ *
+ * So this reads already-captured per-provider cache entries and never fetches. When no provider
+ * has a cached roster there is no honest snapshot to plan against, and the caller reports a
+ * bounded refusal rather than triggering a gather to manufacture one.
+ */
+export function previewExportSnapshot(
+  config: OcxConfig,
+): { models: readonly ExportModel[]; identity: string } | null {
+  // One synchronous read of one const. Taking the roster and its identity in two steps let a
+  // concurrent load publish a new snapshot between them, so a caller could hold one roster while
+  // believing it held the identity of another.
+  const snapshot = lastExportSnapshot;
+  if (snapshot === null) return null;
+  // The roster was built from a configuration proved to be the one on disk; this asks whether both
+  // are still that same configuration, and reads nothing but the file to answer.
+  if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
+  // A completed discovery retires the snapshot: the configuration is unchanged, but the models it
+  // resolves to are not the ones this roster was built from.
+  if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
+  // Cloned on the way out as well as on the way in. The retained copy is the authority, and a
+  // reader holding its objects could edit the roster every later preview plans against without
+  // going anywhere near this module.
+  return {
+    models: structuredClone(snapshot.models) as readonly ExportModel[],
+    identity: rosterIdentity(snapshot.generation),
+  };
+}
+
+export function previewExportModels(config: OcxConfig): readonly ExportModel[] | null {
+  return previewExportSnapshot(config)?.models ?? null;
 }