@davideasden/pi-undo 0.3.6 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -174,3 +174,45 @@ function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoExcept
174
174
  function fail(code: PathSafetyErrorCode, message: string): never {
175
175
  throw new PathSafetyError(code, message);
176
176
  }
177
+
178
+ /**
179
+ * mutation 影响判定索引。
180
+ *
181
+ * 原实现每次判定都重新展开 `[...deletePaths, ...writePaths]` 并线性扫描;
182
+ * 10k 目标路径 × 10k mutation 时是 O(n²)。这里把精确集合、mutation 祖先集合和
183
+ * 排序后的 mutation 列表一次建好,单次判定近 O(log n)。
184
+ * 语义与 `mutationPath === path || mutationPath.startsWith(path + "/") || path.startsWith(mutationPath + "/")` 完全一致。
185
+ */
186
+ export class MutationPathIndex {
187
+ private readonly exact: ReadonlySet<string>;
188
+ private readonly sorted: readonly string[];
189
+
190
+ constructor(deletePaths: readonly string[], writePaths: readonly string[]) {
191
+ this.exact = new Set([...deletePaths, ...writePaths]);
192
+ this.sorted = [...this.exact].sort();
193
+ }
194
+
195
+ affects(path: string): boolean {
196
+ // mutation 是 path 本身,或是 path 内的后代。
197
+ if (this.exact.has(path) || sortedStartsWith(this.sorted, `${path}/`)) return true;
198
+ // path 位于某个 mutation 目录内:path 的严格祖先中存在 mutation。
199
+ let separator = path.lastIndexOf("/");
200
+ while (separator > 0) {
201
+ if (this.exact.has(path.slice(0, separator))) return true;
202
+ separator = path.lastIndexOf("/", separator - 1);
203
+ }
204
+ return false;
205
+ }
206
+ }
207
+
208
+ /** 排序数组中第一个以 prefix 开头的项;供 ignored proof 与 mutation 索引复用。 */
209
+ export function sortedStartsWith(sorted: readonly string[], prefix: string): boolean {
210
+ let low = 0;
211
+ let high = sorted.length;
212
+ while (low < high) {
213
+ const middle = (low + high) >>> 1;
214
+ if (sorted[middle]! < prefix) low = middle + 1;
215
+ else high = middle;
216
+ }
217
+ return low < sorted.length && sorted[low]!.startsWith(prefix);
218
+ }
package/src/pi-runtime.ts CHANGED
@@ -9,6 +9,7 @@ import type {
9
9
 
10
10
  import {
11
11
  UndoControllerImpl,
12
+ type CaptureBaselineOptions,
12
13
  type ControllerDependencies,
13
14
  type ControllerInitialState,
14
15
  type SettlementDiagnostic,
@@ -72,6 +73,7 @@ async function initializePiUndoRuntime(context: ExtensionContext, pi: ExtensionA
72
73
  baseline: SnapshotManifest,
73
74
  onDiagnostics?: (diagnostic: CaptureDiagnostic) => void,
74
75
  onTiming?: (phase: string, durationMs: number) => void,
76
+ options: CaptureBaselineOptions = {},
75
77
  ) => {
76
78
  const discoveryStartedAt = performance.now();
77
79
  let topology: RootTopology;
@@ -85,6 +87,7 @@ async function initializePiUndoRuntime(context: ExtensionContext, pi: ExtensionA
85
87
  }
86
88
  return store.captureBaseline(topology, baseline, undefined, {
87
89
  topologyAlreadyValidated: true,
90
+ ...(options.skipBaselineProbe === true ? { skipBaselineProbe: true } : {}),
88
91
  // captureBaselineWithWorkspaceLock 已持有工作区独占锁,且此处刚完成 discover;
89
92
  // post-capture topology 校验在锁内是冗余的,跳过以节省一次全量目录扫描。
90
93
  skipPostTopologyCheck: true,
@@ -167,6 +170,7 @@ async function initializePiUndoRuntime(context: ExtensionContext, pi: ExtensionA
167
170
  opId: operation.opId,
168
171
  mutationJournal: journal.mutationJournal(operation.opId),
169
172
  forceTargetArtifactSync: true,
173
+ workspaceLockHeld: true,
170
174
  }),
171
175
  settle: (opId, phase) => journal.settleRecovery(opId, phase),
172
176
  });
@@ -276,6 +280,9 @@ async function initializePiUndoRuntime(context: ExtensionContext, pi: ExtensionA
276
280
  store.loadManifest(targetManifestId),
277
281
  ]);
278
282
  if (await restore.canReuseDurableSource(reference, target, scopePaths)) return reference;
283
+ // durable pack 可能仍在后台预制;若当前 scope 已经与 reference manifest 一致,
284
+ // 不必为 rollback 再做一次全量目录扫描。apply 仍会在 mutation 前复核 topology。
285
+ if (await restore.canReuseManifestSource(reference, target, scopePaths)) return reference;
279
286
  return capture(scopePaths);
280
287
  },
