castrum 0.9.3 → 0.9.6

package/scripts/postinstall.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// scripts/postinstall.mjs — cross-platform native addon fallback builder.
+//
+// castrum ships PREBUILT addons for every `napi.targets` platform (the CI
+// "build" job compiles them per-platform and the "publish" job stages all of
+// them into one tarball), so on a supported platform this script is a fast
+// no-op. It exists to keep the core CROSS-COMPATIBLE when that prebuilt path
+// is NOT available:
+//
+//   - the host platform / libc is not in napi.targets (e.g. linux-armv7,
+//     freebsd, android, x86 32-bit, …),
+//   - a partial tarball shipped without this platform's artifact
+//     (CASTRUM_PUBLISH_ALLOW_PARTIAL local publish), or
+//   - the artifact failed to load and the user wants a matching rebuild.
+//
+// In those cases it compiles the addon FROM SOURCE in the consumer's
+// node_modules (`cargo build --release`), so the core keeps working anywhere a
+// Rust toolchain exists.
+//
+// Behaviour (in order):
+//   1. If a loadable artifact for this host already exists next to the script
+//      (a shipped prebuilt), do nothing — installs stay fast. Forced rebuild
+//      with `npm install --build-from-source`.
+//   2. Else if CASTRUM_SKIP_BUILD is set, or CI is detected (GitHub Actions
+//      builds the addon explicitly), warn and skip.
+//   3. Else if no `cargo`/`rustc` is on PATH, warn and skip (the runtime
+//      loader then fails with a clear "build it" error if the addon is needed).
+//   4. Else run `cargo build --release` and copy the resulting cdylib to every
+//      artifact name the loader probes for this host, so whichever libc/name
+//      variant it tries first, it finds a correct file.
+//
+// CASTRUM_REQUIRE_BUILD=1 turns every "warn and skip" above into a hard install
+// failure — for strict environments that must guarantee a loadable addon.
+//
+// No dependency on the `@napi-rs/cli`: `build.rs` runs `napi_build::setup()`
+// during a plain `cargo build`, and the produced cdylib IS the `.node` file the
+// napi CLI would rename — so this works in a consumer's node_modules where the
+// CLI (a devDependency) is not installed.
+//
+// The pure helpers are exported for tests (test/unit/native/postinstall.test.ts);
+// the script only auto-runs when invoked directly (npm/bun postinstall hook).
+
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const IS_MAIN = process.argv[1] != null && import.meta.url === pathToFileURL(process.argv[1]).href
+
+const log = (msg) => console.log(`postinstall: ${msg}`)
+const warn = (msg) => console.warn(`postinstall: WARNING: ${msg}`)
+
+/**
+ * Artifact names `src/native/loader.ts` probes for a host, mirroring its
+ * `libcVariants` logic. A source build always produces the portable BASELINE
+ * (not the optional x86-64-v3 SIMD variant), so this omits the v3 name — the
+ * loader falls through from the absent v3 file to the baseline names below.
+ *
+ * @param platform `process.platform`-style value ('linux' | 'darwin' | 'win32' | …)
+ * @param arch `process.arch`-style value ('x64' | 'arm64' | …)
+ * @returns artifact file names, in loader probe order
+ */
+export function napiArtifactCandidates(platform, arch) {
+  const libcVariants =
+    platform === 'win32' ? ['msvc', 'gnu'] : platform === 'linux' ? ['gnu', 'musl'] : ['']
+  const names = libcVariants.map(
+    (libc) => `castrum.${platform}-${arch}${libc ? `-${libc}` : ''}.node`,
+  )
+  names.push('castrum.node')
+  return names
+}
+
+/**
+ * Path of the cdylib `cargo build --release` produces for the current host
+ * (crate [lib] name = "castrum"; build.rs runs napi_build::setup()).
+ *
+ * @param root package root directory
+ * @param platform `process.platform`-style value
+ * @returns absolute path to the built cdylib
+ */
+export function cdylibArtifact(root, platform) {
+  const release = join(root, 'target', 'release')
+  if (platform === 'win32') return join(release, 'castrum.dll')
+  if (platform === 'darwin') return join(release, 'libcastrum.dylib')
+  return join(release, 'libcastrum.so')
+}
+
+function commandExists(cmd, env) {
+  const probe =
+    process.platform === 'win32'
+      ? spawnSync('where', [cmd], { stdio: 'ignore', env })
+      : spawnSync('which', [cmd], { stdio: 'ignore', env })
+  return probe.status === 0
+}
+
+/**
+ * Ensure a loadable native addon exists for this host, building from source as
+ * a fallback when no prebuilt ships. Pure-ish and testable: every input
+ * (`root`, `platform`, `arch`, `env`) can be injected, and `cargo` is only ever
+ * invoked after all short-circuit checks pass.
+ *
+ * @param root package root (where the .node artifacts live / where to build)
+ * @param opts overrides for testability: `{ platform, arch, env }`
+ * @returns `{ status: 'skip', reason }` or `{ status: 'built', candidates }`
+ */
+export function ensureNativeAddon(root = ROOT, opts = {}) {
+  const platform = opts.platform ?? process.platform
+  const arch = opts.arch ?? process.arch
+  const env = opts.env ?? process.env
+
+  const candidates = napiArtifactCandidates(platform, arch)
+  const prebuilt = candidates.find((name) => {
+    try {
+      return statSync(join(root, name)).size > 0
+    } catch {
+      return false
+    }
+  })
+  const force = env.npm_config_build_from_source === 'true'
+
+  if (prebuilt && !force) {
+    log(`prebuilt addon present (${prebuilt}) — nothing to build`)
+    return { status: 'skip', reason: 'prebuilt' }
+  }
+  if (force) log('npm_config_build_from_source set — forcing a source rebuild')
+
+  if (env.CASTRUM_SKIP_BUILD) {
+    warn(
+      'CASTRUM_SKIP_BUILD is set — skipping the source build. If no prebuilt ' +
+        'ships for this platform the native addon will be missing at runtime.',
+    )
+    return { status: 'skip', reason: 'env' }
+  }
+  if (env.CI) {
+    // GitHub Actions etc. install deps first, then build the addon explicitly
+    // (bun run build / napi build) — don't double-build during bun install.
+    if (!prebuilt) {
+      warn('CI detected — skipping the source build (CI builds the addon explicitly).')
+    }
+    return { status: 'skip', reason: 'ci' }
+  }
+
+  if (!commandExists('cargo', env) || !commandExists('rustc', env)) {
+    const msg =
+      `no Rust toolchain (cargo/rustc) found — cannot build the castrum addon for ` +
+      `${platform}/${arch}. Install Rust from https://rustup.rs and re-run ` +
+      `npm install, or set CASTRUM_SKIP_BUILD=1 to silence this warning.`
+    if (env.CASTRUM_REQUIRE_BUILD) throw new Error(msg)
+    warn(msg)
+    return { status: 'skip', reason: 'no-toolchain' }
+  }
+
+  log(
+    `no prebuilt addon for ${platform}/${arch} — building from source ` +
+      '(cargo build --release; requires network to crates.io, a few minutes on first run)',
+  )
+  // Windows needs the shell so `cargo` resolves via PATH/PATHEXT (cargo.exe).
+  const run =
+    process.platform === 'win32'
+      ? spawnSync('cargo build --release', { cwd: root, stdio: 'inherit', shell: true })
+      : spawnSync('cargo', ['build', '--release'], { cwd: root, stdio: 'inherit' })
+  if (run.status !== 0) {
+    const msg =
+      `cargo build --release failed (exit ${run.status ?? 'unknown'}); the castrum ` +
+      `native addon could not be built for ${platform}/${arch}.`
+    if (env.CASTRUM_REQUIRE_BUILD) throw new Error(msg)
+    warn(msg)
+    return { status: 'skip', reason: 'build-failed' }
+  }
+
+  const built = cdylibArtifact(root, platform)
+  if (!existsSync(built)) {
+    const msg = `build finished but no cdylib found at ${built}`
+    if (env.CASTRUM_REQUIRE_BUILD) throw new Error(msg)
+    warn(msg)
+    return { status: 'skip', reason: 'artifact-missing' }
+  }
+
+  // Copy the SAME correctly-built binary to every candidate name the loader
+  // probes. Only one is ever loaded (the first existing candidate), and since
+  // the file was built on this exact host its content always matches — so a
+  // glibc build copied under the musl name is still the right binary for this
+  // machine, and the loader finds a working file regardless of its probe order.
+  for (const name of candidates) {
+    copyFileSync(built, join(root, name))
+  }
+  log(`built + staged native addon for ${platform}/${arch}: ${candidates.join(', ')}`)
+  return { status: 'built', candidates }
+}
+
+if (IS_MAIN) {
+  try {
+    ensureNativeAddon()
+  } catch (err) {
+    console.error(`\npostinstall: ERROR: ${err instanceof Error ? err.message : String(err)}\n`)
+    process.exit(1)
+  }
+}

