@mnemonik/shared 7.112.1 → 7.112.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.112.1",
+  "version": "7.112.2",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",

package/src/gitEditDetector.ts

@@ -50,8 +50,10 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
 
 /** Bounded so a pathological repo cannot stall the hook's PostToolUse turn. */
 const GIT_REV_PARSE_TIMEOUT_MS = 400;
@@ -161,6 +163,30 @@ function committedPaths(cwd: string, root: string, from: string | undefined, to:
     .map((name) => join(root, name));
 }
 
+/**
+ * Replace `file` whole: write a temporary file beside it, then rename it into
+ * place. Hook processes for one session run concurrently (parallel tool calls)
+ * and each rewrites the snapshot and the retry ledger; a plain writeFileSync
+ * truncates first, so a reader could see an empty or partial file and two
+ * writers could interleave into corrupt JSON. A rename is atomic on the same
+ * file system: a reader sees the old file or the new one. Concurrent writers
+ * still race (the last rename wins), which costs at most a re-sent report.
+ */
+function writeFileWhole(file: string, data: string): void {
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, data, { mode: 0o600 });
+    renameSync(temporary, file);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Never written, or already renamed.
+    }
+    throw error;
+  }
+}
+
 function readSnapshot(snapshotFile: string): DirtySnapshot | null {
   try {
     const parsed = JSON.parse(readFileSync(snapshotFile, 'utf8')) as
@@ -189,7 +215,7 @@ function writeRoot(snapshotFile: string, root: string, entry: RootSnapshot): voi
       roots: total > MAX_SNAPSHOT_PATHS ? { [root]: entry } : roots,
     };
     mkdirSync(dirname(snapshotFile), { recursive: true, mode: 0o700 });
-    writeFileSync(snapshotFile, JSON.stringify(snapshot), { mode: 0o600 });
+    writeFileWhole(snapshotFile, JSON.stringify(snapshot));
   } catch {
     // Best-effort: a missing snapshot degrades to "report nothing", never to a
     // wrong report.
@@ -259,3 +285,321 @@ export function addPathsToGitDirtySnapshot(snapshotFile: string, paths: string[]
     writeRoot(snapshotFile, root, entry);
   }
 }
