toolcraft 0.0.749 → 0.0.751

package/node_modules/@poe-code/safe-fs/dist/platform/browser.js

@@ -0,0 +1,58 @@
+import { FsError } from "../contracts/errors.js";
+import { chargeTransportOptions } from "./transport-budget.js";
+export const platform = Object.freeze({
+    nativeFileSystem: Object.freeze({ open: false, permissions: false, timestamps: false, conditionalChmod: false, trustedOwnedStaging: false, atomicRename: false }),
+    maxCollectionBytes: Infinity,
+    errno(_code) {
+        return undefined;
+    },
+    callbackAuthorities: false,
+    randomUUID() {
+        const crypto = globalThis.crypto;
+        if (typeof crypto?.randomUUID === "function")
+            return crypto.randomUUID();
+        if (typeof crypto?.getRandomValues !== "function") {
+            throw new FsError("ENOTSUP", { message: "secure crypto is required for overlay staging" });
+        }
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+});
+const operationKey = Symbol("filesystem-comparison");
+const contexts = new WeakSet();
+export const comparisonContext = Object.freeze({
+    active(options) {
+        const context = options[operationKey];
+        return context !== undefined && contexts.has(context);
+    },
+    async run(options, action) {
+        const context = Object.freeze({});
+        contexts.add(context);
+        const nested = { ...options, [operationKey]: context };
+        try {
+            return await action(nested);
+        }
+        finally {
+            contexts.delete(context);
+        }
+    }
+});
+// Browser operations carry request budgets in their options, including streams.
+export function getScopedTransportBudget() {
+    return undefined;
+}
+export function withScopedTransportBudget(frames, action) {
+    if (frames !== undefined)
+        throw new FsError("ENOTSUP", { message: "S3 transport budget contexts require Node" });
+    return action();
+}
+export function runScopedTransportBudget(_admit, action, _credit = 1) {
+    return action();
+}
+export function chargeScopedTransportCall(options) {
+    options?.signal?.throwIfAborted();
+    chargeTransportOptions(options);
+}

package/node_modules/@poe-code/safe-fs/dist/platform/node-path.d.ts

@@ -0,0 +1 @@
+export { posix } from "node:path";

package/node_modules/@poe-code/safe-fs/dist/platform/node-path.js

@@ -0,0 +1 @@
+export { posix } from "node:path";

package/node_modules/@poe-code/safe-fs/dist/platform/node.d.ts

@@ -0,0 +1,26 @@
+import type { FsOptions } from "../contracts/filesystem.js";
+import { type ScopedTransportBudgetFrame } from "./transport-budget.js";
+export type PlatformErrno = number;
+export type PlatformComparisonCallback<Callback> = Callback;
+export declare const platform: Readonly<{
+    nativeFileSystem: Readonly<{
+        open: true;
+        permissions: true;
+        timestamps: true;
+        conditionalChmod: true;
+        trustedOwnedStaging: true;
+        atomicRename: true;
+    }>;
+    maxCollectionBytes: number;
+    errno(code: string): PlatformErrno;
+    callbackAuthorities: true;
+    randomUUID: () => string;
+}>;
+export declare const comparisonContext: Readonly<{
+    active(_options: FsOptions): boolean;
+    run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
+}>;
+export declare function getScopedTransportBudget(): readonly ScopedTransportBudgetFrame[] | undefined;
+export declare function withScopedTransportBudget<Result>(frames: readonly ScopedTransportBudgetFrame[] | undefined, action: () => Result): Result;
+export declare function runScopedTransportBudget<Result>(admit: (options?: FsOptions) => void, action: () => Result, credit?: number): Result;
+export declare function chargeScopedTransportCall(options?: FsOptions): void;

package/node_modules/@poe-code/safe-fs/dist/platform/node.js

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import * as util from "node:util";
+import { constants } from "node:os";
+import { hasRegisteredS3FileSystem } from "./transport-budget.js";
+const systemErrnos = (() => {
+    const fallback = new Map(Object.entries(constants.errno).map(([name, errno]) => [name, -Math.abs(errno)]));
+    if (typeof util.getSystemErrorMap !== "function")
+        return fallback;
+    try {
+        return new Map([...util.getSystemErrorMap()].map(([errno, [name]]) => [name, errno]));
+    }
+    catch {
+        return fallback;
+    }
+})();
+const negotiating = new AsyncLocalStorage();
+export const platform = Object.freeze({
+    nativeFileSystem: Object.freeze({ open: true, permissions: true, timestamps: true, conditionalChmod: true, trustedOwnedStaging: true, atomicRename: true }),
+    maxCollectionBytes: Infinity,
+    errno(code) {
+        const errno = systemErrnos.get(code === "EOPNOTSUPP" ? "ENOTSUP" : code);
+        if (errno === undefined)
+            throw new TypeError(`Unsupported platform errno code: ${code}`);
+        return errno;
+    },
+    callbackAuthorities: true,
+    randomUUID: randomUUID
+});
+export const comparisonContext = Object.freeze({
+    active(_options) {
+        return negotiating.getStore() === true;
+    },
+    run(options, action) {
+        return negotiating.run(true, () => action(options));
+    }
+});
+const transportBudgets = new AsyncLocalStorage();
+export function getScopedTransportBudget() {
+    return hasRegisteredS3FileSystem ? transportBudgets.getStore() : undefined;
+}
+export function withScopedTransportBudget(frames, action) {
+    return frames ? transportBudgets.run(frames, action) : action();
+}
+export function runScopedTransportBudget(admit, action, credit = 1) {
+    if (!hasRegisteredS3FileSystem)
+        return action();
+    const parent = transportBudgets.getStore() ?? [];
+    const frame = { credit, admit };
+    return transportBudgets.run([...parent, frame], action);
+}
+export function chargeScopedTransportCall(options) {
+    if (!hasRegisteredS3FileSystem)
+        return;
+    const frames = transportBudgets.getStore();
+    if (!frames)
+        return;
+    for (const frame of frames) {
+        if (frame.credit > 0)
+            frame.credit--;
+        else
+            frame.admit(options);
+    }
+}

package/node_modules/@poe-code/safe-fs/dist/platform/transport-budget.d.ts

@@ -0,0 +1,9 @@
+import type { FsOptions } from "../contracts/filesystem.js";
+export interface ScopedTransportBudgetFrame {
+    credit: number;
+    readonly admit: (options?: FsOptions) => void;
+}
+export declare let hasRegisteredS3FileSystem: boolean;
+export declare function enableS3TransportBudget(): void;
+export declare function scopeTransportOptions(options: FsOptions, admit: (options?: FsOptions) => void, credit: number): FsOptions;
+export declare function chargeTransportOptions(options?: FsOptions): void;

package/node_modules/@poe-code/safe-fs/dist/platform/transport-budget.js

@@ -0,0 +1,17 @@
+export let hasRegisteredS3FileSystem = false;
+export function enableS3TransportBudget() {
+    hasRegisteredS3FileSystem = true;
+}
+const budgetKey = Symbol("scoped-transport-budget");
+export function scopeTransportOptions(options, admit, credit) {
+    const parent = options[budgetKey] ?? [];
+    return { ...options, [budgetKey]: [...parent, { credit, admit }] };
+}
+export function chargeTransportOptions(options) {
+    for (const frame of options?.[budgetKey] ?? []) {
+        if (frame.credit > 0)
+            frame.credit--;
+        else
+            frame.admit(options);
+    }
+}

package/node_modules/@poe-code/safe-fs/dist/python/emscripten.d.ts

@@ -0,0 +1,15 @@
+export interface PythonMountOptions {
+    request: (operation: string, ...args: any[]) => any;
+    cwd: string;
+    runtimeMount: string;
+    maxTransferBytes: number;
+    errno: Record<string, number>;
+    synchronizationFlags: number;
+    runtimeModule: any;
+    getUmask?: () => number;
+}
+export declare function mountPythonFileSystem(FS: any, options: PythonMountOptions): void;
+/** Encode the pinned wasm32 musl stat layout without truncating canonical values. */
+export declare function writePythonStat(heap: Uint8Array, pointer: number, stat: Record<string, any>): number;
+/** Runtime storage and application storage occupy disjoint guest device ranges. */
+export declare function createPythonRuntimeStatMapper(maxDevices?: number): (stat: Record<string | symbol, any>) => Record<string | symbol, any>;

package/node_modules/@poe-code/safe-fs/dist/python/emscripten.js

@@ -0,0 +1,357 @@
+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 & ~(options.getUmask?.() ?? 0), exactMode: true });
+            else {
+                const handle = rpc('open', target, { access: 'write', creation: 'exclusive', mode: mode & 4095 & ~(options.getUmask?.() ?? 0), exactMode: true });
+                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 & ~(options.getUmask?.() ?? 0)), exactMode: true };
+        }
+        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: mode & ~(options.getUmask?.() ?? 0), exactMode: true });
+        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 & ~(options.getUmask?.() ?? 0), exactMode: true });
+        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 = Infinity) {
+    if (maxDevices !== Infinity && (!Number.isSafeInteger(maxDevices) || maxDevices < 1))
+        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');
+            // Preserve the uint32 guest ABI even when the resource budget is unlimited.
+            if (devices.size >= 0x80000000)
+                throw new Error('EOVERFLOW');
+            device = 0x80000000 + devices.size;
+            devices.set(stat.dev, device);
+        }
+        return { ...stat, dev: device, [mapped]: true };
+    };
+}

package/node_modules/@poe-code/safe-fs/dist/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" | "rmtree" | "rmtreeSupported";
+    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>;
+}