pi-hashline-edit-pro 0.11.5 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.11.5",
+  "version": "0.12.0",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-snippet.md

@@ -1 +1 @@
-Replace lines in a text file via HASH anchors from read, batching all edits to a file in one call
+Replace lines in a text file via HASH anchors from read, batching all changes to a file in one call

package/prompts/replace.md

@@ -1,6 +1,6 @@
 Replace lines in a text file using HASH anchors from `read`.
 
-Put all operations on one file in a single `replace` call. Stack every region into the `edits` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot.
+Put all operations on one file in a single `replace` call. Stack every region into the `changes` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot.
 
 How to use:
 
@@ -11,8 +11,8 @@ read({ path: "src/main.ts" })
 
 2. Copy the 3-character HASH (before `│`) into `hash_range_incl`:
 ```json
-{ "path": "src/main.ts", "edits": [
-  { "hash_range_incl": ["MQX", "MQX"], "new_lines": ["const x = 99;"] }
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_incl": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
 ] }
 ```
 
@@ -20,15 +20,15 @@ Examples:
 
 1. Single line replace:
 ```json
-{ "path": "src/main.ts", "edits": [
-  { "hash_range_incl": ["MQX", "MQX"], "new_lines": ["const x = 1;"] }
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_incl": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
 ] }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
-{ "path": "src/main.ts", "edits": [
-  { "hash_range_incl": ["ZPM", "VRW"], "new_lines": [
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_incl": ["ZPM", "VRW"], "content_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
@@ -38,75 +38,74 @@ Examples:
 
 3. Multiple regions in one call (delete two non-adjacent ranges):
 ```json
-{ "path": "src/server.ts", "edits": [
-  { "hash_range_incl": ["aB3", "xY7"], "new_lines": [] },
-  { "hash_range_incl": ["MQX", "ZPM"], "new_lines": [] }
+{ "path": "src/server.ts", "changes": [
+  { "hash_range_incl": ["aB3", "xY7"], "content_lines": [] },
+  { "hash_range_incl": ["MQX", "ZPM"], "content_lines": [] }
 ] }
 ```
 
 4. Append after the last line (include the old last line so the new line is added after it):
 
 ```json
-{ "path": "src/main.ts", "edits": [
-  { "hash_range_incl": ["ZPM", "ZPM"], "new_lines": ["old last line", "new line"] }
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_incl": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
 ] }
 ```
 
 5. Seed content into an empty file (replace the single empty-line hash returned by read):
 
 ```json
-{ "path": "src/main.ts", "edits": [
-  { "hash_range_incl": ["aB3", "aB3"], "new_lines": ["first line", "second line"] }
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_incl": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
 ] }
 ```
 
-⚠️ Common mistake: do not copy the `HASH│` prefix into `new_lines`.
+⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
 
 Wrong:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "new_lines": ["F4T│import { x } from \"./x\";"] }
+{ "hash_range_incl": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
 ```
 
 Right:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "new_lines": ["import { x } from \"./x\";"] }
+{ "hash_range_incl": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
 ```
 
-`hash_range_incl` uses the hash anchor. `new_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
+`hash_range_incl` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
 ⚠️ Common mistake: `hash_range_incl` is only the 3-character HASH, not the full `HASH│content` line.
 
 Wrong:
 ```json
-{ "hash_range_incl": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "new_lines": [...] }
+{ "hash_range_incl": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
 ```
 
 Right:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "new_lines": [...] }
+{ "hash_range_incl": ["F4T", "F4T"], "content_lines": [...] }
 ```
 
 Rules:
-- `hash_range_incl` is a pair `[start, end]`. A single-line replace is `hash_range_incl: ["X", "X"]`.
-- To delete a range, use `new_lines: []`.
+- `hash_range_incl` is a pair `[start, end]`. A single-line replace is `hash_range_incl: ["X", "X"].
+- To delete a range, use `content_lines: []`.
 - `hash_range_incl` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
-- `new_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix, no `+`/`-` diff markers.
+- `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix, no `+`/`-` diff markers.
 - Don't add `""` for spacing unless you actually want a new blank line.
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
-- All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
-- If `new_lines` matches current content, the replace is classified as `noop` (file unchanged).
+- All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
+- If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
 - The `hash_range_incl` is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-
 On success, the response text is empty (or contains only warnings if present). Call `read` to get fresh anchors for follow-up edits.
 
 Error recovery:
 - `[E_STALE_ANCHOR]` — file changed since last read. Call `read` to get fresh anchors, then copy the HASH and retry.
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
-- `[E_BAD_SHAPE]` — malformed request or edit item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_incl, new_lines}` instead.
-- `[E_EDIT_CONFLICT]` — two edits overlap on the same line range. Make edits non-overlapping.
+- `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_incl, content_lines}` instead.
+- `[E_EDIT_CONFLICT]` — two changes overlap on the same line range. Make changes non-overlapping.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
-- `[E_BARE_HASH_PREFIX]` — a `new_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_incl` uses hashes, `new_lines` does not.
-- `[E_INVALID_PATCH]` — diff prefixes (`+`/`-`) in `new_lines`. Use literal content only.
+- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_incl` uses hashes, `content_lines` does not.
+- `[E_INVALID_PATCH]` — diff prefixes (`+`/`-`) in `content_lines`. Use literal content only.
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.

