pi-hashline-edit-pro 0.16.2 → 0.16.3

package/README.md

@@ -68,8 +68,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 {
   "path": "src/main.ts",
   "changes": [
-    { "hash_range_inclusive": ["ve7", "ve7"], "content_lines": ["  console.log('hashline');"] }
-  ]
+    { "content_lines": ["  console.log('hashline');"], "hash_range_inclusive": ["ve7", "ve7"] }
 }
 ```
 
@@ -77,9 +76,9 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ```json
 {
-  "path": "src/main.ts",
+  "content_lines": ["  console.log('hashline');"],
   "hash_range_inclusive": ["ve7", "ve7"],
-  "content_lines": ["  console.log('hashline');"]
+  "path": "src/main.ts"
 }
 ```
 
@@ -89,7 +88,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 | `content_lines` | Literal replacement content, one string per line (use `[]` to delete the range). |
 
 - **Request structure validation.** The request envelope (`path`, `changes` in bulk mode; `path`, `hash_range_inclusive`, `content_lines` in flat mode) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
-- **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: [...]}`.
+- **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 `{content_lines: [...], hash_range_inclusive: ["<START>", "<END>"]}`.
 - **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.
 
 ### Stable hashing across edits

package/index.ts

@@ -33,7 +33,9 @@ export default function (pi: ExtensionAPI): void {
     try {
       const store = await loadHashStore();
       await pruneHashStore(store);
-    } catch {}
+    } catch (err) {
+      console.error("Failed to load or prune hash store:", err);
+    }
     const mode = await readReplaceMode();
     if (mode === "flat") {
       regReplaceFlat(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "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/prompts/replace-bulk.md

@@ -11,64 +11,62 @@ read({ path: "src/main.ts" })
 
 2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
-] }
+{ "changes": [
+  { "content_lines": ["const x = 99;"], "hash_range_inclusive": ["MQX", "MQX"] }
+], "path": "src/main.ts" }
 ```
 
 Examples:
 
 1. Single line replace:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
-] }
+{ "changes": [
+  { "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"] }
+], "path": "src/main.ts" }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
+{ "changes": [
+  { "content_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
-  ] }
-] }
+  ], "hash_range_inclusive": ["ZPM", "VRW"] }
+], "path": "src/main.ts" }
 ```
 
 3. Multiple regions in one call (delete two non-adjacent ranges):
 ```json
-{ "path": "src/server.ts", "changes": [
-  { "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] },
-  { "hash_range_inclusive": ["MQX", "ZPM"], "content_lines": [] }
-] }
+{ "changes": [
+  { "content_lines": [], "hash_range_inclusive": ["aB3", "xY7"] },
+  { "content_lines": [], "hash_range_inclusive": ["MQX", "ZPM"] }
+], "path": "src/server.ts" }
 ```
 
 4. Append after the last line (include the old last line so the new line is added after it):
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
-] }
+{ "changes": [
+  { "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"] }
+], "path": "src/main.ts" }
 ```
 
 5. Seed content into an empty file (replace the single empty-line hash returned by read):
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
-] }
+{ "changes": [
+  { "content_lines": ["first line", "second line"], "hash_range_inclusive": ["aB3", "aB3"] }
+], "path": "src/main.ts" }
 ```
 
 ⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
-```
+{ "content_lines": ["F4T│import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
-```
+{ "content_lines": ["import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 `hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
@@ -76,13 +74,11 @@ Right:
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
@@ -107,14 +103,12 @@ function greet() {
 ```
 A model might write:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;", "}"], "hash_range_inclusive": ["X", "Y"] }
 This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
 
 Right: Only include the new lines that belong in the range:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;"], "hash_range_inclusive": ["X", "Y"] }
 The `}` on line 4 is outside the range and stays in place.
 
 Error recovery:
@@ -122,10 +116,10 @@ Error recovery:
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
 - `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{content_lines, hash_range_inclusive}` instead.
 - `[E_EDIT_CONFLICT]` — two changes overlap on the same line range. Make changes non-overlapping.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
-- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
+- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `content_lines` uses file content only, `hash_range_inclusive` uses hash anchors.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 - `[E_FILE_TOO_LARGE]` — file exceeds the 1,000,000-line edit limit. Use `write` or a non-line-based approach for very large files.

package/prompts/replace-flat.md

@@ -9,51 +9,49 @@ read({ path: "src/main.ts" })
 
 2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+{ "content_lines": ["const x = 99;"], "hash_range_inclusive": ["MQX", "MQX"], "path": "src/main.ts" }
 ```
 
 Examples:
 
 1. Single line replace:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+{ "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"], "path": "src/main.ts" }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
-  "function greet(name) {",
-  "  return `Hello, ${name}`;",
-  "}"
-] }
+{ "content_lines": [
+    "function greet(name) {",
+    "  return `Hello, ${name}`;",
+    "}"
+  ], "hash_range_inclusive": ["ZPM", "VRW"], "path": "src/main.ts" }
 ```
 
 3. Delete a range:
 ```json
