@struktoai/mirage-node 0.0.7 → 0.0.8

package/dist/runtime/js/host/fs.js

@@ -12,23 +12,36 @@
 // limitations under the License.
 // ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
 import { Buffer } from 'node:buffer';
+import { randomBytes } from 'node:crypto';
 import { constants } from 'node:fs';
 import { createRequire } from 'node:module';
 import { posix } from 'node:path';
+import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { classify } from '@struktoai/mirage-core/errors/classify';
 import { ebadf, einval, isMissingPath } from '@struktoai/mirage-core/errors/fs';
 import { posixErrno, posixPhrase } from '@struktoai/mirage-core/errors/posix';
+import { linkView } from '@struktoai/mirage-core/commands/builtin/utils/links';
 import { workspaceBridge } from '@struktoai/mirage-core/runtime/binding';
+import { MountCore } from '@struktoai/mirage-core/mount/core';
 import { RuntimeFiles } from '@struktoai/mirage-core/runtime/files';
+import { openMode } from '@struktoai/mirage-core/runtime/handles/mode';
 import { posixStat } from '@struktoai/mirage-core/runtime/stat';
 import { PrefixResolver } from '@struktoai/mirage-core/runtime/resolver';
 import { MountMode } from '@struktoai/mirage-core/types';
+import { MAX_SYMLINK_HOPS } from '@struktoai/mirage-core/utils/path';
 import { entryName } from '@struktoai/mirage-core/utils/remnants';
+import { pathMode } from '@struktoai/mirage-core/workspace/files';
 import { DESCRIPTOR_CALLS, LISTENED_CALLS, PATH_ARGS, REFUSED_CALLS, ROUTED_CALLS, } from "./constants.js";
-import { Descriptors, openFlags, readAt, readOn } from "./descriptors.js";
+import { Descriptors, openFlags } from "./descriptors.js";
+import { dirent, openedDir } from "./list.js";
+import { stats } from "./stat.js";
 const fs = createRequire(import.meta.url)('node:fs');
