pi-agent-edit 0.0.0-stage → 0.2.3

package/engine.ts

@@ -0,0 +1,1237 @@
+/**
+ * pi-agent-edit — core engine (pure, no Pi dependency, unit-testable)
+ *
+ * Design principles:
+ *  1. Normalization is ONLY used to *locate* text. Untouched characters are never
+ *     rewritten (fixes the built-in fuzzy path converting fullwidth CJK punctuation
+ *     / curly quotes to ASCII on touched lines).
+ *  2. Match cascade: exact → trailing-whitespace → indentation-insensitive (with
+ *     smart relative re-indent of newText) → loose (whitespace runs + Unicode/NFKC folding)
+ *     → line-number-prefix stripped fallback (when models copy "  12│" from error output).
+ *  3. Every failure returns something the model can act on without re-reading the
+ *     file: closest candidate with line numbers, all ambiguous locations, or a hint
+ *     that the edit was already applied.
+ *  4. All edits in one call resolve against the ORIGINAL file and are applied
+ *     atomically (all-or-nothing).
+ */
+
+export type MatchLevel = "exact" | "trailing-ws" | "indent" | "loose" | "lines";
+
+export interface EditSpec {
+  oldText?: string;
+  newText: string;
+  replaceAll?: boolean;
+  nearLine?: number;
+  startLine?: number;
+  endLine?: number;
+  afterLine?: number;
+}
+
+export interface Decoded {
+  text: string; // BOM stripped; CRLF → LF when the file is purely CRLF
+  bom: boolean;
+  eol: "\n" | "\r\n";
+}
+
+export interface AppliedRange {
+  editIndex: number;
+  level: MatchLevel;
+  start: number;
+  end: number;
+  replacement: string;
+  reindented?: { from: string; to: string };
+  strippedLinePrefixes?: boolean;
+}
+
+export interface Hunk {
+  editIndex: number;
+  level: MatchLevel;
+  oldStartLine: number;
+  newStartLine: number;
+  removed: string[];
+  added: string[];
+  before: string[];
+  after: string[];
+}
+
+export interface ApplyResult {
+  text: string;
+  ranges: AppliedRange[];
+  hunks: Hunk[];
+  added: number;
+  removed: number;
+  /** True when some hunk changed its line count, i.e. lines after it moved. */
+  linesShifted: boolean;
+  notes: string[];
+}
+
+export interface ApplyOptions {
+  /**
+   * Whether line numbers the model remembers can be trusted (fresh read, no shift
+   * since). When false, nearLine is not used to pick among several matches.
+   * Defaults to true.
+   */
+  lineNumbersTrusted?: boolean;
+  /** Human-readable reason shown when nearLine is refused. */
+  untrustedReason?: string;
+  /**
+   * Line numbers a previous ambiguity error showed for THIS exact file content. A nearLine
+   * equal to one of them (and to an actual match) is accepted even when lineNumbersTrusted
+   * is false, so the model can pick an occurrence without re-reading.
+   */
+  offeredNearLines?: ReadonlySet<number>;
+}
+
+export class EditError extends Error {
+  /**
+   * Line numbers this error showed for ambiguous oldText matches. They were computed from
+   * the current file, so they are safe to use as nearLine while the file stays unchanged.
+   */
+  nearLineOffers?: number[];
+}
+
+// ───────────────────────────── encoding ─────────────────────────────
+
+export function decode(raw: string): Decoded {
+  let bom = false;
+  if (raw.charCodeAt(0) === 0xfeff) {
+    bom = true;
+    raw = raw.slice(1);
+  }
+  let crlf = 0;
+  let lf = 0;
+  for (let i = 0; i < raw.length; i++) {
+    if (raw.charCodeAt(i) === 10) {
+      lf++;
+      if (i > 0 && raw.charCodeAt(i - 1) === 13) crlf++;
+    }
+  }
+  // Only normalize when the file is *purely* CRLF, so the round trip is lossless.
+  if (crlf > 0 && crlf === lf) {
+    return { text: raw.replace(/\r\n/g, "\n"), bom, eol: "\r\n" };
+  }
+  return { text: raw, bom, eol: "\n" };
+}
+
+export function encode(d: Decoded, text: string): string {
+  // decode() turned every CRLF into LF and resolveEdit() normalizes newText the same
+  // way, so every LF here maps back to exactly one CRLF. Using /\r?\n/ would also
+  // swallow a lone CR that precedes the LF ("x\r\r\n" → "x\r\n") on untouched lines.
+  const body = d.eol === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+  return (d.bom ? "\ufeff" : "") + body;
+}
+
+// ───────────────────────────── line index ─────────────────────────────
+
+class LineIndex {
+  readonly lines: string[];
+  readonly starts: number[];
+  readonly count: number;
+
+  constructor(readonly text: string) {
+    if (text.length === 0) {
+      this.lines = [];
+      this.starts = [0];
+      this.count = 0;
+      return;
+    }
+    this.lines = text.split("\n");
+    this.starts = new Array(this.lines.length);
+    let p = 0;
+    for (let i = 0; i < this.lines.length; i++) {
+      this.starts[i] = p;
+      p += this.lines[i].length + 1;
+    }
+    // A trailing newline produces an empty last element that is not a real line.
+    this.count = text.endsWith("\n") && this.lines.length > 1 ? this.lines.length - 1 : this.lines.length;
+  }
+
+  /** 0-based line containing offset */
+  lineOf(off: number): number {
+    if (this.count === 0) return 0;
+    if (off <= 0) return 0;
+    if (off >= this.text.length) return this.count - 1;
+    let lo = 0;
+    let hi = this.count - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (this.starts[mid] <= off) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  }
+
+  /** offset just past the last char of line i (i.e. position of its "\n" or text end) */
+  lineEnd(i: number): number {
+    if (this.count === 0) return 0;
+    return this.starts[i] + this.lines[i].length;
+  }
+
+  /** Line i is terminated by CRLF (only possible in mixed-EOL files, which are not decoded). */
+  isCrlfLine(i: number): boolean {
+    return i >= 0 && i < this.count && this.lines[i].endsWith("\r") && this.lineEnd(i) < this.text.length;
+  }
+
+  private _indent?: { style?: "tabs" | "spaces"; step?: number };
+  /** Dominant indentation style and step of the whole file (computed on demand). */
+  get indentInfo(): { style?: "tabs" | "spaces"; step?: number } {
+    if (!this._indent) {
+      const ws = this.lines.slice(0, this.count).filter((l) => l.trim() !== "").map(leadingWs);
+      this._indent = { style: wsStyle(ws), step: commonStep(ws) };
+    }
+    return this._indent;
+  }
+}
+
+// ───────────────────────────── normalizers ─────────────────────────────
+
+const QUOTE_MAP: Record<string, string> = {
+  "\u2018": "'", "\u2019": "'", "\u201a": "'", "\u201b": "'", "\u2032": "'",
+  "\u201c": '"', "\u201d": '"', "\u201e": '"', "\u201f": '"', "\u2033": '"',
+  "\u2010": "-", "\u2011": "-", "\u2012": "-", "\u2013": "-", "\u2014": "-",
+  "\u2015": "-", "\u2212": "-",
+  "\u00a0": " ", "\u3000": " ", "\u2009": " ", "\u200a": " ", "\u202f": " ",
+  "\u200b": "", "\ufeff": "",
+};
+
+const FOLD_RE = /[\u2018\u2019\u201a\u201b\u2032\u201c\u201d\u201e\u201f\u2033\u2010-\u2015\u2212\u00a0\u3000\u2009\u200a\u202f\u200b\ufeff]/g;
+
+function fold(s: string): string {
+  return s.normalize("NFKC").replace(FOLD_RE, (c) => QUOTE_MAP[c] ?? c);
+}
+
+const NORMALIZERS: Record<Exclude<MatchLevel, "exact" | "lines">, (l: string) => string> = {
+  "trailing-ws": (l) => l.replace(/\s+$/, ""),
+  indent: (l) => l.trim(),
+  loose: (l) => fold(l).trim().replace(/\s+/g, " "),
+};
+
+// ───────────────────────────── similarity (diagnostics) ─────────────────────────────
+
+type BigramMap = Map<string, number>;
+
+function bigrams(s: string): BigramMap {
+  const m = new Map<string, number>();
+  for (let i = 0; i < s.length - 1; i++) {
+    const b = s.slice(i, i + 2);
+    m.set(b, (m.get(b) || 0) + 1);
+  }
+  return m;
+}
+
+function similarityWithMap(a: string, A: BigramMap, b: string, B?: BigramMap): number {
+  if (a === b) return 1;
+  if (a.length < 2 || b.length < 2) return a.trim() === b.trim() ? 1 : 0;
+  const mapB = B ?? bigrams(b);
+  let inter = 0;
+  for (const [k, v] of A) {
+    const bv = mapB.get(k);
+    if (bv !== undefined) inter += v < bv ? v : bv;
+  }
+  return (2 * inter) / (a.length - 1 + (b.length - 1));
+}
+
+export function similarity(a: string, b: string): number {
+  if (a === b) return 1;
+  if (a.length < 2 || b.length < 2) return a.trim() === b.trim() ? 1 : 0;
+  return similarityWithMap(a, bigrams(a), b);
+}
+
+// ───────────────────────────── helpers ─────────────────────────────
+
+function splitBody(s: string): { lines: string[]; trailingNL: boolean } {
+  const trailingNL = s.endsWith("\n");
+  const body = trailingNL ? s.slice(0, -1) : s;
+  return { lines: body === "" && trailingNL ? [""] : body.split("\n"), trailingNL };
+}
+
+function leadingWs(s: string): string {
+  return /^[ \t]*/.exec(s)![0];
+}
+
+/** Columns per tab when tabs and spaces have to be compared or converted. */
+const TAB = 4;
+
+function indentCols(ws: string, tabWidth = TAB): number {
+  let cols = 0;
+  for (let i = 0; i < ws.length; i++) {
+    cols += ws.charCodeAt(i) === 9 ? tabWidth : 1;
+  }
+  return cols;
+}
+
+/** "tabs" / "spaces" by majority of indented lines (a leading tab means tab-indented). */
+function wsStyle(wss: string[]): "tabs" | "spaces" | undefined {
+  let tabs = 0;
+  let spaces = 0;
+  for (const w of wss) {
+    if (!w) continue;
+    if (w.charCodeAt(0) === 9) tabs++;
+    else spaces++;
+  }
+  if (!tabs && !spaces) return undefined;
+  return tabs >= spaces ? "tabs" : "spaces";
+}
+
+/** Most frequent positive indentation increase (in columns) between consecutive non-blank lines. */
+function commonStep(wss: string[]): number | undefined {
+  const freq = new Map<number, number>();
+  let prev: number | undefined;
+  for (const w of wss) {
+    const c = indentCols(w);
+    if (prev !== undefined && c > prev) freq.set(c - prev, (freq.get(c - prev) ?? 0) + 1);
+    prev = c;
+  }
+  let best: number | undefined;
+  let bestN = 0;
+  for (const [step, n] of freq) {
+    if (n > bestN || (n === bestN && best !== undefined && step > best)) {
+      best = step;
+      bestN = n;
+    }
+  }
+  return best;
+}
+
+function renderWs(cols: number, useTabs: boolean): string {
+  const c = Math.max(0, Math.round(cols));
+  return useTabs ? "\t".repeat(Math.floor(c / TAB)) + " ".repeat(c % TAB) : " ".repeat(c);
+}
+
+interface ReindentPlan {
+  /** Reference (shallowest) line's whitespace in oldText and in the file; used for notes. */
+  from: string;
+  to: string;
+  /** Exact whitespace mapping observed on the matched lines (only unambiguous entries). */
+  exact: Map<string, string>;
+  /** fileCols = a + s * modelCols */
+  a: number;
+  s: number;
+  useTabs: boolean;
+}
+
+/**
+ * Work out how the model's indentation maps onto the file's, from the line-aligned
+ * oldText ↔ file pairs. Whitespace is always rebuilt as a whole in the file's own
+ * style, so tab-indented newText never leaks tabs into a space-indented file (or vice
+ * versa), which previously produced mixed indentation such as "    \treturn".
+ */
+function planReindent(idx: LineIndex, firstLine: number, oldLines: string[], newText: string): ReindentPlan | undefined {
+  const pairs: { m: string; f: string; mc: number; fc: number }[] = [];
+  for (let j = 0; j < oldLines.length; j++) {
+    if (oldLines[j].trim() === "") continue;
+    const m = leadingWs(oldLines[j]);
+    const f = leadingWs(idx.lines[firstLine + j]);
+    pairs.push({ m, f, mc: indentCols(m), fc: indentCols(f) });
+  }
+  if (!pairs.length || pairs.every((p) => p.m === p.f)) return undefined;
+
+  const newWs = newText.split("\n").filter((l) => l.trim() !== "").map(leadingWs);
+  const modelWs = [...pairs.map((p) => p.m), ...newWs];
+  const regionStyle = wsStyle(pairs.map((p) => p.f));
+  const fileStyle = regionStyle ?? idx.indentInfo.style;
+  const modelStyle = wsStyle(modelWs);
+  const useTabs = (fileStyle ?? modelStyle) === "tabs";
+
+  const exact = new Map<string, string>();
+  const conflicting = new Set<string>();
+  for (const p of pairs) {
+    const seen = exact.get(p.m);
+    if (seen !== undefined && seen !== p.f) conflicting.add(p.m);
+    else exact.set(p.m, p.f);
+  }
+  for (const k of conflicting) exact.delete(k);
+
+  let ref = pairs[0];
+  let hi = pairs[0];
+  for (const p of pairs) {
+    if (p.mc < ref.mc) ref = p;
+    if (p.mc > hi.mc) hi = p;
+  }
+
+  let s: number;
+  if (hi.mc !== ref.mc) {
+    s = (hi.fc - ref.fc) / (hi.mc - ref.mc);
+  } else if (!fileStyle || !modelStyle || fileStyle === modelStyle) {
+    s = 1;
+  } else {
+    // One observed nesting level establishes an offset, not a unit ratio.
+    const fileStep = idx.indentInfo.step ?? commonStep(pairs.map((p) => p.f)) ?? TAB;
+    const modelStep = commonStep(modelWs) ?? TAB;
+    s = fileStep / modelStep;
+  }
+  let a = ref.fc - s * ref.mc;
+  const linear = s > 0 && pairs.every((p) => Math.abs(a + s * p.mc - p.fc) < 0.5);
+  if (!linear) {
+    // Not a clean linear relation: fall back to a plain shift of the reference line.
+    s = 1;
+    a = ref.fc - ref.mc;
+  }
+  return { from: ref.m, to: ref.f, exact, a, s, useTabs };
+}
+
+function applyReindent(newText: string, plan: ReindentPlan): string {
+  return newText
+    .split("\n")
+    .map((l) => {
+      if (l.trim() === "") return "";
+      const ws = leadingWs(l);
+      const mapped = plan.exact.get(ws);
+      const out = mapped !== undefined ? mapped : renderWs(plan.a + plan.s * indentCols(ws), plan.useTabs);
+      return out + l.slice(ws.length);
+    })
+    .join("\n");
+}
+
+// Gutters produced by this tool: "   12│text" (diagnostics / context) and "+    12│text"
+// (added lines in a success diff). Models copy both.
+const LINE_PREFIX_RE = /^\+?[ \t]*\d+[ \t]*[│|]/;
+
+/**
+ * requireAll: every non-blank line must carry a gutter (used to decide whether oldText was
+ * copied with gutters). Without it, only lines that carry one are stripped (used for newText,
+ * where the model often mixes copied gutter lines with freshly typed ones).
+ */
+function tryStripLinePrefixes(text: string, separatorSpace = false, requireAll = true): string | null {
+  const { lines, trailingNL } = splitBody(text);
+  if (lines.length === 0) return null;
+  const nonEmpty = lines.filter((l) => l.trim() !== "");
+  if (nonEmpty.length === 0) return null;
+  if (requireAll ? !nonEmpty.every((l) => LINE_PREFIX_RE.test(l)) : !nonEmpty.some((l) => LINE_PREFIX_RE.test(l))) return null;
+  const stripped = lines.map((l) => {
+    if (!LINE_PREFIX_RE.test(l)) return l;
+    const body = l.replace(LINE_PREFIX_RE, "");
+    return separatorSpace && body.startsWith(" ") ? body.slice(1) : body;
+  }).join("\n");
+  return trailingNL ? stripped + "\n" : stripped;
+}
+
+function fmtLines(ls: number[]): string {
+  const shown = ls.slice(0, 12).join(", ");
+  return ls.length > 12 ? `${shown}, … (${ls.length} total)` : shown;
+}
+
+function clip(s: string, n = 160): string {
+  return s.length > n ? s.slice(0, n) + "…" : s;
+}
+
+// ───────────────────────────── matching ─────────────────────────────
+
+interface Match {
+  start: number;
+  end: number;
+  level: MatchLevel;
+  lineMatch?: { firstLine: number; lastLine: number };
+}
+
+function findExact(idx: LineIndex, oldText: string): Match[] {
+  const out: Match[] = [];
+  let from = 0;
+  for (;;) {
+    const i = idx.text.indexOf(oldText, from);
+    if (i < 0) break;
+    out.push({ start: i, end: i + oldText.length, level: "exact" });
+    from = i + 1; // Include overlapping candidates; application rejects overlaps.
+  }
+  return out;
+}
+
+function findLines(idx: LineIndex, oldText: string, level: keyof typeof NORMALIZERS): Match[] {
+  const norm = NORMALIZERS[level];
+  const { lines: oldLines } = splitBody(oldText);
+  const k = oldLines.length;
+  const n = idx.count;
+  if (k === 0 || k > n) return [];
+
+  const target = oldLines.map(norm);
+  if (target.every((t) => t === "")) return [];
+
+  const anchorIdx = target.findIndex((t) => t !== "");
+  const anchorText = target[anchorIdx];
+
+  const fileNorm = idx.lines.slice(0, n).map(norm);
+  const out: Match[] = [];
+
+  for (let i = 0; i + k <= n; ) {
+    if (fileNorm[i + anchorIdx] !== anchorText) {
+      i++;
+      continue;
+    }
+    let ok = true;
+    for (let j = 0; j < k; j++) {
+      if (j !== anchorIdx && fileNorm[i + j] !== target[j]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) {
+      // Re-indentation is planned later in resolveEdit, where newText is known.
+      out.push({
+        start: idx.starts[i],
+        end: idx.lineEnd(i + k - 1),
+        level,
+        lineMatch: { firstLine: i, lastLine: i + k - 1 },
+      });
+    }
+    i++;
+  }
+  return out;
+}
+
+const CASCADE: (keyof typeof NORMALIZERS)[] = ["trailing-ws", "indent", "loose"];
+
+function locate(idx: LineIndex, oldText: string): Match[] {
+  const exact = findExact(idx, oldText);
+  if (exact.length) return exact;
+  for (const level of CASCADE) {
+    const m = findLines(idx, oldText, level);
+    if (m.length) return m;
+  }
+  return [];
+}
+
+// ───────────────────────────── diagnostics ─────────────────────────────
+
+function diagnoseMissing(idx: LineIndex, edit: EditSpec, i: number): string {
+  const oldText = edit.oldText!;
+  const parts: string[] = [
+    `Edit #${i + 1}: oldText not found in file (tried exact, trailing-whitespace, indentation-insensitive and loose Unicode/whitespace matching).`,
+  ];
+
+  // "Already applied?" is only meaningful when newText is distinctive: it must not be part
+  // of oldText (deleting a line leaves newText ⊂ oldText, and the rest of the file usually
+  // still contains it), and it must occur exactly once. Even then this is only a hint: the
+  // closest candidate is still reported so a false positive cannot hide the real problem.
+  const nt = edit.newText;
+  if (nt.trim() !== "") {
+    const looseBlock = (s: string) => splitBody(s).lines.map(NORMALIZERS.loose).join("\n").trim();
+    if (!looseBlock(oldText).includes(looseBlock(nt))) {
+      const already = locate(idx, nt);
+      if (already.length === 1) {
+        const ln = idx.lineOf(already[0].start) + 1;
+        parts.push(
+          `Hint: newText already exists at line ${ln} — if you already made this change, do not repeat it; ` +
+            `otherwise fix oldText using the closest candidate below.`,
+        );
+      }
+    }
+  }
+
+  const n = idx.count;
+  if (n === 0) {
+    parts.push("The file is currently empty (0 lines). Use afterLine: 0 to insert content.");
+    return parts.join("\n");
+  }
+
+  const { lines: oldLines } = splitBody(oldText);
+  const k = Math.min(oldLines.length, n);
+  const tgt = oldLines.slice(0, k).map(NORMALIZERS.loose);
+  const tgtBigrams = tgt.map(bigrams);
+  const fileNorm = idx.lines.slice(0, n).map(NORMALIZERS.loose);
+
+  const fileBigrams = new Array<BigramMap | undefined>(n);
+  const getFileBigram = (lineIdx: number): BigramMap => {
+    let m = fileBigrams[lineIdx];
+    if (!m) {
+      m = bigrams(fileNorm[lineIdx]);
+      fileBigrams[lineIdx] = m;
+    }
+    return m;
+  };
+
+  let best = { score: -1, line: 0 };
+  const budget = 3_000_000;
+  const totalOps = (n - k + 1) * k;
+  const step = Math.max(1, Math.ceil(totalOps / budget));
+
+  for (let s = 0; s + k <= n; s += step) {
+    let sc = 0;
+    for (let j = 0; j < k; j++) {
+      if (sc + (k - j) <= best.score * k) break;
+      sc += similarityWithMap(tgt[j], tgtBigrams[j], fileNorm[s + j], getFileBigram(s + j));
+    }
+    sc /= k;
+    if (sc > best.score) best = { score: sc, line: s };
+  }
+
+  if (step > 1 && best.score > 0) {
+    const lo = Math.max(0, best.line - step);
+    const hi = Math.min(n - k, best.line + step);
+    for (let s = lo; s <= hi; s++) {
+      let sc = 0;
+      for (let j = 0; j < k; j++) {
+        if (sc + (k - j) <= best.score * k) break;
+        sc += similarityWithMap(tgt[j], tgtBigrams[j], fileNorm[s + j], getFileBigram(s + j));
+      }
+      sc /= k;
+      if (sc > best.score) best = { score: sc, line: s };
+    }
+  }
+
+  if (oldLines.length === 1 && best.score < 0.9) {
+    const t = tgt[0];
+    for (let s = 0; s < n; s++) {
+      if (t.length >= 4 && fileNorm[s].includes(t)) {
+        best = { score: 0.95, line: s };
+        break;
+      }
+    }
+  }
+
+  if (best.score < 0.5) {
+    parts.push("No similar region found. The file has likely changed or you are editing the wrong file — re-read it before retrying.");
+    return parts.join("\n");
+  }
+
+  const a = best.line;
+  const b = Math.min(n - 1, a + oldLines.length - 1);
+  parts.push(`Closest candidate (${Math.round(best.score * 100)}% similar) at lines ${a + 1}-${b + 1}. Actual file content:`);
+  for (let l = a; l <= b; l++) parts.push(`${String(l + 1).padStart(5)}│${idx.lines[l]}`);
+  const diffs: string[] = [];
+  for (let j = 0; j < oldLines.length && a + j <= b; j++) {
+    if (idx.lines[a + j] !== oldLines[j]) {
+      diffs.push(`  line ${a + j + 1}\n    file : ${JSON.stringify(clip(idx.lines[a + j]))}\n    yours: ${JSON.stringify(clip(oldLines[j]))}`);
+      if (diffs.length >= 4) break;
+    }
+  }
+  if (diffs.length) parts.push("First differences:", ...diffs);
+  parts.push("Copy oldText from the actual content above (without the '  12│' line number prefix) and retry.");
+  return parts.join("\n");
+}
+
+// ───────────────────────────── resolve one edit ─────────────────────────────
+
+/**
+ * Mixed-EOL files are not decoded, so a CRLF line's "\r" is part of the line string.
+ * When lines first..last are replaced as whole lines, keep the CR of the last line (it is
+ * that line's terminator, not content) and use CRLF inside the replacement when every
+ * replaced line used it. No-op for decoded (purely CRLF) and purely LF files.
+ */
+function crlfAdjust(idx: LineIndex, crlfMode: boolean, first: number, last: number, end: number, rep: string): { end: number; rep: string } {
+  if (crlfMode || !idx.isCrlfLine(last)) return { end, rep };
+  let all = true;
+  for (let l = first; l <= last; l++) {
+    if (!idx.isCrlfLine(l)) {
+      all = false;
+      break;
+    }
+  }
+  return { end: end - 1, rep: all ? rep.replace(/\r?\n/g, "\r\n") : rep };
+}
+
+/** How many occurrences get a snippet, how far context may grow, how long a suggestion may be. */
+const MAX_SHOWN_OCCURRENCES = 5;
+const MAX_CONTEXT_GROWTH = 6;
+const MAX_SUGGESTION_CHARS = 400;
+/** fmtLines lists this many line numbers; only listed numbers are offered as nearLine. */
+const MAX_LISTED_LINES = 12;
+
+function countExact(text: string, needle: string, limit = 2): number {
+  let n = 0;
+  for (let from = 0; n < limit; n++) {
+    const i = text.indexOf(needle, from);
+    if (i < 0) break;
+    from = i + 1;
+  }
+  return n;
+}
+
+/**
+ * Smallest whole-line window around one occurrence whose exact text is unique in the
+ * file. It is copied from the file, so it always matches exactly.
+ */
+function uniqueContext(idx: LineIndex, first: number, last: number): { first: number; last: number; text: string } | undefined {
+  for (let k = 0; k <= MAX_CONTEXT_GROWTH; k++) {
+    for (let up = 0; up <= k; up++) {
+      const a = first - up;
+      const b = last + (k - up);
+      if (a < 0 || b >= idx.count) continue;
+      const text = idx.text.slice(idx.starts[a], idx.lineEnd(b));
+      if (text.length > MAX_SUGGESTION_CHARS) continue;
+      if (countExact(idx.text, text) === 1) return { first: a, last: b, text };
+    }
+  }
+  return undefined;
+}
+
+function matchLines(idx: LineIndex, m: Match): { first: number; last: number } {
+  if (m.lineMatch) return { first: m.lineMatch.firstLine, last: m.lineMatch.lastLine };
+  const first = idx.lineOf(m.start);
+  return { first, last: Math.max(first, idx.lineOf(m.end > m.start ? m.end - 1 : m.end)) };
+}
+
+/** Numbered snippet of each occurrence plus a ready-to-use unique oldText for it. */
+function describeOccurrences(idx: LineIndex, matches: Match[]): string {
+  const parts: string[] = [];
+  const starts = matches.map((m) => idx.lineOf(m.start));
+  matches.slice(0, MAX_SHOWN_OCCURRENCES).forEach((m, k) => {
+    const { first, last } = matchLines(idx, m);
+    const span = first === last ? `line ${first + 1}` : `lines ${first + 1}-${last + 1}`;
+    parts.push(`[${k + 1}] ${span}:`);
+    const a = Math.max(0, first - 1);
+    const b = Math.min(idx.count - 1, last + 1);
+    for (let l = a; l <= b; l++) {
+      if (l > first + 2 && l < last - 1) {
+        if (l === first + 3) parts.push(`        … ${last - first - 4} lines …`);
+        continue;
+      }
+      parts.push(`${String(l + 1).padStart(5)}│${clip(idx.lines[l].replace(/\r$/, ""))}`);
+    }
+    const u = uniqueContext(idx, first, last);
+    parts.push(
+      u
+        ? `    unique oldText (lines ${u.first + 1}-${u.last + 1}): ${JSON.stringify(u.text)}`
+        : `    no unique oldText within ${MAX_CONTEXT_GROWTH} extra lines / ${MAX_SUGGESTION_CHARS} chars.`,
+    );
+    parts.push(
+      starts.filter((l) => l === first).length > 1
+        ? "    Multiple matches start on this line; nearLine cannot distinguish them. Use unique oldText and change only the intended occurrence in newText."
+        : `    use nearLine: ${first + 1}`,
+    );
+  });
+  if (matches.length > MAX_SHOWN_OCCURRENCES) parts.push(`… ${matches.length - MAX_SHOWN_OCCURRENCES} more occurrence(s) not shown.`);
+  return parts.join("\n");
+}
+
+function ambiguityOptions(count: number, stale: boolean): string {
+  return [
+    "Fix it without re-reading, using one of:",
+    "- oldText: the \"unique oldText\" of the occurrence you mean; repeat its extra context lines unchanged in newText.",
+    `- nearLine: the line shown for that occurrence (keep oldText as is); only works when matches start on different lines.${stale ? " These numbers come from the current file, so they are accepted while it stays unchanged." : ""}`,
+    `- replaceAll: true to change all ${count} occurrences.`,
+  ].join("\n");
+}
+
+/** Largest oldLines × newLines table for LCS; never silently drop preservation above it. */
+const MAX_LCS_CELLS = 4_000_000;
+
+/**
+ * Pairs (oldIndex, newIndex) of lines the model left unchanged, in order.
+ * Longest common subsequence on exact line equality, so moved or inserted lines
+ * around an untouched line do not break the pairing.
+ */
+function unchangedPairs(oldLines: string[], newLines: string[]): [number, number][] {
+  const n = oldLines.length;
+  const m = newLines.length;
+  if (n * m > MAX_LCS_CELLS) {
+    // Peel exact common boundaries first: a large insertion must not normalize
+    // thousands of otherwise untouched file lines. Fail closed if still too large.
+    let prefix = 0;
+    while (prefix < Math.min(n, m) && oldLines[prefix] === newLines[prefix]) prefix++;
+    let suffix = 0;
+    while (suffix < Math.min(n, m) - prefix && oldLines[n - suffix - 1] === newLines[m - suffix - 1]) suffix++;
+    if (!prefix && !suffix) {
+      throw new EditError("No changes written: tolerant edit exceeds the safe line-alignment budget. Split it into smaller edits or use exact file text.");
+    }
+    const out: [number, number][] = [];
+    for (let k = 0; k < prefix; k++) out.push([k, k]);
+    for (const [a, b] of unchangedPairs(oldLines.slice(prefix, n - suffix), newLines.slice(prefix, m - suffix))) {
+      out.push([a + prefix, b + prefix]);
+    }
+    for (let k = suffix; k > 0; k--) out.push([n - k, m - k]);
+    return out;
+  }
+  const w = m + 1;
+  const dp = new Uint32Array((n + 1) * w);
+  for (let a = n - 1; a >= 0; a--) {
+    for (let b = m - 1; b >= 0; b--) {
+      dp[a * w + b] = oldLines[a] === newLines[b]
+        ? dp[(a + 1) * w + b + 1] + 1
+        : Math.max(dp[(a + 1) * w + b], dp[a * w + b + 1]);
+    }
+  }
+  const out: [number, number][] = [];
+  let a = 0;
+  let b = 0;
+  while (a < n && b < m) {
+    if (oldLines[a] === newLines[b]) {
+      out.push([a, b]);
+      a++;
+      b++;
+    } else if (dp[(a + 1) * w + b] >= dp[a * w + b + 1]) a++;
+    else b++;
+  }
+  return out;
+}
+
+/**
+ * In a tolerant line match, a newText line identical to its oldText line is a line the
+ * model did not mean to change. Write the FILE's version of it back verbatim, so tolerant
+ * matching never rewrites whitespace inside untouched lines (string literals, Makefile
+ * tabs, alignment spaces, curly quotes …). Only lines the model actually changed are
+ * re-indented or taken from newText.
+ */
+function keepUntouchedLines(idx: LineIndex, firstLine: number, oldLines: string[], modelLines: string[], rep: string): string {
+  const out = rep.split("\n");
+  if (out.length !== modelLines.length) return rep; // defensive: alignment unknown
+  let changed = false;
+  const lastLine = firstLine + oldLines.length - 1;
+  for (const [o, n] of unchangedPairs(oldLines, modelLines)) {
+    let fileLine = idx.lines[firstLine + o];
+    // Mixed-EOL files keep a CRLF line's "\r" inside its line string, so a preserved line
+    // keeps its own CRLF. Only in the last slot, when the block's last line is CRLF, is that
+    // CR already kept outside the replacement by crlfAdjust and must not be doubled.
+    if (idx.isCrlfLine(firstLine + o) && n === out.length - 1 && idx.isCrlfLine(lastLine)) fileLine = fileLine.slice(0, -1);
+    if (out[n] !== fileLine) {
+      out[n] = fileLine;
+      changed = true;
+    }
+  }
+  return changed ? out.join("\n") : rep;
+}
+
+function resolveEdit(idx: LineIndex, edit: EditSpec, i: number, crlfMode: boolean, opts: ApplyOptions): AppliedRange[] {
+  const tag = `Edit #${i + 1}`;
+  let newText = crlfMode ? edit.newText.replace(/\r\n/g, "\n") : edit.newText;
+  const hasOld = edit.oldText !== undefined && edit.oldText !== null;
+  const hasRange = edit.startLine !== undefined;
+  const hasInsert = edit.afterLine !== undefined;
+  const modes = [hasOld, hasRange, hasInsert].filter(Boolean).length;
+  if (modes !== 1) {
+    throw new EditError(`${tag}: specify exactly one of oldText, startLine(/endLine), or afterLine.`);
+  }
+  for (const field of ["startLine", "endLine", "afterLine", "nearLine"] as const) {
+    const value = edit[field];
+    if (value !== undefined && !Number.isSafeInteger(value)) {
+      throw new EditError(`${tag}: ${field} must be a safe integer.`);
+    }
+  }
+  // Options that do not belong to the chosen locator used to be ignored silently.
+  if (!hasRange && edit.endLine !== undefined) {
+    throw new EditError(`${tag}: endLine only works together with startLine.`);
+  }
+  if (!hasOld && (edit.replaceAll || edit.nearLine !== undefined)) {
+    throw new EditError(`${tag}: replaceAll and nearLine only apply to oldText edits.`);
+  }
+  const n = idx.count;
+
+  // ── insert after line ──
+  if (hasInsert) {
+    const N = edit.afterLine!;
+    if (N < 0 || N > n) throw new EditError(`${tag}: afterLine ${N} out of range (0-${n}).`);
+    if (newText === "") {
+      const pos = N === 0 ? 0 : idx.lineEnd(N - 1);
+      return [{ editIndex: i, level: "lines", start: pos, end: pos, replacement: "" }];
+    }
+    const body = splitBody(newText).lines.join("\n");
+    if (N === 0) {
+      const rep = body + "\n";
+      const crlf = !crlfMode && idx.isCrlfLine(0);
+      return [{ editIndex: i, level: "lines", start: 0, end: 0, replacement: crlf ? rep.replace(/\r?\n/g, "\r\n") : rep }];
+    }
+    if (!crlfMode && idx.isCrlfLine(N - 1)) {
+      // Insert before the CR so the previous line keeps its CRLF and the new lines get one too.
+      const pos = idx.lineEnd(N - 1) - 1;
+      return [{ editIndex: i, level: "lines", start: pos, end: pos, replacement: ("\n" + body).replace(/\r?\n/g, "\r\n") }];
+    }
+    const pos = idx.lineEnd(N - 1);
+    return [{ editIndex: i, level: "lines", start: pos, end: pos, replacement: "\n" + body }];
+  }
+
+  // ── replace / delete line range ──
+  if (hasRange) {
+    const s = edit.startLine!;
+    const e = edit.endLine ?? s;
+    if (s < 1 || e < s || e > n) throw new EditError(`${tag}: line range ${s}-${e} invalid (file has ${n} lines).`);
+    let start = idx.starts[s - 1];
+    let end = idx.lineEnd(e - 1);
+    if (newText === "") {
+      if (end < idx.text.length) end += 1;
+      else if (start > 0) start -= idx.text.slice(start - 2, start) === "\r\n" ? 2 : 1;
+      return [{ editIndex: i, level: "lines", start, end, replacement: "" }];
+    }
+    const adj = crlfAdjust(idx, crlfMode, s - 1, e - 1, end, splitBody(newText).lines.join("\n"));
+    return [{ editIndex: i, level: "lines", start, end: adj.end, replacement: adj.rep }];
+  }
+
+  // ── oldText replacement ──
+  let oldText = edit.oldText!;
+  if (crlfMode) oldText = oldText.replace(/\r\n/g, "\n");
+  if (oldText === "") throw new EditError(`${tag}: oldText is empty. Use afterLine to insert text.`);
+  if (oldText === newText) throw new EditError(`${tag}: oldText and newText are identical — nothing to change.`);
+
+  let matches = locate(idx, oldText);
+  let strippedLinePrefixes = false;
+
+  if (!matches.length) {
+    // The space after the gutter may be display padding OR code indentation.
+    // Prefer a complete-line match, never an indented substring of that line.
+    const candidates = [false, true].map((separatorSpace) => ({
+      separatorSpace, text: tryStripLinePrefixes(oldText, separatorSpace),
+    })).filter((c) => c.text !== null && c.text !== oldText);
+    let chosen: typeof candidates[number] | undefined;
+    for (const level of CASCADE) {
+      for (const candidate of candidates) {
+        const found = findLines(idx, candidate.text!, level);
+        if (found.length) {
+          chosen = candidate;
+          matches = found;
+          break;
+        }
+      }
+      if (chosen) break;
+    }
+    if (chosen) {
+      oldText = chosen.text!;
+      strippedLinePrefixes = true;
+      // newText often mixes copied gutter lines with freshly typed ones; strip every
+      // gutter that is present instead of requiring all lines to carry one (otherwise
+      // the literal "    12│" ended up in the file).
+      const strippedNew = tryStripLinePrefixes(newText, chosen.separatorSpace, false);
+      if (strippedNew !== null) newText = strippedNew;
+    }
+  }
+
+  if (!matches.length) throw new EditError(diagnoseMissing(idx, { ...edit, oldText, newText }, i));
+
+  if (matches.length > 1 && !edit.replaceAll) {
+    const lines = matches.map((m) => idx.lineOf(m.start) + 1);
+    const ambiguous = (lead: string, options: string) => {
+      const err = new EditError(`${tag}: ${lead}\n\n${describeOccurrences(idx, matches)}\n\n${options}`);
+      err.nearLineOffers = lines.slice(0, MAX_LISTED_LINES);
+      return err;
+    };
+    const offered = (n: number) => !!opts.offeredNearLines?.has(n) && lines.includes(n);
+    if (edit.nearLine !== undefined) {
+      if (opts.lineNumbersTrusted === false && !offered(edit.nearLine)) {
+        throw ambiguous(
+          `oldText matches ${matches.length} places (lines ${fmtLines(lines)}). nearLine ${edit.nearLine} was not used ` +
+            `because line numbers may be stale (${opts.untrustedReason ?? "the file was not read since its lines last moved"}).`,
+          ambiguityOptions(matches.length, true),
+        );
+      }
+      const d = lines.map((l) => Math.abs(l - edit.nearLine!));
+      const min = Math.min(...d);
+      const winners = d.filter((x) => x === min).length;
+      if (winners > 1) {
+        throw ambiguous(
+          `oldText matches ${matches.length} places (lines ${fmtLines(lines)}); nearLine ${edit.nearLine} is equally close to several.`,
+          ambiguityOptions(matches.length, false),
+        );
+      }
+      matches = [matches[d.indexOf(min)]];
+    } else {
+      throw ambiguous(`oldText matches ${matches.length} places (lines ${fmtLines(lines)}).`, ambiguityOptions(matches.length, false));
+    }
+  }
+
+  const { lines: oldLines, trailingNL: oldTrailingNL } = splitBody(oldText);
+  return matches.map((m): AppliedRange => {
+    let rep = newText;
+    let end = m.end;
+    let reindented: { from: string; to: string } | undefined;
+    if (m.lineMatch) {
+      const { firstLine, lastLine } = m.lineMatch;
+      if (oldTrailingNL && rep === "") {
+        let start = m.start;
+        if (end < idx.text.length) end += 1;
+        else if (start > 0) start -= idx.text.slice(start - 2, start) === "\r\n" ? 2 : 1;
+        return { editIndex: i, level: m.level, start, end, replacement: "", strippedLinePrefixes };
+      }
+      const modelLines = (rep.endsWith("\n") ? rep.slice(0, -1) : rep).split("\n");
+      if (m.level === "indent" || m.level === "loose") {
+        const plan = planReindent(idx, firstLine, oldLines, rep);
+        if (plan) {
+          rep = applyReindent(rep, plan);
+          reindented = { from: plan.from, to: plan.to };
+        }
+      }
+      // A line match covers whole lines without their terminator, so exactly one trailing
+      // newline of newText is redundant ("X\n" → no blank line, "X\n\n" → one blank line).
+      if (rep.endsWith("\n")) rep = rep.slice(0, -1);
+      rep = keepUntouchedLines(idx, firstLine, oldLines, modelLines, rep);
+      ({ end, rep } = crlfAdjust(idx, crlfMode, firstLine, lastLine, end, rep));
+    }
+    return {
+      editIndex: i,
+      level: m.level,
+      start: m.start,
+      end,
+      replacement: rep,
+      reindented,
+      strippedLinePrefixes,
+    };
+  });
+}
+
+// ───────────────────────────── hunks for the report ─────────────────────────────
+
+function buildHunks(idx: LineIndex, final: LineIndex, ranges: AppliedRange[]): Hunk[] {
+  // Include the line at end as well: deleting its preceding newline can join it
+  // to the start line. Ranges sharing an original line must use one final block.
+  const groups: { first: number; last: number; ranges: AppliedRange[] }[] = [];
+  for (const r of ranges) {
+    const first = idx.lineOf(r.start);
+    const last = idx.lineOf(r.end);
+    const previous = groups[groups.length - 1];
+    if (previous && first <= previous.last) {
+      previous.last = Math.max(previous.last, last);
+      previous.ranges.push(r);
+    } else groups.push({ first, last, ranges: [r] });
+  }
+
+  // Count actual LF boundaries, rather than deriving offsets from hunk sizes.
+  // Both scans advance monotonically, so mapping all windows is linear.
+  let scan = 0;
+  let line = 0;
+  const lineAtBoundary = (offset: number): number => {
+    while (scan < offset) {
+      if (final.text.charCodeAt(scan++) === 10) line++;
+    }
+    return offset === final.text.length ? final.count : line;
+  };
+  let shift = 0;
+  return groups.map((group) => {
+    const start = idx.starts[group.first] ?? 0;
+    const endLine = Math.min(idx.count, group.last + 1);
+    const end = endLine < idx.count ? idx.starts[endLine] : idx.text.length;
+    // At an empty-file insertion the start is line zero, not final.count.
+    const newFirst = start + shift === 0 ? 0 : lineAtBoundary(start + shift);
+    for (const r of group.ranges) shift += r.replacement.length - (r.end - r.start);
+    const newEnd = lineAtBoundary(end + shift);
+    const oldLines = idx.lines.slice(group.first, endLine);
+    const newLines = final.lines.slice(newFirst, newEnd);
+    let pre = 0;
+    while (pre < oldLines.length && pre < newLines.length && oldLines[pre] === newLines[pre]) pre++;
+    let suf = 0;
+    while (
+      suf < oldLines.length - pre && suf < newLines.length - pre &&
+      oldLines[oldLines.length - 1 - suf] === newLines[newLines.length - 1 - suf]
+    ) suf++;
+    const newStart = newFirst + pre;
+    const added = newLines.slice(pre, newLines.length - suf);
+    const r = group.ranges[0];
+    return {
+      editIndex: r.editIndex,
+      level: r.level,
+      oldStartLine: group.first + pre + 1,
+      newStartLine: newStart + 1,
+      removed: oldLines.slice(pre, oldLines.length - suf),
+      added,
+      before: final.lines.slice(Math.max(0, newStart - 2), newStart),
+      after: final.lines.slice(newStart + added.length, Math.min(final.count, newStart + added.length + 2)),
+    };
+  });
+}
+
+// ───────────────────────────── main entry ─────────────────────────────
+
+export function applyEdits(decoded: Decoded, edits: EditSpec[], opts: ApplyOptions = {}): ApplyResult {
+  if (!Array.isArray(edits) || edits.length === 0) throw new EditError("edits must be a non-empty array.");
+  const idx = new LineIndex(decoded.text);
+  const crlf = decoded.eol === "\r\n";
+
+  const ranges: AppliedRange[] = [];
+  const errors: string[] = [];
+  const offers: number[] = [];
+  edits.forEach((e, i) => {
+    try {
+      ranges.push(...resolveEdit(idx, e, i, crlf, opts));
+    } catch (err) {
+      if (!(err instanceof EditError)) throw err;
+      errors.push(err.message);
+      if (err.nearLineOffers) offers.push(...err.nearLineOffers);
+    }
+  });
+  if (errors.length) {
+    const ok = edits.length - errors.length;
+    const err = new EditError(
+      (edits.length > 1 ? `No changes written (edits are all-or-nothing; ${ok} of ${edits.length} edits were OK).\n\n` : "No changes written.\n\n") +
+        errors.join("\n\n"),
+    );
+    if (offers.length) err.nearLineOffers = [...new Set(offers)];
+    throw err;
+  }
+
+  ranges.sort((x, y) => x.start - y.start || x.end - y.end || x.editIndex - y.editIndex);
+  const dedupedRanges: AppliedRange[] = [];
+  for (const r of ranges) {
+    const prev = dedupedRanges[dedupedRanges.length - 1];
+    if (prev && prev.start === r.start && prev.end === r.end && prev.replacement === r.replacement) {
+      continue;
+    }
+    dedupedRanges.push(r);
+  }
+
+  for (let k = 1; k < dedupedRanges.length; k++) {
+    const p = dedupedRanges[k - 1];
+    const c = dedupedRanges[k];
+    if (c.start < p.end) {
+      const lp = idx.lineOf(p.start) + 1;
+      const lc = idx.lineOf(c.start) + 1;
+      throw new EditError(
+        `No changes written. Edit #${p.editIndex + 1} (line ${lp}) and edit #${c.editIndex + 1} (line ${lc}) overlap. ` +
+          `Merge them into a single edit; every edit is matched against the original file.`,
+      );
+    }
+    if (c.start === p.end && c.start === c.end && p.start === p.end) {
+      const lp = idx.lineOf(p.start) + 1;
+      const lc = idx.lineOf(c.start) + 1;
+      throw new EditError(
+        `No changes written. Edit #${p.editIndex + 1} (line ${lp}) and edit #${c.editIndex + 1} (line ${lc}) both insert at the same position. ` +
+          `Merge them into a single edit; every edit is matched against the original file.`,
+      );
+    }
+  }
+
+  let out = "";
+  let cursor = 0;
+  for (const r of dedupedRanges) {
+    out += idx.text.slice(cursor, r.start) + r.replacement;
+    cursor = r.end;
+  }
+  out += idx.text.slice(cursor);
+
+  if (out === idx.text) throw new EditError("No changes written: the edits produce an identical file.");
+
+  const hunks = buildHunks(idx, new LineIndex(out), dedupedRanges);
+  const added = hunks.reduce((sum, h) => sum + h.added.length, 0);
+  const removed = hunks.reduce((sum, h) => sum + h.removed.length, 0);
+  // Reporting merges adjacent ranges. Never use those merged hunks for trust:
+  // opposing deltas can cancel while lines inside the merged block still move.
+  const newlineCount = (s: string) => s.split("\n").length - 1;
+  const unterminated = (s: string) => s.length > 0 && !s.endsWith("\n") ? 1 : 0;
+  const linesShifted = dedupedRanges.some((r) => {
+    let delta = newlineCount(r.replacement) - newlineCount(idx.text.slice(r.start, r.end));
+    if (r.end === idx.text.length) {
+      const tail = r.replacement || idx.text.slice(0, r.start);
+      delta += unterminated(tail) - unterminated(idx.text);
+    }
+    return delta !== 0;
+  });
+
+  const notes: string[] = [];
+  const byEdit = new Map<number, AppliedRange[]>();
+  for (const r of dedupedRanges) byEdit.set(r.editIndex, [...(byEdit.get(r.editIndex) || []), r]);
+  for (const [ei, rs] of [...byEdit].sort((a, b) => a[0] - b[0])) {
+    const lv = rs[0].level;
+    if (rs[0].strippedLinePrefixes) {
+      notes.push(`edit #${ei + 1}: stripped accidental line-number prefixes ("12│") from oldText/newText.`);
+    }
+    if (lv === "trailing-ws") notes.push(`edit #${ei + 1}: matched ignoring trailing whitespace.`);
+    if (lv === "indent" || lv === "loose") {
+      const what = lv === "indent" ? "ignoring indentation" : "ignoring whitespace/Unicode punctuation differences";
+      const ri = rs[0].reindented;
+      const fix = !ri ? "" : ri.from !== ri.to
+        ? `; newText re-indented ${JSON.stringify(ri.from)} → ${JSON.stringify(ri.to)}`
+        : "; newText re-indented to the file's indentation style";
+      notes.push(`edit #${ei + 1}: matched ${what}${fix}. Verify the result below.`);
+    }
+    if (rs.length > 1) notes.push(`edit #${ei + 1}: replaced ${rs.length} occurrences.`);
+  }
+
+  return { text: out, ranges: dedupedRanges, hunks, added, removed, linesShifted, notes };
+}
+
+// ───────────────────────────── report formatting ─────────────────────────────
+
+export function formatReport(res: ApplyResult, opts: { path: string; dryRun?: boolean; maxHunks?: number; maxHunkLines?: number }): string {
+  const maxHunks = opts.maxHunks ?? 12;
+  const maxLines = opts.maxHunkLines ?? 40;
+  let total = 0;
+  if (res.text !== "") {
+    for (let i = 0; i < res.text.length; i++) { if (res.text.charCodeAt(i) === 10) total++; }
+    if (!res.text.endsWith("\n")) total++;
+  }
+  const head = `${opts.dryRun ? "DRY RUN — nothing written. Would edit" : "Edited"} ${opts.path}: ${res.hunks.length} change(s), +${res.added} -${res.removed} lines; file now ${total} lines.`;
+  const out: string[] = [head];
+  if (res.notes.length) out.push(...res.notes.map((n) => "note: " + n));
+
+  const num = (n: number) => String(n).padStart(5);
+  res.hunks.slice(0, maxHunks).forEach((h) => {
+    out.push("");
+    out.push(`@@ edit #${h.editIndex + 1} [${h.level}] old L${h.oldStartLine} → new L${h.newStartLine}`);
+    const body: string[] = [];
+    h.before.forEach((l, k) => body.push(`  ${num(h.newStartLine - h.before.length + k)}│${l}`));
+    h.removed.forEach((l, k) => body.push(`- ${num(h.oldStartLine + k)}│${l}`));
+    h.added.forEach((l, k) => body.push(`+ ${num(h.newStartLine + k)}│${l}`));
+    h.after.forEach((l, k) => body.push(`  ${num(h.newStartLine + h.added.length + k)}│${l}`));
+    if (body.length > maxLines) {
+      const keep = Math.floor(maxLines / 2);
+      out.push(...body.slice(0, keep), `  … ${body.length - 2 * keep} lines omitted …`, ...body.slice(-keep));
+    } else out.push(...body);
+  });
+  if (res.hunks.length > maxHunks) out.push("", `… ${res.hunks.length - maxHunks} more change(s) not shown.`);
+  out.push("", "Line numbers above (new L…) reflect the file after this edit; other line numbers you saw earlier may have shifted.");
+  return out.join("\n");
+}
+
+// ───────────────────────────── whitespace-sensitive files ─────────────────────────────
+
+type WsKind = "python" | "yaml" | "make";
+
+function wsKind(filePath: string): WsKind | undefined {
+  const base = filePath.replace(/\\/g, "/").split("/").pop() ?? "";
+  if (/\.(py|pyi|pyw)$/i.test(base)) return "python";
+  if (/\.(ya?ml)$/i.test(base)) return "yaml";
+  if (/^(GNUmakefile|makefile|Makefile)$/.test(base) || /\.mk$/i.test(base)) return "make";
+  return undefined;
+}
+
+const WS_LABEL: Record<WsKind, string> = { python: "Python", yaml: "YAML", make: "Makefile" };
+
+/** Rule header such as "build: deps" (not ":=" / "::=" assignments, not "X = a:b"). */
+const MAKE_RULE_RE = /^[^\s#=][^=]*?:(?!=)/;
+
+function lineList(ls: number[]): string {
+  return ls.length > 8 ? `${ls.slice(0, 8).join(", ")}, …` : ls.join(", ");
+}
+
+/**
+ * Cheap, textual checks for files whose whitespace carries meaning. They do not parse the
+ * language; they flag the edits most likely to have changed meaning silently, so the model
+ * (and the user) look at the diff or run the parser/tests instead of trusting the match.
+ * Only lines added by this edit are inspected, so pre-existing issues are not reported.
+ */
+export function whitespaceWarnings(filePath: string, res: ApplyResult): string[] {
+  const kind = wsKind(filePath);
+  if (!kind) return [];
+  const label = WS_LABEL[kind];
+  const out: string[] = [];
+
+  const tolerant = [...new Set(res.ranges.filter((r) => r.level === "indent" || r.level === "loose").map((r) => r.editIndex + 1))];
+  if (tolerant.length) {
+    out.push(
+      `${label} is whitespace-sensitive and edit ${tolerant.map((n) => "#" + n).join(", ")} matched only after ignoring ` +
+        `indentation/whitespace. Re-indentation is textual, not syntax-aware: check the diff below and run the parser or tests.`,
+    );
+  }
+
+  const finalLines = res.text.split("\n").map((l) => l.replace(/\r$/, ""));
+  const fileStyle = wsStyle(finalLines.filter((l) => l.trim() !== "").map(leadingWs));
+  const mixed: number[] = [];
+  const offStyle: number[] = [];
+  const yamlTabs: number[] = [];
+  const makeSpaces: number[] = [];
+
+  for (const h of res.hunks) {
+    h.added.forEach((raw, k) => {
+      const line = raw.replace(/\r$/, "");
+      if (line.trim() === "") return;
+      const ln = h.newStartLine + k;
+      const ws = leadingWs(line);
+      if (kind === "python") {
+        if (ws.includes("\t") && ws.includes(" ")) mixed.push(ln);
+        else if (ws && fileStyle && (ws[0] === "\t" ? "tabs" : "spaces") !== fileStyle) offStyle.push(ln);
+      } else if (kind === "yaml") {
+        if (ws.includes("\t")) yamlTabs.push(ln);
+      } else if (ws.startsWith(" ")) {
+        // A recipe line indented with spaces is the classic "missing separator" error.
+        let p = ln - 2;
+        while (p >= 0 && finalLines[p].trim() === "") p--;
+        const prev = p >= 0 ? finalLines[p] : "";
+        if (prev.startsWith("\t") || MAKE_RULE_RE.test(prev)) makeSpaces.push(ln);
+      }
+    });
+  }
+
+  if (mixed.length) out.push(`Python: new line(s) ${lineList(mixed)} mix tabs and spaces in their indentation (TabError risk).`);
+  if (offStyle.length) {
+    out.push(`Python: new line(s) ${lineList(offStyle)} are indented with ${fileStyle === "tabs" ? "spaces" : "tabs"} but the file uses ${fileStyle}.`);
+  }
+  if (yamlTabs.length) out.push(`YAML: new line(s) ${lineList(yamlTabs)} use tabs for indentation, which YAML does not allow.`);
+  if (makeSpaces.length) {
+    out.push(`Makefile: new line(s) ${lineList(makeSpaces)} look like recipe lines but start with spaces; recipes must start with a tab.`);
+  }
+  return out;
+}