@d3ara1n/pi-hashline-edit 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @d3ara1n/pi-hashline-edit
+
+> Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash, replacing `oldText`/`newText` matching.
+
+用「行级内容 hash + 行号」双重锚替代 pi 内置的 `oldText`/`newText` 精确匹配编辑。模型指出要改的行（带 hash 校验），而不是重打要改的代码——从根上消除 string-not-found 死循环与空白战争。
+
+## 设计要点
+
+- **行级 hash + 行号双重锚**：`read` 每行带短 hash（`3#aF3│code`），`edit` 引用 `行号#hash`。行号给人读，hash 给机器校验——天然抗行号漂移。
+- **context-aware hash**：每行 hash 把上下两行一起算，使内容相同的行（空行、`}`）因邻居不同而 hash 不同，文件内碰撞接近 0。
+- **严格核心 + 可插拔容错**：核心 `parse → apply` 零猜测、失败快；容错（旧格式归一化、漂移重定位、块解析）做成独立开关的中间件。
+- **不兼容旧格式**：override 内置 `edit`/`read`。edit 只接受 hashline `input`；模型误发 `oldText`/`newText` 会收到明确错误（而非静默降级到旧方案）——让开发者知道 hashline 是否真在用。容错仅限不影响结果的格式归一化。
+
+> **状态**：Phase 1 纯核心库（`src/core/`）已完成，可独立测试。pi 接入层（`src/pi/`）开发中。
+
+## 协议速览
+
+`read` 输出（每行带锚）：
+
+```
+src/foo.ts · 6 lines
+   1#aF3│import { compute } from "./util"
+   2#7Qk│
+   3#mP0│export function foo(x: number) {
+   4#kLp│  if (x < 0) return 0
+   5#xY9│  return compute(x)
+   6#b2H│}
+```
+
+`edit` 的 `input`：path 在工具参数里，input 只含 ops（无需 `file:` 头，工具自动注入）
+
+```
+replace 4#kLp:
++  if (x < 0) throw new Error("neg")
+
+insert_after 6#b2H:
++
++export const bar = foo
+```
+
+## Installation
+
+```bash
+pi install npm:@d3ara1n/pi-hashline-edit
+```
+
+Or add to `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "extensions": [
+    "/absolute/path/to/pi-extensions/packages/pi-hashline-edit"
+  ]
+}
+```
+
+## Dependencies
+
+- 无额外 `@d3ara1n/pi-*` 依赖；peer `@earendil-works/pi-coding-agent` 随 pi 附带（框架级，按惯例不列）。

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@d3ara1n/pi-hashline-edit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hashline-style file editing for pi — line-anchored edits verified by content hash, replacing oldText/newText matching",
+  "keywords": [
+    "pi-package",
+    "pi"
+  ],
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "node --test src/core/*.test.ts src/pi/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d3ara1n/pi-extensions",
+    "directory": "packages/pi-hashline-edit"
+  },
+  "license": "MIT"
+}

package/src/core/apply.test.ts

