@poe-platform/safe-fs 0.1.807 → 0.1.809

package/README.md

@@ -4,6 +4,17 @@ An asynchronous filesystem interface for memory, rooted host directories, S3, an
 
 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.
 
+The `storage` subpath exposes `PagedStorage` and `IntegerTable` for temporary
+working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
+(default 64 pages of 16 KiB). Scratch data uses retained positioned handles in
+`env.TMPDIR` or `cwd`, with conditional unlink and cleanup through `close()`.
+Providers must support those capabilities; there is no host fallback. Use an
+external backend for large data because memory filesystems retain spilled bytes.
+`IntegerTable.entries()` replays records in unsigned key order with a fixed
+16-level node stack and batches of at most 128 records. It accepts zero-filled
+caller storage with `allocate`, `read` and `write`; mutation during traversal
+is rejected. Branch pointers use a separate fixed 128-entry cache.
+
 ## Quickstart
 
 Install the standalone package; it does not depend on SafeJS, Safe Bash, or the `poe-code` CLI. These examples use TypeScript in a Node ESM application.
@@ -79,9 +90,11 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 | Change the namespace | `mkdir`, `rm`, `rename`, `copyFile` |
 | Remove an empty directory | Optional `rmdir`; never a recursive-delete fallback |
 | Links and metadata | Optional `readlink`, `symlink`, `link`, `chmod`, `utimes`, `truncate` |
+| Enumerate directories lazily | Optional `iterateDirectory`; memory, native and paged S3 backends, with mount/overlay/readonly/quota/device/scoped delegation; backend order, no sorted-array fallback |
 | Stream bytes | Optional `readStream`, `writeStream`, using async iterables of byte chunks |
 | Retain an open file | Optional `open` with positioned I/O and synchronization; memory and real backends support `noFollow: true` to atomically refuse a final symlink |
 | Publish immutable objects atomically | Optional `publishFileConditional` with opaque identity/version stats and authoritative compare-and-publish |
+| Publish a checked source set | Optional `publishStagedFileSet` publishes a staged file and retires sibling entries in one backend commit; mount views require all entries on the same supporting backend |
 | Compare backing entries | Optional `compareEntry`, returning `same`, `distinct`, or `unknown` |
 
 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`.
@@ -124,7 +137,11 @@ For temporary staging that must be cleaned up after its parent moves, adapters
 advertising `retainedStagingCleanup` accept `createStagedFile(..., { parent,
 retainCleanup: true })`. Use the returned `staging.cleanup.remove()` and always
 call `staging.cleanup.close()` in `finally`. Memory and its supported wrappers
-retain only the owned staging entries; replacement entries remain protected.
+retain only the owned staging entries; replacement entries remain protected. When
+`atomicStagedFileMutation` is available, `publishStagedFile(..., { preserveIdentity: true,
+parent, destination })` updates an existing file without breaking hardlink aliases.
+Memory and its supported wrappers adopt staged bytes and timestamps while keeping
+the destination identity and mode; unsupported adapters reject this option.
 Overlays backed by stock Memory filesystems support conditional file mutations,
 directory preparation, and confined staging. Publication may omit `ancestors`
 when the destination shares the staging parent; the overlay checks the ancestry
@@ -295,6 +312,16 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 `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).
 
