@oh-my-pi/hashline 15.13.0 → 15.13.2

package/CHANGELOG.md

@@ -2,79 +2,156 @@
 
 ## [Unreleased]
 
+## [15.13.2] - 2026-06-15
+
 ### Breaking Changes
 
-- Changed `BlockResolution.isDelete` to `BlockResolution.op` (`"replace" | "delete" | "insert_after"`) so resolutions can describe every block-anchored op
-- Changed hashline file section headers from `¶PATH#TAG` to `[PATH#TAG]` so model-authored edits use ASCII delimiters instead of a pilcrow sigil.
+- Renamed all hashline DSL operators to concise abbreviated keywords:
+  - `replace` -> `SWAP`
+  - `delete` -> `DEL`
+  - `insert before`/`after`/`head`/`tail` -> `INS.PRE`/`POST`/`HEAD`/`TAIL`
+  - `replace_block` -> `SWAP.BLK`
+  - `delete_block` -> `DEL.BLK`
+  - `insert_after_block` -> `INS.BLK.POST`
+
+## [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
+
+- 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
 
 - Added inward landing correction for `insert after block N:`: a body indented deeper than the block's closing line now slides back across the block's trailing closer lines and lands inside the block at its claimed depth, with a warning naming the landing line. Same conservative guards as the outward shift — comparable indentation only, closers only, abandoned when another hunk targets a crossed line; plain `insert after M:` stays literal
 - Added closer-anchor lowering for `insert after block N:`: anchoring on a pure closing-delimiter line (where no block begins, so resolution previously failed the whole patch) now applies as plain `insert after N:` with a warning teaching the opener-only rule. `resolveBlockEdits` gained an `onWarning` callback; apply, preview, and patcher paths surface it on `warnings`
