castrum 0.7.0 → 0.9.1

package/src/runtime/builtins.ts

@@ -0,0 +1,131 @@
+// src/runtime/builtins.ts — Bun built-in delegation registry (the BUN_WINS set).
+//
+// Single source of truth for "under Bun this op is faster as a built-in than
+// via the rust addon" (measured in docs/bun-builtins-decision-matrix.md). The
+// scalar/text builders prefer `builtins.has(op)` over calling the native
+// transport; `src/selection.ts` derives its `opImpl` decision from the same
+// registry, so the hardcoded `BUN_WINS` set + `isBun()` branch disappear.
+//
+// NOTE: `gzipDecompress` is deliberately NOT delegated — the rust surface
+// keeps the native path (with its 64 MiB decompression-bomb cap) even under
+// Bun, because `Bun.gunzipSync` has no output-size bound.
+//
+// On Node the registry is EMPTY (`has()` returns false; methods throw if
+// called) so every op falls through to the native transport.
+
+import { runtimeCodec } from './codec'
+import { detectedRuntime } from './detect'
+import type { BuiltinsAdapter, RuntimeName } from './types'
+
+/** The delegated op names (matches the historical `BUN_WINS` set). */
+export const BUILTIN_OPS = [
+  'gzipCompress',
+  'crc32',
+  'randomToken',
+  'hmacSha256',
+  'xxh3',
+  'urlEncode',
+  'urlDecode',
+  'base64Encode',
+  'base64UrlEncode',
+  'hexEncode',
+  'httpDate',
+] as const
+
+const MAX_TOKEN_BYTES = 16 * 1024 * 1024 // 16 MiB guard (matches the native path)
+
+function createBunBuiltins(): BuiltinsAdapter {
+  const ops = new Set<string>(BUILTIN_OPS)
+  return {
+    ops: BUILTIN_OPS,
+    has(op: string): boolean {
+      return ops.has(op)
+    },
+    crc32(input: Uint8Array): number {
+      return Bun.hash.crc32(input) >>> 0 // preserves the unsigned-32 contract
+    },
+    xxh3(input: Uint8Array): bigint {
+      return Bun.hash.xxHash3(input)
+    },
+    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | string {
+      const hasher = new Bun.CryptoHasher('sha256', key)
+      hasher.update(data)
+      return Buffer.from(hasher.digest()).toString('hex')
+    },
+    gzipCompress(data: Uint8Array, level?: number | null): Uint8Array {
+      const opts = level != null ? ({ level } as Parameters<typeof Bun.gzipSync>[1]) : undefined
+      return Bun.gzipSync(data as unknown as Uint8Array<ArrayBuffer>, opts)
+    },
+    randomToken(byteLen: number): Uint8Array | string {
+      if (byteLen > MAX_TOKEN_BYTES) {
+        throw new RangeError('randomToken: byteLen exceeds 16 MiB limit')
+      }
+      return Buffer.from(crypto.getRandomValues(new Uint8Array(byteLen))).toString('hex')
+    },
+    base64Encode(
+      input: Uint8Array,
+      urlSafe?: boolean,
+      padding?: boolean,
+    ): Uint8Array | string | undefined {
+      // Only the standard padded, non-url-safe case delegates (SIMD Buffer);
+      // url-safe/unpadded falls through to the native transport.
+      if (urlSafe || padding === false) return undefined
+      return Buffer.from(input).toString('base64')
+    },
+    base64UrlEncode(input: Uint8Array): Uint8Array | string {
+      return Buffer.from(input).toString('base64url')
+    },
+    hexEncode(input: Uint8Array): Uint8Array | string {
+      return Buffer.from(input).toString('hex')
+    },
+    urlEncode(input: Uint8Array): string {
+      return encodeURIComponent(runtimeCodec.decodeUtf8(input))
+    },
+    urlDecode(input: Uint8Array): Uint8Array {
+      return runtimeCodec.encodeUtf8(decodeURIComponent(runtimeCodec.decodeUtf8(input)))
+    },
+    urlEncodeStr(input: string): string {
+      return encodeURIComponent(input)
+    },
+    urlDecodeStr(input: string): string {
+      return decodeURIComponent(input)
+    },
+    httpDate(secs?: number): string {
+      const t = secs ?? Math.floor(Date.now() / 1000)
+      return new Date(t * 1000).toUTCString()
+    },
+  }
+}
+
+function createNodeBuiltins(): BuiltinsAdapter {
+  const unavailable = (op: string): never => {
+    throw new Error(`builtin "${op}" is a Bun-only delegation — not available on Node`)
+  }
+  return {
+    ops: [],
+    has(): boolean {
+      return false
+    },
+    crc32: () => unavailable('crc32'),
+    xxh3: () => unavailable('xxh3'),
+    hmacSha256: () => unavailable('hmacSha256'),
+    gzipCompress: () => unavailable('gzipCompress'),
+    randomToken: () => unavailable('randomToken'),
+    base64Encode: () => unavailable('base64Encode'),
+    base64UrlEncode: () => unavailable('base64UrlEncode'),
+    hexEncode: () => unavailable('hexEncode'),
+    urlEncode: () => unavailable('urlEncode'),
+    urlDecode: () => unavailable('urlDecode'),
+    urlEncodeStr: () => unavailable('urlEncodeStr'),
+    urlDecodeStr: () => unavailable('urlDecodeStr'),
+    httpDate: () => unavailable('httpDate'),
+  }
+}
+
+/** Build the builtins registry for a runtime. */
+export function createBuiltins(name: RuntimeName): BuiltinsAdapter {
+  return name === 'bun' ? createBunBuiltins() : createNodeBuiltins()
+}
+
+/** The shared builtins registry for the detected runtime (selected once at load). */
+export const runtimeBuiltins: BuiltinsAdapter = createBuiltins(detectedRuntime)