+Overlay copy-up, copy, stream replacement/append and resize transfer retained ranges in 64 KiB chunks through the injected upper's stream writer. Resize streams the retained prefix and bounded zero chunks. Stream writes stage input before publication; cancellation or transfer failure leaves the destination unchanged and cleans staging. Stock Memory overlays transfer staged storage into existing upper inodes, preserving hardlinks without an additional whole-file buffer. `readFile` and `writeFile` remain buffering convenience APIs; use `readStream`/`writeStream` for large payloads. `maxBufferBytes` retains its existing optional total-byte admission semantics, not a working-memory guarantee.
+
+A streaming overlay needs an upper with `atomicRename`, `streamingWrite`, retained reads (`retainedRead` plus `openReadFile`), exclusive create, directory mutation, permissions and timestamps. Both layers must provide retained, bounded range reads with stable file and directory identities. For example, inject these host-authorized adapters with `createOverlayFileSystem({ upper: externalSpool, lower: retainedSource })`, then use `overlay.writeStream(path, source)`. The upper must await each consumed chunk, keep transport queues bounded, and preserve ownership until publication. Supply bounded chunks at the input boundary; the overlay cannot undo a payload-wide allocation already made by its caller. Whole-file-only uppers explicitly reject transfer operations with `ENOTSUP`; they do not silently collect streams.
+
+For Workers, `externalSpool` must store payloads outside isolate RAM and satisfy that contract, including atomic rename and retained identity. Memory and the S3 mock store payloads in RAM and are not external spools. Stock S3/WebDAV do not provide the atomic rename/retained-read contract needed for an overlay upper; setting a capability flag does not add it. A host must inject a qualified external adapter. On Node, rooted Real adapters provide the streaming overlay configuration under their documented external-tree isolation requirement. Mount and read-only wrappers forward the selected backend's capabilities; quota streaming additionally requires a real streaming-append route. S3's buffered append convenience path reports `streamingAppend: false`.
+
+The reusable metadata-only fixture in [`tests/fixtures/bounded-filesystem.ts`](tests/fixtures/bounded-filesystem.ts) generates file ranges and consumes slow writes without storing payload bytes. [`tests/overlay-bounded.test.ts`](tests/overlay-bounded.test.ts) checks fixed transfer sizes, source backpressure, cancellation/error cleanup, byte results, and Memory publication allocation/identity. These deterministic conformance checks do not qualify a deployed Worker backend; follow the [Worker QA plan](../../docs/plans/safe-fs-bounded-overlay-qa.md) for runtime measurements.
+
+`readFileStream(fs, path, options)` reads through the caller's native stream or retained range handle without calling `readFile`. It accepts the stream range/window options above, defaults to a 64 KiB read window, and closes owned readers on completion, failure or cancellation. `skipStream: true` selects retained ranges after an already-attempted stream reports `ENOTSUP`. Chunks are borrowed until the iterator advances. Native adapters must honor the requested window and backpressure. Whole-file-only backends receive `ENOTSUP`; use a streaming or retained-range backend for sequential Worker operations. This helper bounds its I/O window, not the consuming command's parser or output capture.
+
 `collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxBytes` and `maxMemoryBytes` accept explicit `Infinity`. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Collection limits are disabled by default on Node, browser, and Worker targets. Each call owns its budget; concurrent collections do not consume one another’s allowance. The returned view may retain geometric spare capacity. Configured budgets cover collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
 
 <details>

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

