@davideasden/pi-undo 0.2.24 → 0.2.25

package/src/restore-engine.ts

@@ -17,6 +17,7 @@ import {
 } from "./durable-pack.ts";
 import { assertManifest, assertOperationId, canonicalJson, checksum } from "./encoding.ts";
 import { MutationJournal } from "./mutation-journal.ts";
+import { allCompleted, checkOperation, rethrowOperationFailure, isUnconfirmedExit, operationFailure, withRecoveryBudget } from "./operation-context.ts";
 import { createNativeFileBatch } from "./native-restore.ts";
 import { recoverPackedMutations } from "./packed-recovery.ts";
 import type { ManifestId, RestorePath, SnapshotManifest, SnapshotRoot } from "./model.ts";
@@ -61,6 +62,7 @@ export interface RestoreResult {
 	verifiedPaths: number;
 	totalPaths: number;
 	postFingerprint?: string;
+	failureCode?: "operation_cancelled" | "operation_timeout";
 }
 
 export interface RestoreEngine {
@@ -97,6 +99,16 @@ interface OwnedPath {
 	readonly root: SnapshotRoot;
 }
 
+interface VisibleSubsetCheck {
+	/**
+	 * 调用方刚刚完成 topology discovery 且随后没有文件 mutation 时为 true，可跳过枚举入口的重复校验。
+	 * 枚举结束后的校验仍然执行，所以该窗口内的漂移依然被拒绝。
+	 */
+	readonly topologyValidated: boolean;
+	readonly extraExclusions?: readonly string[];
+	readonly ownedPaths?: readonly (ReadonlyMap<string, OwnedPath> | undefined)[];
+}
+
 interface PreparedRestorePlan {
 	readonly plan: RestorePlan;
 	readonly currentPaths: ReadonlyMap<string, OwnedPath>;
@@ -207,12 +219,12 @@ export class RestoreEngine {
 		const canonicalScopePaths = scope === undefined ? undefined : [...scope];
 		assertCompatibleManifests(current, target, scope);
 		const isScopedPath = (path: string): boolean => scope === undefined || scope.has(path);
-		await Promise.all([
+		await allCompleted([
 			this.store.assertComplete(current.manifestId, canonicalScopePaths),
 			this.store.assertComplete(target.manifestId, canonicalScopePaths),
 		]);
 
-		const [currentPaths, targetPaths] = await Promise.all([
+		const [currentPaths, targetPaths] = await allCompleted([
 			this.readOwnedPaths(current, canonicalScopePaths),
 			this.readOwnedPaths(target, canonicalScopePaths),
 		]);
@@ -293,7 +305,7 @@ export class RestoreEngine {
 				const expected = await this.plan(current, target, scopePaths);
 				if (expected.planDigest !== cached.planDigest) return false;
 			}
-			const topology = await this.discovery.discover(this.workspaceRoot);
+			const topology = await this.discovery.discover(this.workspaceRoot, "safety-snapshot");
 			this.assertCurrentTopology(current, target, topology);
 			const native = await createNativeFileBatch({
 				workspaceRoot: this.workspaceRoot,
@@ -313,7 +325,8 @@ export class RestoreEngine {
 				);
 			}
 			return true;
-		} catch {
+		} catch (error) {
+			rethrowOperationFailure(error);
 			return false;
 		}
 	}
@@ -517,7 +530,8 @@ export class RestoreEngine {
 	private async acquireDurableIndexLease(): Promise<{ release(): Promise<void> } | undefined> {
 		try {
 			return await this.durableIndexLock.acquire(await this.durableIndexLockIdentity());
-		} catch {
+		} catch (error) {
+			rethrowOperationFailure(error);
 			return undefined;
 		}
 	}
@@ -737,7 +751,7 @@ export class RestoreEngine {
 		compatibilityMode: boolean,
 		pinsDeferred: boolean,
 	): Promise<RestoreResult> {
-		const [current, storedTarget] = await Promise.all([
+		const [current, storedTarget] = await allCompleted([
 			this.store.loadManifest(plan.currentManifestId),
 			this.store.loadManifest(target.manifestId),
 		]);
@@ -773,13 +787,14 @@ export class RestoreEngine {
 			if (await this.assertWorkspaceRootIdentity() !== current.workspaceIdentity) {
 				throw new Error("restore workspace root 必须使用 canonical identity");
 			}
-			topologyBefore = await this.discovery.discover(this.workspaceRoot);
+			topologyBefore = await this.discovery.discover(this.workspaceRoot, "restore-pre");
 			this.assertCurrentTopology(current, target, topologyBefore);
-		} catch {
+		} catch (error) {
+			rethrowOperationFailure(error);
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
 		const [currentPaths, targetPaths] = prepared === undefined
-			? await Promise.all([
+			? await allCompleted([
 				this.readOwnedPaths(current, plan.scopePaths),
 				this.readOwnedPaths(target, plan.scopePaths),
 			])
@@ -796,14 +811,18 @@ export class RestoreEngine {
 			return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
 		}
 		try {
+			// 兼容恢复路径会先在此窗口内补偿 pending mutations，因此只有非补偿路径可以跳过枚举入口的重复发现。
 			await this.assertCompleteVisibleSubset(
 				topologyBefore,
 				[current, target],
 				options.mutationJournal,
-				[],
-				this.completeCoverageOwnedPaths(plan.scopePaths, [currentPaths, targetPaths]),
+				{
+					topologyValidated: !compatibilityMode,
+					ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [currentPaths, targetPaths]),
+				},
 			);
-		} catch {
+		} catch (error) {
+			rethrowOperationFailure(error);
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
 		let durablePack: DurablePack | undefined;
@@ -833,7 +852,8 @@ export class RestoreEngine {
 						entries: await this.durablePackEntries(current, target, currentPaths, targetPaths, plan, options.opId),
 					});
 				}
-			} catch {
+			} catch (error) {
+				rethrowOperationFailure(error);
 				await removeDurablePack(options.mutationJournal).catch(() => {});
 			}
 		}
@@ -873,7 +893,8 @@ export class RestoreEngine {
 		}
 		try {
 			await this.prefetchCompleteRestoreBlobs(plan, current, target, currentPaths, targetPaths);
-		} catch {
+		} catch (error) {
+			rethrowOperationFailure(error);
 			// 预取是性能优化；失败时继续走原有逐文件校验和可恢复 mutation 路径。
 		}
 		const preflight = await this.verifyKnownState(current, target, currentPaths, targetPaths, plan.scopePaths);
@@ -911,14 +932,16 @@ export class RestoreEngine {
 			);
 			await this.writePlannedPaths(target.manifestId, targetPaths, plan.writePaths, mutationContext);
 
-			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
+			const topologyAfter = await this.discovery.discover(this.workspaceRoot, "restore-post");
 			assertUnchangedTopology(topologyBefore, topologyAfter);
 			await this.assertCompleteVisibleSubset(
 				topologyAfter,
 				[target],
 				options.mutationJournal,
-				[],
-				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+				{
+					topologyValidated: true,
+					ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+				},
 			);
 			const verification = await this.verifyTarget(
 				target,
@@ -936,20 +959,17 @@ export class RestoreEngine {
 			return await this.mutationsAreClean(options.mutationJournal)
 				? result
 				: { code: "recovery_required", verifiedPaths: 0, totalPaths: verification.totalPaths };
-		} catch {
-			if (!await this.restorePendingMutations(mutationContext.quarantine, options.mutationJournal)) {
-				return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
-			}
-			return this.rollback(
-				current,
-				target,
-				topologyBefore,
-				currentPaths,
-				targetPaths,
-				options,
-				plan.scopePaths,
-				!durablePackEnabled,
-			);
+		} catch (error) {
+			if (isUnconfirmedExit(error)) throw error;
+			return withRecoveryBudget(async () => {
+				if (!await this.restorePendingMutations(mutationContext.quarantine, options.mutationJournal)) {
+					return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
+				}
+				const result = await this.rollback(
+					current, target, topologyBefore, currentPaths, targetPaths, options, plan.scopePaths, !durablePackEnabled,
+				);
+				return { ...result, failureCode: operationFailure(error) };
+			});
 		}
 	}
 
@@ -984,49 +1004,45 @@ export class RestoreEngine {
 	): Promise<RestoreResult> {
 		try {
 			await nativeRun(pack);
-			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
+			const topologyAfter = await this.discovery.discover(this.workspaceRoot, "restore-post");
 			assertUnchangedTopology(topologyBefore, topologyAfter);
 			await this.assertCompleteVisibleSubset(
 				topologyAfter,
 				[target],
 				options.mutationJournal,
-				pack.paths().flatMap((path) => {
-					const artifacts = pack.artifacts(path);
-					return artifacts === undefined
-						? []
-						: [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
-				}),
-				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+				{
+					topologyValidated: true,
+					extraExclusions: pack.paths().flatMap((path) => {
+						const artifacts = pack.artifacts(path);
+						return artifacts === undefined
+							? []
+							: [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
+					}),
+					ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+				},
 			);
 			const totalPaths = plan.deletePaths.length + plan.writePaths.length;
 			if ((await options.mutationJournal.load()).length !== 0) {
 				return { code: "recovery_required", verifiedPaths: 0, totalPaths };
 			}
 			return { code: "ok", verifiedPaths: totalPaths, totalPaths };
-		} catch {
-			const packedRecovery = await recoverPackedMutations({
-				workspaceRoot: this.workspaceRoot,
-				journal: options.mutationJournal,
-				planDigest: plan.planDigest,
-				decision: "rollback",
+		} catch (error) {
+			if (isUnconfirmedExit(error)) throw error;
+			return withRecoveryBudget(async () => {
+				const packedRecovery = await recoverPackedMutations({
+					workspaceRoot: this.workspaceRoot,
+					journal: options.mutationJournal,
+					planDigest: plan.planDigest,
+					decision: "rollback",
+				});
+				if (packedRecovery.kind !== "clean") {
+					return { code: "recovery_required", verifiedPaths: 0, totalPaths: plan.deletePaths.length + plan.writePaths.length };
+				}
+				const result = await this.rollback(
+					current, target, topologyBefore, currentPaths, targetPaths, options, plan.scopePaths, false,
+				);
+				return { ...result, failureCode: operationFailure(error) };
 			});
-			if (packedRecovery.kind !== "clean") {
-				return {
-					code: "recovery_required",
-					verifiedPaths: 0,
-					totalPaths: plan.deletePaths.length + plan.writePaths.length,
-				};
-			}
-			return this.rollback(
-				current,
-				target,
-				topologyBefore,
-				currentPaths,
-				targetPaths,
-				options,
-				plan.scopePaths,
-				false,
-			);
 		}
 	}
 
@@ -1041,7 +1057,7 @@ export class RestoreEngine {
 		const paths = [...new Set([...plan.deletePaths, ...plan.writePaths])].sort(comparePaths);
 		const useValidatedBatch = SnapshotStore.supportsValidatedBlobBatch(this.store);
 		const [currentBlobBytes, targetBlobBytes] = useValidatedBatch
-			? await Promise.all([
+			? await allCompleted([
 				this.readDurableBlobBytes(current.manifestId, paths, currentPaths),
 				this.readDurableBlobBytes(target.manifestId, paths, targetPaths),
 			])
@@ -1211,7 +1227,7 @@ export class RestoreEngine {
 			}
 			return requests;
 		};
-		await Promise.all([
+		await allCompleted([
 			this.store.prefetchBlobs(current.manifestId, requestsFor(currentPaths, plan.deletePaths)),
 			this.store.prefetchBlobs(target.manifestId, requestsFor(targetPaths)),
 		]);
@@ -1332,6 +1348,7 @@ export class RestoreEngine {
 			fileBatchRoot = undefined;
 		};
 		for (const path of deletePaths) {
+			checkOperation();
 			if (await this.pathIsShadowedByTarget(targetManifestId, path, targetPaths)) continue;
 			const source = context.sourcePaths.get(path);
 			const live = await lstat(this.absolutePath(path)).catch((error) => {
@@ -1516,14 +1533,16 @@ export class RestoreEngine {
 				context,
 			);
 			await this.writePlannedPaths(current.manifestId, currentPaths, rollbackPlan.writePaths, context);
-			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
+			const topologyAfter = await this.discovery.discover(this.workspaceRoot, "restore-post");
 			assertUnchangedTopology(topologyBefore, topologyAfter);
 			await this.assertCompleteVisibleSubset(
 				topologyAfter,
 				[current],
 				options.mutationJournal,
-				[],
-				this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+				{
+					topologyValidated: true,
+					ownedPaths: this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+				},
 			);
 			const verification = await this.verifyTarget(
 				current,
@@ -1559,14 +1578,16 @@ export class RestoreEngine {
 			}
 			if (rollbackPlan !== undefined) {
 				try {
-					const topologyAfter = await this.discovery.discover(this.workspaceRoot);
+					const topologyAfter = await this.discovery.discover(this.workspaceRoot, "compensation");
 					assertUnchangedTopology(topologyBefore, topologyAfter);
 					await this.assertCompleteVisibleSubset(
 						topologyAfter,
 						[current],
 						options.mutationJournal,
-						[],
-						this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+						{
+							topologyValidated: true,
+							ownedPaths: this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+						},
 					);
 					const verification = await this.verifyTarget(
 						current,
@@ -1621,7 +1642,9 @@ export class RestoreEngine {
 		context.ordinal += 1;
 		const ordinal = context.ordinal;
 		const beforeInstall = async (): Promise<void> => {
+			checkOperation();
 			await this.beforeMutation?.({ phase: context.phase, ordinal, kind, path });
+			checkOperation();
 		};
 		if (!deferHook) await beforeInstall();
 		await this.assertMutationPath(path);
@@ -1656,6 +1679,7 @@ export class RestoreEngine {
 		};
 		for (const kind of ["directory", "leaf"] as const) {
 			for (const path of writePaths) {
+				checkOperation();
 				const target = targetPaths.get(path);
 				if (target === undefined) {
 					throw new Error(`${context.phase} plan 引用了 manifest 外路径：${path}`);
@@ -1715,6 +1739,7 @@ export class RestoreEngine {
 			targetFingerprint: fingerprintBytes(target.absolutePath, bytes, target.entry.mode),
 			...(this.beforeMutation === undefined ? {} : {
 				beforeInstall: async () => {
+					checkOperation();
 					await this.beforeMutation?.({
 						phase: context.phase,
 						ordinal,
@@ -1757,9 +1782,8 @@ export class RestoreEngine {
 	private async assertCompleteVisibleSubset(
 		topology: RootTopology,
 		allowedManifests: readonly SnapshotManifest[],
-		mutationJournal?: MutationJournal,
-		extraExclusions: readonly string[] = [],
-		ownedPaths?: readonly (ReadonlyMap<string, OwnedPath> | undefined)[],
+		mutationJournal: MutationJournal | undefined,
+		check: VisibleSubsetCheck,
 	): Promise<void> {
 		if (allowedManifests.some((manifest) => manifest.coverage !== "complete")) {
 			return;
@@ -1769,7 +1793,7 @@ export class RestoreEngine {
 			for (const path of ignoredWorkspacePaths(manifest)) {
 				allowedPaths.add(path);
 			}
-			const paths = ownedPaths?.[index] ?? await this.readOwnedPaths(manifest);
+			const paths = check.ownedPaths?.[index] ?? await this.readOwnedPaths(manifest);
 			for (const [path, owned] of paths) {
 				if (owned.entry.kind !== "directory") {
 					allowedPaths.add(path);
@@ -1777,12 +1801,13 @@ export class RestoreEngine {
 			}
 		}
 
-		const exclusions = new Set(extraExclusions);
+		const exclusions = new Set(check.extraExclusions ?? []);
 		if (mutationJournal !== undefined) {
 			for (const path of await mutationJournal.activeArtifacts()) exclusions.add(path);
 		}
 		const livePaths = await this.store.listVisibleLeafPaths(topology, {
 			excludePaths: exclusions.size === 0 ? undefined : [...exclusions],
+			topologyAlreadyValidated: check.topologyValidated,
 		});
 		for (const path of livePaths) {
 			if (!allowedPaths.has(path)) {
@@ -1933,7 +1958,7 @@ export class RestoreEngine {
 		if (owned.entry.blobId === null) {
 			throw new Error(`普通文件缺少 blob：${path}`);
 		}
-		const [actual, expected] = await Promise.all([
+		const [actual, expected] = await allCompleted([
 			readFile(this.absolutePath(path)),
 			this.store.readBlob(
 				manifestId,
@@ -2262,6 +2287,7 @@ async function mapConcurrentOrdered<T, R>(
 			const index = nextIndex;
 			nextIndex += 1;
 			try {
+				checkOperation();
 				results[index] = await operation(values[index]!);
 			} catch (error) {
 				if (!failed) failure = error;

package/src/root-discovery.ts

@@ -2,8 +2,9 @@ import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { checksum, topologyFingerprint } from "./encoding.ts";
-import { GitRunner } from "./git-runner.ts";
+import { GitRunError, GitRunner } from "./git-runner.ts";
 import type { DiscoveryRoot } from "./model.ts";
+import { allCompleted, checkOperation, OperationError, reportOperationProgress } from "./operation-context.ts";
 
 const DIRECTORY_SCAN_CONCURRENCY = 16;
 const GIT_POINTER_MAX_BYTES = 4096;
@@ -38,6 +39,19 @@ export interface RootTopology {
 	readonly fingerprint: string;
 }
 
+/**
+ * discover 调用原因：区分安全快照、恢复前、可见路径枚举、恢复后与补偿路径。
+ * 扫描行为不依赖该标签，它只作为调用方诊断与调用次数回归的归属标记。
+ */
+export type RootDiscoveryReason =
+	| "safety-snapshot"
+	| "restore-pre"
+	| "visible-paths-pre"
+	| "visible-paths-post"
+	| "restore-post"
+	| "compensation"
+	| "unspecified";
+
 export type RootDiscoveryErrorCode = "workspace_not_found" | "discovery_failed";
 
 export class RootDiscoveryError extends Error {
@@ -51,7 +65,7 @@ export class RootDiscoveryError extends Error {
 }
 
 export interface RootDiscovery {
-	discover(workspaceRoot: string): Promise<RootTopology>;
+	discover(workspaceRoot: string, reason?: RootDiscoveryReason): Promise<RootTopology>;
 }
 
 export class RootDiscovery {
@@ -61,8 +75,11 @@ export class RootDiscovery {
 		this.git = git;
 	}
 
-	async discover(workspaceRoot: string): Promise<RootTopology> {
+	async discover(workspaceRoot: string, reason: RootDiscoveryReason = "unspecified"): Promise<RootTopology> {
+		checkOperation();
+		reportOperationProgress(`discover_roots:${reason}`);
 		const workspaceIdentity = await canonicalWorkspaceRoot(workspaceRoot);
+		checkOperation();
 		const activeRoots = new Map<string, DiscoveredRoot>();
 		const outerRepository = await this.inspectRepository(workspaceIdentity, workspaceIdentity);
 		if (outerRepository.kind === "active") {
@@ -77,7 +94,10 @@ export class RootDiscovery {
 		}
 
 		await this.scanDirectory(workspaceIdentity, workspaceIdentity, activeRoots);
+		checkOperation();
+		reportOperationProgress("discover_gitlinks");
 		const gitlinkRoots = await this.discoverGitlinks(workspaceIdentity, activeRoots);
+		checkOperation();
 		const roots = buildRoots([...activeRoots.values(), ...gitlinkRoots.values()]);
 		return {
 			workspaceIdentity,
@@ -92,13 +112,19 @@ export class RootDiscovery {
 		activeRoots: Map<string, DiscoveredRoot>,
 	): Promise<void> {
 		let level: Array<{ readonly path: string; readonly inspect: boolean }> = [{ path: directory, inspect: false }];
+		let scanned = 0;
+		reportOperationProgress("scan_directories");
 		while (level.length > 0) {
+			checkOperation();
 			const next: Array<{ readonly path: string; readonly inspect: true }> = [];
 			for (let index = 0; index < level.length; index += DIRECTORY_SCAN_CONCURRENCY) {
-				const children = await Promise.all(level.slice(index, index + DIRECTORY_SCAN_CONCURRENCY).map(
+				checkOperation();
+				const children = await allCompleted(level.slice(index, index + DIRECTORY_SCAN_CONCURRENCY).map(
 					(candidate) => this.scanDirectoryNode(workspaceIdentity, candidate, activeRoots),
 				));
 				for (const group of children) next.push(...group);
+				scanned += children.length;
+				reportOperationProgress(`scan_directories:${scanned}`);
 			}
 			level = next;
 		}
@@ -109,6 +135,7 @@ export class RootDiscovery {
 		candidate: { readonly path: string; readonly inspect: boolean },
 		activeRoots: Map<string, DiscoveredRoot>,
 	): Promise<Array<{ readonly path: string; readonly inspect: true }>> {
+		checkOperation();
 		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		if (candidate.inspect) {
 			const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
@@ -124,6 +151,7 @@ export class RootDiscovery {
 			}
 			if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		}
+		checkOperation();
 		const entries = await readdir(candidate.path, { withFileTypes: true });
 		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		return entries
@@ -208,6 +236,7 @@ export class RootDiscovery {
 	): Promise<Map<string, DiscoveredRoot>> {
 		const result = new Map<string, DiscoveredRoot>();
 		for (const root of activeRoots.values()) {
+			checkOperation();
 			if (!root.gitBacked || root.state !== "active") {
 				continue;
 			}
@@ -248,8 +277,19 @@ export class RootDiscovery {
 			const result = await this.git.run(["-c", "core.fsmonitor=false", ...args], {
 				env: cleanGitEnvironment(),
 			});
+			if (result.aborted || result.timedOut) {
+				// 取消/超时不应被当成"仓库损坏"；有 context 时在这里重新抛出具体原因。
+				checkOperation();
+			}
 			return result.killed ? null : result.stdout;
-		} catch {
+		} catch (error) {
+			if (error instanceof GitRunError && error.code === "git_termination_failed") {
+				// 无法证明子进程已停止：上层必须保留 lease 并走恢复，不能继续扫描。
+				throw error;
+			}
+			if (error instanceof OperationError) {
+				throw error;
+			}
 			return null;
 		}
 	}
@@ -391,6 +431,7 @@ async function gitlinkState(absolutePath: string): Promise<DiscoveryRoot["state"
 const SKELETON_NOISE_FILES = new Set([".DS_Store", "desktop.ini", "Thumbs.db"]);
 
 async function directoryTreeContainsFile(directory: string): Promise<boolean> {
+	checkOperation();
 	let entries;
 	try {
 		entries = await readdir(directory, { withFileTypes: true });