@ricsam/r5d-worker 0.0.97 → 0.0.99

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "type": "commonjs"
 }

package/dist/cjs/working-tree-mirror.cjs

@@ -29,8 +29,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var working_tree_mirror_exports = {};
 __export(working_tree_mirror_exports, {
   assertWorkingTreeHasNoPortableGitMetadataAliases: () => assertWorkingTreeHasNoPortableGitMetadataAliases,
+  captureWorkingTreeMirrorPlan: () => captureWorkingTreeMirrorPlan,
+  fsyncWorkingTreePaths: () => fsyncWorkingTreePaths,
   inspectWorkingTree: () => inspectWorkingTree,
-  mirrorWorkingTree: () => mirrorWorkingTree
+  mirrorWorkingTree: () => mirrorWorkingTree,
+  normalizeWorkingTreeRelativePath: () => normalizeWorkingTreeRelativePath,
+  planWorkingTreeMirror: () => planWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope: () => restoreWorkingTreeMirrorScope
 });
 module.exports = __toCommonJS(working_tree_mirror_exports);
 var import_node_fs = __toESM(require("node:fs"), 1);
@@ -186,14 +191,55 @@ function addParentDirectories(entries, root) {
     }
   }
 }
-function inspectWorkingTree(root, mode) {
+function gitlinkPaths(root) {
+  const result = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "ls-files",
+      "-z",
+      "--stage",
+      "--",
+      "."
+    ],
+    {
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: (0, import_git_process_environment.workerGitProcessEnvironment)()
+    }
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`Inspect Git index gitlinks: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+  }
+  const gitlinks = /* @__PURE__ */ new Set();
+  for (const record of result.stdout.toString().split("\0")) {
+    const match = /^160000 [0-9a-f]+ [0-3]\t(.+)$/su.exec(record);
+    if (!match) continue;
+    const normalized = normalizeRelativePath(match[1]);
+    if (normalized) gitlinks.add(normalized);
+  }
+  return gitlinks;
+}
+function directoryIsEmpty(root, relativePath) {
+  const inspected = inspectRelativePathWithoutFollowingAncestors(root, relativePath);
+  return inspected.kind === "entry" && inspected.stat.isDirectory() && import_node_fs.default.readdirSync(inspected.absolutePath).length === 0;
+}
+function inspectWorkingTree(root, mode, options = {}) {
   const entries = /* @__PURE__ */ new Map();
   root = import_node_path.default.resolve(root);
   if (!inspectDirectoryRoot(root, { allowMissing: true, label: "Working-tree root" })) return entries;
   if (mode === "all") {
     for (const child of import_node_fs.default.readdirSync(root).sort()) addEntry(entries, root, child, true);
   } else {
+    const omittedGitlinks = options.omitUnpopulatedGitlinks ? gitlinkPaths(root) : null;
     for (const relativePath of gitEligibleRoots(root)) {
+      if (omittedGitlinks?.has(relativePath) && directoryIsEmpty(root, relativePath)) continue;
       addEntry(entries, root, relativePath, true);
     }
   }
@@ -367,7 +413,9 @@ function mirrorWorkingTree(input) {
   }
   inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
   const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
-  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all");
+  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
+    omitUnpopulatedGitlinks: input.deletionMode === "git"
+  });
   for (const relativePath of [...existing.keys()].sort((left, right) => right.split("/").length - left.split("/").length)) {
     if (!desired.has(relativePath)) removeEntry(targetRoot, relativePath);
   }
@@ -378,9 +426,213 @@ function mirrorWorkingTree(input) {
   }
   return { paths: [...desired.keys()].filter((relativePath) => desired.get(relativePath)?.kind !== "directory").sort() };
 }
+function normalizeWorkingTreeRelativePath(value) {
+  return normalizeRelativePath(value);
+}
+const MIRROR_TEMPORARY_FILE_PATTERN = /^\.r5d-working-tree-mirror-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/u;
+function relativeDepth(relativePath) {
+  return relativePath.split("/").length;
+}
+function shallowestFirst(left, right) {
+  return relativeDepth(left) - relativeDepth(right) || left.localeCompare(right);
+}
+function deepestFirst(left, right) {
+  return relativeDepth(right) - relativeDepth(left) || left.localeCompare(right);
+}
+function hasAncestorIn(relativePath, ancestors) {
+  let parent = import_node_path.default.posix.dirname(relativePath);
+  while (parent !== ".") {
+    if (ancestors.has(parent)) return true;
+    parent = import_node_path.default.posix.dirname(parent);
+  }
+  return false;
+}
+function treeEntryFromStat(stat, absolutePath) {
+  if (stat.isSymbolicLink()) return { kind: "symlink", mode: stat.mode, target: import_node_fs.default.readlinkSync(absolutePath) };
+  if (stat.isFile()) return { kind: "file", mode: stat.mode, size: stat.size };
+  if (stat.isDirectory()) return { kind: "directory", mode: stat.mode };
+  return null;
+}
+function fsyncPath(targetPath, flags) {
+  const descriptor = import_node_fs.default.openSync(targetPath, flags);
+  try {
+    import_node_fs.default.fsyncSync(descriptor);
+  } finally {
+    import_node_fs.default.closeSync(descriptor);
+  }
+}
+function planWorkingTreeMirror(input) {
+  const sourceRoot = import_node_path.default.resolve(input.sourceRoot);
+  const targetRoot = import_node_path.default.resolve(input.targetRoot);
+  const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
+  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
+    omitUnpopulatedGitlinks: input.deletionMode === "git"
+  });
+  const replaced = /* @__PURE__ */ new Map();
+  const absent = [];
+  for (const [relativePath, entry] of existing) {
+    if (!desired.has(relativePath)) replaced.set(relativePath, entry);
+  }
+  for (const [relativePath, entry] of desired) {
+    const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (target.kind !== "entry") {
+      absent.push(relativePath);
+      continue;
+    }
+    const { absolutePath, stat } = target;
+    if (entry.kind === "directory") {
+      if (stat.isDirectory()) continue;
+    } else if (entry.kind === "symlink") {
+      if (stat.isSymbolicLink() && import_node_fs.default.readlinkSync(absolutePath) === entry.target) continue;
+    } else if (stat.isFile() && filesEqual(import_node_path.default.join(sourceRoot, ...relativePath.split("/")), absolutePath, entry)) {
+      continue;
+    }
+    const current = treeEntryFromStat(stat, absolutePath);
+    if (current) replaced.set(relativePath, current);
+    else absent.push(relativePath);
+  }
+  const replacedDirectories = new Set(
+    [...replaced].filter(([, entry]) => entry.kind === "directory").map(([relativePath]) => relativePath)
+  );
+  for (const relativePath of [...replaced.keys()]) {
+    if (hasAncestorIn(relativePath, replacedDirectories)) replaced.delete(relativePath);
+  }
+  return {
+    desired,
+    replaced,
+    absent: absent.filter((relativePath) => !hasAncestorIn(relativePath, replacedDirectories)).sort(shallowestFirst)
+  };
+}
+function captureWorkingTreeMirrorPlan(input) {
+  const targetRoot = import_node_path.default.resolve(input.targetRoot);
+  const snapshotRoot = import_node_path.default.resolve(input.snapshotRoot);
+  const durability = input.durability ?? "per_entry";
+  inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
+  if (!inspectDirectoryRoot(snapshotRoot, { allowMissing: true, label: "Working-tree snapshot root" })) {
+    import_node_fs.default.mkdirSync(snapshotRoot, { recursive: true });
+  }
+  const trees = [];
+  for (const [relativePath, entry] of [...input.plan.replaced.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    if (entry.kind !== "directory") {
+      copyEntry(targetRoot, snapshotRoot, relativePath, entry, durability);
+      continue;
+    }
+    const source = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (source.kind !== "entry" || !source.stat.isDirectory()) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${import_node_path.default.join(targetRoot, ...relativePath.split("/"))}`);
+    }
+    ensureDirectory(snapshotRoot, relativePath, entry.mode);
+    mirrorWorkingTree({
+      sourceRoot: source.absolutePath,
+      targetRoot: import_node_path.default.join(snapshotRoot, ...relativePath.split("/")),
+      sourceMode: "all",
+      deletionMode: "all",
+      durability
+    });
+    trees.push(relativePath);
+  }
+  return { absent: [...input.plan.absent].sort(shallowestFirst), trees: trees.sort(shallowestFirst) };
+}
+function restoreWorkingTreeMirrorScope(input) {
+  const snapshotRoot = import_node_path.default.resolve(input.snapshotRoot);
+  const targetRoot = import_node_path.default.resolve(input.targetRoot);
+  inspectDirectoryRoot(snapshotRoot, { allowMissing: false, label: "Working-tree snapshot root" });
+  if (!inspectDirectoryRoot(targetRoot, { allowMissing: true, label: "Working-tree target root" })) {
+    import_node_fs.default.mkdirSync(targetRoot, { recursive: true });
+  }
+  const normalize = (relativePath) => {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) throw new Error(`Invalid working-tree scope path: ${relativePath}`);
+    return normalized;
+  };
+  const absent = input.scope.absent.map(normalize);
+  const trees = new Set(input.scope.trees.map(normalize));
+  const captured = inspectWorkingTree(snapshotRoot, "all");
+  for (const tree of trees) {
+    if (captured.get(tree)?.kind !== "directory") {
+      throw new Error(`Working-tree snapshot does not hold the captured directory: ${tree}`);
+    }
+  }
+  const touched = /* @__PURE__ */ new Set();
+  for (const relativePath of [...absent].sort(deepestFirst)) {
+    const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (inspected.kind === "entry") import_node_fs.default.rmSync(inspected.absolutePath, { recursive: true, force: true });
+    touched.add(relativePath);
+  }
+  const writtenDirectories = /* @__PURE__ */ new Set();
+  for (const relativePath of absent) writtenDirectories.add(import_node_path.default.posix.dirname(relativePath));
+  for (const [relativePath, entry] of captured) {
+    if (entry.kind !== "directory" && !hasAncestorIn(relativePath, trees)) writtenDirectories.add(import_node_path.default.posix.dirname(relativePath));
+  }
+  for (const directory of writtenDirectories) {
+    let absoluteDirectory = targetRoot;
+    if (directory !== ".") {
+      const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, directory);
+      if (inspected.kind !== "entry" || !inspected.stat.isDirectory()) continue;
+      absoluteDirectory = inspected.absolutePath;
+    }
+    for (const name of import_node_fs.default.readdirSync(absoluteDirectory)) {
+      if (!MIRROR_TEMPORARY_FILE_PATTERN.test(name)) continue;
+      const temporaryPath = import_node_path.default.join(absoluteDirectory, name);
+      if (!import_node_fs.default.lstatSync(temporaryPath).isFile()) continue;
+      import_node_fs.default.rmSync(temporaryPath, { force: true });
+      touched.add(directory === "." ? name : import_node_path.default.posix.join(directory, name));
+    }
+  }
+  for (const [relativePath, entry] of [...captured.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    touched.add(relativePath);
+    if (hasAncestorIn(relativePath, trees)) continue;
+    if (!trees.has(relativePath)) {
+      copyEntry(snapshotRoot, targetRoot, relativePath, entry, "per_entry");
+      continue;
+    }
+    const current = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (current.kind === "blocked") {
+      throw new Error(`Refusing to restore a working-tree directory through a symlink or non-directory: ${current.blockingPath}`);
+    }
+    if (current.kind === "entry" && !current.stat.isDirectory()) {
+      import_node_fs.default.rmSync(current.absolutePath, { recursive: true, force: true });
+    }
+    ensureDirectory(targetRoot, relativePath, entry.mode);
+    mirrorWorkingTree({
+      sourceRoot: import_node_path.default.join(snapshotRoot, ...relativePath.split("/")),
+      targetRoot: import_node_path.default.join(targetRoot, ...relativePath.split("/")),
+      sourceMode: "all",
+      deletionMode: "all"
+    });
+  }
+  return { paths: [...touched].sort(shallowestFirst) };
+}
+function fsyncWorkingTreePaths(root, relativePaths) {
+  root = import_node_path.default.resolve(root);
+  inspectDirectoryRoot(root, { allowMissing: false, label: "Working-tree root" });
+  const directories = /* @__PURE__ */ new Set(["."]);
+  for (const relativePath of relativePaths) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) throw new Error(`Invalid working-tree path: ${relativePath}`);
+    directories.add(import_node_path.default.posix.dirname(normalized));
+    const inspected = inspectRelativePathWithoutFollowingAncestors(root, normalized);
+    if (inspected.kind !== "entry") continue;
+    if (inspected.stat.isDirectory()) directories.add(normalized);
+    else if (inspected.stat.isFile()) fsyncPath(inspected.absolutePath, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
+  }
+  for (const directory of directories) {
+    if (directory === ".") {
+      fsyncPath(root, import_node_fs.default.constants.O_RDONLY);
+      continue;
+    }
+    const inspected = inspectRelativePathWithoutFollowingAncestors(root, directory);
+    if (inspected.kind === "entry" && inspected.stat.isDirectory()) fsyncPath(inspected.absolutePath, import_node_fs.default.constants.O_RDONLY);
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   assertWorkingTreeHasNoPortableGitMetadataAliases,
+  captureWorkingTreeMirrorPlan,
+  fsyncWorkingTreePaths,
   inspectWorkingTree,
-  mirrorWorkingTree
+  mirrorWorkingTree,
+  normalizeWorkingTreeRelativePath,
+  planWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope
 });