@@ -0,0 +1,185 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createSnapshot } from "./snapshot.ts";
+import { applyEdits } from "./apply.ts";
+import type { Edit, FileSnapshot } from "./types.ts";
+
+const snap = (text: string): FileSnapshot => createSnapshot("f.ts", text);
+const ln = (s: FileSnapshot, line: number) => ({ line, hash: s.lineHashes[line - 1] });
+
+// —— 正常路径 ——
+
+test("replace 单行", () => {
+	const text = "a\nb\nc\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "replace", start: ln(s, 2), body: ["B"] }], s);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nB\nc\n");
+});
+
+test("replace range", () => {
+	const text = "a\nb\nc\nd\ne\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[{ op: "replace", start: ln(s, 2), end: ln(s, 4), body: ["X", "Y"] }],
+		s,
+	);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nX\nY\ne\n");
+});
+
+test("delete 单行 / range", () => {
+	const text = "a\nb\nc\nd\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "delete", start: ln(s, 2), end: ln(s, 3) }], s);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nd\n");
+});
+
+test("insert_after", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "insert_after", anchor: ln(s, 1), body: ["x"] }], s);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nx\nb\n");
+});
+
+test("insert_before", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "insert_before", anchor: ln(s, 2), body: ["x"] }], s);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "a\nx\nb\n");
+});
+
+test("append / prepend", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[
+			{ op: "prepend", body: ["head"] },
+			{ op: "append", body: ["tail"] },
+		],
+		s,
+	);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "head\na\nb\ntail\n");
+});
+
+test("多操作乱序 → 按位置正确应用", () => {
+	const text = "a\nb\nc\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[
+			{ op: "insert_after", anchor: ln(s, 3), body: ["z"] },
+			{ op: "replace", start: ln(s, 1), body: ["A"] },
+		],
+		s,
+	);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "A\nb\nc\nz\n");
+});
+
+test("结果带 diff 与 newSnapshot", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "replace", start: ln(s, 1), body: ["A"] }], s);
+	assert.equal(r.ok, true);
+	if (r.ok) {
+		assert.ok(r.diff.includes("@@"));
+		assert.equal(r.newSnapshot.text, "A\nb\n");
+		assert.equal(r.newSnapshot.lineHashes.length, 2);
+	}
+});
+
+test("闭环：newSnapshot 可用于下一次 edit", () => {
+	let s = snap("a\nb\n");
+	let cur = s.text;
+	const r1 = applyEdits(cur, [{ op: "replace", start: ln(s, 1), body: ["A"] }], s);
+	assert.equal(r1.ok, true);
+	if (r1.ok) {
+		cur = r1.text;
+		s = r1.newSnapshot;
+		const r2 = applyEdits(cur, [{ op: "replace", start: ln(s, 2), body: ["B"] }], s);
+		assert.equal(r2.ok, true);
+		if (r2.ok) assert.equal(r2.text, "A\nB\n");
+	}
+});
+
+// —— 错误路径 ——
+
+test("stale（文件已变）拒绝", () => {
+	const s = snap("a\nb\n");
+	const r = applyEdits("a\nCHANGED\n", [{ op: "replace", start: ln(s, 1), body: ["x"] }], s);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "stale");
+});
+
+test("anchor hash 不匹配拒绝（防记错）", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: "WRONG" }, body: ["x"] }], s);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "anchor");
+});
+
+test("行号越界拒绝", () => {
+	const text = "a\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "replace", start: { line: 5, hash: s.lineHashes[0] }, body: ["x"] }], s);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "anchor");
+});
+
+test("range 逆序拒绝", () => {
+	const text = "a\nb\nc\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[{ op: "replace", start: ln(s, 3), end: ln(s, 1), body: ["x"] }],
+		s,
+	);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "range");
+});
+
+test("重叠编辑拒绝", () => {
+	const text = "a\nb\nc\nd\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[
+			{ op: "replace", start: ln(s, 2), end: ln(s, 3), body: ["x"] },
+			{ op: "replace", start: ln(s, 3), body: ["y"] },
+		],
+		s,
+	);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "range");
+});
+
+test("同插入点冲突拒绝", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(
+		text,
+		[
+			{ op: "insert_after", anchor: ln(s, 1), body: ["x"] },
+			{ op: "insert_after", anchor: ln(s, 1), body: ["y"] },
+		],
+		s,
+	);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "range");
+});
+
+test("noop（body 字节相同）拒绝", () => {
+	const text = "a\nb\n";
+	const s = snap(text);
+	const r = applyEdits(text, [{ op: "replace", start: ln(s, 1), body: ["a"] }], s);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error.kind, "noop");
+});

package/src/core/apply.ts

