@oh-my-pi/hashline 15.11.8 → 15.12.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [15.12.0] - 2026-06-12
+
+### Changed
+
+- Condensed all parser/applier/patcher error and warning messages: shorter wording, same diagnostic anchors (op names, line numbers, suggested fallback forms)
+
 ## [15.11.4] - 2026-06-12
 
 ### Added

package/dist/types/block.d.ts

@@ -1,11 +1,13 @@
 import type { BlockResolution, BlockResolver, Edit } from "./types";
 export interface ResolveBlockEditsOptions {
     /**
-     * How to handle a block edit that cannot be resolved (missing resolver or a
-     * `null` span). `"throw"` (default) raises a `blockUnresolvedMessage` error —
-     * used by the authoritative apply + final preview paths. `"drop"` silently
-     * skips the edit — used by the streaming preview, where a half-written file
-     * or transient parse error must not throw.
+     * How to handle a replace/delete block edit that cannot be resolved
+     * (missing resolver or a `null` span). `"throw"` (default) raises a
+     * `blockUnresolvedMessage` error — used by the authoritative apply + final
+     * preview paths. `"drop"` silently skips the edit — used by the streaming
+     * preview, where a half-written file or transient parse error must not
+     * throw. Unresolvable `insert after block N:` edits never reach this: they
+     * are lowered to plain `insert after N:` with a warning.
      */
     onUnresolved?: "throw" | "drop";
     /**
@@ -16,9 +18,9 @@ export interface ResolveBlockEditsOptions {
      */
     onResolved?: (resolution: BlockResolution) => void;
     /**
-     * Invoked once per diagnostic produced while resolving — currently only the
-     * closer-anchor lowering of `insert after block N:`. Hosts should surface
-     * these on the apply result's `warnings`.
+     * Invoked once per diagnostic produced while resolving — currently the
+     * `insert after block N:` lowerings (closer anchor or unresolvable block).
+     * Hosts should surface these on the apply result's `warnings`.
      */
     onWarning?: (message: string) => void;
 }

package/dist/types/messages.d.ts

@@ -1,117 +1,98 @@
-/**
- * Centralized error and warning text emitted by the hashline parser, applier,
- * and patcher. Consolidating these as named constants makes them easy to
- * audit and keeps wording stable across the rendering paths that surface
- * them.
- */
+/** Centralized error/warning text for the hashline parser, applier, and patcher. */
 /** Lines of context shown either side of a hash mismatch. */
 export declare const MISMATCH_CONTEXT = 2;
 /**
- * Render numbered `LINE:TEXT` context rows around `anchorLines`
- * (±{@link MISMATCH_CONTEXT} lines each), `*`-marking the anchored lines and
- * separating non-adjacent runs with `...`. Out-of-range anchors contribute no
- * rows; returns an empty array when every anchor is out of range.
+ * Numbered `LINE:TEXT` rows around `anchorLines` (±{@link MISMATCH_CONTEXT}),
+ * `*`-marking anchors, `...` between non-adjacent runs. Out-of-range anchors
+ * contribute no rows.
  */
 export declare function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[];
-/** Optional patch envelope start marker; silently consumed when present. */
+/** Optional patch envelope start marker; silently consumed. */
 export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
-/** Optional patch envelope end marker; terminates parsing when encountered. */
+/** Optional patch envelope end marker; terminates parsing. */
 export declare const END_PATCH_MARKER = "*** End Patch";
 /**
- * Recovery sentinel emitted by an agent loop when a contaminated tool-call
- * stream is truncated mid-call. Behaves like {@link END_PATCH_MARKER} for
- * parsing — terminates the line loop — and does not surface a warning.
+ * Truncation sentinel emitted by an agent loop mid-call. Ends parsing like
+ * {@link END_PATCH_MARKER}, without a warning.
  */
 export declare const ABORT_MARKER = "*** Abort";