package/dist/cjs/workspace-git-sync.cjs

@@ -954,7 +954,7 @@ function parseHydrationTransactionManifest(transactionPath) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const candidate = parsed;
-  if (candidate.version !== 2 && candidate.version !== 3 || !Array.isArray(candidate.mounts)) {
+  if (candidate.version !== 2 && candidate.version !== 3 && candidate.version !== 4 || !Array.isArray(candidate.mounts)) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const parseReceipt = (rawReceipt) => {
@@ -967,6 +967,25 @@ function parseHydrationTransactionManifest(transactionPath) {
   };
   const targetReceipt = parseReceipt(candidate.targetReceipt);
   const receiptBefore = parseReceipt(candidate.receiptBefore);
+  const parseScope = (rawScope, existed) => {
+    if (rawScope === void 0) return void 0;
+    if (candidate.version !== 4 || !existed || !rawScope || typeof rawScope !== "object") {
+      throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+    }
+    const parsePaths = (rawPaths) => {
+      if (!Array.isArray(rawPaths)) throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+      const seen = /* @__PURE__ */ new Set();
+      return rawPaths.map((rawPath) => {
+        if (typeof rawPath !== "string" || (0, import_working_tree_mirror.normalizeWorkingTreeRelativePath)(rawPath) !== rawPath || seen.has(rawPath)) {
+          throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+        }
+        seen.add(rawPath);
+        return rawPath;
+      });
+    };
+    const { absent, trees } = rawScope;
+    return { absent: parsePaths(absent), trees: parsePaths(trees) };
+  };
   const seenIds = /* @__PURE__ */ new Set();
   const seenSnapshots = /* @__PURE__ */ new Set();
   const mounts = candidate.mounts.map((rawMount) => {
@@ -983,10 +1002,20 @@ function parseHydrationTransactionManifest(transactionPath) {
     }
     seenIds.add(mount.id);
     seenSnapshots.add(mount.snapshotName);
-    return mount;
+    const scope = parseScope(rawMount.scope, mount.existed);
+    return {
+      id: mount.id,
+      incarnationKey: mount.incarnationKey,
+      sourcePath: mount.sourcePath,
+      durabilityRootPath: mount.durabilityRootPath,
+      workspaceRelativePath: mount.workspaceRelativePath,
+      existed: mount.existed,
+      snapshotName: mount.snapshotName,
+      ...scope ? { scope } : {}
+    };
   });
   return {
-    version: 3,
+    version: candidate.version === 4 ? 4 : 3,
     targetReceipt,
     receiptBefore,
     mounts
@@ -1008,6 +1037,7 @@ function hydrationTransactionCommitted(transactionPath) {
 }
 function restoreHydrationTransaction(workspacePath, manifest) {
   const transactionPath = hydrationTransactionPath(workspacePath);
+  const durabilityScopes = /* @__PURE__ */ new Map();
   for (const mount of manifest.mounts) {
     (0, import_workspace_mount_boundary.assertManagedDirectoryPath)({
       trustedRoot: mount.durabilityRootPath,
@@ -1023,6 +1053,11 @@ function restoreHydrationTransaction(workspacePath, manifest) {
     if (!snapshotStatus.isDirectory() || snapshotStatus.isSymbolicLink()) {
       throw new Error(`Workspace hydration snapshot is not a regular directory: ${snapshotPath}`);
     }
+    if (mount.scope) {
+      const restored = (0, import_working_tree_mirror.restoreWorkingTreeMirrorScope)({ snapshotRoot: snapshotPath, targetRoot: mount.sourcePath, scope: mount.scope });
+      durabilityScopes.set(mount.id, restored.paths);
+      continue;
+    }
     (0, import_working_tree_mirror.mirrorWorkingTree)({ sourceRoot: snapshotPath, targetRoot: mount.sourcePath, sourceMode: "all", deletionMode: "all" });
   }
   fsyncHydratedWorkspaceMounts(
@@ -1031,7 +1066,8 @@ function restoreHydrationTransaction(workspacePath, manifest) {
       hydrationIncarnationKey: mount.incarnationKey,
       sourceMode: "all",
       hydrateDeletionMode: "all"
-    }))
+    })),
+    durabilityScopes
   );
 }
 function recoverPendingHydrationTransaction(workspacePath) {
@@ -1075,57 +1111,80 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
   const transactionPath = hydrationTransactionPath(workspacePath);
   const stagingPath = import_node_path.default.join(stateDirectory, `.workspace-hydration-transaction.${process.pid}.${crypto.randomUUID()}.tmp`);
   import_node_fs.default.mkdirSync(stagingPath, { mode: 448 });
+  const durabilityScopes = /* @__PURE__ */ new Map();
   try {
     const snapshotRoot = import_node_path.default.join(stagingPath, "mounts");
     import_node_fs.default.mkdirSync(snapshotRoot, { mode: 448 });
-    const manifest = {
-      version: 3,
-      targetReceipt,
-      receiptBefore: readHydratedWorkspaceReceipt(workspacePath),
-      mounts: mounts.map((mount, index) => {
-        const sourcePath = import_node_path.default.resolve(mount.sourcePath);
-        const durabilityRootPath = import_node_path.default.resolve(mount.durabilityRootPath);
+    const receiptBefore = readHydratedWorkspaceReceipt(workspacePath);
+    const manifestMounts = mounts.map((mount, index) => {
+      const sourcePath = import_node_path.default.resolve(mount.sourcePath);
+      const durabilityRootPath = import_node_path.default.resolve(mount.durabilityRootPath);
+      (0, import_workspace_mount_boundary.assertManagedDirectoryPath)({
+        trustedRoot: durabilityRootPath,
+        candidate: sourcePath,
+        label: `Workspace hydration snapshot mount ${mount.id}`
+      });
+      const sourceStatus = lstatIfExists(sourcePath);
+      if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
+        throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
+      }
+      const snapshotName = String(index);
+      const snapshotPath = import_node_path.default.join(snapshotRoot, snapshotName);
+      import_node_fs.default.mkdirSync(snapshotPath, { mode: 448 });
+      let scope;
+      if (sourceStatus && mount.hydrateDeletionMode === "git") {
+        const outerPath = workspaceMountOuterPath(workspacePath, mount);
         (0, import_workspace_mount_boundary.assertManagedDirectoryPath)({
-          trustedRoot: durabilityRootPath,
-          candidate: sourcePath,
-          label: `Workspace hydration snapshot mount ${mount.id}`
+          trustedRoot: workspacePath,
+          candidate: outerPath,
+          label: `Workspace mount ${mount.id} outer source`
         });
-        const sourceStatus = lstatIfExists(sourcePath);
-        if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
-          throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
-        }
-        const snapshotName = String(index);
-        const snapshotPath = import_node_path.default.join(snapshotRoot, snapshotName);
-        import_node_fs.default.mkdirSync(snapshotPath, { mode: 448 });
-        if (sourceStatus) {
-          (0, import_working_tree_mirror.mirrorWorkingTree)({
-            sourceRoot: sourcePath,
-            targetRoot: snapshotPath,
-            sourceMode: "all",
-            deletionMode: "all",
-            // This tree is still private and the source authority is untouched.
-            // The single recursive barrier below makes the complete snapshot
-            // durable before its directory entry is published or hydration starts.
-            durability: "deferred_private_staging"
-          });
-        }
-        return {
-          id: mount.id,
-          incarnationKey: mount.hydrationIncarnationKey,
-          sourcePath,
-          durabilityRootPath,
-          workspaceRelativePath: mount.workspaceRelativePath,
-          existed: Boolean(sourceStatus),
-          snapshotName
-        };
-      })
+        const plan = (0, import_working_tree_mirror.planWorkingTreeMirror)({ sourceRoot: outerPath, targetRoot: sourcePath, sourceMode: "all", deletionMode: "git" });
+        scope = (0, import_working_tree_mirror.captureWorkingTreeMirrorPlan)({
+          plan,
+          targetRoot: sourcePath,
+          snapshotRoot: snapshotPath,
+          // Same private-staging deferral as the complete snapshot below.
+          durability: "deferred_private_staging"
+        });
+        durabilityScopes.set(mount.id, [...plan.desired.keys()]);
+      } else if (sourceStatus) {
+        (0, import_working_tree_mirror.mirrorWorkingTree)({
+          sourceRoot: sourcePath,
+          targetRoot: snapshotPath,
+          sourceMode: "all",
+          deletionMode: "all",
+          // This tree is still private and the source authority is untouched.
+          // The single recursive barrier below makes the complete snapshot
+          // durable before its directory entry is published or hydration starts.
+          durability: "deferred_private_staging"
+        });
+      }
+      return {
+        id: mount.id,
+        incarnationKey: mount.hydrationIncarnationKey,
+        sourcePath,
+        durabilityRootPath,
+        workspaceRelativePath: mount.workspaceRelativePath,
+        existed: Boolean(sourceStatus),
+        snapshotName,
+        ...scope ? { scope } : {}
+      };
+    });
+    const manifest = {
+      // Older workers reject version 4, so a scoped snapshot can never be
+      // replayed as a complete copy after a downgrade.
+      version: manifestMounts.some((mount) => mount.scope) ? 4 : 3,
+      targetReceipt,
+      receiptBefore,
+      mounts: manifestMounts
     };
     writePrivateFileDurably(import_node_path.default.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest)}
 `);
     fsyncTree(stagingPath);
     import_node_fs.default.renameSync(stagingPath, transactionPath);
     fsyncDirectory(stateDirectory);
-    return manifest;
+    return { manifest, durabilityScopes };
   } catch (error) {
     import_node_fs.default.rmSync(stagingPath, { recursive: true, force: true });
     fsyncDirectory(stateDirectory);
@@ -1137,7 +1196,11 @@ function markHydrationTransactionDurable(workspacePath) {
   writePrivateFileDurably(import_node_path.default.join(transactionPath, "committed"), "committed\n");
   fsyncDirectory(transactionPath);
 }
-function fsyncHydratedWorkspaceMount(mount) {
+function gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus) {
+  if (mount.hydrateDeletionMode !== "git" || !sourceStatus.isDirectory() || !lstatIfExists(import_node_path.default.join(sourcePath, ".git"))) return null;
+  return [...(0, import_working_tree_mirror.inspectWorkingTree)(sourcePath, "git").keys()];
+}
+function fsyncHydratedWorkspaceMount(mount, scope) {
   (0, import_workspace_mount_boundary.assertManagedDirectoryPath)({
     trustedRoot: mount.durabilityRootPath,
     candidate: mount.sourcePath,
@@ -1162,7 +1225,17 @@ function fsyncHydratedWorkspaceMount(mount) {
       import_node_fs.default.closeSync(descriptor);
     }
   };
-  if (import_node_fs.default.existsSync(mount.sourcePath)) syncEntry(mount.sourcePath, true);
+  const sourcePath = import_node_path.default.resolve(mount.sourcePath);
+  const sourceStatus = lstatIfExists(sourcePath);
+  if (sourceStatus) {
+    const paths = scope ?? gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus);
+    if (paths) {
+      if (!sourceStatus.isDirectory()) throw new Error(`Workspace mount ${mount.id} source is not a regular directory: ${sourcePath}`);
+      (0, import_working_tree_mirror.fsyncWorkingTreePaths)(sourcePath, paths);
+    } else {
+      syncEntry(sourcePath, true);
+    }
+  }
   const durabilityRoot = import_node_path.default.resolve(mount.durabilityRootPath);
   let boundaryParent = import_node_path.default.dirname(import_node_path.default.resolve(mount.sourcePath));
   while (true) {
@@ -1181,8 +1254,8 @@ function fsyncHydratedWorkspaceMount(mount) {
     boundaryParent = nextParent;
   }
 }
-function fsyncHydratedWorkspaceMounts(mounts) {
-  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount);
+function fsyncHydratedWorkspaceMounts(mounts, scopes = /* @__PURE__ */ new Map()) {
+  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount, scopes.get(mount.id));
 }
 function workspaceIsShallow(workspacePath) {
   return gitResult(workspacePath, ["rev-parse", "--is-shallow-repository"]).stdout === "true";
@@ -1431,6 +1504,9 @@ function restoreDeferredWorkspaceMountsFromHead(workspacePath, mounts) {
     }
   }
 }
+function workspaceMountOuterPath(workspacePath, mount) {
+  return import_node_path.default.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+}
 function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
   const hydratedMountIds = [];
   const skippedMountIds = [];
@@ -1439,7 +1515,7 @@ function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
       skippedMountIds.push(mount.id);
       continue;
     }
-    const sourceRoot = import_node_path.default.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    const sourceRoot = workspaceMountOuterPath(workspacePath, mount);
     (0, import_workspace_mount_boundary.assertManagedDirectoryPath)({
       trustedRoot: workspacePath,
       candidate: sourceRoot,
@@ -1545,14 +1621,14 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
   }
   const selection = computeSelection();
   const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
-  const manifest = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
+  const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
   try {
     const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
     const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
     if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
       throw new Error("Workspace hydration did not include every required mount");
     }
-    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts);
+    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
     markHydrationTransactionDurable(workspacePath);
     if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
     removeHydrationTransaction(workspacePath);

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "type": "module"
 }

package/dist/mjs/working-tree-mirror.mjs

@@ -151,14 +151,55 @@ function addParentDirectories(entries, root) {
     }
   }
 }
-function inspectWorkingTree(root, mode) {
+function gitlinkPaths(root) {
+  const result = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "ls-files",
+      "-z",
+      "--stage",
+      "--",
+      "."
+    ],
+    {
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: workerGitProcessEnvironment()
+    }
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`Inspect Git index gitlinks: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+  }
+  const gitlinks = /* @__PURE__ */ new Set();
+  for (const record of result.stdout.toString().split("\0")) {
+    const match = /^160000 [0-9a-f]+ [0-3]\t(.+)$/su.exec(record);
+    if (!match) continue;
+    const normalized = normalizeRelativePath(match[1]);
+    if (normalized) gitlinks.add(normalized);
+  }
+  return gitlinks;
+}
+function directoryIsEmpty(root, relativePath) {
+  const inspected = inspectRelativePathWithoutFollowingAncestors(root, relativePath);
+  return inspected.kind === "entry" && inspected.stat.isDirectory() && fs.readdirSync(inspected.absolutePath).length === 0;
+}
+function inspectWorkingTree(root, mode, options = {}) {
   const entries = /* @__PURE__ */ new Map();
   root = path.resolve(root);
   if (!inspectDirectoryRoot(root, { allowMissing: true, label: "Working-tree root" })) return entries;
   if (mode === "all") {
     for (const child of fs.readdirSync(root).sort()) addEntry(entries, root, child, true);
   } else {
+    const omittedGitlinks = options.omitUnpopulatedGitlinks ? gitlinkPaths(root) : null;
     for (const relativePath of gitEligibleRoots(root)) {
+      if (omittedGitlinks?.has(relativePath) && directoryIsEmpty(root, relativePath)) continue;
       addEntry(entries, root, relativePath, true);
     }
   }
@@ -332,7 +373,9 @@ function mirrorWorkingTree(input) {
   }
   inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
   const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
-  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all");
+  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
+    omitUnpopulatedGitlinks: input.deletionMode === "git"
+  });
   for (const relativePath of [...existing.keys()].sort((left, right) => right.split("/").length - left.split("/").length)) {
     if (!desired.has(relativePath)) removeEntry(targetRoot, relativePath);
   }
