@duckmind/dm-linux-x64 0.63.9 → 0.64.2

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

@@ -0,0 +1,1077 @@
+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;
+  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) {
+    const filePath = this.key(record.filePath);
+    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(this.key(filePath), { turnIndex, writeIndex });
+  }
+  recordWritten(rawFilePath) {
+    const filePath = this.key(rawFilePath);
+    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 creation = this.pendingCreations.get(filePath);
+    if (creation) {
+      this.pendingCreations.delete(filePath);
+      this.injectCreationRead(filePath, creation.turnIndex, creation.writeIndex);
+    }
+  }
+  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.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) {
+      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.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 regex = new RegExp(`^${pattern.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);
+}