@poe-platform/safe-fs 0.1.803 → 0.1.805

package/README.md

@@ -1,6 +1,6 @@
 # safe-fs
 
-An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges. Portable filesystem types and POSIX helpers compile without Node types.
+An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges. Portable filesystem types and POSIX helpers compile without Node types. The `posixPath` export from `@poe-code/safe-fs/core` provides `basename`, `dirname`, `extname`, `join`, `isAbsolute`, `normalize`, `resolve`, `relative`, `sep`, and `delimiter`; `resolve` and `relative` use `/` as their working directory in every runtime.
 
 Under `workerd` and `browser` conditions, the root export includes portable filesystems, `S3FileSystem`, and `MockS3Client`. Supply an S3 transport to use object storage without Node globals.
 
@@ -86,14 +86,26 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 
 All required methods must exist, but a backend may reject an operation with `FsError`, such as `EROFS` for a write or `ENOTSUP` for unsupported semantics. Check optional methods and `capabilities` rather than assuming every backend behaves like a local disk. Errors expose `code` and may include `syscall`, `path`, `dest`, and `cause`.
 
+`readBytes` supports frozen host abort signals. The exported
+`listenForAbort(signal, listener)` returns a cleanup function for custom
+operations; if frozen host bookkeeping prevents registration, callers must
+check cancellation at operation boundaries, as `readBytes` does.
+
 `createDeviceFileSystem(fs)` adds portable `/dev/null` whole-file, stream, and descriptor I/O. Descriptor reads return EOF and writes discard bytes; stat remains a zero-size character device and descriptor position remains zero. Truncating opens are accepted, exclusive creation fails with `EEXIST`, and descriptor resizing and synchronization are unsupported. Access modes, cancellation, and closed handles use the normal descriptor checks. With an authoritative object store, use `createDeviceFileSystem(withObjectFileDescriptors(fs, store))` so null-device I/O never acquires or publishes an object version; ordinary files retain conditional publication. The device wrapper must be outermost for this composition.
 
+`PythonStatTranslator` and `createPythonRuntimeStatMapper` allocate stable guest device
+identities without a default device-count budget. Their optional `maxDevices` accepts
+`Infinity` or a positive safe integer. Explicit budgets remain enforced; device numbers
+must still fit the disjoint application/runtime ranges of the uint32 Python stat ABI.
+
 `withObjectFileDescriptors(fs, store)` supports large shell and Python descriptor
 writes when the host supplies `store.createStaging`: private externally backed
 pages keep working memory bounded without publishing the growing file after
 every write. Conditional publication still occurs at sync/close, and retained
 readers keep their old versions. Without that optional backend primitive, the
-optional dirty-page budget limits unflushed output only when configured. See the
+optional dirty-page budget limits unflushed output only when configured. Descriptor
+resource limits accept `Infinity` and are unlimited when omitted; `chunkBytes`
+remains a positive finite integer. See the
 [object descriptor and spill contract](src/contracts/object-publication.md) for
 backend methods, failure semantics and qualification; no provider storage is
 configured automatically.
@@ -270,7 +282,8 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 | Operation | Options |
 | --- | --- |
-| `readFile` | `maxBytes`: upper bound on collected bytes |
+| `readFile` | `maxBytes`: nonnegative safe-integer byte cap; `Infinity` adds no per-read cap |
+| `readdir` | `maxEntries`: nonnegative safe-integer entry cap; omission or `Infinity` preserves backend limits and ordering |
 | `writeFile`, `writeStream` | `flag`: `w` (default, replace), `wx` (exclusive create), `a` (append), or `ax` (exclusive append/create); optional `mode` |
 | `appendFile` | Optional `mode` |
 | `mkdir` | `recursive` (default false); optional `mode` |
@@ -278,7 +291,7 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 | `copyFile` | `exclusive` (default false) |
 | `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
 
-`validatePath(path, { maxPathBytes, maxPathComponents })` accepts optional UTF-8 byte and component quotas; both default to `Infinity`. Memory accepts the same constructor options and counts cumulative symlink expansion. Device operations accept these quotas under `pathLimits`. WebDAV accepts `maxTimestampPropertyBytes` for timestamp metadata, also unlimited by default.
+`validatePath(path, { maxPathBytes, maxPathComponents })` accepts optional UTF-8 byte and component quotas; both default to `Infinity`. Memory accepts the same constructor options and counts cumulative symlink expansion. Device operations and WebDAV stat, access, and writes accept these quotas under `pathLimits`. WebDAV accepts `maxTimestampPropertyBytes` for timestamp metadata, also unlimited by default.
 
 `access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