@@ -343,8 +386,212 @@ function mirrorWorkingTree(input) {
   }
   return { paths: [...desired.keys()].filter((relativePath) => desired.get(relativePath)?.kind !== "directory").sort() };
 }
+function normalizeWorkingTreeRelativePath(value) {
+  return normalizeRelativePath(value);
+}
+const MIRROR_TEMPORARY_FILE_PATTERN = /^\.r5d-working-tree-mirror-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/u;
+function relativeDepth(relativePath) {
+  return relativePath.split("/").length;
+}
+function shallowestFirst(left, right) {
+  return relativeDepth(left) - relativeDepth(right) || left.localeCompare(right);
+}
+function deepestFirst(left, right) {
+  return relativeDepth(right) - relativeDepth(left) || left.localeCompare(right);
+}
+function hasAncestorIn(relativePath, ancestors) {
+  let parent = path.posix.dirname(relativePath);
+  while (parent !== ".") {
+    if (ancestors.has(parent)) return true;
+    parent = path.posix.dirname(parent);
+  }
+  return false;
+}
+function treeEntryFromStat(stat, absolutePath) {
+  if (stat.isSymbolicLink()) return { kind: "symlink", mode: stat.mode, target: fs.readlinkSync(absolutePath) };
+  if (stat.isFile()) return { kind: "file", mode: stat.mode, size: stat.size };
+  if (stat.isDirectory()) return { kind: "directory", mode: stat.mode };
+  return null;
+}
+function fsyncPath(targetPath, flags) {
+  const descriptor = fs.openSync(targetPath, flags);
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function planWorkingTreeMirror(input) {
+  const sourceRoot = path.resolve(input.sourceRoot);
+  const targetRoot = path.resolve(input.targetRoot);
+  const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
+  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
+    omitUnpopulatedGitlinks: input.deletionMode === "git"
+  });
+  const replaced = /* @__PURE__ */ new Map();
+  const absent = [];
+  for (const [relativePath, entry] of existing) {
+    if (!desired.has(relativePath)) replaced.set(relativePath, entry);
+  }
+  for (const [relativePath, entry] of desired) {
+    const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (target.kind !== "entry") {
+      absent.push(relativePath);
+      continue;
+    }
+    const { absolutePath, stat } = target;
+    if (entry.kind === "directory") {
+      if (stat.isDirectory()) continue;
+    } else if (entry.kind === "symlink") {
+      if (stat.isSymbolicLink() && fs.readlinkSync(absolutePath) === entry.target) continue;
+    } else if (stat.isFile() && filesEqual(path.join(sourceRoot, ...relativePath.split("/")), absolutePath, entry)) {
+      continue;
+    }
+    const current = treeEntryFromStat(stat, absolutePath);
+    if (current) replaced.set(relativePath, current);
+    else absent.push(relativePath);
+  }
+  const replacedDirectories = new Set(
+    [...replaced].filter(([, entry]) => entry.kind === "directory").map(([relativePath]) => relativePath)
+  );
+  for (const relativePath of [...replaced.keys()]) {
+    if (hasAncestorIn(relativePath, replacedDirectories)) replaced.delete(relativePath);
+  }
+  return {
+    desired,
+    replaced,
+    absent: absent.filter((relativePath) => !hasAncestorIn(relativePath, replacedDirectories)).sort(shallowestFirst)
+  };
+}
+function captureWorkingTreeMirrorPlan(input) {
+  const targetRoot = path.resolve(input.targetRoot);
+  const snapshotRoot = path.resolve(input.snapshotRoot);
+  const durability = input.durability ?? "per_entry";
+  inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
+  if (!inspectDirectoryRoot(snapshotRoot, { allowMissing: true, label: "Working-tree snapshot root" })) {
+    fs.mkdirSync(snapshotRoot, { recursive: true });
+  }
+  const trees = [];
+  for (const [relativePath, entry] of [...input.plan.replaced.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    if (entry.kind !== "directory") {
+      copyEntry(targetRoot, snapshotRoot, relativePath, entry, durability);
+      continue;
+    }
+    const source = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (source.kind !== "entry" || !source.stat.isDirectory()) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${path.join(targetRoot, ...relativePath.split("/"))}`);
+    }
+    ensureDirectory(snapshotRoot, relativePath, entry.mode);
+    mirrorWorkingTree({
+      sourceRoot: source.absolutePath,
+      targetRoot: path.join(snapshotRoot, ...relativePath.split("/")),
+      sourceMode: "all",
+      deletionMode: "all",
+      durability
+    });
+    trees.push(relativePath);
+  }
+  return { absent: [...input.plan.absent].sort(shallowestFirst), trees: trees.sort(shallowestFirst) };
+}
+function restoreWorkingTreeMirrorScope(input) {
+  const snapshotRoot = path.resolve(input.snapshotRoot);
+  const targetRoot = path.resolve(input.targetRoot);
+  inspectDirectoryRoot(snapshotRoot, { allowMissing: false, label: "Working-tree snapshot root" });
+  if (!inspectDirectoryRoot(targetRoot, { allowMissing: true, label: "Working-tree target root" })) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+  }
+  const normalize = (relativePath) => {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) throw new Error(`Invalid working-tree scope path: ${relativePath}`);
+    return normalized;
+  };
+  const absent = input.scope.absent.map(normalize);
+  const trees = new Set(input.scope.trees.map(normalize));
+  const captured = inspectWorkingTree(snapshotRoot, "all");
+  for (const tree of trees) {
+    if (captured.get(tree)?.kind !== "directory") {
+      throw new Error(`Working-tree snapshot does not hold the captured directory: ${tree}`);
+    }
+  }
+  const touched = /* @__PURE__ */ new Set();
+  for (const relativePath of [...absent].sort(deepestFirst)) {
+    const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (inspected.kind === "entry") fs.rmSync(inspected.absolutePath, { recursive: true, force: true });
+    touched.add(relativePath);
+  }
+  const writtenDirectories = /* @__PURE__ */ new Set();
+  for (const relativePath of absent) writtenDirectories.add(path.posix.dirname(relativePath));
+  for (const [relativePath, entry] of captured) {
+    if (entry.kind !== "directory" && !hasAncestorIn(relativePath, trees)) writtenDirectories.add(path.posix.dirname(relativePath));
+  }
+  for (const directory of writtenDirectories) {
+    let absoluteDirectory = targetRoot;
+    if (directory !== ".") {
+      const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, directory);
+      if (inspected.kind !== "entry" || !inspected.stat.isDirectory()) continue;
+      absoluteDirectory = inspected.absolutePath;
+    }
+    for (const name of fs.readdirSync(absoluteDirectory)) {
+      if (!MIRROR_TEMPORARY_FILE_PATTERN.test(name)) continue;
+      const temporaryPath = path.join(absoluteDirectory, name);
+      if (!fs.lstatSync(temporaryPath).isFile()) continue;
+      fs.rmSync(temporaryPath, { force: true });
+      touched.add(directory === "." ? name : path.posix.join(directory, name));
+    }
+  }
+  for (const [relativePath, entry] of [...captured.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    touched.add(relativePath);
+    if (hasAncestorIn(relativePath, trees)) continue;
+    if (!trees.has(relativePath)) {
+      copyEntry(snapshotRoot, targetRoot, relativePath, entry, "per_entry");
+      continue;
+    }
+    const current = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (current.kind === "blocked") {
+      throw new Error(`Refusing to restore a working-tree directory through a symlink or non-directory: ${current.blockingPath}`);
+    }
+    if (current.kind === "entry" && !current.stat.isDirectory()) {
+      fs.rmSync(current.absolutePath, { recursive: true, force: true });
+    }
+    ensureDirectory(targetRoot, relativePath, entry.mode);
+    mirrorWorkingTree({
+      sourceRoot: path.join(snapshotRoot, ...relativePath.split("/")),
+      targetRoot: path.join(targetRoot, ...relativePath.split("/")),
+      sourceMode: "all",
+      deletionMode: "all"
+    });
+  }
+  return { paths: [...touched].sort(shallowestFirst) };
+}
+function fsyncWorkingTreePaths(root, relativePaths) {
+  root = path.resolve(root);
+  inspectDirectoryRoot(root, { allowMissing: false, label: "Working-tree root" });
+  const directories = /* @__PURE__ */ new Set(["."]);
+  for (const relativePath of relativePaths) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) throw new Error(`Invalid working-tree path: ${relativePath}`);
+    directories.add(path.posix.dirname(normalized));
+    const inspected = inspectRelativePathWithoutFollowingAncestors(root, normalized);
+    if (inspected.kind !== "entry") continue;
+    if (inspected.stat.isDirectory()) directories.add(normalized);
+    else if (inspected.stat.isFile()) fsyncPath(inspected.absolutePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  }
+  for (const directory of directories) {
+    if (directory === ".") {
+      fsyncPath(root, fs.constants.O_RDONLY);
+      continue;
+    }
+    const inspected = inspectRelativePathWithoutFollowingAncestors(root, directory);
+    if (inspected.kind === "entry" && inspected.stat.isDirectory()) fsyncPath(inspected.absolutePath, fs.constants.O_RDONLY);
+  }
+}
 export {
   assertWorkingTreeHasNoPortableGitMetadataAliases,
+  captureWorkingTreeMirrorPlan,
+  fsyncWorkingTreePaths,
   inspectWorkingTree,
-  mirrorWorkingTree
+  mirrorWorkingTree,
+  normalizeWorkingTreeRelativePath,
+  planWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope
 };

package/dist/mjs/workspace-git-sync.mjs

@@ -6,7 +6,15 @@ import {
   mergeWorkspaceProjectionMount,
   workspaceMergeProjectionSupport
 } from "./workspace-merge-projection.mjs";
-import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
+import {
+  captureWorkingTreeMirrorPlan,
+  fsyncWorkingTreePaths,
+  inspectWorkingTree,
+  mirrorWorkingTree,
+  normalizeWorkingTreeRelativePath,
+  planWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope
+} from "./working-tree-mirror.mjs";
 import { assertManagedDirectoryPath } from "./workspace-mount-boundary.mjs";
 const WORKSPACE_GIT_BRANCH = "main";
 const MAX_WORKSPACE_GIT_DIFF_BYTES = 5 * 1024 * 1024;
@@ -909,7 +917,7 @@ function parseHydrationTransactionManifest(transactionPath) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const candidate = parsed;
-  if (candidate.version !== 2 && candidate.version !== 3 || !Array.isArray(candidate.mounts)) {
+  if (candidate.version !== 2 && candidate.version !== 3 && candidate.version !== 4 || !Array.isArray(candidate.mounts)) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const parseReceipt = (rawReceipt) => {
@@ -922,6 +930,25 @@ function parseHydrationTransactionManifest(transactionPath) {
   };
   const targetReceipt = parseReceipt(candidate.targetReceipt);
   const receiptBefore = parseReceipt(candidate.receiptBefore);
+  const parseScope = (rawScope, existed) => {
+    if (rawScope === void 0) return void 0;
+    if (candidate.version !== 4 || !existed || !rawScope || typeof rawScope !== "object") {
+      throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+    }
+    const parsePaths = (rawPaths) => {
+      if (!Array.isArray(rawPaths)) throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+      const seen = /* @__PURE__ */ new Set();
+      return rawPaths.map((rawPath) => {
+        if (typeof rawPath !== "string" || normalizeWorkingTreeRelativePath(rawPath) !== rawPath || seen.has(rawPath)) {
+          throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+        }
+        seen.add(rawPath);
+        return rawPath;
+      });
+    };
+    const { absent, trees } = rawScope;
+    return { absent: parsePaths(absent), trees: parsePaths(trees) };
+  };
   const seenIds = /* @__PURE__ */ new Set();
   const seenSnapshots = /* @__PURE__ */ new Set();
   const mounts = candidate.mounts.map((rawMount) => {
@@ -938,10 +965,20 @@ function parseHydrationTransactionManifest(transactionPath) {
     }
     seenIds.add(mount.id);
     seenSnapshots.add(mount.snapshotName);
-    return mount;
+    const scope = parseScope(rawMount.scope, mount.existed);
+    return {
+      id: mount.id,
+      incarnationKey: mount.incarnationKey,
+      sourcePath: mount.sourcePath,
+      durabilityRootPath: mount.durabilityRootPath,
+      workspaceRelativePath: mount.workspaceRelativePath,
+      existed: mount.existed,
+      snapshotName: mount.snapshotName,
+      ...scope ? { scope } : {}
+    };
   });
   return {
-    version: 3,
+    version: candidate.version === 4 ? 4 : 3,
     targetReceipt,
     receiptBefore,
     mounts
@@ -963,6 +1000,7 @@ function hydrationTransactionCommitted(transactionPath) {
 }
 function restoreHydrationTransaction(workspacePath, manifest) {
   const transactionPath = hydrationTransactionPath(workspacePath);
+  const durabilityScopes = /* @__PURE__ */ new Map();
   for (const mount of manifest.mounts) {
     assertManagedDirectoryPath({
       trustedRoot: mount.durabilityRootPath,
@@ -978,6 +1016,11 @@ function restoreHydrationTransaction(workspacePath, manifest) {
     if (!snapshotStatus.isDirectory() || snapshotStatus.isSymbolicLink()) {
       throw new Error(`Workspace hydration snapshot is not a regular directory: ${snapshotPath}`);
     }
+    if (mount.scope) {
+      const restored = restoreWorkingTreeMirrorScope({ snapshotRoot: snapshotPath, targetRoot: mount.sourcePath, scope: mount.scope });
+      durabilityScopes.set(mount.id, restored.paths);
+      continue;
+    }
     mirrorWorkingTree({ sourceRoot: snapshotPath, targetRoot: mount.sourcePath, sourceMode: "all", deletionMode: "all" });
   }
   fsyncHydratedWorkspaceMounts(
@@ -986,7 +1029,8 @@ function restoreHydrationTransaction(workspacePath, manifest) {
       hydrationIncarnationKey: mount.incarnationKey,
       sourceMode: "all",
       hydrateDeletionMode: "all"
-    }))
+    })),
+    durabilityScopes
   );
 }
 function recoverPendingHydrationTransaction(workspacePath) {
@@ -1030,57 +1074,80 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
   const transactionPath = hydrationTransactionPath(workspacePath);
   const stagingPath = path.join(stateDirectory, `.workspace-hydration-transaction.${process.pid}.${crypto.randomUUID()}.tmp`);
   fs.mkdirSync(stagingPath, { mode: 448 });
+  const durabilityScopes = /* @__PURE__ */ new Map();
   try {
     const snapshotRoot = path.join(stagingPath, "mounts");
     fs.mkdirSync(snapshotRoot, { mode: 448 });
-    const manifest = {
-      version: 3,
-      targetReceipt,
-      receiptBefore: readHydratedWorkspaceReceipt(workspacePath),
-      mounts: mounts.map((mount, index) => {
-        const sourcePath = path.resolve(mount.sourcePath);
-        const durabilityRootPath = path.resolve(mount.durabilityRootPath);
+    const receiptBefore = readHydratedWorkspaceReceipt(workspacePath);
+    const manifestMounts = mounts.map((mount, index) => {
+      const sourcePath = path.resolve(mount.sourcePath);
+      const durabilityRootPath = path.resolve(mount.durabilityRootPath);
+      assertManagedDirectoryPath({
+        trustedRoot: durabilityRootPath,
+        candidate: sourcePath,
+        label: `Workspace hydration snapshot mount ${mount.id}`
+      });
+      const sourceStatus = lstatIfExists(sourcePath);
+      if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
+        throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
+      }
+      const snapshotName = String(index);
+      const snapshotPath = path.join(snapshotRoot, snapshotName);
+      fs.mkdirSync(snapshotPath, { mode: 448 });
+      let scope;
+      if (sourceStatus && mount.hydrateDeletionMode === "git") {
+        const outerPath = workspaceMountOuterPath(workspacePath, mount);
         assertManagedDirectoryPath({
-          trustedRoot: durabilityRootPath,
-          candidate: sourcePath,
-          label: `Workspace hydration snapshot mount ${mount.id}`
+          trustedRoot: workspacePath,
+          candidate: outerPath,
+          label: `Workspace mount ${mount.id} outer source`
         });
-        const sourceStatus = lstatIfExists(sourcePath);
-        if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
-          throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
-        }
-        const snapshotName = String(index);
-        const snapshotPath = path.join(snapshotRoot, snapshotName);
-        fs.mkdirSync(snapshotPath, { mode: 448 });
-        if (sourceStatus) {
-          mirrorWorkingTree({
-            sourceRoot: sourcePath,
-            targetRoot: snapshotPath,
-            sourceMode: "all",
-            deletionMode: "all",
-            // This tree is still private and the source authority is untouched.
-            // The single recursive barrier below makes the complete snapshot
-            // durable before its directory entry is published or hydration starts.
-            durability: "deferred_private_staging"
-          });
-        }
-        return {
-          id: mount.id,
-          incarnationKey: mount.hydrationIncarnationKey,
-          sourcePath,
-          durabilityRootPath,
-          workspaceRelativePath: mount.workspaceRelativePath,
-          existed: Boolean(sourceStatus),
-          snapshotName
-        };
-      })
+        const plan = planWorkingTreeMirror({ sourceRoot: outerPath, targetRoot: sourcePath, sourceMode: "all", deletionMode: "git" });
+        scope = captureWorkingTreeMirrorPlan({
+          plan,
+          targetRoot: sourcePath,
+          snapshotRoot: snapshotPath,
+          // Same private-staging deferral as the complete snapshot below.
+          durability: "deferred_private_staging"
+        });
+        durabilityScopes.set(mount.id, [...plan.desired.keys()]);
+      } else if (sourceStatus) {
+        mirrorWorkingTree({
+          sourceRoot: sourcePath,
+          targetRoot: snapshotPath,
+          sourceMode: "all",
+          deletionMode: "all",
+          // This tree is still private and the source authority is untouched.
+          // The single recursive barrier below makes the complete snapshot
+          // durable before its directory entry is published or hydration starts.
+          durability: "deferred_private_staging"
+        });
+      }
+      return {
+        id: mount.id,
+        incarnationKey: mount.hydrationIncarnationKey,
+        sourcePath,
+        durabilityRootPath,
+        workspaceRelativePath: mount.workspaceRelativePath,
+        existed: Boolean(sourceStatus),
+        snapshotName,
+        ...scope ? { scope } : {}
+      };
+    });
+    const manifest = {
+      // Older workers reject version 4, so a scoped snapshot can never be
+      // replayed as a complete copy after a downgrade.
+      version: manifestMounts.some((mount) => mount.scope) ? 4 : 3,
+      targetReceipt,
+      receiptBefore,
+      mounts: manifestMounts
     };
     writePrivateFileDurably(path.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest)}
 `);
     fsyncTree(stagingPath);
     fs.renameSync(stagingPath, transactionPath);
     fsyncDirectory(stateDirectory);
-    return manifest;
+    return { manifest, durabilityScopes };
   } catch (error) {
     fs.rmSync(stagingPath, { recursive: true, force: true });
     fsyncDirectory(stateDirectory);
@@ -1092,7 +1159,11 @@ function markHydrationTransactionDurable(workspacePath) {
   writePrivateFileDurably(path.join(transactionPath, "committed"), "committed\n");
   fsyncDirectory(transactionPath);
 }
-function fsyncHydratedWorkspaceMount(mount) {
+function gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus) {
+  if (mount.hydrateDeletionMode !== "git" || !sourceStatus.isDirectory() || !lstatIfExists(path.join(sourcePath, ".git"))) return null;
+  return [...inspectWorkingTree(sourcePath, "git").keys()];
+}
+function fsyncHydratedWorkspaceMount(mount, scope) {
   assertManagedDirectoryPath({
     trustedRoot: mount.durabilityRootPath,
     candidate: mount.sourcePath,
@@ -1117,7 +1188,17 @@ function fsyncHydratedWorkspaceMount(mount) {
       fs.closeSync(descriptor);
     }
   };
-  if (fs.existsSync(mount.sourcePath)) syncEntry(mount.sourcePath, true);
+  const sourcePath = path.resolve(mount.sourcePath);
+  const sourceStatus = lstatIfExists(sourcePath);
+  if (sourceStatus) {
+    const paths = scope ?? gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus);
+    if (paths) {
+      if (!sourceStatus.isDirectory()) throw new Error(`Workspace mount ${mount.id} source is not a regular directory: ${sourcePath}`);
+      fsyncWorkingTreePaths(sourcePath, paths);
+    } else {
+      syncEntry(sourcePath, true);
+    }
+  }
   const durabilityRoot = path.resolve(mount.durabilityRootPath);
   let boundaryParent = path.dirname(path.resolve(mount.sourcePath));
   while (true) {
@@ -1136,8 +1217,8 @@ function fsyncHydratedWorkspaceMount(mount) {
     boundaryParent = nextParent;
   }
 }
-function fsyncHydratedWorkspaceMounts(mounts) {
-  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount);
+function fsyncHydratedWorkspaceMounts(mounts, scopes = /* @__PURE__ */ new Map()) {
+  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount, scopes.get(mount.id));
 }
 function workspaceIsShallow(workspacePath) {
   return gitResult(workspacePath, ["rev-parse", "--is-shallow-repository"]).stdout === "true";
@@ -1386,6 +1467,9 @@ function restoreDeferredWorkspaceMountsFromHead(workspacePath, mounts) {
     }
   }
 }
+function workspaceMountOuterPath(workspacePath, mount) {
+  return path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+}
 function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
   const hydratedMountIds = [];
   const skippedMountIds = [];
@@ -1394,7 +1478,7 @@ function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
       skippedMountIds.push(mount.id);
       continue;
     }
