castrum 0.9.0 → 0.9.1

package/src/runtime/uuid.ts

@@ -0,0 +1,45 @@
+// src/runtime/uuid.ts — UUIDv7 generation (Bun built-in, Node fallback).
+//
+// Deliberately does NOT implement UUIDv7 in Rust: the decision matrix measured
+// `Bun.randomUUIDv7` ~2x faster than the FFI-crossing rust random-token path,
+// so this delegates to the Bun built-in and falls back to
+// `crypto.randomUUID` (RFC 4122 v4) under Node. Formerly in
+// `src/shared/uuid.ts`; the branches now live here, selected once at load.
+
+import { detectedRuntime } from './detect'
+import type { UuidAdapter } from './types'
+
+/** Last-resort synchronous UUIDv4 (only if `crypto.randomUUID` is unavailable). */
+function fallbackRandomUuid(): string {
+  const bytes = new Uint8Array(16)
+  const c = globalThis.crypto
+  if (c?.getRandomValues) {
+    c.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)
+  }
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40 // version 4
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80 // variant 10xx
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+function bunUuidv7(): string {
+  return (
+    (globalThis as { Bun?: { randomUUIDv7?: () => string } }).Bun?.randomUUIDv7?.() ??
+    globalThis.crypto?.randomUUID?.() ??
+    fallbackRandomUuid()
+  )
+}
+
+function nodeUuidv7(): string {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackRandomUuid()
+}
+
+/** Build the uuid adapter for a runtime. */
+export function createUuidAdapter(name: 'bun' | 'node' | 'unknown'): UuidAdapter {
+  return name === 'bun' ? { uuidv7: bunUuidv7 } : { uuidv7: nodeUuidv7 }
+}
+
+/** The shared uuid adapter for the detected runtime (selected once at load). */
+export const runtimeUuid: UuidAdapter = createUuidAdapter(detectedRuntime)

package/src/runtime/websocket.ts

@@ -0,0 +1,30 @@
+// src/runtime/websocket.ts — platform WebSocket upgrade 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
+// (whose fetch `Response` rejects 101 — Node users must use the server-node
+// `upgrade` option instead). The handshake computation lives in
+// `src/integration/websocket.ts`; this adapter owns the runtime branch.
+
+import type { WebSocketUpgradeOptions, WebSocketUpgradeResult } from '../integration/websocket'
+import { createWebSocketUpgrade as buildBunUpgrade } from '../integration/websocket'
+import { detectedRuntime } from './detect'
+import type { WebsocketAdapter } from './types'
+
+const BUN_ONLY_ERROR =
+  "createWebSocketUpgrade is Bun-only: Node's Response cannot carry status 101. " +
+  "On Node, use createIngressServerNode's `upgrade` option and compute the " +
+  'accept key with rust.text.wsAcceptKey().'
+
+/** The shared websocket adapter for the detected host runtime. */
+export const runtimeWebsocket: WebsocketAdapter = {
+  createWebSocketUpgrade(
+    req: Request,
+    opts?: WebSocketUpgradeOptions,
+  ): WebSocketUpgradeResult | null {
+    if (detectedRuntime !== 'bun') {
+      throw new Error(BUN_ONLY_ERROR)
+    }
+    return buildBunUpgrade(req, opts)
+  },
+}

package/src/rust-ffi/addon.ts

@@ -4,7 +4,7 @@
 // module does NOT dlopen the addon — the first native call triggers loading
 // exactly once.
 
-import { lazyAddon, getAddon, type NativeAddon } from '../native'
+import { getAddon, lazyAddon, type NativeAddon } from '../native'
 
 /** The shared lazy addon proxy (typed as the full native surface). */
 export const addon: NativeAddon = lazyAddon(getAddon)

package/src/rust-ffi/batch/build.ts

