@davideasden/pi-undo 0.2.28 → 0.2.30

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.
@@ -2,6 +2,16 @@
2
2
 
3
3
  本轮实现目录项缓存与 scoped restore 的可见路径检查,保留恢复前后的拓扑校验。目录扫描仍会逐个打开、核验工作区内的目录;缓存减少 `readdir`,没有把整次检查变成只访问 changedPaths 的增量操作。
4
4
 
5
+ ## 性能诊断与批次调优
6
+
7
+ metadata inspect 默认每批最多处理 2,048 条路径,并受 1 MiB 路径请求字节上限约束。可使用 `PI_UNDO_METADATA_BATCH_MAX_PATHS=4096` 或 `8192` 做受控基准测试;有效范围为 1 到 8,192,超出范围会拒绝本次 capture。路径字节上限不会被环境变量覆盖,用于限制长路径工作区的单批请求规模。
8
+
9
+ 操作诊断文件中的 native helper 现在按 `native:scan-directories`、`native:metadata-inspect`、`native:restore` 等稳定标签区分,并记录捕获到的输出字节数。诊断仍不记录路径、请求内容或 helper 输出正文,可用于比较 helper 启动次数、耗时和输出规模。
10
+
11
+ 当前实现仍为“一批一个 helper 进程”;本轮没有引入常驻 helper 或多请求协议。只有在批次调优数据确认进程启动成本占主要比例后,才进入协议改造。
12
+
13
+ 在本机 macOS arm64、Node 23.11.1、10,000 个依赖包且修改 1 个文件的 SDK 基准中,默认 2,048 批次三次耗时为 `[2437, 2440, 2426]` ms,中位数 `2437 ms`;设置 4,096 批次后三次为 `[2425, 2438, 2432]` ms,中位数 `2432 ms`。差异约 `0.2%`,低于该基准的运行波动,因此没有把默认批次提高到 4,096。两组扫描次数都为 `[5, 5, 5]`,峰值 RSS 分别为约 `260 MiB` 和 `279 MiB`;RSS 未显示出提高批次上限的收益。
14
+
5
15
  ## 实现与边界
6
16
 
7
17
  - `scan-directories-v2` 在 macOS/Linux 上缓存每个目录的 `dev/ino/mtime/ctime`、Git 标记和直接子目录。每次检查仍核验全部目录的身份与时间戳,匹配时才复用目录项。检查点之间发生变化的目录重新枚举;扫描期间发生变化则显式失败,不接受部分结果。
Binary file
Binary file
Binary file
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davideasden/pi-undo",
3
- "version": "0.2.28",
3
+ "version": "0.2.30",
4
4
  "description": "Persistent workspace undo and redo for Pi",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/controller.ts CHANGED
@@ -18,6 +18,8 @@ import type {
18
18
  } from "./model.ts";
19
19
  import type { RestorePlan, RestoreResult } from "./restore-engine.ts";
20
20
 
21
+ const INPUT_CAPTURE_RETRY_DELAY_MS = 250;
22
+
21
23
  /** 控制器所需的最小运行时适配层;Pi 绑定在 extension 中完成。 */
