@openclaw/fs-safe 0.20.0 → 0.21.1

package/dist/watch.js

@@ -0,0 +1,530 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { rootHandleContext } from "./root-handle-context.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { admittedNativeChanges } from "./watch-alias.js";
+import { watchStreamPaths } from "./watch-stream.js";
+import { changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import path from "node:path";
+import { watchBinding, NativeWatchBackend } from "./watch-native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { isWatchPathError, scanWatch, watchScopes } from "./watch-scan.js";
+function deferred() {
+    let settled = false;
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    // Ownership exists even when a consumer closes without awaiting startup.
+    void promise.catch(() => { });
+    return { promise, get settled() { return settled; },
+        resolve() { settled = true; resolve(); },
+        reject(error) { settled = true; reject(error); },
+    };
+}
+function budget(value, fallback, name, max = 1_000_000) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > max)
+        throw new RangeError("invalid watch " + name);
+    return result;
+}
+const retired = () => new DOMException("Watch generation retired", "AbortError");
+const coalesceMs = 25;
+/** Advisory observation only. Hints never grant filesystem authority. */
+export function watch(root, input) {
+    const context = rootHandleContext(root);
+    const options = { ...input };
+    const persistent = options.persistent !== false;
+    if (!["auto", "events", "poll"].includes(options.mode))
+        throw new TypeError("invalid watch mode");
+    let binding;
+    let selectionFailure;
+    try {
+        binding = watchBinding(options.mode);
+    }
+    catch (error) {
+        selectionFailure = error;
+    }
+    let mode = binding || options.mode === "events" ? "events" : "poll";
+    let intervalMs = budget(options.intervalMs, mode === "events" ? 30_000 : 1000, "intervalMs", 2_147_483_647);
+    if (intervalMs < 20)
+        throw new RangeError("watch intervalMs must be at least 20");
+    const pollIntervalMs = budget(options.pollIntervalMs, options.intervalMs ?? 1000, "pollIntervalMs", 2_147_483_647);
+    if (pollIntervalMs < 20)
+        throw new RangeError("watch pollIntervalMs must be at least 20");
+    if (mode === "poll")
+        intervalMs = pollIntervalMs;
+    const maxDirectories = budget(options.maxDirectories, 4096, "maxDirectories");
+    const maxEntries = budget(options.maxEntries, 100_000, "maxEntries");
+    const maxPendingPaths = budget(options.maxPendingPaths, 256, "maxPendingPaths", 4096);
+    if (typeof options.onInvalidate !== "function")
+        throw new TypeError("watch requires onInvalidate");
+    const makeGeneration = (scopes) => ({
+        scopes: watchScopes(scopes), abort: new AbortController(), waiter: deferred(),
+    });
+    let current = makeGeneration(options.scopes);
+    const ready = current.waiter.promise;
+    let state = "starting";
+    let terminal = false;
+    let failure;
+    let failureInfo;
+    let retirementFailure;
+    const retirementErrors = new Set();
+    let closing;
+    let active;
+    let backend;
+    const registered = new Map();
+    let observedDirectories = 0;
+    let snapshot;
+    let resetRequested = false;
+    let refreshBackend = false;
+    let pending = false;
+    let pendingWaiter;
+    let runningWaiter;
+    let pendingHint = false;
+    let pendingBackendOverflow = false;
+    let pendingChanges = new Map();
+    let timer;
+    let hintTimer;
+    const combinedFailure = () => {
+        if (!retirementFailure)
+            return failure;
+        const error = retirementFailure.error;
+        if (failure === undefined || error === failure || error?.suppressed === failure)
+            return error;
+        return createSuppressedError(error, failure, "watch observation and retirement failed");
+    };
+    const retainRetirement = (error) => {
+        if (retirementErrors.has(error))
+            return;
+        retirementErrors.add(error);
+        retirementFailure = { error: retirementFailure
+                ? createSuppressedError(error, retirementFailure.error, "watch retirement failed more than once") : error };
+    };
+    const health = () => Object.freeze({
+        state, mode, directories: observedDirectories,
+        ...(failure === undefined && !retirementFailure ? {} : {
+            failure: retirementFailure ? Object.freeze({ operation: "close", error: combinedFailure() }) : failureInfo,
+        }),
+    });
+    const check = (g) => {
+        g.abort.signal.throwIfAborted();
+        if (terminal || current !== g)
+            throw retired();
+        if (failure !== undefined)
+            throw failure;
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const clearTimers = () => {
+        clearTimeout(timer);
+        clearTimeout(hintTimer);
+        timer = undefined;
+        hintTimer = undefined;
+        pending = false;
+        pendingHint = false;
+        pendingChanges = new Map();
+        pendingBackendOverflow = false;
+    };
+    const notifyHealth = () => {
+        try {
+            const result = options.onHealth?.(health());
+            assertSynchronousCallbackResult(result, "watch onHealth");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch health callback failed", { cause, details: { operation: "callback" } });
+        }
+    };
+    const dirty = (g, reason, changes) => {
+        check(g);
+        try {
+            const result = options.onInvalidate(Object.freeze({ reason, changes: changes && Object.freeze(changes) }));
+            assertSynchronousCallbackResult(result, "watch onInvalidate");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch dirty callback failed", { cause, details: { operation: "callback" } });
+        }
+        check(g);
+    };
+    const retain = (error) => {
+        if (failure === undefined) {
+            failure = error;
+            failureInfo = Object.freeze({ operation: "close", error });
+        }
+        else if (error !== failure)
+            failure = createSuppressedError(error, failure, "watch and retirement both failed");
+    };
+    const retireBackend = async () => {
+        const old = backend;
+        try {
+            await old?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        if (backend === old) {
+            backend = undefined;
+            registered.clear();
+            observedDirectories = 0;
+        }
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const lose = (error, operation = "scan") => {
+        if (terminal || failure !== undefined)
+            return;
+        if (error === undefined)
+            error = new FsSafeError("helper-failed", "watch operation failed without an error value", { details: { operation } });
+        retain(error);
+        const details = error instanceof FsSafeError ? error.details : undefined;
+        const code = details?.code ?? error?.code;
+        failureInfo = Object.freeze({ error, operation: details?.operation === "watch" ? "watch" : details?.operation === "callback" ? "callback" : details?.operation === "close" ? "close" : operation, ...(typeof code === "string" ? { code } : {}) });
+        current.abort.abort(error);
+        current.waiter.reject(error);
+        pendingWaiter?.reject(error);
+        runningWaiter?.reject(error);
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        state = "unavailable";
+        // Stop backend admission before notifying. Its join remains owned by active/close.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        try {
+            notifyHealth();
+        }
+        catch (callbackError) {
+            retain(callbackError);
+        }
+    };
+    const scheduleInterval = () => {
+        if (terminal || failure !== undefined)
+            return;
+        timer = setTimeout(() => { timer = undefined; void request().catch(() => { }); }, intervalMs);
+        if (!persistent)
+            timer.unref();
+    };
+    const onHint = (g, batch) => {
+        if (terminal || current !== g || g.abort.signal.aborted || failure !== undefined)
+            return;
+        if (batch.overflow) {
+            pendingBackendOverflow = true;
+            try {
+                assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "received"), "afterWatchBackendOverflow");
+            }
+            catch (error) {
+                lose(error, "callback");
+                return;
+            }
+        }
+        if (batch.error === "ESTALE")
+            refreshBackend = true;
+        else if (batch.error) {
+            lose(new FsSafeError("helper-failed", "native watch failed", { details: { operation: "watch", code: batch.error } }));
+            return;
+        }
+        if (batch.overflow)
+            pendingChanges = undefined;
+        else if (pendingChanges)
+            for (const hint of batch.hints) {
+                if (typeof hint.name === "string" && excludedWatchPath(snapshot, hint.directory ? path.join(hint.directory, hint.name) : hint.name))
+                    continue;
+                const key = JSON.stringify([hint.directory, hint.name]);
+                if (!pendingChanges.has(key) && pendingChanges.size >= maxPendingPaths) {
+                    pendingChanges = undefined;
+                    break;
+                }
+                const previous = pendingChanges.get(key);
+                pendingChanges.set(key, previous?.event === "rename" ? previous : hint);
+            }
+        pendingHint = true;
+        pending = true;
+        if (hintTimer)
+            return;
+        hintTimer = setTimeout(() => {
+            hintTimer = undefined;
+            if (terminal || current !== g || failure !== undefined)
+                return;
+            // Raw backend filenames stay private. Reconcile before publishing detail.
+            void request().catch(() => { });
+        }, coalesceMs);
+        if (!persistent)
+            hintTimer.unref();
+    };
+    const fallBack = (error) => {
+        if (options.mode !== "auto" || getFsSafeNativeConfig().mode === "require" ||
+            !(error instanceof FsSafeError) || error.code !== "helper-unavailable")
+            return false;
+        mode = "poll";
+        binding = undefined;
+        intervalMs = pollIntervalMs;
+        return true;
+    };
+    const observe = async (g) => {
+        check(g);
+        if (selectionFailure !== undefined)
+            throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { cause: selectionFailure, details: { operation: "watch" } });
+        if (refreshBackend) {
+            await retireBackend();
+            check(g);
+            refreshBackend = false;
+        }
+        if (resetRequested) {
+            await retireBackend();
+            check(g);
+            snapshot = undefined;
+            resetRequested = false;
+        }
+        state = snapshot ? "reconciling" : "starting";
+        notifyHealth();
+        check(g);
+        const hadHints = pendingHint;
+        const hadBackendOverflow = pendingBackendOverflow;
+        const hints = pendingChanges;
+        pendingHint = false;
+        pendingChanges = new Map();
+        pendingBackendOverflow = false;
+        clearTimeout(hintTimer);
+        hintTimer = undefined;
+        if (mode === "events" && !backend && g.scopes.length) {
+            try {
+                const candidate = new NativeWatchBackend(binding, context, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, maxPendingPaths, persistent);
+                backend = candidate;
+                if (snapshot)
+                    candidate.configure(watchStreamPaths(snapshot, g.scopes));
+                const hookResult = getFsSafeTestHooks()?.afterWatchBackendCreated?.(context.rootReal, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, (path, flags) => candidate.testEvent(path, flags));
+                assertSynchronousCallbackResult(hookResult, "afterWatchBackendCreated");
+            }
+            catch (error) {
+                if (!fallBack(error))
+                    throw error;
+            }
+            check(g);
+        }
+        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot, previous: snapshot }, g.abort.signal, async (name, identity, guard) => {
+            check(g);
+            const existing = registered.get(name);
+            const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
+            await getFsSafeTestHooks()?.beforeWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire) {
+                try {
+                    backend?.add(name, identity);
+                }
+                catch (error) {
+                    if (snapshot || !fallBack(error))
+                        throw error;
+                    await retireBackend();
+                    check(g);
+                }
+            }
+            await getFsSafeTestHooks()?.afterWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire)
+                registered.set(name, identity);
+        }, retainRetirement);
+        check(g);
+        if (backend?.configure(watchStreamPaths(next, g.scopes))) {
+            // The replacement stream is live before the next guarded pass covers the handover.
+            pending = true;
+        }
+        // Retire stale inventory before the next pass; that crawl installs fresh anchors first.
+        if ([...registered.keys()].some(name => !next.directories.has(name))) {
+            refreshBackend = true;
+        }
+        observedDirectories = next.directories.size;
+        const initial = !snapshot;
+        let observed = next.overflow ? undefined : changedEntries(snapshot, next, maxPendingPaths);
+        if (observed) {
+            const changes = new Map(observed.map(change => [change.path, change]));
+            for (const name of next.structural ?? [])
+                for (const change of scopedChanges(g.scopes, { path: name, type: "structural" }))
+                    changes.set(change.path, change);
+            observed = changes.size > maxPendingPaths ? undefined : [...changes.values()];
+        }
+        let admittedHints = [];
+        try {
+            if (hadHints)
+                admittedHints = await admittedNativeChanges(context, g.scopes, snapshot, next, {
+                    hints: hints ? [...hints.values()] : [], overflow: !hints,
+                }, g.abort.signal, maxPendingPaths);
+        }
+        catch (error) {
+            check(g);
+            await assertRootIdentityCurrent(context);
+            if (!isWatchPathError(error))
+                throw error;
+            admittedHints = undefined;
+        }
+        check(g);
+        await assertRootIdentityCurrent(context);
+        check(g);
+        let details = hadHints
+            ? guardedHintChanges(g.scopes, snapshot, next, admittedHints, observed, maxPendingPaths)
+            : observed;
+        snapshot = next;
+        if (!initial && !details && hadBackendOverflow) {
+            assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "reconciled"), "afterWatchBackendOverflow");
+        }
+        // Publish before readiness; callbacks may synchronously retire this generation.
+        if (initial || !details || details.length)
+            dirty(g, initial ? "reconcile" : !details ? "overflow" : hadHints ? "event" : "reconcile", initial ? undefined : details);
+        check(g);
+        state = "ready";
+        notifyHealth();
+        check(g);
+    };
+    const pump = () => {
+        if (active || terminal || failure !== undefined)
+            return;
+        // Enroll before any callback. There is one active pass and one coalesced request.
+        active = Promise.resolve().then(async () => {
+            do {
+                const g = current;
+                pending = false;
+                if (pendingWaiter) {
+                    // A scope replacement keeps reconcile requests alive until its baseline completes.
+                    const previous = runningWaiter;
+                    runningWaiter = pendingWaiter;
+                    pendingWaiter = undefined;
+                    if (previous)
+                        void runningWaiter.promise.then(() => previous.resolve(), error => previous.reject(error));
+                }
+                try {
+                    await observe(g);
+                    check(g);
+                    g.waiter.resolve();
+                    runningWaiter?.resolve();
+                    runningWaiter = undefined;
+                }
+                catch (error) {
+                    g.waiter.reject(error);
+                    if (!g.abort.signal.aborted && current === g && !terminal)
+                        lose(error);
+                    try {
+                        await retireBackend();
+                    }
+                    catch (closeError) {
+                        retainRetirement(closeError);
+                    }
+                }
+                if (current !== g) {
+                    await retireBackend();
+                    snapshot = undefined;
+                    pending = true;
+                }
+            } while (pending && !terminal && failure === undefined);
+        }).catch(lose).finally(() => {
+            active = undefined;
+            if (!terminal && failure === undefined) {
+                if (pending || !current.waiter.settled)
+                    pump();
+                else
+                    scheduleInterval();
+            }
+        });
+    };
+    const request = () => {
+        if (terminal)
+            return Promise.reject(retired());
+        if (failure !== undefined)
+            return Promise.reject(failure);
+        clearTimeout(timer);
+        timer = undefined;
+        pending = true;
+        pendingWaiter ??= deferred();
+        const result = pendingWaiter.promise;
+        pump();
+        return result;
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        terminal = true;
+        current.abort.abort(retired());
+        current.waiter.reject(retired());
+        pendingWaiter?.reject(retired());
+        runningWaiter?.reject(retired());
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        options.signal?.removeEventListener("abort", abort);
+        // Start physical stop immediately, without waiting behind an in-flight scan.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        closing = Promise.resolve().then(async () => {
+            await active;
+            try {
+                await retireBackend();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            state = "closed";
+            if (retirementFailure)
+                throw combinedFailure();
+        });
+        void closing.catch(() => { });
+        return closing;
+    };
+    const abort = () => { void close(); };
+    const subscription = {
+        ready, health, close, [Symbol.asyncDispose]: close,
+        reconcile: request,
+        setScopes(scopes) {
+            if (terminal)
+                return Promise.reject(retired());
+            if (failure !== undefined)
+                return Promise.reject(failure);
+            const previous = current;
+            const next = makeGeneration(scopes);
+            // Scope accessors may synchronously close this owner during validation.
+            if (terminal || failure !== undefined || current !== previous) {
+                next.waiter.reject(failure ?? retired());
+                return next.waiter.promise;
+            }
+            current.abort.abort(retired());
+            current.waiter.reject(retired());
+            current = next;
+            resetRequested = true;
+            try {
+                backend?.close();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            clearTimers();
+            state = "starting";
+            // If idle, retire the old backend before the next scan can admit anything.
+            if (!active) {
+                active = retireBackend().catch(error => lose(error, "close")).finally(() => {
+                    active = undefined;
+                    snapshot = undefined;
+                    pump();
+                });
+            }
+            return next.waiter.promise;
+        },
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    else
+        pump();
+    return subscription;
+}

package/docs/advanced.md

@@ -77,6 +77,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |

package/docs/archive.md

@@ -179,6 +179,12 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
+ZIP preflight and bounded reads apply extraction's case-insensitive NFC collision
+policy to the complete archive, including entries that extraction would strip
+or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
+legacy names retain backend-selected decoding and undergo the same collision
+check before callbacks or selected bytes are returned.
+
 ZIP end-record admission searches the bounded comment window for signatures
 while retaining complete comment-length and ambiguity checks. Dense signature
 sequences fall back to the bounded byte scan.

package/docs/atomic.md

@@ -60,6 +60,8 @@ type ReplaceFileAtomicOptions = {
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  assertBeforeMutation?: () => void;
+  onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -108,6 +110,66 @@ descriptor is still closed, and a close failure remains reportable.
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
+### Atomic write authority and destination state
+
+Use `assertBeforeMutation` when a write depends on a lease or other revocable
+application authority. Both atomic variants capture the callback at entry and
+run it synchronously before directory creation or mode changes, compatibility
+lock acquisition, staging creation and writes, each rename attempt, and fallback
+removal, destination acquisition, truncation, and each content write. Asynchronous destination identity checks
+finish before the final authority check; no await separates that check from the
+write dispatch. A dispatched operation still owns its completion.
+
+`onDestinationState` captures facts that a caller may need if the operation later
+rejects:
+
+```ts
+type ReplaceFileAtomicDestinationState =
+  | Readonly<{ state: "removed"; path: string }>
+  | Readonly<{
+      state: "writing" | "published";
+      path: string;
+      dev: bigint;
+      ino: bigint;
+    }>;
+```
+
+- `removed` follows successful removal of an existing fallback destination.
+- `writing` records the fallback's retained descriptor after exclusive creation
+  or the first successful truncation of an existing `restore-original` target.
+  Opening an existing target leaves it untouched and emits no receipt. This state
+  does not claim that all requested bytes were written.
+- `published` follows successful rename and destination identity verification,
+  before parent synchronization or descriptor close can fail. Copy fallback
+  reports it after its content, mode, and requested file synchronization complete.
+  The explicit `verify-content-with-lock` policy first applies its existing
+  locked content verification to admit the replacement descriptor.
+
+Receipts are frozen and use the destination spelling captured by the operation.
+File identities come from retained descriptors, never from reopening a pathname
+after a failed copy. Failed or indeterminate admission can leave no identity
+receipt; a rename followed by replacement before verification also has no
+publication receipt. Do not infer ownership from a fresh post-failure stat. A later writer
+can replace the pathname, so compare the recorded identity with the current
+entry and recheck application authority before compensation. Receipts do not
+promise durable storage or authorize rollback.
+
+Both callbacks must complete synchronously; Promise, thenable, and synchronous
+or asynchronous generator results are rejected. Returned generators are never
+advanced; other ordinary return values are ignored. The first callback refusal
+is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
+from a callback never starts fallback or retry. Refusal during an in-place
+fallback also stops new restoration writes. Final mode, synchronization, close,
+and private-stage cleanup may still settle against owned identities after
+revocation. Callback refusal does not delete a published destination or a
+competing file at a staging name. An observer that throws must retain its receipt
+first if recovery needs it.
+
+`beforeRename` remains the hook for preparing backups. Effects performed inside
+that hook remain the caller's responsibility; the authority option guards the
+atomic writer's own effects. Omitting both new callbacks preserves existing
+write, fallback, restoration, result, and cleanup behavior.
+
 ### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
@@ -184,6 +246,22 @@ that same descriptor, and synchronizes the result. Any write, mode, or sync
 failure triggers a byte-and-mode restore and another sync through the same
 descriptor.
 
+With mutation callbacks enabled, an `EIO` from destination `stat`/`lstat` after
+successful truncation also attempts restoration through that retained descriptor.
+Each restore write still requires live application authority and fresh exact
+descriptor identity, regular-file, and configured hardlink checks. The failed
+pathname observation is not retried to authorize restoration; no pathname is
+opened, removed, or replaced. A successor at that name is left untouched.
+`details.cleanup: "restored"` means the retained original file's bytes and mode
+were restored and synchronized, not that the pathname still names it. The existing
+`writing` receipt identifies that file; no `published` receipt is emitted for a
+failed replacement. Restoration I/O failures report `"restore-failed"`.
+
+Callback refusals, detected identity/type/link changes, and other metadata errors
+remain terminal. Failed descriptor revalidation also stops restoration. These
+cases can leave the retained file empty or partial with only a `writing` receipt;
+before the first successful truncation, verification failure leaves it untouched.
+
 With `syncTempFile: false`, an exclusive-create copy fallback does not report
 success until its new destination writer closes successfully. This includes
 `"restore-original"` when the destination did not exist. A close rejection or throw is
@@ -214,6 +292,10 @@ through short reads and EOF, grow only as data arrives, and enforce the same
 `beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
 synchronous boot paths or test setup code. It returns the same
 `{ method: "rename" | "copy-fallback" }` receipt as the async variant.
+Promise, thenable, and synchronous or asynchronous generator results from the
+hook reject with `TypeError` before publication; rejected promises are consumed
+and generators are never advanced. Other synchronous return values are ignored.
+The replacement is not published; owned-temp cleanup follows the rules above.
 
 ## `replaceDirectoryAtomic`