nano-git 0.3.1 → 0.3.2

package/dist/workdir/change-index-plan.mjs

@@ -1,9 +1,9 @@
-import { resolvePath } from "./session-internal.mjs";
+import { resolvePath } from "./workdir-path.mjs";
 //#region src/workdir/change-index-plan.ts
 /**
 * Virtual Workdir change-index 刷新策略
 *
-* 把 session 写路径里的“是否允许增量刷新”判断与
+* 把 workdir 写路径里的“是否允许增量刷新”判断与
 * “应该执行哪种 change-index 更新动作”集中到单独模块。
 */
 /**

package/dist/workdir/change-index.mjs

@@ -1,6 +1,6 @@
 import { hashObject } from "../core/hash-digest.mjs";
 import { readRepoBlobContent, readRepoTree } from "./origin.mjs";
-import { getDirectoryChildrenView, joinChildPath, resolveCurrentLeafAtPath } from "./session-internal.mjs";
+import { getDirectoryChildrenView, joinChildPath, resolveCurrentLeafAtPath } from "./workdir-path.mjs";
 import { observeListedDirectoryChild } from "./directory-view.mjs";
 //#region src/workdir/change-index.ts
 /**
@@ -15,7 +15,7 @@ import { observeListedDirectoryChild } from "./directory-view.mjs";
 */
 const baseSnapshotCache = /* @__PURE__ */ new WeakMap();
 /**
-* 重建当前 session 的规范化变更索引。
+* 重建当前 workdir 的规范化变更索引。
 *
 * @example
 * ```ts
@@ -173,7 +173,7 @@ function rewriteChangeRecordForRename(source, state, from, to, cache) {
 * 为 copy 目标路径写入折叠后的变更记录。
 *
 * 仅适用于叶子节点 copy；
-* session-only 来源允许退化为普通 create。
+* workdir-only 来源允许退化为普通 create。
 */
 function writeChangeRecordForCopy(source, state, from, to, cache) {
 	const sourceRecord = state.getChangeRecord(from);
@@ -218,7 +218,7 @@ function baseSnapshotViewForTree(source, treeHash) {
 }
 function snapshotCurrentTree(source, state, cache) {
 	const root = state.getNode("root");
-	if (root === null) throw new Error("Virtual workdir session is missing root node");
+	if (root === null) throw new Error("Virtual workdir is missing root node");
 	return snapshotCurrentNode(source, state, root, "", cache);
 }
 function snapshotCurrentNode(source, state, node, path, cache) {
@@ -398,7 +398,7 @@ function modeKind(mode) {
 	return mode === "120000" ? "symlink" : "blob";
 }
 /**
-* 从规范化变更索引导出当前 session 的最终 diff。
+* 从规范化变更索引导出当前 workdir 的最终 diff。
 *
 * @example
 * ```ts

package/dist/workdir/core.d.mts

@@ -1,5 +1,4 @@
 import { SHA1 } from "../core/types.mjs";
-import { ObjectDatabase } from "../core/types/odb.mjs";
 import { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "../core/errors.mjs";
 
 //#region src/workdir/core.d.ts
@@ -93,42 +92,36 @@ type VirtualDiffEntry = {
   readonly source?: VirtualDiffSource;
 };
 /**
- * 创建 VirtualWorkdirSession 的选项
+ * 创建 VirtualWorkdir 的选项
  */
-interface CreateVirtualWorkdirSessionOptions {
+interface CreateVirtualWorkdirOptions {
   /** 基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
 }
 /**
- * Virtual Workdir session 标识
- */
-type VirtualWorkdirSessionId = string & {
-  readonly __brand: "VirtualWorkdirSessionId";
-};
-/**
- * VirtualWorkdirSession（虚拟工作目录会话）
+ * VirtualWorkdir（虚拟工作目录实例）
  *
  * 提供独立生命周期的可变 tree 视图，基于 `baseTree + CoW overlay` 模型。
  * 不绑定 commit，不涉及 Git index / 真实工作目录。
  *
- * 当前 session 对 origin 仓库对象采用弱保证：
+ * 当前实例对 origin 仓库对象采用弱保证：
  * 如果 base tree / origin blob 在后续被移除、损坏或不可读取，
  * 相关读取、`revert()`、`writeTree()` 等操作会抛出 `VirtualOriginUnavailableError`。
  *
  * @example
  * ```ts
  * import { createMemoryRepository } from "nano-git/repository/memory";
- * import { createVirtualWorkdirSession } from "nano-git/workdir/memory";
+ * import { createVirtualWorkdir } from "nano-git/workdir/memory";
  *
  * const repo = createMemoryRepository();
  * const tree = repo.writeTree(); // 初始空 tree
- * const session = createVirtualWorkdirSession(repo, { baseTree: tree });
+ * const workdir = createVirtualWorkdir(repo.objects, { baseTree: tree });
  *
- * session.writeFile("hello.txt", Buffer.from("world"));
- * const newTree = session.writeTree();
+ * workdir.writeFile("hello.txt", Buffer.from("world"));
+ * const newTree = workdir.writeTree();
  * ```
  */
-interface VirtualWorkdirSession {
+interface VirtualWorkdir {
   /** 当前基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
   /** 路径是否存在 */
@@ -161,7 +154,7 @@ interface VirtualWorkdirSession {
   /**
    * 复制路径
    *
-   * 新建 session node，共享 origin，不共享 node 身份。
+   * 新建 workdir node，共享 origin，不共享 node 身份。
    * 目录复制为浅复制，子项保持懒加载。
    */
   copy(from: string, to: string): void;
@@ -186,35 +179,11 @@ interface VirtualWorkdirSession {
    */
   writeTree(): SHA1;
   /**
-   * 重置 session 到指定基线 tree
+   * 重置当前实例到指定基线 tree
    *
    * 丢弃全部 overlay 与变更历史。
    */
   reset(baseTree: SHA1): void;
 }
-/**
- * VirtualWorkdirBackend
- *
- * session 内部状态存储的抽象接口。
- * memory / file / sqlite 后端通过实现此接口来提供不同的持久化策略。
- *
- * `file` / `sqlite` 持久化 backend 当前都按单进程、单写者场景收口；
- * 不承诺跨进程并发写安全，也不提供多写者协调协议。
- *
- * 本接口在后续 Phase 中会逐步补充完整方法签名。
- * 当前仅为命名冻结与角色声明。
- */
-interface VirtualWorkdirBackend {
-  /** 后端类型标识 */
-  readonly kind: "memory" | "file" | "sqlite";
-  /** 创建新 session 并返回其标识 */
-  createSession(options: CreateVirtualWorkdirSessionOptions): VirtualWorkdirSessionId;
-  /** 打开已存在的 session */
-  openSession(source: ObjectDatabase, sessionId: VirtualWorkdirSessionId): VirtualWorkdirSession;
-  /** 删除 session */
-  deleteSession(sessionId: VirtualWorkdirSessionId): void;
-  /** 列出当前后端中可完整恢复的 session */
-  listSessions(): VirtualWorkdirSessionId[];
-}
 //#endregion
-export { CreateVirtualWorkdirSessionOptions, VirtualDiffChanges, VirtualDiffEntry, VirtualDiffObject, VirtualDiffSource, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession, VirtualWorkdirSessionId };
+export { CreateVirtualWorkdirOptions, VirtualDiffChanges, VirtualDiffEntry, VirtualDiffObject, VirtualDiffSource, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdir };

package/dist/workdir/directory-view.mjs

@@ -1,10 +1,10 @@
 import { VirtualNotDirectoryError } from "../core/errors.mjs";
-import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./session-internal.mjs";
+import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./workdir-path.mjs";
 //#region src/workdir/directory-view.ts
 /**
 * Virtual Workdir 目录展开、观察与编译计划
 *
-* 从 session-internal.ts 拆分，聚焦以下职责：
+* 从 workdir-path.ts 拆分，聚焦以下职责：
 * - 目录子项观察（observeDirectoryChildren / observeListedDirectoryChild / observeNamedDirectoryChild）
 * - origin 按名查询视图（createNamedOriginChildLookup）
 * - 受影响子项编译计划（planAffectedDirectoryChildren）

package/dist/workdir/dirty-dir-plan.mjs

@@ -1,12 +1,12 @@
-import { getRootNode } from "./session-internal.mjs";
+import { getRootNode } from "./workdir-path.mjs";
 import { observeDirectoryChildren } from "./directory-view.mjs";
 import { createDirtyDirSummary } from "./dirty-dir.mjs";
 //#region src/workdir/dirty-dir-plan.ts
 /**
 * Virtual Workdir dirty-dir summary 重建策略
 *
-* 把 session 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
-* 让 session.ts 更接近纯编排层。
+* 把 workdir 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
+* 让 workdir.ts 更接近纯编排层。
 */
 /**
 * 创建 dirty-dir summary 策略器。

package/dist/workdir/file-backend.d.mts

@@ -1,22 +1,44 @@
-import { VirtualWorkdirBackend } from "./core.mjs";
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
+import { VirtualWorkdirStateStore } from "./state-store.mjs";
 
 //#region src/workdir/file-backend.d.ts
-/** 创建文件系统 Virtual Workdir backend 的可选参数 */
-interface CreateFileVirtualWorkdirBackendOptions {
-  /** session 根目录名，默认 `sessions` */
-  readonly sessionsDirName?: string;
+/** 打开文件系统 VirtualWorkdir 的可选参数 */
+interface OpenFileVirtualWorkdirOptions extends CreateVirtualWorkdirOptions {
+  /** 不存在时按 baseTree 初始化 */
+  readonly create?: boolean;
 }
 /**
- * 创建基于文件系统目录的 Virtual Workdir backend
+ * 打开基于目录持久化的 VirtualWorkdir
  *
  * @example
  * ```ts
- * const backend = createFileVirtualWorkdirBackend("/tmp/workdirs");
- * const sessionId = backend.createSession({ baseTree: tree });
- * const session = backend.openSession(repo.objects, sessionId);
- * expect(session.baseTree).toBe(tree);
+ * const workdir = openFileVirtualWorkdir(repo.objects, "/tmp/workdir", {
+ *   baseTree: tree,
+ *   create: true,
+ * });
+ * expect(workdir.baseTree).toBe(tree);
  * ```
  */
-declare function createFileVirtualWorkdirBackend(rootDir: string, options?: CreateFileVirtualWorkdirBackendOptions): VirtualWorkdirBackend;
+declare function openFileVirtualWorkdir(source: ObjectDatabase, workdirDir: string, options: OpenFileVirtualWorkdirOptions): VirtualWorkdir;
+/**
+ * 删除指定目录上的持久化 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * deleteFileVirtualWorkdir("/tmp/workdir");
+ * ```
+ */
+declare function deleteFileVirtualWorkdir(workdirDir: string): void;
+/**
+ * 创建单个文件系统 VirtualWorkdir 的状态存储
+ *
+ * @example
+ * ```ts
+ * const store = createFileVirtualWorkdirStateStore("/tmp/workdir");
+ * expect(store.kind).toBe("file");
+ * ```
+ */
+declare function createFileVirtualWorkdirStateStore(workdirDir: string): VirtualWorkdirStateStore;
 //#endregion
-export { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };
+export { OpenFileVirtualWorkdirOptions, createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };

package/dist/workdir/file-backend.mjs

@@ -1,83 +1,71 @@
 import { sha1 } from "../core/types.mjs";
 import { createRootDirectoryNode } from "./nodes.mjs";
-import { createVirtualWorkdirSessionId } from "./session-id.mjs";
-import { openVirtualWorkdirSession } from "./session.mjs";
+import { openVirtualWorkdir } from "./workdir.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 //#region src/workdir/file-backend.ts
 /**
-* Virtual Workdir 文件系统 backend
+* Virtual Workdir 文件系统持久化实现
 */
 const FILE_WORKDIR_MANIFEST_VERSION = 5;
 const FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX = ".txn-snapshot";
 /**
-* 创建基于文件系统目录的 Virtual Workdir backend
+* 打开基于目录持久化的 VirtualWorkdir
 *
 * @example
 * ```ts
-* const backend = createFileVirtualWorkdirBackend("/tmp/workdirs");
-* const sessionId = backend.createSession({ baseTree: tree });
-* const session = backend.openSession(repo.objects, sessionId);
-* expect(session.baseTree).toBe(tree);
+* const workdir = openFileVirtualWorkdir(repo.objects, "/tmp/workdir", {
+*   baseTree: tree,
+*   create: true,
+* });
+* expect(workdir.baseTree).toBe(tree);
 * ```
 */
-function createFileVirtualWorkdirBackend(rootDir, options = {}) {
-	const sessionsRoot = join(rootDir, options.sessionsDirName ?? "sessions");
-	mkdirSync(sessionsRoot, { recursive: true });
-	return {
-		kind: "file",
-		createSession(options) {
-			const sessionId = createVirtualWorkdirSessionId();
-			createFileVirtualWorkdirStateStore(sessionsRoot, sessionId).reset(options.baseTree);
-			return sessionId;
-		},
-		openSession(source, sessionId) {
-			if (!hasSession(sessionsRoot, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-			validateSessionIntegrity(sessionsRoot, sessionId);
-			return openVirtualWorkdirSession(source, createFileVirtualWorkdirStateStore(sessionsRoot, sessionId));
-		},
-		deleteSession(sessionId) {
-			if (!hasSession(sessionsRoot, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-			rmSync(getSessionDir(sessionsRoot, sessionId), {
-				recursive: true,
-				force: true
-			});
-		},
-		listSessions() {
-			if (!existsSync(sessionsRoot)) return [];
-			return readdirSync(sessionsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => !entry.name.endsWith(FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX)).filter((entry) => existsSync(getManifestPath(join(sessionsRoot, entry.name)))).map((entry) => decodePathToken(entry.name)).filter((sessionId) => {
-				try {
-					validateSessionIntegrity(sessionsRoot, sessionId);
-					return true;
-				} catch {
-					return false;
-				}
-			}).sort();
-		}
-	};
+function openFileVirtualWorkdir(source, workdirDir, options) {
+	const store = createFileVirtualWorkdirStateStore(workdirDir);
+	if (!hasFileVirtualWorkdir(workdirDir)) {
+		if (options.create !== true) throw new Error(`Virtual workdir not found: ${workdirDir}`);
+		store.reset(options.baseTree);
+	}
+	validateFileVirtualWorkdirIntegrity(workdirDir);
+	return openVirtualWorkdir(source, store);
+}
+/**
+* 删除指定目录上的持久化 VirtualWorkdir
+*
+* @example
+* ```ts
+* deleteFileVirtualWorkdir("/tmp/workdir");
+* ```
+*/
+function deleteFileVirtualWorkdir(workdirDir) {
+	if (!hasFileVirtualWorkdir(workdirDir)) throw new Error(`Virtual workdir not found: ${workdirDir}`);
+	rmSync(workdirDir, {
+		recursive: true,
+		force: true
+	});
 }
 /**
-* 创建单个 session 的文件系统状态存储
+* 创建单个文件系统 VirtualWorkdir 的状态存储
 *
 * @example
 * ```ts
-* const store = createFileVirtualWorkdirStateStore("/tmp/workdirs/sessions", sessionId);
+* const store = createFileVirtualWorkdirStateStore("/tmp/workdir");
 * expect(store.kind).toBe("file");
 * ```
 */
-function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
-	const sessionDir = getSessionDir(sessionsRoot, sessionId);
-	const manifestPath = getManifestPath(sessionDir);
-	const contentDir = getContentDir(sessionDir);
+function createFileVirtualWorkdirStateStore(workdirDir) {
+	const manifestPath = getManifestPath(workdirDir);
+	const contentDir = getContentDir(workdirDir);
 	return {
 		kind: "file",
 		transact(fn) {
-			const snapshotDir = `${sessionDir}${FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX}`;
+			const snapshotDir = `${workdirDir}${FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX}`;
 			rmSync(snapshotDir, {
 				recursive: true,
 				force: true
 			});
-			if (existsSync(sessionDir)) copyDirectoryRecursive(sessionDir, snapshotDir);
+			if (existsSync(workdirDir)) copyDirectoryRecursive(workdirDir, snapshotDir);
 			try {
 				const result = fn();
 				rmSync(snapshotDir, {
@@ -86,11 +74,11 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 				});
 				return result;
 			} catch (error) {
-				rmSync(sessionDir, {
+				rmSync(workdirDir, {
 					recursive: true,
 					force: true
 				});
-				if (existsSync(snapshotDir)) renameSync(snapshotDir, sessionDir);
+				if (existsSync(snapshotDir)) renameSync(snapshotDir, workdirDir);
 				throw error;
 			}
 		},
@@ -98,7 +86,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			return readManifest(manifestPath).baseTree;
 		},
 		writeBaseTree(baseTree) {
-			updateManifest(sessionDir, (manifest) => ({
+			updateManifest(workdirDir, (manifest) => ({
 				...manifest,
 				baseTree
 			}));
@@ -109,7 +97,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			return restoreNode(record, contentDir);
 		},
 		setNode(node) {
-			updateManifest(sessionDir, (manifest) => {
+			updateManifest(workdirDir, (manifest) => {
 				const record = persistNode(contentDir, node);
 				return {
 					...manifest,
@@ -121,7 +109,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			});
 		},
 		deleteNode(id) {
-			updateManifest(sessionDir, (manifest) => {
+			updateManifest(workdirDir, (manifest) => {
 				if (manifest.nodes[id] === void 0) return manifest;
 				const { [id]: _deleted, ...rest } = manifest.nodes;
 				return {
@@ -137,7 +125,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			return readManifest(manifestPath).changeRecords.map(restoreChangeRecord).find((record) => record.path === path) ?? null;
 		},
 		setChangeRecord(record) {
-			updateManifest(sessionDir, (manifest) => {
+			updateManifest(workdirDir, (manifest) => {
 				const others = manifest.changeRecords.filter((item) => item.path !== record.path);
 				return {
 					...manifest,
@@ -146,7 +134,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			});
 		},
 		deleteChangeRecord(path) {
-			updateManifest(sessionDir, (manifest) => ({
+			updateManifest(workdirDir, (manifest) => ({
 				...manifest,
 				changeRecords: manifest.changeRecords.filter((item) => item.path !== path)
 			}));
@@ -158,7 +146,7 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			return readManifest(manifestPath).dirtyDirSummaries.map(restoreDirtyDirSummary).find((summary) => summary.path === path) ?? null;
 		},
 		setDirtyDirSummary(summary) {
-			updateManifest(sessionDir, (manifest) => {
+			updateManifest(workdirDir, (manifest) => {
 				const others = manifest.dirtyDirSummaries.filter((item) => item.path !== summary.path);
 				return {
 					...manifest,
@@ -167,46 +155,42 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 			});
 		},
 		deleteDirtyDirSummary(path) {
-			updateManifest(sessionDir, (manifest) => ({
+			updateManifest(workdirDir, (manifest) => ({
 				...manifest,
 				dirtyDirSummaries: manifest.dirtyDirSummaries.filter((item) => item.path !== path)
 			}));
 		},
 		reset(baseTree) {
-			rmSync(sessionDir, {
+			rmSync(workdirDir, {
 				recursive: true,
 				force: true
 			});
-			ensureSessionDirs(sessionDir, contentDir);
+			ensureWorkdirDirs(workdirDir, contentDir);
 			writeManifestAtomic(manifestPath, createManifest(baseTree, { [createRootDirectoryNode(baseTree).id]: serializeDirectoryNode(createRootDirectoryNode(baseTree)) }));
 		}
 	};
 }
-function hasSession(sessionsRoot, sessionId) {
-	return existsSync(getManifestPath(getSessionDir(sessionsRoot, sessionId)));
+function hasFileVirtualWorkdir(workdirDir) {
+	return existsSync(getManifestPath(workdirDir));
 }
-function validateSessionIntegrity(sessionsRoot, sessionId) {
-	const sessionDir = getSessionDir(sessionsRoot, sessionId);
-	const manifest = readManifest(getManifestPath(sessionDir));
+function validateFileVirtualWorkdirIntegrity(workdirDir) {
+	const manifest = readManifest(getManifestPath(workdirDir));
 	const root = manifest.nodes.root;
-	if (root === void 0) throw new Error(`Virtual workdir session is corrupted: missing root node for ${sessionId}`);
-	if (restoreNode(root, getContentDir(sessionDir)).state.kind !== "directory") throw new Error(`Virtual workdir session is corrupted: root node is not a directory for ${sessionId}`);
-	for (const record of Object.values(manifest.nodes)) restoreNode(record, getContentDir(sessionDir));
+	if (root === void 0) throw new Error(`Virtual workdir is corrupted: missing root node for ${workdirDir}`);
+	if (restoreNode(root, getContentDir(workdirDir)).state.kind !== "directory") throw new Error(`Virtual workdir is corrupted: root node is not a directory for ${workdirDir}`);
+	for (const record of Object.values(manifest.nodes)) restoreNode(record, getContentDir(workdirDir));
 }
-function getSessionDir(sessionsRoot, sessionId) {
-	return join(sessionsRoot, encodePathToken(sessionId));
+function getManifestPath(workdirDir) {
+	return join(workdirDir, "manifest.json");
 }
-function getManifestPath(sessionDir) {
-	return join(sessionDir, "manifest.json");
-}
-function getContentDir(sessionDir) {
-	return join(sessionDir, "content");
+function getContentDir(workdirDir) {
+	return join(workdirDir, "content");
 }
 function getContentPath(contentDir, payloadRef) {
 	return join(contentDir, `${encodePathToken(payloadRef)}.bin`);
 }
-function ensureSessionDirs(sessionDir, contentDir) {
-	mkdirSync(sessionDir, { recursive: true });
+function ensureWorkdirDirs(workdirDir, contentDir) {
+	mkdirSync(workdirDir, { recursive: true });
 	mkdirSync(contentDir, { recursive: true });
 }
 function copyDirectoryRecursive(sourceDir, targetDir) {
@@ -230,16 +214,16 @@ function createManifest(baseTree, nodes) {
 		dirtyDirSummaries: []
 	};
 }
-function updateManifest(sessionDir, updater) {
-	const manifestPath = getManifestPath(sessionDir);
-	ensureSessionDirs(sessionDir, getContentDir(sessionDir));
+function updateManifest(workdirDir, updater) {
+	const manifestPath = getManifestPath(workdirDir);
+	ensureWorkdirDirs(workdirDir, getContentDir(workdirDir));
 	writeManifestAtomic(manifestPath, updater(readManifest(manifestPath)));
 }
 function writeManifestAtomic(path, manifest) {
 	writeJsonAtomic(path, manifest);
 }
 function readManifest(manifestPath) {
-	if (!existsSync(manifestPath)) throw new Error(`Virtual workdir session manifest not found: ${manifestPath}`);
+	if (!existsSync(manifestPath)) throw new Error(`Virtual workdir manifest not found: ${manifestPath}`);
 	const manifest = readJson(manifestPath);
 	validateManifest(manifest);
 	return manifest;
@@ -445,8 +429,5 @@ function writeBufferAtomic(path, value) {
 function encodePathToken(value) {
 	return encodeURIComponent(value);
 }
-function decodePathToken(value) {
-	return decodeURIComponent(value);
-}
 //#endregion
-export { createFileVirtualWorkdirBackend };
+export { createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };

package/dist/workdir/file.d.mts

@@ -1,2 +1,2 @@
-import { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend } from "./file-backend.mjs";
-export { type CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };
+import { OpenFileVirtualWorkdirOptions, createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir } from "./file-backend.mjs";
+export { type OpenFileVirtualWorkdirOptions, createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };

package/dist/workdir/file.mjs

@@ -1,2 +1,2 @@
-import { createFileVirtualWorkdirBackend } from "./file-backend.mjs";
-export { createFileVirtualWorkdirBackend };
+import { createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir } from "./file-backend.mjs";
+export { createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };

package/dist/workdir/ids.d.mts

@@ -1,5 +1,5 @@
 //#region src/workdir/ids.d.ts
-/** 会话内节点的稳定身份 */
+/** workdir 内节点的稳定身份 */
 type NodeId = string & {
   readonly __brand: "NodeId";
 };

package/dist/workdir/ids.mjs

@@ -1,9 +1,9 @@
 //#region src/workdir/ids.ts
-/** 根目录节点的固定 ID（每个 session 一致） */
+/** 根目录节点的固定 ID（每个 workdir 一致） */
 const VIRTUAL_ROOT_NODE_ID = "root";
 let nextNodeCounter = 1;
 /**
-* 分配新的 session 节点 ID
+* 分配新的 workdir 节点 ID
 */
 function createNodeId() {
 	const id = `node:${nextNodeCounter}`;
@@ -11,7 +11,7 @@ function createNodeId() {
 	return id;
 }
 /**
-* 为仓库对象哈希派生稳定的 session 节点 ID（懒加载、未 copy 前复用）
+* 为仓库对象哈希派生稳定的 workdir 节点 ID（懒加载、未 copy 前复用）
 */
 function originBackedNodeId(hash) {
 	return `origin:${hash}`;

package/dist/workdir/memory-backend.mjs

@@ -1,7 +1,5 @@
 import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
 import { createRootDirectoryNode } from "./nodes.mjs";
-import { createVirtualWorkdirSessionId } from "./session-id.mjs";
-import { openVirtualWorkdirSession } from "./session.mjs";
 //#region src/workdir/memory-backend.ts
 /**
 * Virtual Workdir 内存状态存储
@@ -78,39 +76,6 @@ function createVirtualWorkdirMemoryStateStore(baseTree) {
 		}
 	};
 }
-/**
-* 创建内存版 Virtual Workdir backend
-*
-* @example
-* ```ts
-* const backend = createMemoryVirtualWorkdirBackend();
-* const sessionId = backend.createSession({ baseTree: tree });
-* const session = backend.openSession(repo.objects, sessionId);
-* expect(session.baseTree).toBe(tree);
-* ```
-*/
-function createMemoryVirtualWorkdirBackend() {
-	const sessions = /* @__PURE__ */ new Map();
-	return {
-		kind: "memory",
-		createSession(options) {
-			const sessionId = createVirtualWorkdirSessionId();
-			sessions.set(sessionId, createVirtualWorkdirMemoryStateStore(options.baseTree));
-			return sessionId;
-		},
-		openSession(source, sessionId) {
-			const store = sessions.get(sessionId);
-			if (store === void 0) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-			return openVirtualWorkdirSession(source, store);
-		},
-		deleteSession(sessionId) {
-			if (!sessions.delete(sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-		},
-		listSessions() {
-			return Array.from(sessions.keys());
-		}
-	};
-}
 function resetState(state, baseTree) {
 	state.baseTree = baseTree;
 	state.nodes.clear();
@@ -120,7 +85,7 @@ function resetState(state, baseTree) {
 }
 function snapshotState(state) {
 	const nodes = /* @__PURE__ */ new Map();
-	for (const [nodeId, node] of state.nodes) nodes.set(nodeId, cloneSessionNode(node));
+	for (const [nodeId, node] of state.nodes) nodes.set(nodeId, cloneWorkdirNode(node));
 	return {
 		baseTree: state.baseTree,
 		nodes,
@@ -133,11 +98,11 @@ function restoreState(state, snapshot) {
 	state.nodes.clear();
 	state.changeRecords.clear();
 	state.dirtyDirSummaries.clear();
-	for (const [nodeId, node] of snapshot.nodes) state.nodes.set(nodeId, cloneSessionNode(node));
+	for (const [nodeId, node] of snapshot.nodes) state.nodes.set(nodeId, cloneWorkdirNode(node));
 	for (const [path, record] of snapshot.changeRecords) state.changeRecords.set(path, record);
 	for (const [path, summary] of snapshot.dirtyDirSummaries) state.dirtyDirSummaries.set(path, summary);
 }
-function cloneSessionNode(node) {
+function cloneWorkdirNode(node) {
 	if (node.state.kind === "directory") return {
 		id: node.id,
 		origin: node.origin,
@@ -175,4 +140,4 @@ function cloneSessionNode(node) {
 	};
 }
 //#endregion
-export { createMemoryVirtualWorkdirBackend, createVirtualWorkdirMemoryStateStore };
+export { createVirtualWorkdirMemoryStateStore };

package/dist/workdir/memory.d.mts

@@ -1,3 +1,2 @@
-import { createMemoryVirtualWorkdirBackend } from "./memory-backend.mjs";
-import { createVirtualWorkdirSession, openVirtualWorkdirSession } from "./session.mjs";
-export { createMemoryVirtualWorkdirBackend, createVirtualWorkdirSession, openVirtualWorkdirSession };
+import { createVirtualWorkdir, openVirtualWorkdir } from "./workdir.mjs";
+export { createVirtualWorkdir, openVirtualWorkdir };