@davideasden/pi-undo 0.2.2 → 0.2.4

package/src/native-restore.ts

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import type { DurablePack } from "./durable-pack.ts";
+import type { MutationJournal } from "./mutation-journal.ts";
+
+const NATIVE_TIMEOUT_MS = 120_000;
+const NATIVE_OUTPUT_LIMIT = 64 * 1024;
+
+export interface NativeFileBatch {
+	readonly available: boolean;
+	run(pack: DurablePack): Promise<void>;
+	verifySource(pack: DurablePack): Promise<boolean>;
+}
+
+export async function createNativeFileBatch(options: {
+	readonly workspaceRoot: string;
+	readonly planDigest: string;
+	readonly journal: MutationJournal;
+}): Promise<NativeFileBatch | undefined> {
+	if (process.env.PI_UNDO_DISABLE_NATIVE === "1") return undefined;
+	const executable = nativeExecutable();
+	if (executable === undefined) return undefined;
+	try {
+		await access(executable, constants.X_OK);
+	} catch {
+		return undefined;
+	}
+	const execute = async (pack: DurablePack, requestPath: string, verifyOnly: boolean): Promise<void> => {
+		const paths = pack.paths();
+		if (paths.length === 0) return;
+		if (pack.planDigest !== options.planDigest) throw new Error("native file batch planDigest 不匹配");
+		const request = {
+			schemaVersion: 1,
+			opId: options.journal.operationId,
+			packOpId: pack.opId,
+			planDigest: pack.planDigest,
+			workspaceRoot: options.workspaceRoot,
+			packPath: pack.storagePath,
+			packChecksum: pack.packChecksum,
+			verifyOnly,
+			entries: paths.map((path) => {
+				const artifacts = pack.artifacts(path);
+				const sourceFingerprint = pack.sourceFingerprint(path);
+				const targetFingerprint = pack.targetFingerprint(path);
+				if (
+					artifacts === undefined ||
+					artifacts.target === null ||
+					sourceFingerprint === undefined ||
+					targetFingerprint === undefined ||
+					targetFingerprint === null
+				) {
+					throw new Error(`native file batch pack entry 无效：${path}`);
+				}
+				return {
+					path,
+					sourceArtifact: artifacts.source,
+					targetArtifact: artifacts.target,
+					sourceFingerprint,
+					targetFingerprint,
+				};
+			}),
+		};
+		await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
+		await runNative(executable, requestPath, paths.length);
+	};
+	return {
+		available: true,
+		run: (pack) => execute(pack, join(dirname(options.journal.storagePath), "native-request-v1.json"), false),
+		verifySource: async (pack) => {
+			try {
+				await execute(pack, join(dirname(pack.storagePath), `native-verify-${process.pid}.json`), true);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}
+
+function nativeExecutable(): string | undefined {
+	const platform = process.platform === "darwin"
+		? "darwin"
+		: process.platform === "linux" ? "linux" : undefined;
+	const architecture = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "x64" : undefined;
+	if (platform === undefined || architecture === undefined) return undefined;
+	return fileURLToPath(new URL(`../native/bin/pi-undo-fs-${platform}-${architecture}`, import.meta.url));
+}
+
+function runNative(executable: string, requestPath: string, expected: number): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(executable, [requestPath], {
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		let outputBytes = 0;
+		let settled = false;
+		const timeout = setTimeout(() => child.kill("SIGKILL"), NATIVE_TIMEOUT_MS);
+		const capture = (target: Buffer[]) => (chunk: Buffer | string): void => {
+			if (outputBytes >= NATIVE_OUTPUT_LIMIT) return;
+			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			const captured = bytes.subarray(0, NATIVE_OUTPUT_LIMIT - outputBytes);
+			target.push(captured);
+			outputBytes += captured.length;
+		};
+		child.stdout?.on("data", capture(stdout));
+		child.stderr?.on("data", capture(stderr));
+		child.once("error", (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (code !== 0) {
+				reject(new Error(`native restore 失败：${Buffer.concat(stderr).toString("utf8").trim()}`));
+				return;
+			}
+			try {
+				const result: unknown = JSON.parse(Buffer.concat(stdout).toString("utf8"));
+				if (
+					typeof result !== "object" ||
+					result === null ||
+					!("ok" in result) ||
+					result.ok !== true ||
+					!("processed" in result) ||
+					result.processed !== expected
+				) {
+					throw new Error("native restore 响应无效");
+				}
+				resolve();
+			} catch (error) {
+				reject(error);
+			}
+		});
+	});
+}

package/src/packed-recovery.ts

@@ -0,0 +1,324 @@
+import { link, lstat, rm, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { fsyncDirectory, writeBytesExclusive } from "./atomic-fs.ts";
+import { loadDurablePack, type DurableLeaf, type DurablePack } from "./durable-pack.ts";
+import type { MutationJournal } from "./mutation-journal.ts";
+import type { MutationRecord, MutationState } from "./model.ts";
+import { assertNoSymlinkEscape, relativeSafePath } from "./path-safety.ts";
+import { fingerprintAbsent, fingerprintFile, fingerprintLeaf } from "./quarantine.ts";
+
+const PACKED_RECOVERY_CONCURRENCY = 32;
+
+const stateOrder: readonly MutationState[] = [
+	"INTENT",
+	"SOURCE_QUARANTINED",
+	"SOURCE_VERIFIED",
+	"TARGET_INSTALLED",
+	"TARGET_VERIFIED",
+	"CLEANED",
+];
+
+export async function materializePackedMutationJournal(
+	journal: MutationJournal,
+	pack: DurablePack,
+): Promise<void> {
+	const records = await ensurePackedIntents(journal, pack, await journal.load());
+	const terminalIndex = stateOrder.indexOf("TARGET_VERIFIED");
+	const advances = records.map((record) => ({
+		ordinal: record.ordinal,
+		states: stateOrder.slice(stateOrder.indexOf(record.state) + 1, terminalIndex + 1),
+	})).filter((advance) => advance.states.length > 0);
+	if (advances.length > 0) await journal.advanceBatch(advances);
+}
+
+export async function recoverPackedMutations(options: {
+	readonly workspaceRoot: string;
+	readonly journal: MutationJournal;
+	readonly planDigest: string;
+	readonly decision: "rollback" | "roll_forward";
+	readonly retainArtifacts?: boolean;
+}): Promise<{ readonly kind: "clean" } | { readonly kind: "conflict"; readonly paths: number }> {
+	try {
+		const workspaceRoot = resolve(options.workspaceRoot);
+		const pack = await loadDurablePack(options.journal, options.planDigest, true);
+		const records = await ensurePackedIntents(options.journal, pack, await options.journal.load());
+		await mapConcurrent(records, PACKED_RECOVERY_CONCURRENCY, async (record) => {
+			if (record.kind !== "write" || record.targetArtifact === null) throw new Error("packed recovery 只支持普通文件 write");
+			const source = pack.leaf(record.path, record.sourceFingerprint);
+			const target = pack.leaf(record.path, record.targetFingerprint);
+			if (source === undefined || target === undefined || target.kind !== "file") {
+				throw new Error(`packed recovery variant 缺失：${record.path}`);
+			}
+			await normalizeRecord(
+				workspaceRoot,
+				record,
+				source,
+				target,
+				options.decision,
+				options.retainArtifacts === true,
+			);
+		});
+		const terminalState: MutationState = options.retainArtifacts === true ? "TARGET_VERIFIED" : "CLEANED";
+		const terminalIndex = stateOrder.indexOf(terminalState);
+		const advances = records.map((record) => ({
+			ordinal: record.ordinal,
+			states: stateOrder.slice(stateOrder.indexOf(record.state) + 1, terminalIndex + 1),
+		})).filter((advance) => advance.states.length > 0);
+		if (advances.length > 0) await options.journal.advanceBatch(advances);
+		if (options.retainArtifacts !== true) await options.journal.assertCleaned();
+		return { kind: "clean" };
+	} catch {
+		const active = await options.journal.load().catch(() => []);
+		return {
+			kind: "conflict",
+			paths: Math.max(1, active.filter((record) => record.state !== "CLEANED").length),
+		};
+	}
+}
+
+export async function cleanupPackedMutations(options: {
+	readonly workspaceRoot: string;
+	readonly journal: MutationJournal;
+	readonly planDigest: string;
+}): Promise<void> {
+	const workspaceRoot = resolve(options.workspaceRoot);
+	const pack = await loadDurablePack(options.journal, options.planDigest, true);
+	const records = [...await options.journal.load()];
+	const cleanupDirectories = new Set<string>();
+	await mapConcurrent(records, PACKED_RECOVERY_CONCURRENCY, async (record) => {
+		if (
+			(record.state !== "TARGET_VERIFIED" && record.state !== "CLEANED") ||
+			record.kind !== "write" ||
+			record.targetArtifact === null
+		) {
+			throw new Error(`packed cleanup mutation 状态无效：${record.path}`);
+		}
+		relativeSafePath(workspaceRoot, record.path);
+		await assertNoSymlinkEscape(workspaceRoot, record.path);
+		const original = join(workspaceRoot, ...record.path.split("/"));
+		const sourceArtifact = join(workspaceRoot, ...record.sourceArtifact.split("/"));
+		const targetArtifact = join(workspaceRoot, ...record.targetArtifact.split("/"));
+		const source = pack.leaf(record.path, record.sourceFingerprint);
+		if (source === undefined) throw new Error(`packed cleanup source variant 缺失：${record.path}`);
+		if (await pathExists(targetArtifact)) {
+			await assertSameFileIdentity(original, targetArtifact, record.path);
+		} else if (record.state !== "CLEANED") {
+			throw new Error(`packed cleanup target ownership 缺失：${record.path}`);
+		}
+		await cleanupArtifact(sourceArtifact, record.path, record.sourceFingerprint, cleanupDirectories);
+		await cleanupArtifact(targetArtifact, record.path, record.targetFingerprint, cleanupDirectories);
+	});
+	for (const directory of cleanupDirectories) await fsyncDirectory(directory);
+	const advances = records
+		.filter((record) => record.state === "TARGET_VERIFIED")
+		.map((record) => ({ ordinal: record.ordinal, states: ["CLEANED" as const] }));
+	if (advances.length > 0) await options.journal.advanceBatch(advances);
+	await options.journal.assertCleaned();
+}
+
+async function ensurePackedIntents(
+	journal: MutationJournal,
+	pack: DurablePack,
+	loaded: readonly MutationRecord[],
+): Promise<MutationRecord[]> {
+	const paths = pack.paths();
+	if (loaded.length > paths.length) throw new Error("packed mutation journal 路径数量不匹配");
+	const records = [...loaded];
+	for (let index = 0; index < records.length; index += 1) {
+		assertPackedRecord(pack, paths[index]!, records[index]!);
+	}
+	if (records.length < paths.length) {
+		records.push(...await journal.beginMany(
+			paths.slice(records.length).map((path) => packedIntent(pack, path)),
+		));
+	}
+	return records;
+}
+
+function packedIntent(pack: DurablePack, path: string) {
+	const artifacts = pack.artifacts(path);
+	const sourceFingerprint = pack.sourceFingerprint(path);
+	const targetFingerprint = pack.targetFingerprint(path);
+	if (
+		artifacts === undefined ||
+		artifacts.target === null ||
+		sourceFingerprint === undefined ||
+		targetFingerprint === undefined ||
+		targetFingerprint === null
+	) {
+		throw new Error(`packed recovery intent 缺失：${path}`);
+	}
+	return {
+		kind: "write" as const,
+		path,
+		sourceArtifact: artifacts.source,
+		targetArtifact: artifacts.target,
+		sourceFingerprint,
+		targetFingerprint,
+	};
+}
+
+function assertPackedRecord(pack: DurablePack, path: string, record: MutationRecord): void {
+	const expected = packedIntent(pack, path);
+	if (
+		record.kind !== expected.kind ||
+		record.path !== expected.path ||
+		record.sourceArtifact !== expected.sourceArtifact ||
+		record.targetArtifact !== expected.targetArtifact ||
+		record.sourceFingerprint !== expected.sourceFingerprint ||
+		record.targetFingerprint !== expected.targetFingerprint
+	) {
+		throw new Error(`packed mutation journal 与 pack 不匹配：${path}`);
+	}
+}
+
+async function normalizeRecord(
+	workspaceRoot: string,
+	record: MutationRecord,
+	source: DurableLeaf,
+	target: DurableLeaf,
+	decision: "rollback" | "roll_forward",
+	retainArtifacts: boolean,
+): Promise<void> {
+	relativeSafePath(workspaceRoot, record.path);
+	await assertNoSymlinkEscape(workspaceRoot, record.path);
+	const original = join(workspaceRoot, ...record.path.split("/"));
+	const sourceArtifact = join(workspaceRoot, ...record.sourceArtifact.split("/"));
+	const targetArtifact = join(workspaceRoot, ...record.targetArtifact!.split("/"));
+	const observed = await fingerprintLeaf(original, record.path);
+	const absent = fingerprintAbsent(record.path);
+	if (observed !== absent && observed !== record.sourceFingerprint && observed !== record.targetFingerprint) {
+		throw new Error(`packed recovery original 冲突：${record.path}`);
+	}
+	await assertArtifact(sourceArtifact, record.path, record.sourceFingerprint, source.kind === "absent");
+	await assertArtifact(targetArtifact, record.path, record.targetFingerprint, false);
+	if (observed === record.targetFingerprint) {
+		if (await pathExists(targetArtifact)) {
+			await assertSameFileIdentity(original, targetArtifact, record.path);
+		} else if (!(record.state === "CLEANED" && decision === "roll_forward")) {
+			throw new Error(`packed recovery target ownership 缺失：${record.path}`);
+		}
+	}
+	const desired = decision === "rollback" ? source : target;
+	if (decision === "roll_forward" && observed === record.sourceFingerprint && observed !== absent) {
+		throw new Error(`packed recovery source ownership 冲突：${record.path}`);
+	}
+	if (observed !== desired.fingerprint) {
+		if (observed !== absent) {
+			await unlink(original);
+			await fsyncDirectory(dirname(original));
+		}
+		await materialize(original, record.path, desired);
+		if (retainArtifacts && desired === target) {
+			await linkOwnershipMarker(original, targetArtifact, record.path);
+		}
+	}
+	if (!retainArtifacts) {
+		await cleanupArtifact(sourceArtifact, record.path, record.sourceFingerprint);
+		await cleanupArtifact(targetArtifact, record.path, record.targetFingerprint);
+	}
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	return lstat(path).then(() => true, (error) => {
+		if (hasErrorCode(error, "ENOENT")) return false;
+		throw error;
+	});
+}
+
+async function assertArtifact(
+	path: string,
+	logicalPath: string,
+	expectedFingerprint: string,
+	mustBeAbsent: boolean,
+): Promise<void> {
+	const exists = await lstat(path).then(() => true, (error) => {
+		if (hasErrorCode(error, "ENOENT")) return false;
+		throw error;
+	});
+	if (!exists) return;
+	if (mustBeAbsent || await fingerprintFile(path, logicalPath) !== expectedFingerprint) {
+		throw new Error(`packed recovery artifact 冲突：${logicalPath}`);
+	}
+}
+
+async function linkOwnershipMarker(original: string, artifact: string, logicalPath: string): Promise<void> {
+	try {
+		await link(original, artifact);
+	} catch (error) {
+		if (!hasErrorCode(error, "EEXIST")) throw error;
+	}
+	await assertSameFileIdentity(original, artifact, logicalPath);
+	await fsyncDirectory(dirname(artifact));
+}
+
+async function assertSameFileIdentity(original: string, artifact: string, logicalPath: string): Promise<void> {
+	const [originalMetadata, artifactMetadata] = await Promise.all([lstat(original), lstat(artifact)]);
+	if (
+		!originalMetadata.isFile() ||
+		!artifactMetadata.isFile() ||
+		originalMetadata.dev !== artifactMetadata.dev ||
+		originalMetadata.ino !== artifactMetadata.ino
+	) {
+		throw new Error(`packed recovery target ownership 冲突：${logicalPath}`);
+	}
+}
+
+async function cleanupArtifact(
+	path: string,
+	logicalPath: string,
+	expectedFingerprint: string,
+	deferredDirectories?: Set<string>,
+): Promise<void> {
+	try {
+		if (await fingerprintFile(path, logicalPath) !== expectedFingerprint) {
+			throw new Error(`packed recovery cleanup artifact 冲突：${logicalPath}`);
+		}
+		await unlink(path);
+		if (deferredDirectories === undefined) {
+			await fsyncDirectory(dirname(path));
+		} else {
+			deferredDirectories.add(dirname(path));
+		}
+	} catch (error) {
+		if (!hasErrorCode(error, "ENOENT")) throw error;
+	}
+}
+
+async function materialize(path: string, logicalPath: string, leaf: DurableLeaf): Promise<void> {
+	if (leaf.kind === "absent") return;
+	if (leaf.kind !== "file") throw new Error(`packed recovery 暂不支持 symlink：${logicalPath}`);
+	await writeBytesExclusive(path, leaf.bytes, leaf.mode);
+	if (await fingerprintFile(path, logicalPath) !== leaf.fingerprint) {
+		await rm(path, { force: true });
+		throw new Error(`packed recovery materialize 校验失败：${logicalPath}`);
+	}
+}
+
+async function mapConcurrent<T>(
+	values: readonly T[],
+	concurrency: number,
+	worker: (value: T) => Promise<void>,
+): Promise<void> {
+	let next = 0;
+	let firstFailure: unknown;
+	const runners = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+		while (firstFailure === undefined) {
+			const index = next;
+			next += 1;
+			if (index >= values.length) return;
+			try {
+				await worker(values[index]!);
+			} catch (error) {
+				firstFailure = error;
+			}
+		}
+	});
+	await Promise.all(runners);
+	if (firstFailure !== undefined) throw firstFailure;
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/src/path-safety.ts

@@ -64,6 +64,23 @@ export async function assertNoSymlinkEscape(root: string, relativePath: string):
 	}
 }
 