@@ -289,6 +302,11 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 `S3FileSystem` requires `transport` and `bucket`. A transport supplies `headObject`, `getObject`, `putObject`, `deleteObject`, `copyObject`, and `listObjectsV2`; see the [transport interface](src/fs/s3/transport.ts).
 
+`createS3NamespaceFileSystem` resource limits (`maxBytes`, `maxEntries`,
+`maxManifestBytes`, `maxAttempts`, and inherited descriptor limits) are unlimited
+when omitted or set to `Infinity`; positive safe integers enable finite limits.
+Namespace paths have no implicit length cap; configured manifest budgets still apply.
+
 `createS3Transport(client, capabilities?)` wraps a compatible client with explicit `streamingRead`, `streamingWrite`, `conditionalPut`, `conditionalCopy`, and `conditionalDelete` flags (all absent by default). Direct transport requests accept an optional `abortSignal`.
 
 For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, authorize? })` requires bucket names. `pageSize` defaults to 1,000 (range 1–1,000), `now` defaults to the current date/time, and optional `authorize(request)` can reject requests. It does not verify a real provider.

package/dist/safe-fs/bridge/filesystem.js

@@ -70,7 +70,7 @@ export class FileSystemBridge {
         assertBridgePath(this.#root, this.#cwd);
         this.#signal = options.signal;
         const maximum = options.readFileMaxBytes;
-        if (maximum !== undefined && (!Number.isSafeInteger(maximum) || maximum < 0))
+        if (maximum !== undefined && maximum !== Infinity && (!Number.isSafeInteger(maximum) || maximum < 0))
             throw new TypeError("Invalid readFileMaxBytes");
         this.#readFileMaxBytes = maximum;
         if (options.reserveReadFile !== undefined && typeof options.reserveReadFile !== "function")

package/dist/safe-fs/contracts/errors.d.ts

@@ -40,6 +40,7 @@ export interface FsErrorOptions extends ErrorOptions {
     readonly message?: string;
 }
 export declare class FsError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     readonly code: ErrnoCode;
     readonly errno: PlatformErrno;
     readonly syscall?: string;

package/dist/safe-fs/contracts/errors.js

@@ -31,7 +31,18 @@ const descriptions = {
     ETIMEDOUT: "operation timed out",
     EXDEV: "cross-device link not permitted",
 };
+const FS_ERROR_BRAND = Symbol.for("@poe-code/safe-fs.FsError");
 export class FsError extends Error {
+    static [Symbol.hasInstance](value) {
+        if (typeof value !== "object" || value === null)
+            return false;
+        if (this !== FsError)
+            return Function.prototype[Symbol.hasInstance].call(this, value);
+        if (Function.prototype[Symbol.hasInstance].call(FsError, value))
+            return true;
+        const record = value;
+        return record[FS_ERROR_BRAND] === true && isErrnoCode(record.code);
+    }
     code;
     errno;
     syscall;
@@ -44,14 +55,16 @@ export class FsError extends Error {
         const operation = options.syscall ? `, ${options.syscall}` : "";
         const path = options.path === undefined ? "" : ` '${options.path}'`;
         const destination = options.dest === undefined ? "" : ` -> '${options.dest}'`;
-        const prevStackLimit = Error.stackTraceLimit;
-        Error.stackTraceLimit = 0;
+        const errorConstructor = Error;
+        const prevStackLimit = errorConstructor.stackTraceLimit;
+        errorConstructor.stackTraceLimit = 0;
         try {
             super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
         }
         finally {
-            Error.stackTraceLimit = prevStackLimit;
+            errorConstructor.stackTraceLimit = prevStackLimit;
         }
+        Object.defineProperty(this, FS_ERROR_BRAND, { value: true, enumerable: false, configurable: false, writable: false });
         this.name = "FsError";
         this.code = code;
         this.errno = errno;

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -170,13 +170,14 @@ export interface RenameOptions extends FsOptions {
     readonly noReplace?: boolean;
 }
 export interface ReadFileOptions extends FsOptions {
+    /** Nonnegative safe-integer byte cap; Infinity adds no per-read cap. */
     readonly maxBytes?: number;
 }
 export interface ReadDirectoryOptions extends FsOptions {
     /**
-     * Optional per-listing entry admission limit, a nonnegative safe integer.
+     * Optional per-listing entry admission limit, a nonnegative safe integer or Infinity.
      * Zero permits an empty listing; overflow rejects with EFBIG, never truncates.
-     * Omission preserves the adapter's existing limits and ordering. Composed
+     * Omission or Infinity preserves the adapter's existing limits and ordering. Composed
      * adapters may conservatively count distinct candidates before visibility
      * filtering. This is not a global traversal, host-allocation or work quota.
      */

package/dist/safe-fs/contracts/io.d.ts

@@ -7,4 +7,6 @@ export interface CollectOptions {
 }
 export declare function toByteSource(input: string | Uint8Array): ByteSource;
 export declare function collectBytes(source: ByteSource, options: CollectOptions): Promise<Uint8Array>;
+/** Subscribe when supported; callers must still check cancellation at operation boundaries. */
+export declare function listenForAbort(signal: AbortSignal, listener: () => void): () => void;
 export declare function readBytes(source: ByteSource, signal?: AbortSignal): AsyncGenerator<Uint8Array>;

package/dist/safe-fs/contracts/io.js

@@ -108,27 +108,52 @@ export async function collectBytes(source, options) {
     options.signal?.throwIfAborted();
     return buffer.subarray(0, size);
 }
+/** Subscribe when supported; callers must still check cancellation at operation boundaries. */
+export function listenForAbort(signal, listener) {
+    let callback = listener;
+    const onAbort = () => callback?.();
+    const dispose = () => {
+        // Release operation state even when a frozen host refuses removal.
+        callback = undefined;
+        try {
+            signal.removeEventListener("abort", onAbort);
+        }
+        catch (error) {
+            if (!(error instanceof TypeError) || Object.isExtensible(signal))
+                throw error;
+        }
+    };
+    try {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
+    catch (error) {
+        // Frozen hosts may register before failing to update their bookkeeping.
+        dispose();
+        if (!(error instanceof TypeError) || Object.isExtensible(signal))
+            throw error;
+    }
+    return dispose;
+}
 async function abortable(operation, signal) {
     signal?.throwIfAborted();
     if (!signal)
         return operation();
     return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            signal.removeEventListener("abort", onAbort);
+        const dispose = listenForAbort(signal, () => {
+            dispose();
             reject(signal.reason);
-        };
-        signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
             Promise.resolve(operation()).then((result) => {
-                signal.removeEventListener("abort", onAbort);
+                dispose();
                 resolve(result);
             }, (error) => {
-                signal.removeEventListener("abort", onAbort);
+                dispose();
                 reject(error);
             });
         }
         catch (error) {
-            signal.removeEventListener("abort", onAbort);
+            dispose();
             reject(error);
         }
     });

package/dist/safe-fs/contracts/portable-path.d.ts

@@ -4,10 +4,18 @@ export declare const dirname: typeof virtualDirname;
 export declare function extname(path: string): string;
 export declare function isAbsolutePath(path: string): boolean;
 export declare function joinPath(...paths: string[]): string;
+declare function resolve(...paths: string[]): string;
+declare function relative(from: string, to: string): string;
 export declare const posixPath: Readonly<{
     basename: typeof basename;
     dirname: typeof virtualDirname;
     extname: typeof extname;
     join: typeof joinPath;
     isAbsolute: typeof isAbsolutePath;
+    normalize: typeof joinPath;
+    resolve: typeof resolve;
+    relative: typeof relative;
+    sep: "/";
+    delimiter: ":";
 }>;
+export {};

package/dist/safe-fs/contracts/portable-path.js

@@ -54,4 +54,25 @@ export function joinPath(...paths) {
     const result = `${absolute ? "/" : ""}${components.join("/")}` || ".";
     return joined.endsWith("/") && result !== "/" ? `${result}/` : result;
 }
-export const posixPath = Object.freeze({ basename, dirname, extname, join: joinPath, isAbsolute: isAbsolutePath });
+// Portable paths have a stable root instead of a process working directory.
+function resolve(...paths) {
+    let joined = "/";
+    for (const path of paths) {
+        assertString(path);
+        joined = path.startsWith("/") ? path : `${joined}/${path}`;
+    }
+    const normalized = joinPath(joined);
+    return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+function relative(from, to) {
+    const source = resolve(from).split("/").filter(Boolean);
+    const target = resolve(to).split("/").filter(Boolean);
+    let common = 0;
+    while (common < source.length && common < target.length && source[common] === target[common])
+        common++;
+    return [...Array(source.length - common).fill(".."), ...target.slice(common)].join("/");
+}
+export const posixPath = Object.freeze({
+    basename, dirname, extname, join: joinPath, isAbsolute: isAbsolutePath,
+    normalize: joinPath, resolve, relative, sep: "/", delimiter: ":"
+});

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

@@ -1,27 +1,16 @@
-export * from "./contracts/errors.js";
-export * from "./contracts/filesystem.js";
-export * from "./contracts/io.js";
-export { openFileDescriptor } from "./fs/descriptor.js";
-export type { DescriptorBackend, DescriptorOpenOptions } from "./fs/descriptor.js";
-export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
-export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
-export * from "./fs/memory/index.js";
-export * from "./fs/devices/index.js";
+export * from "./runtime-core.js";
+export { MemoryFileSystem, MemoryRedirectHandle, createMemoryFileSystem, defaultMemoryFileSystemLimits, bindConditionalMutation, getLastReadMemoryFileSourceRef, isCleanAbsolutePath, tryGetMemoryDirectoryEntryNamesSync, tryMkdirMemorySync, tryOpenMemoryRedirectHandleSync, tryReadMemoryFileViewSync, tryResolveMemoryDevicePath, tryRmRfMemorySync, tryWriteMemoryFileInDirSync, tryWriteMemoryFileSync, utf8ByteLength } from "./fs/memory/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
 export * from "./fs/object-publication/index.js";
-export { retargetScopedFileSystem, scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
-export type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
-export type { EntryViewResolver } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
-export { bindConditionalMutation, type ConditionalMutationBinding } from "./fs/memory/index.js";
 export * from "./fs/s3/index.js";
+export * from "./fs/s3/http/index.js";

package/dist/safe-fs/core.js

@@ -1,23 +1,15 @@
-export * from "./contracts/errors.js";
-export * from "./contracts/filesystem.js";
-export * from "./contracts/io.js";
-export { openFileDescriptor } from "./fs/descriptor.js";
-export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
-export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
-export * from "./fs/memory/index.js";
-export * from "./fs/devices/index.js";
+export * from "./runtime-core.js";
+export { MemoryFileSystem, MemoryRedirectHandle, createMemoryFileSystem, defaultMemoryFileSystemLimits, bindConditionalMutation, getLastReadMemoryFileSourceRef, isCleanAbsolutePath, tryGetMemoryDirectoryEntryNamesSync, tryMkdirMemorySync, tryOpenMemoryRedirectHandleSync, tryReadMemoryFileViewSync, tryResolveMemoryDevicePath, tryRmRfMemorySync, tryWriteMemoryFileInDirSync, tryWriteMemoryFileSync, utf8ByteLength } from "./fs/memory/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
 export * from "./fs/object-publication/index.js";
-export { retargetScopedFileSystem, scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
-export { bindConditionalMutation } from "./fs/memory/index.js";
 export * from "./fs/s3/index.js";
+export * from "./fs/s3/http/index.js";

package/dist/safe-fs/fs/devices/index.d.ts

@@ -1,15 +1,20 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
+import { type EntryLocation } from "../mount/comparison.js";
+import { pathNamespace } from "../path-namespace.js";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
     readonly capabilities: FileSystemCapabilities;
+    get [pathNamespace](): any;
+    _resolveEntryView: (path: string, options: FsOptions) => Promise<EntryLocation>;
+    _entryAuthority: () => Promise<"unknown">;
     constructor(filesystem: FileSystem);
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
-    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../runtime-core.js").EntryComparison>;
     realpath(path: string, options?: FsOptions): Promise<string>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;

package/dist/safe-fs/fs/devices/index.js

@@ -2,9 +2,9 @@ import { snapshotStagingCreation } from "../staging-cleanup.js";
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
-import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
+import { compareEntries } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
-import { tryResolveMemoryDevicePath } from "../memory/index.js";
+import { tryResolveMemoryDevicePath } from "../../runtime-core.js";
 import { createDeviceYield, deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
 import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "../capabilities.js";
 import { pathNamespace } from "../path-namespace.js";
@@ -71,21 +71,46 @@ function nonnegative(value, path) {
     if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
         throw new FsError("EINVAL", { path });
 }
+const sharedUnknownEntryAuthority = async () => "unknown";
 export class DeviceFileSystem {
     #filesystem;
     capabilities;
-    #nullStat;
-    #directoryStat;
+    #identityScopeObj;
+    #nullStatObj;
+    #directoryStatObj;
+    get [pathNamespace]() {
+        return Reflect.get(this.#filesystem, pathNamespace);
+    }
+    get #nullStat() {
+        if (this.#nullStatObj)
+            return this.#nullStatObj;
+        const identityScope = (this.#identityScopeObj ??= Object.freeze({}));
+        return (this.#nullStatObj = Object.freeze({
+            type: "character", mode: 0o020666, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
+            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 1, dev: 0, nlink: 1, preferredIoBlockSize: 4096,
+        }));
+    }
+    get #directoryStat() {
+        if (this.#directoryStatObj)
+            return this.#directoryStatObj;
+        const identityScope = (this.#identityScopeObj ??= Object.freeze({}));
+        return (this.#directoryStatObj = Object.freeze({
+            type: "directory", mode: 0o040755, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
+            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 2, dev: 0, nlink: 1,
+        }));
+    }
+    _resolveEntryView = async (path, options) => {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath || resolved === deviceDirectory) {
+            return { filesystem: this, path: resolved, stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
+        }
+        return { filesystem: this.#filesystem, path };
+    };
+    _entryAuthority = sharedUnknownEntryAuthority;
     constructor(filesystem) {
         this.#filesystem = filesystem;
-        Object.defineProperty(this, pathNamespace, { get: () => Reflect.get(filesystem, pathNamespace) });
         this.capabilities = globalCapabilities(filesystem);
-        const identityScope = Object.freeze({});
-        const stat = { mode: 0o020666, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
-            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 1, dev: 0, nlink: 1 };
-        this.#nullStat = Object.freeze({ ...stat, type: "character", preferredIoBlockSize: 4096 });
-        this.#directoryStat = Object.freeze({ ...stat, type: "directory", mode: 0o040755, ino: 2 });
-        const methods = new Map();
+        let methods;
         const view = new Proxy(this, {
             set: (_target, property, value) => Reflect.set(filesystem, property, value, filesystem),
             get(target, property) {
@@ -93,24 +118,14 @@ export class DeviceFileSystem {
                 if (typeof value !== "function" || property === "constructor")
                     return value;
                 const backing = Reflect.get(filesystem, property, filesystem);
-                const cached = methods.get(property);
+                const cached = methods?.get(property);
                 if (cached && cached.backing === backing)
                     return cached.bound;
                 const bound = value.bind(target);
-                methods.set(property, { backing, bound });
+                (methods ??= new Map()).set(property, { backing, bound });
                 return bound;
             },
         });
-        for (const identity of [this, view])
-            registerEntryView(identity, async (path, options) => {
-                const resolved = await this.#resolve(path, options);
-                if (resolved === nullPath || resolved === deviceDirectory)
-                    return { filesystem: this, path: resolved,
-                        stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
-                return { filesystem, path };
-            });
-        // This internal view has no identity proof beyond its synthetic stats.
-        registerEntryAuthority(this, async () => "unknown");
         return view;
     }
     #resolve(path, options, followFinal = true, resizeCreate, traversal) {
@@ -309,7 +324,8 @@ export class DeviceFileSystem {
     async #readFileSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         if (resolved === nullPath) {
-            nonnegative(options.maxBytes, path);
+            if (options.maxBytes !== Infinity)
+                nonnegative(options.maxBytes, path);
             return new Uint8Array();
         }
         if (resolved === deviceDirectory)

package/dist/safe-fs/fs/devices/path.js

@@ -1,7 +1,7 @@
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { pathByteLength, validatePath } from "../../contracts/virtual-path.js";
 import { capturePathNamespace, pathNamespace } from "../path-namespace.js";
-import { isCleanAbsolutePath, tryResolveMemoryDevicePath } from "../memory/index.js";
+import { isCleanAbsolutePath, tryResolveMemoryDevicePath } from "../../runtime-core.js";
 export const nullPath = "/dev/null";
 export const deviceDirectory = "/dev";
 function isNullParts(parts) {

package/dist/safe-fs/fs/directory-admission.js

@@ -1,9 +1,9 @@
 import { FsError } from "../contracts/errors.js";
 export function directoryEntryLimit(options, path) {
     options.signal?.throwIfAborted();
-    const limit = options.maxEntries;
+    const limit = options.maxEntries === Infinity ? undefined : options.maxEntries;
     if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
-        throw new FsError("EINVAL", { syscall: "readdir", path, message: "directory entry limit must be a nonnegative safe integer" });
+        throw new FsError("EINVAL", { syscall: "readdir", path, message: "directory entry limit must be a nonnegative safe integer or Infinity" });
     }
     return limit;
 }

package/dist/safe-fs/fs/memory/atomic-view.d.ts

@@ -4,5 +4,8 @@ export interface MemoryAtomicView {
     stat(path: string): FileStat | undefined;
     names(path: string): readonly string[];
 }
+type LazyMemoryAtomicView = (this: FileSystem) => MemoryAtomicView | undefined;
 export declare function registerMemoryAtomicView(fs: FileSystem, view: MemoryAtomicView, intact: () => boolean): void;
+export declare function registerLazyMemoryAtomicView(fs: FileSystem, create: LazyMemoryAtomicView): void;
 export declare function memoryAtomicView(fs: FileSystem): MemoryAtomicView | undefined;
+export {};

package/dist/safe-fs/fs/memory/atomic-view.js

@@ -2,7 +2,12 @@ const views = new WeakMap();
 export function registerMemoryAtomicView(fs, view, intact) {
     views.set(fs, { view, intact });
 }
+export function registerLazyMemoryAtomicView(fs, create) {
+    views.set(fs, create);
+}
 export function memoryAtomicView(fs) {
     const registered = views.get(fs);
+    if (typeof registered === "function")
+        return registered.call(fs);
     return registered?.intact() ? registered.view : undefined;
 }

package/dist/safe-fs/fs/memory/index.d.ts

@@ -1,5 +1,6 @@
 import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
+import { type MemoryAtomicView } from "./atomic-view.js";
 import { MemoryAllocation, MemoryLedger } from "./ledger.js";
 import { type MemoryFileSystemOptions } from "./limits.js";
 export { defaultMemoryFileSystemLimits, type MemoryFileSystemLimits, type MemoryFileSystemOptions } from "./limits.js";
@@ -59,9 +60,10 @@ export interface ConditionalMutationBinding {
 }
 export declare function bindConditionalMutation<Result>(identityScope: object | symbol | undefined, binding: ConditionalMutationBinding, action: () => Promise<Result>): Promise<Result>;
 export declare class MemoryFileSystem implements FileSystem {
+    #private;
     capabilitiesFor?: NonNullable<FileSystem["capabilitiesFor"]>;
-    readonly capabilities: FileSystemCapabilities;
-    private readonly identityScope;
+    private get identityScope();
+    get capabilities(): FileSystemCapabilities;
     private nextInode;
     private readonly ledger;
     readonly _cache: MemoryCache;
@@ -70,6 +72,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private readonly root;
     private totalBytes;
     symlinkCount: number;
+    _getAtomicView(): MemoryAtomicView | undefined;
     constructor(options?: MemoryFileSystemOptions);
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
@@ -173,7 +176,7 @@ export declare function utf8ByteLength(value: string): number;
 export declare function isCleanAbsolutePath(path: string): boolean;
 export declare function tryResolveMemoryDevicePath(filesystem: FileSystem, path: string, resizeCreate?: boolean): string | undefined;
 export declare function getLastReadMemoryFileSourceRef(view: Uint8Array): Uint8Array | undefined;
-export declare function tryReadMemoryFileViewSync(filesystem: FileSystem, path: string, maxBytes?: number, signal?: AbortSignal, captureSourceRef?: boolean): Uint8Array | undefined;
+export declare function tryReadMemoryFileViewSync(filesystem: FileSystem, path: string, maxBytes?: number, signal?: AbortSignal, captureSourceRef?: boolean, beforeRead?: () => void): Uint8Array | undefined;
 export declare function tryGetMemoryDirectoryEntryNamesSync(filesystem: FileSystem, path: string): ReadonlyMap<string, {
     readonly type: "file" | "directory" | "symlink";
 }> | undefined;