@oh-my-pi/hashline 15.13.0 → 15.13.2

package/src/prompt.md

@@ -1,20 +1,20 @@
-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.
+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; `DEL` 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. INCLUSIVE — line M is consumed too.
-`replace block N:` — replace the whole syntactic block that BEGINS on line N; tree-sitter resolves the closing line. Body rows below.
-`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 after block N:` — insert the body rows after the END of the block that BEGINS on line N — outside it, at sibling depth. To append inside a block, use `insert after`.
-`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:`).
+`SWAP N..M:` — replace original lines N..M with the body rows below. INCLUSIVE — line M is consumed too.
+`SWAP.BLK N:` — replace the whole syntactic block that BEGINS on line N; tree-sitter resolves the closing line. Body rows below.
+`DEL N..M` — delete original lines N..M. No body.
+`DEL.BLK N` — delete the whole syntactic block that BEGINS on line N.
+`INS.PRE N:` — insert the body rows immediately before line N.
+`INS.POST N:` — insert the body rows immediately after line N.
+`INS.BLK.POST N:` — insert the body rows after the END of the block that BEGINS on line N — outside it, at sibling depth. To append inside a block, use `INS.POST`.
+`INS.HEAD:` — insert the body rows at the very start of the file.
+`INS.TAIL:` — insert the body rows at the very end of the file.
+Single line: `SWAP N..N:` / `DEL N`. The range is the ORIGINAL lines you touch; body length is irrelevant (replacing 1 line with 10 is still `SWAP N..N:`).
 </ops>
 
 <body-rows>
@@ -27,18 +27,18 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - Line numbers and the `[PATH#TAG]` header come from your latest `read`/`search` (`LINE:TEXT` rows).
 - Numbers refer to the ORIGINAL file; they do not shift as hunks apply.
 - They die with the call: every applied edit mints a fresh `#TAG` and renumbers — anchor the next edit on the edit response or a fresh `read`.
-- Touch only lines you literally saw as `LINE:TEXT`; the tag certifies the snapshot, not your knowledge of it.
-- Elided regions (`…`) are UNSEEN — never place or span a hunk across one; `read` it first.
+- Touch only lines your latest `read`/`search` literally displayed as `LINE:TEXT`; the tag certifies the snapshot, not your memory of it. A hunk anchored on a line you never displayed is REJECTED — re-`read` those exact lines first. (Seeing a line ≠ it holding the code you mean: confirm the numbers map to the construct you intend, especially far from your last-read window.)
+- Elided regions are UNSEEN: `…`/`..` markers and a collapsed `N-M:` summary row (only boundary lines N and M were shown) hide their interior. NEVER place or span a hunk inside one — `read` the range first.
 - Never start or end a range mid-expression or mid-block.
 - Indent body rows exactly for the depth they should live at.
 - On a stale-tag rejection or any surprising result: STOP and re-`read` before further edits.
 - One hunk per range; the body is the final content, never an old/new pair.
 - Ranges cover ONLY lines whose content changes. Never widen over unchanged lines — a stale wide range shreds everything it spans.
-- Whole construct → `replace block N` (tree-sitter resolves the end); lines inside it → `replace N..M`.
-- `replace block N` resolves EXACTLY the node at N. Leading decorators/attributes/doc-comments are separate nodes: point N at the FIRST decorator to sweep both; standalone line-comments are never swept — use `replace N..M`.
-- `insert after block N`: N is the opener, never the closer or last visible line; saw the closer? Use plain `insert after M:`.
+- Whole construct → `SWAP.BLK N` (tree-sitter resolves the end); lines inside it → `SWAP N..M`.
+- `SWAP.BLK N` resolves EXACTLY the node at N. Leading decorators/attributes/doc-comments are separate nodes: point N at the FIRST decorator to sweep both; standalone line-comments are never swept — use `SWAP N..M`.
+- Block ops (`SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST`) anchor the OPENING line of a MULTI-LINE construct — never its closer, its last line, or a bare statement inside it. Anchoring a single statement resolves to ONE line and is REJECTED: use the plain op (`SWAP N..N` / `DEL N` / `INS.POST N`) for one line, or point N at the real opener. Saw the closer? Use plain `INS.POST M:`.
 - Non-adjacent changes = separate hunks; untouched lines stay out of every range.
