@duckmind/dm-linux-x64 0.65.5 → 0.65.7

package/extensions/dm-lens/dist/clients/project-snapshot.js

@@ -0,0 +1,1178 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { writeFileAtomic } from "./atomic-write.js";
+import { BoundedFifoMap } from "./bounded-cache.js";
+import { getProjectDataDir } from "./file-utils.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import { readJsonCache } from "./json-cache-read.js";
+import { logLatency } from "./latency-logger.js";
+import { normalizeMapKey } from "./path-utils.js";
+import { fingerprintProjectSnapshotJson } from "./project-snapshot-fingerprint.js";
+import { detectProjectConventions } from "./project-conventions.js";
+import { deserializeWordIndex, serializeWordIndex } from "./word-index.js";
+export const PROJECT_SNAPSHOT_VERSION = 2;
+function parseSequenceIndex(value) {
+  if (!value || typeof value !== "object")
+    return;
+  const index = value;
+  if (typeof index.projectSeq !== "number")
+    return;
+  if (!Array.isArray(index.fileSeqByPath))
+    return;
+  const fileSeqByPath = index.fileSeqByPath.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "number");
+  return { projectSeq: index.projectSeq, fileSeqByPath };
+}
+export function getProjectSnapshotPath(cwd) {
+  return path.join(getProjectDataDir(cwd), "cache", "project-snapshot.json.gz");
+}
+export function getProjectSnapshotLegacyPath(cwd) {
+  return path.join(getProjectDataDir(cwd), "cache", "project-snapshot.json");
+}
+export function getProjectSnapshotMetaPath(cwd) {
+  return path.join(getProjectDataDir(cwd), "cache", "project-snapshot.meta.json");
+}
+export function isProjectSnapshotFresh(snapshot, currentProjectSeq) {
+  return !!snapshot && snapshot.version === PROJECT_SNAPSHOT_VERSION && snapshot.seq === currentProjectSeq;
+}
+function parseSnapshot(value) {
+  if (!value || typeof value !== "object")
+    return null;
+  const snapshot = value;
+  if (snapshot.version !== PROJECT_SNAPSHOT_VERSION)
+    return null;
+  if (typeof snapshot.projectRoot !== "string")
+    return null;
+  if (typeof snapshot.generatedAt !== "string")
+    return null;
+  if (typeof snapshot.seq !== "number")
+    return null;
+  if (!Array.isArray(snapshot.cachedExports))
+    return null;
+  return {
+    version: PROJECT_SNAPSHOT_VERSION,
+    projectRoot: snapshot.projectRoot,
+    generatedAt: snapshot.generatedAt,
+    seq: snapshot.seq,
+    files: snapshot.files ?? {},
+    symbols: snapshot.symbols ?? {},
+    reverseDeps: snapshot.reverseDeps ?? {},
+    cachedExports: snapshot.cachedExports.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "string"),
+    sequenceIndex: parseSequenceIndex(snapshot.sequenceIndex),
+    wordIndex: snapshot.wordIndex,
+    projectRulesScan: snapshot.projectRulesScan,
+    startupScan: snapshot.startupScan,
+    languageProfile: snapshot.languageProfile,
+    conventions: snapshot.conventions
+  };
+}
+function parseSnapshotMeta(value) {
+  if (!value || typeof value !== "object")
+    return null;
+  const meta = value;
+  if (typeof meta.version !== "number")
+    return null;
+  if (typeof meta.seq !== "number")
+    return null;
+  return {
+    timestamp: typeof meta.timestamp === "string" ? meta.timestamp : "",
+    version: meta.version,
+    seq: meta.seq,
+    fingerprint: typeof meta.fingerprint === "string" && /^[a-f0-9]{64}$/.test(meta.fingerprint) ? meta.fingerprint : undefined,
+    gzBytes: typeof meta.gzBytes === "number" && Number.isInteger(meta.gzBytes) && meta.gzBytes > 0 ? meta.gzBytes : undefined,
+    sequenceIndex: parseSequenceIndex(meta.sequenceIndex)
+  };
+}
+export function readProjectSnapshotMeta(cwd) {
+  const meta = readJsonCache(getProjectSnapshotMetaPath(cwd), (parsed) => parseSnapshotMeta(parsed) ?? undefined);
+  return meta ?? null;
+}
+export function isProjectSnapshotMetaStale(meta, currentProjectSeq) {
+  return meta.version !== PROJECT_SNAPSHOT_VERSION || meta.seq !== currentProjectSeq;
+}
+export const SNAPSHOT_PARSE_CACHE_MAX = 4;
+const SNAPSHOT_PARSE_CACHE_MAX_BYTES = 24 * 1024 * 1024;
+const snapshotParseCache = new BoundedFifoMap(SNAPSHOT_PARSE_CACHE_MAX);
+function withoutWordIndex(snapshot) {
+  if (!snapshot?.wordIndex)
+    return snapshot;
+  const { wordIndex: _releasedPostings, ...stripped } = snapshot;
+  return stripped;
+}
+function cacheParsedSnapshot(snapshotPath, entry) {
+  snapshotParseCache.delete(snapshotPath);
+  snapshotParseCache.set(snapshotPath, entry);
+}
+const authoritativeSnapshots = new Map;
+export const PROJECT_SNAPSHOT_MAX_WARM_ROOTS = 8;
+const PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT = 20 * 60000;
+function projectSnapshotIdleEvictMs() {
+  const value = Number.parseInt(process.env.DM_LENS_PROJECT_SNAPSHOT_IDLE_EVICT_MS ?? "", 10);
+  return Number.isSafeInteger(value) && value > 0 ? value : PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT;
+}
+function clearAuthoritativeSnapshotTimer(entry) {
+  if (entry.idleTimer)
+    clearTimeout(entry.idleTimer);
+  entry.idleTimer = undefined;
+}
+function deleteAuthoritativeSnapshot(key) {
+  const entry = authoritativeSnapshots.get(key);
+  if (entry)
+    clearAuthoritativeSnapshotTimer(entry);
+  authoritativeSnapshots.delete(key);
+}
+function scheduleAuthoritativeSnapshotEviction(key, entry) {
+  clearAuthoritativeSnapshotTimer(entry);
+  const generation = entry.lastUsedAt;
+  entry.idleTimer = setTimeout(() => {
+    entry.idleTimer = undefined;
+    if (authoritativeSnapshots.get(key) !== entry || entry.lastUsedAt !== generation)
+      return;
+    deleteAuthoritativeSnapshot(key);
+  }, projectSnapshotIdleEvictMs());
+  entry.idleTimer.unref?.();
+}
+function touchAuthoritativeSnapshot(key, entry) {
+  entry.lastUsedAt = Date.now();
+  scheduleAuthoritativeSnapshotEviction(key, entry);
+}
+function enforceAuthoritativeSnapshotCap() {
+  while (authoritativeSnapshots.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
+    const victim = [...authoritativeSnapshots.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+    if (!victim)
+      return;
+    clearAuthoritativeSnapshotTimer(victim[1]);
+    deleteAuthoritativeSnapshot(victim[0]);
+  }
+}
+export function _getAuthoritativeSnapshotCacheKeysForTests() {
+  return [...authoritativeSnapshots.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt).map(([key]) => key);
+}
+export function _resetProjectSnapshotParseCacheForTests() {
+  snapshotParseCache.clear();
+  for (const entry of authoritativeSnapshots.values())
+    clearAuthoritativeSnapshotTimer(entry);
+  authoritativeSnapshots.clear();
+}
+export function _projectSnapshotParseCacheRetainsWordIndexForTests() {
+  return [...snapshotParseCache.values()].some((entry) => entry.snapshot?.wordIndex !== undefined);
+}
+function resolveSnapshotBodyPath(cwd) {
+  const gzPath = getProjectSnapshotPath(cwd);
+  try {
+    const stat = fs.statSync(gzPath);
+    return { path: gzPath, gz: true, mtimeMs: stat.mtimeMs, size: stat.size };
+  } catch {}
+  const legacyPath = getProjectSnapshotLegacyPath(cwd);
+  try {
+    const stat = fs.statSync(legacyPath);
+    return {
+      path: legacyPath,
+      gz: false,
+      mtimeMs: stat.mtimeMs,
+      size: stat.size
+    };
+  } catch {
+    return null;
+  }
+}
+let _snapshotBodyReadCountForTests = 0;
+export function getSnapshotBodyReadCountForTests() {
+  return _snapshotBodyReadCountForTests;
+}
+export function resetSnapshotBodyReadCountForTests() {
+  _snapshotBodyReadCountForTests = 0;
+}
+function readSnapshotBody(bodyPath, gz) {
+  _snapshotBodyReadCountForTests++;
+  if (!gz) {
+    const snapshot = readJsonCache(bodyPath, (parsed) => parseSnapshot(parsed) ?? undefined) ?? null;
+    let rawBytes = 0;
+    try {
+      rawBytes = fs.statSync(bodyPath).size;
+    } catch {}
+    return { snapshot, rawBytes };
+  }
+  try {
+    const json = gunzipSync(fs.readFileSync(bodyPath)).toString("utf-8");
+    const snapshot = parseSnapshot(JSON.parse(json)) ?? null;
+    return { snapshot, rawBytes: Buffer.byteLength(json) };
+  } catch (err) {
+    logLatency({
+      type: "phase",
+      phase: "project_snapshot_body_corrupt",
+      filePath: bodyPath,
+      durationMs: 0,
+      metadata: { error: err instanceof Error ? err.message : String(err) }
+    });
+    return { snapshot: null, rawBytes: 0 };
+  }
+}
+function skipJsonValue(text, start) {
+  let i = start;
+  while (i < text.length && /\s/.test(text[i]))
+    i++;
+  const ch = text[i];
+  if (ch === '"') {
+    i++;
+    while (i < text.length) {
+      if (text[i] === "\\") {
+        i += 2;
+        continue;
+      }
+      if (text[i] === '"') {
+        i++;
+        break;
+      }
+      i++;
+    }
+    return i;
+  }
+  if (ch === "{" || ch === "[") {
+    const open = ch;
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    for (;i < text.length; i++) {
+      const c = text[i];
+      if (inString) {
+        if (c === "\\") {
+          i++;
+          continue;
+        }
+        if (c === '"')
+          inString = false;
+        continue;
+      }
+      if (c === '"') {
+        inString = true;
+        continue;
+      }
+      if (c === open)
+        depth++;
+      else if (c === close) {
+        depth--;
+        if (depth === 0) {
+          i++;
+          break;
+        }
+      }
+    }
+    return i;
+  }
+  while (i < text.length && !",}]".includes(text[i]))
+    i++;
+  return i;
+}
+function stripTopLevelJsonKeys(text, keysToStrip) {
+  const objStart = text.indexOf("{");
+  if (objStart === -1)
+    return text;
+  let out = text.slice(0, objStart + 1);
+  let i = objStart + 1;
+  let wroteField = false;
+  while (i < text.length) {
+    while (i < text.length && /\s/.test(text[i]))
+      i++;
+    if (text[i] === "}" || i >= text.length) {
+      out += text.slice(i);
+      break;
+    }
+    if (text[i] === ",") {
+      i++;
+      continue;
+    }
+    const keyStart = i;
+    const keyTextEnd = skipJsonValue(text, keyStart);
+    let key;
+    try {
+      key = JSON.parse(text.slice(keyStart, keyTextEnd));
+    } catch {
+      return text;
+    }
+    let j = keyTextEnd;
+    while (j < text.length && /\s/.test(text[j]))
+      j++;
+    const valueStart = j + 1;
+    const valueEnd = skipJsonValue(text, valueStart);
+    if (!keysToStrip.has(key)) {
+      out += (wroteField ? "," : "") + text.slice(keyStart, valueEnd);
+      wroteField = true;
+    }
+    i = valueEnd;
+  }
+  return out;
+}
+export function _stripTopLevelJsonKeysForTests(text, keysToStrip) {
+  return stripTopLevelJsonKeys(text, new Set(keysToStrip));
+}
+const HEAVY_SNAPSHOT_KEYS = new Set([
+  "wordIndex",
+  "files",
+  "symbols",
+  "reverseDeps"
+]);
+const NARROW_DIGEST_HEAVY_KEY_LITERALS = [
+  "wordIndex",
+  "files",
+  "symbols",
+  "reverseDeps"
+];
+let _lastNarrowParseDigestForTests;
+export function getLastNarrowParseDigestForTests() {
+  return _lastNarrowParseDigestForTests;
+}
+export function resetLastNarrowParseDigestForTests() {
+  _lastNarrowParseDigestForTests = undefined;
+}
+function parseExportsAndRulesOnly(json) {
+  const narrowed = stripTopLevelJsonKeys(json, HEAVY_SNAPSHOT_KEYS);
+  _lastNarrowParseDigestForTests = {
+    length: narrowed.length,
+    containsHeavyKey: NARROW_DIGEST_HEAVY_KEY_LITERALS.some((key) => narrowed.includes(`"${key}":`))
+  };
+  const parsed = JSON.parse(narrowed);
+  if (parsed.version !== PROJECT_SNAPSHOT_VERSION)
+    return null;
+  if (typeof parsed.seq !== "number")
+    return null;
+  if (!Array.isArray(parsed.cachedExports))
+    return null;
+  return {
+    version: PROJECT_SNAPSHOT_VERSION,
+    seq: parsed.seq,
+    cachedExports: parsed.cachedExports.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "string"),
+    projectRulesScan: parsed.projectRulesScan
+  };
+}
+function readSnapshotExportsAndRulesBody(bodyPath, gz) {
+  try {
+    const json = gz ? gunzipSync(fs.readFileSync(bodyPath)).toString("utf-8") : fs.readFileSync(bodyPath, "utf-8");
+    return parseExportsAndRulesOnly(json);
+  } catch (err) {
+    logLatency({
+      type: "phase",
+      phase: "project_snapshot_body_corrupt",
+      filePath: bodyPath,
+      durationMs: 0,
+      metadata: {
+        error: err instanceof Error ? err.message : String(err),
+        narrow: true
+      }
+    });
+    return null;
+  }
+}
+export function loadProjectSnapshotExportsAndRules(cwd) {
+  const key = normalizeMapKey(cwd);
+  const body = resolveSnapshotBodyPath(cwd);
+  const authoritative = authoritativeSnapshots.get(key);
+  if (authoritative) {
+    const notSuperseded = body === null || body.mtimeMs <= authoritative.knownMtime && body.size === authoritative.knownSize;
+    if (notSuperseded) {
+      const { version, seq, cachedExports, projectRulesScan } = authoritative.snapshot;
+      return { version, seq, cachedExports, projectRulesScan };
+    }
+  }
+  if (!body)
+    return null;
+  return readSnapshotExportsAndRulesBody(body.path, body.gz);
+}
+function loadProjectSnapshotInternal(cwd, requireWordIndex) {
+  const key = normalizeMapKey(cwd);
+  const body = resolveSnapshotBodyPath(cwd);
+  const authoritative = authoritativeSnapshots.get(key);
+  if (authoritative) {
+    const notSuperseded = body === null || body.mtimeMs <= authoritative.knownMtime && body.size === authoritative.knownSize;
+    if (notSuperseded) {
+      touchAuthoritativeSnapshot(key, authoritative);
+      return authoritative.snapshot;
+    }
+    deleteAuthoritativeSnapshot(key);
+  }
+  if (!body) {
+    snapshotParseCache.delete(getProjectSnapshotPath(cwd));
+    return null;
+  }
+  const cacheKey = body.path;
+  const cached = snapshotParseCache.get(cacheKey);
+  if (cached && cached.mtimeMs === body.mtimeMs && cached.size === body.size) {
+    if (!requireWordIndex || !cached.snapshot || cached.snapshot.wordIndex) {
+      return cached.snapshot;
+    }
+  }
+  const { snapshot, rawBytes } = readSnapshotBody(body.path, body.gz);
+  const cacheSnapshot = withoutWordIndex(snapshot);
+  if (rawBytes > 0 && (rawBytes <= SNAPSHOT_PARSE_CACHE_MAX_BYTES || snapshot?.wordIndex)) {
+    cacheParsedSnapshot(cacheKey, {
+      mtimeMs: body.mtimeMs,
+      size: body.size,
+      snapshot: cacheSnapshot
+    });
+  } else {
+    snapshotParseCache.delete(cacheKey);
+  }
+  return snapshot;
+}
+export function loadProjectSnapshot(cwd) {
+  return loadProjectSnapshotInternal(cwd, true);
+}
+export function loadProjectSnapshotWithoutWordIndex(cwd) {
+  return loadProjectSnapshotInternal(cwd, false);
+}
+const _snapshotGenerationStates = new Map;
+const _successfulSnapshotPersists = new BoundedFifoMap(PROJECT_SNAPSHOT_MAX_WARM_ROOTS);
+const _failedSnapshotPersists = new BoundedFifoMap(PROJECT_SNAPSHOT_MAX_WARM_ROOTS);
+const _activeSnapshotPersists = new Map;
+const _queuedSnapshotPersists = new Map;
+const _snapshotWorkerRequests = new Map;
+let _snapshotPersistWorker;
+let _snapshotWorkerRequestId = 0;
+let _snapshotWorkerDisabled = false;
+let _snapshotGenerationGateEnabledForTests = true;
+let _snapshotPromotionSeamForTests;
+let _lastSnapshotPersistErrorForTests;
+let _snapshotExiting = false;
+let _snapshotWorkerBodyWritesForTests = 0;
+function snapshotWorkerEnabled() {
+  const raw = process.env.DM_LENS_SNAPSHOT_PERSIST_SYNC;
+  return !(raw === "1" || raw === "true");
+}
+function pendingSnapshotIsCurrent(pending) {
+  return !_snapshotGenerationGateEnabledForTests || _snapshotGenerationStates.get(pending.key)?.generation === pending.generation;
+}
+function rememberSuccessfulSnapshotPersist(key, record) {
+  _successfulSnapshotPersists.delete(key);
+  _successfulSnapshotPersists.set(key, record);
+}
+function assessSnapshotBodyIntegrity(meta, body) {
+  if (meta.gzBytes === undefined) {
+    return { outcome: "legacy-meta", actualBytes: body.size };
+  }
+  if (!body.gz || body.size !== meta.gzBytes) {
+    return {
+      outcome: "size-mismatch",
+      expectedGzBytes: meta.gzBytes,
+      actualBytes: body.size
+    };
+  }
+  return {
+    outcome: "ok",
+    expectedGzBytes: meta.gzBytes,
+    actualBytes: body.size
+  };
+}
+function noteSnapshotBodyIntegrityWithheld(args) {
+  incrementDegradationCount({
+    kind: "snapshot-integrity",
+    subject: args.gzPath,
+    reason: args.verdict
+  });
+  logLatency({
+    type: "phase",
+    phase: "project_snapshot_body_integrity",
+    filePath: args.gzPath,
+    durationMs: 0,
+    metadata: {
+      outcome: "dedupe_withheld",
+      reason: args.verdict,
+      ...args.seq !== undefined ? { seq: args.seq } : {},
+      ...args.expectedGzBytes === undefined ? {} : { expectedGzBytes: args.expectedGzBytes },
+      actualBytes: args.actualBytes
+    }
+  });
+}
+function noteSnapshotSkipRefused(args) {
+  logLatency({
+    type: "phase",
+    phase: "project_snapshot_body_integrity",
+    filePath: args.gzPath,
+    durationMs: 0,
+    metadata: {
+      outcome: "skip_refused_rewrite",
+      reason: args.verdict,
+      seq: args.seq
+    }
+  });
+}
+function snapshotPersistBaselinesFor(cwd, key) {
+  const local = _successfulSnapshotPersists.get(key);
+  const meta = readProjectSnapshotMeta(cwd);
+  const body = resolveSnapshotBodyPath(cwd);
+  if (!meta?.fingerprint || !body) {
+    if (!body)
+      _successfulSnapshotPersists.delete(key);
+    return { fingerprints: [] };
+  }
+  const integrity = assessSnapshotBodyIntegrity(meta, body);
+  if (integrity.outcome !== "ok") {
+    noteSnapshotBodyIntegrityWithheld({
+      gzPath: getProjectSnapshotPath(cwd),
+      verdict: integrity.outcome,
+      seq: meta.seq,
+      expectedGzBytes: integrity.expectedGzBytes,
+      actualBytes: integrity.actualBytes
+    });
+    return { fingerprints: [] };
+  }
+  const durable = {
+    seq: meta.seq,
+    fingerprint: meta.fingerprint,
+    generatedAt: meta.timestamp,
+    generation: _snapshotGenerationStates.get(key)?.generation ?? 0,
+    gzBytes: meta.gzBytes
+  };
+  const fingerprints = [durable.fingerprint];
+  if (local && local.fingerprint !== durable.fingerprint) {
+    fingerprints.push(local.fingerprint);
+  }
+  return { durable, fingerprints, integrity: "ok" };
+}
+function seedSnapshotPersistBaselineFromDurable(key, durable) {
+  if (!durable || _successfulSnapshotPersists.has(key))
+    return;
+  rememberSuccessfulSnapshotPersist(key, durable);
+}
+function writeProjectSnapshotMeta(metaPath, snapshot, bodyRecord) {
+  writeFileAtomic(metaPath, JSON.stringify({
+    timestamp: bodyRecord?.generatedAt ?? snapshot.generatedAt,
+    version: snapshot.version,
+    seq: snapshot.seq,
+    ...bodyRecord ? {
+      fingerprint: bodyRecord.fingerprint,
+      ...bodyRecord.gzBytes === undefined ? {} : { gzBytes: bodyRecord.gzBytes }
+    } : {},
+    ...snapshot.sequenceIndex ? { sequenceIndex: snapshot.sequenceIndex } : {}
+  }), { bestEffort: false });
+}
+function recordSnapshotPersistFailure(pending, error, bodyPersisted = false) {
+  _lastSnapshotPersistErrorForTests = error;
+  _failedSnapshotPersists.set(pending.key, {
+    seq: pending.snapshot.seq,
+    generation: pending.generation
+  });
+  deleteAuthoritativeSnapshot(pending.key);
+  logLatency({
+    type: "phase",
+    phase: "project_snapshot_persist_failed",
+    filePath: pending.gzPath,
+    durationMs: 0,
+    metadata: {
+      error,
+      seq: pending.snapshot.seq,
+      outcome: bodyPersisted ? "metadata_repair_required" : "failed",
+      ...bodyPersisted ? { bodyPersisted: true } : {}
+    }
+  });
+}
+function logSnapshotPersistSuccess(pending, fingerprint, stats) {
+  rememberSuccessfulSnapshotPersist(pending.key, {
+    seq: pending.snapshot.seq,
+    fingerprint,
+    generatedAt: pending.snapshot.generatedAt,
+    generation: pending.generation,
+    rawBytes: stats.rawBytes,
+    gzBytes: stats.gzBytes
+  });
+  _failedSnapshotPersists.delete(pending.key);
+  logLatency({
+    type: "phase",
+    phase: "project_snapshot_persist",
+    filePath: pending.gzPath,
+    durationMs: stats.serializeMs + stats.writeMs,
+    metadata: { seq: pending.snapshot.seq, outcome: "executed", ...stats }
+  });
+}
+function logSnapshotPersistDecision(args) {
+  logLatency({
+    type: "phase",
+    phase: "project_snapshot_persist_decision",
+    filePath: getProjectSnapshotPath(args.cwd),
+    durationMs: 0,
+    metadata: {
+      seq: args.seq,
+      decision: args.decision,
+      ...args.fingerprint ? { fingerprint: args.fingerprint.slice(0, 12) } : {},
+      ...args.avoidedRawBytes === undefined ? {} : { avoidedRawBytes: args.avoidedRawBytes },
+      ...args.avoidedGzipBytes === undefined ? {} : { avoidedGzipBytes: args.avoidedGzipBytes }
+    }
+  });
+}
+function reconcileAuthoritativeAfterWrite(pending, rawBytes) {
+  const entry = authoritativeSnapshots.get(pending.key);
+  if (!entry || entry.snapshot !== pending.snapshot)
+    return;
+  if (pending.snapshot.wordIndex) {
+    try {
+      const stat = fs.statSync(pending.gzPath);
+      cacheParsedSnapshot(pending.gzPath, {
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        snapshot: withoutWordIndex(pending.snapshot)
+      });
+    } catch {}
+    deleteAuthoritativeSnapshot(pending.key);
+    logLatency({
+      type: "phase",
+      phase: "project_snapshot_word_index_released",
+      filePath: pending.gzPath,
+      durationMs: 0,
+      metadata: { rawBytes }
+    });
+    return;
+  }
+  if (rawBytes > SNAPSHOT_PARSE_CACHE_MAX_BYTES) {
+    logLatency({
+      type: "phase",
+      phase: "project_snapshot_authoritative_dropped_oversized",
+      filePath: pending.gzPath,
+      durationMs: 0,
+      metadata: { rawBytes, maxBytes: SNAPSHOT_PARSE_CACHE_MAX_BYTES }
+    });
+    deleteAuthoritativeSnapshot(pending.key);
+    return;
+  }
+  try {
+    const stat = fs.statSync(pending.gzPath);
+    entry.knownMtime = stat.mtimeMs;
+    entry.knownSize = stat.size;
+  } catch {}
+}
+function finalizeProjectSnapshotMeta(pending, record) {
+  try {
+    writeProjectSnapshotMeta(getProjectSnapshotMetaPath(pending.cwd), pending.snapshot, record);
+    return true;
+  } catch (err) {
+    recordSnapshotPersistFailure(pending, err instanceof Error ? err.message : String(err), true);
+    return false;
+  }
+}
+function completeSnapshotPersist(pending) {
+  if (_activeSnapshotPersists.get(pending.key) !== pending)
+    return;
+  _activeSnapshotPersists.delete(pending.key);
+  if (_snapshotExiting)
+    return;
+  const queued = _queuedSnapshotPersists.get(pending.key);
+  if (!queued)
+    return;
+  _queuedSnapshotPersists.delete(pending.key);
+  dispatchSnapshotPersist(queued);
+}
+function writeSnapshotBodyOnMainThread(pending, reason) {
+  if (!pendingSnapshotIsCurrent(pending)) {
+    completeSnapshotPersist(pending);
+    return;
+  }
+  if (reason) {
+    logLatency({
+      type: "phase",
+      phase: "project_snapshot_worker_fallback",
+      filePath: pending.gzPath,
+      durationMs: 0,
+      metadata: {
+        reason,
+        seq: pending.snapshot.seq,
+        degraded: reason !== "exit_hook"
+      }
+    });
+  }
+  try {
+    const serializeStarted = performance.now();
+    const json = JSON.stringify(pending.snapshot);
+    const serializeMs = performance.now() - serializeStarted;
+    const rawBytes = Buffer.byteLength(json);
+    const fingerprint = fingerprintProjectSnapshotJson(json, pending.snapshot.generatedAt);
+    if (pending.dedupeFingerprints.includes(fingerprint)) {
+      const current = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+      if (current.integrity === "ok") {
+        const prior = current.durable ?? pending.durablePersist;
+        if (authoritativeSnapshots.get(pending.key)?.snapshot === pending.snapshot) {
+          deleteAuthoritativeSnapshot(pending.key);
+        }
+        logSnapshotPersistDecision({
+          cwd: pending.cwd,
+          seq: pending.snapshot.seq,
+          fingerprint,
+          decision: "skipped_unchanged",
+          avoidedRawBytes: rawBytes,
+          avoidedGzipBytes: prior?.gzBytes
+        });
+        return;
+      }
+      if (current.integrity !== undefined) {
+        noteSnapshotSkipRefused({
+          gzPath: pending.gzPath,
+          verdict: current.integrity,
+          seq: pending.snapshot.seq
+        });
+      }
+    }
+    const writeStarted = performance.now();
+    const gzip = gzipSync(json);
+    fs.mkdirSync(path.dirname(pending.gzPath), { recursive: true });
+    writeFileAtomic(pending.gzPath, gzip, { bestEffort: false });
+    fs.rmSync(pending.legacyPath, { force: true });
+    const metadataFinalized = finalizeProjectSnapshotMeta(pending, {
+      fingerprint,
+      generatedAt: pending.snapshot.generatedAt,
+      gzBytes: gzip.byteLength
+    });
+    if (!metadataFinalized)
+      return;
+    reconcileAuthoritativeAfterWrite(pending, rawBytes);
+    logSnapshotPersistSuccess(pending, fingerprint, {
+      rawBytes,
+      gzBytes: gzip.byteLength,
+      serializeMs,
+      writeMs: performance.now() - writeStarted,
+      offloaded: false
+    });
+    if (reason)
+      _lastSnapshotPersistErrorForTests = reason;
+  } catch (err) {
+    recordSnapshotPersistFailure(pending, err instanceof Error ? err.message : String(err));
+  } finally {
+    completeSnapshotPersist(pending);
+  }
+}
+function dispatchMainThreadWriteThroughSeam(pending, reason) {
+  if (_snapshotPromotionSeamForTests) {
+    _snapshotPromotionSeamForTests().then(() => writeSnapshotBodyOnMainThread(pending, reason));
+    return;
+  }
+  writeSnapshotBodyOnMainThread(pending, reason);
+}
+function handleSnapshotWorkerResult(result) {
+  const pending = _snapshotWorkerRequests.get(result.id);
+  if (!pending) {
+    fs.rmSync(result.stagePath, { force: true });
+    return;
+  }
+  _snapshotWorkerRequests.delete(result.id);
+  if (result.error || result.rawBytes === undefined || result.gzBytes === undefined || result.serializeMs === undefined || result.writeMs === undefined || result.semanticFingerprint === undefined) {
+    fs.rmSync(result.stagePath, { force: true });
+    dispatchMainThreadWriteThroughSeam(pending, result.error ?? "invalid worker result");
+    return;
+  }
+  if (!result.skippedUnchanged)
+    _snapshotWorkerBodyWritesForTests++;
+  if (_snapshotGenerationGateEnabledForTests && _snapshotGenerationStates.get(pending.key)?.generation !== result.generation) {
+    fs.rmSync(result.stagePath, { force: true });
+    completeSnapshotPersist(pending);
+    return;
+  }
+  if (result.skippedUnchanged) {
+    const baselines = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+    if (baselines.integrity !== "ok") {
+      if (baselines.integrity !== undefined) {
+        noteSnapshotSkipRefused({
+          gzPath: pending.gzPath,
+          verdict: baselines.integrity,
+          seq: pending.snapshot.seq
+        });
+      }
+      dispatchMainThreadWriteThroughSeam(pending, "snapshot body integrity regressed");
+      return;
+    }
+    const prior = baselines.durable ?? pending.durablePersist;
+    if (authoritativeSnapshots.get(pending.key)?.snapshot === pending.snapshot) {
+      deleteAuthoritativeSnapshot(pending.key);
+    }
+    logSnapshotPersistDecision({
+      cwd: pending.cwd,
+      seq: pending.snapshot.seq,
+      fingerprint: result.semanticFingerprint,
+      decision: "skipped_unchanged",
+      avoidedRawBytes: result.rawBytes,
+      avoidedGzipBytes: prior?.gzBytes
+    });
+    completeSnapshotPersist(pending);
+    return;
+  }
+  try {
+    fs.renameSync(result.stagePath, pending.gzPath);
+    fs.rmSync(pending.legacyPath, { force: true });
+    const metadataFinalized = finalizeProjectSnapshotMeta(pending, {
+      fingerprint: result.semanticFingerprint,
+      generatedAt: pending.snapshot.generatedAt,
+      gzBytes: result.gzBytes
+    });
+    if (!metadataFinalized) {
+      completeSnapshotPersist(pending);
+      return;
+    }
+    reconcileAuthoritativeAfterWrite(pending, result.rawBytes);
+    logSnapshotPersistSuccess(pending, result.semanticFingerprint, {
+      rawBytes: result.rawBytes,
+      gzBytes: result.gzBytes,
+      serializeMs: result.serializeMs,
+      writeMs: result.writeMs,
+      offloaded: true
+    });
+    completeSnapshotPersist(pending);
+  } catch (err) {
+    fs.rm(result.stagePath, { force: true }, () => {});
+    dispatchMainThreadWriteThroughSeam(pending, err instanceof Error ? err.message : String(err));
+  }
+}
+function dispatchSnapshotPersist(pending) {
+  const baselines = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+  pending.durablePersist = baselines.durable;
+  pending.dedupeFingerprints = baselines.fingerprints;
+  seedSnapshotPersistBaselineFromDurable(pending.key, baselines.durable);
+  _activeSnapshotPersists.set(pending.key, pending);
+  if (!snapshotWorkerEnabled()) {
+    dispatchMainThreadWriteThroughSeam(pending, undefined);
+    return;
+  }
+  const worker = getSnapshotPersistWorker();
+  if (!worker) {
+    dispatchMainThreadWriteThroughSeam(pending, "persist worker unavailable");
+    return;
+  }
+  const id = ++_snapshotWorkerRequestId;
+  _snapshotWorkerRequests.set(id, pending);
+  const request = {
+    id,
+    generation: pending.generation,
+    stagePath: pending.stagePath,
+    data: pending.snapshot,
+    priorFingerprints: pending.dedupeFingerprints,
+    testDelayMs: undefined
+  };
+  try {
+    worker.postMessage(request);
+  } catch (err) {
+    _snapshotWorkerRequests.delete(id);
+    dispatchMainThreadWriteThroughSeam(pending, err instanceof Error ? err.message : String(err));
+  }
+}
+function handleSnapshotWorkerDeath(reason) {
+  _snapshotPersistWorker = undefined;
+  _snapshotWorkerDisabled = true;
+  const requests = [..._snapshotWorkerRequests.values()];
+  _snapshotWorkerRequests.clear();
+  for (const pending of requests)
+    dispatchMainThreadWriteThroughSeam(pending, reason);
+}
+function resolveSnapshotPersistWorkerPath() {
+  const candidates = [
+    new URL("./project-snapshot-persist-worker.js", import.meta.url),
+    new URL("./clients/project-snapshot-persist-worker.js", import.meta.url)
+  ];
+  for (const url of candidates) {
+    try {
+      const resolved = fileURLToPath(url);
+      if (fs.existsSync(resolved))
+        return resolved;
+    } catch {}
+  }
+  return;
+}
+function getSnapshotPersistWorker() {
+  if (_snapshotWorkerDisabled)
+    return;
+  if (_snapshotPersistWorker)
+    return _snapshotPersistWorker;
+  try {
+    const workerPath = resolveSnapshotPersistWorkerPath();
+    if (workerPath === undefined) {
+      handleSnapshotWorkerDeath("persist worker script not found in any layout");
+      return;
+    }
+    const worker = new Worker(workerPath);
+    worker.on("message", (result) => {
+      if (_snapshotPromotionSeamForTests) {
+        _snapshotPromotionSeamForTests().then(() => handleSnapshotWorkerResult(result));
+        return;
+      }
+      handleSnapshotWorkerResult(result);
+    });
+    worker.on("error", (err) => handleSnapshotWorkerDeath(err.message));
+    worker.on("exit", (code) => {
+      if (_snapshotPersistWorker === worker)
+        _snapshotPersistWorker = undefined;
+      const stranded = [..._snapshotWorkerRequests.values()];
+      if (stranded.length > 0) {
+        _snapshotWorkerRequests.clear();
+        for (const pending of stranded) {
+          dispatchMainThreadWriteThroughSeam(pending, `persist worker exited with code ${code}`);
+        }
+      }
+      if (code !== 0)
+        _snapshotWorkerDisabled = true;
+    });
+    worker.unref();
+    _snapshotPersistWorker = worker;
+    return worker;
+  } catch (err) {
+    handleSnapshotWorkerDeath(err instanceof Error ? err.message : String(err));
+    return;
+  }
+}
+const _sweptSnapshotStageDirs = new Set;
+function sweepStaleSnapshotStageFiles(cacheDir) {
+  if (_sweptSnapshotStageDirs.has(cacheDir))
+    return;
+  _sweptSnapshotStageDirs.add(cacheDir);
+  fs.readdir(cacheDir, (err, entries) => {
+    if (err)
+      return;
+    const ownMarker = `.stage-${process.pid}-`;
+    for (const entry of entries) {
+      if (!entry.startsWith("project-snapshot.json.gz.stage-"))
+        continue;
+      if (entry.includes(ownMarker))
+        continue;
+      fs.rm(path.join(cacheDir, entry), { force: true }, () => {});
+    }
+  });
+}
+let _snapshotExitHookInstalled = false;
+function ensureSnapshotPersistExitHook() {
+  if (_snapshotExitHookInstalled)
+    return;
+  _snapshotExitHookInstalled = true;
+  process.once("exit", () => {
+    _snapshotExiting = true;
+    const latestByKey = new Map;
+    for (const pending of _snapshotWorkerRequests.values()) {
+      latestByKey.set(pending.key, pending);
+    }
+    for (const pending of _queuedSnapshotPersists.values()) {
+      const prior = latestByKey.get(pending.key);
+      if (!prior || prior.generation <= pending.generation) {
+        latestByKey.set(pending.key, pending);
+      }
+    }
+    _snapshotWorkerRequests.clear();
+    _queuedSnapshotPersists.clear();
+    _activeSnapshotPersists.clear();
+    for (const pending of latestByKey.values()) {
+      if (_snapshotGenerationStates.get(pending.key)?.generation !== pending.generation)
+        continue;
+      writeSnapshotBodyOnMainThread(pending, "exit_hook");
+    }
+    _snapshotPersistWorker?.terminate();
+  });
+}
+export function saveProjectSnapshot(cwd, snapshot) {
+  const gzPath = getProjectSnapshotPath(cwd);
+  const legacyPath = getProjectSnapshotLegacyPath(cwd);
+  const metaPath = getProjectSnapshotMetaPath(cwd);
+  const cacheDir = path.dirname(gzPath);
+  const key = normalizeMapKey(cwd);
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const baselines = snapshotPersistBaselinesFor(cwd, key);
+  const priorPersist = baselines.durable;
+  logSnapshotPersistDecision({
+    cwd,
+    seq: snapshot.seq,
+    decision: "requested"
+  });
+  if (_failedSnapshotPersists.delete(key)) {
+    logSnapshotPersistDecision({ cwd, seq: snapshot.seq, decision: "retry" });
+  }
+  if (priorPersist?.seq !== snapshot.seq) {
+    writeProjectSnapshotMeta(metaPath, snapshot);
+  }
+  const priorBody = resolveSnapshotBodyPath(cwd);
+  const knownMtime = priorBody ? priorBody.mtimeMs : Number.NEGATIVE_INFINITY;
+  const knownSize = priorBody ? priorBody.size : Number.NEGATIVE_INFINITY;
+  const authoritativeEntry = {
+    snapshot,
+    knownMtime,
+    knownSize,
+    lastUsedAt: Date.now()
+  };
+  const previousAuthoritativeEntry = authoritativeSnapshots.get(key);
+  if (previousAuthoritativeEntry)
+    clearAuthoritativeSnapshotTimer(previousAuthoritativeEntry);
+  authoritativeSnapshots.set(key, authoritativeEntry);
+  scheduleAuthoritativeSnapshotEviction(key, authoritativeEntry);
+  enforceAuthoritativeSnapshotCap();
+  snapshotParseCache.delete(gzPath);
+  const generationState = _snapshotGenerationStates.get(key);
+  const generation = generationState?.seq === snapshot.seq ? generationState.generation : (generationState?.generation ?? 0) + 1;
+  _snapshotGenerationStates.set(key, { generation, seq: snapshot.seq });
+  const stagePath = `${gzPath}.stage-${process.pid}-${generation}`;
+  const pending = {
+    key,
+    cwd,
+    gzPath,
+    legacyPath,
+    stagePath,
+    snapshot,
+    generation,
+    durablePersist: priorPersist,
+    dedupeFingerprints: baselines.fingerprints
+  };
+  sweepStaleSnapshotStageFiles(cacheDir);
+  ensureSnapshotPersistExitHook();
+  if (_activeSnapshotPersists.has(key)) {
+    _queuedSnapshotPersists.set(key, pending);
+    logSnapshotPersistDecision({
+      cwd,
+      seq: snapshot.seq,
+      decision: "coalesced"
+    });
+    return;
+  }
+  dispatchSnapshotPersist(pending);
+}
+export async function waitForProjectSnapshotPersistsForTests() {
+  for (let attempts = 0;attempts < 200 && (_snapshotWorkerRequests.size > 0 || _activeSnapshotPersists.size > 0 || _queuedSnapshotPersists.size > 0); attempts++) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+export function flushProjectSnapshotPersistsForTests() {
+  const requests = [..._snapshotWorkerRequests.values()];
+  _snapshotWorkerRequests.clear();
+  for (const pending of requests) {
+    dispatchMainThreadWriteThroughSeam(pending, undefined);
+  }
+}
+export async function terminateProjectSnapshotPersistWorkerForTests() {
+  const worker = _snapshotPersistWorker;
+  if (worker)
+    await worker.terminate();
+}
+export function resetProjectSnapshotPersistWorkerForTests() {
+  _snapshotWorkerDisabled = false;
+  _snapshotGenerationGateEnabledForTests = true;
+  _snapshotPromotionSeamForTests = undefined;
+  _snapshotPersistWorker = undefined;
+  _snapshotWorkerRequests.clear();
+  _snapshotGenerationStates.clear();
+  _successfulSnapshotPersists.clear();
+  _failedSnapshotPersists.clear();
+  _activeSnapshotPersists.clear();
+  _queuedSnapshotPersists.clear();
+  _snapshotExiting = false;
+  _snapshotWorkerBodyWritesForTests = 0;
+  _lastSnapshotPersistErrorForTests = undefined;
+}
+export function getProjectSnapshotPersistStateForTests(cwd) {
+  const key = normalizeMapKey(cwd);
+  return {
+    active: _activeSnapshotPersists.has(key),
+    queued: _queuedSnapshotPersists.has(key),
+    successfulFingerprint: _successfulSnapshotPersists.get(key)?.fingerprint,
+    workerBodyWrites: _snapshotWorkerBodyWritesForTests
+  };
+}
+export function setProjectSnapshotGenerationGateForTests(enabled) {
+  _snapshotGenerationGateEnabledForTests = enabled;
+}
+export function setProjectSnapshotPromotionSeamForTests(seam) {
+  _snapshotPromotionSeamForTests = seam;
+}
+export function getProjectSnapshotPersistErrorForTests() {
+  return _lastSnapshotPersistErrorForTests;
+}
+export function _seedSnapshotParseCacheForTests(key, entry) {
+  cacheParsedSnapshot(key, entry);
+}
+export function _snapshotParseCacheKeysForTests() {
+  return [...snapshotParseCache.keys()];
+}
+export function _snapshotParseCacheGetForTests(key) {
+  return snapshotParseCache.get(key) !== undefined;
+}
+export function _seedSuccessfulSnapshotPersistForTests(key, record) {
+  rememberSuccessfulSnapshotPersist(key, record);
+}
+export function _successfulSnapshotPersistKeysForTests() {
+  return [..._successfulSnapshotPersists.keys()];
+}
+export function _successfulSnapshotPersistGetForTests(key) {
+  return _successfulSnapshotPersists.get(key) !== undefined;
+}
+export function _seedFailedSnapshotPersistForTests(key, record) {
+  _failedSnapshotPersists.set(key, record);
+}
+export function _failedSnapshotPersistKeysForTests() {
+  return [..._failedSnapshotPersists.keys()];
+}
+export function buildProjectSnapshotFromRuntime(args) {
+  return {
+    version: PROJECT_SNAPSHOT_VERSION,
+    projectRoot: normalizeMapKey(path.resolve(args.cwd)),
+    generatedAt: new Date().toISOString(),
+    seq: args.runtime.projectSeq,
+    files: {},
+    symbols: {},
+    reverseDeps: {},
+    cachedExports: [...args.runtime.cachedExports.entries()].sort((a, b) => a[0].localeCompare(b[0])),
+    sequenceIndex: {
+      projectSeq: args.runtime.projectSeq,
+      fileSeqByPath: args.runtime.getFileSeqEntries()
+    },
+    wordIndex: args.runtime.wordIndex ? serializeWordIndex(args.runtime.wordIndex) : undefined,
+    projectRulesScan: args.runtime.projectRulesScan,
+    startupScan: args.startupScan,
+    languageProfile: args.languageProfile,
+    conventions: args.conventions
+  };
+}
+export function hydrateRuntimeFromProjectSnapshot(runtime, snapshot) {
+  runtime.cachedExports.clear();
+  for (const [name, filePath] of snapshot.cachedExports) {
+    runtime.cachedExports.set(name, filePath);
+  }
+  if (snapshot.projectRulesScan) {
+    runtime.projectRulesScan = snapshot.projectRulesScan;
+  }
+  runtime.wordIndex = deserializeWordIndex(snapshot.wordIndex);
+}
+export function hydrateRuntimeFromProjectSnapshotIfIdle(runtime, snapshot) {
+  let hydratedAnything = false;
+  if (runtime.cachedExports.size === 0 && snapshot.cachedExports.length > 0) {
+    runtime.cachedExports.clear();
+    for (const [name, filePath] of snapshot.cachedExports) {
+      runtime.cachedExports.set(name, filePath);
+    }
+    hydratedAnything = true;
+  }
+  if (!runtime.projectRulesScan.hasCustomRules && runtime.projectRulesScan.rules.length === 0 && snapshot.projectRulesScan) {
+    runtime.projectRulesScan = snapshot.projectRulesScan;
+    hydratedAnything = true;
+  }
+  return hydratedAnything;
+}
+export function saveRuntimeProjectSnapshot(args) {
+  try {
+    if (typeof args.runtime.projectSeq !== "number")
+      return;
+    const existing = loadProjectSnapshot(args.cwd);
+    let conventions = args.conventions ?? existing?.conventions;
+    if (!conventions) {
+      try {
+        conventions = detectProjectConventions(args.cwd);
+      } catch (err) {
+        args.dbg?.(`project_snapshot: convention detection failed: ${err}`);
+      }
+    }
+    const snapshot = buildProjectSnapshotFromRuntime({
+      ...args,
+      startupScan: args.startupScan ?? existing?.startupScan,
+      languageProfile: args.languageProfile ?? existing?.languageProfile,
+      conventions
+    });
+    if (existing) {
+      snapshot.files = existing.files ?? {};
+      snapshot.symbols = existing.symbols ?? {};
+      snapshot.reverseDeps = existing.reverseDeps ?? {};
+      if (!snapshot.wordIndex && existing.wordIndex && existing.seq === snapshot.seq) {
+        snapshot.wordIndex = existing.wordIndex;
+      }
+    }
+    saveProjectSnapshot(args.cwd, snapshot);
+    args.dbg?.(`project_snapshot: saved seq=${snapshot.seq} exports=${snapshot.cachedExports.length}`);
+  } catch (err) {
+    args.dbg?.(`project_snapshot: save failed: ${err}`);
+  }
+}