@prometheus-ai/hashline 0.5.0

package/src/patcher.ts

@@ -0,0 +1,392 @@
+/**
+ * High-level patch orchestrator. Reads each section's target file via the
+ * configured {@link Filesystem}, strips BOM and normalizes line endings,
+ * validates the section snapshot tag (with {@link Recovery}), applies the
+ * result back through the same {@link Filesystem}.
+ *
+ * Two layers:
+ *
+ * - {@link Patcher.apply} — high-level, all-or-nothing. Preflights every
+ *   section in memory before any write hits disk, then commits in order.
+ * - {@link Patcher.prepare} / {@link Patcher.commit} — granular primitives
+ *   for callers that need per-section control (e.g. batched LSP flush,
+ *   custom interleaving). `prepare` performs all the read-side work,
+ *   validates the section snapshot tag (with recovery), and applies the
+ *   edits in memory. `commit` writes the prepared result and records a
+ *   fresh snapshot.
+ *
+ * Because `prepare` already runs the full apply, a multi-section batch is
+ * naturally all-or-nothing: by the time any `commit` runs, every section
+ * has been validated.
+ *
+ * The patcher itself is stateless across calls; reuse one instance per
+ * filesystem configuration.
+ */
+import { applyEdits } from "./apply";
+import { hasBlockEdit, resolveBlockEdits } from "./block";
+import { computeFileHash, formatHashlineHeader } from "./format";
+import type { Filesystem, WriteResult } from "./fs";
+import { isNotFound } from "./fs";
+import type { Patch, PatchSection } from "./input";
+import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage } from "./messages";
+import { MismatchError } from "./mismatch";
+import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
+import { Recovery, type RecoveryResult } from "./recovery";
+import type { SnapshotStore } from "./snapshots";
+import type { ApplyResult, BlockResolver, Edit } from "./types";
+
+export interface PatcherOptions {
+	/** Storage backend used for all reads and writes. */
+	fs: Filesystem;
+	/** Snapshot store that minted and resolves hashline section tags. Required. */
+	snapshots: SnapshotStore;
+	/**
+	 * Resolves `replace block N:` anchors to concrete line spans via tree-sitter.
+	 * Optional: when omitted, any `replace block N:` edit throws on apply (the
+	 * host did not wire a resolver). Plain line-range ops never need it.
+	 */
+	blockResolver?: BlockResolver;
+}
+
+/** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
+export interface PatchSectionResult {
+	/** Section path (as authored, after cwd-resolution at parse time). */
+	path: string;
+	/** Filesystem-canonical key for this section (e.g. absolute path). */
+	canonicalPath: string;
+	/** `"noop"` when the apply produced no change; otherwise `"create"` / `"update"`. */
+	op: "create" | "update" | "noop";
+	/** Pre-edit text (LF-normalized, BOM-stripped). */
+	before: string;
+	/** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
+	after: string;
+	/** Same text as `after` but with the original BOM and line ending restored. */
+	persisted: string;
+	/** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
+	written: string;
+	/** 4-hex content-hash tag for `after`. Use to anchor follow-up edits. */
+	fileHash: string;
+	/** Hashline section header (`[path#tag]`) of the post-edit content. */
+	header: string;
+	/** 1-indexed first changed line in `after`, or `undefined` for noops. */
+	firstChangedLine?: number;
+	/** Warnings collected by the parser, applier, and (optionally) recovery. */
+	warnings: string[];
+}
+
+export interface PatcherApplyResult {
+	sections: PatchSectionResult[];
+}
+
+/**
+ * Opaque token returned by {@link Patcher.prepare}. Carries the section, the
+ * raw file content read off disk, and the in-memory apply result.
+ * {@link Patcher.commit} just writes the {@link PreparedSection.applyResult}.
+ */
+export class PreparedSection {
+	/** @internal */
+	constructor(
+		readonly section: PatchSection,
+		readonly canonicalPath: string,
+		readonly exists: boolean,
+		readonly rawContent: string,
+		readonly bom: string,
+		readonly lineEnding: LineEnding,
+		readonly normalized: string,
+		readonly applyResult: ApplyResult,
+		readonly parseWarnings: readonly string[],
+	) {}
+
+	/** Convenience: returns true when the apply produced no change. */
+	get isNoop(): boolean {
+		return this.applyResult.text === this.normalized;
+	}
+}
+
+function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
+	return edits.some(edit => {
+		if (edit.kind === "delete") return true;
+		// A `replace block N:` edit anchors to concrete content on line N.
+		if (edit.kind === "block") return true;
+		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
+	});
+}
+
+function assertSectionHashPresent(sectionPath: string, fileHash: string | undefined): void {
+	if (fileHash !== undefined) return;
+	throw new Error(missingSnapshotTagMessage(sectionPath));
+}
+
+function recoveryToApplyResult(result: RecoveryResult): ApplyResult {
+	return {
+		text: result.text,
+		firstChangedLine: result.firstChangedLine,
+		warnings: result.warnings,
+	};
+}
+function mergeWarnings(...sources: ReadonlyArray<readonly string[] | undefined>): string[] {
+	const out: string[] = [];
+	for (const source of sources) {
+		if (!source) continue;
+		for (const warning of source) out.push(warning);
+	}
+	return out;
+}
+
+function assertUniqueCanonicalPaths(prepared: readonly PreparedSection[]): void {
+	const seen = new Map<string, string>();
+	for (const entry of prepared) {
+		const previous = seen.get(entry.canonicalPath);
+		if (previous !== undefined) {
+			throw new Error(
+				`Multiple hashline sections resolve to the same file (${previous} and ${entry.section.path}). Merge their ops under one header before applying.`,
+			);
+		}
+		seen.set(entry.canonicalPath, entry.section.path);
+	}
+}
+
+/**
+ * High-level patcher. Wires a {@link Filesystem} and a required
+ * {@link SnapshotStore} together with the parsing + applying core.
+ *
+ * Construct once per FS configuration; reuse across patches.
+ */
+export class Patcher {
+	readonly fs: Filesystem;
+	readonly snapshots: SnapshotStore;
+	readonly recovery: Recovery;
+	readonly blockResolver: BlockResolver | undefined;
+
+	constructor(options: PatcherOptions) {
+		if (!options.snapshots) {
+			throw new Error("Hashline Patcher requires a SnapshotStore; section tags are opaque store pointers.");
+		}
+		this.fs = options.fs;
+		this.snapshots = options.snapshots;
+		this.recovery = new Recovery(options.snapshots);
+		this.blockResolver = options.blockResolver;
+	}
+
+	/**
+	 * Apply every section in `patch`. `prepare` runs the full apply for each
+	 * section in memory before any write hits the filesystem, so a
+	 * multi-section batch is naturally all-or-nothing. Returns one
+	 * {@link PatchSectionResult} per section in the original patch order.
+	 */
+	async apply(patch: Patch): Promise<PatcherApplyResult> {
+		// Single-section fast path.
+		if (patch.sections.length === 1) {
+			const prepared = await this.prepare(patch.sections[0]);
+			return { sections: [await this.commit(prepared)] };
+		}
+
+		// Prepare every section first so any failure (stale hash, missing
+		// file, parse error, in-memory no-op) surfaces before any write.
+		const prepared: PreparedSection[] = [];
+		for (const section of patch.sections) prepared.push(await this.prepare(section));
+		assertUniqueCanonicalPaths(prepared);
+		for (const entry of prepared) {
+			if (entry.isNoop) {
+				throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+			}
+		}
+
+		const results: PatchSectionResult[] = [];
+		for (const entry of prepared) results.push(await this.commit(entry));
+		return { sections: results };
+	}
+
+	/**
+	 * Run the preflight pass only: read, parse, validate, apply-in-memory.
+	 * No writes hit the filesystem. Use for CI checks and dry runs.
+	 */
+	async preflight(patch: Patch): Promise<void> {
+		const prepared: PreparedSection[] = [];
+		for (const section of patch.sections) prepared.push(await this.prepare(section));
+		assertUniqueCanonicalPaths(prepared);
+		for (const entry of prepared) {
+			if (entry.isNoop) {
+				throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+			}
+		}
+	}
+
+	/**
+	 * Read a section's target file, parse the section, validate the snapshot
+	 * tag (with recovery), and apply the edits in memory. Returns a
+	 * {@link PreparedSection} which can be fed to {@link commit} to land
+	 * the result on the filesystem.
+	 *
+	 * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
+	 * tag mismatch ({@link MismatchError}).
+	 */
+	async prepare(section: PatchSection): Promise<PreparedSection> {
+		const { edits, warnings: parseWarnings } = section.parse();
+		assertSectionHashPresent(section.path, section.fileHash);
+
+		const canonicalPath = this.fs.canonicalPath(section.path);
+		await this.fs.preflightWrite(section.path);
+		const { exists, rawContent } = await this.#tryRead(section.path);
+		if (!exists) {
+			throw new Error(`File not found: ${section.path}. Use the write tool to create new files.`);
+		}
+
+		const { bom, text } = stripBom(rawContent);
+		const lineEnding = detectLineEnding(text);
+		const normalized = normalizeToLF(text);
+
+		const applyResult = this.#applyWithRecovery({
+			section,
+			canonicalPath,
+			exists,
+			normalized,
+			edits,
+		});
+
+		return new PreparedSection(
+			section,
+			canonicalPath,
+			exists,
+			rawContent,
+			bom,
+			lineEnding,
+			normalized,
+			applyResult,
+			parseWarnings,
+		);
+	}
+
+	/**
+	 * Commit a previously {@link prepare}d section to the filesystem.
+	 * Restores line endings and BOM, writes via the {@link Filesystem}, and
+	 * records a fresh snapshot in the {@link SnapshotStore} keyed by the
+	 * filesystem-canonical path.
+	 */
+	async commit(prepared: PreparedSection): Promise<PatchSectionResult> {
+		const { section, normalized, bom, lineEnding, parseWarnings, exists, applyResult, canonicalPath } = prepared;
+		const after = applyResult.text;
+		const warnings = mergeWarnings(parseWarnings, applyResult.warnings);
+
+		if (after === normalized) {
+			const hash = this.#recordFullSnapshot(canonicalPath, normalized);
+			return {
+				path: section.path,
+				canonicalPath,
+				op: "noop",
+				before: normalized,
+				after: normalized,
+				persisted: prepared.rawContent,
+				written: prepared.rawContent,
+				fileHash: hash,
+				header: formatHashlineHeader(section.path, hash),
+				warnings,
+			};
+		}
+
+		const persisted = bom + restoreLineEndings(after, lineEnding);
+		const write: WriteResult = await this.fs.writeText(section.path, persisted);
+		const fileHash = this.#recordFullSnapshot(canonicalPath, after);
+		const op = exists ? "update" : "create";
+
+		return {
+			path: section.path,
+			canonicalPath,
+			op,
+			before: normalized,
+			after,
+			persisted,
+			written: write.text,
+			fileHash,
+			header: formatHashlineHeader(section.path, fileHash),
+			firstChangedLine: applyResult.firstChangedLine,
+			warnings,
+		};
+	}
+
+	async #tryRead(path: string): Promise<{ exists: boolean; rawContent: string }> {
+		try {
+			const content = await this.fs.readText(path);
+			return { exists: true, rawContent: content };
+		} catch (error) {
+			if (isNotFound(error)) return { exists: false, rawContent: "" };
+			throw error;
+		}
+	}
+
+	#recordFullSnapshot(canonicalPath: string, normalized: string): string {
+		return this.snapshots.record(canonicalPath, normalized);
+	}
+	#mismatchError(
+		section: PatchSection,
+		canonicalPath: string,
+		normalized: string,
+		expected: string,
+		hashRecognized: boolean,
+	): MismatchError {
+		const actualFileHash = this.#recordFullSnapshot(canonicalPath, normalized);
+		return new MismatchError({
+			path: section.path,
+			expectedFileHash: expected,
+			actualFileHash,
+			fileLines: normalized.split("\n"),
+			anchorLines: section.collectAnchorLines(),
+			hashRecognized,
+		});
+	}
+
+	#applyWithRecovery(args: {
+		section: PatchSection;
+		canonicalPath: string;
+		exists: boolean;
+		normalized: string;
+		edits: readonly Edit[];
+	}): ApplyResult {
+		const { section, canonicalPath, exists, normalized, edits } = args;
+		const expected = exists ? section.fileHash : undefined;
+		const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
+
+		// Resolve `replace block N:` edits to concrete ranges before recovery
+		// runs. Block anchors are expressed against the snapshot the section tag
+		// names, so resolve against that exact text:
+		//   - live content matches the tag (or there is no tag) → resolve against
+		//     the live, normalized content;
+		//   - the file drifted → resolve against the tagged snapshot's text so the
+		//     resulting ranges flow through the 3-way-merge recovery below.
+		// When a block edit needs the tagged snapshot but it is unavailable, the
+		// range cannot be placed safely — reject with a MismatchError (re-read).
+		let resolved: readonly Edit[] = edits;
+		if (hasBlockEdit(edits)) {
+			const baseText =
+				expected === undefined || liveMatches ? normalized : this.snapshots.byHash(canonicalPath, expected)?.text;
+			if (baseText === undefined) {
+				throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", false);
+			}
+			resolved = resolveBlockEdits(edits, baseText, section.path, this.blockResolver, { onUnresolved: "throw" });
+		}
+
+		if (expected === undefined) return applyEdits(normalized, resolved);
+		// Whole-file unchanged → the tag still names the live content, so an
+		// edit anchored at ANY line (displayed or not) is safe to apply.
+		if (liveMatches) return applyEdits(normalized, resolved);
+		// Head/tail-only inserts are position-stable: "start"/"end" cannot move
+		// with content drift, so a stale tag is non-fatal. Apply onto the live
+		// content and warn instead of hard-failing — unlike an anchored
+		// mismatch, which cannot be safely relocated and must reject.
+		if (!hasAnchorScopedEdit(resolved)) {
+			const result = applyEdits(normalized, resolved);
+			return { ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] };
+		}
+		// File drifted: try to replay the edit against the version the tag
+		// names and 3-way-merge it onto the live content.
+		const recovered = this.recovery.tryRecover({
+			path: canonicalPath,
+			currentText: normalized,
+			fileHash: expected,
+			edits: resolved,
+		});
+		if (recovered) return recoveryToApplyResult(recovered);
+		const hashRecognized = this.snapshots.byHash(canonicalPath, expected) !== null;
+		throw this.#mismatchError(section, canonicalPath, normalized, expected, hashRecognized);
+	}
+}

