nano-git 0.3.0 → 0.3.2

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,91 +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 = 1;
-const WORKDIR_CHANGES_SESSION_ORDER_INDEX = "workdir_changes_session_id_id_idx";
+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,
@@ -94,16 +88,57 @@ 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 listChangesStmt = db.query("SELECT op, path, old_path FROM workdir_changes WHERE session_id = ? ORDER BY id");
-	const insertChangeStmt = db.query("INSERT INTO workdir_changes (session_id, op, path, old_path) VALUES (?, ?, ?, ?)");
-	const clearNodesStmt = db.query("DELETE FROM workdir_nodes WHERE session_id = ?");
-	const clearChangesStmt = db.query("DELETE FROM workdir_changes 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 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 workdir_key = ? AND path = ?`);
+	const upsertChangeStmt = db.query(`INSERT INTO workdir_changes (
+      workdir_key, path, previous_kind, previous_mode, previous_hash,
+      current_kind, current_mode, current_hash, source_kind, source_path
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(workdir_key, path) DO UPDATE SET
+      previous_kind = excluded.previous_kind,
+      previous_mode = excluded.previous_mode,
+      previous_hash = excluded.previous_hash,
+      current_kind = excluded.current_kind,
+      current_mode = excluded.current_mode,
+      current_hash = excluded.current_hash,
+      source_kind = excluded.source_kind,
+      source_path = excluded.source_path`);
+	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 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 workdir_key = ? AND path = ?`);
+	const upsertDirtyDirStmt = db.query(`INSERT INTO workdir_dirty_dirs (
+      workdir_key, path, is_dirty, dirty_entry_count, dirty_descendant_count,
+      affected_names, current_tree_hash, hash_state
+    )
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     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 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);
-		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",
@@ -111,32 +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);
-		},
-		appendChange(record) {
-			insertChangeStmt.run(sessionId, record.op, getRecordPath(record), getRecordOldPath(record));
+			deleteNodeStmt.run(workdirKey, id);
 		},
 		listChangeRecords() {
-			return listChangesStmt.all(sessionId).map(readChangeRecord);
+			return listChangesStmt.all(workdirKey).map(readChangeRecord);
+		},
+		getChangeRecord(path) {
+			const row = getChangeStmt.get(workdirKey, path);
+			return row === null ? null : readChangeRecord(row);
 		},
