@abide/abide 0.48.0 → 0.50.0

package/src/lib/server/rpc/types/RpcRegistryEntry.ts

@@ -1,13 +1,14 @@
-import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { ErrorJsonSchemas } from '../../../shared/types/ErrorJsonSchemas.ts'
 import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
 import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
 
 /*
 Per-rpc registry record on the server side. MCP and CLI enumerate this
-to discover which RPCs are advertised (clients flags) and what shapes
-they expect/return. The schemas and resolved clients stay off the public
-RemoteFunction shape so the browser-side proxy doesn't need to carry
-server-only state.
+to discover what shapes an rpc expects/returns. The schemas stay off the
+public RemoteFunction shape so the browser-side proxy doesn't need to carry
+server-only state; the resolved `clients` and `crossOrigin` ride on
+`entry.remote` (ADR-0020 sweep finding #4 — no duplicate fields), so readers
+reach them via `entry.remote.clients` / `entry.remote.crossOrigin`.
 
 `inputSchema` validates the argument bag and feeds the MCP tool
 `inputSchema` / OpenAPI parameters; `outputSchema` describes the success
@@ -23,13 +24,27 @@ multipart body advertises the file parts generically as binary.
 export type RpcRegistryEntry = {
     remote: RemoteFunction<unknown, unknown>
     inputSchema: StandardSchemaV1 | undefined
+    /* The handler's input args projected to JSON Schema at build time (ADR-0030 input side) — the
+       input surface's fallback when no `inputSchema` VALIDATOR is declared, mirroring how
+       `outputJsonSchema` backs the output surface. Already JSON Schema (not a validator), so surfaces
+       use it verbatim; `inputSchema`, when present, overrides it. It also makes the endpoint
+       advertisable (MCP/CLI) — the same role a declared `inputSchema` plays — but purely as a SHAPE
+       description: it is never run as runtime validation, so it can't produce a 422. */
+    inputJsonSchema: Record<string, unknown> | undefined
     outputSchema: StandardSchemaV1 | undefined
+    /* The handler's return type projected to JSON Schema at build time (ADR-0030 D2) — the output
+       surface's fallback when no `outputSchema` VALIDATOR is declared. Already JSON Schema (not a
+       validator), so surfaces use it verbatim; `outputSchema`, when present, overrides it. */
+    outputJsonSchema: Record<string, unknown> | undefined
+    /* The handler's typed-error branches projected to a status-keyed JSON-Schema map at build time
+       (ADR-0030) — each `error.typed(...)` return branch's status + `data` payload. Feeds the OpenAPI
+       `responses[status]` entries alongside the 200; undefined when the handler declares no typed
+       errors or the build couldn't resolve them, so the surface omits the error responses. */
+    errorJsonSchemas: ErrorJsonSchemas | undefined
     filesSchema: StandardSchemaV1 | undefined
-    clients: ClientFlags
     /* The rpc's declared opts, recorded so introspection (inspector) can report
-       the deadline/body-cap/CSRF-exemption a handler runs under. Undefined = the
-       framework default (no deadline, Bun's server-wide body ceiling, gated). */
+       the deadline/body-cap a handler runs under. Undefined = the framework default
+       (no deadline, Bun's server-wide body ceiling). */
     timeout: number | undefined
     maxBodySize: number | undefined
-    crossOrigin: boolean | undefined
 }

package/src/lib/server/rpc/validationError.ts

@@ -1,7 +1,7 @@
+import { fieldErrorsFromIssues } from '../../shared/fieldErrorsFromIssues.ts'
 import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
 import type { ValidationErrorData } from '../../shared/types/ValidationErrorData.ts'
 import { typedErrorResponse } from '../runtime/typedErrorResponse.ts'
-import { fieldErrorsFromIssues } from './fieldErrorsFromIssues.ts'
 
 /*
 The framework-reserved `validation` typed error a 422 carries: the raw Standard

package/src/lib/server/runtime/DEV_RELOAD_CLIENT_SCRIPT.ts

@@ -21,11 +21,9 @@ slept still reloads it. The initial connect runs even when the page loads
 hidden (the baseline must be the serving worker's stamp, captured before a swap
 can replace it) and releases itself once that first event lands.
 */