package/src/prefixes.ts

@@ -0,0 +1,132 @@
+/**
+ * When a hashline payload is authored against `read`/`search` output, each
+ * line is prefixed with either a hashline-mode line number (`123:`) or, for
+ * diff-style echoes, a leading `+`. These helpers detect that and recover
+ * the raw text. Two strip modes are exposed:
+ *
+ * - {@link stripNewLinePrefixes} — opportunistic: strips when the input
+ *   clearly carries hashline or diff prefixes, leaves it alone otherwise.
+ * - {@link stripHashlinePrefixes} — strict: only strips when every non-empty
+ *   content line is hashline-prefixed.
+ *
+ * These run *before* the tokenizer; they exist because hashline mode is the
+ * common case for echoed file content, and erroneously echoed prefixes will
+ * otherwise turn every content line into a (malformed) op.
+ */
+
+import { HL_FILE_HASH_LENGTH } from "./format";
+
+const HL_PREFIX_RE = /^\s*(?:>>>|>>)?\s*(?:[+*-]\s*)?\d+:/;
+const HL_PREFIX_PLUS_RE = /^\s*(?:>>>|>>)?\s*\+\s*\d+:/;
+const HL_HEADER_RE = new RegExp(`^\\s*\\[[^#\\r\\n]+#[0-9a-fA-F]{${HL_FILE_HASH_LENGTH}}\\]\\s*$`);
+const DIFF_PLUS_RE = /^[+](?![+])/;
+const READ_TRUNCATION_NOTICE_RE = /^\[(?:Showing lines \d+-\d+ of \d+|\d+ more lines? in (?:file|\S+))\b.*\bUse :L?\d+/;
+
+function stripLeadingHashlinePrefixes(line: string): string {
+	let result = line;
+	let previous: string;
+	do {
+		previous = result;
+		result = result.replace(HL_PREFIX_RE, "");
+	} while (result !== previous);
+	return result;
+}
+
+interface LinePrefixStats {
+	nonEmpty: number;
+	headerCount: number;
+	hashPrefixCount: number;
+	diffPlusHashPrefixCount: number;
+	diffPlusCount: number;
+	truncationNoticeCount: number;
+}
+
+function collectLinePrefixStats(lines: string[]): LinePrefixStats {
+	const stats: LinePrefixStats = {
+		nonEmpty: 0,
+		headerCount: 0,
+		hashPrefixCount: 0,
+		diffPlusHashPrefixCount: 0,
+		diffPlusCount: 0,
+		truncationNoticeCount: 0,
+	};
+
+	for (const line of lines) {
+		if (line.length === 0) continue;
+		if (READ_TRUNCATION_NOTICE_RE.test(line)) {
+			stats.truncationNoticeCount++;
+			continue;
+		}
+		if (HL_HEADER_RE.test(line)) {
+			stats.nonEmpty++;
+			stats.headerCount++;
+			continue;
+		}
+		stats.nonEmpty++;
+		if (HL_PREFIX_RE.test(line)) stats.hashPrefixCount++;
+		if (HL_PREFIX_PLUS_RE.test(line)) stats.diffPlusHashPrefixCount++;
+		if (DIFF_PLUS_RE.test(line)) stats.diffPlusCount++;
+	}
+	return stats;
+}
+
+/**
+ * Strip whichever prefix scheme the lines appear to be carrying:
+ * - hashline line-number prefixes (`123:`) when every content line has one
+ * - leading `+` (diff style) when at least half the lines have one
+ * - mixed `+<n>:` form when present
+ *
+ * Returns the lines untouched if no scheme is recognized.
+ */
+export function stripNewLinePrefixes(lines: string[]): string[] {
+	const stats = collectLinePrefixStats(lines);
+	if (stats.nonEmpty === 0) return lines;
+
+	const contentLineCount = stats.nonEmpty - stats.headerCount;
+	const stripHash = contentLineCount > 0 && stats.hashPrefixCount === contentLineCount;
+	const stripPlus =
+		!stripHash &&
+		stats.diffPlusHashPrefixCount === 0 &&
+		stats.diffPlusCount > 0 &&
+		stats.diffPlusCount >= stats.nonEmpty * 0.5;
+
+	if (!stripHash && !stripPlus && stats.diffPlusHashPrefixCount === 0) return lines;
+
+	return lines
+		.filter(line => !READ_TRUNCATION_NOTICE_RE.test(line) && !(stripHash && HL_HEADER_RE.test(line)))
+		.map(line => {
+			if (stripHash) return stripLeadingHashlinePrefixes(line);
+			if (stripPlus) return line.replace(DIFF_PLUS_RE, "");
+			if (stats.diffPlusHashPrefixCount > 0 && HL_PREFIX_PLUS_RE.test(line)) {
+				return line.replace(HL_PREFIX_RE, "");
+			}
+			return line;
+		});
+}
+
+/**
+ * Strict variant: strip hashline prefixes only when every content line is
+ * hashline-prefixed. Returns the lines unchanged otherwise.
+ */
+export function stripHashlinePrefixes(lines: string[]): string[] {
+	const stats = collectLinePrefixStats(lines);
+	if (stats.nonEmpty === 0) return lines;
+	const contentLineCount = stats.nonEmpty - stats.headerCount;
+	if (contentLineCount === 0 || stats.hashPrefixCount !== contentLineCount) return lines;
+	return lines
+		.filter(line => !READ_TRUNCATION_NOTICE_RE.test(line) && !HL_HEADER_RE.test(line))
+		.map(line => stripLeadingHashlinePrefixes(line));
+}
+
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export function hashlineParseText(edit: string[] | string | null | undefined): string[] {
+	if (edit == null) return [];
+	if (typeof edit === "string") {
+		const trimmed = edit.endsWith("\n") ? edit.slice(0, -1) : edit;
+		edit = trimmed.replaceAll("\r", "").split("\n");
+	}
+	return stripNewLinePrefixes(edit);
+}

package/src/prompt.md

@@ -0,0 +1,109 @@
+Your patch language names lines to replace, delete, or insert at, then lists the new content. Rule of thumb: a header ending in `:` is followed by `+` body rows; `delete` has no body.
+
+<headers>
+Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag from your latest `read`/`search`, and is REQUIRED on every section — there is no hashless form. To create a new file, use the `write` tool; hashline only edits files that already exist.
+</headers>
+
+<ops>
+replace N..M:      replace original lines N..M with the body rows below.
+replace block N:   replace the whole syntactic block that BEGINS on line N — its header line through its closing line — resolved with tree-sitter. Body rows below. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not a closing `}` or a blank line.
+delete N..M        delete original lines N..M. No body.
+delete block N     delete the whole syntactic block that BEGINS on line N.
+insert before N:   insert the body rows immediately before line N.
+insert after N:    insert the body rows immediately after line N.
+insert head:       insert the body rows at the very start of the file.
+insert tail:       insert the body rows at the very end of the file.
+Single line: `replace N..N:` / `delete N`. The range is the ORIGINAL lines you touch; body length is irrelevant (replacing 1 line with 10 is still `replace N..N:`).
+</ops>
+
+<body-rows>
+Body rows appear only under a `:` header. Every body row is:
+  +TEXT     add a new literal line `TEXT`, verbatim (leading whitespace kept). `+` alone adds a blank line.
+There is NO other body row kind. NEVER write `-old` or a bare/context line. To keep a line, leave it out of every range. To insert a literal line starting with `-` or `+`, prefix it: `+-x`, `++x`.
+</body-rows>
+
+<rules>
+- Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `[PATH#TAG]` header; use the bare LINE numbers.
+- Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
+- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `[PATH#TAG]` and lines from the edit response (or re-`read`), never on pre-edit numbers.
+- A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
+- On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
+- One hunk per range; the body is the final content, never an old/new pair.
+- Keep every range as tight as the change: a range must cover ONLY lines whose content actually changes. Never widen it to swallow an unchanged signature, brace, or neighboring statement just to rewrite a few lines inside — change one line with `replace N..N`, not the whole block around it. (A range where every line genuinely changes is correctly long; tightness is about excluding unchanged lines, not about being short.) This bounds the blast radius if a number is off: a stale single-line replace corrupts one line, while a stale block replace shreds the whole block and its structure.
+- To change lines 2 and 5 while keeping 3–4, issue two hunks (`replace 2..2:` and `replace 5..5:`). Untouched lines are simply absent from every range.
+- NEVER use this tool to format code — reordering imports, re-indenting, aligning columns, or any mechanical restyling. That is the project formatter's job; run it instead of hand-editing layout here.
+</rules>
+
+<example>
+Original (the exact shape `read` returns):
+```
+[greet.py#A1B2]
+1:def greet(name):
+2:    msg = "Hello, " + name
+3:    print(msg)
+4:greet("world")
+```
+
+Insert a guard after line 1:
+```
+[greet.py#A1B2]
+insert after 1:
++    if not name: name = "stranger"
+```
+
+Replace line 2 with two lines:
+```
+[greet.py#A1B2]
+replace 2..2:
++    greeting = "Hi"
++    msg = f"{greeting}, {name}"
+```
+
+Delete line 3:
+```
+[greet.py#A1B2]
+delete 3
+```
+
+Add a header and trailer:
+```
+[greet.py#A1B2]
+insert head:
++# generated header
+insert tail:
++greet("everyone")
+```
+
+Replace the whole `greet` function block — `replace block 1:` resolves lines 1–3 (the `def` header through `print(msg)`); line 4 is a separate statement and stays:
+```
+[greet.py#A1B2]
+replace block 1:
++def greet(name):
++    print(f"Hello, {name}")
+```
+</example>
+
+<anti-patterns>
+# WRONG — empty `replace` to delete. RIGHT: delete 4
+replace 4..4:
+
+# WRONG — range describes post-edit size. RIGHT: replace 1..1: (body length is irrelevant)
+replace 1..2:
++def greet(name):
+
+# WRONG — `-` rows / bare context lines do not exist. The range deletes; the body is only the new content.
+replace 3..3:
+    msg = "Hello, " + name
+-   print(msg)
++   return msg
+# RIGHT
+replace 3..3:
++   return msg
+</anti-patterns>
+
+<critical>
+If you remember nothing else:
+1. RE-GROUND AFTER EVERY EDIT. Each applied edit mints a fresh `#TAG` and renumbers the file — the tag and line numbers you just used are now dead. Take the next edit's numbers from the edit response or a fresh `read`, never from pre-edit memory. On a stale-tag rejection or any unexpected result, STOP and re-`read`.
+2. RANGES ARE TIGHT AND IN-BOUNDS. Cover only lines whose content actually changes; never widen a range to swallow an unchanged signature, brace, or statement, and never start or end a range mid-expression or mid-block. A stale single-line replace corrupts one line; a stale block replace shreds the whole block.
+3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows under a `:` header — never `-old`/bare context lines, never an old/new pair. The range does the deleting.
+</critical>