fix(router): preserve write routing in directly served requests

Establish the database routing context once per served request, resolving
the context runner lazily at startup. Keep write state across awaits and
isolate concurrent readers.

Cover direct HTTP write tracking and isolated cold-start serving without
application preloads. Router and database suites: 1432 tests. Unit suite:
366 tests. Framework type checks and pickier lint pass.

Secure SQLite HTTP comparisons completed 76014 requests with exactly
76014 persisted logs and no errors. This is a correctness prerequisite,
not a throughput improvement claim.

Author: chrisbbreuer

storage/framework/core/router/src/stacks-router.ts

@@ -4287,6 +4287,10 @@ export function createStacksRouter(config: StacksRouterConfig = {}): StacksRoute
       // cookie was only ever seeded on API responses. See the wrapper.
       wrapHandleRequestForCsrf(bunRouter)
 
+      // Directly served requests need the same read-after-write tracking as
+      // serverResponse(), including requests that bypass the route pipeline.
+      await wrapHandleRequestForDatabaseContext(bunRouter)
+
       // After the routes and the view configuration, before the first request:
       // the one moment an application can do work once without racing a reader
       // for it. See `BootHook`.
@@ -4807,6 +4811,18 @@ let routesLoadPromise: Promise<void> | null = null
 type ContextRunner = <T>(fn: () => T) => T
 let routingContextRunner: ContextRunner | null = null
 
+const databaseContextWrappedRouters = new WeakSet<Router>()
+
+async function wrapHandleRequestForDatabaseContext(router: Router): Promise<void> {
+  if (databaseContextWrappedRouters.has(router)) return
+  const runInRoutingContext = await getRoutingContextRunner()
+  // Concurrent serve() calls can resolve the runner together.
+  if (databaseContextWrappedRouters.has(router)) return
+  const original = router.handleRequest.bind(router)
+  router.handleRequest = request => runInRoutingContext(() => original(request))
+  databaseContextWrappedRouters.add(router)
+}
+
 async function getRoutingContextRunner(): Promise<ContextRunner> {
   if (!routingContextRunner) {
     try {

storage/framework/core/router/tests/fixtures/cold-start.toml

@@ -0,0 +1,2 @@
+# Keep application preloads out of the router's cold-start import-cycle probe.
+# Leave preload absent: Bun rejects an empty preload array during startup.

storage/framework/core/router/tests/fixtures/serve-cold-start.ts

@@ -0,0 +1,15 @@
+import { createStacksRouter } from '../../src/stacks-router'
+
+const router = createStacksRouter()
+router.get('/__cold_start', () => ({ ready: true }))
+const server = await router.serve({ port: 0 })
+try {
+  const response = await fetch(`http://localhost:${server.port}/__cold_start`)
+  const body = await response.json()
+  if (response.status !== 200 || body.ready !== true)
+    throw new Error(`Unexpected cold-start response: ${response.status}`)
+  console.log('router-cold-start-ok')
+}
+finally {
+  await server.stop(true)
+}

storage/framework/core/router/tests/read-routing-context.test.ts

@@ -18,9 +18,62 @@
 
 import { describe, expect, test } from 'bun:test'
 import { contextHasWritten, markContextWrote, withRoutingContext } from '@stacksjs/database'
-import { serverResponse } from '../src/stacks-router'
+import { createStacksRouter, serverResponse } from '../src/stacks-router'
 
 describe('routing context plumbing', () => {
+  test('direct serving starts without preloading the database package', async () => {
+    const child = Bun.spawn([
+      process.execPath,
+      `--config=${import.meta.dir}/fixtures/cold-start.toml`,
+      `${import.meta.dir}/fixtures/serve-cold-start.ts`,
+    ], { stdout: 'pipe', stderr: 'pipe' })
+    const timeout = setTimeout(() => child.kill(), 10_000)
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([
+        child.exited,
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+      ])
+      expect(exitCode, stderr).toBe(0)
+      expect(stdout).toContain('router-cold-start-ok')
+    }
+    finally {
+      clearTimeout(timeout)
+      child.kill()
+      await child.exited
+    }
+  }, 15_000)
+
+  test('directly served requests track writes and isolate concurrent readers', async () => {
+    const router = createStacksRouter()
+    const writing = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    router.get('/__routing_write', async () => {
+      const before = contextHasWritten()
+      markContextWrote()
+      writing.resolve()
+      await release.promise
+      return { before, after: contextHasWritten() }
+    })
+    router.get('/__routing_read', () => ({ wrote: contextHasWritten() }))
+    const server = await router.serve({ port: 0 })
+    try {
+      const writer = fetch(`http://localhost:${server.port}/__routing_write`)
+      await writing.promise
+      const reader = await fetch(`http://localhost:${server.port}/__routing_read`)
+      expect(await reader.json()).toEqual({ wrote: false })
+      release.resolve()
+      expect(await (await writer).json()).toEqual({ before: false, after: true })
+      const later = await fetch(`http://localhost:${server.port}/__routing_read`)
+      expect(await later.json()).toEqual({ wrote: false })
+      expect(contextHasWritten()).toBe(false)
+    }
+    finally {
+      release.resolve()
+      await server.stop(true)
+    }
+  }, 15_000)
+
   test('marking a write is inert with no context established', () => {
     // Background jobs and one-shot scripts have no request boundary; they
     // must not throw, they simply get no read-your-writes guarantee.