@davideasden/pi-undo 0.2.3 → 0.2.5

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,7 @@ 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 (down from 14.3s before batching), and approximately 2.8s on the native Rust path with durable pack caching and indexed blob reads.
 
 ## License
 

package/package.json

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

package/src/mutation-journal.ts

@@ -64,6 +64,12 @@ export class MutationJournal {
 		return (await this.readRecords()).latest;
 	}
 
+	async loadOrdinal(ordinal: number): Promise<MutationRecord | undefined> {
+		if (!Number.isSafeInteger(ordinal) || ordinal < 1) return undefined;
+		const record = (await this.readRecords()).latest[ordinal - 1];
+		return record?.ordinal === ordinal ? record : undefined;
+	}
+
 	begin(intent: MutationIntent): Promise<MutationRecord> {
 		return this.enqueueMutation(async () => (await this.beginManyMutation([intent]))[0]!);
 	}

package/src/path-safety.ts

@@ -64,6 +64,23 @@ export async function assertNoSymlinkEscape(root: string, relativePath: string):
 	}
 }
 
+export function pathSetsOverlap(leftPaths: readonly string[], rightPaths: readonly string[]): boolean {
+	for (const path of leftPaths) assertRelativeCandidate(path);
+	for (const path of rightPaths) assertRelativeCandidate(path);
+	const rightSet = new Set(rightPaths);
+	const sortedRight = [...rightSet].sort(comparePaths);
+	for (const path of leftPaths) {
+		if (rightSet.has(path)) return true;
+		for (let separator = path.lastIndexOf("/"); separator >= 0; separator = path.lastIndexOf("/", separator - 1)) {
+			if (rightSet.has(path.slice(0, separator))) return true;
+		}
+		const descendantPrefix = `${path}/`;
+		const candidate = sortedRight[lowerBound(sortedRight, descendantPrefix)];
+		if (candidate?.startsWith(descendantPrefix)) return true;
+	}
+	return false;
+}
+
 export function sortDeletePaths(paths: readonly string[]): string[] {
 	return sortPaths(paths, -1);
 }
@@ -108,6 +125,20 @@ function pathDepth(path: string): number {
 	return path === "." ? 0 : path.split("/").length;
 }
 
+function lowerBound(paths: readonly string[], target: string): number {
+	let low = 0;
+	let high = paths.length;
+	while (low < high) {
+		const middle = low + Math.floor((high - low) / 2);
+		if (comparePaths(paths[middle]!, target) < 0) {
+			low = middle + 1;
+		} else {
+			high = middle;
+		}
+	}
+	return low;
+}
+
 function comparePaths(left: string, right: string): number {
 	return left < right ? -1 : left > right ? 1 : 0;
 }

package/src/pi-runtime.ts

@@ -99,7 +99,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 						continue;
 					}
 					await quarantine.rollForwardMutation(record);
-					const latest = (await mutationJournal.load()).find((candidate) => candidate.ordinal === record.ordinal);
+					const latest = await mutationJournal.loadOrdinal(record.ordinal);
 					if (latest === undefined) throw new Error("mutation ordinal 在恢复期间丢失");
 					await quarantine.cleanupMutation(latest);
 				}

package/src/quarantine.ts

