@bakery-framework/core 2.0.0-alpha.8 → 2.0.0-rc.1

package/src/compiler/tsconfig-sync.ts

@@ -17,7 +17,7 @@ const RE_TRAILING_WILDCARD = /\/?\*?$/
 const RE_ABSOLUTE = /^([A-Za-z]:)?[\\/]/
 
 // The application's tsconfig, resolved against its cwd. This used to write into
-// a tsconfig *inside the framework* — app-specific paths mutating a shipped
+// a tsconfig *inside the framework*: app-specific paths mutating a shipped
 // package file, which is also why running the test suite dirtied the tree.
 const APP_CONFIG_PATH = fs.resolve(process.cwd(), 'tsconfig.json')
 const APP_DIR = process.cwd()
@@ -61,6 +61,13 @@ const PROJECT_DIR = fs.resolve(APP_DIR, '.cache/tsconfig')
  * Before this existed, one config covered everything and `Bun.hash()` in a
  * client file typechecked clean and failed in the browser.
  *
+ * The includes overlap the app's own tsconfig, and that is fine *because
+ * nothing references these projects*: each is a standalone projection of one
+ * concern, pointed at directly (`tsc -p .cache/tsconfig/client.json`), and
+ * subtracting the app's include would gut them into projects that check
+ * nothing. What must never come back is the `references` wiring that composed
+ * them with the app project. See {@link syncTSConfigProjects}.
+ *
  * Globs are app-relative here and rewritten to be relative to the generated
  * file, which sits two levels down.
  */
@@ -93,7 +100,7 @@ export function coreProjects(): PluginTsProject[] {
       include: [`${root}/**/*.ts`],
       exclude: [`${root}/**/api/**/*.ts`],
       // The only project that gets `importMap` aliases, because the import map
-      // is a browser mechanism — see `importMapPaths` on `PluginTsProject`.
+      // is a browser mechanism. See `importMapPaths` on `PluginTsProject`.
       importMapPaths: true,
     },
   ]