@@ -0,0 +1,155 @@
+// src/rust-ffi/batch/build.ts — `buildBatch` implementation.
+//
+// Packs an array of byte slices into the packed wire format, calls the native
+// batch function, and unpacks the result into the friendly JS shape. Each
+// method wires one `RustBatch` (./types.ts) member to its `*BatchPacked` napi
+// fn via the shared pool-native resolver (context.ts).
+//
+// The `via` / `via2` builders below collapse the pack → native → unpack
+// plumbing every bulk op shares; each public method keeps its exact signature,
+// so the table stays type-safe against `RustBatch`.
+
+import {
+  schemaValidateBatch,
+  schemaValidateBatchCount,
+  unpackBitset,
+  unpackByteResults,
+  unpackI64ArrayAsBigInt,
+  unpackMultipartParts,
+  unpackU32Array,
+  unpackU64ArrayAsBigInt,
+  withPackScratch,
+  withPackScratch2,
+} from '../../shared/packed'
+import { type RustClientContext, resolvePoolNative } from '../context'
+import type { RustBatch } from './types'
+
+// Native batch fns are process-wide singletons (one lazy addon). `resolvePoolNative`
+// resolves each once (triggering pool init + addon load on first use) and caches
+// it, so the hot path skips the lazy-addon Proxy get on every call — the same
+// cache `resolveNative`/packed use (context.ts), with pool init for the
+// rayon-backed batch surface.
+function nativeFn(ctx: RustClientContext, name: string): (...args: unknown[]) => unknown {
+  return resolvePoolNative(ctx, name)
+}
+
+/**
+ * Build a single-list bulk op: `withPackScratch(items)` →
+ * `unpack(native(packed, ...extras))`. `R` is inferred from `unpack`, so the
+ * result stays assignable to the matching `RustBatch` method.
+ */
+function via<R>(
+  ctx: RustClientContext,
+  name: string,
+  unpack: (bytes: Uint8Array) => R,
+  extras: unknown[] = [],
+): (items: Uint8Array[]) => R {
+  return (items) =>
+    withPackScratch(items, (packed) => unpack(nativeFn(ctx, name)(packed, ...extras) as Buffer))
+}
+
+/**
+ * Build a two-list bulk op (docs+patches, items+sigs, ...): `withPackScratch2(a, b)`
+ * → `unpack(native(packedA, packedB, ...extras))`.
+ */
+function via2<R>(
+  ctx: RustClientContext,
+  name: string,
+  unpack: (bytes: Uint8Array) => R,
+  extras: unknown[] = [],
+): (a: Uint8Array[], b: Uint8Array[]) => R {
+  return (a, b) =>
+    withPackScratch2(a, b, (packedA, packedB) =>
+      unpack(nativeFn(ctx, name)(packedA, packedB, ...extras) as Buffer),
+    )
+}
+
+/** Build the `batch` namespace for a client context. */
+export function buildBatch(ctx: RustClientContext): RustBatch {
+  return {
+    // ── Single-list, no extras ──
+    jsonValid: via(ctx, 'jsonValidBatchPacked', unpackBitset),
+    crc32: via(ctx, 'crc32BatchPacked', unpackU32Array),
+    validateEmail: via(ctx, 'validateEmailBatchPacked', unpackBitset),
+    validateUuid: via(ctx, 'validateUuidBatchPacked', unpackBitset),
+    validateIpv4: via(ctx, 'validateIpv4BatchPacked', unpackBitset),
+    validateIpv6: via(ctx, 'validateIpv6BatchPacked', unpackBitset),
+    jsonSumIds: via(ctx, 'jsonSumBatchPacked', unpackI64ArrayAsBigInt),
+    queryParse: via(ctx, 'queryParseBatchPacked', unpackByteResults),
+    cookieParse: via(ctx, 'cookieParseBatchPacked', unpackByteResults),
+    formParse: via(ctx, 'formParseBatchPacked', unpackByteResults),
+    signCookie: (items, secret) =>
+      via(ctx, 'signCookieBatchPacked', unpackByteResults, [secret])(items),
+    verifyCookie: (items, secret) =>
+      via(ctx, 'verifyCookieBatchPacked', unpackBitset, [secret])(items),
+    csrfVerify: (items, secret) =>
+      via(ctx, 'csrfVerifyBatchPacked', unpackBitset, [secret])(items),
+    httpParseRequest: via(ctx, 'httpParseRequestBatchPacked', unpackByteResults),
+    fnv1a64: via(ctx, 'fnv1A64BatchPacked', unpackU64ArrayAsBigInt),
+    etag: (items, weak) => via(ctx, 'etagBatchPacked', unpackByteResults, [weak ?? null])(items),
+    urlEncode: via(ctx, 'urlEncodeBatchPacked', unpackByteResults),
+    urlDecode: via(ctx, 'urlDecodeBatchPacked', unpackByteResults),
+    urlDecodeBytes: via(ctx, 'urlDecodeBytesBatchPacked', unpackByteResults),
+    mimeFromExtension: via(ctx, 'mimeFromExtensionBatchPacked', unpackByteResults),
+    wsAcceptKey: via(ctx, 'wsAcceptKeyBatchPacked', unpackByteResults),
+    base64UrlEncode: (items) =>
+      via(ctx, 'base64EncodeBatchPacked', unpackByteResults, [true, false])(items),
+    base64UrlDecode: (items) =>
+      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [true, false])(items),
+    jsonPatch: (docs, patches) => via2(ctx, 'jsonPatchBatchPacked', unpackByteResults)(docs, patches),
+    hexEncode: via(ctx, 'hexEncodeBatchPacked', unpackByteResults),
+    hexDecode: via(ctx, 'hexDecodeBatchPacked', unpackByteResults),
+    base64Encode: (items, urlSafe, padding) =>
+      via(ctx, 'base64EncodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(items),
+    base64Decode: (items, urlSafe, padding) =>
+      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(items),
+    schemaValidate(validator, items) {
+      return schemaValidateBatch(validator, items)
+    },
+    schemaValidateCount(validator, items) {
+      return schemaValidateBatchCount(validator, items)
+    },
+
+    // ── Backend-framework features ──
+    passwordHash: (passwords, salt, options) =>
+      via(ctx, 'passwordHashBatchPacked', unpackByteResults, [salt, options ?? null])(passwords),
+    aeadEncrypt: (key, nonce, items, algorithm) =>
+      via(ctx, 'aeadEncryptBatchPacked', unpackByteResults, [key, nonce, algorithm ?? null])(items),
+    aeadDecrypt: (key, nonce, items, algorithm) =>
+      via(ctx, 'aeadDecryptBatchPacked', unpackByteResults, [key, nonce, algorithm ?? null])(items),
+    gzipCompress: (items, level) =>
+      via(ctx, 'gzipCompressBatchPacked', unpackByteResults, [level ?? null])(items),
+    gzipDecompress: (items, maxDecompressed) =>
+      via(ctx, 'gzipDecompressBatchPacked', unpackByteResults, [maxDecompressed ?? null])(items),
+    brotliCompress: (items, quality) =>
+      via(ctx, 'brotliCompressBatchPacked', unpackByteResults, [quality ?? null])(items),
+    brotliDecompress: (items, maxDecompressed) =>
+      via(ctx, 'brotliDecompressBatchPacked', unpackByteResults, [maxDecompressed ?? null])(items),
+    jwtVerify: (tokens, secret, nowSeconds) =>
+      via(ctx, 'jwtVerifyBatchPacked', unpackBitset, [secret, nowSeconds])(tokens),
+    hmacSha256: (items, key) => via(ctx, 'hmacSha256BatchPacked', unpackByteResults, [key])(items),
+    hmacSha256Verify: (items, sigs, key) =>
+      via2(ctx, 'hmacSha256VerifyBatchPacked', unpackBitset, [key])(items, sigs),
+    // ── Two-list ──
+    passwordVerify: (items, phcs) => via2(ctx, 'passwordVerifyBatchPacked', unpackBitset)(items, phcs),
+    urlResolve: (bases, references) =>
+      via2(ctx, 'urlResolveBatchPacked', unpackByteResults)(bases, references),
+    templateRender: (source, contexts) =>
+      via(ctx, 'templateRenderBatchPacked', unpackByteResults, [source])(contexts),
+    jwtSign: (items, secret, ttlSeconds, nowSeconds) =>
+      via(ctx, 'jwtSignBatchPacked', unpackByteResults, [
+        secret,
+        ttlSeconds ?? null,
+        nowSeconds ?? Math.floor(Date.now() / 1000),
+      ])(items),
+    sseEncode: (items, event, id, retry) =>
+      via(ctx, 'sseEncodeBatchPacked', unpackByteResults, [event ?? null, id ?? null, retry ?? null])(
+        items,
+      ),
+    wsFrameEncode: (items, opcode, mask, fin) =>
+      via(ctx, 'wsFrameEncodeBatchPacked', unpackByteResults, [opcode, mask, fin])(items),
+    wsFrameDecode: via(ctx, 'wsFrameDecodeBatchPacked', unpackByteResults),
+    multipartParse: (items, boundary) =>
+      via(ctx, 'multipartParseBatchPacked', unpackMultipartParts, [boundary])(items),
+  }
+}

