@poe-platform/safe-fs 0.1.804 → 0.1.806

package/README.md

@@ -35,7 +35,7 @@ rename nor inode/version identity from placeholder native metadata. Retained
 reads remain available, with native seek reporting `ENOTSUP`. Ordinary browser
 bundles cannot import this backend. Node keeps its POSIX host profile.
 
-For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Unzip extraction requires atomic ancestry verification, currently supported by MemoryFileSystem; the real adapter and mount views refuse it. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
+For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Archive extraction requires atomic ancestry verification. MemoryFileSystem supports it, including a writable root composed with read-only mounts such as `/skills/.system`; the real adapter refuses it. Mount extraction delegates confinement to the root backend and keeps other mounts read-only in the extraction view. Extraction roots inside a separate mount are rejected because directory and metadata mutations cannot atomically guard ancestors on another backend. Staged file publication supports nested writable mounts when every ancestor provides authoritative validation. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
 
 To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression commands, host adapters need atomic no-replace publication. Supply `createRealFileSystem({ root, renameNoReplace })` only when that callback binds a qualified native primitive such as Linux `renameat2` with `RENAME_NOREPLACE`. It receives resolved absolute host paths and an optional signal in its third argument. Existing destinations must reject `EEXIST` atomically; existence checks followed by rename and copy/delete are insufficient. Without this binding the adapter explicitly refuses those operations. See the [no-replace contract](src/contracts/filesystem.md#atomic-no-replace-rename).
 
@@ -148,7 +148,7 @@ Omit `maxOperations` or pass `Infinity` for unlimited cleanup operations.
 | `createOverlayFileSystem({ upper, lower })` | Reading through to a lower layer and writing changes to an upper layer |
 | `withFileSystemQuota(filesystem, { maxBytes })` | Enforcing a cumulative logical-byte ceiling across every write path |
 
-`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. A trusted `reserveReadFile` callback can reserve host resources and return a release function; cancellation retains the reservation until the backend read settles. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
+`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. A trusted `reserveReadFile` callback can reserve host resources and return a release function; cancellation retains the reservation until the backend read settles. The portable `createFsBridge` from `@poe-platform/safe-fs/bridge` instead requires a caller-supplied text codec and returns `Uint8Array` values.
 
 ## Write an adapter
 
@@ -253,7 +253,7 @@ console.log(new TextDecoder().decode(await catalog.readFile("/welcome.txt")));
 
 Output: `Hello from the catalog`. `readFile` returns a copy so callers cannot mutate the stored snapshot. Reads check cancellation and `maxBytes`; required mutations always reject with `EROFS`. `stat` and `lstat` share an implementation because this adapter has no symlinks.
 
-`createFileSystem` validates options before calling the factory. The Node registry includes `memory` and `real`, accepts new names, and rejects attempts to replace those defaults. For an explicit allowlist without either default, pass `new Map([["catalog", catalogAdapter]])` directly as `registry`. Names select registered factories; they do not load modules from config.
+`createFileSystem` validates options before calling the factory. For Workers, import `createPortableFileSystemAdapterRegistry` and `createFileSystem` from `@poe-code/safe-fs/core`; the portable registry includes `memory` and caller-supplied adapters, without ambient filesystem access. The Node registry includes `memory` and `real`, accepts new names, and rejects attempts to replace those defaults. For an explicit allowlist without either default, pass `new Map([["catalog", catalogAdapter]])` directly as `registry`. Names select registered factories; they do not load modules from config.
 
 For a mutable backend, preserve exclusive-create behavior, return independent byte buffers, handle cancellation and size limits, and declare only capabilities you actually provide. Use `FsError` for filesystem failures. Do not invent entry identity from matching paths or metadata; omit `compareEntry` when identity is unknown.
 
@@ -357,8 +357,8 @@ Each batch lists from the beginning because previous keys have been deleted; it
 | `addressingStyle` | `path`; alternative `virtual-hosted` requires a DNS endpoint |
 | `listUrlEncoding` | `percent`; alternative `form` |
 | `allowInsecureHttp` | `false`; HTTPS required unless explicitly enabled |
-| `maxPutBytes`, `maxGetBytes` | Unlimited unless configured |
-| `maxXmlBytes` | Unlimited unless configured |
+| `maxPutBytes`, `maxGetBytes` | Unlimited when omitted or `Infinity`; positive safe integers set byte caps |
+| `maxXmlBytes` | Unlimited when omitted or `Infinity`; positive safe integers set a byte cap |
 | `requestTimeoutMs` | Unlimited unless configured |
 | `enableCopy` | `true`; disabling uses a buffered GET/PUT fallback |
 | `verifiedConditionalOperations` | Optional `put`, `copy`, `delete` booleans, each defaulting to false; enable only after verifying the server's semantics |

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

@@ -12,6 +12,7 @@ type DirectoryOptions = {
 };
 export declare class FileSystemBridge<Binary extends Uint8Array> {
     #private;
+    static getProvider(bridge: object): FileSystem | undefined;
     constructor(fs: FileSystem, options: {
         readonly cwd?: string;
         readonly root?: string;

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

@@ -40,6 +40,9 @@ function timeValue(value) {
     return number;
 }
 export class FileSystemBridge {
+    static getProvider(bridge) {
+        return #fs in bridge ? bridge.#fs : undefined;
+    }
     #fs;
     #cwd;
     #root;

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

@@ -4,3 +4,4 @@ import type { FsBridgeOptions } from "./types.js";
 export type { FsBridgeCodec, FsBridgeDirent, FsBridgeEncoding, FsBridgeFileSystem, FsBridgeOptions, FsBridgeStats } from "./types.js";
 export type FsBridge = FileSystemBridge<Uint8Array<ArrayBuffer>>;
 export declare function createFsBridge(fs: FileSystem, options: FsBridgeOptions): FsBridge;
+export declare const getFsBridgeProvider: typeof FileSystemBridge.getProvider;

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

@@ -16,3 +16,4 @@ export function createFsBridge(fs, options) {
         }
     });
 }
+export const getFsBridgeProvider = FileSystemBridge.getProvider;

package/dist/safe-fs/config/registry.d.ts

@@ -0,0 +1,2 @@
+import type { FileSystemAdapterRegistry } from "../config.js";
+export declare function extendAdapterRegistry(defaults: FileSystemAdapterRegistry, extensions?: FileSystemAdapterRegistry): FileSystemAdapterRegistry;

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

@@ -0,0 +1,15 @@
+export function extendAdapterRegistry(defaults, extensions) {
+    if (extensions !== undefined &&
+        (extensions === null ||
+            typeof extensions.get !== "function" ||
+            typeof extensions[Symbol.iterator] !== "function")) {
+        throw new TypeError("registry must be a filesystem adapter map.");
+    }
+    const registry = new Map(defaults);
+    for (const [name, descriptor] of extensions ?? []) {
+        if (registry.has(name))
+            throw new TypeError(`Filesystem adapter already registered: ${name}`);
+        registry.set(name, descriptor);
+    }
+    return registry;
+}

package/dist/safe-fs/config.node.js

@@ -1,22 +1,11 @@
+import { extendAdapterRegistry } from "./config/registry.js";
 import { createMemoryFileSystemAdapter } from "./config/memory.js";
 import { createRealFileSystemAdapter } from "./config/real.js";
 import { createMemoryFileSystem } from "./fs/memory/index.js";
 import { createRealFileSystem } from "./fs/real/index.js";
 export function createNodeFileSystemAdapterRegistry(extensions) {
-    if (extensions !== undefined &&
-        (extensions === null ||
-            typeof extensions.get !== "function" ||
-            typeof extensions[Symbol.iterator] !== "function")) {
-        throw new TypeError("registry must be a filesystem adapter map.");
-    }
-    const registry = new Map([
+    return extendAdapterRegistry(new Map([
         ["memory", createMemoryFileSystemAdapter(createMemoryFileSystem)],
         ["real", createRealFileSystemAdapter(createRealFileSystem)]
-    ]);
-    for (const [name, descriptor] of extensions ?? []) {
-        if (registry.has(name))
-            throw new TypeError(`Filesystem adapter already registered: ${name}`);
-        registry.set(name, descriptor);
-    }
-    return registry;
+    ]), extensions);
 }

package/dist/safe-fs/config.portable.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystemAdapterRegistry } from "./config.js";
+/** Portable defaults never grant access to the host filesystem. */
+export declare function createPortableFileSystemAdapterRegistry(extensions?: FileSystemAdapterRegistry): FileSystemAdapterRegistry;

package/dist/safe-fs/config.portable.js

@@ -0,0 +1,9 @@
+import { createMemoryFileSystemAdapter } from "./config/memory.js";
+import { extendAdapterRegistry } from "./config/registry.js";
+import { createMemoryFileSystem } from "./fs/memory/index.js";
+/** Portable defaults never grant access to the host filesystem. */
+export function createPortableFileSystemAdapterRegistry(extensions) {
+    return extendAdapterRegistry(new Map([
+        ["memory", createMemoryFileSystemAdapter(createMemoryFileSystem)]
+    ]), extensions);
+}

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

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

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

@@ -31,7 +31,18 @@ const descriptions = {
     ETIMEDOUT: "operation timed out",
     EXDEV: "cross-device link not permitted",
 };
+const FS_ERROR_BRAND = Symbol.for("@poe-code/safe-fs.FsError");
 export class FsError extends Error {
+    static [Symbol.hasInstance](value) {
+        if (typeof value !== "object" || value === null)
+            return false;
+        if (this !== FsError)
+            return Function.prototype[Symbol.hasInstance].call(this, value);
+        if (Function.prototype[Symbol.hasInstance].call(FsError, value))
+            return true;
+        const record = value;
+        return record[FS_ERROR_BRAND] === true && isErrnoCode(record.code);
+    }
     code;
     errno;
     syscall;
@@ -53,6 +64,7 @@ export class FsError extends Error {
         finally {
             errorConstructor.stackTraceLimit = prevStackLimit;
         }
+        Object.defineProperty(this, FS_ERROR_BRAND, { value: true, enumerable: false, configurable: false, writable: false });
         this.name = "FsError";
         this.code = code;
         this.errno = errno;

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

@@ -284,6 +284,17 @@ export interface PublishStagedFileOptions extends FsOptions {
     readonly parent: FileStat;
     readonly destination: FileStat | null;
 }
+/** Publish one staged regular file and validate/retire sibling source entries in
+ * the same indivisible commit. Every expected version (including absence) must
+ * match before any mutation. Hosts must not emulate this with sequential calls.
+ * Unavailable hosts omit publishStagedFileSet. Sources remain caller-owned. */
+export interface PublishStagedFileSetOptions extends PublishStagedFileOptions {
+    readonly companions: readonly {
+        readonly path: string;
+        readonly expected: FileStat | null;
+        readonly remove: boolean;
+    }[];
+}
 export interface PrepareDirectoryOptions extends FsOptions {
     readonly expected: FileStat | null;
     readonly parent: FileStat;
@@ -321,6 +332,7 @@ export interface FileSystem {
     prepareDirectory?(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     createStagedFile?(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile?(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    publishStagedFileSet?(staging: FileStaging, destination: string, options: PublishStagedFileSetOptions): Promise<FileStat>;
     /** Admit a complete canonical root-to-directory prefix and prepare a guard.
      * The returned guard checks current identities/search access synchronously;
      * preparation is not validation, and the guard's result is not an async lease. */

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

@@ -3,3 +3,4 @@ export * from "./filesystem.js";
 export * from "./io.js";
 export * from "./path.js";
 export * from "./object.js";
+export { compareIdentity, compareFileVersion } from "../fs/mount/identity.js";

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

@@ -3,3 +3,4 @@ export * from "./filesystem.js";
 export * from "./io.js";
 export * from "./path.js";
 export * from "./object.js";
+export { compareIdentity, compareFileVersion } from "../fs/mount/identity.js";

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

@@ -211,7 +211,7 @@ class ReadBytesGenerator {
         if (!this.finished && this.iterator?.return) {
             this.finished = true;
             const it = this.iterator;
-            const cleanup = Promise.resolve().then(() => it.return());
+            const cleanup = new Promise(resolve => { resolve(it.return()); });
             if (signal?.aborted)
                 void cleanup.catch(noop);
             else

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

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

package/dist/safe-fs/core.js

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

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

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

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

@@ -2,9 +2,9 @@ import { snapshotStagingCreation } from "../staging-cleanup.js";
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
-import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
+import { compareEntries } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
-import { tryResolveMemoryDevicePath } from "../memory/index.js";
+import { tryResolveMemoryDevicePath } from "../../runtime-core.js";
 import { createDeviceYield, deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
 import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "../capabilities.js";
 import { pathNamespace } from "../path-namespace.js";
@@ -71,21 +71,46 @@ function nonnegative(value, path) {
     if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
         throw new FsError("EINVAL", { path });
 }
+const sharedUnknownEntryAuthority = async () => "unknown";
 export class DeviceFileSystem {
     #filesystem;
     capabilities;
-    #nullStat;
-    #directoryStat;
+    #identityScopeObj;
+    #nullStatObj;
+    #directoryStatObj;
+    get [pathNamespace]() {
+        return Reflect.get(this.#filesystem, pathNamespace);
+    }
+    get #nullStat() {
+        if (this.#nullStatObj)
+            return this.#nullStatObj;
+        const identityScope = (this.#identityScopeObj ??= Object.freeze({}));
+        return (this.#nullStatObj = Object.freeze({
+            type: "character", mode: 0o020666, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
+            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 1, dev: 0, nlink: 1, preferredIoBlockSize: 4096,
+        }));
+    }
+    get #directoryStat() {
+        if (this.#directoryStatObj)
+            return this.#directoryStatObj;
+        const identityScope = (this.#identityScopeObj ??= Object.freeze({}));
+        return (this.#directoryStatObj = Object.freeze({
+            type: "directory", mode: 0o040755, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
+            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 2, dev: 0, nlink: 1,
+        }));
+    }
+    _resolveEntryView = async (path, options) => {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath || resolved === deviceDirectory) {
+            return { filesystem: this, path: resolved, stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
+        }
+        return { filesystem: this.#filesystem, path };
+    };
+    _entryAuthority = sharedUnknownEntryAuthority;
     constructor(filesystem) {
         this.#filesystem = filesystem;
-        Object.defineProperty(this, pathNamespace, { get: () => Reflect.get(filesystem, pathNamespace) });
         this.capabilities = globalCapabilities(filesystem);
-        const identityScope = Object.freeze({});
-        const stat = { mode: 0o020666, size: 0, allocatedBytes: 0, uid: 0, gid: 0,
-            mtimeMs: 0, atimeMs: 0, ctimeMs: 0, birthtimeMs: 0, identityScope, ino: 1, dev: 0, nlink: 1 };
-        this.#nullStat = Object.freeze({ ...stat, type: "character", preferredIoBlockSize: 4096 });
-        this.#directoryStat = Object.freeze({ ...stat, type: "directory", mode: 0o040755, ino: 2 });
-        const methods = new Map();
+        let methods;
         const view = new Proxy(this, {
             set: (_target, property, value) => Reflect.set(filesystem, property, value, filesystem),
             get(target, property) {
@@ -93,24 +118,14 @@ export class DeviceFileSystem {
                 if (typeof value !== "function" || property === "constructor")
                     return value;
                 const backing = Reflect.get(filesystem, property, filesystem);
-                const cached = methods.get(property);
+                const cached = methods?.get(property);
                 if (cached && cached.backing === backing)
                     return cached.bound;
                 const bound = value.bind(target);
-                methods.set(property, { backing, bound });
+                (methods ??= new Map()).set(property, { backing, bound });
                 return bound;
             },
         });
-        for (const identity of [this, view])
-            registerEntryView(identity, async (path, options) => {
-                const resolved = await this.#resolve(path, options);
-                if (resolved === nullPath || resolved === deviceDirectory)
-                    return { filesystem: this, path: resolved,
-                        stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
-                return { filesystem, path };
-            });
-        // This internal view has no identity proof beyond its synthetic stats.
-        registerEntryAuthority(this, async () => "unknown");
         return view;
     }
     #resolve(path, options, followFinal = true, resizeCreate, traversal) {
@@ -624,6 +639,47 @@ export class DeviceFileSystem {
             await requireOwnedMutation(this.#filesystem, destination, "guardedStagingPublication", options, options.destination === null);
         await this.#filesystem.publishStagedFile(staging, destination, options);
     }
+    async publishStagedFileSet(receipt, destination, supplied) {
+        const publish = this.#filesystem.publishStagedFileSet;
+        if (!publish)
+            throw new FsError("ENOTSUP", { path: destination });
+        const entry = (value) => ({ path: value.path, stat: { ...value.stat } });
+        const staging = { ...receipt, parent: entry(receipt.parent), directory: entry(receipt.directory), file: entry(receipt.file) };
+        const options = {
+            ...supplied,
+            parent: { ...supplied.parent },
+            destination: supplied.destination === null ? null : { ...supplied.destination },
+            companions: supplied.companions.map(value => ({ ...value, expected: value.expected === null ? null : { ...value.expected } })),
+            ...(supplied.ancestors === undefined ? {} : { ancestors: snapshotDirectoryAncestry(supplied.ancestors) }),
+        };
+        options.signal?.throwIfAborted();
+        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);
+        const guards = [];
+        if (options.ancestors)
+            guards.push(await this.prepareDirectoryAncestry(options.ancestors, options));
+        for (const path of [staging.file.path, destination, ...options.companions.map(value => value.path)]) {
+            await this.#mutable(path, options, false);
+            const resolution = await this.prepareStagingResolution(path, options);
+            guards.push(resolution.validate);
+        }
+        const callerGuard = options.commitGuard;
+        options.signal?.throwIfAborted();
+        return publish.call(this.#filesystem, staging, destination, { ...options, commitGuard: () => {
+                options.signal?.throwIfAborted();
+                if (callerGuard !== undefined)
+                    runStagingGuard(callerGuard);
+                // Recheck every route in the backend's atomic commit, so a source cannot
+                // cross into the virtual device namespace after asynchronous admission.
+                for (const guard of guards)
+                    runStagingGuard(guard);
+                options.signal?.throwIfAborted();
+                return true;
+            } });
+    }
     async prepareDirectoryAncestry(ancestors, options = {}) {
         options.signal?.throwIfAborted();
         try {

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

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

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

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

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

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

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

@@ -1,5 +1,6 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { 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 { ByteSource } from "../../contracts/io.js";
+import { type MemoryAtomicView } from "./atomic-view.js";
 import { MemoryAllocation, MemoryLedger } from "./ledger.js";
 import { type MemoryFileSystemOptions } from "./limits.js";
 export { defaultMemoryFileSystemLimits, type MemoryFileSystemLimits, type MemoryFileSystemOptions } from "./limits.js";
@@ -34,7 +35,6 @@ interface SymlinkNode extends Metadata {
 }
 type MemoryNode = FileNode | DirectoryNode | SymlinkNode;
 declare class MemoryCache {
-    readonly allocations: MemoryAllocation[];
     readonly files: FileNode[];
     readonly directories: DirectoryNode[];
     readonly removedScratch: MemoryNode[];
@@ -59,9 +59,10 @@ export interface ConditionalMutationBinding {
 }
 export declare function bindConditionalMutation<Result>(identityScope: object | symbol | undefined, binding: ConditionalMutationBinding, action: () => Promise<Result>): Promise<Result>;
 export declare class MemoryFileSystem implements FileSystem {
+    #private;
     capabilitiesFor?: NonNullable<FileSystem["capabilitiesFor"]>;
-    readonly capabilities: FileSystemCapabilities;
-    private readonly identityScope;
+    private get identityScope();
+    get capabilities(): FileSystemCapabilities;
     private nextInode;
     private readonly ledger;
     readonly _cache: MemoryCache;
@@ -70,6 +71,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private readonly root;
     private totalBytes;
     symlinkCount: number;
+    _getAtomicView(): MemoryAtomicView | undefined;
     constructor(options?: MemoryFileSystemOptions);
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
@@ -115,6 +117,7 @@ export declare class MemoryFileSystem implements FileSystem {
     prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
     private verifyDirectoryAncestry;
     publishStagedFile(receipt: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    publishStagedFileSet(receipt: FileStaging, destination: string, options: PublishStagedFileSetOptions): Promise<FileStat>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     private removeStagingLocations;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;