-/** Warning text appended when two consecutive hunks target the exact same concrete range. */
-export declare const REPLACE_PAIR_COALESCED_WARNING = "Detected two identical-range hashline hunks; kept only the second hunk. Issue ONE `replace N..M:` hunk per range \u2014 payload is the final desired content, never both old and new.";
-/** Warning text appended when an empty bodyless hunk is followed by an overlapping concrete hunk. */
-export declare const REPLACE_PAIR_COALESCED_OVERLAP_WARNING = "Detected an overlapping bare hashline hunk immediately followed by a concrete hunk; dropped the earlier bare hunk. Issue ONE `replace N..M:` hunk per range \u2014 payload is the final desired content, never both old and new.";
-/** Warning text appended when bare body rows are auto-converted to literal rows. */
-export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines; pasting raw code as payload is not a portable shape.";
-/** Error text emitted when a hunk body contains a unified-diff-style `-` row. */
-export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; hashline ranges already name the lines being changed. To insert a literal line starting with `-`, write `+-\u2026`.";
-/** Error text emitted when a replace hunk has no body. */
+/** Two consecutive hunks targeted the exact same concrete range. */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the same range; kept only the second. One `replace N..M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Bare bodyless hunk followed by an overlapping concrete hunk. */
+export declare const REPLACE_PAIR_COALESCED_OVERLAP_WARNING = "Dropped a bare hunk overlapped by the concrete hunk after it. One `replace N..M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Bare body rows auto-converted to literal `+` rows. */
+export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
+/** Unified-diff-style `-` row in a hunk body. */
+export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For a literal `-` line, write `+-\u2026`.";
+/** Replace hunk with no body. */
 export declare const EMPTY_REPLACE = "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
-/** Error text emitted when a `replace block N:` hunk has no body. */
-export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+/** `replace block N:` hunk with no body. */
+export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete block N`.";
 /**
- * Error text emitted when a block-anchored op cannot be resolved to a
- * syntactic block (unrecognized language, blank/out-of-range line, no node
- * begins on line N such as a lone closing delimiter, or the resolved block has
- * a syntax error). Names the offending line, steers back to an explicit
- * concrete-line form, and — when `fileLines` is provided — appends a
- * {@link formatAnchoredContext} preview of the file around the anchor line.
+ * Block-anchored replace/delete could not resolve to a syntactic block
+ * (unsupported language, blank/out-of-range line, no node beginning on N, or
+ * parse error). Appends a {@link formatAnchoredContext} preview when
+ * `fileLines` is given. `insert after block N:` never reaches this — it is
+ * lowered to plain `insert after N:` instead (see
+ * {@link insertAfterBlockUnresolvedLoweredWarning}).
  */
-export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete" | "insert_after", fileLines?: readonly string[]): string;
+export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete", fileLines?: readonly string[]): string;
+/** Block-anchored edit reached a path with no {@link BlockResolver} wired in — a host-configuration bug. */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`replace block`/`delete block`/`insert after block` are not available here (no block resolver configured). Use a concrete line range.";
 /**
- * Error text emitted when a block-anchored edit reaches a code path that
- * has no {@link BlockResolver} wired in. Indicates a host-configuration bug
- * rather than authored-input error.
+ * `insert after block N:` anchored on a closing-delimiter line, lowered to
+ * plain `insert after N:` — the closer ends a block, and inserting after it
+ * is exactly what the plain form does.
  */
-export declare const BLOCK_RESOLVER_UNAVAILABLE = "Block-anchored ops (`replace block N:`, `delete block N`, `insert after block N:`) are not available here (no tree-sitter block resolver is configured). Use a concrete line range instead.";
+export declare function insertAfterBlockCloserLoweredWarning(line: number): string;
 /**
- * Warning emitted when an `insert after block N:` anchored on a pure
- * closing-delimiter line is lowered to plain `insert after N:`. No block
- * begins on a closer, but the closer IS the end of one — and inserting after
- * the end of that block is exactly what the plain form does.
+ * `insert after block N:` anchor unresolvable (unsupported language, blank
+ * line, parse error, or no resolver), lowered to plain `insert after N:` —
+ * applying with a warning beats failing the patch.
  */
-export declare function insertAfterBlockCloserLoweredWarning(line: number): string;
+export declare function insertAfterBlockUnresolvedLoweredWarning(line: number): string;
 /**
- * Internal invariant error: `applyEdits` received an unresolved `replace block
- * N:` edit. Block edits must be expanded by `resolveBlockEdits` before reaching
- * the applier; hitting this is a wiring bug, not authored-input error.
+ * Internal invariant: `applyEdits` received an unresolved `replace block N:`
+ * edit; `resolveBlockEdits` must run first. Wiring bug, not authored input.
  */
 export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).";
-/** Error text emitted when a delete hunk receives a body row. */
+/** Delete hunk received a body row. */
 export declare const DELETE_TAKES_NO_BODY = "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
-/** Error text emitted when a `delete block N` hunk receives a body row. */
-export declare const DELETE_BLOCK_TAKES_NO_BODY = "`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
-/** Error text emitted when an insert hunk has no body. */
+/** `delete block N` hunk received a body row. */
+export declare const DELETE_BLOCK_TAKES_NO_BODY = "`delete block N` does not take body rows. Remove the body, or use `replace block N:`.";
+/** Insert hunk with no body. */
 export declare const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
 /**
- * Warning emitted when an `insert after` edit's body rows are indented
- * shallower than the anchor line and the landing point was slid forward past
- * the structural closer lines that follow. The body's indentation names the
- * depth the author wants the new lines to sit at; anchoring inside a deeper
- * construct is the common "insert after the block, anchored on the last line
- * I read" mistake.
+ * `insert after` body indented shallower than the anchor: the landing slid
+ * forward past trailing closer lines — the common "anchored on the last line
+ * I read instead of after the block" mistake.
  */
 export declare function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string;
 /**
- * Warning emitted when an `insert after block N:` body is indented deeper
- * than the block's closing line and the landing was pulled back inside the
- * block. `insert after block` places content AFTER the block at sibling
- * depth; a deeper body almost always means "append inside the block's body"
- * — the misuse this corrects.
+ * `insert after block N:` body indented deeper than the block's closer: the
+ * landing was pulled inside the block — a deeper body almost always means
+ * "append inside the block's body".
  */
 export declare function blockInsertLandingShiftWarning(blockStart: number, closerLine: number, landingLine: number): string;
