@poe-platform/safe-fs 0.1.250 → 0.1.252

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

@@ -1,3 +1,3 @@
 import type { FileSystemFactory } from "../contracts/filesystem.js";
-import { type FileSystemAdapterDescriptor } from "../config.js";
+import type { FileSystemAdapterDescriptor } from "../config.js";
 export declare function createMemoryFileSystemAdapter(create: FileSystemFactory): FileSystemAdapterDescriptor;

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

@@ -1,9 +1,7 @@
-import { readConfigRecord } from "../config.js";
+import { normalizeMemoryFileSystemLimits } from "../fs/memory/limits.js";
 export function createMemoryFileSystemAdapter(create) {
     return {
-        validateOptions(options) {
-            readConfigRecord(options, "memory option", []);
-        },
+        validateOptions: normalizeMemoryFileSystemLimits,
         create
     };
 }

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

@@ -8,6 +8,7 @@ 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 { scopeFileSystem } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";

package/dist/safe-fs/core.js

@@ -8,6 +8,7 @@ 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 { scopeFileSystem } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";

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

@@ -1,5 +1,7 @@
 import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileStat, FileSystem, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
+import { type MemoryFileSystemOptions } from "./limits.js";
+export { defaultMemoryFileSystemLimits, type MemoryFileSystemLimits, type MemoryFileSystemOptions } from "./limits.js";
 export declare class MemoryFileSystem implements FileSystem {
     readonly capabilities: Readonly<{
         read: true;
@@ -37,12 +39,17 @@ export declare class MemoryFileSystem implements FileSystem {
     }>;
     private readonly identityScope;
     private nextInode;
+    private readonly ledger;
     private readonly root;
-    constructor();
+    constructor(options?: MemoryFileSystemOptions);
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
     private metadata;
     private directory;
+    private addNode;
+    private releaseNode;
+    private releaseReference;
+    private replaceData;
     private fail;
     private validatePath;
     private permission;
@@ -56,7 +63,9 @@ export declare class MemoryFileSystem implements FileSystem {
     private snapshot;
     private bytes;
     private allocate;
+    private prepareWrite;
     private openWrite;
+    private writeData;
     private writeAt;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
@@ -81,4 +90,4 @@ export declare class MemoryFileSystem implements FileSystem {
     readStream(path: string, options?: ReadStreamOptions): ByteSource;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
 }
-export declare function createMemoryFileSystem(): MemoryFileSystem;
+export declare function createMemoryFileSystem(options?: MemoryFileSystemOptions | Readonly<Record<string, unknown>>): MemoryFileSystem;

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

@@ -4,6 +4,9 @@ import { getOwnedS3Entry } from "../s3/registry.js";
 import { getOwnedWebDavEntry } from "../webdav/resource-id.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { resolveMissingTarget } from "./missing-target.js";
+import { MemoryAllocation, MemoryLedger } from "./ledger.js";
+import { normalizeMemoryFileSystemLimits } from "./limits.js";
+export { defaultMemoryFileSystemLimits } from "./limits.js";
 const typeModes = { file: 0o100000, directory: 0o040000, symlink: 0o120000 };
 const ownedStats = new WeakMap();
 const ownedStores = new WeakMap();
@@ -70,8 +73,12 @@ export class MemoryFileSystem {
     })(this);
     identityScope = Symbol();
     nextInode = 1;
-    root = this.directory(0o755);
-    constructor() {
+    ledger;
+    root;
+    constructor(options = {}) {
+        this.ledger = new MemoryLedger(normalizeMemoryFileSystemLimits(options));
+        this.ledger.reserve(0, 1, "mkdir", "/");
+        this.root = this.directory(0o755);
         const root = this.root;
         ownedStores.set(this, {
             root,
@@ -105,13 +112,45 @@ export class MemoryFileSystem {
     metadata(mode) {
         const now = Date.now();
         return {
-            mode, ino: this.nextInode++, nlink: 1,
+            mode, ino: this.nextInode++, nlink: 1, references: 0,
             atimeMs: now, mtimeMs: now, ctimeMs: now, birthtimeMs: now,
         };
     }
     directory(mode) {
         return { ...this.metadata(typeModes.directory | mode), type: "directory", entries: new Map() };
     }
+    addNode(parent, name, create, syscall, path, retainedBytes = 0) {
+        const bytes = name.length * 2 + retainedBytes;
+        this.ledger.reserve(bytes, 2, syscall, path);
+        try {
+            const node = create();
+            parent.entries.set(name, node);
+            this.changed(parent);
+            return node;
+        }
+        catch (error) {
+            this.ledger.release(bytes, 2);
+            throw error;
+        }
+    }
+    releaseNode(node) {
+        if (node.nlink !== 0 || node.references !== 0)
+            return;
+        this.ledger.release(node.type === "symlink" ? node.target.length * 2 : 0, 1);
+        if (node.type === "file")
+            node.allocation.release();
+    }
+    releaseReference(node, path) {
+        node.references--;
+        this.ledger.release(path.length * 2, 1);
+        this.releaseNode(node);
+    }
+    replaceData(node, allocation, length = allocation.data.byteLength) {
+        const previous = node.allocation;
+        node.data = allocation.data.subarray(0, length);
+        node.allocation = allocation;
+        previous.release();
+    }
     fail(code, syscall, path, dest) {
         throw new FsError(code, { syscall, path, ...(dest === undefined ? {} : { dest }) });
     }
@@ -163,9 +202,8 @@ export class MemoryFileSystem {
             let node = current.entries.get(component);
             if (!node && options.createDirectories !== undefined) {
                 this.permission(current, 3, syscall, path);
-                node = this.directory(options.createDirectories);
-                current.entries.set(component, node);
-                this.changed(current);
+                const mode = options.createDirectories;
+                node = this.addNode(current, component, () => this.directory(mode), syscall, path);
             }
             if (!node) {
                 if (options.allowMissing && pending.length === 0) {
@@ -222,20 +260,29 @@ export class MemoryFileSystem {
             atimeMs: node.atimeMs, mtimeMs: node.mtimeMs, ctimeMs: node.ctimeMs, birthtimeMs: node.birthtimeMs,
         };
     }
-    bytes(data) {
-        if (!(data instanceof Uint8Array))
-            throw new TypeError("Memory files require Uint8Array data");
-        return new Uint8Array(data);
+    bytes(data, syscall, path) {
+        const allocation = this.allocate(data.byteLength, syscall, path);
+        try {
+            allocation.data.set(data);
+            return allocation;
+        }
+        catch (error) {
+            allocation.release();
+            throw error;
+        }
     }
     allocate(length, syscall, path) {
+        this.ledger.fileSize(length, syscall, path);
+        this.ledger.reserve(length, 0, syscall, path);
         try {
-            return new Uint8Array(length);
+            return new MemoryAllocation(new Uint8Array(length), this.ledger);
         }
         catch (cause) {
+            this.ledger.release(length, 0);
             throw new FsError("EFBIG", { syscall, path, cause });
         }
     }
-    openWrite(path, options, syscall) {
+    prepareWrite(path, options, syscall) {
         const flag = options.flag ?? "w";
         if (!["w", "wx", "a", "ax"].includes(flag))
             this.fail("EINVAL", syscall, path);
@@ -248,13 +295,62 @@ export class MemoryFileSystem {
             if (location.node.type !== "file")
                 this.fail("EISDIR", syscall, path);
             this.permission(location.node, 2, syscall, path);
+        }
+        else {
+            this.permission(location.parent, 3, syscall, path);
+        }
+        return { location, mode, append: flag === "a" || flag === "ax" };
+    }
+    openWrite(path, options, syscall, target = this.prepareWrite(path, options, syscall)) {
+        const { location, mode } = target;
+        if (location.node)
             return location.node;
+        return this.addNode(location.parent, location.name, () => {
+            const allocation = new MemoryAllocation(new Uint8Array(), this.ledger);
+            return { ...this.metadata(typeModes.file | mode), type: "file", data: allocation.data, allocation };
+        }, syscall, path);
+    }
+    writeData(path, data, options, syscall) {
+        if (!(data instanceof Uint8Array))
+            throw new TypeError("Memory files require Uint8Array data");
+        const target = this.prepareWrite(path, options, syscall);
+        const current = target.location.node;
+        const length = (target.append ? current?.data.byteLength ?? 0 : 0) + data.byteLength;
+        this.ledger.fileSize(length, syscall, path);
+        const growth = target.append && length > (current?.allocation.data.byteLength ?? 0) ? length : 0;
+        this.ledger.check(data.byteLength + growth + (current ? 0 : target.location.name.length * 2), current ? 0 : 2, syscall, path);
+        const copied = this.bytes(data, syscall, path);
+        let allocation = copied;
+        let transferred = false;
+        try {
+            if (!current) {
+                if (target.append && length > 0) {
+                    const capacity = Math.min(Math.max(length, 64), this.ledger.limits.maxFileBytes, this.ledger.availableBytes - target.location.name.length * 2);
+                    allocation = this.allocate(capacity, syscall, path);
+                    allocation.data.set(copied.data);
+                }
+                const node = this.addNode(target.location.parent, target.location.name, () => ({
+                    ...this.metadata(typeModes.file | target.mode), type: "file",
+                    data: allocation.data.subarray(0, length), allocation,
+                }), syscall, path);
+                transferred = true;
+                return node;
+            }
+            if (target.append)
+                this.writeAt(current, copied.data, current.data.byteLength, syscall, path);
+            else {
+                this.replaceData(current, copied);
+                transferred = true;
+                this.changed(current);
+            }
+            return current;
+        }
+        finally {
+            if (allocation !== copied && !transferred)
+                allocation.release();
+            if (!transferred || allocation !== copied)
+                copied.release();
         }
-        this.permission(location.parent, 3, syscall, path);
-        const node = { ...this.metadata(typeModes.file | mode), type: "file", data: new Uint8Array() };
-        location.parent.entries.set(location.name, node);
-        this.changed(location.parent);
-        return node;
     }
     writeAt(node, data, position, syscall, path) {
         if (data.byteLength === 0) {
@@ -262,21 +358,31 @@ export class MemoryFileSystem {
             return;
         }
         const end = position + data.byteLength;
-        if (!Number.isSafeInteger(end))
-            this.fail("EFBIG", syscall, path);
+        this.ledger.fileSize(end, syscall, path);
         const length = Math.max(node.data.byteLength, end);
-        let storage;
-        if (length <= node.data.buffer.byteLength) {
-            storage = new Uint8Array(node.data.buffer);
+        let allocation = node.allocation;
+        if (length > allocation.data.byteLength) {
+            this.ledger.check(length, 0, syscall, path);
+            const capacity = Math.min(Math.max(length, node.data.byteLength * 2, 64), this.ledger.limits.maxFileBytes, this.ledger.availableBytes);
+            allocation = this.allocate(capacity, syscall, path);
         }
-        else {
-            storage = this.allocate(Math.max(length, node.data.byteLength * 2, 64), syscall, path);
-            storage.set(node.data);
+        try {
+            const storage = allocation.data;
+            if (allocation !== node.allocation)
+                storage.set(node.data);
+            if (position > node.data.byteLength)
+                storage.fill(0, node.data.byteLength, position);
+            storage.set(data, position);
         }
-        if (position > node.data.byteLength)
-            storage.fill(0, node.data.byteLength, position);
-        storage.set(data, position);
-        node.data = storage.subarray(0, length);
+        catch (error) {
+            if (allocation !== node.allocation)
+                allocation.release();
+            throw error;
+        }
+        if (allocation !== node.allocation)
+            this.replaceData(node, allocation, length);
+        else
+            node.data = allocation.data.subarray(0, length);
         this.changed(node);
     }
     async readFile(path, options = {}) {
@@ -292,20 +398,11 @@ export class MemoryFileSystem {
     }
     async writeFile(path, data, options = {}) {
         options.signal?.throwIfAborted();
-        const copied = this.bytes(data);
-        const node = this.openWrite(path, options, "writeFile");
-        if (options.flag === "a" || options.flag === "ax")
-            this.writeAt(node, copied, node.data.byteLength, "writeFile", path);
-        else {
-            node.data = copied;
-            this.changed(node);
-        }
+        this.writeData(path, data, options, "writeFile");
     }
     async appendFile(path, data, options = {}) {
         options.signal?.throwIfAborted();
-        const copied = this.bytes(data);
-        const node = this.openWrite(path, { ...options, flag: "a" }, "appendFile");
-        this.writeAt(node, copied, node.data.byteLength, "appendFile", path);
+        this.writeData(path, data, { ...options, flag: "a" }, "appendFile");
     }
     async stat(path, options = {}) {
         options.signal?.throwIfAborted();
@@ -342,8 +439,7 @@ export class MemoryFileSystem {
         if (location.node)
             this.fail("EEXIST", "mkdir", path);
         this.permission(location.parent, 3, "mkdir", path);
-        location.parent.entries.set(location.name, this.directory(mode));
-        this.changed(location.parent);
+        this.addNode(location.parent, location.name, () => this.directory(mode), "mkdir", path);
     }
     async rmdir(path, options = {}) {
         options.signal?.throwIfAborted();
@@ -359,8 +455,10 @@ export class MemoryFileSystem {
         if (node.entries.size > 0)
             this.fail("ENOTEMPTY", "rmdir", path);
         location.parent.entries.delete(location.name);
+        this.ledger.release(location.name.length * 2, 1);
         node.nlink = 0;
         node.ctimeMs = Date.now();
+        this.releaseNode(node);
         this.changed(location.parent);
     }
     async rm(path, options = {}) {
@@ -392,9 +490,16 @@ export class MemoryFileSystem {
             }
         }
         location.parent.entries.delete(location.name);
+        this.ledger.release(location.name.length * 2, 1);
         for (const entry of removed) {
+            if (entry.type === "directory") {
+                for (const name of entry.entries.keys())
+                    this.ledger.release(name.length * 2, 1);
+                entry.entries.clear();
+            }
             entry.nlink--;
             entry.ctimeMs = Date.now();
+            this.releaseNode(entry);
         }
         this.changed(location.parent);
     }
@@ -423,11 +528,25 @@ export class MemoryFileSystem {
                     this.fail("EISDIR", "rename", source, destination);
                 if (target.node.type === "directory" && target.node.entries.size > 0)
                     this.fail("ENOTEMPTY", "rename", source, destination);
+            }
+            const nameGrowth = target.node ? 0 : (target.name.length - origin.name.length) * 2;
+            this.ledger.reserve(Math.max(0, nameGrowth), 0, "rename", source);
+            try {
+                target.parent.entries.set(target.name, node);
+            }
+            catch (error) {
+                this.ledger.release(Math.max(0, nameGrowth), 0);
+                throw error;
+            }
+            origin.parent.entries.delete(origin.name);
+            if (target.node) {
+                this.ledger.release(origin.name.length * 2, 1);
                 target.node.nlink--;
                 target.node.ctimeMs = Date.now();
+                this.releaseNode(target.node);
             }
-            origin.parent.entries.delete(origin.name);
-            target.parent.entries.set(target.name, node);
+            else if (nameGrowth < 0)
+                this.ledger.release(-nameGrowth, 0);
             this.changed(origin.parent);
             this.changed(target.parent);
             node.ctimeMs = Date.now();
@@ -448,8 +567,7 @@ export class MemoryFileSystem {
                 this.fail("EEXIST", "copyFile", source, destination);
             if (target.node === origin)
                 this.fail("EINVAL", "copyFile", source, destination);
-            const node = this.openWrite(destination, { mode: origin.mode & 0o7777, flag: options.exclusive ? "wx" : "w" }, "copyFile");
-            node.data = new Uint8Array(origin.data);
+            const node = this.writeData(destination, origin.data, { mode: origin.mode & 0o7777, flag: options.exclusive ? "wx" : "w" }, "copyFile");
             node.mode = origin.mode;
             this.changed(node);
             origin.atimeMs = Date.now();
@@ -484,8 +602,9 @@ export class MemoryFileSystem {
         if (location.node)
             this.fail("EEXIST", "symlink", path);
         this.permission(location.parent, 3, "symlink", path);
-        location.parent.entries.set(location.name, { ...this.metadata(typeModes.symlink | 0o777), type: "symlink", target });
-        this.changed(location.parent);
+        this.addNode(location.parent, location.name, () => ({
+            ...this.metadata(typeModes.symlink | 0o777), type: "symlink", target,
+        }), "symlink", path, target.length * 2);
     }
     async link(existingPath, newPath, options = {}) {
         options.signal?.throwIfAborted();
@@ -496,7 +615,14 @@ export class MemoryFileSystem {
         if (target.node)
             this.fail("EEXIST", "link", existingPath, newPath);
         this.permission(target.parent, 3, "link", newPath);
-        target.parent.entries.set(target.name, node);
+        this.ledger.reserve(target.name.length * 2, 1, "link", newPath);
+        try {
+            target.parent.entries.set(target.name, node);
+        }
+        catch (error) {
+            this.ledger.release(target.name.length * 2, 1);
+            throw error;
+        }
         node.nlink++;
         node.ctimeMs = Date.now();
         this.changed(target.parent);
@@ -523,8 +649,14 @@ export class MemoryFileSystem {
         const node = this.file(path, "truncate");
         this.permission(node, 2, "truncate", path);
         const data = this.allocate(length, "truncate", path);
-        data.set(node.data.subarray(0, length));
-        node.data = data;
+        try {
+            data.data.set(node.data.subarray(0, length));
+        }
+        catch (error) {
+            data.release();
+            throw error;
+        }
+        this.replaceData(node, data);
         this.changed(node);
     }
     async openReadFile(path, options = {}) {
@@ -535,7 +667,7 @@ export class MemoryFileSystem {
             || Object.getOwnPropertyDescriptor(this, "root")?.value !== owner.root)
             unsupported();
         for (const name of ["openReadFile", "readFile", "readStream", "stat", "lstat", "realpath", "access",
-            "file", "resolve", "permission", "validatePath", "fail", "snapshot", "integer"]) {
+            "file", "resolve", "permission", "validatePath", "fail", "snapshot", "integer", "releaseReference", "releaseNode"]) {
             const descriptor = Object.getOwnPropertyDescriptor(this, name)
                 ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
             if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)
@@ -545,8 +677,11 @@ export class MemoryFileSystem {
             unsupported();
         let node = this.file(path, "openReadFile");
         this.permission(node, 4, "openReadFile", path);
+        this.ledger.reserve(path.length * 2, 1, "openReadFile", path);
+        node.references++;
         const snapshot = this.snapshot.bind(this);
         const integer = this.integer.bind(this);
+        const releaseReference = this.releaseReference.bind(this);
         let closing;
         const current = (signal, syscall) => {
             signal?.throwIfAborted();
@@ -570,7 +705,10 @@ export class MemoryFileSystem {
                 return bytes;
             },
             close() {
-                node = undefined;
+                if (node) {
+                    releaseReference(node, path);
+                    node = undefined;
+                }
                 closing ??= Promise.resolve();
                 return closing;
             },
@@ -591,33 +729,55 @@ export class MemoryFileSystem {
         }
         const node = this.file(path, "readStream");
         this.permission(node, 4, "readStream", path);
+        this.ledger.reserve(path.length * 2, 1, "readStream", path);
+        node.references++;
+        const allocation = node.allocation;
+        allocation.retain();
         const data = node.data;
-        const end = Math.min(options.endExclusive ?? data.byteLength, data.byteLength);
-        node.atimeMs = Date.now();
-        for (let offset = start; offset < end; offset += chunkSize) {
+        try {
+            const end = Math.min(options.endExclusive ?? data.byteLength, data.byteLength);
+            node.atimeMs = Date.now();
+            for (let offset = start; offset < end; offset += chunkSize) {
+                options.signal?.throwIfAborted();
+                yield data.slice(offset, Math.min(offset + chunkSize, end));
+            }
             options.signal?.throwIfAborted();
-            yield data.slice(offset, Math.min(offset + chunkSize, end));
         }
-        options.signal?.throwIfAborted();
+        finally {
+            allocation.release();
+            this.releaseReference(node, path);
+        }
     }
     async writeStream(path, source, options = {}) {
         options.signal?.throwIfAborted();
-        const node = this.openWrite(path, options, "writeStream");
-        const append = options.flag === "a" || options.flag === "ax";
-        let position = 0;
-        if (!append) {
-            node.data = new Uint8Array();
-            this.changed(node);
-        }
-        for await (const chunk of source) {
+        this.validatePath(path, "writeStream");
+        this.ledger.reserve(path.length * 2, 1, "writeStream", path);
+        let node;
+        try {
+            node = this.openWrite(path, options, "writeStream");
+            node.references++;
+            const append = options.flag === "a" || options.flag === "ax";
+            let position = 0;
+            if (!append) {
+                this.replaceData(node, new MemoryAllocation(new Uint8Array(), this.ledger));
+                this.changed(node);
+            }
+            for await (const chunk of source) {
+                options.signal?.throwIfAborted();
+                if (!(chunk instanceof Uint8Array))
+                    throw new TypeError("Memory files require Uint8Array data");
+                this.writeAt(node, chunk, append ? node.data.byteLength : position, "writeStream", path);
+                if (!append)
+                    position += chunk.byteLength;
+            }
             options.signal?.throwIfAborted();
-            if (!(chunk instanceof Uint8Array))
-                throw new TypeError("Memory files require Uint8Array data");
-            this.writeAt(node, chunk, append ? node.data.byteLength : position, "writeStream", path);
-            if (!append)
-                position += chunk.byteLength;
         }
-        options.signal?.throwIfAborted();
+        finally {
+            if (node)
+                this.releaseReference(node, path);
+            else
+                this.ledger.release(path.length * 2, 1);
+        }
     }
 }
 const memoryImplementation = Object.getOwnPropertyDescriptors(MemoryFileSystem.prototype);
@@ -629,7 +789,8 @@ function stockDescriptorWrite(filesystem) {
         || Object.getOwnPropertyDescriptor(filesystem, "capabilities")?.value !== owner.capabilities)
         return false;
     for (const name of ["writeStream", "writeFile", "appendFile", "access", "stat", "lstat", "realpath",
-        "openWrite", "resolve", "permission", "validatePath", "mode", "bytes", "allocate", "changed", "metadata", "integer", "writeAt", "fail"]) {
+        "openWrite", "prepareWrite", "writeData", "addNode", "replaceData", "releaseReference", "releaseNode",
+        "resolve", "permission", "validatePath", "mode", "bytes", "allocate", "changed", "metadata", "integer", "writeAt", "fail"]) {
         const descriptor = Object.getOwnPropertyDescriptor(filesystem, name)
             ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
         if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)
@@ -637,6 +798,6 @@ function stockDescriptorWrite(filesystem) {
     }
     return true;
 }
-export function createMemoryFileSystem() {
-    return new MemoryFileSystem();
+export function createMemoryFileSystem(options = {}) {
+    return new MemoryFileSystem(normalizeMemoryFileSystemLimits(options));
 }

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

@@ -0,0 +1,20 @@
+import type { MemoryFileSystemLimits } from "./limits.js";
+export declare class MemoryLedger {
+    readonly limits: Readonly<MemoryFileSystemLimits>;
+    private retainedBytes;
+    private metadataUnits;
+    constructor(limits: Readonly<MemoryFileSystemLimits>);
+    get availableBytes(): number;
+    fileSize(length: number, syscall: string, path: string): void;
+    check(bytes: number, units: number, syscall: string, path: string): void;
+    reserve(bytes: number, units: number, syscall: string, path: string): void;
+    release(bytes: number, units: number): void;
+}
+export declare class MemoryAllocation {
+    readonly data: Uint8Array;
+    private readonly ledger;
+    private references;
+    constructor(data: Uint8Array, ledger: MemoryLedger);
+    retain(): void;
+    release(): void;
+}

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

@@ -0,0 +1,53 @@
+import { FsError } from "../../contracts/errors.js";
+export class MemoryLedger {
+    limits;
+    retainedBytes = 0;
+    metadataUnits = 0;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    get availableBytes() {
+        return this.limits.maxRetainedBytes - this.retainedBytes;
+    }
+    fileSize(length, syscall, path) {
+        if (!Number.isSafeInteger(length) || length < 0 || length > this.limits.maxFileBytes) {
+            throw new FsError("EFBIG", { syscall, path });
+        }
+    }
+    check(bytes, units, syscall, path) {
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.availableBytes ||
+            !Number.isSafeInteger(units) || units < 0 || units > this.limits.maxMetadataUnits - this.metadataUnits) {
+            throw new FsError("ENOSPC", { syscall, path });
+        }
+    }
+    reserve(bytes, units, syscall, path) {
+        this.check(bytes, units, syscall, path);
+        this.retainedBytes += bytes;
+        this.metadataUnits += units;
+    }
+    release(bytes, units) {
+        if (bytes < 0 || units < 0 || bytes > this.retainedBytes || units > this.metadataUnits) {
+            throw new Error("Invalid Memory filesystem reservation release");
+        }
+        this.retainedBytes -= bytes;
+        this.metadataUnits -= units;
+    }
+}
+export class MemoryAllocation {
+    data;
+    ledger;
+    references = 1;
+    constructor(data, ledger) {
+        this.data = data;
+        this.ledger = ledger;
+    }
+    retain() {
+        this.references++;
+    }
+    release() {
+        if (this.references <= 0)
+            throw new Error("Memory allocation already released");
+        if (--this.references === 0)
+            this.ledger.release(this.data.byteLength, 0);
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface MemoryFileSystemLimits {
+    readonly maxFileBytes: number;
+    readonly maxRetainedBytes: number;
+    readonly maxMetadataUnits: number;
+}
+export type MemoryFileSystemOptions = Partial<MemoryFileSystemLimits>;
+export declare const defaultMemoryFileSystemLimits: Readonly<MemoryFileSystemLimits>;
+export declare function normalizeMemoryFileSystemLimits(options: unknown): Readonly<MemoryFileSystemLimits>;

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

@@ -0,0 +1,19 @@
+import { readConfigRecord } from "../../config.js";
+export const defaultMemoryFileSystemLimits = Object.freeze({
+    maxFileBytes: 16 * 1024 * 1024,
+    maxRetainedBytes: 64 * 1024 * 1024,
+    maxMetadataUnits: 10_000,
+});
+export function normalizeMemoryFileSystemLimits(options) {
+    const keys = ["maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
+    const record = readConfigRecord(options, "memory option", keys);
+    const limits = { ...defaultMemoryFileSystemLimits };
+    for (const key of keys) {
+        const value = Object.hasOwn(record, key) ? record[key] : limits[key];
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "maxMetadataUnits" ? 1 : 0)) {
+            throw new RangeError(`${key} must be a ${key === "maxMetadataUnits" ? "positive" : "nonnegative"} safe integer`);
+        }
+        limits[key] = value;
+    }
+    return Object.freeze(limits);
+}

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

@@ -0,0 +1,2 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal): FileSystem;

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

@@ -0,0 +1,98 @@
+import { finishCleanup } from "../contracts/cleanup.js";
+import { registerEntryView } from "./mount/comparison.js";
+const originals = new WeakMap();
+const operations = new Set([
+    "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "readFile", "readStream", "readdir",
+    "readlink", "realpath", "rename", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
+    "writeFile", "writeStream",
+]);
+export function scopeFileSystem(filesystem, charge, signal) {
+    const original = originals.get(filesystem) ?? filesystem;
+    const methods = new Map();
+    const assertOpen = (options) => {
+        signal.throwIfAborted();
+        options?.signal?.throwIfAborted();
+    };
+    const admit = (options) => {
+        assertOpen(options);
+        charge();
+    };
+    const wrapHandle = (handle) => ({
+        async stat(options) { admit(options); return handle.stat(options); },
+        async read(position, maxBytes, options) { admit(options); return handle.read(position, maxBytes, options); },
+        close: handle.close.bind(handle),
+    });
+    const wrapStream = (source, options) => ({
+        [Symbol.asyncIterator]() {
+            assertOpen(options);
+            const iterator = source[Symbol.asyncIterator]();
+            let closing;
+            const close = (value) => closing ??= Promise.resolve().then(() => iterator.return ? iterator.return(value) : { done: true, value: undefined });
+            const advance = async (operation) => {
+                try {
+                    assertOpen(options);
+                    if (closing) {
+                        await closing;
+                        return { done: true, value: undefined };
+                    }
+                    const result = await operation();
+                    assertOpen(options);
+                    if (closing) {
+                        await closing;
+                        return { done: true, value: undefined };
+                    }
+                    return result;
+                }
+                catch (error) {
+                    await finishCleanup(close, true);
+                    throw error;
+                }
+            };
+            return {
+                next: () => advance(() => iterator.next()),
+                return: close,
+                ...(iterator.throw ? { throw: (error) => advance(() => iterator.throw(error)) } : {}),
+            };
+        },
+    });
+    const view = new Proxy(Object.create(original), {
+        set(_target, property, value) {
+            return Reflect.set(original, property, value, original);
+        },
+        get(_target, property) {
+            const method = Reflect.get(original, property, original);
+            if (typeof method !== "function")
+                return method;
+            const cached = methods.get(property);
+            if (cached?.original === method)
+                return cached.scoped;
+            const dispatch = (...args) => {
+                if (operations.has(property)) {
+                    const options = args.at(-1);
+                    admit(options && typeof options === "object" && "signal" in options ? options : undefined);
+                }
+                if (property === "compareEntry") {
+                    const peer = args[1];
+                    args[1] = originals.get(peer) ?? peer;
+                }
+                return Reflect.apply(method, original, args);
+            };
+            const scoped = property === "openReadFile"
+                ? async (...args) => wrapHandle(await dispatch(...args))
+                : property === "readStream"
+                    ? (...args) => wrapStream(dispatch(...args), args[1])
+                    : operations.has(property) && property !== "canonicalizeMissingTarget"
+                        ? async (...args) => dispatch(...args)
+                        : dispatch;
+            methods.set(property, { original: method, scoped });
+            return scoped;
+        },
+    });
+    originals.set(view, original);
+    registerEntryView(view, async (path, options) => {
+        assertOpen(options);
+        return { filesystem: original, path };
+    });
+    return view;
+}

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

@@ -9,6 +9,7 @@ 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 { scopeFileSystem } from "./fs/scoped.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";

package/dist/safe-fs/index.js

@@ -8,6 +8,7 @@ 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 { scopeFileSystem } from "./fs/scoped.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.250",
+  "version": "0.1.252",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",