package/src/runtime/codec.ts

@@ -0,0 +1,147 @@
+// src/runtime/codec.ts — runtime-native UTF-8 codec (Bun transfer, Node fallback).
+//
+// The UTF-8 codec branches (formerly in `src/shared/codec.ts`) are centralized
+// here and selected ONCE at module load:
+//   - encode:     Bun `Bun.ArrayBufferSink` vs `TextEncoder`.
+//   - encodeInto: zero-copy `Buffer` view `.write` vs `TextEncoder.encodeInto`.
+//   - decode:     `new CString(ptr, 0, len)` from `bun:ffi` vs `TextDecoder`.
+//   - decodeFatal: replacement-mode (Bun) vs fatal `TextDecoder` (Node).
+//
+// `src/shared/codec.ts` re-exports these so existing callers are unchanged.
+// This module must NOT import `src/native/ffi.ts` (it would create a cycle
+// through the bind-time self-test) — the Bun decode lazily `require`s
+// `bun:ffi` itself, and depends only on the detection leaf.
+
+import { detectedRuntime } from './detect'
+import type { RuntimeName, Utf8Codec } from './types'
+
+// ── Lazy Node singletons ──────────────────────────────────────────
+let nodeEncoder: TextEncoder | null = null
+let nodeDecoder: TextDecoder | null = null
+let nodeFatalDecoder: TextDecoder | null = null
+
+function getNodeEncoder(): TextEncoder {
+  if (nodeEncoder === null) nodeEncoder = new TextEncoder()
+  return nodeEncoder
+}
+
+function getNodeDecoder(): TextDecoder {
+  if (nodeDecoder === null) nodeDecoder = new TextDecoder()
+  return nodeDecoder
+}
+
+function getNodeFatalDecoder(): TextDecoder {
+  if (nodeFatalDecoder === null) nodeFatalDecoder = new TextDecoder('utf-8', { fatal: true })
+  return nodeFatalDecoder
+}
+
+// ── Bun codec ─────────────────────────────────────────────────────
+let bunSink: Bun.ArrayBufferSink | null = null
+let bunFfiCodec: typeof import('bun:ffi') | null | undefined
+
+function getBunFfiCodec(): typeof import('bun:ffi') | null {
+  if (bunFfiCodec === undefined) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      bunFfiCodec = require('bun:ffi') as typeof import('bun:ffi')
+    } catch {
+      bunFfiCodec = null
+    }
+  }
+  return bunFfiCodec
+}
+
+function createBunCodec(): Utf8Codec {
+  const decodeUtf8Bun = (bytes: Uint8Array): string => {
+    if (bytes.byteLength === 0) return ''
+    const ffi = getBunFfiCodec()
+    if (ffi) {
+      return new ffi.CString(ffi.ptr(bytes), 0, bytes.byteLength).toString()
+    }
+    return getNodeDecoder().decode(bytes)
+  }
+  return {
+    encodeUtf8(s: string): Uint8Array {
+      if (bunSink === null) bunSink = new Bun.ArrayBufferSink()
+      const sink = bunSink
+      // `stream` resets the buffer on flush (reusable singleton); `flush()`
+      // returns the written data as a `Uint8Array`.
+      sink.start({ asUint8Array: true, stream: true })
+      sink.write(s)
+      return sink.flush() as Uint8Array
+    },
+    encodeUtf8Into(s: string, dest: Uint8Array, offset = 0): number {
+      return bunEncodeUtf8Into(s, dest, offset)
+    },
+    decodeUtf8: decodeUtf8Bun,
+    // Bun's CString is replacement-mode; strictness is enforced by the native
+    // `castrum_utf8_valid` probe (callers check it first via the transport's
+    // ffi surface). This fallback matches the historical behavior.
+    decodeUtf8Fatal: decodeUtf8Bun,
+  }
+}
+
+// Cached zero-copy `Buffer` views keyed by the backing `ArrayBuffer`.
+//
+// `Buffer.write` requires a `Buffer` view; the historical implementation
+// created one with `Buffer.from(backing, start, len)` on EVERY call — an
+// object allocation on the hot path (the ingress packers encode the URL/IP
+// twice per request through this function). Caching the full-backing view per
+// `ArrayBuffer` (they are immutable-size in this codebase — the packers
+// replace the whole buffer on growth, giving a fresh `ArrayBuffer` key) turns
+// the per-call `Buffer.from` into a WeakMap hit.
+const bunEncodeViewCache = new WeakMap<ArrayBufferLike, Buffer>()
+
+/**
+ * Write `s` (UTF-8) into `dest` starting at `offset` and return bytes written.
+ *
+ * Fast path (the hot callers — the ingress input/header packers — pass `dest`
+ * as a subarray that extends to the END of its backing buffer): reuse the
+ * cached full-backing `Buffer` view and write at the absolute position — the
+ * write bound is then identical to the historical `Buffer.from(backing, start,
+ * len)` behaviour, so no bytes outside `dest` can be touched.
+ *
+ * When `dest` does NOT extend to the end of its backing (a mid-buffer slice),
+ * fall back to a bounded `subarray` so the truncation semantics match the
+ * original `Buffer.from(backing, start, len)` exactly.
+ */
+function bunEncodeUtf8Into(s: string, dest: Uint8Array, offset = 0): number {
+  const backing = dest.buffer
+  let view = bunEncodeViewCache.get(backing)
+  if (view === undefined || view.byteLength !== backing.byteLength) {
+    view = Buffer.from(backing)
+    bunEncodeViewCache.set(backing, view)
+  }
+  const start = dest.byteOffset + offset
+  if (dest.byteOffset + dest.byteLength !== backing.byteLength) {
+    // Non-suffix dest: bound the write to `dest` exactly (historical semantics).
+    return view.subarray(start, start + dest.byteLength - offset).write(s, 0, 'utf8')
+  }
+  return view.write(s, start, 'utf8')
+}
+
+// ── Node codec ────────────────────────────────────────────────────
+function createNodeCodec(): Utf8Codec {
+  return {
+    encodeUtf8(s: string): Uint8Array {
+      return getNodeEncoder().encode(s)
+    },
+    encodeUtf8Into(s: string, dest: Uint8Array, offset = 0): number {
+      return getNodeEncoder().encodeInto(s, dest.subarray(offset)).written
+    },
+    decodeUtf8(bytes: Uint8Array): string {
+      return getNodeDecoder().decode(bytes)
+    },
+    decodeUtf8Fatal(bytes: Uint8Array): string {
+      return getNodeFatalDecoder().decode(bytes)
+    },
+  }
+}
+
+/** Build the codec for a runtime (used by `createRuntimeAdapter` / tests). */
+export function createCodec(name: RuntimeName): Utf8Codec {
+  return name === 'bun' ? createBunCodec() : createNodeCodec()
+}
+
+/** The shared codec for the detected runtime (selected once at load). */
+export const runtimeCodec: Utf8Codec = createCodec(detectedRuntime)

