nano-git 0.3.4 → 0.3.6

package/dist/backend/sqlite-pool.d.mts

@@ -0,0 +1,20 @@
+import { Database, Statement } from "bun:sqlite";
+
+//#region src/backend/sqlite-pool.d.ts
+/** 连接池获取结果 */
+interface SqliteConnectionHandle {
+  readonly db: Database;
+  /** 释放连接（引用计数减一，归零时关闭数据库） */
+  readonly release: () => void;
+  /**
+   * 获取缓存的 prepared statement
+   *
+   * 相同 SQL 文本返回同一实例，避免重复编译。
+   * 绑定参数类型由调用方按 SQL 保证一致，此处不做泛型约束。
+   */
+  readonly prepare: <T>(sql: string) => Statement<T, any[]>;
+  /** 支持 `using` 语法自动释放 */
+  [Symbol.dispose](): void;
+}
+//#endregion
+export { SqliteConnectionHandle };

package/dist/backend/sqlite-pool.mjs

@@ -0,0 +1,95 @@
+import { Database } from "bun:sqlite";
+//#region src/backend/sqlite-pool.ts
+/**
+* SQLite 连接池（引用计数）
+*
+* 缓存 Database 实例，相同 dbPath 复用同一连接，
+* 防止反复打开同一数据库文件带来的开销。
+*
+* 每个 acquire 对应一个 release，当引用计数归零时自动关闭连接。
+* 返回的 handle 实现了 [Symbol.dispose]()，可用 `using` 语法自动释放。
+*
+* @example
+* ```ts
+* using _conn = acquireConnection("/tmp/repo.sqlite");
+* // 作用域结束时自动释放
+* ```
+*/
+const pool = /* @__PURE__ */ new Map();
+/** 构造连接句柄 */
+function makeHandle(db, stmts, onRelease) {
+	return {
+		db,
+		release: onRelease,
+		prepare(sql) {
+			let stmt = stmts.get(sql);
+			if (stmt === void 0) {
+				stmt = db.query(sql);
+				stmts.set(sql, stmt);
+			}
+			return stmt;
+		},
+		[Symbol.dispose]() {
+			onRelease();
+		}
+	};
+}
+/**
+* 从全局连接池获取或创建 SQLite 数据库连接
+*
+* 相同 dbPath 返回同一个 Database 实例，通过引用计数管理生命周期。
+* 首次打开时根据 walMode 执行 PRAGMA journal_mode = WAL。
+* 后续打开（缓存命中）忽略 walMode 参数。
+*
+* 注意：`:memory:` 和 `file:xxx?mode=memory` 等内存数据库不会被缓存，
+* 每次调用都会创建独立连接（SQLite 的 :memory: 为每个连接独立）。
+*/
+function acquireConnection(dbPath, walMode = true) {
+	if (dbPath === ":memory:" || dbPath.startsWith("file:") && dbPath.includes("mode=memory")) {
+		const db = new Database(dbPath);
+		if (walMode) db.run("PRAGMA journal_mode = WAL");
+		const localCache = /* @__PURE__ */ new Map();
+		let released = false;
+		return makeHandle(db, localCache, () => {
+			if (released) return;
+			released = true;
+			db.close();
+		});
+	}
+	const existing = pool.get(dbPath);
+	if (existing !== void 0) {
+		existing.refCount++;
+		let released = false;
+		return makeHandle(existing.db, existing.stmts, () => {
+			if (released) return;
+			released = true;
+			releaseConnection(dbPath);
+		});
+	}
+	const db = new Database(dbPath);
+	if (walMode) db.run("PRAGMA journal_mode = WAL");
+	const stmts = /* @__PURE__ */ new Map();
+	pool.set(dbPath, {
+		db,
+		refCount: 1,
+		stmts
+	});
+	let released = false;
+	return makeHandle(db, stmts, () => {
+		if (released) return;
+		released = true;
+		releaseConnection(dbPath);
+	});
+}
+/** 内部释放逻辑 */
+function releaseConnection(dbPath) {
+	const entry = pool.get(dbPath);
+	if (entry === void 0) return;
+	entry.refCount--;
+	if (entry.refCount <= 0) {
+		pool.delete(dbPath);
+		entry.db.close();
+	}
+}
+//#endregion
+export { acquireConnection };

package/dist/backend/sqlite.d.mts

