@oh-my-pi/hashline 15.12.4 → 15.13.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [15.13.1] - 2026-06-15
+
+### Breaking Changes
+
+- Rejected edits anchored to lines not displayed in the tagged read/search output, requiring unseen ranges to be re-read before reapplying
+
+### Changed
+
+- Rejected `replace block`, `delete block`, and `insert after block` operations that resolve to a single line and instructed users to use the plain single-line form or anchor the true construct opener
+
+### Fixed
+
+- Auto-repaired one-sided multi-line boundary echoes by dropping delimiter-neutral duplicated boundary lines and emitted a boundary-echo warning
+- Normalized cwd-relative hashline paths to forward-slash form on Windows.
+- Parser now treats a leading `\` on inline payload bodies as the payload delimiter, matching standalone payload rows.
+- Restored the warning emitted when escaped indented payload rows (`\\    TEXT`) are accepted as payload delimiters.
+
+## [15.12.5] - 2026-06-13
+
+### Fixed
+
+- Fixed delimiter-balance boundary repair so it does not keep a deleted structural closer when the replacement payload already restates that closer.
+
 ## [15.12.0] - 2026-06-12
 
 ### Changed
@@ -110,6 +133,7 @@
 - Fixed hashline replacements that accidentally restated unchanged lines above and below the selected range so they no longer duplicate both boundary lines ([#1664](https://github.com/can1357/oh-my-pi/issues/1664)).
 
 ## [15.7.0] - 2026-05-31
+
 ### Added
 
 - Added `replace block N:` and `delete block N` patch syntax to replace or delete the entire syntactic block that begins on line N using tree-sitter-resolved spans
@@ -117,6 +141,7 @@
 - Added `resolveBlockEdits` and block edit type definitions to the package API for resolving deferred `replace block` / `delete block` edits
 
 ## [15.5.13] - 2026-05-29
+
 ### Breaking Changes
 
 - Changed hashline section tags from 3-hex to 4-hex content-hash tags, so legacy 3-digit tags are no longer valid
@@ -125,7 +150,7 @@
 ### Added
 
 - Added `maxPaths` and `maxVersionsPerPath` options to `InMemorySnapshotStore` to bound tracked paths and per-path snapshot history
-- Re-introduced balance-validated boundary repair in `applyEdits`. A replacement hunk (`replace N..M:` + body) is normalized so its payload preserves the deleted region's delimiter balance: when the body restates a closing delimiter that survives just outside the range (duplicate `}` / `);` / `]`) the echo is dropped, and when the range deletes a structural closer the body never restates (missing closer) the closer is spared instead of deleted. A repair fires only when one boundary operation drives the per-channel `()` / `[]` / `{}` imbalance to exactly zero while leaving surrounding text byte-identical (single-line ops are limited to pure structural-closer lines), so balance-preserving edits and intentional balanced duplicates are never touched. Bracket couples are also bounded by line count: structural balance delta repair is capped to 10 duplicate lines across all channels combined, massive balanced blocks are skipped.
+- Re-introduced balance-validated boundary repair in `applyEdits`. A replacement hunk (`replace N..M:` + body) is normalized so its payload preserves the deleted region's delimiter balance: when the body restates a closing delimiter that survives just outside the range (duplicate `}` / `);` / `]`) the echo is dropped, and when the range deletes a structural closer the body never restates (missing closer) the closer is spared instead of deleted. A repair fires only when one boundary operation drives the per-channel `()` / `[]` / `{}` imbalance to exactly zero while leaving surrounding text byte-identical (single-line ops are limited to pure structural-closer lines), so balance-preserving edits and intentional balanced duplicates are never touched. Bracket counting skips strings, template literals, and comments. Each repair surfaces a `delimiter-balance` warning through `ApplyResult.warnings`.
 
 ### Changed
 
@@ -152,6 +177,7 @@
 - `MismatchError` now distinguishes "hash recognized but file content drifted" from "hash never recorded for this path". The latter (likely fabricated or carried over from a prior session) emits a dedicated `hash #X is not from this session` rejection message with explicit "never invent the tag" guidance. The `MismatchDetails` interface gains an optional `hashRecognized?: boolean` (defaults to `true` for backward compatibility); `MismatchError` exposes it as a readonly field so callers can branch on the cause.
 
 ## [15.5.8] - 2026-05-28
