@oh-my-pi/hashline 15.5.6 → 15.5.8

package/README.md

@@ -19,15 +19,15 @@ import {
 } from "@oh-my-pi/hashline";
 
 const fs = new InMemoryFilesystem();
-await fs.writeText(
-	"hello.ts",
-	`const greeting = "hi";\nexport { greeting };\n`,
-);
-
-const patcher = new Patcher({ fs });
-const patch = Patch.parse(String.raw`¶hello.ts
-1:
-|const greeting = "hello";`);
+const snapshots = new InMemorySnapshotStore();
+const before = `const greeting = "hi";\nexport { greeting };\n`;
+await fs.writeText("hello.ts", before);
+
+const tag = snapshots.recordContiguous("hello.ts", 1, before.split("\n"), { fullText: before });
+const patcher = new Patcher({ fs, snapshots });
+const patch = Patch.parse(String.raw`¶hello.ts#${tag}
+@@ 1..1 @@
++const greeting = "hello";`);
 const result = await patcher.apply(patch);
 
 console.log(result.sections[0].op); // "update"
@@ -39,19 +39,19 @@ console.log(await fs.readText("hello.ts"));
 See [`src/prompt.md`](./src/prompt.md) for the user-facing description and
 [`src/grammar.lark`](./src/grammar.lark) for the formal grammar.
 
-Each hunk starts with a `¶PATH#HASH` header. The hash is a 4-hex-character
-xxHash32 truncation of the file's LF-normalized content. The hash protects
-against stale anchors: if the file changed between the read that produced the
-hash and the edit, the patcher refuses (or, with a `SnapshotStore`, tries
-session-aware recovery).
+Each file section starts with `¶PATH#TAG`. The tag is a 3-hex opaque
+pointer into the `SnapshotStore` that minted it; it is not content-derived
+and is not meaningful outside that store. The patcher protects against
+stale anchors by resolving the tag, verifying the recorded snapshot lines
+against live file content, and refusing or attempting session-aware
+recovery on mismatch.
 
-Inside a hunk:
-
-- `A-B:` — anchor lines A..B (single-anchor `A:` is sugar for `A-A:`).
-- `BOF:` / `EOF:` — virtual anchors at the beginning/end of file.
-- `|TEXT` — replace-bucket payload. A non-empty replace bucket replaces A..B.
-- `↑TEXT` — insert before A (`BOF:` treats `↑`/`↓` equivalently).
-- `↓TEXT` — insert after B (`EOF:` treats `↑`/`↓` equivalently).
+Inside a section:
+- `@@ A..B @@` — open a hunk on lines A..B (use `@@ A,A @@` for a single line; bare `@@ A @@` is also accepted).
+- `@@ BOF @@` / `@@ EOF @@` — virtual hunks at the beginning/end of file.
+- `+TEXT` — literal body row (use `+` alone for a blank line).
+- `&A..B` — repeat original file lines A..B inline (`&A` for one line).
+- Empty body — delete the selected range.
 
 ## Abstractions
 
@@ -67,9 +67,9 @@ text-document protocol, a Git tree, anything.
 
 ### `SnapshotStore`
 
-Optional. When provided to `Patcher`, hashline tries to recover from a stale
-section hash by replaying the edit against a cached pre-edit snapshot of the
-file and 3-way-merging onto the current content. See `recovery.ts`.
+Required. Hashline tags are opaque store pointers, so `Patcher` must receive
+the store that minted them. Recovery replays edits against the cached pre-edit
+snapshot and 3-way-merges onto current content when the live file diverged.
 
 ### `Patcher`
 

package/dist/types/apply.d.ts

@@ -1,9 +1,8 @@
-import type { ApplyOptions, ApplyResult, Edit } from "./types";
+import type { ApplyResult, Edit } from "./types";
 /**
  * Apply a parsed list of edits to a text body. Pure function — no I/O.
  *
- * Returns the post-edit text, the first changed line number (1-indexed), and
- * any diagnostic warnings produced by the auto-absorb heuristics or by the
- * structural-boundary delete check. Throws if an anchor is out of bounds.
+ * Returns the post-edit text and the first changed line number (1-indexed).
+ * Throws if an anchor is out of bounds.
  */