-import { DEV_HOT_PREFIX } from '../../shared/DEV_HOT_PREFIX.ts'
 import { DEV_RELOAD_PATH } from '../../shared/DEV_RELOAD_PATH.ts'
 
 export const DEV_RELOAD_CLIENT_SCRIPT = `<script>
-window.__abideDev = true;
 ;(() => {
   let stamp
   let source
@@ -48,18 +46,6 @@ window.__abideDev = true;
       }
     }
   }
-  function swapComponents(next, prev) {
-    const components = next.components || {}
-    const before = prev.components || {}
-    for (const id in components) {
-      if (components[id] !== before[id]) {
-        // The hot module sources its runtime from window.__abide and self-invokes
-        // hotReplace; a load/compile failure or a component with no live instance
-        // falls back to a reload.
-        import('${DEV_HOT_PREFIX}' + id + '?v=' + components[id]).catch(() => location.reload())
-      }
-    }
-  }
   function connect() {
     if (source) {
       return
@@ -84,7 +70,6 @@ window.__abideDev = true;
       if (next.cssHref && next.cssHref !== stamp.cssHref) {
         swapCss(next.cssHref)
       }
-      swapComponents(next, stamp)
       stamp = next
     }
     source.onerror = () => {

package/src/lib/server/runtime/buildCacheSnapshot.ts

@@ -18,20 +18,20 @@ function preview(value: unknown): string | undefined {
     }
 }
 
-/* The entry's armed swr policy as a label, if it declared one. A bare `swr: true`
-   has no window, so it labels as plain `swr`. */
+/* The entry's armed refetch (stale-while-revalidate) policy as a label, if it declared
+   one. A windowless policy refetches immediately, so it labels as plain `refetch`. */
 function policyLabel(entry: CacheEntry): string | undefined {
     const policy = entry.invalidation
     if (!policy) {
         return undefined
     }
     if (policy.debounce !== undefined) {
-        return `swr debounce ${policy.debounce}ms`
+        return `refetch debounce ${policy.debounce}ms`
     }
     if (policy.throttle !== undefined) {
-        return `swr throttle ${policy.throttle}ms`
+        return `refetch throttle ${policy.throttle}ms`
     }
-    return 'swr'
+    return 'refetch'
 }
 
 function projectEntry(entry: CacheEntry, now: number): InspectorCacheEntry {
@@ -48,10 +48,11 @@ function projectEntry(entry: CacheEntry, now: number): InspectorCacheEntry {
 }
 
 /*
-Snapshots the process-level cache store (the persistent one `cache(fn, { shared:
-true, ttl: Infinity })` writes to) for the inspector. Read at call time, so it
-reflects the store as it stands; request-scoped stores are deliberately
-excluded — they're ephemeral and already visible as per-request cache tallies.
+Snapshots the process-level cache store (the persistent one an endpoint declaring
+`cache: { shared: true, ttl }` — or a producer `cache(fn, args, { shared: true, ttl })`
+— writes to) for the inspector. Read at call time, so it reflects the store as it
+stands; request-scoped stores are deliberately excluded — they're ephemeral and
+already visible as per-request cache tallies.
 */
 export function buildCacheSnapshot(): InspectorCacheSnapshot {
     const now = Date.now()

package/src/lib/server/runtime/buildInspectorSurface.ts

@@ -1,5 +1,5 @@
-import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
 import { promptRegistry } from '../prompts/promptRegistry.ts'
+import { resolveInputJsonSchema, resolveOutputJsonSchema } from '../rpc/resolveRpcJsonSchema.ts'
 import { rpcRegistry } from '../rpc/rpcRegistry.ts'
 import { socketOperations } from '../sockets/socketOperations.ts'
 import { socketRegistry } from '../sockets/socketRegistry.ts'
@@ -18,12 +18,14 @@ export function buildInspectorSurface(): InspectorSurface {
         url: entry.remote.url,
         method: entry.remote.method,
         clients: { ...entry.remote.clients },
-        inputSchema: entry.inputSchema ? jsonSchemaForSchema(entry.inputSchema) : undefined,
-        outputSchema: entry.outputSchema ? jsonSchemaForSchema(entry.outputSchema) : undefined,
+        // The declared inputSchema VALIDATOR wins; else the build-projected input-type schema
+        // (ADR-0030 input side); with neither the rpc advertises no input shape, as before.
+        inputSchema: resolveInputJsonSchema(entry),
+        outputSchema: resolveOutputJsonSchema(entry),
         files: entry.filesSchema !== undefined,
         timeout: entry.timeout,
         maxBodySize: entry.maxBodySize,
-        crossOrigin: entry.crossOrigin,
+        crossOrigin: entry.remote.crossOrigin,
     }))
     const sockets = Array.from(socketRegistry.values()).map((entry) => ({
         name: entry.socket.name,

package/src/lib/server/runtime/buildOpenApiSpec.ts

@@ -1,7 +1,10 @@
 import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
 import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import type { ErrorJsonSchemas } from '../../shared/types/ErrorJsonSchemas.ts'
+import { resolveInputJsonSchema, resolveOutputJsonSchema } from '../rpc/resolveRpcJsonSchema.ts'
 import { rpcRegistry } from '../rpc/rpcRegistry.ts'
+import { STATUS_TEXT } from './STATUS_TEXT.ts'
 
 /*
 Turns a rpc's resolved JSON Schema into OpenAPI query parameters — one
@@ -43,6 +46,34 @@ function multipartBodySchema(textSchema: Record<string, unknown>): Record<string
     return schema
 }
 
+/*
+Adds one `responses[status]` entry per typed-error branch (ADR-0030) — its description is the
+status's standard reason phrase, and its `application/json` content is the error's projected `data`
+schema (omitted for a bare `{}`, a nullary error with no payload). An already-present status (the
+200, or any explicit response) is left untouched, so the success body and validation responses win a
+collision. A no-op when the handler declared no typed errors (`errorJsonSchemas` undefined).
+*/
+function mergeErrorResponses(
+    responses: Record<string, unknown>,
+    errorJsonSchemas: ErrorJsonSchemas | undefined,
+): void {
+    if (errorJsonSchemas === undefined) {
+        return
+    }
+    for (const [status, schema] of Object.entries(errorJsonSchemas)) {
+        if (responses[status] !== undefined) {
+            continue
+        }
+        const response: Record<string, unknown> = {
+            description: STATUS_TEXT[Number(status)] ?? 'Error',
+        }
+        if (Object.keys(schema).length > 0) {
+            response.content = { 'application/json': { schema } }
+        }
+        responses[status] = response
+    }
+}
+
 /*
 Builds an OpenAPI 3.1 document from the rpc registry — the HTTP surface
 every rpc exposes regardless of which non-browser clients it advertises.
@@ -58,25 +89,38 @@ export function buildOpenApiSpec(info: {
     for (const entry of rpcRegistry.values()) {
         const url = entry.remote.url
         const method = entry.remote.method
-        const jsonSchema = jsonSchemaForSchema(entry.inputSchema)
+        /*
+        Describe the parameters/request body from the `inputSchema` VALIDATOR when declared, else from
+        the handler's input parameter type projected to JSON Schema at build time (ADR-0030 input side —
+        `entry.inputJsonSchema`); otherwise the opaque fallback. The validator overrides the projection
+        (a runtime narrowing the type can't express), mirroring the 200-body output path below.
+        */
+        const jsonSchema = resolveInputJsonSchema(entry) ?? jsonSchemaForSchema(undefined)
         const description = jsonSchema.description as string | undefined
         /*
-        When the rpc declares an `outputSchema`, describe the 200 body
-        with it so external tooling sees the real return shape; otherwise
-        fall back to a bare OK.
+        Describe the 200 body from the `outputSchema` VALIDATOR when declared, else from the handler
+        return type projected to JSON Schema at build time (ADR-0030 D2 — `entry.outputJsonSchema`);
+        otherwise fall back to a bare OK. The validator overrides the projection (a runtime narrowing
+        the type can't express).
         */
         const okResponse: Record<string, unknown> = { description: 'OK' }
-        if (entry.outputSchema) {
-            okResponse.content = {
-                'application/json': {
-                    schema: jsonSchemaForSchema(entry.outputSchema),
-                },
-            }
+        const outputSchema = resolveOutputJsonSchema(entry)
+        if (outputSchema) {
+            okResponse.content = { 'application/json': { schema: outputSchema } }
         }
+        /*
+        Merge the handler's typed-error branches (ADR-0030 — `entry.errorJsonSchemas`, a status-keyed
+        data-schema map baked from the `error.typed(...)` return branches) into the responses. Each
+        status gets a `responses[status]` entry describing the error's data payload; an existing
+        response (the 200, or a future explicit entry) is never clobbered. So the 200 success body and
+        every typed error's status + payload are documented from the one handler return type.
+        */
+        const responses: Record<string, unknown> = { '200': okResponse }
+        mergeErrorResponses(responses, entry.errorJsonSchemas)
         const operation: Record<string, unknown> = {
             operationId: commandNameForUrl(url),
             ...(description ? { description } : {}),
-            responses: { '200': okResponse },
+            responses,
         }
         if (carriesBodyArgs(method)) {
             operation.requestBody = entry.filesSchema

package/src/lib/server/runtime/buildPreloadManifest.ts

@@ -18,7 +18,7 @@ const ROUTE_CHUNK = /"(\/[^"]*)"\s*:\s*\(\)\s*=>\s*import\("\.\/((?:page|layout)
 /* Reads a `_app` chunk's source by filename — gunzipped from the embedded asset map
    (standalone compile) or off disk (dev + `abide start`). Undefined on a miss. */
 function chunkReader(
-    distDir: string,
+    appDir: string,
     assets?: Assets,
 ): (name: string) => Promise<string | undefined> {
     if (assets) {
@@ -28,23 +28,25 @@ function chunkReader(
         }
     }
     return async (name) => {
-        const file = Bun.file(`${distDir}/_app/${name}`)
+        const file = Bun.file(`${appDir}/${name}`)
         return (await file.exists()) ? file.text() : undefined
     }
 }
 
-/* The hashed client entry filename (`client-<hash>.js`), from the asset map or disk. */
-async function findEntry(distDir: string, assets?: Assets): Promise<string | undefined> {
+/* The hashed client entry filename (`client-<hash>.js`), from the asset map or disk.
+   Each build's `appDir` holds exactly one entry (production `_app`, or a dev
+   generation dir), so `.find` is unambiguous. */
+async function findEntry(appDir: string, assets?: Assets): Promise<string | undefined> {
     const isEntry = (name: string): boolean => /^client-[a-z0-9]+\.js$/i.test(name)
     if (assets) {
         const key = Object.keys(assets).find((path) => isEntry(path.replace('/_app/', '')))
         return key?.replace('/_app/', '')
     }
-    if (!existsSync(`${distDir}/_app`)) {
+    if (!existsSync(appDir)) {
         return undefined
     }
     const names = await Array.fromAsync(
-        new Glob('client-*.js').scan({ cwd: `${distDir}/_app`, onlyFiles: true }),
+        new Glob('client-*.js').scan({ cwd: appDir, onlyFiles: true }),
     )
     return names.find(isEntry)
 }
@@ -64,14 +66,14 @@ stream-close instead of waterfalling after it. Returns an empty map when the bun
 absent or unparseable, so rendering degrades to the entry-only preload.
 */
 export async function buildPreloadManifest({
-    distDir,
+    appDir,
     assets,
 }: {
-    distDir: string
+    appDir: string
     assets?: Assets
 }): Promise<Record<string, string[]>> {
-    const read = chunkReader(distDir, assets)
-    const entryName = await findEntry(distDir, assets)
+    const read = chunkReader(appDir, assets)
+    const entryName = await findEntry(appDir, assets)
     const entrySource = entryName ? await read(entryName) : undefined
     if (entryName === undefined || entrySource === undefined) {
         return {}

package/src/lib/server/runtime/createAppAssetServer.ts

@@ -1,11 +1,10 @@
-import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
-import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
 import { acceptsGzip } from './acceptsGzip.ts'
 import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { globToPathSet } from './globToPathSet.ts'
 import { respondWithEmbeddedAsset } from './respondWithEmbeddedAsset.ts'
+import { textResponse } from './textResponse.ts'
 import type { Assets } from './types/Assets.ts'
 
 /*
@@ -24,23 +23,29 @@ Unlike the public server this answers every `/_app/` request itself (404 on
 a miss — nothing falls through past the build tree). The path-traversal
 guard inspects the raw request URL because the WHATWG parser normalizes
 encoded `..` segments away before `url.pathname` is visible.
+
+`appDir` is the physical directory the `/_app/*` URLs map onto: `dist/_app` for
+a production build, or — under `abide dev` — the generation dir this worker was
+spawned on (`ABIDE_APP_DIR`). The URL space stays `/_app/*` either way; only the
+disk location this worker reads from moves, so a rebuild's new worker reads a new
+dir while this one keeps serving its own, immutable for its lifetime.
 */
 export async function createAppAssetServer({
-    distDir,
+    appDir,
     assets,
 }: {
-    distDir: string
+    appDir: string
     assets?: Assets
 }): Promise<(req: Request, url: URL) => Promise<Response>> {
     // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
     const headersForAsset = createAssetHeaderCache(cacheControlForAsset)
-    /* Boot snapshot of every disk `_app` path, mirroring createPublicAssetServer: the
-       header cache keys on (request-controlled) pathnames, so building bundles for junk
-       `/_app/*` probes would grow it without bound. A rebuild restarts the server (same
-       restart `bun --watch` triggers on a code change), re-snapshotting. */
+    /* Boot snapshot of every disk chunk path (keyed by its `/_app/*` URL), mirroring
+       createPublicAssetServer: the header cache keys on (request-controlled) pathnames,
+       so building bundles for junk `/_app/*` probes would grow it without bound. A
+       rebuild spawns a fresh worker (against a fresh generation dir), re-snapshotting. */
     const diskPaths = assets
         ? new Set<string>()
-        : await globToPathSet(`${distDir}/_app`, '**/*', (file) => `/_app/${file}`)
+        : await globToPathSet(appDir, '**/*', (file) => `/_app/${file}`)
     /* Derive the precompressed `.gz` sibling set from the single tree scan (it already
        includes the `.gz` files) — a gzip-capable client gets those bytes without
        on-the-fly compression. Keyed by the base path (the `.gz` suffix stripped). */
@@ -49,11 +54,7 @@ export async function createAppAssetServer({
     )
 
     // Fresh 404 per call — a Response body is single-use, so it can't be hoisted to a const.
-    const notFound = (): Response =>
-        new Response('Not Found', {
-            status: 404,
-            headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-        })
+    const notFound = (): Response => textResponse(404)
 
     return async function serveAppAsset(req, url) {
         if (containsTraversal(req.url)) {
@@ -88,7 +89,9 @@ export async function createAppAssetServer({
             return notFound()
         }
         const { base: baseHeaders, gzip: gzipHeaders } = headersForAsset(assetPath)
-        const diskPath = distDir + assetPath
+        // Map the `/_app/<file>` URL onto the physical dir: strip the `/_app` prefix
+        // (5 chars) and join under appDir, which already IS the `_app` (or generation) dir.
+        const diskPath = appDir + assetPath.slice('/_app'.length)
         if (acceptsGzip(req) && diskGzipPaths.has(assetPath)) {
             return new Response(Bun.file(`${diskPath}.gz`), { headers: gzipHeaders })
         }

package/src/lib/server/runtime/createAppRouteResolver.ts

@@ -0,0 +1,145 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { matchRoute } from '../../shared/matchRoute.ts'
+import { normalizePathname } from '../../shared/normalizePathname.ts'
+import { parseRouteSegments } from '../../shared/parseRouteSegments.ts'
+import type { Pages } from '../../ui/types/Pages.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
+import type { createRouteDispatcher } from './createRouteDispatcher.ts'
+
+/* A route handler pre-bound to one registered URL — the dispatcher's output. */
+type RouteHandler = ReturnType<ReturnType<typeof createRouteDispatcher>>
+
+/*
+The URL-shape decision for one request, once the framework plumbing has passed
+on it. A `handler` case (rpc, page, or the openapi doc) is dispatched through
+the request scope; a `redirect` is returned verbatim; the asset cases name
+which asset server serves the path, with `publicAsset` as the catch-all bucket
+whose miss falls through to the 404 path. Keeping the decision data-only lets a
+test assert it without booting Bun.serve — the effects (ALS dispatch, asset
+serving, 404 render) stay in the fetch closure.
+*/
+export type RouteResolution =
+    | { kind: 'redirect'; response: Response }
+    | { kind: 'handler'; handler: RouteHandler; params: Record<string, string> }
+    | { kind: 'appAsset' }
+    | { kind: 'publicAsset' }
+
+/*
+Owns the URL-shape decisions that used to sit inline in the Bun.serve fetch
+closure: canonical-slash redirects (308), the openapi document's build +
+memo, and the asset-precedence ordering. Route dispatch (rpc-vs-page-vs-404,
+method matching) stays behind createRouteDispatcher; this resolver composes its
+per-URL handlers and adds the request-URL → decision layer on top, so both the
+redirect logic and the memo semantics become unit-testable without a listener.
+
+App routes are matched AFTER the `/__abide/*` plumbing (a reserved namespace no
+app route occupies) and BEFORE the root-level framework surfaces (the openapi
+doc, `/_app/`, public/ files), so a page route shadows a same-path public file
+— the precedence the Bun routes table used to impose implicitly, now pinned
+here. rpc URLs are flat literals (always `/rpc/...`) resolved by direct lookup;
+page URLs carry `[name]` / `[[name]]` / `[...rest]` segments resolved through
+the shared matchRoute — the same matcher the client router runs — so params
+decode and precedence agree across the sides by construction.
+*/
+export function createAppRouteResolver({
+    pages,
+    rpc,
+    buildRouteHandler,
+    openApiPath,
+    buildOpenApiDocument,
+}: {
+    pages: Pages
+    rpc: RemoteRoutes
+    buildRouteHandler: ReturnType<typeof createRouteDispatcher>
+    openApiPath: string
+    buildOpenApiDocument: () => Promise<Record<string, unknown>>
+}): (req: Request, url: URL) => RouteResolution {
+    /* Handlers pre-bound per registered URL. rpc URLs dispatch by direct lookup;
+       page URLs resolve through matchRoute against pageRouteUrls below. */
+    const rpcHandlers = new Map<string, RouteHandler>()
+    for (const routeUrl of Object.keys(rpc)) {
+        rpcHandlers.set(routeUrl, buildRouteHandler(routeUrl))
+    }
+    const pageHandlers = new Map<string, RouteHandler>()
+    for (const routeUrl of Object.keys(pages)) {
+        /* A `[...rest]` consumes every remaining segment, so segments after it
+           can never constrain matching — the route would silently serve paths
+           it shouldn't. Fail at boot instead. */
+        const segments = parseRouteSegments(routeUrl)
+        const catchAllIndex = segments.findIndex(
+            (segment) => segment.kind === 'param' && segment.catchAll,
+        )
+        if (catchAllIndex !== -1 && catchAllIndex !== segments.length - 1) {
+            throw new Error(
+                `[abide] invalid page route ${routeUrl}: a [...name] catch-all must be the last segment`,
+            )
+        }
+        pageHandlers.set(routeUrl, buildRouteHandler(routeUrl))
+    }
+    const pageRouteUrls = Object.keys(pages)
+
+    /* Built on first request, then reused — the rpc registry is frozen after load.
+       Memoised as a promise so two concurrent cold requests share one build instead
+       of both building (the second otherwise clobbering the first). A rejected build
+       clears the memo so the next request retries rather than caching the failure. */
+    let openApiSpec: Promise<Record<string, unknown>> | undefined
+    const openApiHandler: RouteHandler = async () => {
+        openApiSpec ??= buildOpenApiDocument().catch((error) => {
+            // Don't cache a failed build — clear the memo so a later request
+            // retries instead of 500-ing forever.
+            openApiSpec = undefined
+            throw error
+        })
+        return Response.json(await openApiSpec, { headers: { 'Cache-Control': NO_STORE } })
+    }
+
+    return function resolveAppRoute(_req, url): RouteResolution {
+        const rpcHandler = rpcHandlers.get(url.pathname)
+        if (rpcHandler) {
+            return { kind: 'handler', handler: rpcHandler, params: {} }
+        }
+        /*
+        Pages match only in canonical slash form; a non-canonical request
+        (`/admin/`, `//admin`) that would match is 308'd to the canonical URL
+        instead of served. Serving it directly would hand app.handle — the auth
+        seam — a pathname the matcher silently normalized away, so an exact-match
+        guard on `/admin` never sees the request it's guarding (the old Bun routes
+        table 404'd these forms; the redirect keeps the guard sound AND the URL
+        friendly). rpc URLs stay exact-match strict, as they always were.
+        */
+        const canonicalPathname = normalizePathname(url.pathname)
+        if (canonicalPathname !== url.pathname) {
+            if (matchRoute(pageRouteUrls, canonicalPathname)) {
+                return {
+                    kind: 'redirect',
+                    response: new Response(null, {
+                        status: 308,
+                        headers: {
+                            Location: `${canonicalPathname}${url.search}`,
+                            'Cache-Control': NO_STORE,
+                        },
+                    }),
+                }
+            }
+        } else {
+            const matchedPage = matchRoute(pageRouteUrls, url.pathname)
+            if (matchedPage) {
+                const pageHandler = pageHandlers.get(matchedPage.route)
+                if (pageHandler) {
+                    return { kind: 'handler', handler: pageHandler, params: matchedPage.params }
+                }
+            }
+        }
+        if (url.pathname === openApiPath) {
+            return { kind: 'handler', handler: openApiHandler, params: {} }
+        }
+        /* Static assets sidestep ALS + the per-request CacheStore + app.handle
+           (see the fetch closure); `/_app/` build output takes precedence over
+           public/ files, and anything else falls to the public bucket whose miss
+           becomes the 404. */
+        if (url.pathname.startsWith('/_app/')) {
+            return { kind: 'appAsset' }
+        }
+        return { kind: 'publicAsset' }
+    }
+}