@polyengine/wasi 0.1.0-pre.g633468a

package/esm/internal/fs_provider.js

@@ -0,0 +1,795 @@
+// INTERNAL shared core for the real `wasi:filesystem` impls
+// (filesystem_node.ts, filesystem_web.ts) — not a package export. The
+// backend seam (`FsBackend`) is the sockets_platform.ts move applied to
+// files: everything WIT-shaped (value mapping, path validation, error
+// shaping, stream plumbing, resource classes) lives here once; a backend
+// supplies raw handle operations and an error mapper.
+//
+// TRACKS. Both impls serve `@0.2` (WASI 0.2.12 WIT) and `@0.3` (WASI
+// 0.3.1). The same descriptor method NAMES carry different signatures
+// across tracks (`read-via-stream(offset) -> input-stream` vs
+// `read-via-stream(offset) -> tuple<stream<u8>, future<...>>`), so each
+// track gets its OWN resource class per `makeFilesystem` call — a guest
+// links one track and never mixes instances.
+//
+// ERROR SHAPES (the A10 family, and the reason this file exists twice
+// over): 0.2's `error-code` is an ENUM — the err payload is the bare
+// kebab-case string ("no-entry") — while 0.3's is a VARIANT (it grew
+// `other(option<string>)`) — the payload is `{ kind: "no-entry" }`.
+// Backends throw raw platform errors; `mapError` names the code and the
+// per-track guards shape it. A branded `ComponentException` from inner
+// code passes through untouched; an unmapped throw would be a trap, so
+// the guards map everything.
+//
+// SYNC vs PARKING (A14). 0.2 descriptor methods are sync WIT functions.
+// A sync backend (node) returns plain values from every op — no parking,
+// callback-mode guests work untouched. An async backend (OPFS) returns
+// promises, so every backend-touching 0.2 method is wrapped `suspending`
+// on the freshly-minted class prototype (per-call classes are what make
+// the marking per-backend rather than global). The 0.3 track needs no
+// marks: its methods are `async func` in WIT, and async-typed imports
+// accept thenables.
+//
+// READ-ONLY BY DEFAULT (`makeFilesystem(..., { writable })`). Write
+// access is a PACKAGE-LEVEL opt-in: one flag for the whole
+// implementation, never per-preopen. The rationale is a proof
+// obligation, not ergonomics. Per-preopen permissions form a lattice,
+// and the two-descriptor operations (`link-at`, `rename-at`) are edges
+// between its cells: each is a place where the check can be attached to
+// the wrong descriptor, letting a guest bridge from a read-only preopen
+// into a writable one — wasmtime-wasi shipped a vulnerability of exactly
+// that shape. With a single global flag there is no lattice to bridge,
+// so the obligation collapses to a closed enumeration ("every mutating
+// leaf refuses"), checkable against the WIT method list rather than
+// requiring per-path reasoning. Enforcement therefore lives HERE, in the
+// provider, and nowhere else: both backends and both tracks inherit it
+// from one site. Refusals use the WIT `read-only` error code.
+//
+// Two DISTINCT concerns, deliberately not merged:
+//   * per-descriptor flags (`requireWrite`) -> `bad-descriptor`: this
+//     descriptor was not opened for writing / directory mutation;
+//   * the global grant (`requireWritable`) -> `read-only`: this
+//     filesystem is read-only, whatever the descriptor says.
+// The global check runs FIRST on every mutating leaf, so a read-only
+// package answers `read-only` uniformly rather than leaking descriptor
+// bookkeeping.
+//
+// PATHS. Guest paths are resolved TEXTUALLY: split on "/", drop "." and
+// empty segments, ".." pops (underflow = `not-permitted`), absolute
+// paths and NUL rejected. Backends receive clean, non-escaping segment
+// lists. SECURITY: containment here is a CORRECTNESS mechanism, not a
+// security boundary — see docs/security.md. This layer confines lookups
+// TEXTUALLY only — it does
+// not chase symlinks per-component (no openat2/RESOLVE_BENEATH analogue
+// in node or OPFS). PHYSICAL containment is the backend's job: the node
+// backend realpaths every op against the preopen root before the OS call
+// (filesystem_node.ts header, issue #177), so guest-created and
+// pre-existing escaping symlinks alike are refused with `not-permitted`;
+// OPFS has no symlinks, so the web backend is immune by construction.
+import { ComponentException, Stream, suspending } from "@polyengine/runtime/embedder";
+import { FedInputStream, IoError, OutputStream, Pollable, SinkOutputStream } from "../io.js";
+const OK03 = { kind: "ok" };
+// --- errors ----------------------------------------------------------------------
+/**
+ * The io `error` resource minted by filesystem STREAM failures, carrying
+ * the error-code so 0.2's `filesystem-error-code(borrow<error>)` can
+ * downcast it (SinkOutputStream preserves IoError subclasses).
+ */
+export class FsIoError extends IoError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function err02(code) {
+    return new ComponentException(code);
+}
+function err03(code) {
+    return new ComponentException({ kind: code });
+}
+/** Chain over MaybeAsync without forcing sync backends through a tick. */
+function chain(v, f) {
+    return v instanceof Promise ? v.then(f) : f(v);
+}
+/** Run `fn`, mapping raw throws/rejections to the track's error shape;
+ * branded ComponentExceptions pass through. */
+function guarded(map, shape, fn) {
+    // The explicit annotation is what lets TS's flow analysis treat the
+    // catch-arm call as never-returning.
+    const rethrow = (e) => {
+        if (e instanceof ComponentException)
+            throw e;
+        throw shape(map(e));
+    };
+    try {
+        const r = fn();
+        return r instanceof Promise ? r.catch(rethrow) : r;
+    }
+    catch (e) {
+        return rethrow(e);
+    }
+}
+// --- paths -----------------------------------------------------------------------
+/**
+ * Validate and normalize a guest path to non-escaping segments (module
+ * header). `shape` picks the track's error payload.
+ */
+export function parsePath(path, shape) {
+    if (path.includes("\0"))
+        throw shape("invalid");
+    if (path.startsWith("/"))
+        throw shape("not-permitted");
+    const out = [];
+    for (const seg of path.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (out.length === 0)
+                throw shape("not-permitted");
+            out.pop();
+            continue;
+        }
+        out.push(seg);
+    }
+    return out;
+}
+/** Ops that name an entry (create/remove/unlink/rename/link/symlink)
+ * need a final component; "" or "." resolve to none. */
+function requireFinal(segments, shape) {
+    if (segments.length === 0)
+        throw shape("invalid");
+    return segments;
+}
+// --- conversions -----------------------------------------------------------------
+const NS_PER_SEC = 1000000000n;
+function nsToDatetime(ns) {
+    return { seconds: ns / NS_PER_SEC, nanoseconds: Number(ns % NS_PER_SEC) };
+}
+function newTimestampToSpec(v) {
+    switch (v.kind) {
+        case "no-change":
+        case "now":
+            return { kind: v.kind };
+        case "timestamp":
+            return {
+                kind: "timestamp",
+                ns: v.value.seconds * NS_PER_SEC + BigInt(v.value.nanoseconds),
+            };
+    }
+}
+function statValue(st) {
+    return {
+        type: st.type,
+        linkCount: st.linkCount,
+        size: st.size,
+        ...(st.atimeNs === undefined ? {} : { dataAccessTimestamp: nsToDatetime(st.atimeNs) }),
+        ...(st.mtimeNs === undefined ? {} : { dataModificationTimestamp: nsToDatetime(st.mtimeNs) }),
+        ...(st.ctimeNs === undefined ? {} : { statusChangeTimestamp: nsToDatetime(st.ctimeNs) }),
+    };
+}
+// FNV-1a 64-bit over the identity words: a deterministic, per-object
+// metadata-hash (the WIT contract is only "same object + same hash input
+// => same value"; wasmtime likewise hashes host metadata).
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const U64 = 0xffffffffffffffffn;
+function fnv64(words) {
+    let h = FNV_OFFSET;
+    for (const w of words) {
+        for (let i = 0n; i < 8n; i++) {
+            h ^= (w >> (i * 8n)) & 0xffn;
+            h = (h * FNV_PRIME) & U64;
+        }
+    }
+    return h;
+}
+function hashIdentity(id) {
+    return {
+        lower: fnv64([id.a, id.b]),
+        upper: fnv64([id.b ^ 0x9e3779b97f4a7c15n, id.a]),
+    };
+}
+const READ_CHUNK = 65536;
+/** 0.2 methods wrapped `suspending` for async backends (A14; module
+ * header). Everything that touches the backend — stream CONSTRUCTION
+ * stays plain (the streams themselves park via io.ts's marks). */
+const PARKED_02 = [
+    "advise",
+    "syncData",
+    "setSize",
+    "setTimes",
+    "read",
+    "write",
+    "readDirectory",
+    "sync",
+    "createDirectoryAt",
+    "stat",
+    "statAt",
+    "setTimesAt",
+    "linkAt",
+    "openAt",
+    "readlinkAt",
+    "removeDirectoryAt",
+    "renameAt",
+    "symlinkAt",
+    "unlinkFileAt",
+    "isSameObject",
+    "metadataHash",
+    "metadataHashAt",
+];
+/**
+ * Build the two-track `wasi:filesystem` import fragment over a backend.
+ * `preopens`: directory handles with their guest names, served (as fresh
+ * per-call descriptors) by both tracks' `preopens#get-directories`.
+ * `access.writable` (default false) is the package-level write grant.
+ */
+export function makeFilesystem(backend, preopens, access = {}) {
+    const writable = access.writable === true;
+    const map = (e) => backend.mapError(e);
+    const g02 = (fn) => guarded(map, err02, fn);
+    const g03 = (fn) => guarded(map, err03, fn);
+    /** A stream-facing sink/source error: an IoError subclass carrying the
+     * code, so 0.2 stream failures downcast via filesystem-error-code. */
+    const streamError = (e) => e instanceof FsIoError ? e : new FsIoError(map(e), message(e));
+    const decodeOpen = (pf, of, df) => ({
+        follow: pf.symlinkFollow === true,
+        create: of.create === true,
+        directory: of.directory === true,
+        exclusive: of.exclusive === true,
+        truncate: of.truncate === true,
+        read: df.read === true,
+        write: df.write === true || df.mutateDirectory === true,
+    });
+    /** Descriptor flags as VALUES, masked by the package grant: a
+     * read-only package never advertises `write`/`mutate-directory`, on
+     * preopens or on anything `open-at` mints, so a guest that checks
+     * flags before acting sees the same story the operations tell. */
+    const flagsValue = (df) => ({
+        read: df.read === true,
+        write: writable && df.write === true,
+        fileIntegritySync: df.fileIntegritySync === true,
+        dataIntegritySync: df.dataIntegritySync === true,
+        requestedWriteSync: df.requestedWriteSync === true,
+        mutateDirectory: writable && df.mutateDirectory === true,
+    });
+    const PREOPEN_FLAGS = flagsValue({ read: true, write: true, mutateDirectory: true });
+    /** The package-level grant. Refuses with the WIT `read-only` code —
+     * distinct from `requireWrite`'s per-descriptor `bad-descriptor`
+     * (module header). Called FIRST by every mutating leaf. */
+    const requireWritable = (shape) => {
+        if (!writable)
+            throw shape("read-only");
+    };
+    /** `open-at` is mutating exactly when it asks for write access or for
+     * an open-flag that creates/truncates: read-only means a guest cannot
+     * bring a file into existence either. */
+    const requireOpenAllowed = (of, df, shape) => {
+        if (writable)
+            return;
+        if (df.write === true || df.mutateDirectory === true ||
+            of.create === true || of.truncate === true || of.exclusive === true) {
+            throw shape("read-only");
+        }
+    };
+    /** An async pull over positional reads: the byte source for both
+     * tracks' read-via-stream on any backend. */
+    async function* readFrom(h, offset) {
+        let at = offset;
+        for (;;) {
+            const bytes = await backend.read(h, READ_CHUNK, at);
+            if (bytes.length === 0)
+                return;
+            at += bytes.length;
+            yield bytes;
+        }
+    }
+    // --- 0.2 sync streams (sync backends only: plain values, never park) --------
+    class SyncFileInputStream {
+        #h;
+        #cursor;
+        #closed = false;
+        constructor(h, offset) {
+            this.#h = h;
+            this.#cursor = offset;
+        }
+        read(len) {
+            if (this.#closed)
+                throw new ComponentException({ kind: "closed" });
+            const n = Number(len);
+            let bytes;
+            try {
+                bytes = backend.read(this.#h, n, this.#cursor);
+            }
+            catch (e) {
+                throw new ComponentException({
+                    kind: "last-operation-failed",
+                    value: streamError(e),
+                });
+            }
+            this.#cursor += bytes.length;
+            if (n > 0 && bytes.length === 0) {
+                throw new ComponentException({ kind: "closed" }); // EOF
+            }
+            return bytes;
+        }
+        blockingRead(len) {
+            return this.read(len);
+        }
+        skip(len) {
+            return BigInt(this.read(len).length);
+        }
+        blockingSkip(len) {
+            return this.skip(len);
+        }
+        subscribe() {
+            return new Pollable(); // file bytes are always "ready"
+        }
+        [Symbol.dispose]() {
+            this.#closed = true;
+        }
+    }
+    /** Sync positional/append writes ride the buffer-backed OutputStream
+     * base; the sink converts raw failures to stream-errors. */
+    const syncWriteStream = (write) => new OutputStream((chunk) => {
+        try {
+            write(chunk);
+        }
+        catch (e) {
+            throw new ComponentException({
+                kind: "last-operation-failed",
+                value: streamError(e),
+            });
+        }
+    });
+    /** Async sinks for SinkOutputStream: failures carry the code. */
+    const asyncSink = (write) => async (chunk) => {
+        try {
+            await write(chunk);
+        }
+        catch (e) {
+            throw streamError(e);
+        }
+    };
+    const requireFile = (c, shape) => {
+        if (c.type === "directory")
+            throw shape("is-directory");
+    };
+    const requireDir = (c, shape) => {
+        if (c.type !== "directory")
+            throw shape("not-directory");
+    };
+    const requireRead = (c, shape) => {
+        if (!c.flags.read)
+            throw shape("bad-descriptor");
+    };
+    const requireWrite = (c, shape) => {
+        if (!c.flags.write && !c.flags.mutateDirectory)
+            throw shape("bad-descriptor");
+    };
+    // --- the 0.2 track ---------------------------------------------------------
+    class DirectoryEntryStream02 {
+        #entries;
+        #at = 0;
+        constructor(entries) {
+            this.#entries = entries;
+        }
+        readDirectoryEntry() {
+            return this.#at < this.#entries.length ? this.#entries[this.#at++] : undefined;
+        }
+        [Symbol.dispose]() {
+            this.#at = this.#entries.length;
+        }
+    }
+    class Descriptor02 {
+        core;
+        constructor(h, type, flags) {
+            this.core = { h, type, flags };
+        }
+        readViaStream(offset) {
+            return g02(() => {
+                requireFile(this.core, err02);
+                requireRead(this.core, err02);
+                return backend.isSync
+                    ? new SyncFileInputStream(this.core.h, Number(offset))
+                    : new FedInputStream(readFrom(this.core.h, Number(offset)));
+            });
+        }
+        writeViaStream(offset) {
+            return g02(() => {
+                requireWritable(err02);
+                requireFile(this.core, err02);
+                requireWrite(this.core, err02);
+                let cursor = Number(offset);
+                if (backend.isSync) {
+                    return syncWriteStream((chunk) => {
+                        cursor += backend.write(this.core.h, chunk, cursor);
+                    });
+                }
+                return new SinkOutputStream(asyncSink(async (chunk) => {
+                    cursor += await backend.write(this.core.h, chunk, cursor);
+                }));
+            });
+        }
+        appendViaStream() {
+            return g02(() => {
+                requireWritable(err02);
+                requireFile(this.core, err02);
+                requireWrite(this.core, err02);
+                if (backend.isSync) {
+                    return syncWriteStream((chunk) => void backend.append(this.core.h, chunk));
+                }
+                return new SinkOutputStream(asyncSink(async (chunk) => {
+                    await backend.append(this.core.h, chunk);
+                }));
+            });
+        }
+        advise(_offset, _length, _advice) {
+            return g02(() => requireFile(this.core, err02)); // advisory: accept and ignore
+        }
+        syncData() {
+            return g02(() => backend.syncData(this.core.h));
+        }
+        getFlags() {
+            return { ...this.core.flags };
+        }
+        getType() {
+            return this.core.type;
+        }
+        setSize(size) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.setSize(this.core.h, Number(size));
+            });
+        }
+        setTimes(atime, mtime) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.setTimes(this.core.h, newTimestampToSpec(atime), newTimestampToSpec(mtime));
+            });
+        }
+        read(length, offset) {
+            return g02(() => {
+                requireFile(this.core, err02);
+                requireRead(this.core, err02);
+                const n = Number(length);
+                return chain(backend.read(this.core.h, n, Number(offset)), (bytes) => [bytes, n > 0 && bytes.length === 0]);
+            });
+        }
+        write(buffer, offset) {
+            return g02(() => {
+                requireWritable(err02);
+                requireFile(this.core, err02);
+                requireWrite(this.core, err02);
+                return chain(backend.write(this.core.h, buffer, Number(offset)), BigInt);
+            });
+        }
+        readDirectory() {
+            return g02(() => {
+                requireDir(this.core, err02);
+                return chain(backend.readDirectory(this.core.h), (entries) => new DirectoryEntryStream02(entries));
+            });
+        }
+        sync() {
+            return g02(() => backend.syncAll(this.core.h));
+        }
+        createDirectoryAt(path) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.createDirectoryAt(this.core.h, requireFinal(parsePath(path, err02), err02));
+            });
+        }
+        stat() {
+            return g02(() => chain(backend.stat(this.core.h), statValue));
+        }
+        statAt(pathFlags, path) {
+            return g02(() => chain(backend.statAt(this.core.h, parsePath(path, err02), pathFlags.symlinkFollow === true), statValue));
+        }
+        setTimesAt(pathFlags, path, atime, mtime) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.setTimesAt(this.core.h, parsePath(path, err02), pathFlags.symlinkFollow === true, newTimestampToSpec(atime), newTimestampToSpec(mtime));
+            });
+        }
+        linkAt(oldPathFlags, oldPath, newDescriptor, newPath) {
+            return g02(() => {
+                requireWritable(err02);
+                if (backend.linkAt === undefined)
+                    throw err02("unsupported");
+                // Both ends: a two-descriptor op checked on one side only is the
+                // classic bridge bug (module header).
+                requireWrite(this.core, err02);
+                requireWrite(newDescriptor.core, err02);
+                return backend.linkAt(this.core.h, requireFinal(parsePath(oldPath, err02), err02), oldPathFlags.symlinkFollow === true, newDescriptor.core.h, requireFinal(parsePath(newPath, err02), err02));
+            });
+        }
+        openAt(pathFlags, path, openFlags, flags) {
+            return g02(() => {
+                requireOpenAllowed(openFlags, flags, err02);
+                return chain(backend.openAt(this.core.h, parsePath(path, err02), decodeOpen(pathFlags, openFlags, flags)), ({ handle, type }) => new Descriptor02(handle, type, flagsValue(flags)));
+            });
+        }
+        readlinkAt(path) {
+            return g02(() => {
+                if (backend.readlinkAt === undefined)
+                    throw err02("unsupported");
+                return backend.readlinkAt(this.core.h, requireFinal(parsePath(path, err02), err02));
+            });
+        }
+        removeDirectoryAt(path) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.removeDirectoryAt(this.core.h, requireFinal(parsePath(path, err02), err02));
+            });
+        }
+        renameAt(oldPath, newDescriptor, newPath) {
+            return g02(() => {
+                requireWritable(err02);
+                // Both ends (see link-at).
+                requireWrite(this.core, err02);
+                requireWrite(newDescriptor.core, err02);
+                return backend.renameAt(this.core.h, requireFinal(parsePath(oldPath, err02), err02), newDescriptor.core.h, requireFinal(parsePath(newPath, err02), err02));
+            });
+        }
+        symlinkAt(oldPath, newPath) {
+            return g02(() => {
+                requireWritable(err02);
+                if (backend.symlinkAt === undefined)
+                    throw err02("unsupported");
+                requireWrite(this.core, err02);
+                // old-path is the link CONTENTS (never validated as a lookup path).
+                return backend.symlinkAt(oldPath, this.core.h, requireFinal(parsePath(newPath, err02), err02));
+            });
+        }
+        unlinkFileAt(path) {
+            return g02(() => {
+                requireWritable(err02);
+                requireWrite(this.core, err02);
+                return backend.unlinkFileAt(this.core.h, requireFinal(parsePath(path, err02), err02));
+            });
+        }
+        /** Returns bool, not result: backend failures TRAP (unguarded). */
+        isSameObject(other) {
+            return backend.isSame(this.core.h, other.core.h);
+        }
+        metadataHash() {
+            return g02(() => chain(backend.identity(this.core.h), hashIdentity));
+        }
+        metadataHashAt(pathFlags, path) {
+            return g02(() => chain(backend.identityAt(this.core.h, parsePath(path, err02), pathFlags.symlinkFollow === true), hashIdentity));
+        }
+        [Symbol.dispose]() {
+            backend.close(this.core.h);
+        }
+    }
+    // --- the 0.3 track ---------------------------------------------------------
+    class Descriptor03 {
+        core;
+        constructor(h, type, flags) {
+            this.core = { h, type, flags };
+        }
+        /** tuple<stream<u8>, future<result<_, error-code>>> */
+        readViaStream(offset) {
+            requireFile(this.core, err03);
+            requireRead(this.core, err03);
+            let settle;
+            const done = new Promise((r) => (settle = r));
+            const h = this.core.h;
+            const source = (async function* () {
+                try {
+                    yield* readFrom(h, Number(offset));
+                    settle(OK03);
+                }
+                catch (e) {
+                    settle({ kind: "err", value: { kind: map(e) } });
+                }
+                finally {
+                    settle(OK03); // reader dropped early: no-op if already settled
+                }
+            })();
+            return [source, done];
+        }
+        /** The promise IS the future source (A12): drain the guest's stream. */
+        async writeViaStream(data, offset) {
+            try {
+                requireWritable(err03);
+                requireFile(this.core, err03);
+                requireWrite(this.core, err03);
+                let cursor = Number(offset);
+                for await (const chunk of data) {
+                    const bytes = chunk instanceof Uint8Array ? chunk : Uint8Array.from(chunk);
+                    cursor += await backend.write(this.core.h, bytes, cursor);
+                }
+                return OK03;
+            }
+            catch (e) {
+                if (data instanceof Stream)
+                    data.drop(); // the guest's writer must not hang
+                return {
+                    kind: "err",
+                    value: { kind: e instanceof ComponentException ? e.payload.kind : map(e) },
+                };
+            }
+        }
+        async appendViaStream(data) {
+            try {
+                requireWritable(err03);
+                requireFile(this.core, err03);
+                requireWrite(this.core, err03);
+                for await (const chunk of data) {
+                    const bytes = chunk instanceof Uint8Array ? chunk : Uint8Array.from(chunk);
+                    await backend.append(this.core.h, bytes);
+                }
+                return OK03;
+            }
+            catch (e) {
+                if (data instanceof Stream)
+                    data.drop();
+                return {
+                    kind: "err",
+                    value: { kind: e instanceof ComponentException ? e.payload.kind : map(e) },
+                };
+            }
+        }
+        advise(_offset, _length, _advice) {
+            return g03(() => requireFile(this.core, err03));
+        }
+        syncData() {
+            return g03(() => backend.syncData(this.core.h));
+        }
+        getFlags() {
+            return { ...this.core.flags };
+        }
+        getType() {
+            return this.core.type;
+        }
+        setSize(size) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.setSize(this.core.h, Number(size));
+            });
+        }
+        setTimes(atime, mtime) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.setTimes(this.core.h, newTimestampToSpec(atime), newTimestampToSpec(mtime));
+            });
+        }
+        /** tuple<stream<directory-entry>, future<result<_, error-code>>> */
+        readDirectory() {
+            return g03(() => {
+                requireDir(this.core, err03);
+                return chain(backend.readDirectory(this.core.h), (entries) => [
+                    entries,
+                    Promise.resolve(OK03),
+                ]);
+            });
+        }
+        sync() {
+            return g03(() => backend.syncAll(this.core.h));
+        }
+        createDirectoryAt(path) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.createDirectoryAt(this.core.h, requireFinal(parsePath(path, err03), err03));
+            });
+        }
+        stat() {
+            return g03(() => chain(backend.stat(this.core.h), statValue));
+        }
+        statAt(pathFlags, path) {
+            return g03(() => chain(backend.statAt(this.core.h, parsePath(path, err03), pathFlags.symlinkFollow === true), statValue));
+        }
+        setTimesAt(pathFlags, path, atime, mtime) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.setTimesAt(this.core.h, parsePath(path, err03), pathFlags.symlinkFollow === true, newTimestampToSpec(atime), newTimestampToSpec(mtime));
+            });
+        }
+        linkAt(oldPathFlags, oldPath, newDescriptor, newPath) {
+            return g03(() => {
+                requireWritable(err03);
+                if (backend.linkAt === undefined)
+                    throw err03("unsupported");
+                // Both ends: a two-descriptor op checked on one side only is the
+                // classic bridge bug (module header).
+                requireWrite(this.core, err03);
+                requireWrite(newDescriptor.core, err03);
+                return backend.linkAt(this.core.h, requireFinal(parsePath(oldPath, err03), err03), oldPathFlags.symlinkFollow === true, newDescriptor.core.h, requireFinal(parsePath(newPath, err03), err03));
+            });
+        }
+        openAt(pathFlags, path, openFlags, flags) {
+            return g03(() => {
+                requireOpenAllowed(openFlags, flags, err03);
+                return chain(backend.openAt(this.core.h, parsePath(path, err03), decodeOpen(pathFlags, openFlags, flags)), ({ handle, type }) => new Descriptor03(handle, type, flagsValue(flags)));
+            });
+        }
+        readlinkAt(path) {
+            return g03(() => {
+                if (backend.readlinkAt === undefined)
+                    throw err03("unsupported");
+                return backend.readlinkAt(this.core.h, requireFinal(parsePath(path, err03), err03));
+            });
+        }
+        removeDirectoryAt(path) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.removeDirectoryAt(this.core.h, requireFinal(parsePath(path, err03), err03));
+            });
+        }
+        renameAt(oldPath, newDescriptor, newPath) {
+            return g03(() => {
+                requireWritable(err03);
+                // Both ends (see link-at).
+                requireWrite(this.core, err03);
+                requireWrite(newDescriptor.core, err03);
+                return backend.renameAt(this.core.h, requireFinal(parsePath(oldPath, err03), err03), newDescriptor.core.h, requireFinal(parsePath(newPath, err03), err03));
+            });
+        }
+        symlinkAt(oldPath, newPath) {
+            return g03(() => {
+                requireWritable(err03);
+                if (backend.symlinkAt === undefined)
+                    throw err03("unsupported");
+                requireWrite(this.core, err03);
+                return backend.symlinkAt(oldPath, this.core.h, requireFinal(parsePath(newPath, err03), err03));
+            });
+        }
+        unlinkFileAt(path) {
+            return g03(() => {
+                requireWritable(err03);
+                requireWrite(this.core, err03);
+                return backend.unlinkFileAt(this.core.h, requireFinal(parsePath(path, err03), err03));
+            });
+        }
+        isSameObject(other) {
+            return backend.isSame(this.core.h, other.core.h); // bool, not result: raw throw = trap
+        }
+        metadataHash() {
+            return g03(() => chain(backend.identity(this.core.h), hashIdentity));
+        }
+        metadataHashAt(pathFlags, path) {
+            return g03(() => chain(backend.identityAt(this.core.h, parsePath(path, err03), pathFlags.symlinkFollow === true), hashIdentity));
+        }
+        [Symbol.dispose]() {
+            backend.close(this.core.h);
+        }
+    }
+    // Async backends: mark the 0.2 track's backend-touching methods
+    // park-capable on the freshly-minted prototype (module header; A14).
+    if (!backend.isSync) {
+        const proto = Descriptor02.prototype;
+        for (const name of PARKED_02) {
+            proto[name] = suspending(proto[name]);
+        }
+    }
+    const getDirectories02 = () => preopens.map(([h, name]) => [new Descriptor02(h, "directory", PREOPEN_FLAGS), name]);
+    const getDirectories03 = () => preopens.map(([h, name]) => [new Descriptor03(h, "directory", PREOPEN_FLAGS), name]);
+    return {
+        imports: {
+            "wasi:filesystem/types@0.2": {
+                Descriptor: Descriptor02,
+                DirectoryEntryStream: DirectoryEntryStream02,
+                // `filesystem-error-code(err: borrow<error>) -> option<error-code>`:
+                // downcast succeeds exactly for the io errors OUR streams minted.
+                filesystemErrorCode: (err) => err instanceof FsIoError ? err.code : undefined,
+            },
+            "wasi:filesystem/preopens@0.2": { getDirectories: getDirectories02 },
+            "wasi:filesystem/types@0.3": { Descriptor: Descriptor03 },
+            "wasi:filesystem/preopens@0.3": { getDirectories: getDirectories03 },
+        },
+    };
+}