@poe-platform/safe-fs 0.1.727 → 0.1.729

package/dist/safe-fs/fs/s3/http/transport.js

@@ -4,6 +4,23 @@ import { abortable, collect, limitedBody, scopeFor, sendRequest } from "./reques
 import { canonicalQuery, headerValue, invalid, signRequest, uriEncode } from "./signature.js";
 import { children, integer, malformed, parseXml, text, timestamp } from "./xml.js";
 const empty = new Uint8Array();
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length && value.charCodeAt(i + 1) >= 0xdc00 && value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
 function limit(value, fallback, name, maximum = Number.MAX_SAFE_INTEGER) {
     if (value === undefined)
         return fallback;
@@ -23,7 +40,7 @@ function bucketName(bucket) {
         invalid("expected a standard S3 bucket name");
 }
 function objectKey(key) {
-    if (typeof key !== "string" || !key || Buffer.byteLength(key) > 1024)
+    if (typeof key !== "string" || !key || utf8ByteLength(key) > 1024)
         invalid("object keys must contain 1..1024 UTF-8 bytes");
     uriEncode(key);
 }
@@ -57,7 +74,7 @@ function metadataHeaders(metadata) {
         if (!/^[a-z0-9][a-z0-9_-]*$/.test(lower) || `x-amz-meta-${lower}` in headers)
             invalid("invalid or duplicate metadata key");
         const normalized = headerValue(value);
-        size += Buffer.byteLength(lower) + Buffer.byteLength(normalized);
+        size += utf8ByteLength(lower) + utf8ByteLength(normalized);
         if (size > 2048)
             invalid("metadata exceeds 2 KiB");
         headers[`x-amz-meta-${lower}`] = normalized;
@@ -413,7 +430,7 @@ export function createS3HttpTransport(options) {
             const query = [["list-type", "2"], ["encoding-type", "url"]];
             for (const [name, value] of [["prefix", input.Prefix], ["delimiter", input.Delimiter], ["continuation-token", input.ContinuationToken]]) {
                 if (value !== undefined) {
-                    if (typeof value !== "string" || Buffer.byteLength(value) > 8192)
+                    if (typeof value !== "string" || utf8ByteLength(value) > 8192)
                         invalid(`invalid ${name}`);
                     query.push([name, value]);
                 }

package/dist/safe-fs/fs/s3/mock.js

@@ -1,3 +1,20 @@
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length && value.charCodeAt(i + 1) >= 0xdc00 && value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
 import { createHash } from "node:crypto";
 import { collectBytes } from "../../contracts/io.js";
 import { recordMockS3Head } from "./authority.js";
@@ -37,7 +54,7 @@ export class MockS3Client {
             throw new S3ServiceError("AbortError", 499);
         if (!this.buckets.has(input.Bucket))
             throw new S3ServiceError("NoSuchBucket", 404);
-        if ("Key" in input && (input.Key.length === 0 || Buffer.byteLength(input.Key) > 1024)) {
+        if ("Key" in input && (input.Key.length === 0 || utf8ByteLength(input.Key) > 1024)) {
             throw new S3ServiceError("InvalidArgument", 400);
         }
     }
@@ -62,7 +79,7 @@ export class MockS3Client {
         };
     }
     store(body, metadata = {}) {
-        const metadataBytes = Object.entries(metadata).reduce((total, [key, value]) => total + Buffer.byteLength(key) + Buffer.byteLength(value), 0);
+        const metadataBytes = Object.entries(metadata).reduce((total, [key, value]) => total + utf8ByteLength(key) + utf8ByteLength(value), 0);
         if (metadataBytes > 2048)
             throw new S3ServiceError("MetadataTooLarge", 400);
         return {

package/dist/safe-fs/fs/s3/namespace.js

@@ -250,7 +250,7 @@ export async function createS3NamespaceFileSystem(options) {
     const filesystem = {
         capabilities: Object.freeze({ read: true, write: true, append: true, stat: true, readdir: true, realpath: true, access: true,
             mkdir: true, recursiveMkdir: true, explicitDirectories: true, implicitDirectories: false, exclusiveCreate: true,
-            remove: true, removeDirectory: true, recursiveRemove: true, atomicTreeRemoval: true, atomicEntryRemoval: true,
+            remove: true, removeDirectory: true, recursiveRemove: true, atomicTreeRemoval: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: false,
             rename: true, atomicRename: true, atomicRenameNoReplace: true, copy: true, exclusiveCopy: true,
             readOnly: false, symlinks: false, hardlinks: false, permissions: false, timestamps: false }),
         stat: observe,
@@ -313,7 +313,13 @@ export async function createS3NamespaceFileSystem(options) {
         async unlink(input, forwarded = {}) { entryPath(input); await mutate(forwarded, value => remove(value, resolveName(value, input), false, 'file')); },
         async rmdir(input, forwarded = {}) { entryPath(input); await mutate(forwarded, value => remove(value, resolveName(value, input), false, 'directory')); },
         async removeTreeConditional(input, forwarded) { entryPath(input); return conditionalRemove(input, forwarded, true); },
-        async removeEntryConditional(input, forwarded) { entryPath(input); return conditionalRemove(input, forwarded, false); },
+        async removeEntryConditional(input, forwarded) {
+            forwarded.signal?.throwIfAborted();
+            if (forwarded.returnRemainingStat === true)
+                throw new FsError('ENOTSUP');
+            entryPath(input);
+            return conditionalRemove(input, forwarded, false);
+        },
         async rename(source, destination, forwarded = {}) {
             entryPath(source);
             entryPath(destination);

package/dist/safe-fs/fs/s3/registry.js

@@ -1,5 +1,6 @@
 import { FsError } from "../../contracts/errors.js";
 import { assertCallbackAuthorityAllowed } from "../mount/comparison.js";
+import { enableS3TransportBudget } from "../../platform/transport-budget.js";
 const observedStats = new WeakMap();
 const entries = new WeakMap();
 const comparisons = new WeakMap();
@@ -8,6 +9,7 @@ export function recordS3Observation(filesystem, path, stat, entry) {
     observedStats.set(stat, { filesystem, path, entry });
 }
 export function registerS3EntryOwner(filesystem, normalize, intact, baseComparison, comparison) {
+    enableS3TransportBudget();
     comparisons.set(filesystem, baseComparison);
     if (comparison)
         configuredComparisons.set(filesystem, comparison);

package/dist/safe-fs/fs/scoped.d.ts

@@ -2,6 +2,7 @@ import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
 export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void, options?: {
     readonly preserveDescriptorWriteReceipt?: boolean;
     readonly creationMask?: number;
+    readonly maxPathComponents?: number;
 }): FileSystem;
 export interface RetainedFileSystemCleanupView {
     readonly removeFileConditional?: NonNullable<FileSystem["removeFileConditional"]>;

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>;