package/src/runtime/detect.ts

@@ -0,0 +1,36 @@
+// src/runtime/detect.ts — one-time runtime detection (cached).
+//
+// The ONLY place `typeof Bun` is checked. The result is resolved ONCE at
+// module load into a constant — hot paths never re-evaluate the detection,
+// and `src/shared/runtime.ts` is a thin facade over this module so existing
+// `isBun()` / `isNode()` call sites keep working unchanged.
+
+import type { RuntimeName } from './types'
+
+function detectRuntimeName(): RuntimeName {
+  // Bun defines the global `Bun` object; Node does not.
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') return 'bun'
+  if (typeof process !== 'undefined' && process.versions?.node != null) return 'node'
+  return 'unknown'
+}
+
+/** The host runtime, resolved once at module load. */
+export const detectedRuntime: RuntimeName = detectRuntimeName()
+
+/** Whether the host runtime is Bun (equivalent to `detectedRuntime === "bun"`). */
+export function isBunRuntime(): boolean {
+  return detectedRuntime === 'bun'
+}
+
+/** Whether the host runtime is Node.js. */
+export function isNodeRuntime(): boolean {
+  return detectedRuntime === 'node'
+}
+
+/** The Node.js major version when running under Node, otherwise `null`. */
+export function nodeMajorVersion(): number | null {
+  if (detectedRuntime !== 'node') return null
+  const v = process.versions.node
+  const major = Number(v?.split('.')[0])
+  return Number.isFinite(major) ? major : null
+}

