@davideasden/pi-undo 0.2.0 → 0.2.2

package/src/controller.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
 
 import { canonicalJson, checksum } from "./encoding.ts";
 import type {
@@ -35,7 +36,7 @@ export interface ControllerDependencies {
 	}>;
 	readonly appendControl: (customType: string, data?: unknown) => Promise<string | null>;
 	readonly appendCursor: (cursor: CursorState) => Promise<CursorAppendResult>;
-	readonly capture: () => Promise<SnapshotManifest>;
+	readonly capture: (scopePaths?: readonly string[]) => Promise<SnapshotManifest>;
 	readonly changedPaths: (before: SnapshotManifest, after: SnapshotManifest) => Promise<readonly string[]>;
 	readonly loadManifest: (id: ManifestId) => Promise<SnapshotManifest>;
 	readonly planRestore: (
@@ -73,11 +74,17 @@ export type CursorAppendResult =
 	| { readonly kind: "volatile"; readonly reason: string }
 	| { readonly kind: "recovery_required"; readonly reason: string };
 
+export interface OperationTiming {
+	readonly phase: string;
+	readonly durationMs: number;
+}
+
 export interface OperationResult {
 	readonly code: ResultCode;
 	readonly changedFiles: number;
 	readonly message?: string;
 	readonly refillPrompt?: string;
+	readonly timings?: readonly OperationTiming[];
 }
 
 export type InputEventResult =
@@ -384,85 +391,188 @@ export class UndoControllerImpl implements UndoController {
 		targetManifestId?: ManifestId,
 	): Promise<OperationResult> {
 		if (this.locked || this.operationInFlight) return { code: "busy", changedFiles: 0 };
+		const profile = new OperationProfiler();
+		const done = (result: OperationResult): OperationResult => profile.attach(result);
 		this.operationInFlight = true;
 		this.promptDeferralInFlight = true;
 		this.lastSafetyManifestId = null;
 		let lease: { release(): Promise<void> } | undefined;
 		try {
-			if (!await this.ensureIdle()) return { code: "idle_timeout", changedFiles: 0 };
+			if (!await profile.measure("idle", () => this.ensureIdle())) {
+				return done({ code: "idle_timeout", changedFiles: 0 });
+			}
 			try {
-				lease = await this.dependencies.acquireWorkspaceLock();
+				lease = await profile.measure("lock", () => this.dependencies.acquireWorkspaceLock());
 			} catch {
-				return { code: "busy", changedFiles: 0 };
+				return done({ code: "busy", changedFiles: 0 });
+			}
+			if (checkpoint.changedPaths.length === 0) {
+				return done(await this.runSessionOnlyOperation(action, checkpoint, targetManifestId, profile));
 			}
 			let rollback: SnapshotManifest;
 			try {
-				rollback = await this.dependencies.capture();
+				rollback = await profile.measure("capture", () =>
+					this.dependencies.capture(checkpoint.changedPaths));
 			} catch {
-				return { code: "capture_failed", changedFiles: 0 };
+				return done({ code: "capture_failed", changedFiles: 0 });
 			}
 			let target: SnapshotManifest;
 			let plan: RestorePlan;
 			let targetLogicalLeaf: string | null;
 			try {
-				target = await this.dependencies.loadManifest(
+				target = await profile.measure("load", () => this.dependencies.loadManifest(
 					targetManifestId ?? (action === "undo" ? checkpoint.beforeManifestId : checkpoint.afterManifestId),
-				);
-				plan = await this.dependencies.planRestore(rollback, target, checkpoint.changedPaths);
+				));
+				plan = await profile.measure("plan", () =>
+					this.dependencies.planRestore(rollback, target, checkpoint.changedPaths));
 				targetLogicalLeaf = this.dependencies.resolveSessionTarget(action, checkpoint);
 			} catch {
-				return { code: "restore_failed_safe", changedFiles: 0 };
+				return done({ code: "restore_failed_safe", changedFiles: 0 });
 			}
 			const descriptor = this.createDescriptor(action, rollback, target, plan, targetLogicalLeaf);
-			await this.dependencies.journal.prepare(descriptor, plan);
-			const navigation = await this.dependencies.navigateSession(action, checkpoint);
+			await profile.measure("journal", () => this.dependencies.journal.prepare(descriptor, plan));
+			const navigation = await profile.measure("navigate", () =>
+				this.dependencies.navigateSession(action, checkpoint));
 			if (navigation.cancelled) {
-				await this.dependencies.journal.setPhase(descriptor.opId, "ABORTING");
-				await this.dependencies.journal.setPhase(descriptor.opId, "ABORTED");
-				return { code: "restore_failed_safe", changedFiles: 0 };
+				await profile.measure("journal", async () => {
+					await this.dependencies.journal.setPhase(descriptor.opId, "ABORTING");
+					await this.dependencies.journal.setPhase(descriptor.opId, "ABORTED");
+				});
+				return done({ code: "restore_failed_safe", changedFiles: 0 });
 			}
 			if (navigation.logicalLeafId !== descriptor.toLogicalLeaf) {
 				this.locked = true;
-				await this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED");
-				return { code: "recovery_required", changedFiles: 0 };
+				await profile.measure("journal", () =>
+					this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED"));
+				return done({ code: "recovery_required", changedFiles: 0 });
 			}
-			await this.dependencies.journal.setPhase(descriptor.opId, "SESSION_MOVED", {
-				observedLogicalLeaf: navigation.logicalLeafId,
+			await profile.measure("journal", async () => {
+				await this.dependencies.journal.setPhase(descriptor.opId, "SESSION_MOVED", {
+					observedLogicalLeaf: navigation.logicalLeafId,
+				});
+				await this.dependencies.journal.setPhase(descriptor.opId, "APPLYING");
 			});
-			await this.dependencies.journal.setPhase(descriptor.opId, "APPLYING");
-			const applied = await this.dependencies.applyRestore(plan, target, { opId: descriptor.opId });
-			if (applied.code !== "ok") return this.compensate(descriptor, rollback, target, applied);
-			await this.dependencies.journal.setPhase(descriptor.opId, "FILES_VERIFIED");
+			const applied = await profile.measure("apply", () =>
+				this.dependencies.applyRestore(plan, target, { opId: descriptor.opId }));
+			if (applied.code !== "ok") {
+				return done(await profile.measure("compensate", () =>
+					this.compensate(descriptor, rollback, target, applied)));
+			}
+			await profile.measure("journal", () =>
+				this.dependencies.journal.setPhase(descriptor.opId, "FILES_VERIFIED"));
 			const cursor = this.createCursor(descriptor, action, checkpoint);
-			const cursorResult = await this.dependencies.appendCursor(cursor);
+			const cursorResult = await profile.measure("cursor", () => this.dependencies.appendCursor(cursor));
 			if (cursorResult.kind === "recovery_required") {
 				this.locked = true;
-				await this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {});
-				return { code: "recovery_required", changedFiles: applied.verifiedPaths };
+				await profile.measure("journal", () =>
+					this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {}));
+				return done({ code: "recovery_required", changedFiles: applied.verifiedPaths });
 			}
 			if (cursorResult.kind === "volatile") {
-				return this.compensate(descriptor, rollback, target, {
+				return done(await profile.measure("compensate", () => this.compensate(descriptor, rollback, target, {
 					code: "recovery_required",
 					verifiedPaths: applied.verifiedPaths,
 					totalPaths: applied.totalPaths,
-				});
+				})));
 			}
-			await this.dependencies.journal.setPhase(descriptor.opId, "CURSOR_COMMITTED");
-			await this.dependencies.journal.markCommitted(descriptor.opId);
+			await profile.measure("commit", async () => {
+				await this.dependencies.journal.setPhase(descriptor.opId, "CURSOR_COMMITTED");
+				await this.dependencies.journal.markCommitted(descriptor.opId);
+			});
 			this.lastSafetyManifestId = rollback.manifestId;
-			return { code: "ok", changedFiles: applied.verifiedPaths };
+			return done({ code: "ok", changedFiles: applied.verifiedPaths });
 		} catch {
 			this.locked = true;
-			return { code: "recovery_required", changedFiles: 0 };
+			return done({ code: "recovery_required", changedFiles: 0 });
 		} finally {
-			if (lease !== undefined) {
-				await lease.release().catch(() => { this.locked = true; });
+			const activeLease = lease;
+			if (activeLease !== undefined) {
+				await profile.measure("unlock", () =>
+					activeLease.release().catch(() => { this.locked = true; }));
 			}
 			this.promptDeferralInFlight = false;
 			this.operationInFlight = false;
 		}
 	}
 
+	private async runSessionOnlyOperation(
+		action: "undo" | "redo",
+		checkpoint: CheckpointRecord,
+		targetManifestId: ManifestId | undefined,
+		profile: OperationProfiler,
+	): Promise<OperationResult> {
+		const rollbackManifestId = action === "undo"
+			? checkpoint.afterManifestId
+			: checkpoint.beforeManifestId;
+		const targetId = targetManifestId ?? (
+			action === "undo" ? checkpoint.beforeManifestId : checkpoint.afterManifestId
+		);
+		const plan = emptyRestorePlan(rollbackManifestId, targetId);
+		const targetLogicalLeaf = this.dependencies.resolveSessionTarget(action, checkpoint);
+		const descriptor = this.createDescriptorFromManifestIds(
+			action,
+			rollbackManifestId,
+			targetId,
+			plan,
+			targetLogicalLeaf,
+		);
+		await profile.measure("journal", () => this.dependencies.journal.prepare(descriptor, plan));
+		const navigation = await profile.measure("navigate", () =>
+			this.dependencies.navigateSession(action, checkpoint));
+		if (navigation.cancelled) {
+			await profile.measure("journal", async () => {
+				await this.dependencies.journal.setPhase(descriptor.opId, "ABORTING");
+				await this.dependencies.journal.setPhase(descriptor.opId, "ABORTED");
+			});
+			return { code: "restore_failed_safe", changedFiles: 0 };
+		}
+		if (navigation.logicalLeafId !== descriptor.toLogicalLeaf) {
+			this.locked = true;
+			await profile.measure("journal", () =>
+				this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED"));
+			return { code: "recovery_required", changedFiles: 0 };
+		}
+		await profile.measure("journal", async () => {
+			await this.dependencies.journal.setPhase(descriptor.opId, "SESSION_MOVED", {
+				observedLogicalLeaf: navigation.logicalLeafId,
+			});
+			await this.dependencies.journal.setPhase(descriptor.opId, "APPLYING");
+			await this.dependencies.journal.setPhase(descriptor.opId, "FILES_VERIFIED");
+		});
+		const cursorResult = await profile.measure("cursor", () =>
+			this.dependencies.appendCursor(this.createCursor(descriptor, action, checkpoint)));
+		if (cursorResult.kind === "recovery_required") {
+			this.locked = true;
+			await profile.measure("journal", () =>
+				this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {}));
+			return { code: "recovery_required", changedFiles: 0 };
+		}
+		if (cursorResult.kind === "volatile") {
+			return profile.measure("compensate", () => this.compensateSessionOnly(descriptor));
+		}
+		await profile.measure("commit", async () => {
+			await this.dependencies.journal.setPhase(descriptor.opId, "CURSOR_COMMITTED");
+			await this.dependencies.journal.markCommitted(descriptor.opId);
+		});
+		this.lastSafetyManifestId = rollbackManifestId;
+		return { code: "ok", changedFiles: 0 };
+	}
+
+	private async compensateSessionOnly(descriptor: OperationDescriptor): Promise<OperationResult> {
+		try {
+			await this.dependencies.journal.setPhase(descriptor.opId, "ABORTING");
+			if (!await this.dependencies.restoreSessionLeaf(descriptor.fromLogicalLeaf)) {
+				throw new Error("session rollback failed");
+			}
+			await this.dependencies.journal.setPhase(descriptor.opId, "ABORTED");
+			return { code: "restore_failed_safe", changedFiles: 0 };
+		} catch {
+			this.locked = true;
+			await this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {});
+			return { code: "recovery_required", changedFiles: 0 };
+		}
+	}
+
 	private async ensureIdle(): Promise<boolean> {
 		if (this.dependencies.isAgentIdle()) return true;
 		try {
@@ -541,7 +651,23 @@ export class UndoControllerImpl implements UndoController {
 		plan: RestorePlan,
 		targetLogicalLeaf: string | null,
 	): OperationDescriptor {
-		const scopePaths = [...plan.deletePaths, ...plan.writePaths].sort();
+		return this.createDescriptorFromManifestIds(
+			action,
+			rollback.manifestId,
+			target.manifestId,
+			plan,
+			targetLogicalLeaf,
+		);
+	}
+
+	private createDescriptorFromManifestIds(
+		action: "undo" | "redo" | "tree",
+		rollbackManifestId: ManifestId,
+		targetManifestId: ManifestId,
+		plan: RestorePlan,
+		targetLogicalLeaf: string | null,
+	): OperationDescriptor {
+		const scopePaths = [...(plan.scopePaths ?? [...plan.deletePaths, ...plan.writePaths])].sort();
 		const payload = {
 			schemaVersion: 1 as const,
 			opId: `op-${randomUUID()}`,
@@ -550,8 +676,8 @@ export class UndoControllerImpl implements UndoController {
 			action,
 			fromLogicalLeaf: this.dependencies.getLogicalLeafId(),
 			toLogicalLeaf: targetLogicalLeaf,
-			targetManifestId: target.manifestId,
-			rollbackManifestId: rollback.manifestId,
+			targetManifestId,
+			rollbackManifestId,
 			coverage: `paths:${checksum(canonicalJson(scopePaths))}`,
 			scopePaths,
 			planDigest: plan.planDigest,
@@ -604,6 +730,43 @@ export class UndoControllerImpl implements UndoController {
 	}
 }
 
+function emptyRestorePlan(currentManifestId: ManifestId, targetManifestId: ManifestId): RestorePlan {
+	const payload = {
+		currentManifestId,
+		targetManifestId,
+		boundaryRoots: [],
+		deletePaths: [],
+		writePaths: [],
+		scopePaths: [],
+	};
+	return { ...payload, planDigest: checksum(canonicalJson(payload)) };
+}
+
+class OperationProfiler {
+	private readonly durations = new Map<string, number>();
+
+	async measure<T>(phase: string, operation: () => Promise<T>): Promise<T> {
+		const started = performance.now();
+		try {
+			return await operation();
+		} finally {
+			this.durations.set(phase, (this.durations.get(phase) ?? 0) + performance.now() - started);
+		}
+	}
+
+	attach(result: OperationResult): OperationResult {
+		const total = [...this.durations.values()].reduce((sum, duration) => sum + duration, 0);
+		if (total < 1_000) return result;
+		return {
+			...result,
+			timings: [...this.durations].map(([phase, durationMs]) => ({
+				phase,
+				durationMs: Math.round(durationMs),
+			})),
+		};
+	}
+}
+
 function noop(): OperationResult {
 	return { code: "noop", changedFiles: 0 };
 }

package/src/mutation-journal.ts

@@ -1,4 +1,4 @@
-import { open, readFile } from "node:fs/promises";
+import { open, readFile, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import { fsyncDirectory } from "./atomic-fs.ts";
@@ -14,6 +14,24 @@ export interface MutationIntent {
 	readonly targetFingerprint: string;
 }
 
+export interface MutationAdvance {
+	readonly ordinal: number;
+	readonly states: readonly MutationState[];
+}
+
+interface JournalRecords {
+	readonly latest: readonly MutationRecord[];
+	readonly tail: MutationRecord | undefined;
+	readonly durableEnd: number;
+	readonly hasNonDurableTail: boolean;
+	readonly fileExisted: boolean;
+}
+
+interface CachedJournalRecords {
+	readonly records: JournalRecords;
+	readonly fingerprint: string;
+}
+
 const stateOrder: readonly MutationState[] = [
 	"INTENT",
 	"SOURCE_QUARANTINED",
@@ -27,6 +45,7 @@ export class MutationJournal {
 	private readonly path: string;
 	private readonly opId: string;
 	private mutationQueue: Promise<void> = Promise.resolve();
+	private cachedRecords: CachedJournalRecords | undefined;
 
 	constructor(path: string, opId: string) {
 		this.path = path;
@@ -46,33 +65,53 @@ export class MutationJournal {
 	}
 
 	begin(intent: MutationIntent): Promise<MutationRecord> {
-		return this.enqueueMutation(() => this.beginMutation(intent));
+		return this.enqueueMutation(async () => (await this.beginManyMutation([intent]))[0]!);
+	}
+
+	beginMany(intents: readonly MutationIntent[]): Promise<readonly MutationRecord[]> {
+		return this.enqueueMutation(() => this.beginManyMutation(intents));
 	}
 
-	private async beginMutation(intent: MutationIntent): Promise<MutationRecord> {
+	private async beginManyMutation(intents: readonly MutationIntent[]): Promise<readonly MutationRecord[]> {
+		if (intents.length === 0) throw new Error("mutation 批量 intent 不能为空");
 		const current = await this.readRecords();
-		const content = {
-			schemaVersion: 1 as const,
-			opId: this.opId,
-			ordinal: current.latest.length + 1,
-			state: "INTENT" as const,
-			kind: intent.kind,
-			path: intent.path,
-			sourceArtifact: intent.sourceArtifact,
-			targetArtifact: intent.targetArtifact,
-			sourceFingerprint: intent.sourceFingerprint,
-			targetFingerprint: intent.targetFingerprint,
-			previousChecksum: current.tail?.checksum ?? null,
-		};
-		const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
-		await this.append(record, current.durableEnd, current.hasNonDurableTail);
-		return record;
+		let tail = current.tail;
+		const records: MutationRecord[] = [];
+		for (let index = 0; index < intents.length; index += 1) {
+			const intent = intents[index]!;
+			const content = {
+				schemaVersion: 1 as const,
+				opId: this.opId,
+				ordinal: current.latest.length + index + 1,
+				state: "INTENT" as const,
+				kind: intent.kind,
+				path: intent.path,
+				sourceArtifact: intent.sourceArtifact,
+				targetArtifact: intent.targetArtifact,
+				sourceFingerprint: intent.sourceFingerprint,
+				targetFingerprint: intent.targetFingerprint,
+				previousChecksum: tail?.checksum ?? null,
+			};
+			const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
+			records.push(record);
+			tail = record;
+		}
+		await this.append(records, current);
+		return records;
 	}
 
 	advance(ordinal: number, state: MutationState): Promise<MutationRecord> {
 		return this.enqueueMutation(() => this.advanceMutation(ordinal, state));
 	}
 
+	advanceMany(ordinal: number, states: readonly MutationState[]): Promise<readonly MutationRecord[]> {
+		return this.enqueueMutation(() => this.advanceManyMutation(ordinal, states));
+	}
+
+	advanceBatch(advances: readonly MutationAdvance[]): Promise<readonly MutationRecord[]> {
+		return this.enqueueMutation(() => this.advanceBatchMutation(advances));
+	}
+
 	markRollbackCleaned(ordinal: number): Promise<MutationRecord> {
 		return this.enqueueMutation(() => this.markRollbackCleanedMutation(ordinal));
 	}
@@ -87,16 +126,58 @@ export class MutationJournal {
 	}
 
 	private async advanceMutation(ordinal: number, state: MutationState): Promise<MutationRecord> {
+		const [record] = await this.advanceManyMutation(ordinal, [state]);
+		return record!;
+	}
+
+	private advanceManyMutation(
+		ordinal: number,
+		states: readonly MutationState[],
+	): Promise<readonly MutationRecord[]> {
+		return this.advanceBatchMutation([{ ordinal, states }]);
+	}
+
+	private async advanceBatchMutation(
+		advances: readonly MutationAdvance[],
+	): Promise<readonly MutationRecord[]> {
+		if (advances.length === 0 || advances.some((advance) => advance.states.length === 0)) {
+			throw new Error("mutation 批量状态不能为空");
+		}
 		const current = await this.readRecords();
-		const previous = current.latest[ordinal - 1];
-		if (previous === undefined || stateOrder.indexOf(state) !== stateOrder.indexOf(previous.state) + 1) {
-			throw new Error(`mutation state 必须严格推进：${previous?.state ?? "missing"} -> ${state}`);
+		const latest = [...current.latest];
+		let tail = current.tail;
+		const records: MutationRecord[] = [];
+		for (const advance of advances) {
+			for (const state of advance.states) {
+				const previous = latest[advance.ordinal - 1];
+				if (previous === undefined || stateOrder.indexOf(state) !== stateOrder.indexOf(previous.state) + 1) {
+					throw new Error(`mutation state 必须严格推进：${previous?.state ?? "missing"} -> ${state}`);
+				}
+				const content = {
+					schemaVersion: previous.schemaVersion,
+					opId: previous.opId,
+					ordinal: previous.ordinal,
+					state,
+					kind: previous.kind,
+					path: previous.path,
+					sourceArtifact: previous.sourceArtifact,
+					targetArtifact: previous.targetArtifact,
+					sourceFingerprint: previous.sourceFingerprint,
+					targetFingerprint: previous.targetFingerprint,
+					previousChecksum: tail?.checksum ?? null,
+				};
+				const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
+				records.push(record);
+				latest[advance.ordinal - 1] = record;
+				tail = record;
+			}
 		}
-		return this.appendState(current, previous, state);
+		await this.append(records, current);
+		return records;
 	}
 
 	private async appendState(
-		current: Awaited<ReturnType<MutationJournal["readRecords"]>>,
+		current: JournalRecords,
 		previous: MutationRecord,
 		state: MutationState,
 	): Promise<MutationRecord> {
@@ -114,7 +195,7 @@ export class MutationJournal {
 			previousChecksum: current.tail?.checksum ?? null,
 		};
 		const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
-		await this.append(record, current.durableEnd, current.hasNonDurableTail);
+		await this.append([record], current);
 		return record;
 	}
 
@@ -140,21 +221,26 @@ export class MutationJournal {
 		}
 	}
 
-	private async readRecords(): Promise<{
-		readonly latest: readonly MutationRecord[];
-		readonly tail: MutationRecord | undefined;
-		readonly durableEnd: number;
-		readonly hasNonDurableTail: boolean;
-	}> {
+	private async readRecords(): Promise<JournalRecords> {
+		const before = await journalFileFingerprint(this.path);
+		if (before !== null && this.cachedRecords?.fingerprint === before) {
+			return this.cachedRecords.records;
+		}
 		let bytes: Buffer;
 		try {
 			bytes = await readFile(this.path);
 		} catch (error) {
 			if (hasErrorCode(error, "ENOENT")) {
-				return { latest: [], tail: undefined, durableEnd: 0, hasNonDurableTail: false };
+				const records = emptyJournalRecords();
+				this.cachedRecords = undefined;
+				return records;
 			}
 			throw error;
 		}
+		const after = await journalFileFingerprint(this.path);
+		if (before === null || after === null || before !== after) {
+			throw new Error("mutation journal 读取期间发生变化");
+		}
 
 		const durableEnd = bytes.at(-1) === 0x0a ? bytes.length : bytes.lastIndexOf(0x0a) + 1;
 		const durable = bytes.subarray(0, durableEnd).toString("utf8");
@@ -163,7 +249,7 @@ export class MutationJournal {
 		let tail: MutationRecord | undefined;
 
 		for (const line of lines) {
-			const record = assertMutationRecord(JSON.parse(line));
+			const record = Object.freeze(assertMutationRecord(JSON.parse(line)));
 			if (record.opId !== this.opId) throw new Error("mutation record opId 与 journal 不匹配");
 			if (record.previousChecksum !== (tail?.checksum ?? null)) {
 				throw new Error("mutation journal hash chain 断裂");
@@ -185,24 +271,78 @@ export class MutationJournal {
 			tail = record;
 		}
 
-		return { latest, tail, durableEnd, hasNonDurableTail: durableEnd !== bytes.length };
+		const records: JournalRecords = {
+			latest: Object.freeze(latest),
+			tail,
+			durableEnd,
+			hasNonDurableTail: durableEnd !== bytes.length,
+			fileExisted: true,
+		};
+		this.cachedRecords = { records, fingerprint: after };
+		return records;
 	}
 
-	private async append(record: MutationRecord, durableEnd: number, hasNonDurableTail: boolean): Promise<void> {
+	private async append(records: readonly MutationRecord[], current: JournalRecords): Promise<void> {
 		const directory = dirname(this.path);
+		const lines = records.map((record) => `${canonicalJson(record)}\n`).join("");
 		const handle = await open(this.path, "a+", 0o600);
 		try {
-			if (hasNonDurableTail) {
-				await handle.truncate(durableEnd);
+			if (current.hasNonDurableTail) {
+				await handle.truncate(current.durableEnd);
 				await handle.sync();
-				await fsyncDirectory(directory);
 			}
-			await handle.writeFile(`${canonicalJson(record)}\n`);
+			await handle.writeFile(lines);
 			await handle.sync();
 		} finally {
 			await handle.close();
 		}
-		await fsyncDirectory(directory);
+		if (!current.fileExisted) await fsyncDirectory(directory);
+		const fingerprint = await journalFileFingerprint(this.path);
+		if (fingerprint === null) throw new Error("mutation journal append 后丢失");
+		const latest = [...current.latest];
+		let tail = current.tail;
+		for (const record of records) {
+			const durableRecord = Object.freeze({ ...record });
+			latest[record.ordinal - 1] = durableRecord;
+			tail = durableRecord;
+		}
+		this.cachedRecords = {
+			records: {
+				latest: Object.freeze(latest),
+				tail,
+				durableEnd: current.durableEnd + Buffer.byteLength(lines),
+				hasNonDurableTail: false,
+				fileExisted: true,
+			},
+			fingerprint,
+		};
+	}
+}
+
+function emptyJournalRecords(): JournalRecords {
+	return {
+		latest: Object.freeze([]),
+		tail: undefined,
+		durableEnd: 0,
+		hasNonDurableTail: false,
+		fileExisted: false,
+	};
+}
+
+async function journalFileFingerprint(path: string): Promise<string | null> {
+	try {
+		const metadata = await stat(path, { bigint: true });
+		return [
+			metadata.dev,
+			metadata.ino,
+			metadata.mode,
+			metadata.size,
+			metadata.mtimeNs,
+			metadata.ctimeNs,
+		].join(":");
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return null;
+		throw error;
 	}
 }
 

package/src/pi-runtime.ts

@@ -38,12 +38,12 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 	const workspaceLock = new WorkspaceLock();
 	let commandContext: ExtensionCommandContext | undefined;
 	let internalNavigation = false;
-	const capture = async () => {
+	const capture = async (scopePaths?: readonly string[]) => {
 		const topology = await discovery.discover(context.cwd);
 		if (topology.workspaceIdentity !== initialTopology.workspaceIdentity) {
 			throw new Error("workspace identity 已变化");
 		}
-		return store.capture(topology);
+		return store.capture(topology, scopePaths);
 	};
 	const recovery = new JournalRecovery({
 		sessionIdentity,
@@ -59,8 +59,15 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		recoverMutations: async (pending, decision) => {
 			const mutationJournal = journal.mutationJournal(pending.descriptor.opId);
 			const quarantine = new QuarantineManager({ workspaceRoot: context.cwd, journal: mutationJournal });
-			try {
-				const records = (await mutationJournal.load()).filter((record) => record.state !== "CLEANED");
+				try {
+				const loaded = await mutationJournal.load();
+				const scopePaths = pending.descriptor.scopePaths;
+				if (loaded.some((record) => !scopePaths.some((scope) =>
+					scope === "." || record.path === scope || record.path.startsWith(`${scope}/`)
+				))) {
+					throw new Error("mutation journal path 超出 descriptor scope");
+				}
+				const records = loaded.filter((record) => record.state !== "CLEANED");
 				if (decision === "rollback") records.reverse();
 				for (const record of records) {
 					if (decision === "rollback") {