-{ "path": "src/server.ts", "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] }
+{ "content_lines": [], "hash_range_inclusive": ["aB3", "xY7"], "path": "src/server.ts" }
 ```
 
 4. Append after the last line (include the old last line so the new line is added after it):
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+{ "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"], "path": "src/main.ts" }
 ```
 
 5. Seed content into an empty file (replace the single empty-line hash returned by read):
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+{ "content_lines": ["first line", "second line"], "hash_range_inclusive": ["aB3", "aB3"], "path": "src/main.ts" }
 ```
 
 ⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
-```
+{ "content_lines": ["F4T│import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
-```
+{ "content_lines": ["import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 `hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
@@ -61,13 +59,11 @@ Right:
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
@@ -93,14 +89,12 @@ function greet() {
 ```
 A model might write:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;", "}"], "hash_range_inclusive": ["X", "Y"] }
 This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
 
 Right: Only include the new lines that belong in the range:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;"], "hash_range_inclusive": ["X", "Y"] }
 The `}` on line 4 is outside the range and stays in place.
 
 Error recovery:
@@ -108,9 +102,9 @@ Error recovery:
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
 - `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{content_lines, hash_range_inclusive}` instead.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
-- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
+- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `content_lines` uses file content only, `hash_range_inclusive` uses hash anchors.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 - `[E_FILE_TOO_LARGE]` — file exceeds the 1,000,000-line edit limit. Use `write` or a non-line-based approach for very large files.

package/prompts/replace.md

@@ -21,14 +21,14 @@ read({ path: "src/main.ts" })
 
 **Bulk mode:**
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
-] }
+{ "changes": [
+  { "content_lines": ["const x = 99;"], "hash_range_inclusive": ["MQX", "MQX"] }
+], "path": "src/main.ts" }
 ```
 
 **Flat mode:**
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+{ "content_lines": ["const x = 99;"], "hash_range_inclusive": ["MQX", "MQX"], "path": "src/main.ts" }
 ```
 
 Examples:
@@ -37,85 +37,83 @@ Examples:
 
 Bulk:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
-] }
+{ "changes": [
+  { "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"] }
+], "path": "src/main.ts" }
 ```
 
 Flat:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+{ "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"], "path": "src/main.ts" }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 
 Bulk:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
+{ "changes": [
+  { "content_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
-  ] }
-] }
+  ], "hash_range_inclusive": ["ZPM", "VRW"] }
+], "path": "src/main.ts" }
 ```
 
 Flat:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
-  "function greet(name) {",
-  "  return `Hello, ${name}`;",
-  "}"
-] }
+{ "content_lines": [
+    "function greet(name) {",
+    "  return `Hello, ${name}`;",
+    "}"
+  ], "hash_range_inclusive": ["ZPM", "VRW"], "path": "src/main.ts" }
 ```
 
 3. Multiple regions in one call (bulk mode only — flat mode supports one edit per call):
 ```json
-{ "path": "src/server.ts", "changes": [
-  { "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] },
-  { "hash_range_inclusive": ["MQX", "ZPM"], "content_lines": [] }
-] }
+{ "changes": [
+  { "content_lines": [], "hash_range_inclusive": ["aB3", "xY7"] },
+  { "content_lines": [], "hash_range_inclusive": ["MQX", "ZPM"] }
+], "path": "src/server.ts" }
 ```
 
 4. Append after the last line (include the old last line so the new line is added after it):
 
 Bulk:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
