@poe-platform/safe-fs 0.1.808 → 0.1.810

package/README.md

@@ -10,6 +10,10 @@ working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
 `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
 
@@ -133,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

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

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

package/dist/safe-fs/core.js

@@ -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 * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.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,11 +132,11 @@ 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,
     });
 }
@@ -144,7 +144,7 @@ export function quotaCapabilities(capabilities) {
     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";
@@ -43,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;
@@ -667,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)
@@ -750,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/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";
@@ -116,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>;

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

@@ -584,8 +584,8 @@ const SHARED_STOCK_MEMORY_CAPABILITIES = Object.freeze({
     permissions: true,
     timestamps: true,
     atomicRename: true,
-    atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
-    synchronousDirectoryValidation: true, synchronousStagingResolution: true, guardedStagingPublication: true,
+    atomicStagedFileMutation: true, atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
+    synchronousDirectoryValidation: true, synchronousStagingResolution: true, synchronousFollowedStagingResolution: true, guardedStagingPublication: true,
     atomicDirectoryMetadata: true,
     streamingRead: true,
     retainedRead: true,
@@ -2186,13 +2186,14 @@ export class MemoryFileSystem {
         return () => this.verifyDirectoryAncestry(entries, controls);
     }
     async prepareStagingResolution(path, options = {}) {
+        const followFinal = options.followFinalSymlink === true;
         const controls = options.signal === undefined ? {} : { signal: options.signal };
         controls.signal?.throwIfAborted();
         this.validatePath(path, "prepareStagingResolution");
         if (!path.startsWith("/") || normalizePath(path) !== path)
             this.fail("EINVAL", "prepareStagingResolution", path);
         const traversed = [];
-        const location = this.resolve(path, "prepareStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: traversed });
+        const location = this.resolve(path, "prepareStagingResolution", { followFinal, allowMissing: true, resolutionSteps: traversed });
         if (location.node && location.node.type !== "file")
             this.fail("ENOTSUP", "prepareStagingResolution", path);
         const parentPath = location.path.slice(0, location.path.lastIndexOf("/")) || "/";
@@ -2207,7 +2208,7 @@ export class MemoryFileSystem {
             const currentSteps = [];
             let current;
             try {
-                current = this.resolve(path, "verifyStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: currentSteps });
+                current = this.resolve(path, "verifyStagingResolution", { followFinal, allowMissing: true, resolutionSteps: currentSteps });
             }
             catch (error) {
                 if (error instanceof FsError && ["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code))
@@ -2245,6 +2246,7 @@ export class MemoryFileSystem {
     }
     async publishStagedFile(receipt, destination, options) {
         const signal = options.signal;
+        const preserveIdentity = options.preserveIdentity === true;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
         const snapshot = (entry) => ({ path: entry.path, stat: { ...entry.stat } });
@@ -2272,9 +2274,48 @@ export class MemoryFileSystem {
             this.fail("EINVAL", "publishStagedFile", destination);
         if (target.node && target.node.type !== "file")
             this.fail("EAGAIN", "publishStagedFile", destination);
+        if (preserveIdentity) {
+            if (this.capabilities.atomicStagedFileMutation !== true)
+                this.fail("ENOTSUP", "publishStagedFile", destination);
+            if (file.node?.type !== "file" || target.node?.type !== "file" || expected === null)
+                this.fail("EINVAL", "publishStagedFile", destination);
+            this.permission(file.parent, 3, "publishStagedFile", staging.file.path);
+            this.permission(target.parent, 3, "publishStagedFile", destination);
+            this.permission(target.node, 2, "publishStagedFile", destination);
+            // Provider-owned storage is copied directly, without assembling an archive
+            // in caller memory. Preserve retained staging readers and independent writes.
+            this.admitSize(target.node, file.node.byteLength, "publishStagedFile", destination);
+            const allocation = this.allocate(file.node.byteLength, "publishStagedFile", destination);
+            try {
+                for (let offset = 0; offset < file.node.byteLength; offset += 65536) {
+                    allocation.data.set(file.node.data.subarray(offset, offset + 65536), offset);
+                }
+            }
+            catch (error) {
+                allocation.release();
+                throw error;
+            }
+            // No awaits or overridable operations occur between admission and commit.
+            const now = Date.now();
+            this.replaceData(target.node, allocation);
+            this.changed(target.node, now);
+            target.node.atimeMs = file.node.atimeMs;
+            target.node.mtimeMs = file.node.mtimeMs;
+            file.parent.entries.delete(file.name);
+            this.ledger.release(file.name.length * 2, 1);
+            file.node.nlink--;
+            file.node.ctimeMs = now;
+            file.node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, file.node.revision + 1);
+            this.releaseNode(file.node);
+            this.changed(file.parent, now);
+            memoryCaches.get(this.ledger).clearWrites();
+            return;
+        }
         return MemoryFileSystem.prototype.rename.call(this, staging.file.path, destination, { ...controls, noReplace: expected === null });
     }
     async publishStagedFileSet(receipt, destination, options) {
+        if (options.preserveIdentity)
+            this.fail("ENOTSUP", "publishStagedFileSet", destination);
         const signal = options.signal;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);

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

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, 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, ChmodOptions, 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 { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export interface MountFileSystemOptions {
@@ -18,7 +18,7 @@ export declare class MountFileSystem implements FileSystem {
     private supportsStagingAncestry;
     private supportsDirectoryValidation;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     private prepareAncestry;
     private protected;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;

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

@@ -109,6 +109,7 @@ export class MountFileSystem {
                 retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 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"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
@@ -128,7 +129,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt",
+            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt", "atomicStagedFileMutation",
             "trustedOwnedStaging", "atomicFilePublication", "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
@@ -190,7 +191,8 @@ export class MountFileSystem {
                 fail("EINVAL");
             const location = await this.resolve(path, options, {
                 allowMissing: options.create ?? true,
-                followFinal: options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"),
+                retainedResolution: options.stagingResolution === true && options.followFinalSymlink === true,
+                followFinal: options.stagingResolution === true ? options.followFinalSymlink === true : options.create !== undefined || options.creation !== "exclusive",
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
             const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
@@ -211,15 +213,15 @@ export class MountFileSystem {
                     const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
                     const declared = input === location.local ? resize : ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(input, options) ?? location.mount.backend.capabilities);
                     options.signal?.throwIfAborted();
-                    resolution = declared.synchronousStagingResolution === true && await this.supportsStagingAncestry(location, resize, options);
+                    resolution = declared.synchronousStagingResolution === true && (options.followFinalSymlink !== true || declared.synchronousFollowedStagingResolution === true) && await this.supportsStagingAncestry(location, resize, options);
                 }
             }
             const conditionalChmod = options.conditionalChmod === true
                 ? resize.conditionalChmod === true && typeof location.mount.backend.chmod === "function"
                     && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
                 : this.capabilities.conditionalChmod;
-            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
-            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, synchronousFollowedStagingResolution: ignoredFollowedResolution, ...ordinary } = resize;
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution, ...(options.followFinalSymlink === true ? { synchronousFollowedStagingResolution: resolution } : {}) }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -263,19 +265,19 @@ export class MountFileSystem {
         return this.operation("prepareDirectoryAncestry", ancestors.at(-1)?.path ?? "/", options, () => this.prepareAncestry(ancestors, options));
     }
     prepareStagingResolution(path, options = {}) {
-        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        const controls = { ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.followFinalSymlink === true ? { followFinalSymlink: true } : {}) };
         return this.operation("prepareStagingResolution", path, controls, async () => {
             if (normalizePath(globalPath(path)) !== path)
                 fail("EINVAL");
             const observed = [];
-            const location = await this.resolve(path, controls, { followFinal: false, allowMissing: true, resolutionSteps: observed });
+            const location = await this.resolve(path, controls, { followFinal: controls.followFinalSymlink === true, retainedResolution: controls.followFinalSymlink === true, allowMissing: true, resolutionSteps: observed });
             if (location.synthetic || !within(location.mount.path, path))
                 fail("ENOTSUP");
             const backend = location.mount.backend;
             const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
             const declared = ownedMutationCapabilities(backend, await backend.capabilitiesFor?.(input, { ...controls, stagingResolution: true }) ?? backend.capabilities);
             controls.signal?.throwIfAborted();
-            if (declared.synchronousStagingResolution !== true || !backend.prepareStagingResolution)
+            if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true || !backend.prepareStagingResolution)
                 fail("ENOTSUP");
             const prefix = directoryAncestryPaths(location.mount.path).map(ancestor => {
                 const entry = observed.find(step => step.path === ancestor);
@@ -545,6 +547,10 @@ export class MountFileSystem {
         let followedFinalLink = false;
         const verified = async (location) => {
             let inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            // A guarded resolution binds the original link chain and missing target
+            // through the authoritative backend receipt; realpath cannot name absence.
+            if (settings.retainedResolution && !location.stat && followedFinalLink)
+                inspection = undefined;
             // A missing entry has no realpath. Verify its existing parent while
             // leaving dangling final symlinks on the ordinary following path.
             if (inspection && !location.stat && settings.allowMissing && !followedFinalLink && inspection.finalName === undefined) {
@@ -1096,6 +1102,8 @@ export class MountFileSystem {
             await requireOwnedMutation(local.mount.backend, target.local, "atomicFileStaging", options, options.destination === null);
             if (!local.mount.backend.publishStagedFile)
                 fail("ENOTSUP");
+            if (options.preserveIdentity)
+                await requireOwnedMutation(local.mount.backend, target.local, "atomicStagedFileMutation", options);
             if (ancestors || callerGuard !== undefined)
                 await requireOwnedMutation(local.mount.backend, target.local, "guardedStagingPublication", options, options.destination === null);
             if (!ancestors) {

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

@@ -43,6 +43,7 @@ export declare class OverlayFileSystem implements FileSystem {
     private bytes;
     private cleanGarbage;
     cleanup(options?: FsOptions): Promise<void>;
+    private stagingOptions;
     private staged;
     private preserve;
     private clone;

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

@@ -554,7 +554,12 @@ export class OverlayFileSystem {
     async cleanup(options = {}) {
         return this.run(options, () => this.cleanGarbage(true));
     }
+    // Receipts describe overlay paths and identities, never backing-layer staging paths.
+    stagingOptions({ signal }) {
+        return signal === undefined ? {} : { signal };
+    }
     async staged(options, operation) {
+        options = this.stagingOptions(options);
         const root = `/.virtual-bash-overlay-${platform.randomUUID()}`;
         if (await this.maybeStat(this.#upper, root, options) || await this.maybeStat(this.#lower, root, options))
             fail("EEXIST", root);
@@ -570,6 +575,7 @@ export class OverlayFileSystem {
         }
     }
     async preserve(path, stat, options) {
+        options = this.stagingOptions(options);
         if (this.#upper.chmod)
             await this.#upper.chmod(path, stat.mode & 0o7777, options);
         else if (((await this.#upper.lstat(path, options)).mode & 0o7777) !== (stat.mode & 0o7777))
@@ -579,6 +585,7 @@ export class OverlayFileSystem {
         await this.#upper.utimes(path, stat.atimeMs, stat.mtimeMs, options);
     }
     async clone(entry, destination, options) {
+        options = this.stagingOptions(options);
         if (entry.stat.type !== "directory" && ((entry.stat.nlink ?? 1) > 1
             || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined))) {
             fail("ENOTSUP", entry.path, "copy-up cannot preserve hardlink identity");
@@ -608,6 +615,7 @@ export class OverlayFileSystem {
         }
     }
     async ensureDirectory(path, options) {
+        options = this.stagingOptions(options);
         const entry = await this.lookup(path, options);
         if (!entry)
             fail("ENOENT", path);
@@ -618,6 +626,7 @@ export class OverlayFileSystem {
         await this.copyUp(entry, options);
     }
     async copyUp(entry, options) {
+        options = this.stagingOptions(options);
         if (entry.backend === this.#upper)
             return;
         if (entry.path === "/")
@@ -640,6 +649,7 @@ export class OverlayFileSystem {
         });
     }
     async parent(path, options) {
+        options = this.stagingOptions(options);
         const parent = await this.lookup(dirname(path), options);
         if (!parent)
             fail("ENOENT", dirname(path));

package/dist/safe-fs/fs/overlay/memory-publication.js

@@ -376,6 +376,24 @@ export class OverlayMemoryPublication {
         const owned = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
         const staging = Object.freeze({
             parent: owned.parent, directory: owned.directory, file: owned.file,
+            ...(owned.writer ? { writer: Object.freeze({
+                    write: async (bytes, controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        await owned.writer.write(bytes, controls);
+                    },
+                    finish: async (controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        const stat = await owned.writer.finish(controls);
+                        this.stages.set(staging.directory, { ...owned, file: { ...owned.file, stat } });
+                        return stat;
+                    },
+                }) } : {}),
             ...(owned.cleanup ? { cleanup: createStagingCleanup(directory, controls => this.cleanup(staging, controls, true), () => owned.cleanup.close()) } : {}),
         });
         this.stages.set(staging.directory, owned);
@@ -384,6 +402,8 @@ export class OverlayMemoryPublication {
         return staging;
     }
     async publish(staging, path, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path });
         options.signal?.throwIfAborted();
         this.path(path);
         const owned = this.stages.get(staging.directory);

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

@@ -413,6 +413,8 @@ export class RealFileSystem {
             throw new FsError("EAGAIN");
     }
     async publishStagedFile(staging, destination, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path: destination });
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
             options.signal?.throwIfAborted();
             if (options.ancestors !== undefined || options.commitGuard !== undefined)

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

@@ -343,6 +343,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             if (property === "publishStagedFile") {
                                 const publishOptions = (options ?? {});
                                 await requireOwnedMutation(original, args[1], "atomicFileStaging", publishOptions, publishOptions.destination === null);
+                                if (publishOptions.preserveIdentity)
+                                    await requireOwnedMutation(original, args[1], "atomicStagedFileMutation", publishOptions);
                                 const query = options.destination === null ? { ...options, create: true } : options;
                                 const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(args[1], query) ?? original.capabilities);
                                 assertReady();
@@ -457,7 +459,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     try {
                         const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? original.capabilities);
                         controls.signal?.throwIfAborted();
-                        if (declared.synchronousStagingResolution !== true)
+                        if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true)
                             throw new FsError("ENOTSUP", { path });
                         const resolution = snapshotStagingResolution(await Reflect.apply(method, original, [path, controls]));
                         controls.signal?.throwIfAborted();

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

@@ -39,11 +39,19 @@ export declare class IntegerTable {
     private readonly storage;
     private readonly maxEntries;
     private root;
+    private revision;
+    private readonly branches;
     private readonly cache;
-    constructor(storage: PagedStorage, maxEntries?: number);
+    constructor(storage: Pick<PagedStorage, "allocate" | "read" | "write">, maxEntries?: number);
     private retain;
     get(key: bigint): Promise<bigint | undefined>;
     set(key: bigint, value: bigint): Promise<void>;
+    /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
+     * owned node bytes) and 128 output records. Batches avoid alternating sparse
+     * index reads with consumer writes on every record. Mutation is not permitted. */
+    entries(start?: bigint, end?: bigint): AsyncGenerator<readonly [bigint, bigint]>;
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    private branch;
     private lookup;
     private persist;
 }

package/dist/safe-fs/storage.js

@@ -103,14 +103,20 @@ export class PagedStorage {
             this.pages.set(number, cached);
             return cached;
         }
+        let reusable;
         if (this.pages.size === this.maxPages) {
             if (!this.descriptor)
                 await this.spill();
             const [oldNumber, oldPage] = this.pages.entries().next().value;
             await this.flush(oldNumber, oldPage);
             this.pages.delete(oldNumber);
+            reusable = oldPage;
         }
-        const page = { bytes: new Uint8Array(pageBytes), dirty: false };
+        // Flush owns the bytes until its awaited write completes. Reuse only then;
+        // zero new/unwritten ranges so the previous page cannot leak into them.
+        const page = reusable ?? { bytes: new Uint8Array(pageBytes), dirty: false };
+        if (reusable)
+            page.bytes.fill(0);
         if (number * pageBytes < this.diskLength) {
             let offset = 0;
             while (offset < pageBytes) {
@@ -192,6 +198,8 @@ export class IntegerTable {
     storage;
     maxEntries;
     root = 0;
+    revision = 0;
+    branches = new Map();
     cache = new Map();
     constructor(storage, maxEntries = 4096) {
         this.storage = storage;
@@ -202,8 +210,14 @@ export class IntegerTable {
     async retain(key, value, dirty) {
         if (this.cache.size === this.maxEntries && !this.cache.has(key)) {
             const [oldKey, old] = this.cache.entries().next().value;
+            // Flush the bounded dirty window together, before the caller touches other
+            // stored data. One dirty leaf per insertion otherwise thrashes a page cache.
             if (old.dirty)
-                await this.persist(oldKey, old.value);
+                for (const [key, entry] of this.cache)
+                    if (entry.dirty) {
+                        await this.persist(key, entry.value);
+                        entry.dirty = false;
+                    }
             this.cache.delete(oldKey);
         }
         this.cache.delete(key);
@@ -224,19 +238,98 @@ export class IntegerTable {
     async set(key, value) {
         if (key < 0n || key > 0xffffffffffffffffn || value < 0n || value >= 0xffffffffffffffffn)
             throw new RangeError("Invalid storage integer table value");
+        this.revision++;
         await this.retain(key, value, true);
     }
+    /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
+     * owned node bytes) and 128 output records. Batches avoid alternating sparse
+     * index reads with consumer writes on every record. Mutation is not permitted. */
+    async *entries(start = 0n, end = 0x10000000000000000n) {
+        if (start < 0n || start > end || end > 0x10000000000000000n)
+            throw new RangeError("Invalid integer table range");
+        if (start === end)
+            return;
+        const revision = this.revision;
+        const check = () => { if (revision !== this.revision)
+            throw new Error("Integer table changed during iteration"); };
+        for (const [key, entry] of this.cache)
+            if (entry.dirty) {
+                check();
+                await this.persist(key, entry.value);
+                check();
+                entry.dirty = false;
+            }
+        const storage = this.storage;
+        async function* visit(position, shift, prefix) {
+            check();
+            if (!position)
+                return;
+            const bytes = new Uint8Array(await storage.read(position, 128));
+            check();
+            if (bytes.length !== 128)
+                throw new RangeError("Truncated integer table node");
+            const node = new DataView(bytes.buffer);
+            for (let slot = 0; slot < 16; slot++) {
+                check();
+                const value = node.getBigUint64(slot * 8, true);
+                if (!value)
+                    continue;
+                const key = prefix | BigInt(slot) << shift;
+                if (key >= end || key + (1n << shift) <= start)
+                    continue;
+                if (shift === 0n)
+                    yield [key, value - 1n];
+                else
+                    yield* visit(Number(value), shift - 4n, key);
+            }
+        }
+        const batch = [];
+        for await (const entry of visit(this.root, 60n, 0n)) {
+            batch.push(entry);
+            if (batch.length === 128) {
+                for (const entry of batch) {
+                    check();
+                    yield entry;
+                }
+                batch.length = 0;
+            }
+        }
+        for (const entry of batch) {
+            check();
+            yield entry;
+        }
+        check();
+    }
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    branch(key, shift, position) {
+        const prefix = key >> shift | 1n << (64n - shift);
+        const value = position ?? this.branches.get(prefix);
+        if (value !== undefined) {
+            this.branches.delete(prefix);
+            this.branches.set(prefix, value);
+            if (this.branches.size > 128)
+                this.branches.delete(this.branches.keys().next().value);
+        }
+        return value;
+    }
     async lookup(key) {
         let node = this.root;
         for (let shift = 60n; shift >= 0n; shift -= 4n) {
             if (!node)
                 return undefined;
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
             const slot = node + Number((key >> shift) & 15n) * 8;
             const bytes = await this.storage.read(slot, 8);
             const value = new DataView(bytes.buffer, bytes.byteOffset, 8).getBigUint64(0, true);
             if (shift === 0n)
                 return value === 0n ? undefined : value - 1n;
             node = Number(value);
+            if (node)
+                this.branch(key, shift, node);
         }
         return undefined;
     }
@@ -245,6 +338,11 @@ export class IntegerTable {
             this.root = this.storage.allocate(128);
         let node = this.root;
         for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
             const slot = node + Number((key >> shift) & 15n) * 8;
             const bytes = await this.storage.read(slot, 8);
             const view = new DataView(bytes.buffer, bytes.byteOffset, 8);
@@ -260,6 +358,7 @@ export class IntegerTable {
                 await this.storage.write(slot, bytes);
             }
             node = child;
+            this.branch(key, shift, child);
         }
     }
 }

package/dist/xml-ast/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class XmlLimitError extends SyntaxError {
+    readonly limit: string;
+    constructor(limit: string, message: string);
+}

package/dist/xml-ast/errors.js

@@ -0,0 +1,7 @@
+export class XmlLimitError extends SyntaxError {
+    limit;
+    constructor(limit, message) {
+        super(message);
+        this.limit = limit;
+    }
+}

package/dist/xml-ast/index.d.ts

@@ -1,3 +1,4 @@
+export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
     readonly namespace: string;
@@ -39,9 +40,6 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare class XmlLimitError extends SyntaxError {
-    readonly limit: string;
-    constructor(limit: string, message: string);
-}
 export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
+export { parseXmlStream, type XmlStreamLimits, type XmlStreamEvent } from "./stream.js";

package/dist/xml-ast/index.js

@@ -1,10 +1,5 @@
-export class XmlLimitError extends SyntaxError {
-    limit;
-    constructor(limit, message) {
-        super(message);
-        this.limit = limit;
-    }
-}
+import { XmlLimitError } from "./errors.js";
+export { XmlLimitError } from "./errors.js";
 function* find(source, needle, start) {
     const found = source.indexOf(needle, start);
     const end = found < 0 ? source.length : found;
@@ -633,3 +628,4 @@ export function parseXml(input, limits = {}) {
         result = parser.next();
     return result.value;
 }
+export { parseXmlStream } from "./stream.js";

package/dist/xml-ast/stream.d.ts

@@ -0,0 +1,31 @@
+import type { XmlContent, XmlElement, XmlLimits, XmlName } from "./index.js";
+export type XmlStreamEvent = {
+    readonly type: "open" | "close";
+    readonly element: XmlElement;
+    readonly parent: XmlElement | undefined;
+} | {
+    readonly type: "content";
+    readonly content: Exclude<XmlContent, XmlElement>;
+    readonly parent: XmlElement | undefined;
+};
+export interface XmlStreamLimits extends XmlLimits {
+    /** Validate the full document but return only its root name, without a retained tree. */
+    readonly retainTree?: boolean;
+    /** Ordered node events, awaited after each parser window. Requires retainTree:
+     * false; elements carry metadata without child/content arrays. Individual XML
+     * tokens remain resident until the underlying parser completes them. */
+    readonly events?: (event: XmlStreamEvent) => void | Promise<void>;
+    /** Detach selected non-root subtrees and await their consumer before parsing
+     * the next 512-unit window. By default nested matches belong to the selected ancestor. */
+    readonly streamElements?: {
+        /** Also detach preceding sibling content when selecting a subtree, before
+         * the parser advances. The final trailing content remains in the parent. */
+        readonly captureBefore?: boolean;
+        /** Detach nested matches too, consuming descendants before their ancestors. */
+        readonly includeNested?: boolean;
+        readonly matches: (element: XmlName, parent: XmlName | undefined, depth: number) => boolean;
+        readonly consume: (element: XmlElement, parent: XmlElement, before?: readonly XmlContent[]) => void | Promise<void>;
+    };
+}
+/** Incremental source consumption. Individual XML tokens and optional trees remain resident. */
+export declare function parseXmlStream(source: AsyncIterable<string> | Iterable<string>, limits?: XmlStreamLimits, checkpoint?: (units: number) => void | Promise<void>): Promise<XmlElement>;

package/dist/xml-ast/stream.js

@@ -0,0 +1,179 @@
+import { SaxesParser } from "saxes/saxes.js";
+import { XmlLimitError } from "./errors.js";
+/** Incremental source consumption. Individual XML tokens and optional trees remain resident. */
+export async function parseXmlStream(source, limits = {}, checkpoint) {
+    if (limits.recover)
+        throw new TypeError("XML stream recovery is unsupported; use parseXmlSteps");
+    for (const key of ["maxDepth", "maxNodes", "maxAttributes", "maxAttributesPerElement", "maxNamespaces", "maxContentNodes", "maxTextLength"]) {
+        const value = limits[key];
+        if (value !== undefined && value !== Infinity && (!Number.isSafeInteger(value) || value < 1))
+            throw new RangeError("XML limits must be positive integers");
+    }
+    const counters = { maxNodes: 0, maxAttributes: 0, maxContentNodes: 0, maxTextLength: 0 };
+    function bound(key, value) {
+        if (value > (limits[key] ?? Infinity))
+            throw new XmlLimitError(key, "XML resource limit exceeded");
+    }
+    function charge(key, value = 1) { counters[key] += value; bound(key, counters[key]); }
+    const retainContent = limits.retainContent !== false, tree = limits.retainTree !== false, retain = tree && retainContent;
+    const events = limits.events;
+    if (events && tree)
+        throw new TypeError("XML events require retainTree: false");
+    const describe = retain || !!events;
+    const queued = [];
+    const streaming = limits.streamElements;
+    if (streaming && !retain)
+        throw new TypeError("XML subtree streaming requires retained content and tree mode");
+    let selectedCount = 0;
+    const completed = [];
+    const stack = [];
+    const prolog = [], epilog = [];
+    const emptyNamespaces = new Map();
+    let root, declaration;
+    const parser = new SaxesParser({ xmlns: true, defaultXMLVersion: "1.0", forceXMLVersion: true });
+    parser.on("error", error => { throw new SyntaxError(`Invalid XML: ${error.message}`); });
+    parser.on("doctype", () => { throw new SyntaxError("Invalid XML: DTD and entity declarations are forbidden"); });
+    let prefix = "", capturing = describe;
+    parser.on("xmldecl", value => {
+        const encoding = value.encoding?.toUpperCase();
+        if (value.version !== "1.0" || encoding !== undefined &&
+            (!["UTF-8", "UTF-16", "UTF-16LE", "UTF-16BE"].includes(encoding) ||
+                limits.expectedEncoding !== undefined && encoding !== limits.expectedEncoding &&
+                    !(encoding === "UTF-16" && ["UTF-16LE", "UTF-16BE"].includes(limits.expectedEncoding))))
+            throw new SyntaxError("Invalid XML: unsupported XML declaration");
+        if (describe)
+            declaration = prefix.slice(0, prefix.indexOf("?>") + 2);
+        prefix = "";
+        capturing = false;
+    });
+    parser.on("opentag", tag => {
+        charge("maxNodes");
+        bound("maxDepth", stack.length + 1);
+        const attrs = Object.values(tag.attributes);
+        charge("maxAttributes", attrs.length);
+        bound("maxAttributesPerElement", attrs.length);
+        const parent = stack.at(-1);
+        let namespaces = parent?.namespaces ?? new Map([["xml", "http://www.w3.org/XML/1998/namespace"]]);
+        const bindings = Object.entries(tag.ns);
+        if (bindings.length) {
+            namespaces = new Map(namespaces);
+            for (const [name, uri] of bindings)
+                namespaces.set(name, uri);
+            bound("maxNamespaces", namespaces.size);
+        }
+        for (const attr of attrs)
+            charge("maxTextLength", attr.value.length);
+        const name = { name: tag.name, namespace: tag.uri, localName: tag.local };
+        limits.onElement?.(name, parent?.element, stack.length + 1);
+        const selected = (!selectedCount || streaming?.includeNested === true) && !!streaming?.matches(name, parent?.element, stack.length + 1);
+        if (selected && !parent)
+            throw new TypeError("XML subtree streaming cannot select the root");
+        let before = [];
+        if (selected) {
+            selectedCount++;
+            if (streaming?.captureBefore) {
+                before = parent.element.content.splice(0);
+                parent.element.children.length = 0;
+                parent.element.text = '';
+            }
+        }
+        charge("maxContentNodes", 1 + (retainContent || events ? attrs.length : 0));
+        const element = { kind: "element", ...name, children: [], content: [], text: "",
+            attributes: describe ? attrs.map(attr => ({ name: attr.name, localName: attr.local, namespace: attr.uri, value: attr.value })) : [],
+            namespaces: describe ? namespaces : emptyNamespaces,
+            ...(!root && describe ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
+        if (parent && tree && !selected) {
+            parent.element.children.push(element);
+            if (retain)
+                parent.element.content.push(element);
+        }
+        else if (!parent)
+            root = element;
+        stack.push({ element, namespaces, selected, before });
+        if (events)
+            queued.push({ type: "open", element, parent: parent?.element });
+    });
+    parser.on("closetag", () => {
+        const frame = stack.pop();
+        if (events)
+            queued.push({ type: "close", element: frame.element, parent: stack.at(-1)?.element });
+        if (frame.selected) {
+            completed.push({ element: frame.element, parent: stack.at(-1).element, before: frame.before });
+            selectedCount--;
+        }
+    });
+    async function drain() {
+        for (const entry of completed) {
+            await checkpoint?.(0);
+            await streaming.consume(entry.element, entry.parent, entry.before);
+        }
+        completed.length = 0;
+        for (const event of queued) {
+            await checkpoint?.(0);
+            await events(event);
+        }
+        queued.length = 0;
+    }
+    function append(content) {
+        charge("maxTextLength", content.text.length);
+        charge("maxContentNodes");
+        const parent = stack.at(-1)?.element;
+        if (events)
+            queued.push({ type: "content", content, parent });
+        if (tree && parent && (content.kind === "text" || content.kind === "cdata"))
+            parent.text += content.text;
+        if (retain)
+            (parent ? parent.content : root ? epilog : prolog).push(content);
+    }
+    parser.on("text", text => { if (text.length)
+        append({ kind: "text", text }); });
+    parser.on("cdata", text => append({ kind: "cdata", text }));
+    parser.on("comment", text => append({ kind: "comment", text }));
+    parser.on("processinginstruction", value => append({ kind: "processing-instruction", target: value.target, text: value.body }));
+    let cr = false, first = true;
+    function write(text) {
+        if (!text)
+            return;
+        if (first) {
+            first = false;
+            if (text.charCodeAt(0) === 0xfeff) {
+                parser.write(text[0]);
+                text = text.slice(1);
+            }
+        }
+        if (cr) {
+            if (text.startsWith("\n"))
+                text = text.slice(1);
+            cr = false;
+        }
+        cr = text.endsWith("\r");
+        text = text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+        if (capturing) {
+            prefix += text;
+            if (prefix.length >= 6 && !(prefix.startsWith("<?xml") && " \t\n".includes(prefix[5]))) {
+                prefix = "";
+                capturing = false;
+            }
+        }
+        parser.write(text);
+    }
+    await checkpoint?.(0);
+    for await (const text of source) {
+        if (typeof text !== "string")
+            throw new TypeError("XML producer must yield strings");
+        for (let i = 0; i < text.length; i += 512) {
+            await checkpoint?.(0);
+            write(text.slice(i, i + 512));
+            if (completed.length || queued.length)
+                await drain();
+            await checkpoint?.(Math.min(512, text.length - i));
+        }
+    }
+    await checkpoint?.(0);
+    parser.close();
+    if (completed.length || queued.length)
+        await drain();
+    if (!root)
+        throw new SyntaxError("Invalid XML: incomplete document");
+    return root;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.808",
+  "version": "0.1.810",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -148,6 +148,7 @@
     "access": "public"
   },
   "dependencies": {
+    "saxes": "^6.0.0",
     "@types/node": "^25.2.2",
     "@noble/hashes": "2.4.0"
   },