nano-git 0.3.1 → 0.3.2

package/dist/workdir/memory.mjs

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

package/dist/workdir/nodes.d.mts

@@ -6,7 +6,7 @@ import { DirectoryOverlay } from "./overlay.mjs";
 /** Blob / 符号链接在 origin 与 state 中使用的 mode */
 type BlobObjectMode = "100644" | "100755" | "120000";
 /**
- * 节点来源（repo 对象或纯 session 新建）
+ * 节点来源（repo 对象或纯 workdir 新建）
  */
 type NodeOrigin = {
   readonly kind: "none";
@@ -21,7 +21,7 @@ type NodeOrigin = {
 /**
  * 目录节点当前状态
  *
- * `overlay` 表达 session 层增删改；子项 nodeId 通过 overlay 合成与懒加载解析。
+ * `overlay` 表达 workdir 层增删改；子项 nodeId 通过 overlay 合成与懒加载解析。
  */
 interface DirectoryNodeState {
   readonly kind: "directory";
@@ -44,14 +44,14 @@ interface SymlinkNodeState {
   readonly mode: "120000";
   readonly target?: Buffer;
 }
-type SessionNodeState = DirectoryNodeState | FileNodeState | SymlinkNodeState;
+type WorkdirNodeState = DirectoryNodeState | FileNodeState | SymlinkNodeState;
 /**
- * 完整的会话节点记录
+ * 完整的 workdir 节点记录
  */
-interface SessionNode {
+interface WorkdirNode {
   readonly id: NodeId;
   readonly origin: NodeOrigin;
-  readonly state: SessionNodeState;
+  readonly state: WorkdirNodeState;
 }
 //#endregion
-export { SessionNode };
+export { WorkdirNode };

package/dist/workdir/nodes.mjs

@@ -2,7 +2,7 @@ import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
 import { cloneDirectoryOverlay, createEmptyDirectoryOverlay } from "./overlay.mjs";
 //#region src/workdir/nodes.ts
 /**
-* Virtual Workdir 会话节点状态模型
+* Virtual Workdir 节点状态模型
 *
 * 节点身份（nodeId）与目录路径绑定分离；origin 描述 repo-backed 来源。
 */
@@ -63,7 +63,7 @@ function revertNodeState(node) {
 /**
 * 为 `copy` 创建新节点：共享 origin，目录为浅复制（子项绑定保留，但 nodeId 为新）
 */
-function cloneSessionNodeForCopy(source, newId) {
+function cloneWorkdirNodeForCopy(source, newId) {
 	const origin = source.origin;
 	if (source.state.kind === "directory") return {
 		id: newId,
@@ -103,4 +103,4 @@ function cloneSessionNodeForCopy(source, newId) {
 	};
 }
 //#endregion
-export { cloneSessionNodeForCopy, createRootDirectoryNode, revertNodeState };
+export { cloneWorkdirNodeForCopy, createRootDirectoryNode, revertNodeState };

package/dist/workdir/overlay.d.mts

@@ -2,12 +2,12 @@ import { NodeId } from "./ids.mjs";
 
 //#region src/workdir/overlay.d.ts
 /**
- * 目录 overlay 状态（挂在目录 SessionNode 上）
+ * 目录 overlay 状态（挂在目录 WorkdirNode 上）
  */
 interface DirectoryOverlay {
-  /** session 新增或覆盖：条目名 -> 绑定的 nodeId */
+  /** workdir 新增或覆盖：条目名 -> 绑定的 nodeId */
   readonly addedEntries: Map<string, NodeId>;
-  /** session 删除的 origin/先前条目名（tombstone） */
+  /** workdir 删除的 origin/先前条目名（tombstone） */
   readonly deletedNames: Set<string>;
 }
 //#endregion

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

@@ -1,30 +1,47 @@
-import { VirtualWorkdirBackend } from "./core.mjs";
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
 import { Database } from "bun:sqlite";
 
 //#region src/workdir/sqlite-backend.d.ts
-/** 创建 SQLite Virtual Workdir backend 的可选参数 */
-interface CreateSqliteVirtualWorkdirBackendOptions {
+/** SQLite 连接层的可选参数 */
+interface SqliteVirtualWorkdirConnectionOptions {
   /** 开启 WAL 模式，默认 true */
   readonly walMode?: boolean;
 }
+/** 打开 SQLite VirtualWorkdir 的可选参数 */
+interface OpenSqliteVirtualWorkdirOptions extends CreateVirtualWorkdirOptions, SqliteVirtualWorkdirConnectionOptions {
+  /** 不存在时按 baseTree 初始化 */
+  readonly create?: boolean;
+}
 /**
- * SQLite Virtual Workdir backend（含资源释放能力）
+ * 基于 SQLite 的 VirtualWorkdir
+ *
+ * 返回值附带 `[Symbol.dispose]()`，用于释放内部数据库连接。
  */
-interface SqliteVirtualWorkdirBackend extends VirtualWorkdirBackend {
-  /** 释放 SQLite 数据库连接 */
+type SqliteVirtualWorkdir = VirtualWorkdir & {
   [Symbol.dispose](): void;
-}
+};
+/**
+ * 打开基于 SQLite 的持久化 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * using workdir = openSqliteVirtualWorkdir(repo.objects, ":memory:", "demo", {
+ *   baseTree: tree,
+ *   create: true,
+ * });
+ * expect(workdir.baseTree).toBe(tree);
+ * ```
+ */
+declare function openSqliteVirtualWorkdir(source: ObjectDatabase, dbPath: string, workdirKey: string, options: OpenSqliteVirtualWorkdirOptions): SqliteVirtualWorkdir;
 /**
- * 创建基于 SQLite 的 Virtual Workdir backend
+ * 删除指定 key 上的 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);
+ * deleteSqliteVirtualWorkdir("/tmp/workdir.sqlite", "demo");
  * ```
  */
-declare function createSqliteVirtualWorkdirBackend(dbPath: string, options?: CreateSqliteVirtualWorkdirBackendOptions): SqliteVirtualWorkdirBackend;
+declare function deleteSqliteVirtualWorkdir(dbPath: string, workdirKey: string, options?: SqliteVirtualWorkdirConnectionOptions): void;
 //#endregion
-export { CreateSqliteVirtualWorkdirBackendOptions, SqliteVirtualWorkdirBackend, createSqliteVirtualWorkdirBackend };
+export { OpenSqliteVirtualWorkdirOptions, SqliteVirtualWorkdir, deleteSqliteVirtualWorkdir, openSqliteVirtualWorkdir };

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;
   /** 列出全部规范化变更记录 */