opencode-hashline 1.2.0 → 1.3.0

package/README.en.md

@@ -104,6 +104,49 @@ if (!result.valid) {
 
 Hash verification uses the length of the provided hash reference (not the current file size), so a reference like `2:f1` remains valid even if the file has grown.
 
+### 🔒 File Revision (`fileRev`)
+
+In addition to per-line hashes, hashline computes a whole-file hash (FNV-1a, 8 hex chars). It's prepended as the first annotation line:
+
+```
+#HL REV:72c4946c
+#HL 1:a3f|function hello() {
+#HL 2:f1c|  return "world";
+```
+
+Pass `fileRev` to `hashline_edit` when editing — if the file changed since it was read, the edit is rejected with `FILE_REV_MISMATCH`.
+
+### 🔄 Safe Reapply
+
+If a line moved (e.g., due to insertions above), `safeReapply` finds it by content hash:
+
+- **1 candidate** — edit applies at the new position
+- **>1 candidates** — `AMBIGUOUS_REAPPLY` error (ambiguous)
+- **0 candidates** — `HASH_MISMATCH` error
+
+```typescript
+const result = applyHashEdit(
+  { operation: "replace", startRef: "1:a3f", replacement: "new" },
+  content,
+  undefined,
+  true, // safeReapply
+);
+```
+
+### 🏷️ Structured Errors
+
+All hashline errors are instances of `HashlineError` with error codes, diagnostics, and hints:
+
+| Code | Description |
+|------|-------------|
+| `HASH_MISMATCH` | Line content changed since last read |
+| `FILE_REV_MISMATCH` | File was modified since last read |
+| `AMBIGUOUS_REAPPLY` | Multiple candidates found during safe reapply |
+| `TARGET_OUT_OF_RANGE` | Line number exceeds file length |
+| `INVALID_REF` | Malformed hash reference |
+| `INVALID_RANGE` | Start line is after end line |
+| `MISSING_REPLACEMENT` | Replace/insert operation without content |
+
 ### 🔍 Indentation-Sensitive Hashing
 
 Hash computation uses `trimEnd()` (not `trim()`), so changes to leading whitespace (indentation) are detected as content changes, while trailing whitespace is ignored.
@@ -155,6 +198,8 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | `hashLength` | `number \| undefined` | `undefined` (adaptive) | Force specific hash length |
 | `cacheSize` | `number` | `100` | Max files in LRU cache |
 | `prefix` | `string \| false` | `"#HL "` | Line prefix (`false` to disable) |
+| `fileRev` | `boolean` | `true` | Include file revision hash (`#HL REV:...`) in annotations |
+| `safeReapply` | `boolean` | `false` | Auto-relocate moved lines by content hash |
 
 Default exclude patterns cover: lock files, `node_modules`, minified files, binary files (images, fonts, archives, etc.).
 
@@ -442,9 +487,12 @@ The idea behind hashline is inspired by concepts from **oh-my-pi** by [can1357](
 
 Hashline solves this by assigning each line a short, deterministic hash tag (e.g. `2:f1c`), making line addressing **exact and unambiguous**. The model can reference any line or range precisely, eliminating off-by-one errors and duplicate-line confusion.
 
+The advanced features — **file revision** (`fileRev`), **safe reapply**, and **structured errors** — are inspired by the hash-based editing implementation in **AssistAgents** by [OzeroHAX](https://github.com/OzeroHAX/AssistAgents), which independently applied a similar approach for OpenCode with additional integrity checks and error diagnostics.
+
 **References:**
 - [oh-my-pi by can1357](https://github.com/can1357/oh-my-pi) — AI coding agent toolkit: coding agent CLI, unified LLM API, TUI libraries
 - [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — blog post describing the problem in detail
+- [AssistAgents by OzeroHAX](https://github.com/OzeroHAX/AssistAgents) — hash-based editing for OpenCode with file revision, safe reapply, and structured conflicts
 - [Описание подхода на Хабре](https://habr.com/ru/companies/bothub/news/995986/) — overview of the approach in Russian
 
 ---

package/README.md

@@ -104,6 +104,49 @@ if (!result.valid) {
 
 Верификация хешей использует длину предоставленной хеш-ссылки (а не текущий размер файла), поэтому ссылка вроде `2:f1` остаётся валидной даже если файл вырос.
 
+### 🔒 Ревизия файла (`fileRev`)
+
+Помимо построчных хешей, hashline вычисляет хеш всего файла (FNV-1a, 8 hex-символов). Он добавляется первой строкой аннотации:
+
+```
+#HL REV:72c4946c
+#HL 1:a3f|function hello() {
+#HL 2:f1c|  return "world";
+```
+
+При редактировании передайте `fileRev` в `hashline_edit` — если файл изменился с момента чтения, правка будет отклонена с ошибкой `FILE_REV_MISMATCH`.
+
+### 🔄 Safe Reapply
+
+Если строка переместилась (например, из-за вставки строк выше), `safeReapply` находит её по хешу контента:
+
+- **1 кандидат** — правка применяется к новой позиции
+- **>1 кандидатов** — ошибка `AMBIGUOUS_REAPPLY` (неоднозначность)
+- **0 кандидатов** — ошибка `HASH_MISMATCH`
+
+```typescript
+const result = applyHashEdit(
+  { operation: "replace", startRef: "1:a3f", replacement: "new" },
+  content,
+  undefined,
+  true, // safeReapply
+);
+```
+
+### 🏷️ Structured Errors
+
+Все ошибки hashline — экземпляры `HashlineError` с кодом, диагностикой и подсказками:
+
+| Код | Описание |
+|-----|----------|
+| `HASH_MISMATCH` | Содержимое строки изменилось |
+| `FILE_REV_MISMATCH` | Файл модифицирован с момента чтения |
+| `AMBIGUOUS_REAPPLY` | Несколько кандидатов при safe reapply |
+| `TARGET_OUT_OF_RANGE` | Номер строки за пределами файла |
+| `INVALID_REF` | Некорректная хеш-ссылка |
+| `INVALID_RANGE` | Начало диапазона после конца |
+| `MISSING_REPLACEMENT` | Операция replace/insert без содержимого |
+
 ### 🔍 Чувствительность к отступам
 
 Вычисление хеша использует `trimEnd()` (а не `trim()`), поэтому изменения ведущих пробелов (отступов) обнаруживаются как изменения содержимого, а завершающие пробелы игнорируются.
@@ -155,6 +198,8 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | `hashLength` | `number \| undefined` | `undefined` (адаптивно) | Принудительная длина хеша |
 | `cacheSize` | `number` | `100` | Макс. файлов в LRU-кеше |
 | `prefix` | `string \| false` | `"#HL "` | Префикс строки (`false` для отключения) |
+| `fileRev` | `boolean` | `true` | Включать ревизию файла (`#HL REV:...`) в аннотации |
+| `safeReapply` | `boolean` | `false` | Автоматический поиск перемещённых строк по хешу |
 
 Паттерны исключения по умолчанию: lock-файлы, `node_modules`, минифицированные файлы, бинарные файлы (изображения, шрифты, архивы и т.д.).
 
@@ -417,9 +462,12 @@ npm run typecheck
 
 Hashline решает эту проблему, присваивая каждой строке короткий детерминированный хеш-тег (например, `2:f1c`), что делает адресацию строк **точной и однозначной**. Модель может ссылаться на любую строку или диапазон без ошибок смещения и путаницы с дубликатами.
 
+Продвинутые фичи — **ревизия файла** (`fileRev`), **safe reapply** и **structured errors** — вдохновлены реализацией hash-based editing в проекте **AssistAgents** от [OzeroHAX](https://github.com/OzeroHAX/AssistAgents), который независимо применил аналогичный подход для OpenCode с дополнительными механизмами проверки целостности и диагностики ошибок.
+
 **Ссылки:**
 - [oh-my-pi от can1357](https://github.com/can1357/oh-my-pi) — AI-тулкит для разработки: coding agent CLI, unified LLM API, TUI-библиотеки
 - [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — блог-пост с подробным описанием проблемы
+- [AssistAgents от OzeroHAX](https://github.com/OzeroHAX/AssistAgents) — hash-based editing для OpenCode с file revision, safe reapply и structured conflicts
 - [Статья на Хабре](https://habr.com/ru/companies/bothub/news/995986/) — описание подхода на русском языке
 
 ---

package/dist/{chunk-VPCMHCTB.js → chunk-7KUPGN4M.js}

@@ -4,7 +4,7 @@ import {
   resolveConfig,
   shouldExclude,
   stripHashes
-} from "./chunk-I6RACR3D.js";
+} from "./chunk-DOR4YDIS.js";
 
 // src/hooks.ts
 import { appendFileSync } from "fs";
@@ -94,7 +94,7 @@ function createFileReadAfterHook(cache, config) {
         return;
       }
     }
-    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix);
+    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix, resolved.fileRev);
     output.output = annotated;
     debug("annotated", typeof filePath === "string" ? filePath : input.tool, "lines:", content.split("\n").length);
     if (cache && typeof filePath === "string") {
@@ -206,10 +206,32 @@ function createSystemPromptHook(config) {
         '- Hash references include both the line number AND the content hash, so `2:f1c` means "line 2 with hash f1c".',
         "- If you see a mismatch, do NOT proceed with the edit \u2014 re-read the file to get fresh references.",
         "",
+        "### File revision (`#HL REV:<hash>`):",
+        "- When files are read, the first line may contain a file revision header: `" + prefix + "REV:<8-char-hex>`.",
+        "- This is a hash of the entire file content. Pass it as the `fileRev` parameter to `hashline_edit` to verify the file hasn't changed.",
+        "- If the file was modified between read and edit, the revision check fails with `FILE_REV_MISMATCH` \u2014 re-read the file.",
+        "",
+        "### Safe reapply (`safeReapply`):",
+        "- Pass `safeReapply: true` to `hashline_edit` to enable automatic line relocation.",
+        "- If a line moved (e.g., due to insertions above), safe reapply finds it by content hash.",
+        "- If exactly one match is found, the edit proceeds at the new location.",
+        "- If multiple matches exist, the edit fails with `AMBIGUOUS_REAPPLY` \u2014 re-read the file.",
+        "",
+        "### Structured error codes:",
+        "- `HASH_MISMATCH` \u2014 line content changed since last read",
+        "- `FILE_REV_MISMATCH` \u2014 file was modified since last read",
+        "- `AMBIGUOUS_REAPPLY` \u2014 multiple candidate lines found during safe reapply",
+        "- `TARGET_OUT_OF_RANGE` \u2014 line number exceeds file length",
+        "- `INVALID_REF` \u2014 malformed hash reference",
+        "- `INVALID_RANGE` \u2014 start line is after end line",
+        "- `MISSING_REPLACEMENT` \u2014 replace/insert operation without replacement content",
+        "",
         "### Best practices:",
         "- Use hash references for all edit operations to ensure precision.",
         "- When making multiple edits, work from bottom to top to avoid line number shifts.",
-        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines."
+        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines.",
+        "- Use `fileRev` to guard against stale edits on critical files.",
+        "- Use `safeReapply: true` when editing files that may have shifted due to earlier edits."
       ].join("\n")
     );
   };

package/dist/{chunk-I6RACR3D.js → chunk-DOR4YDIS.js}

@@ -56,7 +56,9 @@ var DEFAULT_CONFIG = {
   // 0 = adaptive
   cacheSize: 100,
   prefix: DEFAULT_PREFIX,
-  debug: false
+  debug: false,
+  fileRev: true,
+  safeReapply: false
 };
 function resolveConfig(config, pluginConfig) {
   const merged = {
@@ -72,9 +74,55 @@ function resolveConfig(config, pluginConfig) {
     hashLength: merged.hashLength ?? DEFAULT_CONFIG.hashLength,
     cacheSize: merged.cacheSize ?? DEFAULT_CONFIG.cacheSize,
     prefix: merged.prefix !== void 0 ? merged.prefix : DEFAULT_CONFIG.prefix,
-    debug: merged.debug ?? DEFAULT_CONFIG.debug
+    debug: merged.debug ?? DEFAULT_CONFIG.debug,
+    fileRev: merged.fileRev ?? DEFAULT_CONFIG.fileRev,
+    safeReapply: merged.safeReapply ?? DEFAULT_CONFIG.safeReapply
   };
 }
+var HashlineError = class extends Error {
+  code;
+  expected;
+  actual;
+  candidates;
+  hint;
+  lineNumber;
+  filePath;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "HashlineError";
+    this.code = opts.code;
+    this.expected = opts.expected;
+    this.actual = opts.actual;
+    this.candidates = opts.candidates;
+    this.hint = opts.hint;
+    this.lineNumber = opts.lineNumber;
+    this.filePath = opts.filePath;
+  }
+  toDiagnostic() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.filePath) {
+      parts.push(`  File: ${this.filePath}`);
+    }
+    if (this.lineNumber !== void 0) {
+      parts.push(`  Line: ${this.lineNumber}`);
+    }
+    if (this.expected !== void 0 && this.actual !== void 0) {
+      parts.push(`  Expected hash: ${this.expected}`);
+      parts.push(`  Actual hash:   ${this.actual}`);
+    }
+    if (this.candidates && this.candidates.length > 0) {
+      parts.push(`  Candidates (${this.candidates.length}):`);
+      for (const c of this.candidates) {
+        const preview = c.content.length > 60 ? c.content.slice(0, 60) + "..." : c.content;
+        parts.push(`    - line ${c.lineNumber}: ${preview}`);
+      }
+    }
+    if (this.hint) {
+      parts.push(`  Hint: ${this.hint}`);
+    }
+    return parts.join("\n");
+  }
+};
 function fnv1aHash(str) {
   let hash = 2166136261;
   for (let i = 0; i < str.length; i++) {
@@ -104,7 +152,49 @@ function computeLineHash(idx, line, hashLen = 3) {
   const hash = raw % modulus;
   return hash.toString(16).padStart(hashLen, "0");
 }
-function formatFileWithHashes(content, hashLen, prefix) {
+function computeFileRev(content) {
+  const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
+  const hash = fnv1aHash(normalized);
+  return hash.toString(16).padStart(8, "0");
+}
+function extractFileRev(annotatedContent, prefix) {
+  const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
+  const escapedPrefix = effectivePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^${escapedPrefix}REV:([0-9a-f]{8})$`);
+  const firstLine = annotatedContent.split("\n")[0];
+  const match = firstLine.match(pattern);
+  return match ? match[1] : null;
+}
+function verifyFileRev(expectedRev, currentContent) {
+  const actualRev = computeFileRev(currentContent);
+  if (actualRev !== expectedRev) {
+    throw new HashlineError({
+      code: "FILE_REV_MISMATCH",
+      message: `File revision mismatch: expected "${expectedRev}", got "${actualRev}". The file has changed since it was last read.`,
+      expected: expectedRev,
+      actual: actualRev,
+      hint: "Re-read the file to get fresh hash references and a new file revision."
+    });
+  }
+}
+function findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+  const effectiveLen = hashLen && hashLen >= 2 ? hashLen : expectedHash.length;
+  const originalIdx = originalLineNumber - 1;
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (i === originalIdx) continue;
+    const candidateHash = computeLineHash(originalIdx, lines[i], effectiveLen);
+    if (candidateHash === expectedHash) {
+      candidates.push({
+        lineNumber: i + 1,
+        // 1-based
+        content: lines[i]
+      });
+    }
+  }
+  return candidates;
+}
+function formatFileWithHashes(content, hashLen, prefix, includeFileRev) {
   const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
   const effectiveLen = hashLen && hashLen >= 3 ? hashLen : getAdaptiveHashLength(lines.length);
@@ -128,9 +218,14 @@ function formatFileWithHashes(content, hashLen, prefix) {
       hashes[idx] = hash;
     }
   }
-  return lines.map((line, idx) => {
+  const annotatedLines = lines.map((line, idx) => {
     return `${effectivePrefix}${idx + 1}:${hashes[idx]}|${line}`;
-  }).join("\n");
+  });
+  if (includeFileRev) {
+    const rev = computeFileRev(content);
+    annotatedLines.unshift(`${effectivePrefix}REV:${rev}`);
+  }
+  return annotatedLines.join("\n");
 }
 var stripRegexCache = /* @__PURE__ */ new Map();
 function stripHashes(content, prefix) {
@@ -141,9 +236,10 @@ function stripHashes(content, prefix) {
     hashLinePattern = new RegExp(`^([+ \\-])?${escapedPrefix}\\d+:[0-9a-f]{2,8}\\|`);
     stripRegexCache.set(escapedPrefix, hashLinePattern);
   }
+  const revPattern = new RegExp(`^${escapedPrefix}REV:[0-9a-f]{8}$`);
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
-  const result = normalized.split("\n").map((line) => {
+  const result = normalized.split("\n").filter((line) => !revPattern.test(line)).map((line) => {
     const match = line.match(hashLinePattern);
     if (match) {
       const patchMarker = match[1] || "";
@@ -157,7 +253,10 @@ function parseHashRef(ref) {
   const match = ref.match(/^(\d+):([0-9a-f]{2,8})$/);
   if (!match) {
     const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-    throw new Error(`Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`);
+    throw new HashlineError({
+      code: "INVALID_REF",
+      message: `Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`
+    });
   }
   return {
     line: parseInt(match[1], 10),
@@ -175,9 +274,10 @@ function normalizeHashRef(ref) {
     return `${parseInt(annotated[1], 10)}:${annotated[2].toLowerCase()}`;
   }
   const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-  throw new Error(
-    `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
-  );
+  throw new HashlineError({
+    code: "INVALID_REF",
+    message: `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
+  });
 }
 function buildHashMap(content, hashLen) {
   const lines = content.split("\n");
@@ -190,50 +290,97 @@ function buildHashMap(content, hashLen) {
   }
   return map;
 }
-function verifyHash(lineNumber, hash, currentContent, hashLen, lines) {
+function verifyHash(lineNumber, hash, currentContent, hashLen, lines, safeReapply) {
   const contentLines = lines ?? currentContent.split("\n");
   const effectiveLen = hashLen && hashLen >= 2 ? hashLen : hash.length;
   if (lineNumber < 1 || lineNumber > contentLines.length) {
     return {
       valid: false,
+      code: "TARGET_OUT_OF_RANGE",
       message: `Line ${lineNumber} is out of range (file has ${contentLines.length} lines)`
     };
   }
   const idx = lineNumber - 1;
   const actualHash = computeLineHash(idx, contentLines[idx], effectiveLen);
   if (actualHash !== hash) {
+    const candidates = findCandidateLines(lineNumber, hash, contentLines, effectiveLen);
+    if (safeReapply && candidates.length === 1) {
+      return {
+        valid: true,
+        relocatedLine: candidates[0].lineNumber,
+        candidates
+      };
+    }
+    if (safeReapply && candidates.length > 1) {
+      return {
+        valid: false,
+        code: "AMBIGUOUS_REAPPLY",
+        expected: hash,
+        actual: actualHash,
+        candidates,
+        message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". Found ${candidates.length} candidate lines \u2014 ambiguous reapply.`
+      };
+    }
     return {
       valid: false,
+      code: "HASH_MISMATCH",
       expected: hash,
       actual: actualHash,
+      candidates,
       message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". The file may have changed since it was read.`
     };
   }
   return { valid: true };
 }
-function resolveRange(startRef, endRef, content, hashLen) {
+function resolveRange(startRef, endRef, content, hashLen, safeReapply) {
   const start = parseHashRef(startRef);
   const end = parseHashRef(endRef);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines);
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
+  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
-  const rangeLines = lines.slice(start.line - 1, end.line);
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
+  }
+  const rangeLines = lines.slice(effectiveStartLine - 1, effectiveEndLine);
   return {
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     lines: rangeLines,
     content: rangeLines.join(lineEnding)
   };
@@ -249,22 +396,37 @@ function replaceRange(startRef, endRef, content, replacement, hashLen) {
   const result = [...before, ...replacementLines, ...after].join("\n");
   return lineEnding === "\r\n" ? result.replace(/\n/g, "\r\n") : result;
 }
-function applyHashEdit(input, content, hashLen) {
+function applyHashEdit(input, content, hashLen, safeReapply) {
   const lineEnding = detectLineEnding(content);
   const workContent = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
+  if (input.fileRev) {
+    verifyFileRev(input.fileRev, workContent);
+  }
   const normalizedStart = normalizeHashRef(input.startRef);
   const start = parseHashRef(normalizedStart);
   const lines = workContent.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
   if (input.operation === "insert_before" || input.operation === "insert_after") {
     if (input.replacement === void 0) {
-      throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+      throw new HashlineError({
+        code: "MISSING_REPLACEMENT",
+        message: `Operation "${input.operation}" requires "replacement" content`
+      });
     }
     const insertionLines = input.replacement.split("\n");
-    const insertIndex = input.operation === "insert_before" ? start.line - 1 : start.line;
+    const insertIndex = input.operation === "insert_before" ? effectiveStartLine - 1 : effectiveStartLine;
     const next2 = [
       ...lines.slice(0, insertIndex),
       ...insertionLines,
@@ -272,34 +434,54 @@ function applyHashEdit(input, content, hashLen) {
     ].join("\n");
     return {
       operation: input.operation,
-      startLine: start.line,
-      endLine: start.line,
+      startLine: effectiveStartLine,
+      endLine: effectiveStartLine,
       content: lineEnding === "\r\n" ? next2.replace(/\n/g, "\r\n") : next2
     };
   }
   const normalizedEnd = normalizeHashRef(input.endRef ?? input.startRef);
   const end = parseHashRef(normalizedEnd);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines);
+  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
+  }
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
   }
   const replacement = input.operation === "delete" ? "" : input.replacement;
   if (replacement === void 0) {
-    throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+    throw new HashlineError({
+      code: "MISSING_REPLACEMENT",
+      message: `Operation "${input.operation}" requires "replacement" content`
+    });
   }
-  const before = lines.slice(0, start.line - 1);
-  const after = lines.slice(end.line);
+  const before = lines.slice(0, effectiveStartLine - 1);
+  const after = lines.slice(effectiveEndLine);
   const replacementLines = input.operation === "delete" ? [] : replacement.split("\n");
   const next = [...before, ...replacementLines, ...after].join("\n");
   return {
     operation: input.operation,
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     content: lineEnding === "\r\n" ? next.replace(/\n/g, "\r\n") : next
   };
 }
@@ -396,7 +578,7 @@ function createHashline(config) {
         const cached = cache.get(filePath, content);
         if (cached) return cached;
       }
-      const result = formatFileWithHashes(content, hl, pfx);
+      const result = formatFileWithHashes(content, hl, pfx, resolved.fileRev);
       if (filePath) {
         cache.set(filePath, content, result);
       }
@@ -412,16 +594,16 @@ function createHashline(config) {
       return buildHashMap(content, hl);
     },
     verifyHash(lineNumber, hash, currentContent) {
-      return verifyHash(lineNumber, hash, currentContent, hl);
+      return verifyHash(lineNumber, hash, currentContent, hl, void 0, resolved.safeReapply);
     },
     resolveRange(startRef, endRef, content) {
-      return resolveRange(startRef, endRef, content, hl);
+      return resolveRange(startRef, endRef, content, hl, resolved.safeReapply);
     },
     replaceRange(startRef, endRef, content, replacement) {
       return replaceRange(startRef, endRef, content, replacement, hl);
     },
     applyHashEdit(input, content) {
-      return applyHashEdit(input, content, hl);
+      return applyHashEdit(input, content, hl, resolved.safeReapply);
     },
     normalizeHashRef(ref) {
       return normalizeHashRef(ref);
@@ -431,6 +613,18 @@ function createHashline(config) {
     },
     shouldExclude(filePath) {
       return shouldExclude(filePath, resolved.exclude);
+    },
+    computeFileRev(content) {
+      return computeFileRev(content);
+    },
+    verifyFileRev(expectedRev, currentContent) {
+      return verifyFileRev(expectedRev, currentContent);
+    },
+    extractFileRev(annotatedContent) {
+      return extractFileRev(annotatedContent, pfx);
+    },
+    findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+      return findCandidateLines(originalLineNumber, expectedHash, lines, hashLen);
     }
   };
 }
@@ -440,8 +634,13 @@ export {
   DEFAULT_PREFIX,
   DEFAULT_CONFIG,
   resolveConfig,
+  HashlineError,
   getAdaptiveHashLength,
   computeLineHash,
+  computeFileRev,
+  extractFileRev,
+  verifyFileRev,
+  findCandidateLines,
   formatFileWithHashes,
   stripHashes,
   parseHashRef,