@poe-platform/safe-fs 0.1.630 → 0.1.631

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

@@ -0,0 +1,354 @@
+import { translatePythonOpenFlags } from './flags.js';
+export function mountPythonFileSystem(FS, options) {
+    const { request: rpc, cwd, runtimeMount, maxTransferBytes, errno, synchronizationFlags } = options;
+    const canonicalStat = Symbol('canonical Python stat');
+    const runtimeDevices = createPythonRuntimeStatMapper();
+    const mapRuntimeStat = (stat) => {
+        try {
+            return runtimeDevices(stat);
+        }
+        catch {
+            throw new FS.ErrnoError(errno.EOVERFLOW);
+        }
+    };
+    const originalWriteStat = options.runtimeModule.SYSCALLS.writeStat;
+    options.runtimeModule.SYSCALLS.writeStat = (pointer, stat) => {
+        if (!stat[canonicalStat]) {
+            try {
+                return originalWriteStat(pointer, mapRuntimeStat(stat));
+            }
+            catch {
+                throw new FS.ErrnoError(errno.EOVERFLOW);
+            }
+        }
+        try {
+            return writePythonStat(options.runtimeModule.HEAPU8, pointer, stat);
+        }
+        catch {
+            throw new FS.ErrnoError(errno.EOVERFLOW);
+        }
+    };
+    function path(node) { return node.parent === node ? "/" : `${path(node.parent) === '/' ? '' : path(node.parent)}/${node.name}`; }
+    function attr(stat) {
+        return { [canonicalStat]: true, dev: stat.dev, ino: stat.ino, mode: stat.mode | (stat.type === 'directory' ? 16384 : stat.type === 'symlink' ? 40960 : stat.type === 'character' ? 8192 : 32768), nlink: stat.nlink, uid: stat.uid, gid: stat.gid, rdev: stat.type === 'character' ? undefined : 0, size: stat.size, atime: new Date(stat.atimeMs), mtime: new Date(stat.mtimeMs), ctime: new Date(stat.ctimeMs), atimeMs: stat.atimeMs, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, blksize: stat.ioBlockSize ?? stat.preferredIoBlockSize, blocks: stat.allocatedBytes === undefined ? undefined : Math.ceil(stat.allocatedBytes / 512) };
+    }
+    function node(parent, name, stat) {
+        const value = FS.createNode(parent, name, attr(stat).mode, 0);
+        value.node_ops = nodeOps;
+        value.stream_ops = streamOps;
+        return value;
+    }
+    let bootstrapMountNode;
+    const nodeOps = {
+        getattr: (n) => attr(n === bootstrapMountNode ? { type: 'directory', mode: 365, size: 0, atimeMs: 0, mtimeMs: 0, ctimeMs: 0 } : rpc('lstat', path(n))),
+        setattr(n, attributes) {
+            if (attributes.size !== undefined)
+                rpc('truncate', path(n), attributes.size);
+            if (attributes.mode !== undefined)
+                rpc('chmod', path(n), attributes.mode & 4095);
+            if (attributes.atime !== undefined || attributes.mtime !== undefined) {
+                const previous = attributes.atime === undefined || attributes.mtime === undefined ? rpc('stat', path(n)) : undefined;
+                rpc('utimes', path(n), attributes.atime ?? previous.atimeMs, attributes.mtime ?? previous.mtimeMs);
+            }
+        },
+        lookup(parent, name) {
+            if (parent.parent === parent && name === runtimeMount.slice(1))
+                return bootstrapMountNode ??= node(parent, name, { type: 'directory', mode: 365, size: 0, atimeMs: 0, mtimeMs: 0, ctimeMs: 0 });
+            return node(parent, name, rpc('lstat', `${path(parent)}/${name}`));
+        },
+        mknod(parent, name, mode) {
+            const target = `${path(parent)}/${name}`;
+            if (FS.isDir(mode))
+                rpc('mkdir', target, { mode: mode & 4095 });
+            else {
+                const handle = rpc('open', target, { access: 'write', creation: 'exclusive', mode: mode & 4095 });
+                rpc('close', handle);
+            }
+            return node(parent, name, rpc('lstat', target));
+        },
+        rename(n, parent, name) { rpc('rename', path(n), `${path(parent)}/${name}`); n.name = name; n.parent = parent; },
+        unlink: (parent, name) => rpc('rm', `${path(parent)}/${name}`),
+        rmdir: (parent, name) => rpc('rmdir', `${path(parent)}/${name}`),
+        readdir: (n) => ['.', '..', ...rpc('readdir', path(n)).map((entry) => entry.name)],
+        readlink: (n) => rpc('readlink', path(n)),
+        symlink(parent, name, target) { rpc('symlink', target, `${path(parent)}/${name}`); return node(parent, name, rpc('lstat', `${path(parent)}/${name}`)); },
+    };
+    const streamOps = {
+        getattr: (stream) => attr(stream.handle ? rpc('fstat', stream.handle) : rpc('stat', path(stream.node))),
+        setattr(stream, attributes) {
+            if (Object.keys(attributes).some(key => key !== 'size' && key !== 'ctime' && !(key === 'timestamp' && attributes.size !== undefined)))
+                throw new FS.ErrnoError(errno.ENOTSUP);
+            if (attributes.size !== undefined)
+                rpc('ftruncate', stream.handle, attributes.size);
+        },
+        open(stream) {
+            if (FS.isDir(stream.node.mode))
+                return;
+            stream.retained = { references: 1 };
+            stream.handle = rpc('open', path(stream.node), { access: (stream.flags & 3) === 0 ? 'read' : (stream.flags & 3) === 1 ? 'write' : 'readwrite', creation: 'never', append: Boolean(stream.flags & 1024) });
+        },
+        dup: (stream) => { if (stream.retained)
+            stream.retained.references++; },
+        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; },
+        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)
+            throw new FS.ErrnoError(28); return position; },
+    };
+    const originalLookupNode = FS.lookupNode.bind(FS);
+    FS.lookupNode = (parent, name) => {
+        const cached = originalLookupNode(parent, name);
+        return parent.node_ops === nodeOps && !cached.mounted ? nodeOps.lookup(parent, name) : cached;
+    };
+    const bootstrapRoot = FS.root;
+    FS.root = null;
+    FS.mount({ mount: () => node(null, '/', rpc('stat', '/')) }, {}, '/');
+    FS.mount({ mount: () => bootstrapRoot }, {}, runtimeMount);
+    FS.chdir(rpc('realpath', cwd));
+    // Intercept before Emscripten decomposes atomic exclusive/truncating open.
+    const originalOpen = FS.open.bind(FS);
+    FS.open = function (inputPath, flags, mode = 438) {
+        if (typeof flags === 'string') {
+            const modes = { r: 0, 'r+': 2, w: 577, 'w+': 578, a: 1089, 'a+': 1090 };
+            const numeric = modes[flags];
+            if (numeric === undefined)
+                throw new FS.ErrnoError(errno.EINVAL);
+            flags = numeric;
+        }
+        if (typeof inputPath !== 'string') {
+            if ((flags & 3) !== 0 || (flags & (64 | 512)))
+                throw new FS.ErrnoError(errno.EROFS);
+            return originalOpen(inputPath, flags, mode);
+        }
+        if (inputPath.length === 0)
+            throw new FS.ErrnoError(errno.ENOENT);
+        const absolute = inputPath.startsWith('/') ? inputPath : `${FS.cwd()}/${inputPath}`;
+        if (absolute === runtimeMount || absolute.startsWith(runtimeMount + '/')) {
+            if (absolute.split('/').includes('..'))
+                throw new FS.ErrnoError(errno.ENOTSUP);
+            if (typeof flags !== 'number' || (flags & 3) !== 0 || (flags & (64 | 512)))
+                throw new FS.ErrnoError(errno.EROFS);
+            return originalOpen(inputPath, flags, mode);
+        }
+        if (typeof flags !== 'number')
+            return originalOpen(inputPath, flags, mode);
+        if (flags & synchronizationFlags)
+            throw new FS.ErrnoError(errno.ENOTSUP);
+        // Atomic exclusive creation already refuses symlinks and all existing entries.
+        const exclusive = (flags & 192) === 192;
+        if ((flags & 131072) && !exclusive)
+            throw new FS.ErrnoError(138);
+        if (flags & 65536)
+            throw new FS.ErrnoError(54);
+        let openOptions;
+        try {
+            openOptions = translatePythonOpenFlags(flags, mode);
+        }
+        catch (error) {
+            throw new FS.ErrnoError(errno[error.code] ?? errno.EIO);
+        }
+        const handle = rpc('open', absolute, openOptions);
+        try {
+            // Bind the stream to the acquired identity, without re-opening its pathname.
+            // A concurrent rename or unlink after acquisition must not invalidate open().
+            const capabilities = rpc('descriptorCapabilities', handle);
+            if ((flags & 1024) && !capabilities.position)
+                throw new FS.ErrnoError(errno.ENOTSUP);
+            const seekable = ((flags & 3) === 1 || capabilities.positionedRead) && ((flags & 3) === 0 || ((flags & 1024) ? capabilities.position : capabilities.positionedWrite));
+            const retainedStat = rpc('fstat', handle);
+            if (retainedStat.type === 'directory')
+                throw new FS.ErrnoError(errno.ENOTSUP);
+            const retainedNode = node(FS.root, absolute.slice(1), retainedStat);
+            return FS.createStream({ node: retainedNode, path: absolute, flags: flags & ~(128 | 512), seekable, position: 0, stream_ops: streamOps, ungotten: [], error: false, handle, pythonCapabilities: capabilities, retained: { references: 1 } });
+        }
+        catch (error) {
+            rpc('close', handle);
+            throw error;
+        }
+    };
+    // Pass application operands intact to the authoritative resolver. Emscripten's
+    // lexical dot-segment normalization must not run before canonical symlink traversal.
+    const absolutePath = (target) => target.length === 0 || target.startsWith('/') ? target : `${FS.cwd()}/${target}`;
+    const bootstrapPath = (target) => {
+        const absolute = absolutePath(target);
+        const bootstrap = absolute === runtimeMount || absolute.startsWith(runtimeMount + '/');
+        if (bootstrap && absolute.split('/').includes('..'))
+            throw new FS.ErrnoError(errno.ENOTSUP);
+        return bootstrap;
+    };
+    for (const operation of ['stat', 'lstat']) {
+        const original = FS[operation].bind(FS);
+        FS[operation] = (target, ...args) => bootstrapPath(target)
+            ? mapRuntimeStat(original(target, ...args)) : attr(rpc(operation, absolutePath(target)));
+    }
+    const originalFstat = FS.fstat.bind(FS);
+    FS.fstat = (fd) => {
+        const value = originalFstat(fd);
+        return value[canonicalStat] ? value : mapRuntimeStat(value);
+    };
+    for (const [operation, canonical] of [['unlink', 'rm'], ['rmdir', 'rmdir'], ['chmod', 'chmod'], ['truncate', 'truncate'], ['utime', 'utimes']]) {
+        const original = FS[operation].bind(FS);
+        FS[operation] = (target, ...args) => bootstrapPath(target)
+            ? original(target, ...args) : rpc(canonical, absolutePath(target), ...args);
+    }
+    const originalMkdir = FS.mkdir.bind(FS);
+    FS.mkdir = (target, mode = 0o777) => {
+        if (bootstrapPath(target))
+            return originalMkdir(target, mode);
+        const absolute = absolutePath(target);
+        rpc('mkdir', absolute, { mode });
+        return node(FS.root, absolute.slice(1), rpc('lstat', absolute));
+    };
+    const originalRename = FS.rename.bind(FS);
+    FS.rename = (source, destination) => bootstrapPath(source) || bootstrapPath(destination)
+        ? originalRename(source, destination) : rpc('rename', absolutePath(source), absolutePath(destination));
+    const originalChdir = FS.chdir.bind(FS);
+    FS.chdir = (target) => bootstrapPath(target) ? originalChdir(target) : originalChdir(rpc('realpath', absolutePath(target)));
+    const runtimeNode = (node) => {
+        const seen = new Set();
+        while (node && !seen.has(node)) {
+            if (node === bootstrapRoot || node.mount?.mountpoint === runtimeMount)
+                return true;
+            seen.add(node);
+            node = node.parent;
+        }
+        return false;
+    };
+    const assertWritablePath = (target) => {
+        if (bootstrapPath(target))
+            throw new FS.ErrnoError(errno.EROFS);
+    };
+    const originalSymlink = FS.symlink.bind(FS);
+    FS.symlink = (source, destination) => bootstrapPath(destination)
+        ? originalSymlink(source, destination) : rpc('symlink', source, absolutePath(destination));
+    const originalReaddir = FS.readdir.bind(FS);
+    FS.readdir = (target) => bootstrapPath(target) ? originalReaddir(target)
+        : ['.', '..', ...rpc('readdir', absolutePath(target)).map((entry) => entry.name)];
+    const originalReadlink = FS.readlink.bind(FS);
+    FS.readlink = (target) => bootstrapPath(target) ? originalReadlink(target) : rpc('readlink', absolutePath(target));
+    for (const operation of ['chown', 'lchown', 'lchmod']) {
+        FS[operation] = (target) => { assertWritablePath(target); throw new FS.ErrnoError(errno.ENOTSUP); };
+    }
+    const originalMknod = FS.mknod.bind(FS);
+    FS.mknod = (target, mode, device) => {
+        if (bootstrapPath(target))
+            return originalMknod(target, mode, device);
+        if (!FS.isFile(mode))
+            throw new FS.ErrnoError(errno.ENOTSUP);
+        const handle = rpc('open', absolutePath(target), { access: 'write', creation: 'exclusive', mode: mode & 4095 });
+        rpc('close', handle);
+        return node(FS.root, absolutePath(target).slice(1), rpc('lstat', absolutePath(target)));
+    };
+    for (const operation of ['mkdir', 'mknod', 'unlink', 'rmdir', 'chmod', 'lchmod', 'chown', 'lchown', 'truncate', 'utime']) {
+        if (typeof FS[operation] !== 'function')
+            continue;
+        const original = FS[operation].bind(FS);
+        FS[operation] = (target, ...args) => { assertWritablePath(target); return original(target, ...args); };
+    }
+    for (const operation of ['rename', 'symlink']) {
+        const original = FS[operation].bind(FS);
+        FS[operation] = (source, destination, ...args) => {
+            if (operation === 'rename')
+                assertWritablePath(source);
+            assertWritablePath(destination);
+            return original(source, destination, ...args);
+        };
+    }
+    for (const operation of ['fchmod', 'fchown', 'ftruncate']) {
+        if (typeof FS[operation] !== 'function')
+            continue;
+        const original = FS[operation].bind(FS);
+        FS[operation] = (fd, ...args) => {
+            if (runtimeNode(FS.getStreamChecked(fd).node))
+                throw new FS.ErrnoError(errno.EROFS);
+            return original(fd, ...args);
+        };
+    }
+    const originalWrite = FS.write.bind(FS);
+    FS.write = (stream, ...args) => {
+        if (stream.fd > 2 && runtimeNode(stream.node))
+            throw new FS.ErrnoError(errno.EROFS);
+        const explicit = typeof args[3] === 'number';
+        if (stream.handle && (stream.flags & 1024) && explicit && !stream.pythonCapabilities.positionedAppendWrite)
+            throw new FS.ErrnoError(errno.EINVAL);
+        const previousPosition = stream.position;
+        stream.pythonExplicitPosition = explicit ? args[3] : undefined;
+        let written;
+        try {
+            written = originalWrite(stream, ...args);
+        }
+        finally {
+            stream.pythonExplicitPosition = undefined;
+            if (explicit)
+                stream.position = previousPosition;
+        }
+        if (stream.handle && (stream.flags & 1024) && args[3] === undefined)
+            stream.position = rpc('position', stream.handle);
+        return written;
+    };
+}
+/** Encode the pinned wasm32 musl stat layout without truncating canonical values. */
+export function writePythonStat(heap, pointer, stat) {
+    const view = new DataView(heap.buffer, heap.byteOffset, heap.byteLength);
+    const integer = (key, max) => {
+        const value = stat[key];
+        if (!Number.isSafeInteger(value) || value < 0 || value > max)
+            throw new Error('EOVERFLOW');
+        return value;
+    };
+    const values = {
+        dev: integer('dev', 0xffffffff), mode: integer('mode', 0xffffffff),
+        nlink: integer('nlink', 0xffffffff), uid: integer('uid', 0xffffffff),
+        gid: integer('gid', 0xffffffff), rdev: integer('rdev', 0xffffffff),
+        size: integer('size', Number.MAX_SAFE_INTEGER), ino: integer('ino', Number.MAX_SAFE_INTEGER),
+        blksize: integer('blksize', 0x7fffffff), blocks: integer('blocks', 0x7fffffff),
+    };
+    const times = ['atime', 'mtime', 'ctime'].map(key => {
+        const time = stat[key + 'Ms'] ?? stat[key]?.getTime();
+        if (!Number.isFinite(time))
+            throw new Error('EOVERFLOW');
+        let seconds = Math.floor(time / 1000);
+        let nanoseconds = Math.round((time - seconds * 1000) * 1000000);
+        if (nanoseconds === 1000000000) {
+            seconds++;
+            nanoseconds = 0;
+        }
+        if (!Number.isSafeInteger(seconds) || nanoseconds < 0 || nanoseconds >= 1000000000)
+            throw new Error('EOVERFLOW');
+        return { seconds, nanoseconds };
+    });
+    if (!Number.isSafeInteger(pointer) || pointer < 0 || pointer + 96 > heap.byteLength)
+        throw new Error('EOVERFLOW');
+    for (const [index, key] of ['dev', 'mode', 'nlink', 'uid', 'gid', 'rdev'].entries())
+        view.setUint32(pointer + index * 4, values[key], true);
+    view.setBigInt64(pointer + 24, BigInt(values.size), true);
+    view.setInt32(pointer + 32, values.blksize, true);
+    view.setInt32(pointer + 36, values.blocks, true);
+    times.forEach((time, index) => { view.setBigInt64(pointer + 40 + index * 16, BigInt(time.seconds), true); view.setUint32(pointer + 48 + index * 16, time.nanoseconds, true); });
+    view.setBigInt64(pointer + 88, BigInt(values.ino), true);
+    return 0;
+}
+/** Runtime storage and application storage occupy disjoint guest device ranges. */
+export function createPythonRuntimeStatMapper(maxDevices = 1024) {
+    if (!Number.isSafeInteger(maxDevices) || maxDevices < 1 || maxDevices > 1024)
+        throw new RangeError('Invalid runtime device limit');
+    const mapped = Symbol('mapped Python runtime device');
+    const devices = new Map();
+    return stat => {
+        if (stat[mapped])
+            return stat;
+        if (!Number.isSafeInteger(stat.dev) || stat.dev < 0 || stat.dev > 0xffffffff)
+            throw new Error('EOVERFLOW');
+        let device = devices.get(stat.dev);
+        if (device === undefined) {
+            if (devices.size >= maxDevices)
+                throw new Error('EOVERFLOW');
+            device = 0x80000000 + devices.size;
+            devices.set(stat.dev, device);
+        }
+        return { ...stat, dev: device, [mapped]: true };
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { FileDescriptor, FileSystem, OpenFileOptions, MkdirOptions } from "../contracts/filesystem.js";
+export type PythonFsRequest = {
+    readonly op: "open";
+    readonly args: readonly [string, OpenFileOptions];
+} | {
+    readonly op: "read";
+    readonly args: readonly [number, number, number | null];
+} | {
+    readonly op: "write";
+    readonly args: readonly [number, Uint8Array, number | null];
+} | {
+    readonly op: "fstat" | "close" | "position" | "descriptorCapabilities";
+    readonly args: readonly [number];
+} | {
+    readonly op: "ftruncate";
+    readonly args: readonly [number, number];
+} | {
+    readonly op: "sync";
+    readonly args: readonly [number, boolean];
+} | {
+    readonly op: "stat" | "lstat" | "readdir" | "realpath" | "readlink" | "rm" | "rmdir";
+    readonly args: readonly [string];
+} | {
+    readonly op: "rename" | "symlink" | "link";
+    readonly args: readonly [string, string];
+} | {
+    readonly op: "mkdir";
+    readonly args: readonly [string, MkdirOptions?];
+} | {
+    readonly op: "chmod" | "truncate" | "access";
+    readonly args: readonly [string, number];
+} | {
+    readonly op: "utimes";
+    readonly args: readonly [string, number, number];
+};
+export interface PythonFileSystemOptions {
+    readonly cwd: string;
+    readonly signal?: AbortSignal;
+    readonly maxTransferBytes?: number;
+    readonly maxOpenFiles?: number;
+    readonly maxDirectoryEntries?: number;
+    /** Caller-owned acquisition wrapper, e.g. shell descriptor quota enrollment. */
+    readonly open?: (path: string, options: OpenFileOptions) => Promise<FileDescriptor>;
+}
+/** Async half of a worker RPC filesystem. Never run this on an Atomics.wait-blocked interpreter thread. */
+export declare class PythonFileSystem {
+    #private;
+    constructor(fs: FileSystem, options: PythonFileSystemOptions);
+    dispatch(value: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,216 @@
+import { parsePythonFsRequest } from "./request.js";
+import { composeAbortSignals } from "../contracts/abort.js";
+import { FsError } from "../contracts/errors.js";
+import { validatePath } from "../contracts/virtual-path.js";
+/** Async half of a worker RPC filesystem. Never run this on an Atomics.wait-blocked interpreter thread. */
+export class PythonFileSystem {
+    #fs;
+    #cwd;
+    #transfer;
+    #limit;
+    #directoryLimit;
+    #open;
+    #abort = new AbortController();
+    #scope;
+    #handles = new Map();
+    #pending = new Set();
+    #acquiring = 0;
+    #next = 1;
+    #closing;
+    constructor(fs, options) {
+        this.#fs = fs;
+        validatePath(options.cwd);
+        if (!options.cwd.startsWith("/"))
+            throw new FsError("EINVAL", { syscall: "python filesystem", path: options.cwd, message: "cwd must be absolute" });
+        this.#cwd = options.cwd;
+        this.#transfer = options.maxTransferBytes ?? 65536;
+        this.#limit = options.maxOpenFiles ?? 256;
+        this.#directoryLimit = options.maxDirectoryEntries ?? 65536;
+        for (const limit of [this.#transfer, this.#limit, this.#directoryLimit])
+            if (!Number.isSafeInteger(limit) || limit < 1)
+                throw new FsError("EINVAL", { syscall: "python filesystem" });
+        this.#open = options.open;
+        this.#scope = composeAbortSignals([...(options.signal === undefined ? [] : [options.signal]), this.#abort.signal]);
+    }
+    dispatch(value) {
+        if (this.#closing)
+            return Promise.reject(new FsError("EBADF"));
+        let request;
+        try {
+            this.#scope.signal.throwIfAborted();
+            request = parsePythonFsRequest(value, this.#transfer);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const operation = this.#execute(request);
+        this.#pending.add(operation);
+        void operation.then(() => this.#pending.delete(operation), () => this.#pending.delete(operation));
+        return operation;
+    }
+    #path(path) {
+        validatePath(path);
+        if (path.length === 0)
+            throw new FsError("ENOENT", { syscall: "resolve", path });
+        return path.startsWith("/") ? path : `${this.#cwd === "/" ? "" : this.#cwd}/${path}`;
+    }
+    #handle(id) {
+        const handle = this.#handles.get(id);
+        if (!handle)
+            throw new FsError("EBADF");
+        return handle;
+    }
+    #size(size) {
+        if (!Number.isSafeInteger(size) || size < 0)
+            throw new FsError("EINVAL");
+        if (size > this.#transfer)
+            throw new FsError("EFBIG", { message: "Python filesystem transfer exceeds configured limit" });
+    }
+    async #execute(request) {
+        const signal = this.#scope.signal;
+        signal.throwIfAborted();
+        const options = { signal };
+        const fs = this.#fs;
+        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.
+                    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--;
+                }
+            }
+            case "close": {
+                const [id] = request.args;
+                const handle = this.#handle(id);
+                this.#handles.delete(id);
+                await handle.close();
+                return;
+            }
+            case "descriptorCapabilities": return { ...this.#handle(request.args[0]).capabilities };
+            case "fstat": return this.#handle(request.args[0]).stat(options);
+            case "position": {
+                const handle = this.#handle(request.args[0]);
+                if (handle.capabilities.position !== true || !handle.getPosition)
+                    throw new FsError("ENOTSUP");
+                return handle.getPosition(options);
+            }
+            case "read": {
+                const [id, length, position] = request.args;
+                this.#size(length);
+                const buffer = new Uint8Array(length);
+                const count = await this.#handle(id).read(buffer, position, options);
+                if (!Number.isSafeInteger(count) || count < 0 || count > length)
+                    throw new FsError("EIO");
+                return buffer.slice(0, count);
+            }
+            case "write": {
+                const [id, data, position] = request.args;
+                if (!(data instanceof Uint8Array))
+                    throw new FsError("EINVAL");
+                this.#size(data.byteLength);
+                // The request may outlive its transport's shared reply/request slot.
+                const owned = data.slice();
+                const count = await this.#handle(id).write(owned, position, options);
+                if (!Number.isSafeInteger(count) || count < 0 || count > owned.byteLength)
+                    throw new FsError("EIO");
+                return count;
+            }
+            case "ftruncate": return this.#handle(request.args[0]).truncate(request.args[1], options);
+            case "sync": return this.#handle(request.args[0]).sync(request.args[1], options);
+            case "stat": return fs.stat(this.#path(request.args[0]), options);
+            case "lstat": return fs.lstat(this.#path(request.args[0]), options);
+            case "realpath": return fs.realpath(this.#path(request.args[0]), options);
+            case "readdir": return fs.readdir(this.#path(request.args[0]), { ...options, maxEntries: this.#directoryLimit });
+            case "access": return fs.access(this.#path(request.args[0]), request.args[1], options);
+            case "mkdir": return fs.mkdir(this.#path(request.args[0]), { ...request.args[1], ...options });
+            case "rm": {
+                const path = this.#path(request.args[0]);
+                if (!fs.unlink)
+                    throw new FsError("ENOTSUP", { syscall: "unlink", path });
+                return fs.unlink(path, options);
+            }
+            case "rmdir": {
+                const path = this.#path(request.args[0]);
+                const capabilities = fs.capabilitiesFor ? await fs.capabilitiesFor(path, options) : fs.capabilities;
+                signal.throwIfAborted();
+                if (capabilities.readOnly === true)
+                    throw new FsError("EROFS", { syscall: "rmdir", path });
+                if (!fs.rmdir || capabilities.removeDirectory === false || capabilities.snapshotRmdir === true)
+                    throw new FsError("ENOTSUP", { syscall: "rmdir", path });
+                return fs.rmdir(path, options);
+            }
+            case "rename": return fs.rename(this.#path(request.args[0]), this.#path(request.args[1]), options);
+            case "readlink":
+                if (fs.readlink)
+                    return fs.readlink(this.#path(request.args[0]), options);
+                break;
+            case "symlink":
+                if (fs.symlink)
+                    return fs.symlink(request.args[0], this.#path(request.args[1]), options);
+                break;
+            case "link":
+                if (fs.link)
+                    return fs.link(this.#path(request.args[0]), this.#path(request.args[1]), options);
+                break;
+            case "chmod":
+                if (fs.chmod)
+                    return fs.chmod(this.#path(request.args[0]), request.args[1], options);
+                break;
+            case "truncate":
+                if (fs.truncate)
+                    return fs.truncate(this.#path(request.args[0]), request.args[1], options);
+                break;
+            case "utimes":
+                if (fs.utimes)
+                    return fs.utimes(this.#path(request.args[0]), request.args[1], request.args[2], options);
+                break;
+        }
+        throw new FsError("ENOTSUP", { syscall: request.op });
+    }
+    close() {
+        if (!this.#closing) {
+            this.#closing = Promise.resolve().then(async () => {
+                await Promise.allSettled([...this.#pending]);
+                const handles = [...this.#handles.values()];
+                this.#handles.clear();
+                const results = await Promise.allSettled(handles.map(handle => handle.close()));
+                this.#scope.dispose();
+                const failed = results.find(result => result.status === "rejected");
+                if (failed?.status === "rejected")
+                    throw failed.reason;
+            });
+            this.#abort.abort(new FsError("ECANCELED", { syscall: "python filesystem close" }));
+        }
+        return this.#closing;
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { OpenFileOptions } from "../contracts/filesystem.js";
+/** Emscripten's pinned musl flag ABI, not the host operating system's flags. */
+export declare function translatePythonOpenFlags(flags: number, mode?: number): OpenFileOptions;

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

@@ -0,0 +1,14 @@
+import { FsError } from "../contracts/errors.js";
+/** Emscripten's pinned musl flag ABI, not the host operating system's flags. */
+export function translatePythonOpenFlags(flags, mode = 0o666) {
+    if (!Number.isSafeInteger(flags) || flags < 0 || flags > 0x7fffffff || (flags & 3) === 3)
+        throw new FsError("EINVAL", { syscall: "open" });
+    const exclusive = (flags & (64 | 128)) === (64 | 128);
+    // CLOEXEC and LARGEFILE do not alter the lifetime or numeric range of a virtual descriptor.
+    const supported = 3 | 64 | 128 | 512 | 1024 | 32768 | 524288 | (exclusive ? 131072 : 0);
+    if ((flags & ~supported) !== 0)
+        throw new FsError("ENOTSUP", { syscall: "open" });
+    return { access: (flags & 3) === 0 ? "read" : (flags & 3) === 1 ? "write" : "readwrite",
+        creation: (flags & 64) !== 0 ? exclusive ? "exclusive" : "ifMissing" : "never",
+        truncate: (flags & 512) !== 0, append: (flags & 1024) !== 0, mode };
+}

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

@@ -0,0 +1,7 @@
+export { PythonFileSystem } from "./filesystem.js";
+export type { PythonFileSystemOptions, PythonFsRequest } from "./filesystem.js";
+export { translatePythonOpenFlags } from "./flags.js";
+export { mountPythonFileSystem } from "./emscripten.js";
+export type { PythonMountOptions } from "./emscripten.js";
+export { PythonStatTranslator } from "./stat.js";
+export type { PythonWireStat } from "./stat.js";

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

@@ -0,0 +1,4 @@
+export { PythonFileSystem } from "./filesystem.js";
+export { translatePythonOpenFlags } from "./flags.js";
+export { mountPythonFileSystem } from "./emscripten.js";
+export { PythonStatTranslator } from "./stat.js";

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

@@ -0,0 +1,2 @@
+import type { PythonFsRequest } from "./filesystem.js";
+export declare function parsePythonFsRequest(value: unknown, maxTransferBytes: number): PythonFsRequest;