@oh-my-pi/hashline 15.5.11 → 15.5.13

package/src/apply.ts

@@ -1,6 +1,11 @@
 /**
  * Apply a parsed list of {@link Edit}s to a text body and return the
- * post-edit lines. Pure function: no FS, no mutation of the input.
+ * post-edit lines plus any diagnostic warnings. Pure function: no FS, no
+ * mutation of the input.
+ *
+ * Replacement groups are first normalized by {@link repairBoundaryBalance},
+ * which fixes the common model mistake of a payload that duplicates or drops
+ * the closing delimiter bordering the range (balance-validated; see below).
  */
 import { cloneCursor } from "./tokenizer";
 import type { Anchor, ApplyResult, Cursor, Edit } from "./types";
@@ -20,20 +25,12 @@ function isReplacementInsert(edit: Edit): edit is InsertEdit & { mode: "replacem
 	return edit.kind === "insert" && edit.mode === "replacement";
 }
 
-function rangeAnchors(start: Anchor, end: Anchor): Anchor[] {
-	const anchors: Anchor[] = [];
-	for (let line = start.line; line <= end.line; line++) anchors.push({ line });
-	return anchors;
-}
-
 function getCursorAnchors(cursor: Cursor): Anchor[] {
-	return cursor.kind === "before_anchor" ? [cursor.anchor] : [];
+	return cursor.kind === "before_anchor" || cursor.kind === "after_anchor" ? [cursor.anchor] : [];
 }
 
 function getEditAnchors(edit: Edit): Anchor[] {
 	if (edit.kind === "delete") return [edit.anchor];
-	if (edit.kind === "repeat")
-		return [...getCursorAnchors(edit.cursor), ...rangeAnchors(edit.range.start, edit.range.end)];
 	return getCursorAnchors(edit.cursor);
 }
 
@@ -51,44 +48,11 @@ function validateLineBounds(edits: AppliedEdit[], fileLines: string[]): void {
 	}
 }
 
-function assertLineExists(line: number, fileLines: string[]): void {
-	if (line < 1 || line > fileLines.length) {
-		throw new Error(`Line ${line} does not exist (file has ${fileLines.length} lines)`);
-	}
-}
-
 function cloneAppliedEdit(edit: AppliedEdit, index: number): AppliedEdit {
 	if (edit.kind === "delete") return { ...edit, anchor: { ...edit.anchor }, index };
 	return { ...edit, cursor: cloneCursor(edit.cursor), index };
 }
 
