@poe-platform/safe-fs 0.1.826 → 0.1.827

package/README.md

@@ -14,7 +14,10 @@ To bound aggregate pages across multiple live stores, pass the same
 `new PagedStorageCache(16)` as the third argument to each `PagedStorage` constructor.
 This shares a 256 KiB resident-page budget; `cache.residentBytes` reports current
 page retention. Eviction uses each store's filesystem, and each store still owns
-its `close()` cleanup. The budget excludes caller buffers and backend storage.
+its `close()` cleanup. Use `new PagedStorageCache(16, 65536)` to coalesce scratch
+I/O into 64 KiB pages within a 1 MiB budget, for example with object-backed files.
+Page sizes must be multiples of 16 KiB, up to 1 MiB; individual `read()` calls
+remain limited to 16 KiB. The budget excludes caller buffers and backend storage.
 Call `await storage.prepare()` before opening a directory iterator when its
 snapshot includes the scratch directory. It acquires and unlinks the backing
 handle up front, so later spills do not mutate that directory's namespace.
@@ -119,6 +122,8 @@ identities without a default device-count budget. Their optional `maxDevices` ac
 `Infinity` or a positive safe integer. Explicit budgets remain enforced; device numbers
 must still fit the disjoint application/runtime ranges of the uint32 Python stat ABI.
 
+Python filesystem directory cursors use `iterateDirectory` when available, share open-handle admission with files, and drain pending reads before cleanup. Backends without lazy enumeration retain the buffered `readdir` fallback.
+
 `withObjectFileDescriptors(fs, store)` supports large shell and Python descriptor
 writes when the host supplies `store.createStaging`: private externally backed
 pages keep working memory bounded without publishing the growing file after

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