@@ -771,7 +771,7 @@ export class QuarantineManager {
 
 	private async assertOwnedRecord(record: MutationRecord): Promise<MutationRecord> {
 		await this.assertWorkspaceIdentity();
-		const owned = (await this.journal.load()).find((candidate) => candidate.ordinal === record.ordinal);
+		const owned = await this.journal.loadOrdinal(record.ordinal);
 		if (owned === undefined || immutableMutation(owned) !== immutableMutation(record)) {
 			throw new QuarantineError("unsafe_artifact", "mutation record 未被当前 journal 精确登记");
 		}

package/src/restore-engine.ts

@@ -32,7 +32,7 @@ import {
 	type DeleteLeafRequest,
 	type ReplaceFileRequest,
 } from "./quarantine.ts";
-import { SnapshotStoreError, type SnapshotStore } from "./snapshot-store.ts";
+import { SnapshotStore, SnapshotStoreError } from "./snapshot-store.ts";
 
 const PREPARED_PLAN_CACHE_LIMIT = 16;
 const RESTORE_FILE_BATCH_MAX_ENTRIES = 1_024;
@@ -730,14 +730,25 @@ export class RestoreEngine {
 		opId: string,
 	): Promise<DurablePackEntryInput[]> {
 		const paths = [...new Set([...plan.deletePaths, ...plan.writePaths])].sort(comparePaths);
+		const useValidatedBatch = SnapshotStore.supportsValidatedBlobBatch(this.store);
+		const [currentBlobBytes, targetBlobBytes] = useValidatedBatch
+			? await Promise.all([
+				this.readDurableBlobBytes(current.manifestId, paths, currentPaths),
+				this.readDurableBlobBytes(target.manifestId, paths, targetPaths),
+			])
+			: [new Map<string, Uint8Array>(), new Map<string, Uint8Array>()];
 		const result: DurablePackEntryInput[] = [];
 		for (const path of paths) {
 			const variants = new Map<string, DurableLeafInput>();
 			const absent: DurableLeafInput = { kind: "absent", fingerprint: fingerprintAbsent(path) };
 			variants.set(absent.fingerprint, absent);
-			const currentLeaf = await this.durableLeaf(current.manifestId, currentPaths.get(path));
+			const currentLeaf = useValidatedBatch
+				? this.durableLeaf(currentPaths.get(path), currentBlobBytes.get(path))
+				: await this.durableLeafCompatible(current.manifestId, currentPaths.get(path));
 			if (currentLeaf !== undefined) variants.set(currentLeaf.fingerprint, currentLeaf);
-			const targetLeaf = await this.durableLeaf(target.manifestId, targetPaths.get(path));
+			const targetLeaf = useValidatedBatch
+				? this.durableLeaf(targetPaths.get(path), targetBlobBytes.get(path))
+				: await this.durableLeafCompatible(target.manifestId, targetPaths.get(path));
 			if (targetLeaf !== undefined) variants.set(targetLeaf.fingerprint, targetLeaf);
 			if (currentLeaf === undefined && targetLeaf === undefined) continue;
 			const artifactId = checksum(canonicalJson({ opId, path })).slice(0, 32);
@@ -757,10 +768,50 @@ export class RestoreEngine {
 		return result;
 	}
 
-	private async durableLeaf(
+	private async readDurableBlobBytes(
+		manifestId: ManifestId,
+		paths: readonly string[],
+		ownedPaths: ReadonlyMap<string, OwnedPath>,
+	): Promise<ReadonlyMap<string, Uint8Array>> {
+		const files = paths.flatMap((path) => {
+			const owned = ownedPaths.get(path);
+			if (owned?.entry.kind !== "file") return [];
+			if (owned.entry.blobId === null) {
+				throw new Error(`durable pack 普通文件缺少 blob：${owned.absolutePath}`);
+			}
+			return [{ path, owned, blobId: owned.entry.blobId }];
+		});
+		if (files.length === 0) return new Map();
+		const requests = files.map(({ owned, blobId }) => ({
+			rootPath: owned.root.relativeRoot,
+			blobId,
+			relativePath: owned.entry.relativePath,
+		}));
+		const blobs = await SnapshotStore.readBlobs(this.store, manifestId, requests);
+		if (blobs.length !== files.length) throw new Error("durable pack blob batch 数量不匹配");
+		return new Map(files.map(({ path }, index) => [path, blobs[index]!]));
+	}
+
+	private async durableLeafCompatible(
 		manifestId: ManifestId,
 		owned: OwnedPath | undefined,
 	): Promise<DurableLeafInput | undefined> {
+		if (owned?.entry.kind !== "file") return this.durableLeaf(owned, undefined);
+		if (owned.entry.blobId === null) {
+			throw new Error(`durable pack 普通文件缺少 blob：${owned.absolutePath}`);
+		}
+		return this.durableLeaf(owned, await this.store.readBlob(
+			manifestId,
+			owned.root.relativeRoot,
+			owned.entry.blobId,
+			owned.entry.relativePath,
+		));
+	}
+
+	private durableLeaf(
+		owned: OwnedPath | undefined,
+		bytes: Uint8Array | undefined,
+	): DurableLeafInput | undefined {
 		if (owned === undefined || owned.entry.kind === "directory") return undefined;
 		if (owned.entry.kind === "symlink") {
 			return {
@@ -769,13 +820,9 @@ export class RestoreEngine {
 				linkText: owned.entry.linkText!,
 			};
 		}
-		if (owned.entry.blobId === null) throw new Error(`durable pack 普通文件缺少 blob：${owned.absolutePath}`);
-		const bytes = await this.store.readBlob(
-			manifestId,
-			owned.root.relativeRoot,
-			owned.entry.blobId,
-			owned.entry.relativePath,
-		);
+		if (owned.entry.blobId === null || bytes === undefined) {
+			throw new Error(`durable pack 普通文件缺少 blob：${owned.absolutePath}`);
+		}
 		const mode = owned.entry.mode & 0o777;
 		return {
 			kind: "file",

package/src/snapshot-store.ts

@@ -20,7 +20,7 @@ import type {
 	SnapshotManifest,
 	SnapshotRoot,
 } from "./model.ts";
-import { assertNoSymlinkEscape, relativeSafePath } from "./path-safety.ts";
+import { assertNoSymlinkEscape, pathSetsOverlap, relativeSafePath } from "./path-safety.ts";
 import { RootDiscovery, type RootTopology } from "./root-discovery.ts";
 import { WorkspaceLock } from "./workspace-lock.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;
@@ -96,6 +96,12 @@ export interface CaptureOptions {
 	readonly excludePaths?: readonly string[];
 }
 
+export interface SnapshotBlobRequest {
+	readonly rootPath: string;
+	readonly blobId: string;
+	readonly relativePath?: string;
+}
+
 export type SnapshotStoreErrorCode =
 	| "capture_failed"
 	| "invalid_manifest_id"
@@ -151,6 +157,33 @@ export class SnapshotStore {
 		this.clock = options.clock ?? Date.now;
 	}
 
+	static supportsValidatedBlobBatch(store: SnapshotStore): boolean {
+		return store instanceof SnapshotStore &&
+			store.readBlob === SnapshotStore.prototype.readBlob &&
+			store.loadManifest === SnapshotStore.prototype.loadManifest;
+	}
+
+	static async readBlobs(
+		store: SnapshotStore,
+		id: ManifestId,
+		requests: readonly SnapshotBlobRequest[],
+	): Promise<readonly Uint8Array[]> {
+		if (requests.length === 0) return [];
+		if (SnapshotStore.supportsValidatedBlobBatch(store)) {
+			return (store as SnapshotStore).readBlobsValidated(id, requests);
+		}
+		const result: Uint8Array[] = [];
+		for (const request of requests) {
+			result.push(await store.readBlob(
+				id,
+				request.rootPath,
+				request.blobId,
+				request.relativePath,
+			));
+		}
+		return result;
+	}
+
 	async durableCacheDirectory(): Promise<string> {
 		const directory = join(this.storeRoot, "durable-cache");
 		await mkdir(directory, { recursive: true });
@@ -309,7 +342,10 @@ export class SnapshotStore {
 	}
 
 	async loadManifest(id: ManifestId): Promise<SnapshotManifest> {
-		const manifestPath = await this.findManifestPath(id);
+		return this.loadManifestFromPath(id, await this.findManifestPath(id));
+	}
+
+	private async loadManifestFromPath(id: ManifestId, manifestPath: string): Promise<SnapshotManifest> {
 		try {
 			const value: unknown = JSON.parse(await readFile(manifestPath, "utf8"));
 			const manifest = assertManifest(value);
@@ -349,10 +385,10 @@ export class SnapshotStore {
 				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
 				await this.assertNoAlternates(gitDirectory);
 				const entries = await this.readTreeEntries(gitDirectory, root.treeId, rootScope);
-				if (root.ignoredPresentPaths.some((ignoredPath) => entries.some(
-					(entry) => isPathAtOrBelow(ignoredPath, entry.relativePath) ||
-						isPathAtOrBelow(entry.relativePath, ignoredPath),
-				))) {
+				if (pathSetsOverlap(
+					root.ignoredPresentPaths,
+					entries.map((entry) => entry.relativePath),
+				)) {
 					throw new SnapshotStoreError("object_missing", "ignored-present proof 与 root tree 冲突");
 				}
 				await this.assertObjectsComplete(gitDirectory, root.treeId, entries);
@@ -432,41 +468,67 @@ export class SnapshotStore {
 		blobId: string,
 		relativePath?: string,
 	): Promise<Uint8Array> {
-		relativeSafePath("/", rootPath);
-		if (!isObjectId(blobId)) {
-			throw new SnapshotStoreError("object_missing", "blob ID 无效");
+		return (await this.readBlobOperation(id, [{ rootPath, blobId, relativePath }], false))[0]!;
+	}
+
+	private readBlobsValidated(
+		id: ManifestId,
+		requests: readonly SnapshotBlobRequest[],
+	): Promise<readonly Uint8Array[]> {
+		return this.readBlobOperation(id, requests, true);
+	}
+
+	private async readBlobOperation(
+		id: ManifestId,
+		requests: readonly SnapshotBlobRequest[],
+		revalidateManifest: boolean,
+	): Promise<readonly Uint8Array[]> {
+		for (const request of requests) {
+			relativeSafePath("/", request.rootPath);
+			if (!isObjectId(request.blobId)) {
+				throw new SnapshotStoreError("object_missing", "blob ID 无效");
+			}
 		}
 		const manifestPath = await this.findManifestPath(id);
-		const manifest = await this.loadManifest(id);
-		const root = manifest.roots.find((candidate) => candidate.relativeRoot === rootPath);
-		if (root === undefined) {
-			throw new SnapshotStoreError("root_not_found", "manifest 中不存在指定 root");
-		}
-		if (root.state !== "active" || root.treeId === null) {
-			throw new SnapshotStoreError("object_missing", "指定 root 没有可读取的 tree");
-		}
-
+		const manifest = revalidateManifest
+			? await this.loadManifestFromPath(id, manifestPath)
+			: await this.loadManifest(id);
+		const roots = new Map(manifest.roots.map((root) => [root.relativeRoot, root]));
 		const storeDirectory = dirname(dirname(manifestPath));
-		const gitDirectory = this.rootGitDirectory(storeDirectory, root);
 		try {
-			const safeRelativePath = relativePath === undefined ? undefined : relativeSafePath("/", relativePath);
-			if (safeRelativePath === undefined) {
-				const entries = await this.readTreeEntries(gitDirectory, root.treeId);
-				if (!entries.some((entry) => entry.objectId === blobId)) {
-					throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree");
+			const result: Uint8Array[] = [];
+			for (const request of requests) {
+				const root = roots.get(request.rootPath);
+				if (root === undefined) {
+					throw new SnapshotStoreError("root_not_found", "manifest 中不存在指定 root");
 				}
-			} else {
-				const membershipKey = treeBlobMembershipKey(gitDirectory, root.treeId, safeRelativePath);
-				let ownedBlobId = this.treeBlobMembership.get(membershipKey);
-				if (ownedBlobId === undefined) {
-					await this.readTreeEntries(gitDirectory, root.treeId, [safeRelativePath]);
-					ownedBlobId = this.treeBlobMembership.get(membershipKey);
+				if (root.state !== "active" || root.treeId === null) {
+					throw new SnapshotStoreError("object_missing", "指定 root 没有可读取的 tree");
 				}
-				if (ownedBlobId !== blobId) {
-					throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree path");
+				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
+				const safeRelativePath = request.relativePath === undefined
+					? undefined
+					: relativeSafePath("/", request.relativePath);
+				if (safeRelativePath === undefined) {
+					const entries = await this.readTreeEntries(gitDirectory, root.treeId);
+					if (!entries.some((entry) => entry.objectId === request.blobId)) {
+						throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree");
+					}
+				} else {
+					const membershipKey = treeBlobMembershipKey(gitDirectory, root.treeId, safeRelativePath);
+					let ownedBlobId = this.treeBlobMembership.get(membershipKey);
+					if (ownedBlobId === undefined) {
+						await this.readTreeEntries(gitDirectory, root.treeId, [safeRelativePath]);
+						ownedBlobId = this.treeBlobMembership.get(membershipKey);
+					}
+					if (ownedBlobId !== request.blobId) {
+						throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree path");
+					}
 				}
+				result.push(new Uint8Array(await this.readBlobBytes(gitDirectory, request.blobId)));
 			}
-			return new Uint8Array(await this.readBlobBytes(gitDirectory, blobId));
+			if (revalidateManifest) await this.loadManifestFromPath(id, manifestPath);
+			return result;
 		} catch (error) {
 			if (error instanceof SnapshotStoreError) {
 				throw error;
@@ -634,7 +696,7 @@ export class SnapshotStore {
 		gitBacked: boolean,
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
-		exactExclusions: readonly string[],
+		exactExclusions: ReadonlySet<string>,
 	): Promise<string[]> {
 		if (inclusions === null) {
 			return [];
@@ -657,7 +719,7 @@ export class SnapshotStore {
 		for (const relativePath of parseNulPaths(output)) {
 			if (
 				exclusions.some((excluded) => isPathAtOrBelow(excluded, relativePath)) ||
-				exactExclusions.includes(relativePath)
+				exactExclusions.has(relativePath)
 			) {
 				continue;
 			}
@@ -686,7 +748,7 @@ export class SnapshotStore {
 		gitBacked: boolean,
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
-		exactExclusions: readonly string[],
+		exactExclusions: ReadonlySet<string>,
 	): Promise<void> {
 		const leaves = await this.collectVisibleLeaves(
 			cwd,
@@ -758,7 +820,7 @@ export class SnapshotStore {
 		gitBacked: boolean,
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
-		exactExclusions: readonly string[],
+		exactExclusions: ReadonlySet<string>,
 		excludeDeleted = false,
 	): Promise<string[]> {
 		if (inclusions === null) return [];
@@ -792,7 +854,7 @@ export class SnapshotStore {
 		return parseNulPaths(output).filter((relativePath) =>
 			!deletedPaths.has(relativePath) &&
 			!exclusions.some((excluded) => isPathAtOrBelow(excluded, relativePath)) &&
-			!exactExclusions.includes(relativePath));
+			!exactExclusions.has(relativePath));
 	}
 
 	private async collectVisibleLeaves(
@@ -801,7 +863,7 @@ export class SnapshotStore {
 		gitBacked: boolean,
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
-		exactExclusions: readonly string[],
+		exactExclusions: ReadonlySet<string>,
 	): Promise<VisibleLeaf[]> {
 		const paths = await this.queryVisibleLeafPaths(
 			cwd,
@@ -1196,7 +1258,7 @@ function ownedArtifactExclusions(
 	roots: readonly DiscoveryRoot[],
 	rootPath: string,
 	exclusions: readonly string[],
-): string[] {
+): ReadonlySet<string> {
 	const result: string[] = [];
 	for (const exclusion of exclusions) {
 		const owner = roots
@@ -1211,7 +1273,7 @@ function ownedArtifactExclusions(
 		}
 		result.push(rootRelativePath(rootPath, exclusion));
 	}
-	return result;
+	return new Set(result);
 }
 
 function rootRelativeScope(rootPath: string, scope: readonly string[] | undefined): string[] | undefined {