+export function pathSetsOverlap(leftPaths: readonly string[], rightPaths: readonly string[]): boolean {
+	for (const path of leftPaths) assertRelativeCandidate(path);
+	for (const path of rightPaths) assertRelativeCandidate(path);
+	const rightSet = new Set(rightPaths);
+	const sortedRight = [...rightSet].sort(comparePaths);
+	for (const path of leftPaths) {
+		if (rightSet.has(path)) return true;
+		for (let separator = path.lastIndexOf("/"); separator >= 0; separator = path.lastIndexOf("/", separator - 1)) {
+			if (rightSet.has(path.slice(0, separator))) return true;
+		}
+		const descendantPrefix = `${path}/`;
+		const candidate = sortedRight[lowerBound(sortedRight, descendantPrefix)];
+		if (candidate?.startsWith(descendantPrefix)) return true;
+	}
+	return false;
+}
+
 export function sortDeletePaths(paths: readonly string[]): string[] {
 	return sortPaths(paths, -1);
 }
@@ -108,6 +125,20 @@ function pathDepth(path: string): number {
 	return path === "." ? 0 : path.split("/").length;
 }
 
+function lowerBound(paths: readonly string[], target: string): number {
+	let low = 0;
+	let high = paths.length;
+	while (low < high) {
+		const middle = low + Math.floor((high - low) / 2);
+		if (comparePaths(paths[middle]!, target) < 0) {
+			low = middle + 1;
+		} else {
+			high = middle;
+		}
+	}
+	return low;
+}
+
 function comparePaths(left: string, right: string): number {
 	return left < right ? -1 : left > right ? 1 : 0;
 }