-/** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
+/** `Recovery`: an external write matched a cached snapshot. */
 export declare const RECOVERY_EXTERNAL_WARNING = "Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
-/** Warning text emitted by `Recovery` when a prior in-session edit advanced the hash. */
-export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale file hash using an earlier in-session snapshot (the file hash advanced after a prior edit in this session).";
+/** `Recovery`: a prior in-session edit advanced the hash. */
+export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale file hash using an earlier in-session snapshot (a prior edit in this session advanced the hash).";
 /**
- * Warning text emitted by `Recovery` when the session-chain replay
- * fast-path was taken. Distinct from {@link RECOVERY_SESSION_CHAIN_WARNING}
- * because replay is the less-certain mode: the structured-patch 3-way
- * merge refused, the anchor-content gate passed, but a coincidental
- * insert+delete pair earlier in the chain could still leave an anchor's
- * line number pointing at a duplicated row. Surface the hedge so the
- * model verifies before continuing.
+ * `Recovery`: session-chain replay fast-path. Less certain than
+ * {@link RECOVERY_SESSION_CHAIN_WARNING} — the 3-way merge refused, the
+ * anchor-content gate passed, but a coincidental insert+delete earlier in
+ * the chain could still misplace an anchor — hence the verify hedge.
  */
-export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content \u2014 your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
 /**
- * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
- * existing file whose snapshot tag is stale (the file drifted since the read).
- * Head/tail insert position is content-independent — "start"/"end" cannot move
- * with drift — so this is non-fatal: the edit applies onto the live content and
- * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
+ * Head/tail position is content-independent, so drift is non-fatal: apply
+ * onto live content and warn instead of hard-failing.
  */