+
 ### Breaking Changes
 
 - Removed the single-number hunk header shorthand. A hunk header now REQUIRES two line numbers (`A A` for a single line, `A B` for a range); a bare `A` row throws `single-number hunk header "A" is no longer accepted`. The `&A` body-row shorthand for `&A..A` is unchanged.
@@ -192,7 +218,7 @@
 
 ### Breaking Changes
 
-- Redesigned hashline syntax around range anchors (`A-B:`, `A:`, `BOF:`, `EOF:`) and per-line payload sigils (`|`, `↑`, `↓`). Old op-line insert syntax and `\` payload continuations are no longer supported.
+- Changed hashline payload continuations from `+TEXT` to `\TEXT`; use `\` for an explicit blank payload line.
 
 ### Added
 
@@ -205,11 +231,12 @@
 
 ### Removed
 
-- Removed legacy deletion semantics that treated bare `A-B:` as a blank-line replacement; a bare range anchor now deletes the range.
+- Removed the `A-B!` / `A!` deletion operator. Use `A-B:` with the desired payload (or empty payload to blank the range) instead.
 
 All notable changes to this package will be documented in this file.
 
 ## [15.5.4] - 2026-05-27
+
 ### Added
 
 - Added a high-level `Patcher` API with all-or-nothing `apply` and staged `prepare`/`commit` flows for multi-file patch updates
@@ -225,4 +252,4 @@ All notable changes to this package will be documented in this file.
 
 - Fixed repeated patch application mutating cached `after_anchor` edits between target snapshots
 - Fixed multi-section patching to preflight write policies and reject duplicate canonical targets before any section is committed
-- Fixed mixed line-ending restoration to preserve the first newline style instead of rewriting ties to LF
+- Fixed mixed line-ending restoration to preserve the first newline style instead of rewriting ties to LF

package/dist/types/messages.d.ts

@@ -96,3 +96,20 @@ export declare const HEADTAIL_DRIFT_WARNING = "Applied the `insert head:`/`inser
  * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
  */
 export declare function missingSnapshotTagMessage(sectionPath: string): string;
+/**
+ * An anchored edit referenced lines the read that minted the cited tag never
+ * displayed (a partial range, or a structural summary that collapsed bodies).
+ * Editing lines you have not read is the off-by-memory failure that mangles
+ * files; reject and make the model re-read those exact lines first.
+ */
+export declare function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string;
+/** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
+export type BlockOp = "replace" | "delete" | "insert_after";
+/**
+ * A `replace block`/`delete block`/`insert after block` anchor resolved to a
+ * single line — almost always a bare statement the model mis-anchored, not a
+ * multi-line construct. The plain op is unambiguous for one line; the block
+ * form only earns its keep when it spares counting a closing line you cannot
+ * see. Reject and point at both fixes.
+ */
+export declare function blockSingleLineMessage(line: number, op: BlockOp): string;

package/dist/types/snapshots.d.ts