-		clearChanges() {
-			clearChangesStmt.run(sessionId);
+		setChangeRecord(record) {
+			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(workdirKey, path);
+		},
+		listDirtyDirSummaries() {
+			return listDirtyDirsStmt.all(workdirKey).map(readDirtyDirSummary);
+		},
+		getDirtyDirSummary(path) {
+			const row = getDirtyDirStmt.get(workdirKey, path);
+			return row === null ? null : readDirtyDirSummary(row);
+		},
+		setDirtyDirSummary(summary) {
+			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(workdirKey, path);
 		},
 		reset(baseTree) {
 			resetTx(baseTree);
@@ -147,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,
@@ -164,32 +216,48 @@ 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 (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id TEXT NOT NULL,
-      op TEXT NOT NULL,
-      path TEXT,
-      old_path TEXT
+      workdir_key TEXT NOT NULL,
+      path TEXT NOT NULL,
+      previous_kind TEXT,
+      previous_mode TEXT,
+      previous_hash TEXT,
+      current_kind TEXT,
+      current_mode TEXT,
+      current_hash TEXT,
+      source_kind TEXT,
+      source_path TEXT,
+      PRIMARY KEY (workdir_key, path)
     )
   `);
 	db.run(`
-    CREATE INDEX IF NOT EXISTS ${WORKDIR_CHANGES_SESSION_ORDER_INDEX}
-    ON workdir_changes (session_id, id)
+    CREATE TABLE IF NOT EXISTS workdir_dirty_dirs (
+      workdir_key TEXT NOT NULL,
+      path TEXT NOT NULL,
+      is_dirty INTEGER NOT NULL,
+      dirty_entry_count INTEGER NOT NULL,
+      dirty_descendant_count INTEGER NOT NULL,
+      affected_names TEXT NOT NULL,
+      current_tree_hash TEXT,
+      hash_state TEXT NOT NULL,
+      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_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) {
@@ -198,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);
@@ -286,6 +354,67 @@ function readNodeOrigin(row) {
 	}
 	throw new Error(`Invalid SQLite workdir node origin kind: ${row.origin_kind}`);
 }
+function readChangeRecord(row) {
+	return {
+		path: row.path,
+		previous: row.previous_kind === null || row.previous_mode === null || row.previous_hash === null ? null : {
+			kind: readDiffObjectKind(row.previous_kind),
+			mode: readDiffObjectMode(row.previous_mode),
+			hash: row.previous_hash
+		},
+		current: row.current_kind === null || row.current_mode === null || row.current_hash === null ? null : {
+			kind: readDiffObjectKind(row.current_kind),
+			mode: readDiffObjectMode(row.current_mode),
+			hash: row.current_hash
+		},
+		source: row.source_kind === null || row.source_path === null ? null : {
+			kind: readDiffSourceKind(row.source_kind),
+			path: row.source_path
+		}
+	};
+}
+function readDiffObjectKind(raw) {
+	if (raw === "blob" || raw === "symlink") return raw;
+	throw new Error(`Invalid SQLite workdir diff object kind: ${raw}`);
+}
+function readDiffObjectMode(raw) {
+	if (raw === "100644" || raw === "100755" || raw === "120000") return raw;
+	throw new Error(`Invalid SQLite workdir diff object mode: ${raw}`);
+}
+function readDiffSourceKind(raw) {
+	if (raw === "rename" || raw === "copy") return raw;
+	throw new Error(`Invalid SQLite workdir diff source kind: ${raw}`);
+}
+function readDirtyDirSummary(row) {
+	const affectedNames = readDirtyDirAffectedNames(row.affected_names);
+	return {
+		path: row.path,
+		isDirty: row.is_dirty !== 0,
+		dirtyEntryCount: readDirtyDirCount(row.dirty_entry_count, "dirty_entry_count"),
+		dirtyDescendantCount: readDirtyDirCount(row.dirty_descendant_count, "dirty_descendant_count"),
+		affectedNames,
+		currentTreeHash: row.current_tree_hash === null ? null : sha1(row.current_tree_hash),
+		hashState: readDirtyDirHashState(row.hash_state)
+	};
+}
+function readDirtyDirCount(raw, field) {
+	if (!Number.isInteger(raw) || raw < 0) throw new Error(`Invalid SQLite workdir dirty dir ${field}: ${raw}`);
+	return raw;
+}
+function readDirtyDirAffectedNames(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("Invalid SQLite workdir dirty dir affected_names JSON");
+	}
+	if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) throw new Error("Invalid SQLite workdir dirty dir affected_names payload");
+	return [...parsed].sort((left, right) => left.localeCompare(right));
+}
+function readDirtyDirHashState(raw) {
+	if (raw === "stale" || raw === "materialized") return raw;
+	throw new Error(`Invalid SQLite workdir dirty dir hash state: ${raw}`);
+}
 function readDirectoryOverlay(raw) {
 	if (raw === null) return {
 		addedEntries: /* @__PURE__ */ new Map(),
@@ -311,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) {
@@ -326,38 +455,5 @@ function isDirectoryOverlayPayload(value) {
 	const hasValidDeletedNames = maybe.deletedNames.every((name) => typeof name === "string");
 	return hasValidAddedEntries && hasValidDeletedNames;
 }
-function getRecordPath(record) {
-	switch (record.op) {
-		case "add":
-		case "modify":
-		case "delete":
-		case "revert": return record.path;
-		case "rename":
-		case "copy": return record.to;
-		default: return record;
-	}
-}
-function getRecordOldPath(record) {
-	if (record.op === "rename" || record.op === "copy") return record.from;
-	return null;
-}
-function readChangeRecord(row) {
-	switch (row.op) {
-		case "add":
-		case "modify":
-		case "delete":
-		case "revert": return {
-			op: row.op,
-			path: row.path
-		};
-		case "rename":
-		case "copy": return {
-			op: row.op,
-			from: row.old_path,
-			to: row.path
-		};
-		default: throw new Error(`Unknown workdir change op: ${row.op}`);
-	}
-}
 //#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

@@ -1,7 +1,8 @@
 import { SHA1 } from "../core/types.mjs";
-import { InternalChangeRecord } from "./change-log.mjs";
 import { NodeId } from "./ids.mjs";
-import { SessionNode } from "./nodes.mjs";
+import { NormalizedChangeRecord } from "./change-index.mjs";
+import { DirtyDirSummary } from "./dirty-dir.mjs";
+import { WorkdirNode } from "./nodes.mjs";
 
 //#region src/workdir/state-store.d.ts
 /**
@@ -13,7 +14,7 @@ interface VirtualWorkdirStateStore {
   /**
    * 在单次提交边界内执行状态变更
    *
-   * 用于把一次 session 写操作封装为单个内部事务。
+   * 用于把一次 workdir 写操作封装为单个内部事务。
    * 若回调抛错，store 应尽力恢复到调用前状态。
    */
   transact<T>(fn: () => T): T;
@@ -22,21 +23,31 @@ 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;
-  /** 追加内部变更记录 */
-  appendChange(record: InternalChangeRecord): void;
-  /** 列出内部变更记录快照 */
-  listChangeRecords(): readonly InternalChangeRecord[];
-  /** 清空变更记录 */
-  clearChanges(): void;
+  /** 列出全部规范化变更记录 */
+  listChangeRecords(): readonly NormalizedChangeRecord[];
+  /** 按路径读取规范化变更记录 */
+  getChangeRecord(path: string): NormalizedChangeRecord | null;
+  /** 写入或覆盖规范化变更记录 */
+  setChangeRecord(record: NormalizedChangeRecord): void;
+  /** 删除规范化变更记录 */
+  deleteChangeRecord(path: string): void;
+  /** 列出全部脏目录摘要 */
+  listDirtyDirSummaries(): readonly DirtyDirSummary[];
+  /** 按目录路径读取脏目录摘要 */
+  getDirtyDirSummary(path: string): DirtyDirSummary | null;
+  /** 写入或覆盖脏目录摘要 */
+  setDirtyDirSummary(summary: DirtyDirSummary): void;
+  /** 删除脏目录摘要 */
+  deleteDirtyDirSummary(path: string): void;
   /**
    * 重置为新的基线 tree
    *
-   * 需要同时清空节点状态与变更记录，并重新建立根节点。
+   * 需要同时清空节点状态，并重新建立根节点。
    */
   reset(baseTree: SHA1): void;
 }