nano-git 0.3.1 → 0.3.3

package/dist/workdir/sqlite-backend.mjs

@@ -1,90 +1,85 @@
 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 { Database } from "bun:sqlite";
 //#region src/workdir/sqlite-backend.ts
 /**
 * Virtual Workdir SQLite backend
 */
-const WORKDIR_SQLITE_SCHEMA_VERSION = 5;
+const WORKDIR_SQLITE_SCHEMA_VERSION = 6;
 /**
-* 创建基于 SQLite 的 Virtual Workdir backend
+* 打开基于 SQLite 的持久化 VirtualWorkdir
 *
 * @example
 * ```ts
-* using backend = createSqliteVirtualWorkdirBackend(":memory:");
-* const sessionId = backend.createSession({ baseTree: tree });
-* const session = backend.openSession(repo.objects, sessionId);
-* expect(session.baseTree).toBe(tree);
+* using workdir = openSqliteVirtualWorkdir(repo.objects, ":memory:", "demo", {
+*   baseTree: tree,
+*   create: true,
+* });
+* expect(workdir.baseTree).toBe(tree);
 * ```
 */
-function createSqliteVirtualWorkdirBackend(dbPath, options = {}) {
+function openSqliteVirtualWorkdir(source, dbPath, workdirKey, options) {
 	const db = new Database(dbPath);
-	let disposed = false;
 	if (options.walMode !== false) db.run("PRAGMA journal_mode = WAL");
 	ensureSchema(db);
-	return {
-		kind: "sqlite",
-		createSession(options) {
-			assertBackendAvailable(disposed);
-			const sessionId = createVirtualWorkdirSessionId();
-			createSqliteVirtualWorkdirStateStore(db, sessionId).reset(options.baseTree);
-			return sessionId;
-		},
-		openSession(source, sessionId) {
-			assertBackendAvailable(disposed);
-			if (!hasSession(db, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-			validateSessionIntegrity(db, sessionId);
-			return openVirtualWorkdirSession(source, createSqliteVirtualWorkdirStateStore(db, sessionId));
-		},
-		deleteSession(sessionId) {
-			assertBackendAvailable(disposed);
-			if (!hasSession(db, sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-			deleteSessionRows(db, sessionId);
-		},
-		listSessions() {
-			assertBackendAvailable(disposed);
-			return db.query("SELECT session_id FROM workdir_sessions ORDER BY session_id").all().map((row) => row.session_id).filter((sessionId) => {
-				try {
-					validateSessionIntegrity(db, sessionId);
-					return true;
-				} catch {
-					return false;
-				}
-			});
-		},
-		[Symbol.dispose]() {
-			if (disposed) return;
-			disposed = true;
+	const store = createSqliteVirtualWorkdirStateStore(db, workdirKey);
+	if (!hasWorkdir(db, workdirKey)) {
+		if (options.create !== true) {
 			db.close();
+			throw new Error(`Virtual workdir not found: ${workdirKey}`);
 		}
-	};
+		store.reset(options.baseTree);
+	}
+	validateWorkdirIntegrity(db, workdirKey);
+	let disposed = false;
+	const workdir = openVirtualWorkdir(source, store);
+	return Object.assign(workdir, { [Symbol.dispose]() {
+		if (disposed) return;
+		disposed = true;
+		db.close();
+	} });
 }
-function assertBackendAvailable(disposed) {
-	if (disposed) throw new Error("SQLite virtual workdir backend is disposed");
+/**
+* 删除指定 key 上的 SQLite VirtualWorkdir
+*
+* @example
+* ```ts
+* deleteSqliteVirtualWorkdir("/tmp/workdir.sqlite", "demo");
+* ```
+*/
+function deleteSqliteVirtualWorkdir(dbPath, workdirKey, options = {}) {
+	const db = new Database(dbPath);
+	try {
+		if (options.walMode !== false) db.run("PRAGMA journal_mode = WAL");
+		ensureSchema(db);
+		if (!hasWorkdir(db, workdirKey)) throw new Error(`Virtual workdir not found: ${workdirKey}`);
+		deleteWorkdirRows(db, workdirKey);
+	} finally {
+		db.close();
+	}
 }
 /**
-* 创建单个 session 的 SQLite 状态存储
+* 创建单个 SQLite VirtualWorkdir 的状态存储
 *
 * @example
 * ```ts
-* const store = createSqliteVirtualWorkdirStateStore(db, sessionId);
+* const store = createSqliteVirtualWorkdirStateStore(db, "demo");
 * expect(store.kind).toBe("sqlite");
 * ```
 */
-function createSqliteVirtualWorkdirStateStore(db, sessionId) {
+function createSqliteVirtualWorkdirStateStore(db, workdirKey) {
 	const transactImpl = db.transaction((fn) => fn());
-	const readBaseTreeStmt = db.query("SELECT base_tree FROM workdir_sessions WHERE session_id = ?");
-	const upsertSessionStmt = db.query("INSERT INTO workdir_sessions (session_id, base_tree) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET base_tree = excluded.base_tree");
+	const readBaseTreeStmt = db.query("SELECT base_tree FROM workdirs WHERE workdir_key = ?");
+	const upsertWorkdirStmt = db.query("INSERT INTO workdirs (workdir_key, base_tree) VALUES (?, ?) ON CONFLICT(workdir_key) DO UPDATE SET base_tree = excluded.base_tree");
 	const getNodeStmt = db.query(`SELECT node_id, origin_kind, origin_hash, origin_mode, state_kind, state_mode, content, target, directory_overlay
      FROM workdir_nodes
-     WHERE session_id = ? AND node_id = ?`);
+     WHERE workdir_key = ? AND node_id = ?`);
 	const setNodeStmt = db.query(`INSERT INTO workdir_nodes (
-        session_id, node_id, origin_kind, origin_hash, origin_mode,
+        workdir_key, node_id, origin_kind, origin_hash, origin_mode,
         state_kind, state_mode, content, target, directory_overlay
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(session_id, node_id) DO UPDATE SET
+      ON CONFLICT(workdir_key, node_id) DO UPDATE SET
         origin_kind = excluded.origin_kind,
         origin_hash = excluded.origin_hash,
         origin_mode = excluded.origin_mode,
@@ -93,20 +88,20 @@ function createSqliteVirtualWorkdirStateStore(db, sessionId) {
         content = excluded.content,
         target = excluded.target,
         directory_overlay = excluded.directory_overlay`);
-	const deleteNodeStmt = db.query("DELETE FROM workdir_nodes WHERE session_id = ? AND node_id = ?");
-	const clearNodesStmt = db.query("DELETE FROM workdir_nodes WHERE session_id = ?");
+	const deleteNodeStmt = db.query("DELETE FROM workdir_nodes WHERE workdir_key = ? AND node_id = ?");
+	const clearNodesStmt = db.query("DELETE FROM workdir_nodes WHERE workdir_key = ?");
 	const listChangesStmt = db.query(`SELECT path, previous_kind, previous_mode, previous_hash, current_kind, current_mode, current_hash, source_kind, source_path
      FROM workdir_changes
-     WHERE session_id = ?
+     WHERE workdir_key = ?
      ORDER BY path`);
 	const getChangeStmt = db.query(`SELECT path, previous_kind, previous_mode, previous_hash, current_kind, current_mode, current_hash, source_kind, source_path
      FROM workdir_changes
-     WHERE session_id = ? AND path = ?`);
+     WHERE workdir_key = ? AND path = ?`);
 	const upsertChangeStmt = db.query(`INSERT INTO workdir_changes (
-      session_id, path, previous_kind, previous_mode, previous_hash,
+      workdir_key, path, previous_kind, previous_mode, previous_hash,
       current_kind, current_mode, current_hash, source_kind, source_path
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(session_id, path) DO UPDATE SET
+    ON CONFLICT(workdir_key, path) DO UPDATE SET
       previous_kind = excluded.previous_kind,
       previous_mode = excluded.previous_mode,
       previous_hash = excluded.previous_hash,
@@ -115,35 +110,35 @@ function createSqliteVirtualWorkdirStateStore(db, sessionId) {
       current_hash = excluded.current_hash,
       source_kind = excluded.source_kind,
       source_path = excluded.source_path`);
-	const deleteChangeStmt = db.query("DELETE FROM workdir_changes WHERE session_id = ? AND path = ?");
-	const clearChangesStmt = db.query("DELETE FROM workdir_changes WHERE session_id = ?");
+	const deleteChangeStmt = db.query("DELETE FROM workdir_changes WHERE workdir_key = ? AND path = ?");
+	const clearChangesStmt = db.query("DELETE FROM workdir_changes WHERE workdir_key = ?");
 	const listDirtyDirsStmt = db.query(`SELECT path, is_dirty, dirty_entry_count, dirty_descendant_count, affected_names, current_tree_hash, hash_state
      FROM workdir_dirty_dirs
-     WHERE session_id = ?
+     WHERE workdir_key = ?
      ORDER BY path`);
 	const getDirtyDirStmt = db.query(`SELECT path, is_dirty, dirty_entry_count, dirty_descendant_count, affected_names, current_tree_hash, hash_state
      FROM workdir_dirty_dirs
-     WHERE session_id = ? AND path = ?`);
+     WHERE workdir_key = ? AND path = ?`);
 	const upsertDirtyDirStmt = db.query(`INSERT INTO workdir_dirty_dirs (
-      session_id, path, is_dirty, dirty_entry_count, dirty_descendant_count,
+      workdir_key, path, is_dirty, dirty_entry_count, dirty_descendant_count,
       affected_names, current_tree_hash, hash_state
     )
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(session_id, path) DO UPDATE SET
+     ON CONFLICT(workdir_key, path) DO UPDATE SET
        is_dirty = excluded.is_dirty,
        dirty_entry_count = excluded.dirty_entry_count,
        dirty_descendant_count = excluded.dirty_descendant_count,
        affected_names = excluded.affected_names,
        current_tree_hash = excluded.current_tree_hash,
        hash_state = excluded.hash_state`);
-	const deleteDirtyDirStmt = db.query("DELETE FROM workdir_dirty_dirs WHERE session_id = ? AND path = ?");
-	const clearDirtyDirsStmt = db.query("DELETE FROM workdir_dirty_dirs WHERE session_id = ?");
+	const deleteDirtyDirStmt = db.query("DELETE FROM workdir_dirty_dirs WHERE workdir_key = ? AND path = ?");
+	const clearDirtyDirsStmt = db.query("DELETE FROM workdir_dirty_dirs WHERE workdir_key = ?");
 	const resetTx = db.transaction((baseTree) => {
-		upsertSessionStmt.run(sessionId, baseTree);
-		clearNodesStmt.run(sessionId);
-		clearChangesStmt.run(sessionId);
-		clearDirtyDirsStmt.run(sessionId);
-		writeNode(setNodeStmt, sessionId, createRootDirectoryNode(baseTree));
+		upsertWorkdirStmt.run(workdirKey, baseTree);
+		clearNodesStmt.run(workdirKey);
+		clearChangesStmt.run(workdirKey);
+		clearDirtyDirsStmt.run(workdirKey);
+		writeNode(setNodeStmt, workdirKey, createRootDirectoryNode(baseTree));
 	});
 	return {
 		kind: "sqlite",
@@ -151,49 +146,49 @@ function createSqliteVirtualWorkdirStateStore(db, sessionId) {
 			return transactImpl(fn);
 		},
 		readBaseTree() {
-			const row = readBaseTreeStmt.get(sessionId);
-			if (row === null) throw new Error(`Virtual workdir session not found: ${sessionId}`);
+			const row = readBaseTreeStmt.get(workdirKey);
+			if (row === null) throw new Error(`Virtual workdir not found: ${workdirKey}`);
 			return readBaseTreeValue(row.base_tree);
 		},
 		writeBaseTree(baseTree) {
-			upsertSessionStmt.run(sessionId, baseTree);
+			upsertWorkdirStmt.run(workdirKey, baseTree);
 		},
 		getNode(id) {
-			const row = getNodeStmt.get(sessionId, id);
+			const row = getNodeStmt.get(workdirKey, id);
 			if (row === null) return null;
 			return readNode(row);
 		},
 		setNode(node) {
-			writeNode(setNodeStmt, sessionId, node);
+			writeNode(setNodeStmt, workdirKey, node);
 		},
 		deleteNode(id) {
-			deleteNodeStmt.run(sessionId, id);
+			deleteNodeStmt.run(workdirKey, id);
 		},
 		listChangeRecords() {
-			return listChangesStmt.all(sessionId).map(readChangeRecord);
+			return listChangesStmt.all(workdirKey).map(readChangeRecord);
 		},
 		getChangeRecord(path) {
-			const row = getChangeStmt.get(sessionId, path);
+			const row = getChangeStmt.get(workdirKey, path);
 			return row === null ? null : readChangeRecord(row);
 		},
 		setChangeRecord(record) {
-			upsertChangeStmt.run(sessionId, record.path, record.previous?.kind ?? null, record.previous?.mode ?? null, record.previous?.hash ?? null, record.current?.kind ?? null, record.current?.mode ?? null, record.current?.hash ?? null, record.source?.kind ?? null, record.source?.path ?? null);
+			upsertChangeStmt.run(workdirKey, record.path, record.previous?.kind ?? null, record.previous?.mode ?? null, record.previous?.hash ?? null, record.current?.kind ?? null, record.current?.mode ?? null, record.current?.hash ?? null, record.source?.kind ?? null, record.source?.path ?? null);
 		},
 		deleteChangeRecord(path) {
-			deleteChangeStmt.run(sessionId, path);
+			deleteChangeStmt.run(workdirKey, path);
 		},
 		listDirtyDirSummaries() {
-			return listDirtyDirsStmt.all(sessionId).map(readDirtyDirSummary);
+			return listDirtyDirsStmt.all(workdirKey).map(readDirtyDirSummary);
 		},
 		getDirtyDirSummary(path) {
-			const row = getDirtyDirStmt.get(sessionId, path);
+			const row = getDirtyDirStmt.get(workdirKey, path);
 			return row === null ? null : readDirtyDirSummary(row);
 		},
 		setDirtyDirSummary(summary) {
-			upsertDirtyDirStmt.run(sessionId, summary.path, summary.isDirty ? 1 : 0, summary.dirtyEntryCount, summary.dirtyDescendantCount, JSON.stringify(summary.affectedNames), summary.currentTreeHash, summary.hashState);
+			upsertDirtyDirStmt.run(workdirKey, summary.path, summary.isDirty ? 1 : 0, summary.dirtyEntryCount, summary.dirtyDescendantCount, JSON.stringify(summary.affectedNames), summary.currentTreeHash, summary.hashState);
 		},
 		deleteDirtyDirSummary(path) {
-			deleteDirtyDirStmt.run(sessionId, path);
+			deleteDirtyDirStmt.run(workdirKey, path);
 		},
 		reset(baseTree) {
 			resetTx(baseTree);
@@ -204,14 +199,14 @@ function ensureSchema(db) {
 	const currentVersion = readSchemaVersion(db);
 	if (currentVersion !== 0 && currentVersion !== WORKDIR_SQLITE_SCHEMA_VERSION) throw new Error(`Unsupported virtual workdir SQLite schema version: expected ${WORKDIR_SQLITE_SCHEMA_VERSION}, got ${currentVersion}`);
 	db.run(`
-    CREATE TABLE IF NOT EXISTS workdir_sessions (
-      session_id TEXT PRIMARY KEY,
+    CREATE TABLE IF NOT EXISTS workdirs (
+      workdir_key TEXT PRIMARY KEY,
       base_tree TEXT NOT NULL
     )
   `);
 	db.run(`
     CREATE TABLE IF NOT EXISTS workdir_nodes (
-      session_id TEXT NOT NULL,
+      workdir_key TEXT NOT NULL,
       node_id TEXT NOT NULL,
       origin_kind TEXT NOT NULL,
       origin_hash TEXT,
@@ -221,12 +216,12 @@ function ensureSchema(db) {
       content BLOB,
       target BLOB,
       directory_overlay TEXT,
-      PRIMARY KEY (session_id, node_id)
+      PRIMARY KEY (workdir_key, node_id)
     )
   `);
 	db.run(`
     CREATE TABLE IF NOT EXISTS workdir_changes (
-      session_id TEXT NOT NULL,
+      workdir_key TEXT NOT NULL,
       path TEXT NOT NULL,
       previous_kind TEXT,
       previous_mode TEXT,
@@ -236,12 +231,12 @@ function ensureSchema(db) {
       current_hash TEXT,
       source_kind TEXT,
       source_path TEXT,
-      PRIMARY KEY (session_id, path)
+      PRIMARY KEY (workdir_key, path)
     )
   `);
 	db.run(`
     CREATE TABLE IF NOT EXISTS workdir_dirty_dirs (
-      session_id TEXT NOT NULL,
+      workdir_key TEXT NOT NULL,
       path TEXT NOT NULL,
       is_dirty INTEGER NOT NULL,
       dirty_entry_count INTEGER NOT NULL,
@@ -249,20 +244,20 @@ function ensureSchema(db) {
       affected_names TEXT NOT NULL,
       current_tree_hash TEXT,
       hash_state TEXT NOT NULL,
-      PRIMARY KEY (session_id, path)
+      PRIMARY KEY (workdir_key, path)
     )
   `);
 	writeSchemaVersion(db, WORKDIR_SQLITE_SCHEMA_VERSION);
 }
-function hasSession(db, sessionId) {
-	return db.query("SELECT 1 FROM workdir_sessions WHERE session_id = ?").get(sessionId) !== null;
+function hasWorkdir(db, workdirKey) {
+	return db.query("SELECT 1 FROM workdirs WHERE workdir_key = ?").get(workdirKey) !== null;
 }
-function deleteSessionRows(db, sessionId) {
+function deleteWorkdirRows(db, workdirKey) {
 	db.transaction(() => {
-		db.query("DELETE FROM workdir_dirty_dirs WHERE session_id = ?").run(sessionId);
-		db.query("DELETE FROM workdir_changes WHERE session_id = ?").run(sessionId);
-		db.query("DELETE FROM workdir_nodes WHERE session_id = ?").run(sessionId);
-		db.query("DELETE FROM workdir_sessions WHERE session_id = ?").run(sessionId);
+		db.query("DELETE FROM workdir_dirty_dirs WHERE workdir_key = ?").run(workdirKey);
+		db.query("DELETE FROM workdir_changes WHERE workdir_key = ?").run(workdirKey);
+		db.query("DELETE FROM workdir_nodes WHERE workdir_key = ?").run(workdirKey);
+		db.query("DELETE FROM workdirs WHERE workdir_key = ?").run(workdirKey);
 	})();
 }
 function readSchemaVersion(db) {
@@ -271,33 +266,33 @@ function readSchemaVersion(db) {
 function writeSchemaVersion(db, version) {
 	db.run(`PRAGMA user_version = ${version}`);
 }
-function validateSessionIntegrity(db, sessionId) {
-	const sessionRow = db.query("SELECT base_tree FROM workdir_sessions WHERE session_id = ?").get(sessionId);
-	if (sessionRow === null) throw new Error(`Virtual workdir session not found: ${sessionId}`);
-	readBaseTreeValue(sessionRow.base_tree);
+function validateWorkdirIntegrity(db, workdirKey) {
+	const workdirRow = db.query("SELECT base_tree FROM workdirs WHERE workdir_key = ?").get(workdirKey);
+	if (workdirRow === null) throw new Error(`Virtual workdir not found: ${workdirKey}`);
+	readBaseTreeValue(workdirRow.base_tree);
 	const rootRow = db.query(`SELECT node_id, origin_kind, origin_hash, origin_mode, state_kind, state_mode, content, target, directory_overlay
      FROM workdir_nodes
-     WHERE session_id = ? AND node_id = ?`).get(sessionId, "root");
-	if (rootRow === null) throw new Error(`Virtual workdir session is corrupted: missing root node for ${sessionId}`);
-	if (readNode(rootRow).state.kind !== "directory") throw new Error(`Virtual workdir session is corrupted: root node is not a directory for ${sessionId}`);
+     WHERE workdir_key = ? AND node_id = ?`).get(workdirKey, "root");
+	if (rootRow === null) throw new Error(`Virtual workdir is corrupted: missing root node for ${workdirKey}`);
+	if (readNode(rootRow).state.kind !== "directory") throw new Error(`Virtual workdir is corrupted: root node is not a directory for ${workdirKey}`);
 	const allNodesStmt = db.query(`SELECT node_id, origin_kind, origin_hash, origin_mode, state_kind, state_mode, content, target, directory_overlay
      FROM workdir_nodes
-     WHERE session_id = ?`);
-	for (const row of allNodesStmt.all(sessionId)) readNode(row);
+     WHERE workdir_key = ?`);
+	for (const row of allNodesStmt.all(workdirKey)) readNode(row);
 }
-function writeNode(stmt, sessionId, node) {
+function writeNode(stmt, workdirKey, node) {
 	if (node.state.kind === "directory") {
-		stmt.run(sessionId, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "directory", null, null, null, JSON.stringify({
+		stmt.run(workdirKey, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "directory", null, null, null, JSON.stringify({
 			addedEntries: Array.from(node.state.overlay.addedEntries.entries()),
 			deletedNames: Array.from(node.state.overlay.deletedNames.values())
 		}));
 		return;
 	}
 	if (node.state.kind === "file") {
-		stmt.run(sessionId, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "file", node.state.mode, node.state.content ?? null, null, null);
+		stmt.run(workdirKey, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "file", node.state.mode, node.state.content ?? null, null, null);
 		return;
 	}
-	stmt.run(sessionId, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "symlink", "120000", null, node.state.target ?? null, null);
+	stmt.run(workdirKey, node.id, node.origin.kind, node.origin.kind === "none" ? null : node.origin.hash, node.origin.kind === "repo-blob" ? node.origin.mode : null, "symlink", "120000", null, node.state.target ?? null, null);
 }
 function readNode(row) {
 	const origin = readNodeOrigin(row);
@@ -445,11 +440,11 @@ function readBlobColumn(raw, column) {
 	return Buffer.from(raw);
 }
 function readBaseTreeValue(raw) {
-	if (typeof raw !== "string") throw new Error("Invalid SQLite workdir session base_tree");
+	if (typeof raw !== "string") throw new Error("Invalid SQLite workdir base_tree");
 	try {
 		return sha1(raw);
 	} catch {
-		throw new Error("Invalid SQLite workdir session base_tree");
+		throw new Error("Invalid SQLite workdir base_tree");
 	}
 }
 function isDirectoryOverlayPayload(value) {
@@ -461,4 +456,4 @@ function isDirectoryOverlayPayload(value) {
 	return hasValidAddedEntries && hasValidDeletedNames;
 }
 //#endregion
-export { createSqliteVirtualWorkdirBackend };
+export { deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir };

package/dist/workdir/sqlite.d.mts

@@ -1,2 +1,2 @@
-import { CreateSqliteVirtualWorkdirBackendOptions, SqliteVirtualWorkdirBackend, createSqliteVirtualWorkdirBackend } from "./sqlite-backend.mjs";
-export { type CreateSqliteVirtualWorkdirBackendOptions, type SqliteVirtualWorkdirBackend, createSqliteVirtualWorkdirBackend };
+import { OpenSqliteVirtualWorkdirOptions, SqliteVirtualWorkdir, deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir } from "./sqlite-backend.mjs";
+export { type OpenSqliteVirtualWorkdirOptions, type SqliteVirtualWorkdir, deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir };

package/dist/workdir/sqlite.mjs

@@ -1,2 +1,2 @@
-import { createSqliteVirtualWorkdirBackend } from "./sqlite-backend.mjs";
-export { createSqliteVirtualWorkdirBackend };
+import { deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir } from "./sqlite-backend.mjs";
+export { deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir };

package/dist/workdir/state-store.d.mts

@@ -2,7 +2,7 @@ import { SHA1 } from "../core/types.mjs";
 import { NodeId } from "./ids.mjs";
 import { NormalizedChangeRecord } from "./change-index.mjs";
 import { DirtyDirSummary } from "./dirty-dir.mjs";
-import { SessionNode } from "./nodes.mjs";
+import { WorkdirNode } from "./nodes.mjs";
 
 //#region src/workdir/state-store.d.ts
 /**
@@ -14,7 +14,7 @@ interface VirtualWorkdirStateStore {
   /**
    * 在单次提交边界内执行状态变更
    *
-   * 用于把一次 session 写操作封装为单个内部事务。
+   * 用于把一次 workdir 写操作封装为单个内部事务。
    * 若回调抛错，store 应尽力恢复到调用前状态。
    */
   transact<T>(fn: () => T): T;
@@ -23,9 +23,9 @@ interface VirtualWorkdirStateStore {
   /** 覆盖当前基线 tree */
   writeBaseTree(baseTree: SHA1): void;
   /** 读取节点，不存在时返回 null */
-  getNode(id: NodeId): SessionNode | null;
+  getNode(id: NodeId): WorkdirNode | null;
   /** 写入或覆盖节点 */
-  setNode(node: SessionNode): void;
+  setNode(node: WorkdirNode): void;
   /** 删除节点 */
   deleteNode(id: NodeId): void;
   /** 列出全部规范化变更记录 */

package/dist/workdir/{session-internal.mjs → workdir-path.mjs}

@@ -1,13 +1,13 @@
 import { VirtualNotDirectoryError, VirtualNotFileError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError } from "../core/errors.mjs";
 import { VIRTUAL_ROOT_NODE_ID, originBackedNodeId } from "./ids.mjs";
-import { mergeDirectoryChildren } from "./overlay.mjs";
 import { readRepoTree, treeEntryToNodeOrigin } from "./origin.mjs";
+import { mergeDirectoryChildren } from "./overlay.mjs";
 import { assertValidVirtualPath, baseName, joinPath, parentPath, splitPathSegments } from "./path.mjs";
-//#region src/workdir/session-internal.ts
+//#region src/workdir/workdir-path.ts
 /**
-* Virtual Workdir session 内部共享逻辑
+* Virtual Workdir 路径解析与共享读视图
 *
-* 供 session.ts 与 write-tree.ts 复用：
+* 供 workdir.ts 与 write-tree.ts 复用：
 * - 路径解析（resolvePath / resolveWriteTarget*）
 * - 目录子项展开（listDirectoryChildren / getDirectoryChildrenView）
 * - origin 节点懒注册（ensureNodeFromTreeEntry）
@@ -28,7 +28,7 @@ function joinChildPath(dirPath, name) {
 }
 function getRootNode(state) {
 	const root = state.getNode(VIRTUAL_ROOT_NODE_ID);
-	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 root;
 }
 /**
@@ -265,14 +265,14 @@ function resolvePathByParentLookup(source, state, path) {
 	};
 }
 /**
-* 确保 origin 条目对应的 session 节点已懒注册
+* 确保 origin 条目对应的 workdir 节点已懒注册
 */
 function ensureNodeFromTreeEntry(state, entry) {
 	const id = originBackedNodeId(entry.hash);
 	if (state.getNode(id) === null) {
 		const origin = treeEntryToNodeOrigin(entry);
 		let nodeState;
-		if (entry.mode === "40000") nodeState = {
+		if (entry.mode === "040000") nodeState = {
 			kind: "directory",
 			overlay: {
 				addedEntries: /* @__PURE__ */ new Map(),
@@ -321,12 +321,12 @@ function buildAddedModes(state, dirNode) {
 	for (const name of dirNode.state.overlay.addedEntries.keys()) {
 		const nodeId = dirNode.state.overlay.addedEntries.get(name);
 		const node = state.getNode(nodeId);
-		if (node !== null) addedModes.set(name, sessionNodeMode(node));
+		if (node !== null) addedModes.set(name, workdirNodeMode(node));
 	}
 	return addedModes;
 }
-function sessionNodeMode(node) {
-	if (node.state.kind === "directory") return "40000";
+function workdirNodeMode(node) {
+	if (node.state.kind === "directory") return "040000";
 	if (node.state.kind === "symlink") return "120000";
 	return node.state.mode;
 }

package/dist/workdir/{session-transaction.mjs → workdir-transaction.mjs}

@@ -1,14 +1,14 @@
 import { createNodeId } from "./ids.mjs";
-import { overlayBindEntry } from "./overlay.mjs";
-import { cloneSessionNodeForCopy } from "./nodes.mjs";
 import { readRepoBlobContent } from "./origin.mjs";
-import { listDirectoryChildren } from "./session-internal.mjs";
+import { overlayBindEntry } from "./overlay.mjs";
+import { listDirectoryChildren } from "./workdir-path.mjs";
 import { observeListedDirectoryChild } from "./directory-view.mjs";
-//#region src/workdir/session-transaction.ts
+import { cloneWorkdirNodeForCopy } from "./nodes.mjs";
+//#region src/workdir/workdir-transaction.ts
 /**
-* Virtual Workdir 事务包装与会话辅助函数
+* Virtual Workdir 写事务与节点辅助函数
 *
-* 从 session.ts 提取，降低编排层的复杂度：
+* 从 workdir.ts 提取，降低编排层复杂度：
 * - 写操作事务生命周期管理
 * - 父目录 overlay 更新
 * - 节点状态统计（stat）
@@ -17,7 +17,7 @@ import { observeListedDirectoryChild } from "./directory-view.mjs";
 /**
 * 在 state store 事务边界内执行写操作。
 *
-* @param state - session 内部状态存储
+* @param state - workdir 内部状态存储
 * @param onBeforeCommit - 提交前回调（在事务 callback 内执行）；可为 null
 * @param onCommitted - 提交后回调（在事务 callback 外执行）
 * @param fn - 实际写入逻辑
@@ -46,7 +46,7 @@ function updateParentOverlay(state, parentId, newOverlay) {
 	});
 }
 /**
-* 获取节点统计信息（用于 session.stat() 实现）
+* 获取节点统计信息（用于 workdir.stat() 实现）
 */
 function statNode(source, node, path) {
 	if (node.state.kind === "directory") return statDirectoryNode(node);
@@ -79,7 +79,7 @@ function statNode(source, node, path) {
 function statDirectoryNode(node) {
 	return {
 		kind: "tree",
-		mode: "40000",
+		mode: "040000",
 		size: 0,
 		hash: node.origin.kind === "repo-tree" ? node.origin.hash : null
 	};
@@ -91,7 +91,7 @@ function statDirectoryNode(node) {
 */
 function cloneNodeGraphForCopy(source, state, node, path) {
 	const newNodeId = createNodeId();
-	const cloned = cloneSessionNodeForCopy(node, newNodeId);
+	const cloned = cloneWorkdirNodeForCopy(node, newNodeId);
 	state.setNode(cloned);
 	if (node.state.kind !== "directory" || cloned.state.kind !== "directory") return newNodeId;
 	let overlay = cloned.state.overlay;

package/dist/workdir/workdir.d.mts

@@ -0,0 +1,30 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
+import { VirtualWorkdirStateStore } from "./state-store.mjs";
+
+//#region src/workdir/workdir.d.ts
+/**
+ * 基于 ObjectDatabase 创建 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * const repo = createMemoryRepository();
+ * const tree = repo.createTree([]);
+ * const workdir = createVirtualWorkdir(repo.objects, { baseTree: tree });
+ * expect(workdir.readdir()).toEqual([]);
+ * ```
+ */
+declare function createVirtualWorkdir(source: ObjectDatabase, options: CreateVirtualWorkdirOptions): VirtualWorkdir;
+/**
+ * 基于已有状态存储打开 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * const store = createVirtualWorkdirMemoryStateStore(tree);
+ * const workdir = openVirtualWorkdir(repo.objects, store);
+ * expect(workdir.baseTree).toBe(tree);
+ * ```
+ */
+declare function openVirtualWorkdir(source: ObjectDatabase, state: VirtualWorkdirStateStore): VirtualWorkdir;
+//#endregion
+export { createVirtualWorkdir, openVirtualWorkdir };