-export declare function applyEdits(text: string, edits: Edit[], options?: ApplyOptions): ApplyResult;
+export declare function applyEdits(text: string, edits: Edit[]): ApplyResult;

package/dist/types/format.d.ts

@@ -1,61 +1,57 @@
 /**
- * Hashline format primitives: sigils, separators, regex fragments, and the
- * file-hash computation. These are the single source of truth for the
- * parser, the tokenizer, the prompt, and the formal grammar.
+ * Hashline format primitives: sigils, separators, regex fragments, and
+ * display helpers. These are the single source of truth for the parser, the
+ * tokenizer, the prompt, and the formal grammar.
  */
-/** Anchor terminator for every hashline operation block. */
-export declare const HL_OP_REPLACE = ":";
-/** Payload sigil for lines that replace the anchored range in place. */
-export declare const HL_PAYLOAD_REPLACE = "|";
-/** Payload sigil for lines inserted before the anchored range. */
-export declare const HL_PAYLOAD_ABOVE = "\u2191";
-/** Payload sigil for lines inserted after the anchored range. */
-export declare const HL_PAYLOAD_BELOW = "\u2193";
-/** All hashline payload sigils, concatenated for fast membership tests. */
-export declare const HL_PAYLOAD_CHARS = "|\u2191\u2193";
-/** Hashline edit file-section header marker. */
+/** File-section header prefix: `¶path#hash`. */
 export declare const HL_FILE_PREFIX = "\u00B6";
-/** Separator between a hashline file path and its file hash. */
+/** Payload sigil for literal body rows. */
+export declare const HL_PAYLOAD_REPLACE = "+";
+/** Payload sigil for body rows that repeat original file lines. */
+export declare const HL_PAYLOAD_REPEAT = "&";
+/** All hashline payload sigils, concatenated for fast membership tests. */
+export declare const HL_PAYLOAD_CHARS = "+&";
+/** Separator between a hashline file path and its opaque snapshot tag. */
 export declare const HL_FILE_HASH_SEP = "#";
+/** Separator between two line numbers in a range, e.g. `5..10`. */
+export declare const HL_RANGE_SEP = "..";
 /** Separator between a line number and displayed line content in hashline mode. */
 export declare const HL_LINE_BODY_SEP = ":";
 /**
  * Decoration prefix that may precede a line number in tool output:
- * `>` (context line in grep), `-` (removed line), `*` (match line).
- * Any combination, in any order, surrounded by optional whitespace. Output
- * formatters emit at most one decoration per line; the parser stays liberal
- * because it accepts whatever the model echoes back.
+ * `*` (match line), `>` (context line in grep). Any combination, in any
+ * order, surrounded by optional whitespace. Output formatters emit at most
+ * one decoration per line; the parser stays liberal because it accepts
+ * whatever the model echoes back.
  */
-export declare const HL_ANCHOR_DECORATION_RE_RAW = "\\s*[>\\-*]*\\s*";
+export declare const HL_ANCHOR_DECORATION_RE_RAW = "\\s*[>*]*\\s*";
 /** Capture-group regex source for a decorated bare line-number anchor. */
-export declare const HL_ANCHOR_RE_RAW = "\\s*[>\\-*]*\\s*(\\d+)";
+export declare const HL_ANCHOR_RE_RAW = "\\s*[>*]*\\s*(\\d+)";
 /** Bare positive line-number Lid (no decorations, no captures, no anchors). */
 export declare const HL_LINE_RE_RAW = "[1-9]\\d*";
 /** Capture-group form of {@link HL_LINE_RE_RAW}. */
 export declare const HL_LINE_CAPTURE_RE_RAW = "([1-9]\\d*)";
-/** Four-hex-character file hash carried by a hashline section header. */
-export declare const HL_FILE_HASH_RE_RAW = "[0-9a-f]{4}";
+/** Regex for repeat payload rows (`&A..B`). */
+export declare const HL_PAYLOAD_REPEAT_RE: RegExp;
+/** Number of hex characters in an opaque snapshot tag. */
+export declare const HL_FILE_HASH_LENGTH = 3;
+/** Canonical uppercase hexadecimal opaque snapshot tag carried by a hashline section header. */
+export declare const HL_FILE_HASH_RE_RAW = "[0-9A-F]{3}";
 /** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
-export declare const HL_FILE_HASH_CAPTURE_RE_RAW = "([0-9a-f]{4})";
+export declare const HL_FILE_HASH_CAPTURE_RE_RAW = "([0-9A-F]{3})";
 /** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
 export declare const HL_LINE_BODY_SEP_RE_RAW: string;
 /**
- * Representative file hashes for use in user-facing error messages and prompt
- * examples.
+ * Representative snapshot tags for use in user-facing error messages and
+ * prompt examples.
  */
