@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/startup.ts

@@ -39,7 +39,7 @@ let pluginSetup: Promise<void> | null = null
  * Calling both meant every non-clustered worker set its plugins up twice.
  * Handler and mount registration is idempotent so that went unnoticed, but the
  * analytics plugin registers a shutdown hook and kicks off `loadAnalyticsData()`
- * from `setup()` — so it got two of each. Memoising the promise (not a boolean)
+ * from `setup()`, so it got two of each. Memoizing the promise (not a boolean)
  * also makes a concurrent second caller await the first run rather than race it.
  */
 export function setupPlugins(): Promise<void> {
@@ -96,7 +96,7 @@ export async function runStartupBanner(): Promise<void> {
   const host = Bakery.config.host
 
   // Ground truth first. The banner's job is to print where the server is
-  // listening, and `Bakery.server.port` is what the OS actually gave us —
+  // listening, and `Bakery.server.port` is what the OS actually gave us,
   // which is the only correct answer under `PORT=0`, and the only *honest*
   // one if the bound port and the requested one ever part company again.
   // `resolvePort` covers the callers that print a banner without a server
@@ -134,7 +134,7 @@ export async function runStartupBanner(): Promise<void> {
     // constant, and any user-supplied value replaces the reference. The
     // default limiter 429s load tests and shared-NAT offices with nothing
     // anywhere saying it exists, so this line is its one announcement. An
-    // app-configured value prints nothing — their choice, their knowledge.
+    // app-configured value prints nothing: their choice, their knowledge.
     if (Bakery.config.rateLimit === DEFAULT_RATE_LIMIT) {
       serveLog.RATE_LIMIT_DEFAULT(DEFAULT_RATE_LIMIT)
     }

package/src/types.d.ts

@@ -4,7 +4,7 @@
  * These were declared in `declare global`, which is fine inside one repo and a
  * hazard the moment the packages are published: the names are generic enough
  * that a consuming app is likely to define its own `MapOf`, and a global type
- * alias cannot be merged or opted out of — the app just gets a redeclaration
+ * alias cannot be merged or opted out of, the app just gets a redeclaration
  * error with nowhere to put the fix.
  *
  * Moving them cost 24 files an `import type` line and cost consumers nothing:
@@ -12,7 +12,7 @@
  * that they were always internal plumbing rather than DX.
  *
  * `verbatimModuleSyntax` makes the compiler reject a value-position import of
- * these, so nothing can accidentally introduce a runtime module edge — which
+ * these, so nothing can accidentally introduce a runtime module edge, which
  * matters because `client/utils.ts` is compiled into the browser bundle.
  */
 export type MapOf<T> = { [key: string]: T }
@@ -20,7 +20,7 @@ export type MapOf<T> = { [key: string]: T }
 /** A value, or a function producing it. */
 export type Wrapped<T, Args extends any[] = []> = T | ((...args: Args) => T)
 
-/** Awaited or not — the shape almost every framework hook returns. */
+/** Awaited or not: the shape almost every framework hook returns. */
 export type MixedPromise<T> = Promise<T> | T
 
 type ResolveMatchReturn<V, R> = R extends any
@@ -54,12 +54,12 @@ export type Match<D extends symbol> = {
 /**
  * The `body` a route module's default export receives: declared params merge
  * over a permissive base. `body.id` is `string` once you declare it, while
- * `body.anythingElse` stays reachable as `any` — the parse rules in
+ * `body.anythingElse` stays reachable as `any`: the parse rules in
  * `utils/http/body.ts` mean the framework genuinely cannot know every key, so
  * locking the object down would be a lie in the other direction.
  *
  * There is no filename-literal inference (`[id].ts` does not conjure
- * `{ id: string }` on its own — that needs codegen); the contract is that the
+ * `{ id: string }` on its own. That needs codegen); the contract is that the
  * author declares the shape once, at the `defineRoute` / `html` call, instead
  * of annotating the whole signature or settling for `any`.
  */
@@ -71,13 +71,13 @@ export type RouteBody<P = {}> = P & MapOf<any>
  * directory under the `!` form).
  *
  * Exists so a route over mixed or unknown segments can say
- * `defineRoute<MapOf<RouteParam>>` instead of hand-writing the union — and so
+ * `defineRoute<MapOf<RouteParam>>` instead of hand-writing the union, and so
  * the union has one definition to change if it ever grows.
  */
 export type RouteParam = string | string[]
 
 /**
- * What a route module may actually return — read off `processResponse`
+ * What a route module may actually return. Read off `processResponse`
  * (`router.ts`) and `ApiHandler.handle`: a `Response`, a `BunFile` (streamed
  * with an ETag), the JSON envelope, a plain data object or array (JSON-encoded
  * as-is), a string (HTML-sniffed) or number, or nothing (204; a 404 under
@@ -85,10 +85,10 @@ export type RouteParam = string | string[]
  *
  * Deliberately not `object` (which `Handler.Response` uses): `object` absorbs
  * `Response`, `BunFile` and `JsonResponse` into one member and the union stops
- * saying anything — the same trap `routeTable()`'s dispatch avoids. `MapOf<any>`
+ * saying anything, the same trap `routeTable()`'s dispatch avoids. `MapOf<any>`
  * is the narrowest thing that covers "a plain data object"; a target index
  * signature of `any` does still accept class instances, but that only matters
- * for inference targets — this union is a constraint on what an author may
+ * for inference targets: this union is a constraint on what an author may
  * return, and nothing consumes a route module's return type downstream, so the
  * members stay legible instead of collapsing.
  */
@@ -107,7 +107,7 @@ export type RouteResponse = MixedPromise<
 
 /**
  * A typed route module default export. `$dynamic.executeModule` calls it as
- * `(req, body, Bakery.server)` — the third argument is optional here because
+ * `(req, body, Bakery.server)`: the third argument is optional here because
  * `Bakery.server` is itself optional before `Bun.serve` runs, and almost no
  * handler wants it.
  *

package/src/utils/common/case.ts

@@ -1,5 +1,5 @@
 /**
- * `Case` moved to `utils/isomorphic/case` — the client bundle carried an
+ * `Case` moved to `utils/isomorphic/case`: the client bundle carried an
  * identical copy. `toHash` stays here: it calls `Bun.hash`, so it is server-only
  * and must not be pulled into the isomorphic layer.
  */

package/src/utils/common/match.ts

@@ -1,6 +1,6 @@
 /**
  * Moved to `utils/isomorphic/match` so the browser bundle and the server share
- * one implementation — the prototype-chain fix (`Object.hasOwn` rather than
+ * one implementation: the prototype-chain fix (`Object.hasOwn` rather than
  * `in`) previously had to be applied to both copies separately.
  */
 export * from '../isomorphic/match'

package/src/utils/common/misc.ts

@@ -1,5 +1,5 @@
 /**
- * `is`, `Math2` and `throws` moved to `utils/isomorphic/` — the client bundle
+ * `is`, `Math2` and `throws` moved to `utils/isomorphic/`: the client bundle
  * carried its own copies of all three. They are re-exported here so existing
  * `@server/utils` importers are unaffected.
  *

package/src/utils/constants.ts

@@ -12,7 +12,7 @@ export const DEFAULT_RATE_LIMIT = { max: 100, refill: 10 }
  * Files that must never be served off disk.
  *
  * These are matched against the file a *file-serving* handler is about to
- * return, not against every request path — see `servesFiles` in `router.ts`.
+ * return, not against every request path. See `servesFiles` in `router.ts`.
  * An API route or a proxied path is a name, not a file, and never had any
  * business being tested against this list.
  *
@@ -22,8 +22,8 @@ export const DEFAULT_RATE_LIMIT = { max: 100, refill: 10 }
  * on that attempt.
  *
  * Note what is *not* here: an extension-wide ban on JSON. It caught every
- * JSON document an app might legitimately publish — a web app manifest, a
- * `.well-known` document — and since `blocked` in config can only ever append,
+ * JSON document an app might legitimately publish: a web app manifest, a
+ * `.well-known` document, and since `blocked` in config can only ever append,
  * an app had no way to opt back out. What the list is actually protecting is
  * the handful of JSON files that describe the project, so those are named.
  */
@@ -46,9 +46,9 @@ export const DEFAULT_BLOCKED_GLOBS = [
   // trailing `**` collapses to a single segment: `{**/node_modules/**}` matches
   // `/node_modules/a` and then stops, so `/node_modules/pkg/index.js` was not
   // blocked by anything. Each pattern still matched on its own, which is why
-  // it survived — the defect only exists in the form the config actually uses.
+  // it survived: the defect only exists in the form the config actually uses.
   // `.cache` is the framework's disposable working dir and `bakery/` holds the
-  // database and its backups — the visible one is the precious one, so that a
+  // database and its backups: the visible one is the precious one, so that a
   // dotfile sweep cannot reach the data. `bakery/` being un-dotted is why it
   // needs naming here explicitly: `*.db` covers the database file itself, but
   // not the `.ts` schema snapshots under `bakery/backups/`.
@@ -67,17 +67,17 @@ export const DEFAULT_BLOCKED_GLOBS = [
 /**
  * A request path folded to the form the *filesystem* would resolve it to.
  *
- * Two normalisations, both of them things the OS does and the glob does not:
+ * Two normalizations, both of them things the OS does and the glob does not:
  *
  * - **Case.** NTFS and APFS are case-insensitive, so `/PACKAGE.JSON` opens the
- *   same bytes as `/package.json` — but `Bun.Glob` is case-sensitive, so only
+ *   same bytes as `/package.json`, but `Bun.Glob` is case-sensitive, so only
  *   the second one was blocked. Every file this list protects was reachable by
  *   holding down shift, and the static pipeline was verified to serve
  *   `/STYLES/GLOBAL.CSS` and `/styles/global.css` as the same 170 bytes.
  * - **Trailing dots and spaces.** Win32 strips both from each path component,
  *   so `/package.json.` and `/package.json ` are the same file too.
  *
- * `.`, `..` and any all-dots component are left intact — trimming those would
+ * `.`, `..` and any all-dots component are left intact: trimming those would
  * rewrite a relative segment into something else, and containment is
  * `fs.isForbidden`'s job, not this function's.
  */
@@ -93,14 +93,14 @@ export function normalizeBlockedPath(path: string): string {
  * Each path component truncated at its first `:`.
  *
  * Win32 resolves `x.ts::$DATA` to the bytes of `x.ts` and
- * `dir::$INDEX_ALLOCATION` to `dir` — NTFS alternate-data-stream syntax — and
+ * `dir::$INDEX_ALLOCATION` to `dir` (NTFS alternate-data-stream syntax), and
  * `new URL()` keeps the suffix in `pathname`, so a glob anchored on the real
  * name missed while the filesystem opened the file anyway. The directory form
  * matters independently: it defeats the `dir/**` patterns that the file form
  * cannot reach.
  *
  * Only ever used as an *extra* match candidate (see `matchBlocked`), never as
- * a replacement — colons are legal in POSIX filenames, and a real file named
+ * a replacement: colons are legal in POSIX filenames, and a real file named
  * `a:b.db` must stay blocked by `*.db` rather than being tested as `a`.
  */
 function stripStreamSuffix(path: string): string {
@@ -117,18 +117,18 @@ function stripStreamSuffix(path: string): string {
 /**
  * Whether `path` is refused by the blocked globs.
  *
- * Matched twice: once as written, once normalised. Both are needed, and for
- * different reasons. The normalised pass is what closes the case and
+ * Matched twice: once as written, once normalized. Both are needed, and for
+ * different reasons. The normalized pass is what closes the case and
  * trailing-dot variants above. The verbatim pass is what keeps an app's own
- * `blocked: ['**\/Secrets.txt']` working — `initConfig` appends user patterns
+ * `blocked: ['**\/Secrets.txt']` working, `initConfig` appends user patterns
  * to this list untouched, so folding only the path would quietly stop matching
  * the very patterns the app wrote.
  *
  * On a case-*sensitive* filesystem this over-blocks: a file genuinely named
  * `/PACKAGE.JSON`, distinct from `/package.json`, is refused. That is the
- * intended direction to be wrong in, and it is the reason this normalises the
+ * intended direction to be wrong in, and it is the reason this normalizes the
  * path rather than resolving the file. The router runs this check before it
- * knows which file — often before there is a file at all — so "ask the
+ * knows which file (often before there is a file at all), so "ask the
  * filesystem for the real name" is not available at the point the answer is
  * needed, and would cost a `realpath` per request where it was.
  */

package/src/utils/fs.ts

@@ -15,7 +15,7 @@ import { gzip as zlibGzip } from 'node:zlib'
 import { LRUCache } from '../cache/lru'
 // A cycle on paper (`core/context` imports this file for `getAppVersion`),
 // harmless in practice: neither module touches the other's bindings during
-// evaluation — `hostStore` is only read inside `isForbidden`, at request time.
+// evaluation. `hostStore` is only read inside `isForbidden`, at request time.
 import { hostStore } from '../core/context'
 import type { MixedPromise } from '../types'
 import { is, Try } from './common'
@@ -42,7 +42,7 @@ const gzipAsync = promisify(zlibGzip) as (
  *   1MB   |   5804us  |    6480us  |  14469us  |  17114us
  *   (32KB gzip: median of 5 x 200-iteration runs; single runs were noisy)
  *
- * At 32KB the sync cost crosses the dispatch overhead for zstd — the
+ * At 32KB the sync cost crosses the dispatch overhead for zstd, the
  * first-preference codec. gzip's raw-latency break-even sits nearer 64KB,
  * but the sync figure is a *stall* shared by every concurrent request while
  * the async figure is latency private to one caller, so the tie goes to
@@ -54,8 +54,8 @@ export const ASYNC_COMPRESSION_MIN = 32 * 1024
  * `compress` is the sync variant (blocks the event loop for the durations
  * above); `compressAsync` runs on a worker pool and only parks the caller.
  * zstd: `Bun.zstdCompress` (native async, Bun >= 1.1.21). gzip: Bun 1.3.14
- * has no async `Bun.gzip`, so `node:zlib`'s callback `gzip` — which runs on
- * the libuv pool — is promisified instead. Both async variants were verified
+ * has no async `Bun.gzip`, so `node:zlib`'s callback `gzip` (which runs on
+ * the libuv pool) is promisified instead. Both async variants were verified
  * byte-identical to their sync counterparts on this Bun, so either path
  * yields the same cached artifacts and the same response bodies.
  */
@@ -82,13 +82,13 @@ function toArray<T>(val?: MixedArray<T>): T[] {
 }
 
 /**
- * Memoised: `resolve` measures ~16-20us on Bun/Windows (see `isForbidden`) and
+ * Memoized: `resolve` measures ~16-20us on Bun/Windows (see `isForbidden`) and
  * a CPU profile of the request path put `safeResolve` + `path.resolve` at over
  * 40% of per-request self time. Caching is safe because the function is purely
- * lexical — `path.resolve` reads no filesystem state, only `process.cwd()`.
+ * lexical: `path.resolve` reads no filesystem state, only `process.cwd()`.
  * Relative arguments make entries cwd-dependent, and while nothing in the
  * runtime calls `chdir`, tests do (config.broken.test.ts boots from temp
- * fixture dirs) — so the cache is invalidated wholesale when cwd moves. The
+ * fixture dirs), so the cache is invalidated wholesale when cwd moves. The
  * check is one `process.cwd()` read per call, measured at 12ns in Bun (it is
  * cached natively), against the ~16us a resolve costs. The cache is an LRU,
  * not a Map, because arguments derive from request paths (convention 6);
@@ -238,7 +238,7 @@ export namespace Glob {
 }
 
 export namespace FileSystem {
-  // Naming, not constraint — `string & {}` is `string`. These document what a
+  // Naming, not constraint: `string & {}` is `string`. These document what a
   // parameter means at its declaration, which earns their keep. Four more
   // (`RequestPath`, `DirectoryPath`, `FileName`, `FileExtension`) documented
   // nothing, because nothing ever referenced them.
@@ -267,7 +267,7 @@ export namespace FileSystem {
 
   /**
    * Reads as UTF-8 text. Without the encoding this returns a Buffer, which
-   * every caller then hands to `JSON.parse` — legal at runtime because it
+   * every caller then hands to `JSON.parse`: legal at runtime because it
    * coerces, but a type error at each call site, papered over in one of them
    * with `as any`.
    */
@@ -281,9 +281,29 @@ export namespace FileSystem {
     return (await Try(() => Bun.file(path).stat()))?.isDirectory() || false
   }
 
+  /**
+   * Handed a `BunFile`, this used to take the path back off it and build a
+   * **second** one to stat. A `BunFile` caches its own stat, so the instance
+   * the caller already has is free to read and the fresh one is a syscall:
+   * one question about one file cost two stats and an allocation.
+   *
+   * It shows up wherever a caller asks both questions, which is the common
+   * shape - `validCache` below, `nm.ts`'s `exists(nmFile) ? nmFile.lastModified`,
+   * and both mtime comparisons in `image.ts`. Measured on this machine, four
+   * interleaved rounds against a CPU-bound control flat at 27-31 ms:
+   *
+   *     validCache, file present    33.0 us -> 17.3 us    1.9x
+   *     validCache, file absent     34.9 us -> 17.4 us    2.0x
+   *
+   * The predicate is unchanged, and the two clauses in it are not
+   * interchangeable. `lastModified` on a **missing** file answers roughly
+   * `Date.now()` rather than 0, which is what the `< Date.now()` guard is
+   * for; dropping it reports every absent file as present. The `size > 0`
+   * fallback then covers a file whose mtime is in the future, which clock
+   * skew on a network share produces.
+   */
   export function exists(path: string | Bun.BunFile): boolean {
-    path = typeof path === 'string' ? path : path.name || ''
-    const file = Bun.file(path)
+    const file = typeof path === 'string' ? Bun.file(path) : path
     const lastMod = file.lastModified
     return Boolean((lastMod && lastMod < Date.now()) || file.size > 0)
   }
@@ -293,7 +313,7 @@ export namespace FileSystem {
   }
 
   /**
-   * True only for an existing regular *file* — a directory answers false.
+   * True only for an existing regular *file*: a directory answers false.
    * Sync because `findDynamicRoute` (a sync hot-path scan) is a caller; one
    * stat, no BunFile allocation.
    */
@@ -302,12 +322,12 @@ export namespace FileSystem {
   }
 
   /**
-   * Parent directory of an **already-normalised** absolute path — the output
+   * Parent directory of an **already-normalized** absolute path: the output
    * shape `safeResolve` produces: forward slashes, no `.`/`..` segments, no
    * trailing slash except at a root.
    *
    * Only correct for that input shape, which is why it is not exported.
-   * `isForbidden` is the sole caller and it normalises before the first call.
+   * `isForbidden` is the sole caller and it normalizes before the first call.
    */
   function parentOf(path: string): string {
     const idx = path.lastIndexOf('/')
@@ -319,7 +339,7 @@ export namespace FileSystem {
     // Both of these branches are defensive rather than covered. `isForbidden`
     // stops as soon as the walk leaves `root`, and every root it is called
     // with is a real serve directory well below a filesystem root, so the walk
-    // never reaches one — dropping them both leaves the equivalence test in
+    // never reaches one: dropping them both leaves the equivalence test in
     // `fs.test.ts` green. They are kept so `parentOf` is correct as written
     // rather than correct only for its current caller.
     if (path.charCodeAt(idx - 1) === 58 /* ':' */) return path.slice(0, idx + 1)
@@ -330,7 +350,7 @@ export namespace FileSystem {
    * True when `pathToCheck`, or any directory between it and `root`, holds a
    * `.forbidden` marker.
    *
-   * This is a security guard, and it runs several times per request — from
+   * This is a security guard, and it runs several times per request, from
    * `router.ts` before anything else, then again from `getStatic`, `getRoute`
    * (once per level of a nested route) and the dynamic-route cache. Each call
    * walks every directory between the target and the serve root, so the
@@ -338,26 +358,26 @@ export namespace FileSystem {
    *
    * The walk used to call `safeResolve` twice per level, once to build
    * `<dir>/.forbidden` and once to step to the parent. Both are `node:path`
-   * `resolve`, which on Bun/Windows measures **~16-20us** — roughly 100x
+   * `resolve`, which on Bun/Windows measures **~16-20us**: roughly 100x
    * `path.dirname` (~0.2us), independent of the filesystem and of where the
    * cwd lives, and not explained by native-call overhead (`Bun.nanoseconds()`
    * is 0.045us). A depth-4 walk therefore paid ten `resolve` calls.
    *
-   * Since `curr` is normalised once on entry, every value it takes afterwards
+   * Since `curr` is normalized once on entry, every value it takes afterwards
    * is already in `resolve`'s own output shape, so both operations are exact
    * string edits. That takes a depth-4 walk from ten `resolve` calls to two
    * and leaves one `existsSync` per level as the only remaining syscall.
    * `fs.test.ts` pins the two implementations as equivalent.
    *
-   * The entry normalisation stays: `pathToCheck` reaches here straight from a
+   * The entry normalization stays: `pathToCheck` reaches here straight from a
    * URL pathname in `router.ts`, before any containment check, and collapsing
    * its dot segments is what makes the rest of the walk safe.
    *
-   * The remaining `existsSync` per level is deliberately **not** memoised
+   * The remaining `existsSync` per level is deliberately **not** memoized
    * *across requests*, which is the opposite call to the one `getMimeType`
-   * below makes. The difference is not the key — both are ultimately derived
+   * below makes. The difference is not the key: both are ultimately derived
    * from a request path and both would need an `LRUCache` to stay bounded
-   * under convention 6 — it is what a stale entry costs. A stale MIME type
+   * under convention 6: it is what a stale entry costs. A stale MIME type
    * serves the wrong `Content-Type`; a stale *negative* here serves a file an
    * operator has marked forbidden, which is the exact outcome the marker
    * exists to prevent.
@@ -367,7 +387,7 @@ export namespace FileSystem {
    * a cached "not forbidden" would persist for the life of the process; a TTL
    * would only bound that window, not close it, and an operator dropping a
    * `.forbidden` file to pull content offline has no way to learn how long the
-   * window is. The LRU also fails exactly when it would matter — a client
+   * window is. The LRU also fails exactly when it would matter: a client
    * requesting varied paths evicts the useful upper-level entries, so the
    * hit rate collapses under the load that motivated caching in the first
    * place. `fs.test.ts` has a regression test that fails if this is added.
@@ -376,8 +396,8 @@ export namespace FileSystem {
    * 4-6x per request over overlapping subtrees (router, `getStatic`, every
    * level of `getRoute`, the dynamic-route cache), each walk re-stating the
    * same directories at ~50us per miss on Bun/Windows. A marker dropped
-   * *mid-request* has no meaningful semantics — the operator's guarantee is
-   * "the next request sees it" — so the raw probe results live on the current
+   * *mid-request* has no meaningful semantics (the operator's guarantee is
+   * "the next request sees it"), so the raw probe results live on the current
    * `hostStore` value (`HostContext.forbiddenProbes`), which worker.ts creates
    * per request and never reuses. No store (tests, direct calls, startup)
    * means no caching, bit-for-bit today's behavior.
@@ -399,7 +419,7 @@ export namespace FileSystem {
     //
     // The walk below is bounded by `curr.startsWith(normalizedRoot)`, so an
     // out-of-root path skipped the loop body entirely and fell through to
-    // `return false` — "not forbidden". That is a guard failing *open* on the
+    // `return false`, "not forbidden". That is a guard failing *open* on the
     // one input it most needs to refuse, and it made every caller that relied
     // on this for containment (all of them: `constants.ts` said so in as many
     // words) incapable of catching an escape.
@@ -409,12 +429,12 @@ export namespace FileSystem {
     // read the pattern as drive-absolute, ignored `cwd`, and matched files at
     // `C:\`. `getRoute` resolved one, asked this function, was told "allowed",
     // and returned an `Info` pointing six levels above the serve root. The glob
-    // is fixed too, but the glob was only how it was reached — a resolved file
+    // is fixed too, but the glob was only how it was reached: a resolved file
     // outside the root has to be refused here whatever produced it.
     //
     // The separator suffix matters: a bare `startsWith` would also accept a
     // sibling directory whose name merely begins with the root's. A root that
-    // is already a filesystem root ends in `/` and must not gain a second one —
+    // is already a filesystem root ends in `/` and must not gain a second one:
     // `C://` matches nothing, which would make every path under `C:/` read as
     // an escape. `fs.test.ts` drives both through its root corpus.
     const rootPrefix = normalizedRoot.endsWith('/')
@@ -452,19 +472,53 @@ export namespace FileSystem {
     return false
   }
 
-  let probeForbidden: (path: string) => boolean = nodeExistsSync
+  /**
+   * `statSync` with ENOENT suppressed, not `existsSync`.
+   *
+   * Node's `existsSync` is a `stat` with a `try`/`catch` around it, and on
+   * Bun/Windows the throw-and-catch for a path that is not there is most of
+   * what it costs. Asking for the stat directly and reading `undefined` for a
+   * miss skips that. Measured on this machine, four interleaved rounds
+   * against a CPU-bound control that stayed flat at 27-30 ms:
+   *
+   *     existsSync 30.00 us    guarded statSync 17.52 us    1.71x
+   *
+   * A miss is the case that matters: almost no directory holds a `.forbidden`
+   * marker, so every level of every walk takes this path. At four unique
+   * levels per request that is 50 us, at six 75 us.
+   *
+   * The `catch` is load-bearing rather than defensive habit. `throwIfNoEntry:
+   * false` suppresses **ENOENT only**, so a directory the process cannot stat
+   * still throws EACCES or EPERM where `existsSync` answers false - and a
+   * throw here would escape through `isForbidden` into the request. Answering
+   * false matches the behavior this replaces exactly; the two forms agree on
+   * a missing marker, a present one, a marker that is a *directory*, a path
+   * several levels below anything that exists, a directory, and the empty
+   * string.
+   */
+  function statProbe(path: string): boolean {
+    try {
+      return nodeStatSync(path, { throwIfNoEntry: false }) !== undefined
+    } catch {
+      // See above: a stat that fails for any reason other than absence is
+      // reported as absent, which is what `existsSync` did.
+      return false
+    }
+  }
+
+  let probeForbidden: (path: string) => boolean = statProbe
 
   /**
    * Test seam (convention 9): lets `fs.test.ts` count the syscalls the
    * per-request dedup above is supposed to be saving, without module-mocking
-   * `node:fs` — which is process-global and never unwinds.
+   * `node:fs`, which is process-global and never unwinds.
    */
   export function __setForbiddenProbe(fn: (path: string) => boolean) {
     probeForbidden = fn
   }
 
   export function __resetForbiddenProbe() {
-    probeForbidden = nodeExistsSync
+    probeForbidden = statProbe
   }
 
   export async function mkdir(path: string) {
@@ -508,6 +562,10 @@ export namespace FileSystem {
     return compressable.has(cleanExt)
   }
 
+  /**
+   * Two reads of one `BunFile`, which is one stat: `exists` no longer
+   * re-wraps the instance, so the second read comes off the cached stat.
+   */
   function validCache(file: Bun.BunFile, sourceMtime: number | null): boolean {
     return exists(file) && (!sourceMtime || sourceMtime <= file.lastModified)
   }
@@ -521,11 +579,11 @@ export namespace FileSystem {
    * so N concurrent first-hits on a cold cache each saw "not cached", each ran
    * `compiler()`, and each wrote the same three paths. Measured: 8 concurrent
    * callers produced 8 compiler invocations. Every `.ts`/`.tsx`/`.vue` asset
-   * goes through here, so a traffic burst on a cold cache — or a cluster whose
-   * workers share one cache directory — paid the full transpile *plus* gzip
+   * goes through here, so a traffic burst on a cold cache (or a cluster whose
+   * workers share one cache directory) paid the full transpile *plus* gzip
    * *and* zstd once per concurrent request.
    *
-   * Same memoised-promise idiom as `initDB`, `setupPlugins` and
+   * Same memoized-promise idiom as `initDB`, `setupPlugins` and
    * `getTranspiler`, keyed rather than singular, and deleted in a `finally` so
    * a failed build is retried by the next caller rather than remembered. It is
    * bounded by construction (convention 6): an entry exists only while its own
@@ -533,7 +591,7 @@ export namespace FileSystem {
    *
    * The key is the path alone, not the path plus `sourceMtime`. A caller that
    * joins mid-build can therefore receive a build started for a marginally
-   * older mtime — a window only as wide as one compile, which the next request
+   * older mtime: a window only as wide as one compile, which the next request
    * re-validates and rebuilds. Including the mtime would close that window by
    * letting two builds of the same file race each other onto the same three
    * output paths, which is the worse trade.
@@ -590,7 +648,7 @@ export namespace FileSystem {
       if (content == null) return null
 
       // Only on the build path: a warm hit was paying this stat on every
-      // request for nothing — the directory necessarily exists if the cached
+      // request for nothing, the directory necessarily exists if the cached
       // file it holds just validated.
       await mkdir(cacheDir)
 
@@ -617,7 +675,7 @@ export namespace FileSystem {
 
     // The mirror of the compressed branch's check above. Without it a
     // non-compressible entry (a .woff2 from the gstatic proxy, say) was
-    // rebuilt — for fonts, re-fetched upstream — on every single request.
+    // rebuilt (for fonts, re-fetched upstream) on every single request.
     if (validCache(rawFile, sourceMtime)) return rawFile
 
     const content = await compiler()
@@ -629,8 +687,8 @@ export namespace FileSystem {
 
   /**
    * The extension→MIME mapping is static, but resolving it allocates a
-   * `Bun.BunFile` every call — ~1.4us, on the path of every static-file and
-   * compressed-asset response. Memoised behind an `LRUCache` rather than a
+   * `Bun.BunFile` every call, ~1.4us, on the path of every static-file and
+   * compressed-asset response. Memoized behind an `LRUCache` rather than a
    * plain Map because `ext` is ultimately derived from the request path, and
    * an unbounded map keyed on client-supplied input is exactly what
    * convention 6 forbids.