+
+/** Largest file whose content is hashed for an edit fingerprint, in bytes. */
+const EDIT_FINGERPRINT_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The fingerprint a host sends with an edit report: the first 32 hex chars of
+ * the sha256 of the file's current content, 'absent' when the file does not
+ * exist, undefined when it cannot be read, is not a regular file, or exceeds
+ * EDIT_FINGERPRINT_MAX_BYTES (the report then carries none and counts as
+ * before).
+ *
+ * Why: a report the server recorded but answered after the host's budget
+ * stays unconfirmed here and the next carrier's diff re-sends it. The server
+ * compares the fingerprint with the last one it recorded for the path, so the
+ * re-send of unchanged content is not counted as a second edit, while any
+ * further edit changes the content and is.
+ */
+export function editFingerprint(path: string, cwd = ''): string | undefined {
+  const absolute = isAbsolute(path) ? path : join(cwd, path);
+  try {
+    const stat = statSync(absolute);
+    if (!stat.isFile() || stat.size > EDIT_FINGERPRINT_MAX_BYTES) return undefined;
+    return createHash('sha256').update(readFileSync(absolute)).digest('hex').slice(0, 32);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : undefined;
+  }
+}
+
+// ─── Bounded edit-report retry ─────────────────────────────────────────────
+//
+// An edit report the server did not confirm stays pending so a later event
+// can deliver it (CQ-033). Unbounded, that meant every later event re-sent
+// every pending path one by one with a 1.5 s timeout each, forever: a hung or
+// refusing server stalled each hook by ~1.5 s per pending path, past the
+// host's hook timeout (Codex and Grok kill the hook at 5 s; Cursor at 30 s,
+// where it also delayed the catastrophic-command deny check), and permanent
+// refusals were retried for the life of the session. One policy for every
+// host bounds it:
+//
+// - one call per hook event, inside a total time budget well under the
+//   shortest host hook timeout; attempts run a few at a time, each capped by
+//   the per-attempt timeout and by what is left of the budget;
+// - per path: the first failure retries on the next event, later failures
+//   back off exponentially; after EDIT_REPORT_RETRY.maxAttempts attempts, or
+//   EDIT_REPORT_RETRY.expiryMs after the first, the path is dropped;
+// - a permanent refusal (4xx other than 408/429, or `{ ok: false }`) drops
+//   the path at once; an answer marked `retryable: true` is not a refusal:
+//   the server could not check the credential (a database blip) or the hook's
+//   own credential could not be used this time (fetchWithHookCredential's 503
+//   marker), so it retries like any other transient failure; 429 pauses every
+//   report until its Retry-After; an event whose every attempt timed out
+//   pauses reports briefly (the server hangs);
+// - a dropped path joins the dirty snapshot exactly as a confirmed one does,
+//   so no later diff re-reports it, and the drop is logged at debug level.
+//
+// Pending state lives beside the dirty snapshot (`<snapshotFile>.retries`),
+// per session. The host's caller runs its safety/deny logic before this.
+
+export const EDIT_REPORT_RETRY = {
+  /** Total time one hook event may spend on edit reports. */
+  budgetMs: 1_500,
+  /** One report's own ceiling (the shared POST_TOOL_TIMEOUT_MS). */
+  attemptTimeoutMs: 1_500,
+  /** Reports in flight at once. */
+  concurrency: 4,
+  maxAttempts: 5,
+  /** Backoff after the second failure; doubles per failure after that. */
+  backoffBaseMs: 5_000,
+  backoffMaxMs: 5 * 60_000,
+  /** A path pending longer than this since its first attempt is dropped. */
+  expiryMs: 30 * 60_000,
+  /** Pause after an event in which every attempt timed out. */
+  hungServerPauseMs: 15_000,
+  rateLimitDefaultMs: 30_000,
+  rateLimitMaxMs: 5 * 60_000,
+  /** Oldest pending paths beyond this are dropped. */
+  maxPending: 200,
+} as const;
+
+/**
+ * The edit-report budget a hook event can still afford (CQ-033 review). The
+ * event's own work runs after its edit reports and the host kills the hook at
+ * its installed timeout, so the reports get only what is left of `deadlineMs`
+ * (the host timeout less a safety margin, measured from process start) after
+ * the time this process has already spent and `reserveMs`, the worst case of
+ * the event's own work still to come; capped at EDIT_REPORT_RETRY.budgetMs.
+ * Zero means send nothing now: every path stays pending for a later, lighter
+ * event. The per-event sums are pinned by tests/HookEventBudgets.test.ts.
+ */
+export function editReportBudgetMs(
+  deadlineMs: number,
+  reserveMs: number,
+  elapsedMs: number = performance.now()
+): number {
+  return Math.max(
+    0,
+    Math.min(EDIT_REPORT_RETRY.budgetMs, Math.floor(deadlineMs - reserveMs - elapsedMs))
+  );
+}
+
+/** What one edit report achieved, as the sending host classifies it. */
+export type EditReportResult =
+  | { kind: 'confirmed' }
+  | { kind: 'transient'; detail: string; timedOut?: boolean }
+  | { kind: 'permanent'; detail: string }
+  | { kind: 'rate_limited'; retryAfterMs?: number };
+
+/**
+ * Classify an HTTP answer to track-ide-edit. `body` is the parsed JSON, if any.
+ * `retryable: true` marks a failure that says nothing lasting (see above); an
+ * older server never sends it, so its `{ ok: false }` stays permanent.
+ */
+export function classifyEditReportResponse(
+  status: number,
+  body: unknown,
+  retryAfter?: string | null
+): EditReportResult {
+  const retryable = (body as { retryable?: unknown } | null | undefined)?.retryable === true;
+  if (status >= 200 && status < 300) {
+    const ok = (body as { ok?: unknown } | null | undefined)?.ok;
+    if (ok === true) return { kind: 'confirmed' };
+    if (ok === false && retryable) return { kind: 'transient', detail: 'ok:false retryable' };
+    if (ok === false) return { kind: 'permanent', detail: 'ok:false' };
+    return { kind: 'transient', detail: 'unreadable response' };
+  }
+  if (status === 429) {
+    const seconds = retryAfter ? Number(retryAfter) : NaN;
+    return {
+      kind: 'rate_limited',
+      ...(Number.isFinite(seconds) && seconds >= 0 ? { retryAfterMs: seconds * 1000 } : {}),
+    };
+  }
+  if (status >= 400 && status < 500 && status !== 408 && !retryable) {
+    return { kind: 'permanent', detail: `HTTP ${status}` };
+  }
+  return { kind: 'transient', detail: `HTTP ${status}` };
+}
+
+interface PendingReport {
+  attempts: number;
+  firstAt: number;
+  nextAt: number;
+}
+
+interface ReportLedger {
+  v: 1;
+  pending: Record<string, PendingReport>;
+  pausedUntil?: number;
+}
+
+function ledgerFile(snapshotFile: string): string {
+  return `${snapshotFile}.retries`;
+}
+
+function readLedger(snapshotFile: string): ReportLedger {
+  if (!snapshotFile) return { v: 1, pending: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(ledgerFile(snapshotFile), 'utf8')) as ReportLedger;
+    if (parsed?.v === 1 && typeof parsed.pending === 'object' && parsed.pending !== null) {
+      return parsed;
+    }
+  } catch {
+    // Missing or unreadable: start empty.
+  }
+  return { v: 1, pending: {} };
+}
+
+function writeLedger(snapshotFile: string, ledger: ReportLedger): void {
+  if (!snapshotFile) return;
+  try {
+    mkdirSync(dirname(snapshotFile), { recursive: true, mode: 0o700 });
+    writeFileWhole(ledgerFile(snapshotFile), JSON.stringify(ledger));
+  } catch {
+    // Best-effort: a lost ledger costs at most one extra attempt per path.
+  }
+}
+
+/** Paths whose report is pending and due now (retry on any hook event). */
+export function pendingEditReports(snapshotFile: string, now = Date.now()): string[] {
+  const ledger = readLedger(snapshotFile);
+  if ((ledger.pausedUntil ?? 0) > now) return [];
+  return Object.entries(ledger.pending)
+    .filter(([, entry]) => entry.nextAt <= now)
+    .map(([path]) => path);
+}
+
+async function attemptReport(
+  path: string,
+  send: (path: string, signal: AbortSignal) => Promise<EditReportResult>,
+  timeoutMs: number
+): Promise<EditReportResult> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<EditReportResult>((resolveTimeout) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolveTimeout({ kind: 'transient', detail: 'timeout', timedOut: true });
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      send(path, controller.signal).catch((error: unknown): EditReportResult => ({
+        kind: 'transient',
+        detail: error instanceof Error ? error.message : String(error),
+        timedOut: controller.signal.aborted,
+      })),
+      timedOut,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Report edited paths under the bounded retry policy: this event's new paths
+ * plus every pending path now due. Call once per hook event (pass `paths: []`
+ * to deliver only pending ones). Confirmed and dropped paths join the dirty
+ * snapshot; the rest stay pending for a later event.
+ */
+export async function reportEditsWithinBudget(options: {
+  snapshotFile: string;
+  paths: readonly string[];
+  send: (path: string, signal: AbortSignal) => Promise<EditReportResult>;
+  budgetMs?: number;
+  now?: () => number;
+  log?: (message: string) => void;
+}): Promise<{ confirmed: string[]; dropped: string[]; deferred: string[] }> {
+  const now = options.now ?? Date.now;
+  // Debug level: silent unless MNEMONIK_HOOK_DEBUG is set (hook stderr can
+  // reach the host's UI).
+  const log =
+    options.log ??
+    ((message: string) => {
+      if (process.env.MNEMONIK_HOOK_DEBUG) process.stderr.write(`${message}\n`);
+    });
+  const policy = EDIT_REPORT_RETRY;
+  const start = now();
+  const deadline = start + (options.budgetMs ?? policy.budgetMs);
+  const ledger = readLedger(options.snapshotFile);
+  const confirmed: string[] = [];
+  const dropped: string[] = [];
+  const drop = (path: string, why: string): void => {
+    delete ledger.pending[path];
+    dropped.push(path);
+    log(`mnemonik: edit report for ${path} dropped (${why})`);
+  };
+
+  for (const [path, entry] of Object.entries(ledger.pending)) {
+    if (start - entry.firstAt > policy.expiryMs) drop(path, 'expired');
+  }
+  for (const path of options.paths) {
+    ledger.pending[path] ??= { attempts: 0, firstAt: start, nextAt: start };
+  }
+  const due = [...new Set([...options.paths, ...Object.keys(ledger.pending)])].filter(
+    (path) => ledger.pending[path] && ledger.pending[path].nextAt <= start
+  );
+
+  let queue = (ledger.pausedUntil ?? 0) > start ? [] : due;
+  while (queue.length > 0) {
+    const remaining = deadline - now();
+    if (remaining <= 0) break;
+    const wave = queue.slice(0, policy.concurrency);
+    queue = queue.slice(policy.concurrency);
+    const timeout = Math.min(policy.attemptTimeoutMs, remaining);
+    const results = await Promise.all(
+      wave.map(async (path) => [path, await attemptReport(path, options.send, timeout)] as const)
+    );
+    const at = now();
+    let rateLimited = false;
+    for (const [path, result] of results) {
+      const entry = ledger.pending[path];
+      if (!entry) continue;
+      if (result.kind === 'confirmed') {
+        delete ledger.pending[path];
+        confirmed.push(path);
+      } else if (result.kind === 'permanent') {
+        drop(path, result.detail);
+      } else if (result.kind === 'rate_limited') {
+        rateLimited = true;
+        const pause = Math.min(
+          result.retryAfterMs ?? policy.rateLimitDefaultMs,
+          policy.rateLimitMaxMs
+        );
+        ledger.pausedUntil = Math.max(ledger.pausedUntil ?? 0, at + pause);
+        entry.nextAt = ledger.pausedUntil;
+      } else {
+        entry.attempts += 1;
+        if (entry.attempts >= policy.maxAttempts) {
+          drop(path, `${entry.attempts} attempts, last: ${result.detail}`);
+        } else {
+          entry.nextAt =
+            entry.attempts <= 1
+              ? at
+              : at +
+                Math.min(policy.backoffBaseMs * 2 ** (entry.attempts - 2), policy.backoffMaxMs);
+        }
+      }
+    }
+    if (rateLimited) break;
+    if (results.every(([, result]) => result.kind === 'transient' && result.timedOut)) {
+      ledger.pausedUntil = at + policy.hungServerPauseMs;
+      break;
+    }
+  }
+
+  const pendingPaths = Object.keys(ledger.pending);
+  if (pendingPaths.length > policy.maxPending) {
+    pendingPaths
+      .sort((a, b) => (ledger.pending[a]?.firstAt ?? 0) - (ledger.pending[b]?.firstAt ?? 0))
+      .slice(0, pendingPaths.length - policy.maxPending)
+      .forEach((path) => drop(path, 'too many pending reports'));
+  }
+  if ((ledger.pausedUntil ?? 0) <= now()) delete ledger.pausedUntil;
+  addPathsToGitDirtySnapshot(options.snapshotFile, [...confirmed, ...dropped]);
+  writeLedger(options.snapshotFile, ledger);
+  const deferred = Object.keys(ledger.pending);
+  return { confirmed, dropped, deferred };
+}

package/src/hookRuntime.ts

@@ -1,5 +1,6 @@
 import { protectWindowsDirectory, type Execute } from './runtimeSigners.js';
-import { stderr } from 'node:process';
+import { stderr, stdin } from 'node:process';
+import { HOOK_STDIN_TIMEOUT_MS } from './hookTimeouts.js';
 import { resolveProjectIdentity, type ProjectIdentityResolution } from './repositoryRoot.js';
 
 export interface ProjectIdentity {
@@ -8,18 +9,47 @@ export interface ProjectIdentity {
   projectRoot: string;
 }
 
+/**
+ * One resolution per directory per process. A hook process serves one event,
+ * and its handlers resolve the same cwd several times in sequence (each
+ * request builder, each gate report); every resolution runs `git rev-parse`
+ * with a 2 s timeout, so on a slow or hung git the repeats alone could pass
+ * the host's 5 s hook timeout. Only hook runtimes call this (short-lived
+ * processes); project setup clears it after it writes an identity.
+ */
+const identityCache = new Map<string, Promise<ProjectIdentity | null>>();
+
+/** Forget cached resolutions (after project setup wrote a `.mnemonik.json`). */
+export function clearProjectIdentityCache(): void {
+  identityCache.clear();
+}
+
 export async function findProjectIdentity(
   startCwd: string,
   options: { allowNestedInherit?: boolean; maxDepth?: number } = {}
 ): Promise<ProjectIdentity | null> {
   if (!startCwd) return null;
-  const result = await findProjectIdentityDetailed(startCwd, options);
-  if (result.kind !== 'ok') return null;
-  return {
-    projectId: result.identity.projectId,
-    projectName: result.identity.projectName,
-    projectRoot: result.root,
-  };
+  const key = JSON.stringify([
+    startCwd,
+    options.allowNestedInherit ?? null,
+    options.maxDepth ?? null,
+  ]);
+  let pending = identityCache.get(key);
+  if (!pending) {
+    pending = findProjectIdentityDetailed(startCwd, options).then((result) =>
+      result.kind === 'ok'
+        ? {
+            projectId: result.identity.projectId,
+            projectName: result.identity.projectName,
+            projectRoot: result.root,
+          }
+        : null
+    );
+    identityCache.set(key, pending);
+    // A failure is not an answer: the next caller resolves afresh.
+    pending.catch(() => identityCache.delete(key));
+  }
+  return pending;
 }
 
 export async function findProjectIdentityDetailed(
@@ -29,6 +59,64 @@ export async function findProjectIdentityDetailed(
   return resolveProjectIdentity(startCwd, options);
 }
 
+/** Largest hook payload read from stdin; a bigger one fails open. */
+export const HOOK_STDIN_MAX_BYTES = 1_048_576;
+
+/**
+ * Read a hook's stdin payload, bounded in size and in time. Resolves the text
+ * (a leading BOM removed) when the host closes stdin, or when `timeoutMs`
+ * passes first: then with whatever arrived, which the caller parses like any
+ * other payload (a partial one fails to parse and the hook fails open).
+ * Resolves null past `maxBytes` or on a stream error. After the timeout or
+ * the cap the stream is destroyed, so an unclosed pipe no longer holds the
+ * process open (Grok's hook returns without calling exit).
+ */
+export function readHookStdin(
+  options: {
+    stream?: NodeJS.ReadableStream & { destroy?: () => void };
+    timeoutMs?: number;
+    maxBytes?: number;
+  } = {}
+): Promise<string | null> {
+  const stream = options.stream ?? stdin;
+  const maxBytes = options.maxBytes ?? HOOK_STDIN_MAX_BYTES;
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    const text = () =>
+      Buffer.concat(chunks)
+        .toString('utf8')
+        .replace(/^\uFEFF/, '');
+    const finish = (value: string | null, release: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stream.removeListener('data', onData);
+      stream.removeListener('end', onEnd);
+      if (release) {
+        stream.pause();
+        stream.destroy?.();
+      }
+      resolve(value);
+    };
+    const onData = (chunk: Buffer | string) => {
+      const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+      bytes += buffer.length;
+      if (bytes > maxBytes) return finish(null, true);
+      chunks.push(buffer);
+    };
+    const onEnd = () => finish(text(), false);
+    const timer = setTimeout(
+      () => finish(text(), true),
+      options.timeoutMs ?? HOOK_STDIN_TIMEOUT_MS
+    );
+    stream.on('data', onData);
+    stream.on('end', onEnd);
+    stream.on('error', () => finish(null, false));
+  });
+}
+
 let mismatchEmitted = false;
 
 export async function parseHookResponse<T>(response: Response): Promise<T> {

package/src/hookTimeouts.ts

@@ -47,6 +47,49 @@ export const POST_TOOL_TIMEOUT_MS = 1500;
  */
 export const MCP_PRECHECK_TIMEOUT_MS = 1000;
 
+/**
+ * PreCompact snapshot POST budget (Claude Code and Cursor; Grok keeps a pinned
+ * copy). Independent of FETCH_TIMEOUT_MS: the snapshot is the one hook call
+ * whose server work is a write the compaction depends on.
+ */
+export const PRECOMPACT_TIMEOUT_MS = 4000;
+
+/**
+ * The timeout each host is installed with for every Mnemonik hook event: the
+ * host kills the hook at this. The installers write these values (seconds =
+ * value / 1000), so a hook event's worst case is checked against the number
+ * the host actually enforces (tests/HookEventBudgets.test.ts).
+ */
+export const HOST_HOOK_TIMEOUT_MS = {
+  claude_code: 5000,
+  copilot: 5000,
+  codex: 5000,
+  grok: 5000,
+  cursor: 30_000,
+} as const;
+export type HookHost = keyof typeof HOST_HOOK_TIMEOUT_MS;
+
+/**
+ * Time every hook event keeps free below its host's timeout: Node start-up,
+ * project identity on a healthy git, local file I/O, writing the answer.
+ * Reading stdin has its own bound below. An event's summed worst case must
+ * fit the rest.
+ */
+export const HOOK_TIMEOUT_MARGIN_MS = 500;
+
+/**
+ * The longest a hook waits for its host to finish writing and close stdin
+ * (readHookStdin). Hosts write the payload at spawn and close the pipe; one
+ * that never closes it would otherwise hold the hook until the host kills it.
+ * On expiry the hook works with what arrived, or fails open.
+ */
+export const HOOK_STDIN_TIMEOUT_MS = 500;
+
+/** The latest an event's own work may run to, measured from process start. */
+export function hookDeadlineMs(host: HookHost): number {
+  return HOST_HOOK_TIMEOUT_MS[host] - HOOK_TIMEOUT_MARGIN_MS - HOOK_STDIN_TIMEOUT_MS;
+}
+
 /**
  * Spawn an `AbortController` tied to a timeout. Returns the signal plus a
  * `cleanup` function the caller MUST invoke (in `finally`) to clear the

package/src/index.ts

@@ -59,6 +59,12 @@ export {
   TELEMETRY_TIMEOUT_MS,
   POST_TOOL_TIMEOUT_MS,
   MCP_PRECHECK_TIMEOUT_MS,
+  PRECOMPACT_TIMEOUT_MS,
+  HOST_HOOK_TIMEOUT_MS,
+  HOOK_TIMEOUT_MARGIN_MS,
+  HOOK_STDIN_TIMEOUT_MS,
+  hookDeadlineMs,
+  type HookHost,
   withHookTimeout,
 } from './hookTimeouts.js';
 export {

package/src/projectIdentityFile.ts

@@ -98,10 +98,18 @@ export async function readIdentityFile(
     const text = await readFile(path, 'utf8');
     if (options.selectedRoot) {
       // A ticked folder with configuration but no identity is a new project.
-      // Keep invalid identities and non-regular files on the strict refusal path.
+      // Keep invalid identities, non-regular files and any file that names a
+      // schema other than 1 on the strict refusal path: a later schema may carry
+      // its identity under other keys, and setup must not replace it.
       try {
         const value: unknown = JSON.parse(text);
-        if (value && typeof value === 'object' && !Array.isArray(value) && !('projectId' in value))
+        if (
+          value &&
+          typeof value === 'object' &&
+          !Array.isArray(value) &&
+          !('projectId' in value) &&
+          (!('schemaVersion' in value) || value.schemaVersion === 1)
+        )
           return { kind: 'absent' };
       } catch {
         /* The strict parser supplies the diagnostic. */