@poe-platform/safe-fs 0.1.727 → 0.1.728

package/dist/safe-fs/fs/scoped.js

@@ -1,9 +1,15 @@
-import { FsError } from "../contracts/errors.js";
+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 } 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 operations = new Set([
+    "prepareDirectoryAncestry", "prepareStagingResolution",
     "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",
@@ -13,6 +19,7 @@ const operations = new Set([
 export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge, options = {}) {
     const original = originals.get(filesystem)?.filesystem ?? filesystem;
     const creationMask = options.creationMask ?? originals.get(filesystem)?.creationMask;
+    const 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) => {
@@ -161,56 +168,96 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             close: () => closing ??= Promise.resolve().then(() => descriptor.close()),
         };
     };
-    const wrapStream = (source, options) => ({
-        [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 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;
                     }
-                    const result = await operation();
-                    assertOpen(options);
-                    if (closing) {
-                        await closing;
-                        return { done: true, value: undefined };
+                    catch (error) {
+                        await finishCleanup(close, true);
+                        throw error;
                     }
-                    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)) } : {}),
-            };
-        },
-    });
+                };
+                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 === "capabilities")
-                return ownedMutationCapabilities(original, retainedResizeCapabilities(original));
+            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 dispatch = (...args) => {
+            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") {
+                    signal.throwIfAborted();
+                    if (property === "createStagedFile")
+                        args[3] = snapshotStagingCreation(args[3], args[0]);
+                    const callerSignal = args[property === "createStagedFile" ? 3 : 2]?.signal;
+                    stagingSignal = callerSignal && callerSignal !== signal ? AbortSignal.any([signal, callerSignal]) : signal;
+                    stagingSignal.throwIfAborted();
+                }
                 if (operations.has(property)) {
                     const options = args.at(-1);
-                    admit(options && typeof options === "object" && "signal" in options ? options : undefined);
+                    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 (["writeFile", "appendFile", "writeStream", "mkdir"].includes(String(property))) {
                     const index = property === "mkdir" ? 1 : 2;
@@ -219,15 +266,89 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                 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 options = args[property === "createStagedFile" ? 3 : property === "publishFileConditional" || property === "publishStagedFile" || property === "writeFileConditional" ? 2 : 1];
-                        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);
-                        assertOpen(options);
-                        if (property === "publishFileConditional") {
-                            args[1] = wrapStream(args[1], options);
-                            args[2] = resizeOptions(options ?? {});
+                        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());
+                            return Object.freeze({ ...staging, cleanup });
+                        }
+                        catch (error) {
+                            await finishCleanup(() => backendCleanup.close(), true);
+                            throw error;
                         }
-                        return Reflect.apply(method, original, args);
                     })();
                 if (property === "compareEntry") {
                     const peer = args[1];
@@ -244,47 +365,113 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             });
                         return Reflect.apply(method, original, args);
                     })();
-                return Reflect.apply(method, original, args);
+                const result = Reflect.apply(method, original, args);
+                return property === "readStream" ? wrapStream(result, args[1]) : result;
             };
-            const scoped = 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;
+            const dispatch = (...args) => hasRegisteredS3FileSystem
+                ? runScopedTransportBudget(admit, () => executeDispatch(args), credit)
+                : executeDispatch(args);
+            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 {
-                            descriptor = await Reflect.apply(method, original, [path, selected]);
-                            assertOpen(options);
-                            return wrapDescriptor(descriptor);
+                            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) {
-                            if (descriptor)
-                                await finishCleanup(() => descriptor.close(), true);
-                            assertOpen(options);
+                            controls.signal?.throwIfAborted();
                             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))
-                                : property === "readStream"
-                                    ? (...args) => wrapStream(dispatch(...args), args[1])
-                                    : operations.has(property) && property !== "canonicalizeMissingTarget"
-                                        ? async (...args) => dispatch(...args)
-                                        : dispatch;
+                    : 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;
         },
     });
