@oh-my-pi/hashline 16.4.8 → 16.5.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [16.5.0] - 2026-07-13
+
+### Fixed
+
+- Fixed a critical issue where ambiguous swaps could silently delete range boundaries.
+- Prevented incorrect auto-repairing of structural closing lines when payload placement is ambiguous.
+- Fixed a bug in stale-hash recovery that could incorrectly relocate edits onto duplicated context after the original target changed.
+
 ## [16.3.3] - 2026-07-02
 
 ### Breaking Changes

package/dist/types/messages.d.ts

@@ -49,6 +49,23 @@ export declare function insertAfterBlockCloserLoweredWarning(line: number): stri
  * applying with a warning beats failing the patch.
  */
 export declare function insertAfterBlockUnresolvedLoweredWarning(line: number): string;
+/**
+ * A one-sided boundary echo whose payload is too short to be the widened
+ * range's full content: dropping the echo deletes range line(s) the payload
+ * never restates (the "widened range" reading), while the "range shifted by
+ * the echo" reading keeps them. The readings produce different files, so the
+ * edit is rejected instead of repaired.
+ */
+export declare function ambiguousBoundaryEchoMessage(startLine: number, endLine: number, side: "leading" | "trailing", count: number): string;
+/**
+ * A replacement range deletes trailing structural closer(s) the payload never
+ * restates, and nothing anchors the payload inside the block those closers
+ * terminate: the payload has no unmatched opener for them and its indentation
+ * is not deeper than the closer. Sparing the closer would have to guess
+ * whether the payload belongs before it (inside the block) or after it (a
+ * sibling), so the edit is rejected instead of repaired.
+ */
+export declare function ambiguousCloserSpareMessage(startLine: number, endLine: number, closerLine: number, count: number): string;
 /**
  * Internal invariant: `applyEdits` received an unresolved `replace_block N:`
  * edit; `resolveBlockEdits` must run first. Wiring bug, not authored input.
@@ -80,13 +97,6 @@ export declare function blockInsertLandingShiftWarning(blockStart: number, close
 export declare const RECOVERY_EXTERNAL_WARNING = "Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
 /** `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).";
-/**
- * `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 (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
 /** `Recovery`: stale anchors were relocated to unchanged live lines after drift. */
 export declare const RECOVERY_LINE_REMAP_WARNING = "Recovered by remapping stale line anchors to unchanged current lines (file changed since the tagged read). Verify the diff matches your intent.";
 /**

package/dist/types/recovery.d.ts

@@ -16,22 +16,13 @@ export interface RecoveryResult {
 }
 /**
  * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
- * call {@link Recovery.tryRecover} per stale-tag incident. The default
- * implementation tries three strategies in order:
+ * call {@link Recovery.tryRecover} per stale-tag incident.
  *
- * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
- *    the resulting patch onto the live content (handles external writes).
- * 2. Remap every stale anchor through the unchanged-line diff from the tagged
- *    snapshot to the live text, then replay on live content. This handles a
- *    prior insertion/deletion before the target while refusing changed anchors
- *    and mixed offsets across the same edit range.
- * 3. (Session chain) If that version wasn't the head, replay the edits onto
- *    the live content directly when line counts match AND every edit's anchor
- *    line content is unchanged between version and current — a prior in-session
- *    edit advanced the tag and the model's anchors still name the same logical
- *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
- *    even with both guards a coincidental insert+delete pair on duplicate rows
- *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ * Recovery maps every stale anchor through unchanged lines from the tagged
+ * snapshot to the live text, validates surrounding context, and replays the
+ * edit directly on live content. All anchors must move by one consistent
+ * offset. A changed, deleted, split, or ambiguous target is rejected so the
+ * caller can surface a {@link MismatchError} with current context.
  */
 export declare class Recovery {
     readonly store: SnapshotStore;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "16.4.8",
+	"version": "16.5.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",
@@ -34,7 +34,7 @@
 	},
 	"dependencies": {
 		"diff": "^9.0.0",
-		"lru-cache": "11.5.1"
+		"lru-cache": "11.5.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/apply.ts

@@ -7,7 +7,13 @@
  * which absorbs common model mistakes where a payload restates unchanged range
  * boundaries or duplicates/drops structural closers.
  */
-import { afterInsertLandingShiftWarning, blockInsertLandingShiftWarning, UNRESOLVED_BLOCK_INTERNAL } from "./messages";
+import {
+	afterInsertLandingShiftWarning,
+	ambiguousBoundaryEchoMessage,
+	ambiguousCloserSpareMessage,
+	blockInsertLandingShiftWarning,
+	UNRESOLVED_BLOCK_INTERNAL,
+} from "./messages";
 import { cloneCursor } from "./tokenizer";
 import type { Anchor, ApplyResult, Cursor, Edit } from "./types";
 
@@ -702,6 +708,12 @@ function describeBoundaryRepair(group: ReplacementGroup, action: string): string
  * carries no delimiter-balance signal itself, such as a JSX `</section>` close.
  * The dropped lines must keep the already-balanced result balanced, and must
  * not consume the whole payload.
+ *
+ * A detected echo is only *repairable* when the payload is long enough to be
+ * the widened range's full content (`payload ≥ range + echo`). Shorter
+ * payloads are ambiguous — the echo may instead mean the range itself was
+ * shifted by the echo, which keeps the far boundary line(s) the repair would
+ * delete — and the caller rejects the edit instead of guessing.
  */
 function findOneSidedBoundaryEcho(
 	group: ReplacementGroup,
@@ -800,6 +812,12 @@ function slotPatchDelta(slot: RepairSlot, fileLines: readonly string[]): Delimit
  * deleted is only kept when the patch as a whole is missing it — never when
  * another hunk already removed the matching opener. Returns the repaired edits
  * plus one warning per repaired group.
+ *
+ * Repairs fire only when exactly one reading explains the mistake. When the
+ * evidence is ambiguous — a one-sided echo whose payload is too short for the
+ * widened range, or a spared closer the payload neither opens nor indents
+ * into — the function throws instead of guessing, so the author re-issues the
+ * edit rather than shipping silently corrupted content.
  */
 function repairReplacementBoundaries(
 	edits: readonly AppliedEdit[],
@@ -842,6 +860,15 @@ function repairReplacementBoundaries(
 		if (balanceIsZero(delta)) {
 			const oneSided = findOneSidedBoundaryEcho(group, fileLines);
 			if (oneSided) {
+				// A payload shorter than range+echo cannot be the widened
+				// range's full content: the repair would delete range line(s)
+				// the payload never restates, while the "shifted range"
+				// reading keeps them. Reject rather than guess.
+				if (group.payload.length < group.deleteIndices.length + oneSided.count) {
+					throw new Error(
+						ambiguousBoundaryEchoMessage(group.startLine, group.endLine, oneSided.side, oneSided.count),
+					);
+				}
 				const trimmed =
 					oneSided.side === "leading"
 						? inserts.slice(oneSided.count)
@@ -934,6 +961,29 @@ function repairReplacementBoundaries(
 			insertedLineMaps,
 		);
 		if (droppedClosers) {
+			// Sparing a closer re-inserts it *after* the payload, which claims
+			// the payload lives inside the block the closer terminates. That
+			// claim needs evidence: the payload carries the closer's unmatched
+			// opener itself, or its indentation sits deeper than the closer.
+			// Without either, "before or after the closer" is a coin flip —
+			// reject rather than guess (e.g. a statement swapped onto a lone
+			// `}` at the closer's own depth belongs after the block).
+			const keptIndent = leadingIndent(fileLines[droppedClosers.startLine - 1] ?? "");
+			const payloadIndent = bodyTargetIndent(slot.group.payload);
+			const payloadOpens = balanceCovers(
+				computeDelimiterBalance(slot.group.payload),
+				balanceNegate(droppedClosers.balance),
+			);
+			if (!payloadOpens && !(payloadIndent !== undefined && isIndentDeeper(payloadIndent, keptIndent))) {
+				throw new Error(
+					ambiguousCloserSpareMessage(
+						slot.group.startLine,
+						slot.group.endLine,
+						droppedClosers.startLine,
+						droppedClosers.count,
+					),
+				);
+			}
 			warnings.push(
 				describeBoundaryRepair(
 					slot.group,

package/src/messages.ts

@@ -108,6 +108,55 @@ export function insertAfterBlockCloserLoweredWarning(line: number): string {
 export function insertAfterBlockUnresolvedLoweredWarning(line: number): string {
 	return `\`INS.BLK.POST ${line}:\` could not resolve a syntactic block on line ${line}, so it was applied as plain \`INS.POST ${line}:\`. Verify the landing line; anchor on a line that OPENS a construct.`;
 }
+/**
+ * A one-sided boundary echo whose payload is too short to be the widened
+ * range's full content: dropping the echo deletes range line(s) the payload
+ * never restates (the "widened range" reading), while the "range shifted by
+ * the echo" reading keeps them. The readings produce different files, so the
+ * edit is rejected instead of repaired.
+ */
+export function ambiguousBoundaryEchoMessage(
+	startLine: number,
+	endLine: number,
+	side: "leading" | "trailing",
+	count: number,
+): string {
+	const where =
+		side === "leading"
+			? `opens by restating the ${count} line(s) just above the range`
+			: `ends by restating the ${count} line(s) just below the range`;
+	return (
+		`\`SWAP ${startLine}${HL_RANGE_SEP}${endLine}:\` rejected: the body ${where}, ` +
+		`but is too short to be the full final content of the widened range — applying it as-is or ` +
+		`auto-repairing would delete range line(s) the body never restates. ` +
+		`Re-issue with the range covering exactly the lines that change and the body as their complete ` +
+		`final content: drop the restated keeper from the body, or widen the range to consume it.`
+	);
+}
+
+/**
+ * A replacement range deletes trailing structural closer(s) the payload never
+ * restates, and nothing anchors the payload inside the block those closers
+ * terminate: the payload has no unmatched opener for them and its indentation
+ * is not deeper than the closer. Sparing the closer would have to guess
+ * whether the payload belongs before it (inside the block) or after it (a
+ * sibling), so the edit is rejected instead of repaired.
+ */
+export function ambiguousCloserSpareMessage(
+	startLine: number,
+	endLine: number,
+	closerLine: number,
+	count: number,
+): string {
+	const closers = count === 1 ? `line ${closerLine}` : `lines ${closerLine}-${closerLine + count - 1}`;
+	return (
+		`\`SWAP ${startLine}${HL_RANGE_SEP}${endLine}:\` rejected: the range deletes the closing-delimiter ` +
+		`${closers} but the body never restates it, and the body claims no position inside that block ` +
+		`(no unmatched opener, indentation not deeper than the closer) — whether the new content belongs ` +
+		`before or after the closer is ambiguous. Restate the closer in the body at the intended position, ` +
+		`or use \`INS.PRE ${closerLine}:\` / \`INS.POST ${closerLine}:\` instead.`
+	);
+}
 
 /**
  * Internal invariant: `applyEdits` received an unresolved `replace_block N:`
@@ -159,15 +208,6 @@ export const RECOVERY_EXTERNAL_WARNING =
 export 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).";
 
-/**
- * `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 (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
-
 /** `Recovery`: stale anchors were relocated to unchanged live lines after drift. */
 export const RECOVERY_LINE_REMAP_WARNING =
 	"Recovered by remapping stale line anchors to unchanged current lines (file changed since the tagged read). Verify the diff matches your intent.";

package/src/patcher.ts

@@ -586,7 +586,7 @@ export class Patcher {
 		const expected = exists ? section.fileHash : undefined;
 		// The 4-hex tag is content-derived: when the live text hashes to it,
 		// trust the match and apply directly. `storedSnapshotForTag` feeds the
-		// drift paths below (block resolution, 3-way recovery); on a 16-bit
+		// drift paths below (block resolution, anchor remapping); on a 16-bit
 		// tag collision it resolves to the most-recently recorded text.
 		const storedSnapshotForTag = expected === undefined ? null : this.snapshots.byHash(canonicalPath, expected);
 		const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
@@ -598,7 +598,7 @@ export class Patcher {
 		//   - live content matches the tag (or there is no tag) → resolve against
 		//     the live, normalized content;
 		//   - the file drifted → resolve against the tagged snapshot's text so the
-		//     resulting ranges flow through the 3-way-merge recovery below.
+		//     resulting ranges can be mapped to unchanged live lines below.
 		// When a block edit needs the tagged snapshot but it is unavailable, the
 		// range cannot be placed safely — reject with a MismatchError (re-read).
 		const blockResolutions: BlockResolution[] = [];
@@ -640,8 +640,8 @@ export class Patcher {
 			const result = applyEdits(normalized, resolved);
 			return withResolveWarnings({ ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] });
 		}
-		// File drifted: try to replay the edit against the version the tag
-		// names and 3-way-merge it onto the live content.
+		// File drifted: map every anchor from the tagged snapshot to unchanged
+		// live lines. Recovery refuses changed or ambiguous targets.
 		const recovered = this.recovery.tryRecover({
 			path: canonicalPath,
 			currentText: normalized,

package/src/recovery.ts

@@ -1,29 +1,17 @@
 /**
- * Recover from a stale section snapshot tag by replaying the would-be edit
- * against a cached pre-edit snapshot of the file and 3-way-merging the
- * result onto the current on-disk content.
+ * Recovers stale section tags by proving that every anchored line still maps
+ * to one unchanged, contiguous region in the current file, then replaying the
+ * edit against that live content.
  *
- * The patcher consults this when a section tag resolves to a snapshot that no
- * longer matches the live file content. The recovery class is stateless apart
- * from the {@link SnapshotStore} it queries; the snapshot store is the seam
- * lets you plug in your own caching strategy.
+ * Recovery fails closed when the target changed or became ambiguous. The
+ * patcher then returns a mismatch with fresh context instead of guessing.
  */
 import * as Diff from "diff";
 import { applyEdits } from "./apply";
-import {
-	RECOVERY_EXTERNAL_WARNING,
-	RECOVERY_LINE_REMAP_WARNING,
-	RECOVERY_SESSION_CHAIN_WARNING,
-	RECOVERY_SESSION_REPLAY_WARNING,
-} from "./messages";
-import type { Snapshot, SnapshotStore } from "./snapshots";
+import { RECOVERY_EXTERNAL_WARNING, RECOVERY_LINE_REMAP_WARNING, RECOVERY_SESSION_CHAIN_WARNING } from "./messages";
+import type { SnapshotStore } from "./snapshots";
 import type { Anchor, ApplyResult, Edit } from "./types";
 
-// Section tags are line-precise; never let Diff.applyPatch slide a hunk
-// onto a duplicate closer 100+ lines away. If snapshot replay does not
-// align exactly, refuse and let the caller re-read.
-const RECOVERY_FUZZ_FACTOR = 0;
-
 export interface RecoveryArgs {
 	path: string;
 	currentText: string;
@@ -40,31 +28,6 @@ export interface RecoveryResult {
 	warnings: string[];
 }
 
-function applyEditsToSnapshot(
-	previousText: string,
-	currentText: string,
-	edits: readonly Edit[],
-	recoveryWarning: string,
-): RecoveryResult | null {
-	let applied: ApplyResult;
-	try {
-		applied = applyEdits(previousText, [...edits]);
-	} catch {
-		return null;
-	}
-	if (applied.text === previousText) return null;
-
-	const patch = Diff.structuredPatch("file", "file", previousText, applied.text, "", "", { context: 3 });
-	const merged = Diff.applyPatch(currentText, patch, { fuzzFactor: RECOVERY_FUZZ_FACTOR });
-	if (typeof merged !== "string" || merged === currentText) return null;
-
-	const firstChangedLine = findFirstChangedLine(currentText, merged) ?? applied.firstChangedLine;
-	const hasNetChange = firstChangedLine !== undefined;
-	const warnings = hasNetChange ? [recoveryWarning, ...(applied.warnings ?? [])] : [...(applied.warnings ?? [])];
-
-	return { text: merged, firstChangedLine, warnings };
-}
-
 function collectAnchorLines(edits: readonly Edit[]): number[] {
 	const lines: number[] = [];
 	for (const edit of edits) {
@@ -81,27 +44,6 @@ function getEditAnchors(edit: Edit): Anchor[] {
 	return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor" ? [edit.cursor.anchor] : [];
 }
 
-/**
- * Returns true when every anchor line in `edits` has identical content in
- * `previousText` and `currentText`. The session-chain replay fast-path
- * requires this: if the prior in-session edit rewrote the line the model is
- * now re-targeting with a stale hash, replaying onto current would silently
- * overwrite the new content with whatever the model authored against the
- * old content — a corruption window, not a recovery.
- */
-function verifyAnchorContent(previousText: string, currentText: string, edits: readonly Edit[]): boolean {
-	const lines = collectAnchorLines(edits);
-	if (lines.length === 0) return true;
-	const prev = previousText.split("\n");
-	const curr = currentText.split("\n");
-	for (const line of lines) {
-		const idx = line - 1;
-		if (idx < 0 || idx >= prev.length || idx >= curr.length) return false;
-		if (prev[idx] !== curr[idx]) return false;
-	}
-	return true;
-}
-
 function buildLineMap(previousText: string, currentText: string): Map<number, number> {
 	const previousLines = previousText.split("\n");
 	const currentLines = currentText.split("\n");
@@ -198,7 +140,7 @@ function validateUniqueAnchorContext(
 ): boolean {
 	const offset = mapped - line;
 	const { before, after } = neighbors;
-	if (after !== undefined) return lineMap.get(after) === after + offset;
+	if (after !== undefined && lineMap.get(after) === after + offset) return true;
 	return before !== undefined && lineMap.get(before) === before + offset;
 }
 
@@ -237,7 +179,12 @@ function validateRemappedAnchorContext(
 	return true;
 }
 
-function remapEditsToCurrent(previousText: string, currentText: string, edits: readonly Edit[]): Edit[] | null {
+interface RemappedEdits {
+	edits: Edit[];
+	offset: number;
+}
+
+function remapEditsToCurrent(previousText: string, currentText: string, edits: readonly Edit[]): RemappedEdits | null {
 	const lineMap = buildLineMap(previousText, currentText);
 	if (!validateRemappedAnchorContext(previousText, currentText, lineMap, edits)) return null;
 	const offsets: number[] = [];
@@ -289,55 +236,21 @@ function remapEditsToCurrent(previousText: string, currentText: string, edits: r
 
 	if (offsets.length === 0) return null;
 	const firstOffset = offsets[0];
-	if (firstOffset === 0) return null;
 	if (!offsets.every(offset => offset === firstOffset)) return null;
-	return remapped;
+	return { edits: remapped, offset: firstOffset };
 }
 
 function replayRemappedAnchorsOnCurrent(
 	previousText: string,
 	currentText: string,
 	edits: readonly Edit[],
+	recoveryWarning: string,
 ): RecoveryResult | null {
 	const remapped = remapEditsToCurrent(previousText, currentText, edits);
 	if (remapped === null) return null;
 	let applied: ApplyResult;
 	try {
-		applied = applyEdits(currentText, remapped);
-	} catch {
-		return null;
-	}
-	if (applied.text === currentText) return null;
-	return {
-		text: applied.text,
-		firstChangedLine: applied.firstChangedLine,
-		warnings: [RECOVERY_LINE_REMAP_WARNING, ...(applied.warnings ?? [])],
-	};
-}
-
-function replaySessionChainOnCurrent(
-	previousText: string,
-	currentText: string,
-	edits: readonly Edit[],
-): RecoveryResult | null {
-	// Two guards narrow the corruption window. Neither alone is sufficient,
-	// and even together they don't fully prove correctness — replay is the
-	// less-certain recovery mode and emits RECOVERY_SESSION_REPLAY_WARNING
-	// so the caller can verify the diff.
-	//   - Equal line counts: every line number in `edits` still resolves to
-	//     SOME logical row (no net shift across the prior chain). A
-	//     coincidental insert+delete pair can still leave indices pointing
-	//     at different logical rows than the model anchored against.
-	//   - Anchor-content alignment: the row at each anchor's line index has
-	//     identical content in previous and current. Catches the common
-	//     case of a prior edit rewriting the targeted line; can still be
-	//     coincidentally satisfied by a duplicated row at the shifted
-	//     index.
-	if (previousText.split("\n").length !== currentText.split("\n").length) return null;
-	if (!verifyAnchorContent(previousText, currentText, edits)) return null;
-	let applied: ApplyResult;
-	try {
-		applied = applyEdits(currentText, [...edits]);
+		applied = applyEdits(currentText, remapped.edits);
 	} catch {
 		return null;
 	}
@@ -345,44 +258,18 @@ function replaySessionChainOnCurrent(
 	return {
 		text: applied.text,
 		firstChangedLine: applied.firstChangedLine,
-		warnings: [RECOVERY_SESSION_REPLAY_WARNING, ...(applied.warnings ?? [])],
+		warnings: [remapped.offset === 0 ? recoveryWarning : RECOVERY_LINE_REMAP_WARNING, ...(applied.warnings ?? [])],
 	};
 }
-
-/** First 1-indexed line at which `a` and `b` diverge, or `undefined` if equal. */
-function findFirstChangedLine(a: string, b: string): number | undefined {
-	if (a === b) return undefined;
-	const aLines = a.split("\n");
-	const bLines = b.split("\n");
-	const max = Math.max(aLines.length, bLines.length);
-	for (let i = 0; i < max; i++) {
-		if (aLines[i] !== bLines[i]) return i + 1;
-	}
-	return undefined;
-}
-
-function isHeadSnapshot(head: Snapshot | null, snapshot: Snapshot): boolean {
-	return head === snapshot;
-}
-
 /**
  * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
- * call {@link Recovery.tryRecover} per stale-tag incident. The default
- * implementation tries three strategies in order:
+ * call {@link Recovery.tryRecover} per stale-tag incident.
  *
- * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
- *    the resulting patch onto the live content (handles external writes).
- * 2. Remap every stale anchor through the unchanged-line diff from the tagged
- *    snapshot to the live text, then replay on live content. This handles a
- *    prior insertion/deletion before the target while refusing changed anchors
- *    and mixed offsets across the same edit range.
- * 3. (Session chain) If that version wasn't the head, replay the edits onto
- *    the live content directly when line counts match AND every edit's anchor
- *    line content is unchanged between version and current — a prior in-session
- *    edit advanced the tag and the model's anchors still name the same logical
- *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
- *    even with both guards a coincidental insert+delete pair on duplicate rows
- *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ * Recovery maps every stale anchor through unchanged lines from the tagged
+ * snapshot to the live text, validates surrounding context, and replays the
+ * edit directly on live content. All anchors must move by one consistent
+ * offset. A changed, deleted, split, or ambiguous target is rejected so the
+ * caller can surface a {@link MismatchError} with current context.
  */
 export class Recovery {
 	constructor(readonly store: SnapshotStore) {}
@@ -392,26 +279,12 @@ export class Recovery {
 	 */
 	tryRecover(args: RecoveryArgs): RecoveryResult | null {
 		const { path, currentText, fileHash, edits } = args;
-		// When two retained texts collide on the 16-bit tag, resolve to the
-		// most-recently recorded one; a wrong pick can only land if one of the
-		// merge/remap/session-chain strategies below applies it cleanly.
+		// When retained texts collide on the 16-bit tag, use the latest one.
+		// Recovery still requires its anchors and context to map unambiguously.
 		const snapshot = this.store.byHash(path, fileHash);
 		if (!snapshot) return null;
-		const isHead = isHeadSnapshot(this.store.head(path), snapshot);
-		const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
-		const merged = applyEditsToSnapshot(snapshot.text, currentText, edits, recoveryWarning);
-		if (merged !== null) return merged;
-		// Line-shift fallback: the 3-way merge refused, but unchanged anchor
-		// lines may have moved because a prior edit inserted or deleted rows
-		// before them. Remap only when every anchor resolves through the diff
-		// with one consistent offset; otherwise the edit range was touched.
-		const remapped = replayRemappedAnchorsOnCurrent(snapshot.text, currentText, edits);
-		if (remapped !== null) return remapped;
-		// Session-chain fallback: replay onto current is gated by line-count
-		// equality AND anchor-content alignment — see
-		// `replaySessionChainOnCurrent` for why both guards together still
-		// don't fully prove correctness.
-		if (!isHead) return replaySessionChainOnCurrent(snapshot.text, currentText, edits);
-		return null;
+		const recoveryWarning =
+			this.store.head(path) === snapshot ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
+		return replayRemappedAnchorsOnCurrent(snapshot.text, currentText, edits, recoveryWarning);
 	}
 }

package/src/snapshots.ts

@@ -11,8 +11,7 @@
  * {@link SnapshotStore.record} with the full normalized text they observed.
  * The store hashes it, dedups against the per-path history, and returns the
  * tag. Consumers (recovery, the patcher) resolve a stale tag back to the
- * recorded full text via {@link SnapshotStore.byHash} and 3-way-merge the
- * would-be edit onto the live content.
+ * recorded full text and map its unchanged edit anchors onto live content.
  *
  * The abstract base class lets callers plug in whatever storage they like
  * (LRU, persistent SQLite, etc.). {@link InMemorySnapshotStore} ships as a
@@ -199,8 +198,8 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		// texts that happen to share the 4-hex tag are DIFFERENT snapshots — fusing
 		// them under one entry would corrupt seenLines (attaching lines from
 		// text B onto the stored text A) and let the patcher misresolve which
-		// snapshot the section tag names when it does 3-way merge or seen-line
-		// validation. See issue #4075.
+		// snapshot the section tag names during recovery or seen-line validation.
+		// See issue #4075.
 		const existing = history.find(version => version.hash === hash && version.text === fullText);
 		if (existing) {
 			// Same content state observed again: refresh recency and promote to