package/src/ingress/constants.ts

@@ -11,7 +11,7 @@
 // they cannot drift.
 
 import { getAddon } from '../native'
-import { getBunFFI, type BunFFI } from '../native/ffi'
+import { type BunFFI, getBunFFI } from '../native/ffi'
 
 // Transport: bun:ffi is PRIMARY on Bun, so the layout is read through the
 // C-ABI blob WITHOUT dlopening the napi addon. Node — or forced

package/src/ingress/context.ts

@@ -1,10 +1,10 @@
 // src/ingress/context.ts — Result snapshotting + synthetic/error context
 // builders for the async ingress API.
 
+import { ERR_CODE_INTERNAL, ERR_CODE_RATE_LIMITED, HV_CORS_SIMPLE, HV_JSON } from './constants'
 import type { ResponseBuildContext } from './headers/fast-templates'
 import { buildTerminalResponse } from './response/terminal'
-import { ERR_CODE_INTERNAL, ERR_CODE_RATE_LIMITED, HV_JSON, HV_CORS_SIMPLE } from './constants'
-import type { IngressOptions, IngressResult, IngressContext } from './types'
+import type { IngressContext, IngressOptions, IngressResult } from './types'
 
 const EMPTY_BODY = new Uint8Array(0)
 

package/src/ingress/decode/baked-result.ts