22
24
  export interface ControllerDependencies {
23
25
  readonly workspaceIdentity: string;
@@ -483,9 +485,18 @@ export class UndoControllerImpl implements UndoController {
483
485
  if (warmUp !== undefined) await warmUp;
484
486
  const warmUpManifest = this.warmUpManifest;
485
487
  this.warmUpManifest = undefined;
486
- return warmUpManifest !== undefined && this.dependencies.captureBaseline !== undefined
488
+ const capture = (): Promise<SnapshotManifest> => warmUpManifest !== undefined && this.dependencies.captureBaseline !== undefined
487
489
  ? this.captureBaselineWithWorkspaceLock(warmUpManifest)
488
490
  : this.captureWithWorkspaceLock();
491
+ try {
492
+ return await capture();
493
+ } catch (error) {
494
+ // 输入前捕获也可能撞上短暂的工作区竞态;重试一次后仍失败才放弃本轮历史。
495
+ if (!isTransientCaptureFailure(error)) throw error;
496
+ await sleep(INPUT_CAPTURE_RETRY_DELAY_MS);
497
+ checkOperation();
498
+ return capture();
499
+ }
489
500
  }
490
501
 
491
502
  private async captureInputForToken(text: string, token: symbol): Promise<void> {
package/src/git-runner.ts CHANGED
@@ -67,7 +67,7 @@ export class GitRunner {
67
67
  let outcome = "failed";
68
68
  let exitCode: number | null = null;
69
69
  try {
70
- const result = await this.runCommand(args, options);
70
+ const result = await this.runCommand(args, options, command);
71
71
  outcome = result.timedOut ? "timeout" : result.aborted ? "cancelled" : "exit";
72
72
  exitCode = result.code;
73
73
  return result;
@@ -82,7 +82,7 @@ export class GitRunner {
82
82
  }
83
83
  }
84
84
 
85
- private async runCommand(args: readonly string[], options: GitRunOptions): Promise<GitRunResult> {
85
+ private async runCommand(args: readonly string[], options: GitRunOptions, command: string): Promise<GitRunResult> {
86
86
  const stderrLimit = options.stderrLimit ?? DEFAULT_STDERR_LIMIT;
87
87
  if (!Number.isInteger(stderrLimit) || stderrLimit < 0) {
88
88
  throw new RangeError("stderrLimit 必须是非负整数");
@@ -212,7 +212,11 @@ export class GitRunner {
212
212
  return;
213
213
  }
214
214
  if (!killed && exit.code !== 0) {
215
- reject(new GitRunError("git_failed", `git 退出码为 ${String(exit.code)}`, result));
215
+ reject(new GitRunError(
216
+ "git_failed",
217
+ formatGitFailure(command, exit.code, result.stderr),
218
+ result,
219
+ ));
216
220
  return;
217
221
  }
218
222
  resolve(result);
@@ -380,6 +384,8 @@ export interface SupervisedProcessRequest {
380
384
  readonly signal?: AbortSignal;
381
385
  readonly timeoutMs: number;
382
386
  readonly outputLimitBytes: number;
387
+ /** 仅用于诊断的稳定命令标签,不包含路径或其他敏感参数。 */
388
+ readonly diagnosticCommand?: string;
383
389
  /** 输出超过限制时:truncate 只停止捕获,terminate 先终止进程组。 */
384
390
  readonly outputOverflow?: "truncate" | "terminate";
385
391
  }
@@ -401,13 +407,21 @@ export async function runSupervisedProcess(request: SupervisedProcessRequest): P
401
407
  const started = performance.now();
402
408
  let outcome = "failed";
403
409
  let exitCode: number | null = null;
410
+ let outputBytes: number | undefined;
404
411
  try {
405
412
  const result = await superviseProcess(request);
413
+ outputBytes = result.stdout.byteLength + result.stderr.byteLength;
406
414
  outcome = result.stopped ? result.outcome : "process_exit_unconfirmed";
407
415
  exitCode = result.code;
408
416
  return result;
409
417
  } finally {
410
- reportProcessDiagnostic({ command: "native-helper", durationMs: Math.round(performance.now() - started), outcome, exitCode });
418
+ reportProcessDiagnostic({
419
+ command: request.diagnosticCommand ?? "native-helper",
420
+ durationMs: Math.round(performance.now() - started),
421
+ outcome,
422
+ exitCode,
423
+ ...(outputBytes === undefined ? {} : { outputBytes }),
424
+ });
411
425
  }
412
426
  }
413
427
 
@@ -600,6 +614,15 @@ function mergeEnvironment(overrides: Readonly<Record<string, string | undefined>
600
614
  return environment;
601
615
  }
602
616
 
617
+ function formatGitFailure(command: string, code: number | null, stderr: string): string {
618
+ const detail = stderr
619
+ .replace(/[\u0000-\u001F\u007F]+/g, " ")
620
+ .replace(/\s+/g, " ")
621
+ .trim()
622
+ .slice(0, 512);
623
+ return `${command} 退出码为 ${String(code)}${detail.length === 0 ? "" : `: ${detail}`}`;
624
+ }
625
+
603
626
  function errorMessage(error: unknown): string {
604
627
  return error instanceof Error ? error.message : String(error);
605
628
  }
@@ -15,6 +15,7 @@ export async function probeNativeCapabilities(
15
15
  ...budget,
16
16
  outputLimitBytes: 64 * 1024,
17
17
  outputOverflow: "terminate",
18
+ diagnosticCommand: "native:capabilities",
18
19
  });
19
20
  if (!result.stopped) throw new GitRunError("git_termination_failed", "native 能力探测进程未能确认终止");
20
21
  if (result.outcome === "cancelled") {
@@ -84,6 +84,7 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
84
84
  ...budget,
85
85
  outputLimitBytes: 32 * 1024 * 1024,
86
86
  outputOverflow: "terminate",
87
+ diagnosticCommand: "native:scan-directories",
87
88
  });
88
89
  if (!result.stopped) throw new GitRunError("git_termination_failed", "native 目录扫描进程未能确认终止");
89
90
  if (result.outcome === "cancelled") {
@@ -11,6 +11,14 @@ const NATIVE_INSPECT_TIMEOUT_MS = 30_000;
11
11
  const NATIVE_INSPECT_OUTPUT_LIMIT = 32 * 1024 * 1024;
12
12
  const NATIVE_PROBE_TIMEOUT_MS = 5_000;
13
13
  const NATIVE_PROBE_OUTPUT_LIMIT = 64 * 1024;
14
+ const NATIVE_INSPECT_BATCHES_MAX_BATCHES = 32;
15
+ const NATIVE_INSPECT_BATCHES_MAX_PATHS = 16_384;
16
+ const NATIVE_INSPECT_BATCHES_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
17
+
18
+ interface NativeCapabilities {
19
+ readonly inspect: boolean;
20
+ readonly inspectBatches: boolean;
21
+ }
14
22
 
15
23
  export interface NativeMetadataEntry {
16
24
  readonly path: string;
@@ -29,12 +37,17 @@ export interface NativeMetadataPort {
29
37
  paths: readonly string[],
30
38
  requestDirectory: string,
31
39
  ): Promise<readonly NativeMetadataEntry[] | undefined>;
40
+ inspectBatches?(
41
+ workspaceRoot: string,
42
+ batches: readonly (readonly string[])[],
43
+ requestDirectory: string,
44
+ ): Promise<readonly (readonly NativeMetadataEntry[])[] | undefined>;
32
45
  }
33
46
 
34
47
  /** 能力探测不支持时回退 TypeScript;已确认支持后的 inspect 错误保持 fail-closed。 */
35
48
  export class NativeMetadataInspector implements NativeMetadataPort {
36
49
  private readonly executable: string | undefined;
37
- private capability: Promise<boolean> | undefined;
50
+ private capability: Promise<NativeCapabilities> | undefined;
38
51
 
39
52
  constructor(executable = nativeExecutable()) {
40
53
  this.executable = process.env.PI_UNDO_DISABLE_NATIVE === "1" ? undefined : executable;
@@ -48,7 +61,8 @@ export class NativeMetadataInspector implements NativeMetadataPort {
48
61
  if (paths.length === 0) return [];
49
62
  // 已取消/超时的操作不启动新的 helper,也不写出请求文件。
50
63
  const budget = operationProcessOptions(NATIVE_INSPECT_TIMEOUT_MS);
51
- if (!await this.supportsInspect(requestDirectory)) return undefined;
64
+ const capabilities = await this.nativeCapabilities(requestDirectory);
65
+ if (!capabilities.inspect) return undefined;
52
66
  const executable = this.executable!;
53
67
  const requestPath = join(requestDirectory, `native-inspect-${process.pid}-${randomUUID()}.json`);
54
68
  try {
@@ -63,22 +77,55 @@ export class NativeMetadataInspector implements NativeMetadataPort {
63
77
  }
64
78
  }
65
79
 
66
- private supportsInspect(requestDirectory: string): Promise<boolean> {
80
+
81
+ async inspectBatches(
82
+ workspaceRoot: string,
83
+ batches: readonly (readonly string[])[],
84
+ requestDirectory: string,
85
+ ): Promise<readonly (readonly NativeMetadataEntry[])[] | undefined> {
86
+ if (batches.length === 0) return [];
87
+ const totalPaths = batches.reduce((total, batch) => total + batch.length, 0);
88
+ if (
89
+ batches.length > NATIVE_INSPECT_BATCHES_MAX_BATCHES ||
90
+ totalPaths > NATIVE_INSPECT_BATCHES_MAX_PATHS
91
+ ) {
92
+ throw new Error("native metadata inspect batches 请求超出限制");
93
+ }
94
+ const requestBytes = Buffer.byteLength(JSON.stringify({ schemaVersion: 1, workspaceRoot, batches }), "utf8");
95
+ if (requestBytes > NATIVE_INSPECT_BATCHES_MAX_REQUEST_BYTES) {
96
+ throw new Error("native metadata inspect batches 请求字节数超出限制");
97
+ }
98
+ const budget = operationProcessOptions(NATIVE_INSPECT_TIMEOUT_MS);
99
+ const capabilities = await this.nativeCapabilities(requestDirectory);
100
+ if (!capabilities.inspectBatches) return undefined;
101
+ const executable = this.executable!;
102
+ const requestPath = join(requestDirectory, `native-inspect-batches-${process.pid}-${randomUUID()}.json`);
103
+ try {
104
+ await writeFile(requestPath, JSON.stringify({ schemaVersion: 1, workspaceRoot, batches }), {
105
+ mode: 0o600,
106
+ flag: "wx",
107
+ });
108
+ return await runNativeInspectBatches(executable, requestPath, batches, budget);
109
+ } finally {
110
+ await rm(requestPath, { force: true }).catch(() => {});
111
+ }
112
+ }
113
+ private nativeCapabilities(requestDirectory: string): Promise<NativeCapabilities> {
67
114
  if (this.capability !== undefined) return this.capability;
68
115
  this.capability = (async () => {
69
- if (this.executable === undefined) return false;
116
+ if (this.executable === undefined) return { inspect: false, inspectBatches: false };
70
117
  try {
71
118
  await access(this.executable, constants.X_OK);
72
- return await probeNativeInspect(this.executable, requestDirectory);
119
+ return await probeNativeCapabilities(this.executable, requestDirectory);
73
120
  } catch {
74
- return false;
121
+ return { inspect: false, inspectBatches: false };
75
122
  }
76
123
  })();
77
124
  return this.capability;
78
125
  }
79
126
  }
80
127
 
81
- async function probeNativeInspect(executable: string, isolatedDirectory: string): Promise<boolean> {
128
+ async function probeNativeCapabilities(executable: string, isolatedDirectory: string): Promise<NativeCapabilities> {
82
129
  try {
83
130
  const result = await runSupervisedProcess({
84
131
  command: executable,
@@ -87,13 +134,21 @@ async function probeNativeInspect(executable: string, isolatedDirectory: string)
87
134
  timeoutMs: NATIVE_PROBE_TIMEOUT_MS,
88
135
  outputLimitBytes: NATIVE_PROBE_OUTPUT_LIMIT,
89
136
  outputOverflow: "terminate",
137
+ diagnosticCommand: "native:metadata-capabilities",
90
138
  });
91
- if (!result.stopped || result.outcome !== "exit" || result.code !== 0) return false;
139
+ if (!result.stopped || result.outcome !== "exit" || result.code !== 0) {
140
+ return { inspect: false, inspectBatches: false };
141
+ }
92
142
  const value: unknown = JSON.parse(result.stdout.toString("utf8"));
93
- return isRecord(value) && value.ok === true && Array.isArray(value.capabilities) &&
94
- value.capabilities.includes("inspect-v1");
143
+ if (!isRecord(value) || value.ok !== true || !Array.isArray(value.capabilities)) {
144
+ return { inspect: false, inspectBatches: false };
145
+ }
146
+ return {
147
+ inspect: value.capabilities.includes("inspect-v1"),
148
+ inspectBatches: value.capabilities.includes("inspect-batches-v1"),
149
+ };
95
150
  } catch {
96
- return false;
151
+ return { inspect: false, inspectBatches: false };
97
152
  }
98
153
  }
99
154
 
@@ -110,6 +165,7 @@ async function runNativeInspect(
110
165
  timeoutMs: budget.timeoutMs,
111
166
  outputLimitBytes: NATIVE_INSPECT_OUTPUT_LIMIT,
112
167
  outputOverflow: "terminate",
168
+ diagnosticCommand: "native:metadata-inspect",
113
169
  });
114
170
  if (!result.stopped) {
115
171
  throw new GitRunError("git_termination_failed", "native metadata inspect 进程未能确认终止");
@@ -129,13 +185,74 @@ async function runNativeInspect(
129
185
  return parseInspectResponse(result.stdout.toString("utf8"), expectedPaths);
130
186
  }
131
187
 
188
+ async function runNativeInspectBatches(
189
+ executable: string,
190
+ requestPath: string,
191
+ expectedBatches: readonly (readonly string[])[],
192
+ budget: OperationProcessOptions,
193
+ ): Promise<readonly (readonly NativeMetadataEntry[])[]> {
194
+ const result = await runSupervisedProcess({
195
+ command: executable,
196
+ args: ["--inspect-batches", requestPath],
197
+ signal: budget.signal,
198
+ timeoutMs: budget.timeoutMs,
199
+ outputLimitBytes: NATIVE_INSPECT_OUTPUT_LIMIT,
200
+ outputOverflow: "terminate",
201
+ diagnosticCommand: "native:metadata-inspect-batches",
202
+ });
203
+ if (!result.stopped) {
204
+ throw new GitRunError("git_termination_failed", "native metadata inspect batches 进程未能确认终止");
205
+ }
206
+ if (result.outcome === "cancelled") {
207
+ throw new OperationError("operation_cancelled", "native metadata inspect batches 已被取消");
208
+ }
209
+ if (result.outcome === "timeout") {
210
+ throw new OperationError("operation_timeout", "native metadata inspect batches 超时");
211
+ }
212
+ if (result.outcome === "output_overflow") {
213
+ throw new Error("native metadata inspect batches 输出超过限制");
214
+ }
215
+ if (result.code !== 0) {
216
+ throw new Error(`native metadata inspect batches 失败:${result.stderr.toString("utf8").trim()}`);
217
+ }
218
+ return parseInspectBatchesResponse(result.stdout.toString("utf8"), expectedBatches);
219
+ }
220
+
132
221
  function parseInspectResponse(text: string, expectedPaths: readonly string[]): readonly NativeMetadataEntry[] {
133
222
  const value: unknown = JSON.parse(text);
134
223
  if (!isRecord(value) || value.ok !== true || value.processed !== expectedPaths.length || !Array.isArray(value.entries)) {
135
224
  throw new Error("native metadata inspect 响应无效");
136
225
  }
137
- if (value.entries.length !== expectedPaths.length) throw new Error("native metadata inspect 条目数量不匹配");
138
- return value.entries.map((candidate, index) => {
226
+ return parseInspectEntries(value.entries, expectedPaths);
227
+ }
228
+
229
+ function parseInspectBatchesResponse(
230
+ text: string,
231
+ expectedBatches: readonly (readonly string[])[],
232
+ ): readonly (readonly NativeMetadataEntry[])[] {
233
+ const value: unknown = JSON.parse(text);
234
+ const expectedTotal = expectedBatches.reduce((total, batch) => total + batch.length, 0);
235
+ if (!isRecord(value) || value.ok !== true || value.processed !== expectedTotal || !Array.isArray(value.batches)) {
236
+ throw new Error("native metadata inspect batches 响应无效");
237
+ }
238
+ if (value.batches.length !== expectedBatches.length) {
239
+ throw new Error("native metadata inspect batches 数量不匹配");
240
+ }
241
+ return value.batches.map((candidate, index) => {
242
+ const expectedPaths = expectedBatches[index]!;
243
+ if (!isRecord(candidate) || candidate.processed !== expectedPaths.length || !Array.isArray(candidate.entries)) {
244
+ throw new Error("native metadata inspect batch 响应无效");
245
+ }
246
+ return parseInspectEntries(candidate.entries, expectedPaths);
247
+ });
248
+ }
249
+
250
+ function parseInspectEntries(
251
+ entries: readonly unknown[],
252
+ expectedPaths: readonly string[],
253
+ ): readonly NativeMetadataEntry[] {
254
+ if (entries.length !== expectedPaths.length) throw new Error("native metadata inspect 条目数量不匹配");
255
+ return entries.map((candidate, index) => {
139
256
  if (!isRecord(candidate) || candidate.path !== expectedPaths[index] ||
140
257
  !isMetadataKind(candidate.kind)) {
141
258
  throw new Error("native metadata inspect 条目无效");
@@ -120,6 +120,8 @@ async function runNative(
120
120
  signal: budget.signal,
121
121
  timeoutMs: budget.timeoutMs,
122
122
  outputLimitBytes: NATIVE_OUTPUT_LIMIT,
123
+ outputOverflow: "terminate",
124
+ diagnosticCommand: "native:restore",
123
125
  });
124
126
  if (!result.stopped) {
125
127
  // 无法证明 helper 已停止:保留 lease,让上层走恢复流程。
@@ -11,6 +11,7 @@ export interface ProcessDiagnostic {
11
11
  readonly durationMs: number;
12
12
  readonly outcome: string;
13
13
  readonly exitCode: number | null;
14
+ readonly outputBytes?: number;
14
15
  }
15
16
 
16
17
  export interface OperationContext {
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import type { BigIntStats } from "node:fs";
2
3
  import { realpathSync } from "node:fs";
3
4
  import { lstat, mkdir, mkdtemp, readFile, readlink, realpath, rm, rmdir } from "node:fs/promises";
4
5
  import { tmpdir } from "node:os";
@@ -99,6 +100,22 @@ interface OwnedPath {
99
100
  readonly root: SnapshotRoot;
100
101
  }
101
102
 
103
+ interface PathAttestation {
104
+ readonly fingerprint: string;
105
+ readonly dev: bigint;
106
+ readonly ino: bigint;
107
+ readonly mode: bigint;
108
+ readonly size: bigint;
109
+ readonly mtimeNs: bigint;
110
+ readonly ctimeNs: bigint;
111
+ readonly linkText?: string;
112
+ }
113
+
114
+ interface EntryVerification {
115
+ readonly fingerprint: string;
116
+ readonly attestation: PathAttestation;
117
+ }
118
+
102
119
  interface VisibleSubsetCheck {
103
120
  /**
104
121
  * 调用方刚刚完成 topology discovery 且随后没有文件 mutation 时为 true,可跳过枚举入口的重复校验。
@@ -901,7 +918,17 @@ export class RestoreEngine {
901
918
  rethrowOperationFailure(error);
902
919
  // 预取是性能优化;失败时继续走原有逐文件校验和可恢复 mutation 路径。
903
920
  }
904
- const preflight = await this.verifyKnownState(current, target, currentPaths, targetPaths, plan.scopePaths);
921
+ const reusableTargetPaths = new Set(
922
+ [...targetPaths.keys()].filter((path) => !isPathAffectedByMutations(path, plan.deletePaths, plan.writePaths)),
923
+ );
924
+ const preflight = await this.verifyKnownState(
925
+ current,
926
+ target,
927
+ currentPaths,
928
+ targetPaths,
929
+ plan.scopePaths,
930
+ reusableTargetPaths,
931
+ );
905
932
  if (!preflight.ok) {
906
933
  return {
907
934
  code: "restore_failed_safe",
@@ -954,6 +981,7 @@ export class RestoreEngine {
954
981
  targetPaths,
955
982
  plan.deletePaths,
956
983
  plan.scopePaths,
984
+ preflight.targetAttestations,
957
985
  );
958
986
  const result: RestoreResult = {
959
987
  code: "ok",
@@ -1253,8 +1281,14 @@ export class RestoreEngine {
1253
1281
  target: SnapshotManifest,
1254
1282
  currentPaths: ReadonlyMap<string, OwnedPath>,
1255
1283
  targetPaths: ReadonlyMap<string, OwnedPath>,
1256
- scopePaths?: readonly string[],
1257
- ): Promise<{ ok: boolean; verifiedPaths: number; totalPaths: number }> {
1284
+ scopePaths: readonly string[] | undefined,
1285
+ reusableTargetPaths: ReadonlySet<string>,
1286
+ ): Promise<{
1287
+ ok: boolean;
1288
+ verifiedPaths: number;
1289
+ totalPaths: number;
1290
+ targetAttestations: ReadonlyMap<string, PathAttestation>;
1291
+ }> {
1258
1292
  const scope = scopePaths === undefined ? undefined : new Set(scopePaths);
1259
1293
  const paths = [...new Set([...currentPaths.keys(), ...targetPaths.keys()])]
1260
1294
  .filter((path) => scope === undefined || scope.has(path))
@@ -1264,18 +1298,43 @@ export class RestoreEngine {
1264
1298
  let stop = false;
1265
1299
  let failure: unknown;
1266
1300
  let failureIndex: number | undefined;
1301
+ const targetAttestations = new Map<string, PathAttestation>();
1267
1302
  const verifyPath = async (path: string): Promise<boolean> => {
1268
1303
  if (await this.pathIsShadowedByTarget(target.manifestId, path, targetPaths)) return true;
1269
1304
  const currentPath = currentPaths.get(path);
1270
1305
  const targetPath = targetPaths.get(path);
1271
- const matchesCurrent = currentPath !== undefined &&
1272
- await this.entryMatches(current.manifestId, currentPath);
1273
- const matchesTarget = !matchesCurrent && targetPath !== undefined &&
1274
- await this.entryMatches(target.manifestId, targetPath);
1275
- const matchesAbsentSide = !matchesCurrent && !matchesTarget &&
1306
+ let currentVerification: EntryVerification | undefined;
1307
+ if (currentPath !== undefined) {
1308
+ try {
1309
+ currentVerification = await this.verifyEntryWithAttestation(current.manifestId, currentPath);
1310
+ } catch {
1311
+ // current 不匹配时继续验证 target;保持 apply 前拒绝未知状态的语义。
1312
+ }
1313
+ }
1314
+ if (currentVerification !== undefined) {
1315
+ if (
1316
+ targetPath !== undefined && reusableTargetPaths.has(path) &&
1317
+ entriesEquivalent(currentPath!, targetPath)
1318
+ ) {
1319
+ targetAttestations.set(path, currentVerification.attestation);
1320
+ }
1321
+ return true;
1322
+ }
1323
+ if (targetPath !== undefined) {
1324
+ try {
1325
+ const targetVerification = await this.verifyEntryWithAttestation(target.manifestId, targetPath);
1326
+ if (reusableTargetPaths.has(path)) {
1327
+ targetAttestations.set(path, targetVerification.attestation);
1328
+ }
1329
+ return true;
1330
+ } catch {
1331
+ // 继续检查 absent side;若路径仍存在但内容未知,最终返回 false。
1332
+ }
1333
+ }
1334
+ const matchesAbsentSide =
1276
1335
  (currentPath === undefined || targetPath === undefined) &&
1277
1336
  await this.pathIsAbsent(path);
1278
- return matchesCurrent || matchesTarget || matchesAbsentSide;
1337
+ return matchesAbsentSide;
1279
1338
  };
1280
1339
  const worker = async (): Promise<void> => {
1281
1340
  while (!stop && nextIndex < paths.length) {
@@ -1303,14 +1362,24 @@ export class RestoreEngine {
1303
1362
  let verifiedPaths = 0;
1304
1363
  for (let index = 0; index < results.length; index += 1) {
1305
1364
  const ok = results[index];
1306
- if (ok === false) return { ok: false, verifiedPaths, totalPaths: paths.length };
1365
+ if (ok === false) return {
1366
+ ok: false,
1367
+ verifiedPaths,
1368
+ totalPaths: paths.length,
1369
+ targetAttestations,
1370
+ };
1307
1371
  if (ok === undefined) {
1308
1372
  if (failureIndex === index && failure !== undefined) throw failure;
1309
- return { ok: false, verifiedPaths, totalPaths: paths.length };
1373
+ return {
1374
+ ok: false,
1375
+ verifiedPaths,
1376
+ totalPaths: paths.length,
1377
+ targetAttestations,
1378
+ };
1310
1379
  }
1311
1380
  verifiedPaths += 1;
1312
1381
  }
1313
- return { ok: true, verifiedPaths, totalPaths: paths.length };
1382
+ return { ok: true, verifiedPaths, totalPaths: paths.length, targetAttestations };
1314
1383
  }
1315
1384
 
1316
1385
  private async deletePlannedPaths(
@@ -1823,13 +1892,14 @@ export class RestoreEngine {
1823
1892
  targetPaths: ReadonlyMap<string, OwnedPath>,
1824
1893
  deletePaths: readonly string[],
1825
1894
  scopePaths?: readonly string[],
1895
+ reusableAttestations: ReadonlyMap<string, PathAttestation> = new Map(),
1826
1896
  ): Promise<{ verifiedPaths: number; totalPaths: number; pathFingerprints: string[] }> {
1827
1897
  const scope = scopePaths === undefined ? undefined : new Set(scopePaths);
1828
1898
  const scopedTargets = [...targetPaths].filter(([path]) => scope === undefined || scope.has(path));
1829
1899
  const pathFingerprints = await mapConcurrentOrdered(
1830
1900
  scopedTargets,
1831
1901
  RESTORE_FILE_VERIFY_CONCURRENCY,
1832
- ([, owned]) => this.verifyEntry(target.manifestId, owned),
1902
+ ([path, owned]) => this.verifyTargetEntry(target.manifestId, owned, reusableAttestations.get(path)),
1833
1903
  );
1834
1904
  const remainingDeletes = deletePaths.filter((path) =>
1835
1905
  !targetPaths.has(path) &&
@@ -1934,26 +2004,46 @@ export class RestoreEngine {
1934
2004
  return false;
1935
2005
  }
1936
2006
 
2007
+ private async verifyTargetEntry(
2008
+ manifestId: ManifestId,
2009
+ owned: OwnedPath,
2010
+ attestation: PathAttestation | undefined,
2011
+ ): Promise<string> {
2012
+ if (attestation !== undefined && await this.matchesAttestation(owned, attestation)) {
2013
+ return attestation.fingerprint;
2014
+ }
2015
+ return (await this.verifyEntryWithAttestation(manifestId, owned)).fingerprint;
2016
+ }
2017
+
1937
2018
  private async verifyEntry(manifestId: ManifestId, owned: OwnedPath): Promise<string> {
2019
+ return (await this.verifyEntryWithAttestation(manifestId, owned)).fingerprint;
2020
+ }
2021
+
2022
+ private async verifyEntryWithAttestation(manifestId: ManifestId, owned: OwnedPath): Promise<EntryVerification> {
1938
2023
  const path = owned.absolutePath;
1939
2024
  await assertNoSymlinkEscape(this.workspaceRoot, path);
1940
- const metadata = await lstat(this.absolutePath(path));
2025
+ const metadata = await lstat(this.absolutePath(path), { bigint: true });
1941
2026
  if (owned.entry.kind === "directory") {
1942
2027
  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
1943
2028
  throw new Error(`目录类型校验失败:${path}`);
1944
2029
  }
1945
- return checksum(canonicalJson({ path, kind: "directory" }));
2030
+ return verifiedEntry(metadata, checksum(canonicalJson({ path, kind: "directory" })));
1946
2031
  }
1947
2032
  if (owned.entry.kind === "symlink") {
1948
- if (!metadata.isSymbolicLink() || await readlink(this.absolutePath(path)) !== owned.entry.linkText) {
2033
+ const linkText = await readlink(this.absolutePath(path));
2034
+ if (!metadata.isSymbolicLink() || linkText !== owned.entry.linkText) {
1949
2035
  throw new Error(`symlink 校验失败:${path}`);
1950
2036
  }
1951
- return checksum(canonicalJson({ path, kind: "symlink", linkText: owned.entry.linkText }));
2037
+ return verifiedEntry(
2038
+ metadata,
2039
+ checksum(canonicalJson({ path, kind: "symlink", linkText: owned.entry.linkText })),
2040
+ linkText,
2041
+ );
1952
2042
  }
1953
2043
  if (!metadata.isFile() || metadata.isSymbolicLink()) {
1954
2044
  throw new Error(`普通文件类型校验失败:${path}`);
1955
2045
  }
1956
- if ((metadata.mode & 0o111) !== (owned.entry.mode & 0o111)) {
2046
+ if ((metadata.mode & 0o111n) !== BigInt(owned.entry.mode & 0o111)) {
1957
2047
  throw new Error(`普通文件 mode 校验失败:${path}`);
1958
2048
  }
1959
2049
  if (owned.entry.blobId === null) {
@@ -1971,12 +2061,33 @@ export class RestoreEngine {
1971
2061
  if (!actual.equals(Buffer.from(expected))) {
1972
2062
  throw new Error(`普通文件内容校验失败:${path}`);
1973
2063
  }
1974
- return checksum(canonicalJson({
2064
+ return verifiedEntry(metadata, checksum(canonicalJson({
1975
2065
  path,
1976
2066
  kind: "file",
1977
2067
  mode: owned.entry.mode,
1978
2068
  blobId: owned.entry.blobId,
1979
- }));
2069
+ })));
2070
+ }
2071
+
2072
+ private async matchesAttestation(owned: OwnedPath, attestation: PathAttestation): Promise<boolean> {
2073
+ try {
2074
+ if (attestation.fingerprint !== entryFingerprint(owned)) return false;
2075
+ const path = owned.absolutePath;
2076
+ await assertNoSymlinkEscape(this.workspaceRoot, path);
2077
+ const metadata = await lstat(this.absolutePath(path), { bigint: true });
2078
+ if (
2079
+ metadata.dev !== attestation.dev || metadata.ino !== attestation.ino ||
2080
+ metadata.mode !== attestation.mode || metadata.size !== attestation.size ||
2081
+ metadata.mtimeNs !== attestation.mtimeNs || metadata.ctimeNs !== attestation.ctimeNs
2082
+ ) return false;
2083
+ if (owned.entry.kind === "directory") return metadata.isDirectory() && !metadata.isSymbolicLink();
2084
+ if (owned.entry.kind === "symlink") {
2085
+ return metadata.isSymbolicLink() && await readlink(this.absolutePath(path)) === attestation.linkText;
2086
+ }
2087
+ return metadata.isFile() && !metadata.isSymbolicLink();
2088
+ } catch {
2089
+ return false;
2090
+ }
1980
2091
  }
1981
2092
 
1982
2093
  private async assertMutationPath(path: string): Promise<void> {
@@ -2035,6 +2146,54 @@ function sameEntry(left: RestorePath, right: RestorePath): boolean {
2035
2146
  left.linkText === right.linkText;
2036
2147
  }
2037
2148
 
2149
+ function entriesEquivalent(left: OwnedPath | undefined, right: OwnedPath): boolean {
2150
+ return left !== undefined && sameEntry(left.entry, right.entry);
2151
+ }
2152
+
2153
+ function isPathAffectedByMutations(
2154
+ path: string,
2155
+ deletePaths: readonly string[],
2156
+ writePaths: readonly string[],
2157
+ ): boolean {
2158
+ return [...deletePaths, ...writePaths].some((mutationPath) =>
2159
+ mutationPath === path || mutationPath.startsWith(`${path}/`) || path.startsWith(`${mutationPath}/`),
2160
+ );
2161
+ }
2162
+
2163
+ function entryFingerprint(owned: OwnedPath): string {
2164
+ const path = owned.absolutePath;
2165
+ if (owned.entry.kind === "directory") {
2166
+ return checksum(canonicalJson({ path, kind: "directory" }));
2167
+ }
2168
+ if (owned.entry.kind === "symlink") {
2169
+ if (owned.entry.linkText === undefined) throw new Error(`symlink 缺少 linkText:${path}`);
2170
+ return checksum(canonicalJson({ path, kind: "symlink", linkText: owned.entry.linkText }));
2171
+ }
2172
+ if (owned.entry.blobId === null) throw new Error(`普通文件缺少 blob:${path}`);
2173
+ return checksum(canonicalJson({
2174
+ path,
2175
+ kind: "file",
2176
+ mode: owned.entry.mode,
2177
+ blobId: owned.entry.blobId,
2178
+ }));
2179
+ }
2180
+
2181
+ function verifiedEntry(metadata: BigIntStats, fingerprint: string, linkText?: string): EntryVerification {
2182
+ return {
2183
+ fingerprint,
2184
+ attestation: {
2185
+ fingerprint,
2186
+ dev: metadata.dev,
2187
+ ino: metadata.ino,
2188
+ mode: metadata.mode,
2189
+ size: metadata.size,
2190
+ mtimeNs: metadata.mtimeNs,
2191
+ ctimeNs: metadata.ctimeNs,
2192
+ ...(linkText === undefined ? {} : { linkText }),
2193
+ },
2194
+ };
2195
+ }
2196
+
2038
2197
  // sourceIdentity/privateRepositoryId 会随 git remote 配置漂移(例如后来补充 remote origin),
2039
2198
  // 它们是仓库元数据而非工作区内容;restore 的内容安全由逐文件校验
2040
2199
  // (verifyKnownState、assertCompleteVisibleSubset、verifyTarget)保证。
@@ -215,9 +215,31 @@ export class RootDiscovery {
215
215
  "--show-toplevel",
216
216
  "--git-dir",
217
217
  "--git-common-dir",
218
+ "HEAD",
218
219
  ]);
219
220
  if (details === null) {
220
- return { kind: "broken", absoluteRoot };
221
+ // unborn repository 没有 HEAD;保留旧行为:root 仍可作为 active,但 treeId 为空。
222
+ const metadata = await this.gitOutput([
223
+ "-C",
224
+ absoluteRoot,
225
+ "rev-parse",
226
+ "--show-toplevel",
227
+ "--git-dir",
228
+ "--git-common-dir",
229
+ ]);
230
+ if (metadata === null) return { kind: "broken", absoluteRoot };
231
+ const metadataLines = metadata.trimEnd().split("\n");
232
+ if (metadataLines.length < 3) return { kind: "broken", absoluteRoot };
233
+ const remote = await this.gitOutput(["-C", absoluteRoot, "config", "--get", "remote.origin.url"]);
234
+ return {
235
+ kind: "active",
236
+ repository: {
237
+ absoluteRoot,
238
+ commonGitDir: resolve(absoluteRoot, metadataLines[2]),
239
+ sourceIdentity: remote?.trim() || `git:${resolve(absoluteRoot, metadataLines[2])}`,
240
+ treeId: null,
241
+ },
242
+ };
221
243
  }
222
244
  const lines = details.trimEnd().split("\n");
223
245
  if (lines.length < 3) {
@@ -233,7 +255,7 @@ export class RootDiscovery {
233
255
 
234
256
  const commonGitDir = resolve(absoluteRoot, lines[2]);
235
257
  const remote = await this.gitOutput(["-C", absoluteRoot, "config", "--get", "remote.origin.url"]);
236
- const head = await this.gitOutput(["-C", absoluteRoot, "rev-parse", "HEAD"]);
258
+ const head = lines[3] !== undefined && /^[0-9a-f]{40,64}$/.test(lines[3]) ? lines[3] : null;
237
259
  return {
238
260
  kind: "active",
239
261
  repository: {
@@ -41,7 +41,12 @@ const HASH_BATCH_MAX_ARGUMENT_BYTES = process.platform === "win32" ? 24 * 1024 :
41
41
  const HASH_BATCH_CONCURRENCY = 4;
42
42
  const ROOT_CAPTURE_CONCURRENCY = 4;
43
43
  const FILE_SYSTEM_INSPECTION_CONCURRENCY = 32;
44
- const METADATA_BATCH_SIZE = 1_024;
44
+ const METADATA_BATCH_MAX_PATHS = 2_048;
45
+ const METADATA_BATCH_HARD_MAX_PATHS = 8_192;
46
+ const METADATA_BATCH_MAX_PATH_BYTES = 1 * 1024 * 1024;
47
+ const METADATA_BATCHES_MAX_BATCHES = 32;
48
+ const METADATA_BATCHES_MAX_PATHS = 16_384;
49
+ const METADATA_BATCHES_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
45
50
  const INDEX_BATCH_MAX_ENTRIES = 4_096;
46
51
  const INDEX_BATCH_MAX_BYTES = 8 * 1024 * 1024;
47
52
  const BLOB_CACHE_MAX_BYTES = 128 * 1024 * 1024;
@@ -720,15 +725,11 @@ export class SnapshotStore {
720
725
  const gitDirectory = this.rootGitDirectory(storeDirectory, root);
721
726
  try {
722
727
  const treeEntries = await this.readTreeEntries(gitDirectory, root.treeId, rootScopePaths);
723
- const directories = new Set<string>();
724
- for (const entry of treeEntries) {
725
- const parts = entry.relativePath.split("/");
726
- for (let index = 1; index < parts.length; index += 1) {
727
- directories.add(parts.slice(0, index).join("/"));
728
- }
729
- }
728
+ const directories = treeDirectoryPaths(treeEntries);
729
+ const symlinkEntries = treeEntries.filter((entry) => entry.mode === 0o120000);
730
+ if (symlinkEntries.length > 0) await this.preloadBlobBytes(gitDirectory, symlinkEntries);
730
731
 
731
- const result: RestorePath[] = [...directories].map((relativePath) => ({
732
+ const result: RestorePath[] = directories.map((relativePath) => ({
732
733
  relativePath,
733
734
  kind: "directory",
734
735
  mode: 0o755,
@@ -1114,9 +1115,30 @@ export class SnapshotStore {
1114
1115
  ): Promise<readonly NativeMetadataEntry[] | undefined> {
1115
1116
  // 空路径不得触发 native inspect;首批 unsupported 才整体回退,中途变化必须 fail closed。
1116
1117
  if (paths.length === 0) return [];
1118
+ const batches = metadataPathBatches(paths, configuredMetadataBatchMaxPaths());
1119
+ const inspectBatches = this.nativeMetadata.inspectBatches;
1120
+ if (inspectBatches !== undefined) {
1121
+ const groupedBatches = metadataInspectRequestGroups(batches, cwd);
1122
+ const groupedResult: NativeMetadataEntry[] = [];
1123
+ let usedGroupedProtocol = false;
1124
+ for (const group of groupedBatches) {
1125
+ const inspected = await inspectBatches.call(this.nativeMetadata, cwd, group, requestDirectory);
1126
+ if (inspected === undefined) {
1127
+ if (usedGroupedProtocol) {
1128
+ throw new SnapshotStoreError("capture_failed", "native metadata 批次协议在请求间变化");
1129
+ }
1130
+ break;
1131
+ }
1132
+ usedGroupedProtocol = true;
1133
+ if (inspected.length !== group.length || inspected.some((entries, index) => entries.length !== group[index]!.length)) {
1134
+ throw new SnapshotStoreError("capture_failed", "native metadata 批次响应数量不匹配");
1135
+ }
1136
+ for (const entries of inspected) groupedResult.push(...entries);
1137
+ }
1138
+ if (usedGroupedProtocol) return groupedResult;
1139
+ }
1117
1140
  const result: NativeMetadataEntry[] = [];
1118
- for (let offset = 0; offset < paths.length; offset += METADATA_BATCH_SIZE) {
1119
- const batch = paths.slice(offset, offset + METADATA_BATCH_SIZE);
1141
+ for (const batch of batches) {
1120
1142
  const inspected = await this.nativeMetadata.inspect(cwd, batch, requestDirectory);
1121
1143
  if (inspected === undefined) {
1122
1144
  if (result.length > 0) {
@@ -1134,8 +1156,7 @@ export class SnapshotStore {
1134
1156
  paths: readonly string[],
1135
1157
  ): Promise<readonly NativeMetadataEntry["kind"][]> {
1136
1158
  const result: NativeMetadataEntry["kind"][] = [];
1137
- for (let offset = 0; offset < paths.length; offset += METADATA_BATCH_SIZE) {
1138
- const batch = paths.slice(offset, offset + METADATA_BATCH_SIZE);
1159
+ for (const batch of metadataPathBatches(paths, configuredMetadataBatchMaxPaths())) {
1139
1160
  await assertNoSymlinkParents(cwd, batch);
1140
1161
  const kinds = await mapConcurrentOrdered(batch, FILE_SYSTEM_INSPECTION_CONCURRENCY, async (relativePath) => {
1141
1162
  const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
@@ -2293,6 +2314,67 @@ async function mapConcurrentOrdered<T, R>(
2293
2314
  return result;
2294
2315
  }
2295
2316
 
2317
+ function metadataPathBatches(paths: readonly string[], maxPaths: number): string[][] {
2318
+ const result: string[][] = [];
2319
+ let batch: string[] = [];
2320
+ let pathBytes = 0;
2321
+ for (const path of paths) {
2322
+ const nextPathBytes = Buffer.byteLength(path, "utf8") + 1;
2323
+ if (
2324
+ batch.length > 0 &&
2325
+ (batch.length >= maxPaths || pathBytes + nextPathBytes > METADATA_BATCH_MAX_PATH_BYTES)
2326
+ ) {
2327
+ result.push(batch);
2328
+ batch = [];
2329
+ pathBytes = 0;
2330
+ }
2331
+ batch.push(path);
2332
+ pathBytes += nextPathBytes;
2333
+ }
2334
+ if (batch.length > 0) result.push(batch);
2335
+ return result;
2336
+ }
2337
+
2338
+ function configuredMetadataBatchMaxPaths(): number {
2339
+ const raw = process.env.PI_UNDO_METADATA_BATCH_MAX_PATHS;
2340
+ if (raw === undefined || raw === "") return METADATA_BATCH_MAX_PATHS;
2341
+ const value = Number(raw);
2342
+ if (!Number.isSafeInteger(value) || value <= 0 || value > METADATA_BATCH_HARD_MAX_PATHS) {
2343
+ throw new Error(`PI_UNDO_METADATA_BATCH_MAX_PATHS 必须是 1-${METADATA_BATCH_HARD_MAX_PATHS} 的整数`);
2344
+ }
2345
+ return value;
2346
+ }
2347
+
2348
+ function metadataInspectRequestGroups(
2349
+ batches: readonly string[][],
2350
+ workspaceRoot: string,
2351
+ ): string[][][] {
2352
+ const result: string[][][] = [];
2353
+ let group: string[][] = [];
2354
+ for (const batch of batches) {
2355
+ const candidate = [...group, batch];
2356
+ const pathCount = candidate.reduce((total, paths) => total + paths.length, 0);
2357
+ const requestBytes = Buffer.byteLength(JSON.stringify({
2358
+ schemaVersion: 1,
2359
+ workspaceRoot,
2360
+ batches: candidate,
2361
+ }), "utf8");
2362
+ if (
2363
+ group.length > 0 &&
2364
+ (candidate.length > METADATA_BATCHES_MAX_BATCHES ||
2365
+ pathCount > METADATA_BATCHES_MAX_PATHS ||
2366
+ requestBytes > METADATA_BATCHES_MAX_REQUEST_BYTES)
2367
+ ) {
2368
+ result.push(group);
2369
+ group = [batch];
2370
+ continue;
2371
+ }
2372
+ group = candidate;
2373
+ }
2374
+ if (group.length > 0) result.push(group);
2375
+ return result;
2376
+ }
2377
+
2296
2378
  function hashPathBatches(leaves: readonly VisibleLeaf[]): VisibleLeaf[][] {
2297
2379
  const result: VisibleLeaf[][] = [];
2298
2380
  let current: VisibleLeaf[] = [];
@@ -2322,6 +2404,27 @@ function parseObjectIdLines(output: string, expectedCount: number): string[] {
2322
2404
  return lines;
2323
2405
  }
2324
2406
 
2407
+ function treeDirectoryPaths(entries: readonly CapturedTreeEntry[]): string[] {
2408
+ const directories: string[] = [];
2409
+ let previousParts: readonly string[] = [];
2410
+ let previousPrefixes: string[] = [];
2411
+ for (const entry of entries) {
2412
+ const parts = entry.relativePath.split("/");
2413
+ let common = 0;
2414
+ while (common < previousParts.length && common < parts.length && previousParts[common] === parts[common]) {
2415
+ common += 1;
2416
+ }
2417
+ for (let index = common; index < parts.length - 1; index += 1) {
2418
+ const prefix = index === 0 ? parts[0]! : `${previousPrefixes[index - 1]!}/${parts[index]!}`;
2419
+ directories.push(prefix);
2420
+ previousPrefixes[index] = prefix;
2421
+ }
2422
+ previousParts = parts;
2423
+ previousPrefixes.length = Math.max(0, parts.length - 1);
2424
+ }
2425
+ return directories;
2426
+ }
2427
+
2325
2428
  function parseTreeEntries(output: Uint8Array): CapturedTreeEntry[] {
2326
2429
  const entries: CapturedTreeEntry[] = [];
2327
2430
  for (const record of splitNulRecords(output)) {