@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/regular-file.js

@@ -0,0 +1,317 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertNoSymlinkParentsSync } from "./symlink-parents.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { isNonRegularWriteOpenError, isNonRegularWriteOpenErrorSync, resolveNonblockingWriteFlag, } from "./write-open-flags.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+export function resolveRegularFileAppendFlags(constants = fsSync.constants) {
+    const noFollow = constants.O_NOFOLLOW;
+    return (constants.O_CREAT |
+        constants.O_APPEND |
+        constants.O_WRONLY |
+        (typeof noFollow === "number" ? noFollow : 0) |
+        resolveNonblockingWriteFlag(constants));
+}
+function regularFileTooLargeError(filePath, maxBytes, cause) {
+    return new FsSafeError("too-large", `File exceeds ${maxBytes} bytes: ${filePath}`, { cause });
+}
+function translateBoundedReadOverflow(error, filePath, maxBytes) {
+    if (error instanceof FsSafeError && error.code === "too-large") {
+        throw regularFileTooLargeError(filePath, maxBytes, error);
+    }
+    throw error;
+}
+export async function statRegularFile(filePath) {
+    return statRegularFileSync(filePath);
+}
+export function statRegularFileSync(filePath) {
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+    let stat;
+    try {
+        stat = fsSync.lstatSync(filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return { missing: true };
+        }
+        throw err;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error("path must be a regular file");
+    }
+    return { missing: false, stat };
+}
+export async function readRegularFile(params) {
+    const { filePath, maxBytes, before } = prepareRegularRead(params);
+    let handle;
+    try {
+        handle = await fs.open(filePath, resolveReadOpenFlags());
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
+        }
+        throw err;
+    }
+    try {
+        const stat = inspectOpenedRegularRead(handle.fd, filePath, before, maxBytes);
+        // With a byte cap, avoid readFile(): a raced file growth would allocate
+        // the oversized content before the post-read check could reject it.
+        let buffer;
+        try {
+            buffer =
+                maxBytes === undefined
+                    ? await handle.readFile()
+                    : await readFileHandleBounded(handle, maxBytes);
+        }
+        catch (error) {
+            if (maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, filePath, maxBytes);
+            }
+            throw error;
+        }
+        return { buffer, stat };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function throwReadPreviewError(error, filePath) {
+    if (isNotFoundPathError(error)) {
+        throw Object.assign(new Error(`File not found: ${filePath}`), { code: "ENOENT" });
+    }
+    throw error;
+}
+function assertRegularReadStat(stat, filePath, preview = false) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(preview ? "path must be a regular file" : `File is not a regular file: ${filePath}`);
+    }
+}
+function prepareRegularRead(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+    assertNoUnsafeDeviceReadPath(filePath);
+    let before;
+    try {
+        before = inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularReadStat(stat, filePath, true);
+            return stat;
+        });
+    }
+    catch (error) {
+        throwReadPreviewError(error, filePath);
+    }
+    if (maxBytes !== undefined && before.size > maxBytes) {
+        throw regularFileTooLargeError(filePath, maxBytes);
+    }
+    return { filePath, maxBytes, before };
+}
+function inspectOpenedRegularRead(fd, filePath, preOpenStat, maxBytes) {
+    const stat = fsSync.fstatSync(fd);
+    const identity = inspectFileIdentitySync(() => {
+        const exact = fsSync.fstatSync(fd, { bigint: true });
+        assertRegularReadStat(exact, filePath);
+        return exact;
+    }, preOpenStat);
+    try {
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularReadStat(current, filePath);
+            return current;
+        }, identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
+        }
+        throw error;
+    }
+    if (maxBytes !== undefined && stat.size > maxBytes) {
+        throw regularFileTooLargeError(filePath, maxBytes);
+    }
+    return stat;
+}
+export function readRegularFileSync(params) {
+    const { filePath, maxBytes, before } = prepareRegularRead(params);
+    let fd;
+    try {
+        fd = fsSync.openSync(filePath, resolveReadOpenFlags());
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${filePath}`);
+        }
+        throw error;
+    }
+    try {
+        const stat = inspectOpenedRegularRead(fd, filePath, before, maxBytes);
+        // Keep capped reads incremental so raced growth cannot allocate unbounded content.
+        let buffer;
+        try {
+            buffer = maxBytes === undefined
+                ? fsSync.readFileSync(fd)
+                : readFileDescriptorBoundedSync(fd, maxBytes);
+        }
+        catch (error) {
+            if (maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, filePath, maxBytes);
+            }
+            throw error;
+        }
+        return { buffer, stat };
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}
+function assertRegularAppendStat(stat, filePath) {
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to append to non-file: ${filePath}`);
+    }
+    if (stat.nlink > 1n) {
+        throw new Error(`Refusing to append to hardlinked file: ${filePath}`);
+    }
+}
+function throwAppendIdentityError(error, filePath) {
+    if (isNotFoundPathError(error) ||
+        (error instanceof FsSafeError && error.code === "path-mismatch")) {
+        throw new Error(`Refusing to append after file changed: ${filePath}`, { cause: error });
+    }
+    throw error;
+}
+function captureAppendOptions(options) {
+    const filePath = options.filePath;
+    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+    return {
+        filePath, content: options.content, encoding: options.encoding ?? "utf8",
+        mode: options.mode ?? 0o600, maxFileBytes: options.maxFileBytes,
+        rejectSymlinkParents: options.rejectSymlinkParents,
+    };
+}
+function inspectAppendPath(filePath) {
+    const stat = fsSync.lstatSync(filePath, { bigint: true });
+    if (stat.isSymbolicLink())
+        throw new Error(`Refusing to append through symlink: ${filePath}`);
+    if (!stat.isFile())
+        throw new Error(`Refusing to append to non-file: ${filePath}`);
+    return stat;
+}
+function prepareRegularAppend(filePath, rejectSymlinkParents) {
+    if (rejectSymlinkParents === true) {
+        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
+        assertNoSymlinkParentsSync({
+            rootDir: path.parse(resolvedDir).root,
+            targetPath: resolvedDir,
+            allowMissing: false,
+            allowRootChildSymlink: true,
+            requireDirectories: true,
+            messagePrefix: "Refusing to append under",
+        });
+    }
+    try {
+        return inspectFileIdentitySync(() => inspectAppendPath(filePath));
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+    }
+}
+function inspectOpenedRegularAppend(fd, filePath, preOpenStat) {
+    try {
+        const identity = inspectFileIdentitySync(() => {
+            const stat = fsSync.fstatSync(fd, { bigint: true });
+            assertRegularAppendStat(stat, filePath);
+            return stat;
+        }, preOpenStat);
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(filePath, { bigint: true });
+            assertRegularAppendStat(current, filePath);
+            return current;
+        }, identity);
+        return identity;
+    }
+    catch (error) {
+        throwAppendIdentityError(error, filePath);
+    }
+}
+export async function appendRegularFile(options) {
+    const { filePath, content, encoding, mode, maxFileBytes, rejectSymlinkParents } = captureAppendOptions(options);
+    const preOpenStat = prepareRegularAppend(filePath, rejectSymlinkParents);
+    const contentBytes = Buffer.isBuffer(content) ? content.byteLength : Buffer.byteLength(content, encoding);
+    if (maxFileBytes !== undefined &&
+        Number(preOpenStat?.size ?? 0n) + contentBytes > maxFileBytes) {
+        return;
+    }
+    await getFsSafeTestHooks()?.beforeRegularFileAppendOpen?.(filePath);
+    const flags = resolveRegularFileAppendFlags();
+    let handle;
+    try {
+        handle = await fs.open(filePath, flags, mode);
+    }
+    catch (error) {
+        if (await isNonRegularWriteOpenError(error, filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${filePath}`);
+        }
+        throw error;
+    }
+    try {
+        const identity = inspectOpenedRegularAppend(handle.fd, filePath, preOpenStat);
+        if (maxFileBytes !== undefined &&
+            Number(identity.size) + contentBytes > maxFileBytes) {
+            return;
+        }
+        // Tighten before writing; restore explicit special bits only after content is complete.
+        await handle.chmod(mode);
+        await handle.appendFile(content, encoding);
+        if (mode & 0o7000)
+            await handle.chmod(mode);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function appendRegularFileSync(options) {
+    const { filePath, content, encoding, mode, maxFileBytes, rejectSymlinkParents } = captureAppendOptions(options);
+    const preOpenStat = prepareRegularAppend(filePath, rejectSymlinkParents);
+    const contentBuffer = typeof content === "string" ? Buffer.from(content, encoding) : Buffer.from(content);
+    if (maxFileBytes !== undefined &&
+        Number(preOpenStat?.size ?? 0n) + contentBuffer.byteLength > maxFileBytes) {
+        return;
+    }
+    getFsSafeTestHooks()?.beforeRegularFileAppendOpenSync?.(filePath);
+    const flags = resolveRegularFileAppendFlags();
+    let fd;
+    try {
+        fd = fsSync.openSync(filePath, flags, mode);
+    }
+    catch (error) {
+        if (isNonRegularWriteOpenErrorSync(error, filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${filePath}`);
+        }
+        throw error;
+    }
+    try {
+        const identity = inspectOpenedRegularAppend(fd, filePath, preOpenStat);
+        if (maxFileBytes !== undefined &&
+            Number(identity.size) + contentBuffer.byteLength > maxFileBytes) {
+            return;
+        }
+        fsSync.fchmodSync(fd, mode);
+        fsSync.appendFileSync(fd, contentBuffer);
+        if (mode & 0o7000)
+            fsSync.fchmodSync(fd, mode);
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-directory.d.ts

@@ -0,0 +1,6 @@
+export type ReplaceDirectoryAtomicOptions = {
+    stagedDir: string;
+    targetDir: string;
+    backupPrefix?: string;
+};
+export declare function replaceDirectoryAtomic(options: ReplaceDirectoryAtomicOptions): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/replace-directory.js

@@ -0,0 +1,287 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, } from "./native-rename-outcome.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { serializePathWrite } from "./write-queue.js";
+function distinctGuards(source, target) {
+    return source === target ? [source] : [source, target];
+}
+function assertGuardsCurrent(guards) {
+    for (const guard of guards)
+        assertSyncDirectoryGuard(guard);
+}
+function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function replacementFailure(error, message, details) {
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, { cause: error, details });
+    }
+    const failure = new Error(message, { cause: error });
+    copyOperationalCode(failure, error);
+    Object.defineProperty(failure, "details", { configurable: true, value: details });
+    return failure;
+}
+function replacementAggregate(error, recoveryError, message, details) {
+    const combined = new AggregateError([error, recoveryError], "directory replacement operation and recovery both failed");
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, { cause: combined, details });
+    }
+    const failure = new Error(message, { cause: combined });
+    copyOperationalCode(failure, error);
+    Object.defineProperty(failure, "details", { configurable: true, value: details });
+    return failure;
+}
+function isMissingDirectoryEntry(error) {
+    return error?.code === "ENOENT";
+}
+function observeOptionalDirectory(pathname) {
+    let initial;
+    try {
+        initial = fsSync.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (isMissingDirectoryEntry(error))
+            return undefined;
+        throw error;
+    }
+    return inspectDirectoryIdentitySync(pathname, undefined, initial);
+}
+function normalizeNativeRenameFailure(error) {
+    const code = error?.code;
+    if (code === NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH) {
+        return new FsSafeError("path-mismatch", "directory replacement source identity changed before native rename", { cause: error });
+    }
+    if (code === "EINVAL" || code === "ENOSYS" || code === "ENOTSUP" ||
+        code === "EOPNOTSUPP") {
+        return new FsSafeError("helper-unavailable", "native no-replace directory rename is unavailable on this filesystem", { cause: error });
+    }
+    return error;
+}
+function renameRetainedDirectory(params) {
+    const guards = distinctGuards(params.sourceParent, params.targetParent);
+    assertGuardsCurrent(guards);
+    const initial = fsSync.lstatSync(params.from, { bigint: true });
+    const identity = inspectDirectoryIdentitySync(params.from, params.expectedSource, initial);
+    try {
+        params.renameNoReplace(identity);
+    }
+    catch (error) {
+        if (classifyNativeRenameFailure(error) === "indeterminate") {
+            params.onIndeterminate();
+        }
+        throw normalizeNativeRenameFailure(error);
+    }
+    // Record the transition synchronously before any post-rename observation.
+    params.onRenamed?.(identity);
+    inspectDirectoryIdentitySync(params.to, identity);
+    assertGuardsCurrent(guards);
+    return identity;
+}
+export async function replaceDirectoryAtomic(options) {
+    const stagedDirInput = admitStandalonePublicationPath(options.stagedDir, "staged directory uses a Windows filesystem namespace alias");
+    const targetDirInput = admitStandalonePublicationPath(options.targetDir, "target directory uses a Windows filesystem namespace alias");
+    const stagedDir = path.resolve(stagedDirInput);
+    const targetDir = path.resolve(targetDirInput);
+    assertNoWindowsPathAlias(stagedDir, "filesystem", "staged directory uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetDir, "filesystem", "target directory uses a Windows filesystem namespace alias");
+    const backupPrefixInput = options.backupPrefix;
+    await serializePathWrite(targetDir, async () => {
+        await replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPrefixInput);
+    });
+}
+async function replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPrefixInput) {
+    const parentDir = path.dirname(targetDir);
+    const backupPrefix = assertSafePathPrefix(backupPrefixInput ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
+    const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
+    const backup = {
+        identity: undefined,
+        transition: "not-renamed",
+    };
+    const publication = {
+        status: "not-published",
+    };
+    let operationFailed = false;
+    let operationError;
+    let operationDetails = {
+        phase: "backup",
+        publication: publication.status,
+        recovery: "none",
+    };
+    const retainedBinding = RetainedDirectoryReplacement.requireBinding();
+    await fs.mkdir(recursiveMkdirPath(parentDir), { recursive: true });
+    const targetParent = await createAsyncDirectoryGuard(parentDir, { bigint: true });
+    const stagedParentDir = path.dirname(stagedDir);
+    const stagedParent = stagedParentDir === parentDir
+        ? targetParent
+        : await createAsyncDirectoryGuard(stagedParentDir, { bigint: true });
+    const stagedIdentity = inspectDirectoryIdentitySync(stagedDir);
+    const targetIdentity = observeOptionalDirectory(targetDir);
+    const retained = RetainedDirectoryReplacement.retain({
+        targetParent: {
+            path: parentDir,
+            realPath: targetParent.realPath,
+            identity: targetParent.stat,
+        },
+        stagedParent: {
+            path: stagedParentDir,
+            realPath: stagedParent.realPath,
+            identity: stagedParent.stat,
+        },
+        ...(targetIdentity ? {
+            originalTarget: { path: targetDir, identity: targetIdentity },
+        } : {}),
+    }, retainedBinding);
+    const targetBasename = path.basename(targetDir);
+    const stagedBasename = path.basename(stagedDir);
+    const backupBasename = path.basename(backupDir);
+    const details = (phase, recovery) => {
+        operationDetails = {
+            phase,
+            publication: publication.status,
+            recovery,
+            ...(backup.transition === "not-renamed" ? {} : { backupPath: backupDir }),
+        };
+        return operationDetails;
+    };
+    const rollback = (error, failedPhase, identity) => {
+        const rollbackState = {
+            transition: "not-renamed",
+        };
+        try {
+            renameRetainedDirectory({
+                from: backupDir,
+                to: targetDir,
+                sourceParent: targetParent,
+                targetParent,
+                expectedSource: identity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("target", backupBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    rollbackState.transition = "indeterminate";
+                    backup.transition = "indeterminate";
+                },
+                onRenamed() {
+                    rollbackState.transition = "renamed";
+                    backup.transition = "not-renamed";
+                },
+            });
+        }
+        catch (rollbackError) {
+            const recovery = rollbackState.transition === "renamed"
+                ? "restored-unverified"
+                : rollbackState.transition === "indeterminate"
+                    ? "indeterminate"
+                    : "backup-path-preserved";
+            throw replacementAggregate(error, rollbackError, `directory ${failedPhase} and rollback failed`, details("rollback", recovery));
+        }
+        throw replacementFailure(error, `directory ${failedPhase} failed after restoring the original target`, details(failedPhase, "restored"));
+    };
+    try {
+        if (targetIdentity) {
+            try {
+                backup.identity = renameRetainedDirectory({
+                    from: targetDir,
+                    to: backupDir,
+                    sourceParent: targetParent,
+                    targetParent,
+                    expectedSource: targetIdentity,
+                    renameNoReplace: expectedSource => {
+                        retained.renameNoReplace("target", targetBasename, backupBasename, expectedSource);
+                    },
+                    onIndeterminate() {
+                        backup.transition = "indeterminate";
+                    },
+                    onRenamed(identity) {
+                        backup.identity = identity;
+                        backup.transition = "renamed";
+                    },
+                });
+            }
+            catch (err) {
+                if (backup.transition === "renamed" && backup.identity) {
+                    rollback(err, "backup", backup.identity);
+                }
+                const recovery = backup.transition === "indeterminate" ? "indeterminate" : "none";
+                throw replacementFailure(err, "directory backup failed before publication", details("backup", recovery));
+            }
+        }
+        try {
+            renameRetainedDirectory({
+                from: stagedDir,
+                to: targetDir,
+                sourceParent: stagedParent,
+                targetParent,
+                expectedSource: stagedIdentity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("staged", stagedBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    publication.status = "indeterminate";
+                },
+                onRenamed() {
+                    publication.status = "published";
+                },
+            });
+        }
+        catch (err) {
+            if (publication.status === "published") {
+                throw replacementFailure(err, "published directory failed retained identity verification", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (publication.status === "indeterminate") {
+                throw replacementFailure(err, "directory publication outcome is indeterminate", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (backup.transition === "renamed" && backup.identity) {
+                rollback(err, "publish", backup.identity);
+            }
+            throw replacementFailure(err, "directory publication failed before commit", details("publish", "none"));
+        }
+        details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none");
+        if (backup.transition === "renamed" && backup.identity) {
+            let cleanupAttempted = false;
+            try {
+                assertSyncDirectoryGuard(targetParent);
+                inspectDirectoryIdentitySync(backupDir, backup.identity);
+                cleanupAttempted = true;
+                const outcome = await retained.removeOriginal(backupBasename);
+                if (outcome !== "removed") {
+                    throw new FsSafeError("path-mismatch", "retained backup changed before bounded cleanup");
+                }
+                backup.transition = "not-renamed";
+                details("cleanup", "none");
+            }
+            catch (error) {
+                throw replacementFailure(error, "published directory but retained backup cleanup failed", {
+                    ...details("cleanup", cleanupAttempted ? "cleanup-incomplete" : "backup-path-preserved"),
+                });
+            }
+        }
+    }
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+        throw error;
+    }
+    finally {
+        try {
+            retained.close();
+        }
+        catch (closeError) {
+            if (operationFailed) {
+                throw replacementAggregate(operationError, closeError, "directory replacement and retained descriptor close failed", operationDetails);
+            }
+            throw replacementFailure(closeError, "directory replacement retained descriptor close failed", operationDetails);
+        }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-copy-fallback.d.ts

@@ -0,0 +1,38 @@
+import syncFs, { type BigIntStats } from "node:fs";
+export type ReplaceFileDestinationHardlinkPolicy = "reject";
+export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
+export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
+export type ReplaceFileAtomicRestoreFailureDetails = {
+    cleanup: ReplaceFileAtomicRestoreCleanup;
+};
+type AsyncFallbackFs = {
+    lstat: typeof import("node:fs/promises").lstat;
+    open: typeof import("node:fs/promises").open;
+    rm: typeof import("node:fs/promises").rm;
+    unlink: typeof import("node:fs/promises").unlink;
+};
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
+export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
+export declare function copyFallbackReplace(params: {
+    fsModule: AsyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
+    sync: boolean;
+}): Promise<void>;
+export declare function copyFallbackReplaceSync(params: {
+    fsModule: SyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
+    fchmodSync?: (fd: number, mode: number) => void;
+    sync: boolean;
+}): void;
+export {};