package/src/runtime/index.ts

@@ -0,0 +1,28 @@
+// src/runtime/index.ts — runtime adapter barrel (FULL adapter).
+//
+// Composes the FFI-facing runtime seam (`src/runtime/native.ts`) with the
+// platform server / websocket adapters (`src/runtime/server.ts` +
+// `websocket.ts`). The FFI layer imports the seam from `./native` (it never
+// pulls the ingress graph); the public API imports the full `runtime` from
+// here.
+
+import { runtimeNative } from './native'
+import { runtimeServer } from './server'
+import type { RuntimeAdapter } from './types'
+import { runtimeWebsocket } from './websocket'
+
+/** The full runtime adapter for the detected host runtime (native + server + websocket). */
+export const runtime: RuntimeAdapter = {
+  ...runtimeNative,
+  server: runtimeServer,
+  websocket: runtimeWebsocket,
+}
+
+// Runtime detection (cached) — the single place `typeof Bun` is checked.
+export { detectedRuntime, isBunRuntime, isNodeRuntime, nodeMajorVersion } from './detect'
+export { runtimeNative } from './native'
+// Runtime-driven server factory (Bun.serve on Bun, node:http on Node) — the
+// public `createIngressServer` (src/ingress/index.ts) re-exports this.
+export { createIngressServer } from './server'
+
+export type { RuntimeName } from './types'

package/src/runtime/native.ts

@@ -0,0 +1,35 @@
+// src/runtime/native.ts — the FFI-facing runtime seam.
+//
+// What the `rust-ffi` layer / selection / shared helpers consume: runtime
+// detection, UTF-8 codec, uuid, env resolution, the Bun built-in delegation
+// registry, and the native transport (bun:ffi vs napi). Importing this module
+// does NOT eagerly bind the ffi transport (lazy) and never pulls the ingress
+// graph, so `rust-ffi/*` can import it without a cycle.
+//
+// The FULL adapter (adding `server` + `websocket`) is composed in
+// `src/runtime/index.ts` / `src/runtime/server.ts` for the public API.
+
+import { resolveEnvVar } from '../shared/env'
+import { runtimeBuiltins } from './builtins'
+import { runtimeCodec } from './codec'
+import { detectedRuntime } from './detect'
+import { createTransport } from './transport'
+import type { NativeRuntimeAdapter } from './types'
+import { runtimeUuid } from './uuid'
+
+/**
+ * The shared runtime adapter (native seam) for the detected host runtime —
+ * codec / uuid / env / builtins / transport. The FULL adapter (adding
+ * `server` + `websocket`) is composed in `src/runtime/index.ts` for the
+ * public API; the FFI layer imports THIS seam so it never pulls the ingress
+ * graph.
+ */
+export const runtimeNative: NativeRuntimeAdapter = {
+  name: detectedRuntime,
+  isWebStandard: detectedRuntime === 'bun',
+  codec: runtimeCodec,
+  uuid: runtimeUuid,
+  env: { resolveVar: resolveEnvVar },
+  builtins: runtimeBuiltins,
+  transport: createTransport(),
+}

package/src/runtime/server.ts