@@ -11,6 +11,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>;
 }
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
@@ -22,8 +31,19 @@ export declare abstract class SnapshotStore {
     abstract head(path: string): Snapshot | null;
     /** 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;
     /** Drop every version history. */
@@ -55,7 +75,8 @@ export declare class InMemorySnapshotStore extends SnapshotStore {
     constructor(options?: InMemorySnapshotStoreOptions);
     head(path: string): Snapshot | null;
     byHash(path: string, hash: string): Snapshot | null;
-    record(path: string, fullText: string): string;
+    record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+    recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
     invalidate(path: string): void;
     clear(): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.12.4",
+	"version": "15.13.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/apply.ts

@@ -318,11 +318,22 @@ function findDuplicatePrefix(group: ReplacementGroup, fileLines: readonly string
 	return 0;
 }
 
+function payloadEndsWithDeletedSuffix(group: ReplacementGroup, fileLines: readonly string[], count: number): boolean {
+	if (group.payload.length < count) return false;
+	const deletedStart = group.endLine - count;
+	const payloadStart = group.payload.length - count;
+	for (let offset = 0; offset < count; offset++) {
+		if (group.payload[payloadStart + offset] !== fileLines[deletedStart + offset]) return false;
+	}
+	return true;
+}
+
 /**
  * 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.
+ * structural closers, the payload does not already restate those same suffix
+ * lines, 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,
@@ -333,6 +344,7 @@ function findDroppedSuffixClosers(
 	const maxM = group.deleteIndices.length;
 	for (let m = 1; m <= maxM; m++) {
 		if (!STRUCTURAL_CLOSER_RE.test(fileLines[group.endLine - m] ?? "")) break;
+		if (payloadEndsWithDeletedSuffix(group, fileLines, m)) continue;
 		if (balanceEqual(computeDelimiterBalance(fileLines.slice(group.endLine - m, group.endLine)), wanted)) return m;
 	}
 	return 0;
@@ -431,6 +443,50 @@ function describeBoundaryRepair(group: ReplacementGroup, action: string): string
 	);
 }
 
+/**
+ * A single-sided boundary echo in an otherwise delimiter-balanced *multi-line*
+ * replacement: the payload's leading XOR trailing edge exactly restates the
+ * surviving line(s) just outside the range — the off-by-one "range one line
+ * short of the keeper I retyped" mistake (e.g. att: payload ends with
+ * `const x = [];` and line B+1 is the same `const x = [];`). Two-sided echoes
+ * are handled by {@link findBoundaryEcho}; delimiter-imbalanced one-sided echoes
+ * by {@link findDuplicateSuffix}/{@link findDuplicatePrefix}.
+ *
+ * Scoped to multi-line ranges (a construct rewrite) on purpose: a single-line
+ * `replace N..N` expanding into several lines is an *expansion* where every
+ * payload line is intentional new content, so a payload line that happens to
+ * equal a neighbor stays — only a genuine block rewrite retypes a boundary
+ * keeper by mistake. The dropped lines must be delimiter-neutral so removing the
+ * duplicate keeps the already-balanced result balanced, and must not consume the
+ * whole payload.
+ */
+function findOneSidedBoundaryEcho(
+	group: ReplacementGroup,
+	fileLines: readonly string[],
+): { side: "leading" | "trailing"; count: number } | undefined {
+	if (group.deleteIndices.length <= 1) return undefined;
+	const leading = countDuplicateLeadingBoundaryLines(group, fileLines);
+	const trailing = countDuplicateTrailingBoundaryLines(group, fileLines);
+	if (leading > 0 === trailing > 0) return undefined;
+	const side = leading > 0 ? "leading" : "trailing";
+	const count = leading > 0 ? leading : trailing;
+	if (count >= group.payload.length) return undefined;
+	const echoLines =
+		side === "leading" ? group.payload.slice(0, count) : group.payload.slice(group.payload.length - count);
+	if (!balanceIsZero(computeDelimiterBalance(echoLines))) return undefined;
+	return { side, count };
+}
+
+function describeOneSidedEchoRepair(group: ReplacementGroup, side: "leading" | "trailing", count: number): string {
+	const where = side === "leading" ? "above" : "below";
+	return (
+		`Auto-repaired a replacement boundary echo at line ${group.startLine}: ` +
+		`dropped ${count} ${side} payload line(s) identical to the surviving line(s) just ${where} the range. ` +
+		`The range was one line short of the content you retyped — issue the payload as the final content for the ` +
+		`selected range only, and widen the range to consume any keeper you restate.`
+	);
+}
+
 /**
  * Normalize replacement groups so common off-by-one boundaries do not duplicate
  * unchanged surrounding lines or structural closers. Returns the repaired edit
@@ -469,6 +525,16 @@ function repairReplacementBoundaries(
 			computeDelimiterBalance(fileLines.slice(group.startLine - 1, group.endLine)),
 		);
 		if (balanceIsZero(delta)) {
+			const oneSided = findOneSidedBoundaryEcho(group, fileLines);
+			if (oneSided) {
+				warnings.push(describeOneSidedEchoRepair(group, oneSided.side, oneSided.count));
+				const trimmed =
+					oneSided.side === "leading"
+						? inserts.slice(oneSided.count)
+						: inserts.slice(0, inserts.length - oneSided.count);
+				out.push(...trimmed, ...deletes);
+				continue;
+			}
 			out.push(...inserts, ...deletes);
 			continue;
 		}

package/src/block.ts

@@ -15,6 +15,7 @@
 import { STRUCTURAL_CLOSER_RE } from "./apply";
 import {
 	BLOCK_RESOLVER_UNAVAILABLE,
+	blockSingleLineMessage,
 	blockUnresolvedMessage,
 	insertAfterBlockCloserLoweredWarning,
 	insertAfterBlockUnresolvedLoweredWarning,
@@ -110,6 +111,15 @@ export function resolveBlockEdits(
 				}`,
 			);
 		}
+		if (span.start === span.end) {
+			// A single-line block resolution means line N is a bare statement, not
+			// the opening line of a multi-line construct — the common mis-anchor
+			// that lands a body in the wrong scope (e.g. between a `case` body line
+			// and its `break;`). The plain op is exact for one line, so reject and
+			// point at it; drop instead on the lenient preview path.
+			if (onUnresolved === "drop") continue;
+			throw new Error(`line ${edit.lineNum}: ${blockSingleLineMessage(edit.anchor.line, op)}`);
+		}
 		options.onResolved?.({
 			anchorLine: edit.anchor.line,
 			start: span.start,

package/src/input.ts

@@ -88,8 +88,9 @@ function normalizeHashlinePath(rawPath: string, cwd?: string): string {
 	const unquoted = stripApplyPatchPathNoise(unquoteHashlinePath(rawPath.trim()));
 	if (!cwd || !path.isAbsolute(unquoted)) return unquoted;
 	const relative = path.relative(path.resolve(cwd), path.resolve(unquoted));
+	const normalizedRelative = relative.split(path.sep).join("/");
 	const isWithinCwd = relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-	return isWithinCwd ? relative || "." : unquoted;
+	return isWithinCwd ? normalizedRelative || "." : unquoted;
 }
 
 interface RawSection {

package/src/messages.ts

@@ -179,3 +179,64 @@ export const HEADTAIL_DRIFT_WARNING =
 export function missingSnapshotTagMessage(sectionPath: string): string {
 	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.`;
 }
+
+/** Compress a line list into a sorted `1-4, 7, 10-12` range string. */
+function formatLineRanges(lines: readonly number[]): string {
+	const sorted = [...new Set(lines)].sort((a, b) => a - b);
+	if (sorted.length === 0) return "";
+	const parts: string[] = [];
+	let start = sorted[0];
+	let prev = sorted[0];
+	for (let i = 1; i <= sorted.length; i++) {
+		const current = sorted[i];
+		if (current === prev + 1) {
+			prev = current;
+			continue;
+		}
+		parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+		start = current;
+		prev = current;
+	}
+	return parts.join(", ");
+}
+
+/**
+ * An anchored edit referenced lines the read that minted the cited tag never
+ * displayed (a partial range, or a structural summary that collapsed bodies).
+ * Editing lines you have not read is the off-by-memory failure that mangles
+ * files; reject and make the model re-read those exact lines first.
+ */
+export function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string {
+	return (
+		`This edit targets line(s) ${formatLineRanges(unseenLines)} of ${sectionPath} that were not shown in the ` +
+		`read/search output for ${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}${tag}${HL_FILE_SUFFIX} — a partial ` +
+		`range, a search hit, or a structural summary that collapsed bodies was displayed, not those exact lines. ` +
+		`Re-read those lines, then re-issue the edit against the fresh tag. NEVER author hunks against line numbers ` +
+		`you have not seen in the current snapshot.`
+	);
+}
+
+/** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
+export type BlockOp = "replace" | "delete" | "insert_after";
+
+/**
+ * A `replace block`/`delete block`/`insert after block` anchor resolved to a
+ * single line — almost always a bare statement the model mis-anchored, not a
+ * multi-line construct. The plain op is unambiguous for one line; the block
+ * form only earns its keep when it spares counting a closing line you cannot
+ * see. Reject and point at both fixes.
+ */
+export function blockSingleLineMessage(line: number, op: BlockOp): string {
+	const blockForm = op === "insert_after" ? "insert after block" : op === "delete" ? "delete block" : "replace block";
+	const plainForm =
+		op === "insert_after"
+			? `insert after ${line}:`
+			: op === "delete"
+				? `delete ${line}`
+				: `replace ${line}..${line}:`;
+	return (
+		`\`${blockForm} ${line}\` resolved a single-line block — line ${line} is a bare statement, not the opening line ` +
+		`of a multi-line construct. For that one line use \`${plainForm}\`; to act on an enclosing construct, anchor ${blockForm} ` +
+		`on the line that OPENS it (e.g. its \`function\`/\`if\`/\`case\` header), never a statement inside it.`
+	);
+}

package/src/patcher.ts

@@ -28,7 +28,7 @@ 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 { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage, unseenLinesMessage } from "./messages";
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
@@ -341,6 +341,22 @@ export class Patcher {
 	#recordFullSnapshot(canonicalPath: string, normalized: string): string {
 		return this.snapshots.record(canonicalPath, normalized);
 	}
+
+	/**
+	 * Reject an anchored edit that references a line the read which minted
+	 * `expected` never displayed. The snapshot's `seenLines` is the set of
+	 * 1-indexed lines a producer (read/search) actually showed under that tag;
+	 * absent or empty means no provenance was recorded, so the edit applies as
+	 * before. Only runs on the no-drift path, where anchor line numbers index
+	 * the tagged content 1:1.
+	 */
+	#assertSeenLines(section: PatchSection, canonicalPath: string, expected: string): void {
+		const seen = this.snapshots.byHash(canonicalPath, expected)?.seenLines;
+		if (!seen || seen.size === 0) return;
+		const unseen = section.collectAnchorLines().filter(line => !seen.has(line));
+		if (unseen.length === 0) return;
+		throw new Error(unseenLinesMessage(section.path, unseen, expected));
+	}
 	#mismatchError(
 		section: PatchSection,
 		canonicalPath: string,
@@ -404,6 +420,10 @@ export class Patcher {
 		// the caller read, so echo them back. (A drifted file falls through to
 		// recovery below, where line numbers shift, so resolutions are dropped.)
 		if (expected === undefined || liveMatches) {
+			// The line numbers in `edits` index the exact content the tag names.
+			// Reject any anchor the read never displayed: editing lines the model
+			// has not seen is the off-by-memory mistake that mangles files.
+			if (expected !== undefined) this.#assertSeenLines(section, canonicalPath, expected);
 			const result = applyEdits(normalized, resolved);
 			return withResolveWarnings(blockResolutions.length > 0 ? { ...result, blockResolutions } : result);
 		}

package/src/prompt.md

@@ -27,8 +27,8 @@ 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.
@@ -36,9 +36,9 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - 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:`.
+- Block ops (`replace block`/`delete block`/`insert after block`) 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 (`replace N..N` / `delete N` / `insert after N`) for one line, or point N at the real opener. Saw the closer? Use plain `insert after 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 `insert`, never a widened `replace` — retyped keepers are exactly what gets dropped. A multi-line `replace` 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>
 

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);
 	}