@nimbus-sh/worker 0.8.0 → 0.10.0

package/dist/runtime/node-shims.js

@@ -45,7 +45,7 @@ import { getExportsResolverJS } from '@nimbus-sh/core/_shared/exports-resolver.j
 import { getTypescriptSpecifiersJS } from '@nimbus-sh/core/_shared/typescript-specifiers.js';
 import { NIMBUS_AI_CREDENTIAL_HEADERS, NIMBUS_AI_TOKEN_ENV } from '@nimbus-sh/core/_shared/ai-egress.js';
 import { MAX_RPC_SAFE_PAYLOAD_BYTES } from '@nimbus-sh/platform/limits.js';
-import { FACET_PROVIDED_PACKAGES, FS_READ_BATCH_PATH_LIMIT, FS_READ_BATCH_REQUEST_BYTES, NIMBUS_AI_GATEWAY_PORT, NODE_VERSION, NODE_VERSIONS, } from '@nimbus-sh/core/constants.js';
+import { FACET_PROVIDED_PACKAGES, FS_READ_BATCH_PATH_LIMIT, FS_READ_BATCH_REQUEST_BYTES, NIMBUS_AI_GATEWAY_PORT, NODE_VERSION, NODE_VERSIONS, VFS_CAPACITY, } from '@nimbus-sh/core/constants.js';
 const STREAMS_CODE = generateStreamsCode();
 const SQLITE_SHIM_CODE = generateSqliteShimCode();
 const UNDICI_SHIM_CODE = generateUndiciShimCode();
@@ -634,6 +634,43 @@ function __residentAnyUnder(prefix) {
   return false;
 }
 
+// ═══════════════════════════════════════════════════════════════════════
+// ──  fs.constants (linux x64) ───────────────────────────────────────
+// ═══════════════════════════════════════════════════════════════════════
+//
+// The ONE table behind fs.constants, fs.promises.constants, and the fs slice
+// of node:constants / process.binding('fs'). Values are real Node on Linux
+// x64 (node -p 'require("fs").constants'). Packages compose open flags from
+// this table at module init — modern-tar (create-astro via @bluwy/giget-core)
+// computes O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW|O_EXCL and passes the number
+// to fs.open — so a partial table silently degrades every such open to
+// O_RDONLY (0) and every extraction fails ENOENT. Frozen, as Node's is.
+const __fsConstants = Object.freeze({
+  // ── libuv fs flags ────────────────────────────────────────────────
+  UV_FS_SYMLINK_DIR: 1, UV_FS_SYMLINK_JUNCTION: 2,
+  // ── open(2) flags ─────────────────────────────────────────────────
+  O_RDONLY: 0, O_WRONLY: 1, O_RDWR: 2,
+  UV_DIRENT_UNKNOWN: 0, UV_DIRENT_FILE: 1, UV_DIRENT_DIR: 2, UV_DIRENT_LINK: 3,
+  UV_DIRENT_FIFO: 4, UV_DIRENT_SOCKET: 5, UV_DIRENT_CHAR: 6, UV_DIRENT_BLOCK: 7,
+  EXTENSIONLESS_FORMAT_JAVASCRIPT: 0, EXTENSIONLESS_FORMAT_WASM: 1,
+  // ── stat.mode file-type bits ──────────────────────────────────────
+  S_IFMT: 61440, S_IFREG: 32768, S_IFDIR: 16384, S_IFCHR: 8192,
+  S_IFBLK: 24576, S_IFIFO: 4096, S_IFLNK: 40960, S_IFSOCK: 49152,
+  O_CREAT: 64, O_EXCL: 128, UV_FS_O_FILEMAP: 0, O_NOCTTY: 256, O_TRUNC: 512,
+  O_APPEND: 1024, O_DIRECTORY: 65536, O_NOATIME: 262144, O_NOFOLLOW: 131072,
+  O_SYNC: 1052672, O_DSYNC: 4096, O_DIRECT: 16384, O_NONBLOCK: 2048,
+  // ── stat.mode permission bits ─────────────────────────────────────
+  S_IRWXU: 448, S_IRUSR: 256, S_IWUSR: 128, S_IXUSR: 64,
+  S_IRWXG: 56, S_IRGRP: 32, S_IWGRP: 16, S_IXGRP: 8,
+  S_IRWXO: 7, S_IROTH: 4, S_IWOTH: 2, S_IXOTH: 1,
+  // ── fs.access modes ───────────────────────────────────────────────
+  F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1,
+  // ── fs.copyFile modes (libuv shape + Node alias) ──────────────────
+  UV_FS_COPYFILE_EXCL: 1, COPYFILE_EXCL: 1,
+  UV_FS_COPYFILE_FICLONE: 2, COPYFILE_FICLONE: 2,
+  UV_FS_COPYFILE_FICLONE_FORCE: 4, COPYFILE_FICLONE_FORCE: 4,
+});
+
 // ═══════════════════════════════════════════════════════════════════════
 // ──  fs shim (VFS-backed) ───────────────────────────────────────────
 // ═══════════════════════════════════════════════════════════════════════
@@ -1271,6 +1308,10 @@ const __fsMod = (() => {
       mtimeMs: _coerceTimeMs(mtime, syscall, p),
     };
     _localTimes[k] = time;
+    // A spawn-time stat record answers statSync ahead of _localTimes, so it
+    // must carry the new times too or the sync view keeps the old mtime.
+    const meta = _metadata(absPath);
+    if (meta) { meta.atime = time.atimeMs; meta.mtime = time.mtimeMs; }
     return time;
   }
 