@@ -0,0 +1,31 @@
+// src/runtime/server.ts — platform HTTP server adapter (Bun.serve / node:http).
+//
+// The SAME pre-baked ingress route handlers (`buildRouteHandlers`) are served
+// by `Bun.serve` on Bun (src/ingress/server.ts) and the `node:http` adapter on
+// Node (src/ingress/server-node.ts). Historically consumers had to pick
+// `createIngressServer` (Bun-only) vs `createIngressServerNode` explicitly;
+// this adapter lets the public `createIngressServer` pick the backend once,
+// at module load. Selected ONCE — the branch never runs in the hot path.
+
+import type { BakedServer, CreateIngressServerOptions } from '../ingress/server'
+import { createIngressServer as createIngressServerBun } from '../ingress/server'
+import { createIngressServerNode } from '../ingress/server-node'
+import { detectedRuntime } from './detect'
+import type { ServerAdapter } from './types'
+
+/** The shared server adapter for the detected host runtime. */
+export const runtimeServer: ServerAdapter = {
+  runtime: detectedRuntime === 'bun' ? 'bun' : 'node',
+  createIngressServer,
+}
+
+/**
+ * Create the runtime-appropriate ingress server: `Bun.serve` on Bun, the
+ * `node:http` adapter on Node. Selected ONCE at module load — the branch
+ * never runs in the hot path.
+ */
+export function createIngressServer(options: CreateIngressServerOptions): BakedServer {
+  return detectedRuntime === 'bun'
+    ? createIngressServerBun(options)
+    : createIngressServerNode(options)
+}

package/src/runtime/transport.ts

@@ -0,0 +1,64 @@
+// src/runtime/transport.ts — native transport adapter (bun:ffi primary, napi fallback).
+//
+// The SAME cdylib is reached two ways: the bun:ffi C-ABI transport
+// (`getBunFFI()`, PRIMARY under Bun — ~10-20ns crossing) and the napi addon
+// (`addon`, Node / forced `CASTRUM_FFI_MODE=napi` / failed ffi self-test).
+// Historically every scalar builder repeated `const ffi = getBunFFI();
+// if (ffi) return ffi.X(...); return addon.X(...)`. This adapter centralizes
+// that selection: `resolve(op)` returns the bound op (ffi-first, cached,
+// napi fallback), and the raw `ffi` / `napi` surfaces are exposed for the few
+// ops with transport-specific JS handling (jsonParse packed path, urlDecode
+// UTF-8 probe, packed unboxers).
+//
+// LAZY: the one-time ffi bind is deferred until the first `resolve` /
+// introspection, so importing the adapter does not eagerly dlopen.
+
+import type { BunFFI } from '../native/ffi'
+import { getBunFFI } from '../native/ffi'
+import { addon } from '../rust-ffi/addon'
+import type { NativeCallable, TransportAdapter } from './types'
+
+/**
+ * Build a native transport adapter: resolves native ops ffi-first (bun:ffi,
+ * cached) with the napi addon as the fallback. The one-time ffi bind is
+ * deferred until the first resolve / introspection — importing the adapter
+ * does not eagerly dlopen.
+ */
+export function createTransport(): TransportAdapter {
+  let cachedFfi: BunFFI | null | undefined // undefined = not yet attempted
+  const getFfi = (): BunFFI | null => {
+    if (cachedFfi === undefined) cachedFfi = getBunFFI()
+    return cachedFfi
+  }
+  const cache = new Map<string, NativeCallable>()
+
+  const resolve = (op: string): NativeCallable | undefined => {
+    let f = cache.get(op)
+    if (f === undefined) {
+      const ffiSurface = getFfi() as unknown as Record<string, unknown> | null
+      const candidate =
+        ffiSurface && typeof ffiSurface[op] === 'function'
+          ? (ffiSurface[op] as NativeCallable)
+          : (addon as unknown as Record<string, unknown>)[op]
+      if (typeof candidate !== 'function') return undefined
+      f = candidate as NativeCallable
+      cache.set(op, f)
+    }
+    return f
+  }
+
+  return {
+    get name(): 'ffi' | 'napi' {
+      return getFfi() !== null ? 'ffi' : 'napi'
+    },
+    get returnType(): 'string' | 'bytes' {
+      return getFfi() !== null ? 'string' : 'bytes'
+    },
+    get ffi(): BunFFI | null {
+      return getFfi()
+    },
+    napi: addon,
+    ffiActive: () => getFfi() !== null,
+    resolve,
+  }
+}

