toolcraft 0.0.749 → 0.0.751

package/node_modules/@poe-code/safe-fs/dist/fs/scoped.js

@@ -0,0 +1,663 @@
+import { FsError, toFsError } from "../contracts/errors.js";
+import { validatePath } from "../contracts/virtual-path.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+import { registerEntryView } from "./mount/comparison.js";
+import { getScopedTransportBudget, runScopedTransportBudget, withScopedTransportBudget } from "#safe-fs-platform";
+import { hasRegisteredS3FileSystem, scopeTransportOptions } from "../platform/transport-budget.js";
+import { openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "./capabilities.js";
+import { createStagingCleanup, snapshotStagingCreation } from "./staging-cleanup.js";
+import { inspectStagingBindings, runStagingGuard, snapshotDirectoryAncestry, snapshotStagingResolution } from "./staging-ancestry.js";
+const originals = new WeakMap();
+const retainedCleanupSymbol = Symbol.for("safe-fs.retainedCleanup");
+const retargeters = new WeakMap();
+export function retargetScopedFileSystem(scoped, charge, signal, cleanupCharge = charge, maxPathComponents) {
+    const fn = retargeters.get(scoped);
+    if (!fn)
+        return false;
+    fn(charge, signal, cleanupCharge, maxPathComponents);
+    return true;
+}
+const operations = new Set([
+    "prepareDirectoryAncestry", "prepareStagingResolution", "publishStagedFileSet",
+    "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
+    "confineExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
+    "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
+    "writeFile", "writeStream",
+]);
+export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge, options = {}) {
+    const original = originals.get(filesystem)?.filesystem ?? filesystem;
+    const creationMask = options.creationMask ?? originals.get(filesystem)?.creationMask;
+    let maxPathComponents = options.maxPathComponents ?? originals.get(filesystem)?.maxPathComponents;
+    if (creationMask !== undefined && (!Number.isInteger(creationMask) || creationMask < 0 || creationMask > 0o777))
+        throw new RangeError("creationMask must be a permission mask between 0 and 0777");
+    const creationOptions = (settings, directory = false) => {
+        // Explicit directory modes (mkdir -m) are independent of the shell mask.
+        // Modes remain advisory on adapters that do not enforce permissions.
+        if (creationMask === undefined || directory && settings.mode !== undefined)
+            return settings;
+        const mode = settings.mode ?? (directory ? 0o777 : 0o666);
+        if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777)
+            throw new FsError("EINVAL");
+        return { ...settings, mode: mode & ~creationMask };
+    };
+    const methods = new Map();
+    const assertOpen = (options) => {
+        signal.throwIfAborted();
+        options?.signal?.throwIfAborted();
+    };
+    const admit = (options) => {
+        assertOpen(options);
+        charge();
+    };
+    const wrapHandle = (handle) => {
+        let closed = false;
+        const close = handle.close.bind(handle);
+        return {
+            async stat(options) { admit(options); return handle.stat(options); },
+            async read(position, maxBytes, options) { admit(options); return handle.read(position, maxBytes, options); },
+            get seekEnd() {
+                const seek = handle.seekEnd;
+                if (typeof seek !== "function")
+                    return undefined;
+                return async (options = {}) => {
+                    assertOpen(options);
+                    if (closed)
+                        throw new FsError("EBADF");
+                    admit(options);
+                    assertOpen(options);
+                    if (closed)
+                        throw new FsError("EBADF");
+                    try {
+                        const result = await Reflect.apply(seek, handle, [resizeOptions(options)]);
+                        assertOpen(options);
+                        return result;
+                    }
+                    catch (error) {
+                        assertOpen(options);
+                        throw error;
+                    }
+                };
+            },
+            close() { closed = true; return close(); },
+        };
+    };
+    let cachedCallerSignal;
+    let cachedCombinedSignal;
+    const combineSignal = (callerSignal) => {
+        if (!callerSignal || callerSignal === signal)
+            return signal;
+        if (callerSignal === cachedCallerSignal && cachedCombinedSignal)
+            return cachedCombinedSignal;
+        cachedCallerSignal = callerSignal;
+        cachedCombinedSignal = AbortSignal.any([signal, callerSignal]);
+        return cachedCombinedSignal;
+    };
+    const resizeOptions = (options) => {
+        const scopedOptions = {
+            ...options, signal: combineSignal(options.signal),
+        };
+        scopedOptions.signal.throwIfAborted();
+        return scopedOptions;
+    };
+    const wrapResizeHandle = (handle) => {
+        let closing;
+        const admitOperation = (options) => {
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            admit(options);
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            return resizeOptions(options);
+        };
+        return {
+            async stat(options = {}) {
+                try {
+                    const result = await handle.stat(admitOperation(options));
+                    assertOpen(options);
+                    return result;
+                }
+                catch (error) {
+                    assertOpen(options);
+                    throw error;
+                }
+            },
+            async truncate(length, options = {}) {
+                try {
+                    await handle.truncate(length, admitOperation(options));
+                    assertOpen(options);
+                }
+                catch (error) {
+                    assertOpen(options);
+                    throw error;
+                }
+            },
+            get seekEnd() {
+                const seek = handle.seekEnd;
+                if (typeof seek !== "function")
+                    return undefined;
+                return async (options = {}) => {
+                    try {
+                        const result = await Reflect.apply(seek, handle, [admitOperation(options)]);
+                        assertOpen(options);
+                        return result;
+                    }
+                    catch (error) {
+                        assertOpen(options);
+                        throw error;
+                    }
+                };
+            },
+            close: () => closing ??= Promise.resolve().then(() => handle.close()),
+        };
+    };
+    const wrapDescriptor = (descriptor) => {
+        let closing;
+        const invoke = async (options, action, preserveReceipt = false) => {
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            admit(options);
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            try {
+                const result = await action(resizeOptions(options));
+                if (!preserveReceipt)
+                    assertOpen(options);
+                return result;
+            }
+            catch (error) {
+                assertOpen(options);
+                throw error;
+            }
+        };
+        const getPosition = descriptor.getPosition;
+        const probeRead = descriptor.probeRead;
+        return {
+            capabilities: Object.freeze({ ...descriptor.capabilities }),
+            ...(getPosition === undefined ? {} : { getPosition: (options = {}) => invoke(options, scoped => getPosition.call(descriptor, scoped)) }),
+            ...(probeRead === undefined ? {} : { probeRead: (options = {}) => invoke(options, scoped => probeRead.call(descriptor, scoped)) }),
+            stat: (options = {}) => invoke(options, scoped => descriptor.stat(scoped)),
+            read: (buffer, position, options = {}) => invoke(options, scoped => descriptor.read(buffer, position, scoped)),
+            write: (buffer, position, forwarded = {}) => invoke(forwarded, scoped => descriptor.write(buffer, position, scoped), options.preserveDescriptorWriteReceipt === true),
+            truncate: (length, options = {}) => invoke(options, scoped => descriptor.truncate(length, scoped)),
+            sync: (dataOnly, options = {}) => invoke(options, scoped => descriptor.sync(dataOnly, scoped)),
+            close: (options = {}) => closing ??= Promise.resolve().then(() => descriptor.close(options)),
+        };
+    };
+    const wrapStream = (source, options) => {
+        const budgetFrames = getScopedTransportBudget();
+        return {
+            [Symbol.asyncIterator]() {
+                assertOpen(options);
+                const iterator = source[Symbol.asyncIterator]();
+                let closing;
+                const close = (value) => closing ??= Promise.resolve().then(() => iterator.return ? iterator.return(value) : { done: true, value: undefined });
+                const advance = async (operation) => {
+                    try {
+                        assertOpen(options);
+                        if (closing) {
+                            await closing;
+                            return { done: true, value: undefined };
+                        }
+                        const result = await withScopedTransportBudget(budgetFrames, operation);
+                        assertOpen(options);
+                        if (closing) {
+                            await closing;
+                            return { done: true, value: undefined };
+                        }
+                        return result;
+                    }
+                    catch (error) {
+                        await finishCleanup(close, true);
+                        throw error;
+                    }
+                };
+                return {
+                    next: () => advance(() => iterator.next()),
+                    return: close,
+                    ...(iterator.throw ? { throw: (error) => advance(() => iterator.throw(error)) } : {}),
+                };
+            },
+        };
+    };
+    let cachedRawCaps;
+    let cachedCreateStaged;
+    let cachedOpenResize;
+    let cachedComputedCaps;
+    const view = new Proxy(Object.create(original), {
+        set(_target, property, value) {
+            cachedComputedCaps = undefined;
+            return Reflect.set(original, property, value, original);
+        },
+        get(_target, property) {
+            if (property === retainedCleanupSymbol)
+                return cleanupBinding;
+            if (property === "capabilities") {
+                const rawCaps = original.capabilities;
+                if (cachedComputedCaps !== undefined &&
+                    cachedRawCaps === rawCaps &&
+                    cachedCreateStaged === original.createStagedFile &&
+                    cachedOpenResize === original.openResizeFile) {
+                    return cachedComputedCaps;
+                }
+                const computed = ownedMutationCapabilities(original, retainedResizeCapabilities(original, rawCaps));
+                cachedRawCaps = rawCaps;
+                cachedCreateStaged = original.createStagedFile;
+                cachedOpenResize = original.openResizeFile;
+                cachedComputedCaps = computed;
+                return computed;
+            }
+            const method = Reflect.get(original, property, original);
+            if (typeof method !== "function")
+                return method;
+            const cached = methods.get(property);
+            if (cached?.original === method)
+                return cached.scoped;
+            const credit = operations.has(property) ? 1 : 0;
+            const executeDispatch = (args) => {
+                if (property === "removeEntryConditional")
+                    args[1] = resizeOptions({ ...args[1] });
+                let stagingSignal;
+                if (property === "createStagedFile" || property === "publishStagedFile" || property === "publishStagedFileSet") {
+                    signal.throwIfAborted();
+                    if (property === "createStagedFile")
+                        args[3] = snapshotStagingCreation(args[3], args[0]);
+                    const callerSignal = args[property === "createStagedFile" ? 3 : 2]?.signal;
+                    stagingSignal = combineSignal(callerSignal);
+                    stagingSignal.throwIfAborted();
+                }
+                if (operations.has(property)) {
+                    const options = args.at(-1);
+                    admit(stagingSignal ? { signal: stagingSignal }
+                        : options && typeof options === "object" && "signal" in options ? options : undefined);
+                    if (property !== "symlink" && typeof args[0] === "string")
+                        validatePath(args[0], maxPathComponents);
+                    if (["copyFile", "rename", "link", "compareEntry"].includes(String(property)) && typeof args[1] === "string")
+                        validatePath(args[1], maxPathComponents);
+                    if (property === "symlink" && typeof args[1] === "string")
+                        validatePath(args[1], maxPathComponents);
+                }
+                if (property === "publishStagedFileSet") {
+                    if (original.capabilities.readOnly === true)
+                        throw new FsError("EROFS", { path: args[1] });
+                    const supplied = args[2];
+                    const callerGuard = supplied.commitGuard;
+                    const entry = (value) => ({ path: value.path, stat: { ...value.stat } });
+                    const input = args[0];
+                    const staging = { ...input, parent: entry(input.parent), directory: entry(input.directory), file: entry(input.file) };
+                    const controls = {
+                        ...supplied,
+                        signal: stagingSignal,
+                        parent: { ...supplied.parent },
+                        destination: supplied.destination === null ? null : { ...supplied.destination },
+                        companions: supplied.companions.map(value => ({ ...value, expected: value.expected === null ? null : { ...value.expected } })),
+                        ...(supplied.ancestors === undefined ? {} : { ancestors: snapshotDirectoryAncestry(supplied.ancestors) }),
+                        commitGuard: () => {
+                            assertOpen({ signal: stagingSignal });
+                            if (callerGuard !== undefined)
+                                runStagingGuard(callerGuard);
+                            assertOpen({ signal: stagingSignal });
+                            return true;
+                        },
+                    };
+                    for (const path of [staging.parent.path, staging.directory.path, staging.file.path, args[1],
+                        ...controls.companions.map(value => value.path), ...(controls.ancestors ?? []).map(value => value.path)]) {
+                        validatePath(path, maxPathComponents);
+                    }
+                    assertOpen(controls);
+                    return Reflect.apply(method, original, [staging, args[1], controls]);
+                }
+                if (["writeFile", "appendFile", "writeStream", "mkdir"].includes(String(property))) {
+                    const index = property === "mkdir" ? 1 : 2;
+                    args[index] = creationOptions((args[index] ?? {}), property === "mkdir");
+                }
+                if (["publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory"].includes(String(property)))
+                    return (async () => {
+                        const path = typeof args[0] === "string" ? args[0] : args[0].directory.path;
+                        const optionIndex = property === "createStagedFile" ? 3 : property === "publishFileConditional" || property === "publishStagedFile" || property === "writeFileConditional" ? 2 : 1;
+                        const supplied = args[optionIndex];
+                        const removalReceipt = property === "removeEntryConditional" && supplied !== undefined && "returnRemainingStat" in supplied && supplied.returnRemainingStat === true;
+                        const options = stagingSignal ? { ...supplied, signal: stagingSignal } : supplied;
+                        if (property === "createStagedFile" || property === "removeEntryConditional")
+                            args[optionIndex] = options;
+                        const assertReady = () => {
+                            if (property === "createStagedFile" || property === "publishStagedFile")
+                                options?.signal?.throwIfAborted();
+                            assertOpen(options);
+                        };
+                        const callerGuard = property === "publishStagedFile" ? supplied?.commitGuard : undefined;
+                        try {
+                            const create = property === "createStagedFile" || (property === "publishFileConditional" || property === "writeFileConditional" || property === "prepareDirectory") && options !== undefined && "expected" in options && options.expected === null;
+                            await requireOwnedMutation(original, path, property === "publishFileConditional" ? "atomicFilePublication" : property === "removeEntryConditional" ? "atomicEntryRemoval" : property === "removeTreeConditional" ? "atomicTreeRemoval" : property === "prepareDirectory" ? "atomicDirectoryMetadata" : property === "writeFileConditional" || property === "removeFileConditional" ? "atomicFileMutation" : "atomicFileStaging", options ?? {}, create);
+                            if (removalReceipt)
+                                await requireOwnedMutation(original, path, "atomicEntryRemovalReceipt", options);
+                            if (property === "createStagedFile" && options && "retainCleanup" in options && options.retainCleanup === true) {
+                                await requireOwnedMutation(original, path, "retainedStagingCleanup", options, true);
+                            }
+                            if (property === "publishStagedFile") {
+                                const publishOptions = (options ?? {});
+                                await requireOwnedMutation(original, args[1], "atomicFileStaging", publishOptions, publishOptions.destination === null);
+                                const query = options.destination === null ? { ...options, create: true } : options;
+                                const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(args[1], query) ?? original.capabilities);
+                                assertReady();
+                                if (callerGuard !== undefined && declared.guardedStagingPublication !== true)
+                                    throw new FsError("ENOTSUP", { path: args[1], syscall: "guardedStagingPublication" });
+                                // Guarded publication preserves the caller signal and observes scope
+                                // cancellation at commit. Unguarded backends need a composed signal.
+                                if (declared.guardedStagingPublication === true)
+                                    args[optionIndex] = {
+                                        ...supplied,
+                                        commitGuard: () => {
+                                            assertReady();
+                                            if (callerGuard !== undefined)
+                                                runStagingGuard(callerGuard);
+                                            assertReady();
+                                            return true;
+                                        },
+                                    };
+                                else
+                                    args[optionIndex] = options;
+                            }
+                            if (property === "publishStagedFile" && options && "ancestors" in options && options.ancestors !== undefined)
+                                await requireOwnedMutation(original, args[1], "atomicStagingAncestry", options, options.destination === null);
+                            assertReady();
+                            if (property === "publishFileConditional") {
+                                args[1] = wrapStream(args[1], options);
+                                args[2] = resizeOptions(options ?? {});
+                            }
+                        }
+                        catch (error) {
+                            assertReady();
+                            if (property === "publishStagedFile" && supplied && "ancestors" in supplied && supplied.ancestors !== undefined
+                                && ["ENOTSUP", "ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code)) {
+                                await inspectStagingBindings(path => original.lstat(path, options), args[1], options);
+                            }
+                            throw error;
+                        }
+                        if (property === "removeEntryConditional") {
+                            const receipt = await Reflect.apply(method, original, args);
+                            return removalReceipt && receipt !== undefined ? Object.freeze({ ...receipt }) : undefined;
+                        }
+                        if (property !== "createStagedFile")
+                            return Reflect.apply(method, original, args);
+                        const staging = await Reflect.apply(method, original, args);
+                        if (!staging.cleanup)
+                            return staging;
+                        const backendCleanup = staging.cleanup;
+                        try {
+                            const cleanup = createStagingCleanup(staging.directory.path, controls => {
+                                controls.signal?.throwIfAborted();
+                                cleanupCharge();
+                                controls.signal?.throwIfAborted();
+                                return backendCleanup.remove(controls);
+                            }, () => backendCleanup.close());
+                            const backendWriter = staging.writer;
+                            const writer = backendWriter && Object.freeze({
+                                write: async (bytes, settings = {}) => {
+                                    const controls = resizeOptions(settings);
+                                    admit(controls);
+                                    await backendWriter.write(bytes, controls);
+                                },
+                                finish: async (settings = {}) => {
+                                    const controls = resizeOptions(settings);
+                                    admit(controls);
+                                    return backendWriter.finish(controls);
+                                },
+                            });
+                            return Object.freeze({ ...staging, cleanup, ...(writer ? { writer } : {}) });
+                        }
+                        catch (error) {
+                            await finishCleanup(() => backendCleanup.close(), true);
+                            throw error;
+                        }
+                    })();
+                if (property === "compareEntry") {
+                    const peer = args[1];
+                    args[1] = originals.get(peer)?.filesystem ?? peer;
+                }
+                if (property === "rename" && args[2]?.noReplace)
+                    return (async () => {
+                        const options = args[2];
+                        const capabilities = await original.capabilitiesFor?.(args[1], options) ?? original.capabilities;
+                        assertOpen(options);
+                        if (capabilities.atomicRenameNoReplace !== true)
+                            throw new FsError("ENOTSUP", {
+                                syscall: "rename", path: args[0], dest: args[1],
+                            });
+                        return Reflect.apply(method, original, args);
+                    })();
+                const result = Reflect.apply(method, original, args);
+                return property === "readStream" ? wrapStream(result, args[1]) : result;
+            };
+            const dispatch = (...args) => {
+                if (!hasRegisteredS3FileSystem)
+                    return executeDispatch(args);
+                if (operations.has(property)) {
+                    const optionIndex = ["compareEntry", "createStagedFile", "utimes"].includes(String(property)) ? 3
+                        : ["writeFile", "appendFile", "writeStream", "rename", "copyFile", "link", "symlink", "access", "chmod", "truncate", "resizeFile", "publishFileConditional", "writeFileConditional", "publishStagedFile"].includes(String(property)) ? 2 : 1;
+                    args[optionIndex] = scopeTransportOptions((args[optionIndex] ?? {}), admit, credit);
+                }
+                return runScopedTransportBudget(admit, () => executeDispatch(args), credit);
+            };
+            const scoped = property === "prepareStagingResolution"
+                ? async (path, options = {}) => {
+                    const controls = resizeOptions({ ...options });
+                    controls.signal?.throwIfAborted();
+                    admit(controls);
+                    try {
+                        const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? original.capabilities);
+                        controls.signal?.throwIfAborted();
+                        if (declared.synchronousStagingResolution !== true)
+                            throw new FsError("ENOTSUP", { path });
+                        const resolution = snapshotStagingResolution(await Reflect.apply(method, original, [path, controls]));
+                        controls.signal?.throwIfAborted();
+                        return snapshotStagingResolution({ ...resolution, validate: () => {
+                                controls.signal?.throwIfAborted();
+                                admit(controls);
+                                controls.signal?.throwIfAborted();
+                                runStagingGuard(resolution.validate);
+                                return true;
+                            } });
+                    }
+                    catch (error) {
+                        controls.signal?.throwIfAborted();
+                        throw error;
+                    }
+                }
+                : property === "prepareDirectoryAncestry"
+                    ? async (...args) => {
+                        const options = (args[1] ?? {});
+                        const controls = resizeOptions(options);
+                        admit(controls);
+                        controls.signal?.throwIfAborted();
+                        const entries = snapshotDirectoryAncestry(args[0]);
+                        try {
+                            for (const entry of entries) {
+                                const declared = await original.capabilitiesFor?.(entry.path, { ...controls, stagingAncestry: true }) ?? original.capabilities;
+                                controls.signal?.throwIfAborted();
+                                if (declared.synchronousDirectoryValidation !== true)
+                                    throw new FsError("ENOTSUP", { path: entry.path });
+                            }
+                            const guard = await Reflect.apply(method, original, [entries, controls]);
+                            controls.signal?.throwIfAborted();
+                            if (typeof guard !== "function")
+                                throw new FsError("ENOTSUP", { syscall: "prepareDirectoryAncestry" });
+                            return () => {
+                                controls.signal?.throwIfAborted();
+                                admit(controls);
+                                controls.signal?.throwIfAborted();
+                                runStagingGuard(guard);
+                                return true;
+                            };
+                        }
+                        catch (error) {
+                            controls.signal?.throwIfAborted();
+                            throw error;
+                        }
+                    }
+                    : property === "confineExtraction"
+                        ? async (...args) => scopeFileSystem(await dispatch(...args), charge, signal, cleanupCharge, options)
+                        : property === "open"
+                            ? async (path, options) => {
+                                admit(options);
+                                const selected = resizeOptions(creationOptions(options));
+                                let descriptor;
+                                try {
+                                    descriptor = await Reflect.apply(method, original, [path, selected]);
+                                    assertOpen(options);
+                                    return wrapDescriptor(descriptor);
+                                }
+                                catch (error) {
+                                    if (descriptor)
+                                        await finishCleanup(() => descriptor.close(), true);
+                                    assertOpen(options);
+                                    throw error;
+                                }
+                            }
+                            : property === "openResizeFile"
+                                ? async (path, options = {}) => {
+                                    admit(options);
+                                    assertOpen(options);
+                                    return wrapResizeHandle(await openRetainedResizeFile(original, path, resizeOptions(creationOptions(options))));
+                                }
+                                : property === "capabilitiesFor"
+                                    ? async (...args) => ownedMutationCapabilities(original, retainedResizeCapabilities(original, await dispatch(...args)))
+                                    : property === "openReadFile"
+                                        ? async (...args) => wrapHandle(await dispatch(...args))
+                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream"
+                                            ? (...args) => {
+                                                try {
+                                                    const res = dispatch(...args);
+                                                    return res instanceof Promise ? res : Promise.resolve(res);
+                                                }
+                                                catch (error) {
+                                                    return Promise.reject(error);
+                                                }
+                                            }
+                                            : dispatch;
+            methods.set(property, { original: method, scoped });
+            return scoped;
+        },
+    });
+    const cleanupBinding = Object.freeze({ filesystem: view, retain: retainFileSystemCleanup });
+    const originalRecord = { filesystem: original, signal, cleanupCharge, creationMask, maxPathComponents };
+    originals.set(view, originalRecord);
+    retargeters.set(view, (nextCharge, nextSignal, nextCleanupCharge, nextMaxPathComponents) => {
+        charge = nextCharge;
+        if (signal !== nextSignal) {
+            cachedCallerSignal = undefined;
+            cachedCombinedSignal = undefined;
+        }
+        signal = nextSignal;
+        cleanupCharge = nextCleanupCharge;
+        maxPathComponents = nextMaxPathComponents ?? originals.get(filesystem)?.maxPathComponents;
+        originalRecord.signal = nextSignal;
+        originalRecord.cleanupCharge = nextCleanupCharge;
+        originalRecord.maxPathComponents = maxPathComponents;
+    });
+    registerEntryView(view, async (path, options) => {
+        assertOpen(options);
+        return { filesystem: original, path };
+    });
+    return view;
+}
+export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
+    const maximum = options?.maxOperations ?? Infinity;
+    if (maximum !== Infinity && (!Number.isSafeInteger(maximum) || maximum < 0))
+        throw new RangeError("cleanup maxOperations must be a nonnegative safe integer or Infinity");
+    if (typeof cleanupCallback !== "function")
+        throw new TypeError("cleanup callback must be a function");
+    const scope = originals.get(filesystem);
+    if (!scope) {
+        // Bundled commands can hold another module copy. Delegate only for this
+        // exact view, never through a wrapper that happens to forward its symbols.
+        const binding = Reflect.get(filesystem, retainedCleanupSymbol);
+        if (binding?.filesystem === filesystem && typeof binding.retain === "function" && binding.retain !== retainFileSystemCleanup)
+            return binding.retain(filesystem, cleanupCallback, options);
+    }
+    scope?.signal.throwIfAborted();
+    const backing = scope?.filesystem ?? filesystem;
+    const pending = new Set();
+    let operations = 0;
+    let active = false;
+    let closing;
+    const invoke = (method, input, settings) => {
+        const path = typeof input === "string" ? input : input.directory.path;
+        if (!active) {
+            const rejected = Promise.reject(new FsError("EBADF", { syscall: method, path, message: "cleanup callback is not active" }));
+            void rejected.catch(() => { });
+            return rejected;
+        }
+        let result;
+        try {
+            settings?.signal?.throwIfAborted();
+            if (operations >= maximum)
+                throw new FsError("EFBIG", { syscall: method, path, message: "cleanup operation limit exceeded" });
+            operations++;
+            scope?.cleanupCharge();
+            settings?.signal?.throwIfAborted();
+            const operation = backing[method];
+            if (typeof operation !== "function")
+                throw new FsError("ENOTSUP", { syscall: method, path });
+            const parameters = method === "rm" ? { ...settings, recursive: false, force: false } : settings;
+            result = method === "removeStagedFile" || method === "removeFileConditional"
+                ? requireOwnedMutation(backing, path, method === "removeFileConditional" ? "atomicFileMutation" : "atomicFileStaging", settings ?? {}).then(() => Reflect.apply(operation, backing, [input, parameters]))
+                : Promise.resolve(Reflect.apply(operation, backing, [input, parameters]));
+        }
+        catch (error) {
+            result = Promise.reject(error);
+            void result.catch(() => { });
+            return result;
+        }
+        const completion = result.then(() => { pending.delete(completion); return { status: "fulfilled", value: undefined }; }, error => { pending.delete(completion); return { status: "rejected", reason: error }; });
+        pending.add(completion);
+        return result;
+    };
+    const view = Object.freeze(Object.assign(Object.create(null), {
+        ...(typeof backing.removeFileConditional === "function" ? { removeFileConditional: invoke.bind(undefined, "removeFileConditional") } : {}),
+        ...(typeof backing.removeStagedFile === "function" ? { removeStagedFile: invoke.bind(undefined, "removeStagedFile") } : {}),
+        lstat: invoke.bind(undefined, "lstat"),
+        realpath: invoke.bind(undefined, "realpath"),
+        rm: invoke.bind(undefined, "rm"),
+        ...(typeof backing.rmdir === "function" ? { rmdir: invoke.bind(undefined, "rmdir") } : {}),
+    }));
+    scope?.signal.throwIfAborted();
+    return () => {
+        if (!closing) {
+            closing = Promise.resolve().then(async () => {
+                active = true;
+                let callbackFailed = false;
+                let callbackFailure;
+                try {
+                    const result = cleanupCallback(view);
+                    if (result !== undefined)
+                        await result;
+                }
+                catch (error) {
+                    callbackFailed = true;
+                    callbackFailure = error;
+                }
+                finally {
+                    active = false;
+                }
+                const outcomes = await Promise.all(pending);
+                if (callbackFailed)
+                    throw callbackFailure;
+                const failures = [];
+                for (const outcome of outcomes)
+                    if (outcome.status === "rejected")
+                        failures.push(outcome.reason);
+                if (failures.length === 1)
+                    throw failures[0];
+                if (failures.length > 1)
+                    throw new AggregateError(failures, "retained filesystem cleanup failed");
+            });
+            void closing.catch(() => { });
+        }
+        return closing;
+    };
+}