281
288
  changedPaths: async (before, after) => {
@@ -292,6 +299,7 @@ async function initializePiUndoRuntime(context: ExtensionContext, pi: ExtensionA
292
299
  opId: operation.opId,
293
300
  mutationJournal: journal.mutationJournal(operation.opId),
294
301
  deferDurability: true,
302
+ workspaceLockHeld: true,
295
303
  onTiming: (phase, durationMs) => {
296
304
  try {
297
305
  phases.push({ phase, elapsedMs: Math.round(performance.now() - operationStarted) });
@@ -34,6 +34,8 @@ export class ResidentScanClient {
34
34
  private readonly executable: string,
35
35
  private readonly workspaceRoot: string,
36
36
  private readonly timeoutMs: number,
37
+ /** 与一次性 helper 共享的持久目录缓存;serve 启动时读取,初始扫描后写回。 */
38
+ private readonly cachePath?: string,
37
39
  ) {}
38
40
 
39
41
  /** 建立进程并完成首次全量扫描;失败静默,正式扫描会回退。 */
@@ -93,6 +95,7 @@ export class ResidentScanClient {
93
95
  const handshakeLine = await this.requestLine(child, JSON.stringify({
94
96
  schemaVersion: 1,
95
97
  workspaceRoot: this.workspaceRoot,
98
+ ...(this.cachePath === undefined ? {} : { cachePath: this.cachePath }),
96
99
  }), timeoutMs);
97
100
  const handshake = handshakeLine === undefined ? undefined : parseObjectOrUndefined(handshakeLine);
98
101
  if (handshake?.ok !== true || handshake.ready !== true) {
@@ -211,9 +214,10 @@ export class ResidentScanClient {
211
214
  private scheduleIdle(): void {
212
215
  if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
213
216
  if (this.closed) return;
217
+ // 与 Rust 端 600s 看门狗保持同一量级;大工作区冷启动比重启进程更贵。
214
218
  this.idleTimer = setTimeout(() => {
215
219
  void this.close();
216
- }, 70_000);
220
+ }, 610_000);
217
221
  this.idleTimer.unref?.();
218
222
  }
219
223
 
@@ -27,6 +27,7 @@ import { recoverPackedMutations } from "./packed-recovery.ts";
27
27
  import type { ManifestId, RestorePath, SnapshotManifest, SnapshotRoot } from "./model.ts";
28
28
  import {
29
29
  assertNoSymlinkEscape,
30
+ MutationPathIndex,
30
31
  relativeSafePath,
31
32
  sortDeletePaths,
32
33
  sortWritePaths,
@@ -79,6 +80,8 @@ export interface RestoreApplyOptions {
79
80
  readonly mutationJournal: MutationJournal;
80
81
  readonly forceTargetArtifactSync?: boolean;
81
82
  readonly deferDurability?: boolean;
83
+ /** 调用方已持有 workspace 独占锁时,可略过 visible-pre 枚举后的重复 topology 扫描。 */
84
+ readonly workspaceLockHeld?: boolean;
82
85
  /** 报告 apply 内部阶段耗时;回调异常不影响恢复结果。 */
83
86
  readonly onTiming?: (phase: string, durationMs: number) => void;
84
87
  }
@@ -250,7 +253,6 @@ export class RestoreEngine {
250
253
  const scope = scopePaths === undefined ? undefined : this.canonicalScope(scopePaths);
251
254
  const canonicalScopePaths = scope === undefined ? undefined : [...scope];
252
255
  assertCompatibleManifests(current, target, scope);
253
- const isScopedPath = (path: string): boolean => scope === undefined || scope.has(path);
254
256
  reportDurablePackTiming(options, "plan.validate", validationStarted);
255
257
  const completeStarted = performance.now();
256
258
  await allCompleted([
@@ -258,6 +260,29 @@ export class RestoreEngine {
258
260
  this.store.assertComplete(target.manifestId, canonicalScopePaths),
259
261
  ]);
260
262
  reportDurablePackTiming(options, "plan.complete", completeStarted);
263
+ return this.computePlan(current, target, scope, canonicalScopePaths, options);
264
+ }
265
+
266
+ private async computePlan(
267
+ current: SnapshotManifest,
268
+ target: SnapshotManifest,
269
+ scope: ReadonlySet<string> | undefined,
270
+ canonicalScopePaths: readonly string[] | undefined,
271
+ options: DurablePackPreparationOptions = {},
272
+ ): Promise<RestorePlan> {
273
+ const isScopedPath = (path: string): boolean => scope === undefined || scope.has(path);
274
+ const prepared = canonicalScopePaths === undefined
275
+ ? undefined
276
+ : this.findPreparedPlan(current.manifestId, target.manifestId, canonicalScopePaths);
277
+ if (prepared !== undefined) {
278
+ // 后台 durable prepare 已读取并验证过同一对 immutable manifest;复用路径表,
279
+ // 避免 undo 前再执行一轮 listTree 与 diff。
280
+ const pathsStarted = performance.now();
281
+ reportDurablePackTiming(options, "plan.paths", pathsStarted);
282
+ const diffStarted = performance.now();
283
+ reportDurablePackTiming(options, "plan.diff", diffStarted);
284
+ return cloneRestorePlan(prepared.plan);
285
+ }
261
286
 
262
287
  const pathsStarted = performance.now();
263
288
  const [currentPaths, targetPaths] = await allCompleted([
@@ -318,6 +343,11 @@ export class RestoreEngine {
318
343
  return plan;
319
344
  }
320
345
 
346
+ /**
347
+ * 仅验证缓存 durable pack 对应 scope 的 source 文件。
348
+ * topology 的权威检查在 apply 的 restore-pre 阶段执行,避免同一 undo
349
+ * 在 safety reuse 与真正 mutation 前重复扫描整个工作区。
350
+ */
321
351
  async canReuseDurableSource(
322
352
  current: SnapshotManifest,
323
353
  target: SnapshotManifest,
@@ -341,11 +371,16 @@ export class RestoreEngine {
341
371
  try {
342
372
  if (await this.assertWorkspaceRootIdentity() !== current.workspaceIdentity) return false;
343
373
  if (fromPersistentIndex) {
344
- const expected = await this.plan(current, target, scopePaths);
374
+ assertManifest(current);
375
+ assertManifest(target);
376
+ const scope = this.canonicalScope(scopePaths);
377
+ assertCompatibleManifests(current, target, scope);
378
+ const expected = await this.computePlan(current, target, scope, [...scope]);
345
379
  if (expected.planDigest !== cached.planDigest) return false;
346
380
  }
347
- const topology = await this.discovery.discover(this.workspaceRoot, "safety-snapshot");
348
- this.assertCurrentTopology(current, target, topology);
381
+ // 这里只验证 durable pack 对应的 scope 源文件;完整 topology 校验由 apply
382
+ // 的 restore-pre 阶段负责。若在这里再次 discover,成功路径会为同一个操作
383
+ // 做两次全量目录扫描,而 apply 仍必须在真正 mutation 前重新确认 topology。
349
384
  const native = await createNativeFileBatch({
350
385
  workspaceRoot: this.workspaceRoot,
351
386
  planDigest: cached.planDigest,
@@ -372,6 +407,48 @@ export class RestoreEngine {
372
407
  }
373
408
  }
374
409
 
410
+ /**
411
+ * durable pack 尚未完成时,尝试直接证明当前 workspace 就是 rollback source。
412
+ * 只核验本次 restore scope 的叶子,不扫描整个 workspace;完整 topology 与可见路径
413
+ * 仍由 apply 的 restore-pre/visible-pre 在真正 mutation 前复核。
414
+ */
415
+ async canReuseManifestSource(
416
+ current: SnapshotManifest,
417
+ target: SnapshotManifest,
418
+ scopePaths: readonly string[],
419
+ ): Promise<boolean> {
420
+ try {
421
+ assertManifest(current);
422
+ assertManifest(target);
423
+ if (await this.assertWorkspaceRootIdentity() !== current.workspaceIdentity) return false;
424
+ const scope = [...this.canonicalScope(scopePaths)];
425
+ assertCompatibleManifests(current, target, new Set(scope));
426
+ const prepared = this.findPreparedPlan(current.manifestId, target.manifestId, scope);
427
+ const currentPaths = prepared === undefined
428
+ ? await this.readOwnedPaths(current, scope)
429
+ : prepared.currentPaths;
430
+ for (const path of scope) {
431
+ if (path === "." || currentPaths.get(path)?.entry.kind === "directory") {
432
+ // 目录 scope 不能由单个 lstat 证明全部 rollback 内容,继续走 scoped capture。
433
+ return false;
434
+ }
435
+ }
436
+ const matches = await mapConcurrentOrdered(scope, RESTORE_FILE_VERIFY_CONCURRENCY, async (path) => {
437
+ const owned = currentPaths.get(path);
438
+ if (owned === undefined) {
439
+ await assertNoSymlinkEscape(this.workspaceRoot, path);
440
+ return this.pathIsAbsent(path);
441
+ }
442
+ await this.verifyEntry(current.manifestId, owned);
443
+ return true;
444
+ });
445
+ return matches.every(Boolean);
446
+ } catch (error) {
447
+ rethrowOperationFailure(error);
448
+ return false;
449
+ }
450
+ }
451
+
375
452
  async prepareDurableRestore(
376
453
  current: SnapshotManifest,
377
454
  target: SnapshotManifest,
@@ -382,7 +459,11 @@ export class RestoreEngine {
382
459
  const plan = await this.plan(current, target, scopePaths, options);
383
460
  const prepared = this.takePreparedPlan(plan);
384
461
  reportDurablePackTiming(options, "prepare.plan", started);
385
- if (prepared === undefined || !this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
462
+ if (prepared === undefined) return;
463
+ // durable pack 的 blob 读取和编码可能持续一段时间;保留已完成的 plan/path 表,
464
+ // 让用户在此窗口触发 undo 时复用前序准备结果,而不是重新 listTree。
465
+ this.rememberPreparedPlan(plan, prepared.currentPaths, prepared.targetPaths);
466
+ if (!this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
386
467
  const cacheRoot = await this.store.durableCacheDirectory();
387
468
  const cacheOpId = `cache-${plan.planDigest}`;
388
469
  const cacheJournal = new MutationJournal(
@@ -393,6 +474,8 @@ export class RestoreEngine {
393
474
  const pack = await createDurablePack(cacheJournal, {
394
475
  opId: cacheOpId,
395
476
  planDigest: plan.planDigest,
477
+ // durablePackEntries 的 blob 是本次操作独占的 store 读取结果,可转移所有权。
478
+ payloadOwnership: "transfer",
396
479
  entries: await this.durablePackEntries(
397
480
  current,
398
481
  target,
@@ -672,6 +755,26 @@ export class RestoreEngine {
672
755
  return this.durablePackCacheMaxBytes + 1;
673
756
  }
674
757
 
758
+ private findPreparedPlan(
759
+ currentManifestId: ManifestId,
760
+ targetManifestId: ManifestId,
761
+ scopePaths: readonly string[],
762
+ ): PreparedRestorePlan | undefined {
763
+ const canonicalScope = [...new Set(scopePaths)].sort(comparePaths);
764
+ for (const prepared of this.preparedPlans.values()) {
765
+ const candidate = prepared.plan;
766
+ if (
767
+ candidate.currentManifestId !== currentManifestId ||
768
+ candidate.targetManifestId !== targetManifestId ||
769
+ candidate.scopePaths === undefined ||
770
+ candidate.scopePaths.length !== canonicalScope.length ||
771
+ candidate.scopePaths.some((path, index) => path !== canonicalScope[index])
772
+ ) continue;
773
+ return prepared;
774
+ }
775
+ return undefined;
776
+ }
777
+
675
778
  private rememberPreparedPlan(
676
779
  plan: RestorePlan,
677
780
  currentPaths: ReadonlyMap<string, OwnedPath>,
@@ -864,24 +967,24 @@ export class RestoreEngine {
864
967
  return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
865
968
  }
866
969
  const t1 = performance.now();
867
- try {
868
- // 兼容恢复路径会先在此窗口内补偿 pending mutations,因此只有非补偿路径可以跳过枚举入口的重复发现。
869
- await this.assertCompleteVisibleSubset(
870
- topologyBefore,
871
- [current, target],
872
- options.mutationJournal,
873
- {
874
- topologyValidated: !compatibilityMode,
875
- scopePaths: plan.scopePaths,
876
- ownedPaths: [currentPaths, targetPaths],
877
- },
878
- );
879
- } catch (error) {
880
- rethrowOperationFailure(error);
881
- return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
882
- } finally {
883
- reportRestoreTiming(options.onTiming, "apply.visiblePre", t1);
884
- }
970
+ const visiblePreflight = this.assertCompleteVisibleSubset(
971
+ topologyBefore,
972
+ [current, target],
973
+ options.mutationJournal,
974
+ {
975
+ topologyValidated: !compatibilityMode,
976
+ // Pi runtime 持有 workspace 独占锁;restore-post 仍会复核 topology。
977
+ skipPostTopologyCheck: options.workspaceLockHeld === true,
978
+ scopePaths: plan.scopePaths,
979
+ ownedPaths: [currentPaths, targetPaths],
980
+ },
981
+ ).then(
982
+ () => true,
983
+ (error: unknown) => {
984
+ rethrowOperationFailure(error);
985
+ return false;
986
+ },
987
+ ).finally(() => reportRestoreTiming(options.onTiming, "apply.visiblePre", t1));
885
988
  let durablePack: DurablePack | undefined;
886
989
  if (
887
990
  !compatibilityMode &&
@@ -919,6 +1022,8 @@ export class RestoreEngine {
919
1022
  durablePack = await createDurablePack(options.mutationJournal, {
920
1023
  opId: options.opId,
921
1024
  planDigest: plan.planDigest,
1025
+ // 同上:这里的 entries 只属于本次 pack,写入后不再被其他调用方使用。
1026
+ payloadOwnership: "transfer",
922
1027
  entries: await this.durablePackEntries(current, target, currentPaths, targetPaths, plan, options.opId),
923
1028
  });
924
1029
  }
@@ -940,6 +1045,9 @@ export class RestoreEngine {
940
1045
  durablePack = undefined;
941
1046
  }
942
1047
  if (pinsDeferred && durablePack === undefined) {
1048
+ if (!await visiblePreflight) {
1049
+ return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
1050
+ }
943
1051
  return this.applyWithOptions(
944
1052
  plan,
945
1053
  target,
@@ -952,6 +1060,9 @@ export class RestoreEngine {
952
1060
  nativeFileBatch !== undefined && durablePack !== undefined &&
953
1061
  this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
954
1062
  ) {
1063
+ if (!await visiblePreflight) {
1064
+ return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
1065
+ }
955
1066
  const result = await this.applyNativeFilePlan(
956
1067
  plan, current, target, currentPaths, targetPaths, topologyBefore, options, durablePack, nativeFileBatch.run,
957
1068
  );
@@ -966,14 +1077,18 @@ export class RestoreEngine {
966
1077
  } finally {
967
1078
  reportRestoreTiming(options.onTiming, "apply.prefetch", t2);
968
1079
  }
1080
+ const mutationIndex = new MutationPathIndex(plan.deletePaths, plan.writePaths);
969
1081
  const reusableTargetPaths = new Set(
970
- [...targetPaths.keys()].filter((path) => !isPathAffectedByMutations(path, plan.deletePaths, plan.writePaths)),
1082
+ [...targetPaths.keys()].filter((path) => !mutationIndex.affects(path)),
971
1083
  );
972
1084
  const t3 = performance.now();
973
- const preflight = await this.verifyKnownState(
1085
+ const preflightPromise = this.verifyKnownState(
974
1086
  current, target, currentPaths, targetPaths, plan.scopePaths, reusableTargetPaths,
975
- );
976
- reportRestoreTiming(options.onTiming, "apply.preflight", t3);
1087
+ ).finally(() => reportRestoreTiming(options.onTiming, "apply.preflight", t3));
1088
+ const [visiblePathsValid, preflight] = await allCompleted([visiblePreflight, preflightPromise]);
1089
+ if (!visiblePathsValid) {
1090
+ return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
1091
+ }
977
1092
  if (!preflight.ok) {
978
1093
  return {
979
1094
  code: "restore_failed_safe",
@@ -2213,16 +2328,6 @@ function entriesEquivalent(left: OwnedPath | undefined, right: OwnedPath): boole
2213
2328
  return left !== undefined && sameEntry(left.entry, right.entry);
2214
2329
  }
2215
2330
 
2216
- function isPathAffectedByMutations(
2217
- path: string,
2218
- deletePaths: readonly string[],
2219
- writePaths: readonly string[],
2220
- ): boolean {
2221
- return [...deletePaths, ...writePaths].some((mutationPath) =>
2222
- mutationPath === path || mutationPath.startsWith(`${path}/`) || path.startsWith(`${mutationPath}/`),
2223
- );
2224
- }
2225
-
2226
2331
  function entryFingerprint(owned: OwnedPath): string {
2227
2332
  const path = owned.absolutePath;
2228
2333
  if (owned.entry.kind === "directory") {
@@ -2405,17 +2510,20 @@ class IgnoredProofIndex {
2405
2510
  if (this.exact.size === 0) return false;
2406
2511
  // 排序成本只在第一次目录判定时付出,纯文件计划完全不触发。
2407
2512
  this.sortedPaths ??= [...this.exact].sort();
2408
- const sorted = this.sortedPaths;
2409
- const prefix = `${path}/`;
2410
- let low = 0;
2411
- let high = sorted.length;
2412
- while (low < high) {
2413
- const middle = (low + high) >>> 1;
2414
- if (sorted[middle]! < prefix) low = middle + 1;
2415
- else high = middle;
2416
- }
2417
- return low < sorted.length && sorted[low]!.startsWith(prefix);
2513
+ return sortedStartsWith(this.sortedPaths, `${path}/`);
2514
+ }
2515
+ }
2516
+
2517
+ /** 排序数组中第一个以 prefix 开头的项;相同逻辑供 ignored proof 与 mutation 索引复用。 */
2518
+ function sortedStartsWith(sorted: readonly string[], prefix: string): boolean {
2519
+ let low = 0;
2520
+ let high = sorted.length;
2521
+ while (low < high) {
2522
+ const middle = (low + high) >>> 1;
2523
+ if (sorted[middle]! < prefix) low = middle + 1;
2524
+ else high = middle;
2418
2525
  }
2526
+ return low < sorted.length && sorted[low]!.startsWith(prefix);
2419
2527
  }
2420
2528
 
2421
2529
  function rootBoundaryDirectories(root: string): string[] {