@poe-platform/safe-fs 0.1.729 → 0.1.730

package/README.md

@@ -25,6 +25,14 @@ console.log(await fs.readFile("note.txt", "utf8"));
 
 Output: `hello`, then `hello world`. Nothing touches the host filesystem. Raw adapters exchange `Uint8Array` values; the Node bridge adds strings, encodings, `Buffer` results, and stat predicates. Its `cwd` is the relative-path base and, by default, the confinement boundary. Set an explicit `root` to use a different boundary, for example `{ cwd: "/work", root: "/" }` to address a complete provider namespace. The bridge supports `unlink` when the provider offers atomic file removal; unsupported methods fail without host fallback. `createHostFileSystem()` provides trusted, unrestricted native host access when a rooted adapter is not desired.
 
+Under the `workerd` export condition, `@poe-platform/safe-fs/fs/real` reads the
+native request-local filesystem, including retained `/tmp` file bytes.
+The restricted profile refuses generic descriptors, permission/timestamp
+changes, exact creation modes, and owned staging; it promises neither atomic
+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.
 
 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).
@@ -108,7 +116,7 @@ See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
 | Backend or wrapper | Use it for |
 | --- | --- |
 | `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams; each path resolution admits at most 65,536 cumulative UTF-16 code units across the input and followed symlink targets, rejecting excess with `ENAMETOOLONG` before component allocation |
-| `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node only |
+| `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node or qualified Workerd operations |
 | `new S3FileSystem({ transport, bucket, … })` | Bucket/prefix storage through an explicitly supplied transport; Node only |
 | `new WebDavFileSystem({ baseUrl, fetch, … })` | A WebDAV namespace through an explicitly supplied Fetch implementation |
 | `createReadOnlyFileSystem(filesystem)` | Rejecting writes through one view of an existing filesystem |

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

@@ -78,6 +78,7 @@ export interface FileSystemCapabilities {
     readonly atomicFileStaging?: boolean;
     /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
     readonly retainedStagingCleanup?: boolean;
+    readonly retainedStagingWrite?: boolean;
     /** Atomically verifies every supplied root-to-parent directory identity at publication. */
     readonly atomicStagingAncestry?: boolean;
     /** Prepares directory guards that validate without yielding or mutating state. */
@@ -249,6 +250,13 @@ export interface FileStaging {
     readonly directory: FileStagingEntry;
     readonly file: FileStagingEntry;
     readonly cleanup?: FileStagingCleanup;
+    /** Available for retained regular-file staging on qualified backends. Writes
+     * append to the owned entry; finish seals it and returns its publication stat.
+     * Cleanup owns the lifetime and checks the last successfully written revision. */
+    readonly writer?: {
+        write(bytes: Uint8Array, options?: FsOptions): Promise<void>;
+        finish(options?: FsOptions): Promise<FileStat>;
+    };
 }
 export type StagedFileContent = {
     readonly type: "file";

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

@@ -12,7 +12,7 @@ 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 { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.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";

package/dist/safe-fs/core.js

@@ -11,7 +11,7 @@ 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 { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.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";

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

@@ -105,7 +105,7 @@ export function readOnlyCapabilities(capabilities) {
         "symlinks", "streamingRead", "open", "retainedRead", "versionedDescriptors",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
-        ...inspection, retainedStagingCleanup: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        ...inspection, retainedStagingCleanup: false, retainedStagingWrite: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
         synchronousStagingResolution: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
@@ -118,7 +118,7 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: 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, 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,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -143,6 +143,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         (unavailable ??= {}).atomicFileStaging = false;
     if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).retainedStagingCleanup = false;
+    if (capabilities.retainedStagingWrite === true && (capabilities.retainedStagingCleanup !== true || unavailable?.retainedStagingCleanup === false))
+        (unavailable ??= {}).retainedStagingWrite = false;
     if (capabilities.atomicStagingAncestry === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).atomicStagingAncestry = false;
     if (capabilities.synchronousDirectoryValidation === true && typeof filesystem.prepareDirectoryAncestry !== "function")

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

@@ -44,6 +44,39 @@ const EMPTY_ALLOC_BYTES = new Uint8Array(0);
 const SMALL_ALLOC_SLAB_SIZE = 8192;
 let smallAllocSlab = new Uint8Array(SMALL_ALLOC_SLAB_SIZE);
 let smallAllocOffset = 0;
+const DUMMY_POOL_LEDGER = new MemoryLedger(normalizeMemoryFileSystemLimits({}));
+const DUMMY_POOL_ALLOCATION = new MemoryAllocation(EMPTY_ALLOC_BYTES, DUMMY_POOL_LEDGER);
+const sharedAllocationPool = [];
+const sharedFileNodePool = [];
+const sharedDirectoryNodePool = [];
+const sharedRemovedScratch = [];
+let sharedRemovedKeyChars = 0;
+let sharedRemovedKeyEntries = 0;
+function collectRemovedChild(child, name) {
+    sharedRemovedScratch.push(child);
+    sharedRemovedKeyChars += name.length;
+    sharedRemovedKeyEntries++;
+}
+function replenishSharedMemoryPools() {
+    while (sharedAllocationPool.length < 112) {
+        if (smallAllocOffset + 64 > SMALL_ALLOC_SLAB_SIZE) {
+            smallAllocSlab = new Uint8Array(SMALL_ALLOC_SLAB_SIZE);
+            smallAllocOffset = 0;
+        }
+        const slice = smallAllocSlab.subarray(smallAllocOffset, smallAllocOffset + 64);
+        smallAllocOffset += 64;
+        DUMMY_POOL_LEDGER.reserve(64, 0, "init", "/");
+        const alloc = new MemoryAllocation(slice, DUMMY_POOL_LEDGER);
+        alloc.release();
+        sharedAllocationPool.push(alloc);
+    }
+    while (sharedFileNodePool.length < 112) {
+        sharedFileNodePool.push(new MemoryFileNode(0, 0, 0, 0, DUMMY_POOL_ALLOCATION, undefined));
+    }
+    while (sharedDirectoryNodePool.length < 16) {
+        sharedDirectoryNodePool.push(new MemoryDirectoryNode(0, 0, 0));
+    }
+}
 class MemoryDirectoryNode {
     constructor(mode, ino, now) {
         this.mode = mode;
@@ -271,7 +304,7 @@ export class MemoryFileSystem {
             permissions: true,
             timestamps: true,
             atomicRename: true,
-            atomicFileStaging: true, retainedStagingCleanup: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
+            atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
             synchronousDirectoryValidation: true, synchronousStagingResolution: true, guardedStagingPublication: true,
             atomicDirectoryMetadata: true,
             streamingRead: true,
@@ -289,6 +322,9 @@ export class MemoryFileSystem {
     symlinkCount = 0;
     constructor(options = {}) {
         this.ledger = new MemoryLedger(normalizeMemoryFileSystemLimits(options));
+        if (this.ledger.hasInfiniteRetained && this.ledger.limits.maxFileBytes === Infinity) {
+            replenishSharedMemoryPools();
+        }
         memoryCaches.set(this.ledger, new MemoryCache());
         this.ledger.reserve(0, 1, "mkdir", "/");
         this.root = this.directory(0o755);
@@ -380,7 +416,7 @@ export class MemoryFileSystem {
             retained.set("/", this.root);
         }
         const capabilities = this.capabilities;
-        const allowed = new Set(["mkdir", "rm", "rmdir", "rename", "symlink", "link", "chmod", "utimes", "writeFile", "appendFile", "writeStream", "writeFileConditional", "removeFileConditional", "prepareDirectory", "createStagedFile", "publishStagedFile", "removeStagedFile"]);
+        const allowed = new Set(["mkdir", "rm", "rmdir", "rename", "symlink", "link", "chmod", "utimes", "writeFile", "appendFile", "writeStream", "writeFileConditional", "removeFileConditional", "removeEntryConditional", "prepareDirectory", "createStagedFile", "publishStagedFile", "removeStagedFile"]);
         const reads = new Set(["access", "capabilitiesFor", "compareEntry", "lstat", "stat", "readFile", "readStream", "readdir", "readlink", "realpath"]);
         const check = (path, followFinal) => {
             if (!roots.some(root => root === "/" || path === root || path.startsWith(`${root}/`)))
@@ -430,6 +466,24 @@ export class MemoryFileSystem {
                                     this.fail("EPERM", "writeStream", path);
                             } };
                     }
+                    if (property === "createStagedFile")
+                        return Reflect.apply(value, target, args).then(staging => {
+                            const writer = staging.writer;
+                            if (!writer)
+                                return staging;
+                            return Object.freeze({ ...staging, writer: Object.freeze({
+                                    write: async (bytes, controls = {}) => {
+                                        controls.signal?.throwIfAborted();
+                                        check(staging.file.path, true);
+                                        await writer.write(bytes, controls);
+                                    },
+                                    finish: async (controls = {}) => {
+                                        controls.signal?.throwIfAborted();
+                                        check(staging.file.path, true);
+                                        return writer.finish(controls);
+                                    },
+                                }) });
+                        });
                     return Reflect.apply(value, target, args);
                 };
             },
@@ -446,7 +500,7 @@ export class MemoryFileSystem {
         const now = Date.now();
         const fullMode = typeModes.directory | mode;
         const ino = this.nextInode++;
-        const pooled = memoryCaches.get(this.ledger)?.directories.pop();
+        const pooled = sharedDirectoryNodePool.pop() ?? memoryCaches.get(this.ledger)?.directories.pop();
         if (pooled) {
             pooled.mode = fullMode;
             pooled.ino = ino;
@@ -511,11 +565,21 @@ export class MemoryFileSystem {
             this.totalBytes -= node.byteLength;
             const alloc = node.allocation;
             node.view = undefined;
+            node.allocation = DUMMY_POOL_ALLOCATION;
             alloc.release();
-            if (alloc.isReleased64() && cache.allocations.length < 128) {
-                cache.allocations.push(alloc);
+            if (alloc.isReleased64()) {
+                alloc.detachLedger(DUMMY_POOL_LEDGER);
+                if (this.ledger.hasInfiniteRetained && this.ledger.limits.maxFileBytes === Infinity && sharedAllocationPool.length < 128) {
+                    sharedAllocationPool.push(alloc);
+                }
+                else if (cache.allocations.length < 128) {
+                    cache.allocations.push(alloc);
+                }
             }
-            if (cache.files.length < 128) {
+            if (sharedFileNodePool.length < 128) {
+                sharedFileNodePool.push(node);
+            }
+            else if (cache.files.length < 128) {
                 cache.files.push(node);
             }
         }
@@ -527,8 +591,13 @@ export class MemoryFileSystem {
                 cache.lastFastDirPrefix = "";
                 cache.lastFastDirNode = undefined;
             }
-            if (node.entries.size === 0 && cache.directories.length < 32) {
-                cache.directories.push(node);
+            if (node.entries.size === 0) {
+                if (sharedDirectoryNodePool.length < 32) {
+                    sharedDirectoryNodePool.push(node);
+                }
+                else if (cache.directories.length < 32) {
+                    cache.directories.push(node);
+                }
             }
         }
     }
@@ -900,11 +969,14 @@ export class MemoryFileSystem {
         if (length === 0) {
             return new MemoryAllocation(EMPTY_ALLOC_BYTES, this.ledger);
         }
-        const allocations = memoryCaches.get(this.ledger).allocations;
-        if (length === 64 && allocations.length > 0) {
-            const pooled = allocations.pop();
-            pooled.reuse();
-            return pooled;
+        if (length === 64) {
+            const pooled = (this.ledger.hasInfiniteRetained && this.ledger.limits.maxFileBytes === Infinity
+                ? sharedAllocationPool.pop()
+                : undefined) ?? memoryCaches.get(this.ledger).allocations.pop();
+            if (pooled) {
+                pooled.reuse(this.ledger);
+                return pooled;
+            }
         }
         try {
             // A shared slab's backing buffer exceeds the admitted slice capacity.
@@ -1020,7 +1092,7 @@ export class MemoryFileSystem {
                     const now = Date.now();
                     const fileMode = typeModes.file | target.mode;
                     const view = capacity === length ? allocation.data : undefined;
-                    const pooled = memoryCaches.get(this.ledger).files.pop();
+                    const pooled = sharedFileNodePool.pop() ?? memoryCaches.get(this.ledger).files.pop();
                     if (pooled) {
                         pooled.mode = fileMode;
                         pooled.ino = this.nextInode++;
@@ -1183,7 +1255,7 @@ export class MemoryFileSystem {
             return;
         }
         if (!current) {
-            const capacity = length;
+            const capacity = length > 0 && length < 64 && this.ledger.hasInfiniteRetained && this.ledger.limits.maxFileBytes === Infinity ? 64 : length;
             const allocation = this.allocate(capacity, syscall, path);
             try {
                 allocation.data.set(data);
@@ -1191,8 +1263,8 @@ export class MemoryFileSystem {
                 try {
                     const now = Date.now();
                     const fileMode = typeModes.file | mode;
-                    const view = allocation.data;
-                    let node = cache.files.pop();
+                    const view = capacity === length ? allocation.data : undefined;
+                    let node = sharedFileNodePool.pop() ?? cache.files.pop();
                     if (node) {
                         node.mode = fileMode;
                         node.ino = this.nextInode++;
@@ -1326,7 +1398,7 @@ export class MemoryFileSystem {
                 return;
             }
             if (!current) {
-                const capacity = length;
+                const capacity = length > 0 && length < 64 && this.ledger.hasInfiniteRetained && this.ledger.limits.maxFileBytes === Infinity ? 64 : length;
                 const allocation = this.allocate(capacity, syscall, name);
                 try {
                     allocation.data.set(data);
@@ -1334,8 +1406,8 @@ export class MemoryFileSystem {
                     try {
                         const now = Date.now();
                         const fileMode = typeModes.file | mode;
-                        const view = allocation.data;
-                        let node = cache.files.pop();
+                        const view = capacity === length ? allocation.data : undefined;
+                        let node = sharedFileNodePool.pop() ?? cache.files.pop();
                         if (node) {
                             node.mode = fileMode;
                             node.ino = this.nextInode++;
@@ -1517,13 +1589,16 @@ export class MemoryFileSystem {
         location.parent.references++;
         directory.references++;
         file.references++;
-        return Object.freeze({ ...staging, cleanup: this.retainStagingCleanup(staging, location.parent, directory, file, location.name, name) });
+        return Object.freeze({ ...staging, ...this.retainStagingCleanup(staging, location.parent, directory, file, location.name, name) });
     }
     retainStagingCleanup(staging, parent, directory, file, directoryName, fileName) {
         // Clear this state on release, so keeping the closed handle does not keep
         // detached nodes alive outside the Memory ledger.
         let retained = { parent, directory, file };
-        return createStagingCleanup(staging.directory.path, options => {
+        let expected = staging.file.stat;
+        let writing = true;
+        const receipt = () => ({ ...staging, file: { ...staging.file, stat: expected } });
+        const ownedCleanup = createStagingCleanup(staging.directory.path, options => {
             options.signal?.throwIfAborted();
             const state = retained;
             if (state.parent.nlink === 0 || state.parent.entries.get(directoryName) !== state.directory)
@@ -1535,7 +1610,7 @@ export class MemoryFileSystem {
             const child = state.directory.entries.get(fileName);
             if (child && child !== state.file)
                 this.fail("EAGAIN", "removeStagedFile", staging.file.path);
-            this.removeStagingLocations(staging, {
+            this.removeStagingLocations(receipt(), {
                 node: state.directory, parent: state.parent, name: directoryName, path: staging.directory.path,
             }, { node: child, parent: state.directory, name: fileName, path: staging.file.path });
         }, () => {
@@ -1545,6 +1620,43 @@ export class MemoryFileSystem {
             this.releaseReference(state.directory, staging.directory.path);
             this.releaseReference(state.parent, staging.parent.path);
         });
+        const cleanup = Object.freeze({
+            remove: (options) => { writing = false; return ownedCleanup.remove(options); },
+            close: () => { writing = false; return ownedCleanup.close(); },
+        });
+        if (file.type !== "file")
+            return { cleanup };
+        const inspect = (options) => {
+            options.signal?.throwIfAborted();
+            if (!retained || !writing)
+                this.fail("EBADF", "stagedWrite", staging.file.path);
+            const location = this.stagingLocations(receipt());
+            if (location.file.node !== retained.file)
+                this.fail("EAGAIN", "stagedWrite", staging.file.path);
+            this.expectEntry(retained.file, expected, staging.file.path);
+            this.permission(retained.parent, 3, "stagedWrite", staging.parent.path);
+            this.permission(retained.directory, 3, "stagedWrite", staging.directory.path);
+            return retained.file;
+        };
+        return { cleanup, writer: Object.freeze({
+                write: async (bytes, options = {}) => {
+                    const node = inspect(options);
+                    if (!(bytes instanceof Uint8Array))
+                        throw new TypeError("Staged writes require Uint8Array data");
+                    this.writeAt(node, bytes, node.byteLength, "stagedWrite", staging.file.path);
+                    expected = Object.freeze(this.snapshot(node));
+                },
+                finish: async (options = {}) => {
+                    const node = inspect(options);
+                    this.changed(node);
+                    // changed updates modification time; archive creation metadata is final.
+                    node.atimeMs = staging.file.stat.atimeMs;
+                    node.mtimeMs = staging.file.stat.mtimeMs;
+                    writing = false;
+                    expected = Object.freeze(this.snapshot(node));
+                    return expected;
+                },
+            }) };
     }
     async prepareDirectoryAncestry(ancestors, options = {}) {
         const entries = snapshotDirectoryAncestry(ancestors);
@@ -1890,38 +2002,38 @@ export class MemoryFileSystem {
             this.fail("EISDIR", syscall, path);
         const cache = memoryCaches.get(this.ledger);
         cache.clearWrites();
-        const removed = cache.removedScratch;
+        const removed = sharedRemovedScratch;
         removed.length = 0;
         removed.push(node);
-        let keyChars = 0;
-        let keyEntries = 0;
-        for (let index = 0; index < removed.length; index++) {
-            const entry = removed[index];
-            if (entry.type === "directory" && entry.entries.size > 0) {
-                this.permission(entry, 7, syscall, path);
-                for (const [name, child] of entry.entries) {
-                    removed.push(child);
-                    keyChars += name.length;
-                    keyEntries++;
+        sharedRemovedKeyChars = 0;
+        sharedRemovedKeyEntries = 0;
+        try {
+            for (let index = 0; index < removed.length; index++) {
+                const entry = removed[index];
+                if (entry.type === "directory" && entry.entries.size > 0) {
+                    this.permission(entry, 7, syscall, path);
+                    entry.entries.forEach(collectRemovedChild);
                 }
             }
-        }
-        location.parent.entries.delete(location.name);
-        this.ledger.release((location.name.length + keyChars) * 2, 1 + keyEntries);
-        const now = Date.now();
-        for (let i = 0; i < removed.length; i++) {
-            const entry = removed[i];
-            if (entry.type === "directory") {
-                entry.entries.clear();
-            }
-            entry.nlink--;
-            if (entry.nlink !== 0 || entry.references !== 0) {
-                entry.ctimeMs = now;
-                entry.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, entry.revision + 1);
+            location.parent.entries.delete(location.name);
+            this.ledger.release((location.name.length + sharedRemovedKeyChars) * 2, 1 + sharedRemovedKeyEntries);
+            const now = Date.now();
+            for (let i = 0; i < removed.length; i++) {
+                const entry = removed[i];
+                if (entry.type === "directory") {
+                    entry.entries.clear();
+                }
+                entry.nlink--;
+                if (entry.nlink !== 0 || entry.references !== 0) {
+                    entry.ctimeMs = now;
+                    entry.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, entry.revision + 1);
+                }
+                this.releaseNode(entry);
             }
-            this.releaseNode(entry);
         }
-        removed.length = 0;
+        finally {
+            removed.length = 0;
+        }
         this.changed(location.parent);
     }
     unlink(path, options = {}) {

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

@@ -18,10 +18,11 @@ export declare class MemoryLedger {
 export declare class MemoryAllocation {
     private references;
     readonly data: Uint8Array;
-    private readonly ledger;
+    private ledger;
     constructor(data: Uint8Array, ledger: MemoryLedger);
     retain(): void;
     release(): void;
     isReleased64(): boolean;
-    reuse(): void;
+    detachLedger(dummyLedger: MemoryLedger): void;
+    reuse(ledger?: MemoryLedger): void;
 }

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

@@ -83,8 +83,13 @@ export class MemoryAllocation {
     isReleased64() {
         return this.references === 0 && this.data.byteLength === 64;
     }
-    reuse() {
+    detachLedger(dummyLedger) {
+        this.ledger = dummyLedger;
+    }
+    reuse(ledger) {
         this.references = 1;
+        if (ledger !== undefined)
+            this.ledger = ledger;
         this.data.fill(0);
     }
 }

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

@@ -188,7 +188,7 @@ export class MountFileSystem {
                     && 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 withOpen = { ...ordinary, retainedStagingWrite: false, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: 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)

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

@@ -1,3 +1,4 @@
+import { platform } from "#safe-fs-platform";
 import { snapshotStagingCreation } from "../staging-cleanup.js";
 import { snapshotConditionalChmod } from "../conditional-chmod.js";
 import { runStagingGuard, snapshotDirectoryAncestry } from "../staging-ancestry.js";
@@ -7,6 +8,7 @@ import * as native from "node:fs/promises";
 import { dirname, basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { nativeAllocatedBytes } from "./allocation.js";
 import { openFileDescriptor } from "../descriptor.js";
+import { compareIdentity } from "../mount/identity.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { callNativeSeekEnd, loadNativeSeekBinding } from "../../node/native-seek.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
@@ -32,11 +34,11 @@ function fileStat(stats) {
         mtimeMs: "mtimeNs" in stats ? Number(stats.mtimeNs / 1000000n) + Number(stats.mtimeNs % 1000000n) / 1e6 : stats.mtimeMs,
         ctimeMs: "ctimeNs" in stats ? Number(stats.ctimeNs / 1000000n) + Number(stats.ctimeNs % 1000000n) / 1e6 : stats.ctimeMs,
         birthtimeMs: "birthtimeNs" in stats ? Number(stats.birthtimeNs / 1000000n) + Number(stats.birthtimeNs % 1000000n) / 1e6 : stats.birthtimeMs, ino, dev,
-        ...(Number.isSafeInteger(dev) && dev >= 0 && Number.isSafeInteger(ino) && ino >= 0
+        ...(Number.isSafeInteger(dev) && dev >= 0 && Number.isSafeInteger(ino) && ino > 0
             ? { identityScope: Symbol.for("virtual-bash.fs.native") } : {}),
         nlink: Number(stats.nlink), uid: Number(stats.uid), gid: Number(stats.gid),
     };
-    if ("ctimeNs" in stats && !stats.isDirectory())
+    if (snapshot.identityScope !== undefined && "ctimeNs" in stats && (stats.ctimeNs !== 0n || stats.mtimeNs !== 0n) && !stats.isDirectory())
         Object.defineProperty(snapshot, "opaqueVersion", { value: `${stats.ctimeNs}:${stats.mtimeNs}`, enumerable: true });
     return snapshot;
 }
@@ -98,14 +100,13 @@ function nativeError(error) {
  */
 export class RealFileSystem {
     capabilities = Object.freeze({
-        read: true, stat: true, readdir: true, realpath: true, access: true, open: true,
+        read: true, stat: true, readdir: true, realpath: true, access: true,
         write: true, append: true, exclusiveCreate: true, explicitDirectories: true, implicitDirectories: false,
         mkdir: true, recursiveMkdir: true, remove: true, removeDirectory: true, recursiveRemove: true,
         rename: true, atomicRenameNoReplace: false, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
         streamingAppend: true, randomAccessWrite: true,
-        readOnly: false, symlinks: true, hardlinks: true, permissions: true,
-        conditionalChmod: true,
-        timestamps: true, atomicRename: true, streamingRead: true, streamingWrite: true, retainedRead: true, retainedResize: true, trustedOwnedStaging: true,
+        readOnly: false, symlinks: true, hardlinks: true, streamingRead: true, streamingWrite: true, retainedRead: true, retainedResize: true,
+        ...platform.nativeFileSystem,
     });
     configuredRoot;
     renameNoReplace;
@@ -122,6 +123,8 @@ export class RealFileSystem {
         this.configuredRoot = root;
         this.renameNoReplace = typeof options === "string" ? undefined : options.renameNoReplace;
         if (this.renameNoReplace !== undefined) {
+            if (!platform.nativeFileSystem.atomicRename)
+                throw new FsError("ENOTSUP", { syscall: "root", message: "atomic rename is unavailable on this host" });
             if (typeof this.renameNoReplace !== "function")
                 throw new FsError("EINVAL", { syscall: "root", message: "renameNoReplace must be a function" });
             this.capabilities = Object.freeze({ ...this.capabilities, atomicRenameNoReplace: true });
@@ -291,10 +294,15 @@ export class RealFileSystem {
         }
     }
     expectStaging(path, expected, identityOnly = false) {
+        if (!platform.nativeFileSystem.trustedOwnedStaging)
+            throw new FsError("ENOTSUP");
         if (expected && (expected.identityScope !== Symbol.for("virtual-bash.fs.native")
             || expected.dev === undefined || expected.ino === undefined || !identityOnly && expected.opaqueVersion === undefined))
             throw new FsError("ENOTSUP");
         const current = this.stagingSnapshot(path);
+        if (expected && current && (current.identityScope !== Symbol.for("virtual-bash.fs.native")
+            || current.dev === undefined || current.ino === undefined || !identityOnly && current.opaqueVersion === undefined))
+            throw new FsError("ENOTSUP");
         if (expected === null ? current !== null : !current || current.dev !== expected.dev || current.ino !== expected.ino || current.type !== expected.type
             || !identityOnly && (current.opaqueVersion !== expected.opaqueVersion || current.size !== expected.size || current.mode !== expected.mode || current.nlink !== expected.nlink))
             throw new FsError("EAGAIN");
@@ -521,6 +529,8 @@ export class RealFileSystem {
         }
     }
     open(path, options) {
+        if (!platform.nativeFileSystem.open)
+            return this.operation("open", path, options, async () => { throw new FsError("ENOTSUP"); });
         return openFileDescriptor(path, options, {
             noFollow: true, positionedRead: true, positionedWrite: true, truncate: true, synchronization: "storage",
         }, async (admitted) => {
@@ -663,7 +673,7 @@ export class RealFileSystem {
         return this.operation("mkdir", path, options, async () => {
             if (options.mode !== undefined)
                 integer(options.mode);
-            if (options.exactMode && options.recursive)
+            if (options.exactMode && (!platform.nativeFileSystem.permissions || options.recursive))
                 throw new FsError("ENOTSUP");
             const target = await this.path(path, {
                 ...options,
@@ -746,8 +756,13 @@ export class RealFileSystem {
                 }
                 if (target && options.exclusive)
                     throw new FsError("EEXIST");
-                if (target && origin.isFile() && origin.dev === target.dev && origin.ino === target.ino)
-                    throw new FsError("EINVAL");
+                if (target && origin.isFile()) {
+                    const identity = compareIdentity(fileStat(origin), fileStat(target));
+                    if (identity === "same")
+                        throw new FsError("EINVAL");
+                    if (identity === "unknown")
+                        throw new FsError("ENOTSUP");
+                }
                 if (!target)
                     flags |= constants.COPYFILE_EXCL;
             }
@@ -813,6 +828,8 @@ export class RealFileSystem {
     }
     async chmod(path, mode, options = {}) {
         return this.operation("chmod", path, options, async () => {
+            if (!platform.nativeFileSystem.permissions)
+                throw new FsError("ENOTSUP");
             integer(mode);
             const conditional = snapshotConditionalChmod(path, options);
             if (conditional) {
@@ -846,6 +863,8 @@ export class RealFileSystem {
     }
     async utimes(path, atimeMs, mtimeMs, options = {}) {
         return this.operation("utimes", path, options, async () => {
+            if (!platform.nativeFileSystem.timestamps)
+                throw new FsError("ENOTSUP");
             if (!Number.isFinite(atimeMs) || !Number.isFinite(mtimeMs)
                 || Math.abs(atimeMs) > 8.64e15 || Math.abs(mtimeMs) > 8.64e15)
                 throw new FsError("EINVAL");

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

@@ -1,4 +1,5 @@
 import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export declare function retargetScopedFileSystem(scoped: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void, maxPathComponents?: number): boolean;
 export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void, options?: {
     readonly preserveDescriptorWriteReceipt?: boolean;
     readonly creationMask?: number;

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

@@ -8,6 +8,14 @@ import { openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabi
 import { createStagingCleanup, snapshotStagingCreation } from "./staging-cleanup.js";
 import { inspectStagingBindings, runStagingGuard, snapshotDirectoryAncestry, snapshotStagingResolution } from "./staging-ancestry.js";
 const originals = new WeakMap();
+const retargeters = new WeakMap();
+export function retargetScopedFileSystem(scoped, charge, signal, cleanupCharge = charge, maxPathComponents) {
+    const fn = retargeters.get(scoped);
+    if (!fn)
+        return false;
+    fn(charge, signal, cleanupCharge, maxPathComponents);
+    return true;
+}
 const operations = new Set([
     "prepareDirectoryAncestry", "prepareStagingResolution",
     "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
@@ -19,7 +27,7 @@ const operations = new Set([
 export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge, options = {}) {
     const original = originals.get(filesystem)?.filesystem ?? filesystem;
     const creationMask = options.creationMask ?? originals.get(filesystem)?.creationMask;
-    const maxPathComponents = options.maxPathComponents ?? originals.get(filesystem)?.maxPathComponents;
+    let maxPathComponents = options.maxPathComponents ?? originals.get(filesystem)?.maxPathComponents;
     if (creationMask !== undefined && (!Number.isInteger(creationMask) || creationMask < 0 || creationMask > 0o777))
         throw new RangeError("creationMask must be a permission mask between 0 and 0777");
     const creationOptions = (settings, directory = false) => {
@@ -343,7 +351,20 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                                 controls.signal?.throwIfAborted();
                                 return backendCleanup.remove(controls);
                             }, () => backendCleanup.close());
-                            return Object.freeze({ ...staging, cleanup });
+                            const backendWriter = staging.writer;
+                            const writer = backendWriter && Object.freeze({
+                                write: async (bytes, settings = {}) => {
+                                    const controls = resizeOptions(settings);
+                                    admit(controls);
+                                    await backendWriter.write(bytes, controls);
+                                },
+                                finish: async (settings = {}) => {
+                                    const controls = resizeOptions(settings);
+                                    admit(controls);
+                                    return backendWriter.finish(controls);
+                                },
+                            });
+                            return Object.freeze({ ...staging, cleanup, ...(writer ? { writer } : {}) });
                         }
                         catch (error) {
                             await finishCleanup(() => backendCleanup.close(), true);
@@ -471,7 +492,17 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             return scoped;
         },
     });
-    originals.set(view, { filesystem: original, signal, cleanupCharge, creationMask, maxPathComponents });
+    const originalRecord = { filesystem: original, signal, cleanupCharge, creationMask, maxPathComponents };
+    originals.set(view, originalRecord);
+    retargeters.set(view, (nextCharge, nextSignal, nextCleanupCharge, nextMaxPathComponents) => {
+        charge = nextCharge;
+        signal = nextSignal;
+        cleanupCharge = nextCleanupCharge;
+        maxPathComponents = nextMaxPathComponents ?? originals.get(filesystem)?.maxPathComponents;
+        originalRecord.signal = nextSignal;
+        originalRecord.cleanupCharge = nextCleanupCharge;
+        originalRecord.maxPathComponents = maxPathComponents;
+    });
     registerEntryView(view, async (path, options) => {
         assertOpen(options);
         return { filesystem: original, path };

package/dist/safe-fs/node/native-seek-unavailable.d.ts

@@ -0,0 +1 @@
+export declare function loadBinding(): Promise<never>;

package/dist/safe-fs/node/native-seek-unavailable.js

@@ -0,0 +1,5 @@
+import { FsError } from "../contracts/errors.js";
+// Workers support native file reads, but cannot load the optional Node addon.
+export async function loadBinding() {
+    throw new FsError("ENOTSUP", { message: "Native seek is unavailable in Workers" });
+}

package/dist/safe-fs/platform/browser.d.ts

@@ -3,6 +3,14 @@ import type { ScopedTransportBudgetFrame } from "./transport-budget.js";
 export type PlatformErrno = number | undefined;
 export type PlatformComparisonCallback<Callback> = Callback & never;
 export declare const platform: Readonly<{
+    nativeFileSystem: Readonly<{
+        open: false;
+        permissions: false;
+        timestamps: false;
+        conditionalChmod: false;
+        trustedOwnedStaging: false;
+        atomicRename: false;
+    }>;
     maxCollectionBytes: number;
     errno(_code: string): PlatformErrno;
     callbackAuthorities: false;

package/dist/safe-fs/platform/browser.js

@@ -1,5 +1,6 @@
 import { FsError } from "../contracts/errors.js";
 export const platform = Object.freeze({
+    nativeFileSystem: Object.freeze({ open: false, permissions: false, timestamps: false, conditionalChmod: false, trustedOwnedStaging: false, atomicRename: false }),
     maxCollectionBytes: 32 * 1024 * 1024,
     errno(_code) {
         return undefined;

package/dist/safe-fs/platform/node.d.ts

@@ -4,6 +4,14 @@ import { type ScopedTransportBudgetFrame } from "./transport-budget.js";
 export type PlatformErrno = number;
 export type PlatformComparisonCallback<Callback> = Callback;
 export declare const platform: Readonly<{
+    nativeFileSystem: Readonly<{
+        open: true;
+        permissions: true;
+        timestamps: true;
+        conditionalChmod: true;
+        trustedOwnedStaging: true;
+        atomicRename: true;
+    }>;
     maxCollectionBytes: number;
     errno(code: string): PlatformErrno;
     callbackAuthorities: true;

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

@@ -16,6 +16,7 @@ const systemErrnos = (() => {
 })();
 const negotiating = new AsyncLocalStorage();
 export const platform = Object.freeze({
+    nativeFileSystem: Object.freeze({ open: true, permissions: true, timestamps: true, conditionalChmod: true, trustedOwnedStaging: true, atomicRename: true }),
     maxCollectionBytes: Infinity,
     errno(code) {
         const errno = systemErrnos.get(code === "EOPNOTSUPP" ? "ENOTSUP" : code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.729",
+  "version": "0.1.730",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -69,9 +69,11 @@
     },
     "./fs/real": {
       "types": {
+        "workerd": "./dist/safe-fs/fs/real/index.d.ts",
         "browser": "./dist/safe-fs/node-unavailable.d.ts",
         "default": "./dist/safe-fs/fs/real/index.d.ts"
       },
+      "workerd": "./dist/safe-fs/fs/real/index.js",
       "browser": null,
       "import": "./dist/safe-fs/fs/real/index.js"
     },
@@ -134,15 +136,17 @@
   "imports": {
     "#safe-fs-platform": {
       "types": {
+        "workerd": "./dist/safe-fs/platform/browser.d.ts",
         "browser": "./dist/safe-fs/platform/browser.d.ts",
         "default": "./dist/safe-fs/platform/node.d.ts"
       },
+      "workerd": "./dist/safe-fs/platform/browser.js",
       "browser": "./dist/safe-fs/platform/browser.js",
       "default": "./dist/safe-fs/platform/node.js"
     },
     "#safe-fs-native-seek": {
       "types": "./dist/safe-fs/native/fs-seek/loader.d.ts",
-      "workerd": null,
+      "workerd": "./dist/safe-fs/node/native-seek-unavailable.js",
       "browser": null,
       "default": "./dist/safe-fs/native/fs-seek/loader.mjs"
     }