@@ -0,0 +1,150 @@
+/**
+ * 纯函数应用器：在快照对应的文件上应用编辑。
+ *
+ * 严格语义：
+ * - 要求当前 `text === snapshot.text`（stale 检查）；漂移由 `transforms/relocate`
+ *   中间件在调用 apply 前处理，纯 apply 不猜。
+ * - 每个锚的 hash 必须匹配快照中对应行（防模型记错行号/hash）。
+ * - 操作范围不得重叠（含同插入点）。
+ * - body 与目标字节相同 → `noop` 错误（引导模型查 bug 而非盲目重试）。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+import { buildDiff } from "./diff.ts";
+import { createSnapshot, joinLines, splitLines } from "./snapshot.ts";
+import type { ApplyResult, Edit, FileSnapshot, PatchError } from "./types.ts";
+
+/** 行级操作：把 `[lo, hi)`（0-based，hi exclusive）区间的原始行替换为 newLines。 */
+interface SpanOp {
+	lo: number;
+	hi: number;
+	newLines: string[];
+}
+
+/** 校验锚匹配快照（纯 apply：text 已等于 snapshot.text，故只防记错）。 */
+function checkAnchor(snapshot: FileSnapshot, line: number, hash: string): PatchError | null {
+	if (line < 1 || line > snapshot.lineHashes.length) {
+		return {
+			kind: "anchor",
+			message: `line ${line} does not exist (file has ${snapshot.lineHashes.length} lines)`,
+		};
+	}
+	if (snapshot.lineHashes[line - 1] !== hash) {
+		return {
+			kind: "anchor",
+			message: `hash mismatch at line ${line}: file has #${snapshot.lineHashes[line - 1]}, edit says #${hash}`,
+		};
+	}
+	return null;
+}
+
+/** 把 Edit 翻译成 SpanOp，同时校验锚与范围。 */
+function translateEdit(edit: Edit, snapshot: FileSnapshot): { op: SpanOp } | { error: PatchError } {
+	switch (edit.op) {
+		case "replace":
+		case "delete": {
+			const startErr = checkAnchor(snapshot, edit.start.line, edit.start.hash);
+			if (startErr) return { error: startErr };
+			let endLine = edit.start.line;
+			if (edit.end) {
+				const endErr = checkAnchor(snapshot, edit.end.line, edit.end.hash);
+				if (endErr) return { error: endErr };
+				endLine = edit.end.line;
+			}
+			if (endLine < edit.start.line) {
+				return { error: { kind: "range", message: `range ${edit.start.line}..${endLine} ends before it starts` } };
+			}
+			return {
+				op: {
+					lo: edit.start.line - 1,
+					hi: endLine,
+					newLines: edit.op === "delete" ? [] : edit.body,
+				},
+			};
+		}
+		case "insert_after": {
+			const err = checkAnchor(snapshot, edit.anchor.line, edit.anchor.hash);
+			if (err) return { error: err };
+			return { op: { lo: edit.anchor.line, hi: edit.anchor.line, newLines: edit.body } };
+		}
+		case "insert_before": {
+			const err = checkAnchor(snapshot, edit.anchor.line, edit.anchor.hash);
+			if (err) return { error: err };
+			return { op: { lo: edit.anchor.line - 1, hi: edit.anchor.line - 1, newLines: edit.body } };
+		}
+		case "append": {
+			return { op: { lo: snapshot.lineHashes.length, hi: snapshot.lineHashes.length, newLines: edit.body } };
+		}
+		case "prepend": {
+			return { op: { lo: 0, hi: 0, newLines: edit.body } };
+		}
+	}
+}
+
+/** 零宽区间（插入点）的"最后影响位"是 lo；非零宽是 hi-1。 */
+function maxAffected(op: SpanOp): number {
+	return op.lo === op.hi ? op.lo : op.hi - 1;
+}
+
+/**
+ * 在快照对应的文件上应用编辑。
+ *
+ * @param text     当前文件全文
+ * @param edits    解析出的编辑操作
+ * @param snapshot read 时记录的快照（text 必须等于当前 text）
+ * @returns 应用结果；失败返回结构化错误
+ */
+export function applyEdits(text: string, edits: Edit[], snapshot: FileSnapshot): ApplyResult {
+	if (text !== snapshot.text) {
+		return {
+			ok: false,
+			error: { kind: "stale", message: "file changed since last read; re-read before editing" },
+		};
+	}
+
+	const lines = splitLines(text);
+
+	const ops: SpanOp[] = [];
+	for (const edit of edits) {
+		const t = translateEdit(edit, snapshot);
+		if ("error" in t) return { ok: false, error: t.error };
+		ops.push(t.op);
+	}
+
+	// 重叠检查：按 lo 升序，相邻 op 的起点不得落在前一个的影响区内
+	const sorted = [...ops].sort((a, b) => a.lo - b.lo || a.hi - b.hi);
+	for (let k = 1; k < sorted.length; k++) {
+		if (sorted[k].lo <= maxAffected(sorted[k - 1])) {
+			return {
+				ok: false,
+				error: {
+					kind: "range",
+					message: `overlapping edits near line ${sorted[k].lo + 1}; issue one edit per range`,
+				},
+			};
+		}
+	}
+
+	// 从后往前应用（lo 降序），避免行号偏移
+	let result = [...lines];
+	for (const op of [...sorted].sort((a, b) => b.lo - a.lo)) {
+		result = [...result.slice(0, op.lo), ...op.newLines, ...result.slice(op.hi)];
+	}
+
+	const newText = joinLines(result, snapshot.lineEnding);
+	if (newText === text) {
+		return {
+			ok: false,
+			error: {
+				kind: "noop",
+				message:
+					"edit parsed and applied cleanly but produced no change; body is byte-identical to the target — the bug is elsewhere, re-read first",
+			},
+		};
+	}
+
+	const newSnapshot = createSnapshot(snapshot.path, newText, snapshot.hashLen);
+	const diff = buildDiff(snapshot.path, lines, sorted);
+	return { ok: true, text: newText, newSnapshot, changed: true, diff };
+}