@@ -19,7 +19,8 @@ interface SqliteRepositoryBackend extends RepositoryBackend {
 /**
  * 创建基于 SQLite 文件的完整仓库后端
  *
- * 内部创建 Database 实例并组合三个子 store。
+ * 内部通过连接池获取 Database 实例并组合三个子 store。
+ * 相同 dbPath 复用同一连接，引用计数归零时自动关闭。
  * 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
  * 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
  *

package/dist/backend/sqlite.mjs

@@ -2,7 +2,7 @@ import { HEADS_PREFIX, HEAD_REF } from "../core/types/refs.mjs";
 import { createSqliteObjectStore } from "../odb/sqlite.mjs";
 import { createSqliteRefStore } from "../refs/sqlite.mjs";
 import { createSqliteShallowStore } from "../refs/shallow/sqlite.mjs";
-import { Database } from "bun:sqlite";
+import { acquireConnection } from "./sqlite-pool.mjs";
 //#region src/backend/sqlite.ts
 /**
 * 基于 SQLite 的仓库后端
@@ -12,11 +12,15 @@ import { Database } from "bun:sqlite";
 *
 * 支持 [Symbol.dispose]() 释放数据库连接，
 * 可使用 `using` 语法管理生命周期。
+*
+* 数据库连接通过全局连接池管理（引用计数），
+* 相同 dbPath 复用同一连接，避免反复打开同一个数据库文件。
 */
 /**
 * 创建基于 SQLite 文件的完整仓库后端
 *
-* 内部创建 Database 实例并组合三个子 store。
+* 内部通过连接池获取 Database 实例并组合三个子 store。
+* 相同 dbPath 复用同一连接，引用计数归零时自动关闭。
 * 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
 * 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
 *
@@ -37,21 +41,20 @@ import { Database } from "bun:sqlite";
 * ```
 */
 function createSqliteRepositoryBackend(dbPath, options = {}) {
-	const db = new Database(dbPath);
-	if (options.walMode !== false) db.run("PRAGMA journal_mode = WAL");
-	db.run("CREATE TABLE IF NOT EXISTS objects (hash TEXT PRIMARY KEY, type TEXT NOT NULL, content BLOB NOT NULL)");
-	db.run("CREATE TABLE IF NOT EXISTS refs (name TEXT PRIMARY KEY, target TEXT NOT NULL)");
-	db.run("CREATE TABLE IF NOT EXISTS shallow (hash TEXT PRIMARY KEY)");
-	db.run("INSERT OR IGNORE INTO refs (name, target) VALUES (?, ?)", [HEAD_REF, `ref: ${HEADS_PREFIX}main`]);
+	const conn = acquireConnection(dbPath, options.walMode !== false);
+	conn.db.run("CREATE TABLE IF NOT EXISTS objects (hash TEXT PRIMARY KEY, type TEXT NOT NULL, content BLOB NOT NULL)");
+	conn.db.run("CREATE TABLE IF NOT EXISTS refs (name TEXT PRIMARY KEY, target TEXT NOT NULL)");
+	conn.db.run("CREATE TABLE IF NOT EXISTS shallow (hash TEXT PRIMARY KEY)");
+	conn.db.run("INSERT OR IGNORE INTO refs (name, target) VALUES (?, ?)", [HEAD_REF, `ref: ${HEADS_PREFIX}main`]);
 	return {
 		gitDir: dbPath,
-		objects: createSqliteObjectStore(db),
-		refs: createSqliteRefStore(db),
-		shallow: createSqliteShallowStore(db),
+		objects: createSqliteObjectStore(conn),
+		refs: createSqliteRefStore(conn),
+		shallow: createSqliteShallowStore(conn),
 		packs: null,
-		/** 释放 SQLite 数据库连接 */
+		/** 释放 SQLite 数据库连接（引用计数减一） */
 		[Symbol.dispose]() {
-			db.close();
+			conn.release();
 		}
 	};
 }

package/dist/odb/sqlite.d.mts

@@ -1,23 +1,23 @@
 import { ObjectDatabase } from "../core/types/odb.mjs";
-import { Database } from "bun:sqlite";
+import { SqliteConnectionHandle } from "../backend/sqlite-pool.mjs";
 
 //#region src/odb/sqlite.d.ts
 /**
  * 创建基于 SQLite 的对象数据库
  *
- * @param db - 已打开的 bun:sqlite Database 实例
+ * @param conn - SQLite 连接池句柄（含 statement 缓存）
  * @returns 符合 ObjectDatabase 接口的存储后端
  *
  * @example
  * ```ts
- * import { Database } from "bun:sqlite";
- * const db = new Database("/tmp/repo.sqlite");
- * const store = createSqliteObjectStore(db);
+ * import { acquireConnection } from "nano-git/backend/sqlite";
+ * using conn = acquireConnection("/tmp/repo.sqlite");
+ * const store = createSqliteObjectStore(conn);
  *
  * store.ingest(raw);
  * const obj = store.read(hash);
  * ```
  */
-declare function createSqliteObjectStore(db: Database): ObjectDatabase;
+declare function createSqliteObjectStore(conn: SqliteConnectionHandle): ObjectDatabase;
 //#endregion
 export { createSqliteObjectStore };

package/dist/odb/sqlite.mjs

@@ -14,27 +14,27 @@ import { hashObject } from "../core/hash-digest.mjs";
 /**
 * 创建基于 SQLite 的对象数据库
 *
-* @param db - 已打开的 bun:sqlite Database 实例
+* @param conn - SQLite 连接池句柄（含 statement 缓存）
 * @returns 符合 ObjectDatabase 接口的存储后端
 *
 * @example
 * ```ts
-* import { Database } from "bun:sqlite";
-* const db = new Database("/tmp/repo.sqlite");
-* const store = createSqliteObjectStore(db);
+* import { acquireConnection } from "nano-git/backend/sqlite";
+* using conn = acquireConnection("/tmp/repo.sqlite");
+* const store = createSqliteObjectStore(conn);
 *
 * store.ingest(raw);
 * const obj = store.read(hash);
 * ```
 */
-function createSqliteObjectStore(db) {
-	const selectStmt = db.query("SELECT hash, type, content FROM objects WHERE hash = ?");
-	const existsStmt = db.query("SELECT 1 FROM objects WHERE hash = ?");
-	const insertStmt = db.query("INSERT OR IGNORE INTO objects (hash, type, content) VALUES (?, ?, ?)");
-	const deleteStmt = db.query("DELETE FROM objects WHERE hash = ?");
-	const listStmt = db.query("SELECT hash FROM objects ORDER BY hash");
+function createSqliteObjectStore(conn) {
+	const selectStmt = conn.prepare("SELECT hash, type, content FROM objects WHERE hash = ?");
+	const existsStmt = conn.prepare("SELECT 1 FROM objects WHERE hash = ?");
+	const insertStmt = conn.prepare("INSERT OR IGNORE INTO objects (hash, type, content) VALUES (?, ?, ?)");
+	const deleteStmt = conn.prepare("DELETE FROM objects WHERE hash = ?");
+	const listStmt = conn.prepare("SELECT hash FROM objects ORDER BY hash");
 	/** 批量插入的事务包装 */
-	const ingestManyTx = db.transaction((objects) => {
+	const ingestManyTx = conn.db.transaction((objects) => {
 		for (const raw of objects) {
 			const expectedHash = hashObject(raw.type, raw.content);
 			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);

package/dist/refs/shallow/sqlite.d.mts

@@ -1,23 +1,23 @@
 import { ShallowStore } from "../../core/types/shallow.mjs";
-import { Database } from "bun:sqlite";
+import { SqliteConnectionHandle } from "../../backend/sqlite-pool.mjs";
 
 //#region src/refs/shallow/sqlite.d.ts
 /**
  * 创建基于 SQLite 的 shallow 边界存储
  *
- * @param db - 已打开的 bun:sqlite Database 实例
+ * @param conn - SQLite 连接池句柄（含 statement 缓存）
  * @returns 符合 ShallowStore 接口的存储后端
  *
  * @example
  * ```ts
- * import { Database } from "bun:sqlite";
- * const db = new Database("/tmp/repo.sqlite");
- * const store = createSqliteShallowStore(db);
+ * import { acquireConnection } from "nano-git/backend/sqlite";
+ * using conn = acquireConnection("/tmp/repo.sqlite");
+ * const store = createSqliteShallowStore(conn);
  *
  * store.write([hashA, hashB]);
  * console.log(store.isShallow(hashA)); // true
  * ```
  */
-declare function createSqliteShallowStore(db: Database): ShallowStore;
+declare function createSqliteShallowStore(conn: SqliteConnectionHandle): ShallowStore;
 //#endregion
 export { createSqliteShallowStore };

package/dist/refs/shallow/sqlite.mjs

@@ -13,32 +13,32 @@ import { sha1 } from "../../core/types.mjs";
 /**
 * 创建基于 SQLite 的 shallow 边界存储
 *
-* @param db - 已打开的 bun:sqlite Database 实例
+* @param conn - SQLite 连接池句柄（含 statement 缓存）
 * @returns 符合 ShallowStore 接口的存储后端
 *
 * @example
 * ```ts
-* import { Database } from "bun:sqlite";
-* const db = new Database("/tmp/repo.sqlite");
-* const store = createSqliteShallowStore(db);
+* import { acquireConnection } from "nano-git/backend/sqlite";
+* using conn = acquireConnection("/tmp/repo.sqlite");
+* const store = createSqliteShallowStore(conn);
 *
 * store.write([hashA, hashB]);
 * console.log(store.isShallow(hashA)); // true
 * ```
 */
-function createSqliteShallowStore(db) {
-	const selectAllStmt = db.query("SELECT hash FROM shallow ORDER BY hash");
-	const selectExistsStmt = db.query("SELECT 1 FROM shallow WHERE hash = ?");
-	const deleteAllStmt = db.query("DELETE FROM shallow");
-	const insertStmt = db.query("INSERT OR IGNORE INTO shallow (hash) VALUES (?)");
-	const deleteOneStmt = db.query("DELETE FROM shallow WHERE hash = ?");
+function createSqliteShallowStore(conn) {
+	const selectAllStmt = conn.prepare("SELECT hash FROM shallow ORDER BY hash");
+	const selectExistsStmt = conn.prepare("SELECT 1 FROM shallow WHERE hash = ?");
+	const deleteAllStmt = conn.prepare("DELETE FROM shallow");
+	const insertStmt = conn.prepare("INSERT OR IGNORE INTO shallow (hash) VALUES (?)");
+	const deleteOneStmt = conn.prepare("DELETE FROM shallow WHERE hash = ?");
 	/** 全量替换事务 */
-	const replaceAllTx = db.transaction((boundaries) => {
+	const replaceAllTx = conn.db.transaction((boundaries) => {
 		deleteAllStmt.run();
 		for (const hash of boundaries) insertStmt.run(hash);
 	});
 	/** 增量更新事务 */
-	const applyUpdateTx = db.transaction((update) => {
+	const applyUpdateTx = conn.db.transaction((update) => {
 		for (const hash of update.unshallow) deleteOneStmt.run(hash);
 		for (const hash of update.shallow) insertStmt.run(hash);
 	});

package/dist/refs/sqlite.d.mts

@@ -1,23 +1,23 @@
 import { RefStore } from "../core/types/refs.mjs";
-import { Database } from "bun:sqlite";
+import { SqliteConnectionHandle } from "../backend/sqlite-pool.mjs";
 
 //#region src/refs/sqlite.d.ts
 /**
  * 创建基于 SQLite 的 RefStore
  *
- * @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+ * @param conn - SQLite 连接池句柄（含 statement 缓存）
  * @returns 符合 RefStore 接口的存储后端（含事务支持）
  *
  * @example
  * ```ts
- * import { Database } from "bun:sqlite";
- * const db = new Database("/tmp/repo.sqlite");
- * const store = createSqliteRefStore(db);
+ * import { acquireConnection } from "nano-git/backend/sqlite";
+ * using conn = acquireConnection("/tmp/repo.sqlite");
+ * const store = createSqliteRefStore(conn);
  *
  * store.write("refs/heads/main", "abc123");
  * const content = store.read("refs/heads/main");
  * ```
  */
-declare function createSqliteRefStore(db: Database): RefStore;
+declare function createSqliteRefStore(conn: SqliteConnectionHandle): RefStore;
 //#endregion
 export { createSqliteRefStore };

package/dist/refs/sqlite.mjs

@@ -13,26 +13,27 @@ import { validateRefName, validateRefPrefix } from "./names.mjs";
 /**
 * 创建基于 SQLite 的 RefStore
 *
-* @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+* @param conn - SQLite 连接池句柄（含 statement 缓存）
 * @returns 符合 RefStore 接口的存储后端（含事务支持）
 *
 * @example
 * ```ts
-* import { Database } from "bun:sqlite";
-* const db = new Database("/tmp/repo.sqlite");
-* const store = createSqliteRefStore(db);
+* import { acquireConnection } from "nano-git/backend/sqlite";
+* using conn = acquireConnection("/tmp/repo.sqlite");
+* const store = createSqliteRefStore(conn);
 *
 * store.write("refs/heads/main", "abc123");
 * const content = store.read("refs/heads/main");
 * ```
 */
-function createSqliteRefStore(db) {
-	const selectStmt = db.query("SELECT target FROM refs WHERE name = ?");
-	const selectExistsStmt = db.query("SELECT 1 FROM refs WHERE name = ?");
-	const insertStmt = db.query("INSERT OR REPLACE INTO refs (name, target) VALUES (?, ?)");
-	const deleteStmt = db.query("DELETE FROM refs WHERE name = ?");
-	const listPrefixStmt = db.query("SELECT name FROM refs WHERE name >= ? AND name < ? ORDER BY name");
-	const listAllStmt = db.query("SELECT name FROM refs WHERE name LIKE 'refs/%' ORDER BY name");
+function createSqliteRefStore(conn) {
+	const selectStmt = conn.prepare("SELECT target FROM refs WHERE name = ?");
+	const selectExistsStmt = conn.prepare("SELECT 1 FROM refs WHERE name = ?");
+	const insertStmt = conn.prepare("INSERT OR REPLACE INTO refs (name, target) VALUES (?, ?)");
+	const deleteStmt = conn.prepare("DELETE FROM refs WHERE name = ?");
+	const listPrefixStmt = conn.prepare("SELECT name FROM refs WHERE name >= ? AND name < ? ORDER BY name");
+	const listAllStmt = conn.prepare("SELECT name FROM refs WHERE name LIKE 'refs/%' ORDER BY name");
+	const db = conn.db;
 	/**
 	* 开启一个新的事务
 	*

package/dist/repository/ops/object-operations.mjs

@@ -6,6 +6,18 @@ import { patchTree } from "../tree/tree-patch.mjs";
 * 仓库对象操作组装
 */
 /**
+* 空 tree 的规范原始对象
+*
+* 空 tree 序列化后内容为空，header 为 "tree 0\0"，
+* 其 SHA-1 是 Git 通用已知常数。
+* 预计算一份避免每次重复序列化和哈希。
+*/
+const EMPTY_TREE_RAW = {
+	hash: hashObject("tree", Buffer.alloc(0)),
+	type: "tree",
+	content: Buffer.alloc(0)
+};
+/**
 * 创建仓库对象相关操作
 *
 * @example
@@ -36,6 +48,10 @@ function createObjectRepositoryOperations(objects) {
 			return objects.list();
 		},
 		createTree(entries) {
+			if (entries.length === 0) {
+				objects.ingest(EMPTY_TREE_RAW);
+				return EMPTY_TREE_RAW.hash;
+			}
 			return writeObject(objects, {
 				type: "tree",
 				entries

package/dist/workdir/change-index.d.mts

@@ -14,7 +14,7 @@ interface NormalizedChangeRecord {
   readonly previous: VirtualDiffObject | null;
   /** 变更后对象 */
   readonly current: VirtualDiffObject | null;
-  /** rename/copy 来源 */
+  /** move/copy 来源 */
   readonly source: VirtualDiffSource | null;
 }
 //#endregion

package/dist/workdir/change-index.mjs

@@ -76,7 +76,7 @@ function rebuildNormalizedChangeIndex(source, state, cache) {
 				previous: renameFrom.previous,
 				current: addRecord.current,
 				source: {
-					kind: "rename",
+					kind: "move",
 					path: renameFrom.path
 				}
 			});
@@ -155,17 +155,17 @@ function refreshChangeRecordForPath(source, state, path, cache) {
 	state.setChangeRecord(nextRecord);
 }
 /**
-* 将单一路径的变更记录折叠为 rename 目标路径。
+* 将单一路径的变更记录折叠为 move 目标路径。
 *
-* 仅适用于叶子节点 rename；
+* 仅适用于叶子节点 move；
 * 目录及无法判定来源的情况应由调用方回退到全量重建。
 */
 function rewriteChangeRecordForRename(source, state, from, to, cache) {
 	const previousRecord = state.getChangeRecord(from);
 	const currentTarget = snapshotCurrentEntryAtPath(source, state, to, cache);
-	if (currentTarget === null) throw new Error(`Cannot rewrite rename change record for missing path: ${to}`);
+	if (currentTarget === null) throw new Error(`Cannot rewrite move change record for missing path: ${to}`);
 	const nextRecord = computeRenameRecordForPath(source, state, from, to, previousRecord, currentTarget);
-	if (nextRecord === null) throw new Error(`Cannot rewrite rename change record from '${from}' to '${to}'`);
+	if (nextRecord === null) throw new Error(`Cannot rewrite move change record from '${from}' to '${to}'`);
 	state.deleteChangeRecord(from);
 	state.setChangeRecord(nextRecord);
 }
@@ -279,7 +279,7 @@ function computeRenameRecordForPath(source, state, from, to, previousRecord, cur
 	if (derivedFromPrevious !== void 0) return derivedFromPrevious;
 	const baseEntry = baseSnapshotEntryAtPath(source, state.readBaseTree(), from);
 	if (baseEntry === null) return null;
-	return createNormalizedChangeRecord(to, baseEntry.object, currentTarget.object, createDiffSource("rename", from));
+	return createNormalizedChangeRecord(to, baseEntry.object, currentTarget.object, createDiffSource("move", from));
 }
 function deriveCopySource(from, sourceRecord, source, state) {
 	const fromRecordSource = sourceRecord?.source;
@@ -288,7 +288,7 @@ function deriveCopySource(from, sourceRecord, source, state) {
 	return null;
 }
 function preserveLineageRecordForPath(path, previousRecord, currentEntry) {
-	if (previousRecord?.source?.kind === "rename" && previousRecord.previous !== null) {
+	if (previousRecord?.source?.kind === "move" && previousRecord.previous !== null) {
 		if (currentEntry === null) return null;
 		return createNormalizedChangeRecord(path, previousRecord.previous, currentEntry.object, previousRecord.source);
 	}
@@ -302,7 +302,7 @@ function deriveRenameRecordFromPreviousRecord(from, to, previousRecord, currentT
 	if (previousRecord.current === null) return null;
 	if (previousRecord.source !== null) return createNormalizedChangeRecord(to, previousRecord.previous, currentTarget.object, previousRecord.source);
 	if (previousRecord.previous === null) return createNormalizedChangeRecord(to, null, currentTarget.object);
-	return createNormalizedChangeRecord(to, previousRecord.previous, currentTarget.object, createDiffSource("rename", from));
+	return createNormalizedChangeRecord(to, previousRecord.previous, currentTarget.object, createDiffSource("move", from));
 }
 function snapshotCurrentEntryAtPath(source, state, path, cache) {
 	const resolved = resolveCurrentLeafAtPath(source, state, path);

package/dist/workdir/core.d.mts

@@ -50,11 +50,11 @@ interface VirtualDiffObject {
   readonly hash: SHA1;
 }
 /**
- * rename/copy 来源描述
+ * move/copy 来源描述
  */
 interface VirtualDiffSource {
   /** 来源类型 */
-  readonly kind: "rename" | "copy";
+  readonly kind: "move" | "copy";
   /** 来源路径 */
   readonly path: string;
 }
@@ -77,7 +77,7 @@ interface VirtualDiffChanges {
 type VirtualDiffEntry = {
   /** 新建路径 */readonly kind: "create"; /** 当前路径 */
   readonly path: string; /** 当前对象 */
-  readonly current: VirtualDiffObject; /** rename/copy 的来源 */
+  readonly current: VirtualDiffObject; /** move/copy 的来源 */
   readonly source?: VirtualDiffSource;
 } | {
   /** 删除路径 */readonly kind: "remove"; /** 当前路径 */
@@ -88,7 +88,7 @@ type VirtualDiffEntry = {
   readonly path: string; /** 更新前对象 */
   readonly previous: VirtualDiffObject; /** 更新后对象 */
   readonly current: VirtualDiffObject; /** 变化维度 */
-  readonly changes: VirtualDiffChanges; /** rename/copy 的来源 */
+  readonly changes: VirtualDiffChanges; /** move/copy 的来源 */
   readonly source?: VirtualDiffSource;
 };
 /**
@@ -158,17 +158,19 @@ interface VirtualWorkdir {
     readonly force?: boolean;
   }): void;
   /**
-   * 重命名路径
+   * 移动路径（可跨目录树）
    *
    * 只做路径重绑定，不退化为 delete + write。
-   * 目录重命名后，子项保持懒加载。
+   * 目标父目录不存在时会自动创建中间目录。
+   * 目录移动后，子项保持懒加载。
    */
-  rename(from: string, to: string): void;
+  move(from: string, to: string): void;
   /**
    * 复制路径
    *
    * 新建 workdir node，共享 origin，不共享 node 身份。
-   * 目录复制为浅复制，子项保持懒加载。
+   * 目录复制采用 CoW（写时复制）：子树节点共享同一份 origin 引用，
+   * 任一副本下的子项被修改时才会真正分裂出独立副本。
    */
   copy(from: string, to: string): void;
   /**