@ricsam/r5d-worker 0.0.131 → 0.0.133

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

@@ -1,7 +1,43 @@
 import fs from "node:fs";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { workerGitProcessEnvironment } from "./git-process-environment.mjs";
+import { AtomicRenameError, atomicRenamePrimitivesFor, isAtomicRenameUnsupported } from "./atomic-rename.mjs";
+function projectedFileEntry(stat) {
+  return { kind: "file", size: stat.size, mode: stat.mode, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino };
+}
+function projectedFileEntryMatches(entry, stat) {
+  return stat.isFile() && stat.ino === entry.ino && stat.size === entry.size && stat.mode === entry.mode && stat.mtimeMs === entry.mtimeMs && stat.ctimeMs === entry.ctimeMs;
+}
+function workingTreeStatsMatch(left, right) {
+  return left.isFile() === right.isFile() && left.isDirectory() === right.isDirectory() && left.isSymbolicLink() === right.isSymbolicLink() && left.ino === right.ino && left.dev === right.dev && left.size === right.size && left.mode === right.mode && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+function sameWorkingTreeInode(left, right) {
+  return left.ino === right.ino && left.dev === right.dev;
+}
+function displacedEntryMatches(expected, displaced) {
+  return sameWorkingTreeInode(expected, displaced) && displaced.mode === expected.mode && displaced.size === expected.size && displaced.mtimeMs === expected.mtimeMs;
+}
+class WorkingTreeTargetChangedError extends Error {
+  constructor(relativePath, options = {}) {
+    const retained = options.retained ?? [];
+    super(
+      `Working-tree target changed while it was being hydrated: ${relativePath}` + (options.detail ? ` (${options.detail})` : "") + (retained.length > 0 ? `; displaced entries retained at ${retained.map(({ path: retainedPath }) => retainedPath).join(", ")}` : "")
+    );
+    this.relativePath = relativePath;
+    this.name = "WorkingTreeTargetChangedError";
+    this.retained = retained;
+  }
+  relativePath;
+  retained;
+}
+let raceHook = null;
+function setWorkingTreeMirrorRaceHook(hook) {
+  raceHook = hook;
+}
+function raceWindow(phase, relativePath, targetPath) {
+  if (raceHook) raceHook({ phase, relativePath, targetPath });
+}
 const HFS_IGNORED_CODE_POINTS = /[\u200c-\u200f\u202a-\u202e\u206a-\u206f\ufeff]/gu;
 const MIRROR_TEMPORARY_FILE_PREFIX = ".r5d-working-tree-mirror-";
 const OBJECT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u;
@@ -76,6 +112,9 @@ function inspectRelativePathWithoutFollowingAncestors(root, relativePath) {
   }
   return { kind: "missing" };
 }