-- Pure additions use `insert`, never a widened `replace` — retyped keepers are exactly what gets dropped.
+- Pure additions use `INS.PRE` / `INS.POST` / `INS.HEAD` / `INS.TAIL`, never a widened `SWAP` — retyped keepers are exactly what gets dropped. A multi-line `SWAP` whose body restates the line just outside the range is auto-dropped as an off-by-one keeper (with a warning), but issue the payload as the final content for the range only and never lean on the repair.
 - NEVER format/restyle code with this tool; run the project formatter instead.
 </rules>
 
@@ -55,14 +55,14 @@ Original (the exact shape `read` returns):
 Insert a guard after line 1:
 ```
 [greet.py#A1B2]
-insert after 1:
+INS.POST 1:
 +    if not name: name = "stranger"
 ```
 
 Replace line 2 with two lines:
 ```
 [greet.py#A1B2]
-replace 2..2:
+SWAP 2..2:
 +    greeting = "Hi"
 +    msg = f"{greeting}, {name}"
 ```
@@ -70,30 +70,30 @@ replace 2..2:
 Delete line 3:
 ```
 [greet.py#A1B2]
-delete 3
+DEL 3
 ```
 
 Add a header and trailer:
 ```
 [greet.py#A1B2]
-insert head:
+INS.HEAD:
 +# generated header
-insert tail:
+INS.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:
+Replace the whole `greet` function block — `SWAP.BLK 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:
+SWAP.BLK 1:
 +def greet(name):
 +    print(f"Hello, {name}")
 ```
 
-A decorator or doc-comment is a SEPARATE block — `replace block` on the `def`/`fn` line keeps it. Point N at the decorator to take both; here line 1 is `@cache`, so anchoring on the `def` (line 2) would resolve only the function and orphan `@cache`:
+A decorator or doc-comment is a SEPARATE block — `SWAP.BLK` on the `def`/`fn` line keeps it. Point N at the decorator to take both; here line 1 is `@cache`, so anchoring on the `def` (line 2) would resolve only the function and orphan `@cache`:
 ```
 [svc.py#C3D4]
-replace block 1:
+SWAP.BLK 1:
 +@cache
 +def load(key):
 +    return store[key]
@@ -101,43 +101,43 @@ replace block 1:
 </example>
 
 <anti-patterns>
-# WRONG — empty `replace` to delete. RIGHT: delete 4
-replace 4..4:
+# WRONG — empty `SWAP` to delete. RIGHT: DEL 4
+SWAP 4..4:
 
-# WRONG — range describes post-edit size. RIGHT: replace 1..1: (body length is irrelevant)
-replace 1..2:
+# WRONG — range describes post-edit size. RIGHT: SWAP 1..1: (body length is irrelevant)
+SWAP 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:
+SWAP 3..3:
     msg = "Hello, " + name
 -   print(msg)
 +   return msg
 # RIGHT
-replace 3..3:
+SWAP 3..3:
 +   return msg
 
-# WRONG — a pure insertion done as a widened `replace`: you only want to add one line after 2,
+# WRONG — a pure insertion done as a widened `SWAP`: you only want to add one line after 2,
 # but you replace 2..4, retype the keepers in the body, and drop one (here line 4, `greet("world")`).
-replace 2..4:
+SWAP 2..4:
 +    msg = "Hello, " + name
 +    extra = compute(name)
 +    print(msg)
 # RIGHT — touch nothing you keep; the new line is the whole body.
-insert after 2:
+INS.POST 2:
 +    extra = compute(name)
 
-# WRONG — `insert after block N:` anchored on a closing delimiter / last visible line. RIGHT: plain `insert after M:`
-insert after block 3:
+# WRONG — `INS.BLK.POST N:` anchored on a closing delimiter / last visible line. RIGHT: plain `INS.POST M:`
+INS.BLK.POST 3:
 +after()
 # RIGHT
-insert after 3:
+INS.POST 3:
 +after()
 </anti-patterns>
 
 <critical>
 If you remember nothing else:
 1. RE-GROUND AFTER EVERY EDIT. Every apply mints a fresh `#TAG` and renumbers — take the next edit's numbers from the edit response or a fresh `read`. Stale tag or surprise? STOP, re-`read`.
-2. RANGES ARE TIGHT. Cover only lines that change; a stale wide range shreds everything it spans. Whole construct → `replace block N`.
+2. RANGES ARE TIGHT. Cover only lines that change; a stale wide range shreds everything it spans. Whole construct → `SWAP.BLK N`.
 3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows; never `-old`/context lines. The range does the deleting.
 </critical>

package/src/snapshots.ts

@@ -36,6 +36,15 @@ export interface Snapshot {
 	readonly hash: string;
 	/** Timestamp (ms since epoch) the version was recorded. */
 	recordedAt: number;
+	/**
+	 * 1-indexed file lines a producer (read/search) actually *displayed* under
+	 * this tag. A partial read (range, or a structural summary that collapsed
+	 * bodies) leaves this sparse; a whole-file read fills every line. Multiple
+	 * reads of the same content union into one set. `undefined` means "no
+	 * provenance recorded" — the patcher then skips the seen-line check and
+	 * applies as before. Mutated in place as more of the same content is read.
+	 */
+	seenLines?: Set<number>;
 }
 
 /**
@@ -50,8 +59,20 @@ export abstract class SnapshotStore {
 	/** Recorded version for `path` whose tag equals `hash`, or `null`. */
 	abstract byHash(path: string, hash: string): Snapshot | null;
 
-	/** Record the full normalized text of `path` and return its content tag. */
-	abstract record(path: string, fullText: string): string;
+	/**
+	 * Record the full normalized text of `path` and return its content tag.
+	 * `seenLines` (optional) are the 1-indexed lines the producer displayed;
+	 * they merge into {@link Snapshot.seenLines} across reads of identical text.
+	 */
+	abstract record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+
+	/**
+	 * Merge `lines` into the {@link Snapshot.seenLines} of the version whose tag
+	 * equals `hash`. No-op when no such version is retained (the content aged
+	 * out or was overwritten). Lets producers attach displayed lines after the
+	 * tag was already minted (the body is formatted after the hash is computed).
+	 */
+	abstract recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
 
 	/** Drop the version history for a single path. */
 	abstract invalidate(path: string): void;
@@ -65,6 +86,13 @@ const DEFAULT_MAX_VERSIONS_PER_PATH = 4;
 /** Global ceiling on retained snapshot text across all paths (UTF-16 code units). */
 const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 
+/** Union `lines` into `snapshot.seenLines`, lazily creating the set. */
+function mergeSeenLines(snapshot: Snapshot, lines: Iterable<number> | undefined): void {
+	if (lines === undefined) return;
+	if (snapshot.seenLines === undefined) snapshot.seenLines = new Set<number>();
+	for (const line of lines) snapshot.seenLines.add(line);
+}
+
 export interface InMemorySnapshotStoreOptions {
 	/** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
 	maxPaths?: number;
@@ -114,15 +142,17 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		return history?.find(version => version.hash === hash) ?? null;
 	}
 
-	record(path: string, fullText: string): string {
+	record(path: string, fullText: string, seenLines?: Iterable<number>): string {
 		const hash = computeFileHash(fullText);
 		// `get` refreshes LRU recency for `path`.
 		const history = this.#versions.get(path) ?? [];
 		const existing = history.find(version => version.hash === hash);
 		if (existing) {
 			// Same content state observed again: refresh recency and promote to
-			// head (it is the current file content), then reuse the tag.
+			// head (it is the current file content), then reuse the tag. Union any
+			// newly-displayed lines so re-reading more of the file widens coverage.
 			existing.recordedAt = Date.now();
+			mergeSeenLines(existing, seenLines);
 			if (history[0] !== existing) {
 				this.#versions.set(path, [existing, ...history.filter(version => version !== existing)]);
 			}
@@ -130,10 +160,16 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		}
 
 		const snapshot: Snapshot = { path, text: fullText, hash, recordedAt: Date.now() };
+		mergeSeenLines(snapshot, seenLines);
 		this.#versions.set(path, [snapshot, ...history].slice(0, this.#maxVersionsPerPath));
 		return hash;
 	}
 
+	recordSeenLines(path: string, hash: string, lines: Iterable<number>): void {
+		const version = this.#versions.get(path)?.find(snapshot => snapshot.hash === hash);
+		if (version) mergeSeenLines(version, lines);
+	}
+
 	invalidate(path: string): void {
 		this.#versions.delete(path);
 	}

package/src/tokenizer.ts

@@ -10,7 +10,7 @@
  */
 import {
 	describeAnchorExamples,
-	HL_BLOCK_KEYWORD,
+	HL_DELETE_BLOCK_KEYWORD,
 	HL_DELETE_KEYWORD,
 	HL_FILE_HASH_LENGTH,
 	HL_FILE_HASH_SEP,
@@ -18,11 +18,13 @@ import {
 	HL_FILE_SUFFIX,
 	HL_HEADER_COLON,
 	HL_INSERT_AFTER,
+	HL_INSERT_AFTER_BLOCK_KEYWORD,
 	HL_INSERT_BEFORE,
 	HL_INSERT_HEAD,
 	HL_INSERT_KEYWORD,
 	HL_INSERT_TAIL,
 	HL_PAYLOAD_REPLACE,
+	HL_REPLACE_BLOCK_KEYWORD,
 	HL_REPLACE_KEYWORD,
 } from "./format";
 import { ABORT_MARKER, BEGIN_PATCH_MARKER, END_PATCH_MARKER } from "./messages";
@@ -218,7 +220,7 @@ function scanKeyword(line: string, index: number, end: number, keyword: string):
 	const next = index + keyword.length;
 	if (next < end) {
 		const code = line.charCodeAt(next);
-		if (!isWhitespaceCode(code) && code !== CHAR_COLON) return null;
+		if (!isWhitespaceCode(code) && code !== CHAR_COLON && code !== CHAR_DOT) return null;
 	}
 	return next;
 }
@@ -229,7 +231,8 @@ function consumeOptionalColon(line: string, index: number, end: number): number
 }
 
 function scanInsertTarget(line: string, index: number, end: number): TargetScan | null {
-	const cursor = skipWhitespace(line, index, end);
+	if (index >= end || line.charCodeAt(index) !== CHAR_DOT) return null;
+	const cursor = skipWhitespace(line, index + 1, end);
 	const beforeEnd = scanKeyword(line, cursor, end, HL_INSERT_BEFORE);
 	if (beforeEnd !== null) {
 		const anchor = scanLineNumber(line, skipWhitespace(line, beforeEnd, end), end);
@@ -239,16 +242,6 @@ function scanInsertTarget(line: string, index: number, end: number): TargetScan
 	}
 	const afterEnd = scanKeyword(line, cursor, end, HL_INSERT_AFTER);
 	if (afterEnd !== null) {
-		// `insert after block N:` — resolve N to a tree-sitter block range at
-		// apply time and insert after its last line. Try the `block` sub-keyword
-		// before falling back to a literal `insert after N:` anchor.
-		const blockEnd = scanKeyword(line, skipWhitespace(line, afterEnd, end), end, HL_BLOCK_KEYWORD);
-		if (blockEnd !== null) {
-			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
-			if (anchor === null) return null;
-			const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);
-			return { target: { kind: "insert_after_block", anchor: { line: anchor.line } }, nextIndex };
-		}
 		const anchor = scanLineNumber(line, skipWhitespace(line, afterEnd, end), end);
 		if (anchor === null) return null;
 		const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);
@@ -263,20 +256,19 @@ function scanInsertTarget(line: string, index: number, end: number): TargetScan
 
 function scanHunkAnchor(line: string, start: number, end: number): TargetScan | null {
 	const cursor = skipWhitespace(line, start, end);
+
+	// `replace_block N:` — resolve N to a tree-sitter block range at apply time.
+	const replaceBlockEnd = scanKeyword(line, cursor, end, HL_REPLACE_BLOCK_KEYWORD);
+	if (replaceBlockEnd !== null) {
+		const anchor = scanLineNumber(line, skipWhitespace(line, replaceBlockEnd, end), end);
+		if (anchor === null) return null;
+		return {
+			target: { kind: "block", anchor: { line: anchor.line } },
+			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
+		};
+	}
 	const replaceEnd = scanKeyword(line, cursor, end, HL_REPLACE_KEYWORD);
 	if (replaceEnd !== null) {
-		// `replace block N:` — resolve N to a tree-sitter block range at apply
-		// time. Try the `block` sub-keyword before falling back to a literal
-		// `replace N..M:` range.
-		const blockEnd = scanKeyword(line, skipWhitespace(line, replaceEnd, end), end, HL_BLOCK_KEYWORD);
-		if (blockEnd !== null) {
-			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
-			if (anchor === null) return null;
-			return {
-				target: { kind: "block", anchor: { line: anchor.line } },
-				nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
-			};
-		}
 		const range = scanHeaderRange(line, replaceEnd, end, true);
 		if (range === null) return null;
 		return {
@@ -284,25 +276,36 @@ function scanHunkAnchor(line: string, start: number, end: number): TargetScan |
 			nextIndex: consumeOptionalColon(line, range.nextIndex, end),
 		};
 	}
+	// `delete_block N` — resolve N to a tree-sitter block range at apply time
+	// and delete its whole span. Like `delete N..M`, it takes no body and no
+	// trailing colon.
+	const deleteBlockEnd = scanKeyword(line, cursor, end, HL_DELETE_BLOCK_KEYWORD);
+	if (deleteBlockEnd !== null) {
+		const anchor = scanLineNumber(line, skipWhitespace(line, deleteBlockEnd, end), end);
+		if (anchor === null) return null;
+		const next = skipWhitespace(line, anchor.nextIndex, end);
+		if (next < end && line.charCodeAt(next) === CHAR_COLON) return null;
+		return { target: { kind: "delete_block", anchor: { line: anchor.line } }, nextIndex: next };
+	}
 	const deleteEnd = scanKeyword(line, cursor, end, HL_DELETE_KEYWORD);
 	if (deleteEnd !== null) {
-		// `delete block N` — resolve N to a tree-sitter block range at apply
-		// time and delete its whole span. Like `delete N..M`, it takes no body
-		// and no trailing colon.
-		const blockEnd = scanKeyword(line, skipWhitespace(line, deleteEnd, end), end, HL_BLOCK_KEYWORD);
-		if (blockEnd !== null) {
-			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
-			if (anchor === null) return null;
-			const next = skipWhitespace(line, anchor.nextIndex, end);
-			if (next < end && line.charCodeAt(next) === CHAR_COLON) return null;
-			return { target: { kind: "delete_block", anchor: { line: anchor.line } }, nextIndex: next };
-		}
 		const range = scanHeaderRange(line, deleteEnd, end, true);
 		if (range === null) return null;
 		const next = skipWhitespace(line, range.nextIndex, end);
 		if (next < end && line.charCodeAt(next) === CHAR_COLON) return null;
 		return { target: { kind: "delete", range: range.range }, nextIndex: next };
 	}
+	// `insert_after_block N:` — insert after the last line of the tree-sitter
+	// block at N.
+	const insertAfterBlockEnd = scanKeyword(line, cursor, end, HL_INSERT_AFTER_BLOCK_KEYWORD);
+	if (insertAfterBlockEnd !== null) {
+		const anchor = scanLineNumber(line, skipWhitespace(line, insertAfterBlockEnd, end), end);
+		if (anchor === null) return null;
+		return {
+			target: { kind: "insert_after_block", anchor: { line: anchor.line } },
+			nextIndex: consumeOptionalColon(line, anchor.nextIndex, end),
+		};
+	}
 	const insertEnd = scanKeyword(line, cursor, end, HL_INSERT_KEYWORD);
 	if (insertEnd !== null) return scanInsertTarget(line, insertEnd, end);
 	return null;

package/src/types.ts

@@ -32,7 +32,7 @@ export type Edit =
 			index: number;
 			mode?: "replacement";
 			/**
-			 * Present on inserts lowered from `insert after block N:`: the
+			 * Present on inserts lowered from `insert_after_block N:`: the
 			 * resolved block's first line. Lets the applier slide a body that
 			 * claims a depth inside the block back across the block's trailing
 			 * closer lines (never above this line).
@@ -42,13 +42,13 @@ export type Edit =
 	| { kind: "delete"; anchor: Anchor; lineNum: number; index: number; oldAssertion?: string }
 	| {
 			/**
-			 * Deferred block edit (`replace block N:` / `delete block N` /
-			 * `insert after block N:`). The exact line span is unknown at parse
+			 * Deferred block edit (`replace_block N:` / `delete_block N` /
+			 * `insert_after_block N:`). The exact line span is unknown at parse
 			 * time — it is computed by {@link resolveBlockEdits} once file text +
 			 * path (→ language) are available, then expanded into concrete edits:
-			 * a non-empty `payloads` without `mode` (from `replace block`) becomes
+			 * a non-empty `payloads` without `mode` (from `replace_block`) becomes
 			 * the same `replacement` inserts + deletes that `replace start..end:`
-			 * produces; an empty `payloads` (from `delete block`) becomes a pure
+			 * produces; an empty `payloads` (from `delete_block`) becomes a pure
 			 * range deletion; `mode: "insert_after"` becomes plain `after_anchor`
 			 * inserts at the block's last line. `applyEdits` never sees this
 			 * variant.
@@ -70,7 +70,7 @@ export interface ApplyResult {
 	/** Diagnostic warnings collected by the parser, patcher, or recovery. */
 	warnings?: string[];
 	/**
-	 * Resolved spans for each `replace block`/`delete block` op in this apply,
+	 * Resolved spans for each `replace_block`/`delete_block` op in this apply,
 	 * in patch order. Present only when the apply matched the tagged content
 	 * (the common no-drift path), so the line numbers line up with what the
 	 * caller read. Absent when there were no block ops.
@@ -122,7 +122,7 @@ export interface CompactDiffOptions {
 }
 
 /**
- * Resolved 1-indexed inclusive line span of a `replace block N:` target.
+ * Resolved 1-indexed inclusive line span of a `replace_block N:` target.
  */
 export interface BlockSpan {
 	/** First line of the block (1-indexed, inclusive). */
@@ -132,7 +132,7 @@ export interface BlockSpan {
 }
 
 /**
- * One `replace block N:` / `delete block N` / `insert after block N:` anchor
+ * One `replace_block N:` / `delete_block N` / `insert_after_block N:` anchor
  * resolved to its concrete line span. Surfaced on {@link ApplyResult} so the
  * host can echo "block N → lines start..end" and let the model catch a wrong
  * opener — e.g. a decorator or doc-comment that sits in a separate node
@@ -149,7 +149,7 @@ export interface BlockResolution {
 	op: "replace" | "delete" | "insert_after";
 }
 
-/** Request handed to a {@link BlockResolver} to resolve one `replace block N:` anchor. */
+/** Request handed to a {@link BlockResolver} to resolve one `replace_block N:` anchor. */
 export interface BlockResolverRequest {
 	/** Target file path (used to infer language by extension). */
 	path: string;
@@ -160,7 +160,7 @@ export interface BlockResolverRequest {
 }
 
 /**
- * Resolves a `replace block N:` anchor to the line span of the syntactic block
+ * Resolves a `replace_block N:` anchor to the line span of the syntactic block
  * that begins on line N. Returns `null` when no block can be resolved
  * (unrecognized language, blank/out-of-range line, no node begins there, or the
  * resolved subtree has a syntax error). Pure seam: the hashline core declares