+
+### Changed
+
+- Condensed the edit-tool prompt: one-line op definitions, 5–20-word rules, and a tighter `<critical>` recap; landing-correction mechanics are no longer described to the agent
+
+## [15.11.1] - 2026-06-11
+
+### Fixed
+
+- Fixed the `insert after block N:` prompt guidance so it explicitly says N must be the block opener, not the closing delimiter or last visible line, and points visible closing-line edits to plain `insert after M:`. ([#2292](https://github.com/can1357/oh-my-pi/issues/2292))
+
+## [15.11.0] - 2026-06-10
+
+### Changed
+
+- Block-unresolved errors (`replace block N:` / `delete block N` / `insert after block N:` failing to resolve a syntactic block) now append a numbered preview of the file around the anchor line — same `*`-marked context rows the hash-mismatch error shows — so the offending line is visible without a re-read
+
+## [15.10.11] - 2026-06-10
+
+### Breaking Changes
+
+- Changed `BlockResolution.isDelete` to `BlockResolution.op` (`"replace" | "delete" | "insert_after"`) so resolutions can describe every block-anchored op
+
+### Added
+
 - Added `insert after block N:` patch syntax to insert body rows after the last line of the tree-sitter-resolved block beginning on line N, so a statement can be placed after a construct without counting to its closing line
 - Added depth-guided landing correction for `insert after N:` hunks: a body indented shallower than its anchor line slides past the structural closer lines below the anchor until depth returns to the body's level, with a warning naming the final landing line. The shift never crosses content lines, skips incomparable indentation styles and pure-closer bodies, and is abandoned when another hunk targets a crossed line
 - Added a global byte ceiling to `InMemorySnapshotStore` (`maxTotalBytes`, default 64 MiB): the cap was previously per-file only, so a session reading many large files retained up to 30 paths × 4 full-text versions indefinitely
-- Added `maxAddedRunContext` option to control how many added lines are shown at each side of collapsed inserted runs, with `maxUnchangedRun` kept as a backward-compatible alias
-- Added a `BlockResolution` type and surfaced resolved block spans on `ApplyResult.blockResolutions` / `PatchSectionResult.blockResolutions`. `resolveBlockEdits` now accepts an `onResolved` callback that reports each `replace block N:` / `delete block N` anchor's resolved `[start, end]` span (and whether it was a delete). Spans are surfaced only on the no-drift apply paths, where the resolved line numbers line up with the tag the caller read.
-- 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
-- Added `BlockResolver` support in `Patcher` and `PatchSection.applyTo`/`applyPartialTo` to wire language-specific block-resolution at apply time
-- Added `resolveBlockEdits` and block edit type definitions to the package API for resolving deferred `replace block` / `delete block` edits
 
 ### Changed
 
-- Condensed all parser/applier/patcher error and warning messages: shorter wording, same diagnostic anchors (op names, line numbers, suggested fallback forms)
-- Condensed the edit-tool prompt: one-line op definitions, 5–20-word rules, and a tighter `<critical>` recap; landing-correction mechanics are no longer described to the agent
-- Block-unresolved errors (`replace block N:` / `delete block N` / `insert after block N:` failing to resolve a syntactic block) now append a numbered preview of the file around the anchor line — same `*`-marked context rows the hash-mismatch error shows — so the offending line is visible without a re-read
 - Trimmed the `replace block N:` ops entry in the patch prompt to grammar and pointing rules; the usage doctrine it duplicated stays in the rules section
 - Changed `buildCompactDiffPreview` to treat blank rows as gap separators alongside `…` markers: separators never stack (removed lines omitted from the preview no longer leave two adjacent), and leading/trailing separators are trimmed
-- Changed `buildCompactDiffPreview` to omit removed lines from the preview while preserving removal counts for offset tracking
-- Changed `buildCompactDiffPreview` to collapse long contiguous added runs with a bare `…` marker, keeping only the first and last `maxAddedRunContext` lines visible (the surrounding line numbers convey how many were elided)
-- Reworked the `edit` tool prompt (`prompt.md`): added a `replace block N` vs `replace N..M` decision rule, documented that a leading decorator/attribute/doc-comment is a separate node not swept into the block (point N at the first decorator line, or use `replace N..M` for a Rust-style `///` sibling comment), reframed the blast-radius guidance so "block replace" no longer reads as the dangerous option, and added a decorated-definition example.
 
 ### Fixed
 
-- Normalized cwd-relative hashline paths to forward-slash form on Windows.
-- Fixed delimiter-balance boundary repair so it does not keep a deleted structural closer when the replacement payload already restates that closer.
-- Fixed the `insert after block N:` prompt guidance so it explicitly says N must be the block opener, not the closing delimiter or last visible line, and points visible closing-line edits to plain `insert after M:`. ([#2292](https://github.com/can1357/oh-my-pi/issues/2292))
 - Fixed the boundary-echo repair stripping payload edges without the balance-neutrality guard its own documentation promised: in brace-heavy code where bare `}` lines repeat, a payload intentionally beginning/ending with lines identical to the range's neighbors had both edges silently dropped, writing content that differed from what was authored
 - Fixed lenient bare-body handling silently mutating payloads: interior blank rows in an un-prefixed body were dropped outright, and a body of numeric-keyed literals (`1: "one"` dict/YAML shapes) satisfied the uniform line-prefix check and had its keys stripped from every line — blank rows are now preserved when proven interior, and the uniform strip refuses lone-literal remainders
 - Fixed the multi-section "all-or-nothing" claim being false for write failures: commits run serially, so a mid-batch write error left earlier sections on disk while the thrown error said nothing — the error now lists exactly which sections were written and which were not
 - Fixed `delete`/`replace` ranges ending on the phantom trailing line of a newline-terminated file silently stripping the file's final newline; such anchors are now rejected with guidance toward `N-1` / `insert tail:` (inserts there remain valid, and genuine empty last lines of unterminated files stay deletable)
-- Fixed compact edit previews to omit deleted content, keep visible lines anchored to the current file, and collapse long inserted runs with a bare `…` elision marker.
-- Fixed compact edit previews to render added/current lines without diff-prefix padding and normalize adjacent ASCII/Unicode elision markers to one `…`.
-- Stripped read-output line-number prefixes (`N:`) from auto-piped bare body rows so that pasting `3:text` without a `+` prefix no longer injects `3:` as literal content. Stripping is applied only when *every* bare row in the hunk carries the prefix (the signature of a pasted snapshot) and removes at most one prefix per row, so a genuine body that merely starts with `digits:` (YAML port maps, timestamps) is left intact ([#1492](https://github.com/can1357/oh-my-pi/issues/1492)).
-- Fixed missing-header diagnostics and copied-content prefix stripping to consistently teach and recognize 4-hex snapshot tags.
-- Fixed delimiter-balance boundary repair to also drop a single duplicated structural opener (e.g. a restated `foo(` / `if (x) {` signature line surviving just above the range), not only duplicated closers. Zero-balance duplicates remain untouched.
-- 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.13.0] - 2026-06-14
 
-## [15.12.5] - 2026-06-13
+## [15.10.5] - 2026-06-08
 
-## [15.12.0] - 2026-06-12
+### Added
 
-## [15.11.4] - 2026-06-12
+- Added `maxAddedRunContext` option to control how many added lines are shown at each side of collapsed inserted runs, with `maxUnchangedRun` kept as a backward-compatible alias
 
-## [15.11.1] - 2026-06-11
+### Changed
 
-## [15.11.0] - 2026-06-10
+- Changed `buildCompactDiffPreview` to omit removed lines from the preview while preserving removal counts for offset tracking
+- Changed `buildCompactDiffPreview` to collapse long contiguous added runs with a bare `…` marker, keeping only the first and last `maxAddedRunContext` lines visible (the surrounding line numbers convey how many were elided)
 
-## [15.10.11] - 2026-06-10
+### Fixed
 
-## [15.10.5] - 2026-06-08
+- Fixed compact edit previews to omit deleted content, keep visible lines anchored to the current file, and collapse long inserted runs with a bare `…` elision marker.
+- Fixed compact edit previews to render added/current lines without diff-prefix padding and normalize adjacent ASCII/Unicode elision markers to one `…`.
 
 ## [15.10.3] - 2026-06-08
 
+### Added
+
+- Added a `BlockResolution` type and surfaced resolved block spans on `ApplyResult.blockResolutions` / `PatchSectionResult.blockResolutions`. `resolveBlockEdits` now accepts an `onResolved` callback that reports each `replace block N:` / `delete block N` anchor's resolved `[start, end]` span (and whether it was a delete). Spans are surfaced only on the no-drift apply paths, where the resolved line numbers line up with the tag the caller read.
+
+### Changed
+
+- Reworked the `edit` tool prompt (`prompt.md`): added a `replace block N` vs `replace N..M` decision rule, documented that a leading decorator/attribute/doc-comment is a separate node not swept into the block (point N at the first decorator line, or use `replace N..M` for a Rust-style `///` sibling comment), reframed the blast-radius guidance so "block replace" no longer reads as the dangerous option, and added a decorated-definition example.
+
 ## [15.10.2] - 2026-06-08
 
+### Fixed
+
+- Stripped read-output line-number prefixes (`N:`) from auto-piped bare body rows so that pasting `3:text` without a `+` prefix no longer injects `3:` as literal content. Stripping is applied only when *every* bare row in the hunk carries the prefix (the signature of a pasted snapshot) and removes at most one prefix per row, so a genuine body that merely starts with `digits:` (YAML port maps, timestamps) is left intact ([#1492](https://github.com/can1357/oh-my-pi/issues/1492)).
+
 ## [15.9.67] - 2026-06-06
 
+### Breaking Changes
+
+- Changed hashline file section headers from `¶PATH#TAG` to `[PATH#TAG]` so model-authored edits use ASCII delimiters instead of a pilcrow sigil.
+
+### Fixed
+
+- Fixed missing-header diagnostics and copied-content prefix stripping to consistently teach and recognize 4-hex snapshot tags.
+
 ## [15.8.2] - 2026-06-03
 
+### Fixed
+
+- Fixed delimiter-balance boundary repair to also drop a single duplicated structural opener (e.g. a restated `foo(` / `if (x) {` signature line surviving just above the range), not only duplicated closers. Zero-balance duplicates remain untouched.
+
 ## [15.8.0] - 2026-06-02
 
+### Fixed
+
+- 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
+- Added `BlockResolver` support in `Patcher` and `PatchSection.applyTo`/`applyPartialTo` to wire language-specific block-resolution at apply time
+- 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
@@ -85,7 +162,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
 
@@ -153,7 +230,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
 
@@ -166,7 +243,7 @@
 
 ### 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.
 

package/README.md

@@ -26,7 +26,7 @@ await fs.writeText("hello.ts", before);
 const tag = snapshots.record("hello.ts", before);
 const patcher = new Patcher({ fs, snapshots });
 const patch = Patch.parse(String.raw`[hello.ts#${tag}]
-replace 1..1:
+SWAP 1..1:
 +const greeting = "hello";`);
 const result = await patcher.apply(patch);
 
@@ -47,11 +47,11 @@ still matches the recorded content hash, and refusing or attempting
 session-aware recovery on mismatch.
 
 Inside a section:
-- `replace A..B:` — replace lines A..B with following `+TEXT` body rows.
-- `replace block A:` — replace the syntactic block beginning on line A.
-- `delete A..B` / `delete block A` — delete concrete lines or a resolved block.
-- `insert before A:` / `insert after A:` / `insert head:` / `insert tail:` — insert following body rows.
-- `insert after block A:` — insert following body rows after the resolved block's last line.
+- `SWAP A..B:` — replace lines A..B with following `+TEXT` body rows.
+- `SWAP.BLK A:` — replace the syntactic block beginning on line A.
+- `DEL A..B` / `DEL.BLK A` — delete concrete lines or a resolved block.
+- `INS.PRE A:` / `INS.POST A:` / `INS.HEAD:` / `INS.TAIL:` — insert following body rows.
+- `INS.BLK.POST A:` — insert following body rows after the resolved block's last line.
 - `+TEXT` — literal body row (use `+` alone for a blank line).
 
 ## Abstractions

package/dist/types/block.d.ts

@@ -6,7 +6,7 @@ export interface ResolveBlockEditsOptions {
      * `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
+     * throw. Unresolvable `insert_after_block N:` edits never reach this: they
      * are lowered to plain `insert after N:` with a warning.
      */
     onUnresolved?: "throw" | "drop";
@@ -19,7 +19,7 @@ export interface ResolveBlockEditsOptions {
     onResolved?: (resolution: BlockResolution) => void;
     /**
      * Invoked once per diagnostic produced while resolving — currently the
-     * `insert after block N:` lowerings (closer anchor or unresolvable block).
+     * `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/format.d.ts

@@ -10,22 +10,25 @@ export declare const HL_FILE_SUFFIX = "]";
 /** Payload sigil for literal body rows. */
 export declare const HL_PAYLOAD_REPLACE = "+";
 /** Hunk-header keyword for concrete line replacement. */
-export declare const HL_REPLACE_KEYWORD = "replace";
-/** Hunk-header sub-keyword: `replace block N:` resolves N to a tree-sitter block range. */
-export declare const HL_BLOCK_KEYWORD = "block";
+export declare const HL_REPLACE_KEYWORD = "SWAP";
 /** Hunk-header keyword for concrete line deletion. */
-export declare const HL_DELETE_KEYWORD = "delete";
+export declare const HL_DELETE_KEYWORD = "DEL";
 /** Hunk-header keyword for insertion operations. */
-export declare const HL_INSERT_KEYWORD = "insert";
+export declare const HL_INSERT_KEYWORD = "INS";
 /** Insert position keyword for inserting before a concrete line. */
-export declare const HL_INSERT_BEFORE = "before";
+export declare const HL_INSERT_BEFORE = "PRE";
 /** Insert position keyword for inserting after a concrete line. */
-export declare const HL_INSERT_AFTER = "after";
+export declare const HL_INSERT_AFTER = "POST";
 /** Insert position keyword for inserting at the start of the file. */
-export declare const HL_INSERT_HEAD = "head";
+export declare const HL_INSERT_HEAD = "HEAD";
 /** Insert position keyword for inserting at the end of the file. */
-export declare const HL_INSERT_TAIL = "tail";
-/** Hunk-header terminator for body-bearing operations. */
+export declare const HL_INSERT_TAIL = "TAIL";
+/** Hunk-header keyword: `SWAP.BLK N:` resolves N to a tree-sitter block range and replaces its span. */
+export declare const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
+/** Hunk-header keyword: `DEL.BLK N` resolves N to a tree-sitter block range and deletes its span. */
+export declare const HL_DELETE_BLOCK_KEYWORD = "DEL.BLK";
+/** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
+export declare const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
 export declare const HL_HEADER_COLON = ":";
 /** Separator between a hashline file path and its opaque snapshot tag. */
 export declare const HL_FILE_HASH_SEP = "#";

package/dist/types/input.d.ts

@@ -50,7 +50,7 @@ export declare class PatchSection {
      * method directly when you've already validated the file content and
      * just want the result.
      *
-     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * `blockResolver` resolves any `replace_block N:` edits against `text`; an
      * unresolvable block throws (this is the final, authoritative preview path).
      */
     applyTo(text: string, blockResolver?: BlockResolver): ApplyResult;
@@ -61,7 +61,7 @@ export declare class PatchSection {
      * empty-payload edit. Intended for incremental diff previews; the writer
      * path should always use {@link applyTo}.
      *
-     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * `blockResolver` resolves any `replace_block N:` edits against `text`; an
      * unresolvable block is silently dropped so a half-written file does not
      * throw mid-stream.
      */

package/dist/types/messages.d.ts

@@ -17,51 +17,49 @@ export declare const END_PATCH_MARKER = "*** End Patch";
  */
 export declare const ABORT_MARKER = "*** Abort";
 /** 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.";
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the same range; kept only the second. One `SWAP 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`.";
-/** `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`.";
+export declare const EMPTY_REPLACE = "`SWAP N..M:` needs at least one `+TEXT` body row. To delete lines, use `DEL N..M`.";
+/** `replace_block N:` hunk with no body. */
+export declare const EMPTY_BLOCK = "`SWAP.BLK N:` needs at least one `+TEXT` body row. To delete a block, use `DEL.BLK N`.";
 /**
  * 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
+ * `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", 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.";
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST` are not available here (no block resolver configured). Use a concrete line range.";
 /**
- * `insert after block N:` anchored on a closing-delimiter line, lowered to
+ * `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 function insertAfterBlockCloserLoweredWarning(line: number): string;
 /**
- * `insert after block N:` anchor unresolvable (unsupported language, blank
+ * `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 insertAfterBlockUnresolvedLoweredWarning(line: number): string;
 /**
- * Internal invariant: `applyEdits` received an unresolved `replace block N:`
+ * 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).";
+export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `SWAP.BLK` edit reached the applier (resolveBlockEdits was not run).";
 /** 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:`.";
-/** `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:`.";
+export declare const DELETE_TAKES_NO_BODY = "`DEL N..M` does not take body rows. Remove the body, or use `SWAP N..M:`.";
+/** `delete_block N` hunk received a body row. */
+export declare const DELETE_BLOCK_TAKES_NO_BODY = "`DEL.BLK N` does not take body rows. Remove the body, or use `SWAP.BLK N:`.";
 /** Insert hunk with no body. */
-export declare const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
+export declare const EMPTY_INSERT = "`INS` needs at least one `+TEXT` body row.";
 /**
  * `insert after` body indented shallower than the anchor: the landing slid
  * forward past trailing closer lines — the common "anchored on the last line
@@ -69,7 +67,7 @@ export declare const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body ro
  */
 export declare function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string;
 /**
- * `insert after block N:` body indented deeper than the block's closer: the
+ * `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".
  */
@@ -90,9 +88,26 @@ export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying y
  * 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 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.";
+export declare const HEADTAIL_DRIFT_WARNING = "Applied the `INS.HEAD:`/`INS.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.";
 /**
  * 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;
+/**
+ * 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/patcher.d.ts

@@ -10,8 +10,8 @@ export interface PatcherOptions {
     /** Snapshot store that minted and resolves hashline section tags. Required. */
     snapshots: SnapshotStore;
     /**
-     * Resolves `replace block N:` anchors to concrete line spans via tree-sitter.
-     * Optional: when omitted, any `replace block N:` edit throws on apply (the
+     * Resolves `replace_block N:` anchors to concrete line spans via tree-sitter.
+     * Optional: when omitted, any `replace_block N:` edit throws on apply (the
      * host did not wire a resolver). Plain line-range ops never need it.
      */
     blockResolver?: BlockResolver;
@@ -41,7 +41,7 @@ export interface PatchSectionResult {
     /** Warnings collected by the parser, applier, and (optionally) recovery. */
     warnings: string[];
     /**
-     * Resolved spans for any `replace block`/`delete block` ops, present when the
+     * Resolved spans for any `replace_block`/`delete_block` ops, present when the
      * apply matched the tagged content. Undefined for patches with no block ops
      * (and for resolutions routed through drift recovery, where numbers shift).
      */

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/dist/types/types.d.ts

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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.13.0",
+	"version": "15.13.2",
 	"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",