package/src/runtime/types.ts

@@ -0,0 +1,173 @@
+// src/runtime/types.ts — Runtime adapter contracts (Bun / Node).
+//
+// The single seam that centralizes every Bun-vs-Node and native-transport
+// decision: detection (detect.ts), UTF-8 codec, uuid, env, Bun built-in
+// delegation (builtins.ts), and the bun:ffi-vs-napi transport (transport.ts).
+// Modeled on Elysia's adapter (`ElysiaAdapterOptions` / `createAdapter`) but
+// internal-only, typed with concrete sub-objects (no string-union escape
+// hatch), and selected ONCE at module load — hot paths never re-check
+// `typeof Bun`.
+//
+// `src/runtime/native.ts` exposes the FFI-facing seam ({ name, codec, uuid,
+// env, builtins, transport }); `src/runtime/index.ts` composes the FULL
+// adapter (adding server + websocket in src/runtime/server.ts). Pure modules
+// must not import this boundary — take the functions they need via DI.
+
+import type { BakedServer, CreateIngressServerOptions } from '../ingress/server'
+import type { WebSocketUpgradeOptions, WebSocketUpgradeResult } from '../integration/websocket'
+import type { NativeAddon } from '../native'
+import type { BunFFI } from '../native/ffi'
+
+/** Host runtime identifier. */
+export type RuntimeName = 'bun' | 'node' | 'unknown'
+
+/** Runtime-native UTF-8 codec (Bun transfer machinery vs TextEncoder/TextDecoder). */
+export interface Utf8Codec {
+  /** Encode a string to UTF-8 bytes (fresh buffer). */
+  encodeUtf8(s: string): Uint8Array
+  /** Encode into `dest` starting at `offset`; returns bytes written (no split chars). */
+  encodeUtf8Into(s: string, dest: Uint8Array, offset?: number): number
+  /** Decode UTF-8 bytes to a string (replacement mode on invalid). */
+  decodeUtf8(bytes: Uint8Array): string
+  /** Decode UTF-8 bytes to a string, throwing on invalid UTF-8. */
+  decodeUtf8Fatal(bytes: Uint8Array): string
+}
+
+/** UUIDv7 generation (Bun built-in vs crypto.randomUUID on Node). */
+export interface UuidAdapter {
+  uuidv7(): string
+}
+
+/** Env-var resolution (CASTRUM_* preferred, napi-rs `NAPI_RS_*` aliases). */
+export interface EnvAdapter {
+  resolveVar(preferred: string, legacy: readonly string[]): string | undefined
+}
+
+/** A bound native callable (bun:ffi C-ABI or napi addon). */
+export type NativeCallable = (...args: unknown[]) => unknown
+
+/**
+ * Native transport: the SAME cdylib accessed via bun:ffi (C-ABI, PRIMARY on
+ * Bun) or napi (Node / fallback). `resolve(op)` returns the bound op
+ * (ffi-first, cached, napi fallback) so hot call sites have no per-call
+ * `getBunFFI()` branch.
+ */
+export interface TransportAdapter {
+  /** Active transport: `"ffi"` (bun:ffi live) or `"napi"`. */
+  readonly name: 'ffi' | 'napi'
+  /** Native text-return contract: `"string"` on the ffi path, `"bytes"` on napi. */
+  readonly returnType: 'string' | 'bytes'
+  /** The raw bun:ffi surface when live, else `null` (for ops with ffi-specific JS handling). */
+  readonly ffi: BunFFI | null
+  /** The napi addon proxy (lazy — first native call triggers the dlopen). */
+  readonly napi: NativeAddon
+  /** Whether the bun:ffi transport is live (equivalent to `name === "ffi"`). */
+  ffiActive(): boolean
+  /** Bound op callable (ffi-first, napi fallback), or `undefined` for unknown ops. */
+  resolve(op: string): NativeCallable | undefined
+}
+
+/**
+ * Bun built-in delegation registry (the `BUN_WINS` set). Single source of
+ * truth for "under Bun this op is faster as a built-in than via the addon".
+ * On Node the registry is empty (`has()` is false) so builders fall through
+ * to the native transport.
+ *
+ * `ops` is the exported op-name list; `selection.ts` derives its BUN_WINS
+ * decision from `has(op)` so the hardcoded set + `isBun()` branch disappear.
+ */
+export interface BuiltinsAdapter {
+  /** Op names this runtime delegates to built-ins (empty on Node). */
+  readonly ops: readonly string[]
+  /** Whether `op` has a built-in delegation on this runtime. */
+  has(op: string): boolean
+
+  // ── The delegated ops (bytes-in scalar surface, Bun contracts) ──
+  crc32(input: Uint8Array): number
+  xxh3(input: Uint8Array): bigint
+  /** HMAC-SHA256 → lowercase-hex STRING on Bun. */
+  hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | string
+  gzipCompress(data: Uint8Array, level?: number | null): Uint8Array
+  /** Random hex token (2n chars) with the 16 MiB guard. */
+  randomToken(byteLen: number): Uint8Array | string
+  /** Standard padded base64 only; `undefined` when url-safe/unpadded (falls to native). */
+  base64Encode(
+    input: Uint8Array,
+    urlSafe?: boolean,
+    padding?: boolean,
+  ): Uint8Array | string | undefined
+  base64UrlEncode(input: Uint8Array): Uint8Array | string
+  hexEncode(input: Uint8Array): Uint8Array | string
+  /** Percent-encode bytes → percent-encoded STRING. */
+  urlEncode(input: Uint8Array): string
+  /** Percent-decode bytes → bytes. */
+  urlDecode(input: Uint8Array): Uint8Array
+  /** String-in percent-encode (`encodeURIComponent`). */
+  urlEncodeStr(input: string): string
+  /** String-in percent-decode (`decodeURIComponent`). */
+  urlDecodeStr(input: string): string
+  /** RFC 1123 IMF-fixdate STRING for `secs` (default now). */
+  httpDate(secs?: number): string
+}
+
+/**
+ * Platform HTTP server adapter. `createIngressServer` builds a `Bun.serve`
+ * server on Bun and the `node:http` adapter on Node — the SAME pre-baked
+ * route handlers (shared `buildRouteHandlers`) either way. The explicit
+ * `createIngressServerNode` stays exported for consumers who want the Node
+ * backend pinned.
+ */
+export interface ServerAdapter {
+  /** The backend this adapter targets. */
+  readonly runtime: 'bun' | 'node'
+  createIngressServer(options: CreateIngressServerOptions): BakedServer
+}
+
+/**
+ * Platform WebSocket adapter. `createWebSocketUpgrade` returns the RFC 6455
+ * 101 handshake on Bun (whose `Response` can carry status 101) and throws a
+ * clear Bun-only error on Node (which must use the server-node `upgrade`
+ * option instead).
+ */
+export interface WebsocketAdapter {
+  createWebSocketUpgrade(
+    req: Request,
+    opts?: WebSocketUpgradeOptions,
+  ): WebSocketUpgradeResult | null
+}
+
+/**
+ * The runtime adapter — the single seam centralizing every Bun-vs-Node and
+ * native-transport decision. Selected ONCE at module load (`src/runtime`).
+ * `src/runtime/native.ts` composes the FFI-facing subset
+ * ({@link NativeRuntimeAdapter}); the FULL adapter additionally carries
+ * `server` + `websocket` (composed in `src/runtime/index.ts` for the public
+ * API).
+ */
+export interface RuntimeAdapter {
+  /** Host runtime (cached at load — never re-checked in hot paths). */
+  readonly name: RuntimeName
+  /** Whether the runtime speaks the web-standard Request/Response surface. */
+  readonly isWebStandard: boolean
+  /** Runtime-native UTF-8 codec. */
+  readonly codec: Utf8Codec
+  /** UUIDv7 generation. */
+  readonly uuid: UuidAdapter
+  /** Env-var alias resolution. */
+  readonly env: EnvAdapter
+  /** Bun built-in delegation registry (empty on Node). */
+  readonly builtins: BuiltinsAdapter
+  /** Native transport (bun:ffi primary, napi fallback). */
+  readonly transport: TransportAdapter
+  /** Platform HTTP server (Bun.serve on Bun, node:http on Node). */
+  readonly server: ServerAdapter
+  /** Platform WebSocket 101 handshake (Bun-only). */
+  readonly websocket: WebsocketAdapter
+}
+
+/**
+ * The FFI-facing runtime subset (no server/websocket) — what the `rust-ffi`
+ * layer / selection / shared helpers import, so the native seam never pulls
+ * the ingress graph.
+ */
+export type NativeRuntimeAdapter = Omit<RuntimeAdapter, 'server' | 'websocket'>