@@ -11,27 +11,27 @@
 // via ./result-base.ts.
 
 import {
-  OUT_VERDICT,
-  OUT_FLAGS,
-  OUT_RATE_LIMIT,
-  OUT_RATE_REMAINING,
-  OUT_COOKIES_JSON_LEN,
-  OUT_QUERY_JSON_LEN,
-  OUT_HEADER_VARIANT,
-  OUT_BODY_JSON_LEN,
-  OUT_DATA_START,
+  ERR_CODE_INTERNAL as ERROR_CODE_INTERNAL,
+  FLAG_BODY_TRUNCATED,
   FLAG_BODY_VALID_JSON,
-  FLAG_SCHEMA_VALID,
   FLAG_CORS_ALLOWED,
   FLAG_IS_PREFLIGHT,
   FLAG_RATE_LIMITED,
+  FLAG_SCHEMA_VALID,
   FLAG_TRUSTED_PROXY,
-  FLAG_BODY_TRUNCATED,
   HV_JSON,
-  ERR_CODE_INTERNAL as ERROR_CODE_INTERNAL,
+  OUT_BODY_JSON_LEN,
+  OUT_COOKIES_JSON_LEN,
+  OUT_DATA_START,
+  OUT_FLAGS,
+  OUT_HEADER_VARIANT,
+  OUT_QUERY_JSON_LEN,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_VERDICT,
 } from '../constants'
-import { sectionLayout } from './packed-sections'
 import { isValidResponseStatus } from '../status'
+import { sectionLayout } from './packed-sections'
 import { IngressResultBase } from './result-base'
 
 /** Zero-alloc, reusable result decoder for the pre-baked handler path. */

package/src/ingress/decode/fast-result.ts

@@ -12,28 +12,28 @@
 
 import { viewForArrayBuffer } from '../../shared/bytes'
 import {
-  OUT_VERDICT,
-  OUT_ERROR_CODE,
-  OUT_STATUS,
-  OUT_FLAGS,
-  OUT_RATE_LIMIT,
-  OUT_RATE_REMAINING,
-  OUT_COOKIES_JSON_LEN,
-  OUT_QUERY_JSON_LEN,
-  OUT_HEADER_VARIANT,
-  OUT_BODY_JSON_LEN,
-  OUT_DATA_START,
-  FLAG_HAS_COOKIES,
-  FLAG_HAS_QUERY,
+  ERR_CODE_INTERNAL,
+  FLAG_BODY_TRUNCATED,
   FLAG_BODY_VALID_JSON,
-  FLAG_SCHEMA_VALID,
   FLAG_CORS_ALLOWED,
+  FLAG_HAS_COOKIES,
+  FLAG_HAS_QUERY,
+  FLAG_HTTPS,
   FLAG_IS_PREFLIGHT,
   FLAG_RATE_LIMITED,
-  FLAG_HTTPS,
+  FLAG_SCHEMA_VALID,
   FLAG_TRUSTED_PROXY,
-  FLAG_BODY_TRUNCATED,
-  ERR_CODE_INTERNAL,
+  OUT_BODY_JSON_LEN,
+  OUT_COOKIES_JSON_LEN,
+  OUT_DATA_START,
+  OUT_ERROR_CODE,
+  OUT_FLAGS,
+  OUT_HEADER_VARIANT,
+  OUT_QUERY_JSON_LEN,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_STATUS,
+  OUT_VERDICT,
 } from '../constants'
 import { normalizeResponseStatus } from '../status'
 import { sectionLayout } from './packed-sections'