-    const sourceRoot = path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    const sourceRoot = workspaceMountOuterPath(workspacePath, mount);
     assertManagedDirectoryPath({
       trustedRoot: workspacePath,
       candidate: sourceRoot,
@@ -1500,14 +1584,14 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
   }
   const selection = computeSelection();
   const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
-  const manifest = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
+  const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
   try {
     const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
     const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
     if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
       throw new Error("Workspace hydration did not include every required mount");
     }
-    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts);
+    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
     markHydrationTransactionDurable(workspacePath);
     if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
     removeHydrationTransaction(workspacePath);

package/dist/types/working-tree-mirror.d.ts

@@ -20,7 +20,14 @@ export type TreeEntry = {
  * every portable alias must be remediated before the old tree is retired.
  */
 export declare function assertWorkingTreeHasNoPortableGitMetadataAliases(root: string): void;
-export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode): Map<string, TreeEntry>;
+export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: {
+    /**
+     * Leave an uninitialized submodule (index gitlink whose directory is
+     * empty) out of a Git-mode inspection. Its empty directory is what keeps
+     * `git status` clean, so a deletion set must never remove it.
+     */
+    omitUnpopulatedGitlinks?: boolean;
+}): Map<string, TreeEntry>;
 export declare function mirrorWorkingTree(input: {
     sourceRoot: string;
     targetRoot: string;
@@ -35,3 +42,75 @@ export declare function mirrorWorkingTree(input: {
 }): {
     paths: string[];
 };
+/** Canonical relative form used by mirror plans and scopes, or null when the value is unsafe. */
+export declare function normalizeWorkingTreeRelativePath(value: string): string | null;
+export type WorkingTreeMirrorPlan = {
+    /** Every target path the mirror creates, rewrites, or verifies, ancestor directories included. */
+    desired: Map<string, TreeEntry>;
+    /**
+     * Target entries the mirror removes or overwrites, as they are before it
+     * runs. A directory entry means the whole subtree goes, ignored files
+     * included; entries beneath it are folded into it.
+     */
+    replaced: Map<string, TreeEntry>;
+    /** Desired paths that have no target entry yet. */
+    absent: string[];
+};
+/**
+ * Compute exactly which target entries `mirrorWorkingTree` would remove,
+ * overwrite, or create for the same input, without changing anything. The
+ * removal set is the target's deletion-mode file set minus the desired paths.
+ * A desired path replaces its target entry when the kinds differ, a symlink
+ * points elsewhere, or a file's bytes or mode differ; an equal entry is left
+ * alone, so the plan covers only what the mirror actually touches. A Git
+ * target's ignored trees appear only where a desired path lands on them.
+ */
+export declare function planWorkingTreeMirror(input: {
+    sourceRoot: string;
+    targetRoot: string;
+    sourceMode: WorkingTreeSourceMode;
+    deletionMode: WorkingTreeDeletionMode;
+}): WorkingTreeMirrorPlan;
+export type WorkingTreeMirrorScope = {
+    /** Desired paths that did not exist before the mirror ran; a restore removes them. */
+    absent: string[];
+    /** Directories captured whole; a restore makes them identical to the snapshot again. */
+    trees: string[];
+};
+/**
+ * Copy the entries a mirror plan replaces into `snapshotRoot` at their
+ * target-relative paths, so that `restoreWorkingTreeMirrorScope` can undo the
+ * mirror. Files and symlinks are copied individually and a replaced directory
+ * is copied whole; ancestor directories appear only as containers. Returns
+ * the scope that must be kept beside the snapshot.
+ */
+export declare function captureWorkingTreeMirrorPlan(input: {
+    plan: WorkingTreeMirrorPlan;
+    targetRoot: string;
+    snapshotRoot: string;
+    durability?: WorkingTreeMirrorDurability;
+}): WorkingTreeMirrorScope;
+/**
+ * Undo a mirror whose plan was captured with `captureWorkingTreeMirrorPlan`:
+ * remove everything the mirror may have created, sweep its interrupted
+ * temporary files, and put every captured entry back. Entries the plan did
+ * not cover (a Git target's ignored files, for instance) are never read or
+ * written. Safe to repeat after a partial run. Returns the target-relative
+ * paths it removed or restored, for the caller's durability barrier.
+ */
+export declare function restoreWorkingTreeMirrorScope(input: {
+    snapshotRoot: string;
+    targetRoot: string;
+    scope: WorkingTreeMirrorScope;
+}): {
+    paths: string[];
+};
+/**
+ * Make the listed target-relative entries durable together with the directory
+ * entries that name them: every listed regular file and real directory is
+ * fsynced, and so is each listed path's parent directory and the root.
+ * Symlinks and missing paths contribute only their parent, which is what
+ * records their creation or removal. Ancestors are never followed through
+ * symlinks. Nothing outside the listed paths is read.
+ */
+export declare function fsyncWorkingTreePaths(root: string, relativePaths: Iterable<string>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",