package/src/hashline/apply.ts

@@ -68,72 +68,72 @@ function throwConflict(
 }
 
 function resToSpan(
-	edit: RHEdit,
-	index: number,
-	content: string,
-	lineIndex: LIdx,
-	noopEdits: NEdit[],
+  edit: RHEdit,
+  index: number,
+  content: string,
+  lineIndex: LIdx,
+  noopEdits: NEdit[],
 ): RESpan | null {
-	const { fileLines, lineStarts, hasTerminalNewline } = lineIndex;
-
-	const startLine = edit.hash_range_incl[0].line;
-	const endLine = edit.hash_range_incl[1].line;
-	const originalLines = fileLines.slice(startLine - 1, endLine);
-	if (
-		originalLines.length === edit.new_lines.length &&
-		originalLines.every(
-			(line, lineIndex) => line === edit.new_lines[lineIndex],
-		)
-	) {
-		noopEdits.push({
-			editIndex: index,
-			loc: edit.hash_range_incl[0].hash,
-			currentContent: originalLines.join("\n"),
-		});
-		return null;
-	}
-
-	if (edit.new_lines.length > 0) {
-		return {
-			kind: "replace",
-			index,
-			label: descEdit(edit),
-			start: lineStarts[startLine - 1]!,
-			end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
-			replacement: edit.new_lines.join("\n"),
-		};
-	}
-
-	if (startLine === 1 && endLine === fileLines.length) {
-		return {
-			kind: "replace",
-			index,
-			label: descEdit(edit),
-			start: 0,
-			end: content.length,
-			replacement: "",
-		};
-	}
-
-	if (endLine < fileLines.length) {
-		return {
-			kind: "replace",
-			index,
-			label: descEdit(edit),
-			start: lineStarts[startLine - 1]!,
-			end: lineStarts[endLine]!,
-			replacement: "",
-		};
-	}
-
-	return {
-		kind: "replace",
-		index,
-		label: descEdit(edit),
-		start: Math.max(0, lineStarts[startLine - 1]! - 1),
-		end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
-		replacement: "",
-	};
+  const { fileLines, lineStarts, hasTerminalNewline } = lineIndex;
+
+  const startLine = edit.hash_range_incl[0].line;
+  const endLine = edit.hash_range_incl[1].line;
+  const originalLines = fileLines.slice(startLine - 1, endLine);
+  if (
+    originalLines.length === edit.content_lines.length &&
+    originalLines.every(
+      (line, lineIndex) => line === edit.content_lines[lineIndex],
+    )
+  ) {
+    noopEdits.push({
+      editIndex: index,
+      loc: edit.hash_range_incl[0].hash,
+      currentContent: originalLines.join("\n"),
+    });
+    return null;
+  }
+
+  if (edit.content_lines.length > 0) {
+    return {
+      kind: "replace",
+      index,
+      label: descEdit(edit),
+      start: lineStarts[startLine - 1]!,
+      end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
+      replacement: edit.content_lines.join("\n"),
+    };
+  }
+
+  if (startLine === 1 && endLine === fileLines.length) {
+    return {
+      kind: "replace",
+      index,
+      label: descEdit(edit),
+      start: 0,
+      end: content.length,
+      replacement: "",
+    };
+  }
+
+  if (endLine < fileLines.length) {
+    return {
+      kind: "replace",
+      index,
+      label: descEdit(edit),
+      start: lineStarts[startLine - 1]!,
+      end: lineStarts[endLine]!,
+      replacement: "",
+    };
+  }
+
+  return {
+    kind: "replace",
+    index,
+    label: descEdit(edit),
+    start: Math.max(0, lineStarts[startLine - 1]! - 1),
+    end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
+    replacement: "",
+  };
 }
 
 function assertNoConflict(spans: RESpan[]): void {
@@ -232,12 +232,12 @@ export function applyEdits(
 			lastChangedLine: undefined,
 		};
 
-	edits = edits.map((edit) =>
-		edit.new_lines.length === 1 &&
-		edit.new_lines[0] === ""
-			? { ...edit, new_lines: [] }
-			: edit,
-	);
+  edits = edits.map((edit) =>
+    edit.content_lines.length === 1 &&
+    edit.content_lines[0] === ""
+      ? { ...edit, content_lines: [] }
+      : edit,
+  );
 
 	const lineIndex = buildIdx(content);
 	const fileHashes = precomputedHashes ?? lineHashes(content);

package/src/hashline/resolve.ts

@@ -9,10 +9,10 @@ export type RAnchor = {
 	hashMatched: boolean;
 };
 
-export type HEdit = { hash_range_incl: [Anchor, Anchor]; new_lines: string[] };
+export type HEdit = { hash_range_incl: [Anchor, Anchor]; content_lines: string[] };
 export type RHEdit = {
-	hash_range_incl: [RAnchor, RAnchor];
-	new_lines: string[];
+  hash_range_incl: [RAnchor, RAnchor];
+  content_lines: string[];
 };
 
 interface HMismatch {
@@ -37,8 +37,8 @@ export interface NEdit {
 }
 
 export type HTEdit = {
-	hash_range_incl: [string, string];
-	new_lines: string[];
+  hash_range_incl: [string, string];
+  content_lines: string[];
 };
 
 function resAnchor(
@@ -119,7 +119,7 @@ export function fmtMismatch(
 	return out.join("\n");
 }
 
-const ITEM_KS = new Set(["hash_range_incl", "new_lines"]);
+const ITEM_KS = new Set(["hash_range_incl", "content_lines"]);
 
 function isStrArr(value: unknown): value is string[] {
 	return (
@@ -136,87 +136,86 @@ function isStrPair(value: unknown): value is [string, string] {
 }
 
 function assertItem(edit: Record<string, unknown>, index: number): void {
-	rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { hash_range_incl, new_lines }.");
-
-	if ("hash_range_incl" in edit && !isStrPair(edit.hash_range_incl)) {
-		throw new Error(
-			`[E_BAD_SHAPE] Edit ${index} field "hash_range_incl" must be a pair of anchor strings [start, end].`,
-		);
-	}
-	if (!("new_lines" in edit)) {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "new_lines" field. Provide the replacement lines (use [] to delete).`);
-	}
-	if ("new_lines" in edit && !isStrArr(edit.new_lines)) {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} field "new_lines" must be a string array.`);
-	}
-	if (!isStrPair(edit.hash_range_incl)) {
-		throw new Error(
-			`[E_BAD_SHAPE] Edit ${index} requires an "hash_range_incl" pair of anchor strings [start, end].`,
-		);
-	}
-
+  rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { hash_range_incl, content_lines }.");
+
+  if ("hash_range_incl" in edit && !isStrPair(edit.hash_range_incl)) {
+    throw new Error(
+      `[E_BAD_SHAPE] Edit ${index} field "hash_range_incl" must be a pair of anchor strings [start, end].`,
+    );
+  }
+  if (!("content_lines" in edit)) {
+    throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "content_lines" field. Provide the replacement lines (use [] to delete).`);
+  }
+  if ("content_lines" in edit && !isStrArr(edit.content_lines)) {
+    throw new Error(`[E_BAD_SHAPE] Edit ${index} field "content_lines" must be a string array.`);
+  }
+  if (!isStrPair(edit.hash_range_incl)) {
+    throw new Error(
+      `[E_BAD_SHAPE] Edit ${index} requires an "hash_range_incl" pair of anchor strings [start, end].`,
+    );
+  }
 }
 
 export function resEdits(edits: HTEdit[]): HEdit[] {
-	const result: HEdit[] = [];
-	for (const [index, edit] of edits.entries()) {
-		assertItem(edit as Record<string, unknown>, index);
-
-		const replaceLines = parseText(edit.new_lines);
-		result.push({
-			hash_range_incl: [parseHashRef(edit.hash_range_incl[0]), parseHashRef(edit.hash_range_incl[1])],
-			new_lines: replaceLines,
-		});
-	}
-	return result;
+  const result: HEdit[] = [];
+  for (const [index, edit] of edits.entries()) {
+    assertItem(edit as Record<string, unknown>, index);
+
+    const replaceLines = parseText(edit.content_lines);
+    result.push({
+      hash_range_incl: [parseHashRef(edit.hash_range_incl[0]), parseHashRef(edit.hash_range_incl[1])],
+      content_lines: replaceLines,
+    });
+  }
+  return result;
 }
 
 function warnUnicodeEsc(
-	edits: HEdit[],
-	warnings: string[],
+  edits: HEdit[],
+  warnings: string[],
 ): void {
-	for (const edit of edits) {
-		if (edit.new_lines.some((line) => /\\uDDDD/i.test(line))) {
-			warnings.push(
-				"Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
-			);
-		}
-	}
+  for (const edit of edits) {
+    if (edit.content_lines.some((line) => /\\uDDDD/i.test(line))) {
+      warnings.push(
+        "Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
+      );
+    }
+  }
 }
 
 export function assertNoBarePrefix(
-	edits: HEdit[],
-	fileLines: string[],
-	fileHashes: string[],
+  edits: HEdit[],
+  fileLines: string[],
+  fileHashes: string[],
 ): void {
-	const suspects: { line: string; hash: string; editIndex: number; lineIndex: number }[] = [];
-	for (let editIndex = 0; editIndex < edits.length; editIndex++) {
-		const edit = edits[editIndex]!;
-		for (let lineIndex = 0; lineIndex < edit.new_lines.length; lineIndex++) {
-			const line = edit.new_lines[lineIndex]!;
-			const match = line.match(HL_BARE_PREFIX_RE);
-			if (match) suspects.push({ line, hash: match[1]!, editIndex, lineIndex });
-		}
-	}
-	if (suspects.length === 0) return;
-	const locations = suspects
-		.map((s) => `edit ${s.editIndex}, new_lines[${s.lineIndex}]`)
-		.join("; ");
-
-	const fileHashSet = new Set(fileHashes);
-	const matched = suspects.filter((s) => fileHashSet.has(s.hash));
-	const matchedCount = matched.length;
-
-	const exampleLine = `${suspects[0]!.hash}│${suspects[0]!.line}`;
-
-	const linesHint =
-		matchedCount === 0
-			? `None match file line hashes.`
-			: `${matchedCount} match file line hashes — strong evidence the prefix was copied from read output.`;
-
-	throw new Error(
-		`[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected new_lines entry; keep only the literal line content that appears after "│" in read output. Remember: hash_range_incl uses hash anchors, new_lines uses file content only.`
-	);
+  const suspects: { line: string; hash: string; editIndex: number; lineIndex: number }[] = [];
+  for (let editIndex = 0; editIndex < edits.length; editIndex++) {
+    const edit = edits[editIndex]!;
+    for (let lineIndex = 0; lineIndex < edit.content_lines.length; lineIndex++) {
+      const line = edit.content_lines[lineIndex]!;
+      const match = line.match(HL_BARE_PREFIX_RE);
+      if (match) suspects.push({ line, hash: match[1]!, editIndex, lineIndex });
+    }
+  }
+  if (suspects.length === 0) return;
+  const locations = suspects
+    .map((s) => `edit ${s.editIndex}, content_lines[${s.lineIndex}]`)
+    .join("; ");
+
+  const fileHashSet = new Set(fileHashes);
+  const matched = suspects.filter((s) => fileHashSet.has(s.hash));
+  const matchedCount = matched.length;
+
+  const exampleLine = `${suspects[0]!.hash}│${suspects[0]!.line}`;
+
+  const linesHint =
+    matchedCount === 0
+      ? `None match file line hashes.`
+      : `${matchedCount} match file line hashes — strong evidence the prefix was copied from read output.`;
+
+  throw new Error(
+    `[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected content_lines entry; keep only the literal line content that appears after "│" in read output. Remember: hash_range_incl uses hash anchors, content_lines uses file content only.`
+  );
 }
 
 export function descEdit(edit: RHEdit): string {
@@ -224,80 +223,80 @@ export function descEdit(edit: RHEdit): string {
 }
 
 export function valEdits(
-	edits: HEdit[],
-	fileLines: string[],
-	fileHashes: string[],
-	warnings: string[],
-	signal: AbortSignal | undefined,
+  edits: HEdit[],
+  fileLines: string[],
+  fileHashes: string[],
+  warnings: string[],
+  signal: AbortSignal | undefined,
 ): { resolved: RHEdit[]; mismatches: HMismatch[]; boundaryWarnings: BDupWarn[] } {
-	assertAligned(fileLines, fileHashes, "valEdits");
-	const resolved: RHEdit[] = [];
-	const mismatches: HMismatch[] = [];
-	const boundaryWarnings: BDupWarn[] = [];
-
-	const tryResolve = (ref: Anchor): RAnchor | undefined => {
-		const result = resAnchor(ref, fileLines, fileHashes);
-		if ("kind" in result) {
-			mismatches.push(result);
-			return undefined;
-		}
-		return result;
-	};
-
-	for (const edit of edits) {
-		abortIf(signal);
-		const startResolved = tryResolve(edit.hash_range_incl[0]);
-		const endResolved = tryResolve(edit.hash_range_incl[1]);
-		if (!startResolved || !endResolved) {
-			continue;
-		}
-		if (startResolved.line > endResolved.line) {
-			throw new Error(
-				`[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_range_incl[0].hash} and ${edit.hash_range_incl[1].hash}).`,
-			);
-		}
-		const endLine = endResolved.line;
-		const nextLine = fileLines[endLine];
-		const replacementLastLine = edit.new_lines.at(-1);
-		if (
-			nextLine !== undefined &&
-			replacementLastLine !== undefined &&
-			replacementLastLine.length > 0 &&
-			replacementLastLine === nextLine
-		) {
-			boundaryWarnings.push({
-				kind: "trailing",
-				survivingLineContent: nextLine,
-				survivingLineIndex: endLine,
-				occurrence: fileLines.slice(0, endLine).filter(l => l === nextLine).length,
-				replacementLineContent: replacementLastLine,
-				editIndex: resolved.length,
-			});
-		}
-		const prevLine = fileLines[startResolved.line - 2];
-		const replacementFirstLine = edit.new_lines[0];
-		if (
-			prevLine !== undefined &&
-			replacementFirstLine !== undefined &&
-			replacementFirstLine.length > 0 &&
-			replacementFirstLine === prevLine
-		) {
-			boundaryWarnings.push({
-				kind: "leading",
-				survivingLineContent: prevLine,
-				survivingLineIndex: startResolved.line - 2,
-				occurrence: fileLines.slice(0, startResolved.line - 2).filter(l => l === prevLine).length,
-				replacementLineContent: replacementFirstLine,
-				editIndex: resolved.length,
-			});
-		}
-		resolved.push({
-			hash_range_incl: [startResolved, endResolved],
-			new_lines: edit.new_lines,
-		});
-	}
-
-	return { resolved, mismatches, boundaryWarnings };
+  assertAligned(fileLines, fileHashes, "valEdits");
+  const resolved: RHEdit[] = [];
+  const mismatches: HMismatch[] = [];
+  const boundaryWarnings: BDupWarn[] = [];
+
+  const tryResolve = (ref: Anchor): RAnchor | undefined => {
+    const result = resAnchor(ref, fileLines, fileHashes);
+    if ("kind" in result) {
+      mismatches.push(result);
+      return undefined;
+    }
+    return result;
+  };
+
+  for (const edit of edits) {
+    abortIf(signal);
+    const startResolved = tryResolve(edit.hash_range_incl[0]);
+    const endResolved = tryResolve(edit.hash_range_incl[1]);
+    if (!startResolved || !endResolved) {
+      continue;
+    }
+    if (startResolved.line > endResolved.line) {
+      throw new Error(
+        `[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_range_incl[0].hash} and ${edit.hash_range_incl[1].hash}).`,
+      );
+    }
+    const endLine = endResolved.line;
+    const nextLine = fileLines[endLine];
+    const replacementLastLine = edit.content_lines.at(-1);
+    if (
+      nextLine !== undefined &&
+      replacementLastLine !== undefined &&
+      replacementLastLine.length > 0 &&
+      replacementLastLine === nextLine
+    ) {
+      boundaryWarnings.push({
+        kind: "trailing",
+        survivingLineContent: nextLine,
+        survivingLineIndex: endLine,
+        occurrence: fileLines.slice(0, endLine).filter(l => l === nextLine).length,
+        replacementLineContent: replacementLastLine,
+        editIndex: resolved.length,
+      });
+    }
+    const prevLine = fileLines[startResolved.line - 2];
+    const replacementFirstLine = edit.content_lines[0];
+    if (
+      prevLine !== undefined &&
+      replacementFirstLine !== undefined &&
+      replacementFirstLine.length > 0 &&
+      replacementFirstLine === prevLine
+    ) {
+      boundaryWarnings.push({
+        kind: "leading",
+        survivingLineContent: prevLine,
+        survivingLineIndex: startResolved.line - 2,
+        occurrence: fileLines.slice(0, startResolved.line - 2).filter(l => l === prevLine).length,
+        replacementLineContent: replacementFirstLine,
+        editIndex: resolved.length,
+      });
+    }
+    resolved.push({
+      hash_range_incl: [startResolved, endResolved],
+      content_lines: edit.content_lines,
+    });
+  }
+
+  return { resolved, mismatches, boundaryWarnings };
 }
 
 export { warnUnicodeEsc };

package/src/replace-normalize.ts

@@ -1,52 +1,58 @@
 import { isRec, has } from "./utils";
 
-function coerceEditsArray(edits: unknown): unknown {
-	if (typeof edits !== "string") {
-		return edits;
-	}
-	try {
-		const parsed: unknown = JSON.parse(edits);
-		return Array.isArray(parsed) ? parsed : edits;
-	} catch {
-		return edits;
-	}
+function coerceChangesArray(changes: unknown): unknown {
+  if (typeof changes !== "string") {
+    return changes;
+  }
+  try {
+    const parsed: unknown = JSON.parse(changes);
+    return Array.isArray(parsed) ? parsed : changes;
+  } catch {
+    return changes;
+  }
 }
 
-function coerceNewLines(edits: unknown): unknown {
-  if (!Array.isArray(edits)) return edits;
-  return edits.map((edit: unknown) => {
-    if (!isRec(edit)) return edit;
-    if (typeof edit.new_lines !== "string") return edit;
+function coerceContentLines(changes: unknown): unknown {
+  if (!Array.isArray(changes)) return changes;
+  return changes.map((change: unknown) => {
+    if (!isRec(change)) return change;
+    if (typeof change.content_lines !== "string") return change;
     try {
-      const parsed: unknown = JSON.parse(edit.new_lines);
+      const parsed: unknown = JSON.parse(change.content_lines);
       if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
-        return { ...edit, new_lines: parsed };
+        return { ...change, content_lines: parsed };
       }
     } catch {
       // not valid JSON, leave as-is for downstream validation
     }
-    return edit;
+    return change;
   });
 }
 
 export function normReq(input: unknown): unknown {
-	if (!isRec(input)) {
-		return input;
-	}
-
-	const record: Record<string, unknown> = { ...input };
-
-	if (typeof record.path !== "string" && typeof record.file_path === "string") {
-		record.path = record.file_path;
-		delete record.file_path;
-	}
-
-	const hasEditsField = has(record, "edits");
-
-	if (hasEditsField) {
-		record.edits = coerceEditsArray(record.edits);
-		record.edits = coerceNewLines(record.edits);
-	}
-
-	return record;
+  if (!isRec(input)) {
+    return input;
+  }
+
+  const record: Record<string, unknown> = { ...input };
+
+  if (typeof record.path !== "string" && typeof record.file_path === "string") {
+    record.path = record.file_path;
+    delete record.file_path;
+  }
+
+  const hasChangesField = has(record, "changes");
+  const hasEditsField = has(record, "edits");
+
+  if (hasChangesField) {
+    record.changes = coerceChangesArray(record.changes);
+    record.changes = coerceContentLines(record.changes);
+  } else if (hasEditsField) {
+    // Accept "edits" as an alias for "changes" for backward compatibility
+    record.changes = coerceChangesArray(record.edits);
+    record.changes = coerceContentLines(record.changes);
+    delete record.edits;
+  }
+
+  return record;
 }

package/src/replace-render.ts

@@ -32,13 +32,13 @@ export function getPreviewInput(
 		return null;
 	}
 
-	if (!Array.isArray(normalized.edits)) {
+	if (!Array.isArray(normalized.changes)) {
 		return null;
 	}
 
 	const request: ReqParams = {
 		path: normalized.path,
-		edits: normalized.edits as HTEdit[],
+		changes: normalized.changes as HTEdit[],
 	};
 
 	return request;

package/src/replace.ts

@@ -42,9 +42,9 @@ import {
 } from "./replace-render";
 import { loadP, loadGuide } from "./prompts";
 
-const newLinesSchema = Type.Array(Type.String(), {
-	description:
-		"literal replacement file content, one string per line. Must not include the HASH│ prefix from read output.",
+const contentLinesSchema = Type.Array(Type.String(), {
+  description:
+    "literal replacement file content, one string per line. Must not include the HASH│ prefix from read output.",
 });
 
 const hashRangeInclSchema = Type.Array(
@@ -56,24 +56,24 @@ const hashRangeInclSchema = Type.Array(
 	},
 );
 
-const editItemSchema = Type.Object(
-	{
-		hash_range_incl: hashRangeInclSchema,
-		new_lines: newLinesSchema,
-	},
-	{ additionalProperties: false },
+const changeItemSchema = Type.Object(
+  {
+    hash_range_incl: hashRangeInclSchema,
+    content_lines: contentLinesSchema,
+  },
+  { additionalProperties: false },
 );
 export const editToolSchema = Type.Object(
-	{
-		path: Type.String({ description: "path" }),
-		edits: Type.Array(editItemSchema, { description: "edits over $path" }),
-	},
-	{ additionalProperties: false },
+  {
+    path: Type.String({ description: "path" }),
+    changes: Type.Array(changeItemSchema, { description: "changes over $path" }),
+  },
+  { additionalProperties: false },
 );
 
 export type ReqParams = {
-	path: string;
-	edits: HTEdit[];
+  path: string;
+  changes: HTEdit[];
 };
 
 export type ReplaceDetails = {
@@ -88,90 +88,90 @@ export type ReplaceDetails = {
 const E_DESC = loadP("../prompts/replace.md");
 const E_SNIPPET = loadP("../prompts/replace-snippet.md");
 const E_GUIDE = loadGuide("../prompts/replace-guidelines.md");
-const ROOT_KS = new Set(["path", "edits"]);
+const ROOT_KS = new Set(["path", "changes"]);
 
 export function assertReq(
-	request: unknown,
+  request: unknown,
 ): asserts request is ReqParams {
-	if (!isRec(request)) {
-		throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
-	}
-
-	for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"]) {
-		if (has(request, legacyKey)) {
-			throw new Error(
-				`[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_incl: ["<START>", "<END>"], new_lines: [...]}.`
-			);
-		}
-	}
-
-	rejectUnknownFields(request, ROOT_KS, "Edit request");
-
-	if (typeof request.path !== "string" || request.path.length === 0) {
-		throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string.');
-	}
-
-	if (!Array.isArray(request.edits)) {
-		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array. Each edit is { hash_range_incl: ["<START>", "<END>"], new_lines: [...] }.');
-	}
+  if (!isRec(request)) {
+    throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
+  }
+
+  for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"]) {
+    if (has(request, legacyKey)) {
+      throw new Error(
+        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_incl: ["<START>", "<END>"], content_lines: [...]}.`
+      );
+    }
+  }
+
+  rejectUnknownFields(request, ROOT_KS, "Edit request");
+
+  if (typeof request.path !== "string" || request.path.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string.');
+  }
+
+  if (!Array.isArray(request.changes)) {
+    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { hash_range_incl: ["<START>", "<END>"], content_lines: [...] }.');
+  }
 }
 
 async function execPipeline(
-	params: ReqParams,
-	cwd: string,
-	accessMode: number,
-	signal?: AbortSignal,
+  params: ReqParams,
+  cwd: string,
+  accessMode: number,
+  signal?: AbortSignal,
 ): Promise<{
-	path: string;
-	toolEdits: HTEdit[];
-	originalNormalized: string;
-	result: string;
-	bom: string;
-	originalEnding: "\r\n" | "\n";
-	hadUtf8DecodeErrors: boolean;
-	warnings: string[];
-	noopEdits?: { editIndex: number; loc: string; currentContent: string }[];
-	firstChangedLine?: number;
-	lastChangedLine?: number;
-	originalHashes?: string[];
+  path: string;
+  toolEdits: HTEdit[];
+  originalNormalized: string;
+  result: string;
+  bom: string;
+  originalEnding: "\r\n" | "\n";
+  hadUtf8DecodeErrors: boolean;
+  warnings: string[];
+  noopEdits?: { editIndex: number; loc: string; currentContent: string }[];
+  firstChangedLine?: number;
+  lastChangedLine?: number;
+  originalHashes?: string[];
 }> {
 
-	const path = params.path;
-	const toolEdits = Array.isArray(params.edits)
-		? (params.edits as HTEdit[])
-		: [];
-
-	if (toolEdits.length === 0) {
-		throw new Error("[E_BAD_SHAPE] Edit request requires a non-empty \"edits\" array.");
-	}
-
-	const { normalized: originalNormalized, bom, originalEnding, fileHashes: originalHashes, hadUtf8DecodeErrors } = await readNormFile(
-		path, cwd, signal, accessMode,
-	);
-
-	const resolved = resEdits(toolEdits);
-	const anchorResult = applyEdits(
-		originalNormalized,
-		resolved,
-		signal,
-		originalHashes,
-		path,
-	);
-
-	return {
-		path,
-		toolEdits,
-		originalNormalized,
-		result: anchorResult.content,
-		bom,
-		originalEnding,
-		hadUtf8DecodeErrors,
-		warnings: [...(anchorResult.warnings ?? [])],
-		noopEdits: anchorResult.noopEdits,
-		firstChangedLine: anchorResult.firstChangedLine,
-		lastChangedLine: anchorResult.lastChangedLine,
-		originalHashes,
-	};
+  const path = params.path;
+  const toolEdits = Array.isArray(params.changes)
+    ? (params.changes as HTEdit[])
+    : [];
+
+  if (toolEdits.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "changes" array.');
+  }
+
+  const { normalized: originalNormalized, bom, originalEnding, fileHashes: originalHashes, hadUtf8DecodeErrors } = await readNormFile(
+    path, cwd, signal, accessMode,
+  );
+
+  const resolved = resEdits(toolEdits);
+  const anchorResult = applyEdits(
+    originalNormalized,
+    resolved,
+    signal,
+    originalHashes,
+    path,
+  );
+
+  return {
+    path,
+    toolEdits,
+    originalNormalized,
+    result: anchorResult.content,
+    bom,
+    originalEnding,
+    hadUtf8DecodeErrors,
+    warnings: [...(anchorResult.warnings ?? [])],
+    noopEdits: anchorResult.noopEdits,
+    firstChangedLine: anchorResult.firstChangedLine,
+    lastChangedLine: anchorResult.lastChangedLine,
+    originalHashes,
+  };
 }
 
 export async function compPreview(
@@ -358,9 +358,9 @@ const toolDef: ToolDef = {
 				signal,
 			);
 
-			const editsAttempted = Array.isArray(normalizedParams.edits)
-				? normalizedParams.edits.length
-				: 0;
+      const editsAttempted = Array.isArray(normalizedParams.changes)
+        ? normalizedParams.changes.length
+        : 0;
 
 			if (originalNormalized === result) {
 				const noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;