agentera 3.0.0-dev.32 → 3.0.0-dev.39

package/dist/state/entityPublicationContext.js

@@ -7,6 +7,7 @@ const DIRECTORY_FLAGS = fs.constants.O_RDONLY
     | (fs.constants.O_DIRECTORY ?? 0)
     | (fs.constants.O_NOFOLLOW ?? 0);
 const FILE_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
+const RECOVERY_IGNORE_BYTES = "*\n!.gitignore\n";
 function samePublished(left, right) {
     return left.dev === right.dev
         && left.ino === right.ino
@@ -75,6 +76,9 @@ function matchesPublished(fd, expected) {
         return false;
     return createHash("sha256").update(readDescriptor(fd)).digest("hex") === expected.sha256;
 }
+function matchesExpected(fd, expected) {
+    return Buffer.isBuffer(expected) ? readDescriptor(fd).equals(expected) : matchesPublished(fd, expected);
+}
 function openMatches(parentFd, name, expectedFd, flags) {
     let observed;
     try {
@@ -89,6 +93,34 @@ function openMatches(parentFd, name, expectedFd, flags) {
             fs.closeSync(observed);
     }
 }
+function entryExists(parentFd, name) {
+    let fd;
+    try {
+        fd = fs.openSync(fdPath(parentFd, name), FILE_FLAGS);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+function pathBytesEqual(parentFd, name, expected) {
+    let fd;
+    try {
+        fd = fs.openSync(fdPath(parentFd, name), FILE_FLAGS);
+        return readDescriptor(fd).equals(expected);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
 function syncDirectory(fd) {
     fs.fsyncSync(fd);
 }
@@ -495,26 +527,29 @@ export class EntityPublicationContext {
             }
         }
     }
-    replaceExisting(relativeTarget, expectedBytes, bytes) {
-        return this.replaceOwned(relativeTarget, expectedBytes, bytes);
+    replaceExisting(relativeTarget, expectedBytes, bytes, maxEntityBytes) {
+        return this.replaceOwned(relativeTarget, expectedBytes, bytes, maxEntityBytes);
     }
-    restoreExact(relativeTarget, expected, bytes) {
+    restoreExact(relativeTarget, expected, bytes, maxEntityBytes) {
         // Recovery stays bound to the pinned root and exact archived target even when context invalidation caused the primary failure.
-        return this.replaceOwned(relativeTarget, expected, bytes, false);
+        return this.replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, false);
     }
-    replaceOwned(relativeTarget, expected, bytes, verifyContext = true) {
+    replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, verifyContext = true) {
         const segments = relativeTarget.split(path.sep).filter(Boolean);
         if (segments.length < 2 || path.isAbsolute(relativeTarget) || segments.includes("..") || segments.includes("."))
             throw new Error(`unsafe entity replacement target '${relativeTarget}'`);
         const directories = [];
         let targetFd;
         let stageFd;
+        let backupFd;
         let stageName;
         let backupName;
         let displacedName;
         let displacedFd;
-        let displacedOwned = false;
-        let replacementVisible = false;
+        let displacementActive = false;
+        let committedResult;
+        let recovery;
+        let baselineBytes;
         try {
             let parentFd = this.rootFd;
             for (const name of segments.slice(0, -1)) {
@@ -527,93 +562,360 @@ export class EntityPublicationContext {
             targetFd = fs.openSync(fdPath(directoryFd, targetName), FILE_FLAGS);
             this.assertBoundary(directories, undefined, { name: targetName, fd: targetFd }, verifyContext);
             const previousBytes = readDescriptor(targetFd);
-            if (typeof expected === "string" ? !previousBytes.equals(Buffer.from(expected)) : !matchesPublished(targetFd, expected))
+            baselineBytes = previousBytes;
+            if (!matchesExpected(targetFd, expected))
                 throw new Error(`entity '${relativeTarget}' ownership changed before replacement; preserve both changes and retry explicitly`);
-            backupName = `.${targetName}.${process.pid}.${randomUUID()}.previous`;
-            fs.linkSync(fdPath(directoryFd, targetName), fdPath(directoryFd, backupName));
-            if (!openMatches(directoryFd, backupName, targetFd, FILE_FLAGS))
-                throw new Error(`entity '${relativeTarget}' prior value could not be pinned for replacement`);
-            stageName = `.${targetName}.${process.pid}.${randomUUID()}.tmp`;
-            stageFd = fs.openSync(fdPath(directoryFd, stageName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+            if (!Number.isSafeInteger(maxEntityBytes) || maxEntityBytes < 1 || previousBytes.length > maxEntityBytes)
+                throw new Error(`entity '${relativeTarget}' exact ${previousBytes.length}-byte baseline exceeds the authority-owned ${maxEntityBytes}-byte recovery limit`);
+            recovery = this.createRecoveryAttempt(directoryFd);
+            backupName = "original.previous";
+            backupFd = fs.openSync(fdPath(recovery.attemptFd, backupName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+            fs.writeFileSync(backupFd, previousBytes);
+            fs.fsyncSync(backupFd);
+            const backupStat = fs.fstatSync(backupFd, { bigint: true });
+            const attemptStat = fs.fstatSync(recovery.attemptFd, { bigint: true });
+            if (!backupStat.isFile() || backupStat.dev !== attemptStat.dev || backupStat.uid !== attemptStat.uid || backupStat.nlink !== 1n || (backupStat.mode & 63n) !== 0n || !openMatches(recovery.attemptFd, backupName, backupFd, FILE_FLAGS) || !readDescriptor(backupFd).equals(previousBytes))
+                throw new Error(`entity '${relativeTarget}' exact prior-byte snapshot could not be verified before replacement`);
+            stageName = "replacement.tmp";
+            stageFd = fs.openSync(fdPath(recovery.attemptFd, stageName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
             fs.writeFileSync(stageFd, bytes, "utf8");
             fs.fsyncSync(stageFd);
-            this.assertBoundary(directories, { name: stageName, fd: stageFd }, { name: targetName, fd: targetFd }, verifyContext);
-            if (verifyContext) {
-                fs.renameSync(fdPath(directoryFd, stageName), fdPath(directoryFd, targetName));
-                replacementVisible = true;
-                stageName = undefined;
+            this.assertBoundary(directories, undefined, { name: targetName, fd: targetFd }, verifyContext);
+            if (!openMatches(recovery.attemptFd, stageName, stageFd, FILE_FLAGS) || !openMatches(recovery.attemptFd, backupName, backupFd, FILE_FLAGS) || !readDescriptor(backupFd).equals(previousBytes))
+                throw new Error(`entity '${relativeTarget}' private recovery attempt changed before displacement`);
+            displacedName = "original.displaced";
+            fs.renameSync(fdPath(directoryFd, targetName), fdPath(recovery.attemptFd, displacedName));
+            displacementActive = true;
+            displacedFd = fs.openSync(fdPath(recovery.attemptFd, displacedName), FILE_FLAGS);
+            if (!openMatches(recovery.attemptFd, displacedName, targetFd, FILE_FLAGS) || !matchesExpected(displacedFd, expected))
+                throw new Error(`entity '${relativeTarget}' ownership changed after staging; competing bytes were preserved at the target`);
+            try {
+                fs.linkSync(fdPath(recovery.attemptFd, stageName), fdPath(directoryFd, targetName));
             }
-            else {
-                displacedName = `.${targetName}.${process.pid}.${randomUUID()}.displaced`;
-                fs.renameSync(fdPath(directoryFd, targetName), fdPath(directoryFd, displacedName));
-                displacedFd = fs.openSync(fdPath(directoryFd, displacedName), FILE_FLAGS);
-                if (typeof expected === "string" || !matchesPublished(displacedFd, expected)) {
-                    try {
-                        fs.linkSync(fdPath(directoryFd, displacedName), fdPath(directoryFd, targetName));
-                        if (!openMatches(directoryFd, targetName, displacedFd, FILE_FLAGS))
-                            throw new Error("competing entity could not be returned to its pathname");
-                        syncDirectory(directoryFd);
-                    }
-                    catch (restoreError) {
-                        throw new Error(`entity '${relativeTarget}' ownership changed immediately before restoration; competing bytes remain at '${displacedName}'`, { cause: restoreError });
-                    }
-                    throw new Error(`entity '${relativeTarget}' ownership changed immediately before restoration; competing bytes were preserved at the target and '${displacedName}'`);
-                }
-                displacedOwned = true;
-                try {
-                    fs.linkSync(fdPath(directoryFd, stageName), fdPath(directoryFd, targetName));
-                }
-                catch (publishError) {
-                    if (publishError.code === "EEXIST")
-                        throw new Error(`entity '${relativeTarget}' ownership changed during no-clobber restoration publication; competing bytes were preserved`, { cause: publishError });
-                    throw publishError;
-                }
-                replacementVisible = true;
-                this.removeOwnedFile(directoryFd, stageName, stageFd);
-                stageName = undefined;
-                this.removeOwnedFile(directoryFd, displacedName, targetFd);
-                displacedName = undefined;
+            catch (publishError) {
+                if (publishError.code === "EEXIST")
+                    throw new Error(`entity '${relativeTarget}' ownership changed during no-clobber publication; competing target bytes were preserved`, { cause: publishError });
+                throw publishError;
             }
+            if (!this.removeOwnedFile(recovery.attemptFd, stageName, stageFd))
+                throw new Error(`entity '${relativeTarget}' replacement stage changed before cleanup`);
+            stageName = undefined;
             syncDirectory(directoryFd);
+            syncDirectory(recovery.attemptFd);
             this.assertBoundary(directories, undefined, { name: targetName, fd: stageFd }, verifyContext);
-            this.removeOwnedFile(directoryFd, backupName, targetFd);
-            backupName = undefined;
-            return { previousBytes: previousBytes.toString("utf8"), publishedIdentity: publishedIdentity(stageFd) };
+            if (!openMatches(recovery.attemptFd, displacedName, targetFd, FILE_FLAGS) || !matchesExpected(displacedFd, expected))
+                throw new Error(`entity '${relativeTarget}' ownership changed through the publication boundary; competing bytes remain recoverable`);
+            committedResult = { previousBytes: previousBytes.toString("utf8"), publishedIdentity: publishedIdentity(stageFd) };
+            this.cleanupCommittedReplacement(recovery.attemptFd, [[displacedName, targetFd], [backupName, backupFd]]);
+            displacementActive = false;
+            return committedResult;
         }
         catch (error) {
+            if (committedResult)
+                return committedResult;
             const directoryFd = directories.at(-1)?.fd;
-            if (verifyContext && replacementVisible && directoryFd !== undefined && stageFd !== undefined && targetFd !== undefined) {
-                const ownsReplacement = openMatches(directoryFd, segments.at(-1), stageFd, FILE_FLAGS);
-                const ownsPrior = backupName !== undefined && openMatches(directoryFd, backupName, targetFd, FILE_FLAGS);
-                if (ownsReplacement && ownsPrior) {
-                    fs.renameSync(fdPath(directoryFd, backupName), fdPath(directoryFd, segments.at(-1)));
-                    backupName = undefined;
-                    syncDirectory(directoryFd);
-                }
-                else if (ownsReplacement) {
-                    throw new Error(`entity '${relativeTarget}' replacement failed and its descriptor-pinned prior value could not be restored`, { cause: error });
-                }
+            if (displacementActive && directoryFd !== undefined && targetFd !== undefined && recovery) {
+                throw this.recoverDisplacedReplacement({ directoryFd, recoveryFd: recovery.attemptFd, recoveryPath: recovery.relativePath, relativeTarget, baselineBytes: baselineBytes, backupFd, stageFd, stageName, backupName, displacedFd, displacedName, retainStage: !verifyContext, primary: error });
             }
+            const cleanupFailures = [];
+            for (const [name, fd, label] of [[stageName, stageFd, "stage"], [backupName, backupFd, "backup"]])
+                if (name && fd !== undefined) {
+                    try {
+                        if (!recovery || !this.removeOwnedFile(recovery.attemptFd, name, fd))
+                            cleanupFailures.push(`${label} '${recovery ? path.join(recovery.relativePath, name) : name}' changed`);
+                    }
+                    catch (cleanupError) {
+                        cleanupFailures.push(`${label} '${recovery ? path.join(recovery.relativePath, name) : name}': ${cleanupError.message}`);
+                    }
+                }
+            if (cleanupFailures.length)
+                throw new Error(`${error.message}; cleanup retained attempt state: ${cleanupFailures.join("; ")}`, { cause: error });
             throw error;
         }
         finally {
-            const directoryFd = directories.at(-1)?.fd;
-            if (directoryFd !== undefined && stageFd !== undefined && stageName !== undefined)
-                this.removeOwnedFile(directoryFd, stageName, stageFd);
-            if (directoryFd !== undefined && targetFd !== undefined && backupName !== undefined)
-                this.removeOwnedFile(directoryFd, backupName, targetFd);
-            if (directoryFd !== undefined && targetFd !== undefined && displacedName !== undefined && displacedOwned)
-                this.removeOwnedFile(directoryFd, displacedName, targetFd);
             if (displacedFd !== undefined)
                 fs.closeSync(displacedFd);
+            if (backupFd !== undefined)
+                fs.closeSync(backupFd);
             if (stageFd !== undefined)
                 fs.closeSync(stageFd);
             if (targetFd !== undefined)
                 fs.closeSync(targetFd);
             for (const entry of directories.reverse())
                 fs.closeSync(entry.fd);
+            if (recovery)
+                this.closeRecoveryAttempt(recovery);
         }
     }
+    createRecoveryAttempt(targetDirectoryFd) {
+        const rootName = ".entity-recovery";
+        const agenteraFd = fs.openSync(fdPath(this.rootFd, ".agentera"), DIRECTORY_FLAGS);
+        let rootFd;
+        let ignoreFd;
+        let ignoreCreated = false;
+        let attemptFd;
+        let attemptName;
+        let rootCreated = false;
+        try {
+            try {
+                rootFd = fs.openSync(fdPath(agenteraFd, rootName), DIRECTORY_FLAGS);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw new Error(`private entity recovery root '.agentera/${rootName}' cannot be opened safely: ${error.message}`, { cause: error });
+                fs.mkdirSync(fdPath(agenteraFd, rootName), 0o700);
+                rootCreated = true;
+                syncDirectory(agenteraFd);
+                rootFd = fs.openSync(fdPath(agenteraFd, rootName), DIRECTORY_FLAGS);
+            }
+            const rootStat = fs.fstatSync(rootFd, { bigint: true });
+            if ((rootStat.mode & 18n) !== 0n || (typeof process.getuid === "function" && rootStat.uid !== BigInt(process.getuid())))
+                throw new Error(`private entity recovery root '.agentera/${rootName}' must be owned by the current user and not group/world-writable`);
+            if (rootStat.dev !== fs.fstatSync(targetDirectoryFd, { bigint: true }).dev)
+                throw new Error("private entity recovery root must share the canonical entity target filesystem");
+            try {
+                ignoreFd = fs.openSync(fdPath(rootFd, ".gitignore"), FILE_FLAGS);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw new Error(`private entity recovery ignore marker cannot be opened safely: ${error.message}`, { cause: error });
+                ignoreFd = fs.openSync(fdPath(rootFd, ".gitignore"), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+                ignoreCreated = true;
+                fs.writeFileSync(ignoreFd, RECOVERY_IGNORE_BYTES, "utf8");
+                fs.fsyncSync(ignoreFd);
+            }
+            const ignoreStat = fs.fstatSync(ignoreFd, { bigint: true });
+            if (!ignoreStat.isFile() || (ignoreStat.mode & 18n) !== 0n || (typeof process.getuid === "function" && ignoreStat.uid !== BigInt(process.getuid())) || !readDescriptor(ignoreFd).equals(Buffer.from(RECOVERY_IGNORE_BYTES)))
+                throw new Error("private entity recovery ignore marker must be an owner-controlled regular file with the authoritative rules");
+            syncDirectory(rootFd);
+            for (let attempt = 0; attempt < 8; attempt += 1) {
+                const candidate = `entity-${process.pid}-${randomUUID()}`;
+                try {
+                    fs.mkdirSync(fdPath(rootFd, candidate), 0o700);
+                    attemptName = candidate;
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                }
+            }
+            if (!attemptName)
+                throw new Error("could not allocate a unique private entity recovery attempt after 8 tries");
+            attemptFd = fs.openSync(fdPath(rootFd, attemptName), DIRECTORY_FLAGS);
+            const attemptStat = fs.fstatSync(attemptFd, { bigint: true });
+            if ((attemptStat.mode & 63n) !== 0n || attemptStat.uid !== rootStat.uid || attemptStat.dev !== rootStat.dev)
+                throw new Error("private entity recovery attempt must be owner-only, owner-controlled, and on the recovery-root filesystem");
+            syncDirectory(rootFd);
+            return { agenteraFd, rootFd, attemptFd, ignoreFd, attemptName, relativePath: `.agentera/${rootName}/${attemptName}` };
+        }
+        catch (error) {
+            if (attemptFd !== undefined)
+                fs.closeSync(attemptFd);
+            if (rootFd !== undefined && attemptName) {
+                try {
+                    fs.rmdirSync(fdPath(rootFd, attemptName));
+                }
+                catch { /* preserve unexpected contents */ }
+            }
+            if (rootFd !== undefined && ignoreFd !== undefined && ignoreCreated) {
+                try {
+                    this.removeOwnedFile(rootFd, ".gitignore", ignoreFd);
+                }
+                catch { /* preserve changed marker */ }
+            }
+            if (ignoreFd !== undefined)
+                fs.closeSync(ignoreFd);
+            if (rootFd !== undefined)
+                fs.closeSync(rootFd);
+            if (rootCreated) {
+                try {
+                    fs.rmdirSync(fdPath(agenteraFd, rootName));
+                }
+                catch { /* preserve non-empty or changed root */ }
+            }
+            fs.closeSync(agenteraFd);
+            throw error;
+        }
+    }
+    closeRecoveryAttempt(recovery) {
+        try {
+            if (openMatches(recovery.rootFd, recovery.attemptName, recovery.attemptFd, DIRECTORY_FLAGS)) {
+                try {
+                    fs.rmdirSync(fdPath(recovery.rootFd, recovery.attemptName));
+                    syncDirectory(recovery.rootFd);
+                }
+                catch { /* best-effort private cleanup retains non-empty or changed attempt */ }
+            }
+            const remaining = fs.readdirSync(fdPath(recovery.rootFd));
+            if (remaining.length === 1 && remaining[0] === ".gitignore" && openMatches(recovery.rootFd, ".gitignore", recovery.ignoreFd, FILE_FLAGS)) {
+                try {
+                    this.removeOwnedFile(recovery.rootFd, ".gitignore", recovery.ignoreFd);
+                    syncDirectory(recovery.rootFd);
+                }
+                catch { /* preserve marker on cleanup failure */ }
+            }
+            if (openMatches(recovery.agenteraFd, ".entity-recovery", recovery.rootFd, DIRECTORY_FLAGS)) {
+                try {
+                    fs.rmdirSync(fdPath(recovery.agenteraFd, ".entity-recovery"));
+                    syncDirectory(recovery.agenteraFd);
+                }
+                catch { /* best-effort private cleanup retains non-empty or changed root */ }
+            }
+        }
+        catch {
+            /* committed or already-recovered state must not be reclassified by private cleanup */
+        }
+        finally {
+            for (const fd of [recovery.attemptFd, recovery.ignoreFd, recovery.rootFd, recovery.agenteraFd]) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* best-effort descriptor close */ }
+            }
+        }
+    }
+    cleanupCommittedReplacement(directoryFd, links) {
+        for (const [name, fd] of links) {
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                try {
+                    this.removeOwnedFile(directoryFd, name, fd);
+                    break;
+                }
+                catch { /* committed publication remains authoritative; retry once and otherwise retain recovery link */ }
+            }
+        }
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                syncDirectory(directoryFd);
+                break;
+            }
+            catch { /* cleanup durability is best-effort after the durable commit boundary */ }
+        }
+    }
+    recoverDisplacedReplacement(state) {
+        const { directoryFd, recoveryFd, recoveryPath, relativeTarget, baselineBytes, backupFd, stageFd, displacedFd, retainStage, primary } = state;
+        const targetName = path.basename(relativeTarget);
+        const failures = [];
+        const retained = new Set();
+        let { stageName, backupName, displacedName } = state;
+        const publicPath = (name) => path.join(recoveryPath, name).split(path.sep).join("/");
+        const exactBaseline = () => Boolean(backupName && backupFd !== undefined && openMatches(recoveryFd, backupName, backupFd, FILE_FLAGS) && readDescriptor(backupFd).equals(baselineBytes));
+        const exactDisplaced = () => Boolean(displacedName && displacedFd !== undefined && openMatches(recoveryFd, displacedName, displacedFd, FILE_FLAGS));
+        const exactStage = () => Boolean(stageName && stageFd !== undefined && openMatches(recoveryFd, stageName, stageFd, FILE_FLAGS));
+        const remove = (name, fd, label) => {
+            try {
+                if (this.removeOwnedFile(recoveryFd, name, fd))
+                    return true;
+                failures.push(`${label} '${publicPath(name)}' changed before cleanup`);
+            }
+            catch (error) {
+                failures.push(`${label} '${publicPath(name)}' cleanup failed: ${error.message}`);
+            }
+            retained.add(publicPath(name));
+            return false;
+        };
+        const sync = (label) => { try {
+            syncDirectory(directoryFd);
+            syncDirectory(recoveryFd);
+            return true;
+        }
+        catch (error) {
+            failures.push(`${label} directory fsync failed: ${error.message}`);
+            return false;
+        } };
+        const displacedBytes = exactDisplaced() ? readDescriptor(displacedFd) : undefined;
+        const displacedCompetitor = Boolean(displacedBytes && !displacedBytes.equals(baselineBytes));
+        const source = displacedCompetitor ? displacedName : exactBaseline() ? backupName : exactDisplaced() && displacedBytes?.equals(baselineBytes) ? displacedName : undefined;
+        const sourceFd = source === backupName ? backupFd : source === displacedName ? displacedFd : undefined;
+        if (stageFd !== undefined && openMatches(directoryFd, targetName, stageFd, FILE_FLAGS) && source && sourceFd !== undefined) {
+            try {
+                if (this.removeOwnedFile(directoryFd, targetName, stageFd))
+                    sync("replacement removal");
+                else
+                    failures.push(`published replacement '${relativeTarget}' changed before cleanup`);
+            }
+            catch (error) {
+                failures.push(`published replacement '${relativeTarget}' cleanup failed: ${error.message}`);
+            }
+        }
+        let restoredBaseline = pathBytesEqual(directoryFd, targetName, baselineBytes);
+        let restoredCompetitor = Boolean(displacedCompetitor && displacedFd !== undefined && openMatches(directoryFd, targetName, displacedFd, FILE_FLAGS));
+        let occupied = !restoredBaseline && !restoredCompetitor && entryExists(directoryFd, targetName);
+        if (!restoredBaseline && !restoredCompetitor && !occupied && source && sourceFd !== undefined) {
+            try {
+                fs.linkSync(fdPath(recoveryFd, source), fdPath(directoryFd, targetName));
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    failures.push(`restoration from '${publicPath(source)}' failed: ${error.message}`);
+            }
+            restoredBaseline = pathBytesEqual(directoryFd, targetName, baselineBytes);
+            restoredCompetitor = Boolean(displacedCompetitor && displacedFd !== undefined && openMatches(directoryFd, targetName, displacedFd, FILE_FLAGS));
+            occupied = !restoredBaseline && !restoredCompetitor && entryExists(directoryFd, targetName);
+        }
+        if (restoredBaseline || restoredCompetitor) {
+            const durable = sync(restoredBaseline ? "exact baseline restoration" : "competitor restoration");
+            if (durable) {
+                if (retainStage && exactStage())
+                    retained.add(publicPath(stageName));
+                else if (exactStage() && remove(stageName, stageFd, "replacement stage"))
+                    stageName = undefined;
+                if (restoredCompetitor) {
+                    if (exactBaseline())
+                        retained.add(publicPath(backupName));
+                    else
+                        failures.push("exact baseline snapshot is unavailable");
+                    if (exactDisplaced() && remove(displacedName, displacedFd, "canonicalized competitor duplicate"))
+                        displacedName = undefined;
+                }
+                else {
+                    if (displacedCompetitor && exactDisplaced())
+                        retained.add(publicPath(displacedName));
+                    else if (exactDisplaced() && remove(displacedName, displacedFd, "displaced baseline duplicate"))
+                        displacedName = undefined;
+                    if (exactBaseline() && remove(backupName, backupFd, "baseline snapshot duplicate"))
+                        backupName = undefined;
+                }
+                sync("restoration cleanup");
+            }
+            for (const name of [backupName, displacedName, stageName])
+                if (name && entryExists(recoveryFd, name))
+                    retained.add(publicPath(name));
+            const outcome = restoredCompetitor
+                ? `recovery restored concurrent competitor bytes at '${relativeTarget}' and retained the exact discovered baseline snapshot at ${exactBaseline() ? `'${publicPath(backupName)}'` : "an unavailable path"}`
+                : `recovery restored byte-verified exact prior bytes at '${relativeTarget}'`;
+            return new Error(`${primary.message}; ${outcome}${retained.size ? `; retained recovery files: ${[...retained].join(", ")}` : ""}${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
+        }
+        if (occupied) {
+            if (exactBaseline())
+                retained.add(publicPath(backupName));
+            else
+                failures.push("exact baseline snapshot is unavailable");
+            if (displacedCompetitor && exactDisplaced())
+                retained.add(publicPath(displacedName));
+            if (sync("competing-target retention")) {
+                if (retainStage && exactStage())
+                    retained.add(publicPath(stageName));
+                else if (exactStage() && remove(stageName, stageFd, "replacement stage"))
+                    stageName = undefined;
+                if (!displacedCompetitor && exactDisplaced() && remove(displacedName, displacedFd, "displaced baseline duplicate"))
+                    displacedName = undefined;
+                sync("retention cleanup");
+            }
+            for (const name of [backupName, displacedName, stageName])
+                if (name && entryExists(recoveryFd, name))
+                    retained.add(publicPath(name));
+            return new Error(`${primary.message}; recovery preserved the competing canonical target and retained the exact discovered baseline snapshot and any displaced competitor at ${[...retained].join(", ") || "unavailable paths"}; preserve each role and resolve ownership explicitly${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
+        }
+        if (exactBaseline())
+            retained.add(publicPath(backupName));
+        if (exactDisplaced())
+            retained.add(publicPath(displacedName));
+        if (exactStage())
+            retained.add(publicPath(stageName));
+        return new Error(`${primary.message}; recovery could not restore the absent canonical target; retained role-labeled recovery files: ${[...retained].join(", ") || "none"}; restore the exact baseline or competitor explicitly before retrying${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
+    }
     close() {
         if (this.closed)
             return;
@@ -641,8 +943,9 @@ export class EntityPublicationContext {
     }
     removeOwnedFile(parentFd, name, expectedFd) {
         if (!openMatches(parentFd, name, expectedFd, FILE_FLAGS))
-            return;
+            return false;
         fs.unlinkSync(fdPath(parentFd, name));
+        return true;
     }
     removeCreatedDirectories(directories) {
         for (const entry of [...directories].reverse()) {