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

package/src/handlers/core/$mounts.ts

@@ -4,7 +4,7 @@ import { fs } from '../../utils'
  * Route mounts: map a URL prefix onto a directory outside the app's serve root.
  *
  * Handlers resolve files under `Bakery.serveRoot`, so a plugin wanting to serve
- * its own pages or client assets had no choice but to hand-roll it — reading
+ * its own pages or client assets had no choice but to hand-roll it: reading
  * files itself, bundling on the fly, and reimplementing the caching and
  * containment the handler pipeline already does. `DashboardHandler` is the
  * worked example of that cost.
@@ -17,7 +17,7 @@ import { fs } from '../../utils'
  * the search dir *and* the root, so traversal cannot escape it.
  */
 export interface RouteMount {
-  /** URL prefix, leading slash, no trailing slash — e.g. `/_dashboard`. */
+  /** URL prefix, leading slash, no trailing slash, e.g. `/_dashboard`. */
   prefix: string
   /** Absolute directory the prefix resolves against. */
   dir: fs.AbsolutePath

package/src/handlers/core/$registry.ts

@@ -1,4 +1,5 @@
 import { LRUCache } from '../../cache/lru'
+import { hostKey } from '../../core/bakery'
 import type { Handler } from './$base'
 
 /**
@@ -51,8 +52,8 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
    * `delete` and `clear` invalidate too, and neither used to.
    *
    * `list()` memoizes the sorted handler array and only `set` cleared it, so a
-   * removed handler stayed in the list — and therefore stayed *in the request
-   * pipeline* — until something happened to add one. Registration is
+   * removed handler stayed in the list (and therefore stayed *in the request
+   * pipeline*) until something happened to add one. Registration is
    * add-only in a served process, which is why this never bit: it is reachable
    * only by code that unregisters, and the first thing to do that was a test.
    *
@@ -98,7 +99,7 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
    * `canHandle` without the microtask hop when the answer is synchronous.
    *
    * Most canHandles are plain predicates, and `await`ing their boolean cost a
-   * microtask hop (~426ns) per probe, 2–4 probes per request. Returns a
+   * microtask hop (~426ns) per probe, 2 to 4 probes per request. Returns a
    * boolean for a sync answer and the promise itself for an async one, so
    * callers only `await` a value that is actually a promise:
    *
@@ -126,8 +127,17 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
   // must not run twice. That constraint is what the branching encodes.
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: cache-path + side-effect-sensitive probe loop
   async resolve(path: string, req?: Request, ...rest: any[]) {
-    const host = req?.__hostname || ''
-    const pathId = `${this.id}:${host}:${path}`
+    // The **resolved** host, not the header. `__hostname` is whatever arrived
+    // in `Host`, and `routeCache` is one bounded LRU shared by every tenant, so
+    // a client varying that header minted an entry per spelling and walked the
+    // real hosts' entries out of the cache for as long as it kept asking. The
+    // file cache carried the same bug and was fixed; this one kept it.
+    //
+    // `hostKey` resolves through the multi-host config the way every other
+    // per-tenant key does, so an unknown or unconfigured host collapses to a
+    // single entry instead of one per spelling. The shape is unchanged when
+    // there is no host: `hostKey` returns the bare path.
+    const pathId = `${this.id}:${hostKey(path)}`
     const cached: any = HandlerMap.routeCache.get(pathId)
 
     // Only tracked once there is a cache hit to skip past. Middleware has
@@ -138,7 +148,7 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     if (cached) {
       probed = new Set()
       // A cache hit skips every handler above the cached one. Ask the
-      // gatekeepers that outrank it first — the same handlers, in the same
+      // gatekeepers that outrank it first: the same handlers, in the same
       // order, a cold resolve would have reached before the cached one.
       const rank = this.order().get(cached) ?? Number.POSITIVE_INFINITY
       for (const gate of this.gatekeepers()) {

package/src/handlers/core/$routing.ts

@@ -15,14 +15,14 @@ export type RouteScanOptions = {
 }
 
 // `[!.]` keeps catch-alls (`[...name]`) out of the single-param globs: they
-// are matched separately, and last — a catch-all is the weakest route form,
+// are matched separately, and last. A catch-all is the weakest route form,
 // consulted only after specific files, single-param siblings and child-index
 // descent have all missed.
 const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 
 // The single-param route forms, in the order they are tried: `[name].ext`
 // first, then the literal-asterisk `*.ext`. Built here rather than twice inside
-// `routeGlobs` — the `dynamicOnly` branch and the combined branch returned
+// `routeGlobs`: the `dynamicOnly` branch and the combined branch returned
 // character-identical pairs, and the two must stay in step or a route form
 // resolves under one caller and not the other. A function, not a hoisted
 // constant: `ext` varies per handler, and `staticOnly` returns before it needs
@@ -33,22 +33,22 @@ const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 // a path separator: Bun read `\*.*` as a drive-absolute pattern, ignored the
 // `cwd` in `GETFILE` entirely, and matched files at `C:\`. A route lookup under
 // a serve root six levels down returned `C:\$WINRE_BACKUP_PARTITION.MARKER`,
-// and `fs.isForbidden` — whose walk is bounded by `startsWith(root)` — waved it
+// and `fs.isForbidden` (whose walk is bounded by `startsWith(root)`) waved it
 // through because an out-of-root path skipped the loop and answered "allowed".
 // That clamp now fails closed, so this is belt and braces; both halves are
 // pinned, and neither test can see the other's bug.
 //
 // Measured with a scan whose cwd was a temp directory holding one file: `[*]`
 // yields nothing, `\*` yields four files from the drive root. The escape is
-// also unreachable on Windows in the direction it was meant for — `*` is a
+// also unreachable on Windows in the direction it was meant for: `*` is a
 // reserved character in a Windows filename, so a route file literally named
 // `*.ts` can only exist on POSIX, where both spellings match it identically
 // (verified on Linux). The character class costs nothing and means the same
 // thing on both platforms.
 //
 // Exported only as a test seam: with the clamp in place no test driving
-// `getRoute` can tell the two spellings apart — verified by reverting this line
-// and watching all 17 pass — so the pattern has to be asserted directly.
+// `getRoute` can tell the two spellings apart (verified by reverting this line
+// and watching all 17 pass), so the pattern has to be asserted directly.
 export const dynamicGlobs = (ext: string) => [
   new Bun.Glob(`[[][!.]*${ext || '.*'}`),
   new Bun.Glob(`[*]${ext || '.*'}`),
@@ -88,8 +88,7 @@ const routeGlobs = (
  * The catch-all fallback for one directory level: `dir/[...name].ext`,
  * containment-checked like every other candidate. Skipped for `staticOnly`
  * (the caller wants a literal file), and it *yields to any real file*: when
- * the request's remaining segments name an existing file under `dir` —
- * whatever its extension — the catch-all declines, so a lower-priority
+ * the request's remaining segments name an existing file under `dir` ( * whatever its extension) the catch-all declines, so a lower-priority
  * handler (TSHandler, StaticHandler) can serve the file itself. A directory
  * is not a file and does not trigger the yield. `findDynamicRoute` applies
  * the same rule on the cached path; the two must agree.
@@ -102,7 +101,7 @@ const routeGlobs = (
  * `provides.ts` at `/teacher/provides` and `/teacher/provides.js`, so neither
  * spelling named a file on disk and a Vue catch-all above it (priority 58 vs
  * 50) served HTML to a browser that asked for a module. The probe now also
- * tries the registered dynamic extensions against the extensionless base —
+ * tries the registered dynamic extensions against the extensionless base:
  * the same mapping the serving handlers apply, read from the live registry so
  * a plugin's extension (`.vue`) counts without core naming it.
  *
@@ -118,7 +117,7 @@ export function servedSourceExists(target: string): boolean {
     try {
       exts = (handler as { config?: { ext?: unknown } }).config?.ext
     } catch {
-      // A config getter that needs state this process lacks — a handler with
+      // A config getter that needs state this process lacks: a handler with
       // no ext table cannot claim a source file either way.
       continue
     }
@@ -147,13 +146,13 @@ async function getCatchAllRoute(
     const target = fs.resolve(dir, restSegments.join('/'))
     // Stat only inside `dir`. A rest containing `..` resolves outside it, and
     // statting there would make this yield a boolean existence probe for any
-    // path on the filesystem — the 404-vs-render difference is observable.
-    // URL parsing normalises `..` and `%2e%2e` away, so no HTTP request
+    // path on the filesystem: the 404-vs-render difference is observable.
+    // URL parsing normalizes `..` and `%2e%2e` away, so no HTTP request
     // reaches here with one; this closes the door for any caller that skips
-    // that normalisation. An escape skips the yield rather than refusing, so
+    // that normalization. An escape skips the yield rather than refusing, so
     // the catch-all answers exactly as it did before the yield rule existed.
     // `dir` comes from `fs.resolve`, so the separator-suffixed prefix test is
-    // exact — plain `startsWith(dir)` would also accept a sibling directory
+    // exact: plain `startsWith(dir)` would also accept a sibling directory
     // whose name merely begins with it.
     if (
       (target === dir || target.startsWith(`${dir}/`)) &&
@@ -169,7 +168,7 @@ async function getCatchAllRoute(
 
   // A bare-directory request (`/docs` with no index) reaches here with no
   // rest segments, and only the `[...name!]` spelling opted into claiming
-  // it — the plain form keeps requiring at least one segment.
+  // it: the plain form keeps requiring at least one segment.
   if (!restSegments.length && !info.optionalCatchAll) return null
 
   return info
@@ -183,7 +182,7 @@ export async function getRoute(
   root?: fs.AbsolutePath,
   options: RouteScanOptions = {},
 ): Promise<Handler.Route.Info | null> {
-  // Both used to default to `Bakery.serveRoot` independently — two reads of
+  // Both used to default to `Bakery.serveRoot` independently. Two reads of
   // the config getter (an AsyncLocalStorage getStore each) when a caller
   // omits both. One read now covers whichever is missing; the values are
   // unchanged.
@@ -234,7 +233,7 @@ export async function getRoute(
     // statement is `isForbidden(dir, root)` with these exact arguments, and its
     // `null` reaches the same `return null` this function ends on. Checking
     // here as well made every level of a nested route pay two identical
-    // directory tree-walks — and `isForbidden` walks from the file to the root
+    // directory tree-walks, and `isForbidden` walks from the file to the root
     // doing an existsSync at each level, so that is the most expensive thing
     // this function does. `src/tests/forbidden.test.ts` pins both branches.
     if (first !== 'index') {
@@ -246,7 +245,7 @@ export async function getRoute(
     // `first === 'index'` is the bare-directory request (`/docs` arrives here
     // as an injected 'index' segment, after no index file matched). The plain
     // `[...name]` pattern requires at least one rest segment and cannot claim
-    // it; `[...name!]` exists to — `getCatchAllRoute` tells them apart.
+    // it; `[...name!]` exists to: `getCatchAllRoute` tells them apart.
     if (!options.staticOnly) {
       return await getCatchAllRoute(
         ext,
@@ -263,7 +262,7 @@ export async function getRoute(
     if (route) return route
 
     // The walk above descends one real segment at a time and dead-ends when
-    // the next directory does not exist — which for a catch-all request
+    // the next directory does not exist, which for a catch-all request
     // (`/docs/a/b/c` against `docs/[...slug].tsx`) is the common case. Each
     // level unwinds through here, so the deepest existing directory gets the
     // first chance to claim the rest.

package/src/handlers/core/$static.ts

@@ -4,14 +4,13 @@ import { fs } from '../../utils/fs'
 import { resolveMount } from './$mounts'
 
 /**
- * Literal file resolution — the static counterpart to `getRoute`.
+ * Literal file resolution: the static counterpart to `getRoute`.
  *
  * `getRoute` answers "which file backs this *route*", with extensionless URLs,
  * dynamic `[id]` segments and glob scanning. This answers the simpler question
  * "which file is at this path, and am I allowed to serve it".
  *
- * It exists because four handlers were each spelling that out themselves —
- * StaticHandler, PublicHandler, ImageHandler and NMHandler — in four slightly
+ * It exists because four handlers were each spelling that out themselves ( * StaticHandler, PublicHandler, ImageHandler and NMHandler) in four slightly
  * different ways, and only some of them checked everything. Once route mounts
  * arrived the drift got worse: a mount-aware StaticHandler sitting next to a
  * mount-blind PublicHandler is the kind of inconsistency that turns into a bug
@@ -19,7 +18,7 @@ import { resolveMount } from './$mounts'
  *
  * **Three of those four go through this; NMHandler does not, on purpose.** Its
  * entry point is resolved by `Bun.build`, not by the filesystem, so
- * `/_nm/pkg/sub` legitimately means `pkg/sub/index.js` — a path this function
+ * `/_nm/pkg/sub` legitimately means `pkg/sub/index.js`: a path this function
  * answers `null` for, because it is a directory. It therefore repeats the
  * containment test and calls `fs.isForbidden` itself; the reasoning, and the
  * test that pins the divergence, are in `handlers/assets/nm.ts`. It is the one
@@ -43,7 +42,7 @@ export interface StaticTarget {
  * mounted plugin cannot be traversed out of.
  *
  * Roots are tried in order, and a root that fails containment is skipped
- * rather than aborting — mirroring ImageHandler, which legitimately looks in
+ * rather than aborting: mirroring ImageHandler, which legitimately looks in
  * both the serve root and the public root.
  */
 export async function getStatic(
@@ -64,23 +63,23 @@ export async function getStatic(
     const file = fs.resolve(root, candidate.relative)
 
     // Two checks, not one: the prefix test catches a resolved path that
-    // escaped the root, and isForbidden additionally honours `.forbidden`
-    // markers. It does *not* apply the blocked globs — `Bakery.config.blocked`
+    // escaped the root, and isForbidden additionally honors `.forbidden`
+    // markers. It does *not* apply the blocked globs: `Bakery.config.blocked`
     // is matched against the request path in `router.ts` and again in
-    // `handlers/assets/static.ts`, never against a resolved file path — so a
-    // caller reaching for `getStatic` as a one-stop authorisation check is
+    // `handlers/assets/static.ts`, never against a resolved file path, so a
+    // caller reaching for `getStatic` as a one-stop authorization check is
     // getting containment and `.forbidden` only.
     //
-    // Containment stays first — nothing stats a path that escaped the root.
+    // Containment stays first: nothing stats a path that escaped the root.
     // After that the order is by cost: `isForbidden` walks every directory
     // between the file and the root, so running it before the existence check
-    // paid for a whole tree-walk on every candidate that simply is not there —
+    // paid for a whole tree-walk on every candidate that simply is not there,
     // which is most of them, since a miss here is how each root in the list,
     // and every extensionless probe, gets ruled out. All checks are pure and
     // all `continue`, so the candidate chosen is unchanged.
     //
     // One stat answers both questions. This used to be `fs.exists` (a stat)
-    // then `fs.isDir` (which is `fs.exists` plus a second stat of its own) —
+    // then `fs.isDir` (which is `fs.exists` plus a second stat of its own):
     // up to three stats per candidate at ~28us each on Bun/Windows. A failed
     // stat means "nothing servable here" and falls through to the next
     // candidate, exactly as the exists check did.

package/src/handlers/routes/api.ts

@@ -46,19 +46,19 @@ export class ApiHandler extends DynamicHandler {
     if (result !== null && result !== undefined) return result
 
     // Two different faults used to share one bare 404, and neither channel
-    // named the file — so "No response from handler" sent the developer
+    // named the file, so "No response from handler" sent the developer
     // hunting for a route that was sitting on disk the whole time.
     //
     // `null` and `undefined` are what tell them apart, and the split is exact
     // rather than incidental: `DynamicHandler.executeModule` *throws* when the
     // import fails (that is the 500 path), returns a literal `null` for
     // "module loaded, no `default`", and otherwise returns whatever the
-    // handler produced — `undefined` when it produced nothing.
+    // handler produced, `undefined` when it produced nothing.
     if (result === null) {
       // A 500, not a 404: the route resolved, the file exists, and the server
       // could not answer with it. That is a server fault, and the message says
-      // what to add. PROD still redacts it — `publicBody` replaces any 5xx
-      // body — so naming the file here discloses nothing to a client.
+      // what to add. PROD still redacts it (`publicBody` replaces any 5xx
+      // body), so naming the file here discloses nothing to a client.
       handlerLog.API_NO_DEFAULT({ file: filePath })
       return response.error(
         `API route has no export default: ${info.path}`,
@@ -88,7 +88,7 @@ export class ApiErrorHandler extends ErrorHandler {
 
   static handle(_p: string, _r: Request, error: Handler.Error.Data) {
     // `publicBody`, not `errorBody`: in production the latter is the stack of
-    // whatever threw. The full trace still reaches the log — `handleRequestError`
+    // whatever threw. The full trace still reaches the log: `handleRequestError`
     // passes the unredacted data to `config.onError` before this runs.
     return response.json.error(error.errorCode, ErrorHandler.publicBody(error))
   }

package/src/handlers/routes/html.ts

@@ -78,8 +78,8 @@ async function sharedHandler(
   // through `{{...}}` *and* through the `__PAGE_PARAMS__` script injected
   // into every page, so the raw stack was published in PROD even by a
   // template that never mentioned it. Guarded because `errorData` is
-  // `undefined` for an ordinary page — `DEFAULT_ERROR` only exists on the
-  // error handler — and the spread below tolerates that where the helper,
+  // `undefined` for an ordinary page (`DEFAULT_ERROR` only exists on the
+  // error handler), and the spread below tolerates that where the helper,
   // deliberately strict about the shape it redacts, does not.
   // Annotated because `beginPageRoute` hands back real `Handler.Error.Data`
   // where this used to read an untyped `(this as any).DEFAULT_ERROR`: the

package/src/handlers/routes/proxy.ts

@@ -63,7 +63,7 @@ export class ProxyHandler extends Handler {
 
     const resHeaders = new Headers(proxyRes.headers)
     // Bun already decompressed the body, so the upstream's content-encoding is
-    // wrong — and so is its content-length, which described the compressed size.
+    // wrong, and so is its content-length, which described the compressed size.
     resHeaders.delete('content-encoding')
     resHeaders.delete('content-length')
     return new Response(proxyRes.body, {

package/src/logger/clients.ts

@@ -1,12 +1,12 @@
 /**
  * WebSocket clients subscribed to the live log stream.
  *
- * `LiveReloadHandler` owns membership — it adds a socket on
+ * `LiveReloadHandler` owns membership: it adds a socket on
  * `subscribe_logger` and removes it on close. Consumers (the dashboard's
  * log broadcast, the analytics `activeLoggers` gauge) only read.
  *
  * This lives in core rather than a plugin deliberately: it used to be
  * defined in `plugins/analytics/core`, which made core import from a
- * plugin — a backwards edge that blocks packaging core on its own.
+ * plugin, a backwards edge that blocks packaging core on its own.
  */
 export const connectedLoggers = new Set<any>()

package/src/logger/logger.ts

@@ -46,7 +46,7 @@ export function setLogCallback(cb: (entry: LoggerEntry) => void) {
  *
  * Three call sites used to spell this as `Promise.try(() =>
  * onLogCallback?.(…)).catch(() => {})`, which allocated two promises and
- * scheduled a microtask for *every* line — including every line logged while
+ * scheduled a microtask for *every* line, including every line logged while
  * no sink was registered at all. `Try` swallows a synchronous throw and a
  * rejected promise alike (see `utils/isomorphic/try.ts`) without allocating
  * anything on the synchronous path, which is the only path a sink typed
@@ -61,7 +61,7 @@ function emit(entry: LoggerEntry): void {
 }
 
 // Hoisted: both were rebuilt on every call, and neither depends on the input.
-// The colour table is a 23-property literal and the pattern a regex literal,
+// The color table is a 23-property literal and the pattern a regex literal,
 // so a process logging steadily paid for both on every line.
 const COLORS: MapOf<string> = {
   r: '\x1b[31m', // Red
@@ -299,7 +299,7 @@ type Messages<T extends MapOf<string>> = {
 const RX_PARAM = /\{([^}]+)\}/g
 
 type ParsedMessage = {
-  /** The string this was parsed from — the cache's validity check. */
+  /** The string this was parsed from: the cache's validity check. */
   raw: string
   level: LogLevels
   template: string
@@ -332,7 +332,7 @@ export function messageLogger<T extends MapOf<string>>(
   targetMsgs: T,
 ) {
   /**
-   * One entry per *declared* key, so it is bounded by the message table — the
+   * One entry per *declared* key, so it is bounded by the message table: the
    * tables in `serve-log.ts` are literals of a dozen-odd entries each.
    * Undeclared props are deliberately left uncached: the trap fabricates a
    * message for those, and a caller reading arbitrary property names off the

package/src/logger/serve-log.ts

@@ -10,10 +10,10 @@ const serveMsgs = {
   // the one recorded after the last successful sync, so the boot-time schema
   // sync is skipped. `--sync` bypasses the skip.
   SCHEMA_SYNC_SKIP:
-    'I Schema unchanged since last sync — %yskipping schema sync%* (%c--sync%* forces it)',
+    'I Schema unchanged since last sync: %yskipping schema sync%* (%c--sync%* forces it)',
   // The skip above is precisely when drift goes unnoticed: schema.ts has not
   // changed, so no sync runs, so nothing looks at the database. Something else
-  // altered it — a hand-run ALTER, another environment pointed at the same URL,
+  // altered it: a hand-run ALTER, another environment pointed at the same URL,
   // a restore from an older dump.
   SCHEMA_DRIFT:
     'W %yDatabase no longer matches the last schema Bakery applied%*: {reason}. Run %cdb:history%* to see what was applied, or %cdb:sync --dry-run%* to see what the difference means.',
@@ -27,26 +27,32 @@ const serveMsgs = {
     'I Synced %ytsconfig.json%* paths with %yserver.config.ts%*!',
   TSCONFIG_PROJECTS_WRITTEN:
     'I Wrote %y{count}%* tsconfig project(s) to %y.cache/tsconfig/%*',
+  // One-time repair. Previous releases wired the generated projects into the
+  // app's tsconfig.json as `references`, which broke `tsc -p <app>`
+  // (TS6305/6306/6310). Named so the rewrite of a tracked file comes with a
+  // line saying why it happened.
+  TSCONFIG_REFERENCES_REMOVED:
+    'I Removed generated %yreferences%* from %ytsconfig.json%*, the %y.cache/tsconfig/%* projects are standalone, and referencing them broke %ytsc -p%*',
   // A plugin asking for a project name that is taken. Named rather than
   // silent: the symptom otherwise is one plugin's types quietly not applying,
   // discovered much later and blamed on the wrong thing.
   TSCONFIG_PROJECT_CLASH:
-    'W Plugin %y{plugin}%* wants tsconfig project %y{project}%*, which already exists — %rskipped%*',
+    'W Plugin %y{plugin}%* wants tsconfig project %y{project}%*, which already exists: %rskipped%*',
   // Degrades to "no types" rather than failing the boot: a missing declaration
   // is a worse editor experience, not a broken server.
   TSCONFIG_FILE_UNRESOLVED:
-    'W Could not resolve tsconfig files entry %y{entry}%* — %rskipped%*',
+    'W Could not resolve tsconfig files entry %y{entry}%*: %rskipped%*',
   MANUAL_RELOAD: 'I %yManual reload%* triggered from client logger!',
   CONFIG_IMPORT_ERR: 'E Failed to import %yserver.config.ts%*: %r{error}%*',
   // Multi-line on purpose: a present-but-broken config booting on defaults is
-  // the kind of failure a single scrolled-away line hides. DEV only — in PROD
+  // the kind of failure a single scrolled-away line hides. DEV only: in PROD
   // the same condition throws out of initConfig() instead of logging.
   CONFIG_BROKEN:
-    'E %rserver.config.ts is present but failed to load — booting on built-in defaults (no plugins, no hosts, default port)%*\n  file: %y{file}%*\n{error}',
+    'E %rserver.config.ts is present but failed to load: booting on built-in defaults (no plugins, no hosts, default port)%*\n  file: %y{file}%*\n{error}',
   // The banner restatement of CONFIG_BROKEN, so the warning survives console
   // scrollback and sits next to the URLs the developer actually reads.
   CONFIG_BROKEN_BANNER:
-    'W %rserver.config.ts failed to load%* %y— running on built-in defaults. See the import error above.%*',
+    'W %rserver.config.ts failed to load%* %y, running on built-in defaults. See the import error above.%*',
   WEBSOCKET_ERR: 'E WebSocket error from %y{ip}%*: %r{error}%*',
   RATE_LIMITED: 'W Rate limited: %y{ip}%*',
   // Emitted instead of RATE_LIMITED when sampling (cli/rate-limit.ts) held
@@ -57,32 +63,39 @@ const serveMsgs = {
   // limit silently 429s load tests and shared-NAT offices, so its existence
   // gets one announcement. An app-configured value prints nothing.
   RATE_LIMIT_DEFAULT:
-    'I Rate limit: %y{max}%* burst / %y{refill}%* req/s per IP (default) — set %crateLimit: false%* to disable',
+    'I Rate limit: %y{max}%* burst / %y{refill}%* req/s per IP (default). Set %crateLimit: false%* to disable',
   // Multi-worker port sharing rides on kernel-level SO_REUSEPORT load
   // balancing, which only Linux provides; elsewhere N sockets either fail to
   // bind or never receive balanced traffic.
   CLUSTER_CLAMPED:
     'W [Cluster] %y{platform}%* has no kernel-level SO_REUSEPORT load balancing (Linux-only), so %y{requested}%* workers cannot share one port. Running a single worker.',
   WORKER_RESPAWN:
-    'W [Cluster] Worker %g{id}%* exited unexpectedly — restarting in %y{delay}%*ms (consecutive failure #%y{failures}%*).',
+    'W [Cluster] Worker %g{id}%* exited unexpectedly: restarting in %y{delay}%*ms (consecutive failure #%y{failures}%*).',
   // Thread-worker only: the master should hand over the shared memory pool
   // before the worker starts serving; past the deadline the worker serves on
   // its local pool rather than deadlock.
   SHARED_POOL_TIMEOUT:
-    'W [Cluster] No shared memory pool from the master within %y{timeout}%*ms — serving on a worker-local pool; cross-worker counters and rate limits will not be shared until it arrives.',
+    'W [Cluster] No shared memory pool from the master within %y{timeout}%*ms: serving on a worker-local pool; cross-worker counters and rate limits will not be shared until it arrives.',
   // The version wipe could not empty the cache directory, so no "current"
   // marker was written and the next boot will try again. Worth a line rather
   // than silence: something is holding those files open, and a stale compiled
   // page surviving an upgrade is the failure the wipe exists to prevent.
+  // SQLite would not take WAL for this file, so it is running the DELETE
+  // journal instead. Worth one line rather than silence: on a local disk WAL
+  // is 100x faster per write and 29x on a transaction, and sessions write on
+  // the request path, so this line is the difference between "this
+  // filesystem cannot do better" and a deployment quietly paying that.
+  JOURNAL_WAL_REFUSED:
+    'W SQLite refused WAL for %y{file}%* (answered %y{answer}%*): running the %y{mode}%* journal instead. Expected on a network path; on a local disk it costs every write.',
   CACHE_WIPE_INCOMPLETE:
-    'W Cache directory could not be cleared for the version change — %y{dir}%* still contains %y{files}%*. Retrying on next start; close anything holding those files.',
+    'W Cache directory could not be cleared for the version change: %y{dir}%* still contains %y{files}%*. Retrying on next start; close anything holding those files.',
 } as const
 
 export const serveLog = messageLogger(new Logger('serve'), serveMsgs)
 
 const handlerMsgs = {
   // Emitted by `DynamicHandler.executeModule`, which every route handler goes
-  // through — an API route, a `.tsx` page and an `error-*.tsx` all land here.
+  // through: an API route, a `.tsx` page and an `error-*.tsx` all land here.
   // It used to say "API module" while printing a `.tsx` path, alongside a
   // `TSX_IMPORT_ERR` that no code ever reached.
   API_IMPORT_ERR: 'E Failed to import route module (%y{file}%*): %r{error}%*',
@@ -90,7 +103,7 @@ const handlerMsgs = {
   // default. `ApiHandler` used to answer that with a bare 404 naming nothing,
   // which reads as "your route file is missing" for a file that is right there.
   API_NO_DEFAULT:
-    'E API route has no %cexport default%* (%y{file}%*) — the module loaded but exposes no handler',
+    'E API route has no %cexport default%* (%y{file}%*): the module loaded but exposes no handler',
   // A handler ran and returned neither a value nor a Response. Still a 404 (see
   // `ApiHandler.handle`), but the log names the file rather than leaving the
   // developer to guess which route answered.
@@ -106,13 +119,13 @@ const handlerMsgs = {
   BUNDLE_SIDE_EFFECTS_REPAIRED:
     'I %y{file}%* tree-shook to an empty export list because its package declares %ysideEffects: false%*; re-bundled through a re-export shim, which keeps the code.',
   BUNDLE_EMPTY_EXPORTS:
-    'E %y{file}%* bundled to an export list with no code behind it — every name it exports is undefined, so it is rejected rather than served. The bundler reported success, and re-bundling through a re-export shim did not recover it. Import the specific module you need instead of the package root.',
+    'E %y{file}%* bundled to an export list with no code behind it: every name it exports is undefined, so it is rejected rather than served. The bundler reported success, and re-bundling through a re-export shim did not recover it. Import the specific module you need instead of the package root.',
   BUNDLE_CJS_INTEROP:
     'I Generated named exports for the CommonJS package %y{file}%*, so a named import of it works in the browser.',
   BUNDLE_CJS_PROBED:
     'I Could not read %y{file}%* export names statically, so they were probed by importing it in a short-lived child process.',
   BUNDLE_CJS_DEFAULT_ONLY:
-    'W %y{file}%* assigns %ymodule.exports%* wholesale and its members could not be read, so its browser bundle exports only %ydefault%* — a named import from it fails in the browser with "does not provide an export named …", and nothing fails here. Import the default and read the property off it, or use an ESM build.',
+    'W %y{file}%* assigns %ymodule.exports%* wholesale and its members could not be read, so its browser bundle exports only %ydefault%*: a named import from it fails in the browser with "does not provide an export named …", and nothing fails here. Import the default and read the property off it, or use an ESM build.',
 } as const
 
 export const handlerLog = messageLogger(new Logger('handlers'), handlerMsgs)
@@ -131,6 +144,7 @@ const pluginMsgs = {
   UNHANDLED_ERR: 'E Unhandled Plugin Error: %r{error}%*',
   ANALYTICS_STORE_ERR: 'E Analytics store init failed: %r{error}%*',
   DASHBOARD_BUNDLE_ERR: 'E Failed to bundle %ydashboard.js%*: %r{error}%*',
+  EXPLORER_QUERY_ERR: 'E Explorer %y{op}%* failed: %r{error}%*',
 } as const
 
 export const pluginLog = messageLogger(new Logger('plugins'), pluginMsgs)
@@ -142,7 +156,7 @@ export const errorMsg = (err: any) => err?.stack || err?.message || String(err)
  *
  * `BuildMessage` and `ResolveMessage` are the two things Bun throws for a
  * syntax error and an unresolvable import. Neither is `instanceof Error`,
- * neither carries a `stack`, and both report *zero* own enumerable keys — so
+ * neither carries a `stack`, and both report *zero* own enumerable keys, so
  * nothing that inspects a thrown value by spreading it or by `instanceof` sees
  * anything at all. `message`, `name` and `position` are the accessors that
  * actually answer.
@@ -188,7 +202,7 @@ function positionLines(position: Diagnostic['position']): string[] {
  * `Error` and useless for the diagnostics above: they have no stack, so it
  * degrades to a bare "Expected identifier but found end of file" with no file
  * and no line. This walks `position` instead, and recurses through the
- * `AggregateError.errors` array that `import()`ing a broken `.tsx` throws —
+ * `AggregateError.errors` array that `import()`ing a broken `.tsx` throws:
  * that one *is* an `Error`, but it has no stack either, so the summary line
  * ("4 errors building …") was all anyone ever saw.
  *
@@ -217,7 +231,7 @@ export function errorDetail(err: any): string {
  *
  * For the log lines whose template already names the file. Bun's own
  * `position.file` is `input.ts` whenever `transform()` was handed a source
- * string rather than a path — which is every compile this codebase does — so
+ * string rather than a path (which is every compile this codebase does), so
  * printing it beside the real path would contradict it.
  */
 export function errorWithPosition(err: any): string {

package/src/plugins/index.ts

@@ -2,7 +2,7 @@
  * The plugin-authoring surface, as one barrel.
  *
  * Every other public directory in core has an `index.ts` and `plugins/` did
- * not, so `@bakery-framework/core/plugins` pointed straight at `routes.ts` — which meant
+ * not, so `@bakery-framework/core/plugins` pointed straight at `routes.ts`, which meant
  * `definePlugin` and `ServerPlugin` were only reachable through
  * `@bakery-framework/core/plugins/types`, a second subpath for one concept. It also broke
  * under TypeScript's `paths` resolution, which maps `@bakery-framework/core/plugins` to

package/src/plugins/routes.ts

@@ -2,8 +2,8 @@
  * Declarative endpoint tables for plugins.
  *
  * The dashboard already used a `Record<path, handler>` map; analytics used a
- * hand-rolled `if (path === … && method === …)` chain. This generalises the
- * dashboard's shape — the one that was already working — so a third plugin does
+ * hand-rolled `if (path === … && method === …)` chain. This generalizes the
+ * dashboard's shape (the one that was already working), so a third plugin does
  * not arrive with a fourth style of dispatch.
  *
  * Scope is deliberately narrow: exact-match paths only, no params or wildcards.
@@ -16,7 +16,7 @@ import { response } from '../utils/http/response'
 import type { ValidResponses } from './types'
 
 /**
- * Handlers may return anything the router knows how to serialize — the
+ * Handlers may return anything the router knows how to serialize: the
  * dashboard's return `JsonResponseData` and `BunFile` as well as `Response`.
  * `ValidResponses` (= `Handler.Response`) is the framework's name for that set.
  */
@@ -27,7 +27,7 @@ export type PluginRoute = (req: Request, url: URL) => ValidResponses
  * method-qualified path (`'POST /api/_x/reset'`). A method-qualified entry wins
  * over a bare one for the same path.
  *
- * The two forms are guarded differently — see `guardFor` below. A bare key is
+ * The two forms are guarded differently. See `guardFor` below. A bare key is
  * same-origin-only; a method-qualified one gets the ordinary CSRF check.
  */
 export type PluginRouteTable = Record<string, PluginRoute>
@@ -35,7 +35,7 @@ export type PluginRouteTable = Record<string, PluginRoute>
 /**
  * What a dispatch built from `T` actually resolves to: the union of that
  * table's own handler return types, awaited, with the `undefined`/`void` cases
- * replaced by `null` — exactly what `dispatch` does at runtime with `?? null`.
+ * replaced by `null`. Exactly what `dispatch` does at runtime with `?? null`.
  *
  * Keyed on the table type rather than flattened to `ValidResponses` because
  * `ValidResponses` contains `object`, which absorbs `Response`, `Bun.BunFile`
@@ -59,7 +59,7 @@ export type PluginRouteResult<T extends PluginRouteTable> =
  * unsafe ones same-origin. `'GET /api/_x/public'` is therefore also the way to
  * declare an endpoint that *is* meant to answer cross-origin.
  *
- * A **bare** key matches every method, which means the author did not say —
+ * A **bare** key matches every method, which means the author did not say,
  * and that is exactly how the dashboard's mutating endpoints ended up
  * answering a `GET`. `checkCsrf` is no help there: it waves GET through by
  * definition, so a cross-site `<img src="/api/_dashboard/execute-action">`
@@ -76,7 +76,7 @@ function guardFor(qualified: boolean) {
 
 export function routeTable<T extends PluginRouteTable>(routes: T) {
   /**
-   * Declared as an overload — the same shape `handleRequest` uses in
+   * Declared as an overload: the same shape `handleRequest` uses in
    * `router.ts`. The signature carries the precise per-table union; the
    * implementation only ever sees the `PluginRoute` *constraint*, so on its own
    * it could infer no better than the wide `ValidResponses`.