package/src/rust-ffi/batch/index.ts

@@ -0,0 +1,8 @@
+// src/rust-ffi/batch/index.ts — Array-of-bytes batch namespace (barrel).
+//
+// Re-exports the `RustBatch` interface (./types.ts) and its builder
+// (./build.ts) so existing `import { buildBatch, type RustBatch } from
+// '../rust-ffi/batch'` call sites keep working.
+
+export { buildBatch } from './build'
+export type { RustBatch } from './types'

package/src/rust-ffi/batch/types.ts

@@ -0,0 +1,92 @@
+// src/rust-ffi/batch/types.ts — Array-of-bytes batch namespace type.
+//
+// The `RustBatch` interface — the friendly JS shape of `rust.batch.*`
+// (bitsets, u32 arrays, i64 arrays, byte results) — separated from the
+// implementation (./build.ts) so type-only consumers don't pull the native
+// resolver.
+
+import type { MultipartPart, PasswordHashOptions } from '../../native'
+import type { SchemaValidator } from '../../shared/packed'
+
+/**
+ * The `rust.batch.*` array-of-bytes batch surface: N items in → one packed
+ * native call → bitsets / typed arrays / byte arrays out. Separated from the
+ * implementation (`./build.ts`) so type-only consumers don't pull the native
+ * resolver.
+ */
+export interface RustBatch {
+  jsonValid(items: Uint8Array[]): Uint8Array
+  crc32(items: Uint8Array[]): Uint32Array
+  validateEmail(items: Uint8Array[]): Uint8Array
+  validateUuid(items: Uint8Array[]): Uint8Array
+  validateIpv4(items: Uint8Array[]): Uint8Array
+  validateIpv6(items: Uint8Array[]): Uint8Array
+  jsonSumIds(items: Uint8Array[]): BigInt64Array
+  queryParse(items: Uint8Array[]): Uint8Array[]
+  cookieParse(items: Uint8Array[]): Uint8Array[]
+  httpParseRequest(items: Uint8Array[]): Uint8Array[]
+  jsonPatch(docs: Uint8Array[], patches: Uint8Array[]): Uint8Array[]
+  hexEncode(items: Uint8Array[]): Uint8Array[]
+  hexDecode(items: Uint8Array[]): Uint8Array[]
+  base64Encode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  base64Decode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  formParse(items: Uint8Array[]): Uint8Array[]
+  signCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array[]
+  verifyCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  csrfVerify(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  schemaValidate(validator: SchemaValidator, items: Uint8Array[]): Uint8Array
+  schemaValidateCount(validator: SchemaValidator, items: Uint8Array[]): number
+  fnv1a64(items: Uint8Array[]): BigUint64Array
+  etag(items: Uint8Array[], weak?: boolean | null): Uint8Array[]
+  urlEncode(items: Uint8Array[]): Uint8Array[]
+  urlDecode(items: Uint8Array[]): Uint8Array[]
+  urlDecodeBytes(items: Uint8Array[]): Uint8Array[]
+  mimeFromExtension(items: Uint8Array[]): Uint8Array[]
+  wsAcceptKey(items: Uint8Array[]): Uint8Array[]
+  base64UrlEncode(items: Uint8Array[]): Uint8Array[]
+  base64UrlDecode(items: Uint8Array[]): Uint8Array[]
+
+  // ── Backend-framework features ──
+  passwordHash(
+    passwords: Uint8Array[],
+    salt: Uint8Array,
+    options?: PasswordHashOptions | null,
+  ): Uint8Array[]
+  aeadEncrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    items: Uint8Array[],
+    algorithm?: string | null,
+  ): Uint8Array[]
+  aeadDecrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    items: Uint8Array[],
+    algorithm?: string | null,
+  ): Uint8Array[]
+  gzipCompress(items: Uint8Array[], level?: number | null): Uint8Array[]
+  gzipDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[]
+  brotliCompress(items: Uint8Array[], quality?: number | null): Uint8Array[]
+  brotliDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[]
+  jwtVerify(tokens: Uint8Array[], secret: Uint8Array, nowSeconds: number): Uint8Array
+  hmacSha256(items: Uint8Array[], key: Uint8Array): Uint8Array[]
+  hmacSha256Verify(items: Uint8Array[], sigs: Uint8Array[], key: Uint8Array): Uint8Array
+  passwordVerify(items: Uint8Array[], phcs: Uint8Array[]): Uint8Array
+  urlResolve(bases: Uint8Array[], references: Uint8Array[]): Uint8Array[]
+  jwtSign(
+    items: Uint8Array[],
+    secret: Uint8Array,
+    ttlSeconds?: number | null,
+    nowSeconds?: number,
+  ): Uint8Array[]
+  sseEncode(
+    items: Uint8Array[],
+    event?: string | null,
+    id?: string | null,
+    retry?: number | null,
+  ): Uint8Array[]
+  wsFrameEncode(items: Uint8Array[], opcode: number, mask: boolean, fin: boolean): Uint8Array[]
+  wsFrameDecode(items: Uint8Array[]): Uint8Array[]
+  multipartParse(items: Uint8Array[], boundary: Uint8Array): MultipartPart[][]
+  templateRender(source: string, contexts: Uint8Array[]): Uint8Array[]
+}

