@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

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

@@ -0,0 +1,1429 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { BoundedSet } from "./bounded-cache.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import { createFileTime } from "./file-time.js";
+import { hashDiagnosticContent } from "./lsp/diagnostic-binding.js";
+import { normalizeEphemeralMapKey, normalizeFilePath, realpathOrResolve } from "./path-utils.js";
+import { logReadGuardEvent, sanitizeCorrelationId } from "./read-guard-logger.js";
+import { beginScope, moveBranch } from "./session-scope.js";
+export const READ_GUARD_STATE_VERSION = 2;
+const DEFAULT_CONFIG = {
+  enabled: true,
+  mode: "block",
+  contextLines: 3,
+  exemptions: [
+    { pattern: "*.md", mode: "warn" },
+    { pattern: "*.txt", mode: "allow" },
+    { pattern: "*.log", mode: "allow" }
+  ]
+};
+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;
+function hashFileBytes(filePath) {
+  return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+const ABSENT_SIZE = -1;
+function observeAuthoredBytes(filePath, knownHash, authoredRanges) {
+  try {
+    const stat = fs.statSync(filePath);
+    const hash = knownHash !== undefined ? knownHash : stat.size <= READ_BINDING_MAX_BYTES ? hashFileBytes(filePath) : undefined;
+    return {
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      ctimeMs: stat.ctimeMs,
+      ...hash !== undefined && { hash },
+      ...authoredRanges !== undefined && { authoredRanges },
+      ...authoredRanges !== undefined && {
+        authoredLineCount: splitLines(fs.readFileSync(filePath, "utf-8")).length
+      }
+    };
+  } catch {
+    return { size: ABSENT_SIZE, mtimeMs: 0, ctimeMs: 0 };
+  }
+}
+function composeAuthoredRanges(previous, next, nextLineCount) {
+  const ranges = previous.authoredLineCount !== undefined && nextLineCount === previous.authoredLineCount ? [...previous.authoredRanges ?? [], ...next] : next;
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+  const merged = [];
+  for (const [start, end] of sorted) {
+    const last = merged.at(-1);
+    if (last && start <= last[1] + 1)
+      last[1] = Math.max(last[1], end);
+    else
+      merged.push([start, end]);
+  }
+  return merged;
+}
+function authoredRangeCovers(authored, touchedLines, editRanges) {
+  if (authored.authoredRanges === undefined)
+    return true;
+  const requested = editRanges ?? (touchedLines ? [touchedLines] : undefined);
+  return requested !== undefined && requested.every(([start, end]) => authored.authoredRanges.some(([authoredStart, authoredEnd]) => start >= authoredStart && end <= authoredEnd));
+}
+function isValidAuthoredRanges(value) {
+  return Array.isArray(value) && value.every((range) => Array.isArray(range) && range.length === 2 && Number.isFinite(range[0]) && Number.isFinite(range[1]));
+}
+function authoredBytesIntact(filePath, authored) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return authored.size === ABSENT_SIZE;
+  }
+  if (stat.size === authored.size && stat.mtimeMs === authored.mtimeMs && stat.ctimeMs === authored.ctimeMs)
+    return true;
+  if (authored.hash === undefined || stat.size !== authored.size)
+    return false;
+  try {
+    if (hashFileBytes(filePath) !== authored.hash)
+      return false;
+  } catch {
+    return false;
+  }
+  authored.mtimeMs = stat.mtimeMs;
+  authored.ctimeMs = stat.ctimeMs;
+  return true;
+}
+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_MAX_AUTHORED_FILES = READ_GUARD_MAX_UNCONSUMED_FILES;
+const READ_GUARD_MAX_CHECKED_CALLS = 16;
+const READ_GUARD_MAX_CHECKED_PATHS_PER_CALL = 128;
+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 newestViewOfLine(reads, lineNo) {
+  for (let i = reads.length - 1;i >= 0; i -= 1) {
+    if (reads[i].provisional !== true && readRangeCoversLine(reads[i], lineNo)) {
+      return reads[i];
+    }
+  }
+  return;
+}
+function hashLines(lines, firstLine) {
+  const hashes = {};
+  lines.forEach((line, i) => {
+    hashes[firstLine + i] = lineContentHash(line);
+  });
+  return lines.length > 0 ? hashes : undefined;
+}
+function captureLineHashes(filePath, offset, limit) {
+  if (limit <= 0 || limit > READ_HASH_MAX_LINES)
+    return;
+  try {
+    const lines = splitLines(fs.readFileSync(filePath, "utf-8"));
+    const start = Math.max(1, offset);
+    const end = Math.min(lines.length, offset + limit - 1);
+    return hashLines(lines.slice(start - 1, end), start);
+  } catch {
+    return;
+  }
+}
+export function deliveredLineEvidence(text, offset) {
+  const lines = splitLines(text);
+  return {
+    lineCount: lines.length,
+    lineHashes: lines.length <= READ_HASH_MAX_LINES ? hashLines(lines, offset) : undefined
+  };
+}
+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 Map;
+  checkedPathsByCall = new Map;
+  expiredWrites = new BoundedSet(READ_GUARD_MAX_FILES);
+  knownPathIndex = new Map;
+  trimAccumulators = new Map;
+  sessionId;
+  scope;
+  constructor(sessionId, config = {}, scope = beginScope({ role: "primary" })) {
+    this.scope = scope;
+    this.sessionId = sessionId;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.fileTime = createFileTime(sessionId);
+  }
+  key(filePath) {
+    return normalizeFilePath(filePath);
+  }
+  licenseKey(filePath) {
+    return normalizeFilePath(realpathOrResolve(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);
+    const droppedAuthorship = this.writtenThisSession.delete(filePath);
+    for (const [syntacticKey, stored] of this.knownPathIndex) {
+      if (stored === filePath)
+        this.knownPathIndex.delete(syntacticKey);
+    }
+    if (reason === "idle-timeout") {
+      if (droppedAuthorship)
+        this.noteExpiredWrite(filePath);
+      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 }
+      });
+    }
+  }
+  noteExpiredWrite(filePath, reason = "idle-timeout") {
+    if (this.expiredWrites.has(filePath))
+      return;
+    this.expiredWrites.add(filePath);
+    if (reason === "authorship-cap") {
+      const isRisingEdge = incrementDegradationCount({
+        kind: "read-guard-authorship-cap",
+        subject: this.sessionId,
+        reason: "authorship cap evicted a live write record"
+      });
+      if (isRisingEdge) {
+        logReadGuardEvent({
+          event: "read_file_evicted",
+          sessionId: this.sessionId,
+          filePath,
+          metadata: { reason, authorshipDropped: true }
+        });
+      }
+      return;
+    }
+    logReadGuardEvent({
+      event: "read_file_evicted",
+      sessionId: this.sessionId,
+      filePath,
+      metadata: { reason, authorshipDropped: true }
+    });
+  }
+  enforceAuthorshipCap() {
+    let excess = this.writtenThisSession.size - READ_GUARD_MAX_AUTHORED_FILES;
+    if (excess <= 0)
+      return;
+    for (const [filePath, authored] of this.writtenThisSession) {
+      if (excess <= 0)
+        return;
+      if (!authored.retired)
+        continue;
+      this.writtenThisSession.delete(filePath);
+      excess -= 1;
+    }
+    for (const filePath of this.writtenThisSession.keys()) {
+      if (excess <= 0)
+        return;
+      this.writtenThisSession.delete(filePath);
+      this.noteExpiredWrite(filePath, "authorship-cap");
+      excess -= 1;
+    }
+  }
+  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");
+    }
+  }
+  dropProvisionalReads() {
+    let dropped = 0;
+    for (const [filePath, records] of this.reads) {
+      const kept = records.filter((record) => {
+        if (!record.provisional)
+          return true;
+        dropped += 1;
+        return false;
+      });
+      if (kept.length === 0)
+        this.reads.delete(filePath);
+      else if (kept.length !== records.length)
+        this.reads.set(filePath, kept);
+    }
+    return dropped;
+  }
+  dropProvisionalReadByCall(toolCallId) {
+    for (const [filePath, records] of this.reads) {
+      const source = `native-read:${toolCallId}:provisional`;
+      const index = records.findIndex((record) => record.source === source);
+      if (index < 0)
+        continue;
+      records.splice(index, 1);
+      if (records.length === 0)
+        this.reads.delete(filePath);
+      return true;
+    }
+    return false;
+  }
+  recordRead(record, opts) {
+    const filePath = this.key(record.filePath);
+    if (opts?.supersedes)
+      this.dropProvisionalReadByCall(opts.supersedes.toolCallId);
+    this.knownPathIndex.set(normalizeEphemeralMapKey(record.filePath), filePath);
+    const storedRecord = {
+      ...record,
+      filePath,
+      lineHashes: record.lineHashes ?? (opts?.captureLineHashes === false ? undefined : 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
+          }
+        });
+      }
+    }
+    if (opts?.stampFileTime !== false)
+      this.fileTime.read(storedRecord.filePath);
+  }
+  retireChangedAuthorship(rawFilePath) {
+    return this.retireIfChanged(this.key(rawFilePath));
+  }
+  noteCheckedPaths(rawToolCallId, rawPaths) {
+    const toolCallId = sanitizeCorrelationId(rawToolCallId);
+    if (toolCallId === undefined || rawPaths.length === 0)
+      return;
+    let checked = this.checkedPathsByCall.get(toolCallId);
+    if (!checked) {
+      checked = new Set;
+      this.checkedPathsByCall.set(toolCallId, checked);
+      while (this.checkedPathsByCall.size > READ_GUARD_MAX_CHECKED_CALLS) {
+        const oldest = this.checkedPathsByCall.keys().next();
+        if (oldest.done === true)
+          break;
+        this.checkedPathsByCall.delete(oldest.value);
+      }
+    }
+    for (const rawPath of rawPaths) {
+      if (checked.size >= READ_GUARD_MAX_CHECKED_PATHS_PER_CALL)
+        return;
+      checked.add(this.licenseKey(rawPath));
+    }
+  }
+  consumeCheckedAtCall(toolCallId, filePath) {
+    const callId = sanitizeCorrelationId(toolCallId);
+    if (callId === undefined)
+      return false;
+    const checked = this.checkedPathsByCall.get(callId);
+    const licensedPath = this.licenseKey(filePath);
+    if (checked?.has(licensedPath) !== true)
+      return false;
+    checked.delete(licensedPath);
+    if (checked.size === 0)
+      this.checkedPathsByCall.delete(callId);
+    return true;
+  }
+  retireIfChanged(filePath, writer, force = false) {
+    const authored = this.writtenThisSession.get(filePath);
+    if (!authored || authored.retired || !force && authoredBytesIntact(filePath, authored))
+      return false;
+    authored.retired = true;
+    const isRisingEdge = incrementDegradationCount({
+      kind: "read-guard-authorship-retired",
+      subject: filePath,
+      reason: force ? "authored range was unknown; the next edit needs a read" : "another writer changed the bytes the conversation wrote; the next edit needs a read"
+    });
+    if (isRisingEdge)
+      logReadGuardEvent({
+        event: "authorship_retired",
+        sessionId: this.sessionId,
+        filePath,
+        metadata: {
+          authoredSize: authored.size,
+          hashed: authored.hash !== undefined,
+          ...writer !== undefined && { writer },
+          ...authored.toolCallId !== undefined && {
+            toolCallId: authored.toolCallId
+          }
+        }
+      });
+    return true;
+  }
+  fileTimeMoved(filePath) {
+    return this.fileTime.hasChanged(this.key(filePath));
+  }
+  diskMovedSinceStamp(filePath) {
+    const key = this.key(filePath);
+    return this.fileTime.get(key) !== undefined && this.fileTime.hasChanged(key);
+  }
+  recordSymbolRead(filePath, symbol, turnIndex, writeIndex, toolCallId) {
+    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(),
+      ...toolCallId !== undefined && { toolCallId }
+    });
+  }
+  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) {
+      this.retireChangedAuthorship(filePath);
+      if (this.writtenThisSession.get(filePath)?.retired) {
+        const verdict = this.blockOrWarn("authorship-retired", `\uD83D\uDD04 RETRYABLE — File modified since your write: \`${filePath}\` no longer holds the bytes this conversation wrote. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
+        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+          reasonKind: "authorship_retired"
+        });
+        return verdict;
+      }
+      const authored = this.writtenThisSession.get(filePath);
+      if (authored && authoredRangeCovers(authored, touchedLines, editRanges)) {
+        const verdict = this.allow();
+        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+          reasonKind: "session_authored"
+        });
+        return verdict;
+      }
+      if (authored) {
+        const verdict = this.blockOrWarn("authorship-range", `\uD83D\uDD04 RETRYABLE — Edit without read: this write only covered part of \`${filePath}\`; read the requested lines first, then retry.`, undefined, effectiveMode);
+        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+          reasonKind: "authorship_range"
+        });
+        return verdict;
+      }
+      const writeRecordExpired = this.expiredWrites.has(filePath);
+      const verdict = this.blockOrWarn("zero-read", writeRecordExpired ? `\uD83D\uDD04 RETRYABLE — Edit without read: the earlier write record for \`${filePath}\` expired, so it needs a read again. Read it first, then retry: \`read path="${filePath}"\`.` : `\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",
+        ...writeRecordExpired ? { writeRecordExpired } : {}
+      });
+      return verdict;
+    }
+    const lastBoundRead = [...fileReads].reverse().find((read) => read.contentBinding !== undefined);
+    if (lastBoundRead?.contentBinding && !currentContentMatchesBinding(filePath, lastBoundRead.contentBinding) && !this.newerReadSupersedesBinding(filePath, fileReads, lastBoundRead, touchedLines, editRanges)) {
+      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 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.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 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;
+      }
+      const snapshotValidation = this.validateRangeSnapshot(filePath, range, !!options?.skipSnapshotCheck);
+      if (snapshotValidation.shouldBlock && !options?.skipSnapshotCheck) {
+        const [editStart, editEnd] = range;
+        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 } : {}
+        }, 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),
+          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,
+      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.keys())
+      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, toolCallId) {
+    this.pendingCreations.set(normalizeEphemeralMapKey(filePath), {
+      turnIndex,
+      writeIndex,
+      ...toolCallId !== undefined && { toolCallId }
+    });
+  }
+  recordWritten(rawFilePath, opts) {
+    if (opts?.branchEpoch !== undefined && opts.branchEpoch !== this.currentBranchEpoch) {
+      incrementDegradationCount({
+        kind: "read-guard-write-after-branch-move",
+        subject: "recordWritten",
+        reason: `a write captured at branch epoch ${opts.branchEpoch} landed at ${this.currentBranchEpoch}; not credited to the new branch`
+      });
+      return;
+    }
+    const filePath = this.key(rawFilePath);
+    this.knownPathIndex.set(normalizeEphemeralMapKey(rawFilePath), filePath);
+    if (opts?.stampFileTime !== false)
+      this.fileTime.read(filePath);
+    this.creditAuthorship(filePath, opts);
+    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, creation.toolCallId, opts?.writtenContent);
+    }
+  }
+  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) ?? [];
+  }
+  contentMatchesLastRead(filePath) {
+    const reads = this.getReadHistory(filePath);
+    const binding = [...reads].reverse().find((read) => read.contentBinding?.fullFile)?.contentBinding;
+    return binding === undefined ? undefined : currentContentMatchesBinding(filePath, binding);
+  }
+  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 }))
+      ])
+    };
+  }
+  exportAuthorship() {
+    return {
+      written: [...this.writtenThisSession].flatMap(([filePath, authored]) => authored.retired ? [] : [filePath]),
+      entries: [...this.writtenThisSession].map(([filePath, authored]) => ({
+        filePath,
+        ...authored
+      }))
+    };
+  }
+  importAuthorship(state, onBranch) {
+    const result = { imported: 0, dropped: 0 };
+    const authorship = state;
+    const entries = Array.isArray(authorship?.entries) ? authorship.entries : [];
+    const withEntry = new Set;
+    for (const entry of entries) {
+      const candidate = entry;
+      if (typeof candidate?.filePath !== "string")
+        continue;
+      withEntry.add(candidate.filePath);
+      if (typeof candidate.toolCallId !== "string" || !onBranch.has(candidate.toolCallId) || typeof candidate.size !== "number" || typeof candidate.mtimeMs !== "number" || typeof candidate.ctimeMs !== "number" || candidate.hash !== undefined && typeof candidate.hash !== "string" || candidate.retired !== undefined && candidate.retired !== true || candidate.authoredRanges !== undefined && !isValidAuthoredRanges(candidate.authoredRanges) || candidate.authoredLineCount !== undefined && typeof candidate.authoredLineCount !== "number") {
+        result.dropped += 1;
+        continue;
+      }
+      const filePath = this.key(candidate.filePath);
+      this.knownPathIndex.set(normalizeEphemeralMapKey(candidate.filePath), filePath);
+      this.writtenThisSession.set(filePath, {
+        size: candidate.size,
+        mtimeMs: candidate.mtimeMs,
+        ctimeMs: candidate.ctimeMs,
+        ...candidate.hash !== undefined && { hash: candidate.hash },
+        toolCallId: candidate.toolCallId,
+        ...candidate.retired === true && { retired: true },
+        ...candidate.authoredRanges !== undefined && {
+          authoredRanges: candidate.authoredRanges
+        },
+        ...candidate.authoredLineCount !== undefined && {
+          authoredLineCount: candidate.authoredLineCount
+        }
+      });
+      result.imported += 1;
+    }
+    this.enforceAuthorshipCap();
+    if (Array.isArray(authorship?.written)) {
+      for (const filePath of authorship.written)
+        if (typeof filePath === "string" && !withEntry.has(filePath))
+          result.dropped += 1;
+    }
+    return result;
+  }
+  retainBranch(onBranch) {
+    const result = { kept: 0, dropped: 0 };
+    for (const [filePath, records] of this.reads) {
+      const kept = [];
+      for (const read of records)
+        if (read.toolCallId !== undefined && onBranch.has(read.toolCallId))
+          kept.push(read);
+      result.kept += kept.length;
+      result.dropped += records.length - kept.length;
+      if (kept.length > 0) {
+        this.reads.set(filePath, kept);
+        continue;
+      }
+      this.reads.delete(filePath);
+    }
+    for (const [filePath, authored] of this.writtenThisSession)
+      if (authored.toolCallId === undefined || !onBranch.has(authored.toolCallId))
+        this.writtenThisSession.delete(filePath);
+    this.edits.clear();
+    this.expiredWrites.clear();
+    this.pendingCreations.clear();
+    this.checkedPathsByCall.clear();
+    this.fileTime.clear();
+    moveBranch(this.scope);
+    return result;
+  }
+  get currentBranchEpoch() {
+    return this.scope.branchEpoch();
+  }
+  get lineageKey() {
+    return `${process.pid}:${this.scope.scopeId}`;
+  }
+  importBranch(state, onBranch) {
+    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);
+      const exists = fs.existsSync(filePath);
+      for (const read of records) {
+        const id = read?.toolCallId;
+        if (!exists || typeof id !== "string" || !onBranch.has(id)) {
+          result.dropped += 1;
+          continue;
+        }
+        this.recordRead({ ...read, filePath, lineHashes: read.lineHashes ?? {} }, { stampFileTime: false });
+        result.imported += 1;
+      }
+    }
+    return result;
+  }
+  getEditHistory(filePath) {
+    const key = this.key(filePath);
+    if (this.edits.has(key))
+      this.touchFile(key);
+    return this.edits.get(key) ?? [];
+  }
+  mayAdvanceAuthorship(filePath, opts) {
+    if (opts?.advanceAuthorship === undefined)
+      return true;
+    if (opts.advanceAuthorship !== true)
+      return false;
+    return this.consumeCheckedAtCall(opts.toolCallId, filePath);
+  }
+  creditAuthorship(filePath, opts) {
+    const existing = this.writtenThisSession.get(filePath);
+    if (!existing && opts?.allowFirstAuthorship === false)
+      return;
+    if (existing?.retired)
+      return;
+    if (opts?.authorship === "unknown") {
+      if (existing)
+        this.retireIfChanged(filePath, "bridge", true);
+      return;
+    }
+    if (existing && !this.mayAdvanceAuthorship(filePath, opts)) {
+      this.retireIfChanged(filePath, "bridge");
+      return;
+    }
+    const observed = observeAuthoredBytes(filePath, opts?.contentHash, opts?.authoredRanges);
+    const { authoredRanges: _observedRanges, ...observedWithoutRanges } = observed;
+    const composedRanges = existing?.authoredRanges === undefined ? existing ? undefined : observed.authoredRanges : opts?.authoredRanges === undefined ? undefined : composeAuthoredRanges(existing, opts.authoredRanges, observed.authoredLineCount);
+    const toolCallId = opts?.toolCallId ?? existing?.toolCallId;
+    this.writtenThisSession.delete(filePath);
+    this.writtenThisSession.set(filePath, {
+      ...observedWithoutRanges,
+      ...composedRanges !== undefined ? {
+        authoredRanges: composedRanges,
+        ...observed.authoredLineCount !== undefined && {
+          authoredLineCount: observed.authoredLineCount
+        }
+      } : {},
+      ...toolCallId !== undefined && { toolCallId }
+    });
+    this.enforceAuthorshipCap();
+  }
+  injectCreationRead(filePath, turnIndex, writeIndex, toolCallId, writtenContent) {
+    let evidence;
+    try {
+      evidence = writtenContent !== undefined ? deliveredLineEvidence(writtenContent, 1) : {
+        lineCount: splitLines(fs.readFileSync(filePath, "utf-8")).length,
+        lineHashes: undefined
+      };
+    } catch {
+      return;
+    }
+    const { lineCount, lineHashes } = evidence;
+    if (lineCount === 0)
+      return;
+    this.recordRead({
+      filePath,
+      requestedOffset: 1,
+      requestedLimit: lineCount,
+      effectiveOffset: 1,
+      effectiveLimit: lineCount,
+      expandedByLsp: false,
+      ...lineHashes && { lineHashes },
+      turnIndex,
+      writeIndex,
+      timestamp: Date.now(),
+      ...toolCallId !== undefined && { toolCallId }
+    });
+  }
+  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(([startLine, endLine]) => {
+      for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+        const view = newestViewOfLine(reads, lineNo);
+        if (!view || !this.readRangeHashesStillMatch(view, lines, [lineNo, lineNo])) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+  validateRangeSnapshot(filePath, [startLine, endLine], snapshotCheckSkipped) {
+    const reads = this.reads.get(filePath) ?? [];
+    const runs = [];
+    const missingLines = [];
+    for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+      const view = newestViewOfLine(reads, lineNo);
+      if (!view || view.lineHashes?.[lineNo] === undefined) {
+        missingLines.push(lineNo);
+        continue;
+      }
+      const last = runs.at(-1);
+      if (last?.read === view && last.range[1] === lineNo - 1) {
+        last.range[1] = lineNo;
+      } else {
+        runs.push({ read: view, range: [lineNo, lineNo] });
+      }
+    }
+    const mismatchedLines = [];
+    let checkedLineCount = 0;
+    for (const { read, range } of runs) {
+      checkedLineCount += range[1] - range[0] + 1;
+      mismatchedLines.push(...currentLinesMatchReadSnapshot(filePath, read, range).mismatchedLines);
+    }
+    const status = mismatchedLines.length > 0 ? "mismatch" : missingLines.length === 0 ? "match" : "unavailable";
+    const shouldBlock = status === "mismatch";
+    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: [startLine, endLine],
+        status,
+        viewRunCount: runs.length,
+        checkedLineCount,
+        missingLineCount: missingLines.length,
+        mismatchedLineCount: mismatchedLines.length,
+        missingLines: missingLines.slice(0, 20),
+        mismatchedLines: mismatchedLines.slice(0, 20),
+        enforced: shouldBlock || status === "match",
+        outcome
+      }
+    });
+    return { status, missingLines, mismatchedLines, 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;
+  }
+  newerReadSupersedesBinding(filePath, fileReads, boundRead, touchedLines, editRanges) {
+    if (!touchedLines)
+      return false;
+    const rangesToCheck = editRanges && editRanges.length > 1 ? editRanges : [touchedLines];
+    const boundIndex = fileReads.lastIndexOf(boundRead);
+    if (boundIndex < 0)
+      return false;
+    for (const candidate of fileReads.slice(boundIndex + 1).reverse()) {
+      if (candidate.provisional === true)
+        continue;
+      const deliversEveryEditedLine = rangesToCheck.every((range) => {
+        const evidence = currentLinesMatchReadSnapshot(filePath, candidate, range);
+        return evidence.checked && evidence.matches;
+      });
+      if (deliversEveryEditedLine)
+        return true;
+    }
+    return false;
+  }
+  findRelocation(filePath, reads, [startLine, endLine]) {
+    const span = endLine - startLine + 1;
+    if (span < 2)
+      return;
+    const source = newestViewOfLine(reads, startLine);
+    if (!source?.lineHashes)
+      return;
+    const wanted = [];
+    for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+      const hash = source.lineHashes[lineNo];
+      if (hash === undefined || newestViewOfLine(reads, lineNo) !== source) {
+        return;
+      }
+      wanted.push(hash);
+    }
+    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);
+}