@duckmind/dm-linux-x64 0.66.0 → 0.66.2

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

@@ -1,1178 +0,0 @@
-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}`);
-  }
-}