@davideasden/pi-undo 0.2.4 → 0.2.6

package/README.md

@@ -15,7 +15,7 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 - **External concurrency detection** — file fingerprint and inode checks detect external modification. Conflicting changes are never silently overwritten; the system fails closed or enters `recovery required`.
 - **No Git workflow** — snapshots use a private object database. No `git commit`, `git stash`, `git reset`, branches, or forges are required.
 - **Nested repositories** and **initialized submodules** are handled as independent roots. Their `.git` metadata is never modified.
-- **Performance** — batch WAL operations (up to 1,024 files per batch), scoped safety snapshots, prebuilt durable transaction packs, and an optional precompiled native regular-file helper keep restore fast at scale. Unsupported platforms and failed integrity checks automatically use the TypeScript path.
+- **Performance** — batch WAL operations (up to 1,024 files per batch), scoped safety snapshots, prebuilt durable transaction packs, native Rust no-clobber file helper for macOS arm64, indexed WAL record and conflict lookups, and parallel manifest blob reads keep restore fast at scale. Unsupported platforms and failed integrity checks automatically use the TypeScript path.
 
 ## Requirements
 
@@ -115,12 +115,18 @@ Real-world measurements from a 104-file undo operation before optimizations:
 ok files:104 total:8797ms apply:8591ms capture:89ms journal:64ms commit:27ms plan:11ms
 ```
 
-After batch WAL, scoped safety snapshots, parallel restore I/O, and batch file deletes:
+After batch WAL, scoped safety snapshots, parallel restore I/O, batch file deletes, and prebuilt durable transaction packs:
 
 ```text
 ok files:104 total:~1050ms apply:~850ms capture:~90ms journal:~65ms
 ```
 
+After native Rust helper, durable pack caching, parallel durable finalization, batch validated blob reads, and indexed mutation/path lookups:
+
+```text
+ok files:104 total:~850ms apply:~650ms capture:~90ms journal:~65ms plan:~10ms
+```
+
 Performance gains come from:
 
 - **Batch WAL durability** — write-once, fsync-once per batch of up to 1,024 entries instead of per-file.
@@ -132,6 +138,11 @@ Performance gains come from:
 - **Concurrent request preparation** — blob reads, live-state checks, and fingerprint computation run at 32-wide concurrency.
 - **Batch file deletes** — delete operations share the same WAL batch and directory fsync merging.
 - **Directory fsync merging** — barriers are applied once per unique directory per phase, not once per file.
+- **Native Rust no-clobber helper** — packaged macOS arm64 binary uses platform renameat2 with EEXIST guard for regular-file batches; missing binaries or platform mismatch fall back to the TypeScript path before mutation.
+- **Durable pack caching** — completed agent runs build and cache reverse/forward durable packs; the undo/redo hot path reuses the cached pack with manifest pin, avoiding redundant snapshot reads.
+- **Indexed WAL record lookups** — mutation records are indexed by ordinal for O(1) direct access instead of linear scan.
+- **Indexed path conflict resolution** — `exactExclusions` are stored as a Set for O(1) membership checks instead of O(n) `Array.includes`.
+- **Batch validated manifest blob reads** — durable pack reads coalesce blob fetches into a single batch per manifest with combined Git validation.
 
 ## How It Works
 
@@ -259,7 +270,7 @@ test/                        Unit, integration, recovery, and fault-injection te
 ### Testing
 
 ```bash
-npm test                  # Full test suite (400+ tests)
+npm test                  # Full test suite (425+ tests)
 npm run test:native       # Rust helper and durable-pack recovery tests
 npm run test:watch        # Watch mode
 npm run test:integration  # Pi runtime and extension integration tests
@@ -279,7 +290,54 @@ Benchmark tests assert Git call counts and WAL record counts, not wall-clock thr
 | 100-file restore (delete) — batch deletes | ≤12 | 600 | ~0.6s |
 | 4,000-file rollback snapshot — batch Git | ≤24 (4 x `mktree`, 4 x `commit-tree`) | — | ~7s |
 