package/src/core/diff.test.ts

@@ -0,0 +1,21 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildDiff } from "./diff.ts";
+
+test("单 hunk", () => {
+	const d = buildDiff("f.ts", ["a", "b", "c"], [{ lo: 1, hi: 2, newLines: ["X"] }]);
+	assert.ok(d.startsWith("--- a/f.ts\n"));
+	assert.ok(d.includes("+++ b/f.ts"));
+	assert.ok(d.includes("@@ -2 +2 @@"));
+	assert.ok(d.includes("-b"));
+	assert.ok(d.includes("+X"));
+});
+
+test("多行 range hunk 带计数", () => {
+	const d = buildDiff("f", ["a", "b", "c", "d"], [{ lo: 0, hi: 3, newLines: ["X"] }]);
+	assert.ok(d.includes("@@ -1,3 +1 @@")); // newCount=1 时省略计数（git 惯例）
+});
+
+test("空 ops 返回空串", () => {
+	assert.equal(buildDiff("f", ["a"], []), "");
+});

package/src/core/diff.ts

@@ -0,0 +1,39 @@
+/**
+ * 基于 ops 的 unified diff 预览。
+ *
+ * 每个 SpanOp 生成一个 hunk，`@@` 行号基于原始文件（多 op 时各自的原始位置），
+ * 内容准确。这是 Phase 1 的近似实现；如需精确的多 op 行号可后续换 LCS。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+interface SpanOpLike {
+	lo: number;
+	hi: number;
+	newLines: string[];
+}
+
+/**
+ * 生成 unified diff。
+ *
+ * @param path     文件路径（用于 diff 头）
+ * @param oldLines 应用前的原始行数组
+ * @param ops      已应用的行级操作
+ */
+export function buildDiff(path: string, oldLines: readonly string[], ops: readonly SpanOpLike[]): string {
+	if (ops.length === 0) return "";
+	const out: string[] = [`--- a/${path}`, `+++ b/${path}`];
+	for (const op of ops) {
+		const oldCount = op.hi - op.lo;
+		const oldStart = oldCount === 0 ? op.lo : op.lo + 1; // 零宽（插入点）用 lo，符合 unified-diff "after line N" 惯例
+		const newCount = op.newLines.length;
+		const newStart = op.lo + 1;
+		// 单行 hunk 省略计数，符合 unified-diff 惯例
+		const oldRange = oldCount === 1 ? `${oldStart}` : `${oldStart},${oldCount}`;
+		const newRange = newCount === 1 ? `${newStart}` : `${newStart},${newCount}`;
+		out.push(`@@ -${oldRange} +${newRange} @@`);
+		for (let i = op.lo; i < op.hi; i++) out.push(`-${oldLines[i]}`);
+		for (const nl of op.newLines) out.push(`+${nl}`);
+	}
+	return out.join("\n") + "\n";
+}