-export declare const HEADTAIL_DRIFT_WARNING = "Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected \u2014 but re-read if the drift was unexpected.";
+export declare const HEADTAIL_DRIFT_WARNING = "Applied the `insert head:`/`insert tail:` edit despite a stale snapshot tag (file changed since your read) \u2014 head/tail position is content-independent. Re-read if the drift was unexpected.";
 /**
- * Error text emitted when a hashline section omits the mandatory snapshot tag.
- * The tag is REQUIRED on every section, enforced identically by the apply path
- * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
- * this single builder to stay in lockstep.
+ * Section omitted the mandatory snapshot tag. Shared by the apply
+ * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
  */
 export declare function missingSnapshotTagMessage(sectionPath: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.11.8",
+	"version": "15.12.1",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

package/src/block.ts

@@ -13,16 +13,23 @@
  * ever see resolved edits.
  */
 import { STRUCTURAL_CLOSER_RE } from "./apply";
-import { BLOCK_RESOLVER_UNAVAILABLE, blockUnresolvedMessage, insertAfterBlockCloserLoweredWarning } from "./messages";
+import {
+	BLOCK_RESOLVER_UNAVAILABLE,
+	blockUnresolvedMessage,
+	insertAfterBlockCloserLoweredWarning,
+	insertAfterBlockUnresolvedLoweredWarning,
+} from "./messages";
 import type { BlockResolution, BlockResolver, Cursor, Edit } from "./types";
 
 export interface ResolveBlockEditsOptions {
 	/**
-	 * How to handle a block edit that cannot be resolved (missing resolver or a
-	 * `null` span). `"throw"` (default) raises a `blockUnresolvedMessage` error —
-	 * used by the authoritative apply + final preview paths. `"drop"` silently
-	 * skips the edit — used by the streaming preview, where a half-written file
-	 * or transient parse error must not throw.
+	 * How to handle a replace/delete block edit that cannot be resolved
+	 * (missing resolver or a `null` span). `"throw"` (default) raises a
+	 * `blockUnresolvedMessage` error — used by the authoritative apply + final
+	 * preview paths. `"drop"` silently skips the edit — used by the streaming
+	 * preview, where a half-written file or transient parse error must not
+	 * throw. Unresolvable `insert after block N:` edits never reach this: they
+	 * are lowered to plain `insert after N:` with a warning.
 	 */
 	onUnresolved?: "throw" | "drop";
 	/**
@@ -33,9 +40,9 @@ export interface ResolveBlockEditsOptions {
 	 */
 	onResolved?: (resolution: BlockResolution) => void;
 	/**
-	 * Invoked once per diagnostic produced while resolving — currently only the
-	 * closer-anchor lowering of `insert after block N:`. Hosts should surface
-	 * these on the apply result's `warnings`.
+	 * Invoked once per diagnostic produced while resolving — currently the
+	 * `insert after block N:` lowerings (closer anchor or unresolvable block).
+	 * Hosts should surface these on the apply result's `warnings`.
 	 */
 	onWarning?: (message: string) => void;
 }
@@ -74,21 +81,27 @@ export function resolveBlockEdits(
 		const op = edit.mode === "insert_after" ? "insert_after" : edit.payloads.length === 0 ? "delete" : "replace";
 		const span = resolver ? resolver({ path, text, line: edit.anchor.line }) : null;
 		if (span === null) {
-			// `insert after block N` anchored on a pure closing-delimiter line:
-			// no block begins there, but line N IS the end of one — and "after
-			// the end of the block" is exactly plain `insert after N:`. Lower it
-			// instead of failing the patch; warn so the author learns the
-			// opener-only rule.
-			if (op === "insert_after" && resolver) {
+			// `insert after block N:` never fails the patch — lower it to plain
+			// `insert after N:` with a warning instead. Two flavors:
+			// - anchored on a pure closing-delimiter line: no block begins
+			//   there, but line N IS the end of one, and "after the end of the
+			//   block" is exactly the plain form — warn with the opener rule.
+			// - otherwise (unsupported language, blank line, unparsable block,
+			//   or no resolver wired): "after the block at N" degrades to
+			//   "after line N" — warn to verify the landing line.
+			if (op === "insert_after") {
 				const anchorText = text.split("\n")[edit.anchor.line - 1];
-				if (anchorText !== undefined && STRUCTURAL_CLOSER_RE.test(anchorText)) {
-					options.onWarning?.(insertAfterBlockCloserLoweredWarning(edit.anchor.line));
-					for (const payload of edit.payloads) {
-						const cursor: Cursor = { kind: "after_anchor", anchor: { line: edit.anchor.line } };
-						resolved.push({ kind: "insert", cursor, text: payload, lineNum: edit.lineNum, index: synthIndex++ });
-					}
-					continue;
+				const isCloser = anchorText !== undefined && STRUCTURAL_CLOSER_RE.test(anchorText);
+				options.onWarning?.(
+					isCloser
+						? insertAfterBlockCloserLoweredWarning(edit.anchor.line)
+						: insertAfterBlockUnresolvedLoweredWarning(edit.anchor.line),
+				);
+				for (const payload of edit.payloads) {
+					const cursor: Cursor = { kind: "after_anchor", anchor: { line: edit.anchor.line } };
+					resolved.push({ kind: "insert", cursor, text: payload, lineNum: edit.lineNum, index: synthIndex++ });
 				}
+				continue;
 			}
 			if (onUnresolved === "drop") continue;
 			throw new Error(

package/src/messages.ts

@@ -1,9 +1,4 @@
-/**
- * Centralized error and warning text emitted by the hashline parser, applier,
- * and patcher. Consolidating these as named constants makes them easy to
- * audit and keeps wording stable across the rendering paths that surface
- * them.
- */
+/** Centralized error/warning text for the hashline parser, applier, and patcher. */
 
 import { formatNumberedLine, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 
@@ -11,10 +6,9 @@ import { formatNumberedLine, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX }
 export const MISMATCH_CONTEXT = 2;
 
 /**
- * Render numbered `LINE:TEXT` context rows around `anchorLines`
- * (±{@link MISMATCH_CONTEXT} lines each), `*`-marking the anchored lines and
- * separating non-adjacent runs with `...`. Out-of-range anchors contribute no
- * rows; returns an empty array when every anchor is out of range.
+ * Numbered `LINE:TEXT` rows around `anchorLines` (±{@link MISMATCH_CONTEXT}),
+ * `*`-marking anchors, `...` between non-adjacent runs. Out-of-range anchors
+ * contribute no rows.
  */
 export function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[] {
 	const displayLines = new Set<number>();
@@ -36,71 +30,59 @@ export function formatAnchoredContext(anchorLines: readonly number[], fileLines:
 	return rows;
 }
 
-/** Optional patch envelope start marker; silently consumed when present. */
+/** Optional patch envelope start marker; silently consumed. */
 export const BEGIN_PATCH_MARKER = "*** Begin Patch";
 
-/** Optional patch envelope end marker; terminates parsing when encountered. */
+/** Optional patch envelope end marker; terminates parsing. */
 export const END_PATCH_MARKER = "*** End Patch";
 
 /**
- * Recovery sentinel emitted by an agent loop when a contaminated tool-call
- * stream is truncated mid-call. Behaves like {@link END_PATCH_MARKER} for
- * parsing — terminates the line loop — and does not surface a warning.
+ * Truncation sentinel emitted by an agent loop mid-call. Ends parsing like
+ * {@link END_PATCH_MARKER}, without a warning.
  */
 export const ABORT_MARKER = "*** Abort";
 
-/** Warning text appended when two consecutive hunks target the exact same concrete range. */
+/** Two consecutive hunks targeted the exact same concrete range. */
 export const REPLACE_PAIR_COALESCED_WARNING =
-	"Detected two identical-range hashline hunks; kept only the second hunk. Issue ONE `replace N..M:` hunk per range — payload is the final desired content, never both old and new.";
+	"Two hunks targeted the same range; kept only the second. One `replace N..M:` hunk per range — the body is the final content, never old+new.";
 
-/** Warning text appended when an empty bodyless hunk is followed by an overlapping concrete hunk. */
+/** Bare bodyless hunk followed by an overlapping concrete hunk. */
 export const REPLACE_PAIR_COALESCED_OVERLAP_WARNING =
-	"Detected an overlapping bare hashline hunk immediately followed by a concrete hunk; dropped the earlier bare hunk. Issue ONE `replace N..M:` hunk per range — payload is the final desired content, never both old and new.";
+	"Dropped a bare hunk overlapped by the concrete hunk after it. One `replace N..M:` hunk per range — the body is the final content, never old+new.";
 
-/** Warning text appended when bare body rows are auto-converted to literal rows. */
+/** Bare body rows auto-converted to literal `+` rows. */
 export const BARE_BODY_AUTO_PIPED_WARNING =
-	"Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines; pasting raw code as payload is not a portable shape.";
+	"Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
 
-/** Error text emitted when a hunk body contains a unified-diff-style `-` row. */
+/** Unified-diff-style `-` row in a hunk body. */
 export const MINUS_ROW_REJECTED =
-	"`-` rows are not valid; hashline ranges already name the lines being changed. To insert a literal line starting with `-`, write `+-…`.";
+	"`-` rows are not valid; the range already names the lines being changed. For a literal `-` line, write `+-…`.";
 
-/** Error text emitted when a replace hunk has no body. */
+/** Replace hunk with no body. */
 export const EMPTY_REPLACE = "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
 
-/** Error text emitted when a `replace block N:` hunk has no body. */
+/** `replace block N:` hunk with no body. */
 export const EMPTY_BLOCK =
-	"`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+	"`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete block N`.";
 
 /**
- * Error text emitted when a block-anchored op cannot be resolved to a
- * syntactic block (unrecognized language, blank/out-of-range line, no node
- * begins on line N such as a lone closing delimiter, or the resolved block has
- * a syntax error). Names the offending line, steers back to an explicit
- * concrete-line form, and — when `fileLines` is provided — appends a
- * {@link formatAnchoredContext} preview of the file around the anchor line.
+ * Block-anchored replace/delete could not resolve to a syntactic block
+ * (unsupported language, blank/out-of-range line, no node beginning on N, or
+ * parse error). Appends a {@link formatAnchoredContext} preview when
+ * `fileLines` is given. `insert after block N:` never reaches this — it is
+ * lowered to plain `insert after N:` instead (see
+ * {@link insertAfterBlockUnresolvedLoweredWarning}).
  */
 export function blockUnresolvedMessage(
 	line: number,
-	op: "replace" | "delete" | "insert_after" = "replace",
+	op: "replace" | "delete" = "replace",
 	fileLines?: readonly string[],
 ): string {
-	const phrase =
-		op === "delete"
-			? `delete block ${line}`
-			: op === "insert_after"
-				? `insert after block ${line}:`
-				: `replace block ${line}:`;
-	const fallback =
-		op === "delete"
-			? `\`delete ${line}..M\``
-			: op === "insert_after"
-				? `\`insert after M:\` with the block's explicit last line`
-				: `\`replace ${line}..M:\` with the block's explicit end line`;
+	const phrase = op === "delete" ? `delete block ${line}` : `replace block ${line}:`;
+	const fallback = op === "delete" ? `delete ${line}..M` : `replace ${line}..M:`;
 	let message =
-		`\`${phrase}\` could not resolve a syntactic block beginning on line ${line}. ` +
-		`The language may be unsupported, the line may be blank or a closing delimiter, or the block may not parse. ` +
-		`Use ${fallback} instead.`;
+		`\`${phrase}\` could not resolve a syntactic block beginning on line ${line} ` +
+		`(unsupported language, blank/closer line, or parse error). Use \`${fallback}\` with explicit lines.`;
 	if (fileLines) {
 		const context = formatAnchoredContext([line], fileLines);
 		if (context.length > 0) message += `\n\n${context.join("\n")}`;
@@ -108,113 +90,92 @@ export function blockUnresolvedMessage(
 	return message;
 }
 
-/**
- * Error text emitted when a block-anchored edit reaches a code path that
- * has no {@link BlockResolver} wired in. Indicates a host-configuration bug
- * rather than authored-input error.
- */
+/** Block-anchored edit reached a path with no {@link BlockResolver} wired in — a host-configuration bug. */
 export const BLOCK_RESOLVER_UNAVAILABLE =
-	"Block-anchored ops (`replace block N:`, `delete block N`, `insert after block N:`) are not available here (no tree-sitter block resolver is configured). Use a concrete line range instead.";
+	"`replace block`/`delete block`/`insert after block` are not available here (no block resolver configured). Use a concrete line range.";
 
 /**
- * Warning emitted when an `insert after block N:` anchored on a pure
- * closing-delimiter line is lowered to plain `insert after N:`. No block
- * begins on a closer, but the closer IS the end of one — and inserting after
- * the end of that block is exactly what the plain form does.
+ * `insert after block N:` anchored on a closing-delimiter line, lowered to
+ * plain `insert after N:` — the closer ends a block, and inserting after it
+ * is exactly what the plain form does.
  */
 export function insertAfterBlockCloserLoweredWarning(line: number): string {
-	return (
-		`\`insert after block ${line}:\` anchors on a closing-delimiter line; no block begins there, so it was applied as plain \`insert after ${line}:\`. ` +
-		"Anchor `insert after block` on the line that OPENS the construct."
-	);
+	return `\`insert after block ${line}:\` anchors on a closing delimiter, so it was applied as plain \`insert after ${line}:\`. Anchor on the line that OPENS the construct.`;
+}
+
+/**
+ * `insert after block N:` anchor unresolvable (unsupported language, blank
+ * line, parse error, or no resolver), lowered to plain `insert after N:` —
+ * applying with a warning beats failing the patch.
+ */
+export function insertAfterBlockUnresolvedLoweredWarning(line: number): string {
+	return `\`insert after block ${line}:\` could not resolve a syntactic block on line ${line}, so it was applied as plain \`insert after ${line}:\`. Verify the landing line; anchor on a line that OPENS a construct.`;
 }
 
 /**
- * Internal invariant error: `applyEdits` received an unresolved `replace block
- * N:` edit. Block edits must be expanded by `resolveBlockEdits` before reaching
- * the applier; hitting this is a wiring bug, not authored-input error.
+ * Internal invariant: `applyEdits` received an unresolved `replace block N:`
+ * edit; `resolveBlockEdits` must run first. Wiring bug, not authored input.
  */
 export const UNRESOLVED_BLOCK_INTERNAL =
 	"internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).";
 
-/** Error text emitted when a delete hunk receives a body row. */
+/** Delete hunk received a body row. */
 export const DELETE_TAKES_NO_BODY = "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
 
-/** Error text emitted when a `delete block N` hunk receives a body row. */
+/** `delete block N` hunk received a body row. */
 export const DELETE_BLOCK_TAKES_NO_BODY =
-	"`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
+	"`delete block N` does not take body rows. Remove the body, or use `replace block N:`.";
 
-/** Error text emitted when an insert hunk has no body. */
+/** Insert hunk with no body. */
 export const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
 
 /**
- * Warning emitted when an `insert after` edit's body rows are indented
- * shallower than the anchor line and the landing point was slid forward past
- * the structural closer lines that follow. The body's indentation names the
- * depth the author wants the new lines to sit at; anchoring inside a deeper
- * construct is the common "insert after the block, anchored on the last line
- * I read" mistake.
+ * `insert after` body indented shallower than the anchor: the landing slid
+ * forward past trailing closer lines — the common "anchored on the last line
+ * I read instead of after the block" mistake.
  */
 export function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string {
-	return (
-		`insert after ${anchorLine}: the body is indented shallower than line ${anchorLine}, so the landing was moved past ` +
-		`${crossed} closing line${crossed === 1 ? "" : "s"} to after line ${landingLine}. ` +
-		`If you meant the deeper position inside the block, re-issue with the body indented to match.`
-	);
+	return `insert after ${anchorLine}: body indented shallower than the anchor, so the landing moved past ${crossed} closing line${crossed === 1 ? "" : "s"} to after line ${landingLine}. For the deeper position inside the block, re-issue with the body indented to match.`;
 }
 
 /**
- * Warning emitted when an `insert after block N:` body is indented deeper
- * than the block's closing line and the landing was pulled back inside the
- * block. `insert after block` places content AFTER the block at sibling
- * depth; a deeper body almost always means "append inside the block's body"
- * — the misuse this corrects.
+ * `insert after block N:` body indented deeper than the block's closer: the
+ * landing was pulled inside the block — a deeper body almost always means
+ * "append inside the block's body".
  */
 export function blockInsertLandingShiftWarning(blockStart: number, closerLine: number, landingLine: number): string {
-	return (
-		`insert after block ${blockStart}: the body is indented deeper than the block's closing line ${closerLine}, ` +
-		`so it was placed inside the block, after line ${landingLine}. ` +
-		"`insert after block` always lands AFTER the block at sibling depth — if you meant that, " +
-		`re-issue as plain \`insert after ${closerLine}:\` with the body indented to match line ${closerLine}.`
-	);
+	return `insert after block ${blockStart}: body indented deeper than closing line ${closerLine}, so it was placed inside the block, after line ${landingLine}. \`insert after block\` lands AFTER the block at sibling depth — if inside was intended, use plain \`insert after ${closerLine}:\`.`;
 }
 
-/** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
+/** `Recovery`: an external write matched a cached snapshot. */
 export const RECOVERY_EXTERNAL_WARNING =
 	"Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
 
-/** Warning text emitted by `Recovery` when a prior in-session edit advanced the hash. */
+/** `Recovery`: a prior in-session edit advanced the hash. */
 export const RECOVERY_SESSION_CHAIN_WARNING =
-	"Recovered from a stale file hash using an earlier in-session snapshot (the file hash advanced after a prior edit in this session).";
+	"Recovered from a stale file hash using an earlier in-session snapshot (a prior edit in this session advanced the hash).";
 
 /**
- * Warning text emitted by `Recovery` when the session-chain replay
- * fast-path was taken. Distinct from {@link RECOVERY_SESSION_CHAIN_WARNING}
- * because replay is the less-certain mode: the structured-patch 3-way
- * merge refused, the anchor-content gate passed, but a coincidental
- * insert+delete pair earlier in the chain could still leave an anchor's
- * line number pointing at a duplicated row. Surface the hedge so the
- * model verifies before continuing.
+ * `Recovery`: session-chain replay fast-path. Less certain than
+ * {@link RECOVERY_SESSION_CHAIN_WARNING} — the 3-way merge refused, the
+ * anchor-content gate passed, but a coincidental insert+delete earlier in
+ * the chain could still misplace an anchor — hence the verify hedge.
  */
 export const RECOVERY_SESSION_REPLAY_WARNING =
-	"Recovered by replaying your edits onto the current file content — your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+	"Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
 
 /**
- * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
- * existing file whose snapshot tag is stale (the file drifted since the read).
- * Head/tail insert position is content-independent — "start"/"end" cannot move
- * with drift — so this is non-fatal: the edit applies onto the live content and
- * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
+ * Head/tail position is content-independent, so drift is non-fatal: apply
+ * onto live content and warn instead of hard-failing.
  */
 export const HEADTAIL_DRIFT_WARNING =
-	"Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected — but re-read if the drift was unexpected.";
+	"Applied the `insert head:`/`insert tail:` edit despite a stale snapshot tag (file changed since your read) — head/tail position is content-independent. Re-read if the drift was unexpected.";
 
 /**
- * Error text emitted when a hashline section omits the mandatory snapshot tag.
- * The tag is REQUIRED on every section, enforced identically by the apply path
- * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
- * this single builder to stay in lockstep.
+ * Section omitted the mandatory snapshot tag. Shared by the apply
+ * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
  */
 export function missingSnapshotTagMessage(sectionPath: string): string {
-	return `Missing hashline snapshot tag for edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX}\` from your latest read/search output. To create a new file, use the write tool.`;
+	return `Missing hashline snapshot tag for ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX}\` from your latest read/search output. To create a new file, use the write tool.`;
 }