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

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`.

package/src/plugins/types.ts

@@ -6,18 +6,20 @@ export type ValidResponses = Handler.Response
 /**
  * A TypeScript project a plugin contributes to the app.
  *
- * Written to `.cache/tsconfig/<name>.json` on every dev boot and referenced
- * from the app's root `tsconfig.json`, so the editor typechecks each file under
- * the project that owns it. Regenerated rather than committed: it is derived
- * from the plugin list and the app's config, and `.cache/` is the disposable
- * half of the two runtime directories.
+ * Written to `.cache/tsconfig/<name>.json` on every dev boot, as a standalone
+ * project invoked directly (`vue-tsc -p .cache/tsconfig/vue.json`). It is
+ * deliberately *not* referenced from the app's root `tsconfig.json`: a
+ * `references` entry to an unbuilt `noEmit` project makes `tsc -p <app>` fail
+ * (TS6305/6306/6310; see `compiler/tsconfig-sync.ts`). Regenerated rather
+ * than committed: it is derived from the plugin list and the app's config, and
+ * `.cache/` is the disposable half of the two runtime directories.
  */
 export interface PluginTsProject {
   /** File name under `.cache/tsconfig/`, and the project's identity. */
   name: string
   /** Usually one of core's three bases. Written through as-is. */
   extends: string
-  /** Globs, relative to the **app root** — the generator rewrites them. */
+  /** Globs, relative to the **app root**: the generator rewrites them. */
   include?: string[]
   exclude?: string[]
   /**
@@ -34,7 +36,7 @@ export interface PluginTsProject {
    *
    * Off by default, and that default is the correction: the generator used to
    * write those `paths` into *every* project on the reasoning that an alias is
-   * app-wide. It is not. `importMap` is a **browser** import map — the framework
+   * app-wide. It is not. `importMap` is a **browser** import map: the framework
    * serves it as `<script type="importmap">` and the browser is what resolves
    * its specifiers. An alias in the server project therefore typechecks an
    * import that only the browser can satisfy, which is the same class of bug the
@@ -47,13 +49,13 @@ export interface PluginTsProject {
    * Does code in this project run on the server?
    *
    * Declared, not inferred. The first version read `bun-types` out of the base
-   * config and treated that as the marker — true today, and an inference about
+   * config and treated that as the marker: true today, and an inference about
    * intent drawn from a detail that exists for another reason. A plugin saying
    * what its project *is* cannot drift out of step with itself.
    *
    * What it controls: the app's schema registration, so the ORM's tables are the
    * app's own rather than the permissive `any` fallback. Off for browser code on
-   * purpose — `@bakery-framework/orm` is server-only, so a `.ts` bound for the
+   * purpose: `@bakery-framework/orm` is server-only, so a `.ts` bound for the
    * browser importing `DB` should fail to typecheck rather than be helpfully
    * typed, and the package ships TypeScript source calling `Bun.*`, which a
    * client config cannot compile anyway.
@@ -63,7 +65,7 @@ export interface PluginTsProject {
 
 /** What a plugin contributes to the generated tsconfig projects. */
 export interface PluginTsConfig {
-  /** A project this plugin owns outright — Vue SFCs, for instance. */
+  /** A project this plugin owns outright: Vue SFCs, for instance. */
   project?: PluginTsProject
 }
 
@@ -77,7 +79,7 @@ export interface ServerPlugin {
    *
    * A plugin that brings its own file type or its own ambient globals needs a
    * project to typecheck them under. `@bakery-framework/plugin-vue` is the
-   * worked example — it owns `.vue` and declares `req`/`body` for SFC scope,
+   * worked example: it owns `.vue` and declares `req`/`body` for SFC scope,
    * globals core deliberately does not provide.
    */
   tsconfig?: PluginTsConfig

package/src/router.ts

@@ -27,11 +27,11 @@ import { parsedUrl } from './utils/http/url'
  * The origin check lives here rather than in each `canHandle` on purpose:
  * every socket a plugin or an app registers inherits it, instead of every
  * author having to remember. `/_analytics_ws` was the only handler that got it
- * right on its own, and it did so by authenticating — `/_livereload` had
+ * right on its own, and it did so by authenticating: `/_livereload` had
  * nothing, and `WebSocketHandler.canHandle` returns `true` by default, so the
  * base class was handing out sockets to anyone who asked.
  *
- * Returning `false` (rather than a 403) keeps the published signature — the
+ * Returning `false` (rather than a 403) keeps the published signature: the
  * caller below turns a refusal into `400 WebSocket Upgrade Failed`, which is
  * also what an unclaimed path gets. The reason reaches the log; the client is
  * told nothing it did not already know.
@@ -65,10 +65,10 @@ export async function upgradeWebsocket(
  * Whether the deny-list applies to whatever this handler is about to answer
  * with. `Bakery.config.blocked` exists to stop files on disk being served, so
  * handlers that read the request path as a route *name* opt out by declaring
- * `servesFiles = false` — `ApiHandler`, `ProxyHandler`, `MiddlewareHandler`.
+ * `servesFiles = false`: `ApiHandler`, `ProxyHandler`, `MiddlewareHandler`.
  *
  * Deny by default, and the direction matters. Naming only the obvious file
- * servers — Static, Public, NM — would have left `/schema.ts` and
+ * servers (Static, Public, NM) would have left `/schema.ts` and
  * `/server.config.ts` reachable through `TSHandler`, which compiles a source
  * file and serves the result. Anything that does not opt out, including a
  * plugin's handler, keeps the check.
@@ -94,7 +94,7 @@ export async function handleRequest(req: Request) {
   // One read of the config getter, not three: `Bakery.serveRoot` walks
   // `hostStore.getStore()?.config ?? getConfig()` on every access, and the
   // blocked-glob check below used to pay the same walk again. And no
-  // `fs.resolve` around the target — `isForbidden` normalises both arguments
+  // `fs.resolve` around the target: `isForbidden` normalizes both arguments
   // itself, so that was a second full path resolution of the same string on
   // every request.
   const config = Bakery.config
@@ -102,7 +102,7 @@ export async function handleRequest(req: Request) {
   // Before anything else, including the forbidden-path check: a preflight names
   // the route it is asking about in a *header*, not the path, so running it
   // through routing would answer a question nobody asked. The browser sends no
-  // credentials with it either, which is why it cannot be authorised.
+  // credentials with it either, which is why it cannot be authorized.
   //
   // Only when `cors` is configured. Absent, this is not reached at all and the
   // browser's own default applies.
@@ -136,7 +136,7 @@ export async function handleRequest(req: Request) {
   const handler = await Bakery.handlers.fetch.resolve(path, req)
   if (!handler) return new Response('Not Found', { status: 404 })
 
-  // `matchBlockedCached` memoises the verdict on the request store, so the
+  // `matchBlockedCached` memoizes the verdict on the request store, so the
   // re-check `StaticHandler.handle` keeps for its direct callers costs a map
   // hit instead of a second pair of glob matches.
   if (servesFiles(handler) && matchBlockedCached(config.blocked, path)) {
@@ -236,14 +236,14 @@ export const serveWebSocket: Bun.WebSocketHandler<any> = {
  * Make an error page answer with the error's status.
  *
  * The HTML and TSX error handlers end in `injectIfHtml`, which builds its
- * Response without one — so an app with `src/error-404.html` served its 404
+ * Response without one, so an app with `src/error-404.html` served its 404
  * page as `200 OK` and every crawler, cache and monitor believed it. Applied
  * here rather than inside `injectIfHtml` on purpose: the only status signal
  * available down there is `params`, which for a GET is the query string, and
  * `?errorCode=500` is not something a client gets to decide.
  *
  * A `JsonResponseData` (the `/api/` arm) carries its own `.status` that
- * `processResponse` reads, and a BunFile has no status at all — both pass
+ * `processResponse` reads, and a BunFile has no status at all: both pass
  * through untouched.
  */
 function applyErrorStatus(
@@ -277,7 +277,7 @@ export async function handleRequestError(
 
   // Wrapped for the same reason the registry call below it is: this is app
   // code. An `onError` that throws used to escape `Try.return`'s fallback in
-  // the caller — a fallback that itself rejects is not a fallback — so the one
+  // the caller (a fallback that itself rejects is not a fallback), so the one
   // hook whose job is to handle failure took the app's error page down with
   // it and the client got Bun's raw 500 instead.
   const [onErrorFailed, configError] = await Try.catch(() =>
@@ -353,8 +353,8 @@ export async function processResponse(
   // (e.g. an auth cookie from a login route) that must not be overwritten.
   sess && resp.headers.append('Set-Cookie', sess)
 
-  // Every response funnels through here — pages, API JSON, static files, error
-  // pages — so this is the one place that cannot miss one. Applied before ETag
+  // Every response funnels through here (pages, API JSON, static files, error
+  // pages), so this is the one place that cannot miss one. Applied before ETag
   // so the negotiated `Vary` sees the `Origin` entry and merges with it rather
   // than either overwriting the other.
   const cors = Bakery.config.cors

package/src/session.ts

@@ -7,7 +7,7 @@ import { DEFAULT_SESSION_PERSIST, DEFAULT_SESSION_TTL } from './utils/constants'
 /**
  * Keys under this prefix are framework-internal privilege markers. They share
  * the same bag as application data, so anything that writes a caller-supplied
- * key must refuse this prefix — otherwise a preferences endpoint (or the
+ * key must refuse this prefix: otherwise a preferences endpoint (or the
  * dashboard's own session editor) becomes a privilege-escalation primitive.
  */
 export const RESERVED_SESSION_PREFIX = '__bakery.'
@@ -17,7 +17,7 @@ export function isReservedSessionKey(key: string): boolean {
 }
 
 /**
- * Clock seam — the cookie half-life bookkeeping is time-based, and its tests
+ * Clock seam: the cookie half-life bookkeeping is time-based, and its tests
  * inject a clock instead of sleeping (see `__setTestDb` / `__setTestConfig`
  * for the pattern). Only the cookie-reissue math reads this; `createdAt` and
  * TTL expiry keep `Date.now()`.
@@ -47,7 +47,7 @@ export function newSessionId(): string {
  * The cache key for a session id under the current host.
  *
  * There is one `TieredCache('sessions')` for the whole process, and until this
- * existed every id went into it unqualified — so under a multi-tenant `hosts`
+ * existed every id went into it unqualified, so under a multi-tenant `hosts`
  * config one tenant's dashboard listed, read and deleted every other tenant's
  * sessions. `hostKey()` is the guard the five other per-tenant caches already
  * use; sessions were the one that never got it.
@@ -102,6 +102,19 @@ export class Session<
     return Session.cache.count
   }
 
+  /**
+   * Attach the session cookie to a response built outside the pipeline.
+   *
+   * **Takes the `Request`, and that is not incidental.** `getCookie` reads the
+   * session through `hasDeferredValue(req, 'session')`, which looks for a
+   * symbol the router installs, so the value has to come from the real
+   * request. There used to be an instance form, `session.bind(res)`, that
+   * called this with `{ session: this }`: a fake carrying no symbol, so the
+   * check failed, `getCookie` returned an empty string, and the cookie was
+   * never appended. It was a documented method that could not work, and it is
+   * gone rather than repaired: the session alone does not know whether the
+   * request it belongs to issued a cookie this turn.
+   */
   public static bind(req: Request, response?: Response) {
     if (!response) return response
 
@@ -116,7 +129,7 @@ export class Session<
     const session = req.session
 
     // Issue only when the session actually changed, or when the read path
-    // flagged a half-life refresh (see `markAccessed`) — not on every read.
+    // flagged a half-life refresh (see `markAccessed`), not on every read.
     // A per-request Set-Cookie made every session-carrying response unique,
     // defeating If-None-Match, and dirtied merely-read sessions into the
     // flush timer's write batch.
@@ -138,7 +151,7 @@ export class Session<
       ? Math.floor(DEFAULT_SESSION_PERSIST / 1000)
       : Math.floor(DEFAULT_SESSION_TTL / 1000)
 
-    // Only believe x-forwarded-proto behind a trusted proxy — the same rule
+    // Only believe x-forwarded-proto behind a trusted proxy: the same rule
     // getHostname and getClientIp already apply. In production default to
     // Secure, so a terminator that omits the header can't downgrade the cookie.
     const trustProxy = Bakery.config.trustProxy
@@ -178,7 +191,7 @@ export class Session<
     session.rawData = { ...metadata.data }
     session.data = session.initProxy()
     // Rows written before the field existed revive as 0 = "unknown", which
-    // `markAccessed` reads as long past half-life — at worst one extra
+    // `markAccessed` reads as long past half-life, at worst one extra
     // reissue, never a cookie that silently expires under an active user.
     session.cookieIssuedAt = metadata.cookieIssuedAt ?? 0
     return session
@@ -209,7 +222,7 @@ export class Session<
         if (existing.isExpired()) {
           Session.cache.delete(sessionKey(sessionId))
         } else {
-          // Accessed, not modified — see `markAccessed`. `touch()` here made
+          // Accessed, not modified. See `markAccessed`. `touch()` here made
           // every session read count as a write.
           existing.markAccessed()
           return existing
@@ -227,7 +240,7 @@ export class Session<
 
   /**
    * Epoch ms when `getCookie` last emitted `Set-Cookie` for this id; 0 means
-   * never (or unknown — a row written before the field existed). Persisted
+   * never (or unknown: a row written before the field existed). Persisted
    * through `toJSON`, so it only costs a write when a write is already
    * happening; while the instance lives in the memory tier it carries across
    * requests for free.
@@ -236,7 +249,7 @@ export class Session<
 
   /**
    * Set by `markAccessed` when the cookie has crossed half its Max-Age;
-   * cleared when `getCookie` issues. Deliberately not persisted — it is
+   * cleared when `getCookie` issues. Deliberately not persisted: it is
    * per-instance request bookkeeping, and losing it costs nothing (the next
    * read recomputes it from `cookieIssuedAt`).
    */
@@ -277,7 +290,7 @@ export class Session<
    * Force the session to count as modified: stored on the next flush and its
    * cookie re-issued. This is the published "force a cookie refresh" surface
    * (docs/guides/sessions.md) and keeps its dirty semantics. It is *not* the
-   * read path — `Session.from` uses `markAccessed`, which slides expiry
+   * read path: `Session.from` uses `markAccessed`, which slides expiry
    * without paying write costs.
    */
   public touch(): this {
@@ -286,18 +299,18 @@ export class Session<
   }
 
   /**
-   * The read-path bump — what `Session.from` does instead of `touch()`.
+   * The read-path bump, what `Session.from` does instead of `touch()`.
    * Reading a session must not dirty it: that made every read-only request
    * pay a JSON.stringify + synchronous SQLite write on the next flush and
    * re-issue Set-Cookie, which defeated If-None-Match caching.
    *
    * Liveness needs no work here: the `Session.cache.get` in `from` has
    * already re-stamped the memory tier's accessedAt. What this method owns is
-   * sliding cookie expiration — once more than half the cookie's Max-Age has
+   * sliding cookie expiration: once more than half the cookie's Max-Age has
    * elapsed since it was last issued, flag a reissue. `getCookie` then emits
    * the cookie *and* re-persists the session, which renews the DB row's
    * accessedAt at a cadence of at most maxAge/2 against the pruner's cutoff
-   * of maxAge — so active sessions never age out server-side either.
+   * of maxAge, so active sessions never age out server-side either.
    */
   private markAccessed(): void {
     const maxAgeMs = this.hasPersistedKeys()
@@ -350,10 +363,10 @@ export class Session<
    *
    * This is the missing anti-fixation primitive. `reset()` clears data but
    * keeps the id, so an app that does `req.session.set('userId', …)` on login
-   * finishes authentication on the *same* id the visitor arrived with —
+   * finishes authentication on the *same* id the visitor arrived with,
    * including one an attacker planted. Call it at the privilege boundary:
    *
-   * ```ts no-check — illustrative call site, not a compiled example
+   * ```ts no-check: illustrative call site, not a compiled example
    * req.session.regenerate().set('userId', user.id, true)
    * ```
    *