package/src/core/hash.test.ts

@@ -0,0 +1,49 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { computeLineHash, hashFileLines } from "./hash.ts";
+
+const ALLOWED = new Set("0123456789ABCDEFGHJKMNPQRSTVWXYZ");
+
+test("computeLineHash 稳定且为 base32", () => {
+	const a = computeLineHash("p", "c", "n", 4);
+	const b = computeLineHash("p", "c", "n", 4);
+	assert.equal(a, b);
+	assert.equal(a.length, 4);
+	for (const ch of a) assert.ok(ALLOWED.has(ch), `bad char ${ch}`);
+});
+
+test("context-aware：相同行不同邻居 → 不同 hash", () => {
+	const h1 = computeLineHash("a", "x", "b");
+	const h2 = computeLineHash("c", "x", "d");
+	assert.notEqual(h1, h2);
+});
+
+test("context-aware：相同三元组 → 相同 hash", () => {
+	assert.equal(computeLineHash("a", "x", "b"), computeLineHash("a", "x", "b"));
+});
+
+test("base32 字符集（去 I/L/O/U）批量", () => {
+	for (let i = 0; i < 2000; i++) {
+		const h = computeLineHash("", `line ${i}`, "", 4);
+		for (const ch of h) assert.ok(ALLOWED.has(ch), `bad char ${ch} in ${h}`);
+	}
+});
+
+test("hashFileLines 长度等于行数", () => {
+	assert.equal(hashFileLines(["a", "b", "c"]).length, 3);
+});
+
+test("hashFileLines 空文件", () => {
+	assert.deepEqual(hashFileLines([]), []);
+});
+
+test("hashFileLines 文件内无碰撞（大量重复行）", () => {
+	const lines = ["", "", "", "", "", "}", "}", "}", "return", "return", ",", ","];
+	const hashes = hashFileLines(lines);
+	assert.equal(new Set(hashes).size, hashes.length, "collision not resolved");
+});
+
+test("hashFileLines 长度参数生效", () => {
+	assert.equal(hashFileLines(["a", "b"], 6)[0].length, 6);
+	assert.equal(hashFileLines(["a", "b"], 4)[0].length, 4);
+});

package/src/core/hash.ts