-] }
+{ "changes": [
+  { "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"] }
+], "path": "src/main.ts" }
 ```
 
 Flat:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+{ "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"], "path": "src/main.ts" }
 ```
 
 5. Seed content into an empty file (replace the single empty-line hash returned by read):
 
 Bulk:
 ```json
-{ "path": "src/main.ts", "changes": [
-  { "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
-] }
+{ "changes": [
+  { "content_lines": ["first line", "second line"], "hash_range_inclusive": ["aB3", "aB3"] }
+], "path": "src/main.ts" }
 ```
 
 Flat:
 ```json
-{ "path": "src/main.ts", "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+{ "content_lines": ["first line", "second line"], "hash_range_inclusive": ["aB3", "aB3"], "path": "src/main.ts" }
 ```
 
 ⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
-```
+{ "content_lines": ["F4T│import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
-```
+{ "content_lines": ["import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
 
 `hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
@@ -123,13 +121,11 @@ Right:
 
 Wrong:
 ```json
-{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"] }
 
 Right:
 ```json
-{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
-```
+{ "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
@@ -156,14 +152,12 @@ function greet() {
 ```
 A model might write:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;", "}"], "hash_range_inclusive": ["X", "Y"] }
 This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
 
 Right: Only include the new lines that belong in the range:
 ```json
-{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
-```
+{ "content_lines": ["  const y = 2;", "  return y;"], "hash_range_inclusive": ["X", "Y"] }
 The `}` on line 4 is outside the range and stays in place.
 
 Error recovery:
@@ -171,10 +165,10 @@ Error recovery:
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
 - `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{content_lines, hash_range_inclusive}` instead.
 - `[E_EDIT_CONFLICT]` — two changes overlap on the same line range. Make changes non-overlapping.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
-- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
+- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `content_lines` uses file content only, `hash_range_inclusive` uses hash anchors.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 - `[E_FILE_TOO_LARGE]` — file exceeds the 1,000,000-line edit limit. Use `write` or a non-line-based approach for very large files.

package/src/file-reader.ts

@@ -6,7 +6,7 @@ import { toCwd } from "./path-utils";
 import { detectEnding, toLF, stripBOM } from "./replace-diff";
 import { abortIf } from "./runtime";
 import { assertText, valAccess } from "./validation";
-
+import { visLines } from "./utils";
 export interface NormFile {
   absolutePath: string;
   normalized: string;
@@ -40,7 +40,7 @@ export async function readNormFile(
   const normalized = toLF(rawContent);
 
   if (maxLines !== undefined) {
-    const lineCount = normalized.split("\n").length;
+    const lineCount = visLines(normalized).length;
     if (lineCount > maxLines) {
       throw new Error(
         `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,

package/src/hashline/resolve.ts

@@ -9,10 +9,10 @@ export type RAnchor = {
 	hashMatched: boolean;
 };
 
-export type HEdit = { hash_range_inclusive: [Anchor, Anchor]; content_lines: string[] };
+export type HEdit = { content_lines: string[]; hash_range_inclusive: [Anchor, Anchor] };
 export type RHEdit = {
-  hash_range_inclusive: [RAnchor, RAnchor];
   content_lines: string[];
+  hash_range_inclusive: [RAnchor, RAnchor];
 };
 
 interface HMismatch {
@@ -37,8 +37,8 @@ export interface NEdit {
 }
 
 export type HTEdit = {
-  hash_range_inclusive: [string, string];
   content_lines: string[];
+  hash_range_inclusive: [string, string];
 };
 
 function resAnchor(
@@ -75,51 +75,52 @@ function assertAligned(
 	}
 }
 
+
 export function fmtMismatch(
-	mismatches: HMismatch[],
-	fileLines: string[],
-	fileHashes: string[],
-	filePath?: string,
-	): string {
-	assertAligned(fileLines, fileHashes, "fmtMismatch");
-
-	const out: string[] = [];
-	const notFound = mismatches.filter((m) => m.kind === "not_found");
-	const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
-
-	const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
-	if (notFound.length > 0) {
-		out.push(
-			`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
-		);
-	}
-	if (ambiguous.length > 0) {
-		if (out.length > 0) out.push("");
-		out.push(
-			`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
-		);
-		for (const m of ambiguous) {
-			const sample = (m.candidates ?? []).slice(0, 5);
-			const more =
-				(m.candidates?.length ?? 0) > sample.length
-					? `, ... (+${(m.candidates?.length ?? 0) - sample.length} more)`
-					: "";
-			const lines = sample
-				.map((line) => {
-					const content = fileLines[line - 1] ?? "";
-					return `    ${line}: ${fileHashes[line - 1]}│${content}`;
-				})
-				.join("\n");
-				out.push(
-					`  Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.\n${lines}`,
-				);
-		}
-	}
+  mismatches: HMismatch[],
+  fileLines: string[],
+  fileHashes: string[],
+  filePath?: string,
+): string {
+  assertAligned(fileLines, fileHashes, "fmtMismatch");
+
+  const out: string[] = [];
+  const notFound = mismatches.filter((m) => m.kind === "not_found");
+  const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
+
+  const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
+  if (notFound.length > 0) {
+    out.push(
+      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
+    );
+  }
+  if (ambiguous.length > 0) {
+    if (out.length > 0) out.push("");
+    out.push(
+      `[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
+    );
+    for (const m of ambiguous) {
+      const sample = (m.candidates ?? []).slice(0, 5);
+      const more =
+        (m.candidates?.length ?? 0) > sample.length
+          ? `, ... (+${(m.candidates?.length ?? 0) - sample.length} more)`
+          : "";
+      const lines = sample
+        .map((line) => {
+          const content = fileLines[line - 1] ?? "";
+          return `    ${line}: ${fileHashes[line - 1]}│${content}`;
+        })
+        .join("\n");
+        out.push(
+          `  Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.\n${lines}`,
+        );
+    }
+  }
 
-	return out.join("\n");
+  return out.join("\n");
 }
 
-const ITEM_KS = new Set(["hash_range_inclusive", "content_lines"]);
+const ITEM_KS = new Set(["content_lines", "hash_range_inclusive"]);
 
 function isStrArr(value: unknown): value is string[] {
 	return (
@@ -136,7 +137,7 @@ function isStrPair(value: unknown): value is [string, string] {
 }
 
 function assertItem(edit: Record<string, unknown>, index: number): void {
-  rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { hash_range_inclusive, content_lines }.");
+  rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { content_lines, hash_range_inclusive }.");
 
   if ("hash_range_inclusive" in edit && !isStrPair(edit.hash_range_inclusive)) {
     throw new Error(
@@ -163,8 +164,8 @@ export function resEdits(edits: HTEdit[]): HEdit[] {
 
     const replaceLines = parseText(edit.content_lines);
     result.push({
-      hash_range_inclusive: [parseHashRef(edit.hash_range_inclusive[0]), parseHashRef(edit.hash_range_inclusive[1])],
       content_lines: replaceLines,
+      hash_range_inclusive: [parseHashRef(edit.hash_range_inclusive[0]), parseHashRef(edit.hash_range_inclusive[1])],
     });
   }
   return result;
@@ -214,7 +215,7 @@ export function assertNoBarePrefix(
       : `${matchedCount} match file line hashes — strong evidence the prefix was copied from read output.`;
 
   throw new Error(
-    `[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected content_lines entry; keep only the literal line content that appears after "│" in read output. Remember: hash_range_inclusive uses hash anchors, content_lines uses file content only.`
+    `[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected content_lines entry; keep only the literal line content that appears after "│" in read output. Remember: content_lines uses file content only, hash_range_inclusive uses hash anchors.`
   );
 }
 
@@ -290,8 +291,8 @@ export function valEdits(
     const leading = checkBoundaryDup(prevLine, replacementFirstLine, "leading", startResolved.line - 2, fileLines, resolved.length);
     if (leading) boundaryWarnings.push(leading);
     resolved.push({
-      hash_range_inclusive: [startResolved, endResolved],
       content_lines: edit.content_lines,
+      hash_range_inclusive: [startResolved, endResolved],
     });
   }
 

package/src/replace-normalize.ts

@@ -1,89 +1,25 @@
 import { isRec, has } from "./utils";
 
-function tryParseJSON<T>(value: unknown, guard: (v: unknown) => v is T): T | undefined {
-  if (typeof value !== "string") return undefined;
-  try {
-    const parsed: unknown = JSON.parse(value);
-    if (guard(parsed)) return parsed;
-  } catch {}
-  return undefined;
-}
-
-function coerceEditArray(items: unknown[]): { result: unknown[]; warnings: string[] } {
-  const warnings: string[] = [];
-  const result = items
-    .map((item: unknown) => {
-      if (typeof item === "string") {
-        const parsed = tryParseJSON(item, isRec);
-        if (parsed) {
-          warnings.push("Edit item was passed as a JSON string instead of a native object. Use native JSON values, not serialized strings.");
-          return parsed;
-        }
-      }
-      return item;
-    })
-    .map((change: unknown) => {
-      if (!isRec(change)) return change;
-      if (typeof change.content_lines !== "string") return change;
-      const parsed = tryParseJSON(change.content_lines, (v): v is string[] =>
-        Array.isArray(v) && v.every((i) => typeof i === "string"),
-      );
-      if (parsed) {
-        warnings.push("content_lines was passed as a JSON string inside an edit item. Use a native array of strings.");
-        return { ...change, content_lines: parsed };
-      }
-      return change;
-    });
-  return { result, warnings };
+export function normalizeFilePath(record: Record<string, unknown>): void {
+  if (typeof record.path !== "string" && typeof record.file_path === "string") {
+    record.path = record.file_path;
+    delete record.file_path;
+  }
 }
 
 function normalizeField(
   record: Record<string, unknown>,
   from: string,
   to: string,
-): string | undefined {
-  if (!has(record, from)) return undefined;
-  const raw = tryParseJSON(record[from], Array.isArray) ?? record[from];
-  const wasString = typeof record[from] === "string" && raw !== record[from];
+): void {
+  if (!has(record, from)) return;
+  const raw = record[from];
   if (Array.isArray(raw)) {
-    const { result, warnings } = coerceEditArray(raw);
-    record[to] = result;
-    if (warnings.length > 0) {
-      return warnings.join(" ");
-    }
-  } else {
-    const single =
-      typeof raw === "string"
-        ? tryParseJSON(raw, isRec)
-        : isRec(raw)
-          ? raw
-          : undefined;
-    if (single) {
-      const { result, warnings } = coerceEditArray([single]);
-      record[to] = result;
-      if (warnings.length > 0) {
-        return warnings.join(" ");
-      }
-    }
+    record[to] = raw;
+  } else if (isRec(raw)) {
+    record[to] = [raw];
   }
   if (from !== to) delete record[from];
-  if (wasString) {
-    return `Field "${from}" was passed as a JSON string instead of a native array. Use native JSON values, not serialized strings.`;
-  }
-  return undefined;
-}
-
-export function normalizeFilePath(record: Record<string, unknown>): void {
-  if (typeof record.path !== "string" && typeof record.file_path === "string") {
-    record.path = record.file_path;
-    delete record.file_path;
-  }
-}
-
-export function tryParseField(record: Record<string, unknown>, field: string): void {
-  if (typeof record[field] === "string") {
-    try { record[field] = JSON.parse(record[field] as string); } catch {}
-  }
 }
 
 export function normReq(input: unknown): unknown {
@@ -92,42 +28,21 @@ export function normReq(input: unknown): unknown {
   }
 
   const record: Record<string, unknown> = { ...input };
-  const warnings: string[] = [];
 
   normalizeFilePath(record);
 
-  const w1 = normalizeField(record, "changes", "changes");
-  if (w1) warnings.push(w1);
-  const w2 = normalizeField(record, "edits", "changes");
-  if (w2) warnings.push(w2);
+  normalizeField(record, "changes", "changes");
+  normalizeField(record, "edits", "changes");
 
   if (!Array.isArray(record.changes) && has(record, "hash_range_inclusive") && has(record, "content_lines")) {
-    const hriRaw = record.hash_range_inclusive;
-    const hri = tryParseJSON(hriRaw, (v): v is string[] =>
-      Array.isArray(v) && v.length === 2 && v.every((i) => typeof i === "string")
-    ) ?? hriRaw;
-    if (typeof hriRaw === "string" && hri !== hriRaw) {
-      warnings.push("hash_range_inclusive was passed as a JSON string instead of a native array. Use native JSON values.");
-    }
-
-    const clRaw = record.content_lines;
-    const cl = tryParseJSON(clRaw, (v): v is string[] =>
-      Array.isArray(v) && v.every((i) => typeof i === "string")
-    ) ?? clRaw;
-    if (typeof clRaw === "string" && cl !== clRaw) {
-      warnings.push("content_lines was passed as a JSON string instead of a native array. Use native JSON values.");
-    }
-
+    const hri = record.hash_range_inclusive;
+    const cl = record.content_lines;
     if (Array.isArray(hri) && Array.isArray(cl)) {
-      record.changes = [{ hash_range_inclusive: hri, content_lines: cl }];
+      record.changes = [{ content_lines: cl, hash_range_inclusive: hri }];
       delete record.hash_range_inclusive;
       delete record.content_lines;
     }
   }
 
-  if (warnings.length > 0) {
-    (record as Record<string, unknown>)._normWarnings = warnings;
-  }
-
   return record;
 }

package/src/replace.ts

@@ -11,7 +11,7 @@ import {
   restoreEndings,
 } from "./replace-diff";
 import { readNormFile } from "./file-reader";
-import { normReq, normalizeFilePath, tryParseField } from "./replace-normalize";
+import { normReq, normalizeFilePath } from "./replace-normalize";
 import { isRec, has, rejectUnknownFields } from "./utils";
 import { MAX_HASH_LINES } from "./constants";
 import { resolveTarget, writeAtomic } from "./fs-write";
@@ -62,25 +62,25 @@ const hashRangeInclSchema = Type.Array(
 
 const changeItemSchema = Type.Object(
   {
-    hash_range_inclusive: hashRangeInclSchema,
     content_lines: contentLinesSchema,
+    hash_range_inclusive: hashRangeInclSchema,
   },
   { additionalProperties: false },
 );
 
 export const editToolSchema = Type.Object(
   {
-    path: Type.String({ description: "path" }),
     changes: Type.Array(changeItemSchema, { description: "changes over $path" }),
+    path: Type.String({ description: "path" }),
   },
   { additionalProperties: false },
 );
 
 export const flatEditToolSchema = Type.Object(
   {
-    path: Type.String({ description: "path" }),
-    hash_range_inclusive: hashRangeInclSchema,
     content_lines: contentLinesSchema,
+    hash_range_inclusive: hashRangeInclSchema,
+    path: Type.String({ description: "path" }),
   },
   { additionalProperties: false },
 );
@@ -127,7 +127,7 @@ export function assertReq(
   for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"]) {
     if (has(request, legacyKey)) {
       throw new Error(
-        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}.`
+        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {content_lines: [...], hash_range_inclusive: ["<START>", "<END>"]}.`
       );
     }
   }
@@ -139,7 +139,7 @@ export function assertReq(
   }
 
   if (!Array.isArray(request.changes)) {
-    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { hash_range_inclusive: ["<START>", "<END>"], content_lines: [...] }.');
+    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { content_lines: [...], hash_range_inclusive: ["<START>", "<END>"] }.');
   }
 }
 
@@ -311,8 +311,6 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
           if (!isRec(args)) return args as any;
           const record = { ...args };
           normalizeFilePath(record);
-          tryParseField(record, "hash_range_inclusive");
-          tryParseField(record, "content_lines");
           return record as any;
         }
       : (args: unknown) =>
@@ -408,14 +406,17 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const canonical = opts.flat
         ? normReq({
+            content_lines: (params as any).content_lines,
+            hash_range_inclusive: (params as any).hash_range_inclusive,
             path: (params as any).path,
             changes: [{
-              hash_range_inclusive: (params as any).hash_range_inclusive,
               content_lines: (params as any).content_lines,
+              hash_range_inclusive: (params as any).hash_range_inclusive,
             }],
           })
         : normReq(params);
-      const normWarnings = (canonical as Record<string, unknown>)._normWarnings as string[] | undefined;
+
+
       const normalizedParams = canonical as { path: string; changes: HTEdit[] };
       const path = normalizedParams.path;
       const absolutePath = toCwd(path, ctx.cwd);
@@ -448,10 +449,6 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
             ? normalizedParams.changes.length
             : 0;
 
-        if (normWarnings) {
-          warnings.push(...normWarnings);
-        }
-
         if (originalNormalized === result) {
           const noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;
           return buildNoop({

package/src/utils.ts

@@ -6,10 +6,23 @@ export function has(record: Record<string, unknown>, key: string): boolean {
 	return Object.hasOwn(record, key);
 }
 
+/**
+ * Splits text into visible lines, stripping the trailing empty element
+ * that `split("\n")` produces when the text ends with "\n".
+ *
+ * This is the canonical way to get user-visible lines from text.
+ * For internal hashing that needs the trailing empty string (e.g.
+ * `_lineHashesPure`, `mapStableHashes`, `buildIdx`), use
+ * `text.split("\n")` directly with a comment explaining why.
+ */
+export function splitLines(text: string): string[] {
+  if (text.length === 0) return [];
+  const lines = text.split("\n");
+  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+}
+
 export function visLines(text: string): string[] {
-	if (text.length === 0) return [];
-	const lines = text.split("\n");
-	return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+  return splitLines(text);
 }
 
 export function cntLines(text: string): number {