-export declare const HL_FILE_HASH_EXAMPLES: readonly ["1a2b", "3c4d", "9f3e"];
+export declare const HL_FILE_HASH_EXAMPLES: readonly ["0A3", "1F7", "3C9"];
 /**
  * Format a comma-separated list of example anchors with an optional line-number
  * prefix, quoted for inclusion in error messages: `"160", "42", "7"`.
  */
 export declare function describeAnchorExamples(linePrefix?: string): string;
-/**
- * Compute the 4-hex-character hash carried by a hashline section header. The
- * hash normalizes CR characters and trailing whitespace before hashing so
- * platform line endings and display-trimmed lines do not invalidate anchors.
- */
-export declare function computeFileHash(text: string): string;
-/** Format a hashline section header for a file path and file hash. */
+/** Format a hashline section header for a file path and snapshot tag. */
 export declare function formatHashlineHeader(filePath: string, fileHash: string): string;
 /** Formats a single numbered line as `LINE:TEXT`. */
 export declare function formatNumberedLine(lineNumber: number, line: string): string;

package/dist/types/input.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyOptions, ApplyResult, Edit, SplitOptions } from "./types";
+import type { ApplyResult, Edit, SplitOptions } from "./types";
 interface RawSection {
     path: string;
     fileHash?: string;
@@ -36,21 +36,21 @@ export declare class PatchSection {
     /** Warnings emitted during parsing of this section. */
     get warnings(): readonly string[];
     /**
-     * True when at least one edit anchors to a concrete file line (range or
-     * before/after_anchor insert). Pure BOF/EOF inserts do not count: those
-     * are safe to apply to files that don't yet exist.
+     * True when at least one edit anchors to concrete file content. Pure BOF/EOF
+     * literal inserts do not count: those are safe to apply to files that don't
+     * yet exist.
      */
     get hasAnchorScopedEdit(): boolean;
     /** Anchor lines touched by this section, sorted ascending and deduplicated. */
     collectAnchorLines(): readonly number[];
     /**
      * Apply this section's edits to `text` and return the post-edit result.
-     * Pure: does no I/O, does not validate the section file hash. The
-     * {@link Patcher} owns hash validation and recovery; reach for this
+     * Pure: does no I/O, does not validate the section snapshot tag. The
+     * {@link Patcher} owns tag validation and recovery; reach for this
      * method directly when you've already validated the file content and
      * just want the result.
      */
-    applyTo(text: string, options?: ApplyOptions): ApplyResult;
+    applyTo(text: string): ApplyResult;
     /**
      * Streaming-tolerant counterpart to {@link applyTo}. Uses
      * {@link parsePatchStreaming} so a trailing in-flight op (no payload yet,
@@ -58,7 +58,7 @@ export declare class PatchSection {
      * empty-payload edit. Intended for incremental diff previews; the writer
      * path should always use {@link applyTo}.
      */
-    applyPartialTo(text: string, options?: ApplyOptions): ApplyResult;
+    applyPartialTo(text: string): ApplyResult;
 }
 /**
  * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted

package/dist/types/messages.d.ts

@@ -13,24 +13,54 @@ 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 additionally surfaces a warning
- * so the caller knows to re-issue any remaining edits.
+ * parsing — terminates the line loop — and does not surface a warning.
  */
 export declare const ABORT_MARKER = "*** Abort";
-/** Warning text appended to the tool result when {@link ABORT_MARKER} terminates parsing. */
-export declare const ABORT_WARNING = "Tool stream truncated mid-call due to detected output corruption. Applied ops above are valid. Re-issue any remaining edits.";
 /**
- * Warning text appended when two consecutive blocks target the exact same
- * concrete range. The second block wins; the first block is discarded.
+ * Warning text appended when two consecutive hunks target the exact same
+ * concrete range. The second hunk wins; the first is discarded.
  */
-export declare const REPLACE_PAIR_COALESCED_WARNING = "Detected two identical-range hashline blocks; kept only the second block. Issue ONE block per range \u2014 payload is the final desired content, never both old and new.";
-/** Error text prefix emitted when an anchor line carries inline payload. */
-export declare const INLINE_PAYLOAD_REJECTED_PREFIX = "Inline payload on the anchor line is rejected.";
-/** Error text emitted when `|` replacement payload targets BOF/EOF. */
-export declare const VIRTUAL_REPLACE_REJECTED_MESSAGE = "BOF:/EOF: anchors are virtual positions and cannot use `|` replacement payload. Use `\u2191` or `\u2193` payload lines.";
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Detected two identical-range hashline hunks; kept only the second hunk. Issue ONE hunk per range \u2014 payload is the final desired content, never both old and new.";
+/**
+ * Warning text appended when a bare hunk header (`A B` with no body)
+ * is followed by an overlapping concrete hunk. The earlier bare hunk is
+ * dropped on the assumption that the model expressed an old/new pair across
+ * two hunks; only the second hunk's payload is applied.
+ */
+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 hunk per range \u2014 payload is the final desired content, never both old and new.";
+/**
+ * Warning text appended when bare body rows (no `+` / `&` prefix) follow a
+ * hunk header and the parser auto-converts them to `+literal` rows because
+ * no `+`/`&` row was present in the hunk. Helps the model learn the
+ * canonical body-row syntax while keeping the patch applying.
+ */
+export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Always start payload rows with `+TEXT` (literal) or `&A..B` (repeat) \u2014 pasting raw code as payload is not a portable shape.";
+/**
+ * Warning text emitted when a body row begins with `+&A..B` — the model
+ * mistakenly prefixed a repeat row with the `+` literal sigil. We reroute
+ * the row as a `&A..B` repeat so the patch still applies, then surface this
+ * warning so the model sees the mistake on the next turn.
+ */
+export declare const PLUS_PREFIXED_REPEAT_WARNING = "A body row started with `+&A..B`. `+` (literal text) and `&A..B` (repeat) are sibling row kinds \u2014 a row uses exactly one of them. Treated as `&A..B`; remove the leading `+` next time.";
+/**
+ * Warning text emitted when a hunk body contains unified-diff-style rows
+ * (`-old`, ` context`) and the parser silently converts them: `-` rows are
+ * dropped (the hunk header's range already deletes those lines), and the
+ * leading metadata-space on context rows is stripped once unified-diff
+ * mode is detected. Bare body rows are auto-prefixed with `+` regardless.
+ */
+export declare const UNIFIED_DIFF_BODY_AUTO_CONVERT_WARNING = "Hunk body contained unified-diff-style rows (`-old`, ` context`). The `-` rows were dropped (the hunk header's range already deletes those lines); context rows were treated as `+TEXT` literals. Use `+TEXT` (literal) or `&A..B` (repeat) directly next time.";
 /** Warning text emitted by `Recovery` when an external write fits 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).";
-/** Warning text emitted by `Recovery` when the session-chain fast-path was taken. */
+/**
+ * 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.
+ */
 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.";

package/dist/types/mismatch.d.ts

@@ -12,7 +12,7 @@ export interface MismatchDetails {
     anchorLines?: readonly number[];
 }
 /**
- * Raised when a hashline section's file hash doesn't match the live file's
+ * Raised when a hashline section's snapshot tag doesn't match the live file's
  * content (and recovery, if configured, declined the merge). Carries the
  * file lines plus anchored lines so renderers can produce a richer
  * diagnostic via {@link MismatchError.displayMessage}.

package/dist/types/parser.d.ts

@@ -4,10 +4,10 @@ import type { Edit } from "./types";
  * Token-driven state machine that turns a stream of {@link Token}s into a
  * flat list of {@link Edit}s.
  *
- * `feed()` accepts tokens one at a time; block payload rows accumulate until
- * the next anchor block or {@link end} flushes them. After `terminated` flips
- * true (on `envelope-end` or `abort`) subsequent feeds are silently ignored
- * so callers can keep draining their tokenizer.
+ * `feed()` accepts tokens one at a time; hunk body rows accumulate until
+ * the next hunk header or {@link end} flushes them. After `terminated`
+ * flips true (on `envelope-end` or `abort`) subsequent feeds are silently
+ * ignored so callers can keep draining their tokenizer.
  */
 export declare class Executor {
     #private;
@@ -20,13 +20,13 @@ export declare class Executor {
      */
     feed(token: Token): void;
     /**
-     * Flush any open pending block and return the accumulated edits and
-     * warnings. The executor is single-use; {@link reset} is required for reuse.
+     * Flush any open pending hunk and return the accumulated edits and
+     * warnings. The executor is single-use; {@link reset} is required for
+     * reuse.
      *
-     * Throws if two replacement/delete blocks target the same line with
-     * non-identical ranges. Identical-range blocks in the same hunk are
-     * coalesced last-wins by `feed()` with a warning, so they never reach the
-     * validator.
+     * Throws if two hunks target the same line with non-identical ranges.
+     * Identical-range hunks in the same patch are coalesced last-wins by
+     * `feed()` with a warning, so they never reach the validator.
      */
     end(): {
         edits: Edit[];
@@ -34,9 +34,9 @@ export declare class Executor {
     };
     /**
      * Streaming-tolerant variant of {@link end}. Identical, except a pending
-     * block whose payload has not yet accumulated any rows is treated as still
-     * in flight and dropped instead of flushed (which would otherwise preview a
-     * destructive bare delete while the model may still be typing payload).
+     * hunk whose body has not yet accumulated any rows is treated as still
+     * in flight and dropped instead of flushed (which would otherwise commit
+     * a destructive delete while the model may still be typing payload).
      */
     endStreaming(): {
         edits: Edit[];
@@ -61,14 +61,14 @@ export declare function parsePatch(diff: string): {
  * parsed successfully when the diff is still being typed:
  *
  * - per-token feed errors stop the drain but preserve the edits already
- *   collected (the trailing block is malformed mid-stream — wait for the next
- *   chunk),
- * - the trailing pending block is dropped if it has no payload yet (avoids a
- *   destructive bare-delete preview while payload may still be coming).
+ *   collected (the trailing hunk is malformed mid-stream — wait for the
+ *   next chunk),
+ * - the trailing pending hunk is dropped if it has no payload yet (avoids
+ *   a destructive bare-delete preview while payload may still be coming).
  *
- * Throws only on the cross-block overlap validator, which catches conflicting
- * shapes (two replacements/deletes hitting the same anchor). Streaming preview
- * callers should treat any throw here as "no preview this tick".
+ * Throws only on the cross-hunk overlap validator, which catches conflicting
+ * shapes (two hunks hitting the same anchor). Streaming preview callers
+ * should treat any throw here as "no preview this tick".
  */
 export declare function parsePatchStreaming(diff: string): {
     edits: Edit[];

package/dist/types/patcher.d.ts

@@ -3,21 +3,12 @@ import type { Patch, PatchSection } from "./input";
 import { type LineEnding } from "./normalize";
 import { Recovery } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyOptions, ApplyResult } from "./types";
+import type { ApplyResult } from "./types";
 export interface PatcherOptions {
     /** Storage backend used for all reads and writes. */
     fs: Filesystem;
-    /**
-     * Optional snapshot store that enables stale-hash recovery. When set, a
-     * section with a stale hash tries a 3-way merge against a cached
-     * snapshot before the apply fails with {@link MismatchError}.
-     */
-    snapshots?: SnapshotStore;
-    /**
-     * Optional default {@link ApplyOptions} forwarded to every section.
-     * Per-call overrides win on a key-by-key basis.
-     */
-    applyOptions?: ApplyOptions;
+    /** Snapshot store that minted and resolves hashline section tags. Required. */
+    snapshots: SnapshotStore;
 }
 /** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
 export interface PatchSectionResult {
@@ -35,9 +26,9 @@ export interface PatchSectionResult {
     persisted: string;
     /** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
     written: string;
-    /** 4-hex hash of `after`. Use to anchor follow-up edits. */
+    /** 3-hex opaque snapshot tag for `after`. Use to anchor follow-up edits. */
     fileHash: string;
-    /** Hashline section header (`¶path#hash`) of the post-edit content. */
+    /** Hashline section header (`¶path#tag`) of the post-edit content. */
     header: string;
     /** 1-indexed first changed line in `after`, or `undefined` for noops. */
     firstChangedLine?: number;
@@ -68,7 +59,7 @@ export declare class PreparedSection {
     get isNoop(): boolean;
 }
 /**
- * High-level patcher. Wires a {@link Filesystem} and an optional
+ * High-level patcher. Wires a {@link Filesystem} and a required
  * {@link SnapshotStore} together with the parsing + applying core.
  *
  * Construct once per FS configuration; reuse across patches.
@@ -76,9 +67,8 @@ export declare class PreparedSection {
 export declare class Patcher {
     #private;
     readonly fs: Filesystem;
-    readonly snapshots: SnapshotStore | undefined;
-    readonly recovery: Recovery | undefined;
-    readonly applyOptions: ApplyOptions;
+    readonly snapshots: SnapshotStore;
+    readonly recovery: Recovery;
     constructor(options: PatcherOptions);
     /**
      * Apply every section in `patch`. `prepare` runs the full apply for each
@@ -86,27 +76,27 @@ export declare class Patcher {
      * multi-section batch is naturally all-or-nothing. Returns one
      * {@link PatchSectionResult} per section in the original patch order.
      */
-    apply(patch: Patch, options?: ApplyOptions): Promise<PatcherApplyResult>;
+    apply(patch: Patch): Promise<PatcherApplyResult>;
     /**
      * Run the preflight pass only: read, parse, validate, apply-in-memory.
      * No writes hit the filesystem. Use for CI checks and dry runs.
      */
-    preflight(patch: Patch, options?: ApplyOptions): Promise<void>;
+    preflight(patch: Patch): Promise<void>;
     /**
-     * Read a section's target file, parse the section, validate the file
-     * hash (with recovery), and apply the edits in memory. Returns a
+     * Read a section's target file, parse the section, validate the snapshot
+     * tag (with recovery), and apply the edits in memory. Returns a
      * {@link PreparedSection} which can be fed to {@link commit} to land
      * the result on the filesystem.
      *
      * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
-     * hash mismatch ({@link MismatchError}).
+     * tag mismatch ({@link MismatchError}).
      */
-    prepare(section: PatchSection, options?: ApplyOptions): Promise<PreparedSection>;
+    prepare(section: PatchSection): Promise<PreparedSection>;
     /**
      * Commit a previously {@link prepare}d section to the filesystem.
      * Restores line endings and BOM, writes via the {@link Filesystem}, and
-     * records a fresh snapshot in the {@link SnapshotStore} (when
-     * configured) keyed by the filesystem-canonical path.
+     * records a fresh snapshot in the {@link SnapshotStore} keyed by the
+     * filesystem-canonical path.
      */
     commit(prepared: PreparedSection): Promise<PatchSectionResult>;
 }

package/dist/types/recovery.d.ts

@@ -1,11 +1,10 @@
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyOptions, Edit } from "./types";
+import type { Edit } from "./types";
 export interface RecoveryArgs {
     path: string;
     currentText: string;
     fileHash: string;
     edits: readonly Edit[];
-    options?: ApplyOptions;
 }
 export interface RecoveryResult {
     /** Post-recovery text. */
@@ -22,10 +21,15 @@ export interface RecoveryResult {
  *
  * 1. Apply on the cached `fullText` snapshot, then 3-way-merge onto current.
  * 2. (Session chain) If the snapshot wasn't the head, retry on current text
- *    when line counts match — the user's previous edit advanced the hash but
- *    didn't shift line numbers.
- * 3. Reconstruct from a sparse snapshot (lines map only), verify the rebuilt
- *    text hashes to the expected value, then 3-way-merge.
+ *    when line counts match AND every edit's anchor line content is unchanged
+ *    between snapshot and current — the previous in-session edit advanced
+ *    the hash 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}.
+ * 3. Reconstruct from a sparse snapshot (lines map only), then 3-way-merge.
+ *    Sparse snapshots that still match the live file are direct-apply cases
+ *    owned by the patcher, so recovery declines them.
  */
 export declare class Recovery {
     readonly store: SnapshotStore;