-function expandRepeatEdits(edits: Edit[], fileLines: string[]): AppliedEdit[] {
-	const expanded: AppliedEdit[] = [];
-	for (const edit of edits) {
-		if (edit.kind !== "repeat") {
-			expanded.push(cloneAppliedEdit(edit, expanded.length));
-			continue;
-		}
-		if (edit.range.end.line < edit.range.start.line) {
-			throw new Error(
-				`line ${edit.lineNum}: range ${edit.range.start.line}-${edit.range.end.line} ends before it starts.`,
-			);
-		}
-		for (let line = edit.range.start.line; line <= edit.range.end.line; line++) {
-			assertLineExists(line, fileLines);
-			expanded.push({
-				kind: "insert",
-				cursor: cloneCursor(edit.cursor),
-				text: fileLines[line - 1] ?? "",
-				lineNum: edit.lineNum,
-				index: expanded.length,
-				...(edit.mode === undefined ? {} : { mode: edit.mode }),
-			});
-		}
-	}
-	return expanded;
-}
-
 function insertAtStart(fileLines: string[], lineOrigins: LineOrigin[], lines: string[]): void {
 	if (lines.length === 0) return;
 	const origins = lines.map((): LineOrigin => "insert");
@@ -122,7 +86,7 @@ function bucketAnchorEditsByLine(edits: IndexedEdit[]): Map<number, IndexedEdit[
 		const line =
 			entry.edit.kind === "delete"
 				? entry.edit.anchor.line
-				: entry.edit.cursor.kind === "before_anchor"
+				: entry.edit.cursor.kind === "before_anchor" || entry.edit.cursor.kind === "after_anchor"
 					? entry.edit.cursor.anchor.line
 					: 0;
 		const bucket = byLine.get(line);
@@ -132,6 +96,311 @@ function bucketAnchorEditsByLine(edits: IndexedEdit[]): Map<number, IndexedEdit[
 	return byLine;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Boundary-balance repair
+//
+// Models routinely miscount a replacement range's edges. The payload either
+// re-states a closing delimiter that still lives just outside the range
+// (producing a DUPLICATE `}` / `);` / `]`) or the range deletes a closer the
+// payload never restates (DROPPING it). Both are the same defect — a
+// replacement whose payload does not preserve the deleted region's delimiter
+// balance — and both leave the file syntactically broken.
+//
+// A repair fires only when (a) the group's payload balance differs from the
+// deleted region's balance and (b) one boundary operation drives that
+// difference to exactly zero while leaving the surrounding text byte-identical.
+// The operation only ever drops an exact multi-line boundary echo or a single
+// pure structural-closer line, or spares a deleted pure structural-closer line,
+// so content lines are never moved or lost. Balance-preserving edits are left
+// strictly alone.
+
+/** A line that is nothing but closing delimiters: `}`, `)`, `];`, `})`, `},`. */
+const STRUCTURAL_CLOSER_RE = /^\s*[)\]}]+[;,]?\s*$/;
+
+interface DelimiterBalance {
+	paren: number;
+	bracket: number;
+	brace: number;
+}
+
+/**
+ * Net `()` / `[]` / `{}` delta across `lines`, skipping delimiters inside line
+ * comments (`//`), block comments, and string/template literals. Block-comment
+ * and backtick-template state carry across lines; `"` / `'` reset at EOL since
+ * they cannot span lines. Deliberately language-light: constructs it cannot
+ * classify (e.g. regex literals) are counted naively, which can only suppress a
+ * repair (the safe direction), never force one.
+ */
+function computeDelimiterBalance(lines: readonly string[]): DelimiterBalance {
+	const balance: DelimiterBalance = { paren: 0, bracket: 0, brace: 0 };
+	let inBlockComment = false;
+	let quote = "";
+	for (const line of lines) {
+		for (let i = 0; i < line.length; i++) {
+			const ch = line[i];
+			if (inBlockComment) {
+				if (ch === "*" && line[i + 1] === "/") {
+					inBlockComment = false;
+					i++;
+				}
+				continue;
+			}
+			if (quote) {
+				if (ch === "\\") i++;
+				else if (ch === quote) quote = "";
+				continue;
+			}
+			if (ch === '"' || ch === "'" || ch === "`") {
+				quote = ch;
+				continue;
+			}
+			if (ch === "/" && line[i + 1] === "/") break;
+			if (ch === "/" && line[i + 1] === "*") {
+				inBlockComment = true;
+				i++;
+				continue;
+			}
+			switch (ch) {
+				case "(":
+					balance.paren++;
+					break;
+				case ")":
+					balance.paren--;
+					break;
+				case "[":
+					balance.bracket++;
+					break;
+				case "]":
+					balance.bracket--;
+					break;
+				case "{":
+					balance.brace++;
+					break;
+				case "}":
+					balance.brace--;
+					break;
+			}
+		}
+		// `"` / `'` cannot span lines; only backtick templates and block comments do.
+		if (quote === '"' || quote === "'") quote = "";
+	}
+	return balance;
+}
+
+function balanceDelta(a: DelimiterBalance, b: DelimiterBalance): DelimiterBalance {
+	return { paren: a.paren - b.paren, bracket: a.bracket - b.bracket, brace: a.brace - b.brace };
+}
+
+function balanceNegate(a: DelimiterBalance): DelimiterBalance {
+	return { paren: -a.paren, bracket: -a.bracket, brace: -a.brace };
+}
+
+function balanceEqual(a: DelimiterBalance, b: DelimiterBalance): boolean {
+	return a.paren === b.paren && a.bracket === b.bracket && a.brace === b.brace;
+}
+
+function balanceIsZero(a: DelimiterBalance): boolean {
+	return a.paren === 0 && a.bracket === 0 && a.brace === 0;
+}
+
+interface ReplacementGroup {
+	/** Positions in the edit array of the payload inserts, in payload order. */
+	insertIndices: number[];
+	/** Positions in the edit array of the range deletes, ascending by line. */
+	deleteIndices: number[];
+	payload: string[];
+	/** First deleted line (1-indexed). */
+	startLine: number;
+	/** Last deleted line (1-indexed). */
+	endLine: number;
+}
+
+/**
+ * Detect a replacement group starting at `start`: a run of `before_anchor`
+ * replacement inserts sharing one source op line, immediately followed by the
+ * contiguous range deletes for that same op. Mirrors how the parser lowers an
+ * `replace N..M:` hunk with a body.
+ */
+function findReplacementGroup(edits: readonly AppliedEdit[], start: number): ReplacementGroup | undefined {
+	const first = edits[start];
+	if (first?.kind !== "insert" || first.mode !== "replacement" || first.cursor.kind !== "before_anchor") {
+		return undefined;
+	}
+	const { lineNum } = first;
+	const anchorLine = first.cursor.anchor.line;
+	const insertIndices: number[] = [];
+	const payload: string[] = [];
+	let i = start;
+	for (; i < edits.length; i++) {
+		const edit = edits[i];
+		if (edit.kind !== "insert" || edit.mode !== "replacement" || edit.lineNum !== lineNum) break;
+		if (edit.cursor.kind !== "before_anchor" || edit.cursor.anchor.line !== anchorLine) break;
+		insertIndices.push(i);
+		payload.push(edit.text);
+	}
+	const deleteIndices: number[] = [];
+	let expectedLine = anchorLine;
+	for (; i < edits.length; i++) {
+		const edit = edits[i];
+		if (edit.kind !== "delete" || edit.lineNum !== lineNum || edit.anchor.line !== expectedLine) break;
+		deleteIndices.push(i);
+		expectedLine++;
+	}
+	if (deleteIndices.length === 0) return undefined;
+	return {
+		insertIndices,
+		deleteIndices,
+		payload,
+		startLine: anchorLine,
+		endLine: anchorLine + deleteIndices.length - 1,
+	};
+}
+
+/**
+ * Largest `k` such that the payload's last `k` lines exactly equal the `k`
+ * surviving file lines just below the range AND dropping them zeroes `delta`.
+ * Single-line drops are limited to pure structural closers.
+ */
+function findDuplicateSuffix(group: ReplacementGroup, fileLines: readonly string[], delta: DelimiterBalance): number {
+	const { payload, endLine } = group;
+	const maxK = Math.min(payload.length, fileLines.length - endLine);
+	for (let k = maxK; k >= 1; k--) {
+		let matches = true;
+		for (let t = 0; t < k; t++) {
+			if (payload[payload.length - k + t] !== fileLines[endLine + t]) {
+				matches = false;
+				break;
+			}
+		}
+		if (!matches) continue;
+		if (k === 1 && !STRUCTURAL_CLOSER_RE.test(payload[payload.length - 1])) continue;
+		if (balanceEqual(computeDelimiterBalance(payload.slice(payload.length - k)), delta)) return k;
+	}
+	return 0;
+}
+
+/**
+ * Largest `j` such that the payload's first `j` lines exactly equal the `j`
+ * surviving file lines just above the range AND dropping them zeroes `delta`.
+ */
+function findDuplicatePrefix(group: ReplacementGroup, fileLines: readonly string[], delta: DelimiterBalance): number {
+	const { payload, startLine } = group;
+	const maxJ = Math.min(payload.length, startLine - 1);
+	for (let j = maxJ; j >= 1; j--) {
+		let matches = true;
+		for (let t = 0; t < j; t++) {
+			if (payload[t] !== fileLines[startLine - 1 - j + t]) {
+				matches = false;
+				break;
+			}
+		}
+		if (!matches) continue;
+		if (j === 1 && !STRUCTURAL_CLOSER_RE.test(payload[0])) continue;
+		if (balanceEqual(computeDelimiterBalance(payload.slice(0, j)), delta)) return j;
+	}
+	return 0;
+}
+
+/**
+ * Smallest `m` such that the range's last `m` deleted lines are all pure
+ * structural closers and sparing them (keeping instead of deleting) zeroes
+ * `delta`. The mirror mistake: a range that swallows a closing delimiter the
+ * payload never restates.
+ */
+function findDroppedSuffixClosers(
+	group: ReplacementGroup,
+	fileLines: readonly string[],
+	delta: DelimiterBalance,
+): number {
+	const wanted = balanceNegate(delta);
+	const maxM = group.deleteIndices.length;
+	for (let m = 1; m <= maxM; m++) {
+		if (!STRUCTURAL_CLOSER_RE.test(fileLines[group.endLine - m] ?? "")) break;
+		if (balanceEqual(computeDelimiterBalance(fileLines.slice(group.endLine - m, group.endLine)), wanted)) return m;
+	}
+	return 0;
+}
+
+function describeBoundaryRepair(group: ReplacementGroup, action: string): string {
+	return (
+		`Auto-repaired a delimiter-balance mismatch in the replacement at line ${group.startLine}: ${action}. ` +
+		`Issue the payload as the final desired content only — never restate or omit a closing bracket bordering the range.`
+	);
+}
+
+/**
+ * Normalize each replacement group so its payload preserves the deleted
+ * region's delimiter balance. See the section header for the contract. Returns
+ * the (possibly trimmed) edit list plus one warning per repaired group.
+ */
+function repairBoundaryBalance(
+	edits: readonly AppliedEdit[],
+	fileLines: readonly string[],
+): {
+	edits: AppliedEdit[];
+	warnings: string[];
+} {
+	const out: AppliedEdit[] = [];
+	const warnings: string[] = [];
+	let i = 0;
+	while (i < edits.length) {
+		const group = findReplacementGroup(edits, i);
+		if (!group) {
+			out.push(edits[i]);
+			i++;
+			continue;
+		}
+		const inserts = group.insertIndices.map(idx => edits[idx]);
+		const deletes = group.deleteIndices.map(idx => edits[idx]);
+		i = group.deleteIndices[group.deleteIndices.length - 1] + 1;
+
+		const delta = balanceDelta(
+			computeDelimiterBalance(group.payload),
+			computeDelimiterBalance(fileLines.slice(group.startLine - 1, group.endLine)),
+		);
+		if (balanceIsZero(delta)) {
+			out.push(...inserts, ...deletes);
+			continue;
+		}
+
+		const dupSuffix = findDuplicateSuffix(group, fileLines, delta);
+		if (dupSuffix > 0) {
+			warnings.push(
+				describeBoundaryRepair(
+					group,
+					`dropped ${dupSuffix} duplicated trailing payload line(s) already present below the range`,
+				),
+			);
+			out.push(...inserts.slice(0, inserts.length - dupSuffix), ...deletes);
+			continue;
+		}
+		const dupPrefix = findDuplicatePrefix(group, fileLines, delta);
+		if (dupPrefix > 0) {
+			warnings.push(
+				describeBoundaryRepair(
+					group,
+					`dropped ${dupPrefix} duplicated leading payload line(s) already present above the range`,
+				),
+			);
+			out.push(...inserts.slice(dupPrefix), ...deletes);
+			continue;
+		}
+		const droppedClosers = findDroppedSuffixClosers(group, fileLines, delta);
+		if (droppedClosers > 0) {
+			warnings.push(
+				describeBoundaryRepair(
+					group,
+					`kept ${droppedClosers} structural closing line(s) the range deleted without restating`,
+				),
+			);
+			out.push(...inserts, ...deletes.slice(0, deletes.length - droppedClosers));
+			continue;
+		}
+		out.push(...inserts, ...deletes);
+	}
+	return { edits: out, warnings };
+}
+
 /**
  * Apply a parsed list of edits to a text body. Pure function — no I/O.
  *
@@ -149,14 +418,15 @@ export function applyEdits(text: string, edits: Edit[]): ApplyResult {
 		if (firstChangedLine === undefined || line < firstChangedLine) firstChangedLine = line;
 	};
 
-	const targetEdits = expandRepeatEdits(edits, fileLines);
+	const targetEdits = edits.map((edit, index) => cloneAppliedEdit(edit, index));
 	validateLineBounds(targetEdits, fileLines);
+	const { edits: repaired, warnings } = repairBoundaryBalance(targetEdits, fileLines);
 
-	// Partition edits into BOF, EOF, and anchor-targeted buckets.
+	// Partition edits into bof, eof, and anchor-targeted buckets.
 	const bofLines: string[] = [];
 	const eofLines: string[] = [];
 	const anchorEdits: IndexedEdit[] = [];
-	targetEdits.forEach((edit, idx) => {
+	repaired.forEach((edit, idx) => {
 		if (edit.kind === "insert" && edit.cursor.kind === "bof") {
 			bofLines.push(edit.text);
 		} else if (edit.kind === "insert" && edit.cursor.kind === "eof") {
@@ -175,28 +445,38 @@ export function applyEdits(text: string, edits: Edit[]): ApplyResult {
 
 		const idx = line - 1;
 		const currentLine = fileLines[idx] ?? "";
-		const insertLines: string[] = [];
+		const beforeInsertLines: string[] = [];
+		const afterInsertLines: string[] = [];
 		const replacementLines: string[] = [];
 		let deleteLine = false;
 
 		for (const { edit } of bucket) {
 			if (isReplacementInsert(edit)) {
 				replacementLines.push(edit.text);
+			} else if (edit.kind === "insert" && edit.cursor.kind === "after_anchor") {
+				afterInsertLines.push(edit.text);
 			} else if (edit.kind === "insert") {
-				insertLines.push(edit.text);
+				beforeInsertLines.push(edit.text);
 			} else if (edit.kind === "delete") {
 				deleteLine = true;
 			}
 		}
-		if (insertLines.length === 0 && replacementLines.length === 0 && !deleteLine) continue;
+		if (
+			beforeInsertLines.length === 0 &&
+			replacementLines.length === 0 &&
+			afterInsertLines.length === 0 &&
+			!deleteLine
+		)
+			continue;
 
 		const replacement = deleteLine
-			? [...insertLines, ...replacementLines]
-			: [...insertLines, ...replacementLines, currentLine];
+			? [...beforeInsertLines, ...replacementLines, ...afterInsertLines]
+			: [...beforeInsertLines, ...replacementLines, currentLine, ...afterInsertLines];
 		const origins: LineOrigin[] = [];
-		for (let i = 0; i < insertLines.length; i++) origins.push("insert");
+		for (let i = 0; i < beforeInsertLines.length; i++) origins.push("insert");
 		for (let i = 0; i < replacementLines.length; i++) origins.push(deleteLine ? "replacement" : "insert");
 		if (!deleteLine) origins.push(lineOrigins[idx] ?? "original");
+		for (let i = 0; i < afterInsertLines.length; i++) origins.push("insert");
 
 		fileLines.splice(idx, 1, ...replacement);
 		lineOrigins.splice(idx, 1, ...origins);
@@ -213,5 +493,6 @@ export function applyEdits(text: string, edits: Edit[]): ApplyResult {
 	return {
 		text: fileLines.join("\n"),
 		firstChangedLine,
+		...(warnings.length > 0 ? { warnings } : {}),
 	};
 }

package/src/format.ts

@@ -4,16 +4,30 @@
  * tokenizer, the prompt, and the formal grammar.
  */
 