-    originals.set(view, { filesystem: original, signal, cleanupCharge, creationMask });
+    originals.set(view, { filesystem: original, signal, cleanupCharge, creationMask, maxPathComponents });
     registerEntryView(view, async (path, options) => {
         assertOpen(options);
         return { filesystem: original, path };

package/dist/safe-fs/fs/staging-ancestry.d.ts

@@ -0,0 +1,8 @@
+import type { FileStagingEntry, FileStagingResolution, FileStat, PublishStagedFileOptions } from "../contracts/filesystem.js";
+export declare function directoryAncestryPaths(directory: string): string[];
+export declare function snapshotDirectoryAncestry(ancestors: readonly FileStagingEntry[]): readonly FileStagingEntry[];
+export declare function runStagingGuard(guard: () => true): void;
+export declare function snapshotStagingResolution(resolution: FileStagingResolution): FileStagingResolution;
+/** Diagnose failed admission against supplied receipts; this is never a commit
+ * guard. Successful publication still requires the backend's atomic checks. */
+export declare function inspectStagingBindings(read: (path: string) => Promise<FileStat>, destination: string, options: PublishStagedFileOptions): Promise<void>;

package/dist/safe-fs/fs/staging-ancestry.js

@@ -0,0 +1,115 @@
+import { FsError, toFsError } from "../contracts/errors.js";
+import { compareIdentity } from "./mount/identity.js";
+import { normalizePath, validatePath } from "../contracts/virtual-path.js";
+export function directoryAncestryPaths(directory) {
+    validatePath(directory);
+    if (!directory.startsWith("/") || normalizePath(directory) !== directory)
+        throw new FsError("EINVAL", { path: directory });
+    let path = "";
+    return ["/", ...directory.split("/").filter(Boolean).map(component => path += `/${component}`)];
+}
+export function snapshotDirectoryAncestry(ancestors) {
+    const entries = ancestors.map(entry => Object.freeze({ path: entry.path, stat: Object.freeze({ ...entry.stat }) }));
+    const paths = directoryAncestryPaths(entries.at(-1)?.path ?? "");
+    if (entries.length !== paths.length || entries.some((entry, index) => entry.path !== paths[index])) {
+        throw new FsError("EINVAL", { message: "directory ancestry requires a complete ordered root-to-directory list" });
+    }
+    for (const entry of entries) {
+        if (entry.stat.type !== "directory")
+            throw new FsError("EINVAL", { path: entry.path });
+        if (compareIdentity(entry.stat, entry.stat) !== "same")
+            throw new FsError("ENOTSUP", { path: entry.path });
+    }
+    return Object.freeze(entries);
+}
+export function runStagingGuard(guard) {
+    const result = guard();
+    if (result !== true) {
+        // A void callback would accept async implementations. Require a literal
+        // success value and observe a misdeclared asynchronous rejection.
+        void Promise.resolve(result).catch(() => { });
+        throw new FsError("ENOTSUP", { message: "staging validation must return true synchronously" });
+    }
+}
+export function snapshotStagingResolution(resolution) {
+    const path = resolution.path;
+    validatePath(path);
+    const ancestors = snapshotDirectoryAncestry(resolution.ancestors);
+    const validate = resolution.validate;
+    if (normalizePath(path) !== path || !path.startsWith("/") || path === "/"
+        || ancestors.at(-1).path !== (path.slice(0, path.lastIndexOf("/")) || "/")
+        || typeof validate !== "function")
+        throw new FsError("EINVAL", { path });
+    const parent = Object.freeze({ ...resolution.parent });
+    if (parent.type !== "directory")
+        throw new FsError("EINVAL", { path });
+    if (compareIdentity(parent, ancestors.at(-1).stat) !== "same")
+        throw new FsError("ENOTSUP", { path });
+    const supplied = resolution.destination;
+    const destination = supplied === null ? null : Object.freeze({ ...supplied });
+    const requireSnapshot = (stat) => {
+        if (compareIdentity(stat, stat) !== "same" || stat.type !== "directory" && (!Number.isSafeInteger(stat.revision) || stat.revision < 0)) {
+            throw new FsError("ENOTSUP", { path });
+        }
+    };
+    if (destination !== null) {
+        if (destination.type !== "file")
+            throw new FsError("EINVAL", { path });
+        requireSnapshot(destination);
+    }
+    if (!resolution.traversed.length)
+        throw new FsError("EINVAL", { path });
+    if (resolution.traversed.length > 4096)
+        throw new FsError("EFBIG", { path });
+    let recordedUnits = 0;
+    const traversed = resolution.traversed.map(entry => {
+        const entryPath = entry.path, stat = Object.freeze({ ...entry.stat }), linkTarget = entry.linkTarget;
+        validatePath(entryPath);
+        if (!entryPath.startsWith("/") || normalizePath(entryPath) !== entryPath
+            || !["directory", "file", "symlink"].includes(stat.type)
+            || stat.type === "symlink" && typeof linkTarget !== "string"
+            || stat.type !== "symlink" && linkTarget !== undefined)
+            throw new FsError("EINVAL", { path: entryPath });
+        requireSnapshot(stat);
+        recordedUnits += entryPath.length + (linkTarget?.length ?? 0);
+        if (recordedUnits > 1_048_576)
+            throw new FsError("EFBIG", { path });
+        return Object.freeze({ path: entryPath, stat, ...(linkTarget === undefined ? {} : { linkTarget }) });
+    });
+    return Object.freeze({ path, parent, destination, ancestors, traversed: Object.freeze(traversed), validate });
+}
+/** Diagnose failed admission against supplied receipts; this is never a commit
+ * guard. Successful publication still requires the backend's atomic checks. */
+export async function inspectStagingBindings(read, destination, options) {
+    options.signal?.throwIfAborted();
+    const ancestors = snapshotDirectoryAncestry(options.ancestors);
+    const parent = destination.slice(0, destination.lastIndexOf("/")) || "/";
+    if (normalizePath(destination) !== destination || ancestors.at(-1)?.path !== parent)
+        throw new FsError("EINVAL", { path: destination });
+    const expected = options.destination === null ? null : { ...options.destination };
+    if (expected !== null && (compareIdentity(expected, expected) !== "same"
+        || expected.type === "file" && (!Number.isSafeInteger(expected.revision) || expected.revision < 0)))
+        throw new FsError("ENOTSUP", { path: destination });
+    const entries = [...ancestors.map(entry => ({ ...entry, directory: true })), { path: destination, stat: expected, directory: false }];
+    for (const entry of entries) {
+        let current;
+        try {
+            current = await read(entry.path);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            const code = toFsError(error).code;
+            if (code === "ENOENT" && entry.stat === null)
+                continue;
+            if (["ENOENT", "ENOTDIR", "ELOOP"].includes(code))
+                throw new FsError("EAGAIN", { path: entry.path, cause: error });
+            throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (entry.stat === null || current.type !== entry.stat.type || compareIdentity(current, entry.stat) !== "same")
+            throw new FsError("EAGAIN", { path: entry.path });
+        if (!entry.directory && ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].some(field => current[field] !== entry.stat[field])) {
+            throw new FsError("EAGAIN", { path: entry.path });
+        }
+    }
+}

package/dist/safe-fs/fs/staging-cleanup.d.ts

@@ -0,0 +1,5 @@
+import type { CreateStagedFileOptions, FileStagingCleanup, FsOptions } from "../contracts/filesystem.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export declare function snapshotStagingCreation(options: CreateStagedFileOptions, path: string): CreateStagedFileOptions;
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export declare function createStagingCleanup(path: string, remove: (options: FsOptions) => void | Promise<void>, release: () => void | Promise<void>): FileStagingCleanup;

package/dist/safe-fs/fs/staging-cleanup.js

@@ -0,0 +1,63 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export function snapshotStagingCreation(options, path) {
+    const captured = { ...options };
+    for (const key of ["signal", "retainCleanup", "parent", "mode", "atimeMs", "mtimeMs"]) {
+        if (!Object.hasOwn(captured, key))
+            Object.defineProperty(captured, key, { value: options[key], enumerable: true });
+    }
+    const { signal, retainCleanup, parent, mode, atimeMs, mtimeMs, ...extra } = captured;
+    signal?.throwIfAborted();
+    if (retainCleanup !== undefined && typeof retainCleanup !== "boolean")
+        throw new FsError("EINVAL", { syscall: "createStagedFile", path });
+    return {
+        ...extra, parent,
+        ...(signal === undefined ? {} : { signal }),
+        ...(retainCleanup === undefined ? {} : { retainCleanup }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(atimeMs === undefined ? {} : { atimeMs }),
+        ...(mtimeMs === undefined ? {} : { mtimeMs }),
+    };
+}
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export function createStagingCleanup(path, remove, release) {
+    let accepting = true;
+    let removal;
+    let closing;
+    let released;
+    const dispose = () => released ??= Promise.resolve().then(release);
+    return Object.freeze({
+        remove(options = {}) {
+            if (removal)
+                return removal;
+            if (!accepting) {
+                const rejected = Promise.reject(new FsError("EBADF", { syscall: "removeStagedFile", path }));
+                void rejected.catch(() => { });
+                return rejected;
+            }
+            accepting = false;
+            removal = Promise.resolve().then(async () => {
+                let failed = true;
+                try {
+                    await remove(options);
+                    failed = false;
+                }
+                finally {
+                    await finishCleanup(dispose, failed);
+                }
+            });
+            void removal.catch(() => { });
+            return removal;
+        },
+        close() {
+            accepting = false;
+            closing ??= (async () => {
+                await removal?.catch(() => { });
+                await dispose();
+            })();
+            void closing.catch(() => { });
+            return closing;
+        },
+    });
+}

package/dist/safe-fs/platform/browser.d.ts

@@ -1,4 +1,5 @@
 import type { FsOptions } from "../contracts/filesystem.js";
+import type { ScopedTransportBudgetFrame } from "./transport-budget.js";
 export type PlatformErrno = number | undefined;
 export type PlatformComparisonCallback<Callback> = Callback & never;
 export declare const platform: Readonly<{
@@ -11,3 +12,7 @@ export declare const comparisonContext: Readonly<{
     active(options: FsOptions): boolean;
     run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
 }>;
+export declare function getScopedTransportBudget(): readonly ScopedTransportBudgetFrame[] | undefined;
+export declare function withScopedTransportBudget<Result>(frames: readonly ScopedTransportBudgetFrame[] | undefined, action: () => Result): Result;
+export declare function runScopedTransportBudget<Result>(_admit: (options?: FsOptions) => void, action: () => Result, _credit?: number): Result;
+export declare function chargeScopedTransportCall(options?: FsOptions): never;

package/dist/safe-fs/platform/browser.js

@@ -38,3 +38,20 @@ export const comparisonContext = Object.freeze({
         }
     }
 });
+// Scoped browser filesystems charge logical operations directly. S3 remains
+// Node-only; never pretend to provide its async transport budget context here.
+export function getScopedTransportBudget() {
+    return undefined;
+}
+export function withScopedTransportBudget(frames, action) {
+    if (frames !== undefined)
+        throw new FsError("ENOTSUP", { message: "S3 transport budget contexts require Node" });
+    return action();
+}
+export function runScopedTransportBudget(_admit, action, _credit = 1) {
+    return action();
+}
+export function chargeScopedTransportCall(options) {
+    options?.signal?.throwIfAborted();
+    throw new FsError("ENOTSUP", { message: "S3 transport budget contexts require Node" });
+}