@@ -12,6 +12,7 @@ export declare class MemoryLedger {
     get availableBytes(): number;
     canPreallocate64(nameBytes: number): boolean;
     fileSize(length: number, syscall: string, path: string): void;
+    private canReserve;
     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;

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

@@ -10,9 +10,9 @@ export class MemoryLedger {
     hasInfiniteRetained;
     constructor(limits) {
         this.limits = limits;
-        this.maxFileBytesSmi = limits.maxFileBytes >= MAX_SMI ? MAX_SMI : (limits.maxFileBytes | 0);
-        this.maxRetainedBytesSmi = limits.maxRetainedBytes >= MAX_SMI ? MAX_SMI : (limits.maxRetainedBytes | 0);
-        this.maxMetadataUnitsSmi = limits.maxMetadataUnits >= MAX_SMI ? MAX_SMI : (limits.maxMetadataUnits | 0);
+        this.maxFileBytesSmi = Math.min(limits.maxFileBytes, MAX_SMI) | 0;
+        this.maxRetainedBytesSmi = Math.min(limits.maxRetainedBytes, MAX_SMI) | 0;
+        this.maxMetadataUnitsSmi = Math.min(limits.maxMetadataUnits, MAX_SMI) | 0;
         this.hasInfiniteRetained = limits.maxRetainedBytes === Infinity;
         if (limits.maxFileBytes !== Infinity)
             this.hasInfiniteFileBytes = false;
@@ -31,27 +31,24 @@ export class MemoryLedger {
             throw new FsError("EFBIG", { syscall, path });
         }
     }
-    check(bytes, units, syscall, path) {
-        if ((bytes | 0) === bytes && bytes >= 0 &&
+    canReserve(bytes, units) {
+        return ((bytes | 0) === bytes && bytes >= 0 &&
             (units | 0) === units && units >= 0 &&
             this.retainedBytes <= this.maxRetainedBytesSmi - bytes &&
-            this.metadataUnits <= this.maxMetadataUnitsSmi - units) {
+            this.metadataUnits <= this.maxMetadataUnitsSmi - units);
+    }
+    check(bytes, units, syscall, path) {
+        if (this.canReserve(bytes, units))
             return;
-        }
-        const maxRetained = this.limits.maxRetainedBytes;
-        const maxUnits = this.limits.maxMetadataUnits;
         if (!Number.isSafeInteger(bytes) || bytes < 0 ||
-            (maxRetained !== Infinity && bytes > maxRetained - this.retainedBytes) ||
+            bytes > this.limits.maxRetainedBytes - this.retainedBytes ||
             !Number.isSafeInteger(units) || units < 0 ||
-            (maxUnits !== Infinity && units > maxUnits - this.metadataUnits)) {
+            units > this.limits.maxMetadataUnits - this.metadataUnits) {
             throw new FsError("ENOSPC", { syscall, path });
         }
     }
     reserve(bytes, units, syscall, path) {
-        if ((bytes | 0) === bytes && bytes >= 0 &&
-            (units | 0) === units && units >= 0 &&
-            this.retainedBytes <= this.maxRetainedBytesSmi - bytes &&
-            this.metadataUnits <= this.maxMetadataUnitsSmi - units) {
+        if (this.canReserve(bytes, units)) {
             this.retainedBytes = (this.retainedBytes + bytes) | 0;
             this.metadataUnits = (this.metadataUnits + units) | 0;
             return;
@@ -90,7 +87,4 @@ export class MemoryAllocation {
         }
     }
 }
-Object.assign(MemoryAllocation.prototype, {
-    references: 1,
-});
 Object.assign(MemoryLedger.prototype, { hasInfiniteFileBytes: true });

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

@@ -20,6 +20,7 @@ export interface ObjectFileAcquireOptions extends FsOptions {
 }
 export interface ObjectFileStaging {
     readPage(index: number, options?: FsOptions): Promise<Uint8Array | undefined>;
+    /** Own acknowledged bytes; the caller may reuse its buffer after settlement. */
     writePage(index: number, bytes: Uint8Array, options?: FsOptions): Promise<void>;
     truncate(size: number, options?: FsOptions): Promise<void>;
     close(): Promise<void>;

package/dist/safe-fs/fs/object-publication/index.js

@@ -28,16 +28,12 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
         while (stagedBytes + chunkBytes > maxStagedBytes || stagedBytes / chunkBytes >= maxStagedPages) {
             forwarded.signal?.throwIfAborted();
             await new Promise((resolve, reject) => {
-                const wake = () => {
+                const cleanup = () => {
                     stagingWaiters.delete(wake);
                     forwarded.signal?.removeEventListener("abort", abort);
-                    resolve();
-                };
-                const abort = () => {
-                    stagingWaiters.delete(wake);
-                    forwarded.signal?.removeEventListener("abort", abort);
-                    reject(forwarded.signal?.reason);
                 };
+                const wake = () => { cleanup(); resolve(); };
+                const abort = () => { cleanup(); reject(forwarded.signal?.reason); };
                 stagingWaiters.add(wake);
                 forwarded.signal?.addEventListener("abort", abort, { once: true });
                 if (forwarded.signal?.aborted)
@@ -87,9 +83,13 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             if (state.failure)
                 throw state.failure.reason;
         };
+        const requirePublication = (writable = true) => {
+            if (!store.publish || !writable)
+                throw new FsError("ENOTSUP", { path, message: "Object writes require authoritative conditional publication" });
+        };
         const perform = async (forwarded, action) => {
             check(forwarded);
-            const scope = composeAbortSignals([...(acquiring && admitted.signal ? [admitted.signal] : []), ...(forwarded.signal ? [forwarded.signal] : [])]);
+            const scope = composeAbortSignals([acquiring && admitted.signal, forwarded.signal].filter((signal) => !!signal));
             try {
                 const result = await action({ signal: scope.signal });
                 scope.signal.throwIfAborted();
@@ -163,8 +163,7 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             check(forwarded);
             if (!state.dirty)
                 return;
-            if (!store.publish)
-                throw new FsError("ENOTSUP", { path, message: "Object writes require authoritative conditional publication" });
+            requirePublication();
             const expected = state.head?.revision ?? null;
             let emitted = 0;
             let active = true;
@@ -174,7 +173,8 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             let streamScope;
             try {
                 await perform(forwarded, async (selected) => {
-                    streamScope = composeAbortSignals([...(selected.signal ? [selected.signal] : []), streamAbort.signal]);
+                    // perform always supplies its composed signal.
+                    streamScope = composeAbortSignals([selected.signal, streamAbort.signal]);
                     const bodyOptions = { signal: streamScope.signal };
                     source = (async function* () {
                         for (let position = 0; position < state.size; position += chunkBytes) {
@@ -230,8 +230,8 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
             const mutating = admitted.access !== "read" || admitted.creation !== "never" || admitted.truncate;
             if (mutating && capabilities.readOnly === true)
                 throw new FsError("EROFS", { path });
-            if (mutating && (!store.publish || capabilities.write === false))
-                throw new FsError("ENOTSUP", { path, message: "Object writes require authoritative conditional publication" });
+            if (mutating)
+                requirePublication(capabilities.write !== false);
             if (admitted.access !== "write" && capabilities.read === false)
                 throw new FsError("EACCES", { path });
             const acquired = await store.acquire(path, { access: admitted.access, ...(admitted.noFollow ? { noFollow: true } : {}), ...(admitted.signal ? { signal: admitted.signal } : {}) });
@@ -296,13 +296,18 @@ export function withObjectFileDescriptors(filesystem, store, options = {}) {
                                     const page = Math.floor(offset / chunkBytes);
                                     const within = offset % chunkBytes;
                                     const length = Math.min(buffer.byteLength - copied, chunkBytes - within);
-                                    let bytes = within === 0 && length === chunkBytes ? undefined : await readStagedPage(page, forwarded);
-                                    if (!bytes) {
-                                        bytes = new Uint8Array(chunkBytes);
-                                        if (within !== 0 || length !== chunkBytes)
-                                            bytes.set(await readBase(page * chunkBytes, chunkBytes, forwarded));
+                                    // Staging owns acknowledged bytes. Borrow complete pages until
+                                    // settlement; only partial writes need read/modify/write storage.
+                                    let bytes = buffer.subarray(copied, copied + length);
+                                    if (within || length !== chunkBytes) {
+                                        let previous = await readStagedPage(page, forwarded);
+                                        if (!previous) {
+                                            previous = new Uint8Array(chunkBytes);
+                                            previous.set(await readBase(page * chunkBytes, chunkBytes, forwarded));
+                                        }
+                                        previous.set(bytes, within);
+                                        bytes = previous;
                                     }
-                                    bytes.set(buffer.subarray(copied, copied + length), within);
                                     await perform(forwarded, selected => state.staging.writePage(page, bytes, selected));
                                     copied += length;
                                 }

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

@@ -7,6 +7,7 @@ export declare function scopeFileSystem(filesystem: FileSystem, charge: () => vo
 }): FileSystem;
 export interface RetainedFileSystemCleanupView {
     readonly removeFileConditional?: NonNullable<FileSystem["removeFileConditional"]>;
+    readonly removeTreeConditional?: NonNullable<FileSystem["removeTreeConditional"]>;
     readonly removeStagedFile?: NonNullable<FileSystem["removeStagedFile"]>;
     readonly lstat: FileSystem["lstat"];
     readonly realpath: FileSystem["realpath"];

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

@@ -82,16 +82,16 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             close() { closed = true; return close(); },
         };
     };
-    let cachedCallerSignal;
-    let cachedCombinedSignal;
+    let combinedSignals = new WeakMap();
     const combineSignal = (callerSignal) => {
         if (!callerSignal || callerSignal === signal)
             return signal;
-        if (callerSignal === cachedCallerSignal && cachedCombinedSignal)
-            return cachedCombinedSignal;
-        cachedCallerSignal = callerSignal;
-        cachedCombinedSignal = AbortSignal.any([signal, callerSignal]);
-        return cachedCombinedSignal;
+        let combined = combinedSignals.get(callerSignal);
+        if (!combined) {
+            combined = AbortSignal.any([signal, callerSignal]);
+            combinedSignals.set(callerSignal, combined);
+        }
+        return combined;
     };
     const resizeOptions = (options) => {
         const scopedOptions = {
@@ -557,8 +557,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
     retargeters.set(view, (nextCharge, nextSignal, nextCleanupCharge, nextMaxPathComponents) => {
         charge = nextCharge;
         if (signal !== nextSignal) {
-            cachedCallerSignal = undefined;
-            cachedCombinedSignal = undefined;
+            combinedSignals = new WeakMap();
         }
         signal = nextSignal;
         cleanupCharge = nextCleanupCharge;
@@ -612,8 +611,8 @@ export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
             if (typeof operation !== "function")
                 throw new FsError("ENOTSUP", { syscall: method, path });
             const parameters = method === "rm" ? { ...settings, recursive: false, force: false } : settings;
-            result = method === "removeStagedFile" || method === "removeFileConditional"
-                ? requireOwnedMutation(backing, path, method === "removeFileConditional" ? "atomicFileMutation" : "atomicFileStaging", settings ?? {}).then(() => Reflect.apply(operation, backing, [input, parameters]))
+            result = method === "removeStagedFile" || method === "removeFileConditional" || method === "removeTreeConditional"
+                ? requireOwnedMutation(backing, path, method === "removeFileConditional" ? "atomicFileMutation" : method === "removeTreeConditional" ? "atomicTreeRemoval" : "atomicFileStaging", settings ?? {}).then(() => Reflect.apply(operation, backing, [input, parameters]))
                 : Promise.resolve(Reflect.apply(operation, backing, [input, parameters]));
         }
         catch (error) {
@@ -625,14 +624,12 @@ export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
         pending.add(completion);
         return result;
     };
-    const view = Object.freeze(Object.assign(Object.create(null), {
-        ...(typeof backing.removeFileConditional === "function" ? { removeFileConditional: invoke.bind(undefined, "removeFileConditional") } : {}),
-        ...(typeof backing.removeStagedFile === "function" ? { removeStagedFile: invoke.bind(undefined, "removeStagedFile") } : {}),
-        lstat: invoke.bind(undefined, "lstat"),
-        realpath: invoke.bind(undefined, "realpath"),
-        rm: invoke.bind(undefined, "rm"),
-        ...(typeof backing.rmdir === "function" ? { rmdir: invoke.bind(undefined, "rmdir") } : {}),
-    }));
+    const view = Object.create(null);
+    for (const method of ["removeFileConditional", "removeStagedFile", "removeTreeConditional", "lstat", "realpath", "rm", "rmdir"]) {
+        if (method === "lstat" || method === "realpath" || method === "rm" || typeof backing[method] === "function")
+            Object.defineProperty(view, method, { value: invoke.bind(undefined, method), enumerable: true });
+    }
+    Object.freeze(view);
     scope?.signal.throwIfAborted();
     return () => {
         if (!closing) {

package/dist/safe-fs/python/directory.d.ts

@@ -0,0 +1,9 @@
+import type { FileSystem, FsOptions } from '../contracts/filesystem.js';
+/** One prefetched entry makes acquisition errors eager without buffering a listing. */
+export declare class PythonDirectory {
+    #private;
+    constructor(fs: FileSystem, path: string, options: FsOptions, limit: number);
+    prepare(): Promise<void>;
+    next(): Promise<string | null>;
+    close(): Promise<void>;
+}

package/dist/safe-fs/python/directory.js

@@ -0,0 +1,38 @@
+import { FsError } from '../contracts/errors.js';
+/** One prefetched entry makes acquisition errors eager without buffering a listing. */
+export class PythonDirectory {
+    #first;
+    #tail = Promise.resolve();
+    #closing;
+    #count = 0;
+    #iterator;
+    #options;
+    #limit;
+    constructor(fs, path, options, limit) {
+        this.#options = options;
+        this.#limit = limit;
+        const source = fs.iterateDirectory ? fs.iterateDirectory(path, options) : (async function* () { yield* await fs.readdir(path, { ...options, ...limit === Infinity ? {} : { maxEntries: limit } }); })();
+        this.#iterator = source[Symbol.asyncIterator]();
+    }
+    async prepare() { this.#first = await this.#iterator.next(); }
+    next() {
+        if (this.#closing)
+            return Promise.reject(new FsError('EBADF'));
+        const work = this.#tail.then(async () => {
+            this.#options.signal?.throwIfAborted();
+            const value = this.#first ?? await this.#iterator.next();
+            this.#first = undefined;
+            this.#options.signal?.throwIfAborted();
+            if (value.done)
+                return null;
+            if (++this.#count > this.#limit)
+                throw new FsError('EFBIG', { syscall: 'readdir' });
+            return value.value.name;
+        });
+        this.#tail = work.catch(() => { });
+        return work;
+    }
+    close() {
+        return this.#closing ??= this.#tail.then(async () => { this.#first = undefined; await this.#iterator.return?.(); });
+    }
+}

package/dist/safe-fs/python/emscripten.js

@@ -92,7 +92,20 @@ export function mountPythonFileSystem(FS, options) {
         close: (stream) => { if (stream.handle && --stream.retained.references === 0)
             rpc('close', stream.handle); },
         fsync: (stream) => { rpc('sync', stream.handle, false); return 0; },
-        read(stream, buffer, offset, length, position) { const data = rpc('read', stream.handle, Math.min(length, maxTransferBytes), stream.seekable ? position : null); buffer.set(data, offset); return data.length; },
+        read(stream, buffer, offset, length, position) {
+            let received = 0;
+            while (received < length) {
+                const requested = Math.min(length - received, maxTransferBytes);
+                const data = rpc('read', stream.handle, requested, stream.seekable ? position + received : null);
+                if (data.length > requested)
+                    throw new FS.ErrnoError(errno.EIO);
+                buffer.set(data, offset + received);
+                received += data.length;
+                if (data.length < requested || !stream.seekable)
+                    break;
+            }
+            return received;
+        },
         write: (stream, buffer, offset, length, position) => rpc('write', stream.handle, Uint8Array.from(buffer.subarray(offset, offset + Math.min(length, maxTransferBytes))), stream.pythonExplicitPosition ?? (stream.flags & 1024 || !stream.seekable ? null : position)),
         llseek(stream, offset, whence) { if (![0, 1, 2].includes(whence) || !Number.isSafeInteger(offset))
             throw new FS.ErrnoError(errno.EINVAL); const position = whence === 0 ? offset : whence === 1 ? stream.position + offset : rpc('fstat', stream.handle).size + offset; if (!Number.isSafeInteger(position) || position < 0)

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

@@ -9,7 +9,7 @@ export type PythonFsRequest = {
     readonly op: "write";
     readonly args: readonly [number, Uint8Array, number | null];
 } | {
-    readonly op: "fstat" | "close" | "position" | "descriptorCapabilities";
+    readonly op: "directoryNext" | "fstat" | "close" | "position" | "descriptorCapabilities";
     readonly args: readonly [number];
 } | {
     readonly op: "ftruncate";
@@ -18,7 +18,7 @@ export type PythonFsRequest = {
     readonly op: "sync";
     readonly args: readonly [number, boolean];
 } | {
-    readonly op: "stat" | "lstat" | "readdir" | "realpath" | "readlink" | "rm" | "rmdir" | "rmtree" | "rmtreeSupported";
+    readonly op: "directoryOpen" | "stat" | "lstat" | "readdir" | "realpath" | "readlink" | "rm" | "rmdir" | "rmtree" | "rmtreeSupported";
     readonly args: readonly [string];
 } | {
     readonly op: "rename" | "symlink" | "link";

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

@@ -1,3 +1,4 @@
+import { PythonDirectory } from "./directory.js";
 import { parsePythonFsRequest } from "./request.js";
 import { composeAbortSignals } from "../contracts/abort.js";
 import { FsError } from "../contracts/errors.js";
@@ -57,10 +58,37 @@ export class PythonFileSystem {
     }
     #handle(id) {
         const handle = this.#handles.get(id);
-        if (!handle)
+        if (!handle || handle instanceof PythonDirectory)
             throw new FsError("EBADF");
         return handle;
     }
+    async #acquire(open) {
+        if (this.#handles.size + this.#acquiring >= this.#limit || !Number.isSafeInteger(this.#next))
+            throw new FsError("EMFILE", { syscall: "open" });
+        this.#acquiring++;
+        let handle;
+        try {
+            handle = await open();
+            if (handle instanceof PythonDirectory)
+                await handle.prepare();
+            this.#scope.signal.throwIfAborted();
+            const id = this.#next++;
+            this.#handles.set(id, handle);
+            return id;
+        }
+        catch (error) {
+            if (handle)
+                try {
+                    await handle.close();
+                }
+                catch { /* Preserve acquisition failure. */ }
+            this.#scope.signal.throwIfAborted();
+            throw error;
+        }
+        finally {
+            this.#acquiring--;
+        }
+    }
     #size(size) {
         if (!Number.isSafeInteger(size) || size < 0)
             throw new FsError("EINVAL");
@@ -70,7 +98,9 @@ export class PythonFileSystem {
     async #execute(request) {
         if (request.op === "close") {
             const [id] = request.args;
-            const handle = this.#handle(id);
+            const handle = this.#handles.get(id);
+            if (!handle)
+                throw new FsError("EBADF");
             this.#handles.delete(id);
             await handle.close({ signal: this.#scope.signal });
             return;
@@ -82,40 +112,25 @@ export class PythonFileSystem {
         switch (request.op) {
             case "open": {
                 const [path, supplied] = request.args;
-                if (this.#handles.size + this.#acquiring >= this.#limit || !Number.isSafeInteger(this.#next))
-                    throw new FsError("EMFILE", { syscall: "open" });
-                if (!this.#open && !fs.open)
-                    throw new FsError("ENOTSUP", { syscall: "open", path });
-                this.#acquiring++;
-                let handle;
-                try {
-                    // A following capability query cannot preflight exclusive final-entry acquisition.
-                    // The canonical open remains authoritative for selected-path policy and atomic refusal.
+                return this.#acquire(async () => {
+                    if (!this.#open && !fs.open)
+                        throw new FsError("ENOTSUP", { syscall: "open", path });
+                    // Exclusive creation must reach the canonical atomic operation directly.
                     const capabilities = supplied.creation !== "exclusive" && fs.capabilitiesFor ? await fs.capabilitiesFor(this.#path(path), { signal, ...(supplied.creation === "ifMissing" ? { create: true } : {}) }) : fs.capabilities;
                     if (capabilities.readOnly === true && (supplied.access === "write" || supplied.access === "readwrite" || supplied.creation === "ifMissing" || supplied.creation === "exclusive" || supplied.truncate === true || supplied.append === true))
                         throw new FsError("EROFS", { syscall: "open", path });
                     if (capabilities.open === false)
                         throw new FsError("ENOTSUP", { syscall: "open", path });
                     signal.throwIfAborted();
-                    const open = this.#open ?? fs.open.bind(fs);
-                    handle = await open(this.#path(path), { ...supplied, signal });
-                    signal.throwIfAborted();
-                    const id = this.#next++;
-                    this.#handles.set(id, handle);
-                    return id;
-                }
-                catch (error) {
-                    if (handle)
-                        try {
-                            await handle.close();
-                        }
-                        catch { /* Preserve the acquisition failure. */ }
-                    signal.throwIfAborted();
-                    throw error;
-                }
-                finally {
-                    this.#acquiring--;
-                }
+                    return (this.#open ?? fs.open.bind(fs))(this.#path(path), { ...supplied, signal });
+                });
+            }
+            case "directoryOpen": return this.#acquire(() => new PythonDirectory(fs, this.#path(request.args[0]), options, this.#directoryLimit));
+            case "directoryNext": {
+                const handle = this.#handles.get(request.args[0]);
+                if (!(handle instanceof PythonDirectory))
+                    throw new FsError("EBADF");
+                return handle.next();
             }
             case "descriptorCapabilities": return { ...this.#handle(request.args[0]).capabilities };
             case "fstat": return this.#handle(request.args[0]).stat(options);

package/dist/safe-fs/python/native.js

@@ -165,7 +165,7 @@ export function createPythonNativeSyscalls(options) {
                 if (entry && !positioned)
                     entry.position = writing && entry.flags & 1024
                         ? await request('position', entry.handle) : entry.position + transferred;
-                if (transferred < size || !writing) {
+                if (transferred < size || !writing && !entry?.seekable) {
                     view().setUint32(output, total, true);
                     return 0;
                 }

package/dist/safe-fs/python/request.js

@@ -2,6 +2,7 @@ import { FsError } from "../contracts/errors.js";
 const argumentKinds = {
     open: ["string", "object"], read: ["number", "number", "position"], write: ["number", "bytes", "position"],
     descriptorCapabilities: ["number"], fstat: ["number"], close: ["number"], position: ["number"], ftruncate: ["number", "number"], sync: ["number", "boolean"],
+    directoryOpen: ["string"], directoryNext: ["number"],
     stat: ["string"], lstat: ["string"], readdir: ["string"], realpath: ["string"], readlink: ["string"], rm: ["string"], rmdir: ["string"], rmtree: ["string"], rmtreeSupported: ["string"],
     rename: ["string", "string"], symlink: ["string", "string"], link: ["string", "string"], mkdir: ["string", "optionalObject"],
     chmod: ["string", "number"], truncate: ["string", "number"], access: ["string", "number"], utimes: ["string", "number", "number"],

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

@@ -13,9 +13,10 @@ type Page = {
  * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
 export declare class PagedStorageCache {
     private readonly maxPages;
+    readonly pageBytes: number;
     private readonly pages;
     private active;
-    constructor(maxPages: number);
+    constructor(maxPages: number, pageBytes?: number);
     get residentBytes(): number;
     run<T>(action: () => Promise<T>): Promise<T>;
     acquire(): Promise<Page>;
@@ -31,6 +32,7 @@ export declare class PagedStorage {
     private readonly maxPages;
     private readonly cache?;
     private readonly pages;
+    private readonly pageBytes;
     private readonly controller;
     private readonly signal;
     private descriptor;

package/dist/safe-fs/storage.js

@@ -1,18 +1,22 @@
 import { FsError, isFsError } from "./contracts/errors.js";
-const pageBytes = 16 * 1024;
+const defaultPageBytes = 16 * 1024;
 let serial = 0;
 /** Shares one resident-page limit across stores, retaining each store's caller
  * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
 export class PagedStorageCache {
     maxPages;
+    pageBytes;
     pages = new Map();
     active = Promise.resolve();
-    constructor(maxPages) {
+    constructor(maxPages, pageBytes = defaultPageBytes) {
         this.maxPages = maxPages;
+        this.pageBytes = pageBytes;
+        if (!Number.isSafeInteger(pageBytes) || pageBytes < defaultPageBytes || pageBytes > 1024 * 1024 || pageBytes % defaultPageBytes !== 0)
+            throw new RangeError("Invalid storage page size");
         if (!Number.isSafeInteger(maxPages) || maxPages < 1)
             throw new RangeError("Invalid storage page cache size");
     }
-    get residentBytes() { return this.pages.size * pageBytes; }
+    get residentBytes() { return this.pages.size * this.pageBytes; }
     run(action) {
         const work = this.active.then(action);
         this.active = work.then(() => undefined, () => undefined);
@@ -20,7 +24,7 @@ export class PagedStorageCache {
     }
     async acquire() {
         if (this.pages.size < this.maxPages)
-            return { bytes: new Uint8Array(pageBytes), dirty: false };
+            return { bytes: new Uint8Array(this.pageBytes), dirty: false };
         const [page, release] = this.pages.entries().next().value;
         await release();
         this.pages.delete(page);
@@ -46,6 +50,7 @@ export class PagedStorage {
     maxPages;
     cache;
     pages = new Map();
+    pageBytes;
     controller = new AbortController();
     signal;
     descriptor;
@@ -63,6 +68,7 @@ export class PagedStorage {
         this.cache = cache;
         if (!Number.isSafeInteger(maxPages) || maxPages < 1)
             throw new RangeError("Invalid storage page cache size");
+        this.pageBytes = cache?.pageBytes ?? defaultPageBytes;
         this.signal = AbortSignal.any([context.signal, this.controller.signal]);
     }
     allocate(length) {
@@ -129,15 +135,15 @@ export class PagedStorage {
         if (!page.dirty)
             return;
         let offset = 0;
-        while (offset < pageBytes) {
+        while (offset < this.pageBytes) {
             this.signal.throwIfAborted();
-            const count = await this.descriptor.write(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+            const count = await this.descriptor.write(page.bytes.subarray(offset), number * this.pageBytes + offset, { signal: this.signal });
             this.signal.throwIfAborted();
-            if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+            if (!Number.isSafeInteger(count) || count <= 0 || count > this.pageBytes - offset)
                 throw new FsError("EIO");
             offset += count;
         }
-        this.diskLength = Math.max(this.diskLength, (number + 1) * pageBytes);
+        this.diskLength = Math.max(this.diskLength, (number + 1) * this.pageBytes);
         page.dirty = false;
     }
     async page(number) {
@@ -161,17 +167,17 @@ export class PagedStorage {
         }
         // Flush owns the bytes until its awaited write completes. Reuse only then;
         // zero new/unwritten ranges so the previous page cannot leak into them.
-        const page = reusable ?? (this.cache ? await this.cache.acquire() : { bytes: new Uint8Array(pageBytes), dirty: false });
+        const page = reusable ?? (this.cache ? await this.cache.acquire() : { bytes: new Uint8Array(this.pageBytes), dirty: false });
         // Shared eviction may await IO owned by a different, still-live signal.
         this.signal.throwIfAborted();
         if (reusable)
             page.bytes.fill(0);
-        if (number * pageBytes < this.diskLength) {
+        if (number * this.pageBytes < this.diskLength) {
             let offset = 0;
-            while (offset < pageBytes) {
-                const count = await this.descriptor.read(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+            while (offset < this.pageBytes) {
+                const count = await this.descriptor.read(page.bytes.subarray(offset), number * this.pageBytes + offset, { signal: this.signal });
                 this.signal.throwIfAborted();
-                if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+                if (!Number.isSafeInteger(count) || count <= 0 || count > this.pageBytes - offset)
                     throw new FsError("EIO");
                 offset += count;
             }
@@ -191,9 +197,9 @@ export class PagedStorage {
         return this.operation(async () => {
             for (let offset = 0; offset < bytes.length;) {
                 const target = position + offset;
-                const page = await this.page(Math.floor(target / pageBytes));
-                const count = Math.min(bytes.length - offset, pageBytes - target % pageBytes);
-                page.bytes.set(bytes.subarray(offset, offset + count), target % pageBytes);
+                const page = await this.page(Math.floor(target / this.pageBytes));
+                const count = Math.min(bytes.length - offset, this.pageBytes - target % this.pageBytes);
+                page.bytes.set(bytes.subarray(offset, offset + count), target % this.pageBytes);
                 page.dirty = true;
                 offset += count;
             }
@@ -205,15 +211,15 @@ export class PagedStorage {
         return position;
     }
     read(position, length) {
-        if (!Number.isSafeInteger(position) || position < 8 || !Number.isSafeInteger(length) || length < 0 || length > pageBytes || position + length > this.end)
+        if (!Number.isSafeInteger(position) || position < 8 || !Number.isSafeInteger(length) || length < 0 || length > defaultPageBytes || position + length > this.end)
             throw new RangeError("Invalid paged storage range");
         return this.operation(async () => {
             const bytes = new Uint8Array(length);
             for (let offset = 0; offset < length;) {
                 const source = position + offset;
-                const page = await this.page(Math.floor(source / pageBytes));
-                const count = Math.min(length - offset, pageBytes - source % pageBytes);
-                bytes.set(page.bytes.subarray(source % pageBytes, source % pageBytes + count), offset);
+                const page = await this.page(Math.floor(source / this.pageBytes));
+                const count = Math.min(length - offset, this.pageBytes - source % this.pageBytes);
+                bytes.set(page.bytes.subarray(source % this.pageBytes, source % this.pageBytes + count), offset);
                 offset += count;
             }
             return bytes;

package/package.json

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