@davideasden/pi-undo 0.3.12 → 0.4.1

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.
package/README.md CHANGED
@@ -167,6 +167,8 @@ recovery_required
167
167
 
168
168
  ### Performance Notes
169
169
 
170
+ **Linux 共享盘:** 可以直接在 Parallels 的 `/media/psf` 下使用默认配置,不需要搬动项目或设置 `PI_UNDO_DISABLE_NATIVE=1`。工作区根位于 FUSE 时,每次完整枚举目录,不依赖宿主机是否投递 inotify 事件。覆盖已有普通文件时,若其父目录位于 FUSE,整批在写入前选择现有的 TypeScript 事务日志路径;元数据检查仍可使用原生 helper。见[共享盘实测](docs/native-performance.md#linux-共享盘)。
171
+
170
172
  普通文件恢复在持有 workspace 独占锁时,先逐项核验 changedPaths 中的叶子文件;若与 checkpoint source 一致,就直接复用 manifest,避免额外 scoped capture 和全目录扫描。目录 scope、内容不匹配或 source 无法证明时仍走 scoped safety capture。成功路径保留 `restore-pre` 与 `restore-post` 两次 topology 检查,并继续执行 scope 内可见路径校验;锁内省略其后的重复 topology 扫描。native helper 仍不跟随符号链接地扫描 ignored 目录中的嵌套仓库;没有默认跳过 `node_modules`,也没有使用 TTL 缓存。
171
173
 
172
174
  原生恢复可处理已有父目录中的普通文件删除、覆盖、创建及混合计划。`restore-files-v2` 覆盖子目录删除和混合 mutation;`restore-files-v3` 会把分散在大量父目录中的文件拆成多个批次,每批最多打开 128 个非根父目录句柄。旧 helper、缺少二进制、目录操作、类型替换及单条路径深度超过句柄预算时继续走 TypeScript 路径。durable pack、逐项内容校验、no-clobber 与恢复依据均保留。
@@ -218,7 +220,7 @@ Performance gains come from:
218
220
  - **Indexed mutation path checks** — `MutationPathIndex` replaces the per-target-path `[...deletePaths, ...writePaths].some(...)` scan (10k × 10k ≈ 962 ms → < 1 ms).
219
221
  - **Deduped batch blob reads** — object IDs are deduplicated with a `Set` instead of `Array.includes` (10k unique blobs ≈ 101 ms → 2.2 ms).
220
222
  - **Shared, parallel parent validation** — native metadata inspect validates the deduplicated parent set once per request with 32-way concurrency (10k deep paths 111.7 ms → 71.0 ms).
221
- - **Persistent resident scan cache** — `--serve` starts from the on-disk v2 directory cache and writes it back; idle timeout raised to 600 s. 20k-directory cold start 377 ms → 251 ms with a warm cache, steady-state requests remain 13–20 ms.
223
+ - **常驻目录缓存**:使用 `--serve` 时可从磁盘 v2 缓存启动,当前服务空闲约 10 秒后退出。Linux FUSE 工作区不使用此缓存。
222
224
  - **Racy-window baseline skip** — settled capture skips the guaranteed-failing `isBaselineFresh` probe within 2 s after a restore, removing ~227–240 ms from the settlement path.
223
225
  - **Transferred pack payloads** — the restore path hands pack ownership of its freshly read blobs instead of copying them (64 MiB benchmark: +64.0 MiB → +0.01 MiB extra ArrayBuffers, +2.3 MiB RSS), and the pack checksum is computed during the write pass.
224
226
 
@@ -1,5 +1,24 @@
1
1
  # 原生目录扫描与普通文件恢复性能验证
2
2
 
3
+ ## Linux 共享盘
4
+
5
+ Linux arm64、Node 23.11.1、Pi 1.4.0 SDK。工作区和会话目录均放在同一 Parallels `fuse.prl_fsd` 挂载上。3,000 个 ignored 依赖包(6,002 个目录),每次只覆盖一个根目录文件。表中为每组连续三次操作的中位数;成功的用例同时断言文件内容与 undo/redo 栈。
6
+
7
+ | 同一挂载上的配置 | 撤销 | 重做 |
8
+ | --- | ---: | ---: |
9
+ | `c73bd40f` 默认 | `recovery_required`,无有效耗时 | 未执行 |
10
+ | `c73bd40f` 全局禁用 native | 5.54 s | 3.75 s |
11
+ | 仅将 FUSE 覆盖切换到事务日志 | 5.58 s | 5.35 s |
12
+ | 同时按目录项扫描,首次 / 复测 | 3.27 / 3.90 s | 3.25 / 3.88 s |
13
+
14
+ 失败的单文件用例在 `renameat2(RENAME_NOREPLACE)` 处返回 `EINVAL`。现在在预制 pack 和真正应用计划前,分别用 `statfs` 检查待覆盖普通文件的父目录(去重、有界并发);Linux FUSE 或无法判断时,整批走原有 WAL。它是保守的挂载类型判断,不是在用户目录创建文件做能力探测;纯新增、纯删除不依赖这次 rename,保留原选择。已进入 mutation 的事务仍使用原恢复流程,不在失败后换实现。
15
+
16
+ 工作区根位于 Linux FUSE 时不启动 `--serve`,TypeScript 每次完整枚举目录,从枚举结果挑选可能含 `.git` 的目录再检查,不对每个普通目录单独查询 `.git`。仍遍历 ignored 目录,并在枚举前后复核目录路径。两次实测每轮撤销均执行两次拓扑发现。完整快照仍须通过 Git 枚举 ignored 叶子。未在 Windows 或其他 FUSE 驱动上实测,不把本机数据当作性能保证。
17
+
18
+ 复现:将 `TMPDIR` 指向共享盘上工作区外的临时目录,运行 `PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts -t '3000 个依赖包,修改 1 个文件'`。不指定 `TMPDIR` 时夹具通常在 `/tmp` 建工作区,测不到共享盘。
19
+
20
+ ## 历史基准
21
+
3
22
  本轮实现目录项缓存与 scoped restore 的可见路径检查;普通一次性扫描仍会逐个打开、核验工作区内的目录,宽目录最多使用 16 个有界 worker 并行处理。常驻 `--serve` 在 macOS 上使用 FSEvents 收集变更父目录,只重新枚举受影响祖先并合并局部 cache;无变化请求复用驻留 cache,事件丢失、监听停止或扫描竞争时回退完整校验。
4
23
 
5
24
  ## Durable pack 准备与批量写入
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.3.12",
3
+ "version": "0.4.1",
4
4
  "description": "Persistent workspace undo and redo for Pi",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,6 +1,20 @@
1
+ import { statfs } from "node:fs/promises";
2
+
1
3
  import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
2
4
  import { checkOperation, OperationError, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
3
5
 
6
+ const LINUX_FUSE_SUPER_MAGIC = 0x65735546;
7
+
8
+ /** Linux FUSE 不保证支持防覆盖 rename,也不保证宿主机变更会产生客户机 inotify 事件。 */
9
+ export async function allowsNativeMountFastPaths(directory: string): Promise<boolean> {
10
+ if (process.platform !== "linux") return true;
11
+ try {
12
+ return (await statfs(directory)).type !== LINUX_FUSE_SUPER_MAGIC;
13
+ } catch {
14
+ return false;
15
+ }
16
+ }
17
+
4
18
  /** 在私有目录探测,防止旧 helper 把 --capabilities 当成工作区里的请求文件。 */
5
19
  export async function probeNativeCapabilities(
6
20
  executable: string,
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
4
4
  import { isAbsolute, join, relative, resolve, sep } from "node:path";
5
5
 
6
6
  import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
7
- import { probeNativeCapabilities } from "./native-capabilities.ts";
7
+ import { allowsNativeMountFastPaths, probeNativeCapabilities } from "./native-capabilities.ts";
8
8
  import { nativeExecutable } from "./native-restore.ts";
9
9
  import { checkOperation, configuredTimeout, OperationError, operationProcessOptions } from "./operation-context.ts";
10
10
  import { ResidentScanClient } from "./resident-scan-client.ts";
@@ -84,6 +84,7 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
84
84
  }
85
85
 
86
86
  private async prewarmResident(workspaceRoot: string): Promise<void> {
87
+ if (!await allowsNativeMountFastPaths(workspaceRoot)) return;
87
88
  const temporaryRoot = await realpath(tmpdir()).catch(() => undefined);
88
89
  if (temporaryRoot === undefined || isPathInside(workspaceRoot, temporaryRoot)) return;
89
90
  const requestDirectory = await mkdtemp(join(temporaryRoot, "pi-undo-native-serve-probe-"));
@@ -118,7 +119,7 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
118
119
 
119
120
  async scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined> {
120
121
  checkOperation();
121
- if (this.executable === undefined) return undefined;
122
+ if (this.executable === undefined || !await allowsNativeMountFastPaths(workspaceRoot)) return undefined;
122
123
  const pendingPrewarm = this.prewarmInFlight;
123
124
  if (pendingPrewarm?.workspaceRoot === workspaceRoot) await pendingPrewarm.promise;
124
125
  checkOperation();
@@ -22,6 +22,7 @@ import {
22
22
  import { assertManifest, assertOperationId, canonicalJson, checksum } from "./encoding.ts";
23
23
  import { MutationJournal } from "./mutation-journal.ts";
24
24
  import { allCompleted, checkOperation, rethrowOperationFailure, isUnconfirmedExit, operationFailure, withRecoveryBudget } from "./operation-context.ts";
25
+ import { allowsNativeMountFastPaths } from "./native-capabilities.ts";
25
26
  import { createNativeFileBatch, nativeRestoreCapability } from "./native-restore.ts";
26
27
  import { recoverPackedMutations } from "./packed-recovery.ts";
27
28
  import type { ManifestId, RestorePath, SnapshotManifest, SnapshotRoot } from "./model.ts";
@@ -515,7 +516,7 @@ export class RestoreEngine {
515
516
  // durable pack 的 blob 读取和编码可能持续一段时间;保留已完成的 plan/path 表,
516
517
  // 让用户在此窗口触发 undo 时复用前序准备结果,而不是重新 listTree。
517
518
  this.rememberPreparedPlan(plan, prepared.currentPaths, prepared.targetPaths);
518
- if (!this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
519
+ if (!await this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
519
520
  const cacheRoot = await this.store.durableCacheDirectory();
520
521
  const cacheOpId = `cache-${plan.planDigest}`;
521
522
  const cacheJournal = new MutationJournal(
@@ -1103,7 +1104,7 @@ export class RestoreEngine {
1103
1104
  !compatibilityMode &&
1104
1105
  options.deferDurability === true &&
1105
1106
  options.forceTargetArtifactSync !== true &&
1106
- this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
1107
+ await this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
1107
1108
  ) {
1108
1109
  try {
1109
1110
  const cached = this.durablePackCache.get(plan.planDigest);
@@ -1169,10 +1170,7 @@ export class RestoreEngine {
1169
1170
  );
1170
1171
  }
1171
1172
  const durablePackEnabled = durablePack !== undefined;
1172
- if (
1173
- nativeFileBatch !== undefined && durablePack !== undefined &&
1174
- this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
1175
- ) {
1173
+ if (nativeFileBatch !== undefined && durablePack !== undefined) {
1176
1174
  if (!await visiblePreflight) {
1177
1175
  return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
1178
1176
  }
@@ -1275,11 +1273,11 @@ export class RestoreEngine {
1275
1273
  }
1276
1274
  }
1277
1275
 
1278
- private canUseNativeFilePlan(
1276
+ private async canUseNativeFilePlan(
1279
1277
  plan: RestorePlan,
1280
1278
  currentPaths: ReadonlyMap<string, OwnedPath>,
1281
1279
  targetPaths: ReadonlyMap<string, OwnedPath>,
1282
- ): boolean {
1280
+ ): Promise<boolean> {
1283
1281
  if (plan.deletePaths.length + plan.writePaths.length === 0) return false;
1284
1282
  if (process.platform === "win32" && plan.deletePaths.length > 0) return false;
1285
1283
  if (!plan.deletePaths.every((path) =>
@@ -1288,7 +1286,20 @@ export class RestoreEngine {
1288
1286
  targetPaths.get(path)?.entry.kind === "file" &&
1289
1287
  (currentPaths.get(path) === undefined || currentPaths.get(path)?.entry.kind === "file"))) return false;
1290
1288
  const paths = [...plan.deletePaths, ...plan.writePaths];
1291
- return process.platform === "win32" || paths.every((path) => strictPathAncestors(path).length <= 128);
1289
+ if (process.platform === "win32") return true;
1290
+ if (paths.some((path) => strictPathAncestors(path).length > 128)) return false;
1291
+ if (process.platform !== "linux") return true;
1292
+ // 只有覆盖已有文件才用 renameat2。按实际父目录判断,以覆盖工作区内的嵌套挂载;
1293
+ // 不跨操作缓存结果,预制 pack 之后挂载也可能变化。
1294
+ const parents = [...new Set(plan.writePaths.filter((path) => currentPaths.has(path))
1295
+ .map((path) => dirname(path)))];
1296
+ for (let start = 0; start < parents.length; start += RESTORE_FILE_PREPARE_CONCURRENCY) {
1297
+ checkOperation();
1298
+ const supported = await allCompleted(parents.slice(start, start + RESTORE_FILE_PREPARE_CONCURRENCY)
1299
+ .map((parent) => allowsNativeMountFastPaths(this.absolutePath(parent))));
1300
+ if (supported.includes(false)) return false;
1301
+ }
1302
+ return true;
1292
1303
  }
1293
1304
 
1294
1305
  private async applyNativeFilePlan(
@@ -176,14 +176,16 @@ export class RootDiscovery {
176
176
  ): Promise<Array<{ readonly path: string; readonly inspect: true }>> {
177
177
  checkOperation();
178
178
  if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
179
- if (candidate.inspect) {
180
- const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
181
- this.recordInspection(workspaceIdentity, inspection, activeRoots);
182
- if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
183
- }
184
179
  checkOperation();
185
180
  const entries = await readdir(candidate.path, { withFileTypes: true });
186
181
  if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
182
+ // 使用这次枚举识别候选;遇到大小写变体仍由文件系统对 .git 的实际查找决定。
183
+ if (candidate.inspect && entries.some((entry) => entry.name.toLowerCase() === ".git")) {
184
+ checkOperation();
185
+ const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
186
+ if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
187
+ this.recordInspection(workspaceIdentity, inspection, activeRoots);
188
+ }
187
189
  return entries
188
190
  .filter((entry) => entry.name !== ".git" && !entry.isSymbolicLink() && entry.isDirectory())
189
191
  .map((entry) => ({ path: join(candidate.path, entry.name), inspect: true as const }));
@@ -1172,6 +1172,36 @@ export class SnapshotStore {
1172
1172
  // 先完成全部 membership 校验,再按 gitDirectory 分组;同一个私有 ODB 的多个 blob
1173
1173
  // 合并成一次 cat-file --batch,省掉每次进程启动的固定开销。
1174
1174
  const pending: { readonly gitDirectory: string; readonly objectId: string }[] = [];
1175
+ // membership 缓存有上限;大批量请求被淘汰的路径按 tree 合并成一次 ls-tree,
1176
+ // 避免逐路径启动 git 进程。查询结果只在本次请求内使用,不依赖缓存是否保留。
1177
+ const fetchedMembership = new Map<string, string>();
1178
+ const missingByTree = new Map<string, { gitDirectory: string; treeId: string; paths: string[] }>();
1179
+ for (const request of requests) {
1180
+ const root = roots.get(request.rootPath);
1181
+ if (root === undefined || root.state !== "active" || root.treeId === null || request.relativePath === undefined) continue;
1182
+ const gitDirectory = this.rootGitDirectory(storeDirectory, root);
1183
+ const safeRelativePath = relativeSafePath("/", request.relativePath);
1184
+ const knownKey = treeBlobMembershipKey(gitDirectory, root.treeId, safeRelativePath);
1185
+ const known = this.treeBlobMembership.get(knownKey);
1186
+ if (known !== undefined) {
1187
+ // 先记入本次请求的局部表:后续批量 ls-tree 可能把它从有界缓存中淘汰。
1188
+ fetchedMembership.set(knownKey, known);
1189
+ continue;
1190
+ }
1191
+ const treeKey = `${gitDirectory}\0${root.treeId}`;
1192
+ let group = missingByTree.get(treeKey);
1193
+ if (group === undefined) {
1194
+ group = { gitDirectory, treeId: root.treeId, paths: [] };
1195
+ missingByTree.set(treeKey, group);
1196
+ }
1197
+ group.paths.push(safeRelativePath);
1198
+ }
1199
+ for (const group of missingByTree.values()) {
1200
+ const entries = await this.readTreeEntries(group.gitDirectory, group.treeId, group.paths);
1201
+ for (const entry of entries) {
1202
+ fetchedMembership.set(treeBlobMembershipKey(group.gitDirectory, group.treeId, entry.relativePath), entry.objectId);
1203
+ }
1204
+ }
1175
1205
  for (const request of requests) {
1176
1206
  const root = roots.get(request.rootPath);
1177
1207
  if (root === undefined) {
@@ -1191,7 +1221,7 @@ export class SnapshotStore {
1191
1221
  }
1192
1222
  } else {
1193
1223
  const membershipKey = treeBlobMembershipKey(gitDirectory, root.treeId, safeRelativePath);
1194
- let ownedBlobId = this.treeBlobMembership.get(membershipKey);
1224
+ let ownedBlobId = this.treeBlobMembership.get(membershipKey) ?? fetchedMembership.get(membershipKey);
1195
1225
  if (ownedBlobId === undefined) {
1196
1226
  await this.readTreeEntries(gitDirectory, root.treeId, [safeRelativePath]);
1197
1227
  ownedBlobId = this.treeBlobMembership.get(membershipKey);