package/src/pi-runtime.ts

@@ -12,9 +12,15 @@ import {
 	type ControllerDependencies,
 	type ControllerInitialState,
 } from "./controller.ts";
+import { finalizeDurablePack, hasDurablePack, loadDurablePack } from "./durable-pack.ts";
 import { assertCursor, canonicalJson, checksum } from "./encoding.ts";
 import { JournalStore, finalizeCursorMarker, inspectCursorMarkers } from "./journal.ts";
 import type { CheckpointRecord, ManifestId, SessionFileIdentity } from "./model.ts";
+import {
+	cleanupPackedMutations,
+	materializePackedMutationJournal,
+	recoverPackedMutations,
+} from "./packed-recovery.ts";
 import { JournalRecovery } from "./recovery.ts";
 import { QuarantineManager } from "./quarantine.ts";
 import { RestoreEngine } from "./restore-engine.ts";
@@ -58,8 +64,26 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		),
 		recoverMutations: async (pending, decision) => {
 			const mutationJournal = journal.mutationJournal(pending.descriptor.opId);
+			if (await hasDurablePack(mutationJournal)) {
+				const result = await recoverPackedMutations({
+					workspaceRoot: context.cwd,
+					journal: mutationJournal,
+					planDigest: pending.descriptor.planDigest,
+					decision,
+					retainArtifacts: decision === "roll_forward",
+				});
+				if (result.kind === "clean" && decision === "roll_forward") {
+					await finalizeDurablePack(mutationJournal, context.cwd);
+					await cleanupPackedMutations({
+						workspaceRoot: context.cwd,
+						journal: mutationJournal,
+						planDigest: pending.descriptor.planDigest,
+					});
+				}
+				return result;
+			}
 			const quarantine = new QuarantineManager({ workspaceRoot: context.cwd, journal: mutationJournal });
-				try {
+			try {
 				const loaded = await mutationJournal.load();
 				const scopePaths = pending.descriptor.scopePaths;
 				if (loaded.some((record) => !scopePaths.some((scope) =>
@@ -75,7 +99,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 						continue;
 					}
 					await quarantine.rollForwardMutation(record);
-					const latest = (await mutationJournal.load()).find((candidate) => candidate.ordinal === record.ordinal);
+					const latest = await mutationJournal.loadOrdinal(record.ordinal);
 					if (latest === undefined) throw new Error("mutation ordinal 在恢复期间丢失");
 					await quarantine.cleanupMutation(latest);
 				}
@@ -95,10 +119,60 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		applyRestore: (plan, target, operation) => restore.apply(plan, target, {
 			opId: operation.opId,
 			mutationJournal: journal.mutationJournal(operation.opId),
+			forceTargetArtifactSync: true,
 		}),
 		settle: (opId, phase) => journal.settleRecovery(opId, phase),
 	});
 
+	let finalizationQueue: Promise<void> = Promise.resolve();
+	let finalizationFailure: unknown;
+	const waitForFinalization = async (): Promise<void> => {
+		await finalizationQueue;
+		if (finalizationFailure !== undefined) throw finalizationFailure;
+	};
+	const scheduleFinalization = (opId: string): void => {
+		finalizationQueue = finalizationQueue.then(async () => {
+			const lease = await workspaceLock.acquire(initialTopology.workspaceIdentity);
+			try {
+				const mutationJournal = journal.mutationJournal(opId);
+				const pack = await loadDurablePack(mutationJournal, undefined, true);
+				const [materialized, finalized] = await Promise.allSettled([
+					materializePackedMutationJournal(mutationJournal, pack),
+					finalizeDurablePack(mutationJournal, context.cwd, {
+						allowCleanedOwnershipWithoutMarker: false,
+					}),
+				]);
+				if (materialized.status === "rejected") throw materialized.reason;
+				if (finalized.status === "rejected") throw finalized.reason;
+				await cleanupPackedMutations({
+					workspaceRoot: context.cwd,
+					journal: mutationJournal,
+					planDigest: pack.planDigest,
+				});
+				await journal.markCommitted(opId);
+			} finally {
+				await lease.release();
+			}
+		}).catch((error: unknown) => {
+			finalizationFailure = error;
+		});
+	};
+	const transactionJournal: ControllerDependencies["journal"] = {
+		prepare: (descriptor, plan) => journal.prepare(descriptor, plan),
+		setPhase: (opId, phase, options) => journal.setPhase(opId, phase, options),
+		setPhases: (opId, transitions) => journal.setPhases(opId, transitions),
+		markCommitted: async (opId) => {
+			const mutationJournal = journal.mutationJournal(opId);
+			if (!await hasDurablePack(mutationJournal)) {
+				await journal.markCommitted(opId);
+				return;
+			}
+			await journal.assertLogicalCommitReady(opId, true);
+			scheduleFinalization(opId);
+		},
+		loadPending: () => journal.loadPending(),
+	};
+
 	const dependencies: ControllerDependencies = {
 		workspaceIdentity: initialTopology.workspaceIdentity,
 		sessionIdentity,
@@ -106,7 +180,10 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		abortAgent: async () => { context.abort(); },
 		waitForIdle: async (deadlineMs) => waitForIdle(commandContext, deadlineMs),
 		getLogicalLeafId: () => sessionStateFor(manager).getLogicalLeafId(),
-		acquireWorkspaceLock: () => workspaceLock.acquire(initialTopology.workspaceIdentity),
+		acquireWorkspaceLock: async () => {
+			await waitForFinalization();
+			return workspaceLock.acquire(initialTopology.workspaceIdentity);
+		},
 		findUserEntryAfter: (startEntryId) => findUserEntryAfter(manager, startEntryId),
 		resolveSessionTarget: (action, checkpoint) => action === "undo"
 			? logicalLeafAt(manager, entryParent(manager, checkpoint.userEntryId))
@@ -136,18 +213,32 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		appendControl: async (customType, data) => appendControlEntry(pi, manager, customType, data),
 		appendCursor: async (cursor) => cursorWriter.appendCursor(cursor, pi, sourceFor(manager)),
 		capture,
+		captureSafety: async (referenceManifestId, targetManifestId, scopePaths) => {
+			const [reference, target] = await Promise.all([
+				store.loadManifest(referenceManifestId),
+				store.loadManifest(targetManifestId),
+			]);
+			if (await restore.canReuseDurableSource(reference, target, scopePaths)) return reference;
+			return capture(scopePaths);
+		},
 		changedPaths: async (before, after) => {
 			const plan = await restore.plan(before, after);
 			return [...new Set([...plan.deletePaths, ...plan.writePaths])].sort();
 		},
 		loadManifest: (manifestId) => store.loadManifest(manifestId),
 		planRestore: (current, target, scopePaths) => restore.plan(current, target, scopePaths),
+		prepareDurableRestore: (current, target, scopePaths) =>
+			restore.prepareDurableRestore(current, target, scopePaths),
 		applyRestore: (plan, target, operation) => restore.apply(plan, target, {
 			opId: operation.opId,
 			mutationJournal: journal.mutationJournal(operation.opId),
+			deferDurability: true,
 		}),
-		recoverPending: () => workspaceLock.withLock(initialTopology.workspaceIdentity, () => recovery.recover()),
-		journal,
+		recoverPending: async () => {
+			await waitForFinalization();
+			return workspaceLock.withLock(initialTopology.workspaceIdentity, () => recovery.recover());
+		},
+		journal: transactionJournal,
 		clock: Date.now,
 	};
 	const startupRecovery = await workspaceLock.withLock(