-const { S_IFMT, S_IFREG, S_IFDIR, S_IFCHR, S_IFLNK, W_OK, X_OK, COPYFILE_EXCL } = constants;
+// fs.promises as the patch leaves it, each call looked up when it is
+// made: a call on it reaches node for a host path and the workspace for
+// a mounted one, so a cp or glob across the two takes each end where it is.
+const routed = fs.promises;
+const { W_OK, X_OK, COPYFILE_EXCL } = constants;
 /** `path` as a string a mount could serve, or null: a descriptor and a
  * Buffer are host spellings no mount uses. */
 function spelled(path) {
@@ -38,10 +51,6 @@ function spelled(path) {
         return fileURLToPath(path);
     return null;
 }
-/** A stamp in nanoseconds, as node's BigIntStats spells one. */
-function ns(date) {
-    return BigInt(date.getTime()) * 1000000n;
-}
 /** A refusal spelled the way node's own fs spells an error. */
 function refusal(condition, syscall, path) {
     const err = new Error(`${condition}: ${posixPhrase(condition).toLowerCase()}, ${syscall} '${path}'`);
@@ -72,11 +81,44 @@ function syncRefusal(name, path) {
 function fieldsOf(options) {
     return typeof options === 'object' && options !== null ? options : {};
 }
+/** The mode a node call asks for: its number, its octal text, or the
+ * `mode` of its options. */
+function modeOf(options) {
+    const mode = typeof options === 'object' ? fieldsOf(options).mode : options;
+    if (typeof mode === 'number')
+        return mode;
+    return typeof mode === 'string' ? parseInt(mode, 8) : undefined;
+}
 function encodingOf(options) {
     if (typeof options === 'string')
         return options;
     return (fieldsOf(options).encoding ?? undefined);
 }
+/** A name as node answers one: a string, or a Buffer or another
+ * encoding where the options ask for it. */
+function encoded(text, options) {
+    const encoding = encodingOf(options);
+    if (encoding === undefined || encoding === 'utf8')
+        return text;
+    const bytes = Buffer.from(text);
+    return encoding === 'buffer' ? bytes : bytes.toString(encoding);
+}
+/** One of node's own `cp` refusals (`ERR_FS_CP_*`), spelled as node spells it. */
+function cpRefusal(code, title, condition, detail, path) {
+    return Object.assign(new Error(`${title}: cp returned ${condition} (${detail}) ${path}`), {
+        code,
+        errno: posixErrno(condition),
+        syscall: 'cp',
+        path,
+    });
+}
+/** Six characters from the alphabet of node's `mkdtemp` template. */
+function tempSuffix() {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    return Array.from(randomBytes(6), (byte) => alphabet[byte % alphabet.length]).join('');
+}
+// A path segment holding a character node's glob matcher reads as one.
+const GLOB_MAGIC = /[*?[\]{}()!+@]/;
 function bytesOf(data, options) {
     if (typeof data === 'string')
         return Buffer.from(data, encodingOf(options) ?? 'utf8');
@@ -94,6 +136,13 @@ function refusedIterator(err) {
         },
     };
 }
+/** Every item an async iterator yields. */
+async function collected(items) {
+    const out = [];
+    for await (const item of items)
+        out.push(item);
+    return out;
+}
 /** A time argument (seconds, a numeric string, a Date) as the ISO stamp
  * setattr stores. */
 function stampOf(time) {
@@ -257,6 +306,13 @@ class MountedFileHandle {
             throw ebadf(String(this.fd));
         return fs.createWriteStream(null, { ...fieldsOf(options), fd: this.fd });
     }
+    // node's own reads its lines through createReadStream, as this does.
+    readLines(options) {
+        return createInterface({
+            input: this.createReadStream(options),
+            crlfDelay: Infinity,
+        });
+    }
 }
 /**
  * Every routed fs call, answered on a mount: python's `HostFs` for
@@ -280,22 +336,27 @@ class HostFs {
     constructor(ws, native) {
         this.ws = ws;
         this.native = native;
-        this.files = new RuntimeFiles(workspaceBridge(async (name, path, args, kwargs) => {
+        // An op that fails with no condition (an upstream 502 a REST mount
+        // throws as it came) answers EIO, the kernel's word for a device that
+        // failed, as a guest's file adapter does; the original rides along as
+        // the cause.
+        const dispatch = async (name, path, args, kwargs, report) => {
             try {
-                const [value] = await ws.vfs.dispatch(name, path, args, kwargs);
-                return value;
+                return await ws.vfs.dispatch(name, path, args, kwargs, report);
             }
             catch (err) {
                 if (classify(err) !== null)
                     throw err;
-                // An op that fails with no condition (an upstream 502 a REST
-                // mount throws as it came) answers EIO, the kernel's word for a
-                // device that failed, as a guest's file adapter does; the original
-                // rides along as the cause.
-                throw Object.assign(refusal('EIO', name, path), { cause: err });
+                throw Object.assign(refusal('EIO', name, typeof path === 'string' ? path : path.virtual), {
+                    cause: err,
+                });
             }
-        }), new PrefixResolver(() => [], (directory) => ws.namespace.linkNamesUnder(directory)));
-        this.descriptors = new Descriptors(this.files, native, ws.namespace);
+        };
+        // Where a link leads, so a file reads as one inode whichever spelling
+        // reached it.
+        const links = linkView(ws.vfs);
+        this.files = new RuntimeFiles(workspaceBridge(async (name, path, args, kwargs) => (await dispatch(name, path, args, kwargs))[0]), new PrefixResolver(() => [], (directory) => ws.namespace.linkNamesUnder(directory)), links === undefined ? null : links.resolve.bind(links), new MountCore(ws.vfs.over(dispatch)));
+        this.descriptors = new Descriptors(this.files, native);
     }
     /** Whether `path` is under a mount the patch answers for. The synthetic
      * root anchor matches every path but backs no files, so a path only it
@@ -314,80 +375,35 @@ class HostFs {
     statsOf(path, st, options, unlinked = false) {
         // The stat every runtime shares; an owner the row lacks is this
         // process's own.
-        const posix = posixStat(st, path, this.ws.registry.tryMountFor(path)?.prefix ?? '/', {
+        // The file the links lead to names both its inode and its device, so a
+        // stat through a link and the fstat of its open file agree.
+        const named = st.name ?? path;
+        const posix = posixStat(st, named, this.ws.registry.tryMountFor(named)?.prefix ?? '/', {
             uid: process.getuid?.() ?? 0,
             gid: process.getgid?.() ?? 0,
             unknownMs: this.born,
         });
-        const kind = posix.mode & S_IFMT;
-        const mtime = new Date(posix.mtimeMs);
-        const atime = new Date(posix.atimeMs);
-        const kinds = {
-            isFile: () => kind === S_IFREG,
-            isDirectory: () => kind === S_IFDIR,
-            isBlockDevice: () => false,
-            isCharacterDevice: () => kind === S_IFCHR,
-            isSymbolicLink: () => kind === S_IFLNK,
-            isFIFO: () => false,
-            isSocket: () => false,
-        };
-        const dates = { atime, mtime, ctime: mtime, birthtime: mtime };
-        const fields = {
-            dev: posix.dev,
-            ino: posix.ino,
-            mode: posix.mode,
-            nlink: unlinked ? 0 : posix.nlink,
-            uid: posix.uid,
-            gid: posix.gid,
-            rdev: posix.rdev,
-            size: posix.size,
-            blksize: posix.blksize,
-            blocks: posix.blocks,
-            atimeMs: posix.atimeMs,
-            mtimeMs: posix.mtimeMs,
-            ctimeMs: posix.ctimeMs,
-            birthtimeMs: posix.mtimeMs,
-        };
-        if (fieldsOf(options).bigint !== true)
-            return { ...kinds, ...fields, ...dates };
-        // node's BigIntStats: every number a bigint, plus the stamps in ns.
-        const big = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, BigInt(Math.trunc(v))]));
-        return {
-            ...kinds,
-            ...big,
-            atimeNs: ns(atime),
-            mtimeNs: ns(mtime),
-            ctimeNs: ns(mtime),
-            birthtimeNs: ns(mtime),
-            ...dates,
-        };
+        return stats(unlinked ? { ...posix, nlink: 0 } : posix, fieldsOf(options).bigint === true);
     }
-    direntOf(directory, row) {
-        const kind = row.isLink === true ? S_IFLNK : row.isDir ? S_IFDIR : (row.mode ?? 0) & S_IFMT;
-        return {
-            name: entryName(row.path),
-            parentPath: directory,
-            path: directory,
-            isFile: () => kind === S_IFREG,
-            isDirectory: () => kind === S_IFDIR,
-            isBlockDevice: () => false,
-            isCharacterDevice: () => kind === S_IFCHR,
-            isSymbolicLink: () => kind === S_IFLNK,
-            isFIFO: () => false,
-            isSocket: () => false,
-        };
+    /**
+     * Whether a write at `path` would be admitted by mode: the mode the write
+     * itself meets (`pathMode`). Mirrors Python's `_writable`.
+     */
+    async writable(path) {
+        const mode = await pathMode(this.ws.vfs, path);
+        return mode !== null && mode !== MountMode.READ;
     }
     nativeCall(name, ...args) {
         return this.native.promises[name](...args);
     }
     async access(path, mode = 0) {
         const st = await this.files.stat(path);
-        // Write is the mount's mode, mirage's access control; a session's own
-        // narrower grant answers when the write happens, as POSIX leaves
-        // access(2) advisory. Execute is the one question the bits answer.
-        if (mode & W_OK && this.ws.registry.tryMountFor(path)?.mode === MountMode.READ) {
+        // Write is the mode in force at the path for the session, mirage's
+        // access control: W_OK answers what the write itself would meet, as
+        // access(2) refuses a write on a read-only file system. Execute is the
+        // one question the bits answer.
+        if (mode & W_OK && !(await this.writable(path)))
             throw refusal('EACCES', 'access', path);
-        }
         if (mode & X_OK && (st.mode & 0o111) === 0)
             throw refusal('EACCES', 'access', path);
     }
@@ -458,6 +474,7 @@ class HostFs {
     async mkdir(path, options) {
         if (fieldsOf(options).recursive !== true) {
             await this.files.mkdir(path);
+            await this.narrowed(path, modeOf(options));
             return undefined;
         }
         // Each missing ancestor in turn, stopping at the mount root, as
@@ -481,6 +498,362 @@ class HostFs {
             await this.files.mkdir(dir);
         return missing[0];
     }
+    async cp(src, dst, options) {
+        const opts = fieldsOf(options);
+        const filter = opts.filter;
+        if (filter !== undefined && !(await filter(src, dst)))
+            return;
+        const from = await this.checked(src, dst, opts);
+        // node makes the destination's missing parents first.
+        const parent = posix.dirname(posix.resolve(dst));
+        try {
+            await routed.stat(parent);
+        }
+        catch (err) {
+            if (!isMissingPath(err))
+                throw err;
+            await routed.mkdir(parent, { recursive: true });
+        }
+        await this.copied(src, dst, from, opts);
+    }
+    /** Narrow a directory just made to the permissions `mode` asks for, as
+     * mkdir(2) does: its own are what the umask left of 0o777, so the two
+     * together are what mkdir(2) leaves of `mode`, and a bit it inherited
+     * (a parent's set-group-ID) stays. A mode asking all of 0o777 needs no
+     * lookup, and one the workspace refuses leaves the directory as made. */
+    async narrowed(path, mode) {
+        if (mode === undefined || (mode & 0o777) === 0o777)
+            return;
+        let own;
+        try {
+            own = (await this.files.stat(path)).mode & 0o7777;
+        }
+        catch (err) {
+            const condition = classify(err);
+            if (condition !== 'EACCES' && condition !== 'EPERM')
+                throw err;
+            console.debug(`mkdir: ${path} keeps the mode it was made with: ${String(err)}`);
+            return;
+        }
+        const narrow = (own & ~0o777) | (own & mode & 0o777);
+        if (narrow !== own)
+            await this.files.setattr(path, { mode: narrow });
+    }
+    /** Whether the link at `path` leads to a directory; a dangling one
+     * leads nowhere. */
+    async linksToDirectory(path) {
+        try {
+            return (await this.entryOf(path, true)).isDirectory();
+        }
+        catch (err) {
+            if (!isMissingPath(err))
+                throw err;
+            return false;
+        }
+    }
+    /** The source's entry once the pair passes the checks node's `cp`
+     * makes of every pair it copies: two names for one file (a link that
+     * makes them one is caught as one spelling is), a directory without
+     * `recursive`, and a directory into itself. */
+    async checked(src, dst, opts) {
+        const follow = opts.dereference === true;
+        const [source, target] = [await this.identity(src, follow), await this.identity(dst, follow)];
+        if (source === target) {
+            throw cpRefusal('ERR_FS_CP_EINVAL', 'Invalid src or dest', 'EINVAL', 'src and dest cannot be the same', dst);
+        }
+        const from = await this.entryOf(src, follow);
+        if (from.isDirectory()) {
+            if (opts.recursive !== true) {
+                throw cpRefusal('ERR_FS_EISDIR', 'Path is a directory', 'EISDIR', `${src} is a directory (not copied)`, src);
+            }
+            if (target.startsWith(`${source}/`)) {
+                throw cpRefusal('ERR_FS_CP_EINVAL', 'Invalid src or dest', 'EINVAL', `cannot copy ${src} to a subdirectory of self ${dst}`, dst);
+            }
+        }
+        return from;
+    }
+    /** The file `path` names once its links are followed, as node's `cp`
+     * tells two files apart: its directories always, its last name when
+     * `follow`, and a name not there as it is spelled. */
+    async identity(path, follow) {
+        const absolute = posix.resolve(path);
+        if (absolute === '/')
+            return absolute;
+        if (follow) {
+            try {
+                return await routed.realpath(absolute);
+            }
+            catch (err) {
+                if (!isMissingPath(err))
+                    throw err;
+            }
+        }
+        return posix.join(await this.identity(posix.dirname(absolute), true), posix.basename(absolute));
+    }
+    /** A path's own entry, or its target's, through the patched calls, so
+     * a host path reaches node and a mounted one the workspace. */
+    entryOf(path, follow) {
+        return follow ? routed.stat(path) : routed.lstat(path);
+    }
+    /** One entry of a `cp` and what is under it, as node's own copies it:
+     * a name already there is replaced unless `force` is off, and a link
+     * keeps its target, a relative one resolved against where it was. */
+    async copied(src, dst, from, opts) {
+        let to = null;
+        try {
+            // `dereference` follows a link on either side, as node's does.
+            to = await this.entryOf(dst, opts.dereference === true);
+        }
+        catch (err) {
+            if (!isMissingPath(err))
+                throw err;
+        }
+        if (from.isDirectory()) {
+            if (to !== null && !to.isDirectory()) {
+                throw cpRefusal('ERR_FS_CP_DIR_TO_NON_DIR', 'Cannot overwrite non-directory with directory', 'EISDIR', `cannot overwrite non-directory ${dst} with directory ${src}`, dst);
+            }
+            if (to === null)
+                await routed.mkdir(dst);
+            const filter = opts.filter;
+            for (const name of await routed.readdir(src)) {
+                const [child, target] = [posix.join(src, name), posix.join(dst, name)];
+                if (filter !== undefined && !(await filter(child, target)))
+                    continue;
+                await this.copied(child, target, await this.checked(child, target, opts), opts);
+            }
+            // A directory it made takes the source's mode, once its entries are in.
+            if (to === null)
+                await routed.chmod(dst, from.mode & 0o7777);
+            return;
+        }
+        if (to?.isDirectory() === true) {
+            throw cpRefusal('ERR_FS_CP_NON_DIR_TO_DIR', 'Cannot overwrite directory with non-directory', 'ENOTDIR', `cannot overwrite directory ${dst} with non-directory ${src}`, dst);
+        }
+        if (from.isSymbolicLink()) {
+            const target = await routed.readlink(src);
+            const kept = opts.verbatimSymlinks === true || posix.isAbsolute(target)
+                ? target
+                : posix.resolve(posix.dirname(src), target);
+            // A link replaces a link there, whatever `force` says, unless one
+            // leads into the other's directory; onto any other entry the
+            // symlink itself refuses the name, as node's does.
+            if (to?.isSymbolicLink() === true) {
+                const there = await routed.readlink(dst);
+                const leads = posix.resolve(kept);
+                const led = posix.isAbsolute(there) ? there : posix.resolve(posix.dirname(dst), there);
+                if ((await this.entryOf(src, true)).isDirectory()) {
+                    if (led === leads || led.startsWith(`${leads}/`)) {
+                        throw cpRefusal('ERR_FS_CP_EINVAL', 'Invalid src or dest', 'EINVAL', `cannot copy ${kept} to a subdirectory of self ${led}`, dst);
+                    }
+                    if (leads.startsWith(`${led}/`)) {
+                        throw cpRefusal('ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY', 'Cannot overwrite symlink in subdirectory of self', 'EINVAL', `cannot overwrite ${led} with ${kept}`, dst);
+                    }
+                }
+                await routed.unlink(dst);
+            }
+            await routed.symlink(kept, dst);
+            return;
+        }
+        if (!from.isFile() && !from.isCharacterDevice() && !from.isBlockDevice()) {
+            const [code, kind] = from.isSocket()
+                ? ['ERR_FS_CP_SOCKET', 'a socket file']
+                : from.isFIFO()
+                    ? ['ERR_FS_CP_FIFO_PIPE', 'a FIFO pipe']
+                    : ['ERR_FS_CP_UNKNOWN', 'an unknown file type'];
+            throw cpRefusal(code, `Cannot copy ${kind}`, 'EINVAL', `cannot copy ${kind}: ${dst}`, dst);
+        }
+        if (to !== null) {
+            if (opts.force === false) {
+                if (opts.errorOnExist !== true)
+                    return;
+                throw cpRefusal('ERR_FS_CP_EEXIST', 'Target already exists', 'EEXIST', `${dst} already exists`, dst);
+            }
+            await routed.unlink(dst);
+        }
+        await routed.copyFile(src, dst, typeof opts.mode === 'number' ? opts.mode : 0);
+        if (opts.preserveTimestamps === true)
+            await routed.utimes(dst, from.atime, from.mtime);
+        await routed.chmod(dst, from.mode & 0o7777);
+    }
+    /** The names `pattern` matches, as node's `fs.promises.glob` yields
+     * them: by node's own matcher, under the part of the pattern that has
+     * no wildcard, relative to `cwd` for a relative pattern. */
+    async *glob(pattern, options) {
+        const opts = fieldsOf(options);
+        const cwd = spelled(opts.cwd) ?? process.cwd();
+        const exclude = opts.exclude;
+        const typed = opts.withFileTypes === true;
+        const follow = opts.followSymlinks === true;
+        const seen = new Set();
+        for (const raw of Array.isArray(pattern) ? pattern : [pattern]) {
+            const spelling = spelled(raw);
+            if (spelling === null)
+                continue;
+            const spelt = posix.isAbsolute(spelling)
+                ? posix.normalize(spelling)
+                : posix.join(cwd, spelling);
+            // A trailing slash asks for directories, named without it.
+            const directories = spelt.length > 1 && spelt.endsWith('/');
+            const absolute = directories ? spelt.slice(0, -1) : spelt;
+            const shown = (path) => posix.isAbsolute(spelling) ? path : posix.relative(cwd, path) || '.';
+            const parts = absolute.split('/').slice(1);
+            const magic = parts.findIndex((part) => GLOB_MAGIC.test(part));
+            const base = `/${parts.slice(0, magic === -1 ? parts.length : magic).join('/')}`;
+            const rest = magic === -1 ? '' : parts.slice(magic).join('/');
+            // A `**` that is a whole name, inside braces too, may match at any
+            // depth; within a name (`foo**`) it is a `*`.
+            const depth = /(^|[/{,])\*\*($|[/},])/.test(rest) ? Infinity : rest.split('/').length;
+            // An exclusion is matched from `cwd` and from the root alike,
+            // whichever way the pattern is spelled, as node matches it.
+            const skipped = (path, named, entry) => {
+                if (typeof exclude === 'function')
+                    return Boolean(exclude(typed ? entry : named));
+                const spellings = [path, posix.relative(cwd, path) || '.'];
+                return (Array.isArray(exclude) &&
+                    exclude.some((ex) => spellings.some((name) => posix.matchesGlob(name, String(ex)))));
+            };
+            let top;
+            try {
+                top = await this.entryOf(base, true);
+            }
+            catch (err) {
+                if (!isMissingPath(err))
+                    throw err;
+                continue;
+            }
+            const baseEntry = {
+                name: posix.basename(base),
+                parentPath: posix.dirname(base),
+                path: posix.dirname(base),
+                isFile: () => top.isFile(),
+                isDirectory: () => top.isDirectory(),
+                isBlockDevice: () => false,
+                isCharacterDevice: () => false,
+                isSymbolicLink: () => false,
+                isFIFO: () => false,
+                isSocket: () => false,
+            };
+            // Each entry carries the directories its branch went through, by
+            // where their links lead, so a followed link never walks into one
+            // of them again, as node's walk does.
+            const pending = [[base, '', 0, baseEntry, []]];
+            for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+                const [path, relative, level, entry, walked] = next;
+                const named = shown(path);
+                // An excluded name is left out with all under it, the base too.
+                if (skipped(path, named, entry))
+                    continue;
+                const kind = entry;
+                // `followSymlinks` takes a link to a directory as one.
+                const isDirectory = kind.isDirectory() ||
+                    (follow && kind.isSymbolicLink() && (await this.linksToDirectory(path)));
+                if ((magic === -1 ? relative === '' : posix.matchesGlob(relative, rest)) &&
+                    (!directories || isDirectory) &&
+                    !seen.has(named)) {
+                    seen.add(named);
+                    yield typed ? entry : named;
+                }
+                if (magic === -1 || !isDirectory || level >= depth)
+                    continue;
+                // A mounted directory's name is where the namespace's links lead,
+                // which needs no lookup; a host one is node's own realpath.
+                const real = !follow
+                    ? path
+                    : this.mounted(path)
+                        ? this.files.walked(path)
+                        : await routed.realpath(path);
+                if (follow && walked.includes(real))
+                    continue;
+                const branch = follow ? [...walked, real] : walked;
+                const children = (await routed.readdir(path, { withFileTypes: true }));
+                for (const child of children) {
+                    const childPath = posix.join(path, child.name);
+                    pending.push([
+                        childPath,
+                        relative === '' ? child.name : `${relative}/${child.name}`,
+                        child.isSymbolicLink() && !follow ? depth : level + 1,
+                        child,
+                        branch,
+                    ]);
+                }
+            }
+        }
+    }
+    async mkdtemp(prefix, options) {
+        // A prefix whose names fall outside the mount (`/data` makes
+        // `/dataXXXXXX`) is the host's.
+        if (!this.mounted(`${prefix}XXXXXX`))
+            return this.nativeCall('mkdtemp', prefix, options);
+        // Six characters after the prefix, as node's template has them, drawn
+        // again for a name already there.
+        for (;;) {
+            const path = prefix + tempSuffix();
+            try {
+                await this.files.mkdir(path);
+                await this.narrowed(path, 0o700);
+                return encoded(path, options);
+            }
+            catch (err) {
+                if (classify(err) !== 'EEXIST')
+                    throw fsError(err, 'mkdtemp', path);
+            }
+        }
+    }
+    async mkdtempDisposable(prefix, options) {
+        // The name handed back takes the encoding asked for; the removal takes
+        // the directory's own.
+        const made = String(await this.mkdtemp(prefix));
+        const remove = () => routed.rm(made, { recursive: true, force: true });
+        return { path: encoded(made, options), remove, [Symbol.asyncDispose]: remove };
+    }
+    async opendir(path, options) {
+        try {
+            return openedDir(path, await this.readdir(path, {
+                withFileTypes: true,
+                recursive: fieldsOf(options).recursive === true,
+                encoding: fieldsOf(options).encoding,
+            }));
+        }
+        catch (err) {
+            throw fsError(err, 'opendir', path);
+        }
+    }
+    async realpath(path, options) {
+        // As realpath(3) walks a path: each name in turn, a link swapped for
+        // where it leads, so a `..` after a link climbs from its target.
+        const todo = path.split('/');
+        let done = '/';
+        let hops = 0;
+        for (let name = todo.shift(); name !== undefined; name = todo.shift()) {
+            if (name === '' || name === '.')
+                continue;
+            if (name === '..') {
+                done = posix.dirname(done);
+                continue;
+            }
+            const next = posix.join(done, name);
+            let st;
+            try {
+                st = await this.files.stat(next, true);
+            }
+            catch (err) {
+                throw fsError(err, 'realpath', path);
+            }
+            if (st.isLink === true) {
+                if (++hops > MAX_SYMLINK_HOPS)
+                    throw refusal('ELOOP', 'realpath', path);
+                const target = await this.files.readlink(next);
+                if (target.startsWith('/'))
+                    done = '/';
+                todo.unshift(...target.split('/'));
+                continue;
+            }
+            if (!st.isDir && todo.some((rest) => rest !== ''))
+                throw refusal('ENOTDIR', 'realpath', path);
+            done = next;
+        }
+        return encoded(done, options);
+    }
     async readFile(path, options) {
         const bytes = Buffer.from(await this.files.read(path));
         const encoding = encodingOf(options);
@@ -493,7 +866,7 @@ class HostFs {
         const walk = async (directory, prefix) => {
             for (const row of await this.files.readdir(directory, typed || recursive)) {
                 const name = entryName(row.path);
-                out.push(typed ? this.direntOf(directory, row) : prefix + name);
+                out.push(typed ? dirent(directory, row, encoded(name, options)) : encoded(prefix + name, options));
                 if (recursive && row.isDir && row.isLink !== true) {
                     await walk(posix.join(directory, name), `${prefix}${name}/`);
                 }
@@ -503,40 +876,26 @@ class HostFs {
         return out;
     }
     async readlink(path, options) {
-        const target = await this.files.readlink(path);
-        const encoding = encodingOf(options);
-        if (encoding === undefined || encoding === 'utf8')
-            return target;
-        const bytes = Buffer.from(target);
-        return encoding === 'buffer' ? bytes : bytes.toString(encoding);
+        return encoded(await this.files.readlink(path), options);
     }
     async rename(src, dst) {
         // A move between a mount and the host is EXDEV, the kernel's answer
         // for two filesystems and the errno a mover retries as copy + delete.
         if (!this.mounted(src) || !this.mounted(dst))
             throw refusal('EXDEV', 'rename', src);
-        // Both ends as the walk names them before the rename, which may move a
-        // link the walk takes. A rename onto its own name changes nothing, its
-        // descriptors included.
-        const from = this.descriptors.walked(src, false);
-        const to = this.descriptors.walked(dst, false);
-        const held = from === to ? [] : await this.descriptors.hold(dst);
+        // The descriptors open on either end follow it (the core sees to it).
         await this.files.rename(src, dst);
-        this.descriptors.keep(held);
-        this.descriptors.moved(from, to);
     }
     /** Remove a file, the descriptors open on it keeping the bytes it had. */
     async removeFile(path) {
-        const held = await this.descriptors.hold(path);
         await this.files.unlink(path);
-        this.descriptors.keep(held);
     }
     async rm(path, options) {
         const force = fieldsOf(options).force === true;
         const recursive = fieldsOf(options).recursive === true;
         // A mount root is refused however it is spelled (`/data/.`), before
         // the stat a backend may answer for that spelling or not.
-        if (this.ws.registry.isMountRoot(posix.normalize(path)))
+        if (this.ws.vfs.isMount(posix.normalize(path)))
             throw refusal('EBUSY', 'rm', path);
         let st;
         try {
@@ -578,7 +937,7 @@ class HostFs {
      * before anything goes, as the agent adapters plan it, so a mount root
      * anywhere in it refuses the call with nothing removed. */
     async plan(path, isDir, out, top, where) {
-        if (this.ws.registry.isMountRoot(posix.normalize(path)))
+        if (this.ws.vfs.isMount(posix.normalize(path)))
             throw refusal('EBUSY', 'rm', path);
         if (isDir) {
             this.held(path, where);
@@ -613,7 +972,7 @@ class HostFs {
     async rmdir(path) {
         // rmdir(2) on a mount point is EBUSY. A mount root is the
         // deployment's own, which the shell's rm refuses the same way.
-        if (this.ws.registry.isMountRoot(posix.normalize(path))) {
+        if (this.ws.vfs.isMount(posix.normalize(path))) {
             throw refusal('EBUSY', 'rmdir', path);
         }
         await this.files.rmdir(path);
@@ -628,16 +987,14 @@ class HostFs {
         // truncate(2) names a file that is there; the op creates a missing
         // one, as GNU truncate does without -c.
         await this.files.stat(path);
-        await this.descriptors.landPath(path);
         await this.files.truncate(path, length);
     }
     async unlink(path) {
         await this.removeFile(path);
     }
     async utimes(path, atime, mtime) {
-        // Writes a descriptor still owes land first, or landing them at its
-        // close would stamp over the times set here.
-        await this.descriptors.landPath(path);
+        // Writes a descriptor still owes land first (the core sees to it), or
+        // landing them at its close would stamp over the times set here.
         await this.files.setattr(path, { atime: stampOf(atime), mtime: stampOf(mtime) });
     }
     async writeFile(path, data, options) {
@@ -650,7 +1007,7 @@ class HostFs {
             throw ebadf(String(target.fd));
         const fd = target instanceof MountedFileHandle ? target.fd : target;
         if (name === 'readFile') {
-            const read = () => readOn(this.descriptors.file(fd, true, false), -1);
+            const read = () => this.descriptors.file(fd, true, false).read(-1);
             const bytes = Buffer.from(await this.descriptors.serial(fd, read));
             const encoding = encodingOf(rest[0]);
             return encoding === undefined ? bytes : bytes.toString(encoding);
@@ -671,22 +1028,23 @@ class HostFs {
     /** A read into `buffer` at `offset`, at `position` or, when null, at the
      * descriptor's own position, advancing it. The caller holds its queue. */
     async readInto(fd, buffer, offset, length, position) {
-        const handle = this.descriptors.file(fd, true, false);
-        const bytes = position === null ? await readOn(handle, length) : await readAt(handle, position, length);
+        const desc = this.descriptors.file(fd, true, false);
+        const bytes = position === null ? await desc.read(length) : await desc.pread(position, length);
         buffer.set(bytes, offset);
         return bytes.byteLength;
     }
     /** A write through a mounted descriptor, in its turn on the descriptor. */
     fdWrite(fd, bytes, position) {
-        return this.descriptors.serial(fd, () => {
-            const handle = this.descriptors.file(fd, false, true);
+        return this.descriptors.serial(fd, async () => {
+            const desc = this.descriptors.file(fd, false, true);
             // Linux appends a positioned write on an O_APPEND descriptor,
-            // whatever the position, and leaves the position where it was.
+            // whatever the position, and leaves the position where it was: the
+            // core writes an appending handle at its end.
             if (position === null)
-                handle.write(bytes.slice());
+                await desc.write(bytes.slice());
             else
-                handle.pwrite(handle.append ? handle.size : position, bytes.slice());
-            return Promise.resolve(bytes.byteLength);
+                await desc.pwrite(position, bytes.slice());
+            return bytes.byteLength;
         });
     }
     /** A descriptor call on a mounted descriptor, answered with what node's
@@ -730,23 +1088,17 @@ class HostFs {
                     return [await this.fdWrite(fd, joined, position), buffers];
                 }
                 case 'fstat': {
-                    const st = desc.kept !== null && desc.stat !== null ? desc.stat : await this.files.stat(desc.path);
-                    const size = desc.handle?.size ?? st.size;
-                    return [
-                        this.statsOf(desc.opened, { ...st, size }, rest[0], desc.kept !== null),
-                    ];
+                    const row = await this.files.fstat(desc.fd);
+                    return [this.statsOf(desc.inode, row, rest[0], this.files.unlinked(desc.fd))];
                 }
                 case 'ftruncate':
                     if (!desc.mode.writable)
                         throw einval(desc.path);
-                    await this.descriptors.serial(fd, () => {
-                        this.descriptors.file(fd, false, true).truncate(Math.max(0, Number(rest[0] ?? 0)));
-                        return Promise.resolve();
-                    });
+                    await this.descriptors.serial(fd, () => this.descriptors.file(fd, false, true).truncate(Math.max(0, Number(rest[0] ?? 0))));
                     return [];
                 case 'fsync':
                 case 'fdatasync':
-                    await this.descriptors.serial(fd, () => this.descriptors.land(desc));
+                    await this.descriptors.serial(fd, () => desc.land());
                     return [];
                 case 'close':
                     await this.descriptors.close(fd);
@@ -775,16 +1127,16 @@ class HostFs {
         const given = fieldsOf(options).flag;
         const flag = typeof given === 'string' ? given : fallback;
         const bytes = bytesOf(data, options);
-        if (flag.includes('x') && (await this.files.statOrNull(path, true)) !== null) {
-            throw refusal('EEXIST', 'open', path);
+        // An open, a write and a close through the core, as node's own do, so
+        // the descriptors open on the file see it and an exclusive flag refuses
+        // a name that is there.
+        const fd = await this.files.open(path, openMode(openFlags(flag), constants));
+        try {
+            await this.files.pwrite(fd, 0, bytes);
+        }
+        finally {
+            await this.files.close(fd);
         }
-        // What descriptors on the file still owe lands first, so their older
-        // writes never land over this one.
-        await this.descriptors.landPath(path);
-        if (flag.startsWith('a'))
-            await this.files.append(path, bytes);
-        else
-            await this.files.write(path, bytes);
     }
 }
 /**
@@ -850,6 +1202,7 @@ export function patchNodeFs(ws) {
     const byDescriptor = (name, args) => FILE_CALLS.has(name) &&
         (host.descriptors.get(args[0]) !== undefined || args[0] instanceof MountedFileHandle);
     for (const name of ROUTED_CALLS) {
+        // A promise, or for `glob` the iterator node's answers with.
         const route = (args) => host[name].call(host, ...spellPaths(name, args));
         swap(fs.promises, name, (original) => (...args) => {
             if (byDescriptor(name, args))
@@ -866,8 +1219,10 @@ export function patchNodeFs(ws) {
             if (typeof done !== 'function' || mountedIn(name, rest) === null)
                 return original(...args);
             const callback = done;
-            // `exists` is the one callback without an error slot.
-            route(rest).then((value) => {
+            const answered = route(rest);
+            (name === 'glob'
+                ? collected(answered)
+                : answered).then((value) => {
                 if (name === 'exists')
                     callback(value);
                 else
@@ -888,10 +1243,11 @@ export function patchNodeFs(ws) {
             if (path === null)
                 return original(...args);
             // existsSync answers false where it cannot look, as node's does for
-            // any path whose stat fails; a mount's root is the one name it
-            // knows is there without asking.
+            // any path whose stat fails; the root of a mount the session sees
+            // is the one name it knows is there without asking, unless a `..`
+            // in the spelling walks through a name it has not checked.
             if (name === 'exists')
-                return ws.registry.isMountRoot(path);
+                return !path.split('/').includes('..') && ws.vfs.isMount(path);
             throw syncRefusal(`${name}Sync`, path);
         });
     }