@@ -362,7 +375,7 @@ export class Session<
    * the same object `req.session` already holds, so the rest of the request
    * sees the new id.
    *
-   * `createdAt` is deliberately preserved — the session continues, only its
+   * `createdAt` is deliberately preserved: the session continues, only its
    * bearer token is replaced.
    */
   public regenerate(): this {
@@ -423,10 +436,6 @@ export class Session<
     return this
   }
 
-  public bind(response?: Response) {
-    return Session.bind({ session: this } as any, response)
-  }
-
   public destroy(): void {
     Session.delete(this.id)
   }
@@ -454,7 +463,7 @@ export class Session<
 
   /**
    * Every enumeration below filters to the current host and yields the bare
-   * session id, not the cache key — so `Session.keys()` still returns ids the
+   * session id, not the cache key, so `Session.keys()` still returns ids the
    * dashboard can hand back to `Session.get` / `Session.delete`.
    */
   static *entries(): IterableIterator<[string, Session<any>]> {
@@ -487,7 +496,7 @@ export class Session<
     // The check is on `hosts` and not on the scope, deliberately: `hostKey`
     // collapses to '' in the unconfigured case too, so the scope alone cannot
     // tell the two situations apart. This method used to compute one anyway and
-    // never read it — scoping lives in `Session.entries()`, which the slow path
+    // never read it: scoping lives in `Session.entries()`, which the slow path
     // below goes through.
     const hosts = Bakery.config.hosts
     if (!hosts || Object.keys(hosts).length === 0) {
@@ -495,7 +504,7 @@ export class Session<
     }
 
     // Scoped path: `TieredCache.search` pages in SQL across the whole table,
-    // which is every tenant's sessions, and it has no key-prefix predicate — so
+    // which is every tenant's sessions, and it has no key-prefix predicate, so
     // the filter has to happen before paging, in JS. Bounded by the session
     // table, which the pruner holds down to live sessions.
     const needle = options.search?.trim().toLowerCase() || ''
@@ -548,6 +557,15 @@ const sessionPruneTimer = setInterval(
   1000 * 60 * 15, // prune every 15 minutes
 )
 
+// Unref'd, like the two flush timers in `cache/`. A 15-minute prune is not a
+// reason a process cannot exit, and this one is module-level: importing
+// `session.ts` (which `core/index` does) held the event loop open for the
+// life of any process that touched core. The CLI never saw it because every
+// one of its paths ends in `process.exit`; a script, an embedder or a bare
+// `bun -e` that imported the barrel printed its answer and then hung.
+// `onShutdown` still clears it, which is what matters for an orderly stop.
+sessionPruneTimer.unref?.()
+
 Bakery.onShutdown(() => {
   clearInterval(sessionPruneTimer)
 })

package/src/shared.d.ts

@@ -5,7 +5,7 @@ import type { MapOf } from './types'
  *
  * These used to be declared twice, verbatim, in `global.d.ts` and
  * `client/globals.d.ts`. Nothing caught it: `skipLibCheck: true` suppresses
- * errors *inside* .d.ts files — including this project's own — so four TS2300
+ * errors *inside* .d.ts files (including this project's own), so four TS2300
  * duplicate-identifier errors sat there invisibly, and every tsconfig excluded
  * `src/client/**` on top of that.
  *
@@ -16,7 +16,7 @@ import type { MapOf } from './types'
  * declared in two ambient files again.
  *
  * `MapOf` and `Wrapped` have since moved out of the global scope entirely,
- * into `types.d.ts` — their names are generic enough to collide with a
+ * into `types.d.ts`: their names are generic enough to collide with a
  * consuming app's own. What stays global here is framework-specific enough
  * not to, and is needed by browser globals that are bound at runtime rather
  * than imported.
@@ -27,12 +27,12 @@ import type { MapOf } from './types'
 declare global {
   /**
    * Bound by `client/utils.ts` in the browser and `core/init.ts` on the
-   * server — the same isomorphic implementation either side, so code moving
+   * server: the same isomorphic implementation either side, so code moving
    * between an SFC browser script and a server block keeps the name.
    */
   var randomId: typeof import('./utils/isomorphic/misc').randomId
 
-  /** The one JSON envelope — see convention 7. */
+  /** The one JSON envelope. See convention 7. */
   type JsonResponse<T = any> = {
     time: number
     status: number
@@ -52,7 +52,7 @@ declare global {
     (value: any, type: 'undefined'): value is undefined
     // `Function` is the type being narrowed to, and there is no narrower
     // spelling of "callable" a predicate can promise. `noBannedTypes` is off
-    // repo-wide, so this needs no suppression — see MONOREPO.md for why.
+    // repo-wide, so this needs no suppression. See MONOREPO.md for why.
     (value: any, type: 'function'): value is Function
     (value: any, type?: string): boolean
     string(value: any): value is string