package/src/rust-ffi/client.ts

@@ -3,13 +3,12 @@
 // Composes the per-namespace builders (scalar / text / batch / packed) over a
 // shared per-instance context (./context.ts) and exposes `configure`.
 
-import { createContext } from './context'
-import { buildText, type RustText } from './text'
 import { buildBatch, type RustBatch } from './batch'
+import { createContext } from './context'
+import type { RustOptions } from './options'
 import { buildPacked, type RustPacked } from './packed'
 import { buildScalar, type RustScalar } from './scalar'
-import { getBunFFI } from '../native/ffi'
-import type { RustOptions } from './options'
+import { buildText, type RustText } from './text'
 
 /** The full Rust FFI client (scalar methods + namespaces + configuration). */
 export interface RustClient extends RustScalar {
@@ -56,10 +55,10 @@ export function createRust(options: RustOptions = {}): RustClient {
 
     // ── Transport introspection (FFI-primary on Bun; napi is the fallback) ──
     transport() {
-      return getBunFFI() !== null ? 'ffi' : 'napi'
+      return ctx.runtime.transport.name
     },
     ffiActive() {
-      return getBunFFI() !== null
+      return ctx.runtime.transport.ffiActive()
     },
 
     // ── Configuration ──

package/src/rust-ffi/context.ts

@@ -6,11 +6,13 @@
 // (initialized flag / pending thread count) stays encapsulated behind accessor
 // functions so it cannot be corrupted externally.
 
+import type { HmacSignerInstance } from '../native'
+import type { BunFFI } from '../native/ffi'
+import { runtimeNative } from '../runtime/native'
+import type { NativeRuntimeAdapter, TransportAdapter } from '../runtime/types'
 import { addon } from './addon'
-import { resolveRayonThreads } from './options'
-import { normalizeExt } from './options'
 import type { RustOptions } from './options'
-import type { HmacSignerInstance } from '../native'
+import { normalizeExt, resolveRayonThreads } from './options'
 
 // Module-level cache of resolved native fns. The native addon is a process
 // singleton, so the resolved function is identical across all client contexts;
@@ -20,9 +22,11 @@ import type { HmacSignerInstance } from '../native'
 const nativeFnCache = new Map<string, unknown>()
 
 /**
- * Resolve a native addon function on first use and cache it for all subsequent
- * calls. Preserves the lazy-load contract (the addon is only loaded on the
- * first real native call) while removing per-call Proxy overhead.
+ * Resolve a native op on first use and cache it for all subsequent calls —
+ * FFI-FIRST via the runtime adapter's transport (`bun:ffi` on Bun, napi
+ * fallback otherwise), so builders no longer repeat `getBunFFI()` inline.
+ * Preserves the lazy-load contract (the addon is only loaded on the first
+ * real native call) while removing per-call Proxy overhead.
  */
 export function resolveNative(
   ctx: RustClientContext,
@@ -30,7 +34,8 @@ export function resolveNative(
 ): (...args: unknown[]) => unknown {
   let f = nativeFnCache.get(name)
   if (f === undefined) {
-    f = (ctx.addon as unknown as Record<string, unknown>)[name]
+    const fn = ctx.runtime.transport.resolve(name)
+    f = fn ?? (ctx.addon as unknown as Record<string, unknown>)[name]
     nativeFnCache.set(name, f)
   }
   return f as (...args: unknown[]) => unknown
@@ -42,7 +47,8 @@ export function resolveNative(
  * `resolveNative` (plain scalars) must NOT init the pool so
  * `rust.configure({ rayonThreads })` can still take effect at startup.
  * Shares the SAME `nativeFnCache` as `resolveNative` (the batch fn names are
- * disjoint from the scalar names, so the shared cache is safe).
+ * disjoint from the scalar names, so the shared cache is safe). FFI-first via
+ * the runtime adapter's transport, like `resolveNative`.
  */
 export function resolvePoolNative(
   ctx: RustClientContext,
@@ -51,16 +57,38 @@ export function resolvePoolNative(
   let f = nativeFnCache.get(name)
   if (f === undefined) {
     ctx.ensurePool()
-    f = (ctx.addon as unknown as Record<string, unknown>)[name]
+    const fn = ctx.runtime.transport.resolve(name)
+    f = fn ?? (ctx.addon as unknown as Record<string, unknown>)[name]
     nativeFnCache.set(name, f)
   }
   return f as (...args: unknown[]) => unknown
 }
 
+/**
+ * Lazy memoized `bun:ffi` resolver for the scalar builders.
+ *
+ * Returns a closure that resolves `transport.ffi` ONCE — on the first call —
+ * and reads the local from then on. This keeps the FFI bind DEFERRED
+ * (importing `rust` does not eagerly dlopen; the builder factories run at
+ * module load) while removing the per-call `() => transport.ffi` getter hop
+ * from the hot path. The transport's own cache already makes the steady-state
+ * resolve a single `undefined`-check; this collapses the getter + inner
+ * closure into one local read.
+ */
+export function memoizeFfi(transport: TransportAdapter): () => BunFFI | null {
+  let resolved: BunFFI | null | undefined
+  return () => {
+    if (resolved === undefined) resolved = transport.ffi
+    return resolved
+  }
+}
+
 /** Shared per-instance state passed to the namespace/scalar builders. */
 export interface RustClientContext {
-  /** The shared lazy addon proxy. */
+  /** The shared lazy addon proxy (napi surface). */
   addon: typeof addon
+  /** The runtime adapter seam (Bun/Node — builtins + ffi/napi transport). */
+  runtime: NativeRuntimeAdapter
   /** Per-instance toggles (mime/hmac caching). */
   state: { mimeCache: boolean; hmacCache: boolean }
   mimeByText: Map<string, Uint8Array>
@@ -151,6 +179,7 @@ export function createContext(options: RustOptions): RustClientContext {
 
   return {
     addon,
+    runtime: runtimeNative,
     state,
     mimeByText,
     hmacSigners,

package/src/rust-ffi/index.ts

@@ -26,29 +26,40 @@
 //   rust.packed.jsonValidBatchPacked(p);  // raw packed in/out
 //   rust.configure({ rayonThreads: 8 });  // override defaults
 
-export { createRust, rust } from './client'
-export type { RustClient } from './client'
-export type { RustOptions } from './options'
-export type { RustText } from './text'
-export type { RustBatch } from './batch'
-export type { RustPacked } from './packed'
-export type { SchemaValidator } from '../shared/packed'
 export type {
-  HmacSignerInstance,
-  SchemaValidatorInstance,
-  SchemaError,
-  TemplateRendererInstance,
-  FormParserInstance,
-  MediaTypeParserInstance,
-  MediaTypeResult,
-  ConditionalRequestInstance,
-  EncodingPrefResult,
   AcceptNegotiatorInstance,
   Base64CodecInstance,
+  ConditionalRequestInstance,
   CookieSignerInstance,
   CsrfProtectorInstance,
-  UrlBuilderInstance,
+  EncodingPrefResult,
+  FormParserInstance,
+  HmacSignerInstance,
+  MediaTypeParserInstance,
+  MediaTypeResult,
   MultipartPart,
   PasswordHashOptions,
+  SchemaError,
+  SchemaValidatorInstance,
+  TemplateRendererInstance,
+  UrlBuilderInstance,
   WsFrame,
 } from '../native'
+export type { SchemaValidator } from '../shared/packed'
+export type { RustBatch } from './batch'
+export type { RustClient } from './client'
+export { createRust, rust } from './client'
+export { proven } from './proven'
+export {
+  PROVEN_SELECTION,
+  isProven,
+  provenEntry,
+  provenImpl,
+  provenStatus,
+  provenSummary,
+  provenSurface,
+} from '../shared/proven'
+export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'
+export type { RustOptions } from './options'
+export type { RustPacked } from './packed'
+export type { RustText } from './text'

package/src/rust-ffi/into.ts

@@ -0,0 +1,21 @@
+// src/rust-ffi/into.ts — pooled `*Into` output-write helper (napi fallback).
+
+/**
+ * Write `bytes` into a caller-owned `output` buffer, or throw when it does not
+ * fit.
+ *
+ * Shared tail of the pooled (`*Into`) napi-fallback paths: every op copies the
+ * allocating result into the caller buffer with the same capacity check, error
+ * message, and byte-length return. The bun:ffi `_into` path never reaches this
+ * helper — the C ABI streams straight into `output`.
+ *
+ * @param op Label for the error message (e.g. `"gzip compress"`).
+ * @param output The caller-owned destination buffer.
+ * @param bytes The allocating op result to copy in.
+ * @returns The number of bytes written (`bytes.length`).
+ */
+export function writeInto(op: string, output: Uint8Array, bytes: Uint8Array): number {
+  if (output.length < bytes.length) throw new Error(`${op}: output buffer too small`)
+  output.set(bytes)
+  return bytes.length
+}

package/src/rust-ffi/options.ts

@@ -51,7 +51,7 @@ export function resolveRayonThreads(explicit?: number): number {
   }
 
   const envThreads = Number(
-    resolveEnvVar('CASTRUM_RAYON_THREADS', ['RUST_BENCH_RAYON_THREADS', 'RUST_RAYON_THREADS']),
+    resolveEnvVar('CASTRUM_RAYON_THREADS'),
   )
 
   if (Number.isFinite(envThreads) && envThreads > 0) {

package/src/rust-ffi/packed.ts

@@ -3,9 +3,9 @@
 // `rust.packed.*` is the zero-copy API: callers pass already-packed buffers and
 // receive the raw packed output, plus the batch metadata/count helpers.
 
-import { asNumber } from './options'
-import { resolvePoolNative, type RustClientContext } from './context'
 import type { PasswordHashOptions } from '../native'
+import { type RustClientContext, resolvePoolNative } from './context'
+import { asNumber } from './options'
 
 /** Raw packed-wire FFI namespace. */
 export interface RustPacked {

package/src/rust-ffi/proven.ts

@@ -1,42 +1,28 @@
-// src/rust-ffi/proven.ts — The performance-annotated export surface.
+// src/rust-ffi/proven.ts — the baked "proven selection" surface.
 //
-// `proven` exposes the FULL `rust.*` surface. Each exported function's JSDoc
-// carries its measured performance vs the native JS baseline, annotated from
-// the CPU benchmark report by `scripts/annotate-performance.ts` (run via
-// `bun run check:annotate`). Functions that are SLOWER than the JS baseline
-// (e.g. `jsonParse` vs Bun's JSON.parse, or schema validation vs ajv) are
-// marked `@deprecated`.
-//
-// The registry (`src/shared/proven.ts`) is the single source of truth for the
-// annotations; `bun run check:proven` audits it against the latest benchmark
-// report (with `--fail` to gate CI).
+// `proven` re-exposes the FULL `rust.*` surface (identical object) alongside
+// the pure-data registry (`src/shared/proven.ts`) that states which
+// implementation is the benchmark-proven winner for every op: 'native',
+// 'js', or 'bun' (Bun built-in delegation). The winners are BAKED (committed,
+// benchmark-derived) and verified by `test/unit/shared/proven.test.ts` — no
+// live benchmark audit and no `@deprecated` JSDoc machinery (the old
+// `check:proven` / `check:annotate` friction, intentionally not re-added).
 
 import { rust, type RustClient } from './client'
 
-/**
- * The performance-annotated client: the full {@link RustClient} surface.
- * Each exported function's JSDoc notes its measured performance vs the JS
- * baseline; functions slower than the baseline carry `@deprecated`.
- */
+/** The full `rust.*` surface — identical to `rust`; the proven wiring is baked (see {@link ../shared/proven}). */
 export type ProvenClient = RustClient
 
-/**
- * The full `rust.*` surface with benchmark-annotated JSDoc. Identical to
- * `rust` — the annotations and `@deprecated` markers are what communicate
- * performance now, not a curated subset.
- */
+/** The full `rust.*` surface, exposed for audit. Same object as `rust`. */
 export const proven: ProvenClient = rust
 
-// Re-export the registry + helpers so consumers can audit the surface.
 export {
-  PROVEN_SURFACE,
-  provenStatus,
+  PROVEN_SELECTION,
   isProven,
-  provenSurface,
+  provenEntry,
+  provenImpl,
+  provenStatus,
   provenSummary,
+  provenSurface,
 } from '../shared/proven'
-export type {
-  PerformanceStatus,
-  ProvenEntry,
-  ProvenKey,
-} from '../shared/proven'
+export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'