castrum 0.9.1 → 0.9.3

package/src/ingress/index.ts

@@ -1,24 +1,14 @@
-// src/ingress/index.ts — Public ingress API (barrel + sync/async factories)
+// src/ingress/index.ts — Public ingress API (barrel).
 //
-// All constants come from Rust via src/ingress/constants.ts.
-// For maximum performance, use createIngressFast() from ./fast.ts directly.
-// This module wraps createIngressFast with convenience async API (createIngress).
-
-import { decoder } from '../shared/bytes'
-import { generateRequestId } from '../shared/request-id'
-import { readRequestBodyOnce } from './body'
-import { ERR_CODE_BODY_TOO_LARGE, ERR_CODE_REQUEST_TIMEOUT } from './constants'
-import { internalContext, snapshotResult, syntheticContext } from './context'
-import { createIngressFast } from './fast'
-import { buildResponseContext } from './headers/fast-templates'
-import { buildTerminalResponse } from './response/terminal'
-import { assertSyncCallback, DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from './shared'
-import type { IngressContext, IngressHandler, IngressOptions, SyncIngressHandler } from './types'
+// All constants come from Rust via src/ingress/constants.ts. For maximum
+// performance use createIngressFast() from ./fast.ts directly. The convenience
+// factories (`createIngressSync` / `createIngress`) live in ./sync.ts and are
+// re-exported here so this barrel stays a pure re-export hub.
 
 // Runtime-driven server factory: picks Bun.serve on Bun and the node:http
 // adapter on Node via the runtime adapter (src/runtime/server.ts). This
 // explicit re-export SHADOWS the Bun-only `createIngressServer` from
-// './server' (re-exported via './handlers' above) so the public API serves
+// './server' (re-exported via './handlers' below) so the public API serves
 // one backend per runtime. `createIngressServerNode` remains exported for
 // consumers who want the Node backend pinned.
 export { createIngressServer } from '../runtime/index'
@@ -44,6 +34,10 @@ export { healthHandler, livenessHandler, readinessHandler } from './health'
 export type { IngressMetrics } from './metrics'
 // ── Observability (zero-dep): metrics, health probes ─────────────
 export { createIngressMetrics, metricsHandler } from './metrics'
+export type { NativeRoute, NativeRoutePlan } from './native-route'
+export { createNativeRoute } from './native-route'
+// ── Route-wire v3 byte contract (PURE wire helpers) ───────────────
+export * from './packing/route-wire'
 export type { IngressFastHandler, IngressFastOptions } from './options'
 export { buildTerminalResponse } from './response/terminal'
 export type { CreateIngressRouterOptions, IngressRouter, RouterRouteSpec } from './router'
@@ -51,6 +45,8 @@ export { createIngressRouter } from './router'
 export type { HeaderPlan } from './shared'
 export { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, METHOD_KIND } from './shared'
 export * from './status'
+// ── Convenience factories (see ./sync.ts) ────────────────────────
+export { createIngress, createIngressSync } from './sync'
 export type {
   IngressContext,
   IngressHandler,
@@ -60,135 +56,3 @@ export type {
   SyncIngressHandler,
   TerminalStyle,
 } from './types'
-
-// ── Sync factory ─────────────────────────────────────────────────
-
-/**
- * Synchronous convenience wrapper over `createIngressFast` (path 1).
- *
- * The callback runs on the fast-path result and MUST be synchronous. Use
- * {@link createIngress} when you want automatic body reading + error contexts.
- */
-export function createIngressSync(options: IngressOptions = {}): SyncIngressHandler {
-  const fast = createIngressFast(options)
-
-  return {
-    run(req, ip, body, requestId, fn) {
-      return fast.run(req, ip, body, requestId, (result) => {
-        const out = fn(result)
-        assertSyncCallback(out, 'createIngressSync().run()')
-        return out
-      })
-    },
-  }
-}
-
-// ── Async factory ────────────────────────────────────────────────
-
-/**
- * Return a copy of `options` without the security-header keys.
- *
- * `createIngress` applies security headers itself (via `buildResponseContext`),
- * so they must not be forwarded to the underlying fast handler, which rejects
- * them (see `createIngressFast`).
- */
-function stripSecurityOptions(options: IngressOptions): IngressOptions {
-  const copy = { ...options }
-  delete copy.security
-  delete copy.enableSecurityHeaders
-  return copy
-}
-
-/**
- * Async ingress factory: reads the request body (size guard + deadline) and
- * returns a snapshot `IngressContext` with a terminal `Response`.
- *
- * Recommended default for serverless/edge-style `fetch` handlers. For maximum
- * throughput use `createIngressFast` / `createIngressSync` directly.
- */
-export function createIngress(options: IngressOptions = {}): IngressHandler {
-  const sync = createIngressSync(stripSecurityOptions(options))
-
-  const guard = options.enableBodySizeGuard !== false
-  const max = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
-  const bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
-
-  const wantsBody =
-    options.readBody === true ||
-    options.requireJsonBody === true ||
-    options.schema != null ||
-    (options.readBody !== false && guard)
-
-  const responseCtx = buildResponseContext(options)
-
-  return async function ingressAsync(req: Request, ip?: string): Promise<IngressContext> {
-    const requestId = options.enableRequestIds === false ? '' : decoder.decode(generateRequestId())
-    options.onRequest?.(req, requestId, ip)
-
-    // Every terminal outcome (success, 413, 408, 500) flows through here so a
-    // hook consumer sees exactly one onResponse per request.
-    const emitResponse = (context: IngressContext): IngressContext => {
-      options.onResponse?.(req, context, context.status, requestId)
-      return context
-    }
-
-    try {
-      if (guard) {
-        const rawLen = req.headers.get('content-length')
-        const contentLength = Number(rawLen ?? '0')
-
-        if (Number.isFinite(contentLength) && contentLength > max) {
-          return emitResponse(
-            syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
-          )
-        }
-      }
-
-      let body: Uint8Array | null = null
-
-      if (wantsBody && req.body !== null) {
-        try {
-          body = await readRequestBodyOnce(req, max, guard, bodyTimeoutMs)
-        } catch (err) {
-          const code = (err as { code?: string } | null)?.code
-
-          if (code === 'BODY_TOO_LARGE') {
-            return emitResponse(
-              syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
-            )
-          }
-
-          if (code === 'REQUEST_TIMEOUT') {
-            // Match the pre-baked route factories: a body-read deadline is a
-            // 408, not a 500 (was silently swallowed as 500 before).
-            return emitResponse(
-              syntheticContext(req, requestId, options, responseCtx, 408, ERR_CODE_REQUEST_TIMEOUT),
-            )
-          }
-
-          // Unknown body-read failure: surface to onError, then fall through
-          // to the internal-error context below.
-          options.onError?.(err instanceof Error ? err : new Error(String(err)))
-          throw err
-        }
-      }
-
-      return emitResponse(
-        sync.run(req, ip, body, requestId, (r) => {
-          const snapshot = snapshotResult(r)
-          const response = buildTerminalResponse(responseCtx, snapshot, req, requestId)
-
-          return {
-            ...snapshot,
-            response,
-          }
-        }),
-      )
-    } catch (err) {
-      // Native/other failures: never silent — report to onError and emit a
-      // structured 500 context so the request still completes observably.
-      options.onError?.(err instanceof Error ? err : new Error(String(err)))
-      return emitResponse(internalContext(req, requestId, options, responseCtx))
-    }
-  }
-}

package/src/ingress/native-route.ts

@@ -0,0 +1,182 @@
+// src/ingress/native-route.ts — public per-route native stack factory.
+//
+// `createNativeRoute` compiles a route-wire v3 descriptor ONCE (via the
+// `castrum_route_*` C-ABI / napi `Route` surface over `rust/ingress/
+// native_route.rs`) and runs each request frame in ONE native call — the same
+// lean per-route stack `@ignex/native`'s `createNativeRoute` consumes. This
+// brings that stack into castrum itself: routes that only need query/cookie
+// parse + `requireJsonBody`/`validateBody` verdicts (no CORS/rate-limit/
+// security/IP/metadata envelope) get the leanest possible 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).
+//
+// IMPURE by design (dlopen + FFI): it lives at the boundary like
+// `handlers.ts`/`server.ts`; the byte wire helpers it uses are the PURE
+// `src/ingress/packing/route-wire.ts`.
+
+import { getBunFFI } from '../native/ffi'
+import { getAddon } from '../native'
+import type { BunFFI } from '../native/ffi/types'
+import {
+  ROUTE_PART,
+  ROUTE_STAGE,
+  decodeRouteResult,
+  encodeRouteDescriptor,
+  packRouteFrame,
+  type RouteStageTag,
+  type RouteWireLimits,
+  type RouteWireResult,
+} from './packing/route-wire'
+
+/** Plan for a compiled native route (the stage/limit/schema surface). */
+export interface NativeRoutePlan {
+  /** Parse + lenient-decode the query string into pairs (stage 0). */
+  parseQuery?: boolean
+  /** Parse + lenient-decode the Cookie header into pairs (stage 1). */
+  parseCookies?: boolean
+  /** Reject a missing / non-JSON body with 400 (stage 5, first-failure-wins). */
+  requireJsonBody?: boolean
+  /** Validate the body against `schema` with 422 on failure (stage 4). */
+  validateBody?: boolean
+  /** Draft-07 JSON schema bytes for the body (`validateBody`). */
+  schema?: Uint8Array
+  /** Max body bytes before `requireJsonBody`/`validateBody` fail (default 2 MiB). */
+  maxBodyBytes?: number
+  /** Max query bytes before the parse VALID bit clears (default 8192). */
+  maxQueryBytes?: number
+  /** Max cookie bytes before the parse VALID bit clears (default 8192). */
+  maxCookieBytes?: number
+  /** Max pairs per section (0 = unlimited; default 0). */
+  maxPairs?: number
+}
+
+/** A compiled per-route native stack (route-wire v3). */
+export interface NativeRoute {
+  /** Whether the plan compiled `parseQuery` (the result carries a query section). */
+  readonly parseQuery: boolean
+  /** Whether the plan compiled `parseCookies` (the result carries a cookie section). */
+  readonly parseCookies: boolean
+  /**
+   * Run one request frame through the compiled stack and return the decoded
+   * verdict. The frame is `[flags u32][qLen][query][cLen][cookie]([bLen][body])`
+   * — build it with {@link packRouteFrame}. Reuses one growable output buffer
+   * (the needed-size convention: `0` = real error → throws; `> out.length` =
+   * exact required size → retry once).
+   */
+  runFrame(frame: Uint8Array): RouteWireResult
+  /** Convenience: pack a `(query, cookie, body)` frame then {@link runFrame}. */
+  run(query: string, cookie: string, body: Uint8Array | null): RouteWireResult
+  /** Free the native handle (idempotent; safe to call once at shutdown). */
+  destroy(): void
+}
+
+/**
+ * Compile a per-route native stack from a plan. Returns a compiled route whose
+ * `run`/`runFrame` perform the parse + verdict in ONE native call.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const result = route.run('page=1&limit=20', 'session=abc', null)
+ * // result.flags & ROUTE_FLAG.OK → parse succeeded; result.query = [['page','1'],…]
+ * ```
+ */
+export function createNativeRoute(plan: NativeRoutePlan = {}): NativeRoute {
+  const limits: RouteWireLimits = {
+    maxBodyBytes: plan.maxBodyBytes ?? 2 * 1024 * 1024,
+    maxQueryBytes: plan.maxQueryBytes ?? 8192,
+    maxCookieBytes: plan.maxCookieBytes ?? 8192,
+    maxPairs: plan.maxPairs ?? 0,
+  }
+
+  // Stage order is first-failure-wins on the native side, so the descriptor
+  // pipeline mirrors the plan's semantics: parse stages first, then body
+  // verdicts (validateBody before requireJsonBody per the Rust compile — it
+  // emits requireJsonBody first defensively; the native side treats the pair
+  // as "require then validate" and the compiler guarantees the order).
+  const stages: RouteStageTag[] = []
+  if (plan.parseQuery) stages.push(ROUTE_STAGE.parseQuery)
+  if (plan.parseCookies) stages.push(ROUTE_STAGE.parseCookies)
+  if (plan.validateBody) stages.push(ROUTE_STAGE.validateBody)
+  if (plan.requireJsonBody) stages.push(ROUTE_STAGE.requireJsonBody)
+
+  const schemas: Array<{ part: number; bytes: Uint8Array }> = []
+  if (plan.validateBody && plan.schema) {
+    schemas.push({ part: ROUTE_PART.body, bytes: plan.schema })
+  }
+
+  const descriptor = encodeRouteDescriptor(stages, schemas, limits)
+  const parseQuery = plan.parseQuery === true
+  const parseCookies = plan.parseCookies === true
+
+  // Transport: bun:ffi PRIMARY on Bun; napi `Route` on Node / fallback. The
+  // compiled route owns exactly one handle; `destroy` frees it.
+  const bunFFI: BunFFI | null = getBunFFI()
+  const ffiHandle = bunFFI !== null ? compileFfi(bunFFI, descriptor) : 0
+  const napiRoute = bunFFI === null ? compileNapi(descriptor) : null
+
+  // Reusable output buffer for the needed-size convention (grow once, retry).
+  let out = new Uint8Array(256)
+
+  const runFrame = (frame: Uint8Array): RouteWireResult => {
+    let written: number
+    if (ffiHandle !== 0 && bunFFI !== null) {
+      written = bunFFI.routeRun(ffiHandle, frame, out)
+      if (written > out.byteLength) {
+        // Exact required size reported — grow and retry once.
+        out = new Uint8Array(written)
+        written = bunFFI.routeRun(ffiHandle, frame, out)
+        if (written > out.byteLength) {
+          throw new Error('native route: output still too small after grow')
+        }
+      }
+    } else if (napiRoute !== null) {
+      written = napiRoute.run(frame, out)
+      if (written > out.byteLength) {
+        out = new Uint8Array(written)
+        written = napiRoute.run(frame, out)
+        if (written > out.byteLength) {
+          throw new Error('native route: output still too small after grow')
+        }
+      }
+    } else {
+      throw new Error('native route: no active transport')
+    }
+    return decodeRouteResult(out.subarray(0, written), { query: parseQuery, cookie: parseCookies })
+  }
+
+  return {
+    parseQuery,
+    parseCookies,
+    runFrame,
+    run: (query, cookie, body) => runFrame(packRouteFrame(query, cookie, body)),
+    destroy: () => {
+      if (ffiHandle !== 0 && bunFFI !== null) {
+        bunFFI.routeDestroy(ffiHandle)
+      }
+    },
+  }
+}
+
+/** Compile through bun:ffi (`castrum_route_compile`), returning the handle (0 = error). */
+function compileFfi(bunFFI: BunFFI, descriptor: Uint8Array): number {
+  try {
+    return bunFFI.routeCompile(descriptor)
+  } catch {
+    return 0 // routeCompile throws on an invalid descriptor; treat as no-handle
+  }
+}
+
+/** Compile through the napi `Route` class (Node / fallback transport). */
+function compileNapi(descriptor: Uint8Array): { run: (frame: Uint8Array, out: Uint8Array) => number } | null {
+  const addon = getAddon()
+  const Route = (addon as { Route?: new (d: Uint8Array) => { run: (f: Uint8Array, o: Uint8Array) => number } }).Route
+  if (typeof Route !== 'function') {
+    return null // addon without the route stack (pre-rebuild) — caller falls back
+  }
+  try {
+    return new Route(descriptor)
+  } catch {
+    return null
+  }
+}

package/src/ingress/packing/gather-raw-headers.ts

@@ -60,13 +60,15 @@ export function gatherRawHeadersPacked(
     return EMPTY_HEADERS_BLOCK
   }
 
+  const nonPreflight = methodKind !== METHOD_KIND.OPTIONS
+
   // CORS-only fast path: the only selected header is the (typically constant)
   // Origin, so the whole packed block is a pure function of the origin string.
   // Skip the per-request encode + scratch write by returning the cached block.
   // Preflight (OPTIONS) is excluded — it also packs ACRM/ACRH and must take
   // the general path. The MAX_SMALL_HEADER_BYTES guard mirrors the general
   // path (an oversized origin is dropped → empty block, not cached).
-  if (plan.cors && !plan.cookie && !plan.proxy && !plan.proto && methodKind !== METHOD_KIND.OPTIONS) {
+  if (plan.cors && !plan.cookie && !plan.proxy && !plan.proto && nonPreflight) {
     const origin = originValue !== undefined ? originValue : req.headers.get('origin')
     if (origin === null || origin.length > MAX_SMALL_HEADER_BYTES) {
       return EMPTY_HEADERS_BLOCK
@@ -74,6 +76,28 @@ export function gatherRawHeadersPacked(
     return cachedOriginBlock(origin)
   }
 
+  // cookie+cors fast path: when the request carries NO cookie header (the
+  // dominant API/bench case), the packed block is still origin-only, so the
+  // (typically constant) origin can reuse the cached block instead of being
+  // UTF-8 re-encoded + re-packed on every request. Byte-identical to the
+  // general path, which would visit ONLY the origin when the cookie is absent:
+  //   - cookie null + origin present → `[u16 1][origin pair]`  (cached block)
+  //   - cookie null + origin absent → `[u16 0]`               (EMPTY block)
+  //   - cookie null + origin oversized → dropped → `[u16 0]`  (EMPTY block)
+  // When a cookie IS present, fall through to the general path but hand the
+  // already-fetched value down (no second `req.headers.get('cookie')`).
+  let preFetchedCookie: string | null | undefined
+  if (plan.cors && plan.cookie && !plan.proxy && !plan.proto && nonPreflight) {
+    preFetchedCookie = req.headers.get('cookie')
+    if (preFetchedCookie === null) {
+      const origin = originValue !== undefined ? originValue : req.headers.get('origin')
+      if (origin === null || origin.length > MAX_SMALL_HEADER_BYTES) {
+        return EMPTY_HEADERS_BLOCK
+      }
+      return cachedOriginBlock(origin)
+    }
+  }
+
   let [buf, view] = getHeaderBuf()
   let pos = 2
   let count = 0
@@ -83,7 +107,7 @@ export function gatherRawHeadersPacked(
     count++
   }
 
-  forEachSelectedHeader(req, plan, methodKind, originValue, write)
+  forEachSelectedHeader(req, plan, methodKind, originValue, write, preFetchedCookie)
 
   // No selected header was actually present (e.g. a route with cookie+cors in
   // its plan but a request that sends neither) — return the shared empty block

package/src/ingress/packing/route-wire.ts

@@ -0,0 +1,197 @@
+// src/ingress/packing/route-wire.ts — route-wire v3 byte helpers (PURE).
+//
+// The per-route native stack (`rust/ingress/native_route.rs`,
+// `castrum_route_*` / napi `Route`) compiles a descriptor ONCE and runs each
+// request frame in ONE native call. This module owns the WIRE on the JS side:
+// descriptor encoding, frame packing, and result decoding — byte-layout
+// constants MUST match `rust/ingress/native_route.rs` and `@ignex/native`
+// `route-wire.ts` EXACTLY (`ROUTE_DESC_VERSION` bumps on any layout change; a
+// mismatched compiler/addon must be a hard reject, never a silent misparse).
+//
+// PURE: no addon import, no module state — safe for any consumer. The
+// addon-touching factory lives in `src/ingress/native-route.ts`.
+
+import { decoder, encoder } from '../../shared/bytes'
+
+/** Route descriptor magic (`"ROUT"` LE). Must match `ROUTE_DESC_MAGIC` in Rust. */
+export const ROUTE_DESC_MAGIC = 0x524f5554
+/** Wire version — bump on ANY descriptor/frame/result layout change. */
+export const ROUTE_DESC_VERSION = 3
+
+/** Descriptor stage tags (the ordered pipeline a route instance runs). */
+export const ROUTE_STAGE = {
+  parseQuery: 0,
+  parseCookies: 1,
+  validateQuery: 2,
+  validateCookies: 3,
+  validateBody: 4,
+  requireJsonBody: 5,
+} as const
+/** A descriptor stage tag (`ROUTE_STAGE` values, must match Rust). */
+export type RouteStageTag = (typeof ROUTE_STAGE)[keyof typeof ROUTE_STAGE]
+
+/** Descriptor part tags (`RoutePartKind`): the schema-bearing request parts. */
+export const ROUTE_PART = { body: 3 } as const
+
+/** Result flag bits (`ROUTE_RESULT_FLAG_*` in Rust). */
+export const ROUTE_FLAG = {
+  OK: 1 << 0,
+  BODY_VALID_JSON: 1 << 1,
+  QUERY_VALID: 1 << 2,
+  COOKIE_VALID: 1 << 3,
+  BODY_VALID: 1 << 4,
+} as const
+
+/** Frame flag: the body section is present (bit 0 of the frame flags word). */
+export const ROUTE_FRAME_FLAG_HAS_BODY = 1 << 0
+
+/** Size limits a route descriptor carries. */
+export interface RouteWireLimits {
+  maxBodyBytes: number
+  maxQueryBytes: number
+  maxCookieBytes: number
+  maxPairs: number
+}
+
+/** A schema part carried by the descriptor (part tag + draft-07 JSON bytes). */
+export interface RouteWireSchema {
+  part: number
+  bytes: Uint8Array
+}
+
+/**
+ * Encode a route plan into the descriptor wire.
+ *
+ * Layout: `[magic u32][version u32][maxBody u32][maxQuery u32][maxCookie u32]
+ * [maxPairs u32][stageCount u32][stages u8…][schemaCount u32]
+ * { [part u8][len u32][schema] }…`
+ */
+export function encodeRouteDescriptor(
+  pipeline: readonly RouteStageTag[],
+  schemas: readonly RouteWireSchema[],
+  limits: RouteWireLimits,
+): Uint8Array {
+  let total = 8 + 16 + 4 + pipeline.length + 4
+  for (const s of schemas) total += 1 + 4 + s.bytes.byteLength
+  const out = new Uint8Array(total)
+  const view = new DataView(out.buffer)
+  let pos = 0
+  view.setUint32(pos, ROUTE_DESC_MAGIC, true)
+  pos += 4
+  view.setUint32(pos, ROUTE_DESC_VERSION, true)
+  pos += 4
+  for (const v of [
+    limits.maxBodyBytes,
+    limits.maxQueryBytes,
+    limits.maxCookieBytes,
+    limits.maxPairs,
+  ]) {
+    view.setUint32(pos, v, true)
+    pos += 4
+  }
+  view.setUint32(pos, pipeline.length, true)
+  pos += 4
+  for (const stage of pipeline) {
+    out[pos] = stage
+    pos += 1
+  }
+  view.setUint32(pos, schemas.length, true)
+  pos += 4
+  for (const s of schemas) {
+    out[pos] = s.part
+    pos += 1
+    view.setUint32(pos, s.bytes.byteLength, true)
+    pos += 4
+    out.set(s.bytes, pos)
+    pos += s.bytes.byteLength
+  }
+  return out
+}
+
+/**
+ * Encode a request frame: `[flags u32][qLen][query][cLen][cookie]([bLen][body])`.
+ * The `flags` word currently only carries `ROUTE_FRAME_FLAG_HAS_BODY`.
+ */
+export function packRouteFrame(
+  query: string,
+  cookie: string,
+  body: Uint8Array | null,
+): Uint8Array {
+  const q = encoder.encode(query)
+  const c = encoder.encode(cookie)
+  const hasBody = body !== null && body.byteLength > 0
+  const total =
+    4 + 4 + q.byteLength + 4 + c.byteLength + (hasBody ? 4 + (body?.byteLength ?? 0) : 0)
+  const out = new Uint8Array(total)
+  const view = new DataView(out.buffer)
+  let pos = 0
+  view.setUint32(pos, hasBody ? ROUTE_FRAME_FLAG_HAS_BODY : 0, true)
+  pos += 4
+  view.setUint32(pos, q.byteLength, true)
+  pos += 4
+  out.set(q, pos)
+  pos += q.byteLength
+  view.setUint32(pos, c.byteLength, true)
+  pos += 4
+  out.set(c, pos)
+  pos += c.byteLength
+  if (hasBody && body) {
+    view.setUint32(pos, body.byteLength, true)
+    pos += 4
+    out.set(body, pos)
+  }
+  return out
+}
+
+/** A decoded `[name, value]` pair from a result section. */
+export type RouteWirePair = [string, string]
+
+/** The decoded route result: the verdict header + optional pair sections. */
+export interface RouteWireResult {
+  /** `ROUTE_FLAG_*` bits from the result header. */
+  flags: number
+  /** `0` = ok; `400` = not-JSON under requireJsonBody; `422` = schema fail. */
+  errorCode: number
+  /** Decoded query pairs (present iff the plan compiled `parseQuery`). */
+  query: RouteWirePair[]
+  /** Decoded cookie pairs (present iff the plan compiled `parseCookies`). */
+  cookie: RouteWirePair[]
+}
+
+/**
+ * Decode the result wire: `[flags u32][errorCode u32]` + a query pair section
+ * iff `query` and a cookie pair section iff `cookie` (the caller knows its own
+ * plan). Sections are `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
+ */
+export function decodeRouteResult(
+  buf: Uint8Array,
+  opts: { query: boolean; cookie: boolean },
+): RouteWireResult {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+  const flags = view.getUint32(0, true)
+  const errorCode = view.getUint32(4, true)
+  let pos = 8
+  const readPairs = (): RouteWirePair[] => {
+    const count = view.getUint32(pos, true)
+    pos += 4
+    const out: RouteWirePair[] = []
+    for (let i = 0; i < count; i++) {
+      const nameLen = view.getUint32(pos, true)
+      pos += 4
+      const name = decoder.decode(buf.subarray(pos, pos + nameLen))
+      pos += nameLen
+      const valueLen = view.getUint32(pos, true)
+      pos += 4
+      const value = decoder.decode(buf.subarray(pos, pos + valueLen))
+      pos += valueLen
+      out.push([name, value])
+    }
+    return out
+  }
+  return {
+    flags,
+    errorCode,
+    query: opts.query ? readPairs() : [],
+    cookie: opts.cookie ? readPairs() : [],
+  }
+}

package/src/ingress/packing/select-headers.ts

@@ -45,6 +45,12 @@ export const HDR_XFP = encoder.encode('x-forwarded-proto')
  *   fetched here. The same `MAX_SMALL_HEADER_BYTES` guard applies either way.
  * @param visit - Invoked once per selected header with the pre-encoded name
  *   bytes and the raw value string.
+ * @param cookieValue - When provided (non-undefined), the already-fetched
+ *   `Cookie` header value, avoiding a second `req.headers.get('cookie')`
+ *   native→JS conversion (the caller's cookie+cors fast path already fetched
+ *   it once to decide between the cached origin block and the general path).
+ *   When omitted, the cookie is fetched here — so existing callers are
+ *   byte-for-byte unchanged.
  */
 export function forEachSelectedHeader(
   req: Request,
@@ -52,11 +58,12 @@ export function forEachSelectedHeader(
   methodKind: number,
   originValue: string | null | undefined,
   visit: (name: Uint8Array, value: string) => void,
+  cookieValue?: string | null,
 ): void {
   const h = req.headers
 
   if (plan.cookie) {
-    const v = h.get('cookie')
+    const v = cookieValue !== undefined ? cookieValue : h.get('cookie')
     if (v !== null && v.length <= MAX_COOKIE_HEADER_BYTES) {
       visit(HDR_COOKIE, v)
     }