@openclaw/fs-safe 0.21.0 → 0.21.1

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.21.1 - 2026-09-27
+
+### Fixes
+
+- **Linux without `openat2`:** native opens now follow in-root relative symlinks exactly as `RESOLVE_BENEATH` does, rejecting absolute links, `..` escapes, procfs and `nosymfollow` links, and chains longer than 40. Denial and symlink policies report the same errors as the `openat2` path. Links inside sticky world-writable directories are refused. ([#717](https://github.com/openclaw/fs-safe/pull/717))
+- **Deny policies on case-insensitive filesystems:** `denyMutations` now denies creating a not-yet-existing case or Unicode-normalization alias of a denied path (for example `case.txt` when `Case.txt` is denied on APFS, NTFS or casefold ext4). Where a filesystem's sensitivity cannot be proven, Unicode-equivalent names are denied conservatively. ([#720](https://github.com/openclaw/fs-safe/pull/720))
+- **Directory listings:** `list()`, `entries()` and `walk()` reject names that are not valid UTF-8 with `invalid-path` instead of decoding them lossily, which could collide with a real `U+FFFD` name and report another entry's metadata. ([#715](https://github.com/openclaw/fs-safe/pull/715))
+- **ZIP admission:** entries that differ only by case or Unicode normalization are rejected during preflight and member reads, matching extraction's collision policy. ([#716](https://github.com/openclaw/fs-safe/pull/716))
+- **Atomic restore:** when a metadata call fails with `EIO` after the destination was truncated, restore-original writes the original bytes back through the retained, identity-verified descriptor instead of leaving the file empty. ([#718](https://github.com/openclaw/fs-safe/pull/718))
+- **Lock and prune cleanup:** cleanup decisions compare exact bigint file identities. Legacy numeric receipts with IDs above 2^53 are refused instead of risking removal of the wrong file. ([#719](https://github.com/openclaw/fs-safe/pull/719))
+- **Watch overflow:** subscriptions no longer publish spurious whole-scope overflow invalidations for excluded or unselected paths or for slow reconcile passes. macOS streams use OS-level exclusion paths and anchor-scoped streams, and Windows uses a 1 MiB change buffer on local volumes. Genuine OS event drops still invalidate. ([#724](https://github.com/openclaw/fs-safe/pull/724))
+- **Mutation authority:** reject synchronous and asynchronous generator callback results before mutation, so lazy authority checks cannot be skipped. ([#711](https://github.com/openclaw/fs-safe/pull/711))
+- **Synchronous atomic writes:** reject deferred `beforeRename` hooks before publication and clean up the owned stage. ([#728](https://github.com/openclaw/fs-safe/pull/728))
+- **Copy publication callbacks:** reject deferred generator observers in `Root.copyIn()` while preserving the completed destination and source bytes. ([#726](https://github.com/openclaw/fs-safe/pull/726))
+- **Native move diagnostics:** no-clobber `Root.move()` keeps the original native loader error as its cause, including missing libraries or incompatible glibc versions. ([#709](https://github.com/openclaw/fs-safe/pull/709))
+
+### Features
+
+- **Watch polling interval:** `pollIntervalMs` sets the scan interval whenever polling is the selected transport, including `mode: "auto"` falling back to polling, without changing the events reconcile interval. ([#723](https://github.com/openclaw/fs-safe/pull/723))
+
+### Performance
+
+- **Linux directory cloning:** reuse the admitted filesystem type when creating clone sources and cloning trees, avoiding a duplicate filesystem probe and allocation per operation. ([#732](https://github.com/openclaw/fs-safe/pull/732))
+
 ## 0.21.0 - 2026-09-26
 
 ### Highlights

package/dist/archive-zip-directory.js

@@ -1,5 +1,6 @@
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
 import { admitZipNames, zipExtraFields, zipFormat, zipUInt64 } from "./archive-zip-names.js";
+import { createArchiveOutputPathTracker } from "./archive-entry.js";
 function entryKind(attributes, directory) {
     const type = (attributes >>> 16) & 0o170000;
     // High-word symlinks remain links regardless of the creator or directory bits.
@@ -186,6 +187,7 @@ export function* scanZipDirectory(size, limits, onEntry) {
     const directory = yield* layout(size);
     assertArchiveEntryCountWithinLimit(directory.count, limits);
     const seen = new Set();
+    const trackKnownPath = createArchiveOutputPathTracker();
     const spans = [];
     let at = directory.start;
     let count = 0;
@@ -226,6 +228,8 @@ export function* scanZipDirectory(size, limits, onEntry) {
         const localNames = yield* read(localAt + 30, localNameLength + localExtraLength, directory.start);
         const localExtra = zipExtraFields(localNames.subarray(localNameLength));
         const admittedName = admitZipNames({ central: centralName, local: localNames.subarray(0, localNameLength), flags, centralExtra, localExtra, seen });
+        if (admittedName.path !== undefined)
+            trackKnownPath(admittedName.path, admittedName.path);
         const localValues = wideValues(local, localExtra, false);
         const crc = central.readUInt32LE(16);
         if (!(flags & 8) && (local.readUInt32LE(14) !== crc || localValues.compressed !== values.compressed || localValues.uncompressed !== values.uncompressed)) {

package/dist/archive-zip-loader.js

@@ -1,5 +1,5 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, validateArchiveEntryPath } from "./archive-entry.js";
 import { createAdmittedZipEntry } from "./archive-zip-entry.js";
 import { zipPathKey } from "./archive-zip-names.js";
 export function assertZipEntryBinding(archive, record, path) {
@@ -27,7 +27,9 @@ function matchesData(value, physical) {
 /** Internal: the caller has admitted these unchanged bytes and their metadata. */
 export async function loadAdmittedZipArchive(buffer, admitted) {
     const physicalByPath = new Map();
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const entry of admitted) {
+        trackOutputPath(entry.portableKey, entry.portableKey);
         if (physicalByPath.has(entry.portableKey))
             collision();
         physicalByPath.set(entry.portableKey, entry);

package/dist/archive-zip-manifest.js

@@ -1,10 +1,11 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { stripArchivePath } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, stripArchivePath } from "./archive-entry.js";
 /** Associate all native entries with physical admission before exposing any. */
 export function validateNativeZipManifest(manifest, admitted) {
     if (manifest.length !== admitted.length) {
         throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
     }
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const [ordinal, entry] of manifest.entries()) {
         const physical = admitted[ordinal];
         const physicalPath = physical?.path;
@@ -18,5 +19,6 @@ export function validateNativeZipManifest(manifest, admitted) {
             (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
             throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
         }
+        trackOutputPath(entry.path, entry.path);
     }
 }

package/dist/copy-publication.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write-types.js";
-export type RootCopyPublicationReceipt = Readonly<{
+export type RootCopyPublicationReceipt = Readonly<PublishedWriteIdentity & {
     path: string;
-    dev: bigint;
-    ino: bigint;
 }>;
 export declare function createCopyPublicationObserver(path: string, notify?: (receipt: RootCopyPublicationReceipt) => void): {
     onPublished(identity: PublishedWriteIdentity): void;

package/dist/copy-publication.js

@@ -1,16 +1,12 @@
 import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 export function createCopyPublicationObserver(path, notify) {
     let rejected;
     return {
         onPublished(identity) {
             const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
             try {
-                const result = notify?.(receipt);
-                if (result !== null && (typeof result === "object" || typeof result === "function") &&
-                    "then" in result && typeof result.then === "function") {
-                    void Promise.resolve(result).catch(() => undefined);
-                    throw new TypeError("onDestinationPublished must be synchronous");
-                }
+                assertSynchronousCallbackResult(notify?.(receipt), "onDestinationPublished");
             }
             catch (error) {
                 rejected = { error };

package/dist/deny-mutation-match.d.ts

@@ -0,0 +1,2 @@
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export declare function createMutationDenyMatcher(): (target: string, denied: string, prefix: boolean, protectAncestors?: boolean) => boolean;

package/dist/deny-mutation-match.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { isPathInside } from "./path.js";
+import { probePathCaseInsensitiveSync } from "./path-case.js";
+import { observeMutationPath } from "./pinned-mutation-observation.js";
+function foldedName(name) {
+    // Decompose before folding so combining marks precede an expanded Greek subscript.
+    // Default folding preserves dotless i even though its uppercase mapping is I.
+    return name.normalize("NFD").replace(/[^\u0131]+/gu, part => part.toLowerCase().toUpperCase().toLowerCase()).normalize("NFC");
+}
+function asciiCasePair(left, right) {
+    return /^[\x00-\x7f]*$/.test(left) && /^[\x00-\x7f]*$/.test(right) &&
+        left.toLowerCase() === right.toLowerCase();
+}
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export function createMutationDenyMatcher() {
+    const observations = new Map();
+    const caseObservations = new Map();
+    const observe = (pathname) => {
+        if (!observations.has(pathname))
+            observations.set(pathname, observeMutationPath(pathname));
+        return observations.get(pathname);
+    };
+    const prospectiveInside = (parent, child) => {
+        const root = path.parse(parent).root;
+        if (root !== path.parse(child).root)
+            return false;
+        const left = parent.slice(root.length).split(path.sep);
+        const right = child.slice(root.length).split(path.sep).slice(0, left.length);
+        if (left.length !== right.length || !left.every((name, i) => foldedName(name) === foldedName(right[i]))) {
+            return false;
+        }
+        // Byte-identical relations were already handled without any observations.
+        if (left.every((name, i) => name === right[i]))
+            return false;
+        const alignedChild = path.join(root, ...right);
+        const a = observe(parent);
+        const b = observe(alignedChild);
+        if (!a || !b)
+            return true;
+        // Distinct existing ancestors are real objects, not prospective aliases.
+        if (a.canonicalAncestor !== b.canonicalAncestor ||
+            a.missingSegments.length === 0 || a.missingSegments.length !== b.missingSegments.length)
+            return false;
+        const missingLeft = a.missingSegments;
+        const missingRight = b.missingSegments;
+        if (!missingLeft.every((name, i) => foldedName(name) === foldedName(missingRight[i])))
+            return false;
+        const difference = missingLeft.findIndex((name, i) => name !== missingRight[i]);
+        if (difference === -1)
+            return true;
+        // A read-only ASCII observation can disprove aliasing at this existing parent.
+        // It cannot prove Unicode sensitivity or the behavior of a future directory.
+        if (difference === 0 && asciiCasePair(missingLeft[0], missingRight[0])) {
+            if (!caseObservations.has(a.canonicalAncestor)) {
+                caseObservations.set(a.canonicalAncestor, probePathCaseInsensitiveSync(path.join(a.canonicalAncestor, missingLeft[0]), { allowTemporaryProbe: false }));
+            }
+            if (caseObservations.get(a.canonicalAncestor) === false)
+                return false;
+        }
+        // Suffix probing writes directories. Policy admission has no authority for
+        // those side effects, so unproven case/normalization equivalence fails closed.
+        return true;
+    };
+    return (target, denied, prefix, protectAncestors = false) => {
+        if ((isPathInside(denied, target) && (prefix || isPathInside(target, denied))) ||
+            (protectAncestors && isPathInside(target, denied)))
+            return true;
+        return ((prefix || target.split(path.sep).length === denied.split(path.sep).length) &&
+            prospectiveInside(denied, target)) || (protectAncestors && prospectiveInside(target, denied));
+    };
+}

package/dist/deny-mutations.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { assertNoNulPathInput, isNotFoundPathError } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { resolveExistingAncestor } from "./root-path-existing.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
@@ -65,6 +66,7 @@ export function assertMutationNotDenied(filePath, policy, options = {}, mode = "
     const strict = mode === "sync-root-lock";
     const comparablePaths = strict ? strictMutationComparablePaths : resolveMutationComparablePaths;
     const targets = comparablePaths(filePath);
+    const matches = createMutationDenyMatcher();
     // Validate one complete phase at a time. A paths denial must not read or
     // canonicalize prefixes, and invalid later paths retain validation precedence.
     for (const kind of ["paths", "prefixes"]) {
@@ -72,8 +74,7 @@ export function assertMutationNotDenied(filePath, policy, options = {}, mode = "
             const deniedPaths = comparablePaths(entry);
             for (const target of targets) {
                 for (const denied of deniedPaths) {
-                    if ((isPathInside(denied, target) && (kind === "prefixes" || isPathInside(target, denied))) ||
-                        (options.protectAncestors === true && isPathInside(target, denied))) {
+                    if (matches(target, denied, kind === "prefixes", options.protectAncestors)) {
                         throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
                     }
                 }

package/dist/file-identity.js

@@ -22,9 +22,17 @@ export function sameFileIdentity(left, right, platform = process.platform) {
     return (!isStatValueProvablyDifferent(left.dev, right.dev, platform) &&
         !isStatValueProvablyDifferent(left.ino, right.ino, platform));
 }
+function sameCleanupStatValue(left, right) {
+    // Converting an unsafe number to bigint cannot recover an already rounded ID.
+    if (typeof left === "number" && !Number.isSafeInteger(left))
+        return false;
+    if (typeof right === "number" && !Number.isSafeInteger(right))
+        return false;
+    return sameStatValue(left, right);
+}
 export function sameFileIdentityForCleanup(left, right, platform = process.platform) {
     if (platform !== "win32") {
-        return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+        return sameCleanupStatValue(left.dev, right.dev) && sameCleanupStatValue(left.ino, right.ino);
     }
     // A zero Windows device or inode is unknown, not proof that a pathname still
     // names the object we created. Cleanup must fail closed rather than delete a
@@ -44,5 +52,5 @@ export function sameFileIdentityForCleanup(left, right, platform = process.platf
     const rightIno = right.ino;
     if (isZero(rightIno))
         return false;
-    return sameStatValue(leftDev, rightDev) && sameStatValue(leftIno, rightIno);
+    return sameCleanupStatValue(leftDev, rightDev) && sameCleanupStatValue(leftIno, rightIno);
 }

package/dist/file-lock-sync-admission.js

@@ -30,7 +30,11 @@ export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
     const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
     if (createdAtMs !== null)
         return nowMs - createdAtMs > staleMs;
-    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
+    if (!snapshot.stat)
+        return true;
+    const mtimeMs = "mtimeNs" in snapshot.stat
+        ? Number(snapshot.stat.mtimeNs) / 1e6 : snapshot.stat.mtimeMs;
+    return nowMs - mtimeMs > staleMs;
 }
 export function syncReclaimGuardExists(reclaimGuardPath) {
     try {

package/dist/file-lock-sync-root-io.d.ts

@@ -1,4 +1,4 @@
-import { type BigIntStats, type Stats } from "node:fs";
+import { type BigIntStats } from "node:fs";
 import type { RootDefaults } from "./root-options.js";
 import { type FileLockSyncRootPath } from "./file-lock-sync-root.js";
 export type ExactIdentity = Readonly<{
@@ -19,7 +19,7 @@ export type FileLockSyncRootDiskSnapshot = {
     ownershipToken?: never;
     payload: unknown;
     raw: string;
-    stat: Stats;
+    stat: BigIntStats;
 };
 export type FileLockSyncRootSnapshot = Readonly<{
     receipt: FileLockSyncRootFileReceipt;

package/dist/file-lock-sync-root-io.js

@@ -143,7 +143,7 @@ export function readFileLockSyncRootSnapshot(pathAuthority, options = {}) {
             throw error;
         }
         assertRegularFile(after, pathAuthority.authority.hardlinks);
-        const stat = fs.fstatSync(fd);
+        const stat = fs.fstatSync(fd, { bigint: true });
         if (expectedReceipt) {
             assertRetainedParentCurrent(pathAuthority, parent);
         }

package/dist/file-lock-sync.js

@@ -240,7 +240,7 @@ export function acquireFileLockSync(targetPath, options) {
                 createdSnapshot = {
                     raw,
                     payload,
-                    stat: fs.fstatSync(fd),
+                    stat: fs.fstatSync(fd, { bigint: true }),
                     ownershipToken,
                 };
                 createdHeld = {
@@ -280,7 +280,7 @@ export function acquireFileLockSync(targetPath, options) {
                     const failed = createdSnapshot ?? { payload: null };
                     if (!failed.stat) {
                         try {
-                            failed.stat = fs.fstatSync(fd);
+                            failed.stat = fs.fstatSync(fd, { bigint: true });
                         }
                         catch {
                             // Missing identity leaves the sidecar in place, but must not skip close.

package/dist/file-store-prune.js

@@ -23,10 +23,10 @@ export async function pruneExpiredStoreEntries(params) {
     const rootGuard = {
         dir: rootReal,
         realPath: rootReal,
-        stat: fsSync.lstatSync(rootReal),
+        stat: fsSync.lstatSync(rootReal, { bigint: true }),
     };
     async function assertRootGuard() {
-        const stat = fsSync.lstatSync(rootGuard.dir);
+        const stat = fsSync.lstatSync(rootGuard.dir, { bigint: true });
         if (stat.isSymbolicLink() ||
             !stat.isDirectory() ||
             stat.dev !== rootGuard.stat.dev ||
@@ -36,7 +36,7 @@ export async function pruneExpiredStoreEntries(params) {
         }
     }
     async function readStableDirectory(dir) {
-        const before = observeOrNull(() => fsSync.lstatSync(dir));
+        const before = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
         if (!before || before.isSymbolicLink() || !before.isDirectory()) {
             return null;
         }
@@ -48,7 +48,7 @@ export async function pruneExpiredStoreEntries(params) {
         if (!entries) {
             return null;
         }
-        const after = observeOrNull(() => fsSync.lstatSync(dir));
+        const after = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
         if (!after || before.dev !== after.dev || before.ino !== after.ino) {
             return null;
         }

package/dist/mutation-authority.js

@@ -1,3 +1,4 @@
+import { types } from "node:util";
 import { FsSafeError } from "./errors.js";
 export class MutationAuthorityError extends FsSafeError {
     rejection;
@@ -14,6 +15,10 @@ export function assertSynchronousCallbackResult(returned, name) {
         void Promise.resolve(returned).catch(() => undefined);
         throw new TypeError(`${name} must be synchronous`);
     }
+    // A generator returns its iterator before running the callback body.
+    if (types.isGeneratorObject(returned)) {
+        throw new TypeError(`${name} must be synchronous`);
+    }
 }
 export function composeMutationAssertions(defaultAssertion, callAssertion) {
     if (!defaultAssertion && !callAssertion)

package/dist/native-binding.d.ts

@@ -106,6 +106,7 @@ export interface NativeBinding {
     /** Windows-only, private handle custody; no borrowed/runtime descriptors. */
     retainWindowsFile?(directory: string, basename: string, parentDev: bigint, parentIno: bigint, dev: bigint, ino: bigint, size: bigint, mtimeNs: bigint, ctimeNs: bigint, sha256: string, maxBytes: number): NativeRetainedFile;
     watchRegister?(root: string, limit: number, callback: (batch: import("./watch-native.js").NativeWatchWireBatch) => void, persistent: boolean): number;
+    watchConfigure?(id: number, anchors: string[], exclusions: string[]): void;
     watchAdd?(id: number, directory: {
         root: string;
         relative: string;
@@ -117,6 +118,16 @@ export interface NativeBinding {
     watchTestEvent?(id: number, path: string, flags: number): void;
     watchUnregister?(id: number): void;
     watchThreadCount?(): number;
+    watchMemoryStats?(): {
+        registrations: number;
+        pendingSets: number;
+        payloadsLive: number;
+        payloadsCreated: number;
+        payloadsDestroyed: number;
+        threadsafeFunctionsLive: number;
+        threadsafeFunctionsCreated: number;
+        threadsafeFunctionsDestroyed: number;
+    };
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
     /** Internal Darwin-only synchronous inspection; the caller retains its fd. */

package/dist/native-pinned-write.js

@@ -182,8 +182,14 @@ async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryF
             completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
         }
         catch (error) {
-            if (error?.code !== "ENOENT" || !params.mkdir)
-                throw error;
+            if (error?.code !== "ENOENT" || !params.mkdir) {
+                // A mechanism rejection must not hide canonical denial/symlink policy.
+                // This admission only classifies failure; it cannot authorize a retry.
+                await authorizePinnedMutation(params, {
+                    targetPath: initialTarget, mutationPath: initialTarget, phase: "parent",
+                });
+                throw normalizePolicyParentOpenError(error, params);
+            }
         }
         if (completeParentFd !== undefined) {
             const parentFd = completeParentFd;

package/dist/pinned-mutation-admission.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { assertMutationNotDenied } from "./deny-mutations.js";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
 import { FsSafeError } from "./errors.js";
 import { isPathInside } from "./path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
@@ -100,8 +101,9 @@ function epochCurrent(epoch, directories) {
         getFsSafeNativeConfig().mode === epoch.mode;
 }
 function assertCachedNotDenied(target, epoch) {
-    if (epoch.paths.some((paths) => paths.some((denied) => isPathInside(denied, target) && isPathInside(target, denied))) ||
-        epoch.prefixes.some((paths) => paths.some((denied) => isPathInside(denied, target)))) {
+    const matches = createMutationDenyMatcher();
+    if (epoch.paths.some((paths) => paths.some((denied) => matches(target, denied, false))) ||
+        epoch.prefixes.some((paths) => paths.some((denied) => matches(target, denied, true)))) {
         throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
     }
 }

package/dist/replace-file-copy-fallback.js

@@ -177,9 +177,9 @@ async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestor
     catch (writeError) {
         mutation.rethrowRefusal();
         try {
-            await writeAtomicDestination(handle, original, destination?.beforeWrite, destination?.assertBeforeMutation, destination?.writing);
+            await writeAtomicDestination(handle, original, destination?.beforeRestore, destination?.assertBeforeMutation, destination?.writing);
             if (destination)
-                await destination.verify();
+                await destination.verifyRestore();
             await handle.chmod(originalMode);
             await handle.sync();
             throw restoreFailure(writeError, "restored");
@@ -206,8 +206,8 @@ function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes
     catch (writeError) {
         mutation?.rethrowRefusal();
         try {
-            writeAtomicDestinationSync(fsModule, fd, original, destination?.beforeWrite, destination?.writing);
-            destination?.verify();
+            writeAtomicDestinationSync(fsModule, fd, original, destination?.beforeRestore, destination?.writing);
+            destination?.verifyRestore();
             fchmodSync?.(fd, originalMode);
             fsModule.fsyncSync(fd);
             throw restoreFailure(writeError, "restored");

package/dist/replace-file-destination.d.ts

@@ -6,6 +6,8 @@ export declare function captureAtomicDestination(fsModule: Pick<typeof fs, "lsta
     verify: () => Promise<void>;
     writing: () => void;
     beforeWrite: () => Promise<void>;
+    beforeRestore: () => Promise<void>;
+    verifyRestore: () => Promise<void>;
     assertBeforeMutation: () => void;
     published: () => void;
 }>;
@@ -13,5 +15,7 @@ export declare function captureAtomicDestinationSync(fsModule: Pick<typeof fsSyn
     verify: () => void;
     writing: () => void;
     beforeWrite: () => void;
+    beforeRestore: () => void;
+    verifyRestore: () => void;
     published: () => void;
 };

package/dist/replace-file-destination.js

@@ -1,5 +1,6 @@
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
+import { hasErrorCode } from "./file-cleanup.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 function regular(stat, pathname, rejectHardlinks) {
@@ -17,10 +18,41 @@ export async function captureAtomicDestination(fsModule, handle, pathname, mutat
         ? fsSync.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
     const identity = await inspectFileIdentity(inspect);
     regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verifyDescriptor = async () => {
+        await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+    };
     const verify = async () => {
+        let metadataFailure = false;
+        const observe = async (read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            await inspectFileIdentity(async () => regular(await observe(inspect), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await observe(() => fsModule.lstat(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                // A metadata observation failed, but the already-owned descriptor can
+                // still restore its bytes after fresh exact descriptor verification.
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = async () => {
+        if (!restoreDescriptorOnly)
+            return await verify();
         try {
-            await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
-            await inspectFileIdentity(async () => regular(await fsModule.lstat(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
+            await verifyDescriptor();
         }
         catch (error) {
             mutation.refuse(error);
@@ -28,11 +60,13 @@ export async function captureAtomicDestination(fsModule, handle, pathname, mutat
     };
     return {
         verify,
-        writing: () => mutation.destination("writing", pathname, identity),
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
         beforeWrite: async () => {
             mutation.assert();
             await verify();
         },
+        beforeRestore: async () => { mutation.assert(); await verifyRestore(); },
+        verifyRestore,
         assertBeforeMutation: () => mutation.assert(),
         published: () => mutation.destination("published", pathname, identity),
     };
@@ -40,10 +74,36 @@ export async function captureAtomicDestination(fsModule, handle, pathname, mutat
 export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, rejectHardlinks) {
     const identity = inspectFileIdentitySync(() => fsModule.fstatSync(fd, { bigint: true }));
     regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
     const verify = () => {
+        let metadataFailure = false;
+        const observe = (read) => {
+            try {
+                return read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.fstatSync(fd, { bigint: true })), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.lstatSync(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = () => {
+        if (!restoreDescriptorOnly)
+            return verify();
         try {
             inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
-            inspectFileIdentitySync(() => regular(fsModule.lstatSync(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
         }
         catch (error) {
             mutation.refuse(error);
@@ -51,11 +111,13 @@ export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, r
     };
     return {
         verify,
-        writing: () => mutation.destination("writing", pathname, identity),
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
         beforeWrite: () => {
             mutation.assert();
             verify();
         },
+        beforeRestore: () => { mutation.assert(); verifyRestore(); },
+        verifyRestore,
         published: () => mutation.destination("published", pathname, identity),
     };
 }

package/dist/replace-file.js

@@ -14,6 +14,7 @@ import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
 import { AtomicMutation } from "./replace-file-mutation.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
@@ -301,7 +302,7 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mu
         }));
         tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
-            options.beforeRename({ filePath, tempPath });
+            assertSynchronousCallbackResult(options.beforeRename({ filePath, tempPath }), "beforeRename");
             tempOwner.assertCurrent(fsModule);
         }
         if (options.destinationHardlinks === "reject") {

package/dist/retained-file-types.d.ts

@@ -1,10 +1,6 @@
+import type { StagedFileReceipt } from "./staged-file-types.js";
 /** Exact producer observations: never supply rounded Number identities. */
-export type RetainedFileExpected = Readonly<{
-    dev: bigint;
-    ino: bigint;
-    size: bigint;
-    mtimeNs: bigint;
-    ctimeNs: bigint;
+export type RetainedFileExpected = Readonly<Pick<StagedFileReceipt["identity"], "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs"> & {
     /** Lowercase SHA-256 of the producer's expected bytes. */
     sha256: string;
 }>;
@@ -47,14 +43,7 @@ export type RetainedFileAdmission = Readonly<{
     status: "retained";
     file: RetainedFile;
 }> | RetainedFileResult;
-export type RetainFileInDirectoryOptions = Readonly<{
-    directory: string;
-    parent: Readonly<{
-        dev: bigint;
-        ino: bigint;
-    }>;
-    basename: string;
-    expected: RetainedFileExpected;
+export type RetainFileInDirectoryOptions = Readonly<Pick<RetainedFileReceipt, "directory" | "parent" | "basename" | "expected"> & {
     assertBeforeMutation: () => void;
     /** Synchronous verification budget, default 16 MiB; maximum 64 MiB. */
     maxBytes?: number;