@duckmind/dm-linux-x64 0.66.0 → 0.66.2

package/extensions/dm-lens/dist/clients/read-guard.js

@@ -1,1096 +0,0 @@
-import * as fs from "node:fs";
-import { incrementDegradationCount } from "./degradation-ledger.js";
-import { createFileTime } from "./file-time.js";
-import { hashDiagnosticContent } from "./lsp/diagnostic-binding.js";
-import { normalizeEphemeralMapKey, normalizeFilePath } from "./path-utils.js";
-import { logReadGuardEvent } from "./read-guard-logger.js";
-export const READ_GUARD_STATE_VERSION = 1;
-const DEFAULT_CONFIG = {
-  enabled: true,
-  mode: "block",
-  contextLines: 3,
-  exemptions: [
-    { pattern: "*.md", mode: "warn" },
-    { pattern: "*.txt", mode: "allow" },
-    { pattern: "*.log", mode: "allow" }
-  ]
-};
-const OWN_EDIT_STALE_GRACE_MS = Math.max(0, Number.parseInt(process.env.DM_LENS_READ_GUARD_OWN_EDIT_GRACE_MS ?? "120000", 10) || 120000);
-const READ_HASH_MAX_LINES = Math.max(0, Number.parseInt(process.env.DM_LENS_READ_GUARD_HASH_MAX_LINES ?? "3000", 10) || 3000);
-const READ_BINDING_MAX_BYTES = 4 * 1024 * 1024;
-const READ_GUARD_MAX_FILES = 256;
-const READ_GUARD_MAX_RECORDS_PER_FILE = 128;
-const NO_TRIM = {
-  evictedCount: 0,
-  evictedCreditCount: 0,
-  evictedGenuineCount: 0
-};
-function enforceRecordCapForFile(records) {
-  if (records.length <= READ_GUARD_MAX_RECORDS_PER_FILE)
-    return NO_TRIM;
-  const excess = records.length - READ_GUARD_MAX_RECORDS_PER_FILE;
-  const evicted = new Set;
-  let evictedCreditCount = 0;
-  for (let i = 0;i < records.length && evicted.size < excess; i++) {
-    if (records[i].searchCredit !== undefined) {
-      evicted.add(i);
-      evictedCreditCount++;
-    }
-  }
-  for (let i = 0;i < records.length && evicted.size < excess; i++) {
-    evicted.add(i);
-  }
-  const kept = records.filter((_, i) => !evicted.has(i));
-  records.length = 0;
-  for (const record of kept)
-    records.push(record);
-  return {
-    evictedCount: excess,
-    evictedCreditCount,
-    evictedGenuineCount: excess - evictedCreditCount
-  };
-}
-const READ_GUARD_MAX_EDITS_PER_FILE = 256;
-const READ_GUARD_MAX_UNCONSUMED_FILES = 4096;
-const READ_GUARD_IDLE_EVICT_MS_DEFAULT = 30 * 60000;
-export function captureReadContentBinding(filePath, offset, limit) {
-  try {
-    if (fs.statSync(filePath).size > READ_BINDING_MAX_BYTES)
-      return;
-    const content = fs.readFileSync(filePath, "utf-8");
-    const lines = splitLinesThrough(content, READ_HASH_MAX_LINES + 1);
-    if (lines.length <= READ_HASH_MAX_LINES) {
-      return {
-        hash: hashDiagnosticContent(content),
-        fullFile: true,
-        offset: 1,
-        limit: lines.length
-      };
-    }
-    const scopedOffset = Math.max(1, offset);
-    const scopedLimit = Math.min(Math.max(0, limit), READ_HASH_MAX_LINES);
-    if (scopedLimit === 0)
-      return;
-    const rangeLines = splitLinesThrough(content, scopedOffset - 1 + scopedLimit);
-    const scopedContent = rangeLines.slice(scopedOffset - 1, scopedOffset - 1 + scopedLimit).join(`
-`);
-    return {
-      hash: hashDiagnosticContent(scopedContent),
-      fullFile: false,
-      offset: scopedOffset,
-      limit: scopedLimit
-    };
-  } catch {
-    return;
-  }
-}
-export function _currentContentMatchesBindingForTests(filePath, binding) {
-  try {
-    const content = fs.readFileSync(filePath, "utf-8");
-    const boundContent = binding.fullFile ? content : splitLines(content).slice(binding.offset - 1, binding.offset - 1 + binding.limit).join(`
-`);
-    return hashDiagnosticContent(boundContent) === binding.hash;
-  } catch {
-    return false;
-  }
-}
-const currentContentMatchesBinding = _currentContentMatchesBindingForTests;
-const RELOCATION_WINDOW_MIN = Math.max(1, Number.parseInt(process.env.DM_LENS_READ_GUARD_RELOCATION_WINDOW_MIN ?? "40", 10) || 40);
-const RELOCATION_WINDOW_PER_EDIT = Math.max(0, Number.parseInt(process.env.DM_LENS_READ_GUARD_RELOCATION_WINDOW_PER_EDIT ?? "20", 10) || 20);
-const RELOCATION_WINDOW_MAX = Math.max(RELOCATION_WINDOW_MIN, Number.parseInt(process.env.DM_LENS_READ_GUARD_RELOCATION_WINDOW_MAX ?? "400", 10) || 400);
-function splitLines(text) {
-  return text.split(/\r?\n/);
-}
-function splitLinesThrough(text, maxLines) {
-  if (maxLines <= 0)
-    return [];
-  const lines = [];
-  let start = 0;
-  while (lines.length < maxLines) {
-    const newline = text.indexOf(`
-`, start);
-    if (newline === -1) {
-      lines.push(text.slice(start));
-      break;
-    }
-    const end = newline > start && text[newline - 1] === "\r" ? newline - 1 : newline;
-    lines.push(text.slice(start, end));
-    start = newline + 1;
-    if (start === text.length && lines.length < maxLines) {
-      lines.push("");
-      break;
-    }
-  }
-  return lines;
-}
-export function lineContentHash(line) {
-  const normalized = line.replace(/\s+/g, "");
-  let hash = 2166136261;
-  for (let i = 0;i < normalized.length; i++) {
-    hash = Math.imul(hash ^ normalized.charCodeAt(i), 16777619);
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}
-function readRangeCoversLine(read, lineNo) {
-  return lineNo >= read.effectiveOffset && lineNo <= read.effectiveOffset + read.effectiveLimit - 1;
-}
-function readEffectiveRangeCoversRange(read, [startLine, endLine]) {
-  return readRangeCoversLine(read, startLine) && readRangeCoversLine(read, endLine);
-}
-function captureLineHashes(filePath, offset, limit) {
-  if (limit <= 0 || limit > READ_HASH_MAX_LINES)
-    return;
-  try {
-    const lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-    const hashes = {};
-    const end = Math.min(lines.length, offset + limit - 1);
-    for (let lineNo = Math.max(1, offset);lineNo <= end; lineNo++) {
-      hashes[lineNo] = lineContentHash(lines[lineNo - 1] ?? "");
-    }
-    return Object.keys(hashes).length > 0 ? hashes : undefined;
-  } catch {
-    return;
-  }
-}
-export function currentLinesMatchReadSnapshot(filePath, read, [startLine, endLine]) {
-  const hashes = read.lineHashes ?? {};
-  const missingLines = [];
-  const mismatchedLines = [];
-  for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
-    if (!readRangeCoversLine(read, lineNo) || hashes[lineNo] === undefined) {
-      missingLines.push(lineNo);
-    }
-  }
-  if (missingLines.length > 0) {
-    return { checked: false, matches: false, missingLines, mismatchedLines };
-  }
-  let lines;
-  try {
-    lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-  } catch {
-    return {
-      checked: true,
-      matches: false,
-      missingLines,
-      mismatchedLines: [...Array(endLine - startLine + 1)].map((_, index) => startLine + index)
-    };
-  }
-  for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
-    if (lineNo < 1 || lineNo > lines.length) {
-      mismatchedLines.push(lineNo);
-      continue;
-    }
-    if (lineContentHash(lines[lineNo - 1] ?? "") !== hashes[lineNo]) {
-      mismatchedLines.push(lineNo);
-    }
-  }
-  return {
-    checked: true,
-    matches: mismatchedLines.length === 0,
-    missingLines,
-    mismatchedLines
-  };
-}
-
-export class ReadGuard {
-  config;
-  reads = new Map;
-  edits = new Map;
-  fileLastUsed = new Map;
-  fileIdleTimers = new Map;
-  consumedReadFiles = new Set;
-  fileTime;
-  exemptions = new Set;
-  pendingCreations = new Map;
-  writtenThisSession = new Set;
-  unchangedThisSession = new Set;
-  knownPathIndex = new Map;
-  trimAccumulators = new Map;
-  sessionId;
-  sessionStartMs;
-  constructor(sessionId, config = {}) {
-    this.sessionId = sessionId;
-    this.sessionStartMs = Date.now();
-    this.config = { ...DEFAULT_CONFIG, ...config };
-    this.fileTime = createFileTime(sessionId);
-  }
-  key(filePath) {
-    return normalizeFilePath(filePath);
-  }
-  idleEvictMs() {
-    const value = Number.parseInt(process.env.DM_LENS_READ_GUARD_IDLE_EVICT_MS ?? "", 10);
-    return Number.isSafeInteger(value) && value > 0 ? value : READ_GUARD_IDLE_EVICT_MS_DEFAULT;
-  }
-  clearFileTimer(filePath) {
-    const timer = this.fileIdleTimers.get(filePath);
-    if (timer)
-      clearTimeout(timer);
-    this.fileIdleTimers.delete(filePath);
-  }
-  evictFile(filePath, reason) {
-    this.clearFileTimer(filePath);
-    this.reads.delete(filePath);
-    this.edits.delete(filePath);
-    this.fileLastUsed.delete(filePath);
-    this.consumedReadFiles.delete(filePath);
-    this.writtenThisSession.delete(filePath);
-    for (const [syntacticKey, stored] of this.knownPathIndex) {
-      if (stored === filePath)
-        this.knownPathIndex.delete(syntacticKey);
-    }
-    if (reason === "idle-timeout")
-      return;
-    const isRisingEdge = incrementDegradationCount({
-      kind: "read-guard-file-evicted",
-      subject: filePath,
-      reason: `evicted (${reason})`
-    });
-    if (isRisingEdge) {
-      logReadGuardEvent({
-        event: "read_file_evicted",
-        sessionId: this.sessionId,
-        filePath,
-        metadata: { reason }
-      });
-    }
-  }
-  touchFile(filePath) {
-    const now = Date.now();
-    this.fileLastUsed.set(filePath, now);
-    this.clearFileTimer(filePath);
-    if (this.reads.has(filePath) && !this.consumedReadFiles.has(filePath))
-      return;
-    const stamp = now;
-    const timer = setTimeout(() => {
-      if (this.fileLastUsed.get(filePath) !== stamp)
-        return;
-      if (this.reads.has(filePath) && !this.consumedReadFiles.has(filePath))
-        return;
-      this.evictFile(filePath, "idle-timeout");
-    }, this.idleEvictMs());
-    timer.unref?.();
-    this.fileIdleTimers.set(filePath, timer);
-  }
-  enforceFileCap() {
-    while (this.reads.size > READ_GUARD_MAX_FILES) {
-      const victim = [...this.reads.keys()].filter((filePath) => this.consumedReadFiles.has(filePath)).sort((a, b) => (this.fileLastUsed.get(a) ?? 0) - (this.fileLastUsed.get(b) ?? 0))[0];
-      if (!victim)
-        break;
-      this.evictFile(victim, "file-cap-consumed");
-    }
-    while (this.reads.size > READ_GUARD_MAX_UNCONSUMED_FILES) {
-      const victim = [...this.reads.keys()].filter((filePath) => !this.consumedReadFiles.has(filePath)).sort((a, b) => (this.fileLastUsed.get(a) ?? 0) - (this.fileLastUsed.get(b) ?? 0))[0];
-      if (!victim)
-        break;
-      this.evictFile(victim, "file-cap-unconsumed");
-    }
-  }
-  recordRead(record, opts) {
-    const filePath = this.key(record.filePath);
-    if (opts?.supersedes) {
-      const records = this.reads.get(filePath);
-      const provisionalSource = `native-read:${opts.supersedes.toolCallId}:provisional`;
-      const provisionalIndex = records?.findIndex((candidate) => candidate.source === provisionalSource);
-      if (provisionalIndex !== undefined && provisionalIndex >= 0)
-        records.splice(provisionalIndex, 1);
-    }
-    this.knownPathIndex.set(normalizeEphemeralMapKey(record.filePath), filePath);
-    const storedRecord = {
-      ...record,
-      filePath,
-      lineHashes: record.lineHashes ?? captureLineHashes(filePath, record.effectiveOffset, record.effectiveLimit)
-    };
-    const arr = this.reads.get(storedRecord.filePath) ?? [];
-    this.consumedReadFiles.delete(storedRecord.filePath);
-    arr.push(storedRecord);
-    this.reads.set(storedRecord.filePath, arr);
-    const rawReadCountForFile = arr.length;
-    const { evictedCount: evictedRecordCount, evictedCreditCount, evictedGenuineCount } = enforceRecordCapForFile(arr);
-    this.touchFile(storedRecord.filePath);
-    this.enforceFileCap();
-    logReadGuardEvent({
-      event: "read_recorded",
-      sessionId: this.sessionId,
-      filePath: storedRecord.filePath,
-      requestedOffset: storedRecord.requestedOffset,
-      requestedLimit: storedRecord.requestedLimit,
-      effectiveOffset: storedRecord.effectiveOffset,
-      effectiveLimit: storedRecord.effectiveLimit,
-      symbol: storedRecord.enclosingSymbol?.name,
-      symbolKind: storedRecord.enclosingSymbol?.kind,
-      symbolStartLine: storedRecord.enclosingSymbol?.startLine,
-      symbolEndLine: storedRecord.enclosingSymbol?.endLine,
-      metadata: {
-        expandedByLsp: storedRecord.expandedByLsp,
-        turnIndex: storedRecord.turnIndex,
-        writeIndex: storedRecord.writeIndex,
-        readCountForFile: arr.length,
-        hashLineCount: Object.keys(storedRecord.lineHashes ?? {}).length,
-        ...storedRecord.source !== undefined && {
-          source: storedRecord.source
-        },
-        ...storedRecord.searchCredit !== undefined && {
-          searchCreditReason: storedRecord.searchCredit.reason,
-          searchCreditMarginBefore: storedRecord.searchCredit.marginBefore,
-          searchCreditMarginAfter: storedRecord.searchCredit.marginAfter
-        },
-        ...evictedRecordCount > 0 && {
-          evictedRecordCount,
-          rawReadCountForFile
-        }
-      }
-    });
-    if (evictedRecordCount > 0) {
-      const key = storedRecord.filePath;
-      const acc = this.trimAccumulators.get(key) ?? {
-        totalEvicted: 0,
-        evictedCreditCount: 0,
-        evictedGenuineCount: 0,
-        trimEventCount: 0
-      };
-      acc.totalEvicted += evictedRecordCount;
-      acc.evictedCreditCount += evictedCreditCount;
-      acc.evictedGenuineCount += evictedGenuineCount;
-      acc.trimEventCount += 1;
-      this.trimAccumulators.set(key, acc);
-      const isRisingEdge = incrementDegradationCount({
-        kind: "read-guard-record-cap-trim",
-        subject: key,
-        reason: `trim #${acc.trimEventCount}: evicted ${evictedRecordCount} (credit ${evictedCreditCount}, genuine ${evictedGenuineCount})`
-      });
-      if (isRisingEdge) {
-        logReadGuardEvent({
-          event: "read_cap_trimmed",
-          sessionId: this.sessionId,
-          filePath: storedRecord.filePath,
-          metadata: {
-            trimEventCount: acc.trimEventCount,
-            evictedRecordCount: acc.totalEvicted,
-            evictedCreditCount: acc.evictedCreditCount,
-            evictedGenuineCount: acc.evictedGenuineCount,
-            rawReadCountForFile
-          }
-        });
-      }
-    }
-    this.fileTime.read(storedRecord.filePath);
-  }
-  recordSymbolRead(filePath, symbol, turnIndex, writeIndex) {
-    const span = Math.max(1, symbol.endLine - symbol.startLine + 1);
-    this.recordRead({
-      filePath,
-      requestedOffset: symbol.startLine,
-      requestedLimit: span,
-      effectiveOffset: symbol.startLine,
-      effectiveLimit: span,
-      expandedByLsp: false,
-      enclosingSymbol: {
-        name: symbol.name,
-        kind: symbol.kind,
-        startLine: symbol.startLine,
-        endLine: symbol.endLine
-      },
-      turnIndex,
-      writeIndex,
-      timestamp: Date.now()
-    });
-  }
-  checkEdit(filePath, touchedLines, editRanges, options) {
-    filePath = this.key(filePath);
-    if (this.reads.has(filePath) || this.edits.has(filePath))
-      this.touchFile(filePath);
-    if (this.exemptions.has(filePath)) {
-      this.exemptions.delete(filePath);
-      const verdict = this.allow();
-      this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "manual_exemption"
-      });
-      return verdict;
-    }
-    const exemptionMode = this.getExemptionMode(filePath);
-    if (exemptionMode === "allow") {
-      const verdict = this.allow();
-      this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "pattern_exemption",
-        exemptionMode
-      });
-      return verdict;
-    }
-    const effectiveMode = exemptionMode === "warn" ? "warn" : undefined;
-    const fileReads = this.reads.get(filePath);
-    if (!fileReads || fileReads.length === 0) {
-      if (this.wasWrittenThisSession(filePath)) {
-        this.injectCreationRead(filePath, 0, 0);
-        const verdict = this.allow();
-        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-          reasonKind: "session_authored"
-        });
-        return verdict;
-      }
-      const verdict = this.blockOrWarn("zero-read", `\uD83D\uDD04 RETRYABLE — Edit without read: you have not read \`${filePath}\` in this conversation. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
-      this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "zero_read"
-      });
-      return verdict;
-    }
-    const lastBoundRead = [...fileReads].reverse().find((read) => read.contentBinding !== undefined);
-    if (lastBoundRead?.contentBinding && !currentContentMatchesBinding(filePath, lastBoundRead.contentBinding)) {
-      const verdict = this.blockOrWarn("file-modified", `\uD83D\uDD04 RETRYABLE — File modified since read
-
-You last read \`${filePath}\` at ${new Date(lastBoundRead.timestamp).toISOString()}.
-The file content no longer matches the bridge-recorded read.
-
-Your mental model is out of sync with the actual file content.
-To proceed:
-  1. Re-read the file: \`read path="${filePath}"\``, undefined, effectiveMode);
-      this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "file_modified",
-        lastReadTimestamp: lastBoundRead.timestamp,
-        contentBindingMismatch: true
-      });
-      return verdict;
-    }
-    let ignoredOwnEditStaleness = false;
-    let ignoredHashStaleness = false;
-    let ignoredOldTextResolvedStaleness = false;
-    if (this.fileTime.hasChanged(filePath)) {
-      const lastRead = fileReads[fileReads.length - 1];
-      if (options?.oldTextResolved === true) {
-        ignoredOldTextResolvedStaleness = true;
-      } else if (this.canTreatStalenessAsOwnPriorEdit(filePath, lastRead.timestamp)) {
-        ignoredOwnEditStaleness = true;
-      } else if (this.canIgnoreStalenessByHashes(filePath, fileReads, touchedLines, editRanges)) {
-        ignoredHashStaleness = true;
-      } else {
-        const verdict = this.blockOrWarn("file-modified", `\uD83D\uDD04 RETRYABLE — File modified since read
-
-You last read \`${filePath}\` at ${new Date(lastRead.timestamp).toISOString()}.
-The file has been modified on disk since then (auto-format, external tool, or previous edit).
-
-Your mental model is out of sync with the actual file content.
-To proceed:
-  1. Re-read the file: \`read path="${filePath}"\``, undefined, effectiveMode);
-        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-          reasonKind: "file_modified",
-          lastReadTimestamp: lastRead.timestamp
-        });
-        return verdict;
-      }
-    }
-    if (!touchedLines) {
-      const verdict = this.allow();
-      this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "no_line_info"
-      });
-      return verdict;
-    }
-    const rangesToCheck = editRanges && editRanges.length > 1 ? editRanges : [touchedLines];
-    let viaSymbol = false;
-    for (const range of rangesToCheck) {
-      const snapshotValidation = this.validateRangeSnapshot(filePath, range, !!options?.skipSnapshotCheck);
-      const coverage = this.checkCoverage(filePath, range);
-      if (!coverage.covered) {
-        const lastRead = fileReads[fileReads.length - 1];
-        const [editStart, editEnd] = range;
-        const lastReadEnd = lastRead.effectiveOffset + lastRead.effectiveLimit - 1;
-        const outOfRangeMode = options?.oldTextResolved ? "warn" : effectiveMode;
-        const verdict = this.blockOrWarn("out-of-range", `\uD83D\uDD04 RETRYABLE — Edit outside read range
-
-You read \`${filePath}\` lines ${lastRead.effectiveOffset}-${lastReadEnd}${lastRead.enclosingSymbol ? ` (${lastRead.enclosingSymbol.kind} \`${lastRead.enclosingSymbol.name}\`)` : ""}, but your edit touches lines ${editStart}-${editEnd}.
-
-Read the relevant section first, then retry the edit:
-  \`read path="${filePath}" offset=${Math.max(1, editStart - 5)} limit=${Math.min(30, editEnd - editStart + 10)}\``, {
-          editRange: range,
-          readRanges: fileReads.map((r) => ({
-            start: r.effectiveOffset,
-            end: r.effectiveOffset + r.effectiveLimit - 1
-          })),
-          symbolRanges: fileReads.filter((r) => r.enclosingSymbol).map((r) => ({
-            name: r.enclosingSymbol.name,
-            start: r.enclosingSymbol.startLine,
-            end: r.enclosingSymbol.endLine
-          }))
-        }, outOfRangeMode);
-        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-          reasonKind: "out_of_range",
-          oldTextResolved: options?.oldTextResolved ?? false
-        });
-        return verdict;
-      }
-      if (snapshotValidation.shouldBlock && !options?.skipSnapshotCheck) {
-        const [editStart, editEnd] = range;
-        const RANGE_STALE_GRACE_MS = 60000;
-        const lastRead = fileReads[fileReads.length - 1];
-        const graceActive = ignoredOwnEditStaleness && Date.now() - lastRead.timestamp < RANGE_STALE_GRACE_MS;
-        const relocation = this.findRelocation(filePath, fileReads, range);
-        const relocationNote = relocation ? `
-
-\uD83D\uDCCD The content you read at lines ${relocation.from[0]}-${relocation.from[1]} now appears unchanged at lines ${relocation.to[0]}-${relocation.to[1]} — it shifted position. Re-target your edit to lines ${relocation.to[0]}-${relocation.to[1]}.` : "";
-        const verdict = this.blockOrWarn("range-stale", `\uD83D\uDD04 RETRYABLE — Edit range changed since read
-
-You are editing \`${filePath}\` lines ${editStart}-${editEnd}, but those lines no longer match the content you read earlier.${relocationNote}
-
-Re-read the relevant section, then retry the edit using the current line range/content:
-  \`read path="${filePath}" offset=${Math.max(1, editStart - 5)} limit=${Math.min(30, editEnd - editStart + 10)}\``, {
-          editRange: range,
-          readRanges: fileReads.map((r) => ({
-            start: r.effectiveOffset,
-            end: r.effectiveOffset + r.effectiveLimit - 1
-          })),
-          symbolRanges: fileReads.filter((r) => r.enclosingSymbol).map((r) => ({
-            name: r.enclosingSymbol.name,
-            start: r.enclosingSymbol.startLine,
-            end: r.enclosingSymbol.endLine
-          })),
-          snapshot: {
-            status: snapshotValidation.status,
-            mismatchedLines: snapshotValidation.mismatchedLines,
-            missingLines: snapshotValidation.missingLines
-          },
-          ...relocation ? { relocation } : {}
-        }, graceActive ? "warn" : effectiveMode);
-        if (relocation && rangesToCheck.length === 1) {
-          verdict.relocation = relocation;
-        }
-        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-          reasonKind: "range_stale",
-          range,
-          mismatchedLines: snapshotValidation.mismatchedLines.slice(0, 20),
-          graceActive,
-          relocatedTo: relocation?.to ?? null,
-          relocationAutoApplyOffered: !!verdict.relocation
-        });
-        return verdict;
-      }
-      if (coverage.viaSymbol)
-        viaSymbol = true;
-    }
-    const verdict = this.allow();
-    this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-      reasonKind: ignoredOldTextResolvedStaleness ? "file_modified_oldtext_unique" : viaSymbol ? "symbol_coverage" : "range_coverage",
-      viaSymbol,
-      ignoredOwnEditStaleness,
-      ignoredHashStaleness,
-      oldTextResolved: ignoredOldTextResolvedStaleness
-    });
-    return verdict;
-  }
-  isNewFile(filePath) {
-    try {
-      return !fs.existsSync(filePath);
-    } catch {
-      return true;
-    }
-  }
-  hasKnownPath(filePath) {
-    const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
-    return stored !== undefined && (this.reads.has(stored) || this.writtenThisSession.has(stored));
-  }
-  getTrackedPaths() {
-    const tracked = new Set(this.reads.keys());
-    for (const written of this.writtenThisSession)
-      tracked.add(written);
-    return [...tracked];
-  }
-  forgetPath(filePath) {
-    const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
-    this.evictFile(stored ?? this.key(filePath), "external-delete");
-  }
-  noteCreatedFile(filePath, turnIndex, writeIndex) {
-    this.pendingCreations.set(normalizeEphemeralMapKey(filePath), {
-      turnIndex,
-      writeIndex
-    });
-  }
-  recordWritten(rawFilePath) {
-    const filePath = this.key(rawFilePath);
-    this.unchangedThisSession.delete(filePath);
-    this.knownPathIndex.set(normalizeEphemeralMapKey(rawFilePath), filePath);
-    this.fileTime.read(filePath);
-    this.writtenThisSession.add(filePath);
-    if (this.reads.has(filePath))
-      this.consumedReadFiles.add(filePath);
-    this.touchFile(filePath);
-    this.enforceFileCap();
-    const creationKey = normalizeEphemeralMapKey(rawFilePath);
-    const creation = this.pendingCreations.get(creationKey);
-    if (creation) {
-      this.pendingCreations.delete(creationKey);
-      this.injectCreationRead(filePath, creation.turnIndex, creation.writeIndex);
-    }
-  }
-  recordUnchanged(rawFilePath) {
-    const filePath = this.key(rawFilePath);
-    if (!this.writtenThisSession.has(filePath))
-      this.unchangedThisSession.add(filePath);
-  }
-  addExemption(filePath) {
-    this.exemptions.add(this.key(filePath));
-    logReadGuardEvent({
-      event: "exemption_added",
-      sessionId: this.sessionId,
-      filePath,
-      metadata: {
-        source: "lens-allow-edit"
-      }
-    });
-  }
-  getSummary() {
-    let totalEdits = 0;
-    let totalBlocks = 0;
-    let lspExpansionsHelped = 0;
-    const byReason = {};
-    const byFile = {};
-    for (const [filePath, records] of this.edits) {
-      for (const record of records) {
-        totalEdits++;
-        byFile[filePath] = byFile[filePath] ?? { edits: 0, blocks: 0 };
-        byFile[filePath].edits++;
-        if (record.verdict === "blocked") {
-          totalBlocks++;
-          byFile[filePath].blocks++;
-        }
-        if (record.reason) {
-          byReason[record.reason] = (byReason[record.reason] ?? 0) + 1;
-        }
-        if (record.precedingReads.some((r) => r.expandedByLsp) && record.verdict === "allowed") {
-          lspExpansionsHelped++;
-        }
-      }
-    }
-    return {
-      totalEdits,
-      totalBlocks,
-      byReason,
-      byFile,
-      lspExpansionsHelped
-    };
-  }
-  getReadHistory(filePath) {
-    const key = this.key(filePath);
-    if (this.reads.has(key))
-      this.touchFile(key);
-    return this.reads.get(key) ?? [];
-  }
-  getTrimStats(filePath) {
-    const stats = this.trimAccumulators.get(this.key(filePath));
-    return stats ? { ...stats } : undefined;
-  }
-  exportState() {
-    return {
-      version: READ_GUARD_STATE_VERSION,
-      reads: [...this.reads.entries()].map(([key, records]) => [
-        key,
-        records.map((record) => ({ ...record }))
-      ])
-    };
-  }
-  importState(state) {
-    const result = { imported: 0, dropped: 0 };
-    if (!state || state.version !== READ_GUARD_STATE_VERSION)
-      return result;
-    if (!Array.isArray(state.reads))
-      return result;
-    for (const entry of state.reads) {
-      if (!Array.isArray(entry) || entry.length !== 2)
-        continue;
-      const [rawPath, records] = entry;
-      if (typeof rawPath !== "string")
-        continue;
-      if (!Array.isArray(records) || records.length === 0)
-        continue;
-      const filePath = this.key(rawPath);
-      let lines;
-      try {
-        lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-      } catch {
-        result.dropped += records.length;
-        continue;
-      }
-      for (const record of records) {
-        const rehydrated = { ...record, filePath };
-        if (this.readHashesStillMatch(rehydrated, lines)) {
-          this.recordRead(rehydrated);
-          result.imported += 1;
-        } else {
-          result.dropped += 1;
-        }
-      }
-    }
-    return result;
-  }
-  getEditHistory(filePath) {
-    const key = this.key(filePath);
-    if (this.edits.has(key))
-      this.touchFile(key);
-    return this.edits.get(key) ?? [];
-  }
-  injectCreationRead(filePath, turnIndex, writeIndex) {
-    let lineCount = 0;
-    try {
-      lineCount = splitLines(fs.readFileSync(filePath, "utf-8")).length;
-    } catch {
-      return;
-    }
-    if (lineCount === 0)
-      return;
-    this.recordRead({
-      filePath,
-      requestedOffset: 1,
-      requestedLimit: lineCount,
-      effectiveOffset: 1,
-      effectiveLimit: lineCount,
-      expandedByLsp: false,
-      turnIndex,
-      writeIndex,
-      timestamp: Date.now()
-    });
-  }
-  wasWrittenThisSession(filePath) {
-    if (this.unchangedThisSession.has(filePath))
-      return false;
-    if (this.writtenThisSession.has(filePath))
-      return true;
-    try {
-      return fs.statSync(filePath).mtimeMs >= this.sessionStartMs;
-    } catch {
-      return false;
-    }
-  }
-  canTreatStalenessAsOwnPriorEdit(filePath, lastReadTimestamp) {
-    const edits = this.edits.get(filePath) ?? [];
-    const latest = edits.at(-1);
-    if (!latest)
-      return false;
-    if (latest.verdict !== "allowed" && latest.verdict !== "warned")
-      return false;
-    if (latest.timestamp < lastReadTimestamp)
-      return false;
-    return Date.now() - latest.timestamp <= OWN_EDIT_STALE_GRACE_MS;
-  }
-  canIgnoreStalenessByHashes(filePath, reads, touchedLines, editRanges) {
-    let lines;
-    try {
-      lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-    } catch {
-      return false;
-    }
-    const rangesToCheck = touchedLines ? editRanges && editRanges.length > 1 ? editRanges : [touchedLines] : undefined;
-    if (!rangesToCheck) {
-      const lastRead = reads.at(-1);
-      return !!lastRead && this.readHashesStillMatch(lastRead, lines);
-    }
-    return rangesToCheck.every((range) => reads.some((read) => this.readCoversRange(read, range) && this.readRangeHashesStillMatch(read, lines, range)));
-  }
-  readCoversRange(read, [editStart, editEnd]) {
-    const readStart = Math.max(1, read.effectiveOffset - this.config.contextLines);
-    const readEnd = read.effectiveOffset + read.effectiveLimit - 1 + this.config.contextLines;
-    if (editStart >= readStart && editEnd <= readEnd)
-      return true;
-    if (!read.enclosingSymbol)
-      return false;
-    return read.enclosingSymbol.startLine <= editStart && read.enclosingSymbol.endLine >= editEnd;
-  }
-  validateRangeSnapshot(filePath, range, snapshotCheckSkipped) {
-    const reads = this.reads.get(filePath) ?? [];
-    const candidates = reads.filter((read) => this.readCoversRange(read, range));
-    let status = "unavailable";
-    let matchingReadIndex = -1;
-    let missingLines = [];
-    let mismatchedLines = [];
-    let checkedCandidateCount = 0;
-    let unavailableCandidateCount = 0;
-    let hashUnavailableCandidateCount = 0;
-    let lastMismatchTimestamp = -1 / 0;
-    let lastUnavailableTimestamp = -1 / 0;
-    for (let i = 0;i < candidates.length; i += 1) {
-      const validation = currentLinesMatchReadSnapshot(filePath, candidates[i], range);
-      if (!validation.checked) {
-        unavailableCandidateCount += 1;
-        if (readEffectiveRangeCoversRange(candidates[i], range)) {
-          hashUnavailableCandidateCount += 1;
-        }
-        if (status === "unavailable") {
-          missingLines = validation.missingLines;
-        }
-        lastUnavailableTimestamp = Math.max(lastUnavailableTimestamp, candidates[i].timestamp);
-        continue;
-      }
-      checkedCandidateCount += 1;
-      if (validation.matches) {
-        status = "match";
-        matchingReadIndex = i;
-        missingLines = [];
-        mismatchedLines = [];
-        break;
-      }
-      status = "mismatch";
-      missingLines = [];
-      mismatchedLines = validation.mismatchedLines;
-      lastMismatchTimestamp = Math.max(lastMismatchTimestamp, candidates[i].timestamp);
-    }
-    const shouldBlock = status === "mismatch" && lastUnavailableTimestamp <= lastMismatchTimestamp && checkedCandidateCount > 0 && hashUnavailableCandidateCount === 0;
-    const outcome = shouldBlock ? snapshotCheckSkipped ? "bypassed-content-match" : "enforced-block" : status === "match" ? "enforced-pass" : "not-decidable";
-    logReadGuardEvent({
-      event: "range_snapshot_validation",
-      sessionId: this.sessionId,
-      filePath,
-      metadata: {
-        range,
-        status,
-        candidateReadCount: candidates.length,
-        checkedCandidateCount,
-        unavailableCandidateCount,
-        hashUnavailableCandidateCount,
-        matchingReadIndex,
-        missingLineCount: missingLines.length,
-        mismatchedLineCount: mismatchedLines.length,
-        missingLines: missingLines.slice(0, 20),
-        mismatchedLines: mismatchedLines.slice(0, 20),
-        enforced: shouldBlock || status === "match",
-        outcome
-      }
-    });
-    return {
-      status,
-      matchingReadIndex,
-      missingLines,
-      mismatchedLines,
-      candidateReadCount: candidates.length,
-      checkedCandidateCount,
-      unavailableCandidateCount,
-      shouldBlock
-    };
-  }
-  readRangeHashesStillMatch(read, lines, [startLine, endLine]) {
-    const hashes = read.lineHashes ?? {};
-    for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
-      if (!readRangeCoversLine(read, lineNo) || hashes[lineNo] === undefined) {
-        return false;
-      }
-      if (lineNo < 1 || lineNo > lines.length)
-        return false;
-      if (lineContentHash(lines[lineNo - 1] ?? "") !== hashes[lineNo]) {
-        return false;
-      }
-    }
-    return true;
-  }
-  findRelocation(filePath, reads, [startLine, endLine]) {
-    const span = endLine - startLine + 1;
-    if (span < 2)
-      return;
-    let wanted;
-    for (let i = reads.length - 1;i >= 0; i -= 1) {
-      const hashes = reads[i].lineHashes;
-      if (!hashes)
-        continue;
-      const seq = [];
-      let complete = true;
-      for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
-        const h = hashes[lineNo];
-        if (h === undefined) {
-          complete = false;
-          break;
-        }
-        seq.push(h);
-      }
-      if (complete) {
-        wanted = seq;
-        break;
-      }
-    }
-    if (!wanted)
-      return;
-    let lines;
-    try {
-      lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-    } catch {
-      return;
-    }
-    const currentHashes = lines.map((line) => lineContentHash(line));
-    const lastStart = currentHashes.length - span;
-    const matchStarts = [];
-    for (let i = 0;i <= lastStart; i += 1) {
-      let ok = true;
-      for (let j = 0;j < span; j += 1) {
-        if (currentHashes[i + j] !== wanted[j]) {
-          ok = false;
-          break;
-        }
-      }
-      if (ok)
-        matchStarts.push(i + 1);
-    }
-    let newStart;
-    if (matchStarts.length === 1) {
-      newStart = matchStarts[0];
-    } else if (matchStarts.length > 1) {
-      const appliedEdits = (this.edits.get(filePath) ?? []).filter((record) => record.verdict !== "blocked").length;
-      const window = Math.min(RELOCATION_WINDOW_MAX, Math.max(RELOCATION_WINDOW_MIN, appliedEdits * RELOCATION_WINDOW_PER_EDIT));
-      const lo = startLine - window;
-      const hi = endLine + window;
-      const local = matchStarts.filter((start) => start >= lo && start <= hi);
-      if (local.length === 1)
-        newStart = local[0];
-    }
-    if (newStart === undefined || newStart === startLine)
-      return;
-    return { from: [startLine, endLine], to: [newStart, newStart + span - 1] };
-  }
-  readHashesStillMatch(read, lines) {
-    const entries = Object.entries(read.lineHashes ?? {});
-    if (entries.length === 0)
-      return false;
-    for (const [lineText, expected] of entries) {
-      const lineNo = Number(lineText);
-      if (!Number.isInteger(lineNo) || lineNo < 1 || lineNo > lines.length) {
-        return false;
-      }
-      if (lineContentHash(lines[lineNo - 1] ?? "") !== expected)
-        return false;
-    }
-    return true;
-  }
-  checkCoverage(filePath, touchedLines) {
-    const [editStart, editEnd] = touchedLines;
-    const reads = this.reads.get(filePath) ?? [];
-    for (const read of reads) {
-      if (read.provisional === true)
-        continue;
-      const readStart = Math.max(1, read.effectiveOffset - this.config.contextLines);
-      const readEnd = read.effectiveOffset + read.effectiveLimit - 1 + this.config.contextLines;
-      if (editStart >= readStart && editEnd <= readEnd) {
-        return { covered: true, viaSymbol: false };
-      }
-      if (read.enclosingSymbol) {
-        const symStart = read.enclosingSymbol.startLine;
-        const symEnd = read.enclosingSymbol.endLine;
-        if (symStart <= editStart && symEnd >= editEnd) {
-          return { covered: true, viaSymbol: true };
-        }
-      }
-    }
-    const intervals = reads.filter((read) => read.provisional !== true).map((read) => [
-      Math.max(1, read.effectiveOffset - this.config.contextLines),
-      read.effectiveOffset + read.effectiveLimit - 1 + this.config.contextLines
-    ]);
-    intervals.sort((a, b) => a[0] - b[0]);
-    const merged = [];
-    for (const [s, e] of intervals) {
-      if (merged.length > 0 && s <= merged[merged.length - 1][1] + 1) {
-        merged[merged.length - 1][1] = Math.max(merged[merged.length - 1][1], e);
-      } else {
-        merged.push([s, e]);
-      }
-    }
-    for (const [s, e] of merged) {
-      if (editStart >= s && editEnd <= e) {
-        return { covered: true, viaSymbol: false };
-      }
-    }
-    return { covered: false, viaSymbol: false };
-  }
-  getExemptionMode(filePath) {
-    for (const exemption of this.config.exemptions) {
-      if (this.matchesPattern(filePath, exemption.pattern)) {
-        return exemption.mode;
-      }
-    }
-    return null;
-  }
-  matchesPattern(filePath, pattern) {
-    if (pattern.startsWith("*")) {
-      const suffix = pattern.slice(1);
-      return filePath.endsWith(suffix);
-    }
-    if (pattern.includes("*")) {
-      const collapsedPattern = pattern.replace(/\*+/g, "*");
-      const regex = new RegExp(`^${collapsedPattern.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/\*/g, ".*")}$`);
-      return regex.test(filePath);
-    }
-    return filePath === pattern;
-  }
-  blockOrWarn(_reason, message, details, overrideMode) {
-    const mode = overrideMode ?? this.config.mode;
-    if (mode === "warn") {
-      return { action: "warn", reason: message, details };
-    }
-    return { action: "block", reason: message, details };
-  }
-  allow() {
-    return { action: "allow" };
-  }
-  recordEdit(filePath, tool, touchedLines, verdict) {
-    this.touchFile(filePath);
-    const arr = this.edits.get(filePath) ?? [];
-    arr.push({
-      filePath,
-      tool,
-      touchedLines,
-      precedingReads: this.reads.get(filePath) ?? [],
-      verdict: mapVerdictAction(verdict.action),
-      reason: verdict.reason,
-      timestamp: Date.now()
-    });
-    if (arr.length > READ_GUARD_MAX_EDITS_PER_FILE) {
-      const trimmedCount = arr.length - READ_GUARD_MAX_EDITS_PER_FILE;
-      arr.splice(0, trimmedCount);
-      const isRisingEdge = incrementDegradationCount({
-        kind: "read-guard-edits-cap-trim",
-        subject: filePath,
-        reason: `trimmed ${trimmedCount} edit record(s) past cap`
-      });
-      if (isRisingEdge) {
-        logReadGuardEvent({
-          event: "edits_cap_trimmed",
-          sessionId: this.sessionId,
-          filePath,
-          metadata: { trimmedCount, cappedLength: arr.length }
-        });
-      }
-    }
-    this.edits.set(filePath, arr);
-  }
-  recordVerdict(filePath, tool, touchedLines, verdict, metadata = {}) {
-    const normalizedTouchedLines = touchedLines ?? [1, 1];
-    this.recordEdit(filePath, tool, normalizedTouchedLines, verdict);
-    const reads = this.reads.get(filePath) ?? [];
-    logReadGuardEvent({
-      event: verdict.action === "allow" ? "edit_allowed" : verdict.action === "warn" ? "edit_warned" : "edit_blocked",
-      sessionId: this.sessionId,
-      filePath,
-      metadata: {
-        tool,
-        touchedLines: touchedLines ?? null,
-        normalizedTouchedLines,
-        readCount: reads.length,
-        reads: reads.map((read) => ({
-          requestedOffset: read.requestedOffset,
-          requestedLimit: read.requestedLimit,
-          effectiveOffset: read.effectiveOffset,
-          effectiveLimit: read.effectiveLimit,
-          expandedByLsp: read.expandedByLsp,
-          enclosingSymbol: read.enclosingSymbol ?? null,
-          timestamp: read.timestamp
-        })),
-        verdictAction: verdict.action,
-        details: verdict.details,
-        ...metadata
-      }
-    });
-  }
-}
-function mapVerdictAction(action) {
-  switch (action) {
-    case "allow":
-      return "allowed";
-    case "block":
-      return "blocked";
-    case "warn":
-      return "warned";
-  }
-}
-export function createReadGuard(sessionId, config) {
-  return new ReadGuard(sessionId, config);
-}