-The 104-file standalone apply probe (10 warmup iterations + 10 measured) completes in approximately 3.9s post-optimization, down from 14.3s before batching.
+The 104-file standalone apply probe (10 warmup iterations + 10 measured) completes in approximately 3.9s post-optimization on the TypeScript path, and approximately 2.8s on the native Rust path.
+
+### Performance Optimizations
+
+Several hot paths were profiled and corrected from quadratic (n doubled ≈ 4× cost) to near-linear scaling. Each change was verified against the existing test suite (425+ tests) plus fault-injection and adversarial-diff tests. Optimization order was guided by real profile data rather than static code review alone. After this phase, attention shifted to the native Rust helper path, which dominates production workloads.
+
+#### Wall-clock comparison (n changed files + n ignored files)
+
+**Plan phase** — undo diff derivation and workspace topology check:
+
+| n | Before | After | Improvement |
+|---|---|---|---|
+| 1,000 | ~178ms | ~131ms | 1.4× |
+| 2,000 | ~399ms | ~259ms | 1.5× |
+| 5,000 | ~2.5s | ~699ms | ~3.6× |
+
+**Bidirectional durable pack prepare** — agent-settled caching for undo/redo:
+
+| n | Before (no batch) | After (batched) | Improvement |
+|---|---|---|---|
+| 500 | ~949ms | ~249ms | 3.8× |
+| 1,000 | ~2,940ms | ~386ms | 7.6× |
+| 2,000 | ~10,512ms | ~677ms | 15.5× |
+
+**Native apply** — the production hot path:
+
+| n | TypeScript fallback | Native Rust helper | Improvement |
+|---|---|---|---|
+| 500 | ~2,572ms | ~253ms | 10.2× |
+| 1,000 | ~5,726ms | ~374ms | 15.3× |
+| 2,000 | ~10,521ms | ~646ms | 16.3× |
+
+#### Algorithm microbenchmarks
+
+| Scenario | Before | After | Improvement |
+|---|---|---|---|
+| 8,000×8,000 path overlap check | ~1,352ms | ~7ms | **193×** |
+| 4,000-directory ignored prefix scan (plan) | ~544ms | ~161ms | **3.4×** |
+| 5,000×5,000 manifest integrity verify | ~610ms | ~7ms | **87×** |
+
+#### Key enablers
+
+- **Manifest context batching** (`SnapshotStore.readBlobs`): one manifest read and full revalidation serves all blob fetches per operation instead of one manifest load per blob. 2,000-file pack creation dropped from 10.5s to 796ms.
+- **Blob read batch sizing** (`BLOB_BATCH_MAX_ENTRIES`: 256 → 2,048): 40 `cat-file --batch` processes collapsed to 6 for 5,000 files by letting the 16MiB byte budget drive batch boundaries.
+- **Path overlap indexing** (`pathSetsOverlap` in `path-safety.ts`): sorted binary search plus ancestor enumeration replaces a nested `some()` pattern. 8,000×8,000 path pairs from 1.35s to 7ms.
+- **Ignored-proof prefix index** (`IgnoredProofIndex` in `restore-engine.ts`): lazily sorted binary lower-bound search for directory prefix lookups replaces a full-set spread per candidate. 4,000 directories from 544ms to 161ms.
+- **WAL ordinal indexing** (`loadOrdinal` in `mutation-journal.ts`): direct array access by contiguous ordinal replaces linear `.find()` throughout quarantine and legacy recovery.
+- **Native Rust no-clobber helper** (`native/pi-undo-fs`): platform native hardlink operations with EEXIST guard. Processes in ~0.3ms per file vs ~5.3ms for the TypeScript fallback, with WAL materialized from the durable pack.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [

package/src/restore-engine.ts

@@ -169,7 +169,7 @@ export class RestoreEngine {
 			this.readOwnedPaths(current, canonicalScopePaths),
 			this.readOwnedPaths(target, canonicalScopePaths),
 		]);
-		const targetIgnoredPaths = ignoredWorkspacePaths(target);
+		const targetIgnoredProof = new IgnoredProofIndex(ignoredWorkspacePaths(target));
 		const deleteByRoot = new Map<string, string[]>();
 		const writeByRoot = new Map<string, string[]>();
 
@@ -183,7 +183,7 @@ export class RestoreEngine {
 				continue;
 			}
 			if (targetOwned === undefined) {
-				if (isProtectedByIgnoredProof(path, owned.entry.kind, targetIgnoredPaths)) {
+				if (targetIgnoredProof.isProtected(path, owned.entry.kind)) {
 					continue;
 				}
 				appendPath(deleteByRoot, owned.root.relativeRoot, path);
@@ -1728,15 +1728,42 @@ function ignoredWorkspacePaths(manifest: SnapshotManifest): Set<string> {
 	));
 }
 
-function isProtectedByIgnoredProof(
-	path: string,
-	kind: RestorePath["kind"],
-	ignoredPaths: ReadonlySet<string>,
-): boolean {
-	if (kind !== "directory") {
-		return ignoredPaths.has(path);
+/**
+ * ignored 证明的前缀索引。
+ *
+ * 目录判定需要回答"是否存在以 `${path}/` 开头的 ignored 路径"。逐次线性扫描
+ * 整个 set 会让"目录数 × ignored 数"变成平方项，因此这里预排序一次，
+ * 之后每次判定用二分下界定位第一个不小于前缀的元素。
+ *
+ * 语义与线性扫描完全一致：只回答存在性，不改变 fail-closed 行为，也不放宽
+ * 任何 ignored 保护。非目录仍走精确 `has()`。
+ */
+class IgnoredProofIndex {
+	private readonly exact: ReadonlySet<string>;
+	private sortedPaths: readonly string[] | undefined;
+
+	constructor(paths: ReadonlySet<string>) {
+		this.exact = paths;
+	}
+
+	isProtected(path: string, kind: RestorePath["kind"]): boolean {
+		if (kind !== "directory") {
+			return this.exact.has(path);
+		}
+		if (this.exact.size === 0) return false;
+		// 排序成本只在第一次目录判定时付出，纯文件计划完全不触发。
+		this.sortedPaths ??= [...this.exact].sort();
+		const sorted = this.sortedPaths;
+		const prefix = `${path}/`;
+		let low = 0;
+		let high = sorted.length;
+		while (low < high) {
+			const middle = (low + high) >>> 1;
+			if (sorted[middle]! < prefix) low = middle + 1;
+			else high = middle;
+		}
+		return low < sorted.length && sorted[low]!.startsWith(prefix);
 	}
-	return [...ignoredPaths].some((ignoredPath) => ignoredPath.startsWith(`${path}/`));
 }
 
 function rootBoundaryDirectories(root: string): string[] {

package/src/snapshot-store.ts

@@ -41,7 +41,7 @@ const INDEX_BATCH_MAX_ENTRIES = 4_096;
 const INDEX_BATCH_MAX_BYTES = 8 * 1024 * 1024;
 const BLOB_CACHE_MAX_BYTES = 128 * 1024 * 1024;
 const BLOB_BATCH_MAX_BYTES = 16 * 1024 * 1024;
-const BLOB_BATCH_MAX_ENTRIES = 256;
+const BLOB_BATCH_MAX_ENTRIES = process.platform === "win32" ? 256 : 2_048;
 
 interface PinRecord {
 	readonly schemaVersion: 1;