@@ -76,6 +76,8 @@ export interface FileSystemCapabilities {
     /** Owned staging serialized within a trusted host; requires external tree isolation. */
     readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Staged payload publication can atomically preserve an existing inode. */
+    readonly atomicStagedFileMutation?: boolean;
     /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
     readonly retainedStagingCleanup?: boolean;
     readonly retainedStagingWrite?: boolean;
@@ -85,6 +87,8 @@ export interface FileSystemCapabilities {
     readonly synchronousDirectoryValidation?: boolean;
     /** Captures a followed destination path with a synchronous commit validator. */
     readonly synchronousStagingResolution?: boolean;
+    /** Also binds the final symlink and its target in the synchronous validator. */
+    readonly synchronousFollowedStagingResolution?: boolean;
     /** Invokes commitGuard in the same synchronous section as staged replacement. */
     readonly guardedStagingPublication?: boolean;
     readonly atomicFilePublication?: boolean;
@@ -127,6 +131,7 @@ export interface CapabilityQueryOptions extends OpenReadFileOptions {
      * Omission retains the ordinary per-target query and its acquisition intent. */
     readonly stagingAncestry?: boolean;
     readonly stagingResolution?: boolean;
+    readonly followFinalSymlink?: boolean;
     readonly create?: boolean;
     readonly creation?: OpenFileOptions["creation"];
 }
@@ -231,6 +236,10 @@ export interface FileStagingEntry {
 export interface FileResolutionStep extends FileStagingEntry {
     readonly linkTarget?: string;
 }
+export interface PrepareStagingResolutionOptions extends FsOptions {
+    /** Requires synchronousFollowedStagingResolution; omission preserves final-entry resolution. */
+    readonly followFinalSymlink?: boolean;
+}
 export interface FileStagingResolution {
     readonly path: string;
     readonly parent: FileStat;
@@ -277,6 +286,11 @@ export interface CreateStagedFileOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface PublishStagedFileOptions extends FsOptions {
+    /** Requires atomicStagedFileMutation and an existing regular destination.
+     * Atomically adopts staged bytes and timestamps while preserving destination
+     * identity, links and mode. Consumes the staged pathname as ordinary publication.
+     * Unsupported hosts must reject before effects, never silently rename. */
+    readonly preserveIdentity?: boolean;
     readonly ancestors?: readonly FileStagingEntry[];
     /** Trusted, mutation-free validation. Must return literal true synchronously;
      * a promise is not acceptance. Requires guardedStagingPublication. */
@@ -337,7 +351,7 @@ export interface FileSystem {
      * The returned guard checks current identities/search access synchronously;
      * preparation is not validation, and the guard's result is not an async lease. */
     prepareDirectoryAncestry?(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution?(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution?(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
@@ -352,6 +366,11 @@ export interface FileSystem {
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry?(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    /** Optional bounded, lazy directory enumeration in backend-defined order.
+     * No complete listing/sort fallback. Consumers must retire the iterator on
+     * early exit. Namespace changes may reject or follow the backend's live view;
+     * this is not a tree snapshot or a retained path-authority grant. */
+    iterateDirectory?(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     /** Atomic final-entry removal; every directory is refused, including raced replacements. */

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

@@ -8,7 +8,7 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlStream, 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";
@@ -17,3 +17,5 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable, type PagedStorageContext } from "./storage.js";

package/dist/safe-fs/core.js

@@ -8,10 +8,12 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlStream, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";
 export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable } from "./storage.js";

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

@@ -7,4 +7,4 @@ export declare function openRetainedResizeFile(filesystem: FileSystem, path: str
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function ownedMutationCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
-export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;
+export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "atomicStagedFileMutation" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;

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

@@ -132,19 +132,19 @@ export function readOnlyCapabilities(capabilities) {
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
         ...inspection, retainedStagingCleanup: false, retainedStagingWrite: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
-        synchronousStagingResolution: false,
+        synchronousStagingResolution: false, synchronousFollowedStagingResolution: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
         randomAccessWrite: false, hardlinks: false, permissions: false, conditionalChmod: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         atomicFilePublication: false, atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
 export function quotaCapabilities(capabilities) {
-    const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
-    const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
+    const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
+    const streamingAppend = requireCapabilities(capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, synchronousFollowedStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -167,6 +167,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
     if (capabilities.atomicFileStaging === true && (capabilities.readOnly === true
         || typeof filesystem.createStagedFile !== "function" || typeof filesystem.publishStagedFile !== "function" || typeof filesystem.removeStagedFile !== "function"))
         (unavailable ??= {}).atomicFileStaging = false;
+    if (capabilities.atomicStagedFileMutation === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).atomicStagedFileMutation = false;
     if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).retainedStagingCleanup = false;
     if (capabilities.retainedStagingWrite === true && (capabilities.retainedStagingCleanup !== true || unavailable?.retainedStagingCleanup === false))
@@ -177,6 +179,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         (unavailable ??= {}).synchronousDirectoryValidation = false;
     if (capabilities.synchronousStagingResolution === true && (capabilities.readOnly === true || typeof filesystem.prepareStagingResolution !== "function"))
         (unavailable ??= {}).synchronousStagingResolution = false;
+    if (capabilities.synchronousFollowedStagingResolution === true && (capabilities.synchronousStagingResolution !== true || unavailable?.synchronousStagingResolution === false))
+        (unavailable ??= {}).synchronousFollowedStagingResolution = false;
     if (capabilities.guardedStagingPublication === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).guardedStagingPublication = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))

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

@@ -1,5 +1,5 @@
 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, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.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, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, 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";
@@ -25,6 +25,7 @@ export declare class DeviceFileSystem implements FileSystem {
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
@@ -42,7 +43,7 @@ export declare class DeviceFileSystem implements FileSystem {
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
     publishStagedFileSet(receipt: FileStaging, destination: string, supplied: PublishStagedFileSetOptions): Promise<FileStat>;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;

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

@@ -13,14 +13,14 @@ import { openFileDescriptor } from "../descriptor.js";
 import { normalizePath } from "../../contracts/virtual-path.js";
 const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
-    synchronousStagingResolution: false,
+    synchronousStagingResolution: false, synchronousFollowedStagingResolution: false,
     readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
     write: true, append: true, exclusiveCreate: true, streamingRead: true, retainedRead: true,
     streamingWrite: true, streamingAppend: true, independentWriteStreams: true, copy: true, exclusiveCopy: true,
     remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
     mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
     permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
-    open: true, retainedStagingCleanup: false, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    open: true, retainedStagingCleanup: false, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
@@ -31,6 +31,7 @@ function globalCapabilities(filesystem) {
         synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
         synchronousStagingResolution: ["prepareStagingResolution"],
         trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
+        atomicStagedFileMutation: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
         atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
         streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
         streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
@@ -178,7 +179,7 @@ export class DeviceFileSystem {
         let selected;
         const traversal = options.stagingResolution === true ? { virtual: false } : undefined;
         try {
-            resolved = await this.#resolve(path, options, options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"), options.create, traversal);
+            resolved = await this.#resolve(path, options, options.stagingResolution === true ? options.followFinalSymlink === true : options.create !== undefined || options.creation !== "exclusive", options.create, traversal);
         }
         catch (error) {
             options.signal?.throwIfAborted();
@@ -209,7 +210,7 @@ export class DeviceFileSystem {
         // This intent cannot bind virtual traversal. Do not infer other path
         // capabilities by resolving the shadowed entry in the backing filesystem.
         if (traversal?.virtual)
-            return Object.freeze({ synchronousStagingResolution: false });
+            return Object.freeze({ synchronousStagingResolution: false, synchronousFollowedStagingResolution: false });
         if (selected === undefined) {
             const query = this.#filesystem.capabilitiesFor;
             options.signal?.throwIfAborted();
@@ -228,6 +229,7 @@ export class DeviceFileSystem {
                     throw new FsError("EAGAIN", { path });
                 if ([resolution.path, ...resolution.traversed.map(entry => entry.path)].some(entry => entry === deviceDirectory || entry.startsWith(`${deviceDirectory}/`))) {
                     (unavailable ??= {}).synchronousStagingResolution = false;
+                    unavailable.synchronousFollowedStagingResolution = false;
                 }
                 runStagingGuard(resolution.validate);
             }
@@ -236,6 +238,7 @@ export class DeviceFileSystem {
                 if (!isFsError(error, "ENOTSUP"))
                     throw error;
                 (unavailable ??= {}).synchronousStagingResolution = false;
+                unavailable.synchronousFollowedStagingResolution = false;
             }
         }
         if (resolved.startsWith(`${deviceDirectory}/`)) {
@@ -243,6 +246,7 @@ export class DeviceFileSystem {
             u.atomicStagingAncestry = false;
             u.synchronousDirectoryValidation = false;
             u.synchronousStagingResolution = false;
+            u.synchronousFollowedStagingResolution = false;
         }
         if (typeof this.#filesystem.open !== "function" && capabilities.open !== false)
             (unavailable ??= {}).open = false;
@@ -490,6 +494,40 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.writeStream(path, source, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { syscall: "iterateDirectory", path });
+        const virtual = resolved === "/" ? "dev" : resolved === deviceDirectory ? "null" : undefined;
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        let seen = false;
+        try {
+            for await (const entry of this.#filesystem.iterateDirectory(virtual ? resolved : path, options)) {
+                options.signal?.throwIfAborted();
+                if (entry.name === "." || entry.name === "..")
+                    continue;
+                if (!entry.name || entry.name.includes("/") || entry.name.includes("\0"))
+                    throw new FsError("EIO", { path, message: "invalid directory entry" });
+                if (entry.name === virtual) {
+                    if (seen)
+                        continue;
+                    seen = true;
+                    yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+                }
+                else
+                    yield { name: entry.name, type: entry.type };
+            }
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!virtual || !isFsError(error, "ENOENT") && !isFsError(error, "ENOTDIR"))
+                throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (virtual && !seen)
+            yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+    }
     readdir(path, options = {}) {
         const fast = this.#tryResolveSync(path, options);
         if (fast !== undefined && fast !== "/") {
@@ -633,6 +671,8 @@ export class DeviceFileSystem {
             await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, staging.directory.path, "atomicFileStaging", options);
         await requireOwnedMutation(this.#filesystem, destination, "atomicFileStaging", options, options.destination === null);
+        if (options.preserveIdentity)
+            await requireOwnedMutation(this.#filesystem, destination, "atomicStagedFileMutation", options);
         if (!this.#filesystem.publishStagedFile)
             throw new FsError("ENOTSUP", { path: destination });
         if (options.commitGuard !== undefined)
@@ -656,8 +696,12 @@ export class DeviceFileSystem {
         const capabilities = await this.#filesystem.capabilitiesFor?.(destination, { ...options, create: options.destination === null }) ?? this.#filesystem.capabilities;
         if (capabilities.readOnly === true)
             throw new FsError("EROFS", { path: destination });
-        for (const path of [staging.parent.path, staging.directory.path])
-            await this.#mutable(path, options, false);
+        // The parent is an identity guard, not an entry being replaced. Root is a
+        // valid parent; the synthetic device directory still cannot own staging.
+        const parentPath = await this.#resolve(staging.parent.path, options, false);
+        if (parentPath === deviceDirectory || parentPath === nullPath)
+            throw new FsError("EBUSY", { path: staging.parent.path });
+        await this.#mutable(staging.directory.path, options, false);
         const guards = [];
         if (options.ancestors)
             guards.push(await this.prepareDirectoryAncestry(options.ancestors, options));
@@ -712,19 +756,19 @@ export class DeviceFileSystem {
         }
     }
     async prepareStagingResolution(path, options = {}) {
-        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        const controls = { ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.followFinalSymlink === true ? { followFinalSymlink: true } : {}) };
         controls.signal?.throwIfAborted();
         if (normalizePath(path) !== path || !path.startsWith("/"))
             throw new FsError("EINVAL", { path });
         try {
             const traversal = { virtual: false };
-            const resolved = await this.#resolve(path, controls, false, undefined, traversal);
+            const resolved = await this.#resolve(path, controls, controls.followFinalSymlink === true, undefined, traversal);
             controls.signal?.throwIfAborted();
             if (traversal.virtual)
                 throw new FsError("ENOTSUP", { path });
             const declared = ownedMutationCapabilities(this.#filesystem, await this.#filesystem.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? this.#filesystem.capabilities);
             controls.signal?.throwIfAborted();
-            if (declared.synchronousStagingResolution !== true || !this.#filesystem.prepareStagingResolution)
+            if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true || !this.#filesystem.prepareStagingResolution)
                 throw new FsError("ENOTSUP", { path });
             const receipt = snapshotStagingResolution(await this.#filesystem.prepareStagingResolution(path, controls));
             controls.signal?.throwIfAborted();

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

@@ -1,6 +1,7 @@
 import type { FileStat, FileSystem } from "../../contracts/filesystem.js";
 /** Internal authority: inspections and stock mutations share one JavaScript turn. */
 export interface MemoryAtomicView {
+    replaceContents(source: string, destination: string): void;
     stat(path: string): FileStat | undefined;
     names(path: string): readonly string[];
 }

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

@@ -1,4 +1,4 @@
-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, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+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, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, 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";
@@ -49,6 +49,9 @@ type OwnedStore = {
     root: DirectoryNode;
     ledger: MemoryLedger;
     capabilities: FileSystem["capabilities"];
+    customCapabilities?: FileSystemCapabilities;
+    identityScope?: symbol;
+    atomicView?: MemoryAtomicView;
     intact: () => boolean;
 };
 export interface ConditionalMutationBinding {
@@ -59,7 +62,6 @@ 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"]>;
     private get identityScope();
     get capabilities(): FileSystemCapabilities;
@@ -114,7 +116,7 @@ export declare class MemoryFileSystem implements FileSystem {
     createStagedFile(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     private retainStagingCleanup;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     private verifyDirectoryAncestry;
     publishStagedFile(receipt: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
     publishStagedFileSet(receipt: FileStaging, destination: string, options: PublishStagedFileSetOptions): Promise<FileStat>;
@@ -132,6 +134,7 @@ export declare class MemoryFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     tryMkdirFastSync(path: string, recursive: boolean, mode: number | undefined): boolean;
     tryRmFastSync(path: string, recursive: boolean, force: boolean): boolean;