+import type { Cursor } from "./types";
+
 /** File-section header prefix: `¶path#hash`. */
 export const HL_FILE_PREFIX = "¶";
 
 /** Payload sigil for literal body rows. */
 export const HL_PAYLOAD_REPLACE = "+";
-/** Payload sigil for body rows that repeat original file lines. */
-export const HL_PAYLOAD_REPEAT = "&";
 
-/** All hashline payload sigils, concatenated for fast membership tests. */
-export const HL_PAYLOAD_CHARS = `${HL_PAYLOAD_REPLACE}${HL_PAYLOAD_REPEAT}`;
+/** Hunk-header keyword for concrete line replacement. */
+export const HL_REPLACE_KEYWORD = "replace";
+/** Hunk-header keyword for concrete line deletion. */
+export const HL_DELETE_KEYWORD = "delete";
+/** Hunk-header keyword for insertion operations. */
+export const HL_INSERT_KEYWORD = "insert";
+/** Insert position keyword for inserting before a concrete line. */
+export const HL_INSERT_BEFORE = "before";
+/** Insert position keyword for inserting after a concrete line. */
+export const HL_INSERT_AFTER = "after";
+/** Insert position keyword for inserting at the start of the file. */
+export const HL_INSERT_HEAD = "head";
+/** Insert position keyword for inserting at the end of the file. */
+export const HL_INSERT_TAIL = "tail";
+/** Hunk-header terminator for body-bearing operations. */
+export const HL_HEADER_COLON = ":";
 
 /** Separator between a hashline file path and its opaque snapshot tag. */
 export const HL_FILE_HASH_SEP = "#";
