dsh-hashline-edit 0.2.2 → 0.3.0

package/src/apply-patch/plan.ts

@@ -0,0 +1,800 @@
+/**
+ * apply_patch v4 — planner.
+ *
+ * Turns a parsed `PatchDocument` into a `PatchPlan`: loads one baseline per
+ * touched file, resolves every hunk against that baseline, validates paths,
+ * lifecycle targets, served anchors and overlap, and materializes Copy/Cut
+ * sources. Planning is read-only; the commit seam consumes the plan.
+ *
+ * Data flow: grammar.parse → **plan** → commit → render.
+ *
+ * @module dsh-hashline-edit/apply-patch/plan
+ */
+import { stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative as relativePath, resolve as resolvePath } from "node:path";
+import { DomainError, type DomainErrorCode } from "../domain-errors.js";
+import { SERVED_ROWS_CAP } from "../constants.js";
+import { decodeNormText } from "../file-content/index.js";
+import { isPathWithinWorkspace } from "../fs-lifecycle.js";
+import { defaultHashIdentity } from "../hashline/hash-identity.js";
+import type { LeaseSpanSource } from "../hashline/resolve.js";
+import { loadHashStore, type HashStore } from "../hash-store.js";
+import { leaseSpanSource } from "../mutation-engine/edit-source.js";
+import {
+  buildRangeServeBlock,
+  fmtServedRows,
+  paginationHint,
+} from "../served-session/serve-render.js";
+import { createSessionHandle } from "../served-session/session.js";
+import { errCode } from "../utils.js";
+import {
+  baselineLinesOf,
+  checkMutationOverlaps,
+  matchFragmentHunk,
+  resolveIdentityHunk,
+  resolveReferenceHunk,
+  type ResolveContext,
+  type ServedAnchors,
+} from "./resolve.js";
+import type {
+  ApplyPatchEngineOptions,
+  FileBaseline,
+  LifecyclePlan,
+  PatchDocument,
+  PatchPath,
+  PatchPlan,
+  PatchProblem,
+  PatchStats,
+  PlannedMutation,
+  PlannedReferenceUse,
+  PlanPatchResult,
+} from "./types.js";
+
+/**
+ * The baseline/served loader port.
+ *
+ * Production wires `readBaseline` to the file-content decode path,
+ * `readServed` to `createSessionHandle(...).load()` and `readLeaseSource` to
+ * the read-only lease identity source. Tests inject a pure in-memory
+ * implementation, which is what makes the planner testable without a store.
+ */
+export interface PlanFileLoader {
+  /** Load one file's baseline (LF-normalized text + anchors + BOM + ending). */
+  readBaseline(path: PatchPath, absolutePath: string, signal?: AbortSignal): Promise<FileBaseline>;
+  /** Load this session's served anchors for one file, parallel to its lines. */
+  readServed(absolutePath: string, sessionKey: string, store?: HashStore): Promise<ServedAnchors>;
+  /** Session-wide anchor homes, for foreign-anchor diagnosis (optional legacy port). */
+  anchorHomes?(anchor: string, sessionKey: string, store?: HashStore): readonly PatchPath[];
+  /** Build the read-only lease identity source for one file's baseline content. */
+  readLeaseSource?(
+    absolutePath: string,
+    sessionKey: string,
+    content: string,
+    store?: HashStore,
+  ): Promise<LeaseSpanSource>;
+}
+
+/** Options for {@link planApplyPatch}; `loader` is the test seam. */
+export interface PlanApplyPatchOptions extends ApplyPatchEngineOptions {
+  readonly loader?: PlanFileLoader;
+}
+
+/** A baseline for a file that does not exist yet (Add File / missing target). */
+export function absentBaseline(path: PatchPath, absolutePath: string): FileBaseline {
+  return {
+    path,
+    absolutePath,
+    text: "",
+    hashes: [],
+    bom: "",
+    ending: "\n",
+    exists: false,
+  };
+}
+
+/** The production loader over node:fs, the file-content decoder and the hash store. */
+export function createDefaultPlanFileLoader(): PlanFileLoader {
+  return {
+    async readBaseline(path, absolutePath, signal) {
+      let info;
+      try {
+        info = await stat(absolutePath);
+      } catch (error) {
+        if (errCode(error) === "ENOENT") return absentBaseline(path, absolutePath);
+        throw error;
+      }
+      if (!info.isFile()) {
+        throw new DomainError("E_UNSUPPORTED_FILE", {
+          path,
+          kind: info.isDirectory() ? "directory" : "binary",
+        });
+      }
+      const normalized = await decodeNormText(
+        absolutePath,
+        dirname(absolutePath),
+        signal === undefined ? undefined : { signal },
+      );
+      if (normalized.hadUtf8DecodeErrors) {
+        throw new DomainError("E_LOSSY_TEXT", { path });
+      }
+      const hashes = await defaultHashIdentity.hashesFor(normalized.normalized, {
+        path: normalized.absolutePath,
+        persist: false,
+      });
+      return {
+        path,
+        absolutePath: normalized.absolutePath,
+        text: normalized.normalized,
+        hashes,
+        bom: normalized.bom,
+        ending: normalized.originalEnding,
+        exists: true,
+      };
+    },
+    async readServed(absolutePath, sessionKey, store) {
+      const hashStore = store ?? (await loadHashStore());
+      return createSessionHandle(sessionKey, absolutePath, hashStore).load();
+    },
+    async readLeaseSource(absolutePath, sessionKey, content, store) {
+      const hashStore = store ?? (await loadHashStore());
+      return leaseSpanSource({ store: hashStore, sessionKey, absolutePath, content });
+    },
+  };
+}
+
+interface ResolvedRequestPath {
+  readonly path: PatchPath;
+  readonly absolutePath: string;
+}
+
+function resolveRequestPath(
+  path: PatchPath,
+  cwd: string,
+):
+  | { readonly ok: true; readonly value: ResolvedRequestPath }
+  | { readonly ok: false; readonly message: string } {
+  if (path.length === 0) return { ok: false, message: "path must not be empty" };
+  if (path.includes("\0")) return { ok: false, message: "path contains a null byte" };
+  const segments = path.split(/[\\/]+/u).filter((segment) => segment.length > 0);
+  if (segments.includes("..")) {
+    return { ok: false, message: 'path must stay inside the workspace: ".." is not allowed' };
+  }
+  if (segments.some((segment) => segment.toLowerCase() === ".git")) {
+    return { ok: false, message: "path may not name a .git entry" };
+  }
+  const cwdAbsolute = resolvePath(cwd);
+  const absolutePath = isAbsolute(path) ? resolvePath(path) : resolvePath(cwdAbsolute, path);
+  const relative = relativePath(cwdAbsolute, absolutePath);
+  if (relative.startsWith("..") || isAbsolute(relative)) {
+    return { ok: false, message: "path must stay inside the workspace" };
+  }
+  return { ok: true, value: { path, absolutePath } };
+}
+
+/**
+ * Reject a target whose fully-resolved location escapes the workspace. The check runs before any
+ * baseline load or mkdir, so an Add/Move destination under a symlink/junction ancestor can never
+ * be created outside `cwd`.
+ */
+async function workspaceEscapeMessage(
+  cwd: string,
+  absolutePath: string,
+): Promise<string | undefined> {
+  try {
+    if (await isPathWithinWorkspace(cwd, absolutePath)) return undefined;
+  } catch (error) {
+    return `path boundary could not be checked: ${messageOf(error)}`;
+  }
+  return "path escapes the workspace through a symlink or junction";
+}
+
+function messageOf(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  return raw.replace(/^\[(?:MODEL|USER)\] \[[EW]_[A-Z0-9_]+\] /u, "");
+}
+
+function codeOf(error: unknown): DomainErrorCode | "E_PATCH_SYNTAX" {
+  return error instanceof DomainError ? error.code : "E_PATCH_SYNTAX";
+}
+
+/** Apply resolved baseline-coordinate mutations to a line array (descending, so coordinates stay valid). */
+export function applyPlannedMutations(
+  lines: readonly string[],
+  mutations: readonly PlannedMutation[],
+): string[] {
+  const result = [...lines];
+  const ordered = mutations
+    .map((mutation, index) => ({ mutation, index }))
+    .sort((left, right) => {
+      const a = left.mutation.range;
+      const b = right.mutation.range;
+      if (a.startLine !== b.startLine) return b.startLine - a.startLine;
+      const aInsert = a.startLine > a.endLine;
+      const bInsert = b.startLine > b.endLine;
+      // WHY: a replacement owns the line at this coordinate; it must land before zero-width
+      // WHY: insertions that name the position immediately before it.
+      if (aInsert !== bInsert) return aInsert ? 1 : -1;
+      // WHY: equal-point insertions are applied in reverse submission order so splice() leaves
+      // WHY: them in submission order in the final text.
+      if (aInsert && bInsert) return right.index - left.index;
+      const endDiff = b.endLine - a.endLine;
+      return endDiff !== 0 ? endDiff : right.index - left.index;
+    })
+    .map((entry) => entry.mutation);
+  for (const mutation of ordered) {
+    const insertAt = Math.max(0, mutation.range.startLine - 1);
+    const removeCount = Math.max(0, mutation.range.endLine - mutation.range.startLine + 1);
+    result.splice(insertAt, removeCount, ...mutation.lines);
+  }
+  return result;
+}
+
+export function mutationDelta(
+  baselineLines: readonly string[],
+  mutation: PlannedMutation,
+): { added: number; removed: number } {
+  const start = Math.max(0, mutation.range.startLine - 1);
+  const end = Math.max(start, mutation.range.endLine);
+  const oldSlice = baselineLines.slice(start, end);
+  const newLines = mutation.lines;
+  let prefix = 0;
+  while (
+    prefix < oldSlice.length &&
+    prefix < newLines.length &&
+    oldSlice[prefix] === newLines[prefix]
+  ) {
+    prefix += 1;
+  }
+  let suffix = 0;
+  while (
+    suffix < oldSlice.length - prefix &&
+    suffix < newLines.length - prefix &&
+    oldSlice[oldSlice.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) {
+    suffix += 1;
+  }
+  return { added: newLines.length - prefix - suffix, removed: oldSlice.length - prefix - suffix };
+}
+
+function computeStats(entries: readonly PlannedFileEntry[]): PatchStats {
+  let filesChanged = 0;
+  let addedLines = 0;
+  let removedLines = 0;
+  for (const entry of entries) {
+    if (!entry.writes) continue;
+    filesChanged += 1;
+    if (entry.lifecycle.kind === "delete") {
+      removedLines += baselineLinesOf(entry.baseline).length;
+      continue;
+    }
+    const baselineLines = baselineLinesOf(entry.baseline);
+    for (const mutation of entry.mutations) {
+      const delta = mutationDelta(baselineLines, mutation);
+      addedLines += delta.added;
+      removedLines += delta.removed;
+    }
+  }
+  return { filesChanged, addedLines, removedLines };
+}
+
+interface PlannedFileEntry {
+  readonly path: PatchPath;
+  readonly absolutePath: string;
+  readonly baseline: FileBaseline;
+  lifecycle: LifecyclePlan;
+  readonly mutations: PlannedMutation[];
+  readonly references: PlannedReferenceUse[];
+  writes: boolean;
+}
+
+function entryFor(
+  path: PatchPath,
+  absolutePath: string,
+  baseline: FileBaseline,
+  lifecycle: LifecyclePlan,
+): PlannedFileEntry {
+  return {
+    path,
+    absolutePath,
+    baseline,
+    lifecycle,
+    mutations: [],
+    references: [],
+    writes: lifecycle.kind !== "keep",
+  };
+}
+
+function markWrites(entry: PlannedFileEntry): void {
+  if (entry.mutations.length > 0) entry.writes = true;
+}
+
+/**
+ * Plan one apply_patch call without writing anything.
+ *
+ * All hunks resolve against the pre-call baseline (never chained application);
+ * a later hunk's fragment window begins after the previous hunk's end. Any
+ * problem aborts the whole call: the returned list is every independently
+ * diagnosable problem, not just the first, together with the current rows of
+ * every named file (reject-and-serve).
+ *
+ * @param document - the parsed patch AST.
+ * @param options - cwd/session/store plus the optional baseline loader.
+ * @returns the plan, or every problem found plus the rows to serve.
+ */
+export async function planApplyPatch(
+  document: PatchDocument,
+  options: PlanApplyPatchOptions,
+): Promise<PlanPatchResult> {
+  const loader = options.loader ?? createDefaultPlanFileLoader();
+  const problems: PatchProblem[] = [];
+  const entries: PlannedFileEntry[] = [];
+  const byAbsolute = new Map<string, PlannedFileEntry>();
+  const baselines = new Map<string, FileBaseline>();
+  const pathToAbsolute = new Map<string, string>();
+  const documentPaths = new Set<string>();
+  const servedCache = new Map<string, ServedAnchors>();
+  const identityCache = new Map<string, LeaseSpanSource>();
+  const referenceBaselines = new Map<string, FileBaseline>();
+
+  const loadBaseline = async (
+    path: PatchPath,
+    absolutePath: string,
+    patchLine: number,
+  ): Promise<FileBaseline | undefined> => {
+    const cached = baselines.get(absolutePath);
+    if (cached !== undefined) return cached;
+    try {
+      const baseline = await loader.readBaseline(path, absolutePath, options.signal);
+      const requested = resolvePath(absolutePath);
+      const resolvedBaseline =
+        process.platform === "win32" ? baseline.absolutePath.toLowerCase() : baseline.absolutePath;
+      const requestedBaseline = process.platform === "win32" ? requested.toLowerCase() : requested;
+      if (resolvedBaseline !== requestedBaseline) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine,
+          path,
+          message: `symbolic link target is not allowed: ${path}`,
+        });
+        return undefined;
+      }
+      baselines.set(absolutePath, baseline);
+      pathToAbsolute.set(path, absolutePath);
+      return baseline;
+    } catch (error) {
+      problems.push({
+        code: codeOf(error),
+        patchLine,
+        path,
+        message: messageOf(error),
+      });
+      return undefined;
+    }
+  };
+
+  const contextFor = async (
+    baseline: FileBaseline,
+    needServed: boolean,
+  ): Promise<ResolveContext> => {
+    const absolutePath = baseline.absolutePath;
+    let served = needServed ? servedCache.get(absolutePath) : [];
+    if (served === undefined) {
+      served = await loader.readServed(absolutePath, options.sessionKey, options.store);
+      servedCache.set(absolutePath, served);
+    }
+    let identity = identityCache.get(absolutePath);
+    if (needServed && identity === undefined && loader.readLeaseSource !== undefined) {
+      identity = await loader.readLeaseSource(
+        absolutePath,
+        options.sessionKey,
+        baseline.text,
+        options.store,
+      );
+      identityCache.set(absolutePath, identity);
+    }
+    return { baseline, served, ...(identity !== undefined ? { identity } : {}) };
+  };
+
+  const ensureSourceEntry = async (
+    path: PatchPath,
+    absolutePath: string,
+    patchLine: number,
+  ): Promise<PlannedFileEntry | undefined> => {
+    const existing = byAbsolute.get(absolutePath);
+    if (existing !== undefined) return existing;
+    const baseline = await loadBaseline(path, absolutePath, patchLine);
+    if (baseline === undefined) return undefined;
+    if (!baseline.exists) {
+      problems.push({
+        code: "E_NOT_FOUND",
+        patchLine,
+        path,
+        message: `source file not found: ${path}`,
+      });
+      return undefined;
+    }
+    const entry = entryFor(path, absolutePath, baseline, { kind: "keep" });
+    entries.push(entry);
+    byAbsolute.set(absolutePath, entry);
+    documentPaths.add(absolutePath);
+    return entry;
+  };
+
+  for (const op of document.files) {
+    const resolved = resolveRequestPath(op.path, options.cwd);
+    if (!resolved.ok) {
+      problems.push({
+        code: "E_PATCH_SYNTAX",
+        patchLine: op.headerLine,
+        path: op.path,
+        message: resolved.message,
+      });
+      continue;
+    }
+    if (documentPaths.has(resolved.value.absolutePath)) {
+      problems.push({
+        code: "E_PATCH_SYNTAX",
+        patchLine: op.headerLine,
+        path: op.path,
+        message: `file is named more than once in this patch: ${op.path}`,
+      });
+      continue;
+    }
+    const escapedTarget = await workspaceEscapeMessage(options.cwd, resolved.value.absolutePath);
+    if (escapedTarget !== undefined) {
+      problems.push({
+        code: "E_PATCH_SYNTAX",
+        patchLine: op.headerLine,
+        path: op.path,
+        message: escapedTarget,
+      });
+      continue;
+    }
+    documentPaths.add(resolved.value.absolutePath);
+
+    if (op.kind === "add") {
+      const baseline = await loadBaseline(op.path, resolved.value.absolutePath, op.headerLine);
+      if (baseline === undefined) continue;
+      if (baseline.exists) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: op.headerLine,
+          path: op.path,
+          message: `Add File target already exists: ${op.path}`,
+        });
+        continue;
+      }
+      const entry = entryFor(op.path, resolved.value.absolutePath, baseline, { kind: "add" });
+      entry.mutations.push({
+        kind: "insert",
+        range: { startLine: 1, endLine: 0 },
+        lines: [...op.contentLines],
+        patchLine: op.headerLine,
+      });
+      markWrites(entry);
+      entries.push(entry);
+      byAbsolute.set(resolved.value.absolutePath, entry);
+      continue;
+    }
+
+    if (op.kind === "delete") {
+      const baseline = await loadBaseline(op.path, resolved.value.absolutePath, op.headerLine);
+      if (baseline === undefined) continue;
+      if (!baseline.exists) {
+        problems.push({
+          code: "E_NOT_FOUND",
+          patchLine: op.headerLine,
+          path: op.path,
+          message: `Delete File target not found: ${op.path}`,
+        });
+        continue;
+      }
+      const entry = entryFor(op.path, resolved.value.absolutePath, baseline, { kind: "delete" });
+      entries.push(entry);
+      byAbsolute.set(resolved.value.absolutePath, entry);
+      continue;
+    }
+
+    const baseline = await loadBaseline(op.path, resolved.value.absolutePath, op.headerLine);
+    if (baseline === undefined) continue;
+    if (!baseline.exists) {
+      problems.push({
+        code: "E_NOT_FOUND",
+        patchLine: op.headerLine,
+        path: op.path,
+        message: `Update File target not found: ${op.path}`,
+      });
+      continue;
+    }
+
+    let lifecycle: LifecyclePlan = { kind: "keep" };
+    if (op.moveTo !== undefined) {
+      const destination = resolveRequestPath(op.moveTo.path, options.cwd);
+      const destEscape = destination.ok
+        ? await workspaceEscapeMessage(options.cwd, destination.value.absolutePath)
+        : undefined;
+      if (!destination.ok) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: op.moveTo.line,
+          path: op.moveTo.path,
+          message: destination.message,
+        });
+      } else if (destEscape !== undefined) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: op.moveTo.line,
+          path: op.moveTo.path,
+          message: destEscape,
+        });
+      } else if (destination.value.absolutePath === resolved.value.absolutePath) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: op.moveTo.line,
+          path: op.moveTo.path,
+          message: "Move to names the same file",
+        });
+      } else if (documentPaths.has(destination.value.absolutePath)) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: op.moveTo.line,
+          path: op.moveTo.path,
+          message: `Move to target is another member of this patch: ${op.moveTo.path}`,
+        });
+      } else {
+        const destinationBaseline = await loadBaseline(
+          op.moveTo.path,
+          destination.value.absolutePath,
+          op.moveTo.line,
+        );
+        if (destinationBaseline !== undefined && destinationBaseline.exists) {
+          problems.push({
+            code: "E_PATCH_SYNTAX",
+            patchLine: op.moveTo.line,
+            path: op.moveTo.path,
+            message: `Move to target already exists: ${op.moveTo.path}`,
+          });
+        } else if (destinationBaseline !== undefined) {
+          lifecycle = {
+            kind: "move",
+            to: op.moveTo.path,
+            toAbsolutePath: destination.value.absolutePath,
+          };
+          documentPaths.add(destination.value.absolutePath);
+        }
+      }
+    }
+
+    const entry = entryFor(op.path, resolved.value.absolutePath, baseline, lifecycle);
+    entries.push(entry);
+    byAbsolute.set(resolved.value.absolutePath, entry);
+    // WHY: fragment mode needs no served state; identity and reference hunks do.
+    const needsServed = op.hunks.some((hunk) => hunk.kind !== "fragment");
+    const context = await contextFor(baseline, needsServed);
+    let cursor = 1;
+
+    for (const hunk of op.hunks) {
+      if (hunk.kind === "fragment") {
+        const match = matchFragmentHunk(hunk, context, cursor);
+        if (!match.ok) {
+          const candidateCount = new Set(match.candidates.map((row) => row.line)).size;
+          problems.push({
+            code: "E_UNIQUE_MATCH",
+            patchLine: hunk.headerLine,
+            path: op.path,
+            message:
+              match.reason === "ambiguous"
+                ? `fragment hunk matches more than one place in ${op.path} (${candidateCount} candidate rows); nothing was written`
+                : `fragment hunk does not match ${op.path} byte-exactly; nothing was written`,
+            ...(match.candidates.length > 0 ? { candidates: match.candidates } : {}),
+          });
+          continue;
+        }
+        const oldLines = hunk.lines.filter((line) => line.op !== "add");
+        // WHY: replacement is the body's context and added lines in submission order; only removed
+        // WHY: lines are dropped. Dropping context lines silently deleted them from the result.
+        const replacementLines = hunk.lines
+          .filter((line) => line.op !== "remove")
+          .map((line) => line.text);
+        const oldLineTexts = oldLines.map((line) => line.text);
+        // WHY: a context-only hunk is a no-op: the bytes are unchanged, so only the cursor moves.
+        if (
+          replacementLines.length === oldLineTexts.length &&
+          replacementLines.every((line, index) => line === oldLineTexts[index])
+        ) {
+          cursor = match.match.range.endLine + 1;
+          continue;
+        }
+        entry.mutations.push({
+          kind: oldLines.length === 0 ? "insert" : "replace",
+          range: match.match.range,
+          lines: replacementLines,
+          patchLine: hunk.headerLine,
+        });
+        cursor = match.match.range.endLine + 1;
+        continue;
+      }
+
+      if (hunk.kind === "identity") {
+        const resolvedIdentity = resolveIdentityHunk(hunk, context);
+        if (!resolvedIdentity.ok) {
+          problems.push(...resolvedIdentity.problems);
+          continue;
+        }
+        entry.mutations.push({
+          kind: hunk.addedLines.length === 0 ? "delete" : "replace",
+          range: resolvedIdentity.range,
+          lines: [...hunk.addedLines],
+          patchLine: hunk.headerLine,
+        });
+        cursor = Math.max(cursor, resolvedIdentity.range.endLine + 1);
+        continue;
+      }
+
+      if (hunk.address.kind !== "anchors") {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: hunk.headerLine,
+          path: op.path,
+          message:
+            "Copy From / Cut From requires an identity target (@@<a> or @@<a>-<b>); fragment addressing is not allowed",
+        });
+        continue;
+      }
+      const sourcePath = resolveRequestPath(hunk.source.path, options.cwd);
+      if (!sourcePath.ok) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: hunk.source.line,
+          path: hunk.source.path,
+          message: sourcePath.message,
+        });
+        continue;
+      }
+      const sourceEscape = await workspaceEscapeMessage(options.cwd, sourcePath.value.absolutePath);
+      if (sourceEscape !== undefined) {
+        problems.push({
+          code: "E_PATCH_SYNTAX",
+          patchLine: hunk.source.line,
+          path: hunk.source.path,
+          message: sourceEscape,
+        });
+        continue;
+      }
+      const sourceBaseline = await loadBaseline(
+        hunk.source.path,
+        sourcePath.value.absolutePath,
+        hunk.source.line,
+      );
+      if (sourceBaseline === undefined) continue;
+      if (!sourceBaseline.exists) {
+        problems.push({
+          code: "E_NOT_FOUND",
+          patchLine: hunk.source.line,
+          path: hunk.source.path,
+          message: `reference source file not found: ${hunk.source.path}`,
+        });
+        continue;
+      }
+      const sourceContext = await contextFor(sourceBaseline, true);
+      const reference = resolveReferenceHunk(hunk, context, sourceContext);
+      if (!reference.ok) {
+        problems.push(...reference.problems);
+        continue;
+      }
+      entry.mutations.push(reference.mutation);
+      entry.references.push(reference.reference);
+      cursor = Math.max(cursor, reference.mutation.range.endLine + 1);
+
+      if (hunk.source.mode === "cut") {
+        const sourceEntry = await ensureSourceEntry(
+          hunk.source.path,
+          sourcePath.value.absolutePath,
+          hunk.source.line,
+        );
+        if (sourceEntry !== undefined) {
+          sourceEntry.mutations.push({
+            kind: "delete",
+            range: reference.reference.range,
+            lines: [],
+            patchLine: hunk.source.line,
+          });
+          markWrites(sourceEntry);
+        }
+      } else if (!byAbsolute.has(sourcePath.value.absolutePath)) {
+        referenceBaselines.set(sourcePath.value.absolutePath, sourceBaseline);
+      }
+    }
+
+    const overlaps = checkMutationOverlaps(entry.mutations, entry.path);
+    if (overlaps.length > 0) problems.push(...overlaps);
+    markWrites(entry);
+  }
+
+  if (problems.length > 0) {
+    return { ok: false, problems, served: buildServedBlocks(problems, baselines, pathToAbsolute) };
+  }
+
+  const planFiles = entries
+    .filter((entry) => entry.writes)
+    .map((entry): import("./types.js").PlannedFile => ({
+      path: entry.path,
+      absolutePath: entry.absolutePath,
+      lifecycle: entry.lifecycle,
+      baseline: entry.baseline,
+      mutations: [...entry.mutations],
+      references: [...entry.references],
+      writes: true,
+    }));
+  const plan: PatchPlan = {
+    files: planFiles,
+    referenceFiles: [...referenceBaselines.values()],
+    stats: computeStats(entries),
+  };
+  return { ok: true, plan };
+}
+
+/** Build the current-row blocks a rejection serves back, one per problem file. */
+function buildServedBlocks(
+  problems: readonly PatchProblem[],
+  baselines: Map<string, FileBaseline>,
+  pathToAbsolute: Map<string, string>,
+): readonly import("./types.js").ServedFileBlock[] {
+  const grouped = new Map<string, PatchProblem[]>();
+  for (const problem of problems) {
+    if (problem.path === undefined) continue;
+    const list = grouped.get(problem.path) ?? [];
+    list.push(problem);
+    grouped.set(problem.path, list);
+  }
+  const blocks: import("./types.js").ServedFileBlock[] = [];
+  for (const [path, list] of grouped) {
+    const absolutePath = pathToAbsolute.get(path);
+    const baseline = absolutePath === undefined ? undefined : baselines.get(absolutePath);
+    if (baseline === undefined || !baseline.exists) continue;
+    const lines = baselineLinesOf(baseline);
+    if (lines.length === 0) continue;
+    const candidateRows = list.flatMap((problem) => problem.candidates ?? []);
+    if (candidateRows.length > 0) {
+      // WHY: ambiguity candidates are evidence rows, not a contiguous range. Collapsing them to
+      // WHY: [first..last] let a distant second candidate fall outside the 150-row cap.
+      const byLine = new Map<number, import("../domain-errors.js").ServedRow>();
+      for (const candidate of candidateRows) {
+        if (candidate.line < 1) continue;
+        byLine.set(candidate.line, { position: candidate.line - 1, hash: candidate.hash });
+      }
+      let rows = [...byLine.values()].sort((left, right) => left.position - right.position);
+      if (rows.length > 0) {
+        let text = fmtServedRows(rows, lines);
+        if (rows.length > SERVED_ROWS_CAP) {
+          const next = rows[SERVED_ROWS_CAP]!;
+          text += "\n" + paginationHint(next.position + 1, rows.length - SERVED_ROWS_CAP);
+          rows = rows.slice(0, SERVED_ROWS_CAP);
+        }
+        blocks.push({ path, rows, text });
+      }
+      continue;
+    }
+    const hintLine = list
+      .map((problem) => problem.line)
+      .filter((line): line is number => typeof line === "number")
+      .sort((left, right) => left - right)[0];
+    let startLine = 1;
+    let endLine = lines.length;
+    if (hintLine !== undefined) {
+      // WHY: a stale anchor can sit anywhere in a large file; serve a local window that contains
+      // WHY: the offending line so retrying needs no read, instead of the first 150 rows only.
+      startLine = Math.max(1, hintLine - 2);
+      endLine = Math.max(startLine, lines.length);
+    }
+    const { servedRows, rendered } = buildRangeServeBlock(
+      startLine,
+      endLine,
+      [...baseline.hashes],
+      lines,
+    );
+    if (servedRows.length === 0) continue;
+    blocks.push({ path, rows: servedRows, text: rendered });
+  }
+  return blocks;
+}