+function inspectWorkingTreePath(root, relativePath) {
+  return inspectRelativePathWithoutFollowingAncestors(path.resolve(root), relativePath);
+}
 function inspectDirectoryRoot(root, options) {
   let stat;
   try {
@@ -220,7 +259,7 @@ function writeGitlinkStaleHeads(root, heads) {
   fs.renameSync(temporaryPath, markerPath);
   fsyncPath(directory, fs.constants.O_RDONLY);
 }
-function addEntry(entries, root, relativePath, recurseDirectories, gitlinks) {
+function addEntry(entries, root, relativePath, recurseDirectories, gitlinks, stats) {
   const normalized = normalizeRelativePath(relativePath);
   if (!normalized || entries.has(normalized)) return;
   const gitlink = gitlinks?.get(normalized);
@@ -233,23 +272,29 @@ function addEntry(entries, root, relativePath, recurseDirectories, gitlinks) {
   const { absolutePath, stat } = inspected;
   if (stat.isSymbolicLink()) {
     for (const existing of [...entries.keys()]) {
-      if (existing.startsWith(`${normalized}/`)) entries.delete(existing);
+      if (existing.startsWith(`${normalized}/`)) {
+        entries.delete(existing);
+        stats?.delete(existing);
+      }
     }
     entries.set(normalized, { kind: "symlink", mode: stat.mode, target: fs.readlinkSync(absolutePath) });
+    stats?.set(normalized, stat);
     return;
   }
   if (stat.isFile()) {
     entries.set(normalized, { kind: "file", mode: stat.mode, size: stat.size });
+    stats?.set(normalized, stat);
     return;
   }
   if (!stat.isDirectory()) return;
   entries.set(normalized, { kind: "directory", mode: stat.mode });
+  stats?.set(normalized, stat);
   if (!recurseDirectories) return;
   for (const child of fs.readdirSync(absolutePath).sort()) {
-    addEntry(entries, root, path.posix.join(normalized, child), true, gitlinks);
+    addEntry(entries, root, path.posix.join(normalized, child), true, gitlinks, stats);
   }
 }
-function addParentDirectories(entries, root) {
+function addParentDirectories(entries, root, stats) {
   for (const relativePath of [...entries.keys()]) {
     let parent = path.posix.dirname(relativePath);
     while (parent !== ".") {
@@ -259,12 +304,13 @@ function addParentDirectories(entries, root) {
           throw new Error(`Working-tree entry has an unsafe parent directory: ${parent}`);
         }
         entries.set(parent, { kind: "directory", mode: inspected.stat.mode });
+        stats?.set(parent, inspected.stat);
       }
       parent = path.posix.dirname(parent);
     }
   }
 }
-function inspectGitWorkingTree(root) {
+function inspectGitWorkingTree(root, stats) {
   const entries = /* @__PURE__ */ new Map();
   const listing = listGitCheckout(root);
   const indexGitlinks = /* @__PURE__ */ new Map();
@@ -277,13 +323,13 @@ function inspectGitWorkingTree(root) {
     if (entries.has(relativePath)) continue;
     const indexObjectId = indexGitlinks.get(relativePath);
     if (indexObjectId === void 0 && !nestedRepository) {
-      addEntry(entries, root, relativePath, true);
+      addEntry(entries, root, relativePath, true, void 0, stats);
       continue;
     }
     const inspected = inspectRelativePathWithoutFollowingAncestors(root, relativePath);
     if (inspected.kind !== "entry") continue;
     if (!inspected.stat.isDirectory() || inspected.stat.isSymbolicLink()) {
-      addEntry(entries, root, relativePath, true);
+      addEntry(entries, root, relativePath, true, void 0, stats);
       continue;
     }
     const head = populatedCheckoutHead(root, inspected.absolutePath);
@@ -293,9 +339,12 @@ function inspectGitWorkingTree(root) {
       staleHeads ??= readGitlinkStaleHeads(root);
       objectId = staleHeads.get(relativePath) === head ? indexObjectId : head;
     }
-    if (objectId) entries.set(relativePath, { kind: "gitlink", objectId });
+    if (objectId) {
+      entries.set(relativePath, { kind: "gitlink", objectId });
+      stats?.set(relativePath, inspected.stat);
+    }
   }
-  addParentDirectories(entries, root);
+  addParentDirectories(entries, root, stats);
   return { entries, indexRecords: listing.indexRecords, submodules };
 }
 function normalizedGitlinks(gitlinks) {
@@ -312,13 +361,16 @@ 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 === "git") return inspectGitWorkingTree(root).entries;
+  if (mode === "git") return inspectGitWorkingTree(root, options.stats).entries;
   const gitlinks = normalizedGitlinks(options.gitlinks);
-  for (const child of fs.readdirSync(root).sort()) addEntry(entries, root, child, true, gitlinks);
+  for (const child of fs.readdirSync(root).sort()) addEntry(entries, root, child, true, gitlinks, options.stats);
   for (const [relativePath, objectId] of gitlinks) {
-    if (entries.get(relativePath)?.kind !== "gitlink") entries.set(relativePath, { kind: "gitlink", objectId });
+    if (entries.get(relativePath)?.kind !== "gitlink") {
+      entries.set(relativePath, { kind: "gitlink", objectId });
+      options.stats?.delete(relativePath);
+    }
   }
-  addParentDirectories(entries, root);
+  addParentDirectories(entries, root, options.stats);
   return entries;
 }
 function removeEntry(targetRoot, relativePath) {
@@ -329,6 +381,443 @@ function removeEntry(targetRoot, relativePath) {
   }
   fs.rmSync(inspected.absolutePath, { recursive: true, force: true });
 }
+function assertTargetExpectation(targetRoot, relativePath, guards) {
+  if (!guards?.expectations?.has(relativePath)) return;
+  const expected = guards.expectations.get(relativePath) ?? null;
+  const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (expected === null) {
+    if (inspected.kind === "missing") return;
+    throw new WorkingTreeTargetChangedError(relativePath);
+  }
+  if (expected.isDirectory() && !expected.isSymbolicLink()) {
+    if (inspected.kind === "entry" && inspected.stat.isDirectory() && !inspected.stat.isSymbolicLink()) return;
+    throw new WorkingTreeTargetChangedError(relativePath);
+  }
+  if (inspected.kind !== "entry" || !workingTreeStatsMatch(expected, inspected.stat)) throw new WorkingTreeTargetChangedError(relativePath);
+}
+const DISPLACED_RETENTION_DIRECTORY = "hydration-displaced";
+const RETAINED_NAME_MAX_ENCODED_LENGTH = 150;
+const YIELD_ATTEMPTS = 4;
+const passStates = /* @__PURE__ */ new WeakMap();
+function newPassState(targetRoot) {
+  const retention = retentionDirectoryFor(targetRoot);
+  const primitives = atomicRenamePrimitivesFor(retention ?? targetRoot);
+  return { targetRoot, retention, primitives, exchangeUnavailable: primitives.support.exchange === "unavailable" };
+}
+function workingTreeAtomicRenameSupport(targetRoot) {
+  return newPassState(path.resolve(targetRoot)).primitives.support;
+}
+function guardedPassState(guards, targetRoot) {
+  let state = passStates.get(guards);
+  if (!state) {
+    state = newPassState(targetRoot);
+    passStates.set(guards, state);
+  }
+  return state;
+}
+function workingTreeDisplacedRetentionDirectory(targetRoot) {
+  const gitDirectory = checkoutGitDirectory(path.resolve(targetRoot));
+  return gitDirectory ? path.join(gitDirectory, "r5d", DISPLACED_RETENTION_DIRECTORY) : null;
+}
+function retentionDirectoryFor(targetRoot) {
+  const directory = workingTreeDisplacedRetentionDirectory(targetRoot);
+  if (!directory) return null;
+  try {
+    fs.mkdirSync(directory, { recursive: true, mode: 448 });
+    const status = fs.lstatSync(directory);
+    if (!status.isDirectory() || status.isSymbolicLink()) return null;
+    if (status.dev !== fs.lstatSync(targetRoot).dev) return null;
+    return directory;
+  } catch {
+    return null;
+  }
+}
+function encodeRetainedName(relativePath) {
+  let encoded = "";
+  for (const byte of Buffer.from(relativePath, "utf8")) {
+    const isPlain = byte >= 48 && byte <= 57 || byte >= 65 && byte <= 90 || byte >= 97 && byte <= 122 || byte === 45 || byte === 46 || byte === 95;
+    encoded += isPlain ? String.fromCharCode(byte) : `%${byte.toString(16).padStart(2, "0")}`;
+  }
+  return encoded.length > RETAINED_NAME_MAX_ENCODED_LENGTH ? encoded.slice(0, RETAINED_NAME_MAX_ENCODED_LENGTH) : encoded;
+}
+function stagingPathFor(state, targetPath, relativePath) {
+  if (state.retention) return path.join(state.retention, `${randomUUID()}.${encodeRetainedName(relativePath)}`);
+  return path.join(path.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${randomUUID()}.tmp`);
+}
+function switchExpectation(targetRoot, relativePath, guards) {
+  if (guards.expectations?.has(relativePath)) return guards.expectations.get(relativePath) ?? null;
+  const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (inspected.kind === "blocked") throw new Error(`Refusing to copy through a symlink or non-directory: ${inspected.blockingPath}`);
+  return inspected.kind === "entry" ? inspected.stat : null;
+}
+function settledAfter(targetPath, stagedStat, stagedContent) {
+  const current = lstatIfExists(targetPath);
+  return current && displacedEntryMatches(stagedStat, current) && entryContent(targetPath, current) === stagedContent ? current : stagedStat;
+}
+function entryContent(filePath, expected, expectedBlob) {
+  try {
+    if (expected.isSymbolicLink()) {
+      const before = fs.lstatSync(filePath);
+      if (!workingTreeStatsMatch(expected, before)) return null;
+      const bytes = Buffer.from(fs.readlinkSync(filePath));
+      if (!workingTreeStatsMatch(before, fs.lstatSync(filePath))) return null;
+      const digest = createHash("sha256").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
+      if (expectedBlob && (expectedBlob.length === 64 ? digest : createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex")) !== expectedBlob)
+        return null;
+      return digest;
+    }
+    if (!expected.isFile()) return null;
+    const descriptor = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+      const before = fs.fstatSync(descriptor);
+      if (!workingTreeStatsMatch(expected, before)) return null;
+      const hash = createHash("sha256").update(`blob ${before.size}\0`);
+      const knownHash = expectedBlob && expectedBlob.length !== 64 ? createHash("sha1").update(`blob ${before.size}\0`) : null;
+      const buffer = Buffer.allocUnsafe(64 * 1024);
+      for (let offset = 0; offset < before.size; ) {
+        const count = fs.readSync(descriptor, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
+        if (count <= 0) return null;
+        const bytes = buffer.subarray(0, count);
+        hash.update(bytes);
+        knownHash?.update(bytes);
+        offset += count;
+      }
+      if (!workingTreeStatsMatch(before, fs.fstatSync(descriptor)) || !workingTreeStatsMatch(before, fs.lstatSync(filePath))) return null;
+      const digest = hash.digest("hex");
+      if (expectedBlob && (knownHash ? knownHash.digest("hex") : digest) !== expectedBlob) return null;
+      return digest;
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  } catch (error) {
+    if (isPathStateCode(error.code) || error.code === "ELOOP") return null;
+    throw error;
+  }
+}
+function fsyncRetainedEntry(retainedPath) {
+  const status = fs.lstatSync(retainedPath);
+  if (status.isDirectory() && !status.isSymbolicLink()) {
+    for (const child of fs.readdirSync(retainedPath)) fsyncRetainedEntry(path.join(retainedPath, child));
+    fsyncPath(retainedPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } else if (status.isFile()) {
+    fsyncPath(retainedPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  }
+  fsyncPath(path.dirname(retainedPath), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+}
+function retainForeign(journal, relativePath, retainedPath, reason) {
+  fsyncRetainedEntry(retainedPath);
+  const retained = { relativePath, path: retainedPath, reason };
+  if (journal) (journal.retained ??= []).push(retained);
+  return retained;
+}
+function isPathStateCode(code) {
+  return code === "EEXIST" || code === "ENOENT" || code === "ENOTDIR" || code === "ENOTEMPTY" || code === "EISDIR";
+}
+function publishNoReplace(state, stagedPath, stagedStat, relativePath, targetPath) {
+  if (stagedStat.isSymbolicLink() && state.primitives.support.noReplace === "link") {
+    throw new WorkingTreeTargetChangedError(relativePath, { detail: "filesystem cannot publish a symlink with provable ownership" });
+  }
+  try {
+    state.primitives.renameNoReplace(stagedPath, targetPath);
+  } catch (error) {
+    if (error instanceof AtomicRenameError && isPathStateCode(error.code)) throw new WorkingTreeTargetChangedError(relativePath);
+    throw error;
+  }
+  return null;
+}
+function restoreDisplacedNoReplace(state, displacedPath, displaced, targetPath) {
+  try {
+    if (displaced.isSymbolicLink() && state.primitives.support.noReplace === "link") {
+      return false;
+    }
+    state.primitives.renameNoReplace(displacedPath, targetPath);
+    return true;
+  } catch (error) {
+    const code = error instanceof AtomicRenameError ? error.code : error.code;
+    if (isPathStateCode(code) || code === "ENOTSUP") return false;
+    throw error;
+  }
+}
+function discardStaged(input, reason) {
+  const current = lstatIfExists(input.stagedPath);
+  if (!current) return null;
+  if (input.onFailure === "unlink" && input.stagedContent && displacedEntryMatches(input.stagedStat, current) && entryContent(input.stagedPath, current) === input.stagedContent) {
+    fs.rmSync(input.stagedPath, { force: true });
+    return null;
+  }
+  return retainForeign(input.journal, input.relativePath, input.stagedPath, reason);
+}
+function discardStagedAndThrow(input, error) {
+  const retained = discardStaged(input, "unrestorable");
+  if (retained && error instanceof WorkingTreeTargetChangedError) {
+    throw new WorkingTreeTargetChangedError(input.relativePath, { detail: error.message, retained: [...error.retained, retained] });
+  }
+  throw error;
+}
+function switchStagedEntry(input) {
+  const { state, targetRoot, relativePath, targetPath, stagedPath, stagedStat, expected } = input;
+  const stagedContent = input.stagedContent ?? entryContent(stagedPath, stagedStat);
+  if (!stagedContent) {
+    const retained = retainForeign(input.journal, relativePath, stagedPath, "unrestorable");
+    throw new WorkingTreeTargetChangedError(relativePath, { retained: [retained] });
+  }
+  input.stagedContent = stagedContent;
+  if (stagedStat.isSymbolicLink() && state.primitives.support.noReplace === "link") {
+    discardStagedAndThrow(
+      input,
+      new WorkingTreeTargetChangedError(relativePath, { detail: "filesystem cannot publish a symlink with provable ownership" })
+    );
+  }
+  const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (inspected.kind === "blocked") {
+    discardStagedAndThrow(input, new Error(`Refusing to copy through a symlink or non-directory: ${inspected.blockingPath}`));
+  }
+  if (expected === null) {
+    if (inspected.kind !== "missing") {
+      discardStagedAndThrow(input, new WorkingTreeTargetChangedError(relativePath));
+    }
+    raceWindow(input.phase, relativePath, targetPath);
+    let created;
+    try {
+      created = publishNoReplace(state, stagedPath, stagedStat, relativePath, targetPath);
+    } catch (error) {
+      discardStagedAndThrow(input, error);
+    }
+    raceWindow("after_switch", relativePath, targetPath);
+    return { after: created ?? settledAfter(targetPath, stagedStat, stagedContent), afterContent: stagedContent, displaced: null };
+  }
+  if (inspected.kind !== "entry" || !workingTreeStatsMatch(expected, inspected.stat)) {
+    discardStagedAndThrow(input, new WorkingTreeTargetChangedError(relativePath));
+  }
+  const expectedContent = entryContent(targetPath, expected, input.expectedBlob);
+  if (!expectedContent || input.expectedContent && input.expectedContent !== expectedContent) {
+    discardStagedAndThrow(input, new WorkingTreeTargetChangedError(relativePath));
+  }
+  input.expectedContent = expectedContent;
+  raceWindow(input.phase, relativePath, targetPath);
+  if (!state.exchangeUnavailable) {
+    try {
+      state.primitives.exchange(stagedPath, targetPath);
+    } catch (error) {
+      if (isAtomicRenameUnsupported(error)) {
+        state.exchangeUnavailable = true;
+        return switchWithoutExchange(input);
+      }
+      if (error instanceof AtomicRenameError && isPathStateCode(error.code)) {
+        discardStagedAndThrow(input, new WorkingTreeTargetChangedError(relativePath, { detail: `${error.code} at the switch` }));
+      }
+      discardStagedAndThrow(input, error);
+    }
+    raceWindow("after_switch", relativePath, targetPath);
+    const displaced = fs.lstatSync(stagedPath);
+    if (displacedEntryMatches(expected, displaced) && entryContent(stagedPath, displaced) === expectedContent) {
+      return {
+        after: settledAfter(targetPath, stagedStat, stagedContent),
+        afterContent: stagedContent,
+        displaced: { path: stagedPath, stat: displaced, content: expectedContent }
+      };
+    }
+    return yieldDisplacedEntry(input, displaced);
+  }
+  return switchWithoutExchange(input);
+}
+function yieldDisplacedEntry(input, displaced) {
+  const { state, relativePath, targetPath, stagedPath, stagedStat } = input;
+  raceWindow("before_yield", relativePath, targetPath);
+  let installedBefore = stagedStat;
+  let toInstall = displaced;
+  for (let attempt = 0; attempt < YIELD_ATTEMPTS; attempt += 1) {
+    try {
+      state.primitives.exchange(stagedPath, targetPath);
+    } catch (error) {
+      if (!(error instanceof AtomicRenameError && isPathStateCode(error.code))) throw error;
+      if (restoreDisplacedNoReplace(state, stagedPath, toInstall, targetPath)) {
+        throw new WorkingTreeTargetChangedError(relativePath, { detail: "another writer replaced the entry; its bytes were kept" });
+      }
+      const retained2 = retainForeign(input.journal, relativePath, stagedPath, "later_writer");
+      throw new WorkingTreeTargetChangedError(relativePath, { retained: [retained2] });
+    }
+    const returned = fs.lstatSync(stagedPath);
+    if (sameWorkingTreeInode(returned, installedBefore)) {
+      if (sameWorkingTreeInode(returned, stagedStat)) {
+        discardStagedAndThrow(
+          input,
+          new WorkingTreeTargetChangedError(relativePath, { detail: "another writer replaced the entry; its bytes were kept" })
+        );
+      }
+      const retained2 = retainForeign(input.journal, relativePath, stagedPath, "later_writer");
+      throw new WorkingTreeTargetChangedError(relativePath, { retained: [retained2] });
+    }
+    installedBefore = toInstall;
+    toInstall = returned;
+  }
+  const retained = retainForeign(input.journal, relativePath, stagedPath, "unrestorable");
+  throw new WorkingTreeTargetChangedError(relativePath, { detail: "the path kept changing while the pass yielded", retained: [retained] });
+}
+function switchWithoutExchange(input) {
+  const { state, relativePath, targetPath, stagedPath, stagedStat, expected } = input;
+  const park = stagingPathFor(state, targetPath, relativePath);
+  try {
+    fs.renameSync(targetPath, park);
+  } catch (error) {
+    if (isPathStateCode(error.code))
+      discardStagedAndThrow(input, new WorkingTreeTargetChangedError(relativePath, { detail: "removed before the switch" }));
+    discardStagedAndThrow(input, error);
+  }
+  raceWindow("after_switch", relativePath, targetPath);
+  const displaced = fs.lstatSync(park);
+  if (displacedEntryMatches(expected, displaced) && entryContent(park, displaced) === input.expectedContent) {
+    let created;
+    try {
+      created = publishNoReplace(state, stagedPath, stagedStat, relativePath, targetPath);
+    } catch (error) {
+      if (error instanceof WorkingTreeTargetChangedError) {
+        const retained2 = retainForeign(input.journal, relativePath, park, "reappeared");
+        discardStagedAndThrow(
+          input,
+          new WorkingTreeTargetChangedError(relativePath, {
+            detail: "an entry was created while the path was being replaced",
+            retained: [retained2]
+          })
+        );
+      }
+      if (!restoreDisplacedNoReplace(state, park, displaced, targetPath)) retainForeign(input.journal, relativePath, park, "unrestorable");
+      discardStagedAndThrow(input, error);
+    }
+    return {
+      after: created ?? settledAfter(targetPath, stagedStat, input.stagedContent),
+      afterContent: input.stagedContent,
+      displaced: { path: park, stat: displaced, content: input.expectedContent }
+    };
+  }
+  raceWindow("before_yield", relativePath, targetPath);
+  const stagedRetained = discardStaged(input, "unrestorable");
+  if (restoreDisplacedNoReplace(state, park, displaced, targetPath)) {
+    throw new WorkingTreeTargetChangedError(relativePath, {
+      detail: "another writer replaced the entry; its bytes were kept",
+      retained: stagedRetained ? [stagedRetained] : []
+    });
+  }
+  const retained = retainForeign(input.journal, relativePath, park, "later_writer");
+  throw new WorkingTreeTargetChangedError(relativePath, { retained: [...stagedRetained ? [stagedRetained] : [], retained] });
+}
+function removeSwitchedEntry(input) {
+  const { state, targetRoot, relativePath, targetPath, expected } = input;
+  const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (inspected.kind === "blocked") {
+    throw new Error(`Refusing to remove a working-tree path through a symlink or non-directory: ${inspected.blockingPath}`);
+  }
+  if (inspected.kind !== "entry" || !workingTreeStatsMatch(expected, inspected.stat)) throw new WorkingTreeTargetChangedError(relativePath);
+  const content = entryContent(targetPath, expected, input.expectedBlob);
+  if (!content || input.expectedContent && content !== input.expectedContent) throw new WorkingTreeTargetChangedError(relativePath);
+  raceWindow(input.phase, relativePath, targetPath);
+  const park = stagingPathFor(state, targetPath, relativePath);
+  try {
+    fs.renameSync(targetPath, park);
+  } catch (error) {
+    if (isPathStateCode(error.code))
+      throw new WorkingTreeTargetChangedError(relativePath, { detail: "removed before the switch" });
+    throw error;
+  }
+  raceWindow("after_remove", relativePath, targetPath);
+  const displaced = fs.lstatSync(park);
+  if (displacedEntryMatches(expected, displaced) && entryContent(park, displaced) === content)
+    return { path: park, stat: displaced, content };
+  raceWindow("before_yield", relativePath, targetPath);
+  if (restoreDisplacedNoReplace(state, park, displaced, targetPath)) {
+    throw new WorkingTreeTargetChangedError(relativePath, { detail: "another writer replaced the entry; its bytes were kept" });
+  }
+  const retained = retainForeign(input.journal, relativePath, park, "later_writer");
+  throw new WorkingTreeTargetChangedError(relativePath, { retained: [retained] });
+}
+function removeEntryGuarded(targetRoot, relativePath, replaced, guards) {
+  if (!guards) {
+    removeEntry(targetRoot, relativePath);
+    return;
+  }
+  const state = guardedPassState(guards, targetRoot);
+  const expected = switchExpectation(targetRoot, relativePath, guards);
+  const targetPath = path.join(targetRoot, ...relativePath.split("/"));
+  assertInside(targetRoot, targetPath);
+  const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (inspected.kind === "blocked") {
+    throw new Error(`Refusing to remove a working-tree path through a symlink or non-directory: ${inspected.blockingPath}`);
+  }
+  if (expected === null) {
+    if (inspected.kind !== "missing") throw new WorkingTreeTargetChangedError(relativePath);
+    return;
+  }
+  if (expected.isDirectory() && !expected.isSymbolicLink()) {
+    if (inspected.kind === "entry") {
+      if (!inspected.stat.isDirectory() || inspected.stat.isSymbolicLink()) throw new WorkingTreeTargetChangedError(relativePath);
+      raceWindow("before_remove", relativePath, targetPath);
+      try {
+        fs.rmdirSync(inspected.absolutePath);
+      } catch (error) {
+        const code = error.code;
+        if (code === "ENOTEMPTY" || code === "EEXIST" || code === "ENOTDIR") throw new WorkingTreeTargetChangedError(relativePath);
+        if (code !== "ENOENT") throw error;
+      }
+    }
+    if (guards.expectations?.has(relativePath)) guards.expectations.set(relativePath, null);
+    if (replaced) guards.journal?.entries.push({ relativePath, replaced, after: null });
+    return;
+  }
+  const displaced = removeSwitchedEntry({
+    state,
+    targetRoot,
+    relativePath,
+    targetPath,
+    expected,
+    expectedBlob: guards.preBlobs?.get(relativePath),
+    journal: guards.journal,
+    phase: "before_remove"
+  });
+  if (guards.expectations?.has(relativePath)) guards.expectations.set(relativePath, null);
+  const recorded = replaced ?? treeEntryFromStat(displaced.stat, displaced.path);
+  if (guards.journal && recorded) guards.journal.entries.push({ relativePath, replaced: recorded, after: null, displaced });
+  else releaseRetainedEntry(void 0, relativePath, displaced);
+}
+function ensureDirectoryGuarded(targetRoot, relativePath, guards) {
+  if (!guards) {
+    ensureDirectory(targetRoot, relativePath, 493);
+    return;
+  }
+  const normalized = normalizeRelativePath(relativePath);
+  if (!normalized) throw new Error(`Invalid working-tree directory path: ${relativePath}`);
+  let current = path.resolve(targetRoot);
+  let relative = "";
+  for (const segment of normalized.split("/")) {
+    current = path.join(current, segment);
+    relative = relative ? `${relative}/${segment}` : segment;
+    assertInside(targetRoot, current);
+    const stat = lstatIfExists(current);
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new WorkingTreeTargetChangedError(relative);
+    if (stat) continue;
+    try {
+      fs.mkdirSync(current, { mode: 493 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const now = lstatIfExists(current);
+      if (!now || !now.isDirectory() || now.isSymbolicLink()) throw new WorkingTreeTargetChangedError(relative);
+    }
+  }
+}
+function replaceWithSymlink(targetRoot, relativePath, target) {
+  const targetPath = path.join(targetRoot, ...relativePath.split("/"));
+  assertInside(targetRoot, targetPath);
+  const temporaryPath = path.join(path.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${randomUUID()}.tmp`);
+  fs.symlinkSync(target, temporaryPath);
+  try {
+    const current = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (current.kind === "blocked") throw new Error(`Refusing to copy through a symlink or non-directory: ${current.blockingPath}`);
+    if (current.kind === "entry" && current.stat.isDirectory() && !current.stat.isSymbolicLink()) removeEntry(targetRoot, relativePath);
+    fs.renameSync(temporaryPath, targetPath);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
 function ensureDirectory(targetRoot, relativePath, mode) {
   const normalized = normalizeRelativePath(relativePath);
   if (!normalized) throw new Error(`Invalid working-tree directory path: ${relativePath}`);
@@ -386,9 +875,8 @@ function filesEqual(leftPath, rightPath, entry) {
     fs.closeSync(right);
   }
 }
-function copyRegularFile(sourcePath, targetPath, entry, durability) {
+function stageRegularFile(sourcePath, stagedPath, entry, durability) {
   const source = fs.openSync(sourcePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
-  const temporaryPath = path.join(path.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${randomUUID()}.tmp`);
   let target;
   try {
     const sourceStat = fs.fstatSync(source);
@@ -396,7 +884,7 @@ function copyRegularFile(sourcePath, targetPath, entry, durability) {
       throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
     }
     target = fs.openSync(
-      temporaryPath,
+      stagedPath,
       fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
       entry.mode & 511
     );
@@ -417,22 +905,54 @@ function copyRegularFile(sourcePath, targetPath, entry, durability) {
     if (!finalSourceStat.isFile() || finalSourceStat.size !== sourceStat.size || (finalSourceStat.mode & 511) !== (sourceStat.mode & 511) || finalSourceStat.mtimeMs !== sourceStat.mtimeMs || finalSourceStat.ctimeMs !== sourceStat.ctimeMs) {
       throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
     }
+    const stagedStat = fs.fstatSync(target);
     fs.closeSync(target);
     target = void 0;
-    fs.renameSync(temporaryPath, targetPath);
-    if (durability === "per_entry") {
-      const parent = fs.openSync(path.dirname(targetPath), fs.constants.O_RDONLY);
-      try {
-        fs.fsyncSync(parent);
-      } finally {
-        fs.closeSync(parent);
-      }
+    return { sourceStat: finalSourceStat, stagedStat };
+  } catch (error) {
+    if (target !== void 0) {
+      fs.closeSync(target);
+      target = void 0;
     }
+    fs.rmSync(stagedPath, { force: true });
+    throw error;
   } finally {
     if (target !== void 0) fs.closeSync(target);
     fs.closeSync(source);
+  }
+}
+function writeStagedContent(stagedPath, override, durability) {
+  const target = fs.openSync(
+    stagedPath,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
+    override.mode & 511
+  );
+  try {
+    let written = 0;
+    while (written < override.content.length) {
+      written += fs.writeSync(target, override.content, written, override.content.length - written, written);
+    }
+    fs.fchmodSync(target, override.mode & 511);
+    if (durability === "per_entry") fs.fsyncSync(target);
+    return fs.fstatSync(target);
+  } catch (error) {
+    fs.rmSync(stagedPath, { force: true });
+    throw error;
+  } finally {
+    fs.closeSync(target);
+  }
+}
+function copyRegularFile(sourcePath, targetPath, entry, durability) {
+  const temporaryPath = path.join(path.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${randomUUID()}.tmp`);
+  const { sourceStat } = stageRegularFile(sourcePath, temporaryPath, entry, durability);
+  try {
+    fs.renameSync(temporaryPath, targetPath);
+  } catch (error) {
     fs.rmSync(temporaryPath, { force: true });
+    throw error;
   }
+  if (durability === "per_entry") fsyncPath(path.dirname(targetPath), fs.constants.O_RDONLY);
+  return sourceStat;
 }
 function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
   const targetPath = path.join(targetRoot, ...relativePath.split("/"));
@@ -449,7 +969,7 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
       throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
     }
     ensureDirectory(targetRoot, relativePath, entry.mode);
-    return;
+    return null;
   }
   if (entry.kind === "symlink") {
     if (!source.stat.isSymbolicLink() || fs.readlinkSync(sourcePath) !== entry.target) {
@@ -461,11 +981,8 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
     } catch {
       unchanged = false;
     }
-    if (!unchanged) {
-      removeEntry(targetRoot, relativePath);
-      fs.symlinkSync(entry.target, targetPath);
-    }
-    return;
+    if (!unchanged) replaceWithSymlink(targetRoot, relativePath, entry.target);
+    return { kind: "symlink", target: entry.target };
   }
   if (entry.kind === "gitlink") {
     throw new Error(`Working-tree gitlink cannot be copied as content: ${relativePath}`);
@@ -473,19 +990,183 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
   if (!source.stat.isFile() || source.stat.isSymbolicLink() || source.stat.size !== entry.size) {
     throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
   }
-  if (!filesEqual(sourcePath, targetPath, entry)) {
-    const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
-    if (target.kind === "blocked") {
-      throw new Error(`Refusing to copy through a symlink or non-directory: ${target.blockingPath}`);
+  if (filesEqual(sourcePath, targetPath, entry)) {
+    const settled = fs.lstatSync(sourcePath);
+    if (!settled.isFile() || settled.ino !== source.stat.ino || settled.size !== source.stat.size || settled.mode !== source.stat.mode) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
     }
-    const targetStat = target.kind === "entry" ? target.stat : null;
-    if (targetStat && !targetStat.isFile()) removeEntry(targetRoot, relativePath);
-    copyRegularFile(sourcePath, targetPath, entry, durability);
+    if (settled.mtimeMs !== source.stat.mtimeMs || settled.ctimeMs !== source.stat.ctimeMs) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+    }
+    return projectedFileEntry(settled);
+  }
+  const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (target.kind === "blocked") {
+    throw new Error(`Refusing to copy through a symlink or non-directory: ${target.blockingPath}`);
   }
+  if (target.kind === "entry" && !target.stat.isFile()) removeEntry(targetRoot, relativePath);
+  return projectedFileEntry(copyRegularFile(sourcePath, targetPath, entry, durability));
 }
-function inspectMirrorTarget(targetRoot, deletionMode) {
-  if (deletionMode !== "git") return { existing: inspectWorkingTree(targetRoot, "all"), git: null };
-  const inspection = inspectGitWorkingTree(targetRoot);
+function copyEntryGuarded(sourceRoot, targetRoot, relativePath, entry, durability, guards) {
+  const state = guardedPassState(guards, targetRoot);
+  const targetPath = path.join(targetRoot, ...relativePath.split("/"));
+  assertInside(targetRoot, targetPath);
+  const parent = path.posix.dirname(relativePath);
+  if (parent !== ".") ensureDirectoryGuarded(targetRoot, parent, guards);
+  const override = guards.overrides?.get(relativePath);
+  if (override && entry.kind !== "file") throw new Error(`Working-tree override must replace a regular file: ${relativePath}`);
+  let sourcePath = null;
+  let sourceStat = null;
+  if (!override) {
+    const source = inspectRelativePathWithoutFollowingAncestors(sourceRoot, relativePath);
+    if (source.kind !== "entry") throw new Error(`Working-tree source became unsafe while it was being mirrored: ${relativePath}`);
+    sourcePath = source.absolutePath;
+    sourceStat = source.stat;
+  }
+  if (entry.kind === "directory") {
+    if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+    }
+    const target2 = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (target2.kind === "blocked") throw new Error(`Refusing to copy through a symlink or non-directory: ${target2.blockingPath}`);
+    if (target2.kind === "entry" && target2.stat.isDirectory() && !target2.stat.isSymbolicLink()) return null;
+    if (target2.kind === "entry") {
+      if (guards.expectations && !guards.expectations.has(relativePath)) throw new WorkingTreeTargetChangedError(relativePath);
+      removeEntryGuarded(targetRoot, relativePath, treeEntryFromStat(target2.stat, target2.absolutePath), guards);
+    } else assertTargetExpectation(targetRoot, relativePath, guards);
+    createDirectoryGuarded(targetRoot, relativePath, entry.mode, guards);
+    return null;
+  }
+  if (entry.kind === "gitlink") {
+    throw new Error(`Working-tree gitlink cannot be copied as content: ${relativePath}`);
+  }
+  const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (target.kind === "blocked") throw new Error(`Refusing to copy through a symlink or non-directory: ${target.blockingPath}`);
+  if (entry.kind === "symlink") {
+    if (!sourceStat.isSymbolicLink() || fs.readlinkSync(sourcePath) !== entry.target) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+    }
+    if (target.kind === "entry" && target.stat.isSymbolicLink() && fs.readlinkSync(target.absolutePath) === entry.target) {
+      return { kind: "symlink", target: entry.target };
+    }
+  } else if (!override) {
+    if (!sourceStat.isFile() || sourceStat.isSymbolicLink() || sourceStat.size !== entry.size) {
+      throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+    }
+    if (filesEqual(sourcePath, targetPath, entry)) {
+      const settled = fs.lstatSync(sourcePath);
+      if (!settled.isFile() || settled.ino !== sourceStat.ino || settled.size !== sourceStat.size || settled.mode !== sourceStat.mode) {
+        throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+      }
+      if (settled.mtimeMs !== sourceStat.mtimeMs || settled.ctimeMs !== sourceStat.ctimeMs) {
+        throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
+      }
+      return projectedFileEntry(settled);
+    }
+  }
+  let replaced = target.kind === "entry" ? treeEntryFromStat(target.stat, target.absolutePath) : null;
+  let expected = switchExpectation(targetRoot, relativePath, guards);
+  if (target.kind === "entry" && target.stat.isDirectory() && !target.stat.isSymbolicLink()) {
+    removeEntryGuarded(targetRoot, relativePath, replaced, guards);
+    replaced = null;
+    expected = null;
+  }
+  const stagedPath = stagingPathFor(state, targetPath, relativePath);
+  let stagedStat;
+  let projected = null;
+  if (entry.kind === "symlink") {
+    fs.symlinkSync(entry.target, stagedPath);
+    stagedStat = fs.lstatSync(stagedPath);
+    projected = { kind: "symlink", target: entry.target };
+  } else if (override) {
+    stagedStat = writeStagedContent(stagedPath, override, durability);
+  } else {
+    const staged = stageRegularFile(sourcePath, stagedPath, entry, durability);
+    stagedStat = staged.stagedStat;
+    projected = projectedFileEntry(staged.sourceStat);
+  }
+  const outcome = switchStagedEntry({
+    state,
+    targetRoot,
+    relativePath,
+    targetPath,
+    stagedPath,
+    stagedStat,
+    expected,
+    expectedBlob: guards.preBlobs?.get(relativePath),
+    journal: guards.journal,
+    phase: "before_switch",
+    onFailure: "unlink"
+  });
+  if (durability === "per_entry") fsyncPath(path.dirname(targetPath), fs.constants.O_RDONLY);
+  if (guards.journal)
+    guards.journal.entries.push({
+      relativePath,
+      replaced,
+      after: outcome.after,
+      afterContent: outcome.afterContent,
+      ...outcome.displaced ? { displaced: outcome.displaced } : {}
+    });
+  else if (outcome.displaced) releaseRetainedEntry(void 0, relativePath, outcome.displaced);
+  if (guards.expectations?.has(relativePath)) guards.expectations.set(relativePath, outcome.after);
+  return projected;
+}
+function createDirectoryGuarded(targetRoot, relativePath, mode, guards) {
+  if (!guards) {
+    ensureDirectory(targetRoot, relativePath, mode);
+    return;
+  }
+  const targetPath = path.join(targetRoot, ...relativePath.split("/"));
+  assertInside(targetRoot, targetPath);
+  try {
+    fs.mkdirSync(targetPath, { mode: mode & 511 });
+  } catch (error) {
+    if (isPathStateCode(error.code)) throw new WorkingTreeTargetChangedError(relativePath);
+    throw error;
+  }
+  if (!guards.journal) return;
+  const created = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+  if (created.kind !== "entry" || !created.stat.isDirectory() || created.stat.isSymbolicLink()) {
+    throw new WorkingTreeTargetChangedError(relativePath);
+  }
+  guards.journal.entries.push({ relativePath, replaced: null, after: created.stat });
+}
+function retainedEntryIntact(retained, current) {
+  return retained.content !== void 0 && sameWorkingTreeInode(retained.stat, current) && current.mode === retained.stat.mode && current.size === retained.stat.size && current.mtimeMs === retained.stat.mtimeMs && current.ctimeMs === retained.stat.ctimeMs && entryContent(retained.path, current) === retained.content;
+}
+function settleRetainedEntries(journal, targetRoot) {
+  raceWindow("before_settle", "", targetRoot);
+  for (const entry of journal.entries) {
+    if (!entry.displaced) continue;
+    const current = lstatIfExists(entry.displaced.path);
+    if (!current || !retainedEntryIntact(entry.displaced, current)) {
+      throw new WorkingTreeTargetChangedError(entry.relativePath, {
+        detail: "written through a descriptor opened before hydration replaced the path"
+      });
+    }
+  }
+  releaseRetainedEntries(journal);
+}
+function releaseRetainedEntries(journal) {
+  for (const entry of journal.entries) {
+    if (!entry.displaced) continue;
+    releaseRetainedEntry(journal, entry.relativePath, entry.displaced);
+    delete entry.displaced;
+  }
+}
+function releaseRetainedEntry(journal, relativePath, displaced) {
+  const current = lstatIfExists(displaced.path);
+  if (!current) return;
+  if (!retainedEntryIntact(displaced, current)) {
+    const retained = retainForeign(journal, relativePath, displaced.path, "unrestorable");
+    if (!journal) throw new WorkingTreeTargetChangedError(relativePath, { retained: [retained] });
+    return;
+  }
+  fs.rmSync(displaced.path, { force: true });
+}
+function inspectMirrorTarget(targetRoot, deletionMode, stats) {
+  if (deletionMode !== "git") return { existing: inspectWorkingTree(targetRoot, "all", { stats }), git: null };
+  const inspection = inspectGitWorkingTree(targetRoot, stats);
   const occupied = /* @__PURE__ */ new Set();
   for (const relativePath of inspection.submodules.keys()) {
     const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
@@ -587,43 +1268,109 @@ function recordGitlinkStaleHeads(targetRoot, desired, shielded, git) {
   }
   if (changed) writeGitlinkStaleHeads(targetRoot, heads);
 }
-function mirrorWorkingTree(input) {
+function prepareWorkingTreeMirror(input) {
   const sourceRoot = path.resolve(input.sourceRoot);
   const targetRoot = path.resolve(input.targetRoot);
-  const durability = input.durability ?? "per_entry";
   if (!inspectDirectoryRoot(targetRoot, { allowMissing: true, label: "Working-tree target root" })) {
     fs.mkdirSync(targetRoot, { recursive: true });
   }
   inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
   const desired = inspectWorkingTree(sourceRoot, input.sourceMode, { gitlinks: input.sourceGitlinks });
-  const target = inspectMirrorTarget(targetRoot, input.deletionMode);
+  const existingStats = /* @__PURE__ */ new Map();
+  const target = inspectMirrorTarget(targetRoot, input.deletionMode, existingStats);
   const shielded = target.git ? shieldedDesiredPaths(desired, target.git) : /* @__PURE__ */ new Set();
-  const index = target.git ? planIndexChanges(desired, shielded, target.git) : null;
-  for (const relativePath of [...target.existing.keys()].sort(deepestFirst)) {
-    if (desired.has(relativePath)) continue;
-    const entry = target.existing.get(relativePath);
+  return {
+    sourceRoot,
+    targetRoot,
+    deletionMode: input.deletionMode,
+    desired,
+    existing: target.existing,
+    existingStats,
+    git: target.git,
+    shielded
+  };
+}
+function applyWorkingTreeMirror(prepared, options = {}) {
+  const { sourceRoot, targetRoot, desired, existing, shielded } = prepared;
+  const durability = options.durability ?? "per_entry";
+  const guards = options.guards;
+  const selection = options.selection;
+  const target = { existing, git: prepared.git };
+  const indexDesired = selection?.desiredForIndex ?? desired;
+  const index = target.git ? planIndexChanges(indexDesired, shielded, target.git) : null;
+  const neededDirectories = /* @__PURE__ */ new Set();
+  if (selection) {
+    for (const relativePath of selection.write) {
+      let parent = path.posix.dirname(relativePath);
+      while (parent !== ".") {
+        neededDirectories.add(parent);
+        parent = path.posix.dirname(parent);
+      }
+    }
+  }
+  for (const relativePath of [...existing.keys()].sort(deepestFirst)) {
+    if (selection ? !selection.remove.has(relativePath) : desired.has(relativePath)) continue;
+    const entry = existing.get(relativePath);
     if (entry.kind === "gitlink" || directoryShieldsSubmodule(relativePath, entry, target.git)) continue;
-    removeEntry(targetRoot, relativePath);
+    if (selection && entry.kind === "directory") {
+      const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+      if (inspected.kind !== "entry" || !inspected.stat.isDirectory() || inspected.stat.isSymbolicLink()) continue;
+      try {
+        fs.rmdirSync(inspected.absolutePath);
+      } catch (error) {
+        const code = error.code;
+        if (code === "ENOTEMPTY" || code === "EEXIST" || code === "ENOENT") continue;
+        throw error;
+      }
+      if (guards?.expectations?.has(relativePath)) guards.expectations.set(relativePath, null);
+      guards?.journal?.entries.push({ relativePath, replaced: entry, after: null });
+      continue;
+    }
+    removeEntryGuarded(targetRoot, relativePath, entry, guards);
   }
   const gitlinks = [];
   for (const [relativePath, entry] of [...desired.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
     if (shielded.has(relativePath)) continue;
+    if (selection && entry.kind === "directory" && !neededDirectories.has(relativePath)) continue;
+    if (selection && entry.kind !== "directory" && !selection.write.has(relativePath)) continue;
     if (entry.kind === "gitlink") {
-      ensureDirectory(targetRoot, relativePath, 493);
+      if (guards) {
+        const parent = path.posix.dirname(relativePath);
+        if (parent !== ".") ensureDirectoryGuarded(targetRoot, parent, guards);
+        const current = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+        if (current.kind === "blocked") throw new Error(`Refusing to copy through a symlink or non-directory: ${current.blockingPath}`);
+        if (current.kind === "entry" && (!current.stat.isDirectory() || current.stat.isSymbolicLink())) {
+          if (guards.expectations && !guards.expectations.has(relativePath)) throw new WorkingTreeTargetChangedError(relativePath);
+          removeEntryGuarded(targetRoot, relativePath, treeEntryFromStat(current.stat, current.absolutePath), guards);
+          createDirectoryGuarded(targetRoot, relativePath, 493, guards);
+        } else if (current.kind !== "entry") {
+          assertTargetExpectation(targetRoot, relativePath, guards);
+          createDirectoryGuarded(targetRoot, relativePath, 493, guards);
+        }
+      } else {
+        ensureDirectory(targetRoot, relativePath, 493);
+      }
       gitlinks.push({ relativePath, objectId: entry.objectId });
+      options.projected?.set(relativePath, { kind: "gitlink", objectId: entry.objectId });
       continue;
     }
-    copyEntry(sourceRoot, targetRoot, relativePath, entry, durability);
+    const projected = guards ? copyEntryGuarded(sourceRoot, targetRoot, relativePath, entry, durability, guards) : copyEntry(sourceRoot, targetRoot, relativePath, entry, durability);
+    if (projected && options.projected) options.projected.set(relativePath, projected);
   }
+  if (guards?.journal) settleRetainedEntries(guards.journal, targetRoot);
   if (index && target.git) {
     updateIndex(targetRoot, { drop: index.removed, put: index.written.map((gitlink) => ({ mode: "160000", stage: 0, ...gitlink })) });
-    recordGitlinkStaleHeads(targetRoot, desired, shielded, target.git);
+    if (guards?.journal && (index.removed.length > 0 || index.written.length > 0)) guards.journal.indexApplied = index;
+    recordGitlinkStaleHeads(targetRoot, indexDesired, shielded, target.git);
   }
   return {
     paths: [...desired.keys()].filter((relativePath) => !shielded.has(relativePath) && desired.get(relativePath)?.kind !== "directory").sort(),
     gitlinks
   };
 }
+function mirrorWorkingTree(input) {
+  return applyWorkingTreeMirror(prepareWorkingTreeMirror(input), { durability: input.durability, projected: input.projected });
+}
 function normalizeWorkingTreeRelativePath(value) {
   return normalizeRelativePath(value);
 }
@@ -660,16 +1407,23 @@ function fsyncPath(targetPath, flags) {
   }
 }
 function planWorkingTreeMirror(input) {
-  const sourceRoot = path.resolve(input.sourceRoot);
-  const targetRoot = path.resolve(input.targetRoot);
-  const inspectedDesired = inspectWorkingTree(sourceRoot, input.sourceMode, { gitlinks: input.sourceGitlinks });
-  const target = inspectMirrorTarget(targetRoot, input.deletionMode);
-  const shielded = target.git ? shieldedDesiredPaths(inspectedDesired, target.git) : /* @__PURE__ */ new Set();
-  const desired = new Map([...inspectedDesired].filter(([relativePath]) => !shielded.has(relativePath)));
+  return planPreparedWorkingTreeMirror(prepareWorkingTreeMirror(input));
+}
+function planPreparedWorkingTreeMirror(prepared, options = {}) {
+  const { sourceRoot, targetRoot, existing, shielded } = prepared;
+  const inspectedDesired = prepared.desired;
+  const selection = options.selection;
+  const target = { existing, git: prepared.git };
+  const desired = new Map(
+    [...inspectedDesired].filter(
+      ([relativePath, entry]) => !shielded.has(relativePath) && (!selection || entry.kind === "directory" || selection.write.has(relativePath))
+    )
+  );
   const replaced = /* @__PURE__ */ new Map();
   const absent = [];
-  for (const [relativePath, entry] of target.existing) {
-    if (inspectedDesired.has(relativePath) || entry.kind === "gitlink") continue;
+  for (const [relativePath, entry] of existing) {
+    if (selection ? !selection.remove.has(relativePath) : inspectedDesired.has(relativePath)) continue;
+    if (entry.kind === "gitlink") continue;
     if (directoryShieldsSubmodule(relativePath, entry, target.git)) continue;
     replaced.set(relativePath, entry);
   }
@@ -680,7 +1434,8 @@ function planWorkingTreeMirror(input) {
       continue;
     }
     const { absolutePath, stat } = targetEntry;
-    if (entry.kind === "directory" || entry.kind === "gitlink") {
+    if (options.overrides?.has(relativePath)) {
+    } else if (entry.kind === "directory" || entry.kind === "gitlink") {
       if (stat.isDirectory()) continue;
     } else if (entry.kind === "symlink") {
       if (stat.isSymbolicLink() && fs.readlinkSync(absolutePath) === entry.target) continue;
@@ -701,7 +1456,208 @@ function planWorkingTreeMirror(input) {
     desired,
     replaced,
     absent: absent.filter((relativePath) => !hasAncestorIn(relativePath, replacedDirectories)).sort(shallowestFirst),
-    index: target.git ? planIndexChanges(inspectedDesired, shielded, target.git) : { removed: [], written: [] }
+    index: target.git ? planIndexChanges(selection?.desiredForIndex ?? inspectedDesired, shielded, target.git) : { removed: [], written: [] }
+  };
+}
+function rollbackWorkingTreeMirrorJournal(input) {
+  const targetRoot = path.resolve(input.targetRoot);
+  const snapshotRoot = path.resolve(input.snapshotRoot);
+  const { journal } = input;
+  const state = newPassState(targetRoot);
+  const touched = /* @__PURE__ */ new Set();
+  const abandoned = [];
+  const restoredTrees = /* @__PURE__ */ new Set();
+  const targetPathOf = (relativePath) => {
+    const targetPath = path.join(targetRoot, ...relativePath.split("/"));
+    assertInside(targetRoot, targetPath);
+    return targetPath;
+  };
+  const stageFromSnapshot = (relativePath, replaced) => {
+    const captured = inspectRelativePathWithoutFollowingAncestors(snapshotRoot, relativePath);
+    if (captured.kind !== "entry") throw new Error(`Working-tree snapshot does not hold the replaced entry: ${relativePath}`);
+    const stagedPath = stagingPathFor(state, targetPathOf(relativePath), relativePath);
+    if (replaced.kind === "symlink") {
+      if (!captured.stat.isSymbolicLink()) throw new Error(`Working-tree snapshot does not hold the replaced entry: ${relativePath}`);
+      fs.symlinkSync(fs.readlinkSync(captured.absolutePath), stagedPath);
+      return { path: stagedPath, stat: fs.lstatSync(stagedPath) };
+    }
+    if (!captured.stat.isFile()) throw new Error(`Working-tree snapshot does not hold the replaced entry: ${relativePath}`);
+    return { path: stagedPath, stat: stageRegularFile(captured.absolutePath, stagedPath, replaced, "per_entry").stagedStat };
+  };
+  const restoreReplaced = (entry, expected) => {
+    const replaced = entry.replaced;
+    const { relativePath } = entry;
+    if (replaced.kind === "gitlink") return true;
+    if (replaced.kind === "directory") return restoreCapturedDirectory(relativePath, replaced);
+    let staged;
+    let onFailure = "unlink";
+    if (entry.displaced && lstatIfExists(entry.displaced.path)) {
+      const current = fs.lstatSync(entry.displaced.path);
+      if (!sameWorkingTreeInode(current, entry.displaced.stat))
+        throw new Error(`Retained working-tree entry was replaced: ${entry.displaced.path}`);
+      if (!retainedEntryIntact(entry.displaced, current)) onFailure = "retain";
+      staged = { path: entry.displaced.path, stat: current };
+    } else {
+      staged = stageFromSnapshot(relativePath, replaced);
+    }
+    try {
+      const outcome = switchStagedEntry({
+        state,
+        targetRoot,
+        relativePath,
+        targetPath: targetPathOf(relativePath),
+        stagedPath: staged.path,
+        stagedStat: staged.stat,
+        expected,
+        expectedContent: expected === null ? void 0 : entry.afterContent,
+        journal,
+        phase: "before_rollback_switch",
+        onFailure
+      });
+      if (outcome.displaced) releaseRetainedEntry(journal, relativePath, outcome.displaced);
+      delete entry.displaced;
+      return true;
+    } catch (error) {
+      if (!(error instanceof WorkingTreeTargetChangedError)) throw error;
+      if (onFailure === "retain") delete entry.displaced;
+      else if (entry.displaced && !lstatIfExists(entry.displaced.path)) delete entry.displaced;
+      return false;
+    }
+  };
+  const restoreCapturedDirectory = (relativePath, replaced) => {
+    const captured = inspectRelativePathWithoutFollowingAncestors(snapshotRoot, relativePath);
+    if (captured.kind !== "entry" || !captured.stat.isDirectory()) {
+      throw new Error(`Working-tree snapshot does not hold the captured directory: ${relativePath}`);
+    }
+    try {
+      fs.mkdirSync(targetPathOf(relativePath), { mode: replaced.mode & 511 });
+    } catch (error) {
+      if (isPathStateCode(error.code)) return false;
+      throw error;
+    }
+    let complete = true;
+    const children = inspectWorkingTree(captured.absolutePath, "all");
+    for (const [childRelative, child] of [...children.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+      const childPath = path.posix.join(relativePath, childRelative);
+      if (child.kind === "gitlink") continue;
+      if (child.kind === "directory") {
+        try {
+          fs.mkdirSync(targetPathOf(childPath), { mode: child.mode & 511 });
+        } catch (error) {
+          if (!isPathStateCode(error.code)) throw error;
+          const now = inspectRelativePathWithoutFollowingAncestors(targetRoot, childPath);
+          if (now.kind !== "entry" || !now.stat.isDirectory() || now.stat.isSymbolicLink()) {
+            abandoned.push(childPath);
+            complete = false;
+          }
+        }
+        continue;
+      }
+      const staged = stageFromSnapshot(childPath, child);
+      try {
+        switchStagedEntry({
+          state,
+          targetRoot,
+          relativePath: childPath,
+          targetPath: targetPathOf(childPath),
+          stagedPath: staged.path,
+          stagedStat: staged.stat,
+          expected: null,
+          journal,
+          phase: "before_rollback_switch",
+          onFailure: "unlink"
+        });
+      } catch (error) {
+        if (!(error instanceof WorkingTreeTargetChangedError)) throw error;
+        abandoned.push(childPath);
+        complete = false;
+      }
+    }
+    restoredTrees.add(relativePath);
+    return complete;
+  };
+  for (const entry of [...journal.entries].reverse()) {
+    const { relativePath } = entry;
+    if (hasAncestorIn(relativePath, restoredTrees)) {
+      touched.add(relativePath);
+      continue;
+    }
+    const current = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (current.kind === "blocked") {
+      abandoned.push(relativePath);
+      continue;
+    }
+    if (entry.after === null) {
+      if (current.kind !== "missing") {
+        abandoned.push(relativePath);
+        continue;
+      }
+      if (entry.replaced && !restoreReplaced(entry, null)) {
+        abandoned.push(relativePath);
+        continue;
+      }
+      touched.add(relativePath);
+      continue;
+    }
+    if (current.kind !== "entry" || !workingTreeStatsMatch(entry.after, current.stat) || entry.afterContent !== void 0 && entryContent(current.absolutePath, current.stat) !== entry.afterContent) {
+      if (!(current.kind === "entry" && entry.after.isDirectory() && current.stat.isDirectory())) {
+        abandoned.push(relativePath);
+        continue;
+      }
+    }
+    if (current.stat.isDirectory() && !current.stat.isSymbolicLink()) {
+      try {
+        fs.rmdirSync(current.absolutePath);
+      } catch (error) {
+        const code = error.code;
+        if (code === "ENOTEMPTY" || code === "EEXIST" || code === "ENOTDIR") {
+          abandoned.push(relativePath);
+          continue;
+        }
+        if (code !== "ENOENT") throw error;
+      }
+      if (entry.replaced && !restoreReplaced(entry, null)) {
+        abandoned.push(relativePath);
+        continue;
+      }
+      touched.add(relativePath);
+      continue;
+    }
+    if (entry.replaced) {
+      if (!restoreReplaced(entry, entry.after)) {
+        abandoned.push(relativePath);
+        continue;
+      }
+      touched.add(relativePath);
+      continue;
+    }
+    try {
+      const displaced = removeSwitchedEntry({
+        state,
+        targetRoot,
+        relativePath,
+        targetPath: targetPathOf(relativePath),
+        expected: entry.after,
+        expectedContent: entry.afterContent,
+        journal,
+        phase: "before_rollback_remove"
+      });
+      releaseRetainedEntry(journal, relativePath, displaced);
+    } catch (error) {
+      if (!(error instanceof WorkingTreeTargetChangedError)) throw error;
+      abandoned.push(relativePath);
+      continue;
+    }
+    touched.add(relativePath);
+  }
+  releaseRetainedEntries(journal);
+  if (journal.indexApplied) {
+    updateIndex(targetRoot, { drop: journal.indexApplied.written, put: journal.indexApplied.removed });
+  }
+  return {
+    paths: [...touched].sort(shallowestFirst),
+    abandoned: [...new Set(abandoned)].sort(shallowestFirst),
+    ...journal.retained && journal.retained.length > 0 ? { retained: [...journal.retained] } : {}
   };
 }
 function captureWorkingTreeMirrorPlan(input) {
@@ -782,7 +1738,8 @@ function restoreWorkingTreeMirrorScope(input) {
     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;
+      const temporaryStatus = fs.lstatSync(temporaryPath);
+      if (!temporaryStatus.isFile() && !temporaryStatus.isSymbolicLink()) continue;
       fs.rmSync(temporaryPath, { force: true });
       touched.add(directory === "." ? name : path.posix.join(directory, name));
     }
@@ -835,12 +1792,26 @@ function fsyncWorkingTreePaths(root, relativePaths) {
   }
 }
 export {
+  WorkingTreeTargetChangedError,
+  applyWorkingTreeMirror,
   assertWorkingTreeHasNoPortableGitMetadataAliases,
   captureWorkingTreeMirrorPlan,
+  displacedEntryMatches,
   fsyncWorkingTreePaths,
   inspectWorkingTree,
+  inspectWorkingTreePath,
   mirrorWorkingTree,
   normalizeWorkingTreeRelativePath,
+  planPreparedWorkingTreeMirror,
   planWorkingTreeMirror,
-  restoreWorkingTreeMirrorScope
+  prepareWorkingTreeMirror,
+  projectedFileEntry,
+  projectedFileEntryMatches,
+  restoreWorkingTreeMirrorScope,
+  rollbackWorkingTreeMirrorJournal,
+  sameWorkingTreeInode,
+  setWorkingTreeMirrorRaceHook,
+  workingTreeAtomicRenameSupport,
+  workingTreeDisplacedRetentionDirectory,
+  workingTreeStatsMatch
 };