@@ -1412,6 +1453,27 @@ const __fsMod = (() => {
     return evicted;
   }
 
+  // Cells an own-mutation lease evicted with no barrier in hand.
+  //
+  // A barrier hands _acquireAndRefetch every path it dropped, which is what
+  // keeps a sync read inside a timer callback reading the peer's new bytes
+  // instead of EAGAIN. A lease's end drops a cell on its own account — the
+  // barrier that would have reported it was suppressed by the lease itself
+  // — so the same debt is recorded here and settled by the next untrusted
+  // resumption.
+  const _owedRefetch = new Set();
+
+  // An own-mutation lease can end in an eviction (a peer wrote inside the
+  // window). The ledger owning that decision is spliced AHEAD of this
+  // closure, so it is handed the one eviction path rather than keeping a
+  // second copy of it: content view, stat view, the invalidation count and
+  // the refetch debt move together here or not at all.
+  globalThis.__nimbusEvictResidentCell = (k) => {
+    if (!_evictResident(k)) return;
+    _stats.invalidations++;
+    _owedRefetch.add(k);
+  };
+
   /**
    * Install bytes the supervisor just served as the resident cell for a
    * path, at the cursor they were served under.
@@ -1591,6 +1653,11 @@ const __fsMod = (() => {
     } else if (Array.isArray(result.paths)) {
       for (const entry of result.paths) {
         const k = entry.path;
+        // This cursor is about to advance past the report, so a path with
+        // one of this facet's own writes in flight keeps the number: only
+        // that write's own revision, when it arrives, can say whether the
+        // report was itself or a peer. Everything else ignores it.
+        __nimbusNoteVfsReport(k, entry.rev);
         if (__vfsBundleRevisions[k] >= entry.rev) { _stats.selfWrites++; continue; }
         const held = !!(__vfsBundle && k in __vfsBundle);
         if (_evictResident(k)) _stats.invalidations++;
@@ -1624,6 +1691,13 @@ const __fsMod = (() => {
    */
   async function _acquireAndRefetch(supervisor) {
     const stale = await _acquireBarrier(supervisor);
+    // Plus what an own-mutation lease dropped since the last resumption:
+    // the same debt this function exists to settle, owed by an eviction
+    // that had no barrier to report it (see _owedRefetch).
+    if (_owedRefetch.size > 0) {
+      for (const k of _owedRefetch) if (stale.indexOf(k) === -1) stale.push(k);
+      _owedRefetch.clear();
+    }
     if (stale.length === 0) return;
     await Promise.all(stale.map((k) => _liveReadFile("/" + k, undefined, true).catch(() => {})));
   }
@@ -1724,7 +1798,16 @@ const __fsMod = (() => {
   // supervisor.mkdir is recursive, so the deepest unannounced one creates all
   // of them in a single round trip; a path whose directories are already live
   // (the common case) costs none at all.
+  //
+  // This is also the one seam every asynchronous fs entry point crosses on
+  // its way to the authority — directly, or through
+  // _flushLocalPathToSupervisor — so it is where a live call waits for the
+  // structural mutations the program issued synchronously before it:
+  // mkdirSync, rmdirSync, unlinkSync, renameSync queue their authority RPC
+  // (below) rather than land it, and an open/stat/readdir that overtook that
+  // queue would be answered for a tree the program has already changed.
   async function _announceLocalDirs(absPath, supervisor) {
+    await _awaitStructuralOrder(absPath);
     if (!__vfsDirs || typeof supervisor.mkdir !== "function") return;
     const pending = [];
     let key = "";
@@ -1740,24 +1823,142 @@ const __fsMod = (() => {
     _markVfsStale();
   }
 
+  // The write ledger is spliced ahead of the shims in every runner
+  // (facets/manager.ts, opencode-facet-runner.ts). A harness that evaluates
+  // the shims alone has no mutation queue and therefore nothing to wait for;
+  // an absent ledger must not be an error on a read path that never needed
+  // one before.
+  function _hasVfsMutationQueue() {
+    return typeof __nimbusQueueVfsMutation === "function";
+  }
+  function _awaitStructuralOrder(absPath) {
+    return _hasVfsMutationQueue() ? __nimbusAwaitAncestorMutations(absPath) : Promise.resolve();
+  }
+
+  /**
+   * Carry a synchronous structural mutation to the authority.
+   *
+   * mkdirSync, rmdirSync, unlinkSync and renameSync used to edit the local
+   * tables and stop: a sync syscall cannot make an RPC, and unlike a sync
+   * write they parked nothing the write-back could later flush. Measured
+   * live: node-tar's \`mkdirSync(dir)\` then \`fs.promises.open(dir/file,
+   * "w")\` — once per extracted entry — was answered ENOENT by an authority
+   * that had never heard of \`dir\`; that is create-astro's template copy.
+   *
+   * The sync effect stays exactly as it was. What is added is the same RPC
+   * the asynchronous form of the call issues, queued through the write
+   * ledger so it registers with the exit drain, is ordered behind pending
+   * mutations of its ancestors (the ledger does that for every queued
+   * mutation), and — for the two that act on a subtree — behind pending
+   * mutations beneath it. The async forms are that same queued call, awaited.
+   *
+   * \`null\` when there is no authority to tell: standalone and unit contexts
+   * keep today's local-only behaviour. Without a ledger the RPC is issued
+   * directly, which is what the async forms did before they were queued.
+   */
+  // \`method\` names the supervisor RPC when it differs from the syscall the
+  // caller reports (lchown rides \`chown\`, rm rides \`fsRemove\`).
+  function _queueStructuralMutation(absPath, syscall, displayPath, rpc, after, method) {
+    const supervisor = _supervisor();
+    if (!supervisor || typeof supervisor[method || syscall] !== "function") return null;
+    const queued = _hasVfsMutationQueue();
+    const before = queued && after ? after() : null;
+    const run = async () => {
+      if (before) await before;
+      // Only chown answers with a receipt. The rest (mkdir, unlink, rmdir,
+      // rename, rm) have already dropped the path's cell and stamp in their
+      // synchronous half, so no lease is taken at all; where one is — the
+      // stamp unlink leaves behind — an absent receipt retires it, which is
+      // what an unstamped cell already costs.
+      await _ownMutation(
+        absPath,
+        () => _fsRpc(rpc(supervisor), syscall, displayPath, (result) => result),
+      );
+      _markVfsStale();
+    };
+    return queued ? __nimbusQueueVfsMutation(absPath, run) : run();
+  }
+
+  /**
+   * Run one of this facet's own partial mutations under a lease.
+   *
+   * See __nimbusBeginOwnMutation: the barrier KEEPS the cell while the RPC
+   * is in flight — a barrier issued after this mutation can be answered
+   * ahead of it, and an eviction there loses bytes no later stamp can
+   * recover — and the receipt decides at the end. \`apply\` lands the local
+   * effect while the lease still holds the cell, so the stamp the end
+   * settles describes a cell that already carries the mutation.
+   *
+   * Heap-side stamps do not describe rows in the resident store, so store
+   * mode has no lease to take and is left to the store's own provenance.
+   */
+  async function _ownMutation(absPath, rpc, apply) {
+    const key = _strip(absPath);
+    const held = !_residentStorePresent() && __nimbusBeginOwnMutation(key);
+    let receipt;
+    let landed = false;
+    try { receipt = await rpc(); landed = true; }
+    finally {
+      // The local effect follows the mutation landing, not the receipt: the
+      // receipt only settles the stamp, and a supervisor that answers
+      // without one still applied the bytes. The end runs even if applying
+      // throws: a lease left open pins its cell at Infinity, which is the one
+      // state in this protocol that can serve a stale byte forever.
+      try { if (landed && apply) apply(receipt); }
+      finally { __nimbusEndOwnMutation(key, held, receipt); }
+    }
+    return receipt;
+  }
+
+  // A sync caller has no frame to receive the outcome. The ledger already
+  // marks a queued result handled and retains what the exit drain must
+  // report; this only keeps a ledger-less embedding from raising an
+  // unhandled rejection for a verdict nobody could catch.
+  function _detachStructuralMutation(mutation) {
+    if (mutation) mutation.then(undefined, () => undefined);
+  }
+
+  // A rename lives at two names. Its mutation is queued under the source;
+  // this parks a fence under the destination so that anything queued for the
+  // destination, or an ancestor wait that passes through it, is ordered
+  // behind the move as well. The fence never fails on its own account.
+  function _fenceVfsMutation(absPath, mutation) {
+    if (!mutation || !_hasVfsMutationQueue()) return;
+    __nimbusQueueVfsMutation(absPath, () => mutation.then(() => undefined, () => undefined), false);
+  }
+
+  // Queue the parked write for \`absPath\`, if any, on the path's mutation
+  // tail. Registration is synchronous: a caller that queues its own mutation
+  // on the same tail right after this call is ordered behind the flush.
+  function _flushParkedWrite(absPath, supervisor) {
+    const k = _strip(absPath);
+    if (!__vfsWrites || !(k in __vfsWrites) || typeof supervisor.writeFile !== "function") {
+      return Promise.resolve(undefined);
+    }
+    return __nimbusFlushVfsWrite(
+      absPath,
+      (content, snapshot) => _fsRpc(
+        __nimbusPersistVfsWrite(supervisor, absPath, content, snapshot),
+        "write", absPath,
+        (result) => result,
+      ),
+    );
+  }
+
   async function _flushLocalPathToSupervisor(absPath, supervisor) {
     const k = _strip(absPath);
     await _announceLocalDirs(absPath, supervisor);
     if (__vfsWrites && k in __vfsWrites && typeof supervisor.writeFile === "function") {
-      await __nimbusFlushVfsWrite(
-        absPath,
-        (content, snapshot) => _fsRpc(
-          __nimbusPersistVfsWrite(supervisor, absPath, content, snapshot),
-          "write", absPath,
-          (result) => result,
-        ),
-      );
+      await _flushParkedWrite(absPath, supervisor);
       _markVfsStale();
     }
     // Pending sync chmod rides along with any flush of the same path
     // (idempotent — the entry stays so local statSync remains coherent).
     if (k in _localModes && typeof supervisor.chmod === "function") {
-      await _fsRpc(supervisor.chmod(absPath, _localModes[k]), "chmod", absPath, () => undefined);
+      await _ownMutation(
+        absPath,
+        () => _fsRpc(supervisor.chmod(absPath, _localModes[k]), "chmod", absPath, (result) => result),
+      );
       _markVfsStale();
     }
   }
@@ -1852,16 +2053,26 @@ const __fsMod = (() => {
     return stat;
   }
 
-  function _direntObject(name, type) {
-    const isDir = type === "directory" || type === "dir";
-    const isSymlink = type === "symlink";
-    return {
-      name,
-      isFile: () => !isDir && !isSymlink,
-      isDirectory: () => isDir,
-      isSymbolicLink: () => isSymlink,
-    };
+  // The one Dirent shape: readdir({ withFileTypes }) sync and async, and
+  // every Dir.read(). \`parentPath\` is Node's field; \`path\` its deprecated
+  // alias that older callers still read.
+  class __Dirent {
+    constructor(name, type, parentPath) {
+      this.name = name;
+      this.parentPath = parentPath === undefined ? "" : String(parentPath);
+      this.path = this.parentPath;
+      this._isDir = type === "directory" || type === "dir";
+      this._isSymlink = type === "symlink";
+    }
+    isFile() { return !this._isDir && !this._isSymlink; }
+    isDirectory() { return this._isDir; }
+    isSymbolicLink() { return this._isSymlink; }
+    isBlockDevice() { return false; }
+    isCharacterDevice() { return false; }
+    isFIFO() { return false; }
+    isSocket() { return false; }
   }
+  function _direntObject(name, type, parentPath) { return new __Dirent(name, type, parentPath); }
 
   // Largest single ranged read issued against the supervisor. Every live
   // read path (read streams, whole-file async reads) is expressed as a
@@ -2125,7 +2336,7 @@ const __fsMod = (() => {
         }
         if (opts?.withFileTypes) {
           return entries
-            .map((entry) => _direntObject(entry.name, entry.type))
+            .map((entry) => _direntObject(entry.name, entry.type, absPath))
             .sort((a, b) => a.name.localeCompare(b.name));
         }
         return entries.map((entry) => entry.name).sort();
@@ -2148,7 +2359,9 @@ const __fsMod = (() => {
   async function _readlinkAsync(p) {
     const supervisor = _supervisor();
     if (supervisor && typeof supervisor.readlink === "function") {
-      const target = await _fsRpc(supervisor.readlink(_resolve(p)), "readlink", p, (result) => result);
+      const absPath = _resolve(p);
+      await _awaitStructuralOrder(absPath);
+      const target = await _fsRpc(supervisor.readlink(absPath), "readlink", p, (result) => result);
       if (target !== null && target !== undefined) return target;
     }
     throw _fsErr("EINVAL", "readlink", p);
@@ -2157,7 +2370,9 @@ const __fsMod = (() => {
   async function _symlinkAsync(target, path) {
     const supervisor = _supervisor();
     if (supervisor && typeof supervisor.symlink === "function") {
-      await _fsRpc(supervisor.symlink(String(target), _resolve(path)), "symlink", path, () => undefined);
+      const absPath = _resolve(path);
+      await _awaitStructuralOrder(absPath);
+      await _fsRpc(supervisor.symlink(String(target), absPath), "symlink", path, () => undefined);
       _markVfsStale();
       return;
     }
@@ -2170,8 +2385,10 @@ const __fsMod = (() => {
     const supervisor = _supervisor();
     if (supervisor && typeof supervisor.writeFile === "function") {
       await _announceLocalDirs(absPath, supervisor);
+      // The revision comes back so the ledger can stamp the cell: an async
+      // whole write is the facet's own as much as a parked sync one is.
       await __nimbusFlushVfsWrite(absPath, (content) =>
-        _fsRpc(supervisor.writeFile(absPath, content), "write", p, () => undefined)
+        _fsRpc(supervisor.writeFile(absPath, content), "write", p, (result) => result)
       );
       _markVfsStale();
     }
@@ -2194,41 +2411,13 @@ const __fsMod = (() => {
     _markVfsStale();
   }
 
-  async function _mkdirAsync(p, opts) {
-    mkdirSync(p, opts);
-    const supervisor = _supervisor();
-    if (supervisor && typeof supervisor.mkdir === "function") {
-      await _fsRpc(supervisor.mkdir(_resolve(p)), "mkdir", p, () => undefined);
-      _markVfsStale();
-    }
-  }
-
-  async function _unlinkAsync(p) {
-    unlinkSync(p);
-    const supervisor = _supervisor();
-    if (supervisor && typeof supervisor.unlink === "function") {
-      await _fsRpc(supervisor.unlink(_resolve(p)), "unlink", p, () => undefined);
-      _markVfsStale();
-    }
-  }
-
-  async function _rmdirAsync(p) {
-    rmdirSync(p);
-    const supervisor = _supervisor();
-    if (supervisor && typeof supervisor.rmdir === "function") {
-      await _fsRpc(supervisor.rmdir(_resolve(p)), "rmdir", p, () => undefined);
-      _markVfsStale();
-    }
-  }
-
-  async function _renameAsync(oldP, newP) {
-    renameSync(oldP, newP);
-    const supervisor = _supervisor();
-    if (supervisor && typeof supervisor.rename === "function") {
-      await _fsRpc(supervisor.rename(_resolve(oldP), _resolve(newP)), "rename", oldP, () => undefined);
-      _markVfsStale();
-    }
-  }
+  // The async structural calls ARE the sync ones, awaited: the same local
+  // effect and the same queued authority RPC, so the two forms cannot
+  // disagree about order, and a program mixing them sees one sequence.
+  async function _mkdirAsync(p, opts) { await _mkdirQueued(p, opts); }
+  async function _unlinkAsync(p) { await _unlinkQueued(p); }
+  async function _rmdirAsync(p) { await _rmdirQueued(p); }
+  async function _renameAsync(oldP, newP) { await _renameQueued(oldP, newP); }
 
   async function _truncateAsync(p, len) {
     const absPath = _resolve(p);
@@ -2246,6 +2435,9 @@ const __fsMod = (() => {
             (content, snapshot) =>
               __nimbusPersistVfsWrite(supervisor, absPath, content, snapshot),
           );
+          // Persisting the append drops the resident cell (the ledger
+          // refetches it on the next live read), so there is no cell to
+          // trim or stamp behind this truncate.
           await __nimbusQueueVfsMutation(absPath, async () => {
             await flush;
             await _fsRpc(
@@ -2267,12 +2459,15 @@ const __fsMod = (() => {
       // Live file is the source of truth — supervisor trims only the
       // boundary chunk; ENOENT propagates when it does not exist.
       const generation = __vfsWriteGenerations[k];
-      await __nimbusQueueVfsMutation(absPath, () =>
-        _fsRpc(supervisor.fsTruncate(absPath, size), "truncate", p, () => undefined)
-      );
-      if (__vfsWriteGenerations[k] === generation && localCell !== undefined) {
-        _truncateLocalCell(absPath, size);
-      }
+      await __nimbusQueueVfsMutation(absPath, () => _ownMutation(
+        absPath,
+        () => _fsRpc(supervisor.fsTruncate(absPath, size), "truncate", p, (result) => result),
+        () => {
+          if (__vfsWriteGenerations[k] === generation && localCell !== undefined) {
+            _truncateLocalCell(absPath, size);
+          }
+        },
+      ));
       _markVfsStale();
       return;
     }
@@ -2292,9 +2487,9 @@ const __fsMod = (() => {
     _recordLocalTimes(absPath, atime, mtime, "lutimes", p);
   }
 
-  async function _utimesAsync(p, atime, mtime, opts) {
+  async function _utimesAsync(p, atime, mtime, opts, syscallOverride) {
     const followSymlinks = !(opts && opts.followSymlinks === false);
-    const syscall = followSymlinks ? "utimes" : "lutimes";
+    const syscall = syscallOverride || (followSymlinks ? "utimes" : "lutimes");
     const absPath = _resolve(p);
     const supervisor = _supervisor();
     let localExists = false;
@@ -2305,11 +2500,16 @@ const __fsMod = (() => {
     const time = _recordLocalTimes(absPath, atime, mtime, syscall, p);
     if (supervisor && typeof supervisor.utimes === "function") {
       await _flushLocalPathToSupervisor(absPath, supervisor);
-      await _fsRpc(
+      // Ordered behind the path's pending mutations: an fd write queued a
+      // moment ago (modern-tar writes, then futimes, then closes) would
+      // otherwise land AFTER the timestamp and reset it to "now".
+      const leased = () => _ownMutation(absPath, () => _fsRpc(
         supervisor.utimes(absPath, time.atimeMs, time.mtimeMs),
         syscall, p,
-        () => undefined,
-      );
+        (result) => result,
+      ));
+      if (_hasVfsMutationQueue()) await __nimbusQueueVfsMutation(absPath, leased);
+      else await leased();
       _markVfsStale();
       return;
     }
@@ -2359,11 +2559,46 @@ const __fsMod = (() => {
     const nextUid = _coerceId(uid, syscall, p);
     const nextGid = _coerceId(gid, syscall, p);
     await _flushLocalPathToSupervisor(absPath, supervisor);
-    await _fsRpc(supervisor.chown(absPath, nextUid, nextGid, opts), syscall, p, () => undefined);
+    await _ownMutation(
+      absPath,
+      () => _fsRpc(supervisor.chown(absPath, nextUid, nextGid, opts), syscall, p, (result) => result),
+      () => {
+        const meta = _metadata(absPath);
+        if (meta) { meta.uid = nextUid; meta.gid = nextGid; }
+      },
+    );
+    _markVfsStale();
+  }
+
+  // Sync ownership change: the stat record is updated locally at once and
+  // the authority RPC is queued behind the path's pending flush, the same
+  // parked model mkdirSync/unlinkSync use. Without an authority there is no
+  // owner table to change, so the answer is the same ENOSYS as the async form.
+  function _chownQueued(p, uid, gid, opts, syscall) {
+    const followSymlinks = !(opts && opts.followSymlinks === false);
+    const absPath = _resolve(p);
+    const supervisor = _supervisor();
+    if (!supervisor || typeof supervisor.chown !== "function") {
+      if (!existsSync(p)) throw _fsErr("ENOENT", syscall, p);
+      throw _fsErr("ENOSYS", syscall, p);
+    }
+    const nextUid = _coerceId(uid, syscall, p);
+    const nextGid = _coerceId(gid, syscall, p);
     const meta = _metadata(absPath);
     if (meta) { meta.uid = nextUid; meta.gid = nextGid; }
-    _markVfsStale();
+    // The parked write must be registered on the tail BEFORE the chown is
+    // (a flush awaited from inside the queued step would queue behind it
+    // and wait on itself), so it is the synchronous-registering flush.
+    return _queueStructuralMutation(
+      absPath, syscall, p,
+      (s) => s.chown(absPath, nextUid, nextGid, followSymlinks ? undefined : { followSymlinks: false }),
+      () => _flushParkedWrite(absPath, supervisor),
+      "chown",
+    );
   }
+  function chownSync(p, uid, gid) { _detachStructuralMutation(_chownQueued(p, uid, gid, undefined, "chown")); }
+  function lchownSync(p, uid, gid) { _detachStructuralMutation(_chownQueued(p, uid, gid, { followSymlinks: false }, "lchown")); }
+  function lchmodSync(p, mode) { chmodSync(p, mode); }
 
   function _modeAllows(meta, want) {
     if (want === 0) return true;
@@ -2756,46 +2991,67 @@ const __fsMod = (() => {
           (!!__vfsDirs && fp in __vfsDirs) ||
           _metadata(fp)?.type === "directory" ||
           (!!__vfsBundle && __residentAnyUnder(fp + "/"));
-        return { name: n, isFile: () => !isDir, isDirectory: () => isDir, isSymbolicLink: () => false };
+        return _direntObject(n, isDir ? "directory" : "file", absPath);
       });
     }
     return arr;
   }
 
   // ── mkdirSync ──
-  function mkdirSync(p, opts) {
+  // The sync effect, then the authority mutation queued behind it (see
+  // _queueStructuralMutation). One RPC whatever the depth: the async form
+  // sends the path alone and the authority's mkdir creates the ancestors.
+  function _mkdirQueued(p, opts) {
     const absPath = _resolve(p);
     const k = _strip(absPath);
+    const created = [];
     if (opts?.recursive) {
       const parts = k.split("/").filter(Boolean);
       let cur = "";
-      for (const part of parts) { cur = cur ? cur + "/" + part : part; __vfsDirs[cur] = true; }
+      for (const part of parts) { cur = cur ? cur + "/" + part : part; __vfsDirs[cur] = true; created.push(cur); }
     } else {
       __vfsDirs[k] = true;
+      created.push(k);
     }
+    const queued = _queueStructuralMutation(absPath, "mkdir", p, (supervisor) => supervisor.mkdir(absPath));
+    // Told, not merely known locally: _announceLocalDirs must not issue a
+    // second mkdir for a directory whose own RPC is already in the queue.
+    if (queued) for (const dir of created) _announcedDirs.add(dir);
+    return queued;
   }
+  function mkdirSync(p, opts) { _detachStructuralMutation(_mkdirQueued(p, opts)); }
 
   // ── unlinkSync ──
-  function unlinkSync(p) {
+  function _unlinkQueued(p) {
     const absPath = _resolve(p);
     const k = _strip(absPath);
     if (__vfsBundle) delete __vfsBundle[k];
     if (__vfsWrites) delete __vfsWrites[k];
     _forgetSyncPath(k);
+    return _queueStructuralMutation(absPath, "unlink", p, (supervisor) => supervisor.unlink(absPath));
   }
+  function unlinkSync(p) { _detachStructuralMutation(_unlinkQueued(p)); }
 
   // ── rmdirSync ──
-  function rmdirSync(p) {
+  function _rmdirQueued(p) {
     const absPath = _resolve(p);
     const k = _strip(absPath);
     if (__vfsDirs) delete __vfsDirs[k];
     _forgetSyncPath(k);
+    return _queueStructuralMutation(
+      absPath, "rmdir", p,
+      (supervisor) => supervisor.rmdir(absPath),
+      () => __nimbusAwaitSubtreeMutations(absPath),
+    );
   }
+  function rmdirSync(p) { _detachStructuralMutation(_rmdirQueued(p)); }
 
   // ── renameSync ──
-  function renameSync(oldP, newP) {
-    const oldK = _strip(_resolve(oldP));
-    const newK = _strip(_resolve(newP));
+  function _renameQueued(oldP, newP) {
+    const oldAbs = _resolve(oldP);
+    const newAbs = _resolve(newP);
+    const oldK = _strip(oldAbs);
+    const newK = _strip(newAbs);
     const content = __vfsBundle?.[oldK] ?? __vfsWrites?.[oldK];
     if (content !== undefined) {
       _parkWrite(newK, content);
@@ -2809,13 +3065,181 @@ const __fsMod = (() => {
       const moved = metadata ? metadata[oldK] : undefined;
       _forgetSyncPath(oldK);
       if (moved) metadata[newK] = moved;
-    }
+    } else if (__vfsDirs && oldK in __vfsDirs) {
+      // A directory this process made travels under its new name, so the
+      // sync view stops listing the old one and _announceLocalDirs cannot
+      // re-create it at the authority behind the rename.
+      const prefix = oldK + "/";
+      for (const dk of Object.keys(__vfsDirs)) {
+        if (dk !== oldK && !dk.startsWith(prefix)) continue;
+        const moved = newK + dk.slice(oldK.length);
+        __vfsDirs[moved] = true;
+        delete __vfsDirs[dk];
+        if (_announcedDirs.has(dk)) _announcedDirs.add(moved);
+      }
+      _forgetSyncTree(oldK);
+    }
+    const queued = _queueStructuralMutation(
+      oldAbs, "rename", oldP,
+      (supervisor) => supervisor.rename(oldAbs, newAbs),
+      // The queue orders the move behind the source's ancestors; the move
+      // also needs the destination's ancestors to exist and every pending
+      // mutation beneath the source to have landed under the old name.
+      () => Promise.all([__nimbusAwaitAncestorMutations(newAbs), __nimbusAwaitSubtreeMutations(oldAbs)]),
+    );
+    _fenceVfsMutation(newAbs, queued);
+    return queued;
   }
+  function renameSync(oldP, newP) { _detachStructuralMutation(_renameQueued(oldP, newP)); }
 
   // ── copyFileSync ──
-  function copyFileSync(src, dest) {
-    writeFileSync(dest, readFileSync(src, "utf8"));
+  // Bytes, not utf8: a utf8 round trip replaces every byte ≥ 0x80 with
+  // U+FFFD, which is how a copied .png or .woff2 arrived corrupted.
+  function copyFileSync(src, dest, mode) {
+    if ((Number(mode) & __fsConstants.COPYFILE_EXCL) !== 0 && existsSync(dest)) {
+      throw _fsErr("EEXIST", "copyfile", dest);
+    }
+    writeFileSync(dest, readFileSync(src));
+  }
+
+  // ── rmSync / rm ──
+  // The local tables are edited at once (the same retraction unlinkSync and
+  // rmdirSync perform, over the whole subtree when recursive) and ONE
+  // authority RPC — fsRemove, which the bridge serves as unlink or a bounded
+  // recursive removal — is queued behind every pending mutation beneath the
+  // path. ENOENT under \`force\` is the authority's to swallow; locally an
+  // unknown path may still exist live, so it is asked rather than answered.
+  function _rmQueued(p, opts, sync) {
+    const o = opts || {};
+    const absPath = _resolve(p);
+    const k = _strip(absPath);
+    const st = statSync(p, { throwIfNoEntry: false });
+    const supervisor = _supervisor();
+    const canRemove = !!supervisor && typeof supervisor.fsRemove === "function";
+    if (st === undefined) {
+      if (!canRemove) {
+        if (o.force) return null;
+        throw _fsErr("ENOENT", "rm", p);
+      }
+      // A path the sync view cannot map may still exist live (born after
+      // boot). The async form asks the authority, whose ENOENT is the real
+      // one; the sync form has no frame to receive that answer, so it gives
+      // statSync's own provisional not-found unless \`force\` makes the
+      // verdict irrelevant.
+      if (sync && !o.force) throw _fsErr("ENOENT", "rm", p);
+    }
+    if (st !== undefined && st.isDirectory() && !o.recursive) {
+      throw _fsErr("ERR_FS_EISDIR", "rm", p);
+    }
+    const prefix = k + "/";
+    // A parked write is content the authority may never have seen: the
+    // caller's file demonstrably existed here, so the removal succeeds, and
+    // the authority is told "if present" rather than made to fail on a file
+    // that was only ever local.
+    let parked = false;
+    if (__vfsBundle) {
+      if (k in __vfsBundle) delete __vfsBundle[k];
+      if (o.recursive) for (const bk of __residentUnder(prefix)) delete __vfsBundle[bk];
+    }
+    delete __vfsBundleRevisions[k];
+    if (__vfsWrites) {
+      for (const wk of Object.keys(__vfsWrites)) {
+        if (wk === k || (o.recursive && wk.startsWith(prefix))) { delete __vfsWrites[wk]; parked = true; }
+      }
+    }
+    if (__vfsDirs) {
+      for (const dk of Object.keys(__vfsDirs)) {
+        if (dk === k || (o.recursive && dk.startsWith(prefix))) delete __vfsDirs[dk];
+      }
+    }
+    if (o.recursive) _forgetSyncTree(k); else _forgetSyncPath(k);
+    if (!canRemove) {
+      // No fsRemove: a plain file still has the unlink RPC.
+      if (st !== undefined && !st.isDirectory()) {
+        return _queueStructuralMutation(absPath, "rm", p, (s) => s.unlink(absPath), undefined, "unlink");
+      }
+      return null;
+    }
+    return _queueStructuralMutation(
+      absPath, "rm", p,
+      (s) => s.fsRemove(absPath, { recursive: !!o.recursive, force: !!o.force || parked }),
+      () => __nimbusAwaitSubtreeMutations(absPath),
+      "fsRemove",
+    );
+  }
+  function rmSync(p, opts) { _detachStructuralMutation(_rmQueued(p, opts, true)); }
+  async function _rmAsync(p, opts) { await _rmQueued(p, opts, false); }
+
+  // ── cpSync ──
+  // A walk of the resident view; every file copy is a parked sync write that
+  // the existing write-back drains, and every directory a queued mkdir.
+  function cpSync(src, dest, opts) {
+    const o = opts || {};
+    const st = statSync(src, { throwIfNoEntry: false });
+    if (st === undefined) throw _fsErr("ENOENT", "cp", src);
+    if (typeof o.filter === "function" && !o.filter(String(src), String(dest))) return;
+    if (!st.isDirectory()) {
+      const destSt = statSync(dest, { throwIfNoEntry: false });
+      if (destSt !== undefined) {
+        if (destSt.isDirectory()) throw _fsErr("EISDIR", "cp", dest);
+        if (o.errorOnExist) throw _fsErr("ERR_FS_CP_EEXIST", "cp", dest);
+        if (o.force === false) return;
+      }
+      copyFileSync(src, dest);
+      return;
+    }
+    if (!o.recursive) throw _fsErr("ERR_FS_EISDIR", "cp", src);
+    mkdirSync(dest, { recursive: true });
+    for (const ent of readdirSync(src, { withFileTypes: true })) {
+      cpSync(__pathMod.join(String(src), ent.name), __pathMod.join(String(dest), ent.name), o);
+    }
+  }
+
+  // ── mkdtemp ──
+  // Node appends six characters from [a-zA-Z0-9]; a collision with a name
+  // the sync view already knows is retried rather than reused.
+  const _MKDTEMP_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  function _mkdtempName(prefix) {
+    for (let attempt = 0; attempt < 64; attempt++) {
+      let suffix = "";
+      for (let i = 0; i < 6; i++) suffix += _MKDTEMP_ALPHABET[Math.floor(Math.random() * _MKDTEMP_ALPHABET.length)];
+      const name = String(prefix) + suffix;
+      if (!existsSync(name)) return name;
+    }
+    throw _fsErr("EEXIST", "mkdtemp", String(prefix) + "XXXXXX");
   }
+  function mkdtempSync(prefix) {
+    const name = _mkdtempName(prefix);
+    mkdirSync(name);
+    return name;
+  }
+  async function _mkdtempAsync(prefix) {
+    const name = _mkdtempName(prefix);
+    await _mkdirAsync(name);
+    return name;
+  }
+
+  // ── truncateSync ──
+  // The resident-view rule of ftruncateSync applied to a path: trim the
+  // resident cell and park it, refuse EAGAIN when the bytes are not here.
+  function truncateSync(p, len) {
+    const absPath = _resolve(p);
+    const st = statSync(p, { throwIfNoEntry: false });
+    if (st === undefined) throw _fsErr("ENOENT", "truncate", p);
+    if (st.isDirectory()) throw _fsErr("EISDIR", "truncate", p);
+    const size = Math.max(0, Math.trunc(Number(len) || 0));
+    _ensureWritable(absPath, "truncate", p);
+    const base = _residentWriteBase(absPath, p, "truncate");
+    const next = new Uint8Array(size);
+    next.set(base.subarray(0, Math.min(size, base.byteLength)), 0);
+    _parkWrite(_strip(absPath), next);
+    _markVfsStale();
+  }
+
+  // ── link / linkSync ──
+  // The VFS has no hard links and a copy would lie about sharing an inode,
+  // so both forms answer ENOSYS like fs.promises.link always has.
+  function linkSync(existingPath, newPath) { throw _fsErr("ENOSYS", "link", newPath); }
 
   // ── realpathSync (X.5-T per X5Z5-plan §4.3 + X526b-retro §3.1) ──
   // Sync realpath stays local and identity-resolves. Async symlink
@@ -2863,7 +3287,7 @@ const __fsMod = (() => {
   // ── open-flag parsing for fs.promises.open ──
   function _parseOpenFlags(flags) {
     if (typeof flags === "number") {
-      const O_WRONLY = 1, O_RDWR = 2, O_CREAT = 64, O_EXCL = 128, O_TRUNC = 512, O_APPEND = 1024;
+      const { O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_DIRECTORY } = __fsConstants;
       return {
         read: (flags & O_WRONLY) === 0,
         write: (flags & (O_WRONLY | O_RDWR)) !== 0,
@@ -2871,15 +3295,16 @@ const __fsMod = (() => {
         create: (flags & O_CREAT) !== 0,
         truncate: (flags & O_TRUNC) !== 0,
         exclusive: (flags & O_EXCL) !== 0,
+        directory: (flags & O_DIRECTORY) !== 0,
       };
     }
     const s = String(flags === undefined || flags === null ? "r" : flags);
     const plus = s.indexOf("+") !== -1;
     const exclusive = s.indexOf("x") !== -1;
     const base = s.charAt(0);
-    if (base === "w") return { read: plus, write: true, append: false, create: true, truncate: true, exclusive };
-    if (base === "a") return { read: plus, write: true, append: true, create: true, truncate: false, exclusive };
-    return { read: true, write: plus, append: false, create: false, truncate: false, exclusive };
+    if (base === "w") return { read: plus, write: true, append: false, create: true, truncate: true, exclusive, directory: false };
+    if (base === "a") return { read: plus, write: true, append: true, create: true, truncate: false, exclusive, directory: false };
+    return { read: true, write: plus, append: false, create: false, truncate: false, exclusive, directory: false };
   }
 
   // ── FileHandle — returned from fs.promises.open ──
@@ -2889,6 +3314,38 @@ const __fsMod = (() => {
   // hibernation and partial reads/writes never move whole files. Unflushed
   // sync writes (__vfsWrites) take read precedence; the local sync view is
   // overlaid on writes so readFileSync stays coherent.
+  // The prior content a sync positional write or truncate lays its bytes
+  // over. Shared by the descriptor forms and truncateSync.
+  function _residentWriteBase(absPath, p, syscall) {
+    const cell = _writtenCell(absPath);
+    if (cell !== undefined) {
+      const denial = _denialCode(cell);
+      if (denial) throw _fsErr(denial, syscall, p);
+      _residencySatisfied(absPath);
+      return _asBytes(cell);
+    }
+    const asyncForm = "the async fs." + syscall + "/fs.promises form";
+    const st = statSync(p, { throwIfNoEntry: false });
+    // Non-resident and non-empty: writing onto a zero-filled base would
+    // silently destroy the bytes we cannot see. Refuse instead.
+    if (st !== undefined && st.size !== 0) throw _notResidentError(absPath, p, syscall, asyncForm);
+    // Absent or empty — an empty base IS the true prior content, but only
+    // where absence is knowledge. A path the view never mapped may hold bytes
+    // this process cannot see, and an O_APPEND descriptor onto a zero-filled
+    // base would overwrite the file with the fragment it meant to add.
+    if (st === undefined && !_absenceIsKnown(absPath)) throw _refuseUnmapped(absPath, p, syscall, asyncForm);
+    return new Uint8Array(0);
+  }
+
+  async function _fsyncAsync(absPath, p) {
+    const supervisor = _supervisor();
+    if (supervisor) {
+      await _flushLocalPathToSupervisor(absPath, supervisor);
+      await _awaitStructuralOrder(absPath);
+    }
+    _markVfsStale();
+  }
+
   let __nextFileHandleFd = 3;
   const __fileHandles = new Map();
   class __FileHandle {
@@ -2963,16 +3420,21 @@ const __fsMod = (() => {
             );
             if (meta && meta.type === "file") writeAt = Number(meta.size) || 0;
           }
-          await _fsRpc(
-            supervisor.fsWriteRange(this._abs, writeAt, bytes),
-            "write", this._path,
-            () => undefined,
+          await _ownMutation(
+            this._abs,
+            () => _fsRpc(
+              supervisor.fsWriteRange(this._abs, writeAt, bytes),
+              "write", this._path,
+              (result) => result,
+            ),
+            () => {
+              const key = _strip(this._abs);
+              if (!Object.prototype.hasOwnProperty.call(__vfsWrites, key) &&
+                  __vfsWriteGenerations[key] === overlayGeneration) {
+                _overlayLocalCell(this._abs, writeAt, bytes);
+              }
+            },
           );
-          const key = _strip(this._abs);
-          if (!Object.prototype.hasOwnProperty.call(__vfsWrites, key) &&
-              __vfsWriteGenerations[key] === overlayGeneration) {
-            _overlayLocalCell(this._abs, writeAt, bytes);
-          }
         });
         _markVfsStale();
       } else {
@@ -3028,24 +3490,7 @@ const __fsMod = (() => {
       if (bytes === undefined) throw this._notResident(syscall);
       return bytes;
     }
-    _writeBase(syscall) {
-      const bytes = this._residentBytes(syscall);
-      if (bytes !== undefined) return bytes;
-      const st = statSync(this._path, { throwIfNoEntry: false });
-      // Non-resident and non-empty: writing onto a zero-filled base would
-      // silently destroy the bytes we cannot see. Refuse instead.
-      if (st !== undefined && st.size !== 0) throw this._notResident(syscall);
-      // Absent or empty — an empty base IS the true prior content, but only
-      // where absence is knowledge. A path the view never mapped may hold bytes
-      // this process cannot see, and an O_APPEND descriptor onto a zero-filled
-      // base would overwrite the file with the fragment it meant to add.
-      if (st === undefined && !_absenceIsKnown(this._abs)) {
-        throw _refuseUnmapped(
-          this._abs, this._path, syscall, "the async fs." + syscall + "/fs.promises form",
-        );
-      }
-      return new Uint8Array(0);
-    }
+    _writeBase(syscall) { return _residentWriteBase(this._abs, this._path, syscall); }
     _commit(next) {
       _parkWrite(_strip(this._abs), next);
       _markVfsStale();
@@ -3095,9 +3540,38 @@ const __fsMod = (() => {
     }
     async chmod(mode) { this._assertOpen("fchmod"); await _chmodAsync(this._path, mode); }
     async chown(uid, gid) { this._assertOpen("fchown"); await _chownAsync(this._path, uid, gid, undefined, "fchown"); }
-    async utimes(atime, mtime) { this._assertOpen("futimes"); await _utimesAsync(this._path, atime, mtime); }
-    async sync() {}
-    async datasync() {}
+    async utimes(atime, mtime) { this._assertOpen("futimes"); await _utimesAsync(this._path, atime, mtime, undefined, "futimes"); }
+    // Durability here means: every byte parked for this path has reached
+    // the authority and every mutation queued for it has landed. The bridge
+    // itself is synchronously durable, so no further RPC is owed.
+    async sync() { this._assertOpen("fsync"); await _fsyncAsync(this._abs, this._path); }
+    async datasync() { this._assertOpen("fdatasync"); await _fsyncAsync(this._abs, this._path); }
+    // Scatter/gather over the ranged read/write: one sequential pass per
+    // buffer, stopping at the first short read, positions advanced by hand
+    // when an explicit one was given so the file position stays untouched.
+    async readv(buffers, position) {
+      this._assertOpen("read");
+      let bytesRead = 0;
+      let pos = _isCurrentPos(position) ? null : Number(position);
+      for (const buffer of buffers) {
+        const r = await this.read(buffer, 0, buffer.byteLength, pos);
+        bytesRead += r.bytesRead;
+        if (pos !== null) pos += r.bytesRead;
+        if (r.bytesRead < buffer.byteLength) break;
+      }
+      return { bytesRead, buffers };
+    }
+    async writev(buffers, position) {
+      this._assertOpen("write");
+      let bytesWritten = 0;
+      let pos = _isCurrentPos(position) ? null : Number(position);
+      for (const buffer of buffers) {
+        const r = await this.write(buffer, 0, buffer.byteLength, pos);
+        bytesWritten += r.bytesWritten;
+        if (pos !== null) pos += r.bytesWritten;
+      }
+      return { bytesWritten, buffers };
+    }
     async close() { this._assertOpen("close"); this._closed = true; __fileHandles.delete(this.fd); }
     [Symbol.asyncDispose]() { return this.close(); }
   }
@@ -3118,6 +3592,7 @@ const __fsMod = (() => {
       if (localStat && localStat.isDirectory()) throw _fsErr("EISDIR", "open", path);
     }
     const exists = !!liveMeta || !!localStat;
+    if (exists && fl.directory) throw _fsErr("ENOTDIR", "open", path);
     if (!exists && !fl.create) throw _fsErr("ENOENT", "open", path);
     if (exists && fl.create && fl.exclusive) throw _fsErr("EEXIST", "open", path);
     let size = liveMeta ? (Number(liveMeta.size) || 0) : (localStat ? localStat.size : 0);
@@ -3141,6 +3616,7 @@ const __fsMod = (() => {
     const st = statSync(path, { throwIfNoEntry: false });
     if (st && st.isDirectory()) throw _fsErr("EISDIR", "open", path);
     const exists = st !== undefined;
+    if (exists && fl.directory) throw _fsErr("ENOTDIR", "open", path);
     if (!exists && !fl.create) throw _fsErr("ENOENT", "open", path);
     if (exists && fl.create && fl.exclusive) throw _fsErr("EEXIST", "open", path);
     if (fl.write || !exists) _ensureWritable(absPath, "open", path);
@@ -3261,6 +3737,49 @@ const __fsMod = (() => {
   function fsyncSync(fd) { if (!_isStdioFd(fd)) _fdHandle(fd, "fsync"); _markVfsStale(); }
   function fdatasyncSync(fd) { if (!_isStdioFd(fd)) _fdHandle(fd, "fdatasync"); _markVfsStale(); }
 
+  // Descriptor metadata, sync: the path forms on the handle's path, so the
+  // local overlay (times, modes, ownership) and the parked write-through are
+  // exactly what utimesSync/chmodSync/chownSync give.
+  function futimesSync(fd, atime, mtime) {
+    if (_isStdioFd(fd)) throw _fsErr("EINVAL", "futimes", fd);
+    const handle = _fdHandle(fd, "futimes");
+    _recordLocalTimes(handle._abs, atime, mtime, "futimes", handle._path);
+  }
+  function fchmodSync(fd, mode) {
+    if (_isStdioFd(fd)) throw _fsErr("EINVAL", "fchmod", fd);
+    const handle = _fdHandle(fd, "fchmod");
+    _localModes[_strip(handle._abs)] = _coerceMode(mode, "fchmod", handle._path);
+  }
+  function fchownSync(fd, uid, gid) {
+    if (_isStdioFd(fd)) throw _fsErr("EINVAL", "fchown", fd);
+    const handle = _fdHandle(fd, "fchown");
+    _detachStructuralMutation(_chownQueued(handle._path, uid, gid, undefined, "fchown"));
+  }
+
+  // Scatter/gather, sync: readSync/writeSync per buffer; stdio fds keep the
+  // stream behaviour those two already give them.
+  function readvSync(fd, buffers, position) {
+    let bytesRead = 0;
+    let pos = _isCurrentPos(position) ? null : Number(position);
+    for (const buffer of buffers) {
+      const n = readSync(fd, buffer, 0, buffer.byteLength, pos);
+      bytesRead += n;
+      if (pos !== null) pos += n;
+      if (n < buffer.byteLength) break;
+    }
+    return bytesRead;
+  }
+  function writevSync(fd, buffers, position) {
+    let bytesWritten = 0;
+    let pos = _isCurrentPos(position) ? null : Number(position);
+    for (const buffer of buffers) {
+      const n = writeSync(fd, buffer, 0, buffer.byteLength, pos);
+      bytesWritten += n;
+      if (pos !== null) pos += n;
+    }
+    return bytesWritten;
+  }
+
   // ── callback forms (live I/O — these CAN reach the supervisor) ──
   function open(path, flags, mode, cb) {
     if (typeof flags === "function") { cb = flags; flags = undefined; mode = undefined; }
@@ -3341,21 +3860,56 @@ const __fsMod = (() => {
     if (!handle) return;
     handle.truncate(len).then(() => cb(null)).catch((e) => cb(e));
   }
-  function fsync(fd, cb) {
+  // The async forms CAN wait for durability: the parked bytes are flushed
+  // and the path's queued mutations awaited before the callback fires.
+  function _fsyncCb(fd, syscall, cb) {
+    let handle = null;
     let err = null;
-    try { fsyncSync(fd); } catch (e) { err = e; }
+    try { if (!_isStdioFd(fd)) handle = _fdHandle(fd, syscall); } catch (e) { err = e; }
     // Without a callback there is nowhere to deliver the failure, so raise
     // it here rather than let an EBADF vanish.
-    if (typeof cb !== "function") { if (err) throw err; return; }
-    queueMicrotask(() => cb(err));
-  }
-  function fdatasync(fd, cb) {
-    let err = null;
-    try { fdatasyncSync(fd); } catch (e) { err = e; }
-    // Without a callback there is nowhere to deliver the failure, so raise
-    // it here rather than let an EBADF vanish.
-    if (typeof cb !== "function") { if (err) throw err; return; }
-    queueMicrotask(() => cb(err));
+    if (typeof cb !== "function") { if (err) throw err; _markVfsStale(); return; }
+    if (err || !handle) { _markVfsStale(); queueMicrotask(() => cb(err)); return; }
+    _fsyncAsync(handle._abs, handle._path).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function fsync(fd, cb) { _fsyncCb(fd, "fsync", cb); }
+  function fdatasync(fd, cb) { _fsyncCb(fd, "fdatasync", cb); }
+  function futimes(fd, atime, mtime, cb) {
+    if (_isStdioFd(fd)) { queueMicrotask(() => cb(_fsErr("EINVAL", "futimes", fd))); return; }
+    const handle = _fdFor(fd, "futimes", cb);
+    if (!handle) return;
+    handle.utimes(atime, mtime).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function readv(fd, buffers, position, cb) {
+    if (typeof position === "function") { cb = position; position = null; }
+    const run = async () => {
+      let bytesRead = 0;
+      let pos = _isCurrentPos(position) ? null : Number(position);
+      for (const buffer of buffers) {
+        const n = await new Promise((res, rej) =>
+          read(fd, buffer, 0, buffer.byteLength, pos, (e, count) => (e ? rej(e) : res(count))));
+        bytesRead += n;
+        if (pos !== null) pos += n;
+        if (n < buffer.byteLength) break;
+      }
+      return bytesRead;
+    };
+    run().then((n) => cb(null, n, buffers)).catch((e) => cb(e));
+  }
+  function writev(fd, buffers, position, cb) {
+    if (typeof position === "function") { cb = position; position = null; }
+    const run = async () => {
+      let bytesWritten = 0;
+      let pos = _isCurrentPos(position) ? null : Number(position);
+      for (const buffer of buffers) {
+        const n = await new Promise((res, rej) =>
+          write(fd, buffer, 0, buffer.byteLength, pos, (e, count) => (e ? rej(e) : res(count))));
+        bytesWritten += n;
+        if (pos !== null) pos += n;
+      }
+      return bytesWritten;
+    };
+    run().then((n) => cb(null, n, buffers)).catch((e) => cb(e));
   }
   function fchmod(fd, mode, cb) {
     const handle = _fdFor(fd, "fchmod", cb);
@@ -3368,6 +3922,135 @@ const __fsMod = (() => {
     handle.chown(uid, gid).then(() => cb(null)).catch((error) => cb(error));
   }
 
+  // ── Dir — fs.opendir / opendirSync / fs.promises.opendir ──
+  // The listing is taken whole at open (both readdir forms already return
+  // one) and handed out one Dirent per read(); closing a closed Dir is
+  // ERR_DIR_CLOSED as in Node.
+  class __Dir {
+    constructor(path, entries) {
+      this.path = path;
+      this._entries = entries;
+      this._at = 0;
+      this._closed = false;
+    }
+    _assertOpen() {
+      if (this._closed) {
+        const err = new Error("Directory handle was closed");
+        err.code = "ERR_DIR_CLOSED";
+        throw err;
+      }
+    }
+    readSync() {
+      this._assertOpen();
+      return this._at < this._entries.length ? this._entries[this._at++] : null;
+    }
+    read(cb) {
+      const result = new Promise((res, rej) => { try { res(this.readSync()); } catch (e) { rej(e); } });
+      if (typeof cb !== "function") return result;
+      result.then((entry) => cb(null, entry), (e) => cb(e));
+    }
+    closeSync() { this._assertOpen(); this._closed = true; }
+    close(cb) {
+      const result = new Promise((res, rej) => { try { this.closeSync(); res(); } catch (e) { rej(e); } });
+      if (typeof cb !== "function") return result;
+      result.then(() => cb(null), (e) => cb(e));
+    }
+    async *[Symbol.asyncIterator]() {
+      try {
+        for (;;) {
+          const entry = this.readSync();
+          if (entry === null) break;
+          yield entry;
+        }
+      } finally {
+        if (!this._closed) this._closed = true;
+      }
+    }
+    [Symbol.asyncDispose]() { return this._closed ? Promise.resolve() : this.close(); }
+    [Symbol.dispose]() { if (!this._closed) this.closeSync(); }
+  }
+  function opendirSync(p, opts) {
+    return new __Dir(String(p), readdirSync(p, { withFileTypes: true }));
+  }
+  async function _opendirAsync(p, opts) {
+    return new __Dir(String(p), await _readdirAsync(p, { withFileTypes: true }));
+  }
+  function opendir(p, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    _opendirAsync(p, opts).then((dir) => cb(null, dir)).catch((e) => cb(e));
+  }
+
+  // ── statfs ──
+  // Honest constants for the VFS: the block size is the SQLite chunk unit's
+  // page size, and blocks is the configured VFS capacity in those blocks.
+  // The supervisor surface exposes no usage counter, so bfree/bavail report
+  // the whole capacity; the VFS has no inode table, so files/ffree are 0
+  // (unknown, not "none"). \`type\` is 0: this is no kernel filesystem and
+  // no magic number would be true of it.
+  const _STATFS_BSIZE = 4096;
+  const _STATFS_BLOCKS = Math.floor(${VFS_CAPACITY} / 4096);
+  function _statfsObject(opts) {
+    const wrap = opts && opts.bigint ? BigInt : Number;
+    return {
+      type: wrap(0),
+      bsize: wrap(_STATFS_BSIZE),
+      blocks: wrap(_STATFS_BLOCKS),
+      bfree: wrap(_STATFS_BLOCKS),
+      bavail: wrap(_STATFS_BLOCKS),
+      files: wrap(0),
+      ffree: wrap(0),
+    };
+  }
+  function statfsSync(p, opts) {
+    if (statSync(p, { throwIfNoEntry: false }) === undefined) throw _fsErr("ENOENT", "statfs", p);
+    return _statfsObject(opts);
+  }
+  async function _statfsAsync(p, opts) {
+    await _statAsync(p);
+    return _statfsObject(opts);
+  }
+  function statfs(p, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    _statfsAsync(p, opts).then((s) => cb(null, s)).catch((e) => cb(e));
+  }
+
+  // ── remaining callback forms of the path operations ──
+  function rm(p, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    _rmAsync(p, opts).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function cp(src, dest, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    promises.cp(src, dest, opts).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function truncate(p, len, cb) {
+    if (typeof len === "function") { cb = len; len = 0; }
+    _truncateAsync(p, len || 0).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function copyFile(src, dest, mode, cb) {
+    if (typeof mode === "function") { cb = mode; mode = 0; }
+    promises.copyFile(src, dest, mode).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function mkdtemp(prefix, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    _mkdtempAsync(prefix).then((name) => cb(null, name)).catch((e) => cb(e));
+  }
+  function link(existingPath, newPath, cb) { queueMicrotask(() => cb(_fsErr("ENOSYS", "link", newPath))); }
+  function symlink(target, path, type, cb) {
+    if (typeof type === "function") { cb = type; type = undefined; }
+    _symlinkAsync(target, path).then(() => cb(null)).catch((e) => cb(e));
+  }
+  function readlink(p, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    _readlinkAsync(p).then((target) => cb(null, target)).catch((e) => cb(e));
+  }
+  function realpath(p, opts, cb) {
+    if (typeof opts === "function") { cb = opts; opts = undefined; }
+    promises.realpath(p, opts).then((r) => cb(null, r)).catch((e) => cb(e));
+  }
+  realpath.native = realpath;
+  function lchmod(p, mode, cb) { chmod(p, mode, cb); }
+
   // ── promises namespace (W3: full surface, VFS-backed) ──
   // We can't forward to workerd's node:fs/promises because that operates
   // on a real-host filesystem, not our VFS. So every method is shim'd
@@ -3385,22 +4068,8 @@ const __fsMod = (() => {
     // W3 additions:
     appendFile: async (p, d, o) => { await _appendFileAsync(p, d, o); },
     lstat: (p) => new Promise((res, rej) => lstat(p, (e, s) => e ? rej(e) : res(s))),
-    rm: async (p, opts) => {
-      const o = opts || {};
-      const k = _strip(_resolve(p));
-      const prefix = k + "/";
-      if (o.recursive) {
-        if (__vfsBundle) {
-          if (k in __vfsBundle) delete __vfsBundle[k];
-          for (const bk of __residentUnder(prefix)) delete __vfsBundle[bk];
-        }
-        if (__vfsWrites) for (const wk of Object.keys(__vfsWrites)) if (wk === k || wk.startsWith(prefix)) delete __vfsWrites[wk];
-        if (__vfsDirs) for (const dk of Object.keys(__vfsDirs)) if (dk === k || dk.startsWith(prefix)) delete __vfsDirs[dk];
-        _forgetSyncTree(k);
-      } else {
-        try { await _unlinkAsync(p); } catch (e) { if (!o.force) throw e; }
-      }
-    },
+    // The same local retraction and queued authority removal rmSync does.
+    rm: async (p, opts) => { await _rmAsync(p, opts); },
     cp: async (src, dest, opts) => {
       const o = opts || {};
       const srcAbs = _resolve(src);
@@ -3436,7 +4105,12 @@ const __fsMod = (() => {
       };
       await walk("");
     },
-    copyFile: async (src, dest) => { await _writeFileAsync(dest, await _readFileAsync(src)); },
+    copyFile: async (src, dest, mode) => {
+      if ((Number(mode) & __fsConstants.COPYFILE_EXCL) !== 0 && await _existsAsync(dest)) {
+        throw _fsErr("EEXIST", "copyfile", dest);
+      }
+      await _writeFileAsync(dest, await _readFileAsync(src));
+    },
     rename: async (oldP, newP) => { await _renameAsync(oldP, newP); },
     rmdir: async (p) => { await _rmdirAsync(p); },
     realpath: async (p) => __pathMod.resolve(String(p)),
@@ -3450,12 +4124,10 @@ const __fsMod = (() => {
     symlink: async (target, path) => { await _symlinkAsync(target, path); },
     link: async () => { throw _fsErr("ENOSYS", "link", ""); },
     readlink: async (p) => _readlinkAsync(p),
-    mkdtemp: async (prefix) => {
-      const name = String(prefix) + Math.random().toString(36).slice(2, 10);
-      mkdirSync(name, { recursive: true });
-      return name;
-    },
+    mkdtemp: async (prefix) => _mkdtempAsync(prefix),
     open: async (path, flags, mode) => _openAsync(path, flags, mode),
+    opendir: async (p, opts) => _opendirAsync(p, opts),
+    statfs: async (p, opts) => _statfsAsync(p, opts),
     watch: async function* (filename, opts) {
       // Minimal async iter — polls _bundleLookup every 500ms and yields
       // a single \`change\` event when content differs. Adequate for
@@ -3500,8 +4172,9 @@ const __fsMod = (() => {
     },
   };
 
-  // ── constants ──
-  const constants = { F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1 };
+  // ── constants ── the shared linux x64 table (see __fsConstants).
+  const constants = __fsConstants;
+  promises.constants = constants;
 
   // fs.ReadStream / fs.WriteStream classes. Real Node exposes these as
   // constructors; graceful-fs (bundled by degit → create-cloudflare)
@@ -3591,10 +4264,15 @@ const __fsMod = (() => {
   const __fsExports = {
     readFileSync, writeFileSync, appendFileSync, existsSync, statSync, lstatSync,
     readdirSync, mkdirSync, unlinkSync, rmdirSync, renameSync, copyFileSync,
-    realpathSync, utimesSync, lutimesSync, chmodSync, accessSync,
+    realpathSync, utimesSync, lutimesSync, chmodSync, lchmodSync, chownSync, lchownSync, accessSync,
+    rmSync, cpSync, mkdtempSync, truncateSync, linkSync, opendirSync, statfsSync,
     openSync, closeSync, readSync, writeSync, fstatSync, ftruncateSync, fsyncSync, fdatasyncSync,
-    open, close, read, write, fstat, ftruncate, fsync, fdatasync, fchmod,
-    readFile, writeFile, appendFile, stat, lstat, readdir, exists, mkdir, unlink, rename, utimes, lutimes, chmod, chown, lchown, fchown, access,
+    futimesSync, fchmodSync, fchownSync, readvSync, writevSync,
+    open, close, read, write, fstat, ftruncate, fsync, fdatasync, fchmod, futimes, readv, writev,
+    readFile, writeFile, appendFile, stat, lstat, readdir, exists, mkdir, unlink, rename, utimes, lutimes, chmod, lchmod, chown, lchown, fchown, access,
+    rm, cp, truncate, copyFile, mkdtemp, link, symlink, readlink, realpath, opendir, statfs,
+    Dirent: __Dirent,
+    Dir: __Dir,
     promises, constants,
     createReadStream: (p, opts) => new (__getReadStream())(p, opts),
     createWriteStream: (p, opts) => {
@@ -3936,13 +4614,10 @@ globalThis.WebSocket = __NimbusRelayedWebSocket;
 //
 // require('node:constants') (and the legacy bare require('constants'))
 // expose a FLAT object of POSIX/Linux/OpenSSL constants. Real Node ships
-// ~234 constants; we ship the ones that actually get touched by:
+// ~234 constants; the full fs slice comes from __fsConstants, and the rest
+// is what actually gets touched by:
 //   - create-next-app (touches UV_FS_O_FILEMAP — verified via grep on
 //     unpkg.com/create-next-app@latest/dist/index.js)
-//   - typical fs.openSync flag composition (O_RDONLY, O_WRONLY, O_RDWR,
-//     O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_DIRECTORY, etc.)
-//   - typical fs.access mode composition (F_OK, R_OK, W_OK, X_OK)
-//   - typical fs.copyFile mode composition (COPYFILE_EXCL etc.)
 //   - signal/errno tables (shared shape with __osMod.constants.signals
 //     etc. — flat here, nested there; both shapes are real-Node-accurate
 //     and we expose both via the right module).
@@ -3987,26 +4662,10 @@ const __constantsMod = {
   SIGTSTP: 20, SIGTTIN: 21, SIGTTOU: 22, SIGURG: 23, SIGXCPU: 24,
   SIGXFSZ: 25, SIGVTALRM: 26, SIGPROF: 27, SIGWINCH: 28, SIGIO: 29,
   SIGPOLL: 29, SIGPWR: 30, SIGSYS: 31,
-  // ── File-type bits (stat.mode masks) ──────────────────────────────
-  S_IFMT: 61440, S_IFREG: 32768, S_IFDIR: 16384, S_IFCHR: 8192,
-  S_IFBLK: 24576, S_IFIFO: 4096, S_IFLNK: 40960, S_IFSOCK: 49152,
-  // ── File-open flags (fs.openSync / fs.constants.O_*) ──────────────
-  O_RDONLY: 0, O_WRONLY: 1, O_RDWR: 2,
-  O_CREAT: 64, O_EXCL: 128, O_NOCTTY: 256, O_TRUNC: 512, O_APPEND: 1024,
-  O_DIRECTORY: 65536, O_NOATIME: 262144, O_NOFOLLOW: 131072,
-  O_SYNC: 1052672, O_DSYNC: 4096, O_DIRECT: 16384, O_NONBLOCK: 2048,
-  // libuv-specific fs flag — create-next-app touches this directly.
-  UV_FS_O_FILEMAP: 0,
-  // ── File-permission bits (chmod / stat.mode user/group/other) ─────
-  S_IRWXU: 448, S_IRUSR: 256, S_IWUSR: 128, S_IXUSR: 64,
-  S_IRWXG: 56, S_IRGRP: 32, S_IWGRP: 16, S_IXGRP: 8,
-  S_IRWXO: 7, S_IROTH: 4, S_IWOTH: 2, S_IXOTH: 1,
-  // ── fs.access mode constants ──────────────────────────────────────
-  F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1,
-  // ── fs.copyFile mode constants (libuv shape + Node alias) ─────────
-  UV_FS_COPYFILE_EXCL: 1, COPYFILE_EXCL: 1,
-  UV_FS_COPYFILE_FICLONE: 2, COPYFILE_FICLONE: 2,
-  UV_FS_COPYFILE_FICLONE_FORCE: 4, COPYFILE_FICLONE_FORCE: 4,
+  // ── fs constants (O_*, S_IF*, S_I*, F_OK.., COPYFILE_*, UV_*) ────
+  // Node's constants module is the union of os, fs and crypto constants;
+  // the fs slice is __fsConstants, the same object fs.constants exposes.
+  ...__fsConstants,
   // ── OpenSSL / TLS option flags ────────────────────────────────────
   // Numeric values from real Node v20. Libraries probe defined-ness;
   // we ship the surface so constants.SSL_OP_* doesn't undefined-throw.
@@ -6424,7 +7083,20 @@ builtins.tty = {
 // core and must not be reported as such — a package that sniffs this list
 // would otherwise conclude e.g. undici ships with node.
 const __nimbusFacetProvidedPackages = new Set(${FACET_PROVIDED_PACKAGES_LITERAL});
-	builtins.module = { get builtinModules() { return Object.keys(builtins).filter((n) => !__nimbusFacetProvidedPackages.has(n)); }, createRequire: (specifier) => __makeRequire(__requireBaseDir(specifier)), _resolveFilename: (id) => id, _cache: {} };
+	builtins.module = {
+	  get builtinModules() { return Object.keys(builtins).filter((n) => !__nimbusFacetProvidedPackages.has(n)); },
+	  createRequire: (specifier) => __makeRequire(__requireBaseDir(specifier)),
+	  isBuiltin: (specifier) => Object.hasOwn(builtins, String(specifier).replace(/^node:/, '')) && !__nimbusFacetProvidedPackages.has(String(specifier).replace(/^node:/, '')),
+	  // Node 22.1's on-disk compile cache. There is no disk to cache into and
+	  // nothing to compile ahead: callers (pi's CLI entry calls it
+	  // unconditionally) get Node's own answer for a cache that is off.
+	  enableCompileCache: () => ({ status: 3, message: 'compile cache is not available in this runtime' }),
+	  getCompileCacheDir: () => undefined,
+	  flushCompileCache: () => {},
+	  constants: { compileCacheStatus: { FAILED: 0, ENABLED: 1, ALREADY_ENABLED: 2, DISABLED: 3 } },
+	  _resolveFilename: (id) => id,
+	  _cache: {},
+	};
 // Bind to globalThis: workerd's timer globals throw "Illegal invocation"
 // when called with a receiver other than globalThis (i.e. as
 // timers.setInterval(...)), which clack's spinner — used by