@@ -108,7 +115,7 @@ export function coreProjects(): PluginTsProject[] {
 export function fromProjectDir(pathOrGlob: string): string {
   // **`Bakery.config.root` is absolute**, so globs built from it arrive here as
   // full paths. Prefixing `../../` to one yields
-  // `../../C:/WebDAV/.../src/**/*.ts`, which matches nothing — and a project
+  // `../../C:/WebDAV/.../src/**/*.ts`, which matches nothing, and a project
   // that matches nothing typechecks clean, so the mistake presents as success.
   // That is exactly how the first version of this passed with zero files.
   if (RE_ABSOLUTE.test(pathOrGlob)) {
@@ -121,8 +128,8 @@ export function fromProjectDir(pathOrGlob: string): string {
 /**
  * Resolve a `files` entry to something TypeScript will actually load.
  *
- * A package specifier is the useful form for a plugin to write — it does not
- * know where it was installed — but `files` is resolved as a path, so
+ * A package specifier is the useful form for a plugin to write (it does not
+ * know where it was installed), but `files` is resolved as a path, so
  * `@scope/pkg/x.d.ts` would simply be missing. Resolution failure is not fatal:
  * a plugin whose declaration cannot be found should degrade to "no types" and
  * say so, not stop the dev server from booting.
@@ -145,16 +152,16 @@ function resolveFilesEntry(entry: string): string | null {
  *
  * **TypeScript's rule is that a child's `files` *replaces* the parent's, and
  * that rule silently disarmed every project a plugin contributes.**
- * `tsconfig.vue.json` lists core's three ambient declarations — `global.d.ts`,
- * `shared.d.ts`, `types.d.ts` — which is where `Bakery`, `AppConfig`, the JSX
+ * `tsconfig.vue.json` lists core's three ambient declarations: `global.d.ts`,
+ * `shared.d.ts`, `types.d.ts`, which is where `Bakery`, `AppConfig`, the JSX
  * namespace and `Request.session` come from. `@bakery-framework/plugin-vue`
  * declares one `files` entry of its own for `vue.d.ts`, and that one entry
  * replaced all three: measured on a real app, the generated `vue` project loaded
  * **zero** of them.
  *
  * It hid because `vue.d.ts` happens to declare `req` and `body` itself, so the
- * globals an SFC reaches for most still resolved. Everything else — `Bakery`,
- * `MapOf`, the JSX namespace — was quietly missing.
+ * globals an SFC reaches for most still resolved. Everything else (`Bakery`,
+ * `MapOf`, the JSX namespace) was quietly missing.
  *
  * So the base's list is read and merged rather than inherited. Paths inside it
  * are relative to *that* file, which is the property the whole arrangement rests
@@ -174,7 +181,7 @@ function readBase(extendsSpecifier: string): string[] {
     })
   } catch {
     // A base that cannot be read is not fatal: the project still compiles, it
-    // just loses the ambients — which is the status quo this repairs, not a
+    // just loses the ambients, which is the status quo this repairs, not a
     // regression. Assume client-side, which is the conservative half.
     return []
   }
@@ -187,12 +194,12 @@ function readBase(extendsSpecifier: string): string[] {
  * it reached exactly one project: `server`, because that is the only one whose
  * `include` covers `orm/**`. Everywhere else `SchemaRegistry` stayed empty,
  * `Registered` resolved to `never`, and every table fell back to
- * `MapOf<MapOf<any>>` — the ORM's documented untyped mode, arrived at by
+ * `MapOf<MapOf<any>>`: the ORM's documented untyped mode, arrived at by
  * accident. It does not error; it just stops checking.
  *
  * **Server-side projects only.** The client project deliberately does not get
  * it: the ORM is server-only, so a browser file importing `DB` should fail to
- * typecheck rather than be helpfully typed. That is not only a preference —
+ * typecheck rather than be helpfully typed. That is not only a preference:
  * `@bakery-framework/orm` ships TypeScript source that calls `Bun.*`, so pulling
  * it into a config without `bun-types` produces errors from inside the package
  * rather than types for the app. Measured when this was applied to every
@@ -276,7 +283,7 @@ export async function writeProjects(paths: MapOf<string[]>): Promise<string[]> {
       project.server && registrationFile ? [registrationFile] : []
 
     // The base's own `files` are merged back in whenever this project declares
-    // any of its own, because a child's `files` *replaces* the parent's — see
+    // any of its own, because a child's `files` *replaces* the parent's. See
     // `readBase`. Left entirely empty, TypeScript inherits correctly and there
     // is nothing to repair.
     const declared = [...own, ...registration]
@@ -292,7 +299,7 @@ export async function writeProjects(paths: MapOf<string[]>): Promise<string[]> {
         ...(project.compilerOptions ?? {}),
         // Only projects that opt in. `importMap` is served to the browser as
         // `<script type="importmap">`, so its specifiers are resolved there and
-        // nowhere else — writing them into the server project made an import
+        // nowhere else: writing them into the server project made an import
         // that cannot work on the server typecheck as though it could.
         ...(project.importMapPaths && Object.keys(paths).length
           ? { paths: mapPaths(paths) }
@@ -322,22 +329,81 @@ function mapPaths(paths: MapOf<string[]>): MapOf<string[]> {
 }
 
 /**
- * The app's root tsconfig with `references` set, and nothing else touched.
+ * A `references` entry the generator wrote in a previous release, as opposed
+ * to one the developer owns. Ours always pointed into `.cache/tsconfig/`, and
+ * nothing else has a reason to: `.cache/` is the disposable runtime directory,
+ * and every project inside it is regenerated on boot.
+ */
+const RE_GENERATED_REF = /^(\.[\\/])?\.cache[\\/]tsconfig[\\/]/
+
+function isGeneratedReference(entry: unknown): boolean {
+  if (typeof entry !== 'object' || entry === null) return false
+  const path = (entry as { path?: unknown }).path
+  return typeof path === 'string' && RE_GENERATED_REF.test(path)
+}
+
+/**
+ * The root config with the generator's own `references` removed, or `null`
+ * when there is nothing to repair.
+ *
+ * Until 2026-08-27 `syncTSConfigProjects` *added* those references, wiring the
+ * generated projects into the app's project graph. That glue is what broke
+ * `tsc -p <app>` for every consumer who had booted once. Measured directly
+ * (TypeScript 6.0.3):
+ *
+ * - `tsc -p` verifies every referenced project whenever the referencing
+ *   program has input files of its own: a reference to a non-composite
+ *   project is TS6306 and to a `noEmit` one TS6310, **even when the
+ *   referenced project's include is disjoint from the root's, and even when
+ *   it matches zero files**. No include shape survives.
+ * - Each root file a referenced project also claims is redirected to that
+ *   project's declaration output, which `noEmit` guarantees was never built:
+ *   TS6305, once per overlapping file: `src/**`, `server.config.ts`, every
+ *   `.tsx` page.
+ *
+ * The generated projects extend `noEmit` bases and rely on
+ * `allowImportingTsExtensions`, so they are unbuildable by design. Making them
+ * `composite` instead would trade the errors above for a `tsc -b` build-order
+ * requirement no consumer runs, and TS6305 would still fire for any root file
+ * importing into one while unbuilt. The only reference shape `tsc -p`
+ * tolerates from a root that has files of its own is no reference at all, so
+ * the projects stand alone now and this strips what previous releases wrote.
+ *
+ * Everything the developer owns is preserved: only entries into
+ * `.cache/tsconfig/` are removed, a real project reference (say `../shared`)
+ * stays, and the `references` key itself survives unless the generator wrote
+ * every entry in it.
+ *
+ * Pure, and exported, so the repair can be tested without a function that
+ * writes to `process.cwd()`. The property that matters is negative (*no key
+ * the developer wrote is lost*), which a shape assertion on the source cannot
+ * check.
+ */
+export function stripGeneratedReferences(
+  current: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const refs = current.references
+  if (!Array.isArray(refs)) return null
+
+  const kept = refs.filter(entry => !isGeneratedReference(entry))
+  if (kept.length === refs.length) return null
+
+  const repaired = { ...current }
+  if (kept.length) repaired.references = kept
+  else delete repaired.references
+  return repaired
+}
+
+/**
+ * The root config written when the app has none at all.
  *
- * Pure, and exported, so the merge can be tested without a function that writes
- * to `process.cwd()`. The property that matters is negative — *no key the
- * developer wrote is lost* — which is the kind of thing a shape assertion on the
- * source cannot check.
+ * The generated projects do not help Bun's runtime: it reads
+ * `compilerOptions.jsx*` from the root `tsconfig.json` and follows `extends`
+ * only into a relative path, never a package specifier, so the file this
+ * writes has to carry the JSX options itself, inline, exactly as the
+ * scaffolder spells them.
  */
-export function mergeRootConfig(
-  current: Record<string, unknown> | null,
-  references: { path: string }[],
-): Record<string, unknown> {
-  // Spread first so `references` is the only key this owns.
-  if (current) return { ...current, references }
-
-  // No root config at all. The generated projects do not help Bun's runtime, so
-  // the one this writes has to carry the JSX options itself.
+export function defaultRootConfig(): Record<string, unknown> {
   return {
     extends: '@bakery-framework/core/tsconfig.server.json',
     compilerOptions: {
@@ -345,58 +411,63 @@ export function mergeRootConfig(
       jsxFactory: 'createElement',
       jsxFragmentFactory: 'Fragment',
     },
-    references,
   }
 }
 
 /**
- * Generate the project configs and add `references` to the app's root tsconfig.
+ * Generate the project configs, and keep the app's root tsconfig viable:
+ * created with the runtime JSX options when the app has none, and stripped of
+ * the `references` a previous release wrote into it.
  *
  * Separate from `syncTSConfigPaths` because an app can reasonably want one and
  * not the other: the paths sync has existed for a long time and rewrites a file
  * people keep in git, while this owns a directory nobody edits.
  *
- * **It used to replace the root config with a references-only stub, and that
- * silently broke every `.tsx` page in the app.** The reasoning was tidy — the
- * generated projects carry the JSX options, so the root does not need them — and
- * it was wrong about *who reads the root*. `tsc` follows `references`; **Bun's
- * runtime does not.** Bun reads `compilerOptions.jsx*` from the root
- * `tsconfig.json` and nothing else, so a references-only root means pages get
- * transpiled against the automatic JSX runtime instead of Bakery's
- * `createElement`.
- *
- * The symptom is worse than the 500 that mistake usually produces. Measured on a
- * scratch app: `GET /` answered **200** with
- * `{"type":"html","props":{…},"_owner":null,"_store":{}}` — a React element tree,
- * JSON-encoded, because the handler received an object where it expects a
- * `SafeHtml` string. Nothing logs, nothing throws, the status is fine.
+ * **The generated projects are standalone on purpose; the root config does not
+ * reference them.** They exist for direct invocation against the one concern
+ * each covers: `vue-tsc -p .cache/tsconfig/vue.json` is the only way an SFC
+ * typechecks at all, `tsc -p .cache/tsconfig/client.json` proves browser code
+ * clean of `Bun.*`, and a plugin's project carries its own ambients the same
+ * way. Their `include` deliberately overlaps the app's own project: they are
+ * alternate projections of the same files, used *instead of* the root for
+ * their slice, never composed with it. Wiring them in as `references` broke
+ * `tsc -p <app>` for any consumer who had booted once (TS6305/6306/6310: the
+ * measurements are on {@link stripGeneratedReferences}), and what the wiring
+ * bought was less than it looked: tsserver routes a file to the project whose
+ * `include` claims it, so for everything a scaffolded root claims, `src/**`,
+ * `server.config.ts`, `orm/**`, the reference walk never ran anyway.
  *
- * So the root is now *merged*, not replaced: every key the developer wrote stays,
- * and only `references` is ours. That also settles the contradiction with the
- * scaffolder, which writes those JSX options under a comment saying to keep them
- * — and with the three documentation pages that repeat it.
+ * Two earlier lessons still bind the root-config half. It used to be
+ * *replaced* with a references-only stub, which silently broke every `.tsx`
+ * page: Bun's runtime reads `compilerOptions.jsx*` from the root and does not
+ * follow `references`, so pages transpiled against the automatic JSX runtime
+ * and `GET /` answered 200 with a JSON-encoded React element tree. Hence
+ * {@link defaultRootConfig} when no root exists, and surgical repair (never
+ * wholesale rewrite) when one does. And a boot that dirties git every time
+ * trains people to ignore the diff, so an already-clean root is not rewritten.
  */
 export async function syncTSConfigProjects(): Promise<void> {
   try {
     const written = await writeProjects(buildPaths())
 
-    const references = written.map(name => ({
-      path: `./.cache/tsconfig/${name}.json`,
-    }))
-
     const current = fs.exists(APP_CONFIG_PATH)
       ? parseJSONC(await Bun.file(APP_CONFIG_PATH).text())
       : null
 
-    // Only rewrite when the reference set actually changed. The root config is
-    // committed, and a dev boot that dirties git every time trains people to
-    // ignore the diff.
-    if (current && Bun.deepEquals(current.references, references)) return
+    if (!current) {
+      await Bun.write(
+        APP_CONFIG_PATH,
+        `${JSON.stringify(defaultRootConfig(), null, 2)}\n`,
+      )
+      serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+      return
+    }
 
-    const root = mergeRootConfig(current, references)
+    const repaired = stripGeneratedReferences(current)
+    if (!repaired) return
 
-    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(root, null, 2)}\n`)
-    serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(repaired, null, 2)}\n`)
+    serveLog.TSCONFIG_REFERENCES_REMOVED()
   } catch (err: any) {
     serveLog.UNHANDLED_ERR({
       error: `TSConfig project sync error: ${errorMsg(err)}`,

package/src/core/bakery.ts

@@ -14,7 +14,7 @@ export { hostStore } from './context'
  * one collapses to the unprefixed key. That is not cosmetic: this key becomes a
  * **filename** in five handlers, and `getOrCreateCachedFile` writes three files
  * per entry with no bound and no eviction. Prefixing the raw `Host` header let
- * any client mint an unlimited number of cache entries — 25 requests for one
+ * any client mint an unlimited number of cache entries: 25 requests for one
  * path under 25 made-up hostnames took the cache directory from 9 files to 84.
  *
  * `resolveHostConfig` already carries this reasoning for the config cache; the
@@ -69,9 +69,12 @@ export const Bakery: globalThis.Bakery = {
   get version() {
     return getAppVersion()
   },
-  sharedPool: new SharedMemoryPool(1024 * 1024),
+  // No size: the pool's own layout is the default now. It used to be asked for
+  // a megabyte, of which 9,280 bytes were the layout and the rest a region
+  // nothing read. See the constructor in `utils/shared-pool.ts`.
+  sharedPool: new SharedMemoryPool(),
   // Defined in `core/context.ts`, which is low enough that a module needing a
-  // path does not have to import `Bakery` to get one — reaching them through
+  // path does not have to import `Bakery` to get one: reaching them through
   // here is what closed the logger cycle. These stay the reading surface for
   // application and framework code; context is the single definition.
   //

package/src/core/cache-version.ts

@@ -8,19 +8,19 @@ import { getAppVersion, getFrameworkVersion } from './context'
 /**
  * Discard `.cache/` when the thing that produced it has changed.
  *
- * Its own module, and that is the fix rather than an organisational
+ * Its own module, and that is the fix rather than an organizational
  * preference. This used to live in `config.ts` and run from `initConfig()`,
  * which is far too late: `cache/shared-db.ts` opens `.cache/shared-cache.db`
  * at **import** time, so by the time the check ran the process was already
  * holding a handle to a file inside the directory it was about to delete. On
  * Windows that delete fails with `EBUSY`, node's recursive walk stops at the
- * locked entry, and everything it had not reached yet survived — including
+ * locked entry, and everything it had not reached yet survived, including
  * `html/`, the compiled-page cache, which is exactly what a version bump has
  * to discard.
  *
  * Now `shared-db.ts` awaits this before opening the database, and `initConfig`
  * still calls it for the case where nothing has touched the cache yet. It is
- * memoised, so whichever gets there first does the work and the other is free.
+ * memoized, so whichever gets there first does the work and the other is free.
  */
 let done: Promise<void> | null = null
 
@@ -29,6 +29,41 @@ export function checkCacheVersion(): Promise<void> {
   return done
 }
 
+/** Every field that decides whether a compiled artifact is still valid. */
+export interface CacheMarker {
+  mode: string
+  version: string
+  framework: string
+  runtime: string
+}
+
+/**
+ * Whether a marker describes a cache the current process can still use.
+ *
+ * Exported and called rather than restated, which is the point. The tests
+ * beside this file used to write the comparison out a second time and assert
+ * on their own copy - so they passed whichever fields the real code compared,
+ * and would have gone on passing if one were dropped. Adding `runtime` is what
+ * made that visible: three tests agreed the marker "carries all three fields"
+ * while the code had four.
+ *
+ * A missing field reads as stale, which is the intended upgrade path. A marker
+ * written before a field existed describes a cache built under conditions
+ * nobody recorded, and one wipe is cheaper than guessing.
+ */
+export function isCacheStale(
+  prev: Partial<CacheMarker> | null | undefined,
+  current: CacheMarker,
+): boolean {
+  if (!prev) return true
+  return (
+    prev.mode !== current.mode ||
+    prev.version !== current.version ||
+    prev.framework !== current.framework ||
+    prev.runtime !== current.runtime
+  )
+}
+
 /** Test seam: forget that the check ran, so a fixture can exercise it again. */
 export function __resetCacheVersionCheck(): void {
   done = null
@@ -41,7 +76,7 @@ async function run(): Promise<void> {
 
   // Read from `Bakery.cacheDir`, never re-derived from `fs.cwd`. This value is
   // handed straight to a recursive delete below, and it used to be a
-  // hand-written copy of the constant in `core/bakery.ts` — two sources of
+  // hand-written copy of the constant in `core/bakery.ts`: two sources of
   // truth for a `rm -rf`. Renaming the cache directory in one place and not the
   // other would have pointed this delete at whatever the stale literal named.
   const cacheDir = Bakery.cacheDir
@@ -55,17 +90,32 @@ async function run(): Promise<void> {
     // framework version, with nothing to invalidate it.
     version: getAppVersion(),
     framework: getFrameworkVersion(),
+    // **And the runtime, for exactly the same reason one level down.**
+    //
+    // This directory holds *compiled and bundled output* - `html/`, `static/`,
+    // `ts_cache/`, the console bundle. Bun's transpiler and bundler produce it,
+    // so a Bun upgrade changes what a correct entry looks like, and nothing
+    // here used to notice.
+    //
+    // Not hypothetical, and found the day it happened. Bun 1.4.1 reworked the
+    // bundler's barrel optimization across ten commits: 1.4.0 emptied a
+    // `sideEffects: false` re-export entry to `export { a };` with no
+    // declaration, which is the husk `compiler.ts` carries a repair for. So a
+    // cache written by 1.4.0 can hold a husk that the running 1.4.2 would
+    // never have produced, and would have served it for the life of the
+    // install. 1.4.1 is worse in a quieter way: a bundle it built can rename a
+    // `let` onto a function parameter's name and compute **wrong values**
+    // while loading perfectly (oven-sh/bun#41354).
+    //
+    // `Bun.version` rather than `Bun.revision`: a canary build of the same
+    // version is a real distinction, but invalidating on every canary would
+    // wipe the cache of anyone tracking one, and the failure this prevents is
+    // a released bundler change.
+    runtime: Bun.version,
   }
 
   const [err, prev] = await Try.catch(() => Bun.file(markerPath).json())
-  const stale =
-    err ||
-    !prev ||
-    prev.mode !== current.mode ||
-    prev.version !== current.version ||
-    prev.framework !== current.framework
-
-  if (!stale) return
+  if (!err && !isCacheStale(prev, current)) return
 
   const survivors = await wipe(cacheDir)
   if (!fs.exists(cacheDir)) await fs.mkdir(cacheDir)
@@ -73,7 +123,7 @@ async function run(): Promise<void> {
   // The marker is written **only** when the directory is actually empty.
   //
   // It used to be written unconditionally, right after a delete whose every
-  // error was swallowed — so a failed wipe produced a file asserting the cache
+  // error was swallowed, so a failed wipe produced a file asserting the cache
   // was current, and nothing ever tried again. A stale compiled page then
   // outlived the upgrade that was supposed to remove it, silently and
   // permanently. Leaving the old marker in place costs one retry per boot and
@@ -95,7 +145,7 @@ async function run(): Promise<void> {
  *
  * Per-entry rather than one recursive call on the directory itself, because a
  * single locked file otherwise shields every entry the walk had not yet
- * reached — the failure is ordering-dependent, so it presents as "sometimes the
+ * reached: the failure is ordering-dependent, so it presents as "sometimes the
  * cache clears".
  */
 export const __wipeCacheDir = wipe
@@ -104,7 +154,7 @@ export const __wipeCacheDir = wipe
  * The one thing in `.cache/` the wipe must not take.
  *
  * **The app's committed `tsconfig.json` *references* `.cache/tsconfig/*.json`,
- * so deleting them breaks the editor for the whole project** — not one setting,
+ * so deleting them breaks the editor for the whole project**, not one setting,
  * everything. TypeScript reports `TS6053: File '…/server.json' not found` for
  * each reference, has no project left to put a file in, and falls back to an
  * inferred one with no ambients: `req.session`, `Bakery`, the JSX namespace and
@@ -112,13 +162,13 @@ export const __wipeCacheDir = wipe
  *
  * That happens on every framework upgrade, because the version wipe is keyed on
  * the framework version among others. The developer sees their editor lose every
- * type the moment they bump a patch, and nothing says why — the files come back
+ * type the moment they bump a patch, and nothing says why: the files come back
  * only on the next `bun run dev`, which is not an obvious remedy for "my types
  * vanished".
  *
  * Keeping them is safe in the direction that matters. A stale project is
  * regenerated on the next dev boot and is, in the meantime, *approximately
- * right* — while a missing one is catastrophically wrong. Nothing is executed
+ * right*, while a missing one is catastrophically wrong. Nothing is executed
  * from these files either: they configure a typechecker, so the "never read a
  * cache an older framework wrote" rule the wipe exists to enforce does not apply.
  */
@@ -131,7 +181,7 @@ async function wipe(dir: string): Promise<string[]> {
 
   for (const entry of entries) {
     if (WIPE_KEEP.has(entry)) continue
-    // Errors are deliberately not swallowed *silently* here — each failure is
+    // Errors are deliberately not swallowed *silently* here: each failure is
     // collected and reported by the caller.
     await Try.catch(() =>
       rm(`${dir}/${entry}`, { recursive: true, force: true }),

package/src/core/config.ts

@@ -38,7 +38,7 @@ const defaultConfig: Required<AppConfig> = {
   },
   onShutdown: NOOP,
   // `maxCacheSize: 500` used to sit here. Nothing in the framework ever read
-  // it — not the route LRUs, not the tiered cache — so it was a knob that
+  // it (not the route LRUs, not the tiered cache), so it was a knob that
   // typechecked, appeared in completion, and did nothing. Removed from
   // `AppConfig` at the same time; `defaultConfig` is `Required<AppConfig>`, so
   // the two can only move together.
@@ -52,7 +52,7 @@ const defaultConfig: Required<AppConfig> = {
   rateLimit: DEFAULT_RATE_LIMIT,
   trustProxy: false,
   // Empty means auto-detect, matching `head`/`body` above. There is no default
-  // *path* to give here: the default behaviour is the probe itself.
+  // *path* to give here: the default behavior is the probe itself.
   schema: '',
   root: 'src',
   hosts: {},
@@ -72,7 +72,7 @@ let configLoadError: string | null = null
 /**
  * The import failure recorded by the most recent `initConfig()` run, when a
  * `server.config.ts` was *present but failed to load*. DEV-only by
- * construction — in PROD that same condition throws out of `initConfig()`
+ * construction: in PROD that same condition throws out of `initConfig()`
  * instead of being recorded. Read by `runStartupBanner()` so the warning is
  * restated where the developer is actually looking, not just in scrollback.
  */
@@ -81,10 +81,10 @@ export function getConfigLoadError(): string | null {
 }
 
 /**
- * `hosts` folded to lower case, memoised against the object it came from.
+ * `hosts` folded to lower case, memoized against the object it came from.
  *
  * Keyed on identity rather than rebuilt per request because `hosts` is frozen
- * for the process lifetime — except under `__setTestConfig`, where a new object
+ * for the process lifetime: except under `__setTestConfig`, where a new object
  * arrives and the identity check rebuilds rather than serving a stale map.
  */
 let hostLookup: {
@@ -117,16 +117,16 @@ export async function initConfig(): Promise<Readonly<ProcessedAppConfig>> {
     const [error, loaded] = await Try.catch(import(configPath))
     if (error) {
       // Present-but-broken is not absence. This used to log one line and boot
-      // on `defaultConfig` — port 3000, no plugins, no hosts — so the
+      // on `defaultConfig` (port 3000, no plugins, no hosts), so the
       // developer debugged the vanished dashboard instead of the config that
       // never parsed. In PROD that boot must not happen: the throw lands in
       // the entry's existing catch (prod.ts / threads.ts / worker.ts), which
       // logs and exits 1. In DEV a crash would just loop the watcher, so boot
-      // — loudly, and leave the error for the startup banner to restate.
+      //: loudly, and leave the error for the startup banner to restate.
       const message = errorMsg(error)
       if (import.meta.env.PROD) {
         throw new Error(
-          `server.config.ts exists but failed to import — refusing to start on the default config.\n  file: ${configPath}\n${message}`,
+          `server.config.ts exists but failed to import: refusing to start on the default config.\n  file: ${configPath}\n${message}`,
         )
       }
       configLoadError = message
@@ -165,7 +165,7 @@ let testOverrides: Partial<ProcessedAppConfig> | null = null
  * The resolved config is frozen, so a test that needs to exercise a
  * config-dependent branch cannot simply assign to it. The alternative was
  * `mock.module('./core/config', …)`, which is process-global and never
- * restored — one file doing that left `Bakery.config` undefined for every test
+ * restored: one file doing that left `Bakery.config` undefined for every test
  * file loaded after it, and the suite stayed green only because Bun happened
  * to order that file last.
  *
@@ -246,12 +246,12 @@ function lookupHostEntry(
 
 /**
  * The canonical form of `hostname` if the app declares it under `hosts`, and
- * `''` otherwise — including when no `hosts` are configured at all.
+ * `''` otherwise, including when no `hosts` are configured at all.
  *
  * Same reasoning as `resolveHostConfig` below, which already refuses to cache
  * an unknown hostname: the value arrives on the `Host` header, so anything
- * derived from it that is *kept* — a config entry, a cache key, a file on disk
- * — has to be bounded by the configured set, or an unauthenticated client can
+ * derived from it that is *kept* (a config entry, a cache key, a file on disk
+ *) has to be bounded by the configured set, or an unauthenticated client can
  * grow it without limit. Collapsing unknown hosts to `''` puts them all in one
  * bucket, which is correct because they all get the base config and therefore
  * the same content.
@@ -276,10 +276,10 @@ export function resolveHostConfig(
   const hosts = base.hosts
   if (!hosts || !Object.keys(hosts).length) return base
 
-  // Hostnames are case-insensitive (RFC 4343) and nothing upstream normalises
+  // Hostnames are case-insensitive (RFC 4343) and nothing upstream normalizes
   // the Host header, so a request to `EXAMPLE.com` used to miss an
   // `example.com` entry and silently fall back to the base config. Both sides
-  // fold to lower case — `toLowerCase`, not `toLocaleLowerCase`, which would
+  // fold to lower case: `toLowerCase`, not `toLocaleLowerCase`, which would
   // map `I` to a dotless `ı` in a Turkish locale.
   const key = hostname.toLowerCase()
 
@@ -290,9 +290,9 @@ export function resolveHostConfig(
   if (!entry) {
     // Deliberately NOT cached. The hostname comes straight from the Host
     // header, so caching unknown values let any client grow this map without
-    // bound — one request per made-up hostname until the process runs out of
+    // bound: one request per made-up hostname until the process runs out of
     // memory. Known hosts are a fixed, small set, so only those are cached.
-    // Normalising above keeps that bound honest: without it, `EXAMPLE.com` and
+    // Normalizing above keeps that bound honest: without it, `EXAMPLE.com` and
     // `example.com` would occupy two entries for one configured host.
     return base
   }