@@ -28,46 +42,68 @@ function regexEscape(str: string): string {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-/**
- * Decoration prefix that may precede a line number in tool output:
- * `*` (match line), `>` (context line in grep). Any combination, in any
- * order, surrounded by optional whitespace. Output formatters emit at most
- * one decoration per line; the parser stays liberal because it accepts
- * whatever the model echoes back.
- */
-export const HL_ANCHOR_DECORATION_RE_RAW = `\\s*[>*]*\\s*`;
-
-/** Capture-group regex source for a decorated bare line-number anchor. */
-export const HL_ANCHOR_RE_RAW = `${HL_ANCHOR_DECORATION_RE_RAW}(\\d+)`;
-
 /** Bare positive line-number Lid (no decorations, no captures, no anchors). */
 export const HL_LINE_RE_RAW = `[1-9]\\d*`;
 
 /** Capture-group form of {@link HL_LINE_RE_RAW}. */
 export const HL_LINE_CAPTURE_RE_RAW = `(${HL_LINE_RE_RAW})`;
 
-/** Regex for repeat payload rows (`&A..B`). */
-export const HL_PAYLOAD_REPEAT_RE = new RegExp(
-	`^\\${HL_PAYLOAD_REPEAT}${HL_LINE_CAPTURE_RE_RAW},${HL_LINE_CAPTURE_RE_RAW}$`,
-);
+/** Format a concrete replacement hunk header. */
+export function formatReplaceHeader(start: number, end: number): string {
+	return `${HL_REPLACE_KEYWORD} ${start}${HL_RANGE_SEP}${end}${HL_HEADER_COLON}`;
+}
 
-/** Number of hex characters in an opaque snapshot tag. */
-export const HL_FILE_HASH_LENGTH = 3;
+/** Format a concrete deletion hunk header. */
+export function formatDeleteHeader(start: number, end = start): string {
+	return start === end ? `${HL_DELETE_KEYWORD} ${start}` : `${HL_DELETE_KEYWORD} ${start}${HL_RANGE_SEP}${end}`;
+}
 
-/** Canonical uppercase hexadecimal opaque snapshot tag carried by a hashline section header. */
-export const HL_FILE_HASH_RE_RAW = `[0-9A-F]{${HL_FILE_HASH_LENGTH}}`;
+/** Format an insertion hunk header for a cursor position. */
+export function formatInsertHeader(cursor: Cursor): string {
+	switch (cursor.kind) {
+		case "before_anchor":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_BEFORE} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "after_anchor":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_AFTER} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "bof":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_HEAD}${HL_HEADER_COLON}`;
+		case "eof":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_TAIL}${HL_HEADER_COLON}`;
+	}
+}
 
