@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/integrations/config-io.ts

@@ -10,7 +10,7 @@
 import { lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import type { ConfigFormat } from "../clients/config-export";
 import { MAX_JSON_NESTING } from "./serialize";
-import { atomicWriteFile } from "../config";
+import { atomicWriteFileNoFollow, isMissingPathError } from "../config/atomic-write";
 import type { JournalEntry } from "./journal";
 import type { OwnershipRecord } from "./ownership";
 import type { IntegrationClientId } from "./registry";
@@ -192,6 +192,15 @@ export type ReadResult =
 
 export type StatKind = "file" | "dir" | "other" | "missing" | "failed";
 
+function lstatKind(path: string): StatKind {
+  try {
+    const stats = lstatSync(path);
+    return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
+  }
+}
+
 export interface IntegrationIO {
   /**
    * ONLY a missing file yields `missing`. Every other failure (EACCES, EPERM,
@@ -234,6 +243,18 @@ export type TargetState =
  * an unreadable config gets clobbered.
  */
 export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
+  // Managed client paths are a lower-trust boundary. Never inspect through a
+  // final symlink that can be retargeted between this read and the eventual
+  // write: when a no-follow probe exists, the named directory entry itself must
+  // be a regular file or absent. `missing` stays legal so a virtual pair probe
+  // (such as Cline's pair-aware statKind) can still report one absent member.
+  const named = io.lstatKind?.(configPath);
+  // A failed probe is uncertainty, not evidence about the entry's shape: it
+  // keeps the read-failed classification the follow-probe would have produced.
+  if (named === "failed") return { ok: false, why: "read-failed" };
+  if (named !== undefined && named !== "file" && named !== "missing") {
+    return { ok: false, why: "not-regular-file" };
+  }
   const kind = io.statKind(configPath);
   if (kind === "missing") return { ok: true, before: null };
   if (kind === "failed") return { ok: false, why: "read-failed" };
@@ -252,14 +273,7 @@ export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
  */
 export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "dropRecord"> {
   return {
-    lstatKind: path => {
-      try {
-        const stats = lstatSync(path);
-        return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
-      } catch (error) {
-        return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
-      }
-    },
+    lstatKind,
     readText: path => {
       try {
         return { kind: "text", text: readFileSync(path, "utf8") };
@@ -277,8 +291,28 @@ export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "d
       }
     },
     writeText: (path, text) => {
+      const kind = lstatKind(path);
+      if (kind !== "file" && kind !== "missing") {
+        throw new Error(`refusing unsafe integration write target: ${path}`);
+      }
       assertIntegrationWriteOwnership(path);
-      atomicWriteFile(path, text);
+      atomicWriteFileNoFollow(path, text, undefined, {
+        // The pre-check above rejects a symlink already in place; this one runs
+        // inside the atomic write immediately before the rename, so a link
+        // exchanged after validation is refused rather than followed. Even a
+        // swap past this point can only replace the named entry, never redirect
+        // the write through it.
+        validateBeforeRename: target => {
+          try {
+            if (lstatSync(target).isSymbolicLink()) {
+              throw new Error(`refusing to replace symbolic-link integration target: ${target}`);
+            }
+          } catch (error) {
+            if (isMissingPathError(error)) return;
+            throw error;
+          }
+        },
+      });
     },
     removeFile: path => rmSync(path, { force: true }),
     mkdirp: path => mkdirSync(path, { recursive: true, mode: 0o700 }),

package/src/integrations/merge.ts

@@ -9,7 +9,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/031_wp3_writer_impl.md.
  */
-import type { ManagedContribution } from "../clients/config-export";
+import type { ManagedContribution } from "../clients/config-export/contracts";
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -22,20 +22,87 @@ function clone<T>(value: T): T {
 
 /**
  * `[field=value]` addresses the ONE element of a sequence whose `field` equals
- * `value`. Raycast keeps its providers as a YAML list, so the element is the
+ * `value`, and `[v2:field=value,field=value]` the one whose every named field
+ * matches. Raycast keeps its providers as a YAML list, so the element is the
  * smallest thing we can own there; an index would move under us the moment
  * the user reordered their own entries. Any other segment is a plain key.
+ *
+ * A conjunction exists because one field is not always the identity. ZCode
+ * keys a model rule in its provider store by the PAIR `(providerId, modelId)`,
+ * so a `[modelId=…]` selector alone would match another provider's rule for the
+ * same model and then replace it, in a file holding every provider the user
+ * has. Addressing an element by less than what identifies it is the same
+ * defect as addressing it by index.
+ *
+ * The single-criterion spelling keeps its original grammar, where the value may
+ * itself contain commas and equals signs. A conjunction uses an explicit v2
+ * marker, so no path already written into an ownership record on disk changes
+ * meaning. Once the marker is present the whole segment must be valid; falling
+ * back to a key or v1 selector would recreate the silent reselection hazard.
  */
 const ARRAY_SELECTOR = /^\[([A-Za-z_][A-Za-z0-9_]*)=([^\]]+)\]$/u;
+const SELECTOR_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const SELECTOR_CONJUNCTION_PREFIX = "[v2:";
+
+/** One `field=value` equality a selector requires of the element it names. */
+export interface SelectorCriterion {
+  field: string;
+  value: string;
+}
 
 export type PathSegment =
   | { kind: "key"; key: string }
-  | { kind: "select"; field: string; value: string };
+  | { kind: "select"; criteria: readonly SelectorCriterion[] };
+
+/** A reserved v2 selector marker was present, but its complete grammar was not. */
+export class InvalidSelectorError extends Error {
+  constructor() {
+    super("invalid versioned selector");
+    this.name = "InvalidSelectorError";
+  }
+}
+
+function validConjunctionCriteria(criteria: readonly SelectorCriterion[]): boolean {
+  return criteria.length >= 2 && criteria.every(criterion => (
+    SELECTOR_FIELD.test(criterion.field)
+    && criterion.value.length > 0
+    && !criterion.value.includes(",")
+    && !criterion.value.includes("]")
+  ));
+}
+
+/** Spell a multi-field selector without colliding with persisted v1 paths. */
+export function formatSelectorConjunction(criteria: readonly SelectorCriterion[]): string | null {
+  if (!validConjunctionCriteria(criteria)) return null;
+  return `${SELECTOR_CONJUNCTION_PREFIX}${criteria
+    .map(criterion => `${criterion.field}=${criterion.value}`)
+    .join(",")}]`;
+}
 
 export function parseSegment(raw: string): PathSegment {
+  if (raw.startsWith(SELECTOR_CONJUNCTION_PREFIX)) {
+    if (!raw.endsWith("]")) throw new InvalidSelectorError();
+    const parts = raw.slice(SELECTOR_CONJUNCTION_PREFIX.length, -1).split(",");
+    const criteria = parts.map(part => {
+      const equals = part.indexOf("=");
+      return equals < 0
+        ? { field: "", value: "" }
+        : { field: part.slice(0, equals), value: part.slice(equals + 1) };
+    });
+    if (!validConjunctionCriteria(criteria)) throw new InvalidSelectorError();
+    return {
+      kind: "select",
+      criteria,
+    };
+  }
   const match = ARRAY_SELECTOR.exec(raw);
   if (!match) return { kind: "key", key: raw };
-  return { kind: "select", field: match[1]!, value: match[2]! };
+  return { kind: "select", criteria: [{ field: match[1]!, value: match[2]! }] };
+}
+
+/** The `field=value` list a selector segment spells, for messages and seeding. */
+export function selectorPairs(criteria: readonly SelectorCriterion[]): string {
+  return criteria.map(criterion => `${criterion.field}=${criterion.value}`).join(", ");
 }
 
 /**
@@ -44,19 +111,21 @@ export function parseSegment(raw: string): PathSegment {
  * this to an `unsafe` refusal instead.
  */
 export class AmbiguousSelectorError extends Error {
-  constructor(field: string, value: string) {
-    super(`more than one entry has ${field}=${value}`);
+  constructor(criteria: readonly SelectorCriterion[]) {
+    super(`more than one entry has ${selectorPairs(criteria)}`);
     this.name = "AmbiguousSelectorError";
   }
 }
 
 /** The index of the element a selector names, -1 when none matches. */
-export function selectIndex(items: readonly unknown[], field: string, value: string): number {
+export function selectIndex(items: readonly unknown[], criteria: readonly SelectorCriterion[]): number {
   const matches: number[] = [];
   items.forEach((item, index) => {
-    if (isPlainRecord(item) && item[field] === value) matches.push(index);
+    if (isPlainRecord(item) && criteria.every(criterion => item[criterion.field] === criterion.value)) {
+      matches.push(index);
+    }
   });
-  if (matches.length > 1) throw new AmbiguousSelectorError(field, value);
+  if (matches.length > 1) throw new AmbiguousSelectorError(criteria);
   return matches[0] ?? -1;
 }
 
@@ -64,6 +133,44 @@ function assertNever(segment: never): never {
   throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
 }
 
+/** The element a selector names, or `undefined` when none matches. */
+function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
+  return items[selectIndex(items, segment.criteria)];
+}
+
+/**
+ * Read `path` through the same segment grammar `setPath` writes through.
+ *
+ * It belongs here rather than beside the classifier because the grammar does: a
+ * reader that resolved a selector differently from the writer would report one
+ * element as ours and then rewrite another. `state` re-exports it for the
+ * callers that have always imported it from there.
+ */
+export function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor: unknown = doc;
+  // Validate the complete persisted grammar before document shape can short-circuit
+  // the walk. Otherwise an absent early key can hide a malformed later selector,
+  // making an unreadable ownership record look absent and move the operation to a
+  // different file.
+  const segments = path.map(parseSegment);
+  for (const segment of segments) {
+    switch (segment.kind) {
+      case "key":
+        if (!isPlainRecord(cursor)) return undefined;
+        cursor = cursor[segment.key];
+        break;
+      case "select":
+        if (!Array.isArray(cursor)) return undefined;
+        cursor = selectElement(cursor, segment);
+        break;
+      default:
+        return assertNever(segment);
+    }
+    if (cursor === undefined) return undefined;
+  }
+  return cursor;
+}
+
 /**
  * Write `value` at `path`, creating intermediate containers. Returns a new document.
  *
@@ -99,7 +206,7 @@ export function setPath(doc: unknown, path: readonly string[], value: unknown):
       case "select": {
         if (!Array.isArray(read())) write([]);
         const items = read() as unknown[];
-        const found = selectIndex(items, segment.field, segment.value);
+        const found = selectIndex(items, segment.criteria);
         parent = items;
         if (found >= 0) {
           slot = found;
@@ -107,7 +214,7 @@ export function setPath(doc: unknown, path: readonly string[], value: unknown):
           // Seed the element so the selector stays true for whatever a deeper
           // segment writes into it; a last-position select replaces it whole.
           slot = items.length;
-          items.push({ [segment.field]: segment.value });
+          items.push(Object.fromEntries(segment.criteria.map(criterion => [criterion.field, criterion.value])));
         }
         break;
       }
@@ -155,7 +262,7 @@ export function deletePath(
       }
       case "select": {
         if (!Array.isArray(container)) return { doc: root, removed: false };
-        const found = selectIndex(container, segment.field, segment.value);
+        const found = selectIndex(container, segment.criteria);
         if (found < 0) return { doc: root, removed: false };
         slots.push(found);
         chain.push(container[found] as Record<string, unknown> | unknown[]);
@@ -249,7 +356,7 @@ export function createdContainerPaths(
         case "select": {
           // A selector that matches nothing means setPath will push the element.
           next = Array.isArray(cursor)
-            ? cursor[selectIndex(cursor, segment.field, segment.value)]
+            ? cursor[selectIndex(cursor, segment.criteria)]
             : undefined;
           break;
         }

package/src/integrations/mutation-plan.ts

@@ -17,12 +17,23 @@ import { createHash } from "node:crypto";
 import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
 import { ClientPathError, EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { OPENCODE_PROVIDER_ID } from "../clients/config-export/constants";
+import {
+  ZCODE_STORE_MODEL_RULES_PATH,
+  ZCODE_STORE_PROVIDER_RULES_PATH,
+} from "../clients/config-export/zcode-store";
 import { createClineIO, ClineTransactionError } from "./cline-io";
 import { parseClineDocument } from "./cline-document";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
-import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
+import {
+  INTEGRATION_CLIENTS,
+  isLoopbackOnly,
+  resolveIntegrationPaths,
+  type IntegrationClientId,
+} from "./registry";
+import { declaredIntegrationTarget, resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { classifyIntegration, exportContextOf, readPath, type IntegrationState, type StateReason } from "./state";
+import { InvalidSelectorError } from "./merge";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import type { OcxConfig } from "../types";
 import { matchesOperationResult, type JournalEntry } from "./journal";
@@ -37,6 +48,7 @@ export type RefusalReason =
   | "conflict"
   | "unsafe"
   | "non_loopback"
+  | "superseded_store"
   | "drift_requires_confirm"
   | "snapshot_expired"
   | "write_failed";
@@ -114,7 +126,16 @@ const CLIENT_MANAGED_PATHS = {
   gajae: [["providers", OPENCODE_PROVIDER_ID]],
   dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID]],
   mcode: [["custom_provider", OPENCODE_PROVIDER_ID]],
-  zcode: [["provider", OPENCODE_PROVIDER_ID]],
+  zcode: [
+    ["provider", OPENCODE_PROVIDER_ID],
+    /*
+     * The store the current client reads. The model rule carries the model id in
+     * its own selector, so the published segment is the dynamic one: the template
+     * leaves this module, never the observed path.
+     */
+    [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
+    [...ZCODE_STORE_MODEL_RULES_PATH, DYNAMIC_SEGMENT],
+  ],
   prime: [["providers", OPENCODE_PROVIDER_ID]],
   aside: [["providers", OPENCODE_PROVIDER_ID]],
   raycast: [["providers", `[id=${OPENCODE_PROVIDER_ID}]`]],
@@ -205,6 +226,18 @@ export interface PlanFingerprintInput {
    * plan that did not bind it could be confirmed after the proxy stopped being a legal target.
    */
   readonly admissionBlocked: boolean;
+  /**
+   * Why a write to the target would not reach the client, or null.
+   *
+   * Bound for the same reason `installKind` is: it can flip without touching the
+   * file, the record or the contribution. A client that creates its new store
+   * while a confirmation is outstanding has changed whether the write can reach
+   * it, and a plan that did not bind this would still authorize the write. The
+   * reason travels with the location because both can move on their own: a store
+   * whose schema version changes under an unchanged path is the same class of
+   * flip as a store appearing.
+   */
+  readonly ineffectiveWrite: string | null;
   /** Exact current bytes, or null when the target is missing. Missing and empty are not equal. */
   readonly before: string | null;
   readonly contribution: ManagedContribution | null;
@@ -226,7 +259,7 @@ export interface PlanFingerprintInput {
   };
 }
 
-const PLAN_FINGERPRINT_VERSION = "p1";
+const PLAN_FINGERPRINT_VERSION = "p2";
 
 function digest(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 32);
@@ -251,6 +284,7 @@ export function planFingerprint(input: PlanFingerprintInput): string {
     input.detectDir,
     input.installKind,
     input.admissionBlocked,
+    input.ineffectiveWrite,
     input.before === null ? "\u0000absent" : fingerprint(input.before),
     input.contribution === null ? null : fingerprint(canonicalContribution(input.contribution)),
     input.record === null ? null : fingerprint(JSON.stringify(input.record)),
@@ -305,6 +339,13 @@ function foreignEditOf(input: PlanInput): IntegrationPlanForeignEdit {
 function applyOutcome(input: PlanInput): PlanOutcome {
   if (input.installKind !== "dir") return deny("not_installed");
   if (input.admissionBlocked) return deny("non_loopback");
+  /*
+   * Before any file state. The document may be perfectly writable and our block
+   * may already be current in it; neither says anything about whether the
+   * client reads it, and reporting a change to a file nobody opens is the
+   * defect this refusal exists for.
+   */
+  if (input.ineffectiveWrite !== null) return deny("superseded_store");
   // Overwrite exists precisely to proceed through a conflict the operator has been shown.
   if (input.classified.state === "conflict" && input.operation !== "overwrite") return deny("conflict");
   if (input.classified.state === "unsafe") return deny("unsafe");
@@ -400,7 +441,20 @@ function changesOf(input: PlanInput): readonly IntegrationPlanChange[] {
      */
     const documentKnown = input.parsed !== PARSE_FAILED;
     for (const [path, fragment] of prior) {
-      const absent = documentKnown && readPath(input.parsed, fragment) === undefined;
+      let absent = false;
+      if (documentKnown) {
+        try {
+          absent = readPath(input.parsed, fragment) === undefined;
+        } catch (error) {
+          /*
+           * Restore eligibility is byte-based and does not parse ownership paths.
+           * A malformed versioned selector therefore makes this ONE descriptive
+           * comparison unknown; it must not make preview execute a different
+           * selector, and it must not hide the backup behind an internal error.
+           */
+          if (!(error instanceof InvalidSelectorError)) throw error;
+        }
+      }
       changes.push({ kind: absent ? "add" : "replace", path });
     }
     for (const fragment of input.record?.fragmentPaths ?? []) {
@@ -514,9 +568,16 @@ export function observeRestore(
     return { failed: observationFailure("unsafe", "unsafe", "that operation cannot be undone") } as const;
   }
   const configPath = entry.configPath;
-  // An undo acts on the path the operation was journaled against. A row recorded for one home must
-  // never be allowed to rewrite a file in another.
-  if (resolved.configPath !== configPath) {
+  /*
+   * An undo acts on the path the operation was journaled against. A row recorded for one home must
+   * never be allowed to rewrite a file in another — but a client may legally have written more than
+   * one file, so the test is whether this client still names that location, not whether it is the
+   * config file. The answer also carries the document shape those bytes are in.
+   */
+  const rowTarget = declaredIntegrationTarget({
+    clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home,
+  });
+  if (rowTarget === null) {
     return {
       failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"),
     } as const;
@@ -546,6 +607,7 @@ export function observeRestore(
     failed: undefined,
     clientId,
     configPath,
+    format: rowTarget.format,
     detectDir: resolved.detectDir,
     installKind: io.statKind(resolved.detectDir),
     entry,
@@ -589,6 +651,7 @@ export function previewIntegration(input: IntegrationWriteInput, request: Previe
     installKind: observed.io.statKind(observed.detectDir),
     // Loopback-only clients cannot carry the admission header a non-loopback bind requires.
     admissionBlocked: isLoopbackOnly(observed.clientId) && shouldInjectApiAuthHeader(input.config),
+    ineffectiveWrite: observed.ineffectiveWrite,
     before: observed.before,
     contribution: observed.contribution,
     record: observed.record,
@@ -659,6 +722,13 @@ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest):
     detectDir: observed.detectDir,
     installKind: observed.installKind,
     admissionBlocked: false,
+    /*
+     * Undo puts back bytes this project already wrote to this file. Whether the
+     * client still reads the file does not change whether those bytes may be
+     * restored, and refusing here would strand a user on a state they asked to
+     * leave.
+     */
+    ineffectiveWrite: null,
     before: observed.before,
     contribution: null,
     // Descriptive, never decisive. The record says which places are ours now and the document
@@ -673,7 +743,7 @@ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest):
       ? {}
       : observed.clientId === "cline"
         ? parseClineDocument(observed.before)
-        : parseConfig(observed.before, EXPORT_CLIENTS[observed.clientId].format),
+        : parseConfig(observed.before, observed.format),
     restore: {
       opId: observed.entry.opId,
       entry: observed.entry,
@@ -757,6 +827,8 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
    */
   let configPath: string;
   let detectDir: string;
+  let effective: IntegrationTarget;
+  let stored: OwnershipRecord | null;
   try {
     /*
      * Resolve the PAIR, never one half.
@@ -768,9 +840,26 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
      * verify account 1 was installed and then write account 0's catalog.
      */
     const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
-    configPath = resolved.configPath;
     detectDir = resolved.detectDir;
-    if (clientId === "cline") io = createClineIO(io, configPath, store, effects.recover);
+    if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover);
+    /*
+     * A record proves ownership of the file it was written FOR, and it is also
+     * one of the inputs the target is chosen from: a block we already wrote to
+     * the config file keeps this operation on that file, so disable removes what
+     * we wrote from where we wrote it. Matching by path happens after the
+     * target is known, because that is the path it has to match.
+     */
+    stored = store.readRecords()[clientId] ?? null;
+    /*
+     * Inside the same guard as resolution, because this resolver can refuse the
+     * same way: the store is named by a client env var, and a relative one is a
+     * misconfiguration to report rather than an exception to leak through the
+     * collection route.
+     */
+    effective = resolveIntegrationTarget({
+      clientId, configPath: resolved.configPath, io, record: stored, env: input.env, home: input.home,
+    });
+    configPath = effective.configPath;
   } catch (error) {
     if (error instanceof ClineTransactionError) {
       return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
@@ -781,26 +870,31 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
   // Pruning writes, so only a mutation may perform it. Preview reports the state it finds.
   if (effects.maintenance) store.retryPendingPrunes();
 
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) {
     return {
       failed: observationFailure("unsafe", "unsafe",
-        target.why === "read-failed"
+        loaded.why === "read-failed"
           ? `${configPath} exists but could not be read`
           : `${configPath} is not a regular file`),
     } as const;
   }
-  const before = target.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
+  const before = loaded.before;
+  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, effective.format);
   if (parsed === PARSE_FAILED) {
     return { failed: observationFailure("unsafe", "unsafe",
       `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
   }
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
+  /*
+   * The shape the TARGET's reader understands, which is not always the
+   * client's config format: a client that moved its providers to another file
+   * reads a different document there, and a write in the config file's shape
+   * would be as unread as a write to the config file itself.
+   */
+  const contribution = effective.buildContribution(exportContextOf(input));
   // A record proves ownership of the file it was written FOR. Matching only by
   // client id let a record for one home authorize a write to another whose
   // bytes happened to hash the same — which deleted a config we never touched.
-  const stored = store.readRecords()[clientId] ?? null;
   const record = stored && stored.clientId === clientId && stored.configPath === configPath
     ? stored
     : null;
@@ -810,6 +904,18 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
   // ownership here and disable would delete fragments it never wrote.
   const classified = classifyIntegration({
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
+    format: effective.format,
   });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
+  return {
+    failed: undefined, store, io, clientId, spec, exportSpec, target: effective, configPath, detectDir,
+    /*
+     * One token for the plan, because the location alone is not the input: a
+     * store whose schema stops being one we recognise changes the answer while
+     * its path stays exactly the same.
+     */
+    ineffectiveWrite: effective.ineffective === null
+      ? null
+      : `${effective.ineffective.why}\u0000${effective.ineffective.store}`,
+    before, parsed, contribution, record, classified,
+  } as const;
 }

package/src/integrations/registry.ts

@@ -43,6 +43,11 @@ import {
   raycastConfigPath,
   zcodeConfigPath,
   zcodeHomeDir,
+  zcodeProviderStorePath,
+  buildZcodeStoreContribution,
+  zcodeStoreSchemaEstablished,
+  type BuildContribution,
+  type ConfigFormat,
   type ExportClientId,
 } from "../clients/config-export";
 
@@ -58,6 +63,28 @@ export interface IntegrationClientSpec {
   configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
   detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /**
+   * The provider store this client reads INSTEAD of `configPath`.
+   *
+   * A client that moves its store between releases usually keeps a one-shot
+   * import from the old location, and that import is exactly what makes the old
+   * write look like it still works: it runs once, on an install that has never
+   * created the new file, and never again. Everything after it lands in a file
+   * the client does not open.
+   *
+   * A declaration carries everything needed to write the store, not only its
+   * location: the text format, the contribution shape its reader understands,
+   * and the predicate that says whether a document on disk is a version whose
+   * shape has been observed. The last one is what keeps this honest — a store
+   * we cannot establish is reported as the reason the write cannot reach the
+   * client, never merged into on a guess.
+   */
+  currentStore?: {
+    path: (env?: NodeJS.ProcessEnv, home?: string) => string;
+    format: ConfigFormat;
+    establishes: (parsed: unknown) => boolean;
+    buildContribution: BuildContribution;
+  };
   /** Patch only this block-map YAML leaf; never re-render the shared file. */
   sourcePreservingYaml?: { path: readonly string[] };
   /** Coordinate the complete mutation through a sibling config lock. */
@@ -231,6 +258,17 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     id: "zcode",
     configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+    /*
+     * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches
+     * `v2/config.json` only through the import that seeded it. Where the new
+     * file exists the import is spent, so our write is read by nobody (#5348).
+     */
+    currentStore: {
+      path: (env = process.env, home = homedir()) => zcodeProviderStorePath(env, home),
+      format: "json",
+      establishes: zcodeStoreSchemaEstablished,
+      buildContribution: buildZcodeStoreContribution,
+    },
   },
   prime: {
     id: "prime",