@@ -0,0 +1,94 @@
+/**
+ * 行级 context-aware hash。
+ *
+ * 每行的 hash 把「上一行 + 本行 + 下一行」拼起来一起算，使内容相同的行
+ * （空行、`}`、`return`）因邻居不同而 hash 不同，文件内碰撞实际接近 0。
+ * 残余碰撞由 {@link hashFileLines} 自动扩展长度解决（per-file 无碰撞保证）。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+/** Crockford base32 字符表（去 I/L/O/U，避免易混字符）。正好 32 个。 */
+const BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * FNV-1a 32-bit。稳定（同一输入永远同一输出）、分布均匀、非加密用途。
+ * 用 `Math.imul` 保证 32-bit 整数乘法在 JS 下正确。
+ */
+function fnv1a32(str: string): number {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < str.length; i++) {
+		h ^= str.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return h >>> 0;
+}
+
+/** 把 32-bit 整数编码为指定长度的 base32 字符串。 */
+function toBase32(n: number, len: number): string {
+	let s = "";
+	for (let i = 0; i < len; i++) {
+		s = BASE32[n & 31] + s;
+		n = Math.floor(n / 32);
+	}
+	return s;
+}
+
+/**
+ * 计算单行的 context-aware hash。
+ *
+ * @param prev 上一行内容（首行传 `""`）
+ * @param cur  本行内容
+ * @param next 下一行内容（末行传 `""`）
+ * @param len  hash 长度（默认 4，20 bits ≈ 100 万值）
+ */
+export function computeLineHash(prev: string, cur: string, next: string, len = 4): string {
+	const h = fnv1a32(`${prev}\n${cur}\n${next}`);
+	return toBase32(h, len);
+}
+
+/** 给每行算 raw hash（不处理碰撞）。 */
+function rawHashes(lines: readonly string[], len: number): string[] {
+	return lines.map((line, i) =>
+		computeLineHash(lines[i - 1] ?? "", line, lines[i + 1] ?? "", len),
+	);
+}
+
+/** 找出出现 >1 次的 hash 值。 */
+function duplicatedHashes(hashes: readonly string[]): Set<string> {
+	const counts = new Map<string, number>();
+	for (const h of hashes) counts.set(h, (counts.get(h) ?? 0) + 1);
+	return new Set([...counts.entries()].filter(([, c]) => c > 1).map(([h]) => h));
+}
+
+/** 兜底：用序号后缀强制唯一（context-aware 下理论不可达）。 */
+function forceUnique(hashes: string[]): string[] {
+	const seen = new Map<string, number>();
+	return hashes.map((h) => {
+		const c = seen.get(h) ?? 0;
+		seen.set(h, c + 1);
+		return c === 0 ? h : `${h}${c}`;
+	});
+}
+
+/**
+ * 给整个文件的每行算 hash，并解决文件内碰撞：
+ * 碰撞的行自动用更长 len 重算，直到文件内唯一（per-file 无碰撞保证）。
+ *
+ * 设计依据：context-aware 已使碰撞概率接近 0；此处扩展是防御性兜底，
+ * 保证 apply 永远不会因 hash 歧义而误定位。
+ */
+export function hashFileLines(lines: readonly string[], len = 4): string[] {
+	if (lines.length === 0) return [];
+	let hashes = rawHashes(lines, len);
+	for (let curLen = len; curLen <= len + 4; curLen++) {
+		const dups = duplicatedHashes(hashes);
+		if (dups.size === 0) return hashes;
+		hashes = hashes.map((h, i) =>
+			dups.has(h)
+				? computeLineHash(lines[i - 1] ?? "", lines[i] ?? "", lines[i + 1] ?? "", curLen + 1)
+				: h,
+		);
+	}
+	return forceUnique(hashes);
+}

package/src/core/index.ts

@@ -0,0 +1,17 @@
+/**
+ * pi-hashline-edit 核心库公共 API。
+ *
+ * 纯 hashline 引擎，零 pi 依赖，可独立 `node --test`。
+ * pi 接入层在 `../pi/` 下。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+export * from "./types.ts";
+export { computeLineHash, hashFileLines } from "./hash.ts";
+export { splitLines, joinLines, createSnapshot, verifyAnchor } from "./snapshot.ts";
+export type { AnchorVerifyResult } from "./snapshot.ts";
+export { parsePatch } from "./parse.ts";
+export type { ParseResult } from "./parse.ts";
+export { applyEdits } from "./apply.ts";
+export { buildDiff } from "./diff.ts";