pi-hashline-edit-pro 0.14.1 → 0.15.0

package/README.md

@@ -92,8 +92,13 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
 - **Batched atomicity (bulk mode).** All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
 
-### Chained edits
+### Stable hashing across edits
+
+Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro/hash-store.json`) that preserves hashes for unchanged lines across edits. When you replace lines in a file, the runtime diffs the old content against the new content and copies hashes for unchanged lines to their new positions. This means editing one part of a file does not change the hashes of unrelated lines elsewhere — the model can keep using previously seen anchors for untouched regions.
 
+The store contains per-file snapshots: the last known content and hashes for each file. On read, if the file content matches the snapshot, the saved hashes are returned immediately. Stale snapshots (for files that no longer exist) are pruned on session start.
+
+### Chained edits
 After a successful replace, the response confirms with `Successfully replaced in {path}.` (warnings are still shown if present). To get fresh anchors for follow-up edits, call `read` on the file first. This avoids token overhead from re-displaying content the model already knows.
 
 ### Auto-read after write
@@ -140,7 +145,7 @@ The file is created automatically when any setting is toggled. Both fields are i
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 - **Boundary duplication warnings.** When the last line of a replacement matches the next surviving line (or the first line matches the preceding one), a warning is emitted. This catches a common LLM pattern where closing delimiters like `}`, `});`, or `} else {` are accidentally duplicated. The warning is a short header followed by a hashline-anchored window: the duplicated pair plus 2 lines of context before and after, shown as plain `HASH│content` rows with post-edit hashes. Seeing the duplication in context (rather than just being told a hash) is what prompts the model to act on it — and since the hashes are current and staleness is per-line, the model can remove the duplicate in one follow-up `replace` without re-reading. No autocorrection is applied — the duplicate stays in the file and the model decides whether to remove it. Raw line comparison (not trimmed) avoids false positives when indentation differs.
 - **Flat mode normalization.** When flat mode is active, the tool's `execute` function wraps the top-level `hash_range_inclusive` and `content_lines` into a single-element `changes` array internally, then runs the same pipeline as bulk mode. The `normReq` function in `replace-normalize.ts` also handles flat format directly, so any code path that normalizes input (e.g. `compPreview`) works with both formats.
-
+- **Persistent hash store.** `lineHashes` is async and uses a persistent store to preserve hashes for unchanged lines across edits. The store is at `~/.config/pi-hashline-edit-pro/hash-store.json` and is auto-created on first use. It contains per-file snapshots (last known content+hashes). When called from the replace pipeline, it diffs old vs new content and copies hashes for unchanged lines. When called from read, it returns saved hashes if the content matches, otherwise computes fresh hashes via `_lineHashesPure`. Stale snapshots are pruned on session start. This ensures that editing one part of a file does not cascade to change hashes of unrelated lines.
 ## Hashing
 
 Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32 via WebAssembly), then mapped to a 3-character string from the URL-safe base64 alphabet `A-Za-z0-9-_`. That's 64 distinct characters, 6 bits per position, 18 bits of entropy per anchor.
@@ -148,9 +153,7 @@ Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (
 The alphabet is sized for an LLM consumer. The model tokenizes, it doesn't squint at pixel glyphs, so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply. The full 64 chars give maximum entropy per character, with case and digits included.
 
 **Perfect hashing (collision resolution):** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the hash is incremented (using a retry counter: `:R{retry}`) until a unique hash is found. This ensures every line in a file gets a unique anchor, even with the shorter 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
-
-The runtime always precomputes the full per-line hash array for a file via `lineHashes(content)`, then looks up by line number during validation and during `read` / `replace` response formatting. There is no per-line recomputation that could disagree with what the model saw in its last read.
-
+The runtime always precomputes the full per-line hash array for a file via `lineHashes(content, path)`, then looks up by line number during validation and during `read` / `replace` response formatting. There is no per-line recomputation that could disagree with what the model saw in its last read. When `path` is provided, `lineHashes` uses a persistent store to preserve hashes for unchanged lines across edits — see [Stable hashing across edits](#stable-hashing-across-edits).
 `HASH_LEN` in `src/hashline/hash.ts` sets the hash body length; bump it to 4 if you need even more entropy without collision resolution.
 
 ### Bare-prefix detector

package/index.ts

@@ -14,6 +14,7 @@ import {
   readAutoRead,
   toggleAutoRead,
 } from "./src/config";
+import { loadHashStore, pruneHashStore } from "./src/hash-store";
 
 export default function (pi: ExtensionAPI): void {
   regRead(pi);
@@ -31,7 +32,11 @@ export default function (pi: ExtensionAPI): void {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
     await initHasher();
-
+    // Prune stale snapshots (files that no longer exist) on session start
+    try {
+      const store = await loadHashStore();
+      await pruneHashStore(store);
+    } catch { /* best-effort */ }
     // Re-register the replace tool according to the persisted mode
     const mode = await readReplaceMode();
     if (mode === "flat") {
@@ -93,8 +98,7 @@ export default function (pi: ExtensionAPI): void {
 
       if (visLines(normalized).length === 0) return;
 
-      const preview = fmtReadPreview(normalized, { limit: AUTO_READ_MAX });
-      if (!preview.text) return;
+      const preview = await fmtReadPreview(normalized, { limit: AUTO_READ_MAX }, undefined, absolutePath);
 
       return {
         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/src/file-reader.ts

@@ -46,8 +46,7 @@ export async function readNormFile(
 		}
 	}
 
-	const fileHashes = lineHashes(normalized);
-
+	const fileHashes = await lineHashes(normalized, absolutePath);
 	return {
 		absolutePath,
 		normalized,

package/src/hash-store.ts

@@ -0,0 +1,61 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { stat } from "fs/promises";
+
+export interface FileSnapshot {
+  content: string;
+  hashes: string[];
+}
+
+export interface HashStore {
+  version: 1;
+  snapshots: Record<string, FileSnapshot>;
+}
+
+function storePath(): string {
+  return join(homedir(), ".config", "pi-hashline-edit-pro", "hash-store.json");
+}
+
+function storeDir(): string {
+  return dirname(storePath());
+}
+
+export async function loadHashStore(): Promise<HashStore> {
+  try {
+    const content = await readFile(storePath(), "utf-8");
+    const parsed = JSON.parse(content) as Partial<HashStore>;
+    return {
+      version: 1,
+      snapshots: parsed.snapshots ?? {},
+    };
+  } catch {
+    await mkdir(storeDir(), { recursive: true });
+    const defaultStore: HashStore = {
+      version: 1,
+      snapshots: {},
+    };
+    await writeFile(storePath(), JSON.stringify(defaultStore), "utf-8");
+    return defaultStore;
+  }
+}
+
+export async function saveHashStore(store: HashStore): Promise<void> {
+  await mkdir(storeDir(), { recursive: true });
+  await writeFile(storePath(), JSON.stringify(store, null, 2), "utf-8");
+}
+
+export async function pruneHashStore(store: HashStore): Promise<void> {
+  let changed = false;
+  for (const filePath of Object.keys(store.snapshots)) {
+    try {
+      await stat(filePath);
+    } catch {
+      delete store.snapshots[filePath];
+      changed = true;
+    }
+  }
+  if (changed) {
+    await saveHashStore(store);
+  }
+}

package/src/hashline/apply.ts

@@ -1,5 +1,5 @@
 import { abortIf } from "../runtime";
-import { lineHashes, HASH_SEP } from "./hash";
+import { _lineHashesPure, HASH_SEP } from "./hash";
 import {
 	valEdits,
 	assertNoBarePrefix,
@@ -272,9 +272,9 @@ export function applyEdits(
 	content: string;
 	firstChangedLine: number | undefined;
 	lastChangedLine: number | undefined;
-	resultHashes?: string[];
 	warnings?: string[];
 	noopEdits?: NEdit[];
+	boundaryWarnings?: BDupWarn[];
 } {
 	abortIf(signal);
 	if (!edits.length)
@@ -292,7 +292,7 @@ export function applyEdits(
   );
 
 	const lineIndex = buildIdx(content);
-	const fileHashes = precomputedHashes ?? lineHashes(content);
+	const fileHashes = precomputedHashes ?? _lineHashesPure(content);
 	const noopEdits: NEdit[] = [];
 	const warnings: string[] = [];
 
@@ -324,37 +324,13 @@ export function applyEdits(
 	assertNotEmpty(content, result);
 	const range = changedRange(content, result);
 
-	const resultLines = result.split("\n");
-	const resultHashes = lineHashes(result);
-	for (const bw of boundaryWarnings) {
-		let seen = 0;
-		let matchIndex = -1;
-		for (let i = 0; i < resultLines.length; i++) {
-			if (resultLines[i] === bw.survivingLineContent) {
-				if (seen === bw.occurrence) { matchIndex = i; break; }
-				seen++;
-			}
-		}
-		if (matchIndex >= 0) {
-			warnings.push(
-				fmtBoundaryWarning({
-					kind: bw.kind,
-					survivingContent: bw.survivingLineContent,
-					matchIndex,
-					resultLines,
-					resultHashes,
-				}),
-			);
-		}
-	}
-
 	return {
 		content: result,
 		firstChangedLine: range?.firstChangedLine,
 		lastChangedLine: range?.lastChangedLine,
-		resultHashes,
 		...(warnings.length ? { warnings } : {}),
 		...(noopEdits.length ? { noopEdits } : {}),
+		...(boundaryWarnings.length ? { boundaryWarnings } : {}),
 	};
 }
 

package/src/hashline/hash.ts

@@ -1,4 +1,6 @@
 import xxhash from "xxhash-wasm";
+import * as Diff from "diff";
+import { loadHashStore, saveHashStore } from "../hash-store";
 
 export const HASH_LEN = 3;
 export const ANCHOR_LEN = HASH_LEN;
@@ -73,8 +75,8 @@ function canon(line: string): string {
 }
 
 /**
- * Compute a unique 3-character hash for every line of `content`.
- *
+ * Pure hash computation — no I/O, no persistence. Used internally by the
+ * stable path and as a fallback when no file path is available.
  * Each line is hashed with xxHash32 over its canonical form (trailing
  * whitespace and CR characters stripped). If the base hash collides with a
  * hash already assigned to an earlier line, a retry counter (`:R{retry}`)
@@ -83,7 +85,7 @@ function canon(line: string): string {
  * in a file receives a distinct anchor, even when multiple lines contain
  * identical text (e.g. repeated `}` or `import` statements).
  */
-export function lineHashes(content: string): string[] {
+export function _lineHashesPure(content: string): string[] {
 	const lines = content.split("\n");
 	const hashes = new Array<string>(lines.length);
 	const assigned = new Set<string>();
@@ -101,5 +103,113 @@ export function lineHashes(content: string): string[] {
 	return hashes;
 }
 
+/**
+ * Stable, persistent-aware hash computation.
+ *
+ * When `path` is provided, uses the persistent hash store to preserve
+ * hashes for unchanged lines across edits. When `previous` is also
+ * provided (called from the replace pipeline), diffs the previous content
+ * against the new content and copies hashes for unchanged lines to their
+ * new positions. New/changed lines allocate fresh hashes with collision
+ * avoidance against the preserved set.
+ *
+ * When `path` is provided without `previous` (called from read), loads
+ * the stored snapshot for that path. If the content matches, returns the
+ * saved hashes. Otherwise computes fresh hashes via `_lineHashesPure` and
+ * saves a new snapshot.
+ *
+ * When `path` is not provided, falls back to `_lineHashesPure` (for
+ * backward compatibility and tests that don't need persistence).
+ */
+export async function lineHashes(
+  content: string,
+  path?: string,
+  previous?: { content: string; hashes: string[] },
+): Promise<string[]> {
+  if (!path) {
+    return _lineHashesPure(content);
+  }
+
+  const store = await loadHashStore();
+
+  // Case 1: previous content provided (replace pipeline) — diff and preserve
+  if (previous) {
+    const newHashes = mapStableHashes(
+      previous.content, previous.hashes,
+      content,
+    );
+    store.snapshots[path] = { content, hashes: newHashes };
+    await saveHashStore(store);
+    return newHashes;
+  }
+
+  // Case 2: no previous — check snapshot or compute fresh
+  const snapshot = store.snapshots[path];
+  if (snapshot && snapshot.content === content) {
+    return snapshot.hashes;
+  }
+
+  // Compute fresh hashes
+  const newHashes = _lineHashesPure(content);
+  store.snapshots[path] = { content, hashes: newHashes };
+  await saveHashStore(store);
+  return newHashes;
+}
+
+/**
+ * Diff old content against new content, preserving hashes for unchanged
+ * lines. New/changed lines allocate fresh hashes with collision avoidance.
+ */
+function mapStableHashes(
+  oldContent: string,
+  oldHashes: string[],
+  newContent: string,
+): string[] {
+  const newLines = newContent.split("\n");
+  const newHashes = new Array<string>(newLines.length);
+  const used = new Set<string>();
+
+  const parts = Diff.diffLines(oldContent, newContent);
+  let oldIdx = 0;
+  let newIdx = 0;
+
+  for (const part of parts) {
+    const raw = part.value.split("\n");
+    if (raw[raw.length - 1] === "") raw.pop();
+    const count = raw.length;
+    if (count === 0) continue;
+
+    if (part.added) {
+      newIdx += count;
+    } else if (part.removed) {
+      oldIdx += count;
+    } else {
+      // unchanged — copy hashes
+      for (let k = 0; k < count; k++) {
+        const h = oldHashes[oldIdx]!;
+        newHashes[newIdx] = h;
+        used.add(h);
+        oldIdx++;
+        newIdx++;
+      }
+    }
+  }
+
+  // Fill remaining (new/changed) lines with fresh hashes
+  for (let i = 0; i < newLines.length; i++) {
+    if (newHashes[i]) continue;
+    const c = canon(newLines[i]!);
+    let retry = 0;
+    let hash = h2s(xxh32(c));
+    while (used.has(hash)) {
+      retry++;
+      hash = h2s(xxh32(`${c}:R${retry}`));
+    }
+    used.add(hash);
+    newHashes[i] = hash;
+  }
+
+  return newHashes;
+}
 
 export { ALPH_RE };

package/src/hashline/index.ts

@@ -8,6 +8,7 @@ export {
 	DIFF_MINUS_RE,
 	HL_BARE_PREFIX_RE,
 	lineHashes,
+	_lineHashesPure,
 	initHasher,
 } from "./hash";
 

package/src/read.ts

@@ -57,26 +57,26 @@ export function formatPaginationHint(
 	return `[Showing lines ${startLine}-${endLine} of ${totalLines}${sizeSuffix}. Use offset=${nextOffset} to continue.]`;
 }
 
-export function fmtReadPreview(
+export async function fmtReadPreview(
 	text: string,
 	options: { offset?: number; limit?: number },
 	precomputedHashes?: string[],
-): { text: string; truncation?: TruncationResult; nextOffset?: number } {
+	path?: string,
+): Promise<{ text: string; truncation?: TruncationResult; nextOffset?: number }> {
 	const allLines = visLines(text);
 	const totalLines = allLines.length;
 	const startLine = normPosInt(options.offset, "offset") ?? 1;
 	if (totalLines === 0) {
 		if (startLine === 1) {
-			const allHashes = precomputedHashes ?? lineHashes(text);
-			const emptyLineHash = allHashes[0] ?? "";
-			return {
+      const allHashes = precomputedHashes ?? await (path ? lineHashes(text, path) : lineHashes(text));
+      const emptyLineHash = allHashes[0] ?? "";
+      return {
 				text: `${emptyLineHash}${HASH_SEP}\n[File is empty. Use replace to insert content.]`,
 			};
 		}
 		return {
 			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use replace to insert content.`,
 		};
