castrum 0.9.0 → 0.9.2

package/src/ingress/router.ts

@@ -0,0 +1,277 @@
+// src/ingress/router.ts — createIngressRouter: per-route compiled ingress.
+//
+// The "one super solution" over the existing ingress core. Instead of one
+// global `IngressInner` serving every path (with a superset of options), each
+// route in the table carries its OWN `IngressHandlerOptions` and compiles a
+// DEDICATED native `IngressInner` (via `createIngressHandler`) — so the native
+// pipeline prunes to exactly that route's stages (parseCookies, parseQuery,
+// schema, cors, rateLimit, limits...), and `buildHeaderPlan` (inside
+// `createIngressHandler`) produces a per-route header plan that reads ZERO
+// headers for routes that need none. All routes share the same wire format
+// (the existing packed `handle_request_packed`), the shared process-wide rate
+// limiter budgets, and pre-warm on construction (`warmOnCreate`).
+//
+// This is the completion of what `rust/route.rs` (now deleted — it was dead,
+// external-project wire) attempted: per-route native stage pruning, WITHOUT a
+// second/third wire format. The route factories (`readHandler`,
+// `jsonWriteHandler`, ...) and the dispatch machinery (`buildRouteHandlers` /
+// `buildPathMatcher`) are reused unchanged. The per-route native-compile idea
+// is ALSO exposed as the standalone per-route stack in
+// `rust/ingress/native_route.rs` (the `castrum_route_*`/napi `Route` surface
+// consumed by `@ignex/native`'s `createNativeRoute` — the LIVE successor to
+// the deleted dead wire).
+
+import type { BakedIngressResult } from './decode/baked-result'
+import { type BakedIngressRuntime, createIngressHandler } from './handlers'
+import type { NativeRoutePlan } from './native-route'
+import type { IngressHandlerOptions } from './options'
+import type { PathMatch } from './path-matcher'
+import { buildPathMatcher } from './path-matcher'
+import type { BakedRoute, RouteHandler } from './server'
+import { buildRouteHandlers } from './server'
+import type { BakedContext, NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
+
+/** Per-route spec for {@link createIngressRouter}. */
+export interface RouterRouteSpec {
+  /**
+   * Per-route ingress options — compiled into a DEDICATED native `IngressInner`
+   * for this route (parseCookies, parseQuery, schema, cors, rateLimit, limits,
+   * requireJsonBody, ...). This is what makes the pipeline prune per route.
+   */
+  options?: IngressHandlerOptions
+  /** Wire GET + HEAD read handlers over this route's compiled handler. */
+  read?: boolean
+  /** Wire POST/PUT/PATCH JSON-write handlers over this route's compiled handler. */
+  write?: boolean
+  /** Wire a POST echo handler over this route's compiled handler. */
+  echo?: boolean
+  /** Wire a GET read handler (cookies-style) over this route's compiled handler. */
+  cookies?: boolean
+  /** Wire a DELETE read-style handler over this route's compiled handler. */
+  delete?: boolean
+  /**
+   * A JS responder route: the native pipeline decides + rejects (terminal
+   * response in {@link terminalStyle}); on success the responder builds the
+   * 2xx body (async OK) from a decoded snapshot. Wired for `methods`
+   * (default `['GET']`). When set, the standard `read`/`write`/etc. flags for
+   * this route are ignored.
+   */
+  responder?: {
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Read the body for native validation (default false — framework owns it). */
+    readBody?: boolean
+  }
+  /**
+   * A LEAN native-stack responder route: the route-wire v3 per-route stack
+   * (`createNativeRoute` over `castrum_route_*`) runs ONLY the stages in
+   * `plan` (parseQuery/parseCookies/requireJsonBody/validateBody) in ONE
+   * native call — no CORS/rate-limit/security/IP/metadata envelope. On a
+   * verdict failure the route rejects (400 non-JSON / 422 schema); on success
+   * the responder builds the 2xx from the decoded snapshot. Measured ~580ns
+   * cheaper per request than the full-pipeline responder on a
+   * parseQuery+parseCookies route (bench/cost/native-route-vs-router.ts).
+   * Wired for `methods` (default `['GET']`). When set, `read`/`write`/etc.
+   * for this route are ignored.
+   */
+  native?: {
+    /** The route-wire v3 plan (parse/validate stages + limits). */
+    plan: NativeRoutePlan
+    /** The JS 2xx builder (receives the decoded query/cookies/body snapshot). */
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Read the body for `requireJsonBody`/`validateBody` (default false). */
+    readBody?: boolean
+  }
+  /** Terminal envelope style for this route's responder (default: router-level
+   *  `terminalStyle` or `'castrum'`). */
+  terminalStyle?: TerminalStyle
+  /**
+   * A raw request→Response handler served directly for GET, OUTSIDE the
+   * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
+   * `write`/etc. for this route are ignored.
+   */
+  raw?: RouteHandler
+  /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
+  maxBodyBytes?: number
+  /** Overrides `bodyTimeoutMs` for this route's write/echo handlers. */
+  bodyTimeoutMs?: number
+}
+
+/** Options for {@link createIngressRouter}. */
+export interface CreateIngressRouterOptions {
+  /** Route table: path → per-route spec. */
+  routes: Record<string, RouterRouteSpec>
+  /** Shared runtime hooks (onRequest/onResponse/onError, security headers,
+   *  output buffer size) applied to EVERY compiled route handler. */
+  runtime?: BakedIngressRuntime
+  /** Shared `getIp` resolver for route handlers. */
+  getIp?: (req: Request, srv: unknown) => string | undefined
+  /** Shared `copyBody` default for route handlers. */
+  copyBody?: boolean
+  /** Default terminal envelope style for responder routes (`'castrum'`). */
+  terminalStyle?: TerminalStyle
+  /** Pre-warm every compiled route at construction (JIT the packed pipeline +
+   *  the FFI ingress call before the first real request). Default: false. */
+  warmOnCreate?: boolean
+}
+
+/** A compiled per-route router. */
+export interface IngressRouter {
+  /** The per-route compiled handlers keyed by path (for custom route wiring). */
+  routeHandlers: Record<string, OptimizedIngressHandler>
+  /** The route → method → handler map (compatible with Bun.serve `routes` and
+   *  `createIngressServerNode`). */
+  routes: Record<string, Record<string, unknown>>
+  /** The path matcher (`:param`/`*` dynamic routes). */
+  match: (pathname: string) => PathMatch | undefined
+  /** A fetch-style dispatcher: match path + method → the route's handler. */
+  fetch: (req: Request, srv?: unknown) => Response | Promise<Response>
+  /** Pre-warm every compiled route (JIT the packed pipeline + FFI call). */
+  prewarm: () => void
+}
+
+/**
+ * Compile a route table into per-route native ingress instances.
+ *
+ * Each route with a pipeline-backed spec (`read`/`write`/`echo`/`cookies`/
+ * `delete`) compiles its OWN `createIngressHandler(options)` — a dedicated
+ * `IngressInner` pruned to that route's stages + a per-route header plan.
+ * Routes that need nothing (a bare `read` with no cookies/query/cors) therefore
+ * gather zero headers and run a near-empty native pipeline. All routes share
+ * the same wire format and the shared process-wide rate-limiter budgets.
+ *
+ * @example
+ * ```ts
+ * const router = createIngressRouter({
+ *   warmOnCreate: true,
+ *   runtime: ingressMetrics?.runtime,
+ *   routes: {
+ *     '/health': { read: true, options: { parseCookies: false, parseQuery: false } },
+ *     '/api/users': {
+ *       read: true,
+ *       write: true,
+ *       options: { parseCookies: true, parseQuery: true, schema: USER_SCHEMA_BYTES },
+ *     },
+ *     '/metrics': { raw: metricsHandler(ingressMetrics) },
+ *   },
+ * })
+ * const server = Bun.serve({ routes: router.routes }) // or router.fetch
+ * ```
+ */
+export function createIngressRouter(options: CreateIngressRouterOptions): IngressRouter {
+  const runtime = options.runtime ?? {}
+
+  // Per-route compiled handlers + the BakedRoute table the shared wiring reads.
+  const compiled: Record<string, OptimizedIngressHandler> = {}
+  const bakedRoutes: Record<string, BakedRoute> = {}
+  const baseOpts: {
+    getIp?: (req: Request, srv: unknown) => string | undefined
+    copyBody?: boolean
+  } = {}
+  if (options.getIp !== undefined) baseOpts.getIp = options.getIp
+  if (options.copyBody !== undefined) baseOpts.copyBody = options.copyBody
+
+  for (const [path, spec] of Object.entries(options.routes)) {
+    if (spec.raw) {
+      // Raw handler: served directly, outside the pipeline.
+      bakedRoutes[path] = { read: spec.raw as RouteHandler }
+      continue
+    }
+    if (spec.native) {
+      // LEAN native-stack responder route: the route-wire v3 stack runs ONLY
+      // the plan's stages (no full IngressInner, no CORS/rate-limit/security).
+      bakedRoutes[path] = {
+        native: {
+          plan: spec.native.plan,
+          handler: spec.native.handler,
+          methods: spec.native.methods,
+          readBody: spec.native.readBody,
+        },
+        maxBodyBytes: spec.maxBodyBytes,
+        bodyTimeoutMs: spec.bodyTimeoutMs,
+      }
+      continue
+    }
+    // Compile a dedicated native instance for this route's options.
+    const handler = createIngressHandler(spec.options ?? {}, runtime)
+    compiled[path] = handler
+
+    if (spec.responder) {
+      // Responder route: native decides + rejects; JS builds the 2xx.
+      bakedRoutes[path] = {
+        responder: {
+          ingress: handler,
+          handler: spec.responder.handler,
+          methods: spec.responder.methods,
+          terminalStyle: spec.terminalStyle ?? options.terminalStyle,
+          readBody: spec.responder.readBody,
+        },
+        maxBodyBytes: spec.maxBodyBytes,
+        bodyTimeoutMs: spec.bodyTimeoutMs,
+      }
+      continue
+    }
+
+    const routeSpec: BakedRoute = {
+      read: spec.read ? handler : undefined,
+      write: spec.write ? handler : undefined,
+      echo: spec.echo ? handler : undefined,
+      cookies: spec.cookies ? handler : undefined,
+      delete: spec.delete ? handler : undefined,
+      maxBodyBytes: spec.maxBodyBytes,
+      bodyTimeoutMs: spec.bodyTimeoutMs,
+    }
+    bakedRoutes[path] = routeSpec
+  }
+
+  const { routes } = buildRouteHandlers({ ...baseOpts, routes: bakedRoutes })
+  const matcher = buildPathMatcher(routes)
+
+  const prewarm = (): void => {
+    // Run one probe GET through each compiled handler so the packed pipeline,
+    // header plan and FFI ingress call are JIT-warmed before the first real
+    // request. `run` never throws for a bad request (native failures become a
+    // 500 via setInternalError), so this is safe on any handler.
+    for (const handler of Object.values(compiled)) {
+      const probe = new Request('http://localhost:0/prewarm', { method: 'GET' })
+      handler.run<unknown>(
+        probe,
+        '127.0.0.1',
+        null,
+        (_result: BakedIngressResult, _ctx: BakedContext) => 0,
+      )
+    }
+  }
+
+  if (options.warmOnCreate === true) {
+    prewarm()
+  }
+
+  const fetch = (req: Request, srv?: unknown): Response | Promise<Response> => {
+    let pathname: string
+    try {
+      pathname = new URL(req.url).pathname
+    } catch {
+      return new Response('Bad Request', { status: 400 })
+    }
+    const matched = matcher(pathname)
+    if (!matched) {
+      return new Response('Not Found', { status: 404 })
+    }
+    const methodHandler = matched.methods[req.method]
+    if (typeof methodHandler === 'function') {
+      return (methodHandler as RouteHandler)(req, srv, matched.params)
+    }
+    // A route matched but this method isn't wired — 405, or a bare OPTIONS 204
+    // when the route answers preflights.
+    if (req.method === 'OPTIONS' && typeof matched.methods.OPTIONS === 'function') {
+      return (matched.methods.OPTIONS as RouteHandler)(req, srv, matched.params)
+    }
+    return new Response('Method Not Allowed', { status: 405 })
+  }
+
+  return { routeHandlers: compiled, routes, match: matcher, fetch, prewarm }
+}

package/src/ingress/routes/common.ts

@@ -1,6 +1,8 @@
 // src/ingress/routes/common.ts — Shared route-handler options + helpers.
 
-import type { OptimizedIngressHandler } from '../types'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { secondsFromMs } from '../shared'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
 
 /** Options accepted by the pre-baked route factories. */
 export interface BakedHandlerOptions {
@@ -18,6 +20,14 @@ export interface BakedHandlerOptions {
   bodyTimeoutMs?: number
   /** Fallback handler used for write error paths. Defaults to the write ingress. */
   fallback?: OptimizedIngressHandler
+  /**
+   * Zero-DOM JSON-validity check for the write-route fallback validation
+   * (`jsonWriteHandler` when neither `requireJsonBody` nor a `schema` is
+   * configured). Injected so the pure route factories never import the native
+   * layer (dependency injection across the purity boundary). Defaults to the
+   * `ingress.jsonValid` capability that `createIngressHandler` provides.
+   */
+  jsonValid?: (bytes: Uint8Array) => boolean
   /**
    * When true, route the JSON-validity fallback check through the higher-order
    * loader (`loader("jsonValid")`) instead of the direct native call —
@@ -36,3 +46,42 @@ export function resolveIp(
 ): string | undefined {
   return opts.getIp ? opts.getIp(req, srv) : undefined
 }
+
+/**
+ * Build the success `ResponseInit` (status + ratelimit headers) shared by
+ * every pre-baked success path. A plain function call, so the hot path keeps
+ * its single init-object allocation and nothing else.
+ *
+ * @param status Success status; defaults to 200.
+ */
+export function buildSuccessInit(
+  ingress: OptimizedIngressHandler,
+  result: BakedIngressResult,
+  ctx: BakedContext,
+  status = 200,
+): ResponseInit {
+  return {
+    status,
+    headers: ingress.responseHeaders(
+      result.headerVariant,
+      ctx.requestIdHeader,
+      ctx.origin,
+      result.rateRemaining,
+      result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+    ),
+  }
+}
+
+/**
+ * Wrap a `(result, ctx) => Response` responder in the shared sync route
+ * runner: resolve the client IP once and dispatch through the native pipeline
+ * (`ingress.run` with a null body). Used by the read / head / fallback route
+ * factories whose responder never needs the request object.
+ */
+export function runBaked(
+  ingress: OptimizedIngressHandler,
+  opts: BakedHandlerOptions,
+  respond: (result: BakedIngressResult, ctx: BakedContext) => Response,
+): (req: Request, srv?: unknown) => Response {
+  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+}

package/src/ingress/routes/fallback.ts

@@ -2,7 +2,7 @@
 
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { resolveIp, type BakedHandlerOptions } from './common'
+import { runBaked, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.
@@ -19,5 +19,5 @@ export function fallbackHandler(
     return ingress.errorResponse(undefined, result, 404, 'not_found', 'Not found', ctx)
   }
 
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return runBaked(ingress, opts, respond)
 }

package/src/ingress/routes/head.ts

@@ -2,8 +2,7 @@
 
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { secondsFromMs } from '../shared'
+import { buildSuccessInit, runBaked, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked HEAD read handler: headers only, no body.
@@ -21,17 +20,8 @@ export function headHandler(
       return ingress.internalErrorResponse(ctx, result)
     }
 
-    return new Response(null, {
-      status: 200,
-      headers: ingress.responseHeaders(
-        result.headerVariant,
-        ctx.requestIdHeader,
-        ctx.origin,
-        result.rateRemaining,
-        result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-      ),
-    })
+    return new Response(null, buildSuccessInit(ingress, result, ctx))
   }
 
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return runBaked(ingress, opts, respond)
 }

package/src/ingress/routes/index.ts

@@ -1,10 +1,11 @@
 // src/ingress/routes/index.ts — Route-handler factory composer.
 
 export * from './common'
-export * from './read'
+export * from './delete'
+export * from './echo'
+export * from './fallback'
 export * from './head'
 export * from './json-write'
-export * from './echo'
-export * from './delete'
 export * from './options'
-export * from './fallback'
+export * from './read'
+export * from './responder'

package/src/ingress/routes/json-write.ts

@@ -1,27 +1,26 @@
 // src/ingress/routes/json-write.ts — Pre-baked JSON-write handler
 // (POST/PUT/PATCH).
 
-import type { OptimizedIngressHandler } from '../types'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS, secondsFromMs } from '../shared'
+import { decodeUtf8 } from '../../shared/codec'
 import { readBodyWithLimit } from '../body'
-import { getAddon } from '../../native'
-import { getBunFFI } from '../../native/ffi'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
+import type { OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, buildSuccessInit, resolveIp } from './common'
 
 /**
- * Zero-DOM JSON-validity check — the same native fast path the ingress
- * pipeline uses internally (`json_valid_bytes`).
- *
- * Used by `jsonWriteHandler` as a fallback when the pipeline skipped JSON
- * validation because neither `requireJsonBody` nor a `schema` is configured
- * on the ingress (see the `bodyValidJson` handling in the route).
- *
- * bun:ffi is primary on Bun; the napi addon is the fallback (Node, forced
- * `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test).
+ * Pure JSON-validity fallback used ONLY for hand-rolled
+ * `OptimizedIngressHandler` mocks that carry no native `jsonValid` capability.
+ * Real handlers from `createIngressHandler` always provide the zero-DOM native
+ * check (`ingress.jsonValid`), so this never runs on the hot path — it exists
+ * to keep the security property (invalid JSON must be rejected) for mocks.
  */
-function isValidJsonBytes(bytes: Uint8Array): boolean {
-  const ffi = getBunFFI()
-  return ffi ? ffi.jsonValid(bytes) : getAddon().jsonValid(bytes)
+function defaultJsonValid(bytes: Uint8Array): boolean {
+  try {
+    JSON.parse(decodeUtf8(bytes))
+    return true
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -39,6 +38,10 @@ export function jsonWriteHandler(
   // Non-zero default: protect against slowloris / trickling bodies. Set
   // `bodyTimeoutMs: 0` to disable.
   const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+  // JSON-validity check via DI across the purity boundary: an explicit option
+  // wins, otherwise the handler's own native capability (from
+  // `createIngressHandler`), otherwise the pure mock fallback.
+  const jsonValid = opts.jsonValid ?? ingress.jsonValid ?? defaultJsonValid
 
   return async (req, srv) => {
     const ip = resolveIp(req, srv, opts)
@@ -60,25 +63,10 @@ export function jsonWriteHandler(
       })
     }
 
-    const contentLengthHeader = req.headers.get('content-length')
-    const contentLength = contentLengthHeader === null ? NaN : Number(contentLengthHeader)
-
-    if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
-      return fallback.run(req, ip, null, (result, ctx) => {
-        const terminal = fallback.terminalResponse(req, result, ctx)
-        if (terminal) return terminal
-
-        return fallback.errorResponse(
-          req,
-          result,
-          413,
-          'body_too_large',
-          'Request body is too large',
-          ctx,
-        )
-      })
-    }
-
+    // Content-Length / body-size enforcement happens INSIDE readBodyWithLimit
+    // (guard on): the declared length is checked before reading and re-checked
+    // after, so a client lying about Content-Length still gets a 413. Not
+    // re-reading the header here saves a per-POST headers.get on the hot path.
     let bodyBytes: Uint8Array
     try {
       // Stream-read with the limit enforced WHILE reading — a body that
@@ -130,20 +118,11 @@ export function jsonWriteHandler(
             ctx,
           )
         }
-      } else if (!isValidJsonBytes(bodyBytes)) {
+      } else if (!jsonValid(bodyBytes)) {
         return ingress.errorResponse(req, result, 400, 'invalid_json', 'Invalid JSON body', ctx)
       }
 
-      const init: ResponseInit = {
-        status: 200,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-        ),
-      }
+      const init = buildSuccessInit(ingress, result, ctx)
 
       return copyBody
         ? new Response(result.bodyJson(true), init)

package/src/ingress/routes/native.ts

@@ -0,0 +1,130 @@
+// src/ingress/routes/native.ts — lean per-route native-stack route factory.
+//
+// A `RouteHandler` backed by the route-wire v3 stack (`createNativeRoute`)
+// instead of the full 8-stage `IngressInner`: the native side runs ONLY the
+// stages the plan compiled (parseQuery/parseCookies/requireJsonBody/
+// validateBody) and returns a packed verdict + pair sections; the responder
+// builds the 2xx from the decoded snapshot. This is the leanest per-request
+// path — measured `bench/cost/native-route-vs-router.ts`: ~551ns full JS-glue
+// path vs ~1131ns router `run()` on a parseQuery+parseCookies route (−580ns).
+//
+// PURE: the compiled `NativeRoute` is injected (dependency injection across
+// the purity boundary) — this factory never touches the dlopen layer itself;
+// the impure `createNativeRoute(plan)` call happens in the boundary
+// (`router.ts` / `server.ts` `buildRouteHandlers`).
+//
+// Trade-off (deliberate): the native route stack does NOT do CORS, rate
+// limiting, security headers, IP trust, or the castrum metadata envelope — a
+// route that needs those must use the full pipeline (`readHandler` /
+// `nativeResponderRoute`). This factory is for routes where the framework
+// owns the response body and only needs parse + verdict.
+
+import { decoder } from '../../shared/bytes'
+import { generateRequestId } from '../../shared/request-id'
+import { readBodyWithLimit } from '../body'
+import type { NativeRoute } from '../native-route'
+import type { RouteHandler } from '../server'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
+import type { NativeRequestContext, NativeResponder } from '../types'
+import type { BakedHandlerOptions } from './common'
+import { resolveIp } from './common'
+
+/** Options for {@link nativeRouteHandler}. */
+export interface NativeRouteHandlerOptions extends BakedHandlerOptions {
+  /** Read the request body and pass it for `requireJsonBody`/`validateBody`. */
+  readBody?: boolean
+}
+
+/** The `+`-to-space / `%XX` decoding is done natively; keys are last-wins. */
+function pairsToRecord(pairs: ReadonlyArray<[string, string]>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of pairs) out[k] = v
+  return out
+}
+
+/**
+ * Build a lean native-stack route handler over a COMPILED route (injected —
+ * compile via `createNativeRoute` in the boundary, then pass the route here).
+ *
+ * Terminal verdicts (`errorCode !== 0`) become JSON rejections: 400 for
+ * `requireJsonBody` (missing / non-JSON body), 422 for `validateBody` schema
+ * failure. On success the responder builds the 2xx from the snapshot.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const handler = nativeRouteHandler(route, (snap) =>
+ *   Response.json({ ok: true, query: snap.query, cookies: snap.cookies }),
+ * )
+ * ```
+ */
+export function nativeRouteHandler(
+  route: NativeRoute,
+  responder: NativeResponder,
+  opts: NativeRouteHandlerOptions = {},
+): RouteHandler {
+  const readBody = opts.readBody ?? false
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+  const parseQuery = route.parseQuery
+  const parseCookies = route.parseCookies
+
+  const terminal = (status: number, code: string, message: string): Response =>
+    Response.json(
+      { ok: false, error: { code, message } },
+      { status, headers: { 'content-type': 'application/json' } },
+    )
+
+  return async (req, srv, _params) => {
+    const ip = resolveIp(req, srv, opts)
+    const requestId = decoder.decode(generateRequestId())
+
+    let body: Uint8Array | null = null
+    if (readBody) {
+      try {
+        body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
+      } catch (err) {
+        const code = (err as Error & { code?: string }).code
+        const status = code === 'REQUEST_TIMEOUT' ? 408 : code === 'BODY_TOO_LARGE' ? 413 : 400
+        return terminal(status, 'BAD_REQUEST', 'Request body read failed')
+      }
+    }
+
+    // Extract the query substring + Cookie header (the only request inputs the
+    // native stack reads) and run the tiny frame in ONE native call.
+    const url = req.url
+    const qIndex = url.indexOf('?')
+    const queryStr = qIndex >= 0 ? url.slice(qIndex + 1) : ''
+    const cookieStr = req.headers.get('cookie') ?? ''
+
+    let result
+    try {
+      result = route.run(queryStr, cookieStr, body)
+    } catch {
+      return terminal(500, 'INTERNAL', 'Native route run failed')
+    }
+
+    if (result.errorCode !== 0) {
+      if (result.errorCode === 400) {
+        return terminal(400, 'INVALID_JSON', 'Request body must be valid JSON')
+      }
+      if (result.errorCode === 422) {
+        return terminal(422, 'VALIDATION_FAILED', 'Request body failed schema validation')
+      }
+      return terminal(400, 'BAD_REQUEST', 'Bad request')
+    }
+
+    const snapshot: NativeRequestContext = {
+      requestId,
+      status: 200,
+      rateLimited: false,
+      retryAfterMs: 0,
+      query: parseQuery ? pairsToRecord(result.query) : {},
+      cookies: parseCookies ? pairsToRecord(result.cookie) : {},
+      body: body ?? new Uint8Array(0),
+      ip,
+      req,
+    }
+    return responder(snapshot)
+  }
+}

package/src/ingress/routes/options.ts

@@ -1,8 +1,7 @@
 // src/ingress/routes/options.ts — Pre-baked OPTIONS handler (CORS preflight).
 
 import type { OptimizedIngressHandler } from '../types'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { secondsFromMs } from '../shared'
+import { buildSuccessInit, resolveIp, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked OPTIONS handler: serves the native pipeline's CORS preflight
@@ -22,15 +21,6 @@ export function optionsHandler(
       const terminal = ingress.terminalResponse(req, result, ctx)
       if (terminal) return terminal
 
-      return new Response(null, {
-        status: 204,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-        ),
-      })
+      return new Response(null, buildSuccessInit(ingress, result, ctx, 204))
     })
 }