+/** Number of hex characters in a content-derived file-hash tag. */
+export const HL_FILE_HASH_LENGTH = 4;
+/** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */
+export const HL_FILE_HASH_RE_RAW = `[0-9A-F]{${HL_FILE_HASH_LENGTH}}`;
 /** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
 export const HL_FILE_HASH_CAPTURE_RE_RAW = `(${HL_FILE_HASH_RE_RAW})`;
-
 /** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
 export const HL_LINE_BODY_SEP_RE_RAW = regexEscape(HL_LINE_BODY_SEP);
-
 /**
- * Representative snapshot tags for use in user-facing error messages and
+ * Representative file-hash tags for use in user-facing error messages and
  * prompt examples.
  */
-export const HL_FILE_HASH_EXAMPLES = ["0A3", "1F7", "3C9"] as const;
+export const HL_FILE_HASH_EXAMPLES = ["1A2B", "3C4D", "9F3E"] as const;
+/**
+ * Normalize text before hashing: trim trailing `[ \t\r]` from every line (and
+ * the final line) in a single pass so CRLF endings and display-trimmed lines
+ * do not invalidate a tag.
+ */
+function normalizeFileHashText(text: string): string {
+	return text.replace(/[ \t\r]+(?=\n|$)/g, "");
+}
+/**
+ * Compute the content-derived hash tag carried by a hashline section header.
+ * The tag is a 4-hex fingerprint of the whole file's normalized text: any read
+ * of byte-identical content mints the same tag, and a follow-up edit anchored
+ * at any line validates whenever the live file still hashes to it.
+ */
+export function computeFileHash(text: string): string {
+	const normalized = normalizeFileHashText(text);
+	const low16 = Bun.hash.xxHash32(normalized, 0) & 0xffff;
+	return low16.toString(16).padStart(HL_FILE_HASH_LENGTH, "0").toUpperCase();
+}
 
 /**
  * Format a comma-separated list of example anchors with an optional line-number

package/src/grammar.lark

@@ -4,19 +4,19 @@ end_patch:   "*** End Patch" LF?
 
 file_patch: file_header hunk+
 file_header: "¶" filename ("#" file_hash)? LF
-file_hash: /[0-9A-F]{3}/
+file_hash: /[0-9A-F]{4}/
 filename: /[^\s#]+/
 
-hunk: hunk_header op*
-hunk_header: anchor LF
-op: emit_op | repeat_op
-emit_op:   "+" /(.*)/ LF
-repeat_op: "&" body_range LF
+hunk: body_hunk | delete_hunk
+body_hunk:   body_header emit_op+
+delete_hunk: "delete " header_range LF
+body_header: (replace_anchor | insert_anchor) LF
+replace_anchor: "replace " header_range ":"
+insert_anchor:  "insert " insert_pos ":"
+insert_pos: "before " LID | "after " LID | "head" | "tail"
+emit_op: "+" /(.*)/ LF
 
-anchor: header_range | "BOF" | "EOF"
-header_range: LID WS LID
-body_range: LID (".." LID)?
+header_range: LID ".." LID
 LID: /[1-9]\d*/
-WS: /[ \t]+/
 
 %import common.LF