-
 	}
 	if (startLine > totalLines) {
 		return {
@@ -89,7 +89,7 @@ export function fmtReadPreview(
 		? Math.min(startLine - 1 + limit, totalLines)
 		: totalLines;
 	const selected = allLines.slice(startLine - 1, endIdx);
-	const allHashes = precomputedHashes ?? lineHashes(text);
+	const allHashes = precomputedHashes ?? await (path ? lineHashes(text, path) : lineHashes(text));
 	const selectedHashes = allHashes.slice(startLine - 1, endIdx);
 	const formatted = fmtRegion(selectedHashes, selected);
 
@@ -171,13 +171,14 @@ export function regRead(pi: ExtensionAPI): void {
 			const { normalized, fileHashes, hadUtf8DecodeErrors } = await readNormFile(
 				rawPath, ctx.cwd, signal, undefined, file,
 			);
-			const preview = fmtReadPreview(
+			const preview = await fmtReadPreview(
 				normalized,
 				{
 					offset: params.offset,
 					limit: params.limit,
 				},
 				fileHashes,
+				absolutePath,
 			);
 			const snapshot = await fileSnap(absolutePath);
 

package/src/replace-diff.ts

@@ -1,6 +1,6 @@
 import * as Diff from "diff";
 import {
-  lineHashes,
+  _lineHashesPure,
   ANCHOR_LEN,
   HASH_SEP,
 } from "./hashline";
@@ -48,8 +48,7 @@ export function genDiff(
 ): { diff: string; firstChangedLine: number | undefined } {
   const parts = Diff.diffLines(oldContent, newContent);
   const output: string[] = [];
-  const effectiveNewHashes = newContentHashes ?? lineHashes(newContent);
-
+  const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
   let oldLineNum = 1;
   let newLineNum = 1;
   let lastWasChange = false;

package/src/replace-flat.ts

@@ -17,7 +17,6 @@ import { MAX_HASH_LINES } from "./constants";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import {
   applyEdits,
-  lineHashes,
   resEdits,
   type HTEdit,
 } from "./hashline";

package/src/replace-response.ts

@@ -1,8 +1,5 @@
 import type { ReplaceDetails } from "./replace";
 import { genDiff } from "./replace-diff";
-import {
-	lineHashes,
-} from "./hashline";
 import { visLines } from "./utils";
 
 type TResult = {
@@ -46,7 +43,7 @@ export interface SuccessInput {
 	path: string;
 	originalNormalized: string;
 	result: string;
-	resultHashes?: string[];
+	resultHashes: string[];
 	warnings: string[] | undefined;
 	snapshotId: string;
 	editMeta: RMeta;
@@ -142,10 +139,9 @@ export function buildNoop(input: NoopInput): TResult {
 }
 
 export function buildChanged(input: SuccessInput): TResult {
-	const { path, result, warnings, snapshotId, originalNormalized, editMeta } = input;
+	const { path, result, warnings, snapshotId, originalNormalized, editMeta, resultHashes } = input;
 
 	const resultLines = visLines(result);
-	const resultHashes = input.resultHashes ?? lineHashes(result);
 	const diffResult = genDiff(originalNormalized, result, 2, resultHashes);
 	const addedLines = cntDiff(diffResult.diff, "+");
 	const removedLines = cntDiff(diffResult.diff, "-");

package/src/replace.ts

@@ -18,6 +18,7 @@ import { resolveTarget, writeAtomic } from "./fs-write";
 import {
   applyEdits,
   lineHashes,
+  fmtBoundaryWarning,
   resEdits,
   type HTEdit,
 } from "./hashline";
@@ -101,7 +102,7 @@ interface PipelineResult {
   firstChangedLine?: number;
   lastChangedLine?: number;
   originalHashes?: string[];
-  resultHashes?: string[];
+  resultHashes: string[];
 }
 
 const ROOT_KS = new Set(["path", "changes"]);
@@ -152,6 +153,7 @@ export async function execPipeline(
     path, cwd, signal, accessMode, undefined, MAX_HASH_LINES,
   );
 
+  const absolutePath = toCwd(path, cwd);
   const resolved = resEdits(toolEdits);
   const anchorResult = applyEdits(
     originalNormalized,
@@ -161,19 +163,52 @@ export async function execPipeline(
     path,
   );
 
+  const result = anchorResult.content;
+
+  // Compute stable result hashes using diff-based preservation
+  const resultHashes = await lineHashes(result, absolutePath, {
+    content: originalNormalized,
+    hashes: originalHashes,
+  });
+
+  // Format boundary warnings using stable result hashes
+  const resultLines = result.split("\n");
+  const warnings = [...(anchorResult.warnings ?? [])];
+  for (const bw of anchorResult.boundaryWarnings ?? []) {
+    let seen = 0;
+    let matchIndex = -1;
+    for (let i = 0; i < resultLines.length; i++) {
+      if (resultLines[i] === bw.survivingLineContent) {
+        if (seen === bw.occurrence) { matchIndex = i; break; }
+        seen++;
+      }
+    }
+    if (matchIndex >= 0) {
+      warnings.push(
+        fmtBoundaryWarning({
+          kind: bw.kind,
+          survivingContent: bw.survivingLineContent,
+          matchIndex,
+          resultLines,
+          resultHashes,
+        }),
+      );
+    }
+  }
+
   return {
     path,
     toolEdits,
     originalNormalized,
-    result: anchorResult.content,
+    result,
     bom,
     originalEnding,
     hadUtf8DecodeErrors,
-    warnings: [...(anchorResult.warnings ?? [])],
+    warnings,
     noopEdits: anchorResult.noopEdits,
     firstChangedLine: anchorResult.firstChangedLine,
     lastChangedLine: anchorResult.lastChangedLine,
-    resultHashes: anchorResult.resultHashes,
+    resultHashes,
     originalHashes,
   };
 }