package/src/ingress/errors.ts

@@ -5,16 +5,16 @@
 // the two mappings are intentionally not unified (see AGENTS.md).
 
 import {
-  ERR_CODE_NONE,
-  ERR_CODE_CORS_PREFLIGHT,
-  ERR_CODE_RATE_LIMITED,
+  ERR_CODE_BAD_REQUEST,
   ERR_CODE_BODY_TOO_LARGE,
+  ERR_CODE_CORS_PREFLIGHT,
+  ERR_CODE_INTERNAL,
   ERR_CODE_INVALID_JSON,
-  ERR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST,
-  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_NONE,
+  ERR_CODE_RATE_LIMITED,
   ERR_CODE_REQUEST_TIMEOUT,
-  ERR_CODE_INTERNAL,
+  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_SCHEMA_VALIDATION,
 } from './constants'
 
 /** Map a native error code to its stable string name. */

package/src/ingress/headers/baked-templates.ts

@@ -8,7 +8,7 @@
 // builder (./fast-templates.ts) with a different wire format (x-ratelimit-*) —
 // do not unify them (see AGENTS.md).
 
-import { HV_JSON, HV_CORS_SIMPLE, HV_CORS_PREFLIGHT, HV_RATE_ACTIVE } from '../constants'
+import { HV_CORS_PREFLIGHT, HV_CORS_SIMPLE, HV_JSON, HV_RATE_ACTIVE } from '../constants'
 
 /** Inputs needed to build the pre-baked header templates. */
 export interface BakedTemplateParams {

package/src/ingress/headers/fast-templates.ts

@@ -9,15 +9,15 @@
 // a different wire format — do not unify them (see AGENTS.md).
 
 import {
-  HV_COUNT,
-  HV_CORS_SIMPLE,
   HV_CORS_PREFLIGHT,
+  HV_CORS_SIMPLE,
+  HV_COUNT,
   HV_RATE_ACTIVE,
   HV_RATE_LIMITED,
 } from '../constants'
+import { secondsFromMs } from '../shared'
 import { buildCorsStaticStrings, type CorsOptions, type CorsStaticStrings } from './cors'
 import { buildHstsValue, buildSecurityPairs, type SecurityHeadersOptions } from './hsts'
-import { secondsFromMs } from '../shared'
 
 /** A single precomputed header-variant template. */
 export interface HeaderTemplate {

package/src/ingress/health.ts

@@ -49,10 +49,9 @@ export function readinessHandler(check?: () => boolean | Promise<boolean>) {
       return ok
         ? jsonResponse(200, { status: 'ready' })
         : jsonResponse(503, { status: 'not_ready' })
-    } catch (err) {
+    } catch (_err) {
       return jsonResponse(503, {
         status: 'not_ready',
-        error: err instanceof Error ? err.message : String(err),
       })
     }
   }

package/src/ingress/index.ts

@@ -36,9 +36,9 @@ export type { IngressMetrics } from './metrics'
 export { createIngressMetrics, metricsHandler } from './metrics'
 export type { NativeRoute, NativeRoutePlan } from './native-route'
 export { createNativeRoute } from './native-route'
+export type { IngressFastHandler, IngressFastOptions } from './options'
 // ── 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'
 export { createIngressRouter } from './router'

package/src/ingress/native-route.ts

@@ -14,15 +14,15 @@
 // `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 { getBunFFI } from '../native/ffi'
 import type { BunFFI } from '../native/ffi/types'
 import {
-  ROUTE_PART,
-  ROUTE_STAGE,
   decodeRouteResult,
   encodeRouteDescriptor,
   packRouteFrame,
+  ROUTE_PART,
+  ROUTE_STAGE,
   type RouteStageTag,
   type RouteWireLimits,
   type RouteWireResult,
@@ -168,9 +168,13 @@ function compileFfi(bunFFI: BunFFI, descriptor: Uint8Array): number {
 }
 
 /** Compile through the napi `Route` class (Node / fallback transport). */
-function compileNapi(descriptor: Uint8Array): { run: (frame: Uint8Array, out: Uint8Array) => number } | null {
+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
+  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
   }

package/src/ingress/options.ts

@@ -78,9 +78,9 @@ export interface IngressFastHandler {
  */
 export type IngressHandlerOptions = Omit<IngressFastOptions, 'onError'>
 
+import type { FastIngressResult } from './decode/fast-result'
 import type { CorsOptions } from './headers/cors'
 import type { SecurityHeadersOptions } from './headers/hsts'
-import type { FastIngressResult } from './decode/fast-result'
 
 const KNOWN_INGRESS_OPTION_KEYS: ReadonlySet<string> = new Set([
   'trustProxy',

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

@@ -9,8 +9,8 @@
 import type { HeaderPlan } from '../shared'
 import { METHOD_KIND } from '../shared'
 import { writeHeaderPair } from './header-packing'
-import { forEachSelectedHeader, HDR_ORIGIN } from './select-headers'
 import { getHeaderBuf, MAX_SMALL_HEADER_BYTES } from './scratch'
+import { forEachSelectedHeader, HDR_ORIGIN } from './select-headers'
 
 // Shared per-header size guards (single source of truth in scratch.ts).
 // Re-exported for back-compat with imports that referenced them here.

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

@@ -112,11 +112,7 @@ export function encodeRouteDescriptor(
  * 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 {
+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

package/src/ingress/response/error-bodies.ts

@@ -8,14 +8,14 @@
 
 import { encoder } from '../../shared/bytes'
 import {
-  ERR_CODE_CORS_PREFLIGHT,
-  ERR_CODE_RATE_LIMITED,
+  ERR_CODE_BAD_REQUEST,
   ERR_CODE_BODY_TOO_LARGE,
+  ERR_CODE_CORS_PREFLIGHT,
+  ERR_CODE_INTERNAL,
   ERR_CODE_INVALID_JSON,
-  ERR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST,
+  ERR_CODE_RATE_LIMITED,
   ERR_CODE_REQUEST_TOO_LARGE,
-  ERR_CODE_INTERNAL,
+  ERR_CODE_SCHEMA_VALIDATION,
 } from '../constants'
 
 function staticErrorBody(code: string, message: string): Uint8Array {

package/src/ingress/response/terminal.ts

@@ -6,9 +6,9 @@
 // the pre-baked path has its own builders (see ./handlers.ts) — do not unify
 // them (see AGENTS.md).
 
+import { errorCodeName, errorMessage } from '../errors'
 import { headersForResult, type ResponseBuildContext } from '../headers/fast-templates'
 import { safeTerminalStatus } from '../status'
-import { errorCodeName, errorMessage } from '../errors'
 
 /**
  * Build a terminal response for a result, or `null` when the result is not

package/src/ingress/routes/echo.ts

@@ -1,11 +1,11 @@
 // src/ingress/routes/echo.ts — Pre-baked echo handler.
 
-import type { OptimizedIngressHandler } from '../types'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS, secondsFromMs } from '../shared'
+import { readBodyWithLimit } from '../body'
 import { HV_JSON } from '../constants'
 import { ERROR_BODIES } from '../response/error-bodies'
-import { readBodyWithLimit } from '../body'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, secondsFromMs } from '../shared'
+import type { OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, resolveIp } from './common'
 
 /**
  * Pre-baked echo handler: streams the request body back with the client's

package/src/ingress/routes/fallback.ts

@@ -1,8 +1,8 @@
 // src/ingress/routes/fallback.ts — Pre-baked fallback handler.
 
-import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { runBaked, type BakedHandlerOptions } from './common'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, runBaked } from './common'
 
 /**
  * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.

package/src/ingress/routes/head.ts

@@ -1,8 +1,8 @@
 // src/ingress/routes/head.ts — Pre-baked HEAD read handler.
 
-import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { buildSuccessInit, runBaked, type BakedHandlerOptions } from './common'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, buildSuccessInit, runBaked } from './common'
 
 /**
  * Pre-baked HEAD read handler: headers only, no body.

package/src/ingress/routes/native.ts

@@ -23,6 +23,7 @@ import { decoder } from '../../shared/bytes'
 import { generateRequestId } from '../../shared/request-id'
 import { readBodyWithLimit } from '../body'
 import type { NativeRoute } from '../native-route'
+import type { RouteWireResult } from '../packing/route-wire'
 import type { RouteHandler } from '../server'
 import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
 import type { NativeRequestContext, NativeResponder } from '../types'
@@ -97,7 +98,7 @@ export function nativeRouteHandler(
     const queryStr = qIndex >= 0 ? url.slice(qIndex + 1) : ''
     const cookieStr = req.headers.get('cookie') ?? ''
 
-    let result
+    let result: RouteWireResult
     try {
       result = route.run(queryStr, cookieStr, body)
     } catch {

package/src/ingress/routes/options.ts

@@ -1,7 +1,7 @@
 // src/ingress/routes/options.ts — Pre-baked OPTIONS handler (CORS preflight).
 
 import type { OptimizedIngressHandler } from '../types'
-import { buildSuccessInit, resolveIp, type BakedHandlerOptions } from './common'
+import { type BakedHandlerOptions, buildSuccessInit, resolveIp } from './common'
 
 /**
  * Pre-baked OPTIONS handler: serves the native pipeline's CORS preflight

package/src/ingress/routes/read.ts

@@ -1,8 +1,8 @@
 // src/ingress/routes/read.ts — Pre-baked GET read handler.
 
-import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { buildSuccessInit, runBaked, type BakedHandlerOptions } from './common'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, buildSuccessInit, runBaked } from './common'
 
 /**
  * Pre-baked GET read handler: returns the ingress body JSON on success.

package/src/ingress/server.ts

@@ -1,6 +1,8 @@
 // src/ingress/server.ts — Bun.serve builder over pre-baked route handlers.
 
 import { isBun } from '../shared/runtime'
+import type { NativeRoutePlan } from './native-route'
+import { createNativeRoute } from './native-route'
 import {
   deleteHandler,
   echoHandler,
@@ -13,8 +15,6 @@ import {
 import type { BakedHandlerOptions } from './routes/common'
 import { nativeRouteHandler } from './routes/native'
 import { nativeResponderRoute } from './routes/responder'
-import { createNativeRoute } from './native-route'
-import type { NativeRoutePlan } from './native-route'
 import type { NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
 /** Server-level default for the socket request-body cap (16 MiB). */
@@ -304,10 +304,14 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
       // LEAN native-stack responder route: route-wire v3 stack, no envelope.
       // The compiled route is injected into the pure route factory (DI across
       // the purity boundary — the compile touches the dlopen layer here).
-      const nativeRoute = nativeRouteHandler(createNativeRoute(spec.native.plan), spec.native.handler, {
-        ...routeOpts,
-        readBody: spec.native.readBody,
-      })
+      const nativeRoute = nativeRouteHandler(
+        createNativeRoute(spec.native.plan),
+        spec.native.handler,
+        {
+          ...routeOpts,
+          readBody: spec.native.readBody,
+        },
+      )
       const nativeMethods = spec.native.methods ?? ['GET']
       for (const m of nativeMethods) {
         methods[m] = nativeRoute

package/src/ingress/status.ts

@@ -6,16 +6,16 @@
 // ./constants.ts, so they live in one place and cannot drift.
 
 import {
-  ERR_CODE_NONE,
-  ERR_CODE_CORS_PREFLIGHT,
-  ERR_CODE_RATE_LIMITED,
+  ERR_CODE_BAD_REQUEST,
   ERR_CODE_BODY_TOO_LARGE,
+  ERR_CODE_CORS_PREFLIGHT,
+  ERR_CODE_INTERNAL,
   ERR_CODE_INVALID_JSON,
-  ERR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST,
-  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_NONE,
+  ERR_CODE_RATE_LIMITED,
   ERR_CODE_REQUEST_TIMEOUT,
-  ERR_CODE_INTERNAL,
+  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_SCHEMA_VALIDATION,
 } from './constants'
 
 /**

package/src/integration/batch.ts

@@ -13,12 +13,12 @@
 // checks) — exactly the pattern these helpers exist for.
 
 import {
-  loader,
   type LoaderBulk,
   type LoaderBulkArgs,
   type LoaderOpArgs,
   type LoaderOpName,
   type LoaderScalar,
+  loader,
 } from '../loader'
 import type { SchemaValidator } from '../shared/packed'