@duckmind/dm-linux-x64 0.63.9 → 0.64.2

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

@@ -0,0 +1,1053 @@
+import { createHash } from "node:crypto";
+import * as nodeFs from "node:fs";
+import { BoundedFifoMap } from "./bounded-cache.js";
+import {
+  hostWouldApplyOldText,
+  normalizeForGuardMatch,
+  normalizeToLF,
+  stripBom
+} from "./host-edit-normalize.js";
+import { classifyMutatingTool } from "./mutating-tool.js";
+import {
+  isExactAppliedRetry
+} from "./partial-edit-apply.js";
+import {
+  boundedEditIndexes,
+  createReadGuardEditBatchSummary,
+  logReadGuardEvent
+} from "./read-guard-logger.js";
+export const MAX_FAILURE_TRACKER_SIZE = 200;
+const recentOldTextFailures = new BoundedFifoMap(MAX_FAILURE_TRACKER_SIZE);
+const REPEAT_FAILURE_TTL_MS = 300000;
+function trackOldTextFailure(filePath, preview) {
+  const key = `${filePath}::${preview}`;
+  const now = Date.now();
+  const prev = recentOldTextFailures.get(key);
+  const count = prev && now - prev.lastTs < REPEAT_FAILURE_TTL_MS ? prev.count + 1 : 1;
+  recentOldTextFailures.set(key, { count, lastTs: now });
+  return count;
+}
+export function _trackOldTextFailureForTests(filePath, preview) {
+  return trackOldTextFailure(filePath, preview);
+}
+export function _hasOldTextFailureForTests(filePath, preview) {
+  return recentOldTextFailures.has(`${filePath}::${preview}`);
+}
+function findFirstLineOfOldText(content, oldText) {
+  const firstLine = oldText.replace(/\r\n/g, `
+`).split(`
+`)[0].trim();
+  if (firstLine.length < 5)
+    return;
+  const lines = content.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].trim() === firstLine)
+      return i + 1;
+  }
+  return;
+}
+function tokenizeForSimilarity(text) {
+  return text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+}
+function tokenSimilarity(a, b) {
+  const ta = new Set(tokenizeForSimilarity(a));
+  const tb = new Set(tokenizeForSimilarity(b));
+  if (ta.size === 0 || tb.size === 0)
+    return 0;
+  let intersection = 0;
+  for (const token of ta)
+    if (tb.has(token))
+      intersection += 1;
+  return intersection / (ta.size + tb.size - intersection);
+}
+function findSimilarLines(content, target, options = {}) {
+  const { nearLine, window = 60, max = 3, minScore = 0.5 } = options;
+  const needle = target.trim();
+  if (needle.length < 4)
+    return [];
+  const lines = content.split(`
+`);
+  const start = nearLine ? Math.max(0, nearLine - 1 - window) : 0;
+  const end = nearLine ? Math.min(lines.length, nearLine - 1 + window) : lines.length;
+  const scored = [];
+  for (let i = start;i < end; i += 1) {
+    const text = lines[i];
+    if (text.trim() === "")
+      continue;
+    const score = tokenSimilarity(needle, text);
+    if (score >= minScore)
+      scored.push({ line: i + 1, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, max);
+}
+function formatSimilarLines(suggestions, rawLineAligned) {
+  const rawLines = rawLineAligned.split(`
+`);
+  const pad = (n) => String(n).padStart(4, " ");
+  const rows = suggestions.map(({ line }) => `      ${pad(line)} │ ${(rawLines[line - 1] ?? "").trimEnd()}`);
+  return `
+
+Did you mean one of these current lines?
+${rows.join(`
+`)}`;
+}
+export function countFileLines(filePath) {
+  try {
+    const content = nodeFs.readFileSync(filePath, "utf-8");
+    if (content.length === 0)
+      return 1;
+    return content.split(/\r?\n/).length;
+  } catch {
+    return 1;
+  }
+}
+function normalizeContent(text) {
+  return normalizeForGuardMatch(text);
+}
+function lineNumberAt(content, index) {
+  return content.substring(0, index).split(`
+`).length;
+}
+function overlapPairs(candidates) {
+  const pairs = [];
+  const reported = new Set;
+  for (let i = 0;i < candidates.length; i += 1) {
+    const a = candidates[i];
+    if (reported.has(a))
+      continue;
+    for (let j = i + 1;j < candidates.length; j += 1) {
+      const b = candidates[j];
+      if (reported.has(b))
+        continue;
+      if (b.spanStart < a.spanEnd && a.spanStart < b.spanEnd) {
+        pairs.push([a, b]);
+        reported.add(a);
+        reported.add(b);
+        break;
+      }
+    }
+  }
+  return pairs;
+}
+export function formatAlreadyAppliedNotes(editIndexes) {
+  if (!editIndexes || editIndexes.length === 0)
+    return "";
+  const list = boundedEditIndexes(editIndexes).map((index) => `edits[${index}]`).join(", ");
+  const suffix = editIndexes.length === 1 ? "was" : "were";
+  const pronoun = editIndexes.length === 1 ? "it" : "them";
+  return `
+
+✅ ${list} ${suffix} already applied by an identical earlier edit — the file already contains the result. Do NOT resubmit ${pronoun}.`;
+}
+function findOccurrenceLines(content, needle) {
+  const lines = [];
+  let pos = 0;
+  while (pos < content.length) {
+    const idx = content.indexOf(needle, pos);
+    if (idx === -1)
+      break;
+    lines.push(lineNumberAt(content, idx));
+    pos = idx + needle.length;
+  }
+  return lines;
+}
+function formatOccurrenceContext(content, occurrenceLines, matchSpanLines, maxOccurrences = 5) {
+  const fileLines = content.split(`
+`);
+  const shown = occurrenceLines.slice(0, maxOccurrences);
+  const extra = occurrenceLines.length - shown.length;
+  const pad = (n) => String(n).padStart(4, " ");
+  const blocks = shown.map((startLine) => {
+    const endLine = startLine + matchSpanLines - 1;
+    const before = startLine > 1 ? fileLines[startLine - 2] : undefined;
+    const after = endLine < fileLines.length ? fileLines[endLine] : undefined;
+    const lines = [`  • Line ${startLine}:`];
+    if (before !== undefined)
+      lines.push(`      ${pad(startLine - 1)} │ ${before}`);
+    if (matchSpanLines === 1) {
+      lines.push(`      ${pad(startLine)} │ ${fileLines[startLine - 1] ?? ""}  ← match`);
+    } else {
+      lines.push(`      ${pad(startLine)} │ ${fileLines[startLine - 1] ?? ""}  ← match start`);
+      if (matchSpanLines > 2) {
+        lines.push(`      ${pad(0)} │ … (${matchSpanLines - 2} more line${matchSpanLines - 2 === 1 ? "" : "s"})`);
+      }
+      lines.push(`      ${pad(endLine)} │ ${fileLines[endLine - 1] ?? ""}  ← match end`);
+    }
+    if (after !== undefined)
+      lines.push(`      ${pad(endLine + 1)} │ ${after}`);
+    return lines.join(`
+`);
+  });
+  const tail = extra > 0 ? `
+  • … and ${extra} more occurrence${extra === 1 ? "" : "s"}` : "";
+  return blocks.join(`
+`) + tail;
+}
+function countRawOccurrences(content, needle) {
+  if (!needle)
+    return 0;
+  let count = 0;
+  let pos = 0;
+  while (pos < content.length) {
+    const idx = content.indexOf(needle, pos);
+    if (idx === -1)
+      break;
+    count += 1;
+    pos = idx + needle.length;
+  }
+  return count;
+}
+function exactOldTextForApply(rawContentLf, normalizedContent, oldText, candidate) {
+  const oldTextLf = oldText.replace(/\r\n/g, `
+`);
+  if (countRawOccurrences(rawContentLf, oldTextLf) === 1) {
+    const start = rawContentLf.indexOf(oldTextLf);
+    return { text: oldTextLf, start, end: start + oldTextLf.length };
+  }
+  if (candidate !== oldTextLf && countRawOccurrences(rawContentLf, candidate) === 1) {
+    const start = rawContentLf.indexOf(candidate);
+    return { text: candidate, start, end: start + candidate.length };
+  }
+  if (candidate !== oldTextLf)
+    return;
+  const matchStart = normalizedContent.indexOf(candidate);
+  if (matchStart < 0)
+    return;
+  const rawLines = rawContentLf.split(`
+`);
+  const normalizedLines = normalizedContent.split(`
+`);
+  const rawLineStarts = [];
+  let rawOffset = 0;
+  for (const line of rawLines) {
+    rawLineStarts.push(rawOffset);
+    rawOffset += line.length + 1;
+  }
+  const normalizedLineStarts = [];
+  let normalizedOffset = 0;
+  for (const line of normalizedLines) {
+    normalizedLineStarts.push(normalizedOffset);
+    normalizedOffset += line.length + 1;
+  }
+  const mapOffset = (offset, preferEnd) => {
+    const line = Math.min(normalizedLines.length - 1, normalizedContent.slice(0, offset).split(`
+`).length - 1);
+    const rawLine = rawLines[line] ?? "";
+    const bomOffset = line === 0 && rawLine.startsWith("\uFEFF") ? 1 : 0;
+    const rawMatchLine = rawLine.slice(bomOffset);
+    const target = offset - normalizedLineStarts[line];
+    const normalizedLine = normalizedLines[line] ?? "";
+    if (target >= normalizedLine.length) {
+      if (preferEnd)
+        return rawLineStarts[line] + rawLine.length;
+      return rawLineStarts[line] + bomOffset + rawMatchLine.length;
+    }
+    let lower = 0;
+    let upper = rawMatchLine.length;
+    for (let boundary = 0;boundary <= rawMatchLine.length; boundary += 1) {
+      const length = normalizeContent(rawMatchLine.slice(0, boundary)).length;
+      if (length === target)
+        return rawLineStarts[line] + bomOffset + boundary;
+      if (length < target)
+        lower = boundary;
+      else if (upper === rawMatchLine.length)
+        upper = boundary;
+    }
+    return rawLineStarts[line] + bomOffset + (preferEnd ? upper : lower);
+  };
+  const start = mapOffset(matchStart, false);
+  const end = mapOffset(matchStart + candidate.length, true);
+  const text = rawContentLf.slice(start, end);
+  return normalizeContent(text) === candidate ? { text, start, end } : undefined;
+}
+function resolveOldTextEdits(edits, filePath, sessionId, correlationId, partialApplyRecords) {
+  const startedAt = Date.now();
+  const requestedIndexes = [];
+  const logBatchEvent = (entry) => logReadGuardEvent({ ...entry, correlationId });
+  let rawBytes;
+  try {
+    rawBytes = nodeFs.readFileSync(filePath);
+  } catch {
+    const editBatchSummary = createReadGuardEditBatchSummary({
+      requestedIndexes: edits.map((edit, index) => edit.originalIndex ?? index),
+      rejectedReasons: edits.map((edit, index) => ({
+        index: edit.originalIndex ?? index,
+        code: "preflight_blocked"
+      }))
+    });
+    logBatchEvent({
+      event: "touched_lines_missing",
+      sessionId,
+      filePath,
+      metadata: {
+        tool: "edit",
+        source: "edits_without_ranges",
+        editCount: edits.length
+      }
+    });
+    logBatchEvent({
+      event: "edit_batch_summary",
+      filePath,
+      metadata: { tool: "edit", editBatchSummary }
+    });
+    return { touchedLines: undefined, editBatchSummary };
+  }
+  const rawContent = rawBytes.toString("utf8");
+  const rawContentLf = normalizeToLF(rawContent);
+  const content = normalizeContent(rawContent);
+  const snapshot = {
+    hash: createHash("sha256").update(rawBytes).digest("hex")
+  };
+  const errors = [];
+  const failureKinds = [];
+  const failedEditIndexes = [];
+  const failedOldTextPreviews = [];
+  const rejectedReasons = [];
+  const resolvedIndexes = [];
+  const resolvedRanges = [];
+  const candidateEdits = [];
+  const passedEdits = [];
+  let overlapRejectedCount = 0;
+  const alreadyAppliedEdits = [];
+  let maxFailCount = 0;
+  for (let i = 0;i < edits.length; i++) {
+    const oldText = edits[i].oldText;
+    const editIndex = edits[i].originalIndex ?? i;
+    if (requestedIndexes.length < 100)
+      requestedIndexes.push(editIndex);
+    if (!oldText)
+      continue;
+    if (partialApplyRecords) {
+      const record = partialApplyRecords.find(filePath, oldText, edits[i].newText);
+      if (record && isExactAppliedRetry({
+        contentLf: rawContentLf,
+        oldKey: normalizeContent(oldText),
+        newKey: normalizeContent(edits[i].newText ?? ""),
+        contentHash: snapshot.hash,
+        expectedContentHash: record.contentHash,
+        expectedAfterWriteHash: record.afterWriteContentHash
+      })) {
+        if (alreadyAppliedEdits.length < 100)
+          alreadyAppliedEdits.push(editIndex);
+        logBatchEvent({
+          event: "edit_already_applied_retry",
+          sessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            source: "edits_without_ranges",
+            editIndex
+          }
+        });
+        continue;
+      }
+    }
+    let needle = normalizeContent(oldText);
+    let occurrenceLines = findOccurrenceLines(content, needle);
+    if (occurrenceLines.length === 0) {
+      const corrected = tryCorrectIndentationMismatchFromContent(oldText, rawContentLf);
+      if (corrected !== undefined) {
+        needle = normalizeContent(corrected);
+        occurrenceLines = findOccurrenceLines(content, needle);
+        if (occurrenceLines.length > 0) {
+          logBatchEvent({
+            event: "oldtext_indent_corrected",
+            sessionId,
+            filePath,
+            metadata: {
+              tool: "edit",
+              source: "edits_without_ranges",
+              editIndex
+            }
+          });
+        }
+      }
+    }
+    if (occurrenceLines.length === 0) {
+      const preview = oldText.trimStart().substring(0, 60).replace(/\n/g, "↵");
+      failureKinds.push("oldtext_not_found");
+      if (failedEditIndexes.length < 100) {
+        failedEditIndexes.push(editIndex);
+        failedOldTextPreviews.push(preview);
+      }
+      if (rejectedReasons.length < 100) {
+        rejectedReasons.push({ index: editIndex, code: "oldtext_not_found" });
+      }
+      const failCount = trackOldTextFailure(filePath, preview);
+      if (failCount > maxFailCount)
+        maxFailCount = failCount;
+      let errorMsg = `edits[${editIndex}].oldText ("${preview}") was not found in the current file content.`;
+      const quoteSwapCandidates = [];
+      if (needle.includes('"'))
+        quoteSwapCandidates.push(needle.replace(/"/g, "'"));
+      if (needle.includes("'"))
+        quoteSwapCandidates.push(needle.replace(/'/g, '"'));
+      const quoteHit = quoteSwapCandidates.find((s) => s !== needle && findOccurrenceLines(content, s).length === 1);
+      if (quoteHit !== undefined) {
+        errorMsg += ` The file uses a different quote style — your oldText has ${needle.includes('"') ? "double" : "single"} quotes but the file has ${needle.includes('"') ? "single" : "double"} quotes. Fix the quote style in both oldText and newText before retrying.`;
+      } else {
+        const lineHint = findFirstLineOfOldText(content, oldText);
+        const offsetHint = lineHint !== undefined ? `\`offset=${Math.max(1, lineHint - 2)} limit=20\`` : undefined;
+        if (lineHint !== undefined) {
+          if (failCount >= 2) {
+            errorMsg += ` This is attempt #${failCount} — the first line of your oldText appears near line ${lineHint}` + ` but the surrounding content no longer matches. This is a content-drift failure,` + ` not an indentation issue (indentation autopatch already ran and did not fix it).` + ` Re-read ${offsetHint} and rebuild oldText verbatim from the current file.`;
+          } else {
+            errorMsg += ` The first line of your oldText appears near line ${lineHint} but the rest doesn't match.` + ` The file has likely changed since your last read — this is a content-drift issue, not indentation.` + ` Re-read ${offsetHint} and rebuild oldText from the verbatim file content.`;
+          }
+        } else {
+          if (failCount >= 2) {
+            errorMsg += ` This is attempt #${failCount} — this text does not appear anywhere in the file,` + ` even ignoring whitespace differences. Do NOT retry from memory.` + ` Re-read the relevant section before rebuilding your edit.`;
+          } else {
+            errorMsg += ` This text does not appear anywhere in the file, even ignoring indentation differences —` + ` the file has likely changed significantly. Re-read the relevant section before retrying.`;
+          }
+        }
+      }
+      if (!errorMsg.includes("quote style")) {
+        const similarLines = findSimilarLines(content, oldText.replace(/\r\n/g, `
+`).split(`
+`)[0], { nearLine: findFirstLineOfOldText(content, oldText) });
+        if (similarLines.length > 0) {
+          errorMsg += formatSimilarLines(similarLines, normalizeToLF(stripBom(rawContent).text));
+        }
+      }
+      errors.push(errorMsg);
+      const hostMatch = hostWouldApplyOldText(rawContent, oldText);
+      logBatchEvent({
+        event: "oldtext_not_found",
+        sessionId,
+        filePath,
+        metadata: {
+          tool: "edit",
+          source: "edits_without_ranges",
+          editIndex,
+          oldTextPreview: preview,
+          repeatFailureCount: failCount,
+          hostWouldApply: hostMatch.wouldApply,
+          hostOccurrences: hostMatch.occurrences,
+          hostUsedFuzzyMatch: hostMatch.usedFuzzyMatch
+        }
+      });
+    } else if (occurrenceLines.length === 1) {
+      const startLine = occurrenceLines[0];
+      const endLine = startLine + needle.split(`
+`).length - 1;
+      const applySpan = exactOldTextForApply(rawContentLf, content, oldText, needle);
+      if (applySpan !== undefined) {
+        candidateEdits.push({
+          oldText,
+          appliedSpanText: applySpan.text,
+          newText: edits[i].newText,
+          originalIndex: editIndex,
+          snapshot,
+          spanStart: applySpan.start,
+          spanEnd: applySpan.end
+        });
+        resolvedRanges.push([startLine, endLine]);
+        if (resolvedIndexes.length < 100)
+          resolvedIndexes.push(editIndex);
+      } else {
+        failureKinds.push("oldtext_unrepresentable");
+        if (failedEditIndexes.length < 100)
+          failedEditIndexes.push(editIndex);
+        if (rejectedReasons.length < 100) {
+          rejectedReasons.push({
+            index: editIndex,
+            code: "oldtext_unrepresentable"
+          });
+        }
+        errors.push(`edits[${editIndex}].oldText matched normalized content but could not be mapped to one raw file span; the whole batch must be rebuilt from the current file content.`);
+        logBatchEvent({
+          event: "edit_preflight_blocked",
+          sessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            source: "edits_without_ranges",
+            reasonKind: "oldtext_unrepresentable",
+            editIndex
+          }
+        });
+      }
+      if (applySpan !== undefined) {
+        logBatchEvent({
+          event: "oldtext_resolved",
+          sessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            source: "edits_without_ranges",
+            editIndex,
+            touchedLines: [startLine, endLine]
+          }
+        });
+      }
+    } else {
+      const preview = oldText.trimStart().substring(0, 60).replace(/\n/g, "↵");
+      failureKinds.push("oldtext_duplicate");
+      if (failedEditIndexes.length < 100) {
+        failedEditIndexes.push(editIndex);
+        failedOldTextPreviews.push(preview);
+      }
+      if (rejectedReasons.length < 100) {
+        rejectedReasons.push({ index: editIndex, code: "oldtext_duplicate" });
+      }
+      const matchSpanLines = needle.split(`
+`).length;
+      const contextBlock = formatOccurrenceContext(content, occurrenceLines, matchSpanLines);
+      errors.push(`edits[${editIndex}].oldText ("${preview}") appears ${occurrenceLines.length} times:
+${contextBlock}
+Pick the location you want and extend your oldText with the unique line above or below it (shown as context).`);
+      logBatchEvent({
+        event: "oldtext_duplicate",
+        sessionId,
+        filePath,
+        metadata: {
+          tool: "edit",
+          source: "edits_without_ranges",
+          editIndex,
+          occurrenceLines: occurrenceLines.slice(0, 100),
+          occurrenceCount: occurrenceLines.length,
+          oldTextPreview: preview
+        }
+      });
+    }
+  }
+  const sortedCandidates = [...candidateEdits].sort((a, b) => a.spanStart - b.spanStart);
+  const overlaps = overlapPairs(sortedCandidates);
+  for (let i = 0;i < sortedCandidates.length; i += 1) {
+    const candidate = sortedCandidates[i];
+    const overlapping = sortedCandidates.find((other) => other !== candidate && other.spanStart < candidate.spanEnd && candidate.spanStart < other.spanEnd);
+    if (overlapping) {
+      overlapRejectedCount += 1;
+      if (rejectedReasons.length < 100) {
+        rejectedReasons.push({
+          index: candidate.originalIndex,
+          code: "span_overlap"
+        });
+      }
+      continue;
+    }
+    passedEdits.push(candidate);
+  }
+  for (const [a, b] of overlaps) {
+    errors.push(`edits[${a.originalIndex}] and edits[${b.originalIndex}] resolved to overlapping spans of the file — their oldTexts match regions that share bytes. Extend one oldText with a unique neighboring line so each edit targets one unambiguous span, or apply them in separate calls.`);
+  }
+  if (overlaps.length > 0)
+    passedEdits.length = 0;
+  const oldTextEditCount = edits.filter((edit) => !!edit.oldText).length;
+  if (errors.length === 0 && passedEdits.length === 0 && alreadyAppliedEdits.length > 0 && alreadyAppliedEdits.length === oldTextEditCount) {
+    const header = `✅ ALREADY APPLIED — every edit in this call was already applied by an identical earlier submission. Do NOT retry this payload; re-read the file if you need to build a new edit.`;
+    const details = alreadyAppliedEdits.map((editIndex) => `edits[${editIndex}]: already applied — do not resubmit.`);
+    const editBatchSummary = createReadGuardEditBatchSummary({
+      requestedIndexes,
+      requestedTotal: edits.length,
+      alreadyAppliedIndexes: boundedEditIndexes(alreadyAppliedEdits),
+      alreadyAppliedTotal: alreadyAppliedEdits.length,
+      durationMs: Date.now() - startedAt,
+      terminalStatus: "skipped"
+    });
+    logBatchEvent({
+      event: "edit_batch_summary",
+      correlationId,
+      filePath,
+      metadata: { tool: "edit", editBatchSummary }
+    });
+    return {
+      touchedLines: undefined,
+      preflightError: `${header}
+
+${details.join(`
+`)}`,
+      preflightHeader: header,
+      preflightDetails: details,
+      alreadyAppliedEdits,
+      editBatchSummary
+    };
+  }
+  if (errors.length > 0 || alreadyAppliedEdits.length > 0 || resolvedRanges.length !== oldTextEditCount) {
+    const failureDetails = errors.length > 0 ? errors : alreadyAppliedEdits.map((editIndex) => `edits[${editIndex}]: already applied — do not resubmit.`);
+    const uniqueFailureKinds = [...new Set(failureKinds)];
+    const editBatchSummary = createReadGuardEditBatchSummary({
+      requestedIndexes,
+      requestedTotal: edits.length,
+      resolvedIndexes,
+      resolvedTotal: resolvedRanges.length,
+      rejectedReasons,
+      rejectedTotal: Math.max(0, oldTextEditCount - resolvedRanges.length - alreadyAppliedEdits.length + overlapRejectedCount),
+      alreadyAppliedIndexes: boundedEditIndexes(alreadyAppliedEdits),
+      alreadyAppliedTotal: alreadyAppliedEdits.length,
+      durationMs: Date.now() - startedAt,
+      terminalStatus: "blocked"
+    });
+    logBatchEvent({
+      event: "edit_preflight_blocked",
+      correlationId,
+      sessionId,
+      filePath,
+      metadata: {
+        tool: "edit",
+        source: "edits_without_ranges",
+        reasonKind: uniqueFailureKinds.length === 1 ? uniqueFailureKinds[0] : "oldtext_resolution_failed",
+        failureKinds: uniqueFailureKinds,
+        editCount: edits.length,
+        oldTextEditCount,
+        resolvedOldTextEditCount: resolvedRanges.length,
+        unresolvedOldTextEditCount: oldTextEditCount - resolvedRanges.length,
+        alreadyAppliedCount: alreadyAppliedEdits.length,
+        overlapRejectedCount,
+        failedEditIndexes,
+        oldTextPreviews: failedOldTextPreviews.slice(0, 5),
+        errorCount: errors.length
+      }
+    });
+    const header = errors.length === 0 ? `✅ ALREADY APPLIED — some edits in this call were already applied by an identical earlier submission. Do NOT resubmit them.` : maxFailCount >= 2 ? `\uD83D\uDED1 RE-READ REQUIRED — You have submitted this oldText before and it still does not match.
+
+Do NOT retry from memory. Re-read \`${filePath}\` to get the current content, then rebuild your edit from the verbatim file text.` : uniqueFailureKinds.length === 1 && uniqueFailureKinds[0] === "span_overlap" ? `\uD83D\uDD04 RETRYABLE — Overlapping edit spans` : `\uD83D\uDD04 RETRYABLE — Edit target not found`;
+    logBatchEvent({
+      event: "edit_batch_summary",
+      correlationId,
+      filePath,
+      metadata: { tool: "edit", editBatchSummary }
+    });
+    return {
+      touchedLines: undefined,
+      preflightError: `${header}
+
+${failureDetails.join(`
+
+`)}${formatAlreadyAppliedNotes(alreadyAppliedEdits)}`,
+      preflightHeader: header,
+      preflightDetails: failureDetails,
+      partiallyApplicable: passedEdits.length > 0 && !failureKinds.includes("oldtext_unrepresentable") ? passedEdits : undefined,
+      alreadyAppliedEdits: alreadyAppliedEdits.length > 0 ? alreadyAppliedEdits : undefined,
+      editBatchSummary
+    };
+  }
+  if (resolvedRanges.length === 0) {
+    const editBatchSummary = createReadGuardEditBatchSummary({
+      requestedIndexes,
+      requestedTotal: edits.length,
+      rejectedTotal: oldTextEditCount,
+      terminalStatus: "blocked"
+    });
+    logBatchEvent({
+      event: "touched_lines_missing",
+      sessionId,
+      filePath,
+      metadata: {
+        tool: "edit",
+        source: "edits_without_ranges",
+        editCount: edits.length
+      }
+    });
+    logBatchEvent({
+      event: "edit_batch_summary",
+      filePath,
+      metadata: { tool: "edit", editBatchSummary }
+    });
+    return { touchedLines: undefined, editBatchSummary };
+  }
+  const starts = resolvedRanges.map(([s]) => s);
+  const ends = resolvedRanges.map(([, e]) => e);
+  const touchedLines = [
+    Math.min(...starts),
+    Math.max(...ends)
+  ];
+  const editRanges = resolvedRanges.length > 1 ? resolvedRanges : undefined;
+  logBatchEvent({
+    event: "touched_lines_detected",
+    sessionId,
+    filePath,
+    metadata: {
+      tool: "edit",
+      source: "oldtext_resolved",
+      touchedLines,
+      resolvedEditCount: resolvedRanges.length,
+      totalEditCount: edits.length
+    }
+  });
+  const editBatchSummary = createReadGuardEditBatchSummary({
+    requestedIndexes,
+    requestedTotal: edits.length,
+    resolvedIndexes,
+    resolvedTotal: resolvedRanges.length,
+    durationMs: Date.now() - startedAt,
+    terminalStatus: "success"
+  });
+  return {
+    touchedLines,
+    editRanges,
+    contentMatchValidated: true,
+    editBatchSummary
+  };
+}
+export { stripOldTextTrailingWhitespace } from "./partial-edit-apply.js";
+export function tryCorrectIndentationMismatchFromContent(oldText, content) {
+  const normalized = oldText.replace(/\r\n/g, `
+`);
+  if (content.includes(normalized))
+    return;
+  const conversions = [
+    (s) => s.split(`
+`).map((l) => l.replace(/^\t+/, (m) => "  ".repeat(m.length))).join(`
+`),
+    (s) => s.split(`
+`).map((l) => l.replace(/^\t+/, (m) => "    ".repeat(m.length))).join(`
+`),
+    (s) => s.split(`
+`).map((l) => l.replace(/^( {2})+/, (m) => "\t".repeat(m.length / 2))).join(`
+`),
+    (s) => s.split(`
+`).map((l) => l.replace(/^( {4})+/, (m) => "\t".repeat(m.length / 4))).join(`
+`)
+  ];
+  for (const convert of conversions) {
+    const candidate = convert(normalized);
+    if (candidate !== normalized && content.includes(candidate))
+      return candidate;
+  }
+  const indentationInsensitiveCandidate = findIndentationInsensitiveCandidate(content, normalized);
+  if (indentationInsensitiveCandidate !== undefined) {
+    return indentationInsensitiveCandidate;
+  }
+  const blankLineCandidate = findBlankLineInsensitiveCandidate(content, normalized);
+  if (blankLineCandidate !== undefined) {
+    return blankLineCandidate;
+  }
+  const whitespaceCandidate = findWhitespaceInsensitiveCandidate(content, normalized);
+  if (whitespaceCandidate !== undefined) {
+    return whitespaceCandidate;
+  }
+  const unicodeCandidate = findUnicodePunctuationInsensitiveCandidate(content, normalized);
+  if (unicodeCandidate !== undefined) {
+    return unicodeCandidate;
+  }
+  return;
+}
+export function tryCorrectIndentationMismatch(oldText, filePath) {
+  try {
+    return tryCorrectIndentationMismatchFromContent(oldText, nodeFs.readFileSync(filePath, "utf-8").replace(/\r\n/g, `
+`));
+  } catch {
+    return;
+  }
+}
+function findIndentationInsensitiveCandidate(content, oldText) {
+  const contentLines = content.split(`
+`);
+  const oldLines = oldText.split(`
+`);
+  const stripIndent = (line) => line.replace(/^[\t ]+/, "").trimEnd();
+  const expected = oldLines.map(stripIndent);
+  for (let start = 0;start <= contentLines.length - oldLines.length; start += 1) {
+    let matches = true;
+    for (let offset = 0;offset < oldLines.length; offset += 1) {
+      if (stripIndent(contentLines[start + offset] ?? "") !== expected[offset]) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) {
+      const candidate = contentLines.slice(start, start + oldLines.length).join(`
+`);
+      if (candidate !== oldText)
+        return candidate;
+    }
+  }
+  return;
+}
+function findBlankLineInsensitiveCandidate(content, oldText) {
+  const stripIndent = (line) => line.replace(/^[\t ]+/, "").trimEnd();
+  const isBlank = (line) => stripIndent(line) === "";
+  const contentLines = content.split(`
+`);
+  const oldNonBlank = oldText.split(`
+`).map(stripIndent).filter((line) => line !== "");
+  if (oldNonBlank.length < 2)
+    return;
+  const spans = [];
+  for (let start = 0;start < contentLines.length; start += 1) {
+    if (stripIndent(contentLines[start]) !== oldNonBlank[0])
+      continue;
+    let contentIdx = start + 1;
+    let oldIdx = 1;
+    let end = start;
+    let ok = true;
+    while (oldIdx < oldNonBlank.length) {
+      while (contentIdx < contentLines.length && isBlank(contentLines[contentIdx]))
+        contentIdx += 1;
+      if (contentIdx >= contentLines.length || stripIndent(contentLines[contentIdx]) !== oldNonBlank[oldIdx]) {
+        ok = false;
+        break;
+      }
+      end = contentIdx;
+      oldIdx += 1;
+      contentIdx += 1;
+    }
+    if (ok)
+      spans.push([start, end]);
+  }
+  if (spans.length !== 1)
+    return;
+  const [start, end] = spans[0];
+  const candidate = contentLines.slice(start, end + 1).join(`
+`);
+  return candidate === oldText ? undefined : candidate;
+}
+function findWhitespaceInsensitiveCandidate(content, oldText) {
+  const collapse = (line) => line.replace(/\s+/g, "");
+  const isBlank = (line) => collapse(line) === "";
+  const contentLines = content.split(`
+`);
+  const oldSignature = oldText.split(`
+`).map(collapse).filter((line) => line !== "");
+  if (oldSignature.length < 2)
+    return;
+  const spans = [];
+  for (let start = 0;start < contentLines.length; start += 1) {
+    if (collapse(contentLines[start]) !== oldSignature[0])
+      continue;
+    let contentIdx = start + 1;
+    let sigIdx = 1;
+    let end = start;
+    let ok = true;
+    while (sigIdx < oldSignature.length) {
+      while (contentIdx < contentLines.length && isBlank(contentLines[contentIdx]))
+        contentIdx += 1;
+      if (contentIdx >= contentLines.length || collapse(contentLines[contentIdx]) !== oldSignature[sigIdx]) {
+        ok = false;
+        break;
+      }
+      end = contentIdx;
+      sigIdx += 1;
+      contentIdx += 1;
+    }
+    if (ok)
+      spans.push([start, end]);
+  }
+  if (spans.length !== 1)
+    return;
+  const [start, end] = spans[0];
+  const candidate = contentLines.slice(start, end + 1).join(`
+`);
+  return candidate === oldText ? undefined : candidate;
+}
+function normalizeUnicodePunctuation(text) {
+  return text.replace(/[‘’‚‛]/g, "'").replace(/[“”„‟]/g, '"').replace(/[‐-―−]/g, "-").replace(/[  -   　]/g, " ");
+}
+function findUnicodePunctuationInsensitiveCandidate(content, oldText) {
+  const fold = (line) => normalizeUnicodePunctuation(line).replace(/\s+/g, "");
+  const isBlank = (line) => fold(line) === "";
+  const contentLines = content.split(`
+`);
+  const oldSignature = oldText.split(`
+`).map(fold).filter((line) => line !== "");
+  if (oldSignature.length < 2)
+    return;
+  const spans = [];
+  for (let start = 0;start < contentLines.length; start += 1) {
+    if (fold(contentLines[start]) !== oldSignature[0])
+      continue;
+    let contentIdx = start + 1;
+    let sigIdx = 1;
+    let end = start;
+    let ok = true;
+    while (sigIdx < oldSignature.length) {
+      while (contentIdx < contentLines.length && isBlank(contentLines[contentIdx]))
+        contentIdx += 1;
+      if (contentIdx >= contentLines.length || fold(contentLines[contentIdx]) !== oldSignature[sigIdx]) {
+        ok = false;
+        break;
+      }
+      end = contentIdx;
+      sigIdx += 1;
+      contentIdx += 1;
+    }
+    if (ok)
+      spans.push([start, end]);
+  }
+  if (spans.length !== 1)
+    return;
+  const [start, end] = spans[0];
+  const candidate = contentLines.slice(start, end + 1).join(`
+`);
+  return candidate === oldText ? undefined : candidate;
+}
+export function relocateEditRange(input, from, to) {
+  const delta = to[0] - from[0];
+  if (delta === 0 || !input || typeof input !== "object")
+    return false;
+  const editInput = input;
+  const matchesFrom = (start, end) => start === from[0] && end === from[1];
+  let applied = false;
+  const oldRange = editInput.oldRange;
+  if (oldRange?.start?.line !== undefined && oldRange.end?.line !== undefined && matchesFrom(oldRange.start.line, oldRange.end.line)) {
+    oldRange.start.line += delta;
+    oldRange.end.line += delta;
+    applied = true;
+  }
+  if (Array.isArray(editInput.edits)) {
+    for (const edit of editInput.edits) {
+      const start = edit.range?.start?.line;
+      const end = edit.range?.end?.line ?? start;
+      if (start !== undefined && matchesFrom(start, end)) {
+        edit.range.start.line = start + delta;
+        if (edit.range?.end?.line !== undefined) {
+          edit.range.end.line += delta;
+        }
+        applied = true;
+      }
+    }
+  }
+  return applied;
+}
+export function getTouchedLinesForGuard(event, filePath, sessionId, correlationId, partialApplyRecords) {
+  const mutation = classifyMutatingTool(event, {
+    filePath,
+    sessionId,
+    correlationId
+  });
+  if (mutation === undefined)
+    return { touchedLines: undefined };
+  if (mutation.kind === "edit") {
+    if (mutation.touchedLines !== undefined || mutation.preflightError) {
+      return {
+        touchedLines: mutation.touchedLines,
+        ...mutation.editRanges ? { editRanges: mutation.editRanges } : {},
+        ...mutation.preflightError ? { preflightError: mutation.preflightError } : {},
+        ...mutation.editBatchSummary ? { editBatchSummary: mutation.editBatchSummary } : {}
+      };
+    }
+    const editInput = event.input;
+    if (editInput.oldRange) {
+      const touchedLines = [
+        editInput.oldRange.start.line,
+        editInput.oldRange.end.line
+      ];
+      if (filePath) {
+        logReadGuardEvent({
+          event: "touched_lines_detected",
+          correlationId,
+          sessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            source: "oldRange",
+            touchedLines
+          }
+        });
+      }
+      return { touchedLines };
+    }
+    if (editInput.edits?.length) {
+      const rangedEdits = editInput.edits.map((edit) => {
+        const start = edit.range?.start?.line;
+        const end = edit.range?.end?.line ?? start;
+        if (typeof start !== "number" || typeof end !== "number") {
+          return null;
+        }
+        return [start, end];
+      }).filter((range) => range !== null);
+      const unresolvedOldTextEdits = editInput.edits.map((edit, index) => ({ ...edit, originalIndex: index })).filter((edit) => typeof edit.range?.start?.line !== "number" && !!edit.oldText);
+      if (rangedEdits.length === 0) {
+        if (filePath) {
+          return resolveOldTextEdits(editInput.edits, filePath, sessionId, correlationId, partialApplyRecords);
+        }
+        return { touchedLines: undefined };
+      }
+      let oldTextTouchedLines;
+      let oldTextEditRanges;
+      if (unresolvedOldTextEdits.length > 0 && filePath) {
+        const resolved = resolveOldTextEdits(unresolvedOldTextEdits, filePath, sessionId, correlationId, partialApplyRecords);
+        if (resolved.preflightError) {
+          return {
+            ...resolved,
+            partiallyApplicable: undefined,
+            touchedLines: undefined
+          };
+        }
+        oldTextTouchedLines = resolved.touchedLines;
+        oldTextEditRanges = resolved.editRanges;
+      }
+      const starts = rangedEdits.map(([start]) => start);
+      const ends = rangedEdits.map(([, end]) => end);
+      if (oldTextTouchedLines) {
+        starts.push(oldTextTouchedLines[0]);
+        ends.push(oldTextTouchedLines[1]);
+      }
+      const touchedLines = [
+        Math.min(...starts),
+        Math.max(...ends)
+      ];
+      const allEditRanges = [...rangedEdits];
+      if (oldTextEditRanges?.length) {
+        allEditRanges.push(...oldTextEditRanges);
+      } else if (oldTextTouchedLines) {
+        allEditRanges.push(oldTextTouchedLines);
+      }
+      const editRanges = allEditRanges.length > 1 ? allEditRanges : undefined;
+      if (filePath) {
+        logReadGuardEvent({
+          event: "touched_lines_detected",
+          correlationId,
+          sessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            source: unresolvedOldTextEdits.length > 0 ? "edits_mixed" : "edits_ranges",
+            touchedLines,
+            rangedEditCount: rangedEdits.length,
+            resolvedOldTextEditCount: unresolvedOldTextEdits.length,
+            totalEditCount: editInput.edits.length
+          }
+        });
+      }
+      return { touchedLines, editRanges };
+    }
+    if (filePath) {
+      const topLevelKeys = Object.keys(editInput);
+      logReadGuardEvent({
+        event: "touched_lines_missing",
+        correlationId,
+        sessionId,
+        filePath,
+        metadata: {
+          tool: "edit",
+          source: "unknown_edit_schema",
+          mutatingToolName: mutation.toolName,
+          mutationProvenance: mutation.provenance,
+          adapterSource: mutation.source,
+          unresolvedReason: mutation.unresolvedReason,
+          topLevelKeys,
+          hasNativeOldRange: !!editInput.oldRange,
+          hasNativeEdits: Array.isArray(editInput.edits),
+          hasHashlineSetLine: !!editInput.set_line,
+          hasHashlineReplaceLines: !!editInput.replace_lines,
+          hasHashlineReplaceSymbol: !!editInput.replace_symbol,
+          hasHashlineBatch: Array.isArray(editInput.operations) || Array.isArray(editInput.ops),
+          strictModeWouldBlock: true
+        }
+      });
+    }
+    return { touchedLines: undefined };
+  }
+  const lineCount = filePath ? countFileLines(filePath) : 1;
+  const writeTouchedLines = [1, lineCount];
+  if (filePath) {
+    logReadGuardEvent({
+      event: "touched_lines_detected",
+      correlationId,
+      sessionId,
+      filePath,
+      metadata: {
+        tool: "write",
+        source: "full_file_write",
+        touchedLines: writeTouchedLines,
+        lineCount
+      }
+    });
+  }
+  return { touchedLines: writeTouchedLines };
+}